npm - @davidsouther/jiffies - Versions diffs - 2026.4.1 → 2026.24.0 - Mend

@davidsouther/jiffies 2026.4.1 → 2026.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (121) hide show

package/README.md +0 -3
package/package.json +11 -6
package/src/404.html +1 -1
package/src/components/accordion.ts +25 -0
package/src/components/alert.ts +47 -0
package/src/components/card.ts +54 -0
package/src/components/children.ts +11 -0
package/src/components/form.ts +25 -0
package/src/components/index.ts +22 -0
package/src/components/link.ts +22 -0
package/src/components/modal.ts +15 -0
package/src/components/nav.ts +42 -0
package/src/components/property.ts +32 -0
package/src/components/tabs.ts +82 -0
package/src/components/virtual_scroll.ts +1 -1
package/src/dom/README.md +7 -2
package/src/dom/SKILL.md +201 -0
package/src/dom/dom.ts +185 -41
package/src/dom/fc.ts +3 -2
package/src/dom/form/form.app.ts +35 -41
package/src/dom/form/form.ts +79 -10
package/src/dom/form/index.html +2 -2
package/src/dom/hydrate.ts +206 -0
package/src/dom/navigation/index.ts +349 -0
package/src/dom/render.ts +41 -0
package/src/dom/svg.ts +6 -2
package/src/fs_node.ts +2 -2
package/src/log.ts +154 -2
package/src/server/http/response.ts +6 -3
package/src/server/http/sitemap.ts +10 -34
package/src/server/http/static.ts +0 -2
package/src/server/live-reload.ts +208 -0
package/src/server/main.ts +14 -7
package/src/server/ws/frame.ts +36 -0
package/src/server/ws/handshake.ts +42 -0
package/src/server/ws/index.ts +100 -0
package/src/ssg/bundle.ts +85 -0
package/src/ssg/copy-public.ts +44 -0
package/src/ssg/discover.ts +143 -0
package/src/ssg/main.ts +168 -0
package/src/ssg/rewrite.ts +18 -0
package/src/ssg/ssg.ts +134 -0
package/src/components/test.ts +0 -5
package/src/components/virtual_scroll.test.ts +0 -30
package/src/context.test.ts +0 -58
package/src/context.ts +0 -67
package/src/diff.test.ts +0 -48
package/src/dom/fc.test.ts +0 -43
package/src/dom/form/form.test.ts +0 -0
package/src/dom/html.test.ts +0 -74
package/src/dom/observable.test.ts +0 -43
package/src/dom/test.ts +0 -11
package/src/equal.test.ts +0 -23
package/src/flags.test.ts +0 -43
package/src/flags.ts +0 -53
package/src/fs.test.ts +0 -106
package/src/fs_win.test.ts +0 -11
package/src/generator.test.ts +0 -27
package/src/index.html +0 -82
package/src/is_browser.js +0 -1
package/src/lock.test.ts +0 -17
package/src/observable/observable.test.ts +0 -73
package/src/pico/_variables.scss +0 -66
package/src/pico/components/_accordion.scss +0 -112
package/src/pico/components/_button-group.scss +0 -51
package/src/pico/components/_card.scss +0 -47
package/src/pico/components/_dropdown.scss +0 -203
package/src/pico/components/_modal.scss +0 -181
package/src/pico/components/_nav.scss +0 -79
package/src/pico/components/_progress.scss +0 -70
package/src/pico/components/_property.scss +0 -34
package/src/pico/content/_button.scss +0 -152
package/src/pico/content/_code.scss +0 -63
package/src/pico/content/_embedded.scss +0 -0
package/src/pico/content/_form-alt.scss +0 -276
package/src/pico/content/_form.scss +0 -259
package/src/pico/content/_misc.scss +0 -0
package/src/pico/content/_table.scss +0 -28
package/src/pico/content/_toggle.scss +0 -132
package/src/pico/content/_typography.scss +0 -232
package/src/pico/layout/_container.scss +0 -40
package/src/pico/layout/_document.scss +0 -0
package/src/pico/layout/_flex.scss +0 -46
package/src/pico/layout/_grid.scss +0 -24
package/src/pico/layout/_scroller.scss +0 -16
package/src/pico/layout/_section.scss +0 -8
package/src/pico/layout/_sectioning.scss +0 -55
package/src/pico/pico.scss +0 -60
package/src/pico/reset/_accessibility.scss +0 -34
package/src/pico/reset/_button.scss +0 -17
package/src/pico/reset/_code.scss +0 -15
package/src/pico/reset/_document.scss +0 -48
package/src/pico/reset/_embedded.scss +0 -39
package/src/pico/reset/_form.scss +0 -97
package/src/pico/reset/_misc.scss +0 -23
package/src/pico/reset/_nav.scss +0 -5
package/src/pico/reset/_progress.scss +0 -4
package/src/pico/reset/_table.scss +0 -8
package/src/pico/reset/_typography.scss +0 -25
package/src/pico/themes/default/_colors.scss +0 -65
package/src/pico/themes/default/_dark.scss +0 -148
package/src/pico/themes/default/_light.scss +0 -149
package/src/pico/themes/default/_styles.scss +0 -272
package/src/pico/themes/default.scss +0 -34
package/src/pico/utilities/_accessibility.scss +0 -3
package/src/pico/utilities/_loading.scss +0 -52
package/src/pico/utilities/_reduce-motion.scss +0 -27
package/src/pico/utilities/_tooltip.scss +0 -101
package/src/result.test.ts +0 -101
package/src/scope/describe.ts +0 -81
package/src/scope/display/console.ts +0 -26
package/src/scope/display/dom.ts +0 -36
package/src/scope/display/junit.ts +0 -64
package/src/scope/execute.ts +0 -110
package/src/scope/expect.ts +0 -169
package/src/scope/fix.ts +0 -30
package/src/scope/index.ts +0 -11
package/src/scope/scope.ts +0 -21
package/src/scope/state.ts +0 -13
package/src/test.mjs +0 -33
package/src/test_all.ts +0 -35

