diff --git a/.agents/skills/webjs/references/client-router-and-streaming.md b/.agents/skills/webjs/references/client-router-and-streaming.md index 2b1f85a08..ad171f859 100644 --- a/.agents/skills/webjs/references/client-router-and-streaming.md +++ b/.agents/skills/webjs/references/client-router-and-streaming.md @@ -138,6 +138,14 @@ html`…contents…` On click the router walks `closest('webjs-frame')` from the target. If a frame is found and the response carries a matching ``, the swap is scoped to that frame's children, and the server returns ONLY that subtree. A link that drives a frame participates in link prefetch like any other, in that frame's own dimension (#1407), so a hovered or viewport-warmed frame link swaps on click with no round trip. A `` SELF-load is the exception: it neither reads nor keeps that cache, since asking a frame to load its own src is a freshness request rather than a hover being followed. See the prefetch section above for the frame dimension's rules. +**A frame swap never moves the window scroll.** A page navigation scrolls to top, the way a browser does; a frame swap changes one region and leaves the rest of the document standing, the reader's scroll offset included. That holds for a nested link, an external `data-webjs-frame` trigger, a frame-targeted form submission, and a `src` self-load alike, and it holds for a `#hash` on a frame link too, which rides the URL without moving the viewport. It does NOT cover a pure fragment link to a NAMED anchor (`#section`, same path and query), because the router never sees one: the click handler bows out before `preventDefault`, so the browser does its own native fragment jump and the window moves. + +The EMPTY fragment is the trap, and it goes the other way. `href="#"` (and `href=""`) parse to an empty `URL.hash`, and the bow-out tests the hash for truthiness, so it does not fire: the click is an ordinary frame nav that re-fetches the frame and, under this rule, leaves the window still. So a bare `Back to top` INSIDE a frame does nothing visible. Give it a real target (`href="#top"`), which the bow-out then honours, or a click handler that scrolls (its `preventDefault` runs first and the router stands down). + +The escapes are page navigations and DO scroll: `data-webjs-frame="_top"`, and an id `resolveTargetFrameId` cannot match to a live frame, which warns and degrades to a normal nav. Do not read that second one as covering a RESPONSE that lacks the requested frame (the `webjs:frame-missing` warning). There the frame resolved and the nav stayed frame-scoped, so the offset holds and only the panel is left unchanged. Turbo's `autoscroll` opt-in, which scrolls the frame itself into view on swap, has no WebJs equivalent; the router simply never writes scroll for a frame. + +**Read "never moves" as "WebJs never writes one", not as a guarantee the viewport cannot move.** A swap that makes the panel SHORTER shortens the document with it, and a reader parked near the bottom is then holding an offset the document can no longer reach, so the browser clamps it. Measured on the gallery's frames demo: filtering from All to Done at the bottom of the page moves the window from 474 to 405, exactly the 69px the document lost. The router wrote no scroll there (verified with every scrolling API instrumented), and any DOM change that shortens a page does the same thing. Keeping the frame a stable height across its states avoids it entirely. + **External targeting.** A trigger does not have to be nested inside the frame. An `` or `
` carrying `data-webjs-frame=""` drives that frame from anywhere (an explicit `data-webjs-frame` wins over the enclosing-frame default). `data-webjs-frame="_top"` is a reserved token forcing a full-page navigation that breaks out of the frame. **Self-loading.** Give a frame a `src` and it self-fetches (through the same swap path). diff --git a/packages/core/src/router-client/fetch-apply.js b/packages/core/src/router-client/fetch-apply.js index 57d4a1797..92c09b635 100644 --- a/packages/core/src/router-client/fetch-apply.js +++ b/packages/core/src/router-client/fetch-apply.js @@ -340,7 +340,26 @@ export async function fetchAndApply(href, frameId, recordHistory, optimisticStat // (b) a cache-miss popstate: modern browsers fire scroll- // restoration themselves before dispatching popstate, so // leaving scroll alone preserves the browser-native UX. - if (recordHistory) { + // + // And never for a FRAME-scoped response (#1427). `recordHistory` means "a + // foreground navigation the reader initiated", which a frame click is (it + // advances the URL, deliberately), so a frame swap used to fall into the + // page-navigation scroll by omission rather than by decision. A frame swaps + // ONE region and leaves the rest of the document standing, the scroll offset + // included, so the router writes no scroll for it: on a page whose frame sits + // below the fold, scrolling to top throws the region the reader just clicked + // in off screen. Turbo, which `` is modelled on, likewise never + // scrolls on a frame navigation (its `autoscroll` opt-in is a separate + // feature WebJs does not have). This is the same rule `restoreGeneration` in + // `scroll.js` already applies when deciding what ends a scroll-restore + // window, so the two now agree on what a frame nav is. + // + // The hash branch is excluded too. A `#anchor` on a frame link is no more a + // request to move the document viewport than the frame swap itself is, and + // one rule ("a frame swap never moves the window") beats two. `_top` and an + // unresolvable `data-webjs-frame` id both resolve to a null `frameId` in + // `resolveTargetFrameId`, so they stay page navigations and still scroll. + if (recordHistory && !frameId) { // Use the final URL (after any server-side redirect) so hash // anchors point at the document we actually rendered. const url = new URL(finalUrl); diff --git a/packages/core/test/routing/browser/frame-missing.test.js b/packages/core/test/routing/browser/frame-missing.test.js index 7439fa4a5..ac25ee81b 100644 --- a/packages/core/test/routing/browser/frame-missing.test.js +++ b/packages/core/test/routing/browser/frame-missing.test.js @@ -153,7 +153,7 @@ suite('Client router: frame-missing contract (#251)', () => { // pipeline. A click-driven frame nav records history, so an implementation // that returned early on the sentinel would stop advancing the URL here, // which nothing else in the suite would notice. - test('a frameless response still advances the URL, because the sentinel only reports', async () => { + test('a frameless response advances the URL and holds the scroll offset', async () => { setup(); // Observe the history CALL rather than reading `location` afterwards. // @@ -171,16 +171,35 @@ suite('Client router: frame-missing contract (#251)', () => { const pushed = []; const origPush = history.pushState; history.pushState = function (...args) { pushed.push(String(args[2])); }; + // The SCROLL half of the same contract (#1427). This path keeps a truthy + // `frameId` all the way through, so the guard holds the offset even though + // nothing was applied: the reader gets a changed address over an unchanged + // panel, still in their place. The docs say so on both surfaces and nothing + // pinned it, which is how the claim it replaced went stale in the first + // place. The spacer is what gives the assertion teeth, since a document + // that cannot hold an offset reports 0 either way. + const spacer = document.createElement('div'); + spacer.style.height = '3000px'; + document.body.appendChild(spacer); try { window.fetch = () => htmlResponse( '

Login

' ); + window.scrollTo({ left: 0, top: 400, behavior: 'instant' }); + assert.equal(window.scrollY, 400, + 'precondition: the page holds an offset, so a 0 below is the router moving it'); + document.getElementById('frame-link').click(); await settle(); assert.equal(pushed.length, 1, 'the frame-missing return still records history'); assert.match(pushed[0], /\/no-frame-here$/, 'and it advanced to the navigation target'); + assert.equal(window.scrollY, 400, + 'a frame-missing response leaves the window where the reader put it'); } finally { history.pushState = origPush; + // Reset before the next case: nothing else in this file expects an offset. + window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); + spacer.remove(); teardown(); } }); diff --git a/packages/core/test/routing/browser/frame-swap-scroll.test.js b/packages/core/test/routing/browser/frame-swap-scroll.test.js new file mode 100644 index 000000000..b33536dec --- /dev/null +++ b/packages/core/test/routing/browser/frame-swap-scroll.test.js @@ -0,0 +1,313 @@ +/** + * Real-browser test for #1427: a `` swap must not move the window + * scroll, while an ordinary page navigation still scrolls to top. + * + * The router's scroll block was gated on `recordHistory` alone, which means "a + * foreground navigation the reader initiated". A click on a frame-driving link + * is exactly that (it advances the URL, deliberately), so a frame swap fell + * into the page-navigation scroll by omission: filtering a tabbed panel on + * gallery.webjs.dev threw the reader from 400px back to the top of the page, + * with the panel they had just clicked in now off screen. + * + * This MUST run in a real browser. linkedom implements no layout and no + * scrolling at all, so `window.scrollY` never moves there and every assertion + * below would pass vacuously against the bug. + * + * Three things make the fixture load-bearing, and each is easy to get wrong in + * a way that leaves the test green either way: + * + * - The page has to be TALL, and stay tall across the swap. The offset is + * only preserved if the document can still hold it, so a swap that shortens + * the document would clamp `scrollY` to 0 and look exactly like the defect. + * The spacer therefore sits OUTSIDE the frame (a frame swap never touches + * it) and the page-navigation response carries its own. + * - The starting offset has to be non-zero and asserted BEFORE the click. A + * fixture that never managed to scroll would report 0 after the click for + * the wrong reason. + * - Every href keeps the page's OWN query string, which is what identifies + * the web-test-runner session. A link that replaces the search string + * pushes the page out of its session and takes down the entire run, with + * every test still passing, so it reads as an infrastructure blip. + */ +import { enableClientRouter, disableClientRouter } from '../../../src/router-client.js'; + +import { assert } from '../../../../../test/browser-assert.js'; +import { installNavGuard } from '../../../../../test/browser-nav-guard.js'; + +/** Where the reader is when they click. Comfortably clear of 0. */ +const START_Y = 500; +/** Tall enough that neither swap can shorten the document below `START_Y`. */ +const SPACER = 3000; + +const frame = () => new Promise((r) => requestAnimationFrame(() => r())); +const tick = () => new Promise((r) => setTimeout(r, 0)); +/** Past the fetch, the swap, and the layout it produces. */ +async function settle() { for (let i = 0; i < 3; i++) { await tick(); } await frame(); } + +/** + * A same-page url carrying one extra param, built from the LIVE url so the + * session query string survives (see the header note). + * + * @param {string} kind + * @returns {string} pathname + search + */ +function href(kind) { + const u = new URL(location.href); + u.searchParams.set('wj1427', kind); + return u.pathname + u.search; +} + +/** + * The live page: an anchor target, a tall spacer, then a frame carrying its own + * filter link, an anchored (`#hash`) filter link, a `_top` breakout link, an + * unresolvable-id link, and a frame-targeted form. The + * boundary comments are what let the page-navigation case swap INSIDE this + * container rather than replacing the whole body, so the web-test-runner + * harness DOM is never touched. + */ +function liveHtml() { + return '' + // Above the spacer, so scrolling to it would move the window UP from + // `START_Y` by an unmistakable margin (the hash case asserts that gap). + + 'anchor' + + `
spacer
` + + '' + + `filter` + + `filter, anchored` + + `breakout` + + `ghost` + + `` + + '' + + '
' + + 'ORIGINAL' + + '' + + ''; +} + +/** A frame-scoped response: only the frame subtree changes. */ +const FRAME_RESPONSE = + '' + + 'UPDATED' + + ''; + +/** + * A page response, with its OWN tall spacer. Without that the swap would + * shorten the document, the browser would clamp `scrollY` to 0 on its own, and + * the scroll-to-top assertion would pass even with the router's scroll removed. + * + * It repeats the live boundary KEY on purpose. A different key shares no + * boundary with the live DOM, so the router degrades to a full page load rather + * than swapping, and the case would then assert scroll behaviour on a + * navigation that never applied. + * + * It also echoes the LIVE head back, as insurance rather than out of need. The + * path this fixture takes is `addNewHeadElements` (a foreground nav that finds + * a shared boundary, which this response is built to offer); a nav with no + * shared boundary hard-navigates instead of swapping, and the wholesale-removing + * merge (`mergeHead`, through the full-body swap) belongs to the background + * snapshot paths, which no case here reaches. `addNewHeadElements` is add-only + * for links and scripts but finishes with a keyed-`` reconcile that DOES + * remove a live meta the incoming head omits, so "add-only" is not the whole + * story. It cannot bite here either way: that reconcile early-returns on a head + * with no `` at all (a fragment response), and an echoed head declares + * every key the live one does, so the sets match and nothing is touched. It stays because the cost is zero and the failure it guards against + * is invisible: `mergeHead` drops any live head element the response omits, and + * losing web-test-runner's session scripts would not fail THIS file, which has + * already loaded, but would destabilize the Firefox session and surface as + * unrelated later files failing to start a test page. The echo cannot itself do + * harm, because the merge dedupes on the serialized element, so an element + * already live is neither removed nor re-appended and no script runs twice. + */ +function pageResponse() { + return '' + document.head.innerHTML + '' + + '' + + `
swapped
` + + '' + + ''; +} + +suite('Client router: a swap leaves the window scroll alone (#1427)', () => { + let navGuard, container, origFetch, origScrollBehavior, origUrl; + /** Every url the router fetched, tagged with the shape it asked for. */ + let fetched; + + function setup() { + navGuard = installNavGuard(); + enableClientRouter(); + origUrl = location.href; + origScrollBehavior = document.documentElement.style.scrollBehavior; + // The assertions are about position, not animation, and a smooth scroll + // would not have landed by the time they run (#601). + document.documentElement.style.scrollBehavior = ''; + + container = document.createElement('div'); + container.innerHTML = liveHtml(); + document.body.appendChild(container); + + fetched = []; + origFetch = window.fetch; + // Answer the SHAPE the router asked for, read off its own `x-webjs-frame` + // request header rather than guessed from the url. That matters for the + // degradation cases: a page request answered with a bare frame body would + // carry no boundary comments, so the router would swap the whole body and + // take the web-test-runner harness DOM with it. + window.fetch = (u, init) => { + const url = String(typeof u === 'string' ? u : (u && u.url) || u); + const headers = (init && init.headers) || {}; + const framed = Boolean(headers['x-webjs-frame']); + fetched.push((framed ? 'frame:' : 'page:') + url); + return Promise.resolve(new Response(framed ? FRAME_RESPONSE : pageResponse(), { + headers: { 'content-type': 'text/html', 'x-webjs-build': '' }, + })); + }; + + window.scrollTo({ left: 0, top: START_Y, behavior: 'instant' }); + assert.equal(window.scrollY, START_Y, + 'the fixture is tall enough to scroll: without this the test proves nothing'); + } + + /** + * Undo everything `setup` installed. Every step is guarded, because `setup` + * ASSERTS (its precondition) and so can throw partway through, and a teardown + * that threw on the first missing field would leave the fetch stub and the nav + * guard installed for the rest of the RUN, not just the rest of this file. + * That failure is invisible where it happens and surfaces as unrelated later + * files misbehaving, which is exactly the shape this fixture already produced + * once through its head handling. So each test calls `setup` INSIDE its try, + * and this cleans up whatever got as far as being installed. + */ + function teardown() { + if (origFetch) { window.fetch = origFetch; origFetch = null; } + // A page swap replaces the container's contents and nothing puts them back. + const swapped = document.getElementById('wj-swapped-1427'); + if (swapped) swapped.remove(); + if (container) { container.remove(); container = null; } + if (origUrl) { history.replaceState(null, '', origUrl); origUrl = null; } + if (origScrollBehavior != null) { + document.documentElement.style.scrollBehavior = origScrollBehavior; + origScrollBehavior = null; + } + window.scrollTo({ left: 0, top: 0, behavior: 'instant' }); + if (navGuard) { navGuard.remove(); navGuard = null; } + // Re-arm cleanly for the next case; every other suite in the run expects + // the router enabled. + disableClientRouter(); + enableClientRouter(); + } + + test('a link INSIDE a frame swaps the frame and holds the scroll offset', async () => { + try { + setup(); + document.getElementById('wj-frame-link').click(); + await settle(); + + assert.equal(document.getElementById('wj-frame-content').textContent, 'UPDATED', + 'the frame actually swapped, so the scroll assertion is about a real frame nav'); + assert.equal(window.scrollY, START_Y, + 'a frame swap left the window scroll where the reader put it'); + } finally { teardown(); } + }); + + test('a #hash on a frame link does not move the window either', async () => { + try { + setup(); + // The hash branch is excluded on purpose, and nothing else in this file + // reaches it. Narrowing the guard back to the obvious + // `recordHistory && (!frameId || url.hash)` (an anchor reads as explicit + // intent, so someone will propose it) leaves every other case here, plus + // frame-targeting, frame-missing, and the e2e case, green while restoring + // the `scrollIntoView` this one catches. + const target = document.getElementById('wj-hash-target'); + const targetY = Math.round(window.scrollY + target.getBoundingClientRect().top); + assert.ok(Math.abs(targetY - START_Y) > 100, + `the anchor sits at ${targetY}, which must be clear of ${START_Y}: if the two ` + + 'coincided, scrolling to the anchor would be indistinguishable from holding ' + + 'the offset and this case could not fail'); + + document.getElementById('wj-hash-link').click(); + await settle(); + + assert.equal(document.getElementById('wj-frame-content').textContent, 'UPDATED', + 'the anchored link swapped the frame, so this is a real frame nav'); + assert.equal(window.scrollY, START_Y, + 'a frame swap ignores the hash and leaves the window where the reader put it'); + } finally { teardown(); } + }); + + test('an EXTERNAL data-webjs-frame link holds the scroll offset too', async () => { + try { + setup(); + // Same fixture, driven from outside the frame: the resolve path differs + // (an explicit id rather than the enclosing-frame default) but it reaches + // the same swap, so both spellings need pinning. + const external = document.createElement('a'); + external.id = 'wj-external-link'; + external.href = href('external'); + external.setAttribute('data-webjs-frame', 'wj-scroll-frame'); + external.textContent = 'external'; + container.appendChild(external); + + external.click(); + await settle(); + + assert.equal(document.getElementById('wj-frame-content').textContent, 'UPDATED', + 'the external link swapped the frame'); + assert.equal(window.scrollY, START_Y, + 'an externally targeted frame swap left the window scroll alone'); + } finally { teardown(); } + }); + + test('a frame-targeted FORM submission holds the scroll offset', async () => { + try { + setup(); + // The submit path reaches the scroll block through its own caller + // (`submitForm`, which hardcodes `recordHistory: true`), so a fix proven + // only on the click path would leave this one scrolling. + document.getElementById('wj-frame-submit').click(); + await settle(); + + assert.equal(document.getElementById('wj-frame-content').textContent, 'UPDATED', + 'the submission swapped the frame'); + assert.ok(fetched.some((u) => u.startsWith('frame:') && u.includes('wj1427=form')), + 'the router handled the submission as a frame request, not the browser'); + assert.equal(window.scrollY, START_Y, + 'a frame-targeted submission left the window scroll alone'); + } finally { teardown(); } + }); + + test('a data-webjs-frame="_top" breakout is a page nav, so it still scrolls to top', async () => { + try { + setup(); + document.getElementById('wj-top-link').click(); + await settle(); + + assert.ok(document.getElementById('wj-swapped-1427'), + 'the page swap applied, so this is a genuine page navigation'); + assert.ok(document.documentElement.scrollHeight - window.innerHeight > START_Y, + 'the swapped page is still tall enough to hold the old offset, so a 0 here ' + + 'is the router scrolling and not the browser clamping'); + assert.equal(window.scrollY, 0, + 'breaking out of a frame is a page navigation and still scrolls to top'); + } finally { teardown(); } + }); + + test('an unresolvable frame id degrades to a page nav, and still scrolls to top', async () => { + try { + setup(); + const origWarn = console.warn; + console.warn = () => {}; + try { + // `resolveTargetFrameId` warns and returns null here, so the click is a + // page navigation. It is the one shape where the new guard could + // silently over-apply, since the link does carry a frame attribute. + document.getElementById('wj-ghost-link').click(); + await settle(); + } finally { console.warn = origWarn; } + + assert.ok(fetched.some((u) => u.startsWith('page:') && u.includes('wj1427=ghost')), + 'the unresolvable id degraded to a page request'); + assert.equal(window.scrollY, 0, + 'an unresolvable frame id is a page navigation and still scrolls to top'); + } finally { teardown(); } + }); +}); diff --git a/packages/core/test/routing/browser/prefetch-frame.test.js b/packages/core/test/routing/browser/prefetch-frame.test.js index a55b49ded..ed5adceba 100644 --- a/packages/core/test/routing/browser/prefetch-frame.test.js +++ b/packages/core/test/routing/browser/prefetch-frame.test.js @@ -316,11 +316,13 @@ suite('Client router: frame-dimensioned link prefetch (#1407)', () => { test('a full-document answer to a framed prefetch is not stored, but the refusal is memoed', async () => { // The server's frame branch has two fall-throughs (a streamed render, an // absent frame id) that answer with a whole document and no marker. Storing - // one under a frame key risks a click that changes the url and scrolls to - // top while the panel stays put: the swap looks for `webjs-frame#` in the - // body and may not find it (an absent id was never rendered, and a streamed - // page's content sits in a template the swap does not descend into), so it - // leaves the region unchanged while the navigation around it completes. + // one under a frame key risks a click that changes the url while the panel + // stays put: the swap looks for `webjs-frame#` in the body and may not + // find it (an absent id was never rendered, and a streamed page's content + // sits in a template the swap does not descend into), so it leaves the + // region unchanged while the navigation around it completes. The scroll + // offset survives that (#1427 holds it for anything frame-scoped, this path + // included), so what the reader loses is the panel, not their place. setup('/tasks?status=streamed'); try { window.fetch = async (url, init) => { diff --git a/test/e2e/e2e.test.mjs b/test/e2e/e2e.test.mjs index da6bf88e0..55e4ac617 100644 --- a/test/e2e/e2e.test.mjs +++ b/test/e2e/e2e.test.mjs @@ -3031,6 +3031,53 @@ describe('E2E: Blog example', { skip: !process.env.WEBJS_E2E && 'set WEBJS_E2E=1 } finally { page.off('request', onReq); } }); + test('frame: a frame swap holds the window scroll, while the _top breakout still scrolls to top (#1427)', async () => { + // The router used to gate its scroll-to-top on "is this a foreground + // navigation", which a frame click is (it advances the URL), so filtering + // a panel threw the reader back to the top of the page with the panel + // they had just clicked in off screen. Over the real wire here, because + // the offset only survives if the document is genuinely tall and the swap + // genuinely applied. + await page.goto(`${baseUrl}/frame-demo?tab=one`, { waitUntil: 'domcontentloaded', timeout: 15000 }); + await sleep(1500); + + // The page carries a 1200px spacer for the lazy deferred frame, so it + // scrolls. Stop well short of that frame: pulling it into view would start + // a self-load this case is not about. + const startY = await page.evaluate(() => { + window.scrollTo({ left: 0, top: 300, behavior: 'instant' }); + return window.scrollY; + }); + assert.equal(startY, 300, 'the page is tall enough to scroll, so the assertion below means something'); + + await page.evaluate(() => document.getElementById('tab-two')?.click()); + await waitForCond( + () => page.evaluate(() => document.getElementById('panel-body')?.getAttribute('data-tab') === 'two'), + 6000, + () => 'the tab click should swap the frame to tab two', + ); + + const afterFrame = await page.evaluate(() => window.scrollY); + assert.equal(afterFrame, 300, `a frame swap must leave the window scroll alone, got ${afterFrame}`); + + // The same page, the same scroll offset, a link that is NOT a frame nav. + // Without this the assertion above would also pass on a router that had + // simply stopped scrolling altogether. + await page.evaluate(() => document.getElementById('top-link')?.click()); + await waitForCond( + () => page.evaluate(() => location.pathname === '/'), + 6000, + () => `_top should navigate to "/", got ${page.url()}`, + ); + const after = await page.evaluate(() => ({ + y: window.scrollY, + reachable: document.documentElement.scrollHeight - window.innerHeight, + })); + assert.ok(after.reachable > 300, + `the home page must be tall enough to hold the old offset, else a 0 proves nothing (max ${after.reachable})`); + assert.equal(after.y, 0, `a page navigation must still scroll to top, got ${after.y}`); + }); + test('frame: aria-busy toggles true during the frame fetch and clears after, with start+finish events', async () => { await page.goto(`${baseUrl}/frame-demo`, { waitUntil: 'domcontentloaded', timeout: 15000 }); await sleep(1500); diff --git a/website/app/docs/client-router/page.ts b/website/app/docs/client-router/page.ts index 2d609183a..49f915f20 100644 --- a/website/app/docs/client-router/page.ts +++ b/website/app/docs/client-router/page.ts @@ -152,6 +152,13 @@ export default async function PostPage({ params }) {

When the user clicks "Load more", the router's closest('webjs-frame') from the click target finds #comments. The fetched response is expected to contain a <webjs-frame id="comments"> too. Only its children swap into the live frame, leaving the article body (and any reading scroll position, video playback, etc.) fully intact.

This takes precedence over the layout-marker mechanism. Most apps never need it. Only reach for it when you've identified that the auto-marker swap is wider than the actual change.

+

A frame swap never scrolls the page

+

A page navigation scrolls to top, the way a browser does. A frame swap does not: it changes one region and leaves the rest of the document standing, the reader's scroll offset included. Without that, filtering a panel below the fold would throw the reader back to the top of the page, with the panel they just clicked in off screen. The rule covers every way a frame swaps, a nested link, an external data-webjs-frame trigger, a frame-targeted form submission, and a src self-load, and it covers a #hash on a frame link too, which rides the URL without moving the viewport.

+

One thing this rule does NOT cover, because the router never sees it: a pure fragment link to a named anchor (#section), whose path and query match the page it sits on. The click handler bows out before preventDefault, so the browser performs its own native fragment jump and the window does move.

+

The empty fragment is the trap, and it goes the other way. href="#" (and href="") parse to an empty hash, and the bow-out tests that hash for truthiness, so it does not fire. The click becomes an ordinary frame navigation, which re-fetches the frame and, under this rule, leaves the window still. So a bare <a href="#">Back to top</a> placed INSIDE a frame does nothing visible. Give it a real target (href="#top"), which the bow-out honours, or a click handler that scrolls, whose preventDefault runs first and makes the router stand down.

+

Read "never scrolls" as "WebJs never writes a scroll", not as a promise the viewport cannot move. A swap that makes the panel shorter shortens the document with it, and a reader parked near the bottom is then holding an offset the document can no longer reach, so the browser clamps it. On the gallery's frames demo, filtering from All to Done at the bottom of the page moves the window from 474 to 405, exactly the 69px the document lost. The router writes no scroll there, and any DOM change that shortens a page does the same. Keeping the frame a stable height across its states avoids it.

+

The escapes are page navigations and DO scroll to top: data-webjs-frame="_top", and an id that cannot be matched to a live frame, which warns and degrades to a normal navigation. Do not read that second one as covering a response that lacks the requested frame (the webjs:frame-missing warning): there the frame resolved and the navigation stayed frame-scoped, so the offset holds and only the panel is left unchanged. Turbo's autoscroll opt-in, which scrolls the frame itself into view on swap, has no WebJs equivalent; the router simply never writes scroll for a frame.

+

External targeting (data-webjs-frame) and _top

A trigger does not have to be nested inside the frame it drives. Mirroring Turbo's data-turbo-frame, an <a> or <form> (or any ancestor of it) carrying data-webjs-frame="<id>" drives the frame with that id from anywhere in the document, resolved via getElementById. So an external nav/sidebar link or a filter form can drive a content frame it does not enclose.

<nav data-webjs-frame="results"> @@ -257,7 +264,7 @@ revalidate();

Frame links are prefetched too, in their own dimension

A link that drives a <webjs-frame> is prefetched with the same X-Webjs-Frame header its click will send, so the warm entry is the frame subtree the swap actually needs and the click is instant. Without this the hover cost a duplicate request and bought nothing, because the click needs a different response than a page-level prefetch holds.

Since the server varies that response on the request header, the cache keys an entry by URL plus frame id. A prefetched page fragment is therefore never applied into a frame region, nor a frame subtree into a full-page swap, and both can be cached for one URL at once. A frame entry is validated by its frame still being in the document rather than by a boundary anchor, because a subtree carries no boundary comment. A framed link pointing at the URL you are already on is not prefetched at all: that is a frame refresh, and a refresh must show fresh bytes. A <webjs-frame src> that loads itself stands outside this cache entirely, neither reading it nor keeping an entry it supersedes, for the same reason.

-

A route that streams does not get this. The server slices the subtree only when the render did not stream, so a route with a loading.{js,ts} or a Suspense boundary answers every framed request with the whole document instead. The router will not cache that under a frame key. The swap looks for the frame inside the response body, and on a streamed page it may not be there yet: content still inside a pending boundary arrives in a <template> the swap does not descend into. Consuming such an entry would then leave the region unchanged and log a warning, while the navigation around it still completes: the URL advances and the page scrolls to top, so the reader gets a changed address over an unchanged panel. A frame sitting outside every boundary does arrive in the first flush and would be found, but the router cannot tell the two cases apart from the bytes, so it declines the body either way. On those routes the click still costs its round trip, exactly as before. The refusal is remembered, so the link re-asks about once per cache TTL rather than on every hover (the memo set is itself small and capped, so a page with many distinct refused frame links can re-ask sooner).

+

A route that streams does not get this. The server slices the subtree only when the render did not stream, so a route with a loading.{js,ts} or a Suspense boundary answers every framed request with the whole document instead. The router will not cache that under a frame key. The swap looks for the frame inside the response body, and on a streamed page it may not be there yet: content still inside a pending boundary arrives in a <template> the swap does not descend into. Consuming such an entry would then leave the region unchanged and log a warning, while the navigation around it still completes: the URL advances, though the scroll offset is left alone as on any frame nav, so the reader gets a changed address over an unchanged panel. A frame sitting outside every boundary does arrive in the first flush and would be found, but the router cannot tell the two cases apart from the bytes, so it declines the body either way. On those routes the click still costs its round trip, exactly as before. The refusal is remembered, so the link re-asks about once per cache TTL rather than on every hover (the memo set is itself small and capped, so a page with many distinct refused frame links can re-ask sooner).

One thing to expect in the network tab: because dedupe is per dimension, a page that links the same URL twice, once driving a frame and once not, warms both and issues two speculative requests where it previously issued one. The two responses genuinely differ and a click on either link needs its own, so collapsing them would leave one of the links unwarmed ahead of the click. Both stay inside the same cache cap, concurrency gate, TTL, and Save-Data gate as every other prefetch, and no new prefetch trigger is added.

Observing a degraded navigation (webjs:navigation-fallback)