@barefootjs/router 0.14.0

package/dist/region.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Read a fetched page and lift out the swappable region subtree(s).
+ *
+ * The router fetches an ordinary full-page HTML response (no protocol header),
+ * parses it client-side, and matches its `[bf-region]` boundaries against the
+ * live document. v0 swaps a single broad region; v2 matches compiler-derived
+ * nested/sibling regions by their stable `bf-region` id and swaps only the
+ * deepest ones whose *owned* content differs (spec/router.md "Regions"). Island
+ * module scripts (`<script type=module src>`) sit at body-end, outside any
+ * region, so they are collected from the whole parsed document.
+ */
+import type { RouterState } from './types.ts';
+/** Parse a fetched page's HTML into a detached document. */
+export declare function parseDocument(html: string): Document;
+/**
+ * Same-origin absolute URLs of `<script type=module src>` in a tree, resolved
+ * against `baseUrl`. For a fetched page that is the response's **final URL**
+ * (not `location`), so a relative module `src` in the incoming document loads
+ * from the right place (spec/router.md lifecycle step 4).
+ */
+export declare function collectModuleScripts(root: ParentNode, baseUrl: string): Set<string>;
+/** A swap target: a live region element and its counterpart in the incoming doc. */
+export interface RegionSwap {
+    current: Element;
+    incoming: Element;
+}
+export type SwapPlan = 
+/**
+ * Matched compiler-derived regions: swap exactly `targets` (may be empty when
+ * nothing changed). `incomingKeys` is the owned-content key per matched region
+ * id from the **incoming server render** — the caller commits it as the new
+ * per-region baseline (see {@link planRegionSwaps}).
+ */
+{
+    mode: 'regions';
+    targets: RegionSwap[];
+    incomingKeys: Map<string, string>;
+}
+/** Region ids don't line up (or collide): fall back to the single broadest-region swap (v0). */
+ | {
+    mode: 'broadest';
+};
+/**
+ * A region's **owned** content: its inner HTML with every *nested* `[bf-region]`
+ * subtree masked out (replaced by an id-keyed placeholder), and with per-render
+ * **volatile hydration scaffolding** normalized away. Two regions compare equal
+ * when only their nested regions' interiors differ — so an outer region stays
+ * mounted when just an inner region changed (the deepest differing region is the
+ * one that swaps).
+ *
+ * The normalization matters: a top-level island's scope id is randomized per
+ * server render (`<div bf-s="Counter_a1b2c3">`), so two renders of the *same*
+ * region are never byte-identical. Comparing raw `innerHTML` would flag every
+ * region containing an island as "changed" and swap away its state — the
+ * opposite of v2's goal. The diff therefore compares *content*, ignoring the
+ * scope-id-carrying markers (`bf-s`, `bf-h`, and the id inside `bf-scope:`
+ * comments); the structural markers (`bf` slot refs, `bf-m` slot ids, `bf-r`)
+ * and any props stay, so a real content/prop change is still detected.
+ */
+export declare function ownedContentKey(region: Element, selector: string): string;
+/**
+ * Decide which regions to swap between the live document and a parsed incoming
+ * document. When both expose the **same set** of region ids, swap the *topmost*
+ * regions whose owned content differs (an ancestor swap rebuilds its nested
+ * regions, so a nested candidate inside another candidate is dropped). When the
+ * id sets differ or collide, fall back to the broadest single-region swap.
+ *
+ * The "differs" test compares the incoming region's **server-rendered** owned
+ * content against `baselines` — the owned-content key captured from the server
+ * render currently displayed in that region — **not** the live DOM. A live
+ * region's DOM may have been mutated by its islands (signal-driven updates), so
+ * comparing against it would flag an unchanged region as changed and swap away
+ * its state — the opposite of v2's goal. The caller seeds `baselines` from the
+ * initial document and refreshes it from `incomingKeys` after each navigation.
+ * A region missing from `baselines` falls back to its live owned content.
+ */
+export declare function planRegionSwaps(currentRoot: ParentNode, incomingRoot: ParentNode, selector: string, baselines: ReadonlyMap<string, string>): SwapPlan;
+/**
+ * Capture the owned-content key of every `[bf-region]` in `root`, keyed by id —
+ * the per-region server-render baseline the swap planner compares against.
+ */
+export declare function captureRegionBaselines(root: ParentNode, selector: string): Map<string, string>;
+/**
+ * True when `region` contains every other `[bf-region]` in its document — i.e.
+ * it is a single root whose swap rebuilds them all. Used by the broadest
+ * fallback: a root may be swapped wholesale (the v0 behaviour), but if the
+ * regions are siblings a single swap would only half-update the page, so the
+ * caller hard-navigates instead.
+ */
+export declare function isRootRegion(region: Element, selector: string): boolean;
+/**
+ * Adopt an incoming region's child nodes into the live document so they're ready
+ * to insert (the parsed nodes belong to a detached document).
+ */
+export declare function importRegionChildren(incoming: Element): Node[];
+/**
+ * Prefetch-path read: parse once, confirm the page belongs to this shell, and
+ * return only its island module srcs (resolved against `baseUrl`). It does
+ * **not** clone/import any region subtree — prefetch only needs the module list,
+ * and importing a large region is wasted work. Returns `null` when the page has
+ * no region.
+ */
+export declare function collectRegionModuleSrcs(html: string, selector: string, baseUrl: string): string[] | null;
+export declare function loadNewModules(state: RouterState, srcs: string[]): Promise<void>;
+//# sourceMappingURL=region.d.ts.map

