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

 1# Tables Implementation Plan
 2
 3> **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.
 4
 5**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.
 6
 7**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.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.
10
11**Spec:** `docs/design.md`, "Goals" (tables), "Phase 2" (table alignment).
12
13## Global Constraints
14
15- The oracle now fontifies every case (`font-lock-ensure`, again inside the option bindings), as a displayed buffer is; widths depend on it.
16- `org-table-may-need-update` is treated as always set: org sets it on any table edit, so commands realign.
17- Field formulas (`=…` in a field), shrunk columns and table.el tables are not handled; formulas come with phase 4.
18
19## Defaults chosen (user may change)
20
21- Display options follow the user's config: emphasis markers hidden, pretty entities, sub/superscripts only with braces.
22- Mac preset: ⌃⌘ arrows move rows/columns in tables, ⌃⌥⌘ arrows insert/delete, ⌃⌘- rule, ⌃⌘\ create.
23
24---
25
26### Task 1: Visible widths
27
28- [ ] `VisibleLine`; tag alignment, columns and fill use it; oracle passes refontified.
29
30### Task 2: Tables
31
32- [ ] 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.
33- [ ] Commit "Port org tables".