@webjsdev/core 0.7.49 → 0.7.51

package/src/router-client/scroll.js

@@ -0,0 +1,259 @@
+/**
+ * Client router: scroll.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { ANCHOR_RELEASE_EVENTS, ANCHOR_SUPPRESS_CEILING_MS, ANCHOR_SUPPRESS_FLOOR_MS } from './constants.js';
+
+/**
+ * Closes the currently open restore window, or null when none is open.
+ * @type {(() => void) | null}
+ */
+export let releaseScrollAnchor = null;
+
+/**
+ * Suppress the browser's scroll anchoring for the duration of a back/forward
+ * scroll restore (#1310).
+ *
+ * A snapshot's `scrollY` is recorded against the page at its SETTLED height.
+ * The restore replays that number onto a document that has only just been
+ * swapped in and is still shorter, because the components in the restored
+ * markup have not upgraded and re-rendered yet. When they do, content grows
+ * ABOVE the viewport, and scroll anchoring (`overflow-anchor: auto`, the UA
+ * default) holds the VISUAL position by adding that growth to `scrollY`. The
+ * offset is counted twice. On webjs.dev's `/ui/button` that lands the reader
+ * 763px too low, exactly the settled-minus-swapped height delta.
+ *
+ * Anchoring is right for a reader on a live page and wrong for exactly this
+ * window, where the restored number already accounts for the growth. So the
+ * window suppresses it rather than re-scrolling afterwards. A re-assert would
+ * have to fire on every growth, and a settling restore cannot be told apart
+ * from a `<webjs-suspense>` boundary streaming in (#471 / #473). Suppression
+ * never MOVES the viewport, it only withholds a correction, so it also cannot
+ * yank a reader who has already started scrolling.
+ *
+ * Chromium, Firefox, and WebKit all implement scroll anchoring, and all three
+ * honour `overflow-anchor: none` identically whether it sits on the root
+ * scroller or on `<body>`, so there is no engine-specific path here.
+ *
+ * It goes on the ROOT, and `<body>` is not an alternative even though it looks
+ * like the tidier one. Suppressing on `<body>` works identically on all three
+ * engines (the property excludes an element and its subtree from being chosen
+ * as the anchor, and every candidate lives under `<body>`), and it would avoid
+ * writing to the root at all, which is worth wanting: toggling something on the
+ * root re-runs global style resolution, and on WebKit that re-resolves
+ * `oklch()` token values and repaints them for a frame, which is the #610 flash
+ * that made `data-navigating` opt-in.
+ *
+ * It is disqualified by the RELEASE, not the suppression. On WebKit, anchoring
+ * never resumes once it has been suppressed on `<body>`: removing the property,
+ * setting it back to `auto`, and both in sequence were each measured, and after
+ * every one the next growth above the viewport still failed to move `scrollY`.
+ * Suppressing on the root resumes correctly on all three. Since the whole point
+ * is that suppression is TEMPORARY, a placement that cannot be undone would
+ * leave every WebKit reader, so every iOS browser, with scroll anchoring off
+ * for the life of the page after their first Back. That is a far worse trade
+ * than one repaint, so the root it is.
+ *
+ * @returns {() => void} Idempotent release. Safe to call after the window has
+ *   already closed on user input or the ceiling.
+ */
+export function suppressScrollAnchoring() {
+  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.
+  const prev = root.style.getPropertyValue('overflow-anchor');
+  root.style.setProperty('overflow-anchor', 'none');
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let timer = 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 (typeof window !== 'undefined') {
+      for (const ev of ANCHOR_RELEASE_EVENTS) {
+        window.removeEventListener(ev, release, /** @type {any} */ ({ capture: true }));
+      }
+    }
+    if (prev) root.style.setProperty('overflow-anchor', prev);
+    else root.style.removeProperty('overflow-anchor');
+  };
+  releaseScrollAnchor = release;
+  timer = setTimeout(release, ANCHOR_SUPPRESS_CEILING_MS);
+  if (typeof window !== 'undefined') {
+    for (const ev of ANCHOR_RELEASE_EVENTS) {
+      window.addEventListener(ev, release, { capture: true, passive: true });
+    }
+  }
+  return release;
+}
+
+/**
+ * Cancels an in-flight catch-up, or null when none is running.
+ * @type {(() => void) | null}
+ */
+export let cancelScrollCatchUp = null;
+
+/**
+ * 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.
+ *
+ * Deliberately NOT `currentNavigationToken`, which is the obvious choice and the
+ * wrong one: `loadFrame` bumps that too, and its own contract says a frame
+ * self-load is not a page navigation. An eager `<webjs-frame src>` inside a
+ * RESTORED snapshot loads during the swap, so keying on the nav token would
+ * read a routine frame load as a supersede and drop the entire restore, leaving
+ * the reader at the outgoing page's offset. That is worse than the defect this
+ * whole change fixes. This counter moves only for the three things that really
+ * do end a restore.
+ */
+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<typeof setTimeout> | 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
+  // <webjs-suspense> 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
+ * `requestAnimationFrame` is absent (the linkedom-backed node test harness).
+ *
+ * @param {() => void} fn
+ */
+export function afterTwoFrames(fn) {
+  if (typeof requestAnimationFrame !== 'function') { setTimeout(fn, 0); return; }
+  requestAnimationFrame(() => requestAnimationFrame(fn));
+}
+
+/**
+ * Bump the restore generation.
+ *
+ * `restoreGeneration` is written by this module AND by the navigator, where
+ * every fresh navigation invalidates an in-flight scroll restore. An ESM import
+ * binding cannot be assigned across a module boundary, so the navigator calls
+ * this rather than doing `restoreGeneration += 1` itself. Same statement, same
+ * semantics, one indirection.
+ */
+export function bumpRestoreGeneration() {
+  restoreGeneration += 1;
+}

