@wular/coder 0.4.2 → 0.4.4

package/dist/dash/standalone/node_modules/@wular/pnext/src/client/router/hub.ts

@@ -0,0 +1,201 @@
+// FIRST-PAINT TIER. Every byte here is in every route entry's static graph, so this module holds
+// only what a click must decide before the navigation runtime lands (link eligibility, soft-URL
+// resolution) and the mutable state both tiers share. The runtime lives behind ./runtime (idle
+// chunk), and because both tiers import THIS module, a seam registered during first paint is already
+// in place when the runtime reads it - nothing is replayed.
+//
+// A symbol only the runtime touches must live in a SEPARATE module even though it would tree-shake
+// out of an entry: this module is a chunk SHARED with the runtime chunk, so anything the runtime
+// imports from here is kept in the first-paint chunk regardless. ./policies, ./history, ./events and
+// the bfcache route key all ride the idle chunk for that reason.
+import type { EntryModule } from './types'
+
+// Router-wide mutable state SHARED BY BOTH TIERS. Every field here is committed by more than one
+// region (install, soft nav, popstate), so it lives on one record: a module-level `let` can only be
+// reassigned inside the module that declares it. State only the runtime touches stays in ./runtime.
+
+export const routerState: {
+  observedLocationKey: string
+  // The route key (pathname+search) of the currently committed navigation, used
+  // as the departing key on popstate (where `location` already points at the
+  // target). Seeded on router init and updated at each committed navigation.
+  activeRouteKey?: string
+  // The entry id whose document is currently on screen. A traversal to that
+  // same id — an app-level shallow pushState now carries the id forward — needs
+  // no fetch and no swap: the DOM already is this entry's.
+  renderedEntryId?: string
+  /** The navigation that last painted a fallback, and when. */
+  fallbackPaint?: [sequence: number, at: number]
+  /** Ends the clicked link's pending state; set once the runtime installs. */
+  settleLink?: () => void
+} = {
+  // pathname+search of the URL the router last observed. A popstate that leaves both unchanged is a
+  // same-document FRAGMENT traversal - Chrome fires popstate, not just hashchange, for those - and
+  // treating one as a history traversal would refetch and swap the body, remounting the live tree
+  // under the user's feet.
+  observedLocationKey: locationKey(),
+}
+
+export function locationKey() {
+  return process.browser || typeof location !== 'undefined'
+    ? location.pathname + location.search
+    : ''
+}
+
+// Installers that only the navigation runtime ever observes — compat's policy
+// seams (segment cache, prefetch windows, scroll, stylesheet order). Registering
+// one costs first paint a closure holding an `import()`; the facade runs them
+// while the runtime chunk loads, so a policy is in place before the first fetch.
+const deferredInstalls: (() => unknown)[] = []
+
+export function registerDeferredInstall(install: () => unknown): void {
+  deferredInstalls.push(install)
+}
+
+export function takeDeferredInstalls(): (() => unknown)[] {
+  return deferredInstalls.splice(0)
+}
+
+// Compat-registered policy seams FIRST PAINT ITSELF READS. The rest (prefetch
+// windows, loading shells, segment cache, export documents) never runs before a
+// navigation, so they live in ./policies and ride the runtime chunk.
+
+// `javascript:` URLs are a navigation-time XSS vector; the router refuses them
+// at every entry point. The generic block lives in core; the user-facing
+// message is framework-specific, so compat supplies a reporter/thrower.
+export let blockedJsUrlReporter: ((url: string) => void) | undefined
+
+export function setBlockedJavascriptUrlReporter(reporter: (url: string) => void) {
+  blockedJsUrlReporter = reporter
+}
+
+// basePath boundary: under a configured basePath a same-origin URL OUTSIDE the
+// basePath (a `basePath:false` target) must hard-navigate, not soft-swap. The
+// check is a next.config concern, so compat registers it; pure core returns
+// false (every same-origin URL stays soft-navigable).
+export let softNavBoundary: ((url: URL) => boolean) | undefined
+
+/** Register the compat soft-nav boundary predicate (true → hard navigate). */
+export function setSoftNavBoundary(predicate: (url: URL) => boolean) {
+  softNavBoundary = predicate
+}
+
+export function isJavascriptUrl(href: string) {
+  // eslint-disable-next-line no-control-regex
+  return /^[\u0000-\u0020]*javascript:/i.test(href)
+}
+
+/** True when the URL was a blocked javascript: URL (caller must not navigate). */
+export function blockJavascriptUrl(href: string): boolean {
+  if (!isJavascriptUrl(href)) return false
+  if (blockedJsUrlReporter) blockedJsUrlReporter(href)
+  else if (process.browser || typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent('pnext:blocked-javascript-url', { detail: href }))
+  }
+  return true
+}
+
+// Whether a href is soft-navigable at all — the one navigation decision the
+// first-paint hub has to make synchronously, before the router chunk lands.
+
+export function resolveSoftUrl(href: string) {
+  let url: URL
+  try {
+    url = new URL(href, location.href)
+  } catch {
+    return null
+  }
+  if (url.origin !== location.origin) return null
+  // Under a configured basePath, a same-origin URL that falls OUTSIDE the
+  // basePath (a `basePath:false` target) is not part of the app — it must be a
+  // real browser navigation, not a soft swap. Pure core / no-basePath: never
+  // outside (predicate returns false), so behavior is unchanged.
+  if (softNavBoundary?.(url)) return null
+  return url
+}
+
+// The synchronous half of link interception: everything a click's default
+// action must be decided on before the router chunk can be awaited (modifier
+// keys, target/download, javascript: block, same-origin resolution). The hub
+// runs this at first paint and queues the result; the installed router runs it
+// and commits immediately.
+
+export interface LinkClickTarget {
+  link: HTMLAnchorElement
+  url: URL
+  replace: boolean
+  scroll: boolean
+}
+
+export function linkFromEvent(event: Event) {
+  const target = event.target
+  if (!(target instanceof Element)) return null
+  return target.closest<HTMLAnchorElement>('a[data-pnext-link]')
+}
+
+/**
+ * The navigation a click asks for, or null when the browser should keep the
+ * click. Preventing the default action is the caller's job EXCEPT for the two
+ * cases resolved entirely here: a blocked `javascript:` URL and a `replace`
+ * link pointing outside the app (both return null having acted).
+ */
+export function linkClickTarget(event: MouseEvent): LinkClickTarget | null {
+  if (event.defaultPrevented) return null
+  if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+    return null
+  const link = linkFromEvent(event)
+  if (!link) return null
+  if (link.target && link.target !== '_self') return null
+  if (link.hasAttribute('download')) return null
+  const href = link.getAttribute('data-pnext-blocked-href') ?? link.getAttribute('href')
+  if (!href) return null
+  // Refuse javascript: URLs before the browser can run them (the anchor's
+  // default action is cancellable from this bubble-phase listener).
+  if (blockJavascriptUrl(href)) {
+    event.preventDefault()
+    return null
+  }
+  const replace = link.getAttribute('data-pnext-replace') === 'true'
+  const url = resolveSoftUrl(href)
+  if (!url) {
+    if (replace) {
+      event.preventDefault()
+      window.location.replace(href)
+    }
+    return null
+  }
+  return { link, url, replace, scroll: link.getAttribute('data-pnext-scroll') !== 'false' }
+}
+
+// Route entry modules: the cache of imported entries plus the guard that keeps
+// a router-triggered import from auto-mounting into the live document.
+
+export const entryModuleCache = new Map<string, EntryModule>()
+
+// The document's own entry module registers itself at boot. Without this, the first history
+// traversal back to the hard-loaded route pays a real import() - one task yield - and a test reading
+// the DOM right after history.back() catches the DEPARTING page. With every step of the cached-entry
+// restore microtask-only, the commit lands before any post-traversal task can read.
+if (process.browser || typeof window !== 'undefined') {
+  ;(
+    window as unknown as {
+      __PNEXT_REGISTER_ENTRY__?: (src: string, module: EntryModule) => void
+    }
+  ).__PNEXT_REGISTER_ENTRY__ = (src, module) => {
+    const href = entryModuleHref(src)
+    if (!entryModuleCache.has(href)) entryModuleCache.set(href, module)
+  }
+}
+
+// Entries auto-mount when the browser loads them as the document's module
+// script. When this router imports an entry (prefetch warmup or navigation)
+// the DOM they'd mount into is not this document's, so they must not. The
+// counter is only ever non-zero while a router-triggered import is in flight,
+// and hard document loads can never overlap one.
+export function routerImportActive() {
+  return (window.__PNEXT_ROUTER_IMPORTS__ ?? 0) > 0
+}
+
+export function entryModuleHref(src: string) {
+  return new URL(src, location.href).href
+}

