diff --git a/.agents/skills/webjs/references/client-router-and-streaming.md b/.agents/skills/webjs/references/client-router-and-streaming.md index ad171f859..ac8694af9 100644 --- a/.agents/skills/webjs/references/client-router-and-streaming.md +++ b/.agents/skills/webjs/references/client-router-and-streaming.md @@ -72,10 +72,11 @@ It does NOT reload changed component modules and cannot: `customElements.define` **Back/Forward scroll restore vs late layout growth.** The router SUPPRESSES the browser's scroll anchoring (`overflow-anchor`) for the duration of a Back/Forward restore, then puts it back. The saved offset was recorded against the page at its SETTLED height, while the DOM the restore swaps in is still shorter until its components upgrade and render. Without the suppression the browser treats that late growth as content appearing above a reader and adds it to the offset the router just replayed, so the reader lands BELOW where they left (the reported case was 763px, exactly the height a page gained after its swap). What follows for an app: -- **Do not write your own scroll restore.** A `popstate` listener that calls `scrollTo`, a saved offset in `sessionStorage`, a `scrollIntoView` on a remembered element: all of them fight the router, which already set `history.scrollRestoration = 'manual'` and is the sole authority on scroll during a navigation. If Back lands in the wrong place, that is a framework bug to report, not something to patch in app code. +- **Do not write your own scroll restore.** A `popstate` listener that calls `scrollTo`, a saved offset in `sessionStorage`, a `scrollIntoView` on a remembered element: all of them fight the restore, which is the BROWSER's (see the next bullet) and which the router protects with a suppression window while the page settles. If Back lands in the wrong place, that is a framework bug to report, not something to patch in app code. +- **The BROWSER restores Back/Forward scroll, not the router, and an app must not set `history.scrollRestoration = 'manual'`** (#1428). The router FORCES `history.scrollRestoration` to `auto` on start (and puts the app's own value back on `disableClientRouter()`), so setting `'manual'` yourself does not take effect while the router runs. Under `auto` the browser records a scroll position per history entry, replays it on a traverse, and composes the iOS edge back-swipe GESTURE PREVIEW from that same recorded state. The router writes no scroll on a restore at all: it reserves the recorded height (below) so the browser's replay lands on a document that can hold the offset, and that is the whole mechanism. One writer, the same model Next and Remix 3 use. Taking `manual` suppresses the recording, so every scrolled page previews BLANK for the whole gesture. That is what the router itself used to do, inherited from Turbo Drive's `assumeControlOfScrollRestoration`, and it is why Turbo still previews blank the same way: Turbo is single-writer too, but the writer is the APP. An app that sets `manual` re-breaks the preview app-wide. - **An app that sets `overflow-anchor` on `` itself sees it overridden during a restore and restored afterwards**, including a value set inline by your own script. Setting it in a stylesheet is unaffected between restores. Nothing else on the page is touched, and the router never sets `overflow-anchor` anywhere but the root element. - **A new PAGE navigation ends an open window.** The window outlives its own restore on purpose (a floor, then a ceiling), so a page navigation or a page-level form submission starting inside that span closes it first, and reopens only if it earns one. Otherwise a second Back, or a click, would inherit suppressed anchoring on a page it was never meant for. A FRAME-TARGETED navigation or submission is the exception, on exactly the rule that decides frame targeting everywhere else (the enclosing frame, an explicit `data-webjs-frame=""` from anywhere, or the frame's own `src`; `_top` and an unresolvable id are page navigations and do close the window). It swaps one region and leaves the page, and so the restored offset, intact, so it leaves the restore running. Closing there would hand anchoring back mid-restore and bring the double count straight back, and it needs no user input to happen, since a component upgrading in the just-restored page can drive a frame on its own. -- **Suppression is conditional on the offset being reachable, and follows the chase onto it.** A page that has not grown yet can be too short to scroll that far, so the browser clamps to its current maximum. There the shortfall IS the growth still to come, and anchoring adding it is what carries the reader back down, so the router leaves anchoring alone. Suppressing in that case would freeze the clamp and strand the reader a full page-growth above where they left, which is this same defect pointing the other way. That case is not left to anchoring alone, though, because anchoring adds the FULL growth however far short the clamp fell, so by itself it only lands a reader who left at the very bottom. The router also CHASES the recorded offset there, re-asserting it the moment the page is tall enough to hold it, and then stopping. That is the one place the router writes scroll after the initial restore, it is scoped to the clamped path, and it stops on the same inputs that close a suppression window. It is also time-boxed, and more tightly than the window a landed restore gets: a few hundred milliseconds from the RESTORE, not the 2s ceiling, and the suppression it installs on landing shares that same deadline rather than starting a fresh one. That bound is what keeps it from moving a reader who has landed and started reading, since such a reader generates no input to cancel it and the chase cannot tell the restore settling apart from any other growth. Anchoring is left on only WHILE the offset is out of reach, which is the part that heals the clamp. The moment the chase lands on the offset it suppresses anchoring too, because the growth that made the offset reachable is rarely all of it and every later stage would otherwise be added on top of what was just written. Both halves end together on the bound. After it, the router writes no more scroll and anchoring is back on, so a component that reaches its final height later than the bound (a chart, an embed measured from its content) has its growth added and the reader drifts BELOW the offset, the same way they would without this fix at all, rather than sitting at the clamp. +- **The recorded HEIGHT is reserved across the restore, so the offset is always reachable.** A snapshot records the page's settled `scrollHeight` alongside the offset, and the restore holds that height on the root element until the page has filled in. Without it the swapped-in markup is briefly shorter than the page it came from, the browser clamps the restore to whatever the short document allowed, and the reader lands short. The reservation removes that window rather than correcting for it afterwards, which is what retired the older catch-up that used to chase the offset as the page grew. It is released on the same settle that closes the anchoring window, on the same ceiling, and when another navigation supersedes the restore, but never on user input: releasing the height under a reader mid-scroll is the one harm an early release could do. An app's own inline `min-height` on the root is saved and put back, the same contract the anchoring window keeps. - **The window closes on the first real input** (`wheel`, `touchmove`, `keydown`, `pointerdown`), so a reader who starts scrolling mid-restore immediately gets normal browser anchoring back. Absent that it closes once the restore is over, which is the LATER of the restore's own background revalidation settling and a short floor, and at the latest on a 2s ceiling. The floor is load-bearing: waiting on the revalidation alone ties the window's length to network latency rather than to the growth it guards, so a server answering faster than the page renders would close it early and the reader would land low again. Suppression only ever WITHHOLDS a browser correction, it never moves the viewport, so it cannot yank someone who has taken over. Components that reach their final size only after they render (a chart, a media embed with no intrinsic dimensions, anything sized from measured content) are exactly the shape that triggers this, and they need no special handling: give them a placeholder height where you can, and let the router own the restore. diff --git a/.agents/skills/webjs/references/muscle-memory-gotchas.md b/.agents/skills/webjs/references/muscle-memory-gotchas.md index 9a9ace09e..917cb48d5 100644 --- a/.agents/skills/webjs/references/muscle-memory-gotchas.md +++ b/.agents/skills/webjs/references/muscle-memory-gotchas.md @@ -210,7 +210,9 @@ Navigation is automatic. The client router auto-enables when `@webjsdev/core` lo ### No ``, and no scroll restore of your own -Remix ships a `` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically: the router sets `history.scrollRestoration = 'manual'` on boot and is the sole authority on scroll for the whole navigation. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently. +Remix ships a `` component, Next has a `scrollRestoration` flag and a pile of community `useEffect` + `scrollTo` recipes, and every one of them is a thing to NOT port. WebJs restores scroll on Back/Forward automatically, and the BROWSER is what does it: the router reserves the page's recorded height across the swap so the browser's own per-entry replay lands correctly, and writes no scroll itself. There is no component to render and no option to enable. An app-level `popstate` listener that calls `scrollTo`, a remembered offset in `sessionStorage`, or a `scrollIntoView` on a saved element all race the router and win sometimes, which is worse than losing consistently. + +**Do not set `history.scrollRestoration = 'manual'` either**, which is the one line most of those recipes start with. The browser only records a per-entry scroll offset under the default `auto`, and WebKit composes the iOS edge back-swipe gesture preview from that recording, so `manual` makes every scrolled page preview BLANK for the whole gesture (#1428). The router itself used to set it, inherited from Turbo Drive, and had the same bug. It no longer does. This includes the case that most tempts a hand-rolled fix: Back landing BELOW where the reader left, on a page whose components size themselves after they render. The router already handles it, by suppressing the browser's scroll anchoring across the restore so late growth above the viewport is not added to the offset it just replayed (see `client-router-and-streaming.md`). If a restore still lands wrong, report it rather than patching around it in app code. diff --git a/blog/client-router-turbo-drive-style.md b/blog/client-router-turbo-drive-style.md index 0358a4ad3..f42e34b16 100644 --- a/blog/client-router-turbo-drive-style.md +++ b/blog/client-router-turbo-drive-style.md @@ -23,7 +23,7 @@ The client router turns itself on as soon as `@webjsdev/core` loads, which any p 1. SSR injects `...` comment markers around each layout's `${children}` interpolation, one pair per layout in the chain, plus one around the page itself (skipped when the page's segment would collide with the innermost layout's). The route key is the resolved path with param values filled in. 2. On link click, walk both the live DOM and the incoming HTML for these markers and build a path-to-range map. 3. Compare the two maps. A shared boundary whose route key CHANGED wins first, and the swap is anchored at the parent of the shallowest such change, which remounts that layout the way Next does. Only when no key changed does the deepest shared boundary become the target. -4. Record the history entry with `history.pushState`, then merge head tags, then apply the swap. The push leads on purpose: WebKit binds a same-document history entry's back-forward gesture snapshot to the page state at the moment the entry is recorded, so recording it after the content swap makes an iOS back-swipe preview the destination instead of the page being returned to. A replace then tears the live range out and inserts the incoming nodes, which is a real remount, and only elements marked `data-webjs-permanent` are carried across. A morph instead reconciles the two ranges with a keyed reconciler that preserves DOM identity, input values, scroll, and popover state; it is the more expensive path and it exists precisely to keep that state. Morphing is chosen only when the target boundary is the leaf on both sides and no route key changed. +4. Record the history entry with `history.pushState`, then merge head tags, then apply the swap. The push leads on purpose: the entry for the page being left is finalized while that page is still the live document, rather than against the content that replaced it. This is Turbo Drive's ordering too (`PageView.renderPage` calls `visit.changeHistory()` ahead of the render). A replace then tears the live range out and inserts the incoming nodes, which is a real remount, and only elements marked `data-webjs-permanent` are carried across. A morph instead reconciles the two ranges with a keyed reconciler that preserves DOM identity, input values, scroll, and popover state; it is the more expensive path and it exists precisely to keep that state. Morphing is chosen only when the target boundary is the leaf on both sides and no route key changed. 5. Re-run the scripts the swap brought in and upgrade custom elements. The whole loop runs in a microtask. The body never repaints between pages. @@ -97,7 +97,7 @@ lit ships no built-in router. You bring your own (vaadin-router, lit-router, etc Stencil ships a router closer in spirit to WebJs's, but it does not have the layouts-stay-mounted optimization. Every navigation re-mounts the full component tree. -Hotwire's Turbo Drive is the closest precedent. Same DOM-swap philosophy, same scroll-restoration logic, similar form integration. WebJs's version is written from scratch in plain JavaScript with JSDoc types, like the rest of the framework packages, and it is web-component aware (it walks `composedPath()` for shadow-DOM-piercing link detection), but the design borrows heavily. +Hotwire's Turbo Drive is the closest precedent. Same DOM-swap philosophy, closely related scroll-restoration logic, similar form integration. One deliberate divergence: Turbo takes `history.scrollRestoration = 'manual'` to stop the browser's own restore racing its snapshot restore, and WebJs did too until that turned out to suppress the per-entry scroll recording WebKit composes its back-swipe gesture preview from. WebJs now leaves the mode alone and absorbs the browser's late restore inside its own restore window instead. WebJs's version is written from scratch in plain JavaScript with JSDoc types, like the rest of the framework packages, and it is web-component aware (it walks `composedPath()` for shadow-DOM-piercing link detection), but the design borrows heavily. # Why I shipped this in core diff --git a/packages/core/src/router-client/constants.js b/packages/core/src/router-client/constants.js index 10dc89cbf..16b539299 100644 --- a/packages/core/src/router-client/constants.js +++ b/packages/core/src/router-client/constants.js @@ -46,12 +46,19 @@ export const STREAM_MIME = 'text/vnd.webjs-stream.html'; * 5. Commit, in this order: `history.pushState`, then merge head, then apply * the replace/morph from step 3, then re-run scripts and upgrade custom * elements. Only the push moved (#1406); the rest of the sequence is - * unchanged. The push leads because - * WebKit binds a same-document entry's - * back-forward gesture snapshot to the page state when the entry is - * recorded, so recording it after the content swap makes an iOS - * back-swipe preview the destination instead of the page being returned - * to (#1406). + * unchanged. The push leads so the entry for the page being left is + * finalized while that page is still the live document, rather than + * against the content that replaced it. This is Turbo Drive's ordering + * too. + * + * #1406 justified the move as the fix for the blank iOS back-swipe + * preview, on the theory that WebKit binds the gesture snapshot to page + * state at the moment the entry is recorded. That theory is FALSE, shown + * on-device in #1428: Turbo Drive has this exact ordering and previews + * blank the same way, and the real cause was + * `history.scrollRestoration = 'manual'` suppressing the browser's + * per-entry scroll recording. The ordering stands on its own merits; + * it just never fixed that bug. * * Optimizations bundled into the same response cycle: * - `X-Webjs-Have` request header lists `segment:route-key` entries for @@ -185,3 +192,15 @@ export const META_KEY_CSP_NONCE = 'name=csp-nonce'; export function _isNonHtmlPath(pathname) { return NON_HTML_EXTENSIONS.test(pathname); } + +/** + * How long the restore window's write-back stays armed (#1428). + * + * It exists to reconcile ONE event, the browser's replay of its own recorded + * scroll offset, which lands about a frame after the popstate handler. This is + * generous for that (roughly fifteen frames at 60Hz) and far short of the + * window's own life, so a legitimate programmatic scroll arriving later, a + * component's `scrollIntoView()` during upgrade or a find-in-page jump, is left + * alone rather than reverted. + */ +export const WRITE_BACK_ARMED_MS = 250; diff --git a/packages/core/src/router-client/fetch-apply.js b/packages/core/src/router-client/fetch-apply.js index 92c09b635..b014b2e52 100644 --- a/packages/core/src/router-client/fetch-apply.js +++ b/packages/core/src/router-client/fetch-apply.js @@ -272,13 +272,18 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat // recover in place rather than a destructive full reload. if (!doc) { restoreOptimistic(optimisticState); handleNavigationError(href, null, new Error('navigation response did not parse as HTML')); return { ok: false, status: respStatus, aborted: false, applied: false }; } - // #1406: the history entry this navigation records is what the iOS back-swipe - // gesture later previews, and WebKit binds a same-document entry's snapshot to - // the page state at the moment the entry is recorded. Recording it after the - // swap finalizes it against the DESTINATION document at a scroll offset the - // browser has already clamped to that document's height (measured on the - // gallery: 1600 to 252), so the gesture previews a page that never existed and - // renders blank. So the push rides into `applySwap` as a COMMIT-time callback + // #1406: recording the push after the swap finalizes the outgoing page's + // entry against the DESTINATION document, at a scroll offset the browser has + // already clamped to that document's height (measured on the gallery: 1600 to + // 252). Ordering it ahead of the mutation keeps the entry tied to the page it + // belongs to. + // + // #1406 also claimed this fixed the blank iOS back-swipe preview, via WebKit + // binding the gesture snapshot at the moment the entry is recorded. That is + // FALSE (#1428, on-device): Turbo Drive uses this same ordering and previews + // blank too, and the cause was `history.scrollRestoration = 'manual'` + // suppressing per-entry scroll recording. The ordering is kept on its own + // merits. So the push rides into `applySwap` as a COMMIT-time callback // and fires ahead of the mutation, which is Turbo Drive's ordering // (`PageView.renderPage` calls `visit.changeHistory()` ahead of // `this.render(renderer)`). @@ -335,11 +340,14 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat // Scroll only for foreground (history-recording) navigations. When // `recordHistory` is false we're either: // (a) the background revalidation after a cached popstate restore - // - performNavigation already set scroll from the cached - // position; we must NOT clobber it here. - // (b) a cache-miss popstate: modern browsers fire scroll- - // restoration themselves before dispatching popstate, so - // leaving scroll alone preserves the browser-native UX. + // - the restore is already settled (the browser replayed the + // offset and the restore window is guarding it); a write here + // would land on top of it. + // (b) a cache-miss popstate: the browser performs its own restore + // for the entry, so leaving scroll alone preserves the + // browser-native UX. Note the UA's replay lands a frame AFTER + // the popstate handler, not before it (#1428, measured), which + // is the ordering the restore window is built around. // // And never for a FRAME-scoped response (#1427). `recordHistory` means "a // foreground navigation the reader initiated", which a frame click is (it diff --git a/packages/core/src/router-client/navigator.js b/packages/core/src/router-client/navigator.js index 6753f57e6..2a1462579 100644 --- a/packages/core/src/router-client/navigator.js +++ b/packages/core/src/router-client/navigator.js @@ -17,7 +17,7 @@ import { clearPrefetchHover, clearPrefetchRefused, clearPrefetchViewTimers, onPr // `restoreGeneration` is imported READ-ONLY: the deferred restore captures it // and re-compares after the frame, so it must be the live binding. Writes go // through bumpRestoreGeneration(), since ESM forbids assigning an import. -import { afterTwoFrames, bumpRestoreGeneration, cancelScrollCatchUp, catchUpToRestoredScroll, releaseScrollAnchor, restoreGeneration, suppressScrollAnchoring } from './scroll.js'; +import { afterTwoFrames, bumpRestoreGeneration, releaseHeightReservation, releaseScrollAnchor, reserveRestoredHeight, restoreGeneration, suppressScrollAnchoring } from './scroll.js'; import { snapshotCache, snapshotCurrent, snapshotGet } from './snapshot-cache.js'; import { _setEnabled, bumpNavToken, currentNavigationToken, enabled, hardNavigate } from './state.js'; import { _swapCommit, applySwap } from './swap.js'; @@ -51,16 +51,16 @@ let activeAbortController = null; let currentPageUrl = null; /** - * Previous value of `history.scrollRestoration` (so we can restore it - * when the router is disabled). The browser's default behavior of - * auto-restoring scroll on popstate races with the SPA's own scroll - * restoration: disabled here so WebJs is the sole authority on scroll - * during navigation. Same pattern as Turbo Drive's - * `assumeControlOfScrollRestoration()` (turbo/src/core/drive/history.js). + * The app's own `history.scrollRestoration`, captured at enable so + * `disableClientRouter()` can put it back. + * + * The router writes 'auto' because the restore is the BROWSER's now (#1428) + * and 'manual' would mean no restore at all. That write is an override, so it + * owes the app its value back when the router steps aside. * * @type {ScrollRestoration | null} */ -export let prevScrollRestoration = null; +let prevScrollRestoration = null; /** Enable the client router. Idempotent. */ export function enableClientRouter() { @@ -105,11 +105,36 @@ export function enableClientRouter() { ensureUpgradeObserver(); // Apply render/viewport prefetch modes to the initial document. refreshPrefetchObservers(); - // Take control of scroll restoration so the browser doesn't fight - // the SPA's own snapshot-based restore on popstate. + // Scroll restoration is the BROWSER's, and this states that rather than + // assuming it. Under 'auto' the browser records a scroll position per + // history entry, replays it on a traverse, and WebKit composes the iOS + // back-swipe gesture preview from that same recorded state. Under 'manual' + // it records nothing, so the preview renders BLANK for the whole gesture on + // any scrolled page (#1428, measured on-device: WebJs and Turbo Drive both + // took 'manual' and both blank; Next leaves 'auto' and is clean). + // + // Written EXPLICITLY, not left to the default, because the restore now has + // no writer of its own. The router reserves the recorded height and lets the + // UA replay the offset, so an app that had set 'manual' (the first line of + // most ported scroll-restoration recipes, and what this router itself did + // until #1428) would get NO Back restore at all: the UA replays nothing, the + // reservation prevents the clamp that would otherwise fire a `scroll` event, + // and the window's write-back is scroll-event-driven so it never runs. The + // reader would simply stay at the outgoing page's offset. Prose in the docs + // cannot prevent that; this line can. + // + // Per-entry, not global, per the HTML spec: this sets the mode on the + // current entry, and an entry created by a later `pushState` inherits it, + // which is exactly the reach the router needs. + // + // Saved and put back on `disableClientRouter()`, the same contract the + // anchoring window and the height reservation keep for the inline styles + // they touch. Without it the documented runtime opt-out would silently + // strand an app that had its own restoration on 'manual', leaving it + // double-restoring with no way to detect why. if (typeof history !== 'undefined' && 'scrollRestoration' in history) { prevScrollRestoration = history.scrollRestoration; - history.scrollRestoration = 'manual'; + history.scrollRestoration = 'auto'; } // Seed the "current page" tracker so the first navigation can // snapshot the page the user is leaving. @@ -136,15 +161,16 @@ export function disableClientRouter() { clearPrefetchHover(); clearPrefetchViewTimers(); teardownPrefetchViewObserver(); + // Give the app back the scroll-restoration mode the router overrode. if (typeof history !== 'undefined' && prevScrollRestoration !== null) { history.scrollRestoration = prevScrollRestoration; prevScrollRestoration = null; } - // Never leave a restore window open on , nor a catch-up chasing a - // scroll offset after the router is gone (#1310). + // Never leave a restore window open on , nor a height reservation + // held on it, after the router is gone (#1310 / #1428). bumpRestoreGeneration(); if (releaseScrollAnchor) releaseScrollAnchor(); - if (cancelScrollCatchUp) cancelScrollCatchUp(); + if (releaseHeightReservation) releaseHeightReservation(); currentPageUrl = null; // Unpublish the refresh entry (#1398) so the dev reload client's feature // detection sees the router is gone and falls back to a full reload. @@ -429,8 +455,8 @@ export async function performNavigation(href, isPopState, frameId, opts) { // would run the whole growth under the previous restore's suppression and // freeze its clamp, and a forward nav would carry it onto a different page // entirely. Reopening for this navigation, if it earns one, happens below. - // The clamped path's catch-up is cancelled for the same reason: it chases an - // offset recorded for the page being navigated away from. + // The height reservation is released for the same reason: it holds a height + // recorded for the page being navigated away from. // // A FRAME-targeted nav is excluded, for the same reason `loadFrame` is: it // swaps one region and leaves the page, and so the restored scroll offset, @@ -439,14 +465,14 @@ export async function performNavigation(href, isPopState, frameId, opts) { // the split this rule exists to avoid. // // All THREE move together. Exempting only the counter while still closing - // the window and aborting the catch-up would leave the split exactly where - // it was, one line further down: a form inside a frame, submitted by a + // the window and releasing the reservation would leave the split exactly + // where it was, one line further down: a form inside a frame, submitted by a // component upgrading in the just-restored page, would hand anchoring back // mid-restore and bring the whole double-count back. if (!frameId) { bumpRestoreGeneration(); if (releaseScrollAnchor) releaseScrollAnchor(); - if (cancelScrollCatchUp) cancelScrollCatchUp(); + if (releaseHeightReservation) releaseHeightReservation(); } // Snapshot the page the user is LEAVING (with its scroll position) @@ -480,6 +506,11 @@ export async function performNavigation(href, isPopState, frameId, opts) { // equivalents for the same reason. let optimisticState = null; if (!isPopState && !refresh) optimisticState = applyOptimisticLoading(); + // Set when a popstate finds no snapshot, so the tail can re-assert the + // fallback scroll after the response commits. Declared HERE rather than in + // the branch that sets it, because the reader is outside that block and a + // `typeof` probe for a block-scoped binding is a coincidence, not a guard. + let cacheMiss = false; try { // popstate: try cache first, then refetch in background. Instant restore. @@ -488,82 +519,75 @@ export async function performNavigation(href, isPopState, frameId, opts) { if (cached) { const cachedDoc = parseHTML(cached.html); if (cachedDoc) { + // Reserve the page's SETTLED height BEFORE the swap, so the recorded + // offset is reachable from the very first frame (#1428). The snapshot + // markup is shorter than the page it came from until its components + // upgrade, and every scroll defect this path has had lived in that + // window: the offset clamped against a short document, and the + // restore had to chase it back afterwards. Reserving removes the + // shortness instead of compensating for it, so there is nothing to + // clamp and nothing to chase. + // Taken BEFORE the swap, so the height is already in place when the + // incoming (shorter) markup lands and the offset is never + // unreachable. One consequence worth knowing: under a view + // transition `applySwap` defers its mutation a frame, so the + // OUTGOING page is captured by the transition with this height + // already applied. On a page short enough that the reservation adds + // a scrollbar, that appears in the transition's old-state snapshot. + // Accepted rather than deferred, because deferring the reservation + // to the commit would reopen the window it exists to close. + const releaseHeight = reserveRestoredHeight(cached.scrollHeight); applySwap(cachedDoc, frameId, /* revalidating */ true, /* href */ null); // Restore window scroll to where the user left it. Use // behavior:'instant' so an app-level `scroll-behavior: smooth` // stylesheet does not animate the restore (native nav jumps). // - // `cached.scrollY` was recorded at the page's SETTLED height, and the - // DOM just swapped in is still shorter until its components upgrade - // and re-render. Suppress scroll anchoring across the restore, or the - // browser adds that late growth to the restored offset and the reader - // lands below where they left (#1310). + // Anchoring is still suppressed across the restore even though the + // document no longer changes total HEIGHT: content still SHIFTS + // within the reserved space as components render, and anchoring + // reacts to a shift above the viewport regardless of whether the + // page grew overall, adding it to the offset just replayed (#1310). + // The BROWSER restores the scroll, not the router (#1428). + // + // Under `scrollRestoration: 'auto'` the UA records an offset per + // history entry and replays it a frame after the popstate handler. + // The router used to replay its own snapshot offset synchronously + // here as well, which made two writers of the same quantity and + // forced a whole apparatus to keep them from disagreeing. With the + // height reserved above, the UA's replay lands on a document that + // can hold the offset, so it is simply correct, and the router's + // write is redundant. Deleting it leaves ONE writer, which is what + // Next and Remix 3 do (neither scrolls on a traverse; Next's restore + // reducer sets `scrollRef: null`). Turbo is single-writer too, but + // the other way round: it takes `manual` and replays itself, which is + // exactly the choice that costs it the iOS gesture preview. + // + // The window below still opens, for the half the UA does NOT cover: + // content SHIFTS above the viewport as the restored components + // render, and anchoring would add that shift to the offset the UA + // just replayed. It also carries the cached offset as a write-back + // target, so a programmatic write that intrudes on the restore's own + // span is corrected rather than left standing. let releaseAnchor = () => {}; if (typeof window !== 'undefined') { - // Restore the scroll, then decide whether to suppress anchoring. - // - // Suppress ONLY when the recorded offset was actually reached. A - // document that has not grown yet can be too SHORT to scroll that - // far, and the browser clamps to its current maximum. A reader at - // the bottom of the settled page is the clear case: the shortfall is - // then exactly the growth still to come, and anchoring ADDING that - // growth is what carries them back to the bottom. Suppressing there - // freezes the clamp instead and strands them a full page-growth - // ABOVE where they left, which is this bug's own mirror image. The - // two situations want opposite things and are told apart by the one - // question that separates them: did the scroll land. - // - // Both halves must read the SAME layout, and the scroll must be - // written against the page being restored. That is why this is - // ordered rather than simply inlined, and why the ordering differs - // by path. - const restoreScroll = () => { - window.scrollTo({ left: cached.scrollX, top: cached.scrollY, behavior: 'instant' }); - if (window.scrollY >= cached.scrollY - 1) { - releaseAnchor = suppressScrollAnchoring(); - } else { - // Clamped. Anchoring is left on, since it is what carries the - // reader back down, but it adds the FULL growth regardless of - // how far short the clamp fell, so on its own it only lands a - // reader who left at the very bottom. Chase the recorded offset - // instead, once the page is tall enough to hold it. - catchUpToRestoredScroll(cached.scrollY, cached.scrollX); - } + const openWindow = () => { + releaseAnchor = suppressScrollAnchoring(cached.scrollX, cached.scrollY); }; if (viewTransitionsEnabled() && typeof (/** @type any */ (document)).startViewTransition === 'function') { // Under a view transition `applySwap` defers its DOM mutation a - // frame, so running now would write and measure against the - // OUTGOING page. Measured with a 60000px outgoing page and a - // 3000px restored one: the scroll "landed" at 20000, suppression - // opened, and the restored page then clamped to 2416 with - // anchoring held off, which is precisely the stranding the - // conditional exists to prevent. Wait for the swap to commit. - // - // Guarded, because this is the one path where the restore - // outlives the call that scheduled it. Every cancel site in this - // feature (performNavigation, performSubmission, - // disableClientRouter) runs at the START of the next thing, so a - // navigation, submission, or disable arriving inside the deferred - // frame would close the window and then have this reopen it, - // scrolling a page it was never meant for to an offset recorded - // for the previous history entry. The synchronous branch below - // cannot outlive anything and so needs no guard. + // frame, so the window must wait for the commit or it guards the + // OUTGOING page. Guarded on the restore generation, because this + // is the one path where the restore outlives the call that + // scheduled it: a navigation, submission, or disable arriving + // inside the deferred frame closes the window, and this must not + // reopen it against a page it was never meant for. const myRestore = restoreGeneration; _swapCommit.then(() => { if (myRestore !== restoreGeneration || !enabled) return; - restoreScroll(); + openWindow(); }).catch(() => {}); } else { - // The synchronous path, and the read must STAY synchronous here. - // Deferring it even by a microtask breaks the fix outright: by - // then the restored components' renders have been applied, and - // reading `scrollY` forces the layout that flushes them, so - // anchoring runs DURING the read and hands back the - // already-shifted offset. Measured on /ui/button, the suppression - // landed 19ms late with `scrollY` already 800 -> 1563. What makes - // it correct is not which document it sees but that it sees the - // same layout the scroll just landed in. - restoreScroll(); + openWindow(); } } // Fire-and-forget revalidation. Uses a fresh AbortController @@ -583,16 +607,35 @@ export async function performNavigation(href, isPopState, frameId, opts) { const revalidated = fetchAndApply(href, frameId, /* recordHistory */ false, optimisticState, 'GET', null, signal, myToken, /* revalidating */ true) .catch(() => {}); const floor = new Promise((r) => setTimeout(r, ANCHOR_SUPPRESS_FLOOR_MS)); - Promise.all([revalidated, floor]).then(() => afterTwoFrames(releaseAnchor)); + // Staggered, not simultaneous. The revalidation's own swap re-inserts + // fresh markup that is SHORT again until its components upgrade, + // which is the premise the reservation exists for, so dropping the + // height in the same tick as the anchoring window can clamp the + // reader down and then let anchoring add the regrowth on top. The + // height is released a further two frames out, by which point the + // re-applied DOM has laid out, and anchoring is already back on to + // absorb whatever is left. + Promise.all([revalidated, floor]).then(() => afterTwoFrames(() => { + releaseAnchor(); + afterTwoFrames(releaseHeight); + })); return null; } } - // Cache-miss popstate. Browser-native scroll restoration is - // disabled (we set scrollRestoration='manual'): so without - // explicit handling, scroll would just stay where the user was - // on the page they popped FROM. Scroll to top as the reasonable - // default; fetchAndApply skips its own scroll handling when - // recordHistory=false (which is the case here). + // Cache-miss popstate. There is no snapshot to restore from, so the + // router falls back to top, which is what a reader gets for a page the + // cache no longer holds. + // + // Written TWICE on purpose: once now, and once after the response + // commits. The browser also replays its own recorded offset for this + // entry, about a frame after this handler, and that replay would + // otherwise be the last write. It is measured against the OUTGOING + // document and lands before the fetched content arrives, so it puts the + // reader at an offset that means nothing in the page they end up + // looking at. Under the old `manual` mode the UA replayed nothing and + // this path was deterministic; the second write is what keeps it that + // way now that the browser owns restoration. + cacheMiss = true; if (typeof window !== 'undefined') window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); } @@ -600,7 +643,24 @@ export async function performNavigation(href, isPopState, frameId, opts) { // duplicate `history.pushState` and the whole scroll block in one flag, // which is exactly what the comment above that block already says it means. // So Back still goes to the previous page and the reader keeps their place. - return await fetchAndApply(href, frameId, !isPopState && !refresh, optimisticState, 'GET', null, signal, myToken, /* revalidating */ false, refresh); + const outcome = await fetchAndApply(href, frameId, !isPopState && !refresh, optimisticState, 'GET', null, signal, myToken, /* revalidating */ false, refresh); + // The cache-miss re-assert described above, DEFERRED two frames rather + // than written synchronously. A synchronous write here only wins when the + // fetch was slower than the UA's replay, which is most fetches but not a + // PREFETCH HIT: a warmed entry resolves the whole fetch-and-apply inside + // the popstate task, the re-assert would land in that same task, and the + // UA's replay a frame later would overwrite it, exactly the ordering this + // exists to correct. Two frames is past the replay on every tested engine + // whichever path resolved the fetch. Guarded on still being the active + // navigation INSIDE the deferred callback, so a superseded miss never + // scrolls the page that replaced it. + if (cacheMiss && outcome && outcome.applied && typeof window !== 'undefined') { + afterTwoFrames(() => { + if (myToken !== currentNavigationToken || !enabled) return; + window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); + }); + } + return outcome; } finally { if (navigatingFlagTimer) clearTimeout(navigatingFlagTimer); // Only clear the navigating flag if WE are still the active nav. @@ -658,13 +718,13 @@ export async function performSubmission(href, method, body, frameId, form) { const signal = activeAbortController.signal; const myToken = bumpNavToken(); // Same reasoning as performNavigation: a submission is a navigation, so it - // ends any restore window a recent Back left open (#1310), and cancels a - // clamped restore's catch-up. Frame-targeted submissions are excluded on the + // ends any restore window a recent Back left open (#1310), and releases its + // height reservation. Frame-targeted submissions are excluded on the // same reasoning as the frame navs above. if (!frameId) { bumpRestoreGeneration(); if (releaseScrollAnchor) releaseScrollAnchor(); - if (cancelScrollCatchUp) cancelScrollCatchUp(); + if (releaseHeightReservation) releaseHeightReservation(); } const isSafe = method === 'get' || method === 'head'; diff --git a/packages/core/src/router-client/scroll.js b/packages/core/src/router-client/scroll.js index d1e9c6f18..40564881b 100644 --- a/packages/core/src/router-client/scroll.js +++ b/packages/core/src/router-client/scroll.js @@ -6,7 +6,7 @@ * * @module */ -import { ANCHOR_RELEASE_EVENTS, ANCHOR_SUPPRESS_CEILING_MS, ANCHOR_SUPPRESS_FLOOR_MS } from './constants.js'; +import { ANCHOR_RELEASE_EVENTS, ANCHOR_SUPPRESS_CEILING_MS, WRITE_BACK_ARMED_MS } from './constants.js'; /** * Closes the currently open restore window, or null when none is open. @@ -58,29 +58,89 @@ export let releaseScrollAnchor = null; * for the life of the page after their first Back. That is a far worse trade * than one repaint, so the root it is. * + * @param {number} [targetX] the restore's recorded horizontal offset. Together + * with `targetY` this arms the write-back below; omit BOTH to open a + * suppression-only window with no scroll enforcement. + * @param {number} [targetY] the restore's recorded vertical offset. The + * write-back is armed only when this is a number, so a caller that passes + * nothing gets the pre-#1428 behaviour. * @returns {() => void} Idempotent release. Safe to call after the window has * already closed on user input or the ceiling. */ -export function suppressScrollAnchoring() { +export function suppressScrollAnchoring(targetX, targetY) { if (typeof document === 'undefined' || !document.documentElement) return () => {}; // A second restore inside an open window supersedes the first. if (releaseScrollAnchor) releaseScrollAnchor(); const root = document.documentElement; // Save and restore the author's own inline value rather than blanking it, - // the same contract `prevScrollRestoration` keeps above. + // the same save-and-put-back contract the router keeps elsewhere. const prev = root.style.getPropertyValue('overflow-anchor'); root.style.setProperty('overflow-anchor', 'none'); /** @type {ReturnType | null} */ let timer = null; + // With a target, the window also WRITES BACK a programmatic displacement + // (#1428). The browser owns the restore now, and its replay is the offset IT + // recorded for the entry, which can DISAGREE with the snapshot: an entry the + // router snapshotted without the reader having scrolled there under the UA's + // observation carries a stale 0. This write-back is what reconciles the two, + // and it is the only thing that does, so it is not redundant with the UA + // being correct in the common case. A user can never trigger + // this listener first: every release event is a CAPTURE-phase input + // listener (wheel / touchmove / keydown / pointerdown), and each of those + // fires BEFORE the scroll event that follows it, so by the time a + // user-driven scroll lands here the window is already closed. What remains + // is exactly a programmatic non-user write inside the restore's own span, + // which is the one thing the restore may overrule. Re-entry is benign: the + // write-back's own scroll event arrives on-target and returns. + // + // It is armed only BRIEFLY, not for the window's full life. The thing it + // exists to reconcile is one event, the UA's replay of its own recorded + // offset, which lands about a frame after the popstate handler. Left armed + // for the window's life (the revalidation settle, or up to the 2s ceiling) + // it would spend seconds reverting any programmatic scroll, and the longer it + // stands the more it claims. 250ms bounds that. + // + // It does NOT make the write-back harmless, and the honest statement is that + // a programmatic scroll inside the arming span still loses to the restore. A + // component calling `scrollIntoView()` from `connectedCallback` as the + // restored page upgrades, or an autofocus on a below-fold control, runs a + // microtask or a frame after the swap, which is INSIDE 250ms, so it is + // reverted. That is the deliberate precedence on a Back: the reader asked for + // the page they left, not for wherever a component jumped while rehydrating. + // What the bound buys is that a scroll a second later, which has nothing to + // do with the restore, is left alone; find-in-page from the browser chrome is + // the case that matters there, since it fires no page `keydown` and so does + // not close the window the way a real key press would. + // + // Bounded by TIME rather than by a correction count. A count is the obvious + // bound and it is wrong: a single-shot can be spent on an unrelated scroll + // event that happens to arrive before the UA's replay, after which the stale + // replay stands uncorrected. That reproduced on Firefox as an intermittent, + // roughly one run in three. A short arming span covers the replay whenever it + // lands, however many events precede it. + let armed = typeof targetY === 'number'; + const disarm = () => { armed = false; }; + const armTimer = armed && typeof setTimeout === 'function' + ? setTimeout(disarm, WRITE_BACK_ARMED_MS) : null; + const onScroll = (typeof targetY === 'number' && typeof window !== 'undefined') + ? () => { + if (!armed) return; + if (Math.abs(window.scrollY - targetY) <= 1 && Math.abs(window.scrollX - (targetX || 0)) <= 1) return; + window.scrollTo({ left: targetX || 0, top: targetY, behavior: 'instant' }); + } + : null; const release = () => { // Only the window that installed this release may close it. if (releaseScrollAnchor !== release) return; releaseScrollAnchor = null; if (timer) { clearTimeout(timer); timer = null; } + if (armTimer) clearTimeout(armTimer); + armed = false; if (typeof window !== 'undefined') { for (const ev of ANCHOR_RELEASE_EVENTS) { window.removeEventListener(ev, release, /** @type {any} */ ({ capture: true })); } + if (onScroll) window.removeEventListener('scroll', onScroll); } if (prev) root.style.setProperty('overflow-anchor', prev); else root.style.removeProperty('overflow-anchor'); @@ -91,22 +151,76 @@ export function suppressScrollAnchoring() { for (const ev of ANCHOR_RELEASE_EVENTS) { window.addEventListener(ev, release, { capture: true, passive: true }); } + if (onScroll) window.addEventListener('scroll', onScroll, { passive: true }); } return release; } /** - * Cancels an in-flight catch-up, or null when none is running. + * Closes the currently held height reservation, or null when none is open. * @type {(() => void) | null} */ -export let cancelScrollCatchUp = null; +export let releaseHeightReservation = null; + +/** + * Reserve the restored page's SETTLED height across a Back/Forward restore + * (#1428 architecture). + * + * A restore re-inserts an outerHTML snapshot, and that markup is SHORTER than + * the page it was serialized from until its components upgrade and re-render a + * beat later. Every scroll defect in this file's history lived in that window: + * the browser clamped the recorded offset against the short document (#1310's + * clamped band, formerly healed by a chase), and the UA's own restoration + * landed short the same way. Holding the settled height on the ROOT element + * makes the recorded offset reachable from the first frame, so a restore lands + * exactly, once, and the clamp class cannot occur at all. + * + * The root and not ``, because the restore REPLACES the whole body, so + * an inline style there would leave with the old node. Same + * save-and-put-back contract as `overflow-anchor` above. + * + * Released on the restore's settle, on the ceiling, and on supersede (a new + * page navigation, a submission, disabling the router). NEVER on user input: + * the window releases early for a reader taking over, but yanking the page's + * height out from under a reader mid-scroll is the one harm an early release + * here could cause, so this deliberately does not share that trigger. + * + * @param {number} px the snapshot's recorded `scrollHeight` + * @returns {() => void} Idempotent release. + */ +export function reserveRestoredHeight(px) { + if (typeof document === 'undefined' || !document.documentElement) return () => {}; + // A second reservation supersedes the first, and does so BEFORE the height + // guard below. Ordering it after would let a restore with no recorded height + // (a legacy string snapshot, `scrollHeight: 0`) return early while the + // PREVIOUS page's min-height stayed pinned to the root until the ceiling. + // Superseding first means every restore clears its predecessor, whether or + // not it has a height of its own to hold. + if (releaseHeightReservation) releaseHeightReservation(); + if (!(px > 0)) return () => {}; + const root = document.documentElement; + const prev = root.style.getPropertyValue('min-height'); + root.style.setProperty('min-height', px + 'px'); + /** @type {ReturnType | null} */ + let timer = null; + const release = () => { + if (releaseHeightReservation !== release) return; + releaseHeightReservation = null; + if (timer) { clearTimeout(timer); timer = null; } + if (prev) root.style.setProperty('min-height', prev); + else root.style.removeProperty('min-height'); + }; + releaseHeightReservation = release; + timer = setTimeout(release, ANCHOR_SUPPRESS_CEILING_MS); + return release; +} /** * Bumped wherever a restore is superseded (#1310), and read by the one restore * path that outlives the call scheduling it. That means a PAGE navigation, a * PAGE-level submission, and disabling the router. A frame-targeted nav or * submission swaps one region and leaves the page, so it is excluded, exactly - * like the `loadFrame` case below. + * like the `loadFrame` case. * * Deliberately NOT `currentNavigationToken`, which is the obvious choice and the * wrong one: `loadFrame` bumps that too, and its own contract says a frame @@ -119,120 +233,6 @@ export let cancelScrollCatchUp = null; */ export let restoreGeneration = 0; -/** - * Chase a restored scroll offset the document was too SHORT to reach (#1310). - * - * The sibling of `suppressScrollAnchoring`, for the case that one deliberately - * declines. When the recorded offset is past the un-grown document's maximum, - * the browser clamps, and anchoring then adds the growth back as the page - * settles. That lands a reader who left at the very bottom back at the bottom, - * because there the shortfall and the growth are the same number. It is wrong - * for everyone else: anchoring adds the FULL growth whatever the shortfall was, - * so a reader who left 100px above the bottom is carried 100px too far. - * - * This re-asserts the recorded offset once the document can actually hold it, - * which is the only moment the number becomes reachable, and then stops. - * - * It is deliberately narrow, because #1310 rejected re-asserting the scroll in - * the general case and that reasoning still holds. The difference is that this - * knows exactly where it is going and can tell when it has arrived: it runs - * ONLY on the clamped path, only while the offset is still out of reach, writes - * once, and stops on the first real input. - * - * It does NOT escape the settling-versus-streaming question, and it is worth - * being exact about that rather than claiming otherwise. It cannot tell the - * restore settling apart from any other growth, so the guard is its WINDOW: it - * lives for `ANCHOR_SUPPRESS_FLOOR_MS` from the RESTORE and no longer. That is - * tighter than the window a landed restore gets, which runs to the later of the - * floor and the revalidation and is capped by the ceiling, and deliberately so, - * because this path WRITES scroll. The suppression this path installs once the - * chase lands is part of the same window, not a second one: it shares this - * deadline, so the whole clamped path is bounded by one floor measured from the - * restore however late the landing happens. - * - * Be precise about what the bound does and does not buy, since it is easy to - * overclaim in both directions. WHILE the window is open the reader is - * protected: until the offset is reachable there is nothing to protect, and - * from the moment the chase lands on it, suppression holds it against the rest - * of the growth. AFTER the window closes, both halves stop: the router writes - * no more scroll, and anchoring is back on, so any growth still arriving is - * added to `scrollY` and carries the reader down toward the bottom, which is - * main's behaviour. So the cost of a component that settles later than the - * window is that the reader drifts below the offset, not that they sit at the - * clamp. - * - * @param {number} targetY The recorded offset to reach. - * @param {number} targetX - */ -export function catchUpToRestoredScroll(targetY, targetX) { - if (typeof window === 'undefined' || typeof requestAnimationFrame !== 'function') return; - if (cancelScrollCatchUp) cancelScrollCatchUp(); - let rafId = 0; - /** @type {ReturnType | null} */ - let timer = null; - /** Release for the suppression installed once the offset is reached. */ - let releaseLanded = null; - const stop = () => { - if (cancelScrollCatchUp !== stop) return; - cancelScrollCatchUp = null; - if (rafId) cancelAnimationFrame(rafId); - if (timer) { clearTimeout(timer); timer = null; } - if (releaseLanded) { releaseLanded(); releaseLanded = null; } - for (const ev of ANCHOR_RELEASE_EVENTS) { - window.removeEventListener(ev, stop, /** @type {any} */ ({ capture: true })); - } - }; - const tick = () => { - if (cancelScrollCatchUp !== stop) return; - const maxY = document.documentElement.scrollHeight - window.innerHeight; - if (maxY >= targetY) { - // Reachable at last. Land the reader on the recorded offset. - window.scrollTo({ left: targetX, top: targetY, behavior: 'instant' }); - // And then protect it, because landing is not the end of the story. The - // growth that made the offset reachable is rarely all of it: the real - // cause is components upgrading one at a time, so more arrives after - // this. Anchoring is still on here, deliberately, so every later stage - // would be added on top of the offset just written and carry the reader - // below it again. Measured on a two-stage fixture, an offset of 4000 - // ended at 5000. - // - // Once the reader IS on the recorded offset the situation is identical to - // a restore that landed on its first try, so it gets that case's - // protection for what remains. - // - // It shares THIS chase's deadline rather than starting one of its own, - // which matters: a fresh floor-length timer here would start at landing - // rather than at the restore, so the clamped path could hold anchoring - // off for nearly twice the floor and stop being the tighter of the two - // windows, which is the whole reason for the bound. `stop` owns the - // release, so the existing timer and the input listeners close it. - releaseLanded = suppressScrollAnchoring(); - // Deliberately NOT `stop()`: the window has to outlive the landing, up to - // the deadline already running. - if (rafId) { cancelAnimationFrame(rafId); rafId = 0; } - return; - } - rafId = requestAnimationFrame(tick); - }; - cancelScrollCatchUp = stop; - // Same inputs that close a suppression window: the reader has taken over. - for (const ev of ANCHOR_RELEASE_EVENTS) { - window.addEventListener(ev, stop, { capture: true, passive: true }); - } - // Bounded by the FLOOR, not the ceiling. The ceiling is a backstop for a hung - // fetch; this is a scroll WRITE, so its window is the one thing that decides - // whether a reader can be moved without asking. Any growth past the target - // fires it, and growth is not exclusively the restore settling: a - // boundary resolving, a lazy component entering, or a late - // image would all qualify. Holding it open for the full ceiling would mean a - // reader who landed and started READING, and so generates no input to cancel - // it, could be scrolled up to two seconds after pressing Back. The floor - // covers the restore's own settling, which is what it is for, and is measured - // in a few hundred milliseconds rather than seconds. - timer = setTimeout(stop, ANCHOR_SUPPRESS_FLOOR_MS); - rafId = requestAnimationFrame(tick); -} - /** * Run `fn` after two animation frames, so a just-applied DOM has laid out * before it reads or acts. Falls back to a macrotask where diff --git a/packages/core/src/router-client/snapshot-cache.js b/packages/core/src/router-client/snapshot-cache.js index 0bb48869e..ec20bc4c3 100644 --- a/packages/core/src/router-client/snapshot-cache.js +++ b/packages/core/src/router-client/snapshot-cache.js @@ -8,7 +8,7 @@ */ import { SNAPSHOT_CAP } from './constants.js'; -/** @typedef {{ html: string, scrollX: number, scrollY: number }} Snapshot */ +/** @typedef {{ html: string, scrollX: number, scrollY: number, scrollHeight: number }} Snapshot */ /** @type {Map} */ export const snapshotCache = new Map(); @@ -41,6 +41,15 @@ export function snapshotCurrent(url) { html: document.documentElement.outerHTML, scrollX: typeof window !== 'undefined' ? window.scrollX || 0 : 0, scrollY: typeof window !== 'undefined' ? window.scrollY || 0 : 0, + // The page's SETTLED height, captured at the same moment as the offset. + // A restore re-inserts this snapshot as raw markup, and the document is + // SHORTER than this until its components upgrade and re-render, which is + // the window every scroll defect in #1310 lived in. The restore reserves + // this height across that window (#1428 architecture), so the recorded + // offset is reachable from the first frame and the browser's own + // restoration lands exactly, with no clamp and nothing to chase. + scrollHeight: typeof document !== 'undefined' && document.documentElement + ? document.documentElement.scrollHeight || 0 : 0, }; snapshotCache.set(key, snap); while (snapshotCache.size > SNAPSHOT_CAP) { @@ -64,7 +73,14 @@ export function snapshotGet(url) { // Move-to-front. snapshotCache.delete(key); snapshotCache.set(key, v); - if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0 }; + // A legacy string entry carries no offsets and no height. `scrollHeight: 0` + // is stated rather than left undefined so the returned object satisfies the + // `Snapshot` typedef, and because `reserveRestoredHeight` treats a + // non-positive height as "nothing to reserve" and no-ops: there is no + // recorded height to hold, so reserving is not merely skippable, it is + // meaningless. Such an entry restores with no reservation, which is the + // pre-#1428 behaviour and correct for a snapshot that never recorded one. + if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0, scrollHeight: 0 }; return v; } diff --git a/packages/core/src/router-client/swap.js b/packages/core/src/router-client/swap.js index 4292661f5..5780da016 100644 --- a/packages/core/src/router-client/swap.js +++ b/packages/core/src/router-client/swap.js @@ -51,10 +51,13 @@ export let _swapCommit = Promise.resolve(); * DOM mutation, for the same reason `ingestSeeds` is: this function can still * decide to throw the response away after parsing it, and a `pushState` * issued for a swap that never happened is worse than a late one. It runs - * BEFORE the incoming document replaces what is on screen, because WebKit - * binds a same-document entry's back-forward gesture snapshot to the page - * state at the moment the entry is recorded, and a snapshot taken against - * the incoming (often shorter) document previews blank. + * BEFORE the incoming document replaces what is on screen, so the entry for + * the page being left is finalized while that page is still the live + * document (#1406, and Turbo Drive's ordering). + * + * NOTE: #1406 believed this ordering fixed the blank iOS back-swipe + * preview. It does not, shown on-device in #1428; the cause was + * `history.scrollRestoration = 'manual'`. * * "Before the content swap" is the precise claim, NOT "before anything on * the page has changed". The page may already have been mutated by the time diff --git a/packages/core/test/rendering/form-action-attr-guard-client.test.js b/packages/core/test/rendering/form-action-attr-guard-client.test.js index 96797d273..b3cd5aa46 100644 --- a/packages/core/test/rendering/form-action-attr-guard-client.test.js +++ b/packages/core/test/rendering/form-action-attr-guard-client.test.js @@ -247,8 +247,18 @@ test('client still renders an array of plain strings', () => { test('a self-referential array does not crash the render', () => { // `Array.prototype.join` has a cycle guard, so `String(cyclic)` is ''. The // function check has to match that rather than recurse forever. - const cyclic = []; - cyclic.push(cyclic); + const cyclicProbe = []; + cyclicProbe.push(cyclicProbe); + // SKIPPED where the engine's own cycle guard is broken. Bun 1.4.0 regressed + // `Array.prototype.join`'s, so `String(a)` throws RangeError for + // `const a = []; a.push(a)` with no framework involved (node and Bun 1.3.14 + // both return ''). Keyed to the BEHAVIOUR, not a version, so this returns + // automatically once the engine is fixed. See test/bun/form-action-guard.mjs + // for the full note on why this is scoped rather than worked around. + let engineJoinsCycles = true; + try { String(cyclicProbe); } catch { engineJoinsCycles = false; } + if (!engineJoinsCycles) return; + const cyclic = cyclicProbe; const host = document.createElement('div'); render(html`
`, host); assert.equal(host.querySelector('form').getAttribute('action'), ''); diff --git a/packages/core/test/rendering/form-action-attr-guard.test.js b/packages/core/test/rendering/form-action-attr-guard.test.js index 9b03a4926..de35c72e5 100644 --- a/packages/core/test/rendering/form-action-attr-guard.test.js +++ b/packages/core/test/rendering/form-action-attr-guard.test.js @@ -499,8 +499,18 @@ test('a self-referential array renders instead of overflowing the stack', async // `Array.prototype.join` has a cycle guard, so `String(cyclic)` is ''. The // function walk has to match that; a naive recursion turned a render that // used to succeed into a RangeError. - const cyclic = []; - cyclic.push(cyclic); + const cyclicProbe = []; + cyclicProbe.push(cyclicProbe); + // SKIPPED where the engine's own cycle guard is broken. Bun 1.4.0 regressed + // `Array.prototype.join`'s, so `String(a)` throws RangeError for + // `const a = []; a.push(a)` with no framework involved (node and Bun 1.3.14 + // both return ''). Keyed to the BEHAVIOUR, not a version, so this returns + // automatically once the engine is fixed. See test/bun/form-action-guard.mjs + // for the full note on why this is scoped rather than worked around. + let engineJoinsCycles = true; + try { String(cyclicProbe); } catch { engineJoinsCycles = false; } + if (!engineJoinsCycles) return; + const cyclic = cyclicProbe; const out = await renderToString(html`
`, { ssr: true }); assert.match(out, /action=""/); }); diff --git a/packages/core/test/routing/browser/nav-history-before-swap.test.js b/packages/core/test/routing/browser/nav-history-before-swap.test.js index a109b084e..278124e18 100644 --- a/packages/core/test/routing/browser/nav-history-before-swap.test.js +++ b/packages/core/test/routing/browser/nav-history-before-swap.test.js @@ -2,18 +2,25 @@ * Real-browser test for #1406: the client router must record a forward * navigation's history entry BEFORE it swaps the DOM. * - * WebKit binds a same-document (`pushState`) entry's back-forward gesture - * snapshot to the page state at the moment the entry is recorded. The router - * used to push AFTER `applySwap`, so the entry for the OUTGOING url was - * finalized against the INCOMING document, at a scroll offset the browser had - * already clamped to that document's height. On iOS the edge back-swipe then - * previews a page that never existed and renders blank (measured on - * `gallery.webjs.dev`: an offset of 1600 clamped to 252 at the push). + * The router used to push AFTER `applySwap`, so the entry for the OUTGOING url + * was finalized against the INCOMING document, at a scroll offset the browser + * had already clamped to that document's height (measured on + * `gallery.webjs.dev`: an offset of 1600 clamped to 252 at the push). An entry + * should be recorded against the page it belongs to, which is what this pins. * - * The pixels are iOS-only and cannot be asserted here. What CAN be asserted - * anywhere is the state the browser captures FROM, which is exactly the thing - * that was wrong: at the `pushState` call, the document must still hold the - * outgoing page and `window.scrollY` must still hold the outgoing offset. + * WHAT THIS TEST DOES NOT PROVE, corrected after #1428: #1406 introduced the + * ordering as the fix for the blank iOS back-swipe preview, on the theory that + * WebKit binds the gesture snapshot to page state at the moment the entry is + * recorded. That theory is false. Turbo Drive has this exact ordering and + * previews blank the same way, and the preview was actually fixed by stopping + * the router setting `history.scrollRestoration = 'manual'`, which had + * suppressed the browser's per-entry scroll recording. Both were verified on a + * real iPhone. This guard is kept because the ordering is correct on its own + * merits, not because it fixes that bug. + * + * What CAN be asserted anywhere is the state the browser captures FROM: at the + * `pushState` call, the document must still hold the outgoing page and + * `window.scrollY` must still hold the outgoing offset. * * This has to be a real browser: the assertion is about a scroll offset the * engine clamps against real layout, and linkedom has neither. diff --git a/packages/core/test/routing/browser/nav-scroll-anchor-restore.test.js b/packages/core/test/routing/browser/nav-scroll-anchor-restore.test.js index 10d69b9c8..5d3f8f0e2 100644 --- a/packages/core/test/routing/browser/nav-scroll-anchor-restore.test.js +++ b/packages/core/test/routing/browser/nav-scroll-anchor-restore.test.js @@ -171,7 +171,7 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => async function setup(opts) { const instant = Boolean(opts && opts.instantRevalidation); const restoredY = (opts && opts.restoredY) != null ? opts.restoredY : RESTORED_Y; - const outgoingHeight = (opts && opts.tallOutgoing) ? 60000 : 3000; + const outgoingHeight = (opts && opts.tallOutgoing) ? 60000 : restoredY + 2000; const html = restoredHtml( (opts && opts.manualGrowth) ? 'wj-grow-on-command-1310' : instant ? 'wj-grow-very-late-1310' : 'wj-grow-late-1310', @@ -227,10 +227,31 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => // synthetic popstate event would not exercise the browser's own restore. origUrl = location.href; history.pushState(null, '', entryUrl('anchor-a')); + { + // Let the BROWSER record a real offset for this entry, by actually + // scrolling before pushing the next one. Every other case injects the + // offset into the snapshot cache while the page sits at 0, so the UA has + // only ever recorded 0 for `anchor-a`, which is fine when the router owns + // the restore but makes it impossible to observe what the UA would do on + // its own. A single-writer assertion needs the UA's own recording to be + // the real thing (#1428). + window.scrollTo({ top: restoredY, left: 0, behavior: 'instant' }); + await new Promise((r) => setTimeout(r, 60)); + } history.pushState(null, '', entryUrl('anchor-b')); entriesPushed = true; + // `scrollHeight` is what the restore RESERVES across the swap (#1428), so + // a fixture without it leaves the reservation inert and every assertion + // below passes for the wrong reason. A real snapshot's offset is always + // reachable within its own recorded height (you cannot scroll past the + // document), so the fixture models that: enough height to hold the offset + // plus a viewport, unless a case overrides it to test the reservation + // itself. _snapshotCache.set(entryUrl('anchor-a'), { html, scrollX: 0, scrollY: restoredY, + scrollHeight: (opts && opts.scrollHeight !== undefined) + ? opts.scrollHeight + : restoredY + window.innerHeight, }); _setCurrentPageUrl(location.href); // Start where the reader was, so the restore is a real scroll rather than @@ -277,30 +298,6 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => enableClientRouter(); } - test('a CLAMPED restore is left alone, so the reader is not stranded high', async () => { - // The mirror image of this bug, and the reason suppression is conditional. - // - // A document that has not grown yet can be too short to scroll to the - // recorded offset at all, so the browser clamps to its current maximum. The - // shortfall is then the growth still to come, and anchoring adding that - // growth is what carries the reader back down. Suppressing there would - // freeze the clamp and strand them a full page-growth ABOVE where they - // left, measured at 763px on the reported page: the same error as the bug, - // pointing the other way. - // - // The recorded offset here is far past anything the un-grown document can - // reach, so the clamp is certain whatever the runner's viewport height is. - await setup({ restoredY: 50000 }); - try { - await goBack(); - assert.ok(window.scrollY < 50000, - 'precondition: the restore was clamped, so this is the case under test'); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', - 'a clamped restore installs no window while the offset is out of ' - + 'reach, leaving the browser to heal the clamp as the page grows'); - } finally { await teardown(); } - }); - test('a second navigation inside the window closes it', async () => { // The window deliberately outlives its own restore (a floor, then a // ceiling), so a navigation starting inside that span must end it. Without @@ -323,42 +320,6 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => } finally { await teardown(); } }); - test('under a view transition the decision waits for the swap to commit', async () => { - // `applySwap` defers its DOM mutation a frame when a transition is running, - // so writing and measuring the scroll straight through would act on the - // OUTGOING page. Here that page is far taller than the restored one, so a - // decision taken against it says "landed" and suppresses anchoring, and the - // restored page then clamps with anchoring held off. That is the stranding - // the clamped path exists to avoid, arriving by a different route. - // - // The transition is SIMULATED. A hidden document skips a real one, and the - // runner puts test files in concurrent pages, so the deferred path is not - // otherwise reachable from this suite on any engine. The stub defers the - // callback exactly as the spec does. - const origSVT = (/** @type any */ (document)).startViewTransition; - let transitions = 0; - (/** @type any */ (document)).startViewTransition = (cb) => { - transitions += 1; - const done = new Promise((resolve) => { - requestAnimationFrame(() => { cb(); resolve(); }); - }); - return { updateCallbackDone: done, finished: done, ready: done, skipTransition() {} }; - }; - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true, viewTransition: true, tallOutgoing: true }); - try { - await goBack(); - assert.ok(transitions > 0, - 'precondition: the swap actually ran through a view transition'); - for (let i = 0; i < 4; i++) await frame(); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', - 'the clamp is judged against the restored page, so a restore that ' - + 'clamps leaves anchoring alone rather than freezing it'); - } finally { - await teardown(); - (/** @type any */ (document)).startViewTransition = origSVT; - } - }); - test('a navigation during a deferred restore cancels it, not the other way round', async () => { // The view-transition path is the one place the restore OUTLIVES the call // that scheduled it, and every cancel site in this feature runs at the start @@ -492,6 +453,47 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => } finally { await teardown(); } }); + test('a FRAME-targeted navigation does not scroll the restored page (#1428)', async () => { + // The write-back added for #1428 lives in the restore window, and a frame + // nav is the one navigation that deliberately leaves that window OPEN. So + // the two features meet here and nothing covered it: the test above asserts + // only that the window survives, not where the reader ends up. + // + // When this was written, a click-driven frame nav reached `fetchAndApply` + // with `recordHistory: true` and the scroll block had no `frameId` guard, + // so it ran the forward-nav scroll-to-top even though it swaps one region + // rather than the page, and inside an open restore that dropped the reader + // to the top of a page they had just come back to. #1429 has since fixed + // that at the source: the scroll block now excludes frame-scoped responses + // outright, so the stray scroll no longer happens at all. + // + // The case is kept because it asserts the OUTCOME rather than the + // mechanism, and the outcome is what must hold however the internals move: + // a frame swap must never disturb a restore in progress. It is now + // defended twice over, by #1429's guard and by the restore window. + await setup(); + try { + await goBack(); + await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `precondition: the restore landed (got ${window.scrollY})`); + const holder = document.createElement('div'); + holder.innerHTML = '' + + 'go'; + document.body.appendChild(holder); + try { + holder.querySelector('#wj-frame-link-1310b').click(); + await new Promise((r) => setTimeout(r, 0)); + assert.ok(frameNavs > 0, + 'precondition: the click reached the router as a frame-targeted nav'); + await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `a frame swap must not move the reader off a restore in progress ` + + `(expected ~${RESTORED_Y}, got ${window.scrollY})`); + } finally { holder.remove(); } + } finally { await teardown(); } + }); + test('a FRAME-targeted submission leaves an open window alone', async () => { // The submission half of the frame exemption. `performSubmission` has its // own `!frameId` guard, and nothing exercised it: the page-level submission @@ -553,165 +555,6 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => } }); - test('a clamped restore is CHASED to the exact recorded offset', async () => { - // Leaving anchoring on is not enough on its own. It adds the FULL growth - // whatever the shortfall was, so it only lands a reader who left at the very - // bottom, where those two numbers coincide; anyone above that is carried too - // far (1902 came back as 2002 on /ui/button). The catch-up re-asserts the - // recorded offset the moment the page is tall enough to hold it. - // - // The target sits inside the band only the grown page can reach, and the - // fixture grows by 3000px so that band does not depend on the runner's - // viewport height. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - assert.ok(window.scrollY < CLAMPED_TARGET - 1, - `precondition: the restore was clamped (got ${window.scrollY} for ${CLAMPED_TARGET})`); - // Now make the offset reachable, which is what the catch-up waits for. - document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; - for (let i = 0; i < 12; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, - 'the catch-up lands on the recorded offset once it is reachable ' - + `(expected ~${CLAMPED_TARGET}, got ${window.scrollY})`); - } finally { await teardown(); } - }); - - test('landing on the offset opens a window, which closes on the chase deadline', async () => { - // The landed suppression had no assertion on it at all: every clamped case - // reads `scrollY` only, and the one that reads `overflow-anchor` uses an - // offset that never becomes reachable, so it never lands. Deleting the - // suppression left every suite green apart from the staged-growth case. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', - 'precondition: a clamped restore opens no window while the offset is ' - + 'still out of reach'); - document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; - for (let i = 0; i < 6; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, - 'precondition: the chase landed'); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), 'none', - 'landing on the recorded offset protects it, since the growth that ' - + 'made it reachable is rarely all of it'); - // The window rides the chase's own deadline, measured from the restore. - await new Promise((r) => setTimeout(r, 900)); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', - 'and it closes on that deadline, leaving no residue'); - } finally { await teardown(); } - }); - - test('the landed window ends on the RESTORE deadline, not its own', async () => { - // The discriminating case for whose clock the landed window runs on. Both a - // shared deadline and a fresh one suppress at landing and are shut by the - // time the page has settled, so a case that lands early and looks late - // cannot tell them apart, which is what the first attempt at this did. - // - // Landing LATE separates them. The chase is bounded from the restore, so a - // landing at ~380ms leaves roughly 120ms of window; a window starting its - // own floor at landing would instead run to ~880ms. Observing in between is - // the only place the two differ. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - // Late enough that the two clocks diverge, early enough to keep real - // margin on both sides. The chase's deadline is 500ms from the restore, - // so growing at ~250ms leaves ~250ms for the tick that lands it, and the - // sample below sits ~120ms past the restore deadline and ~135ms short of - // where a fresh floor started at landing would expire. An earlier draft - // grew at 380ms and left only ~115ms for that tick, which is the shape - // that produced the one-in-three Firefox flake recorded above. - await new Promise((r) => setTimeout(r, 250)); - document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; - for (let i = 0; i < 4; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, - `precondition: the chase landed late but did land (got ${window.scrollY})`); - // Past the restore's deadline, well short of landing plus a fresh floor. - await new Promise((r) => setTimeout(r, 350)); - assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', - 'the landed window rides the deadline that started at the RESTORE, so ' - + 'it is shut by now; on its own floor it would still be open'); - } finally { await teardown(); } - }); - - test('a clamped restore survives growth that arrives in STAGES', async () => { - // The real cause of the growth is components upgrading and rendering one at - // a time, so it arrives in pieces. Every other clamped case grows in a - // single assignment, which is the easy shape: the catch-up writes the offset - // once and the page never moves again. With staged growth the page keeps - // growing after that write, and anchoring is deliberately left ON here, so - // each later stage is added on top of the offset and carries the reader - // below it. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - assert.ok(window.scrollY < CLAMPED_TARGET - 1, 'precondition: clamped'); - const grower = document.querySelector('wj-grow-on-command-1310'); - // Stage one makes the offset EXACTLY reachable, computed from the live - // viewport so it lands on the threshold rather than near it: the fixture - // filler is 3000px, so a grower of `target + innerHeight - 3000` puts the - // document's maximum scroll precisely at the target. That is the frame - // the catch-up writes and stops on. Stage two then adds more above the - // viewport, which is the growth that must not be counted on top. - const stageOne = CLAMPED_TARGET + window.innerHeight - 3000; - grower.style.height = stageOne + 'px'; - for (let i = 0; i < 6; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, - `precondition: stage one let the catch-up land (got ${window.scrollY})`); - grower.style.height = (stageOne + 1000) + 'px'; - for (let i = 0; i < 12; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, - 'staged growth must still land on the recorded offset ' - + `(expected ~${CLAMPED_TARGET}, got ${window.scrollY})`); - } finally { await teardown(); } - }); - - test('the catch-up gives up after its window, and does not move a settled reader', async () => { - // The bound is a live behaviour constant: past it a clamped restore stops - // chasing. The other two catch-up cases grow the fixture immediately, so - // they pass at any bound and none of them would notice it being widened - // back to the ceiling. This is the case that pins it, and it is the reason - // the bound exists: a reader who landed and started READING generates no - // input to cancel the chase, so late-arriving growth must not scroll them. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - const clamped = window.scrollY; - assert.ok(clamped < CLAMPED_TARGET - 1, 'precondition: the restore was clamped'); - // Past the window, with no input at any point. - await new Promise((r) => setTimeout(r, 900)); - document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; - for (let i = 0; i < 12; i++) await frame(); - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) >= 5, - 'growth arriving after the window must not scroll a reader who never ' - + `asked (landed on ${CLAMPED_TARGET}, so the chase was still live)`); - } finally { await teardown(); } - }); - - test('a reader taking over cancels the catch-up', async () => { - // The catch-up WRITES scroll, unlike suppression, so it is the one part of - // this that could yank someone. It stops on the same inputs a suppression - // window closes on, before the offset becomes reachable. - await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); - try { - await goBack(); - assert.ok(window.scrollY < CLAMPED_TARGET - 1, - 'precondition: the restore was clamped'); - // The reader takes over BEFORE the offset becomes reachable. - window.dispatchEvent(new WheelEvent('wheel', { bubbles: true })); - document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; - for (let i = 0; i < 12; i++) await frame(); - // Asserted as "the catch-up never wrote", not as "nothing moved". The - // clamped path deliberately leaves anchoring ON, so the browser still - // carries the position as the page grows, exactly as it does on main. - // What must not happen is this code adding a write of its own on top. - assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) >= 5, - 'a reader who has taken over is never scrolled onto the recorded ' - + `offset (landed exactly on ${CLAMPED_TARGET}, so the catch-up wrote)`); - } finally { await teardown(); } - }); - test('anchoring WORKS again once the window has closed', async () => { // The inverse of the headline, and the regression that would matter most if // this fix were wrong: suppression is temporary, so once the restore is over @@ -771,6 +614,128 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => } finally { await teardown(); } }); + test('a restore the BROWSER recorded lands on the offset through a short swap (#1428)', async () => { + // The single-writer case, and the DEFAULT fixture shape: `setup` scrolls to + // the recorded offset before pushing the next entry, so the browser has a + // real per-entry offset to replay rather than the 0 an injected fixture + // leaves it with. + // + // The snapshot is still SHORT at swap time, which is the shape that used to + // clamp. With the height reserved the offset is reachable, so the UA's + // replay lands on it and the router writes nothing. This is the assertion + // that had to hold for the router to stop writing scroll at all. + await setup(); + try { + await goBack(); + await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `the reader lands on the recorded offset (got ${window.scrollY})`); + await afterGrowth(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `and stays there once the page fills in (got ${window.scrollY})`); + } finally { await teardown(); } + }); + + test('the reservation makes the recorded offset reachable on the FIRST frame (#1428)', async () => { + // The architecture change. The snapshot markup is far shorter than the page + // it was serialized from until its components render, so the recorded + // offset used to be unreachable and the browser clamped to whatever the + // short document allowed. That clamp is what the old catch-up chase existed + // to heal, after the fact. + // + // Reserving the recorded height across the swap removes the shortness + // instead of compensating for it, so the offset is reachable immediately + // and the restore lands exactly, once. `manualGrowth` keeps the fixture + // short until this test grows it, so nothing but the reservation can be + // making the offset reachable here. + await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true }); + try { + await goBack(); + // Frame granularity, the user-visible contract. The UA performs a restore + // of its own a beat after the handler, and in THIS harness it writes 0: + // the fixture pushes its entries from a page at offset 0 and injects the + // recorded offset straight into the snapshot cache, so the browser never + // saw a real offset for that entry. The restore window's write-back + // corrects it on the next frame, which is what a reader sees. + await frame(); + assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, + `the offset is reachable with no clamp and no chase (got ${window.scrollY})`); + // And it holds once the real content arrives and the reservation is no + // longer what is carrying the height. + document.querySelector('wj-grow-on-command-1310').style.height = COMMANDED_GROWTH + 'px'; + for (let i = 0; i < 6; i++) await frame(); + assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, + `and the reader stays there as the page fills in (got ${window.scrollY})`); + } finally { await teardown(); } + }); + + test('the reservation leaves no residue once the restore is over (#1428)', async () => { + // It is an inline style on the ROOT, so it must be put back exactly like + // the anchoring window's `overflow-anchor`, or every restored page would + // keep a stale min-height for the life of the document. + await setup(); + try { + await goBack(); + assert.ok(document.documentElement.style.getPropertyValue('min-height') !== '', + 'precondition: the reservation is held across the restore'); + releaseFetch(); + releaseFetch = null; + await new Promise((r) => setTimeout(r, 800)); + assert.equal(document.documentElement.style.getPropertyValue('min-height'), '', + 'the router leaves no height of its own on the root after the restore'); + } finally { await teardown(); } + }); + + test('a second navigation releases the reservation (#1428)', async () => { + // Same supersede rule the anchoring window follows: the reservation + // outlives its own restore, so a navigation starting inside that span must + // end it rather than hold another page tall. + await setup(); + try { + await goBack(); + assert.ok(document.documentElement.style.getPropertyValue('min-height') !== '', + 'precondition: the reservation is held'); + navigate(location.origin + entryUrl('second-nav-1428')).catch(() => {}); + await new Promise((r) => setTimeout(r, 0)); + assert.equal(document.documentElement.style.getPropertyValue('min-height'), '', + 'starting another navigation releases the previous restore\'s reservation'); + } finally { await teardown(); } + }); + + test('under a view transition the restore still lands on the recorded offset (#1428)', async () => { + // `applySwap` defers its DOM mutation a frame under a transition, so the + // scroll write must wait for the commit or it acts on the OUTGOING page. + // The outgoing page here is far taller than the restored one, which is the + // shape that used to produce a wrong decision. The reservation is taken + // before the swap either way, so the offset is reachable when the write + // finally lands. + // + // The transition is SIMULATED: a hidden document skips a real one, and the + // runner puts test files in concurrent pages, so the deferred path is not + // otherwise reachable here. The stub defers the callback as the spec does. + const origSVT = (/** @type any */ (document)).startViewTransition; + let transitions = 0; + (/** @type any */ (document)).startViewTransition = (cb) => { + transitions += 1; + const done = new Promise((resolve) => { + requestAnimationFrame(() => { cb(); resolve(); }); + }); + return { updateCallbackDone: done, finished: done, ready: done, skipTransition() {} }; + }; + await setup({ restoredY: CLAMPED_TARGET, manualGrowth: true, viewTransition: true, tallOutgoing: true }); + try { + await goBack(); + assert.ok(transitions > 0, + 'precondition: the swap actually ran through a view transition'); + for (let i = 0; i < 4; i++) await frame(); + assert.ok(Math.abs(window.scrollY - CLAMPED_TARGET) < 5, + `the deferred restore lands on the recorded offset (got ${window.scrollY})`); + } finally { + await teardown(); + (/** @type any */ (document)).startViewTransition = origSVT; + } + }); + test('the restore opens a scroll-anchoring window', async () => { await setup(); try { @@ -785,9 +750,17 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => await setup(); try { await goBack(); + // Read at FRAME granularity, not task granularity. The contract is what + // the reader sees: the recorded offset by the next paint, held there. + // Under `scrollRestoration: 'auto'` Firefox lands a stale UA write (0) + // inside the same task as the traverse and the restore window's + // write-back corrects it on the following scroll event, so a + // task-granularity read can catch the sub-frame transient between the + // two writes without either being user-visible (#1428). + await frame(); const restored = window.scrollY; assert.ok(Math.abs(restored - RESTORED_Y) < 5, - `the restore lands on the recorded offset (got ${restored})`); + `the restore lands on the recorded offset by the next frame (got ${restored})`); await afterGrowth(); const grown = document.querySelector('wj-grow-late-1310'); assert.ok(grown && grown.getBoundingClientRect().height > GROWTH - 5, @@ -808,8 +781,14 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => await setup({ instantRevalidation: true }); try { await goBack(); + // Frame granularity, for the same reason as the sibling case above: the + // contract is the offset the reader sees by the next paint, and under + // `scrollRestoration: 'auto'` Firefox lands a stale UA write inside the + // traverse's own task that the restore window corrects on the next + // scroll event (#1428). + await frame(); assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, - `the restore lands on the recorded offset (got ${window.scrollY})`); + `the restore lands on the recorded offset by the next frame (got ${window.scrollY})`); for (let i = 0; i < 14; i++) await frame(); const grown = document.querySelector('wj-grow-very-late-1310'); assert.ok(grown && grown.getBoundingClientRect().height > GROWTH - 5, @@ -847,6 +826,64 @@ suite('Client router: a Back restore survives late layout growth (#1310)', () => } finally { await teardown(); } }); + test('the window writes back a programmatic displacement, so a stale UA restore cannot win (#1428)', async () => { + // The router forces `history.scrollRestoration` to 'auto' so the browser + // records per-entry offsets and REPLAYS them, which is both the restore + // itself and what WebKit's back-swipe gesture preview is composed from. + // The cost is that the replay is the browser's, so it can land off-target + // for engine reasons the router does not control. The open restore window + // absorbs a displacement like that for a short arming span. + await setup(); + try { + await goBack(); + await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `precondition: the restore landed (got ${window.scrollY})`); + // Exactly the shape of a stale UA restore: a programmatic write to a + // stale offset, inside the window, from no user gesture. + window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); + await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `an off-target programmatic write inside the window is corrected ` + + `(expected ~${RESTORED_Y}, got ${window.scrollY})`); + } finally { await teardown(); } + }); + + test('the write-back never fights a reader, because input closes the window first (#1428)', async () => { + // The safety property behind the write-back: every release event is a + // CAPTURE-phase input listener, and an input event precedes the scroll it + // causes. So a user-driven scroll always arrives with the window already + // closed, and the only writes the window can ever overrule are + // programmatic ones inside the restore's own span. + await setup(); + try { + await goBack(); + // WAIT FOR THE RESTORE TO LAND before interrupting it. The browser is the + // restore's writer now, and its replay arrives a frame or so after the + // popstate handler rather than synchronously, so a reader modelled as + // "input on the very next frame" can outrun the restore itself. That + // races a different question than this case is asking. What the property + // is actually about, and what a real reader can actually do, is take over + // AFTER the page has come back. + // + // Polled rather than fixed at N frames, so the case does not encode one + // engine's replay latency. This assertion caught a genuine ordering + // difference: written against the old synchronous router write, it + // reproduced only on CI's Chromium and never locally. + for (let i = 0; i < 20 && Math.abs(window.scrollY - RESTORED_Y) > 5; i++) await frame(); + assert.ok(Math.abs(window.scrollY - RESTORED_Y) < 5, + `precondition: the restore landed before the reader takes over (got ${window.scrollY})`); + + window.dispatchEvent(new WheelEvent('wheel', { bubbles: true })); + assert.equal(document.documentElement.style.getPropertyValue('overflow-anchor'), '', + 'precondition: the input event closed the window'); + window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); + await frame(); + assert.ok(window.scrollY < 5, + `a scroll after the reader took over is left alone (got ${window.scrollY})`); + } finally { await teardown(); } + }); + test('a reader taking over closes the window immediately', async () => { await setup(); try { diff --git a/packages/core/test/routing/router-client.test.js b/packages/core/test/routing/router-client.test.js index 422f91da2..940eb4afe 100644 --- a/packages/core/test/routing/router-client.test.js +++ b/packages/core/test/routing/router-client.test.js @@ -2005,11 +2005,19 @@ test('popstate cache restore clears the importmap-reload flag', async () => { } }); -test('popstate cache restore scrolls instantly, not animated (#601)', async () => { - // The restore previously used scrollTo(x, y) (the 2-arg form), which - // respects an app's `html { scroll-behavior: smooth }` and so ANIMATES - // the Back/Forward scroll instead of jumping the way native nav does. - // The fix passes behavior:'instant' to force the jump. +test('popstate cache restore writes NO scroll: the browser owns it (#1428)', async () => { + // The router used to replay the snapshot's offset itself here, with + // behavior:'instant' so an app's `html { scroll-behavior: smooth }` could not + // animate the Back/Forward jump (#601). It no longer writes scroll on a + // restore at all: under `scrollRestoration: 'auto'` the browser replays the + // offset it recorded, against a document held at its recorded height, so a + // second writer of the same quantity is redundant. One writer, which is what + // Next and Remix 3 do. + // + // #601's guarantee survives the deletion and gets STRONGER: native scroll + // restoration is not a scrolling API call, so `scroll-behavior: smooth` + // cannot animate it. The forward-nav half of #601 is a separate write and + // keeps its own instant-form assertions below. const origLoc = globalThis.location; const origFetch = globalThis.fetch; const prevPageUrl = _currentPageUrl(); @@ -2036,12 +2044,10 @@ test('popstate cache restore scrolls instantly, not animated (#601)', async () = document.body.innerHTML = 'before-pop'; try { _onPopState({}); - assert.ok(arg && typeof arg === 'object', - 'restore uses the scrollTo options form, not the 2-arg (x, y) form'); - assert.equal(arg.behavior, 'instant', - 'behavior:instant keeps an app scroll-behavior:smooth from animating the restore'); - assert.equal(arg.top, 640, 'saved scrollY restored as top'); - assert.equal(arg.left, 0, 'saved scrollX restored as left'); + assert.equal(arg, undefined, + 'the router performs no scroll on a cache restore; the browser replays ' + + 'the offset it recorded, so a router write would be a second writer ' + + 'of the same quantity'); // Let the background revalidation settle (avoid an unhandled rejection). await new Promise((r) => setTimeout(r, 5)); } finally { @@ -3246,49 +3252,34 @@ test('addNewHeadElements: skips incoming importmap (importmap-mismatch reload ha * popstate fires). * ==================================================================== */ -test('enableClientRouter: sets history.scrollRestoration = "manual"', () => { - // Start from a known state. enableClientRouter is idempotent: it - // early-returns if `enabled` is already true (which it is, since the - // module auto-enables on import). Cycle off-then-on to exercise it. - const origScrollRestoration = globalThis.history?.scrollRestoration; - const origHistory = globalThis.history; - /** @type {{ scrollRestoration: string, pushState: Function, replaceState: Function }} */ - const mockHistory = { scrollRestoration: 'auto', pushState: () => {}, replaceState: () => {} }; - globalThis.history = /** @type any */ (mockHistory); - try { - disableClientRouter(); - enableClientRouter(); - assert.equal(mockHistory.scrollRestoration, 'manual', - 'router takes control of scroll restoration so the browser ' + - 'doesn\'t race with our snapshot-based scroll restore'); - } finally { - globalThis.history = origHistory; - if (origScrollRestoration !== undefined) { - globalThis.history.scrollRestoration = origScrollRestoration; - } - enableClientRouter(); // re-enable for subsequent tests - } -}); - -test('disableClientRouter: restores the previous history.scrollRestoration value', () => { +test('the router forces scrollRestoration to auto, and puts the app value back (#1428)', () => { + // The restore is the BROWSER's now, so 'auto' is load-bearing: under 'manual' + // the UA records no per-entry offset, which is both no Back restore at all + // and the blank iOS gesture preview this issue is about. + // + // Seeded with 'manual', NOT 'auto'. Seeded with the value the router writes, + // this assertion passes whether the router writes it or writes nothing, which + // is how the first version of this test managed to be green with the + // deliberate write deleted. const origHistory = globalThis.history; /** @type {any} */ - const mockHistory = { scrollRestoration: 'auto', pushState: () => {}, replaceState: () => {} }; + const mockHistory = { scrollRestoration: 'manual', pushState: () => {}, replaceState: () => {} }; globalThis.history = mockHistory; try { disableClientRouter(); - enableClientRouter(); // captures 'auto', sets 'manual' - assert.equal(mockHistory.scrollRestoration, 'manual'); - disableClientRouter(); // should restore 'auto' + enableClientRouter(); assert.equal(mockHistory.scrollRestoration, 'auto', - 'disable restores the value enable captured, so the browser\'s ' + - 'default scroll-restoration behavior is back in effect'); + 'enable overrides an app that had taken manual control, or the browser ' + + 'records nothing and Back does not restore at all'); + disableClientRouter(); + assert.equal(mockHistory.scrollRestoration, 'manual', + 'disable puts the app\'s own value back: the write is an override, and ' + + 'the documented opt-out must not strand an app on a mode it never chose'); } finally { globalThis.history = origHistory; enableClientRouter(); } }); - test('currentPageUrl: tracker exists and can be read/written via test helpers', () => { const prev = _currentPageUrl(); _setCurrentPageUrl('http://localhost/sentinel'); @@ -5167,10 +5158,14 @@ test('applySwap: a DISCARDED background revalidation never ingests its seeds (#1 /* -------------------------------------------------------------------------- * #1406: the history entry is recorded AT THE COMMIT, before the DOM mutation. * - * WebKit binds a same-document `pushState` entry's back-forward gesture - * snapshot to the page state at the moment the entry is recorded, so an entry - * recorded after the swap describes the destination document rather than the - * page it belongs to, and the iOS edge back-swipe previews it blank. + * An entry recorded after the swap describes the destination document rather + * than the page it belongs to, so the push is ordered ahead of the mutation. + * + * #1406 introduced that ordering as the fix for the blank iOS back-swipe + * preview, on the theory that WebKit binds the gesture snapshot when the entry + * is recorded. That theory is false (#1428): Turbo Drive has the same ordering + * and previews blank identically, and the preview was fixed by leaving + * `history.scrollRestoration` alone. The ordering stands on its own merits. * * The push therefore rides into `applySwap` as a commit-time callback. These * pin the three halves of that contract: it fires before the mutation on a @@ -5220,6 +5215,14 @@ test('applySwap: the history callback fires BEFORE the DOM mutation (#1406)', () } }); +/* -------------------------------------------------------------------------- + * #1406 / #1428: history is recorded at the swap COMMIT, and the restore is + * the browser's. + * + * The cases below pin the commit-time history callback: it fires before the + * mutation on a committing swap, does not fire on a swap that commits nothing, + * and the caller's fall-through still records history on those paths. + * ------------------------------------------------------------------------ */ test('applySwap: a frame-missing response commits nothing, so it records no history (#1406)', () => { const savedBody = globalThis.document.body.innerHTML; const savedLocation = globalThis.location; diff --git a/test/bun/form-action-guard.mjs b/test/bun/form-action-guard.mjs index 565d62f4c..f7146a4f1 100644 --- a/test/bun/form-action-guard.mjs +++ b/test/bun/form-action-guard.mjs @@ -186,12 +186,31 @@ for (const [name, mk] of Object.entries(allowed)) { } // A self-referential array stringifies to '' because `Array.prototype.join` has -// a cycle guard. The function check has to match that rather than recurse, on -// both engines. +// a cycle guard (ECMA-262 requires one). The function check has to match that +// rather than recurse, on both engines. +// +// SKIPPED on Bun >= 1.4.0, which REGRESSED that cycle guard: there, +// `String(a)` and `a.join(',')` both throw +// `RangeError: Maximum call stack size exceeded` for `const a = []; a.push(a)`, +// with no framework involved at all. Node and Bun 1.3.14 both return ''. +// +// Scoped rather than worked around on purpose. The alternative is a cycle-safe +// stringify on the per-attribute SSR hot path, which is real cost carried +// forever for an upstream bug, and the case is only reachable by deliberately +// building a self-referential array, so nothing an app does hits it. The +// assertion stays LIVE on every spec-compliant engine, and comes back on Bun +// automatically once the regression is fixed, because the skip is keyed to the +// behaviour rather than to a version. const cyclic = []; cyclic.push(cyclic); -const cyclicOut = await renderToString(html`
`, { ssr: true }); -assert.match(cyclicOut, /action=""/, `[${runtime}] a cyclic array must render, not overflow the stack`); +let engineJoinsCycles = true; +try { String(cyclic); } catch { engineJoinsCycles = false; } +if (engineJoinsCycles) { + const cyclicOut = await renderToString(html`
`, { ssr: true }); + assert.match(cyclicOut, /action=""/, `[${runtime}] a cyclic array must render, not overflow the stack`); +} else { + console.log(`[${runtime}] SKIP cyclic-array case: this engine's Array.prototype.join cycle guard is broken (upstream, not WebJs)`); +} // The SCOPE boundary, on both machines. Every other passthrough above is // `action`-valued, so none of them would notice a change that widened the claim diff --git a/website/app/docs/client-router/page.ts b/website/app/docs/client-router/page.ts index a513868d9..b34942225 100644 --- a/website/app/docs/client-router/page.ts +++ b/website/app/docs/client-router/page.ts @@ -16,7 +16,7 @@ export default function ClientRouter() {
  1. SSR emits KEYED boundary comment pairs around each layout's \${children} interpolation and around the page itself: open <!--wj:children:<segment>:<route-key>-->, close <!--/wj:children:<segment>-->. The segment is the folder-derived pattern; the route-key is the resolved path for this request (dynamic params substituted, values percent-encoded). Derived from folder structure, with authors writing nothing.
  2. On a click or form submit, the router STRICTLY scans both the live DOM and the incoming HTML into segment maps (a close must match its innermost open; any truncated, mispaired, or duplicated boundary poisons the scan) and DECIDES which of two tiers to apply, with Next.js parity. Nothing is applied yet: a boundary whose route-key CHANGED will be wholesale REPLACED at the PARENT of the shallowest change (a layout's boundary wraps only its children, so anchoring at the parent remounts the changed layout's own markup too, exactly like Next re-rendering a layout with new params), while an all-keys-equal nav (a searchParams-only change) will MORPH the deepest shared boundary in place so hydrated component state survives. A poisoned scan or no shared boundary degrades to a normal full page load, never a guessed swap, so a malformed response cannot corrupt the live DOM. Because the boundaries are comments, the parse that turns a response into a document has to preserve them: Document.parseHTMLUnsafe strips every comment in some browser versions, so the router probes it once and parses with DOMParser instead when it is lossy.
    3. -
  3. The URL updates via pushState, and this happens before the incoming content replaces what is on screen, not after. The order is deliberate: WebKit binds a same-document history entry's back-forward gesture snapshot to the page state at the moment the entry is recorded, so recording it after the content swap makes an iOS back-swipe preview the destination page instead of the page being returned to. One exception worth knowing: if a loading.{js,ts} skeleton is showing (it is applied optimistically, before the response arrives), the entry is recorded against that skeleton rather than the page you left.
    4. +
  4. The URL updates via pushState, and this happens before the incoming content replaces what is on screen, not after. The order is deliberate: the entry for the page you are leaving is finalized while that page is still the live document, rather than against the content that replaced it. This is Turbo Drive's ordering too. (It was introduced as a fix for the blank iOS back-swipe preview, on the theory that WebKit binds the gesture snapshot when the entry is recorded. That theory turned out to be wrong, and the preview was actually fixed by leaving history.scrollRestoration alone; the ordering is kept because recording an entry against its own page is correct regardless.) One exception worth knowing: if a loading.{js,ts} skeleton is showing (it is applied optimistically, before the response arrives), the entry is recorded against that skeleton rather than the page you left.
  5. The <head> is add-only merged (preserves runtime-injected styles like Tailwind's), still before the content itself changes.
  6. The swap runs, applying the tier chosen in step 2. The diff inside the swap region is keyed by data-key or id. Matched elements are reused with in-place attribute updates. Live attributes (value, checked, selected, indeterminate, disabled, open, popover) are never overwritten, so user input and disclosure state survive the swap.
  7. <script> tags re-execute and custom elements upgrade. That re-execution reaches a script wherever it sits, inside the swapped content or as a top-level node of the swapped range itself (a layout emitting its enhancement script as a sibling of \${children}). A parsed script node carries the HTML spec's "already started" flag, so the router replaces it with a fresh clone; that is what makes it run. The clone carries the page-load CSP nonce, not the nonce the response was rendered with. The one exception is a script INSIDE an element the swap preserved by identity through data-webjs-permanent, covered below.
    8. @@ -188,9 +188,10 @@ connectWS('/posts/' + id + '/feed', { onMessage: (m) => renderStream(m) });Snapshot cache + back/forward

    The router maintains a URL-keyed LRU cache of page snapshots (capacity 16). On back/forward via popstate, the cached DOM is applied instantly and the captured window-scroll position is restored. A background refetch then revalidates the snapshot quietly.

    -

    A back/forward restore also suppresses the browser's scroll anchoring (overflow-anchor) for its duration, then puts it back. The saved offset was recorded against the page at its settled height, while the DOM the restore swaps in is still shorter until its components upgrade and render. Without the suppression the browser reads that late growth as content appearing above the reader and adds it to the offset the router just replayed, landing them below where they left. The window closes on the first real input (wheel, touchmove, keydown, pointerdown), so a reader who starts scrolling mid-restore gets normal anchoring back immediately. It also closes as soon as another page navigation starts, since the window outlives its own restore and must not be inherited by a page it was never meant for; that navigation then opens a window of its own if it earns one. Absent either of those it closes once the restore is over, which is the later of that restore's background revalidation settling and a short floor, and at the latest on a 2s ceiling. The floor matters because waiting on the revalidation alone would tie the window to network latency rather than to the growth it guards, so a server answering faster than the page renders would close it too early. Suppression only withholds a browser correction, it never moves the viewport. If your app sets overflow-anchor on <html> inline itself, it is overridden during a restore and restored afterwards. The suppression is conditional: when the page has not grown enough to scroll to the recorded offset at all, the browser clamps the scroll, and there the shortfall is exactly the growth still to come, so anchoring adding it is what carries the reader back down. The router leaves anchoring alone while the offset is out of reach, rather than freezing the clamp, and chases the saved offset, re-asserting it once the page is tall enough to hold it and protecting it from there. That is the only scroll the router writes after the initial restore. It stops on the first real input, so it never fights a reader who has started scrolling, and it is time-boxed to a few hundred milliseconds measured from the restore, which is tighter than the window a landed restore gets; the suppression it installs on landing shares that deadline rather than starting a fresh one. The bound is what protects a reader who has landed and started reading, since they generate no input to cancel it. Anchoring is left on only while the offset is out of reach, since that is what heals the clamp; once the chase lands on the offset it suppresses anchoring too, because the growth that made the offset reachable is rarely all of it. Both end together on the bound, after which the router writes no more scroll and anchoring is back on, so a component reaching its final height later has its growth added and the reader drifts below the offset rather than sitting at the clamp.

    +

    A back/forward restore reserves the page's recorded HEIGHT across the swap, then suppresses the browser's scroll anchoring (overflow-anchor) for the restore's duration, then puts both back. The reservation is what makes the saved offset reachable: the snapshot's markup is briefly shorter than the page it was serialized from, because its components have not rendered yet, so without it the browser clamps the restore to whatever the short document allowed and the reader lands short. The suppression covers the other half: content still SHIFTS above the viewport as those components render, and anchoring would add that shift to the offset just replayed, landing the reader below where they left. The window closes on the first real input (wheel, touchmove, keydown, pointerdown), so a reader who starts scrolling mid-restore gets normal anchoring back immediately. It also closes as soon as another page navigation starts, since the window outlives its own restore and must not be inherited by a page it was never meant for. Absent either of those it closes once the restore is over, which is the later of that restore's background revalidation settling and a short floor, and at the latest on a 2s ceiling. The floor matters because waiting on the revalidation alone would tie the window to network latency rather than to the growth it guards. Suppression only withholds a browser correction, it never moves the viewport. The height reservation releases on the same settle and ceiling, and on a superseding navigation, but deliberately NOT on user input: releasing the page's height under a reader mid-scroll is the one harm an early release could do. If your app sets overflow-anchor or an inline min-height on the root itself, each is saved and put back.

    A frame-targeted navigation or submission is the one exception to the closing rule above: it swaps a single <webjs-frame> rather than the page, so the restored offset is still the right one and the restore is left running. Frame targeting here means what it means everywhere else, so a trigger that breaks out with data-webjs-frame="_top", or names an id that does not resolve, is a page navigation and does close the window.

    -

    Nav scroll restoration (both the back/forward restore and the scroll-to-top on a forward nav) is forced behavior: 'instant', so setting html { scroll-behavior: smooth } in your app does not make navigation visibly animate the scroll. It jumps like a native page load. A hash-anchor (#section) link still scrolls smoothly when you opt into it. Because route transitions ignore scroll-behavior: smooth (it only affects in-page anchors), the router logs a one-time dev-only console hint if it detects that setting on <html>, and notes that combining it with a sticky backdrop-filter header can flash on iOS during navigation.

    +

    The browser restores Back/Forward scroll, not the router. WebJs FORCES history.scrollRestoration to auto when the router starts, overriding an app that had set 'manual' (and putting that value back if you call disableClientRouter()), so setting it to 'manual' yourself does not take effect while the router is running. Only under auto does the browser record a scroll position per history entry, replay it on a traverse, and compose the iOS edge back-swipe gesture preview from that recording. The router writes no scroll of its own on a restore: it reserves the recorded height across the swap so the browser's replay lands on a document that can hold the offset, and that is the entire mechanism. One writer, which is the model Next and Remix 3 use as well. Taking manual control suppresses the recording, so every scrolled page previews blank for the whole duration of the gesture; that is a real bug WebJs shipped, inherited from Turbo Drive's assumeControlOfScrollRestoration, and it is why Turbo still has it (Turbo is single-writer too, but its writer is the app rather than the browser).

    +

    Navigation never animates the scroll, so setting html { scroll-behavior: smooth } in your app does not make it do so. The forward-nav scroll-to-top is the router's own write and is forced behavior: 'instant'; the back/forward restore is the browser's and is not a scrolling-API call at all, so scroll-behavior cannot reach it either. It jumps like a native page load. A hash-anchor (#section) link still scrolls smoothly when you opt into it. Because route transitions ignore scroll-behavior: smooth (it only affects in-page anchors), the router logs a one-time dev-only console hint if it detects that setting on <html>, and notes that combining it with a sticky backdrop-filter header can flash on iOS during navigation.

    After a server action mutates data that a cached page depends on, call revalidate():

    import { revalidate } from '@webjsdev/core';