package/src/router-client/snapshot-cache.js

@@ -0,0 +1,97 @@
+/**
+ * Client router: snapshot-cache.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { SNAPSHOT_CAP } from './constants.js';
+
+/** @typedef {{ html: string, scrollX: number, scrollY: number }} Snapshot */
+/** @type {Map<string, Snapshot | string>} */
+export const snapshotCache = new Map();
+
+/**
+ * Cache the current document's HTML + window scroll position keyed by
+ * URL. Used on back/forward navigation: the cached DOM restores
+ * instantly, scroll position restores to whatever the user left it at.
+ *
+ * Turbo Drive captures `window.pageXOffset/pageYOffset` on every scroll
+ * event into history state. Webjs captures lazily at snapshot time -
+ * one read per nav rather than one per scroll event. Sufficient because
+ * we only need the position at the moment of leaving.
+ *
+ * @param {string} url
+ */
+export function snapshotCurrent(url) {
+  const key = cacheKey(url);
+  // Let components and app code strip transient state (open overlays, toasts,
+  // in-progress wizard steps) from the page BEFORE it is serialized into the
+  // back/forward cache, so a later popstate restore shows a clean page rather
+  // than, say, a hover-card frozen open (#766, Turbo's `before-cache` contract).
+  // Fires SYNCHRONOUSLY on the live DOM right before the outerHTML read, so a
+  // handler's mutations are captured; the live edits are invisible because the
+  // page is being navigated away from.
+  document.dispatchEvent(new CustomEvent('webjs:before-cache', { detail: { url } }));
+  // Move-to-front for LRU.
+  if (snapshotCache.has(key)) snapshotCache.delete(key);
+  /** @type {Snapshot} */
+  const snap = {
+    html: document.documentElement.outerHTML,
+    scrollX: typeof window !== 'undefined' ? window.scrollX || 0 : 0,
+    scrollY: typeof window !== 'undefined' ? window.scrollY || 0 : 0,
+  };
+  snapshotCache.set(key, snap);
+  while (snapshotCache.size > SNAPSHOT_CAP) {
+    const oldest = snapshotCache.keys().next().value;
+    snapshotCache.delete(oldest);
+  }
+}
+
+/**
+ * Look up a cached snapshot by URL. Returns a normalized Snapshot or
+ * null. Tolerates legacy string entries (e.g. from test fixtures that
+ * `_snapshotCache.set('/x', 'snap')`).
+ *
+ * @param {string} url
+ * @returns {Snapshot | null}
+ */
+export function snapshotGet(url) {
+  const key = cacheKey(url);
+  const v = snapshotCache.get(key);
+  if (v == null) return null;
+  // Move-to-front.
+  snapshotCache.delete(key);
+  snapshotCache.set(key, v);
+  if (typeof v === 'string') return { html: v, scrollX: 0, scrollY: 0 };
+  return v;
+}
+
+/**
+ * The cache key for a URL, optionally in a `<webjs-frame>` dimension (#1407).
+ *
+ * A frame response is SLICED by the `x-webjs-frame` request header and the
+ * server marks it `Vary: X-Webjs-Frame`, so a client-side cache of that
+ * response has to carry the same dimension or a frame subtree and a page
+ * fragment for one URL alias onto each other.
+ *
+ * The delimiter is a single SPACE, which cannot occur in either half: the URL
+ * parser percent-encodes U+0020 in both the path and the query, and an HTML
+ * `id` may not contain ASCII whitespace. So a framed key always holds a space
+ * and an unframed one never does, and even a non-conforming id set through the
+ * DOM stays unambiguous, because the space-free URL half means the LAST space
+ * separates the two.
+ *
+ * @param {string} url
+ * @param {string | null} [frameId]
+ */
+export function cacheKey(url, frameId) {
+  const u = new URL(url, location.href);
+  const path = u.pathname + u.search;
+  return frameId ? `${frameId} ${path}` : path;
+}
+
+/* ====================================================================
+ * Navigation
+ * ==================================================================== */