package/dist/region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.d.ts","sourceRoot":"","sources":["../src/region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAEpD;AAGD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAcnF;AAED,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,MAAM,QAAQ;AAClB;;;;;GAKG;AACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE;AAC/E,gGAAgG;GAC9F;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAiBxB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAazE;AAuED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,UAAU,EACvB,YAAY,EAAE,UAAU,EACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,QAAQ,CAoBV;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM9F;AAQD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,EAAE,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,EAAE,GAAG,IAAI,CAIjB;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBtF"}

package/dist/router.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The router controller: event interception, programmatic navigation, prefetch.
+ *
+ * One router is active at a time (`active`). `startRouter` installs all the
+ * seams itself (correct by default — no opt-in step), delegates events on
+ * `document`/`window`, and returns a `Router` handle. A navigation swaps only
+ * the `[bf-region]` children, disposing the outgoing islands and re-hydrating
+ * the incoming ones, with last-wins semantics across overlapping navigations.
+ */
+import type { NavigateOptions, Router, RouterOptions } from './types.ts';
+export declare function startRouter(options?: RouterOptions): Router;
+export declare function navigate(url: string, options?: NavigateOptions): Promise<void>;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,OAAO,KAAK,EACV,eAAe,EAEf,MAAM,EACN,aAAa,EAEd,MAAM,YAAY,CAAA;AAInB,wBAAgB,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAkE/D;AA4FD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6JxF"}

package/dist/seams.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Window bridges to the optional `@barefootjs/client` runtime.
+ *
+ * The router core never statically imports `@barefootjs/client` — that keeps it
+ * an *optional* peer, so a static-shell site ships the router with zero client
+ * runtime. Every coupling lives here, and every coupling is correct by default:
+ * `dispose`/`rehydrate` degrade through the SAME fallback chain ending at
+ * `@barefootjs/client/runtime`, and neither silently no-ops on a page that has
+ * islands (spec/router.md "Seams & correctness" — the #1910 `setupStreaming()`
+ * footgun, where islands leaked unless the dev opted in, is what this avoids).
+ */
+/**
+ * Push the committed query string into the env signal, if a `searchParams()`
+ * consumer has registered the seam. Returns whether the seam exists — the
+ * caller uses that boolean to decide query-only-vs-structural navigation.
+ */
+export declare function pushSearchSeam(search: string): boolean;
+export declare function defaultRehydrate(region: Element): Promise<void>;
+export declare function defaultDispose(region: Element): Promise<void>;
+/**
+ * Does the region contain BarefootJS hydration markers (`bf-s` scope roots or
+ * `bf-h` child-scope hosts)? If so, the client runtime *should* be on the page,
+ * and failing to reach it is an error worth surfacing — not the silent
+ * "static shell" path.
+ */
+export declare function regionHasIslands(region: Element): boolean;
+/** Full browser navigation — the "never worse than an MPA" floor. */
+export declare function hardNavigate(url: string): void;
+//# sourceMappingURL=seams.d.ts.map

