Skip to content

fix(widgets): stop inline widget frames toggling their scrollbar - #20183

Merged
cruisercohen merged 2 commits into
mainfrom
fix/inline-widget-scrollbar-oscillation
Oct 14, 2026
Merged

cruisercohen merged 2 commits into
mainfrom
fix/inline-widget-scrollbar-oscillation

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A static inline widget frame stops flickering its vertical scrollbar and reflowing its content forever.

On Windows (and anywhere the browser draws a classic, space-taking scrollbar rather than an overlay one), a self-sizing inline widget frame whose content is a fraction of a pixel taller than the frame shows its own vertical scrollbar. That scrollbar narrows the viewport, the text re-wraps taller, the frame grows to the new report, the scrollbar disappears, the text re-wraps shorter, the frame shrinks back, and the scrollbar returns — a loop that runs about twice a second for as long as the widget is on screen.

Why it matters

Any user on a platform with classic scrollbars (the default on Windows) sees an inline widget's scrollbar strobe and its content jump continuously. It is distracting, makes the widget hard to read, and never settles on its own.

Not a goal

  • The expanded/fullscreen (fixed-height) view keeps scrolling. Its scrollbar appears once the grace window (300ms) passes after load, instead of at first paint.
  • This does not add a user-facing option; the frame continues to auto-size to its content.

What changed (motivation → approach → change)

Root cause: a classic vertical scrollbar is the one thing that feeds the frame's height back into the content's width. When the frame is a sub-pixel short of its content, the scrollbar appears, which re-wraps the content, which changes the reported height, which removes the scrollbar — a self-sustaining oscillation. Two sub-pixel sources drive it: the height reporter measured document.body.scrollHeight (an integer that can round down, leaving the frame short), and the frame's device-pixel-snapped viewport can be a fraction of a pixel shorter than its CSS height.

Approach: break the feedback by (1) rounding the measured content height up so the frame is never sized short, and (2) hiding the frame's own vertical overflow while the frame holds the whole document, so the content's layout width no longer depends on whether a scrollbar is showing. A frame that is held at a fixed height (expanded view, popout, thumbnail) still needs to scroll, so the reporter gives the scroll back once the document stays taller than a viewport that is not resizing — a short grace window that every viewport resize restarts, so a frame still catching up to a growth is never mistaken for a fixed-height one.

Change, all in the iframe's injected height-reporter (website/src/lib/widgetSrcdoc.ts):

  • measure() now returns Math.ceil(bodyTop + max(bodyRectHeight, body.scrollHeight) + bodyMarginBottom) instead of body.scrollHeight, so a fractional content height rounds up and the box's top offset and bottom margin are counted.
  • The reporter hides html vertical overflow while everything fits, and restores the document's own inline overflow-y once the content stays taller than the viewport past a grace window (default 300ms). A 1px fit slack absorbs device-pixel viewport snapping. The window resize listener restarts the grace window so a slow host growing the frame never gets its scrollbar back mid-growth.
  • Once the scroll is handed back, the reporter keeps it until the viewport changes height. Content that keeps its aspect ratio (a full-width image or chart) gets shorter when a classic scrollbar narrows it, so in a fixed-height frame it can fit only while the scrollbar shows; re-clipping on that fit would toggle the scrollbar every grace window.

Backwards compatibility

Compatible: inline frames already auto-size to their content, so hiding the inner vertical overflow removes a scrollbar that should never have been needed there. Fixed-height frames (expanded/popout) keep their scrollbar via the grace-window path. No stored data, key, type, or public function changes.

Removes nothing: no capability, key, record, or path is removed; the inner scrollbar in inline mode was an artifact of the sub-pixel overflow, not a feature.

Tests