package/src/router-client/state.js

@@ -0,0 +1,92 @@
+/**
+ * Client router: state.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+
+/**
+ * Monotonic counter incremented at the start of every navigation. Each
+ * async path captures the value at its entry point and compares before
+ * applying side effects (swap, restore-optimistic). A mismatch means a
+ * newer nav superseded this one: bail out silently. Belt-and-suspenders
+ * on top of AbortController: covers paths where a response has already
+ * resolved past the await but a newer nav started before applySwap ran.
+ */
+export let currentNavigationToken = 0;
+
+/**
+ * The one place the router hands a navigation back to the browser.
+ *
+ * Every hard navigation the router performs goes through here rather than
+ * assigning `location.href` inline, so a browser test can observe it. The
+ * default is exactly the assignment it replaces, so behaviour is unchanged
+ * unless something calls `setHardNavigate`.
+ *
+ * This exists because a hard navigation is UNOBSERVABLE and UNPREVENTABLE from
+ * outside. `preventDefault` cancels a default action, not a script assignment,
+ * and `location.href` is non-configurable on Chromium, Firefox, and WebKit
+ * alike, so a test cannot redefine its setter either (measured; the older
+ * `spyOnReload` helper that tried was silently a no-op on every engine). In a
+ * web-test-runner session a real navigation aborts the WHOLE session, so one
+ * degradation destroys every remaining browser test file and reports `0 failed`
+ * on the way out. A seam is the only thing that makes it catchable.
+ *
+ * @param {string} href
+ */
+export let hardNavigate = (href) => { location.href = href; };
+
+/**
+ * Test-only: replace the hard-navigate action so a browser test can observe a
+ * navigation instead of being destroyed by it. Call with no argument to
+ * restore. Underscore-prefixed and kept in this block like every other
+ * test-only export here, so it stays out of `router-client.d.ts` and out of
+ * the app-facing API (the `./client-router` subpath resolves this file under
+ * the `source` condition, so an unprefixed name here would read as public).
+ *
+ * @param {((href: string) => void) | null} [fn]
+ */
+export function _setHardNavigate(fn) {
+  hardNavigate = fn || ((href) => { location.href = href; });
+}
+
+/** Test-only: read the monotonic navigation-token counter. */
+export function _navToken() { return currentNavigationToken; }
+
+/** Test-only: bump the navigation-token counter (simulates a fresh nav). */
+export function _bumpNavToken() { return ++currentNavigationToken; }
+
+/**
+ * Bump the navigation token and return the new value.
+ *
+ * The navigator opens every navigation with `++currentNavigationToken`, and the
+ * counter lives here beside the `_navToken` seam that reads it. An ESM import
+ * binding cannot be incremented from another module, so the navigator calls
+ * this and keeps the same capture-then-compare pattern.
+ */
+export function bumpNavToken() {
+  return ++currentNavigationToken;
+}
+
+/**
+ * Whether the client router is currently intercepting navigations.
+ *
+ * Owned here rather than in navigator.js because `events.js` and
+ * `prefetch.js` both gate on it, so parking it beside the code that flips it
+ * made two leaf-ward modules import the orchestrator and pulled them into the
+ * router's import cycle. navigator.js still owns the TRANSITIONS through
+ * `_setEnabled`; this module just holds the bit.
+ */
+export let enabled = false;
+
+/**
+ * Flip the router-enabled bit. Called only by enableClientRouter /
+ * disableClientRouter in navigator.js.
+ *
+ * @param {boolean} v
+ */
+export function _setEnabled(v) {
+  enabled = v;
+}

package/src/router-client/stream.js

