dogfood: mobile navbar flickers on forward nav (backdrop-blur sticky header)

[vivek7405]

Problem

On REAL mobile devices (iOS Safari and Android Chrome), the example-blog top navbar flickers on a FORWARD client-router navigation (scroll down the home post list, tap a post like "Hello World!"), but NOT when using the browser Back button. Desktop does not show it, and crucially Chrome DevTools mobile emulation does not show it either, so it can only be observed on a physical phone.

The navbar is the root layout's <header>, which sits OUTSIDE the <!--wj:children--> slot, so the client router preserves its DOM identity across a soft nav (it is never recreated). This is therefore NOT a layout-recreation bug. It is a paint artifact.

Design / approach

Mechanism (grounded in the code):

• The header is position: sticky plus backdrop-blur-[18px] backdrop-saturate-[180%] (examples/blog/app/layout.ts ~L207). A backdrop-filter continuously re-samples and re-blurs the content behind it.
• The blog has no loading.* boundary, so forward nav is a single content swap (no optimistic skeleton). The real forward-vs-back difference is the scroll: forward jumps to top via window.scrollTo({ top: 0, left: 0, behavior: 'instant' }) (added in fix: force instant scroll on navigation so smooth CSS does not animate it #603); back restores the previous scroll position.
• After fix: force instant scroll on navigation so smooth CSS does not animate it #603 the forward scroll-to-top is INSTANT (it was animated scroll-behavior: smooth before). On a large single-frame jump the sticky header's backdrop-filter must re-rasterize its entire blurred backdrop in one frame. Weaker mobile GPUs show a one-frame stale-blur flicker; the desktop compositor (and DevTools device mode, which runs Blink and does not emulate the mobile GPU) composites it fast enough to hide it. iOS Safari is WebKit, with its own known backdrop-filter + sticky quirks that Chrome DevTools cannot reproduce at all.

The instant scroll itself is correct (it fixed #601 and matches a native page load), so the fix is NOT to revert it. The fix belongs in the blog CSS: promote the header to its own compositor layer so the blur composites cleanly through an instant scroll, e.g. add transform: translateZ(0) / will-change: transform (and the -webkit- equivalents for Safari) to the <header>, and/or trim the backdrop-filter. Try the compositor hint first (cheapest, most likely fix); fall back to reducing/removing the blur if it persists.

Implementation notes (for the implementing agent)

• Where to edit: examples/blog/app/layout.ts, the <header class="sticky top-0 z-20 ... backdrop-blur-[18px] backdrop-saturate-[180%]"> element (~L207). This is light-DOM Tailwind in a page/layout; a one-off compositor hint can go via a utility class or a small tag-prefixed CSS rule in the layout's <style> block (invariant 7: a light-DOM custom CSS class selector must be tag-prefixed, but the header is a plain element in a layout, so a scoped rule is fine).
• Landmines: this CANNOT be reproduced on desktop or in Chrome DevTools device mode. Verify ONLY on a real phone in BOTH iOS Safari and Android Chrome. Do not declare it fixed off desktop testing. will-change: transform left on permanently can raise memory on some devices; prefer transform: translateZ(0) (a static compositor promotion) over a permanent will-change if either works.
• The instant scroll in packages/core/src/router-client.js (fix: force instant scroll on navigation so smooth CSS does not animate it #603) is correct and must NOT be reverted; the flicker is the blog header's rendering, not the router.
• Invariants: light-DOM tag-prefix rule (refactor(ui): tailwindify installStyles in 5 native-HTML tier-2 components #7); no backtick in html template bodies (feat(server): replace esbuild TS stripping with Node 24+ strip-types #9); no banned prose punctuation in comments (release: bump core/server/cli versions, honest engines fields #11).
• Tests + docs: this is a visual/rendering fix with no automated-test surface (the flicker is GPU/compositor-dependent and invisible to headless/emulated browsers). Note in the PR that verification is manual-on-device. No docs-site / AGENTS.md change (blog-app CSS only).

Acceptance criteria

• On a real iOS Safari device, forward nav (scroll the post list, tap a post) shows no navbar flicker
• On a real Android Chrome device, same: no navbar flicker
• Back navigation still has no flicker (no regression)
• The header still renders its intended blur/translucency (the fix does not visually degrade it on desktop)
• No automated test added (documented why: GPU/compositor artifact, not reproducible headless); manual on-device verification recorded in the PR
• The fix: force instant scroll on navigation so smooth CSS does not animate it #603 instant-scroll behavior is unchanged (not reverted)

[vivek7405]

Reopening: the translateZ(0) fix (#611) did not resolve it on a real device

The compositor-layer promotion shipped in #611 is live on the blog/website/docs and the flicker still happens on the phone, so the cause is NOT just the backdrop-blur layer needing its own compositing layer.

What I have ruled out / confirmed:

• The navbar DOM is preserved by the router (sits outside the wj:children slot), so it is not a layout-recreation bug.
• In fetchAndApply, the content applySwap and the instant scrollTo({top:0}) run in the SAME synchronous block (router-client.js ~L1706 then ~L1731), so there is no awaited paint gap between "new content inserted" and "scroll reset".
• [transform:translateZ(0)] on the sticky header does not stop it.

Next I need to narrow whether the trigger is the instant scroll-jump itself or the content swap behind the blur, before attempting another fix. Leaving #611 merged (the hint is harmless) while I narrow the real cause.

[vivek7405]

Research: how other frameworks scroll on client nav, and is this webjs-specific (it is not)

Reviewed the locally-cloned routers for how they reset scroll on a forward client navigation:

Framework	Forward-nav scroll-to-top	Forces instant?
Astro (view transitions)	scrollTo({ left: 0, top: 0, behavior: 'instant' })	YES (identical to webjs #603)
Next.js (app router)	temporarily sets scroll-behavior: auto, reflows, then htmlElement.scrollTop = 0	YES (equivalent)
webjs (#603)	scrollTo({ left: 0, top: 0, behavior: 'instant' })	YES
Remix 3	window.scrollTo(0, 0) (2-arg)	instant by default; animates if the app sets scroll-behavior: smooth
Remix 2 / react-router	window.scrollTo(0, 0) (2-arg)	same
Qwik	scrollTo(0, 0) (2-arg)	same
Nuxt / Vue Router	scrollBehavior returns { top: 0 }	default instant

Two camps: force-instant (Astro, Next, webjs) and respect-app-CSS via the 2-arg form (Remix, Qwik). webjs sits in the force-instant camp and its call is byte-identical to Astro's. The force-instant camp is the more robust one: it guarantees a native-like instant scroll regardless of the app's scroll-behavior, which is exactly what #601 wanted.

NONE of these routers special-case backdrop-filter. The flash is not a router concern; it is a known WebKit/iOS limitation: a backdrop-filter must re-sample its backdrop whenever the scroll position changes, and a large INSTANT jump makes one stale frame visible on iOS (all iOS browsers are WebKit, which is why it shows in both Safari and Chrome on iOS but not on desktop). On the public web this is documented as having no fully reliable CSS fix; the translateZ(0) / translate3d GPU hack is the usual suggestion and is exactly what #611 tried, which did not work here. The advanced workaround (backdrop-filter on an isolated pseudo-element) is also not guaranteed.

Conclusion: the framework behavior is correct and should NOT change (reverting the instant scroll reintroduces #601). The reliable fix is at the app layer: drop the header backdrop-filter (opaque/near-opaque background, guaranteed) or accept the minor flash as a known iOS limitation. Separately, Next.js emits a dev warning when it detects scroll-behavior: smooth on <html>; webjs could add a similar hint, but that is an enhancement, not a fix for this flash.