package/src/dom/form/form.ts CHANGED Viewed

@@ -1,5 +1,14 @@
 import type { Attrs, DenormChildren } from "../dom.ts";
-import { form, input, label, option, select } from "../html.ts";
+import {
+  button,
+  fieldset,
+  form,
+  input,
+  label,
+  legend,
+  option,
+  select,
+} from "../html.ts";
 import type {
   FormAttributes,
   InputAttributes,
@@ -38,7 +47,19 @@ export const Select = (
       ...prepareOptions(attrs.options as string[], attrs.selected).map(Option),
     ),
   );
-export const Button = () => {};
+// Sanctioned jiffies-css button variants. The default button needs no class.
+export type ButtonVariant = "secondary" | "contrast" | "outline";
+// Button emits button[type=button] so it never accidentally submits a form. The
+// optional variant maps to the matching sanctioned jiffies-css class.
+export const Button = (
+  variant?: ButtonVariant,
+  ...children: DenormChildren[]
+) =>
+  button(
+    variant ? { type: "button", class: variant } : { type: "button" },
+    ...children,
+  );
 const prepareOptions = (
   attrs:
@@ -71,12 +92,60 @@ export const Dropdown = (
     ...attrs,
     options: typeof options[0] === "string" ? options : options[0],
   });
-export const Radios = () => {};
-export const Checks = () => {};
-export const Switches = () => {};
+// A {value: label} map: option value (also the id/name stem) to display text.
+export type ChoiceOptions = Record<string, string>;
+// Derive a stable name/id stem from the legend text.
+const slug = (text: string) =>
+  text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+// Shared builder for Radios/Checks/Switches: fieldset[role=group] > legend +
+// (input[type] + label[for])* — the jiffies-css grouped-controls structure. The
+// shared name groups the inputs; id/for pairs each input to its label.
+const choiceGroup = (
+  type: "radio" | "checkbox",
+  legendText: string,
+  options: ChoiceOptions,
+  role?: "switch",
+): HTMLFieldSetElement => {
+  const name = slug(legendText);
+  const children: DenormChildren[] = [legend(legendText)];
+  for (const [value, labelText] of Object.entries(options)) {
+    const id = `${name}-${value}`;
+    const box = input({ type, name, id, value });
+    if (role) {
+      box.setAttribute("role", role);
+    }
+    const lbl = label(labelText);
+    lbl.setAttribute("for", id);
+    children.push(box, lbl);
+  }
+  const group = fieldset(...children);
+  group.setAttribute("role", "group");
+  return group;
+};
+export const Radios = (legendText: string, options: ChoiceOptions) =>
+  choiceGroup("radio", legendText, options);
+export const Checks = (legendText: string, options: ChoiceOptions) =>
+  choiceGroup("checkbox", legendText, options);
+export const Switches = (legendText: string, options: ChoiceOptions) =>
+  choiceGroup("checkbox", legendText, options, "switch");
-export const Radio = (_attrs: Omit<InputAttributes, "type">) =>
-  Input({ type: "radio" });
-export const Checkbox = (_attrs: Omit<InputAttributes, "type">) =>
-  Input({ type: "checkbox" });
-export const Switch = () => Checkbox({ role: "switch" });
+// Single-item controls wrap the input in its label (label > input + text), the
+// jiffies-css labelled-control pattern. type and role are fixed per variant.
+export const Radio = (
+  labelText: string,
+  attrs: Omit<InputAttributes, "type"> = {},
+) => Input({ ...attrs, type: "radio" }, labelText);
+export const Checkbox = (
+  labelText: string,
+  attrs: Omit<InputAttributes, "type"> = {},
+) => Input({ ...attrs, type: "checkbox" }, labelText);
+export const Switch = (
+  labelText: string,
+  attrs: Omit<InputAttributes, "type" | "role"> = {},
+) => Input({ ...attrs, type: "checkbox", role: "switch" }, labelText);

