@wular/pnext 0.0.1

package/src/compat/client/link-status.ts

@@ -0,0 +1,86 @@
+// Per-link navigation pending state for `useLinkStatus()` (next/link). A single link is "pending" at a
+// time: the last one whose click started an in-flight soft navigation. It clears on completion, and on
+// any navigation started elsewhere - all of which broadcast a location change.
+import { createContext } from 'preact/compat';
+import { softNavigate } from '../../api/router';
+import { locationListeners, onNavigationStart } from '../../api/router/events';
+import { patchHistory } from '../../api/client-navigation';
+
+export interface LinkStatus {
+  pending: boolean;
+}
+
+export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
+
+type Listener = () => void;
+
+let pendingToken: symbol | null = null;
+// Set right before navigateWithStatus starts its own soft-nav, so the resulting
+// synchronous nav-start is recognized as the link's own, not a supersession.
+let ownNavStart: symbol | null = null;
+const listeners = new Set<Listener>();
+let wired = false;
+
+function notify() {
+  for (const listener of [...listeners]) listener();
+}
+
+function setPending(token: symbol | null) {
+  if (pendingToken === token) return;
+  pendingToken = token;
+  notify();
+}
+
+// A different navigation starting (router.push, refresh, another link)
+// supersedes the pending link immediately, even while its own nav is still
+// in flight — its synchronous start isn't the pending link's own.
+function onNavStart() {
+  if (ownNavStart !== null) {
+    ownNavStart = null;
+    return;
+  }
+  setPending(null);
+}
+
+// A location change ends the pending state: for the pending link's own nav this
+// only fires at completion (its pushState happens after the fetch resolves);
+// for shallow pushState / browser back it fires immediately. Both should clear.
+function onLocationChange() {
+  setPending(null);
+}
+
+function wire() {
+  if (wired || (!process.browser && typeof window === 'undefined')) return;
+  wired = true;
+  // Raw window.history.pushState/replaceState (shallow routing) must clear the
+  // pending link; the patch broadcasts them through locationListeners.
+  patchHistory();
+  onNavigationStart(onNavStart);
+  locationListeners().add(onLocationChange);
+  window.addEventListener('popstate', onLocationChange);
+}
+
+export function subscribeLinkStatus(_token: symbol, listener: Listener) {
+  wire();
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function linkPending(token: symbol) {
+  return pendingToken === token;
+}
+
+// Start a soft navigation owned by this link: mark it pending, clear on
+// completion. A newer click flips the token, so a stale completion won't clear
+// the newer link's pending state.
+export function navigateWithStatus(
+  token: symbol,
+  href: string,
+  options: { replace?: boolean; scroll?: boolean },
+) {
+  ownNavStart = token;
+  setPending(token);
+  void softNavigate(href, options).finally(() => {
+    if (pendingToken === token) setPending(null);
+  });
+}

package/src/compat/client/nav-compat-runtime.ts

@@ -0,0 +1,57 @@
+// DEFERRED TIER of the navigation compat layer (see ./nav-compat). Every policy
+// here is read by the router runtime and by nothing else, so it loads with the
+// runtime chunk — the installers finish before the facade hands the runtime out,
+// so the first fetch already sees Next's windows and caches.
+import { setSoftNavBoundary } from '../../api/router';
+import { setNavigationScrollAction } from '../../api/router/events';
+import {
+  setLoadingShellPredictionPolicy,
+  setPrefetchStaleTimePolicy,
+  setRevalidationPrefetchDelay,
+  setSegmentCachePolicy,
+  setShellStaleTimePolicy,
+  setStylesheetReconciler,
+} from '../../api/router/policies';
+import { installSegmentCachePolicy } from './segment-cache-policy';
+// `output: 'export'` document fetching. Imported for its module-scope
+// registration, which has to beat the router's first prefetches — this module
+// resolving before the runtime is handed out is exactly that guarantee.
+import '../export/client';
+import { reconcileNextStylesheets } from './css-order';
+import { staleTimeForEntryMs, staticStaleTimeMs } from './prefetch-cache';
+import { isOutsideBasePath } from './base-path';
+import { predictNextLoadingShell } from './optimistic-routing';
+import { applyNextNavigationScroll } from './navigation-scroll';
+import { installRouteAnnouncer } from './route-announcer';
+
+export function installNavPolicies() {
+  // Route announcer: mount the empty `<next-route-announcer>` and update it on
+  // every soft-nav commit (a11y — announce client route changes to AT). Next
+  // mounts it at hydration; it announces nothing until the first navigation, and
+  // this tier lands on idle, long before one can happen.
+  installRouteAnnouncer();
+  // Prefetch staleTime policy: static 300s / dynamic 0, with the
+  // experimental.staleTimes override injected as window.__PNEXT_STALE_TIMES__,
+  // and a response `x-nextjs-stale-time` header overriding both when present.
+  setPrefetchStaleTimePolicy(staleTimeForEntryMs);
+  setRevalidationPrefetchDelay(300);
+  // Loading-shell window: a route's cached loading boundary (and the prefetch
+  // entry carrying it) reuses for the STATIC window even when its dynamic data
+  // is immediately stale — Next's split staleness model.
+  setShellStaleTimePolicy(staticStaleTimeMs);
+  setLoadingShellPredictionPolicy(predictNextLoadingShell);
+  // Per-segment (vary-params) client cache — Segment-M2 deliverable 3. Entries
+  // are keyed on the params a segment provably reads, so one entry serves every
+  // param value it does not depend on.
+  setSegmentCachePolicy(installSegmentCachePolicy());
+  setNavigationScrollAction(applyNextNavigationScroll);
+  setStylesheetReconciler(reconcileNextStylesheets);
+  // basePath boundary: a same-origin URL outside the configured basePath must
+  // hard-navigate (a `basePath:false` target), not soft-swap.
+  setSoftNavBoundary(isOutsideBasePath);
+  // NOTE: the standalone segment-prefetch wire runtime (segment-prefetch.ts) is
+  // deliberately NOT installed: its intent-time tree/body fetches fed caches
+  // nothing consumed and broke Next's request-count contracts (a hover inside a
+  // "no-requests" scope must not fetch). The router's own prefetch cache +
+  // loading-shell cache cover the segment semantics on the HTML-swap model.
+}

package/src/compat/client/nav-compat.ts

@@ -0,0 +1,42 @@
+// Client-side navigation compat, installed once per compat entry.
+//
+// FIRST PAINT holds only what a click can hit before the navigation runtime lands: Next's
+// javascript:-URL block message (a static Link click reports it with no runtime at all) and
+// `window.next.router`, which app code can call at any time. Everything else here is a POLICY the
+// runtime alone reads, so it rides the runtime's own chunk via registerDeferredInstall and never costs
+// a page that never navigates.
+import {
+  prefetchRoute,
+  registerDeferredInstall,
+  setBlockedJavascriptUrlReporter,
+  softNavigate,
+} from '../../api/router';
+
+const BLOCKED_JS_URL_MESSAGE =
+  'Next.js has blocked a javascript: URL as a security precaution.';
+
+export function installNavCompat() {
+  if (!process.browser && typeof window === 'undefined') return;
+  setBlockedJavascriptUrlReporter(() => console.error(BLOCKED_JS_URL_MESSAGE));
+  const windowWithReporter = window as typeof window & { __PNEXT_JS_URL_REPORTER__?: boolean };
+  if (!windowWithReporter.__PNEXT_JS_URL_REPORTER__) {
+    windowWithReporter.__PNEXT_JS_URL_REPORTER__ = true;
+    window.addEventListener('pnext:blocked-javascript-url', () => {
+      console.error(BLOCKED_JS_URL_MESSAGE);
+    });
+  }
+  installNextRouterGlobal();
+  registerDeferredInstall(() => import('./nav-compat-runtime').then(m => m.installNavPolicies()));
+}
+
+// `window.next.router` — Next's own global handle. Pure-core apps have no such
+// namespace, so it installs from compat rather than from the router hub.
+function installNextRouterGlobal() {
+  window.next ??= {};
+  window.next.router = {
+    ...window.next.router,
+    push: href => softNavigate(String(href)),
+    replace: href => softNavigate(String(href), { replace: true }),
+    prefetch: href => prefetchRoute(String(href), { strict: true }),
+  };
+}

package/src/compat/client/navigation-scroll.ts

@@ -0,0 +1,154 @@
+import type { NavigationScrollAction, NavigationScrollOptions } from '../../api/router';
+
+const RECT_PROPERTIES = ['bottom', 'height', 'left', 'right', 'top', 'width', 'x', 'y'] as const;
+
+export type NextScrollPlan = 'hash' | 'preserve' | 'restore' | 'top' | 'top-then-target';
+
+export function nextScrollPlan(
+  url: URL,
+  options: NavigationScrollOptions,
+  targetInViewport: boolean | undefined,
+): NextScrollPlan {
+  if (options.pop) return 'restore';
+  if (options.scroll === false) return 'preserve';
+  if (url.hash) return 'hash';
+  if (targetInViewport === undefined) return 'top';
+  return targetInViewport ? 'preserve' : 'top-then-target';
+}
+
+export function firstScrollCandidate<T>(
+  candidates: Iterable<T>,
+  shouldSkip: (candidate: T) => boolean,
+): T | undefined {
+  for (const candidate of candidates) if (!shouldSkip(candidate)) return candidate;
+  return undefined;
+}
+
+export function deepestSingleChild<T>(node: T | undefined, onlyChild: (node: T) => T | undefined) {
+  while (node) {
+    const child = onlyChild(node);
+    if (!child) return node;
+    node = child;
+  }
+  return undefined;
+}
+
+export function topOnlyScrollPosition(scrollX: number): [number, number] {
+  return [scrollX, 0];
+}
+
+export const applyNextNavigationScroll: NavigationScrollAction = (url, options) => {
+  const target = scrollFocusTarget();
+  const plan = nextScrollPlan(
+    url,
+    options,
+    target ? targetTopInViewport(target, document.documentElement.clientHeight) : undefined,
+  );
+  if (plan === 'restore') {
+    const state = history.state as { __pnextScroll?: [number, number] } | null;
+    const [x, y] = state?.__pnextScroll ?? [0, 0];
+    window.scrollTo(x, y);
+    return;
+  }
+  // React hoists a rendered <style precedence>/<link rel=stylesheet>/metadata element out of the segment
+  // and into <head>. Next resolves its scroll target with findDOMNode() on the changed segment, so when
+  // the segment's FIRST host element is one of those the walk starts inside <head>, skips every
+  // zero-rect sibling there and runs out - the navigation scrolls nowhere and focuses nothing. pnext
+  // renders those elements in place, so recognize the leading hoisted element and reproduce the same
+  // no-op. Placed after `restore` so history traversal still restores its saved position.
+  if (segmentLeadsWithHoistedElement()) return;
+  if (plan === 'hash') {
+    scrollToHash(url.hash);
+    return;
+  }
+  if (plan === 'preserve') {
+    if (target && options.scroll !== false) focusSegment(target);
+    return;
+  }
+  if (plan === 'top') {
+    window.scrollTo(...topOnlyScrollPosition(window.scrollX));
+    return;
+  }
+  if (!target) return;
+  window.scrollTo(...topOnlyScrollPosition(window.scrollX));
+  if (!targetTopInViewport(target, document.documentElement.clientHeight)) target.scrollIntoView();
+  focusSegment(target);
+};
+
+function shouldSkipScrollElement(element: HTMLElement) {
+  const position = getComputedStyle(element).position;
+  if (position === 'sticky' || position === 'fixed') return true;
+  const rect = element.getBoundingClientRect();
+  return RECT_PROPERTIES.every(item => rect[item] === 0);
+}
+
+function targetTopInViewport(element: HTMLElement, viewportHeight: number) {
+  const rects = element.getClientRects();
+  if (rects.length === 0) return false;
+  let top = Number.POSITIVE_INFINITY;
+  for (const rect of rects) top = Math.min(top, rect.top);
+  return top >= 0 && top <= viewportHeight;
+}
+
+function scrollFocusTarget(): HTMLElement | null {
+  const segment = changedSegmentRoot();
+  if (!segment) return null;
+  // Next resolves the target with findDOMNode() on the changed segment: the
+  // FIRST host element the segment rendered, never a descendant of it. The page
+  // container IS that segment, so its first element child is the target as-is.
+  // The fallback roots below wrap the segment in pnext's own chrome, so there
+  // the single-child chain is walked down to the content that segment rendered.
+  const first =
+    segment.id === PAGE_CONTAINER_ID
+      ? (segment.firstElementChild ?? undefined)
+      : deepestSingleChild(segment.firstElementChild ?? undefined, node =>
+          node.nextElementSibling === null ? (node.firstElementChild ?? undefined) : undefined,
+        );
+  const nodes: HTMLElement[] = [];
+  for (let node = first; node; node = node.nextElementSibling ?? undefined) {
+    if (node instanceof HTMLElement) nodes.push(node);
+  }
+  return firstScrollCandidate(nodes, shouldSkipScrollElement) ?? null;
+}
+
+/** The renderer's page-slot wrapper — the segment a navigation replaced. */
+const PAGE_CONTAINER_ID = 'pnext-page';
+
+// Elements React relocates into <head> when a component renders them.
+const HOISTED_TAGS = new Set(['style', 'link', 'title', 'meta', 'base']);
+
+/**
+ * Whether the changed segment's first rendered element is one React would have hoisted into <head> -
+ * the state in which Next's scroll walk never reaches the page content (see the call site).
+ */
+function segmentLeadsWithHoistedElement(): boolean {
+  const segment = changedSegmentRoot();
+  const first = segment?.firstElementChild;
+  return first !== null && first !== undefined && HOISTED_TAGS.has(first.localName);
+}
+
+function changedSegmentRoot(): HTMLElement | null {
+  const page = document.getElementById(PAGE_CONTAINER_ID);
+  if (page instanceof HTMLElement) return page;
+  const root = document.querySelector('[data-pnext-root]');
+  return root instanceof HTMLElement ? root : document.body;
+}
+
+function scrollToHash(hash: string) {
+  const id = decodeURIComponent(hash.slice(1));
+  const target = id === 'top' ? document.body : (document.getElementById(id) ?? namedTarget(id));
+  target?.scrollIntoView();
+}
+
+function namedTarget(name: string): HTMLElement | null {
+  const named = document.getElementsByName(name)[0];
+  return named instanceof HTMLElement ? named : null;
+}
+
+function focusSegment(target: HTMLElement) {
+  try {
+    target.focus({ preventScroll: true });
+  } catch {
+    // A swap can detach the target before focus runs.
+  }
+}

package/src/compat/client/optimistic-routing.ts

@@ -0,0 +1,206 @@
+// Optimistic routing (Next's route-prediction trie) - COMPAT client policy.
+//
+// After a route pattern is learned from one URL (its prefetched/visited shell carries
+// `window.__PNEXT_ROUTE__`), a navigation to a DIFFERENT URL matching the same pattern paints that
+// cached loading shell instantly with the predicted params - no tree prefetch needed.
+//
+// Two guards keep predictions honest, both mirroring Next:
+//   - `staticChildren`: literal siblings of the dynamic level. A target whose segment names a static
+//     sibling must resolve on the server, since the sibling route wins over the dynamic pattern, so
+//     prediction bails.
+//   - rewrite detection: a shell whose OWN stored pathname does not match its route pattern was
+//     produced by a rewrite. Such a response must never seed predictions - the rewrite may map a
+//     sibling URL somewhere else entirely, or vary on search params.
+
+import type { RouteParamValue } from '../../types';
+
+interface RouteState {
+  // Bracket-free colon form: `:id` for a dynamic segment, `:slug*` for a
+  // catch-all; `catchAllOptional` distinguishes `[[...slug]]` (matches zero
+  // segments) from `[...slug]` (requires at least one).
+  route: string;
+  params: Record<string, RouteParamValue>;
+  catchAllOptional?: boolean;
+  staticChildren?: string[];
+  staticChildrenBySegment?: Record<string, string[]>;
+  prefetchKind?: 'shell' | 'eager';
+  /** `prefetch = 'allow-runtime'`: the shell is request-sampled PER URL. */
+  runtimePrefetch?: boolean;
+}
+
+interface PredictedShell {
+  html: string;
+  route: RouteState;
+  prefetch?: 'shell' | 'eager';
+  /**
+   * True when the predicted shell belongs to an `allow-runtime` route. Its content is derived from the
+   * sampled request's params, so a cached shell of ONE param value says nothing about another - the
+   * router must still prefetch every unseen URL of the route (a `partial` shell, being static, is shared).
+   *
+   * ...UNLESS `experimental.appShells` is on: there the runtime prefetch of a non-eager route renders
+   * with its `params` HANGING, so the cached shell IS the route's shared App Shell and says the same
+   * thing for every param. Revealing another link of the route then has nothing to fetch.
+   */
+  runtimePrefetch?: boolean;
+}
+
+/** `experimental.appShells`, stamped into the document by register-render. */
+function appShellsEnabled(): boolean {
+  if (!process.browser && typeof window === 'undefined') return false;
+  return (window as { __PNEXT_APP_SHELLS__?: boolean }).__PNEXT_APP_SHELLS__ === true;
+}
+
+export function predictNextLoadingShell(
+  url: URL,
+  shells: ReadonlyMap<string, string>,
+): PredictedShell | undefined {
+  // Most recently stored shells first (Map preserves insertion order).
+  for (const [pathname, html] of [...shells.entries()].reverse()) {
+    const state = routeStateFromShell(html);
+    if (!state) continue;
+    // A shell's own URL must fit its route pattern before it can teach the
+    // route trie. This catches rewrites, including a dynamic response served
+    // for a known static sibling.
+    if (!matchRoute(state, pathname)) continue;
+    const params = matchRoute(state, url.pathname);
+    if (params) {
+      return {
+        html: reifyShellParams(html, state.params, params),
+        route: {
+          route: state.route,
+          params,
+          ...(state.catchAllOptional ? { catchAllOptional: true } : {}),
+        },
+        ...(state.prefetchKind ? { prefetch: state.prefetchKind } : {}),
+        ...(state.runtimePrefetch && !appShellsEnabled() ? { runtimePrefetch: true } : {}),
+      };
+    }
+  }
+  return undefined;
+}
+
+function routeStateFromShell(html: string): RouteState | undefined {
+  const raw = /window\.__PNEXT_ROUTE__=(\{.*?\});<\/script>/.exec(html)?.[1];
+  if (!raw) return undefined;
+  try {
+    const state = JSON.parse(raw) as RouteState;
+    return typeof state.route === 'string' && state.params && typeof state.params === 'object'
+      ? state
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function matchRoute(state: RouteState, pathname: string): Record<string, RouteParamValue> | undefined {
+  const pattern = state.route.split('/').filter(Boolean);
+  const target = pathname.split('/').filter(Boolean).map(decodeSegment);
+  const params: Record<string, RouteParamValue> = {};
+  let cursor = 0;
+  for (let index = 0; index < pattern.length; index++) {
+    const segment = pattern[index]!;
+    // Colon form: `:slug*` is a catch-all, `:id` a single dynamic segment.
+    const catchAll = /^:([\w$]+)\*$/.exec(segment);
+    const dynamic = catchAll ? null : /^:([\w$]+)$/.exec(segment);
+    const siblingKey = String(index);
+    const siblings = state.staticChildrenBySegment?.[siblingKey] ??
+      (index === pattern.length - 1 ? state.staticChildren : undefined);
+    // A dynamic trie node is usable only after the server has said its static
+    // siblings are complete. This is the production-only null-vs-empty rule.
+    if ((dynamic || catchAll) && siblings === undefined) return undefined;
+    if (siblings?.includes(target[cursor] ?? '')) return undefined;
+    if (catchAll) {
+      const name = catchAll[1]!;
+      if (state.catchAllOptional) {
+        // `[[...slug]]`: matches the base path plus any nested tail.
+        const rest = target.slice(cursor);
+        if (rest.length > 0) params[name] = rest;
+        return params;
+      }
+      // `[...slug]`: a catch-all learned from a parallel slot must not predict a
+      // sibling URL for the primary route. Only reuse it when the source shell
+      // itself was rendered through that catch-all, and require ≥1 segment.
+      if (!Array.isArray(state.params[name])) return undefined;
+      const rest = target.slice(cursor);
+      if (rest.length === 0) return undefined;
+      params[name] = rest;
+      return params;
+    }
+    const value = target[cursor++];
+    if (value === undefined) return undefined;
+    if (dynamic) params[dynamic[1]!] = value;
+    else if (segment !== value) return undefined;
+  }
+  return cursor === target.length ? params : undefined;
+}
+
+function reifyShellParams(
+  html: string,
+  previous: Record<string, RouteParamValue>,
+  params: Record<string, RouteParamValue>,
+): string {
+  if (typeof DOMParser === 'undefined') return html;
+  const doc = new DOMParser().parseFromString(html, 'text/html');
+  materializeClientMarkers(doc);
+  for (const root of doc.querySelectorAll<HTMLElement>('[data-pnext-params]')) {
+    const raw = root.getAttribute('data-pnext-params');
+    if (!raw) continue;
+    try {
+      const scoped = JSON.parse(raw) as Record<string, RouteParamValue>;
+      if (sameParams(scoped, previous)) root.setAttribute('data-pnext-params', JSON.stringify(params));
+    } catch {
+      // A malformed island scope cannot safely be reified.
+    }
+  }
+  return `<!doctype html>${doc.documentElement.outerHTML}`;
+}
+
+function materializeClientMarkers(doc: Document): void {
+  const comments: Comment[] = [];
+  const walker = doc.createTreeWalker(doc, NodeFilter.SHOW_COMMENT);
+  while (walker.nextNode()) comments.push(walker.currentNode as Comment);
+  for (const start of comments.reverse()) {
+    const match = /^(pnext-client|pnext-page):([^>]*)$/.exec(start.data);
+    const kind = match?.[1];
+    const encoded = match?.[2];
+    if (!kind || !encoded || !start.parentNode) continue;
+    const container = doc.createElement('div');
+    const tag = kind === 'pnext-page' ? 'div' : 'pnext-client';
+    container.innerHTML = `<${tag} ${encoded}></${tag}>`;
+    const island = container.firstElementChild;
+    if (!island) continue;
+    let node = start.nextSibling;
+    while (node && !(node.nodeType === Node.COMMENT_NODE && node.nodeValue === `/${kind}`)) {
+      const next = node.nextSibling;
+      island.append(node);
+      node = next;
+    }
+    if (!node) continue;
+    start.replaceWith(island);
+    node.remove();
+  }
+}
+
+function sameParams(
+  left: Record<string, RouteParamValue>,
+  right: Record<string, RouteParamValue>,
+): boolean {
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every(key => {
+    const a = left[key];
+    const b = right[key];
+    return Array.isArray(a)
+      ? Array.isArray(b) && a.length === b.length && a.every((value, index) => value === b[index])
+      : a === b;
+  });
+}
+
+function decodeSegment(segment: string) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}

package/src/compat/client/prefetch-cache.ts

@@ -0,0 +1,111 @@
+// Client prefetch-cache policy (COMPAT - ships to the browser).
+//
+// Core's router owns a single HTML-swap prefetch cache with a flat TTL. Next's semantics split that
+// window into a static staleTime and a dynamic staleTime, overridable through
+// `experimental.staleTimes.{static,dynamic}`, and it seeds the cache from visited pages, uses low fetch
+// priority for viewport prefetches, and skips prefetching entirely for bot user agents.
+//
+// The exact static/dynamic distinction Next draws is a property of the RSC segment payload. On the
+// HTML-swap model the router can still learn a route's staleness from the `x-nextjs-stale-time`
+// response header; when present it wins, otherwise the entry falls back to the configured dynamic
+// window. This module is the single source of the windows plus the config override, read by the core
+// router through a registered hook so core carries no next.config dependency.
+//
+// Injected into the client at build time as `window.__PNEXT_STALE_TIMES__`; undefined means Next defaults.
+
+
+/** Next's built-in prefetch staleTimes (milliseconds). */
+// Since Next 15 the DYNAMIC default is 0: dynamic data is never reused across
+// navigations unless `experimental.staleTimes.dynamic` opts in. (The loading
+// shell of a dynamic route still reuses for the STATIC window.)
+export const DEFAULT_DYNAMIC_STALE_TIME_MS = 0;
+export const DEFAULT_STATIC_STALE_TIME_MS = 300_000;
+/** Next's runtime-prefetch stale threshold (RUNTIME_PREFETCH_DYNAMIC_STALE). */
+const RUNTIME_DOCUMENT_STALE_TIME_MS = 30_000;
+
+/** Shape injected by the server (seconds, mirroring next.config). */
+interface StaleTimesConfig {
+  /** experimental.staleTimes.dynamic (seconds). */
+  dynamic?: number;
+  /** experimental.staleTimes.static (seconds). */
+  static?: number;
+}
+
+declare global {
+  interface Window {
+    __PNEXT_STALE_TIMES__?: StaleTimesConfig;
+  }
+}
+
+function configuredStaleTimes(): StaleTimesConfig {
+  if (!process.browser && typeof window === 'undefined') return {};
+  return window.__PNEXT_STALE_TIMES__ ?? {};
+}
+
+function windowFromSeconds(value: number | undefined, fallbackMs: number): number {
+  // A configured 0 means "always fresh" (never reuse) — honour it exactly.
+  return typeof value === 'number' && Number.isFinite(value) ? value * 1000 : fallbackMs;
+}
+
+/** The dynamic prefetch window in ms (config override or 30s default). */
+export function dynamicStaleTimeMs(): number {
+  return windowFromSeconds(configuredStaleTimes().dynamic, DEFAULT_DYNAMIC_STALE_TIME_MS);
+}
+
+/** The static prefetch window in ms (config override or 300s default). */
+export function staticStaleTimeMs(): number {
+  return windowFromSeconds(configuredStaleTimes().static, DEFAULT_STATIC_STALE_TIME_MS);
+}
+
+/**
+ * The reuse window for a prefetched/visited entry. `prefetchFull` marks a `prefetch={true}` full-page
+ * prefetch, which Next reuses for the FULL static window even when the route itself is dynamic - it
+ * wins over the header. A route that reported an explicit `x-nextjs-stale-time` uses that value;
+ * otherwise the entry is treated as dynamic.
+ *
+ * `static`/`runtime` classify a per-segment entry (the cached static stage a navigation paints before
+ * its dynamic stage lands). A STATIC payload reports its own staleness and that value is authoritative:
+ * widening it to the configured static window keeps painting an expired static stage. A RUNTIME payload
+ * is request-sampled data, never static content: it reuses for the window its own short-lived cache
+ * reported, or the dynamic window when the response named none - never the static one.
+ *
+ * The header value is used RAW here, not through `getStaleTimeMs`: this cache backs the classic
+ * staleTimes semantics, where a configured `staleTimes.dynamic: 0` must mean "never reuse". The clamp
+ * applies only to the per-segment cache.
+ */
+export function staleTimeForEntryMs(options: {
+  headerStaleTimeSeconds?: number;
+  prefetchFull?: boolean;
+  static?: boolean;
+  runtime?: boolean;
+  runtimeDocument?: boolean;
+}): number {
+  // A NAVIGATION document of an `allow-runtime` route: its header reports the route's PUBLIC cache
+  // window (the private/runtime caches resolve after the headers flushed), but the content is
+  // request-sampled. Next files no such entry from a navigation at all - the runtime-prefetch stream is
+  // what seeds its segment cache - so anything recorded from the document must not outlive the
+  // runtime-prefetch threshold: shorter-lived private caches are hung out of runtime samples entirely.
+  if (options.runtimeDocument) {
+    const headerMs =
+      typeof options.headerStaleTimeSeconds === 'number'
+        ? options.headerStaleTimeSeconds * 1000
+        : Number.POSITIVE_INFINITY;
+    return Math.min(headerMs, RUNTIME_DOCUMENT_STALE_TIME_MS);
+  }
+  if ((options.static || options.runtime) && typeof options.headerStaleTimeSeconds === 'number') {
+    return options.headerStaleTimeSeconds * 1000;
+  }
+  if (options.runtime) return dynamicStaleTimeMs();
+  if (options.prefetchFull) {
+    return Math.max(
+      staticStaleTimeMs(),
+      typeof options.headerStaleTimeSeconds === 'number'
+        ? options.headerStaleTimeSeconds * 1000
+        : 0,
+    );
+  }
+  if (typeof options.headerStaleTimeSeconds === 'number') {
+    return options.headerStaleTimeSeconds * 1000;
+  }
+  return dynamicStaleTimeMs();
+}