website/src/test/widgetSrcdocReporter.test.tsx (vitest, fake timers, no real sleeps):

  • measure() rounds a fractional height up, counts body's top offset and bottom margin, and counts content overflowing body's box.
  • Vertical overflow is hidden while the frame holds the whole document, is handed back to a fixed-height frame once the grace window passes, counts a pixel of overhang as fitting, restores the document's own inline overflow-y, stays hidden while a slow host is still growing the frame, and hides again when the frame grows back to fit.
  • A fixed-height frame holding aspect-ratio content (610px at full width, 590px once narrowed) keeps its scroll after the hand-back instead of toggling the scrollbar each grace window; this test fails without the hand-back latch.
  • A layout model of the reported loop (content re-wraps 1000.7px → 1040px when a scrollbar narrows a sub-pixel-short viewport, host rounds the report, grows at once, shrinks after 250ms) settles on one height with no scrollbar across 420 ticks and reports exactly once, where the old reporter would ping-pong.

Manual verification

Recorded in a real browser with classic scrollbars: headless Chromium 145.0.7632.6 (Playwright 1.58.2) on Linux (kernel 6.12, x86_64), launched without Playwright's default --hide-scrollbars, so it draws classic, space-taking scrollbars. Before each measurement the run asserts that a classic scrollbar has a width above 0 inside the widget frame's own document: 15px at 100% zoom, and 14px and 12px (CSS px) at 110% and 125%. Numbers only, no screenshots. No run on a Windows machine is recorded.

Harness: the real buildSrcdoc output, bundled once from main (641b42a) and once from this branch (bb74da8), loads into a sandboxed iframe in a 640px column. A later rebase onto main (head c5f2985) leaves widgetSrcdoc.ts, its imports, WidgetFrame.tsx and widgetHeights.ts byte-identical to the measured code. The host mirrors WidgetFrame's height handling: round and clamp, apply a growth at once, apply a shrink after 250ms. Page zoom is CSS zoom on the column. A requestAnimationFrame sampler inside the frame records innerWidth - documentElement.clientWidth and innerHeight, and the host counts its iframe height writes. Each window is 10 s and starts 500ms after load.

Shapes:

  • Inline card (self-sizing): text at 15px with a 1.37 line height, over a tag row that fits at full width and wraps once a scrollbar narrows the viewport.
  • Aspect-ratio content in a frame held at 400px (expanded view): a full-width box just taller than 400px at full width and just shorter once narrowed.
  • Tall content in a frame held at 400px (expanded view): about 830px of wrapped paragraphs. After the 10 s window, which is well past the 300ms grace, a mouse wheel of 200px over the frame checks that the user can still scroll it.
Shape Zoom Build Scrollbar toggles in 10 s Frame height changes in 10 s End state
Inline card 100% main 0 0 153px, no scrollbar
Inline card 100% this PR 0 0 154px, no scrollbar
Inline card 110% main 38 38 never settles, 153px ↔ 180px
Inline card 110% this PR 0 0 154px, no scrollbar
Inline card 125% main 38 38 never settles, 153px ↔ 180px
Inline card 125% this PR 0 0 154px, no scrollbar
Aspect, fixed 400px 100%, 110%, 125% main 0 0 scrollbar shown, steady
Aspect, fixed 400px 100%, 110%, 125% this PR 0 0 scrollbar shown, steady
Tall, fixed 400px 100% main 0 0 scrollbar shown, wheel scrolls 200px of 432px
Tall, fixed 400px 100% this PR 0 0 scrollbar shown, wheel scrolls 200px of 432px
Tall, fixed 400px 125% main 0 0 scrollbar shown, wheel scrolls 160px of 433px
Tall, fixed 400px 125% this PR 0 0 scrollbar shown, wheel scrolls 160px of 433px