package/dist/seams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seams.d.ts","sourceRoot":"","sources":["../src/seams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8BH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAMtD;AAED,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BrE;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBnE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAMzD;AAUD,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C"}

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Public + internal types for the BarefootJS partial-navigation router.
+ *
+ * A **region** (`[bf-region]`, spec/router.md) is the page-lifecycle boundary
+ * the router swaps: everything outside it persists across a navigation;
+ * everything inside is disposed, re-loaded, and re-hydrated. v0 swaps a single
+ * authored region (the broadest match); compiler-derived nested regions are v2.
+ */
+export interface RouterOptions {
+    /**
+     * Selector for the swappable region. Defaults to `[bf-region]`. The first
+     * match in the document is the v0 swap point ("single authored region");
+     * if a page has none, the router hard-navigates (never worse than an MPA).
+     */
+    region?: string;
+    /**
+     * Re-hydrate the freshly swapped region. Defaults to {@link defaultRehydrate},
+     * which prefers the `@barefootjs/client` runtime's subtree-scoped walk and
+     * degrades through the shared fallback chain. Never silently no-ops on a page
+     * that has islands.
+     */
+    rehydrate?: (region: Element) => void | Promise<void>;
+    /**
+     * Dispose the outgoing islands after they are swapped out. Receives a
+     * detached holder — a shallow clone of the region element (same tag,
+     * attributes, id, classes) holding the previous region children — so tearing
+     * it down never affects the live document. When `morph` is on, any matched
+     * `[data-bf-permanent]` node was moved into the new tree first and so is
+     * absent from the holder; with `morph: false` the permanent nodes remain in
+     * the holder and are disposed normally. Defaults to {@link defaultDispose}.
+     * Pass `() => {}` to opt out (e.g. a fully static shell with no client
+     * runtime).
+     */
+    dispose?: (region: Element) => void | Promise<void>;
+    /** Import an island module by src. Defaults to `(src) => import(src)`. */
+    loadModule?: (src: string) => Promise<unknown>;
+    /**
+     * Fetch a page's HTML. Defaults to the global `fetch`. Inject to add auth
+     * headers / a custom transport, or to drive the router under test without
+     * monkeypatching the global.
+     */
+    fetch?: typeof fetch;
+    /** Decide whether to intercept an anchor click. Defaults to {@link defaultShouldIntercept}. */
+    shouldIntercept?: (anchor: HTMLAnchorElement, event: Event) => boolean;
+    /** Scroll to the top of the document after a swap. Default `true`. */
+    scrollToTop?: boolean;
+    /** Move focus to the swapped region + announce the route change. Default `true`. */
+    manageFocus?: boolean;
+    /**
+     * Preserve `[data-bf-permanent]` elements across a swap — their live DOM node
+     * (state, media playback, scroll, hydrated scope) is moved into the incoming
+     * tree instead of disposed and recreated (spec/router.md v1). Default `true`;
+     * a no-op when no permanent elements are present. Pass `false` for a plain
+     * `replaceChildren` swap.
+     */
+    morph?: boolean;
+    /** Enable hover/focus/pointerdown prefetch. Default `true`. */
+    prefetch?: boolean;
+    /** Hover dwell before prefetch (ms). Default `65`. */
+    prefetchDelay?: number;
+    /** How long a cached page stays fresh (no refetch), ms. Default `15000`. */
+    cacheFreshMs?: number;
+    /** How long a cached page may be served (stale-while-revalidate), ms. Default `60000`. */
+    cacheStaleMs?: number;
+    /** Max cached pages (LRU). Default `30`. */
+    cacheCap?: number;
+}
+export interface NavigateOptions {
+    /**
+     * How to commit history. `'push'` (default) adds an entry, `'replace'`
+     * overwrites the current one, `false` writes nothing (used by `popstate`,
+     * where the browser already moved history).
+     */
+    history?: 'push' | 'replace' | false;
+}
+export interface Router {
+    /** Tear down all listeners and abort any in-flight navigation. */
+    stop(): void;
+    /** Navigate programmatically. SSR no-op. */
+    navigate: (url: string, options?: NavigateOptions) => Promise<void>;
+    /** Warm the cache (and modulepreload islands) for a URL. */
+    prefetch: (url: string) => void;
+}
+/** A fetched page: its HTML plus the redirect-resolved final URL. */
+export interface PageSnapshot {
+    html: string;
+    finalUrl: string;
+}
+export interface CacheEntry {
+    snap: Promise<PageSnapshot | null>;
+    /** Past this (jittered) instant → serve cached AND refresh in the background. */
+    refreshAt: number;
+    /** Past this instant → too old to serve, refetch synchronously. */
+    staleAt: number;
+    /** Single-flight guard for the background refresh. */
+    refreshing: boolean;
+}
+/** Mutable state for the one active router instance. */
+export interface RouterState {
+    regionSelector: string;
+    rehydrate: (region: Element) => void | Promise<void>;
+    dispose: (region: Element) => void | Promise<void>;
+    loadModule: (src: string) => Promise<unknown>;
+    /** Fetch used for page loads (injectable; defaults to the global `fetch`). */
+    fetchFn: typeof fetch;
+    /** Absolute URLs of island modules already loaded (deduped across navigations). */
+    loadedModules: Set<string>;
+    prefetchEnabled: boolean;
+    prefetchDelay: number;
+    cacheFreshMs: number;
+    cacheStaleMs: number;
+    cacheCap: number;
+    cache: Map<string, CacheEntry>;
+    /** Module srcs already `<link rel=modulepreload>`-ed. */
+    preloaded: Set<string>;
+    shouldIntercept: (anchor: HTMLAnchorElement, event: Event) => boolean;
+    scrollToTop: boolean;
+    manageFocus: boolean;
+    /**
+     * Per-region server-render baseline: `bf-region` id → owned-content key of the
+     * server render currently displayed there. The swap planner compares an
+     * incoming region against this (not the island-mutated live DOM) so an
+     * unchanged region keeps its state; refreshed after each navigation.
+     */
+    regionBaselines: Map<string, string>;
+    morph: boolean;
+    /** Pathname of the currently-displayed region (for the query-only short-circuit). */
+    currentPath: string;
+    inflight: AbortController | null;
+    /** Hover-prefetch dwell timer + the anchor it is counting down for (per instance). */
+    hoverTimer: ReturnType<typeof setTimeout> | null;
+    hoverAnchor: HTMLAnchorElement | null;
+    stop: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@barefootjs/router",
+  "version": "0.14.0",
+  "description": "Backend-agnostic partial-navigation client router for BarefootJS — swaps only the page region and re-hydrates the islands inside it",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --format esm --external @barefootjs/shared --external @barefootjs/client",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "barefoot",
+    "router",
+    "spa",
+    "partial-navigation",
+    "islands",
+    "region"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/router"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "0.14.0"
+  },
+  "peerDependencies": {
+    "@barefootjs/client": ">=0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@barefootjs/client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@barefootjs/client": "^0.14.0",
+    "@happy-dom/global-registrator": "^20.0.11",
+    "typescript": "^5.0.0"
+  }
+}

