Skip to content

fix(toolbar): render lazy surfaces once their CSS applies in Safari - #78

Merged
HMarzban merged 45 commits into
mainfrom
fix/safari-lazy-css
Nov 15, 2026
Merged

HMarzban merged 45 commits into
mainfrom
fix/safari-lazy-css

Conversation

@HMarzban

Copy link
Copy Markdown
Contributor

What and why

In Safari (WebKit), lazy surfaces could render unstyled for a moment while another lazy stylesheet was still loading. On a phone-width window, the docked bar showed Redo, the Insert label and cells narrower than 44px. At 1440px, the colour popover body showed as a column of bare icons. The WebKit pass in #67 found this.

The fix: the phone bar, every lazySurface (colour popover, Insert steps, selection bubble, diagram templates, Your formats, the Continue chip) and the palette now first render only once the CSS loaded so far applies. The new helper is lib/styles-applied.ts.

  • Outside Safari it resolves at once, so Chromium is unchanged.
  • A stylesheet that failed (offline) has no sheet and never counts.
  • A stalled one stops blocking after 1.5 s, so nothing waits forever.

Root cause

WebKit leaves a stylesheet that has loaded out of document.styleSheets, and off the page, until every pending <link rel=stylesheet> has loaded or failed. Turbopack resolves a lazy import() once the chunk's JS and CSS have loaded. In WebKit that sheet may still be inactive at that moment, because another preloaded CSS chunk (here the colour popover's or the table grid's) is still in flight. A per-frame sample during the hold showed this:

  • WebKit: min-width: auto and Redo display: flex, and some link with a non-null .sheet was missing from document.styleSheets.
  • Chromium: 44px in every frame.

stylesApplied() checks that exact condition (every loaded link's sheet is in document.styleSheets) once, then on each animation frame until it holds or 1.5 s pass.

Why not the two approaches the task suggested:

  • Waiting for the surface's own link load event cannot help. That event has already fired when import() resolves; the sheet is loaded but inactive.
  • Avoiding concurrent CSS loads is not under our control. Turbopack inserts the links, and the idle preloads fire together.

How verified

  • New tests/e2e/mobile-bar-lazy-css.spec.ts. The test holds the colour popover CSS chunk while the window narrows to a phone width, then lets the held sheet load or fail (offline). It asserts that every animation frame in which the bar exists has 44px cells. A third case never releases the sheet and asserts the bar still shows (the 1.5 s cap).
    • Without the fix: 6/6 fail on WebKit.
    • With the fix: 30/30 pass on WebKit and Chromium (--repeat-each=5, --workers=2).
  • Production build (next start, WebKit, the table grid CSS held):
    • main: the bar's frames are auto (unstyled);
    • this branch: the bar first appears after release, styled.
    • So the check holds in the production Turbopack runtime too, not only under next dev.
  • Unit tests in tests/unit/lib/styles-applied.test.ts:
    • resolves at once when every sheet applies;
    • a loading or failed link never blocks;
    • waits while a loaded sheet is inactive;
    • gives up at the timeout.
  • Checks: bun run check (warnings only, unchanged from main), bun run lint, bun run typecheck and bun run test (1238 pass) all pass.
  • Chromium: lazy-surfaces, mobile-bar, mobile-bar-followups, mobile-bar-lazy-css, palette, palette-followups, selection-bubble, continue-chip, toolbar-surfaces, toolbar, action-preview, paint-format, mermaid-templates and extensions all pass (250 passed).
  • Full --project=webkit (--workers=2): 346 passed. The one failure is unrelated to this change: slash-menu "Home, End, Page Up and Page Down…" calls newCDPSession unguarded, so it can never pass on WebKit.
  • One WebKit flake: selection-bubble "bubble-in-row matrix" failed once on a combined run ("some words" not found after an undo) and passed on four reruns. The phone-bar specs passed under --workers=2, so the "rerun with --workers=1" caveat in tests/TESTING.md is replaced by a description of the mechanism.
  • Screenshots: before and after, 1440 and 375, light and dark, dev badge hidden, WebKit. Playwright's WebKit screenshot itself activates pending sheets, so it cannot capture the unstyled frame directly. The "before" shots keep the measured unstyled state (cells auto, panel block) by disabling the surface's own sheet for the shot.
    • Before: the unstyled bar (Redo and the Insert label showing), and the colour popover as a column of bare icons.
    • After: no bar, or the popover's own loading placeholder, until the CSS applies; then the styled surface.

Bytes

  • Eager editor chunk: +19,519 B → +19,679 B (+160 B gz); under the 200 B allowance.
  • Palette first Alt+/: 20,475 B → 20,475 B (+0 B). The wait lives in the eager host, not in the palette chunk.

Follow-ups

  • The editor's own next/dynamic load (editor-app.tsx) is not waited for. Its CSS is part of the editor chunk group, and the app-shell skeleton covers that load.
  • lazy-surfaces.spec.ts is not in the WebKit project's testMatch.
  • slash-menu.spec.ts needs a CDP skip on WebKit (from main).
  • Optional: a unit test asserting that lazySurface waits for stylesApplied, so removing the wait would be caught without WebKit.

The phone status pill spans the docked bar's width 8px above it, in
the band where the presence and Discord/GitHub/Privacy chips float, so
a refused "/" pick, a removed format's Undo or an unavailable cell's
reason covered them. Hide the chips while the bar holds a pill, as
they already hide for the selection bar; they come back when it closes.
The colour hover preview drew one decoration over each selection range,
so Red text or Yellow highlight showed over inline code and code blocks
although applying never colours them: inlineCode excludes every mark
and a code block allows none.

setActionPreview now takes { attrs, mark } and decorates only the inline
nodes addMark would mark (the parent allows the mark and no mark on the
node excludes it), merging adjacent runs. A collaborator's redraw keeps
the same rule.

A highlight preview's run that starts after the selection nests the
blurred selection's span inside its mark, so the colour panel's
stylesheet keeps that tint off.
…loads

A brush press before the lazy formatting engine landed went through
runWithEngine, which runs a queued action only if the selection has not
moved. For Paint format the next selection is the intended next step, so
the press was dropped and the brush never showed pressed.

The brushes now keep the press in paint-pending.ts: pressed at once, with
the copy cursor and the pill, the pressed text kept as a session range
that follows edits. Once the engine lands it arms on that range and paints
a mouse selection made meanwhile (on touch, the second tap). Other queued
actions keep the unmoved-selection rule.
A pointer-up that started in the text set the pending press's apply
flag even for a plain click, and landing then painted whatever was
selected, a keyboard selection too. Read the selection a frame after
the pointer-up, as the armed listener does, keep it only when it is
other text, and on landing paint only if it is still that selection;
otherwise just arm. The touch second press keeps its selection the
same way.
# Conflicts:
#	CHANGELOG.md
#	tests/TESTING.md
# Conflicts:
#	CHANGELOG.md
#	tests/TESTING.md
@HMarzban
HMarzban merged commit 4bb6e11 into main Nov 15, 2026
2 checks passed
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