package/dist/dash/standalone/node_modules/@wular/pnext/src/client/router/index.ts

@@ -0,0 +1,168 @@
+// First-paint router hub. Generated client entries import this module, so every byte it statically
+// reaches is on the critical path of every route: keep it to link interception, history events and
+// the seams compat registers into, all of which live in ./hub. The navigation runtime itself
+// sits behind ./runtime and is import()ed on idle into its own chunk.
+//
+// Everything routed through this file is a facade over that chunk. That is the point: a static
+// import of softNavigate anywhere in core or compat would otherwise pull the whole runtime back into
+// first paint. State BOTH tiers touch lives in ./hub and is imported by both, so a setter
+// called before the chunk lands is not replayed - it is already in place when the runtime reads it.
+// Chunk membership is decided per module, so each seam is its own module.
+import {
+  linkClickTarget,
+  locationKey,
+  resolveSoftUrl,
+  routerState,
+  takeDeferredInstalls,
+} from './hub'
+import type { LinkClickTarget } from './hub'
+import type { PrefetchOptions, SoftNavigateOptions } from './types'
+
+export {
+  blockJavascriptUrl,
+  isJavascriptUrl,
+  registerDeferredInstall,
+  routerImportActive,
+  setBlockedJavascriptUrlReporter,
+  setSoftNavBoundary,
+} from './hub'
+// NOTE: ./policies, ./history and ./events are deliberately NOT re-exported
+// here. esbuild assigns a chunk per set-of-reaching-entries, computed on the module graph, so a
+// re-export edge from this file lands any of them in the first-paint chunk even though every symbol
+// tree-shakes away. Their consumers import them directly.
+export type {
+  LoadingShellPrediction,
+  NavigationScrollAction,
+  NavigationScrollOptions,
+  PrefetchedPage,
+  SegmentCacheHit,
+  SegmentCacheLookup,
+  SegmentCachePolicy,
+  SegmentCacheRecord,
+  StylesheetReconciler,
+} from './types'
+
+type RouterRuntime = typeof import('./runtime')
+
+let runtime: Promise<RouterRuntime> | undefined
+
+/**
+ * Load (once) and run against the idle tier. Every facade export chains off
+ * this single promise, so calls keep their relative order even when the first
+ * of them arrives before the chunk does.
+ */
+function withRouter<T>(use: (module: RouterRuntime) => T): Promise<Awaited<T>> {
+  // Deferred installers land with the runtime chunk, before anything reads a
+  // policy. Drained inside the chain (not at call time) so an installer any
+  // entry registers after the first facade call still runs.
+  runtime ??= import('./runtime').then(async module => {
+    await Promise.all(takeDeferredInstalls().map(install => install()))
+    return module
+  })
+  return runtime.then(use) as Promise<Awaited<T>>
+}
+
+export function softNavigate(href: string, options?: SoftNavigateOptions) {
+  return withRouter(module => module.softNavigate(href, options))
+}
+
+export function prefetchRoute(href: string, options?: PrefetchOptions) {
+  // Resolved here, not behind the import: `strict` (router.prefetch) reports an unusable href by
+  // THROWING at the call site, and a URL this router cannot soft-navigate is a miss that never needs
+  // the runtime. The throw is spelled out here rather than in the hub because the hub is a chunk
+  // shared with the runtime. Only an unparseable href throws - a cross-origin or out-of-basePath one
+  // is a silent miss.
+  const url = resolveSoftUrl(href)
+  if (!url) {
+    if (options?.strict) {
+      try {
+        new URL(href, location.href)
+      } catch {
+        throw new Error(`Cannot prefetch '${href}' because it cannot be converted to a URL.`)
+      }
+    }
+    return Promise.resolve(null)
+  }
+  return withRouter(module => module.prefetchRoute(url.href, options))
+}
+
+export function evictClientRouterCache(options?: { rearmVisiblePrefetches?: boolean }) {
+  return withRouter(module => module.evictClientRouterCache(options))
+}
+
+export function rearmVisiblePrefetches() {
+  return withRouter(module => module.rearmVisiblePrefetches())
+}
+
+// A click intercepted before the runtime lands waits for it. The wait is
+// bounded: a chunk that never arrives (offline, a failed deploy) must still
+// navigate, so the queued click falls back to a real browser navigation rather
+// than leaving the user on a dead link.
+const QUEUED_CLICK_TIMEOUT_MS = 3_000
+
+let pendingClicks: LinkClickTarget[] = []
+let pendingPop = false
+let installedFull = false
+let hardNavTimer: ReturnType<typeof setTimeout> | undefined
+
+function hubLinkClick(event: MouseEvent) {
+  const target = linkClickTarget(event)
+  if (!target) return
+  event.preventDefault()
+  pendingClicks.push(target)
+  hardNavTimer ??= setTimeout(() => {
+    const queued = pendingClicks[0]
+    if (queued) location.href = queued.url.href
+  }, QUEUED_CLICK_TIMEOUT_MS)
+  void loadRuntime()
+}
+
+// The browser has already committed the traversal (URL and history state are
+// the target's). Record it and let the installed handler run it as an ordinary
+// popstate; broadcasting here would move `observedLocationKey` and make that
+// handler read the traversal as a shallow one that needs no document.
+function hubPopState() {
+  pendingPop = true
+  void loadRuntime()
+}
+
+function loadRuntime() {
+  return withRouter(module => {
+    if (!installedFull) {
+      installedFull = true
+      document.removeEventListener('click', hubLinkClick)
+      window.removeEventListener('popstate', hubPopState)
+      module.installRouterFull()
+    }
+    clearTimeout(hardNavTimer)
+    hardNavTimer = undefined
+    const clicks = pendingClicks
+    pendingClicks = []
+    for (const click of clicks) module.commitLinkNavigation(click)
+    if (pendingPop) {
+      pendingPop = false
+      module.onPopState()
+    }
+  })
+}
+
+function whenIdle(run: () => void) {
+  if (typeof requestIdleCallback === 'function') requestIdleCallback(() => run(), { timeout: 1000 })
+  else setTimeout(run, 1)
+}
+
+export function installRouter() {
+  if ((!process.browser && typeof window === 'undefined') || window.__PNEXT_ROUTER_INSTALLED__)
+    return
+  window.__PNEXT_ROUTER_INSTALLED__ = true
+  if ('scrollRestoration' in history) history.scrollRestoration = 'manual'
+  // Seed the bfcache departing key with the hard-loaded route so the first
+  // navigation away stashes this route's island state under the right key.
+  // `locationKey()` IS `bfRouteKey(location.pathname, location.search)` — the
+  // hub's own definition — and it is already on the first-paint graph.
+  routerState.activeRouteKey = locationKey()
+
+  document.addEventListener('click', hubLinkClick)
+  window.addEventListener('popstate', hubPopState)
+  whenIdle(() => void loadRuntime())
+}