package/src/a11y.ts

@@ -0,0 +1,66 @@
+/**
+ * Focus management and route-change announcement on swap (spec/router.md
+ * lifecycle step 7).
+ *
+ * A client swap replaces content without a browser navigation, so the browser
+ * does none of the accessibility work a real page load does: focus is left on a
+ * now-detached node and a screen reader never hears that the route changed.
+ * After a region swap the router (a) moves focus into the new region and (b)
+ * announces the route via a polite live region, mirroring what Remix/Turbo do.
+ */
+
+const LIVE_REGION_ID = 'bf-route-announcer'
+
+/**
+ * Move focus into the freshly swapped region so keyboard/AT users resume there
+ * rather than at the top of a detached tree. Prefer the region's first heading
+ * (gives a screen reader the page context); fall back to the region element
+ * itself, made programmatically focusable without becoming a tab stop.
+ */
+export function focusRegion(region: Element): void {
+  if (typeof document === 'undefined') return
+  const target =
+    (region.querySelector('h1, h2, [role="heading"]') as HTMLElement | null) ??
+    (region as HTMLElement)
+  if (!target) return
+  // `tabindex=-1` makes an otherwise non-focusable element focusable via script
+  // without inserting it into the tab order. Leave an author-set tabindex alone.
+  if (!target.hasAttribute('tabindex')) target.setAttribute('tabindex', '-1')
+  try {
+    target.focus({ preventScroll: true })
+  } catch {
+    // Older engines reject the options arg — fall back to a bare focus().
+    target.focus()
+  }
+}
+
+/**
+ * Announce the new route through a singleton `aria-live="polite"` region kept
+ * visually hidden. Setting its text after the swap lets a screen reader read
+ * the new page title without stealing focus.
+ */
+export function announceNavigation(title: string | null): void {
+  if (typeof document === 'undefined') return
+  const message = (title ?? document.title ?? '').trim()
+  if (!message) return
+  const announcer = ensureAnnouncer()
+  // Clearing first guarantees the value changes, so AT re-announces even when
+  // two consecutive routes share a title.
+  announcer.textContent = ''
+  announcer.textContent = message
+}
+
+function ensureAnnouncer(): HTMLElement {
+  const existing = document.getElementById(LIVE_REGION_ID)
+  if (existing) return existing
+  const el = document.createElement('div')
+  el.id = LIVE_REGION_ID
+  el.setAttribute('aria-live', 'polite')
+  el.setAttribute('aria-atomic', 'true')
+  el.setAttribute('role', 'status')
+  // Visually hidden but available to assistive tech (the standard sr-only clip).
+  el.style.cssText =
+    'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0'
+  document.body.appendChild(el)
+  return el
+}

