docs(merge): spec + plan for Rider-style 3-pane merge editor

docs/superpowers/specs/2026-06-19-rider-merge-editor-design.md

@@ -0,0 +1,132 @@
+# Rider-style 3-pane merge editor (conflict resolver redesign)
+
+Date: 2026-06-19
+
+## Goal
+
+Replace ClaudeDo's current conflict resolver (3 read-only columns Base|Ours|Theirs,
+one conflict at a time, accept buttons + editable result below) with a JetBrains
+Rider-style **3-pane merge editor**:
+
+- LEFT = **Ours** (read-only) · current branch / merge target
+- MIDDLE = **Result** (editable) · the merged file being assembled
+- RIGHT = **Theirs** (read-only) · incoming task branch
+
+Whole file per pane (not one conflict at a time), color-coded conflict blocks,
+inline per-hunk accept controls (`›` accept a side into the result, `✕` dismiss),
+a `M conflicts · K resolved` readout, synced scrolling, Continue gated until every
+conflict is resolved, Abort, and a binary-file guard. Visual reference: the
+attached "Merge Revisions" screenshot.
+
+## Background
+
+- Avalonia 12 desktop app; the conflict editor already uses **AvaloniaEdit 12.0.0**
+  + `AvaloniaEdit.TextMate` (theme `StyleInclude` in `src/ClaudeDo.App/App.axaml`).
+- **Backend is kept unchanged.** `WorkerHub.GetMergeConflictDocuments(taskId)` returns
+  each conflicted file as ordered `MergeSegment`s: *stable* text (git's already
+  auto-merged content) interleaved with *conflict* blocks carrying `Ours/Base/Theirs`.
+  `StartConflictMerge` / `WriteConflictResolution` / `Continue[Planning]ConflictMerge` /
+  `Abort[Planning]ConflictMerge` and their `IWorkerClient` mirrors stay as-is.
+  `ConflictMarkerParser` (Data) already produces the segments. **ours = merge target
+  (current branch); theirs = incoming task branch.** Merges are LOCAL-only (no push).
+- **Seam kept unchanged** so single-task AND planning conflict paths keep working:
+  `IslandsShellViewModel.ConflictResolverFactory` + `ShowConflictResolver`
+  (wired in `MainWindow.axaml.cs`), VM ctor `(IWorkerClient, taskId)`,
+  `OpenAsync(targetBranch)`, `OpenForPlanningAsync(parentId, subtaskId)`, `CloseRequested`.
+  The planning-path WIP currently uncommitted in the tree (`OpenForPlanningAsync`,
+  `_conflictTaskId`, `LoadDocumentsAsync`) is part of this seam and is preserved.
+
+### Key insight: the segments already line the panes up
+
+Because every conflicted file is split into *stable* (identical on both sides, git
+auto-merged) and *conflict* (divergent) segments, reconstructing three documents —
+
+- **Ours**   = Σ over segments of (stable.Text | conflict.Ours)
+- **Theirs**  = Σ over segments of (stable.Text | conflict.Theirs)
+- **Result**  = Σ over segments of (stable.Text | conflict.Resolution ?? conflict.Ours)
+
+— yields three documents that are byte-identical in their stable regions and differ
+only inside conflict blocks. So the panes align line-for-line for free, and a real
+client-side 3-way diff is **not** needed for the core feature.
+
+## Decisions
+
+- **Data source = segment-based (no backend change, no DiffPlex).** The worker already
+  applied git's auto-merge; only conflicts remain actionable. The screenshot's
+  "N changes" (non-conflicting hunks shown as separately flippable) are already merged
+  and have nothing to accept, so the readout is **`M conflicts · K resolved`**. True
+  "N changes" parity (raw `:1/:2/:3` blobs + DiffPlex 3-way) is an explicit later
+  add-on that does not touch the seam — see *Out of scope / fast-follow*.
+- **One file at a time + file switcher.** Like Rider's title bar ("Merge Revisions for
+  …file"). When more than one file conflicts, a compact switcher selects the active
+  file; Continue still requires *all* files resolved. (Replaces today's cross-file
+  flattened one-at-a-time navigation as the primary model.)
+- **Result-pane editing model.** The middle document is the merged file. Stable text is
+  read-only via `IReadOnlySectionProvider`; only conflict regions are editable. Each
+  conflict's result span is tracked in a `TextSegmentCollection` (anchors auto-adjust on
+  edit). Accepting `›`(ours)/`‹`(theirs) replaces that span; editing inside it or
+  accepting flips the block to **resolved**. Unresolved regions are seeded with the Ours
+  text and painted red until acted on.
+- **Accept controls = overlay between panes** (not an AvaloniaEdit margin). A thin Canvas
+  overlay between Ours|Result and Result|Theirs hosts `›`/`✕` (and `‹`) per conflict,
+  positioned at each block's visual Y (recomputed on scroll/resize). This matches the
+  screenshot's between-pane gutters and avoids the lack of a built-in right-side margin.
+- **Synced scroll = proportional (Green).** Mirror each pane's vertical scroll offset to
+  the other two with a re-entrancy guard. Aligned/virtual-space scroll + bezier connector
+  curves are a deferred stretch.
+- **Seam + existing VM tests preserved.** Keep `MergeConflictBlock` with its
+  `AcceptOurs/Theirs/Both/Base` commands and `MergeFile.Compose`; keep
+  `Current`/`CurrentIndex`/`Next`/`Previous` repurposed as the focused-conflict the top
+  arrows jump to. New state (active file, readout) is additive.
+
+## Architecture
+
+### ViewModel (`ConflictResolverViewModel`, `ConflictModels.cs`)
+
+Unchanged seam: ctor, `OpenAsync`, `OpenForPlanningAsync`, `CloseRequested`,
+`Continue`/`Abort` (incl. planning routing), `CanContinue` gating, binary guard.
+
+Additive:
+- `ActiveFile` (`MergeFile`) + the switcher list (`Files`) + `SelectFileCommand`.
+- Per-active-file reconstruction exposed for the view and for tests:
+  `ActiveOursText`, `ActiveTheirsText`, `ActiveResultText` (result seeds unresolved =
+  Ours), plus an ordered list of conflict descriptors (the block + its segment index)
+  so the view can compute offsets/spans as it assembles each document.
+- Readout `PositionText` → `"{M} conflicts · {K} resolved"` (active file and/or total);
+  `CanContinue` stays "all files resolved AND no binary".
+- On switching files, block `Resolution` persists (state lives on `MergeConflictBlock`),
+  so progress survives navigation; the view rebuilds documents from the active file.
+
+### View (`Views/Conflicts/ConflictResolverView.axaml` + `.cs`)
+
+- AXAML: ModalShell host (kept), header (prev/next arrows, file switcher, readout),
+  `Grid` of three bordered panes with headers, two between-pane overlay Canvases,
+  footer (Continue/Abort), binary banner, `Escape`→Abort. Drop the Base column.
+- Code-behind builds three `TextDocument`s from `ActiveFile`'s segments, recording each
+  conflict's line span per document; installs TextMate by file extension on all three;
+  rebuilds on file switch; pushes result-pane edits back into the active block's
+  `Resolution` and flips resolved.
+- `IReadOnlySectionProvider` on the Result `TextArea` (stable = read-only, conflicts =
+  editable) backed by a `TextSegmentCollection` of the conflict result-spans.
+- One `IBackgroundRenderer` per pane painting unresolved-conflict (red), resolved
+  (green/muted), and ours/theirs side tints, driven by the recorded spans + block state.
+- Overlay accept controls positioned at each block's `TextView` visual top; click →
+  `block.AcceptOurs/AcceptTheirs` and the code-behind replaces the tracked result span.
+- Proportional synced vertical scroll across the three panes.
+
+### Localization / tokens
+
+- New `conflictResolver.*` keys (pane headers, readout, accept tooltips) in
+  `en.json` + `de.json` (parity enforced by Localization.Tests).
+- Block colors from `Tokens.axaml` (reuse Blood/Moss/Accent tints; add tokens only if a
+  needed shade is missing).
+
+## Out of scope / fast-follow (not in this plan)
+
+- **Raw 3-way diff "N changes" parity (Option B):** a new worker method returning raw
+  `:1/:2/:3` blobs per conflicted file + DiffPlex client-side 3-way diff so
+  non-conflicting changes also appear as accept-able hunks. Seam-preserving; later.
+- **Intra-conflict word/line highlighting** (Rider's "Highlight words") via a line
+  transformer.
+- **Bezier connector curves + aligned / virtual-space synced scroll** (Red stretch).
+- No DB migration, no backend/seam changes, no push.