docs/plans/2026-10-05-tables.md

Tables Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Org tables, byte- and caret-exact against Emacs: alignment (C-c C-c), TAB / S-TAB / RET navigation that realigns and grows the table, row and column moves, inserting and deleting rows and columns, rules (C-c -), creating a table (C-c |), with #+TBLFM references kept in step.

Architecture: Table.swift ports org-table.el: org-table-to-lisp, org-table-align (column widths, number columns right-aligned by org-table-number-regexp and the 0.5 fraction, <l>/<r>/<c> cookies), org-table--align-field, org-table-next-field / -previous-field / -next-row (with the point move org-table-maybe-eval-formula makes), org-table-move-row / -column, org-table-insert-row / -column / -hline, org-table-delete-column, org-table-kill-row, org-table-create, org-table-fix-formulas. VisibleText.swift gives each character its display width as Emacs shows the line, since Emacs's columns and org-string-width count only visible text: bracket links show their description, and with the options emphasis markers and sub/superscript braces are hidden and entities are composed into one glyph. Tag alignment, M-q and tables all use it; lines are measured with three lines of context so links spanning lines are whole. Elements are found by parsing only the section around point.

Tech Stack: Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.

Spec: docs/design.md, "Goals" (tables), "Phase 2" (table alignment).

Global Constraints

• The oracle now fontifies every case (font-lock-ensure, again inside the option bindings), as a displayed buffer is; widths depend on it.
• org-table-may-need-update is treated as always set: org sets it on any table edit, so commands realign.
• Field formulas (=… in a field), shrunk columns and table.el tables are not handled; formulas come with phase 4.

Defaults chosen (user may change)

• Display options follow the user's config: emphasis markers hidden, pretty entities, sub/superscripts only with braces.
• Mac preset: ⌃⌘ arrows move rows/columns in tables, ⌃⌥⌘ arrows insert/delete, ⌃⌘- rule, ⌃⌘\ create.

---

Task 1: Visible widths

• VisibleLine; tag alignment, columns and fill use it; oracle passes refontified.

Task 2: Tables

• Port; oracle over 11 tables (numbers, rules, indentation, links, emphasis, entities, cookies, TBLFM, unicode, ragged rows) × every caret × 13 commands at both option sets; table creation; real tables in all three corpora.
• Commit "Port org tables".