Skip to content

fix(ui): keep the composer text overlay aligned with the textarea when a classic scrollbar appears - #1530

Merged
backnotprop merged 2 commits into
mainfrom
fix/composer-overlay-scrollbar-width
Sep 15, 2026
Merged

backnotprop merged 2 commits into
mainfrom
fix/composer-overlay-scrollbar-width

Conversation

@backnotprop

Copy link
Copy Markdown
Owner

Fixes #1525

Root cause

ComposerTextarea paints the composer's visible glyphs with a mirror <div> (absolute inset-0, overflow: hidden) over a textarea whose own text is transparent — only the native caret still comes from the textarea. When the textarea reaches max-h-64 and grows a layout-consuming vertical scrollbar (Windows/Linux classic scrollbars; the app's global scrollbar-width: thin makes them ~12px), the textarea's line box shrinks by that width while the mirror's does not, so from the first line whose wrap point differs the caret is drawn away from the glyph it belongs to. macOS/iOS overlay scrollbars consume no layout, which is why the bug is invisible there.

The fix

One measurement inside the existing syncScroll callback, mirrored onto the overlay's right padding:

  • the scrollbar width is offsetWidth - clientWidth minus the computed left/right border widths, so a border added later can never be mistaken for a scrollbar;
  • the base padding is read from the textarea's own computed style (not hardcoded, not read back off the overlay), so the two boxes can't drift if COMPOSER_TEXT_CLASSES changes;
  • a ResizeObserver on the textarea re-runs the sync, because syncScroll otherwise only fires on scroll and on value change — a window/panel resize that adds or drops the scrollbar without a keystroke would leave the gutter stale;
  • the measurement is cached: when offsetWidth - clientWidth is unchanged the sync returns before it touches getComputedStyle or the DOM.

scrollbar-gutter: stable was tried and cannot work here — it is ignored on an overflow: hidden box, and making the mirror a scroll container can't guarantee the same scrollbar kind as the textarea.

Zero-change guarantee where the bug can't occur

When the measured scrollbar width is 0, the code writes no inline style at all — it does not write the same number inline, it does not create a style attribute, it takes no DOM write of any kind. macOS, iOS and every touch/compact surface therefore render a byte-identical DOM to main. This is asserted two ways:

  • a DOM test asserts overlay.getAttribute('style') === null after typing past the max height with a 0px delta, and
  • a Playwright run against the real annotate app on macOS reports inline=null at every typing stage (below).

Risk analysis

Windows/Linux users (the fix): once the composer overflows, the mirror gains padding-right: base + scrollbarWidth. The caret lands on its glyph, and the overlay stops painting text underneath the scrollbar. Nothing else about the composer changes — no layout of the popover, no scroll behavior, no IME path (the composing branch still hides the overlay and shows the native text).

macOS / touch / compact users: nothing. No inline style is ever written, so the rendered DOM and computed styles are what they are today. Proven by the test and the macOS Playwright control.

Performance: the sync already read el.scrollTop/scrollLeft; it now also reads offsetWidth/clientWidth in the same reads-before-writes block, so a sync still costs at most one forced layout. getComputedStyle runs only when the measured delta actually changes (typically once, when the scrollbar appears, and once when it disappears), never per keystroke or per scroll event.

Failure modes, all degrading to today's behavior: no ResizeObserver in the environment → the observer is never created and the scroll/value-change path still carries the fix; computed padding-right unparsable → any applied gutter is cleared and nothing is written; a remounted overlay invalidates the memo, so a stale applied value can never suppress a needed write.

Not exercised: real Windows and real Linux hardware. The classic-scrollbar geometry was reproduced in Chromium on macOS with a genuine ::-webkit-scrollbar { width: 12px } (see below), not emulated with padding. Firefox and Safari were not driven; both take the same code path, and on Safari/macOS the measured width is 0, i.e. the no-write branch.

Consumer audit

ComposerTextarea is module-private to CommentPopover.tsx and used only by its popover and dialog modes, and the mirror only exists when skillReferences is on. Everything below reaches it through CommentPopover:

Surface Uses the mirror? Why it's safe
Plan review comment popover (Viewer.tsx) yes same component; gains the fix, no change at 0px
Plan diff block comments (PlanCleanDiffView.tsx) yes same
Annotate composer incl. raw-HTML / live-app pinpoints (HtmlViewer.tsx, incl. the global-comment popover) yes same
Goal setup (GoalSetupSurface.tsx), code-file popout (CodeFilePopout.tsx) yes same
Code review: DiffViewer, AllFilesCodeView, PRCommentsTab, AnnotatableDescription, CallFlowTreeView, CallFlowRawView, ReviewPRArtifactsPanel yes same
CommentPopover with skillReferences off no renders the plain pre-feature <textarea>; no overlay exists and syncScroll returns early
DecisionNoteField / DecisionNoteDialog (header decision composer, sidebar "+ General comment") no plain <textarea>, no mirror — untouched
Compact/touch shell yes, via the dialog mode overlay scrollbars measure 0 → no write
guides.show portable viewer n/a CommentPopover is stubbed out at build time (read-only-stubs-plugin.ts)

Nothing else in the repo sets paddingRight (or any style) on [data-skill-ref-overlay]; the only other inline style on that element is React's own visibility during IME composition, and React never clears properties it did not render.

Test plan

  • packages/ui/components/CommentPopover.overlayGutter.test.tsx (new, DOM-gated): base + 12px gutter with a 12px delta; borders counted as borders, not scrollbar; no inline style at all at 0px; the gutter removed when the scrollbar goes away; the ResizeObserver path re-syncing without a keystroke and disconnecting on unmount; and the no-ResizeObserver environment. 5 of the 6 fail against the unfixed component (the sixth is the zero-change guarantee, which must pass both before and after).
  • bun run typecheck — clean.
  • DOM_TESTS=1 bun test packages/ui packages/editor packages/review-editor — 2164 pass / 5 fail, against a 2158 pass / 5 fail baseline on main: the same five order-dependent DocBadges / artifactDocument failures, which pass in isolation on both.
  • bun run --cwd packages/ui smoke:package — packs and resolves.
  • bun run --cwd apps/review build && bun run build:hook — both clean.

Playwright, real app, real classic scrollbar

Annotate surface driven in Chromium (--hide-scrollbars disabled, ::-webkit-scrollbar { width: 12px } injected into the test page only), typing prose into the comment composer until it overflows. OFFSET is the horizontal distance between where the textarea lays the caret out and where the overlay paints the glyph before it.

chars scrollbar overlay padding-right OFFSET before OFFSET after
200-600 0px 4px (no inline style) 0.00px 0.00px
640 12px 4px → 16px +123.70px 0.00px
680 12px 16px +116.31px 0.00px
720 12px 16px +133.59px 0.00px
760 12px 16px −167.77px 0.00px
800-1080 12px 16px −158 … −151px 0.00px

Worst case: 167.77px → 0.00px.

macOS control (same script, no scrollbar injection), every stage through 1080 chars: scrollbar=0px, ovPadRight=4px, inline=null, OFFSET=0.00px — identical to the run against the unfixed build.

…n a classic scrollbar appears

The skill-reference composer paints its glyphs with a mirror <div> over a
transparent-text textarea; only the caret still comes from the textarea. When a
layout-consuming vertical scrollbar appears (Windows/Linux classic scrollbars,
~12px under the app's `scrollbar-width: thin`), the textarea's line box narrows
by the scrollbar width while the `overflow: hidden` mirror keeps its full width,
so from the first line whose wrap point differs the caret is drawn away from the
glyph it belongs to.

Measure the scrollbar in the existing scroll/value sync and mirror it onto the
overlay's right padding, with a ResizeObserver so a resize that adds or drops
the scrollbar without a keystroke re-syncs too. Base padding and border widths
are read from the textarea's computed style rather than hardcoded. When the
measured width is 0 (macOS/iOS overlay scrollbars, touch) nothing is written at
all, so those surfaces keep byte-identical DOM.

Fixes #1525
Guards the four failures that matter: the mirror not picking up the scrollbar
width, an inline style being written where the scrollbar takes no layout
(macOS/touch must stay unchanged), a stale gutter left behind when the
scrollbar goes away, and the ResizeObserver path that catches a resize with no
keystroke. happy-dom has no layout engine, so the textarea's box metrics are
stubbed.
@backnotprop
backnotprop merged commit 01eda97 into main Sep 15, 2026
28 checks passed
@backnotprop
backnotprop deleted the fix/composer-overlay-scrollbar-width branch September 15, 2026 04:00
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.

[Bug] Comment textarea caret becomes visually misaligned after scrollbar appears

1 participant