@ogygia/core 0.0.0 → 0.11.0

package/dist/runtime/page-defer.js

@@ -0,0 +1,103 @@
+import { PAGE_DEFER_BOOTSTRAP, PAGE_DEFER_GLOBAL, PAGE_DEFER_KEY, PAGE_DEFER_REGISTRY_KEY, PAGE_SETTLED_KEY } from "../page-defer.js";
+import { parse } from "devalue";
+// src/runtime/page-defer.ts
+/**
+* Client side of streaming `$page.data` promises into islands (see `../page-defer.ts` for the why).
+*
+* The page seed carries a DEFER MARKER (`[id]`) for each pending promise; the reviver turns it into a
+* real pending Promise, so an island's `{#await page.data.x}` renders its pending branch. As each
+* promise settles the server streams `<script>__ogygia_page_resolve(id, ok, encoded)<\/script>`, which
+* resolves the matching Promise — the `{#await}` flips to its resolved branch, live.
+*
+* Ordering is fully decoupled: an inline bootstrap (first body chunk) defines the resolve global and
+* QUEUES calls until the runtime installs the live parser; the reviver may create a deferred before or
+* after its resolve arrives. One registry per document via a Symbol.for handle (dev evaluates the
+* runtime twice — a module-local map would split; PAGE-STATE-SINGLETON).
+*/
+function reg() {
+	const g = globalThis;
+	return g[PAGE_DEFER_REGISTRY_KEY] ??= {};
+}
+function to_error(value) {
+	const msg = value && typeof value === "object" && "message" in value ? String(value.message) : "ogygia: streamed promise rejected";
+	return new Error(msg);
+}
+/** Reviver: a defer marker `[id]` becomes a real Promise, pending until its resolve script lands (or
+*  already-resolved if the resolve raced ahead of the seed). */
+function create_deferred(id) {
+	const r = reg();
+	const deferreds = r.deferreds ??= /* @__PURE__ */ new Map();
+	const existing = deferreds.get(id);
+	if (existing) return existing.promise;
+	const early = r.settled?.get(id);
+	if (early) {
+		r.settled.delete(id);
+		if (early.ok) return Promise.resolve(early.value);
+		const p = Promise.reject(to_error(early.value));
+		p.catch(() => {});
+		return p;
+	}
+	let resolve;
+	let reject;
+	const promise = new Promise((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	promise.catch(() => {});
+	deferreds.set(id, {
+		promise,
+		resolve,
+		reject
+	});
+	return promise;
+}
+function settle(id, ok, value) {
+	const r = reg();
+	const d = r.deferreds?.get(id);
+	if (d) {
+		r.deferreds.delete(id);
+		if (ok) d.resolve(value);
+		else d.reject(to_error(value));
+	} else (r.settled ??= /* @__PURE__ */ new Map()).set(id, {
+		ok,
+		value
+	});
+}
+/** Install the live resolver (which parses the encoded value) and drain anything the inline bootstrap
+*  queued before the runtime loaded. `extra_revivers` are the app's transport decoders (custom types in
+*  a streamed value). Idempotent — safe to call on every boot; the first call's revivers win. */
+function install_page_defer(extra_revivers) {
+	const r = reg();
+	if (r.live) return;
+	r.revivers = page_defer_revivers(extra_revivers);
+	r.live = (id, ok, encoded) => {
+		let value = null;
+		try {
+			value = parse(encoded, r.revivers);
+		} catch {}
+		settle(id, ok, value);
+	};
+	const queued = r.q;
+	r.q = [];
+	if (queued) for (const [id, ok, encoded] of queued) r.live(id, ok, encoded);
+	const g = globalThis;
+	g[PAGE_DEFER_GLOBAL] ??= (id, ok, encoded) => r.live(id, ok, encoded);
+}
+/** devalue reviver map for the page seed. A DEFER marker becomes a pending Promise (streaming path); a
+*  SETTLED marker becomes an already resolved/rejected Promise (non-navigate path). Both keep
+*  `page.data.x` a Promise, so `{#await}` works identically regardless of how the page was requested.
+*  `extra` merges the app's transport decoders; ogygia's own keys always win on any name clash. */
+function page_defer_revivers(extra) {
+	return {
+		...extra,
+		[PAGE_DEFER_KEY]: (payload) => create_deferred(payload[0]),
+		[PAGE_SETTLED_KEY]: (payload) => {
+			const [ok, value] = payload;
+			if (ok) return Promise.resolve(value);
+			const p = Promise.reject(to_error(value));
+			p.catch(() => {});
+			return p;
+		}
+	};
+}
+export { PAGE_DEFER_BOOTSTRAP, create_deferred, install_page_defer, page_defer_revivers };

package/dist/runtime/parse-html.d.ts

@@ -0,0 +1,40 @@
+/**
+ * THE one place region / SSR HTML becomes DOM. A leaf module (no imports) so every parse site shares
+ * it: `region_fragment` (a fetched hole / live tick / held region), `repair_if_drifted` (the server
+ * copy an island hydrates against), and anything added later. Having ONE parser is the point — a second,
+ * DSD-unaware one would silently drift (see below).
+ *
+ * `<template shadowrootmode>` (declarative shadow DOM — a web STANDARD, nothing library-specific) turns
+ * into a real shadow root ONLY when a DSD-aware parser reads it. `Element.setHTMLUnsafe()` is that
+ * parser — the very algorithm the document uses on first load — so a server-painted region body arrives
+ * with its shadow roots live, exactly as the initial page paints. `createContextualFragment` /
+ * `innerHTML` / `DOMParser` are all DSD-UNAWARE by spec: they leave the `<template>` inert, so any host
+ * that renders its box from inside its shadow paints at 0 height until its own runtime upgrades it (the
+ * swap-then-blank-then-paint flicker). "Unsafe" means only "no sanitizer"; a region body is our own
+ * signed, same-origin SSR (HOLE-TRUST), so it is exactly as trusted as the page itself.
+ *
+ * NOTE the parse happens in a `<template>`'s inert content, so custom elements do NOT upgrade here
+ * (no `connectedCallback`) — attaching a declarative shadow root is a parse step, not an upgrade. That
+ * is what `repair_if_drifted` needs: the server copy stays inert, but its light-DOM sequence is now
+ * DSD-consistent with a live region whose hosts already carry shadow roots.
+ */
+export declare function parse_region_html(html: string): DocumentFragment;
+/** The spec's declarative-shadow-DOM attach step, for engines that render DSD on first parse but predate
+ *  `setHTMLUnsafe`. Recurse into each shadow we attach: `querySelectorAll` stops at shadow boundaries,
+ *  and a `<template shadowrootmode>` can nest inside another. First template per host wins (a host already
+ *  carrying a shadow root is left as is). */
+export declare function attach_declarative_shadows(root: DocumentFragment | ShadowRoot): void;
+/** The app's transform reshaped this markup (server/reversible.ts): restore it before anything reads
+ *  it. The restorer is the page's own (the handle inlines it only when the app has a transform), so
+ *  the runtime carries none of it — without one, this is a no-op. */
+export declare function restore_markup(root: ParentNode): void;
+/** Adopt the keyed sheets of roots restored outside the page, right after their insertion. */
+export declare function restore_adopt_sheets(): void;
+/**
+ * Shadow roots attached while the markup sat in an inert document — a declarative shadow root the
+ * parse above attached, a restored one — get no custom element registry in a browser with scoped
+ * registries, and keep none once inserted: nothing inside them upgrades (an element that calls
+ * `attachInternals` in its constructor throws). Give each the page's registry, right after the
+ * insertion. A browser without scoped registries never nulls it (and has no `initialize`): a no-op.
+ */
+export declare function init_shadow_registries(under: Node): void;

package/dist/runtime/parse-html.js

@@ -0,0 +1,81 @@
+// src/runtime/parse-html.ts
+/**
+* THE one place region / SSR HTML becomes DOM. A leaf module (no imports) so every parse site shares
+* it: `region_fragment` (a fetched hole / live tick / held region), `repair_if_drifted` (the server
+* copy an island hydrates against), and anything added later. Having ONE parser is the point — a second,
+* DSD-unaware one would silently drift (see below).
+*
+* `<template shadowrootmode>` (declarative shadow DOM — a web STANDARD, nothing library-specific) turns
+* into a real shadow root ONLY when a DSD-aware parser reads it. `Element.setHTMLUnsafe()` is that
+* parser — the very algorithm the document uses on first load — so a server-painted region body arrives
+* with its shadow roots live, exactly as the initial page paints. `createContextualFragment` /
+* `innerHTML` / `DOMParser` are all DSD-UNAWARE by spec: they leave the `<template>` inert, so any host
+* that renders its box from inside its shadow paints at 0 height until its own runtime upgrades it (the
+* swap-then-blank-then-paint flicker). "Unsafe" means only "no sanitizer"; a region body is our own
+* signed, same-origin SSR (HOLE-TRUST), so it is exactly as trusted as the page itself.
+*
+* NOTE the parse happens in a `<template>`'s inert content, so custom elements do NOT upgrade here
+* (no `connectedCallback`) — attaching a declarative shadow root is a parse step, not an upgrade. That
+* is what `repair_if_drifted` needs: the server copy stays inert, but its light-DOM sequence is now
+* DSD-consistent with a live region whose hosts already carry shadow roots.
+*/
+function parse_region_html(html) {
+	const tpl = document.createElement("template");
+	const set_html_unsafe = tpl.setHTMLUnsafe;
+	if (typeof set_html_unsafe === "function") set_html_unsafe.call(tpl, html);
+	else {
+		tpl.innerHTML = html;
+		attach_declarative_shadows(tpl.content);
+	}
+	return tpl.content;
+}
+/** The spec's declarative-shadow-DOM attach step, for engines that render DSD on first parse but predate
+*  `setHTMLUnsafe`. Recurse into each shadow we attach: `querySelectorAll` stops at shadow boundaries,
+*  and a `<template shadowrootmode>` can nest inside another. First template per host wins (a host already
+*  carrying a shadow root is left as is). */
+function attach_declarative_shadows(root) {
+	for (const node of Array.from(root.querySelectorAll("template[shadowrootmode]"))) {
+		const tpl = node;
+		const host = tpl.parentElement;
+		tpl.remove();
+		if (!host || host.shadowRoot) continue;
+		const shadow = host.attachShadow({
+			mode: tpl.getAttribute("shadowrootmode") === "closed" ? "closed" : "open",
+			delegatesFocus: tpl.hasAttribute("shadowrootdelegatesfocus")
+		});
+		shadow.append(tpl.content);
+		attach_declarative_shadows(shadow);
+	}
+}
+/** The app's transform reshaped this markup (server/reversible.ts): restore it before anything reads
+*  it. The restorer is the page's own (the handle inlines it only when the app has a transform), so
+*  the runtime carries none of it — without one, this is a no-op. */
+function restore_markup(root) {
+	globalThis.__og_restore?.(root);
+}
+/** Adopt the keyed sheets of roots restored outside the page, right after their insertion. */
+function restore_adopt_sheets() {
+	globalThis.__og_restore_adopt?.();
+}
+/**
+* Shadow roots attached while the markup sat in an inert document — a declarative shadow root the
+* parse above attached, a restored one — get no custom element registry in a browser with scoped
+* registries, and keep none once inserted: nothing inside them upgrades (an element that calls
+* `attachInternals` in its constructor throws). Give each the page's registry, right after the
+* insertion. A browser without scoped registries never nulls it (and has no `initialize`): a no-op.
+*/
+function init_shadow_registries(under) {
+	const ce = customElements;
+	if (typeof ce.initialize !== "function") return;
+	const scopes = [under];
+	for (let q = 0; q < scopes.length; q++) {
+		const walk = document.createTreeWalker(scopes[q], 1);
+		for (let n = walk.nextNode(); n; n = walk.nextNode()) {
+			const sr = n.shadowRoot;
+			if (!sr) continue;
+			if (sr.customElementRegistry === null) ce.initialize(sr);
+			scopes.push(sr);
+		}
+	}
+}
+export { attach_declarative_shadows, init_shadow_registries, parse_region_html, restore_adopt_sheets, restore_markup };

package/dist/runtime/reconcile.d.ts

@@ -0,0 +1,41 @@
+import { endpoint_key, fingerprint_of, fnv1a, signature_of } from "./hash.js";
+/** The `<script data-ogygia-props>` seed text of a region — keyed at the end of the body or the
+ *  adjacent sibling (runtime/sidecar.ts) — or '' — the same lookup the hydrator uses, read-only.
+ *  SSR-stable across hydration. */
+export declare function region_props_text(el: Element): string;
+/** Match key for a rendered region element (which slot). */
+export declare function region_signature(el: Element): string;
+/**
+ * THE region identity — did its inputs change / which instance is this. ONE value, not a recompute:
+ * the server already emitted it as `data-og-fp` (Region.svelte), so READ that. Only fall back to
+ * computing it when the attribute is absent (a region type that doesn't emit it). Reading the
+ * server's value makes client↔server parity EXACT by construction — no divergence between
+ * `fingerprint_of(...)` here and the server's emit is possible, which is the correctness property
+ * the server-delta skip decision rides on.
+ */
+export declare function region_props_fp(el: Element): string;
+/** Stamp reconcile keys onto a root's regions + keep-chrome, without clobbering an authored key/id.
+ *  A region's key is signature+fingerprint (patch on either change); keep-chrome keys by keep name. */
+export declare function stamp_region_keys(root: ParentNode): void;
+/**
+ * SHADOW-DOM SAFETY: reconcile (querySelectorAll + morph) does NOT pierce shadow boundaries, so a
+ * region rendered INSIDE a shadow root (a web component's own template) would be invisible to it —
+ * morph would keep the stale host and never update that region. The router decides the fallback
+ * from a count, not a walk: the runtime keeps the set of CONNECTED regions (every region connects,
+ * shadow or light), the light DOM is one `querySelectorAll`; a mismatch means a region lives in a
+ * shadow root. An author forces the fallback with `data-og-no-reconcile` — the only thing checked
+ * here, on either document.
+ */
+export declare const NO_RECONCILE_SELECTOR = "[data-og-no-reconcile]";
+export declare function reconcile_body(live: Element, next: Element, morph: (parent: Element, nodes: ArrayLike<Node>) => void): void;
+/**
+ * outerSync body swap — the FALLBACK path (reconcile off, or a region trapped in a shadow root the
+ * morph can't pierce). The old code did `document.body.replaceWith(doc.body)`, which THROWS AWAY the
+ * live `<body>` element — and with it every listener, observer, and dataset value anything (Kit,
+ * analytics, a scroll library) attached to `document.body`. htmx 4 boosts land the same way and use
+ * `outerSync` for exactly this reason: keep the element, sync its attributes, replace its children.
+ * So we do too — the live body node survives, only its guts change. Incoming children are moved out
+ * of the parsed document (insertion adopts them across documents).
+ */
+export declare function swap_body(live: HTMLElement, next: HTMLElement): void;
+export { endpoint_key, fingerprint_of, fnv1a, signature_of };

package/dist/runtime/reconcile.js

@@ -0,0 +1,194 @@
+import { dispose_ids } from "../ref.js";
+import { boot_link, morph_sync_attributes } from "./slots.js";
+import { region_owned_ids } from "./region-ids.js";
+import { emit } from "../events/bus.js";
+import { endpoint_key, fingerprint_of, fnv1a, signature_of } from "./hash.js";
+// src/runtime/reconcile.ts
+/**
+* State-delta reconciler — R0: region identity + change detection (client-side, no SSR change).
+*
+* A navigation should MOVE regions, not reset them. To decide keep/patch/mount/remove per region
+* (R1), the reconciler needs two derived keys off each `<ogygia-region>` — computed purely from
+* attributes the compiler already emits (which is untouchable), never from live-mutated innerHTML:
+*
+*   • signature   — WHICH region slot this is (the match key). entry (component chunk) + the
+*                   endpoint's stable id/props part. Two regions with the same signature are
+*                   candidates for the same slot; document-order position (R1's diff) disambiguates
+*                   duplicate signatures.
+*   • props_fp    — DID ITS INPUTS CHANGE. A hash of the SSR seed: entry + endpoint + the
+*                   `<script data-ogygia-props>` text that follows the region. The seed is stable
+*                   across hydration (islands read it, never rewrite it), so comparing old↔new
+*                   props_fp answers "does the new page feed this region the same props?" — if yes,
+*                   the live island (which may hold interaction state the SSR html lacks) is the
+*                   source of truth and is KEPT; if no, the region is PATCHED.
+*
+* Pure and DOM-light: the hashing core takes strings so it unit-tests without a document.
+*/
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+const props_sidecar_of = (region) => boot_link().props_sidecar_of(region);
+/**
+* `<body>`'s attributes have two owners (runtime/ownership.ts): the server, page by page (a theme
+* class, a layout flag), and the scripts living on the page (a scroll lock, a consent banner's state,
+* an analytics marker). A navigation moves the server's attributes to the new page's — and removes
+* only those the PREVIOUS page's server sent that the new one doesn't. An attribute a script set is
+* not the server's to take away (before this, every navigation stripped them all). The server's set
+* starts as the body's attributes when this module loads, which the runtime does before the page's
+* own scripts (head-presence.ts puts it first).
+*/
+const attr_names = (el) => new Set(Array.from(el.attributes, (a) => a.name));
+let server_body_attrs = typeof document !== "undefined" && document.body ? attr_names(document.body) : null;
+function sync_body_attributes(live, next) {
+	morph_sync_attributes()(live, next, true);
+	if (server_body_attrs) {
+		for (const name of server_body_attrs) if (!next.hasAttribute(name)) live.removeAttribute(name);
+	}
+	server_body_attrs = attr_names(next);
+}
+/** The `<script data-ogygia-props>` seed text of a region — keyed at the end of the body or the
+*  adjacent sibling (runtime/sidecar.ts) — or '' — the same lookup the hydrator uses, read-only.
+*  SSR-stable across hydration. */
+function region_props_text(el) {
+	return props_sidecar_of(el)?.textContent ?? "";
+}
+/** Match key for a rendered region element (which slot). */
+function region_signature(el) {
+	return signature_of(el.getAttribute("entry") ?? "", el.getAttribute("endpoint") ?? "");
+}
+/**
+* THE region identity — did its inputs change / which instance is this. ONE value, not a recompute:
+* the server already emitted it as `data-og-fp` (Region.svelte), so READ that. Only fall back to
+* computing it when the attribute is absent (a region type that doesn't emit it). Reading the
+* server's value makes client↔server parity EXACT by construction — no divergence between
+* `fingerprint_of(...)` here and the server's emit is possible, which is the correctness property
+* the server-delta skip decision rides on.
+*/
+function region_props_fp(el) {
+	const emitted = el.getAttribute("data-og-fp");
+	if (emitted !== null && emitted !== "") return emitted;
+	return fingerprint_of(el.getAttribute("entry") ?? "", el.getAttribute("endpoint") ?? "", region_props_text(el));
+}
+const RECONCILE_KEY = "data-key";
+/** Stamp reconcile keys onto a root's regions + keep-chrome, without clobbering an authored key/id.
+*  A region's key is signature+fingerprint (patch on either change); keep-chrome keys by keep name. */
+function stamp_region_keys(root) {
+	for (const el of root.querySelectorAll("ogygia-region")) {
+		if (el.getAttribute(RECONCILE_KEY) !== null || el.id !== "") continue;
+		const keep = el.getAttribute("data-ogygia-keep");
+		if (keep !== null) el.setAttribute(RECONCILE_KEY, "k\0" + keep);
+		else if (el.hasAttribute("data-persist")) el.setAttribute(RECONCILE_KEY, "p\0" + region_signature(el));
+		else el.setAttribute(RECONCILE_KEY, "r\0" + region_props_fp(el));
+	}
+	for (const el of root.querySelectorAll("[data-ogygia-keep]")) {
+		if (el.getAttribute(RECONCILE_KEY) !== null || el.id !== "") continue;
+		el.setAttribute(RECONCILE_KEY, "k\0" + (el.getAttribute("data-ogygia-keep") ?? ""));
+	}
+}
+/**
+* SHADOW-DOM SAFETY: reconcile (querySelectorAll + morph) does NOT pierce shadow boundaries, so a
+* region rendered INSIDE a shadow root (a web component's own template) would be invisible to it —
+* morph would keep the stale host and never update that region. The router decides the fallback
+* from a count, not a walk: the runtime keeps the set of CONNECTED regions (every region connects,
+* shadow or light), the light DOM is one `querySelectorAll`; a mismatch means a region lives in a
+* shadow root. An author forces the fallback with `data-og-no-reconcile` — the only thing checked
+* here, on either document.
+*/
+const NO_RECONCILE_SELECTOR = "[data-og-no-reconcile]";
+/** Reconcile the live body toward the parsed next body IN PLACE (no replaceWith). `morph` is the
+*  keyed morpher (slots.morph / morph_children). After this, `live` IS the reconciled tree: matched
+*  regions kept live, changed regions re-mounted, shell morphed. Region ownership of hub ids (R3)
+*  lives in ./region-ids.ts. */
+/**
+* DEVTOOLS (nav lab): classify each region's fate under this reconcile — keep | patch | mount |
+* remove — and emit one `nav.reconcile` per region. Matched reconcile keys are KEPT; the rest are
+* grouped by SIGNATURE (which slot), so a same-slot pair (props changed → different fp key) reads as
+* a PATCH, a leftover old-only as REMOVE, a leftover new-only as MOUNT. Called only behind the gate,
+* before morph mutates the trees. Cheap: attribute reads + set math, once per nav.
+*/
+function dt_emit_reconcile(live, next) {
+	const key = (el) => el.getAttribute("data-key") ?? "";
+	const rec = (el, decision) => emit({
+		domain: "nav",
+		name: "nav.reconcile",
+		key: key(el),
+		decision,
+		entry: el.getAttribute("entry") ?? void 0,
+		wake: el.getAttribute("wake") ?? void 0
+	});
+	const live_els = Array.from(live.querySelectorAll("ogygia-region"));
+	const next_els = Array.from(next.querySelectorAll("ogygia-region"));
+	const live_keys = new Set(live_els.map(key));
+	const next_key_set = new Set(next_els.map(key));
+	for (const el of next_els) if (live_keys.has(key(el))) rec(el, "keep");
+	const group = (els, only) => {
+		const m = /* @__PURE__ */ new Map();
+		for (const el of els) {
+			if (only.has(key(el))) continue;
+			const sig = region_signature(el);
+			(m.get(sig) ?? m.set(sig, []).get(sig)).push(el);
+		}
+		return m;
+	};
+	const old_by_sig = group(live_els, next_key_set);
+	const new_by_sig = group(next_els, live_keys);
+	const sigs = /* @__PURE__ */ new Set([...old_by_sig.keys(), ...new_by_sig.keys()]);
+	for (const sig of sigs) {
+		const olds = old_by_sig.get(sig) ?? [];
+		const news = new_by_sig.get(sig) ?? [];
+		const pairs = Math.min(olds.length, news.length);
+		for (let i = 0; i < pairs; i++) rec(news[i], "patch");
+		for (let i = pairs; i < olds.length; i++) rec(olds[i], "remove");
+		for (let i = pairs; i < news.length; i++) rec(news[i], "mount");
+	}
+}
+function reconcile_body(live, next, morph) {
+	stamp_region_keys(live);
+	stamp_region_keys(next);
+	sync_body_attributes(live, next);
+	if (DEVTOOLS) dt_emit_reconcile(live, next);
+	const next_keys = /* @__PURE__ */ new Set();
+	for (const el of next.querySelectorAll("ogygia-region")) {
+		const k = el.getAttribute("data-key");
+		if (k !== null) next_keys.add(k);
+	}
+	const removed_ids = [];
+	for (const el of live.querySelectorAll("ogygia-region")) {
+		const k = el.getAttribute("data-key");
+		if (k !== null && next_keys.has(k)) continue;
+		const set = region_owned_ids(el);
+		if (set !== void 0) for (const id of set) removed_ids.push(id);
+	}
+	absorb_kept_props(live, next);
+	morph(live, next.childNodes);
+	if (removed_ids.length > 0) dispose_ids(removed_ids);
+}
+/**
+* outerSync body swap — the FALLBACK path (reconcile off, or a region trapped in a shadow root the
+* morph can't pierce). The old code did `document.body.replaceWith(doc.body)`, which THROWS AWAY the
+* live `<body>` element — and with it every listener, observer, and dataset value anything (Kit,
+* analytics, a scroll library) attached to `document.body`. htmx 4 boosts land the same way and use
+* `outerSync` for exactly this reason: keep the element, sync its attributes, replace its children.
+* So we do too — the live body node survives, only its guts change. Incoming children are moved out
+* of the parsed document (insertion adopts them across documents).
+*/
+function swap_body(live, next) {
+	sync_body_attributes(live, next);
+	live.replaceChildren();
+	while (next.firstChild) live.appendChild(next.firstChild);
+}
+/** For each live region whose reconcile key also appears in `next`, push the incoming region's
+*  props into the live island (kept regions only — a re-mounting region gets its props on mount). */
+function absorb_kept_props(live, next) {
+	const incoming = /* @__PURE__ */ new Map();
+	for (const el of next.querySelectorAll("ogygia-region")) {
+		const k = el.getAttribute("data-key");
+		if (k !== null && !incoming.has(k)) incoming.set(k, el);
+	}
+	for (const el of live.querySelectorAll("ogygia-region")) {
+		const k = el.getAttribute("data-key");
+		if (k === null) continue;
+		const twin = incoming.get(k);
+		const absorb = el.absorbKeptProps;
+		if (twin !== void 0 && twin !== el && typeof absorb === "function") absorb.call(el, twin);
+	}
+}
+export { NO_RECONCILE_SELECTOR, endpoint_key, fingerprint_of, fnv1a, reconcile_body, region_props_fp, region_props_text, region_signature, signature_of, stamp_region_keys, swap_body };

package/dist/runtime/region-attrs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * DOM attribute vocabulary for `<ogygia-region>` (DESIGN.md two axes).
+ *
+ * - `wake`    — when JS wakes: `none` | `load` | `idle` | `visible` | `interaction` | media query
+ * - `render`  — when HTML arrives: omit/`page` | `defer`
+ * - `when`    — schedule for `render="defer"` OR `remount="swr"` revalidate
+ * - `hydrate-margin` — IntersectionObserver rootMargin for phase-2 `wake="visible"`
+ * - `remount` — `{#if}` re-creation of `wake="none"`: `cache` | `empty` | `swr`
+ * - `max-age` — client lake-cache TTL in ms (optional)
+ * - `on-expire` — past max-age: `empty` | `fetch` (swr default `fetch`, cache default `empty`)
+ *
+ * No "island" / "lake" attribute names — those are nicknames, not the mechanism.
+ */
+/** CSS selector for frozen regions (`hydrate: 'none'`). */
+export declare const FROZEN_SELECTOR = "ogygia-region[wake=\"none\"]";
+/** True if this region is a wake boundary (JS will / did run for its subtree). */
+export declare function is_awake(el: Element): boolean;
+/** True if this region freezes its subtree (SSR DOM preserved; no client module). */
+export declare function is_frozen(el: Element): boolean;
+/** True if this region fetches HTML later (`render="defer"`). */
+export declare function is_deferred(el: Element): boolean;
+/**
+ * The regions whose INSIDE Kit's hydration never walks — OPAQUE to it, adopted as one element: a lake
+ * (frozen server HTML), a hole (a fallback, then an answer fetched after load — a region found inside
+ * one on a Kit-hydrated document came with that answer: the page's own fallback renders its islands
+ * inline, as Kit's), and a BAKED live region (its first HTML is server-only, morphed in after by the
+ * runtime). Their insides are ogygia's on every page: nothing else will wake them. The server twins:
+ * `isInLake()` (context.ts — set by LakeBoundary and on every render root whose HTML lands in one) and
+ * `region_kind` (reversible.ts).
+ */
+export declare const OPAQUE_SELECTOR = "ogygia-region[wake=\"none\"],ogygia-region[render=\"defer\"],ogygia-region[data-og-baked]";
+/** True if this region sits inside an {@link OPAQUE_SELECTOR opaque} region: on a Kit-hydrated
+ *  document nothing but the runtime will ever wake it. */
+export declare function inside_opaque(el: Element): boolean;
+/** Mixed mode (a csr=true document): Kit hydrates the tree, so an island there is Kit's — EXCEPT
+ *  what Kit never sees: a deferred region (its HTML is fetched after load) and anything inside an
+ *  opaque region (a lake, a hole's answer, a baked region's first HTML). Those are ours. */
+export declare function ours_on_kit_document(el: Element): boolean;
+/** `{#if}` remount policy for `wake="none"` regions. Default `cache`. */
+export declare function region_remount(el: Element): "cache" | "empty" | "swr";
+/** Client lake-cache TTL in ms from `max-age`. `0` = no expiry. */
+export declare function region_max_age_ms(el: Element): number;
+/**
+ * Past-maxAge behavior. Defaults: `cache` → `empty`, `swr` → `fetch`.
+ * `fetch` is only meaningful with `remount="swr"` (endpoint present).
+ */
+export declare function region_on_expire(el: Element): "empty" | "fetch";
+/**
+ * True when a frozen region has only Svelte placeholder anchors (comments / whitespace).
+ * Used by remount: a text-only lake is still "filled" — `querySelector('*')` would miss it and
+ * double-append the cache on reconnect (REMOUNT-VACANT).
+ */
+export declare function region_is_vacant(el: ParentNode): boolean;
+/** True when this document was SERVED FROM a page store (a plugin stamps the hit/join copies with
+ *  `STORED_DOCUMENT_META`). A stored copy is a cached render by definition — swr lakes read this to
+ *  revalidate on FIRST mount, not only on remounts. */
+export declare function document_is_stored(): boolean;
+/**
+ * True when the browser's HTML parser tore this placed island's SSR content OUT of the region —
+ * the invalid-nesting hoist.
+ *
+ * A block-rendering island authored INLINE inside a `<p>` (e.g. a `<Counter/>` sitting in a markdown
+ * sentence, where the component renders `<div>…</div>`) is invalid HTML: a `<div>` start tag while a
+ * `<p>` is in button scope makes the parser CLOSE the paragraph, popping this `<ogygia-region>` with
+ * it — the region is left holding only its opening Svelte hydration anchors (`<!--[-->`), while the
+ * rendered nodes (and the closing anchors) become siblings of the paragraph. Hydrating that empty
+ * region then fresh-mounts a SECOND copy, and the hoisted server copy lingers as an orphan → the
+ * page shows the island twice.
+ *
+ * Detected as an UNBALANCED hydration envelope: strictly more `[` open anchors than `]` close anchors
+ * among the region's descendants. A validly-nested region (inline content, or block content in block
+ * context) always balances; a region that renders nothing balances (0 == 0); a not-yet-swapped
+ * deferred/live region carries no anchors at all (0 == 0). So this never false-positives on a
+ * correctly-parsed region — only the parser-truncated envelope reads open > close.
+ */
+export declare function region_ssr_truncated(el: ParentNode): boolean;
+/**
+ * Schedule string for the shared scheduler.
+ * Deferred regions use `when`; waking regions use `wake`; default `load`.
+ */
+export declare function region_schedule(el: Element): string;
+/**
+ * Wake schedule from `wake`, or `null` when this region does not run JS
+ * (`wake` absent / `'none'`). Used after a deferred HTML swap for phase 2.
+ */
+export declare function region_hydrate_schedule(el: Element): string | null;
+/**
+ * Phase-2 (post-swap) hydrate schedule for a deferred client island.
+ *
+ * - Matching schedules (`load`/`load`, `idle`/`idle`, `visible`/`visible`, same media) → `'load'`
+ *   (hydrate immediately; do not re-arm the same idle / IO / MQ).
+ * - `hydrate: 'load'` after any defer → `'load'` (ASAP after swap).
+ * - Otherwise arm hydrate’s own schedule only.
+ */
+export declare function phase2_hydrate_schedule(defer_when: string, hydrate: string): string;