38 toggles in 10 s is the reported rate of about two cycles a second. At 100% zoom the card does not loop on main: its 0.47px overhang stays under the 0.5px at which this Chromium shows a scrollbar. At 110% and 125% the same card loops on main and settles on this branch. An emulated 1.25 or 1.5 device scale factor without page zoom did not start the loop in this run. The fixed-height aspect case keeps its scrollbar steady on both builds, so the scroll this branch hands back to a fixed-height frame stays put. The tall fixed-height frame keeps overflow-y: visible and scrolls by the same amount on both builds. At 125% the wheel moves 160 CSS px because the column is zoomed.

The hosted-frame layout model test above also covers the oscillation and its fix deterministically: it reproduces the toggle on the pre-fix reporter and settles on the fixed one.

Screenshots / video

Why no screenshot: the only visual change is the absence of a strobing scrollbar on a correctly-sized inline frame — a frame that previously flickered now renders statically at the same size, so there is no new or changed rendered surface to capture, only a defect that no longer occurs.

Related Issues

N/A

Pattern harvest

Not generalizable: this is a specific layout feedback loop between a classic scrollbar's width and content re-wrapping inside a self-sizing iframe; the fix (round height up, clip inner overflow while self-sizing) is particular to the widget frame's reporter.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — N/A
  • No secrets, credentials, or internal references in the diff

Rejected / considered alternatives

  • Set overflow-y:hidden unconditionally on inline mode (first suggestion): rejected because an inline widget that genuinely relies on an inner scroll would clip. The grace-window approach keeps the scroll for any frame held at a fixed height and only clips while the frame is actively holding the whole document.
  • Only round the height up, without clipping overflow: rejected because device-pixel viewport snapping can still leave the frame a fraction of a pixel short of its own CSS height, which re-opens the loop even with an up-rounded report. The 1px fit slack plus the clip is what closes it.
  • scrollbar-gutter: stable on html instead of the clip: it removes the width feedback, but it reserves an empty scrollbar-width strip on the right of every inline widget on classic-scrollbar platforms, a visible layout change for every existing inline widget (centred content shifts off-centre). The clip keeps the inline layout unchanged.
  • Switch the viewport to overlay scrollbars via CSS: rejected as platform-dependent and not controllable from inside a sandboxed iframe for the classic-scrollbar platforms where the bug occurs.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 14, 2026
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c5f29859834fb165484e9e9c93ff1136a6403b42 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check on a real Windows browser at a fractional display scale that inline frames settle and expanded frames still scroll. The 1px slack has only been run in emulation.

Suggestions

  • The 300ms grace window guesses whether a frame has a fixed height. It covers every buildSrcdoc host without changing them, but if a host ever grows a frame in steps slower than 300ms, the scrollbar comes back during the growth. A host-sent "fixed height" message would remove the guess if that case ever shows up.

[DESIGN-REVIEWED] c5f2985

Description read

[DESCRIPTION-READ] 5d4db0608d66ab070482b1b3a31ddac35e76371bbead4f7e8bf319cea7a64450

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c5f29859834fb165484e9e9c93ff1136a6403b42 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Before merge, check on real Windows that the four fixed-height hosts (expanded WidgetFrame, ArtifactBody, ArtifactThumbs, the mochi renderer) still scroll once the 300ms grace window passes.

What this change ships

Inventory (6 items) — 6 justified

Intent: stop an inline widget's scrollbar from flickering and its content from reflowing in a loop on browsers that draw classic scrollbars. FIX.

  1. A widget frame now sizes to its content rounded up to the next whole pixel, including body's top offset and bottom margin. — justified
  2. An inline frame that fits its content no longer shows its own vertical scrollbar. — justified
  3. In a fixed-height frame (expanded view, popout, thumbnail) the scrollbar now appears 300ms after load instead of at first paint. — justified
  4. Once a fixed-height frame gets its scrollbar back, it keeps it until the frame's height changes. This stops aspect-ratio content from making the scrollbar toggle. — justified
  5. Resizing the frame's viewport restarts the grace window and triggers a re-measure, so a host that is slow to grow the frame never sees the scrollbar flash. — justified
  6. A frame starts with no vertical scrollbar, so a frame still growing to its first height never shows one. — justified