package/src/cache.ts

@@ -0,0 +1,77 @@
+/**
+ * Stale-while-revalidate snapshot cache with an LRU bound.
+ *
+ * The cache stores *Promises*, so a prefetch and a near-simultaneous click for
+ * the same URL share a single in-flight request (single-flight). Three states,
+ * keyed on `now` vs the entry's `refreshAt`/`staleAt`:
+ *   - fresh  (now < refreshAt)  → serve cached, no refetch.
+ *   - aging  (refreshAt ≤ now < staleAt) → serve cached AND refresh in the
+ *     background (single-flight), so a swap is instant while the next is fresh.
+ *   - stale  (now ≥ staleAt) / miss → fetch synchronously; never serve stale.
+ */
+
+import type { PageSnapshot, RouterState } from './types.ts'
+
+const REFRESH_JITTER = 0.3 // ±30% on the per-entry refresh threshold
+
+export function fetchSnapshot(state: RouterState, url: string): Promise<PageSnapshot | null> {
+  return (async () => {
+    try {
+      const res = await state.fetchFn(url, { headers: { Accept: 'text/html' }, credentials: 'same-origin' })
+      if (!res.ok) return null
+      // Response-URL base resolution: a redirect commits at the real URL.
+      const finalUrl = res.redirected && res.url ? res.url : url
+      const html = await res.text()
+      return { html, finalUrl }
+    } catch {
+      return null
+    }
+  })()
+}
+
+function storeEntry(state: RouterState, url: string, snap: Promise<PageSnapshot | null>): void {
+  const now = Date.now()
+  const jitter = 1 + (Math.random() * 2 - 1) * REFRESH_JITTER // 0.7 … 1.3
+  state.cache.set(url, {
+    snap,
+    refreshAt: now + state.cacheFreshMs * jitter,
+    staleAt: now + state.cacheStaleMs,
+    refreshing: false,
+  })
+  // Don't cache failures: evict once the promise resolves to null.
+  void snap.then((result) => {
+    if (result === null && state.cache.get(url)?.snap === snap) state.cache.delete(url)
+  })
+  // Bound the cache (LRU: a hit re-inserts, so the first key is least-recent).
+  while (state.cache.size > state.cacheCap) {
+    const lru = state.cache.keys().next().value
+    if (lru === undefined) break
+    state.cache.delete(lru)
+  }
+}
+
+export function loadPage(state: RouterState, url: string): Promise<PageSnapshot | null> {
+  const hit = state.cache.get(url)
+  const now = Date.now()
+
+  if (hit && now < hit.staleAt) {
+    if (now >= hit.refreshAt && !hit.refreshing) {
+      // Aging → refresh in the background (single-flight), keep serving cached.
+      hit.refreshing = true
+      const fresh = fetchSnapshot(state, url)
+      void fresh.then((result) => {
+        if (result !== null) storeEntry(state, url, fresh) // swap in the fresh window
+        else if (state.cache.get(url) === hit) hit.refreshing = false // failed → keep old, retry later
+      })
+    }
+    // LRU bump: move this entry to the most-recent position.
+    state.cache.delete(url)
+    state.cache.set(url, hit)
+    return hit.snap
+  }
+
+  // Miss or past staleAt → fetch fresh (and cache it).
+  const snap = fetchSnapshot(state, url)
+  storeEntry(state, url, snap)
+  return snap
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { startRouter, navigate } from './router.ts'
+export type { RouterOptions, NavigateOptions, Router } from './types.ts'
+
+// Re-exported so server-side helpers can reference the swappable-region marker.
+export { BF_REGION } from '@barefootjs/shared'

package/src/morph.ts

@@ -0,0 +1,69 @@
+/**
+ * Permanent-node preservation during a region swap (spec/router.md **v1**,
+ * "persistence within a region": `data-bf-permanent` + idiomorph-style
+ * morphing).
+ *
+ * A plain swap (`replaceChildren`) tears the whole region down and rebuilds it,
+ * so anything with live state inside the region — a playing `<video>`, a
+ * scrolled list, an open `<details>`, an input's value — is lost across a
+ * navigation. An element marked `data-bf-permanent` is instead **preserved**:
+ * its *live* DOM node (with its state, media playback, scroll, and already-
+ * hydrated reactive scope) is moved into the incoming tree at the matching
+ * position, rather than disposed and recreated. (Focus is not preserved when
+ * the router's default `manageFocus` moves it to the region heading post-swap.)
+ *
+ * The match is keyed by the `data-bf-permanent` value (falling back to `id`),
+ * so the same logical element is recognised across the two page documents —
+ * idiomorph's id-keyed node reuse, scoped to the nodes the author marked.
+ */
+
+/** Stable key for a permanent element: its `data-bf-permanent` value, else `id`. */
+function permanentKey(el: Element): string | null {
+  const attr = el.getAttribute('data-bf-permanent')
+  if (attr) return attr
+  if (el.id) return el.id
+  return null // marked but unkeyed → cannot be matched across documents; treated as ordinary content
+}
+
+/**
+ * Assemble the incoming region nodes, moving any **live** `[data-bf-permanent]`
+ * node from `current` into the matching position of the new tree. Returns the
+ * fragment to insert.
+ *
+ * Call this **before** disposing `current`: moving the live nodes out first is
+ * exactly what spares them from the dispose walk, and re-inserting them keeps
+ * their hydrated scope marks so the subsequent re-hydration walk skips them
+ * (`hydrateElementScope` is a no-op on an already-hydrated node).
+ */
+export function buildMorphedContent(current: Element, incoming: Node[]): DocumentFragment {
+  const fragment = document.createDocumentFragment()
+  for (const node of incoming) fragment.appendChild(node)
+
+  // Index the live permanent nodes currently mounted in the region.
+  const liveByKey = new Map<string, Element>()
+  for (const el of current.querySelectorAll('[data-bf-permanent]')) {
+    const key = permanentKey(el)
+    if (key && !liveByKey.has(key)) liveByKey.set(key, el)
+  }
+  if (liveByKey.size === 0) return fragment
+
+  // For each incoming placeholder with a matching key, swap in the live node.
+  for (const placeholder of Array.from(fragment.querySelectorAll('[data-bf-permanent]'))) {
+    // Nested permanents: this list is a snapshot. Once an *outer* placeholder is
+    // replaced by a live node, its descendant placeholders detach from
+    // `fragment` — and that live node already carries its own nested permanents
+    // from the old tree, so we must NOT then yank those out into a stale
+    // placeholder. Skip any placeholder no longer rooted in `fragment`.
+    if (!fragment.contains(placeholder)) continue
+    const key = permanentKey(placeholder)
+    if (!key) continue
+    const live = liveByKey.get(key)
+    if (!live) continue
+    // Moves `live` out of `current` and into the new tree at the placeholder's
+    // position; the freshly-parsed placeholder is discarded.
+    placeholder.replaceWith(live)
+    liveByKey.delete(key) // one live node per key
+  }
+
+  return fragment
+}