@webjsdev/core 0.7.50 → 0.7.53

package/src/router-client/scroll.js

@@ -0,0 +1,308 @@
+/**
+ * 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, WRITE_BACK_ARMED_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.
+ *
+ * @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(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 save-and-put-back contract the router keeps elsewhere.
+  const prev = root.style.getPropertyValue('overflow-anchor');
+  root.style.setProperty('overflow-anchor', 'none');
+  /** @type {ReturnType<typeof setTimeout> | 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');
+  };
+  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 });
+    }
+    if (onScroll) window.addEventListener('scroll', onScroll, { passive: true });
+  }
+  return release;
+}
+
+/**
+ * Closes the currently held height reservation, or null when none is open.
+ * @type {(() => void) | 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 `<body>`, 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<typeof setTimeout> | 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.
+ *
+ * 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;
+
+/**
+ * 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;
+}
+
+/**
+ * Whether this navigation should keep the reader's current scroll offset rather
+ * than scrolling to top (#1436).
+ *
+ * Resolved from `data-preserve-scroll` on the trigger OR the nearest ancestor
+ * carrying it, so one filter bar / tab strip / breadcrumb marks every link in it
+ * at once. That is `resolveTargetFrameId`'s precedent (`frames.js`), not
+ * `data-no-router`'s element-only read: `data-no-router` turns the router OFF
+ * for a link, a big enough hammer that an ancestor doing it silently would
+ * surprise, while this is a soft preference whose natural authoring unit is a
+ * region.
+ *
+ * VALUE-aware, and the only value that means anything is the literal `false`.
+ * That is Remix 3's `rmx-reset-scroll` test (`!== 'false'`) and the value
+ * vocabulary `prefetchMode` already accepts here. Because `closest()` returns
+ * the NEAREST carrier, `data-preserve-scroll="false"` on one link inside a
+ * marked wrapper opts that link back into the default with no extra logic.
+ *
+ * `fallback` is consulted only when `trigger` resolves NO carrier, which is what
+ * a form submission needs. A submitter is form-associated by `form="id"` rather
+ * than by containment, so `<button form="f">` may sit anywhere in the document
+ * and `closest()` from it would never pass through the form it submits. Falling
+ * back to the form covers that, and ordering it AFTER the trigger is what keeps
+ * `data-preserve-scroll="false"` on the submitter winning over a marked form:
+ * a resolved carrier is never overridden, only a missing one is filled in.
+ *
+ * @param {Element | null} trigger  the clicked anchor, or a submitted form's
+ *   submitter (falling back to the form when there is no submitter).
+ * @param {Element | null} [fallback]  the submitted form, consulted only when
+ *   the trigger carries no mark and is not inside one.
+ * @returns {boolean}
+ */
+export function resolvePreserveScroll(trigger, fallback) {
+  const carrier = findScrollCarrier(trigger) || findScrollCarrier(fallback);
+  if (!carrier) return false;
+  return (carrier.getAttribute('data-preserve-scroll') || '').toLowerCase().trim() !== 'false';
+}
+
+/**
+ * The nearest element at or above `el` carrying `data-preserve-scroll`.
+ *
+ * @param {Element | null | undefined} el
+ * @returns {Element | null}
+ */
+function findScrollCarrier(el) {
+  if (!el || typeof el.closest !== 'function') return null;
+  return el.closest('[data-preserve-scroll]');
+}

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

@@ -0,0 +1,113 @@
+/**
+ * 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, scrollHeight: 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,
+    // 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) {
+    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);
+  // 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;
+}
+
+/**
+ * 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,155 @@
+/**
+ * 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;
+}
+
+/**
+ * The href a bowed-out same-document fragment CLICK is navigating to, pending
+ * the popstate that click is about to produce.
+ *
+ * This exists because URLs alone cannot separate the two ways a popstate can
+ * arrive carrying the url the reader is already on, and the two need opposite
+ * treatment (#1437).
+ *
+ *   - A REPEAT click of one in-page anchor REPLACES its history entry rather
+ *     than pushing, so it fires popstate with `location.href` unchanged. The
+ *     browser has already done the jump and there is nothing to fetch.
+ *   - A Back between two DISTINCT entries that happen to share a url is a real
+ *     traversal that must re-render. The no-JS write path produces that pair: a
+ *     bound `<form action=${fn}>` emits no `action` attribute (invariant 12), so
+ *     `form.action` reflects the node document's URL and the 422 re-render
+ *     pushes a duplicate entry at it.
+ *
+ * An earlier attempt tried to tell them apart by whether the url carried a
+ * fragment, on the reasoning that a repeat anchor click always has one and a
+ * 422 entry never does. The second half is false: `form.action` returns the
+ * document URL WITH its fragment (measured in Chromium, for a missing `action`
+ * attribute and an empty one alike), so a reader who used an in-page anchor
+ * before submitting produces a 422 entry carrying `#sec`, and the Back out of
+ * the validation error was swallowed.
+ *
+ * So the signal is not the url, it is provenance: the router SAW the click it
+ * bowed out of, and it never sees a traversal. `onClick` records the href here
+ * on its way out, the very next popstate consumes it, and anything that starts
+ * a real navigation or submission drops it so it cannot leak across.
+ *
+ * Underscore-prefixed because no source module reads the binding (they go
+ * through the three functions below); its only reader is the test suite, and
+ * this file's own convention is that an unprefixed export here reads as public
+ * API.
+ *
+ * @type {string | null}
+ */
+export let _pendingFragmentNav = null;
+
+/**
+ * Record that a bowed-out fragment click is about to fire a popstate.
+ *
+ * @param {string} href The absolute href the click is navigating to.
+ */
+export function markFragmentNav(href) { _pendingFragmentNav = href; }
+
+/**
+ * Consume the pending mark if it matches, and clear it either way. Clearing on
+ * a MISS matters as much as on a hit: a mark that outlived its popstate must
+ * not sit around waiting to swallow an unrelated one.
+ *
+ * @param {string} href `location.href` at popstate time.
+ * @returns {boolean} True when this popstate is the one that click produced.
+ */
+export function consumeFragmentNav(href) {
+  const hit = _pendingFragmentNav !== null && _pendingFragmentNav === href;
+  _pendingFragmentNav = null;
+  return hit;
+}
+
+/** Drop the pending mark. Any real navigation or submission invalidates it. */
+export function clearFragmentNav() { _pendingFragmentNav = null; }