package/src/dom/form/index.html CHANGED Viewed

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="en-us">
+<html lang="en-US">
   <head>
     <title>Jiffies Form</title>
     <base href="/dom/form/" />
-    <link rel="stylesheet" href="https://unpkg.com/@picocss/pico@latest/css/pico.min.css">
+    <link rel="stylesheet" href="https://unpkg.com/@davidsouther/jiffies-css/dist/index.css">
   </head>
   <body>
     <script type="module">

package/src/dom/hydrate.ts ADDED Viewed

@@ -0,0 +1,206 @@
+"use client"; // Hydrate runs entirely client side.
+import { reconcileChildren } from "./dom.ts";
+/**
+ * Self-contained IIFE source for the capture stub. Embedded inline by the SSG
+ * build pass so events fired before the client bundle loads are queued in
+ * window.__hydrateQueue and replayed after hydration. No external references.
+ */
+export const captureStubSource = `(function(){
+  window.__hydrateQueue = window.__hydrateQueue || [];
+  var queue = window.__hydrateQueue;
+  var handler = function(event) {
+    var path = event.composedPath();
+    var unitEl = null;
+    for (var i = 0; i < path.length; i++) {
+      var node = path[i];
+      if (node instanceof Element && customElements.get(node.localName)) {
+        unitEl = node;
+        break;
+      }
+    }
+    if (!unitEl) return;
+    var target = event.target;
+    var targetPath = [];
+    var cur = target;
+    while (cur !== unitEl) {
+      var parent = cur.parentNode;
+      var siblings = Array.from(parent.childNodes);
+      targetPath.unshift(siblings.indexOf(cur));
+      cur = parent;
+    }
+    queue.push({ unitEl: unitEl, type: event.type, targetPath: targetPath, init: { bubbles: event.bubbles, cancelable: event.cancelable } });
+  };
+  var types = ["click","input","change","submit","keydown"];
+  for (var t = 0; t < types.length; t++) {
+    document.addEventListener(types[t], handler, true);
+  }
+})()`;
+/**
+ * Serialize `units` to a JSON string safe for embedding in an HTML script tag
+ * (angle brackets and ampersands are Unicode-escaped).
+ */
+export function buildPayload(units: Record<string, unknown>[]): string {
+  return JSON.stringify(units)
+    .replace(/&/g, "\\u0026")
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e");
+}
+/**
+ * Read the hydration payload from the `#__hydration` script element embedded
+ * by the SSG build step. Returns an empty array when the element is absent.
+ */
+export function readPayload(): Record<string, unknown>[] {
+  const el = window.document.getElementById("__hydration");
+  if (!el) return [];
+  return JSON.parse(el.textContent ?? "[]") as Record<string, unknown>[];
+}
+/**
+ * Walk `root` depth-first, returning every element whose localName is a
+ * defined custom element. Does NOT descend into matched elements — each custom
+ * element owns its own subtree; inner elements will be reached by their
+ * parent's `el.update()` call, not by `start()`.
+ */
+function scanUnits(root: ParentNode): Element[] {
+  const results: Element[] = [];
+  const stack: Element[] = [...root.children].reverse();
+  while (stack.length > 0) {
+    const el = stack.pop() as Element;
+    if (customElements.get(el.localName)) {
+      results.push(el);
+    } else {
+      for (let i = el.children.length - 1; i >= 0; i--) {
+        stack.push(el.children[i] as Element);
+      }
+    }
+  }
+  return results;
+}
+/**
+ * Scan `root` for registered custom elements and schedule each for hydration.
+ * `customElements.whenDefined` resolves as a microtask even when the element
+ * is already defined. The callback clears server-rendered children then runs
+ * `el.update()`, which re-executes the element's render function and rebuilds
+ * its subtree. `root` defaults to `window.document.body`.
+ */
+export function start(root?: ParentNode): void {
+  const r = root ?? window.document.body;
+  const units = scanUnits(r);
+  const payload = readPayload();
+  units.forEach((el, index) => {
+    customElements.whenDefined(el.localName).then(() => {
+      el.replaceChildren();
+      el.update(payload[index]);
+      drainQueue(el);
+    });
+  });
+}
+// Hydrate custom elements inside `root` without clearing their server-rendered
+// children first. `el.update()` reconciles onto the existing DOM so attributes
+// and listeners are grafted in place. Recurses after each element hydrates so
+// parents are always processed before their nested custom elements.
+function startHydrate(root: ParentNode): void {
+  for (const el of scanUnits(root)) {
+    customElements.whenDefined(el.localName).then(() => {
+      el.update();
+      startHydrate(el);
+    });
+  }
+}
+interface HydrateQueueEntry {
+  unitEl: Element;
+  type: string;
+  targetPath: number[];
+  init: { bubbles: boolean; cancelable: boolean };
+}
+function getHydrateQueue(): HydrateQueueEntry[] {
+  const w = window as unknown as Record<string, unknown>;
+  w.__hydrateQueue ??= [];
+  return w.__hydrateQueue as HydrateQueueEntry[];
+}
+/**
+ * Install capture-phase listeners on `document` that intercept events
+ * targeting nodes inside un-hydrated custom elements and push descriptors into
+ * `window.__hydrateQueue`. `start()` drains the queue for each element after
+ * `el.update()` runs by calling `drainQueue`.
+ */
+export function installCaptureStub(): void {
+  const queue = getHydrateQueue();
+  const handler = (event: Event) => {
+    const path = event.composedPath() as Node[];
+    let unitEl: Element | null = null;
+    for (const node of path) {
+      if (node instanceof Element && customElements.get(node.localName)) {
+        unitEl = node;
+        break;
+      }
+    }
+    if (!unitEl) return;
+    const target = event.target as Node;
+    const targetPath: number[] = [];
+    let cur: Node = target;
+    while (cur !== unitEl) {
+      const parent = cur.parentNode as Node;
+      targetPath.unshift(
+        Array.from(parent.childNodes).indexOf(cur as ChildNode),
+      );
+      cur = parent;
+    }
+    queue.push({
+      unitEl,
+      type: event.type,
+      targetPath,
+      init: { bubbles: event.bubbles, cancelable: event.cancelable },
+    });
+  };
+  for (const type of ["click", "input", "change", "submit", "keydown"]) {
+    window.document.addEventListener(type, handler, true);
+  }
+}
+function drainQueue(el: Element): void {
+  const w = window as unknown as Record<string, unknown>;
+  const allEntries = (w.__hydrateQueue ?? []) as HydrateQueueEntry[];
+  const mine = allEntries.filter((e) => e.unitEl === el);
+  w.__hydrateQueue = allEntries.filter((e) => e.unitEl !== el);
+  for (const entry of mine) {
+    let node: Node = el;
+    let resolved = true;
+    for (const idx of entry.targetPath) {
+      const child = node.childNodes[idx];
+      if (!child) {
+        console.warn(
+          `hydrateQueue: path index ${idx} out of range, dropping queued ${entry.type}`,
+        );
+        resolved = false;
+        break;
+      }
+      node = child;
+    }
+    if (resolved) {
+      node.dispatchEvent(new Event(entry.type, entry.init));
+    }
+  }
+}
+/**
+ * Hydrate a server-rendered page: call `render` once, reconcile the result
+ * into `mount` without replacing existing DOM nodes, and graft event handlers
+ * onto kept server nodes. Custom-element boundaries are left for each element
+ * to hydrate itself. Use this instead of `start` when the full page tree is
+ * produced by a single render function rather than independent custom elements.
+ */
+export function hydrateRoot(mount: Element, render: () => Node | Node[]): void {
+  const fresh = [render()].flat() as Node[];
+  reconcileChildren(mount, fresh);
+  startHydrate(mount);
+}

