Skip to content

[mac] fix: keep reading position when switching editor ⇄ preview - #415

Open
thiagosansi wants to merge 1 commit into
Shpigford:mainfrom
thiagosansi:fix/scroll-anchor-mode-switch
Open

thiagosansi wants to merge 1 commit into
Shpigford:mainfrom
thiagosansi:fix/scroll-anchor-mode-switch

Conversation

@thiagosansi

Copy link
Copy Markdown

Fixes #396. Same root cause as #104 and #88.

The problem

ScrollBridge carried one normalized scroll fraction, and each mode restored fraction × its own height. Those heights are unrelated — a fenced code block is twenty source lines and renders compact, a heading is one line and renders tall.

Measured on a real 357-line document (tables, no images): the same source line sat at 34% of the editor and 18% of the preview, because the preview was 18393px against the editor's 6600px. Sixty percent of one is not sixty percent of the other, so every switch landed by luck — and, as #396 reports, usually further ahead.

The fix

Anchor on the source line. cmark already stamps every block with data-sourcepos and the editor can resolve an offset to a line, so both sides can speak the same coordinate.

  • ScrollAnchor carries a fractional 1-based source line. A fraction is kept only as the fallback for anchors with no line yet.
  • The preview builds a table of [data-sourcepos] blocks and binary-searches it on scroll. It is rebuilt when the document height changes, which covers images, mermaid and folds. Building it costs ~3ms for 452 blocks.
  • The editor resolves the offset at the viewport top through LineIndex, a cached UTF-16 offset ⇄ line map, so per-frame anchoring never walks the whole document.
  • Both directions interpolate inside the anchoring block, using the line count (el - sl + 1) rather than the difference — the difference put a hard-wrapped paragraph's interior consistently one line ahead.

Reload restores by line too, so editing no longer drifts the preview.

Three things the first cut got wrong

Each was found by measuring, not by reading:

  1. Stale ceiling. TextKit lays out lazily, so the document view is only as tall as the layout done so far. Measuring maxScroll before resolving the line gave a ceiling that clamped deep targets short. Resolve first, measure after, and never cap an offset that came from real geometry.
  2. Restoring once is not enough when anything resizes after the scroll. The preview re-applies across two frames and a few timers, skips the work when neither height nor position moved, and stops the moment the reader touches the wheel.
  3. ensureLayout per scroll tick forced layout of everything above the viewport for no gain — the visible region is already laid out for display. It now runs only when restoring.

Testing

  • 10 new LineIndexTests (UTF-16 offsets, CRLF, astral characters, blank lines, clamping, full round trip). Suite green: 101 XCTest + 31 Swift Testing.
  • The preview JS was exercised headlessly against a synthetic layout and against a nested one modelling table > tr > td with 1032 anchor elements sharing tops: 0.000 source lines of drift across a relayout, anchor always monotonic. Residual pixel drift equals the inter-block margin, where no element exists to anchor to.
  • Verified interactively on macOS against the document measured above, in both directions.

iOS is untouched — it does not use ScrollBridge.

Switching modes moved the reader somewhere else in the document, usually
further ahead (Shpigford#396, Shpigford#104, Shpigford#88).

ScrollBridge carried a single normalized scroll fraction and each mode
restored `fraction × its own height`. Those heights are unrelated: a fenced
code block is twenty source lines and renders compact, a heading is one line
and renders tall. On a real document — 357 lines, tables, no images — the
same line sat at 34% of the editor and 18% of the preview, because the
preview was 18393px against the editor's 6600px. Sixty percent of one is
simply not sixty percent of the other, so every switch landed by luck.

Anchor on the source line instead. cmark already stamps every block with
data-sourcepos, and the editor can resolve an offset to a line, so both sides
speak the same coordinate:

- ScrollAnchor carries a fractional 1-based source line, with a fraction kept
  only as the fallback for anchors that have no line yet.
- The preview builds a table of [data-sourcepos] blocks and binary-searches it
  on scroll, rebuilt when the document height changes — which covers images,
  mermaid and folds. Building it costs ~3ms for 452 blocks.
- The editor resolves the offset at the viewport top through LineIndex, a
  cached UTF-16 offset ⇄ line map, so per-frame anchoring never walks the
  whole document.

Both directions interpolate inside the anchoring block, using the line COUNT
(el - sl + 1) rather than the difference, so a hard-wrapped paragraph's
interior is not consistently one line ahead of where the reader was.

Three things the first cut got wrong, each found by measuring:

- TextKit lays out lazily, so the document view is only as tall as the layout
  performed so far. Measuring maxScroll before resolving the line yielded a
  stale ceiling that clamped deep targets short. Resolve first, measure after,
  and never cap an offset that came from real geometry.
- Restoring once is not enough when anything resizes after the scroll. The
  preview now re-applies across two frames and a few timers, skipping the work
  when neither the document height nor the position moved, and stopping the
  moment the reader touches the wheel.
- ensureLayout on every scroll tick forces layout of everything above the
  viewport for no gain; the visible region is already laid out for display.

Reload restores by line too, so editing no longer drifts the preview.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018G1JoED1hiNJZCTwKz8xsH
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Shifting Text Window with Editor/Preview switching

1 participant