artifact-canvas: horizontal multi-column reading mode for spec/plan review (toggleable, vertical stays default)

[amrmelsayed]

Problem

The artifact canvas (the afx open annotation viewer and markdown preview — the surface where gate reviews of specs/plans/reviews happen) renders documents as a single vertical column. On wide monitors this wastes most of the screen: one column of readable measure occupies roughly a third of the width, and reviewing a long spec means constant vertical scrolling with only one screenful of context visible at a time. Gate review is a cross-referencing activity — requirements against acceptance criteria, a plan phase against its constraints — and a single-column viewport forces the reviewer to hold one side of every comparison in memory.

Proposal

A horizontal multi-column reading mode for the canvas: content flows top-to-bottom within fixed-height columns of readable measure (~400px), continuing into the next column rightward — newspaper flow — inside a horizontally-scrolling container. Three to four columns per screenful on a typical wide display, so an entire spec section is visible at once.

• Toggleable, vertical stays default. A toolbar toggle + persisted preference; horizontal is an opt-in reading mode, not a replacement.
• Implemented natively in the canvas (CSS multi-column layout: column-width + column-fill: auto, plus a wheel-to-horizontal-scroll remap, axis-aware keyboard navigation, and a scroll-progress indicator). No new dependencies.
• Works in both canvas hosts (browser via afx open, VS Code webview).

Why SPIR

Real design decisions belong in a spec phase:

1. Fragmentation policy — break-inside: avoid for code blocks, tables, marker cards, and the inline composer (a mid-composer column split is unacceptable); policy for blocks taller than the viewport (fragment vs overflow-with-inner-scroll).
2. Affordance geometry — the current '+' overlay is absolutely positioned in a left gutter keyed off offsetTop; both concepts dissolve in column layout. artifact-canvas: full-row '+' affordance (GitHub-diff pattern) — structurally eliminate the hover travel-gap bug class #1343 (full-row affordance) is a prerequisite: an in-row affordance travels with its block wherever the column places it. Marker cards are already in-flow (vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863) and fragment naturally.
3. Navigation semantics — artifact-canvas: keyboard-first review navigation — jump keys, focus management audit, minimap focusability #1237's jump keys need axis-aware scrollIntoView (inline: 'center'); wheel remap must not fight native horizontal trackpad gestures; the minimap's vertical dot rail needs a horizontal-progress equivalent (or is suppressed in this mode).
4. Preference surface — where the toggle lives, per-workspace vs per-user persistence, and whether column width is configurable.

Sequencing

After #1343 lands (geometric prerequisite). Orthogonal to the diff-editor review-queue work (#1037/#1049 — different surface). Touches the same files as the recently-merged #1344 batch, so single-lane scheduling within artifact-canvas.

Non-goals

• The unified diff editor (code review is line-oriented; column flow doesn't apply).
• Replacing or changing the default vertical mode's behavior.
• Any external runtime dependency.

Requirements (architect-provided; the builder's spec elaborates from these)

1. Mode toggle in the canvas toolbar; vertical remains default; switching lands the reader within the same section (coarse position preservation).
2. Preference persists across sessions (scope — per-user vs per-workspace — is a spec/plan decision; architect lean: per-user).
3. Every existing review interaction works identically in both modes: block hover/focus, the "+" affordance (per artifact-canvas: full-row '+' affordance (GitHub-diff pattern) — structurally eliminate the hover travel-gap bug class #1343's in-row model), inline composer, marker cards, edit/delete, and the full artifact-canvas: keyboard-first review navigation — jump keys, focus management audit, minimap focusability #1237 keyboard flow.
4. Fragmentation rules: code blocks, tables, images, marker cards, and an open composer never split across a column boundary; prose may fragment naturally.
5. Tall-block policy required for blocks exceeding column height (candidates: inner scroll / allow fragmenting / cap-with-expand; architect lean: inner scroll for code, fragment for prose).
6. Wheel remap only in horizontal mode, only for vertical wheel deltas; native horizontal trackpad gestures and pinch-zoom untouched.
7. Progress indication in horizontal mode (the vertical scrollbar's positional feedback disappears).
8. Minimap treatment decided in the spec: horizontal re-orientation vs suppression-with-jump-keys (architect lean: suppress in v1).
9. Host parity: browser (afx open) and VS Code webview.
10. Vertical mode behaviorally untouched for users who never toggle.
11. Theme/token compliance for all new chrome; light + dark.
12. Accessibility: keyboard-focusable container, ARIA roledescription + progress announcements, DOM-order focus (= reading order across columns).

Acceptance criteria (minimum; builder's spec may extend)

• A long spec reflows into readable-measure columns with no clipped/unreachable content; toggling back restores vertical exactly.
• A complete review pass (read → comment → submit → edit → delete) works in horizontal mode, mouse-only AND keyboard-only.
• No protected block type straddles a column boundary; oversized code blocks fully readable via the chosen mechanism.
• Existing canvas tests pass unchanged; running flow demonstrated in both hosts at dev-approval (UI verification per testing guide).

Additional open decisions for the spec phase

• Scroll-snap to column starts vs free scrolling (lean: free first; snap can fight precise positioning while composing).
• Column width: fixed ~400px default vs configurable (lean: fixed first).
• Mode-switch position mapping (nearest-heading anchor likely sufficient).

Risks the spec should address

• CSS fragmentation edge cases (column-fill: auto × break-inside) across both Chromium hosts; the canvas's block-decoration DOM under fragmentation.
• Audit for any remaining offsetTop-style geometry in the canvas that predates artifact-canvas: full-row '+' affordance (GitHub-diff pattern) — structurally eliminate the hover travel-gap bug class #1343 and assumes vertical flow.
• Single-lane scheduling in packages/artifact-canvas; rebases over artifact-canvas: full-row '+' affordance (GitHub-diff pattern) — structurally eliminate the hover travel-gap bug class #1343.

[amrmelsayed]

Requirements addendum (architect, from design discussion 2026-08-10): fragment-local affordance behavior

The '+' affordance model this feature inherits from #1343 is block-scoped (renders within the block's own DOM, so column placement is the browser's problem). One case needs an explicit spec-phase decision: a prose block that fragments across a column boundary (permitted by the fragmentation rules; protected block types never fragment).

• Hovering the block's continuation fragment in column N must NOT surface the affordance back at the block's first fragment in column N-1 — that recreates the cross-gap travel bug artifact-canvas: full-row '+' affordance (GitHub-diff pattern) — structurally eliminate the hover travel-gap bug class #1343 eliminates, now spanning columns.
• The available primitive is element.getClientRects(), which returns one rect per fragment: the affordance can anchor to the fragment under the pointer, appearing in the column the reviewer is actually reading.
• Spec decision: pointer-side fragment anchoring in v1, vs accepting block-start placement for the fragmenting-prose minority as a documented v1 limitation. Architect lean: pointer-side anchoring if the getClientRects approach proves simple in the spike; documented limitation otherwise — but decided, not defaulted.

Related layout note for the spec: the current canvas-level 1.9rem left gutter should become block-local leading space in both modes (it travels through fragmentation and unifies vertical mode as the one-column case of the same geometry).