[FIRST-PRINCIPLES-REVIEWED] c5f2985

Description read

[DESCRIPTION-READ] e5ff0350e3f30659ef225c3157d07b9ecc43b8256af6ae222f88a51354cf6bda

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of c5f29859834fb165484e9e9c93ff1136a6403b42 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Check the expanded/popout widget view on a real Windows machine: this fix was only measured in headless Chromium, and the scrollbar now appears 300ms after load.

[UX-REVIEWED] c5f2985

Description read

[DESCRIPTION-READ] ec8c73783fdbc304e1bc93900fb767dc214bd404c4a4bde17b5bcd90ae9c4f7c

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c5f29859834fb165484e9e9c93ff1136a6403b42 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c5f2985

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c5f29859834fb165484e9e9c93ff1136a6403b42: <one-sentence reason>

@cruisercohen
cruisercohen marked this pull request as ready for review October 14, 2026 07:33
@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners October 14, 2026 07:33
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c5f29859834fb165484e9e9c93ff1136a6403b42 — this comment is updated in place on each push.

Review details

No findings that block the merge.

FINDING — website/src/lib/widgetSrcdoc.ts:222 — top + Math.max(r.height, b.scrollHeight) + marginBottom adds body's top offset and bottom margin on top of a body sized by the viewport. One case is author CSS body{margin:0;padding:0;min-height:100vh} with a first child .container{margin:40px auto}, whose top margin collapses through body so r.top is 40. Another is a nonzero body margin with min-height:100vh. Each report comes out as the viewport plus that offset. WidgetFrame or ArtifactBody passes it through clampFrameHeight and grows the frame, 100vh grows with the frame, and the ResizeObserver reports the viewport plus the offset again. The frame keeps growing until it reaches MAX_REPORTED_FRAME_HEIGHT (100 000px). The old body.scrollHeight measure equalled the viewport in this case and settled after one report. → Fix: add the top offset and bottom margin only when body's own height does not already fill the viewport (r.height < root.clientHeight). Or measure the bottom of body's content without the margins outside body's box.

[OPUS-REVIEWED] c5f2985

Verdict parsed from the review's SHA-scoped output markers for commit c5f29859834fb165484e9e9c93ff1136a6403b42.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c5f29859834fb165484e9e9c93ff1136a6403b42: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 14, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Replies to the review lanes:

  • Opus 5.5 (fixed-height loop with aspect-ratio content): reproduced and fixed in 6795422. Once the grace window hands the scroll back, the reporter keeps it until the viewport changes height, so content that fits only while the scrollbar narrows it no longer re-clips. The new test (610px at full width, 590px once narrowed, viewport 600px) toggles the scrollbar every grace window without the latch and stays put with it.
  • First Principles (scrollbar-gutter: stable): it does remove the width feedback, but it reserves an empty scrollbar-width strip on every inline widget on classic-scrollbar platforms, which shifts centred content and changes the layout of every existing inline widget. The clip leaves the inline layout as it is. The description now lists this under rejected alternatives and says plainly that a fixed-height frame gets its scrollbar once the 300ms grace window passes after load.
  • Design (real-browser run): agreed that classic scrollbars are not Windows-only. The description now says so and states that no browser run is recorded; the fix is covered by the hosted-frame layout model tests.

@cruisercohen
cruisercohen enabled auto-merge (squash) October 14, 2026 08:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 14, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Frontend Tests (2) on 6795422 is red on main, not from this diff: the same 5 tests in ChatEmbed.optimisticSend.test.tsx fail locally on origin/main 30bb0b3 without this branch. #19881 added that test file and #20102 changed ChatEmbed's composer; the two merged 14 seconds apart. #20212 fixes the test. This PR touches only the widget srcdoc builder and its reporter test. Once #20212 merges, I'll rebase this branch so CI tests a fresh merge ref.