@@ -0,0 +1,206 @@
+/**
+ * Client router: stream.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { warnDropped } from './diagnostics.js';
+import { upgradeTree } from './upgrade.js';
+
+/**
+ * Forward streamed Suspense resolver templates from the fetched body to
+ * the live body. Needed when the new page emits a Suspense boundary that
+ * resolves later.
+ *
+ * @param {HTMLElement} fetchedBody
+ */
+export function forwardSuspenseResolvers(fetchedBody) {
+  for (const tpl of fetchedBody.querySelectorAll('template[data-webjs-resolve]')) {
+    const clone = /** @type {HTMLTemplateElement} */ (tpl.cloneNode(true));
+    document.body.appendChild(clone);
+    // Resolve SYNCHRONOUSLY against the just-swapped DOM instead of relying on
+    // the inline MutationObserver. The observer fires on a microtask, which
+    // races an async `startViewTransition` swap: with view transitions on, the
+    // swap that places the `#<id>` placeholder is deferred a frame, so the
+    // observer ran first, found no placeholder, and the skeleton stuck (#1048).
+    // Called from INSIDE the swap thunk (below), the placeholder is already in
+    // the DOM here, so this replaces it within the same commit (and inside any
+    // wrapping view transition, so the transition captures the resolved
+    // content, not the fallback). Falls back to the observer if the page-level
+    // resolver global is somehow absent.
+    const id = clone.getAttribute('data-webjs-resolve');
+    const resolve = /** @type {any} */ (window).__webjsResolve;
+    if (id && typeof resolve === 'function') resolve(id);
+  }
+}
+
+/**
+ * Read a navigation response body progressively (#473). Returns the SHELL
+ * (the HTML up to the first streamed Suspense boundary template) as soon as it
+ * is available, so the router can swap it in immediately and the user sees the
+ * fallbacks without waiting for the slow boundary. When the body carries
+ * streamed boundaries it also returns the still-open `reader` + leftover buffer
+ * so the caller applies each boundary progressively AFTER the shell swap. A body
+ * with no boundaries reads to completion and returns the whole thing, so a
+ * non-streaming navigation is behaviourally identical to `resp.text()`.
+ *
+ * @param {Response} resp
+ * @returns {Promise<{ shell: string, streaming: boolean, reader?: ReadableStreamDefaultReader<Uint8Array>, dec?: TextDecoder, rest?: string }>}
+ */
+export async function readStreamedShell(resp) {
+  if (!resp.body || typeof resp.body.getReader !== 'function') {
+    return { shell: await resp.text(), streaming: false };
+  }
+  const reader = resp.body.getReader();
+  const dec = new TextDecoder();
+  let buf = '';
+  const MARK = '<template data-webjs-resolve';
+  // The SSR stream flushes the whole shell (prefix + body with fallbacks)
+  // followed by a `<!--wj-stream-shell-->` sentinel in the SAME chunk, then
+  // PAUSES for the slow data before streaming each boundary template and the
+  // `</body></html>` closer. The sentinel is what lets the shell swap in
+  // immediately instead of blocking until the slow boundary arrives. Fallbacks
+  // for robustness: an already-buffered boundary marker (a fast boundary), or
+  // `</html>` (a fully-buffered response that happens to carry boundaries).
+  const SHELL = '<!--wj-stream-shell-->';
+  const HTML_CLOSE = /<\/html\s*>/i;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (value) buf += dec.decode(value, { stream: true });
+    if (done) buf += dec.decode();
+    const si = buf.indexOf(SHELL);
+    if (si !== -1) {
+      return { shell: buf.slice(0, si), streaming: true, reader: done ? null : reader, dec, rest: buf.slice(si + SHELL.length) };
+    }
+    const mi = buf.indexOf(MARK);
+    if (mi !== -1) {
+      return { shell: buf.slice(0, mi), streaming: true, reader: done ? null : reader, dec, rest: buf.slice(mi) };
+    }
+    if (done) {
+      // Stream ended with no streaming markers: the whole body is the shell.
+      return { shell: buf, streaming: false };
+    }
+    const hm = HTML_CLOSE.exec(buf);
+    if (hm) {
+      const end = hm.index + hm[0].length;
+      return { shell: buf.slice(0, end), streaming: true, reader, dec, rest: buf.slice(end) };
+    }
+  }
+}
+
+/**
+ * Extract the next complete top-level
+ * `<template data-webjs-resolve="ID">...</template>` unit from `buf`,
+ * depth-tracking NESTED `<template>` tags (a streamed shadow component carries a
+ * `<template shadowrootmode>` inside). Returns `{ id, content, rest }` for the
+ * first complete unit, or null when the closing tag has not streamed in yet.
+ *
+ * @param {string} buf
+ * @returns {{ id: string, content: string, rest: string } | null}
+ */
+export function takeResolveUnit(buf) {
+  const m = /<template\s+data-webjs-resolve="([^"]+)"\s*>/i.exec(buf);
+  if (!m) return null;
+  const id = m[1];
+  const contentStart = m.index + m[0].length;
+  const tagRe = /<(\/?)template\b[^>]*>/gi;
+  tagRe.lastIndex = contentStart;
+  let depth = 1;
+  let mm;
+  while ((mm = tagRe.exec(buf))) {
+    if (mm[1] === '/') {
+      depth--;
+      if (depth === 0) {
+        return { id, content: buf.slice(contentStart, mm.index), rest: buf.slice(mm.index + mm[0].length) };
+      }
+    } else {
+      depth++;
+    }
+  }
+  return null;
+}
+
+/**
+ * Apply one streamed Suspense resolution to the live DOM (#473). REPLACES the
+ * boundary element (its fallback) with the resolved content and upgrades any
+ * custom elements inside. This mirrors the initial-load boot resolver
+ * (`b.replaceWith(template.content)`) and the prefetched-buffered path exactly,
+ * so a streamed boundary settles to the SAME DOM shape (the transient
+ * `<webjs-boundary>` / `<webjs-suspense>` wrapper removed) however the page was
+ * reached, in JS so a soft-nav apply does not depend on the inline swap script.
+ *
+ * @param {string} id
+ * @param {string} content
+ */
+export function applyStreamedResolve(id, content) {
+  const boundary = document.getElementById(id);
+  // A missing boundary is dropped (non-destructive), exactly as before. The
+  // async-view-transition race that USED to drop a still-valid boundary (#1048)
+  // is handled upstream: `streamBoundariesProgressively` is gated on the swap
+  // COMMIT (`_swapCommit`), so the placeholder is already live by the time any
+  // resolve is applied. A retry here would run OUTSIDE the streamer's
+  // `isCurrent()` nav-token fence and could splice a superseded nav's content
+  // into a recycled boundary id, so it is deliberately not attempted.
+  if (!boundary) {
+    // Dev-only diagnostic (#1051): the drop is benign for the normal reasons (a
+    // superseded / degraded / discarded nav), but a stuck skeleton that ISN'T
+    // one of those is otherwise silent, which is exactly what made #1048 hard to
+    // find. Surface the dropped boundary so a future regression is one glance
+    // away. Never in production, never throws, once per id.
+    warnDropped(id);
+    return;
+  }
+  const tpl = document.createElement('template');
+  tpl.innerHTML = content;
+  const inserted = [...tpl.content.childNodes];
+  boundary.replaceWith(tpl.content);
+  // Upgrade any custom elements now that they are connected (belt-and-braces:
+  // a connected, defined element upgrades on insertion, but a fragment that was
+  // built before its module loaded would not).
+  for (const n of inserted) if (n.nodeType === 1) upgradeTree(/** @type {Element} */ (n));
+}
+
+/**
+ * Progressively apply streamed Suspense boundaries from an open response reader
+ * to the live DOM AFTER the shell has been swapped in (#473). Runs detached
+ * (fire-and-forget); each apply is guarded by `isCurrent` so a newer navigation
+ * stops it (and cancels the reader). A mid-stream transport failure leaves the
+ * already-applied boundaries in place and the rest showing their fallback,
+ * which is non-destructive.
+ *
+ * @param {ReadableStreamDefaultReader<Uint8Array>} reader
+ * @param {TextDecoder} dec
+ * @param {string} initialBuf
+ * @param {() => boolean} isCurrent
+ */
+export async function streamBoundariesProgressively(reader, dec, initialBuf, isCurrent) {
+  let buf = initialBuf;
+  const flush = () => {
+    let unit;
+    while ((unit = takeResolveUnit(buf))) {
+      if (!isCurrent()) return false;
+      applyStreamedResolve(unit.id, unit.content);
+      buf = unit.rest;
+    }
+    return true;
+  };
+  // The whole response was already buffered (the stream ended before the shell
+  // delimiter): just apply whatever boundaries are in hand.
+  if (!reader) { flush(); return; }
+  try {
+    for (;;) {
+      if (!flush()) { try { await reader.cancel(); } catch { /* ignore */ } return; }
+      const { value, done } = await reader.read();
+      if (value) buf += dec.decode(value, { stream: true });
+      if (done) {
+        buf += dec.decode();
+        flush();
+        return;
+      }
+    }
+  } catch {
+    /* transport drop mid-stream: leave applied boundaries + remaining fallbacks */
+  }
+}