package/dist/dash/standalone/node_modules/@wular/pnext/src/client/router/page-slot.ts

@@ -0,0 +1,139 @@
+type PageSlotRange = [start: Element | Comment, end: Comment | undefined, nodes: ChildNode[]]
+
+/** Resolve either wire form of a page slot inside a preserved server segment. */
+export function pageSlotRange(segment: Element): PageSlotRange | null {
+  const element = segment.querySelector('#pnext-page')
+  if (element) return [element, undefined, [...element.childNodes]]
+  const walker = document.createTreeWalker(segment, 128 /* NodeFilter.SHOW_COMMENT */)
+  while (walker.nextNode()) {
+    const start = walker.currentNode as Comment
+    if (!start.data.startsWith('pnext-page:')) continue
+    const nodes: ChildNode[] = []
+    let end = start.nextSibling
+    while (end && !(end.nodeType === 8 && end.nodeValue === '/pnext-page')) {
+      nodes.push(end)
+      end = end.nextSibling
+    }
+    return end ? [start, end as Comment, nodes] : null
+  }
+  return null
+}
+
+/** Whether an element belongs to the page slot in either DOM form. */
+export function elementInPageSlot(element: Element): boolean {
+  return !!(
+    element.closest('#pnext-page') ||
+    pageSlotRange(document.body)?.[2].some(node => node.contains(element))
+  )
+}
+
+const SEGMENT = 'pnext-layout[data-pnext-segment]'
+
+/** A server layout's identity and the URL prefix it rendered for. */
+export function segmentKey(segment: Element): string {
+  return `${segment.getAttribute('data-pnext-segment')}\u0001${segment.getAttribute('data-pnext-scope')}`
+}
+
+/** The server layout directly below `segment`, outside parallel-route slots. */
+export function childSegment(segment: Element): Element | null {
+  for (const child of segment.querySelectorAll(SEGMENT))
+    if (!segment.contains(child.closest('[data-pnext-slot]'))) return child
+  return null
+}
+
+/**
+ * The live layout below the deepest layout `boundary` shares with `slot` (null when that layout
+ * holds `slot`), and the incoming node that replaces it: the boundary, or the new layout holding
+ * it. Null when either sits in an island.
+ */
+export function divergingLayout(slot: Node, boundary: Element): [Element | null, Element] | null {
+  let paint = boundary
+  let owner = boundary.closest(SEGMENT)
+  let below: Element | null
+  for (;;) {
+    const key = owner && segmentKey(owner)
+    below = null
+    let layout = slot.parentElement?.closest(SEGMENT)
+    for (; layout && segmentKey(layout) !== key; layout = layout.parentElement?.closest(SEGMENT))
+      below = layout
+    if (layout || !owner) break
+    paint = owner
+    owner = owner.parentElement!.closest(SEGMENT)
+  }
+  return !boundary.closest('pnext-client') &&
+    !(below ?? slot).parentElement?.closest('pnext-client')
+    ? [below, paint]
+    : null
+}
+
+function childNodes(segment: Element): ChildNode[] | null {
+  const child = childSegment(segment)
+  if (child) return [child]
+  const range = pageSlotRange(segment)
+  return range && (range[1] ? [range[0], ...range[2], range[1]] : [range[0]])
+}
+
+/** Replace a kept layout's children (its child layout or page slot) with the incoming ones. */
+export function graftSegmentChildren(liveSegment: Element, incomingSegment: Element): boolean {
+  if (!childSegment(liveSegment) && !childSegment(incomingSegment))
+    return graftPageSlot(liveSegment, incomingSegment)
+  const live = childNodes(liveSegment)
+  const incoming = childNodes(incomingSegment)
+  if (!live || !incoming) return false
+  live[0]!.before(...incoming)
+  for (const stale of live) stale.remove()
+  return true
+}
+
+/**
+ * Graft a destination page into a preserved layout without changing the destination's mount shape.
+ * Client pages need the real `#pnext-page` element; server/island-only pages need the marker range.
+ */
+export function graftPageSlot(liveSegment: Element, incomingSegment: Element): boolean {
+  const live = pageSlotRange(liveSegment)
+  const incoming = pageSlotRange(incomingSegment)
+  if (!live || !incoming) return false
+  const nodes = reusePageNodes(live[2], incoming[2])
+  for (const stale of live[2]) stale.remove()
+  const end = incoming[1]
+  if (!end) (incoming[0] as Element).replaceChildren(...nodes)
+  else {
+    for (const stale of incoming[2]) stale.remove()
+  }
+  live[0].replaceWith(incoming[0])
+  if (end) incoming[0].after(...nodes, end)
+  live[1]?.remove()
+  return true
+}
+
+// Next re-renders a page in place, so unchanged DOM keeps its node identity.
+function reusePageNodes(live: readonly ChildNode[], incoming: readonly Node[]): Node[] {
+  const candidates = live.filter(
+    (node): node is Element =>
+      node instanceof Element &&
+      !node.matches('script, pnext-client, #pnext-page') &&
+      !node.querySelector('pnext-client, #pnext-page, [data-pnext-preserve]'),
+  )
+  return incoming.map(node => {
+    if (!(node instanceof Element)) return node
+    const index = candidates.findIndex(candidate => candidate.outerHTML === node.outerHTML)
+    return index === -1 ? node : candidates.splice(index, 1)[0]!
+  })
+}
+
+export interface LoadingShellTarget {
+  container: HTMLElement
+  markerRange?: PageSlotRange
+}
+
+/** Resolve a safe loading-shell target without falling through a dissolved page to the body. */
+export function loadingShellTarget(): LoadingShellTarget {
+  const page = document.getElementById('pnext-page')
+  if (page) return { container: page }
+  const markerRange = pageSlotRange(document.body)
+  if (markerRange?.[1]) {
+    return { container: markerRange[0].parentElement!, markerRange }
+  }
+  const root = document.querySelector<HTMLElement>('[data-pnext-root]')
+  return { container: root ?? document.body }
+}