@cruisercohen
cruisercohen force-pushed the fix/inline-widget-scrollbar-oscillation branch from 6795422 to bb74da8 Compare October 14, 2026 10:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 14, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (head bb74da8); both commits are unchanged by the rebase.

On the Design lane's blocker: no browser run with classic scrollbars is recorded for this change, and none is in the description. That ask stands as written. The verification that exists is deterministic:

  • The reporter runs in jsdom with a stubbed layout. Of the 15 tests in the reporter test file, 10 fail when main's reporter is swapped in, and all 15 pass with this change. They cover:
    • rounding a fractional content height up to a whole pixel;
    • hiding the vertical overflow while the frame holds the whole document;
    • giving a fixed-height frame its scroll back after the grace window, and keeping it while the viewport holds its height;
    • hiding the overflow again when the frame grows to fit;
    • keeping the scrollbar hidden while a slow host is still growing the frame.
  • Two loop tests feed a 1000.7 px / 1040 px re-wrap through the reporter and the host's rule (grow at once, shrink after 250 ms). Both fail on main's reporter. With this change it posts once (1001 px) and settles.
  • Expanded, popout and thumbnail frames are held at a fixed height. When the document is taller than such a frame, the reporter gives the scroll back 300 ms after the viewport stops resizing.

A run in Chromium with scrollbars always shown would close the gap the lane names. Until such a run is recorded, a maintainer can either ask for it or override the Design concern.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 14, 2026
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Design Review: the PR description's Manual verification section now records a real-browser run with classic scrollbars, on head bb74da8. It ran headless Chromium 145.0.7632.6 on Linux with Playwright's --hide-scrollbars default removed. A scrollbar width above 0 was asserted inside the widget frame before each measurement. The run loaded the real buildSrcdoc output from main and from this branch, with a host that mirrors WidgetFrame's height handling, over a 10 s window per case:

  • Inline card at 110% and 125% zoom: main toggles its scrollbar 38 times and changes the frame height 38 times (153px ↔ 180px, about two cycles a second). This branch toggles 0 times and settles at 154px. At 100% zoom neither build loops.
  • Frames held at 400px (expanded view): 0 toggles on both builds. A tall document keeps overflow-y: visible, and a mouse wheel after the 300ms grace scrolls it by the same amount on both builds (200px of 432px at 100%). Aspect-ratio content keeps a steady scrollbar.

No code change: the run shows the loop on the old reporter and the fix settling on classic scrollbars.

A self-sizing widget frame a fraction of a pixel short of its content
showed a classic vertical scrollbar, the narrower viewport re-wrapped
the content taller, the frame grew, the scrollbar went, and the cycle
repeated about twice a second.

The height reporter now rounds the content height up and hides the
frame's vertical overflow while the frame holds the whole document, so
the content's width no longer depends on the frame's height. A frame
held at a fixed height (expanded view, popout) gets its scroll back
after a short grace window.
Content that keeps its aspect ratio gets shorter when a classic scrollbar
narrows it. In a frame held at a fixed height, re-clipping on that fit
widened the content past the viewport again and toggled the scrollbar every
grace window. The scroll now stays until the viewport changes height.
@cruisercohen
cruisercohen force-pushed the fix/inline-widget-scrollbar-oscillation branch from bb74da8 to c5f2985 Compare October 14, 2026 11:13
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 14, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 14, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (2 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: the inline widget height reporter rounds its measurement up and hides the frame's vertical overflow while the content fits, which stops the scrollbar resize loop; a fixed-height frame gets its scroll back after a grace window, and the reporter test covers both cases.

@cruisercohen
cruisercohen merged commit c92621a into main Oct 14, 2026
104 of 112 checks passed
@cruisercohen
cruisercohen deleted the fix/inline-widget-scrollbar-oscillation branch October 14, 2026 12:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 14, 2026
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.

2 participants