Skip to content

fix(ui): accept whitespace-only differences in restore verification, snap excluded selection starts, and merge folder-session chrome re-stamps - #1541

Merged
backnotprop merged 4 commits into
mainfrom
fix/qa-verify-restore-guard
Sep 15, 2026
Merged

backnotprop merged 4 commits into
mainfrom
fix/qa-verify-restore-guard

Conversation

@backnotprop

Copy link
Copy Markdown
Owner

Four verification-QA findings from the current release candidate: one HIGH regression introduced by #1535, two remaining gaps in the same alert-anchoring area, and the incomplete half of #1537's folder-session chrome fix. One commit per fix.

1. HIGH — restore verification rejected every correct cross-block restore

verifyRestoredContent (turned on for plan review and annotate by #1535) compared originalText against the painted text with whitespace collapsed to a single space. originalText is the browser's selection string, which carries a blank line between block elements; the painted text is the wrapper <mark>s concatenated with nothing between them, because sibling blocks are rendered from a .map() with no whitespace text node. So "Alpha.\n\nBeta." never matched "Alpha.Beta.": the correct highlight was removed, the text-search rescue could not bridge the boundary either, and every annotation spanning two paragraphs, a heading and its paragraph, or two list items came back from a reload, an agent resubmit or a markdown edit with no highlight at all — under the misleading toast "N annotations no longer match the text · The highlighted text was edited".

Compare with compactText — the helper #1535 already added for the identical asymmetry in its quote repair. Content drift (the #1509 case the guard exists for) still differs once whitespace is gone, so the guard keeps its teeth.

New packages/ui/components/Viewer.crossBlockRestore.test.tsx (registered in the CI DOM list) restores a two-paragraph, heading+paragraph, two-list-item and paragraph+code-fence selection through the real Viewer, and pins that a quote whose content really changed is still rejected. Four of its five tests fail on the pre-fix comparison. Viewer.driftedRestore.test.tsx still passes.

2. MEDIUM — a drag starting inside excluded chrome painted only its tail

web-highlighter never enters an .annotation-exclude subtree: its painter skips such an element before the "is this the start node" check, so a range that starts inside one never flips its in-selection flag and paints only the trailing text node. A drag from a GitHub alert's icon — where the visually hidden "Tip: " lives — through the alert body highlighted the body alone, silently dropping the title, while the quote still carried the invisible word. Any title holding inline markup (a code span, a link) reproduced the original #1511 symptom inside the title row itself, because the quote repair only recognized the shape where the whole non-excluded selection is one trailing run.

The range's start is now moved off the excluded subtree onto the first annotatable text position it covers, by node identity, before anything paints or quotes it — on all three paths that reach the highlighter: the pointer-end selection (capture phase, since web-highlighter's own handler reads the live selection), highlightRange for pinpoint clicks and vim visual selections, and the touch selectionchange bridge.

3. LOW — the quote repair removed the wrong occurrence

The repair removed the FIRST occurrence of each excluded element's text anywhere in the selection string. With body prose that legitimately reads "Tip: ", a selection running through a tip alert's title row had the reviewer's own words removed instead of the hidden ones; the result then failed the repair's own content check and reverted, leaving the invisible word in the quote after all.

The excluded runs are now located positionally, from the range's own text nodes captured before painting (painting splits and re-parents them, so the range itself is stale by the time the highlight is created). They are matched in the quote's whitespace-free coordinate space, where the selection string and the concatenated runs agree character for character. The painted highlight stays the last word on content: a shape this cannot read leaves the quote exactly as before.

Three tests added to AlertBlock.annotation.test.tsx; each fails against the code it replaces (the two snap tests without the snap, the prose test against the first-indexOf repair).

4. MEDIUM — folder sessions still leaked sidebar/panel into the HTML chrome cookie

The annotation-activity TTL re-stamp wrote the live chrome straight to saveHtmlChromeState, bypassing mergeHtmlChromeState, which the save effect uses. It was unreachable in folder sessions while their chrome restore was suppressed; once #1537 enabled the restore, one comment in a folder session — whose file browser forces the sidebar open — rewrote both halves, so the reviewer's next annotate page.html opened with the sidebar and the annotations drawer forced open.