package/dist/dash/standalone/node_modules/@wular/pnext/src/client/router/policies.ts

@@ -0,0 +1,107 @@
+// IDLE-TIER POLICY SEAMS. Compat registers Next-shaped policies for prefetch windows, loading
+// shells, stylesheet order, the segment cache and export-mode documents; core keeps a flat-TTL
+// default for each. Every one is WRITTEN by compat's deferred installer and READ only inside
+// ./runtime, so this module belongs to neither entry's static graph - it rides the runtime chunk.
+// Seams first paint itself reads stay in ./hub.
+import type {
+  LoadingShellPredictionPolicy,
+  SegmentCachePolicy,
+  StylesheetReconciler,
+} from './types'
+
+// Fallback reuse window when compat did not register a staleTime policy (pure
+// core has no static/dynamic split).
+export const PREFETCH_TTL_MS = 300_000
+
+// The static/dynamic staleTime split + experimental.staleTimes override are Next
+// semantics; the policy lives in compat (compat/client/prefetch-cache) and is
+// registered here so core keeps its flat-TTL default when no compat is present.
+export interface PrefetchStaleContext {
+  /** Value of `x-nextjs-stale-time` on the prefetch response (seconds), if any. */
+  headerStaleTimeSeconds?: number
+  /** True for a full-page (prefetch={true}) prefetch — uses the static window. */
+  prefetchFull?: boolean
+  /**
+   * The payload is STATIC (a prerender: bytes are a pure function of the URL). Such a route reports
+   * its own staleness, which is authoritative - it must not be widened to the configured static
+   * window, or a cached static stage outlives the data it was built from.
+   */
+  static?: boolean
+  /**
+   * The payload came from a RUNTIME (request-sampled) prefetch: cookies/headers
+   * holes filled at prefetch time. Never static content, so it reuses for the
+   * dynamic window at most.
+   */
+  runtime?: boolean
+  /**
+   * A NAVIGATION document of an `allow-runtime` route. Its stale-time header
+   * reports the route's public cache window; the request-sampled content it
+   * carries is only good for the runtime-prefetch threshold (compat caps it).
+   */
+  runtimeDocument?: boolean
+}
+export let prefetchStaleTimePolicy: ((ctx: PrefetchStaleContext) => number) | undefined
+
+/** Register the compat prefetch-staleTime policy (ms). */
+export function setPrefetchStaleTimePolicy(policy: (ctx: PrefetchStaleContext) => number) {
+  prefetchStaleTimePolicy = policy
+}
+
+export function prefetchStaleTimeMs(ctx: PrefetchStaleContext): number {
+  return prefetchStaleTimePolicy?.(ctx) ?? PREFETCH_TTL_MS
+}
+
+// The loading-shell reuse window (Next's STATIC staleTime: the cached loading
+// boundary of a route outlives its dynamic data). Compat registers the
+// configured static window; core falls back to the flat TTL.
+export let shellStaleTimePolicy: (() => number) | undefined
+export let loadingShellPredictionPolicy: LoadingShellPredictionPolicy | undefined
+export let stylesheetReconciler: StylesheetReconciler | undefined
+export let revalidationPrefetchDelayMs = 0
+
+/** Register the compat loading-shell staleTime (ms) — Next's static window. */
+export function setShellStaleTimePolicy(policy: () => number) {
+  shellStaleTimePolicy = policy
+}
+
+/** Register framework-specific matching for cached loading shells. */
+export function setLoadingShellPredictionPolicy(policy: LoadingShellPredictionPolicy) {
+  loadingShellPredictionPolicy = policy
+}
+
+/** Register framework-specific stylesheet ordering after a document swap. */
+export function setStylesheetReconciler(reconciler: StylesheetReconciler | undefined) {
+  stylesheetReconciler = reconciler
+}
+
+/** Register a framework-specific delay before invalidated prefetches retry. */
+export function setRevalidationPrefetchDelay(delayMs: number) {
+  revalidationPrefetchDelayMs = Math.max(0, delayMs)
+}
+
+export function shellStaleTimeMs(): number {
+  return shellStaleTimePolicy?.() ?? PREFETCH_TTL_MS
+}
+
+// Export-mode document source. An exported build has no server to negotiate with, so its documents
+// come from flat artifacts written beside each page. Registered by compat, and ONLY when the running
+// document came out of an export; once registered it replaces the server protocol wholesale, so a
+// null result is a miss, not a fallback.
+type ExportDocumentFetcher = (
+  href: string,
+  init: RequestInit,
+  prefetch: boolean,
+) => Promise<{ html: string; finalUrl: string } | null>
+export let exportDocumentFetcher: ExportDocumentFetcher | undefined
+
+/** Register the compat `output: 'export'` document fetcher. */
+export function setExportDocumentFetcher(fetcher: ExportDocumentFetcher) {
+  exportDocumentFetcher = fetcher
+}
+
+// Next's segment cache (compat/client/segment-cache).
+export let segmentCachePolicy: SegmentCachePolicy | undefined
+
+export function setSegmentCachePolicy(policy: SegmentCachePolicy): void {
+  segmentCachePolicy = policy
+}