Tracker: stacked generated diff layout

[barrettruth]

Root tracker for a Pierre-like stacked generated diff layout.

Original note:

see pierre-like diffs stacked mode (i.e. not two columns)

Goal

Add ++layout=stacked as a generated single-column diff layout that keeps unified diff text flow but uses one side-aware line-number rail instead of the current dual old/new rail.

This is not a new diff algorithm and not a new buffer topology. It should reuse existing generated diffs:// buffers, hunk metadata, actions, source navigation, lists, highlighting, and reload machinery.

Accepted product decisions

• Use ++layout=stacked as the user-facing mode name.
• Support both :Gdiff ++layout=stacked and :Greview ++layout=stacked.
• Do not add public config in the first pass.
• Keep ++layout=unified as the default and preserve current dual old/new rails.
• Keep ++layout=split as the existing paired endpoint/native-diff behavior.
• Avoid Pierre-specific implementation details in vimdoc; document the behavior directly.

Line-number semantics

The stacked rail displays one file line number per rendered diff row:

• - deleted lines show old-side line numbers.
• + added lines show new-side line numbers.
• context lines show new-side line numbers.
• file headers, hunk headers, and metadata rows do not display file line numbers.

Example replacement display:

  10 │  alpha
  10 │ -beta
  11 │ +beta changed
  12 │  gamma

The repeated 10 is intentional: the context line is numbered on the new side, while the deletion is numbered on the old side.

Internal direction

• Treat unified and stacked as generated-buffer layouts.
• Map generated layouts to rail styles:
  • unified -> dual
  • stacked -> single
• Add or centralize layout constants/helpers for unified, stacked, and split.
• Store generated rail style in buffer metadata, for example b:diffs_rail_style, so reloads preserve stacked buffers.
• Keep raw hunk/action metadata parsed from raw unified diff lines, not rail-prefixed display lines.

Child issues

• [stacked] Add layout parsing and command completion #361
• [stacked] Add single side-aware rail rendering #362
• [stacked] Preserve rail style in generated buffers and reloads #363
• [stacked] Wire stacked layout through Gdiff and Greview #364
• [stacked] Make parser, highlighting, and merge handling rail-style aware #365
• [stacked] Document stacked generated diff layout #366
• [stacked] Final verification for generated diff actions and shim #367

Non-goals for this tracker

• No public default-layout or rail-style config unless a later issue explicitly scopes it.
• No rewrite of generated hunk/action metadata.
• No changes to the split paired-window endpoint model beyond preserving existing behavior.
• No attempt to port Pierre's web renderer architecture; use Neovim-native buffers/extmarks/highlights.

Final acceptance criteria

• :Gdiff ++layout=stacked opens a generated single-column diffs:// buffer with single side-aware rails.
• :Greview ++layout=stacked opens the full generated review map with single side-aware rails.
• :edit / BufReadCmd reload preserves stacked rail style.
• Hunk navigation, source opening, dp/do, and visual hunk actions still operate on raw generated diff metadata.
• Parser, highlighting, and merge/conflict helpers handle both dual and single rails correctly.
• Vimdoc describes stacked layout, exact line-number semantics, and relevant highlight behavior.
• Existing unified and split behavior remains unchanged.

Planning reference

Detailed implementation conference notes were used to create the scoped child issues above; those child issues are the source of truth for implementation slices.