@davidsouther/jiffies 2026.4.1 → 2026.24.1

package/lib/esm/dom/fc.js

@@ -0,0 +1,32 @@
+import { CLEAR, normalizeArguments, reconcileChildren, update, } from "./dom.js";
+export const State = Symbol();
+export function FC(name, component) {
+    class FCImpl extends HTMLElement {
+        [State] = {};
+        #attrs = {};
+        #children = [];
+        update(attrs, ...children) {
+            [attrs, children] = normalizeArguments(attrs, children);
+            if (children[0] === CLEAR) {
+                this.#children = [];
+            }
+            else if (children.length > 0) {
+                this.#children = children;
+            }
+            this.#attrs = { ...this.#attrs, ...attrs };
+            // Apply updates from the attrs to the dom node itself
+            update(this, this.#attrs, []);
+            // Re-run the component function using new element, attrs, and children.
+            const rendered = [component(this, this.#attrs, this.#children)];
+            reconcileChildren(this, rendered.flat());
+            return this;
+        }
+    }
+    customElements.define(name, FCImpl);
+    const ctor = (attrs, ...children) => {
+        const element = window.document.createElement(name);
+        element.update(attrs, ...children);
+        return element;
+    };
+    return ctor;
+}

package/lib/esm/dom/form/form.app.d.ts

@@ -0,0 +1 @@
+export declare const App: () => HTMLElement;

package/lib/esm/dom/form/form.app.js

@@ -0,0 +1,19 @@
+import { button, div, main, small } from "../html.js";
+import { Form, Input } from "./form.js";
+export const App = () => main(Form({
+    events: {
+        submit(event) {
+            console.log("Should see fields for firstname, lastname, email, etc");
+            console.log(event);
+        },
+    },
+}, div({ class: "grid" }, Input({ id: "firstname", placeholder: "First name" }), Input({ id: "lastname", placeholder: "Last name" })), Input({
+    id: "email",
+    type: "email",
+    placeholder: "Email address",
+    required: true,
+}, small("We will never share your email with anyone.")), button({ type: "submit" }, "Submit"), div({ class: "grid" }, Input({ id: "valid", placeholder: "Valid", "aria-invalid": "false" }), Input({
+    id: "invalid",
+    placeholder: "Invalid",
+    "aria-invalid": "true",
+}), Input({ id: "disabled", placeholder: "Disabled", disabled: true }), Input({ id: "readonly", value: "Readonly", readOnly: true }))));

package/lib/esm/dom/form/form.d.ts

@@ -0,0 +1,27 @@
+import type { DenormChildren } from "../dom.ts";
+import type { FormAttributes, InputAttributes, LabelAttributes, OptionAttributes, SelectAttributes } from "../types/html";
+export declare const Form: (attrs: FormAttributes, ...children: DenormChildren[]) => HTMLFormElement;
+export declare const Input: (attrs: InputAttributes, ...children: DenormChildren[]) => HTMLLabelElement;
+export declare const Select: (attrs: {
+    options: string[] | object;
+    selected?: string;
+} & SelectAttributes & LabelAttributes) => HTMLLabelElement;
+export type ButtonVariant = "secondary" | "contrast" | "outline";
+export declare const Button: (variant?: ButtonVariant, ...children: DenormChildren[]) => HTMLButtonElement;
+declare const prepareOptions: (attrs: string[] | Record<string, string | {
+    label: string;
+    disabled?: boolean;
+    selected?: boolean;
+}>, selected?: string) => Parameters<typeof Option>[0][];
+export declare const Option: (attrs: OptionAttributes) => HTMLOptionElement;
+export declare const Dropdown: (attrs: SelectAttributes | {
+    selected?: string;
+}, ...options: Parameters<typeof prepareOptions>[0][]) => HTMLLabelElement;
+export type ChoiceOptions = Record<string, string>;
+export declare const Radios: (legendText: string, options: ChoiceOptions) => HTMLFieldSetElement;
+export declare const Checks: (legendText: string, options: ChoiceOptions) => HTMLFieldSetElement;
+export declare const Switches: (legendText: string, options: ChoiceOptions) => HTMLFieldSetElement;
+export declare const Radio: (labelText: string, attrs?: Omit<InputAttributes, "type">) => HTMLLabelElement;
+export declare const Checkbox: (labelText: string, attrs?: Omit<InputAttributes, "type">) => HTMLLabelElement;
+export declare const Switch: (labelText: string, attrs?: Omit<InputAttributes, "type" | "role">) => HTMLLabelElement;
+export {};

package/lib/esm/dom/form/form.js

@@ -0,0 +1,65 @@
+import { button, fieldset, form, input, label, legend, option, select, } from "../html.js";
+export const Form = (attrs, ...children) => {
+    if (attrs.events?.submit) {
+        const submit = attrs.events.submit;
+        attrs.events.submit = (event) => {
+            event.preventDefault();
+            submit(event);
+        };
+    }
+    return form(attrs, ...children);
+};
+export const Input = (attrs, ...children) => label(input(
+// @ts-expect-error
+attrs), ...children);
+export const Select = (attrs) => label({ style: attrs.style ?? {} }, select({ events: attrs.events ?? {} }, ...prepareOptions(attrs.options, attrs.selected).map(Option)));
+// 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, ...children) => button(variant ? { type: "button", class: variant } : { type: "button" }, ...children);
+const prepareOptions = (attrs, selected) => Array.isArray(attrs)
+    ? attrs.map((value) => ({
+        value,
+        label: value,
+        selected: selected === value,
+    }))
+    : Object.entries(attrs).map(([value, label]) => typeof label === "string"
+        ? { value, label, selected: selected === value }
+        : { value, ...label });
+export const Option = (attrs) => option(attrs);
+export const Dropdown = (attrs, ...options) => Select({
+    ...attrs,
+    options: typeof options[0] === "string" ? options : options[0],
+});
+// Derive a stable name/id stem from the legend text.
+const slug = (text) => 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, legendText, options, role) => {
+    const name = slug(legendText);
+    const children = [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, options) => choiceGroup("radio", legendText, options);
+export const Checks = (legendText, options) => choiceGroup("checkbox", legendText, options);
+export const Switches = (legendText, options) => choiceGroup("checkbox", legendText, options, "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, attrs = {}) => Input({ ...attrs, type: "radio" }, labelText);
+export const Checkbox = (labelText, attrs = {}) => Input({ ...attrs, type: "checkbox" }, labelText);
+export const Switch = (labelText, attrs = {}) => Input({ ...attrs, type: "checkbox", role: "switch" }, labelText);

package/lib/esm/dom/html.d.ts

@@ -0,0 +1,112 @@
+import { type DenormAttrs, type DenormChildren } from "./dom.ts";
+export declare const a: (attrs?: DenormAttrs<HTMLAnchorElement>, ...children: DenormChildren[]) => HTMLAnchorElement;
+export declare const abbr: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const address: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const area: (attrs?: DenormAttrs<HTMLAreaElement>, ...children: DenormChildren[]) => HTMLAreaElement;
+export declare const article: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const aside: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const audio: (attrs?: DenormAttrs<HTMLAudioElement>, ...children: DenormChildren[]) => HTMLAudioElement;
+export declare const b: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const base: (attrs?: DenormAttrs<HTMLBaseElement>, ...children: DenormChildren[]) => HTMLBaseElement;
+export declare const bdi: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const bdo: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const blockquote: (attrs?: DenormAttrs<HTMLQuoteElement>, ...children: DenormChildren[]) => HTMLQuoteElement;
+export declare const body: (attrs?: DenormAttrs<HTMLBodyElement>, ...children: DenormChildren[]) => HTMLBodyElement;
+export declare const br: (attrs?: DenormAttrs<HTMLBRElement>, ...children: DenormChildren[]) => HTMLBRElement;
+export declare const button: (attrs?: DenormAttrs<HTMLButtonElement>, ...children: DenormChildren[]) => HTMLButtonElement;
+export declare const canvas: (attrs?: DenormAttrs<HTMLCanvasElement>, ...children: DenormChildren[]) => HTMLCanvasElement;
+export declare const caption: (attrs?: DenormAttrs<HTMLTableCaptionElement>, ...children: DenormChildren[]) => HTMLTableCaptionElement;
+export declare const cite: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const code: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const col: (attrs?: DenormAttrs<HTMLTableColElement>, ...children: DenormChildren[]) => HTMLTableColElement;
+export declare const colgroup: (attrs?: DenormAttrs<HTMLTableColElement>, ...children: DenormChildren[]) => HTMLTableColElement;
+export declare const data: (attrs?: DenormAttrs<HTMLDataElement>, ...children: DenormChildren[]) => HTMLDataElement;
+export declare const datalist: (attrs?: DenormAttrs<HTMLDataListElement>, ...children: DenormChildren[]) => HTMLDataListElement;
+export declare const dd: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const del: (attrs?: DenormAttrs<HTMLModElement>, ...children: DenormChildren[]) => HTMLModElement;
+export declare const details: (attrs?: DenormAttrs<HTMLDetailsElement>, ...children: DenormChildren[]) => HTMLDetailsElement;
+export declare const dfn: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const dialog: (attrs?: DenormAttrs<HTMLDialogElement>, ...children: DenormChildren[]) => HTMLDialogElement;
+export declare const div: (attrs?: DenormAttrs<HTMLDivElement>, ...children: DenormChildren[]) => HTMLDivElement;
+export declare const dl: (attrs?: DenormAttrs<HTMLDListElement>, ...children: DenormChildren[]) => HTMLDListElement;
+export declare const dt: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const em: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const embed: (attrs?: DenormAttrs<HTMLEmbedElement>, ...children: DenormChildren[]) => HTMLEmbedElement;
+export declare const fieldset: (attrs?: DenormAttrs<HTMLFieldSetElement>, ...children: DenormChildren[]) => HTMLFieldSetElement;
+export declare const figcaption: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const figure: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const footer: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const form: (attrs?: DenormAttrs<HTMLFormElement>, ...children: DenormChildren[]) => HTMLFormElement;
+export declare const h1: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const h2: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const h3: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const h4: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const h5: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const h6: (attrs?: DenormAttrs<HTMLHeadingElement>, ...children: DenormChildren[]) => HTMLHeadingElement;
+export declare const head: (attrs?: DenormAttrs<HTMLHeadElement>, ...children: DenormChildren[]) => HTMLHeadElement;
+export declare const header: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const hgroup: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const hr: (attrs?: DenormAttrs<HTMLHRElement>, ...children: DenormChildren[]) => HTMLHRElement;
+export declare const html: (attrs?: DenormAttrs<HTMLHtmlElement>, ...children: DenormChildren[]) => HTMLHtmlElement;
+export declare const i: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const iframe: (attrs?: DenormAttrs<HTMLIFrameElement>, ...children: DenormChildren[]) => HTMLIFrameElement;
+export declare const img: (attrs?: DenormAttrs<HTMLImageElement>, ...children: DenormChildren[]) => HTMLImageElement;
+export declare const input: (attrs?: DenormAttrs<HTMLInputElement>, ...children: DenormChildren[]) => HTMLInputElement;
+export declare const ins: (attrs?: DenormAttrs<HTMLModElement>, ...children: DenormChildren[]) => HTMLModElement;
+export declare const kbd: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const label: (attrs?: DenormAttrs<HTMLLabelElement>, ...children: DenormChildren[]) => HTMLLabelElement;
+export declare const legend: (attrs?: DenormAttrs<HTMLLegendElement>, ...children: DenormChildren[]) => HTMLLegendElement;
+export declare const li: (attrs?: DenormAttrs<HTMLLIElement>, ...children: DenormChildren[]) => HTMLLIElement;
+export declare const link: (attrs?: DenormAttrs<HTMLLinkElement>, ...children: DenormChildren[]) => HTMLLinkElement;
+export declare const main: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const map: (attrs?: DenormAttrs<HTMLMapElement>, ...children: DenormChildren[]) => HTMLMapElement;
+export declare const mark: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const menu: (attrs?: DenormAttrs<HTMLMenuElement>, ...children: DenormChildren[]) => HTMLMenuElement;
+export declare const meta: (attrs?: DenormAttrs<HTMLMetaElement>, ...children: DenormChildren[]) => HTMLMetaElement;
+export declare const meter: (attrs?: DenormAttrs<HTMLMeterElement>, ...children: DenormChildren[]) => HTMLMeterElement;
+export declare const nav: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const noscript: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const object: (attrs?: DenormAttrs<HTMLObjectElement>, ...children: DenormChildren[]) => HTMLObjectElement;
+export declare const ol: (attrs?: DenormAttrs<HTMLOListElement>, ...children: DenormChildren[]) => HTMLOListElement;
+export declare const optgroup: (attrs?: DenormAttrs<HTMLOptGroupElement>, ...children: DenormChildren[]) => HTMLOptGroupElement;
+export declare const option: (attrs?: DenormAttrs<HTMLOptionElement>, ...children: DenormChildren[]) => HTMLOptionElement;
+export declare const output: (attrs?: DenormAttrs<HTMLOutputElement>, ...children: DenormChildren[]) => HTMLOutputElement;
+export declare const p: (attrs?: DenormAttrs<HTMLParagraphElement>, ...children: DenormChildren[]) => HTMLParagraphElement;
+export declare const picture: (attrs?: DenormAttrs<HTMLPictureElement>, ...children: DenormChildren[]) => HTMLPictureElement;
+export declare const pre: (attrs?: DenormAttrs<HTMLPreElement>, ...children: DenormChildren[]) => HTMLPreElement;
+export declare const progress: (attrs?: DenormAttrs<HTMLProgressElement>, ...children: DenormChildren[]) => HTMLProgressElement;
+export declare const q: (attrs?: DenormAttrs<HTMLQuoteElement>, ...children: DenormChildren[]) => HTMLQuoteElement;
+export declare const rp: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const rt: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const ruby: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const s: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const samp: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const script: (attrs?: DenormAttrs<HTMLScriptElement>, ...children: DenormChildren[]) => HTMLScriptElement;
+export declare const section: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const select: (attrs?: DenormAttrs<HTMLSelectElement>, ...children: DenormChildren[]) => HTMLSelectElement;
+export declare const slot: (attrs?: DenormAttrs<HTMLSlotElement>, ...children: DenormChildren[]) => HTMLSlotElement;
+export declare const small: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const source: (attrs?: DenormAttrs<HTMLSourceElement>, ...children: DenormChildren[]) => HTMLSourceElement;
+export declare const span: (attrs?: DenormAttrs<HTMLSpanElement>, ...children: DenormChildren[]) => HTMLSpanElement;
+export declare const strong: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const style: (attrs?: DenormAttrs<HTMLStyleElement>, ...children: DenormChildren[]) => HTMLStyleElement;
+export declare const sub: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const summary: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const sup: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const table: (attrs?: DenormAttrs<HTMLTableElement>, ...children: DenormChildren[]) => HTMLTableElement;
+export declare const tbody: (attrs?: DenormAttrs<HTMLTableSectionElement>, ...children: DenormChildren[]) => HTMLTableSectionElement;
+export declare const td: (attrs?: DenormAttrs<HTMLTableCellElement>, ...children: DenormChildren[]) => HTMLTableCellElement;
+export declare const template: (attrs?: DenormAttrs<HTMLTemplateElement>, ...children: DenormChildren[]) => HTMLTemplateElement;
+export declare const textarea: (attrs?: DenormAttrs<HTMLTextAreaElement>, ...children: DenormChildren[]) => HTMLTextAreaElement;
+export declare const tfoot: (attrs?: DenormAttrs<HTMLTableSectionElement>, ...children: DenormChildren[]) => HTMLTableSectionElement;
+export declare const th: (attrs?: DenormAttrs<HTMLTableCellElement>, ...children: DenormChildren[]) => HTMLTableCellElement;
+export declare const thead: (attrs?: DenormAttrs<HTMLTableSectionElement>, ...children: DenormChildren[]) => HTMLTableSectionElement;
+export declare const time: (attrs?: DenormAttrs<HTMLTimeElement>, ...children: DenormChildren[]) => HTMLTimeElement;
+export declare const title: (attrs?: DenormAttrs<HTMLTitleElement>, ...children: DenormChildren[]) => HTMLTitleElement;
+export declare const tr: (attrs?: DenormAttrs<HTMLTableRowElement>, ...children: DenormChildren[]) => HTMLTableRowElement;
+export declare const track: (attrs?: DenormAttrs<HTMLTrackElement>, ...children: DenormChildren[]) => HTMLTrackElement;
+export declare const u: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const ul: (attrs?: DenormAttrs<HTMLUListElement>, ...children: DenormChildren[]) => HTMLUListElement;
+export declare const htmlvar: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;
+export declare const video: (attrs?: DenormAttrs<HTMLVideoElement>, ...children: DenormChildren[]) => HTMLVideoElement;
+export declare const wbr: (attrs?: DenormAttrs<HTMLElement>, ...children: DenormChildren[]) => HTMLElement;

package/{src/dom/html.ts → lib/esm/dom/html.js}

@@ -1,17 +1,5 @@
-import { type DenormAttrs, type DenormChildren, up } from "./dom.ts";
-
-const makeHTMLElement =
-  <K extends keyof HTMLElementTagNameMap>(name: K) =>
-  (
-    attrs?: DenormAttrs<HTMLElementTagNameMap[K]>,
-    ...children: DenormChildren[]
-  ) =>
-    up(
-      window.document.createElement(name),
-      attrs,
-      ...children,
-    ) as HTMLElementTagNameMap[K];
-
+import { up } from "./dom.js";
+const makeHTMLElement = (name) => (attrs, ...children) => up(window.document.createElement(name), attrs, ...children);
 export const a = makeHTMLElement("a");
 export const abbr = makeHTMLElement("abbr");
 export const address = makeHTMLElement("address");

package/lib/esm/dom/hydrate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const captureStubSource = "(function(){\n  window.__hydrateQueue = window.__hydrateQueue || [];\n  var queue = window.__hydrateQueue;\n  var handler = function(event) {\n    var path = event.composedPath();\n    var unitEl = null;\n    for (var i = 0; i < path.length; i++) {\n      var node = path[i];\n      if (node instanceof Element && customElements.get(node.localName)) {\n        unitEl = node;\n        break;\n      }\n    }\n    if (!unitEl) return;\n    var target = event.target;\n    var targetPath = [];\n    var cur = target;\n    while (cur !== unitEl) {\n      var parent = cur.parentNode;\n      var siblings = Array.from(parent.childNodes);\n      targetPath.unshift(siblings.indexOf(cur));\n      cur = parent;\n    }\n    queue.push({ unitEl: unitEl, type: event.type, targetPath: targetPath, init: { bubbles: event.bubbles, cancelable: event.cancelable } });\n  };\n  var types = [\"click\",\"input\",\"change\",\"submit\",\"keydown\"];\n  for (var t = 0; t < types.length; t++) {\n    document.addEventListener(types[t], handler, true);\n  }\n})()";
+/**
+ * Serialize `units` to a JSON string safe for embedding in an HTML script tag
+ * (angle brackets and ampersands are Unicode-escaped).
+ */
+export declare function buildPayload(units: Record<string, unknown>[]): string;
+/**
+ * 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 declare function readPayload(): Record<string, unknown>[];
+/**
+ * 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 declare function start(root?: ParentNode): void;
+/**
+ * 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 declare function installCaptureStub(): void;
+/**
+ * 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 declare function hydrateRoot(mount: Element, render: () => Node | Node[]): void;

package/lib/esm/dom/hydrate.js

@@ -0,0 +1,187 @@
+"use client"; // Hydrate runs entirely client side.
+import { reconcileChildren } from "./dom.js";
+/**
+ * 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) {
+    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() {
+    const el = window.document.getElementById("__hydration");
+    if (!el)
+        return [];
+    return JSON.parse(el.textContent ?? "[]");
+}
+/**
+ * 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) {
+    const results = [];
+    const stack = [...root.children].reverse();
+    while (stack.length > 0) {
+        const el = stack.pop();
+        if (customElements.get(el.localName)) {
+            results.push(el);
+        }
+        else {
+            for (let i = el.children.length - 1; i >= 0; i--) {
+                stack.push(el.children[i]);
+            }
+        }
+    }
+    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) {
+    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) {
+    for (const el of scanUnits(root)) {
+        customElements.whenDefined(el.localName).then(() => {
+            el.update();
+            startHydrate(el);
+        });
+    }
+}
+function getHydrateQueue() {
+    const w = window;
+    w.__hydrateQueue ??= [];
+    return w.__hydrateQueue;
+}
+/**
+ * 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() {
+    const queue = getHydrateQueue();
+    const handler = (event) => {
+        const path = event.composedPath();
+        let unitEl = null;
+        for (const node of path) {
+            if (node instanceof Element && customElements.get(node.localName)) {
+                unitEl = node;
+                break;
+            }
+        }
+        if (!unitEl)
+            return;
+        const target = event.target;
+        const targetPath = [];
+        let cur = target;
+        while (cur !== unitEl) {
+            const parent = cur.parentNode;
+            targetPath.unshift(Array.from(parent.childNodes).indexOf(cur));
+            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) {
+    const w = window;
+    const allEntries = (w.__hydrateQueue ?? []);
+    const mine = allEntries.filter((e) => e.unitEl === el);
+    w.__hydrateQueue = allEntries.filter((e) => e.unitEl !== el);
+    for (const entry of mine) {
+        let 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, render) {
+    const fresh = [render()].flat();
+    reconcileChildren(mount, fresh);
+    startHydrate(mount);
+}

package/lib/esm/dom/index.js

@@ -0,0 +1,2 @@
+export * as fc from "./fc.js";
+export * as html from "./html.js";

package/lib/esm/dom/navigation/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;
+/**
+ * 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 declare function onNavigate(cb: NavigateCallback): void;
+/** A hook registered through `onFirstLoad`, run once when the initial page hydrates. */
+type FirstLoadCallback = (ctx: NavigationContext) => void;
+/**
+ * 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 declare function onFirstLoad(cb: FirstLoadCallback): void;
+/**
+ * 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 declare function navigate(url: string | URL, options?: NavigateOptions): Promise<void>;
+/**
+ * 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 declare function bootstrap(): Promise<void>;
+export {};