Both call sites now share one saveChrome() helper, the only writer of the record, so a third write cannot reintroduce the bypass. The new test in App.htmlChrome.test.tsx adds one comment in a folder session and asserts the persisted sidebar/panel halves are unchanged; it fails against the raw write.

Verification

  • bun run typecheck — clean
  • DOM_TESTS=1 bun test packages/ui packages/editor — 1724 pass, 4 fail, all four the pre-existing order-dependent DocBadges open-in placement cases (8/8 pass in isolation)
  • bun test scripts/dom-test-allowlist.test.ts — pass (the new DOM test file is registered in .github/workflows/test.yml)
  • bun run --cwd packages/ui smoke:package — packs, resolves and installs externally
  • bun run --cwd apps/review build && bun run build:hook — both build
  • bun run --cwd apps/guides-show build:viewer && check:manifest — manifest in sync (no fixture ids leaked into the viewer CSS)

A restore whose stored positions resolve onto exactly the right text was
rejected whenever the annotation spanned two block elements. `originalText`
is the browser's selection string, which carries a blank line between
blocks; the painted highlight is the wrapper marks concatenated with
nothing between them, because sibling blocks are rendered from a `.map()`
with no whitespace text node. The verification collapsed whitespace to a
single space instead of removing it, so "Alpha.\n\nBeta." never matched
"Alpha.Beta." — the correct highlight was removed, the text search could
not bridge the boundary either, and the annotation came back from a
reload, a resubmit or a markdown edit with no highlight at all.

Compare with `compactText`, the helper the same change already added for
the quote repair's identical asymmetry. Content drift — the #1509 case
the guard exists for — still differs once whitespace is gone, so the
guard keeps its teeth.
web-highlighter never enters an `.annotation-exclude` subtree: its painter
skips such an element before the "is this the start node" check, so a range
that STARTS inside one never flips its in-selection flag and paints only
the trailing text node. A drag from a GitHub alert's icon — where the
visually hidden "Tip: " lives — through the alert body therefore
highlighted the body alone, silently dropping the title, while the quote
still carried the invisible word. A title holding any inline markup
reproduced it within the title row itself, because the quote repair only
recognizes the shape where the whole non-excluded selection is one
trailing run.

Move the range's start off the excluded subtree, onto the first
annotatable text position the range covers, before anything paints or
quotes it: by node identity, never by matching text. Applied on all three
paths that reach the highlighter — the pointer-end selection (on the
capture phase, since web-highlighter's own handler reads the live
selection), `highlightRange` for pinpoint clicks and vim visual
selections, and the touch selectionchange bridge.
The quote repair removed the FIRST occurrence of each excluded element's
text anywhere in the selection string. With body prose that legitimately
reads "Tip: ", a selection running through a tip alert's title row had the
reviewer's own words removed instead of the hidden ones; the result then
failed the repair's own content check and reverted, leaving the invisible
word in the quote after all — the exact bug the repair exists to fix.

Locate the excluded runs positionally instead, from the range's own text
nodes captured before painting (painting splits and re-parents them, so
the range itself is stale by the time the highlight is created). The runs
are matched in the quote's whitespace-free coordinate space, where the
selection string and the concatenated runs agree character for character,
so the right occurrence is removed and real prose survives. The painted
highlight stays the last word on content: a shape this cannot read leaves
the quote exactly as before.
Annotation activity re-stamps the HTML chrome record so the preference
does not expire for a reviewer who is still annotating. That write went
straight to saveHtmlChromeState with the live sidebar/panel/tools values,
bypassing mergeHtmlChromeState, which the save effect uses. It was
unreachable in folder sessions while the restore was suppressed there;
once the restore was enabled, one comment in a folder session — whose file
browser forces the sidebar open — rewrote both halves, so the reviewer's
next `annotate page.html` opened with the sidebar and the annotations
drawer forced open.

Both call sites now share one saveChrome() helper, which is the only
writer of the record, so a third write cannot reintroduce the bypass.
@backnotprop
backnotprop merged commit ec7a3eb into main Sep 15, 2026
28 checks passed
@backnotprop
backnotprop deleted the fix/qa-verify-restore-guard branch September 15, 2026 14:32
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.

1 participant