@davmash/bygone 0.9.7 → 0.10.0

package/docs/visual-walkthrough/walkthrough.bygone

@@ -0,0 +1,340 @@
+{
+  "version": 4,
+  "title": "Bygone, one screen at a time",
+  "range": {
+    "base": "e431a208f5ad24e3fae1a22300a14fc7d041375f",
+    "head": "32bf8166cf6ae852fa801a540fe722b4070d5f4f"
+  },
+  "anchors": {
+    "two-files": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Two files, one visual comparison"
+    },
+    "many-panels": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Keep more versions in view"
+    },
+    "directories": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Start with the directory"
+    },
+    "search": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Find without abandoning the comparison"
+    },
+    "repository-history": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Begin with repository history"
+    },
+    "file-history": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Follow a file through real revisions"
+    },
+    "branch-review": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Review the shape of a branch"
+    },
+    "tour-reader": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Read the tour as a document"
+    },
+    "focused-step": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Keep the explanation beside its evidence"
+    },
+    "deconstructed": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Separate explanation stages from commits"
+    },
+    "exploration": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Explore, then return to the story"
+    },
+    "authoring": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Write the tour with explicit evidence"
+    },
+    "export": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Share a particular place or a portable view"
+    },
+    "vscode": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Stay near the editor in VS Code"
+    },
+    "cli": {
+      "file": "docs/visual-walkthrough/narrative.md",
+      "revision": "head",
+      "contains": "### Choose the launch that matches the question"
+    }
+  },
+  "connections": [],
+  "chapters": [
+    {
+      "id": "chapter-1",
+      "title": "Compare what is in front of you",
+      "scenes": [
+        {
+          "id": "arc-1",
+          "title": "Compare what is in front of you",
+          "summary": "Start with concrete files. The same visual language scales from two versions to directories and search.",
+          "bullets": [],
+          "tags": [
+            "visual-guide"
+          ],
+          "takeaway": "Start with concrete files. The same visual language scales from two versions to directories and search.",
+          "steps": [
+            {
+              "id": "two-files",
+              "title": "Two files, one visual comparison",
+              "body": "Start with two files when you already know what belongs on each side. Blue regions connect corresponding changed text; green regions mark content present on only one side. The ribbons show where the regions meet across the gutter. Read the pane labels before interpreting the colors: a local file can be editable, while a historical snapshot is read-only. Change navigation moves between the interesting regions without requiring you to scan every line.",
+              "focus": "two-files",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/01-two-files.png",
+                "revision": "head",
+                "alt": "Two JavaScript files with paired blue changes, green additions, and gutter ribbons connecting the regions."
+              }
+            },
+            {
+              "id": "many-panels",
+              "title": "Keep more versions in view",
+              "body": "A comparison can contain more than two panels. Visible panels controls how many fit in the window, while the active adjacent pair determines the current diff. Choose a fixed density or Fit; a narrower window may show fewer panels. The numbered headers keep the sequence legible. Use this when two endpoints hide an intermediate version that matters to the explanation.",
+              "focus": "many-panels",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/02-many-panels.png",
+                "revision": "head",
+                "alt": "Three of five JavaScript versions are visible, with Fit selected and the first adjacent pair active."
+              }
+            },
+            {
+              "id": "directories",
+              "title": "Start with the directory",
+              "body": "When you know the area but not the file, compare directories first. The inventory puts additions, deletions, and changed files together. Open a file to inspect its contents, then return to the directory. This keeps the question “which file matters?” separate from the closer reading of its lines.",
+              "focus": "directories",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/03-directories.png",
+                "revision": "head",
+                "alt": "The before and after directory trees align three modified files and one added changelog."
+              }
+            },
+            {
+              "id": "search",
+              "title": "Find without abandoning the comparison",
+              "body": "Search helps when you know a name or phrase but not its location. Choose the scope before interpreting the results: visible panes, all comparison panels, the current change set, and Git history answer different questions. A result takes you back to the matching evidence. Replacement is a separate operation and depends on whether the target is writable.",
+              "focus": "search",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/04-search.png",
+                "revision": "head",
+                "alt": "A search for publish finds one result in each of the two visible comparison panes."
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "chapter-2",
+      "title": "Ask how it got here",
+      "scenes": [
+        {
+          "id": "arc-2",
+          "title": "Ask how it got here",
+          "summary": "Add time to the comparison. Follow a path through commits or begin with the shape of a whole branch.",
+          "bullets": [],
+          "tags": [
+            "visual-guide"
+          ],
+          "takeaway": "Add time to the comparison. Follow a path through commits or begin with the shape of a whole branch.",
+          "steps": [
+            {
+              "id": "repository-history",
+              "title": "Begin with repository history",
+              "body": "Repository history combines file navigation with the commit axis. Here, the latest commit adds CHANGELOG.md: the earlier pane is explicitly absent. Files and Commits are two ways to choose your next question. Revision labels identify the snapshots being compared; commit-list selections are a draft until you apply them. The numbered badges show which revisions occupy the comparison panels.",
+              "focus": "repository-history",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/05-repository-history.png",
+                "revision": "head",
+                "alt": "The commit navigator marks two loaded revisions; the comparison shows CHANGELOG.md added in the newest commit."
+              }
+            },
+            {
+              "id": "file-history",
+              "title": "Follow a file through real revisions",
+              "body": "File history brings that same timeline to one path. The panels show exact historical contents, making a changed line something you can place in time. History and Compare share the window controls. Use the file navigation to visit files changed by the selected comparison, and the change controls to move within the open file.",
+              "focus": "file-history",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/06-file-history.png",
+                "revision": "head",
+                "alt": "Two pinned release.js revisions show a new channel field and sorted return value beside the commit navigator."
+              }
+            },
+            {
+              "id": "branch-review",
+              "title": "Review the shape of a branch",
+              "body": "A branch review starts with an overview of the committed range. Its suggested reading order helps you choose an entry point; the complete file list remains available. The range labels matter: this is a comparison of committed evidence, not an implicit inclusion of every local edit. Start broad, then drill into the files that explain the change.",
+              "focus": "branch-review",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/07-branch-review.png",
+                "revision": "head",
+                "alt": "The branch overview recommends starting with release.yaml, paying attention to release.js, and shows four changed files."
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "chapter-3",
+      "title": "Turn exploration into an explanation",
+      "scenes": [
+        {
+          "id": "arc-3",
+          "title": "Turn exploration into an explanation",
+          "summary": "A tour turns findings into a reading path while leaving room for exploration.",
+          "bullets": [],
+          "tags": [
+            "visual-guide"
+          ],
+          "takeaway": "A tour turns findings into a reading path while leaving room for exploration.",
+          "steps": [
+            {
+              "id": "tour-reader",
+              "title": "Read the tour as a document",
+              "body": "A tour adds a written argument to the evidence. The outline groups chapters, scenes, and steps; the continuous narrative establishes the question before pointing at source. Scrolling the narrative advances the reading position. Scrolling the code lets you inspect the evidence without advancing the story. The Narration controls provide another way to follow the same explanation.",
+              "focus": "tour-reader",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/08-tour-reader.png",
+                "revision": "head",
+                "alt": "A tour outline and continuous narrative introduce a safer release plan above its changed-file overview."
+              }
+            },
+            {
+              "id": "focused-step",
+              "title": "Keep the explanation beside its evidence",
+              "body": "A step brings a precise passage into focus. Its body should explain why those lines matter, rather than repeat their syntax. As you read farther into a scene, the scene heading can stay at the top; expand it to recover the overview. The narrative and evidence remain independently navigable.",
+              "focus": "focused-step",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/09-focused-step.png",
+                "revision": "head",
+                "alt": "The Preview by default step sits under a sticky scene heading and highlights the dry-run code evidence below."
+              }
+            },
+            {
+              "id": "deconstructed",
+              "title": "Separate explanation stages from commits",
+              "body": "Deconstructed tours group changes into conceptual stages. These are explicitly labeled explanation stages, so they should not be read as a claim about the actual commit sequence. Historical tours and real revision stacks answer the chronological question. Choose the mode that matches the explanation you want to give, and keep its provenance visible.",
+              "focus": "deconstructed",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/10-deconstructed.png",
+                "revision": "head",
+                "alt": "Deconstructed tour stages show an explanation baseline beside the Carry every anchor stage, with focused TypeScript changes."
+              }
+            },
+            {
+              "id": "exploration",
+              "title": "Explore, then return to the story",
+              "body": "A tour is a route through the material, not a fence around it. Files opens the broader inventory; Commits exposes the available revisions. History and Compare let you investigate a question that the author did not anticipate. Return to tour restores the authored passage after that detour.",
+              "focus": "exploration",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/11-exploration.png",
+                "revision": "head",
+                "alt": "The Files navigator selects release.yaml while the authored narrative remains above; Return to tour is visible."
+              }
+            },
+            {
+              "id": "authoring",
+              "title": "Write the tour with explicit evidence",
+              "body": "The missing-tour handoff supplies an editable prompt and authoring instructions. It does not call an AI service on your behalf. The authoring workflow remains file based: write a .bygone source, validate the anchors against the intended Git range, then compile or present it. Keeping the evidence explicit makes the tour inspectable and repeatable.",
+              "focus": "authoring",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/12-authoring.png",
+                "revision": "head",
+                "alt": "An authoring dialog contains an editable prompt, pinned review range, and a Read instructions button."
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "chapter-4",
+      "title": "Take the work with you",
+      "scenes": [
+        {
+          "id": "arc-4",
+          "title": "Take the work with you",
+          "summary": "Choose a sharing format and a host that fit the next reader’s question.",
+          "bullets": [],
+          "tags": [
+            "visual-guide"
+          ],
+          "takeaway": "Choose a sharing format and a host that fit the next reader’s question.",
+          "steps": [
+            {
+              "id": "export",
+              "title": "Share a particular place or a portable view",
+              "body": "Heading links identify a particular place in the tour. This screenshot shows the other sharing route: an exported HTML document with Tour details expanded. Local desktop links still depend on the referenced repository and tour being available. An HTML export is the portable reading option: minimal exports keep the tour evidence, while full exports also include bounded history. The notice here identifies a minimal snapshot and an embedded viewer requiring no internet. Choose based on how much independent exploration the recipient needs; CDN-backed exports instead require internet for their pinned viewer.",
+              "focus": "export",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/13-export.png",
+                "revision": "head",
+                "alt": "An exported tour has Tour details expanded: minimal snapshot, no browsable history, embedded viewer, no internet required."
+              }
+            },
+            {
+              "id": "vscode",
+              "title": "Stay near the editor in VS Code",
+              "body": "The VS Code companion handles contextual file comparison and file history near the editor. Larger repository, directory, multi-panel, and authored-tour work can open in Desktop. This is a division of workflows across hosts, with the same visual diff language carrying between them.",
+              "focus": "vscode",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/14-vscode.png",
+                "revision": "head",
+                "alt": "VS Code hosts a read-only Bygone file history comparison next to the Explorer and source tabs."
+              }
+            },
+            {
+              "id": "cli",
+              "title": "Choose the launch that matches the question",
+              "body": "The CLI provides direct entry points: two paths for a comparison, --history for a file or directory, --git-diff for revisions, review for a branch, and present --tour for an authored document. The tour subcommands provide schema, validation, compilation, and export. Start with the smallest question you can name, then use the shared window to expand the investigation.",
+              "focus": "cli",
+              "depth": "explained",
+              "image": {
+                "file": "docs/visual-walkthrough/images/15-cli.png",
+                "revision": "head",
+                "alt": "A VS Code terminal displays the CLI usage forms for comparison, history, review, presentation, validation, compilation, and export."
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/docs/walkthrough.md

@@ -1,103 +1,8 @@
-# Bygone Walkthrough
+# Bygone visual walkthrough
 
-This walkthrough uses Bygone on the Bygone source tree itself, so every screenshot shows real project data rather than sample filler.
+The [15-screen visual guide](visual-walkthrough/README.md) covers the major
+Bygone workflows with real screenshots and an executable Bygone tour.
 
-Source files used below:
-
-- `src/fileComparator.ts`
-- `media/script.js`
-- `media/dom.js`
-- the repository root for Git directory history
-
-## 1. Start In Directory History
-
-If you launch Bygone with no arguments from the repo root, it opens Git directory history for the current directory:
-
-```bash
-cd ~/code/bygone
-./bin/bygone.js
-```
-
-You can also be explicit:
-
-```bash
-./bin/bygone.js --history ~/code/bygone
-```
-
-![Directory history view](../media/walkthrough/directory-history.png)
-
-What to look for:
-
-- The timeline controls at the top move commit-by-commit.
-- The left rail defaults to `History`, with `Changed Files` available as a secondary scope.
-- The main panes compare directory snapshots, not individual files.
-- This is the best starting point when you want to answer “what changed in this repo over time?”
-
-## 2. Narrow Down To One File
-
-For a file-level history view, point Bygone at a single tracked file:
-
-```bash
-./bin/bygone.js --history ~/code/bygone/src/fileComparator.ts
-```
-
-![File history view](../media/walkthrough/file-history.png)
-
-What to look for:
-
-- The history rail stays visible and becomes the primary way to jump between commits for that file.
-- Commit labels stay pinned above the two panes, so it is always clear which revision is on each side.
-- Change navigation sits above the editors. `Cmd/Ctrl+Alt+Up` and `Cmd/Ctrl+Alt+Down` jump between diff hunks.
-- This view is useful when you already know the file and want to understand how a specific implementation evolved.
-
-## 3. Open A Direct Two-File Diff
-
-For a plain compare outside Git history, pass two files:
-
-```bash
-./bin/bygone.js ~/code/bygone/media/script.js ~/code/bygone/media/dom.js
-```
-
-![Direct file diff view](../media/walkthrough/direct-file-diff.png)
-
-What to look for:
-
-- There is no history rail here because this is a direct file-to-file compare, not a history session.
-- The compare stays focused on the diff canvas: current change position, copy controls, and hunk traversal.
-- `Editing On` indicates that both panes are editable in this mode.
-- This is the fastest path when you want to compare two working files directly, regardless of Git history.
-
-## 4. Recommended Mental Model
-
-The current UI makes the most sense if you think about it along two axes:
-
-- `file` vs `directory`
-- `git-backed history` vs `direct compare`
-
-That yields the core flows:
-
-- directory history
-- file history
-- directory diff
-- file diff
-
-The shell then stays mostly consistent:
-
-- context at the top
-- commit navigation only in history-backed views
-- history or changed-files navigation in the left rail when it adds value
-- change navigation and copy actions close to the diff panes
-
-## 5. Practical Shortcuts
-
-- `bygone` or `bygone <directory>`: open Git directory history
-- `bygone <file>`: open file history
-- `bygone <left> <right>`: open a direct file or directory compare
-- `Cmd/Ctrl+Alt+Down`: next change
-- `Cmd/Ctrl+Alt+Up`: previous change
-
-## 6. When To Use Which View
-
-- Start in directory history when the question is “what happened in this area of the repo?”
-- Switch to file history when the question becomes “how did this file get here?”
-- Use direct file diff when you already have two concrete files and just want the compare.
+Start with the [opening instructions](visual-walkthrough/README.md#open-the-tour),
+or read the [narrative](visual-walkthrough/narrative.md) and browse the
+[screenshots](visual-walkthrough/images/).

package/examples/bygone-history.bygone

@@ -1,52 +1,19 @@
-version: 3
+version: 5
 title: How Bygone learned to review a branch
+opening:
+  title: How does a branch become reviewable evidence?
+  summary: Follow one branch-review pipeline from merge-base selection to temporary trees and the existing directory viewer. The final fixture checks the historical boundary; this tour does not assess every renderer behavior.
+conclusion:
+  title: A stable boundary reaches the existing viewer
+  summary: The pipeline resolves the merge base before materializing snapshots, then hands those trees to the directory comparison surface. The fixture protects that range choice.
+  bullets:
+    - Git preparation and rendering meet at the temporary-tree boundary.
+    - The cited test establishes range semantics; interactive renderer behavior needs its own checks.
 sourceUrl: https://github.com/davidmashburn/bygone/commit/75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
 range:
   base: 292fe9248c5c49f762489dc688296fc100d120bc
   head: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
 
-review:
-  baseOid: 292fe9248c5c49f762489dc688296fc100d120bc
-  headOid: 75b6d7c0303124ec314aa790d6b808c4a9d9ea0e
-  items:
-    - id: merge-base-contract
-      kind: concept
-      title: Merge-base defines the reviewed history
-      body: "resolveBranchReviewRange selects one merge base, then derives changed paths and commits from that boundary. The review is the merge-base-to-head story."
-      evidence:
-        - sceneId: review-pipeline
-          stepId: establish-boundary
-        - sceneId: review-pipeline
-          stepId: lock-the-semantics
-    - id: git-directory-boundary
-      kind: boundary
-      title: Git-specific work ends at two trees
-      body: "The Git layer discovers the range and materializes snapshots; FileComparator then hands those temporary roots to the ordinary directory comparison. A reader needs the range model before the reusable directory surface is meaningful."
-      evidence:
-        - sceneId: review-pipeline
-          stepId: make-range-portable
-        - sceneId: review-pipeline
-          stepId: turn-history-into-files
-        - sceneId: review-pipeline
-          stepId: reuse-the-diff-surface
-    - id: setup-owns-complexity
-      kind: tradeoff
-      title: Review support moves complexity into range and snapshot setup
-      body: "Reusing directory comparison avoids a branch-only renderer, while range resolution and temporary snapshot creation add complexity before that renderer."
-      evidence:
-        - sceneId: review-pipeline
-          stepId: establish-boundary
-        - sceneId: review-pipeline
-          stepId: turn-history-into-files
-        - sceneId: review-pipeline
-          stepId: reuse-the-diff-surface
-    - id: partial-materialization-cleanup
-      kind: question
-      title: Does a failed materialization clean up both temporary roots?
-      body: "The focused walkthrough follows the successful handoff, but it does not prove cleanup when git show fails after one root has been partially populated."
-      evidence: []
-      nextCheck: "Inspect the preparation-error path and add a fault-injection fixture only if a failed materialization leaves either temporary root behind."
-
 anchors:
   choose-merge-base:
     file: src/gitComparison.ts
@@ -89,7 +56,7 @@ chapters:
     scenes:
       - id: review-pipeline
         title: From Git history to a visual workspace
-        summary: Follow the branch-review feature from its historical boundary to the reusable comparison surface and the test that fixes its semantics.
+        summary: Which historical boundary should a branch review show? Trace the range resolver, tree materialization, and viewer handoff, then inspect the fixture. Notice that the merge base is chosen before any comparison files are created.
         bullets:
           - Resolve the range before materializing files for the comparison.
           - Keep Git-specific preparation at the temporary-tree handoff.

package/examples/marker-focus.bygone

@@ -0,0 +1,116 @@
+version: 5
+title: Keep highlighted code in view when panels resize
+opening:
+  title: Resizing a panel should not lose the highlighted code
+  summary: >-
+    A tour reveals a line of code. You resize a panel, and that line can move out of view—even
+    though you never scrolled. This fix changes which editor events trigger linked scrolling. Follow
+    the unwanted path, the guard that blocks it, and the tests that keep normal scrolling intact.
+conclusion:
+  title: Keep redraws; synchronize only actual movement
+  summary: >-
+    The handler now distinguishes a changed scrollable area from a changed scroll position.
+    Layout-only events redraw the connectors and stop; unsuppressed movement still synchronizes. The
+    tests establish that routing distinction. They do not reproduce a resize, so the final visual
+    check is whether highlighted code stays in view when a panel changes size.
+range:
+  base: a50c2a6f58a2dfd7f85039105a27e4b92b98a3f7
+  head: 901a193203e4840dbf6e06c6a273fac7f2d713bd
+anchors:
+  before-guard:
+    file: media/script.js
+    revision: base
+    contains: |2-
+          editor.onDidScrollChange(() => {
+              if (suppressEditorEvents) {
+                  connectorController.scheduleDrawConnections();
+                  return;
+              }
+
+              if (editorMode === MODE_MULTI_WAY) {
+                  synchronizeMultiScroll(editor);
+              } else {
+                  synchronizeEditorScroll(editor);
+              }
+              connectorController.scheduleDrawConnections();
+          });
+  ignore-layout:
+    file: media/script.js
+    revision: head
+    contains: |2-
+              if (suppressEditorEvents || (!event.scrollTopChanged && !event.scrollLeftChanged)) {
+                  connectorController.scheduleDrawConnections();
+                  return;
+              }
+  width-test:
+    file: test/runTests.js
+    revision: head
+    contains: |2-
+          assert.deepEqual(
+              invokeScrollHandler({ scrollTopChanged: false, scrollLeftChanged: false, scrollWidthChanged: true }),
+              ['draw']
+          );
+  real-scroll-tests:
+    file: test/runTests.js
+    revision: head
+    contains: |2-
+          assert.deepEqual(
+              invokeScrollHandler({ scrollTopChanged: true, scrollLeftChanged: false }),
+              ['two-way-scroll', 'draw']
+          );
+          assert.deepEqual(
+              invokeScrollHandler({ scrollTopChanged: false, scrollLeftChanged: true }, 'multi-way'),
+              ['multi-scroll', 'draw']
+          );
+connections: []
+chapters:
+  - id: focus
+    title: Preserve code focus
+    scenes:
+      - id: marker-focus
+        title: Why a resize can move code—and where to stop it
+        summary: >-
+          The scroll callback also reports changes in how much content can be scrolled. The old
+          handler does not inspect that distinction. We’ll compare it with the new guard, then test
+          the layout-only case and real movement separately.
+        takeaway: >-
+          Filter the event before synchronization; preserve the redraw and the normal scrolling
+          path.
+        steps:
+          - id: before-guard
+            title: The old handler treats an unsuppressed event as movement
+            body: >-
+              After the suppression check, every event reaches a synchronizer selected by panel
+              mode. The handler never asks whether the position moved. The fix’s source comment
+              identifies the consequence: synchronizing a layout-only notification can push a
+              revealed code anchor out of view.
+            focus: before-guard
+          - id: ignore-layout
+            title: Redraw layout changes without moving the other panels
+            body: >-
+              The new condition asks whether either scroll position changed. If neither did, it
+              redraws the lines connecting matching code and returns before synchronization.
+              Existing event suppression also takes this early exit. Unsuppressed movement still
+              reaches the synchronizer, so fixing the resize case does not require disabling linked
+              scrolling.
+            focus: ignore-layout
+          - id: width-test
+            title: A wider scrollable area must not move the code
+            body: >-
+              The test changes the scrollable width while leaving both position flags false. It
+              expects only a connector redraw. Calling a synchronizer here would reopen the route by
+              which layout changes can disturb a code reveal.
+            focus: width-test
+          - id: real-scroll-tests
+            title: Real movement must still keep panels together
+            body: >-
+              Skipping synchronization for every scroll event would pass the previous check but break linked scrolling.
+              These assertions rule that out: vertical movement in two-panel mode and horizontal
+              movement in multi-panel mode each synchronize, then redraw. Panel mode selects the
+              synchronizer; the direction of movement does not. These tests check callback routing,
+              not on-screen marker visibility.
+            focus: real-scroll-tests
+        bullets: []
+        tags:
+          - scrolling
+          - bug-fix