package/src/dom/navigation/index.ts ADDED Viewed

@@ -0,0 +1,349 @@
+"use client"; // The navigation runtime drives same-document transitions client side.
+import { start } from "../hydrate.ts";
+/**
+ * Context describing a completed navigation, handed to every `onNavigate` hook
+ * (e.g. an analytics pageview). Built by `navigate()` after the head reconcile,
+ * so `title` reflects the destination and `url` is absolute.
+ */
+export interface NavigationContext {
+  /** Absolute destination URL of the navigation. */
+  url: URL;
+  /** document.title after the head reconcile for this navigation. */
+  title: string;
+  /**
+   * "first" on initial load; otherwise the navigation's entry kind —
+   * "push" | "traverse" | "replace" — mirrored from the NavigateEvent on the
+   * interception path. A direct `navigate(url)` with no event, and a "reload",
+   * both report "push".
+   */
+  type: "first" | "push" | "traverse" | "replace";
+}
+/** A hook registered through `onNavigate`, run once per completed navigation. */
+type NavigateCallback = (ctx: NavigationContext) => void;
+/**
+ * Registered `onNavigate` hooks, fired in registration order after every
+ * completed navigation. Module-level state only: this module installs no
+ * listeners, touches no DOM, and never hydrates or calls `start()` at import
+ * time (M1 plan Step 1 invariant). The static `../hydrate.ts` import does pull
+ * in `../dom.ts`, whose jsdom bootstrap runs only in windowless Node and is
+ * skipped under a browser or jsdom where `window` already exists — so importing
+ * `./index.ts` is side-effect-free in those environments.
+ */
+const navigateCallbacks: NavigateCallback[] = [];
+/**
+ * Register `cb` to run after every in-app navigation completes (body swapped and
+ * hydration scheduled). Invariant: callbacks fire exactly once per navigation,
+ * in registration order, with the navigation's `NavigationContext`. Used by
+ * shell code such as a GA `page_view`.
+ */
+export function onNavigate(cb: NavigateCallback): void {
+  navigateCallbacks.push(cb);
+}
+/** A hook registered through `onFirstLoad`, run once when the initial page hydrates. */
+type FirstLoadCallback = (ctx: NavigationContext) => void;
+/** Hooks awaiting the first load, fired once during bootstrap in registration order. */
+const firstLoadCallbacks: FirstLoadCallback[] = [];
+/**
+ * The first-load context, set by `bootstrap()` once the initial page hydrates.
+ * `undefined` until then. Retained so an `onFirstLoad` registered AFTER first load
+ * (e.g. a shell module that imports the runtime lazily) still receives the event.
+ */
+let firstLoadContext: NavigationContext | undefined;
+/**
+ * Register `cb` to run once, when the initial page hydrates on first document load.
+ * Invariant: if registered BEFORE bootstrap, `cb` is queued and fired during
+ * bootstrap with the first-load context (`type: "first"`). If registered AFTER first
+ * load, `cb` is invoked immediately with the retained context, so a late
+ * registration never drops the initial event (design §1). Registering installs no
+ * listeners and touches no DOM (import-side-effect-free invariant).
+ */
+export function onFirstLoad(cb: FirstLoadCallback): void {
+  if (firstLoadContext) {
+    cb(firstLoadContext);
+    return;
+  }
+  firstLoadCallbacks.push(cb);
+}
+/**
+ * Attribute marking a one-time "shell" node in `<head>` (a theme bootstrap, an
+ * analytics tag): the build emits it, and the head reconciler preserves any node
+ * carrying it by identity across navigations so its inline script never re-runs.
+ */
+const SHELL_ATTR = "data-shell";
+/** True for a head node the reconciler must preserve in place across navigations. */
+function isShell(node: ChildNode): boolean {
+  return node instanceof Element && node.hasAttribute(SHELL_ATTR);
+}
+/**
+ * Abandon the same-document path for an ordinary full document load of `url`
+ * (design "Failure modes"). Returns `null` so a fetch caller can `return fullLoad(url)`
+ * to both trigger the load and signal "stop here" — the destination becomes a normal
+ * navigation, never a broken intermediate state.
+ */
+function fullLoad(url: URL): null {
+  window.location.assign(url.href);
+  return null;
+}
+/**
+ * Fetch `url` and parse its body text into a detached Document via the global
+ * DOMParser. Returns the parsed document, or `null` when the same-document path
+ * must be abandoned for a full load: a non-2xx response or a network error falls
+ * back to `fullLoad(url)` so the caller aborts before reconciling. Invariant: a
+ * returned document is detached — its nodes must be adopted with
+ * `document.importNode` before insertion into the live document.
+ */
+async function fetchDocument(url: URL): Promise<Document | null> {
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch {
+    return fullLoad(url); // network error
+  }
+  if (!response.ok) {
+    return fullLoad(url); // non-2xx
+  }
+  const html = await response.text();
+  return new DOMParser().parseFromString(html, "text/html");
+}
+/**
+ * Reconcile the live `<head>` against `destHead`. Preserves every existing
+ * `[data-shell]` node by identity; replaces all non-shell live nodes with
+ * `destHead`'s non-shell nodes (adopted into the live document). Applies the
+ * destination `<title>` via `document.title` and mirrors `<html lang>`. Leaves
+ * the destination `#__hydration` payload in place for the subsequent `start()`.
+ */
+function reconcileHead(destHead: HTMLHeadElement): void {
+  const liveHead = window.document.head;
+  // Drop every live per-page node, leaving the [data-shell] nodes untouched —
+  // preserved by identity so their inline scripts (theme, analytics) never re-run.
+  for (const node of [...liveHead.childNodes]) {
+    if (!isShell(node)) node.remove();
+  }
+  // Adopt the destination's per-page nodes (title, metadata, the #__hydration
+  // payload) and append them. The destination's own shell nodes are dropped —
+  // the live ones already cover them.
+  for (const node of [...destHead.childNodes]) {
+    if (isShell(node)) continue;
+    liveHead.appendChild(window.document.importNode(node, true));
+  }
+  // Apply <title> through document.title so it takes effect immediately, and
+  // mirror <html lang> from the destination when it differs.
+  const destRoot = destHead.ownerDocument.documentElement;
+  window.document.title = destHead.ownerDocument.title;
+  if (destRoot.lang && destRoot.lang !== window.document.documentElement.lang) {
+    window.document.documentElement.lang = destRoot.lang;
+  }
+}
+/**
+ * Replace the live `<body>` children with `destBody`'s children, adopted via
+ * `document.importNode`. New element instances replace the old ones — a child
+ * replacement, not an in-place patch — so the destination's island is a fresh
+ * node. Any `<script type="module">` rides along inert: a script inserted via
+ * the DOM never executes on its own, which is why `importPageModules` imports it
+ * explicitly. (`destBody` is typed `HTMLElement` because `Document.body` is.)
+ */
+function swapBody(destBody: HTMLElement): void {
+  const adopted = [...destBody.childNodes].map((node) =>
+    window.document.importNode(node, true),
+  );
+  window.document.body.replaceChildren(...adopted);
+}
+/** Matches each inline `import "<spec>";` statement, capturing the specifier. */
+const IMPORT_STATEMENT = /import\s+["']([^"']+)["']\s*;?/g;
+/**
+ * Extract every `import "<spec>";` specifier from `root`'s
+ * `<script type="module">` elements and dynamically import each, awaiting all.
+ * The build emits inline `import` statements (not `src` attributes, matching
+ * src/ssg/rewrite.ts), and a script node inserted via the DOM never executes on
+ * its own, so the runtime imports the specifiers itself. The ES module cache
+ * dedupes chunks already loaded this session.
+ */
+async function importPageModules(root: ParentNode): Promise<void> {
+  const specifiers: string[] = [];
+  for (const script of root.querySelectorAll('script[type="module"]')) {
+    for (const match of (script.textContent ?? "").matchAll(IMPORT_STATEMENT)) {
+      specifiers.push(match[1]);
+    }
+  }
+  await Promise.all(specifiers.map((spec) => import(spec)));
+}
+/**
+ * Same-document transition hints the interceptor lifts off the `NavigateEvent`
+ * and threads into `navigate()` — the View-Transition guard reads a field only
+ * the interception path sees. `hasUAVisualTransition` is true when the browser
+ * already ran its own visual transition for this navigation (a cross- to
+ * same-document hand-off), so the runtime must NOT start a second one;
+ * `navigationType` is the entry kind, reported on the `NavigationContext`. A
+ * direct `navigate(url)` (no event) passes neither.
+ */
+interface NavigateOptions {
+  hasUAVisualTransition?: boolean;
+  navigationType?: "push" | "replace" | "traverse" | "reload";
+}
+/**
+ * The shared same-document core the Navigation API interceptor funnels into
+ * (design §2). Fetches the destination's built HTML, reconciles `<head>`, swaps
+ * `<body>` — inside a View Transition when one is available — imports the
+ * destination's page modules, hydrates, then fires `onNavigate`. Resolves when
+ * hydration has been scheduled and hooks have fired. If `fetchDocument` fell back
+ * to a full load (non-2xx or network error), it returns `null` and this aborts
+ * without reconciling, swapping, or firing hooks.
+ */
+export async function navigate(
+  url: string | URL,
+  options: NavigateOptions = {},
+): Promise<void> {
+  const target = new URL(url, window.location.href);
+  const destination = await fetchDocument(target);
+  if (destination === null) return; // fell back to a full document load
+  reconcileHead(destination.head);
+  // Swap the body inside a same-document View Transition when the browser
+  // supports one AND has not already animated this navigation itself (design §2
+  // step 4). startViewTransition snapshots the live DOM, runs the swap callback
+  // to mutate it, then animates the before/after states; awaiting
+  // updateCallbackDone resumes once the swap has applied (the DOM is updated),
+  // before modules import and hydration run. Where startViewTransition is absent
+  // or the UA already transitioned (hasUAVisualTransition), the swap is applied
+  // directly — degraded to an abrupt replacement, never broken (design "Failure
+  // modes").
+  const doc = window.document;
+  const applySwap = () => swapBody(destination.body);
+  if (
+    typeof doc.startViewTransition === "function" &&
+    !options.hasUAVisualTransition
+  ) {
+    await doc.startViewTransition(applySwap).updateCallbackDone;
+  } else {
+    applySwap();
+  }
+  await importPageModules(window.document.body);
+  // Hydrate the swapped-in body: start() reads the destination #__hydration
+  // payload (placed by reconcileHead) and schedules each island's update().
+  start(window.document.body);
+  // Report the completed navigation. title reflects the reconciled <head>; url
+  // is the absolute target; type mirrors the navigation's entry kind (a "reload"
+  // or a direct navigate() with no event reports "push"). Hooks fire once each,
+  // in registration order.
+  const { navigationType } = options;
+  const context: NavigationContext = {
+    url: target,
+    title: window.document.title,
+    type:
+      navigationType === "push" ||
+      navigationType === "replace" ||
+      navigationType === "traverse"
+        ? navigationType
+        : "push",
+  };
+  for (const cb of navigateCallbacks) cb(context);
+}
+/**
+ * Install the navigation interceptor. The Navigation API is the sole interception
+ * mechanism: it delivers one `navigate` event for every same-document candidate —
+ * link click, programmatic navigation, and back/forward — so a single listener
+ * replaces a click handler plus a `popstate` listener, and the API owns history
+ * and scroll restoration (so the core stays `history.pushState`-free).
+ *
+ * The Navigation API is Baseline as of Jan 2026; this project targets evergreen
+ * browsers. Where it is absent there is NO interception: links perform normal
+ * full-document navigations — degraded (no shared-runtime hydration) but never
+ * broken. That minimal alternative is the entire fallback.
+ *
+ * Called by `bootstrap()` after `start()` and before firing `onFirstLoad`. The
+ * listener is added only here, never at module top level, so importing this module
+ * stays side-effect-free. Types come from `@types/dom-navigation` (folded into
+ * lib.dom as of TS 6.0); see the tracking task in `docs/developer/TASKS.md`.
+ */
+function installInterceptor(): void {
+  if (!("navigation" in window)) return;
+  window.navigation.addEventListener("navigate", (event) => {
+    // Decline (let the browser navigate natively) when the API cannot intercept
+    // — cross-origin, etc. — or for a hash-only, download, or non-GET (form)
+    // navigation. Form submissions are out of scope (design §2, Summary).
+    if (!event.canIntercept) return;
+    if (event.hashChange) return;
+    if (event.downloadRequest !== null) return;
+    if (event.formData !== null) return;
+    // Claim the navigation: run the shared core as the same-document transition.
+    // navigate() fetches, reconciles <head>, swaps <body> (inside a View
+    // Transition when the browser offers one and did not already animate this
+    // navigation), imports the page module, hydrates, and fires onNavigate. The
+    // API commits the history entry. hasUAVisualTransition and navigationType are
+    // threaded through because only this interception path sees the event.
+    const { url } = event.destination;
+    event.intercept({
+      handler: () =>
+        navigate(url, {
+          hasUAVisualTransition: event.hasUAVisualTransition,
+          navigationType: event.navigationType,
+        }),
+    });
+  });
+}
+/**
+ * Bootstrap route hydration for the initial document. Explicit entry — NOT run at
+ * import time (the module stays side-effect-free; tests and the M3 injected entry
+ * decide when this runs). On call it:
+ *   1. `start(window.document.body)` — hydrate the server-rendered initial islands
+ *      in place (reads the initial `#__hydration` payload already in <head>).
+ *   2. `installInterceptor()` — register the Navigation API `navigate` listener to
+ *      capture subsequent in-app navigations, between `start()` and `onFirstLoad`.
+ *   3. Build the first-load `NavigationContext`: `url` from `window.location.href`,
+ *      `title` from `document.title`, `type: "first"`. Store it in `firstLoadContext`.
+ *   4. Fire every queued `onFirstLoad` callback once, in registration order.
+ * Invariant: `onFirstLoad` fires exactly once per bootstrap.
+ */
+export async function bootstrap(): Promise<void> {
+  // 1. Hydrate the server-rendered initial islands in place. start() reads the
+  // initial #__hydration payload already in <head> and schedules each update().
+  start(window.document.body);
+  // 2. Register the Navigation API interceptor so subsequent in-app navigations
+  // are captured. Between start() and firing onFirstLoad, per design §1.
+  installInterceptor();
+  // 3. Build and retain the first-load context (design §1). url is the initial
+  // location, title the current document title, type "first".
+  firstLoadContext = {
+    url: new URL(window.location.href),
+    title: window.document.title,
+    type: "first",
+  };
+  // 4. Fire every queued onFirstLoad callback once, in registration order, then
+  // clear the queue so the event fires exactly once per bootstrap. A callback
+  // registered AFTER this point fires immediately against firstLoadContext (see
+  // onFirstLoad), so a late registration never drops the initial event.
+  for (const cb of firstLoadCallbacks) cb(firstLoadContext);
+  firstLoadCallbacks.length = 0;
+}