@ogygia/core 0.0.0 → 0.11.1

package/dist/runtime/hydrate-core.js

@@ -0,0 +1,605 @@
+import { set_current_region, set_foreign_hydrate } from "../current-region.js";
+import { capture_region_ids } from "./region-ids.js";
+import { foreign_region_prop_revivers } from "./foreign-props.js";
+import { SEED_REF_KEY, seed_ref_reviver } from "../seed-refs.js";
+import { parse_sidecar_text, seed_data_of, seed_page_once, seed_remote_once } from "./seeds.js";
+import { is_deferred, ours_on_kit_document, region_ssr_truncated } from "./region-attrs.js";
+import { boot_link, slots } from "./slots.js";
+import { keep_host_classes, note_host_classes } from "./host-classes.js";
+import { emit } from "../events/bus.js";
+import { kit_page_thread } from "./kit-page-thread.svelte.js";
+import { hydrate, unmount } from "svelte";
+import NestedProvider from "../NestedProvider.svelte";
+import { install } from "virtual:ogygia/hydrate-features";
+// src/runtime/hydrate-core.ts
+/**
+* THE HYDRATE CORE — everything an island needs only at the moment it hydrates: Svelte's
+* `hydrate`/`unmount`, the `NestedProvider` host, the devalue props parse, the page seed, the
+* DEV props guard. Loaded LAZILY by the region element on its first `#hydrate` (one dynamic
+* import, shared by every island), so a page whose islands all wake on `visible` or `interaction`
+* boots the runtime WITHOUT fetching Svelte's client runtime — that arrives with the first island
+* that actually wakes, together with the island's own chunk. The always-on core (`core.ts`) keeps
+* only what every region needs at connect: the schedule, the observers, the hole fetch.
+*
+* Stateless towards the element: the element owns its handle (`IslandHandle`) and its flags; this
+* module owns the how.
+*/
+install();
+const kit_hydrates_page = () => boot_link().kit_hydrates_page();
+const props_sidecar_of = (region) => boot_link().props_sidecar_of(region);
+const parse_region_html = (html) => boot_link().parse_region_html(html);
+const walk_enters = (el) => boot_link().walk_enters(el);
+const is_self_owned = (el) => boot_link().is_self_owned(el);
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+/** The morph target for hydration repair: the server sequence Svelte's walk binds — see `repair_markup`. */
+const REPAIR_MORPH = { target: "walk" };
+/** The hydration ENVELOPE: `hydrate()` anchors on a top-level `<!--[-->` comment and then expects
+*  the component's OWN region envelope — but embedded SSR (Region.svelte) emits only the inner
+*  layer. Idempotent: the second attempt after a failed first one finds it in place. */
+function ensure_envelope(region) {
+	if (has_envelope(region)) return;
+	region.insertBefore(document.createComment("["), region.firstChild);
+	region.appendChild(document.createComment("]"));
+}
+function has_envelope(region) {
+	const first = region.firstChild;
+	return !!first && first.nodeType === 8 && first.data === "[";
+}
+/** Set the first time {@link neutralize_head_hydration_markers} runs on this document (once per page). */
+let head_markers_neutralized = false;
+/**
+* MAKE `<svelte:head>` HYDRATION SAFE on a csr=false document, before any island's head effect runs.
+* The caller runs this once per document (see the `head_markers_neutralized` guard at its call site).
+*
+* Svelte renders a component's `<svelte:head>` into `document.head`, not into the component's own
+* DOM, and delimits each block there as `<!--HASH-->` …content… `<!---->` (svelte/internal/server
+* `head()`). Its CLIENT `head(HASH, …)` hydrates by scanning document.head for the comment whose data
+* is HASH, then walking the nodes right after it as that block's content. That contract holds for a
+* whole-page hydrate (csr=true — Kit owns it, and this function never runs), but an ogygia island
+* hydrates in ISOLATION while that scan still reads the ONE shared document.head. By island-wake time
+* a third party has usually mutated the head (a design-system/monitoring inject, a hoisted sheet); a
+* foreign node landing in a block's range desyncs the walk into `set_attribute()` on a non-element,
+* which throws and discards the ENTIRE island (it never wakes). Note ogygia already keeps its OWN
+* head writes off this range by inserting region sheets at the head TOP (core.ts) — this closes the
+* same hole for head writes ogygia does not control.
+*
+* The fix is Svelte's own documented fallback: when `head()` finds no matching HASH marker it flips
+* out of hydration mode and RE-RENDERS the block fresh (svelte-head.js, `head_anchor === null`).
+* Removing the open markers up front takes every island's head down that safe path instead of the
+* fragile walk. The SSR-rendered head ELEMENTS stay (correct, already applied — sheets loaded, title
+* set) until the island's own live copy exists; then the island owns its head content and the
+* page's copy is retired (runtime/session.ts — who owns each node in <head>, and the one-copy rule).
+*
+* A head block is `<!--HASH-->` …content… `<!---->` — the HASH open and the empty close both sit at
+* the head's TOP LEVEL, while the content in between may carry Svelte's own block anchors when the head
+* is looped or branched: `{#if}`/`{#each}`/`{:else}` emit `<!--[-->` / `<!--[!-->` / `<!--[?-->` opens
+* and `<!--]-->` closes (svelte constants HYDRATION_START… and HYDRATION_END). So the open markers are found
+* by walking head's DIRECT children while tracking bracket depth: a comment whose data starts with `[`
+* is a block open (depth+1), `]` is a block close (depth−1), and at depth 0 a non-bracket, non-empty
+* comment is a head-block HASH open — confirmed when a depth-0 empty `<!---->` later closes its block.
+* That confirmation is what tells a real head marker from a lone third-party head comment (which has no
+* depth-0 empty close), so only genuine markers are removed; page/layout head blocks keep every rendered
+* element (their inert markers go), and element children are never descended into.
+*/
+function neutralize_head_hydration_markers() {
+	const head = typeof document !== "undefined" ? document.head : null;
+	if (!head) return;
+	let depth = 0;
+	let pending_open = null;
+	const to_remove = [];
+	for (let n = head.firstChild; n; n = n.nextSibling) {
+		if (n.nodeType !== 8) continue;
+		const data = n.data;
+		if (data[0] === "[") {
+			depth++;
+			continue;
+		}
+		if (data === "]") {
+			if (depth > 0) depth--;
+			continue;
+		}
+		if (depth !== 0) continue;
+		if (data === "") {
+			if (pending_open) {
+				to_remove.push(pending_open);
+				pending_open = null;
+			}
+		} else pending_open = n;
+	}
+	for (const m of to_remove) m.remove();
+}
+/**
+* REPAIR the island's light DOM toward its server markup, keeping every element it still has.
+*
+* Svelte's walk cares about the node SEQUENCE (elements, text, comments), never about attributes.
+* The edits sleeping islands actually receive keep the element skeleton and touch what is between
+* the elements: a design-system runtime strips the whitespace text nodes, an A/B tool leaves a
+* comment. So: match the live elements to the server markup's elements one to one (same count,
+* same tags, recursively), and rebuild only the text and comment nodes around them from the server
+* copy. No element is created, so no upgraded custom element reacts — the design-system element
+* that re-strips the island on every connect (measured on a customer deploy) is left exactly where
+* it is, and the walk that follows sees the server's sequence.
+*
+* Only when the element skeleton itself differs (an element removed or added) does the repair fall
+* to the morph (existing nodes still keep their identity where the morph can match them), or to a
+* plain `innerHTML` swap where the runtime has no morph. Those paths may re-create an element, and
+* a re-created element may react once more; the second attempt tells.
+*
+* The morph runs in its STRICT contract here ({@link REPAIR_MORPH}): the target is the server's node
+* sequence, exactly. The live morph's "a self-owned element keeps the children it gave itself" rule is
+* right for a hole re-answer, but in a repair it is the residue that breaks the walk — a node a
+* web-component runtime added inside a nested custom element is exactly what Svelte's cursor then
+* lands on (`getAttribute is not a function`), and the island discards.
+*/
+function repair_markup(region, want) {
+	if (align_to(region, want)) return;
+	const nodes = Array.from(want.childNodes);
+	const morph = slots.morph;
+	if (morph) morph(region, nodes, REPAIR_MORPH);
+	else region.replaceChildren(...nodes);
+}
+/**
+* Does the live node SEQUENCE differ from the server's? Exactly what Svelte's walk reads: node
+* types, element tags, text and comment data, recursively — never attributes (a custom element
+* upgrading adds `tabindex`, `aria-*`, ids; the walk does not care, and neither does this).
+*
+* Asked BEFORE the first hydrate attempt, not after a failed one: Svelte's walk does not verify
+* tags, so on a shifted sequence it writes attributes onto whatever node sits at its cursor —
+* measured on a customer deploy, the login trigger's `id`/`class`/`text` landed on the dropdown's
+* wrapper `<div>` — and only throws further down. A repair that came after would put the text
+* nodes back and leave those attributes on the wrong elements (an unstyled dropdown). Repairing
+* first, the walk never runs on the edited sequence.
+*/
+function sequence_differs(live, want) {
+	const a = live.childNodes;
+	const b = want.childNodes;
+	if (a.length !== b.length) return true;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		const y = b[i];
+		if (x.nodeType !== y.nodeType) return true;
+		if (x.nodeType === 1) {
+			if (x.tagName !== y.tagName) return true;
+			if (walk_enters(x) && sequence_differs(x, y)) return true;
+		} else if (x.nodeValue !== y.nodeValue) return true;
+	}
+	return false;
+}
+/** Any non-whitespace char? A char-code scan, not `/\S/` — this walks on every drift check. */
+function has_non_ws(s) {
+	if (!s) return false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c !== 32 && c !== 9 && c !== 10 && c !== 12 && c !== 13) return true;
+	}
+	return false;
+}
+/** A short label for a node in a divergence message: the tag for an element, else its kind. */
+function node_label(n) {
+	if (n.nodeType === 1) return `<${n.tagName.toLowerCase()}>`;
+	if (n.nodeType === 3) return has_non_ws(n.nodeValue) ? "a text node" : "whitespace";
+	if (n.nodeType === 8) return "a comment";
+	return "a node";
+}
+/** A guess at WHAT left a foreign node in the region's light DOM, read off the node's shape — the
+*  tell-tales of the passes that reshape a region between SSR and wake: a scoped-CSS or web-component
+*  runtime, a declarative-shadow-DOM injector, a whitespace normalizer. Names the observable evidence
+*  (a tag, an attribute pattern), never a specific tool. The "why" a recovery is otherwise silent
+*  about; empty when nothing recognizable. */
+function culprit_hint(n) {
+	if (n.nodeType !== 1) return "";
+	const el = n;
+	const tag = el.tagName.toLowerCase();
+	if (tag === "style") return " — an injected <style> (scoped CSS from a component/design-system runtime)";
+	if (tag === "template" && el.hasAttribute("shadowrootmode")) return " — a declarative shadow-DOM template injected after SSR";
+	for (const a of el.attributes) if (a.name.startsWith("sc-") || a.name === "s-id" || a.name === "c-id" || a.name === "s-sn") return " — scoped web-component hydration marks (sc-*, s-id, c-id) a component runtime stamped over the island";
+	if (el.classList.contains("hydrated")) return " — a web-component runtime marked it `hydrated`";
+	return "";
+}
+/** Describe the FIRST place the live light DOM diverges from `want` (the server copy) — the specific
+*  reason an island drifted, for the DEV console + devtools (never a bare "it was recovered"). Mirrors
+*  {@link sequence_differs}' walk exactly, so it names the divergence that trips the repair. `null`
+*  when the sequences match. DEV / devtools only — prod DCEs the call site, so this never runs there. */
+function describe_divergence(live, want, where = "the island") {
+	const a = live.childNodes;
+	const b = want.childNodes;
+	if (a.length !== b.length) {
+		const longer = a.length > b.length ? a : b;
+		const shorter = a.length > b.length ? b : a;
+		let i = 0;
+		while (i < shorter.length && longer[i].nodeType === shorter[i].nodeType && (longer[i].nodeType !== 1 || longer[i].tagName === shorter[i].tagName)) i++;
+		const node = longer[i] ?? longer[longer.length - 1];
+		if (a.length > b.length) return `${a.length - b.length} node(s) were inserted into ${where} — e.g. ${node_label(node)}${culprit_hint(node)}`;
+		const ws = node.nodeType === 3 && !has_non_ws(node.nodeValue);
+		return `${b.length - a.length} node(s) the server sent were removed from ${where} — e.g. ${node_label(node)}${ws ? " (whitespace stripped by a DOM-normalizing pass)" : ""}`;
+	}
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		const y = b[i];
+		if (x.nodeType !== y.nodeType || x.nodeType === 1 && x.tagName !== y.tagName) return `${where}: the server sent ${node_label(y)} but the browser had ${node_label(x)}${culprit_hint(x)}`;
+		if (x.nodeType === 1) {
+			if (!walk_enters(x)) continue;
+			const deeper = describe_divergence(x, y, node_label(x));
+			if (deeper) return deeper;
+		} else if (x.nodeValue !== y.nodeValue) return `${where}: the text of ${node_label(y)} changed (a translator or text rewrite)`;
+	}
+	return null;
+}
+/** The first ownership conflict the current repair met (DEV / devtools read it), or `null`. */
+let conflict = null;
+function note_conflict(el) {
+	conflict ??= `${node_label(el)} is a web component that changed its own children in a position Svelte's hydration reads, so the repair had to remove the nodes it added. Render that subtree with {@html} or as static markup (Svelte never reads inside it), put it in a lake (wake: 'none'), or mark the element data-ogygia-keep.`;
+}
+/** Put the island's light DOM back to the server's node sequence when it drifted while the island
+*  slept. Returns whether a repair was made and, in DEV / devtools, WHY it drifted (the first
+*  divergence, named before the repair rewrites the sequence). Called with the island's lakes LIFTED
+*  (lakes.ts): a lake's content is never part of the walk, and it may legitimately differ from the
+*  server copy by now (a live lake refreshes itself to the visitor before its host wakes) — so the
+*  copy's direct lakes are emptied the same way before the comparison, and the repair never touches
+*  them. */
+function repair_if_drifted(region, ssr_html) {
+	const content = parse_region_html(ssr_html);
+	const want = content.ownerDocument.createElement("ogygia-region");
+	want.appendChild(content);
+	slots.lakes.lift(want);
+	if (!sequence_differs(region, want)) return {
+		repaired: false,
+		reason: null,
+		conflict: null
+	};
+	const reason = import.meta.env.DEV || DEVTOOLS ? describe_divergence(region, want) : null;
+	conflict = null;
+	repair_markup(region, want);
+	const met = conflict;
+	conflict = null;
+	return {
+		repaired: true,
+		reason,
+		conflict: met
+	};
+}
+/** Make `live`'s child sequence the server's (`want`), keeping `live`'s elements. `false` when the
+*  element skeleton differs (no changes made at that level). */
+function align_to(live, want) {
+	const live_elements = element_children(live);
+	const want_elements = element_children(want);
+	if (live_elements.length !== want_elements.length) return false;
+	for (let i = 0; i < live_elements.length; i++) if (live_elements[i].tagName !== want_elements[i].tagName) return false;
+	for (let i = 0; i < live_elements.length; i++) {
+		const child = live_elements[i];
+		if (!walk_enters(child)) continue;
+		if (!align_to(child, want_elements[i])) {
+			if (is_self_owned(child)) note_conflict(child);
+			const morph = slots.morph;
+			if (morph) morph(child, Array.from(want_elements[i].childNodes), REPAIR_MORPH);
+			else child.innerHTML = want_elements[i].innerHTML;
+		}
+	}
+	for (const node of Array.from(live.childNodes)) if (node.nodeType !== 1) node.remove();
+	let next = 0;
+	for (const node of Array.from(want.childNodes)) {
+		if (node.nodeType === 1) {
+			next++;
+			continue;
+		}
+		const before = live_elements[next] ?? null;
+		live.insertBefore(node.cloneNode(true), before);
+	}
+	return true;
+}
+function element_children(node) {
+	const out = [];
+	for (const child of node.childNodes) if (child.nodeType === 1) out.push(child);
+	return out;
+}
+/** Svelte's own line from inside its hydrate catch, printed BEFORE it throws `hydration_failed`
+*  to us. A speculative attempt (recovery off) is ours to report — healed, or handed to Svelte's
+*  recovery, which prints its own line then. Swallow exactly this message for the synchronous
+*  duration of such an attempt, nothing else. */
+const SVELTE_FAILED_TO_HYDRATE = "Failed to hydrate";
+function quietly(fn) {
+	const warn = console.warn;
+	console.warn = (...args) => {
+		if (typeof args[0] === "string" && args[0].startsWith(SVELTE_FAILED_TO_HYDRATE)) return;
+		warn.apply(console, args);
+	};
+	try {
+		return fn();
+	} finally {
+		console.warn = warn;
+	}
+}
+const HEALED_WARNING = "[ogygia] island \"%s\" was edited while it slept (its light DOM no longer matched the server render — a design-system runtime, an A/B tool, a translator), so its server HTML was put back and hydrated instead of re-rendering it client-side. Whatever the edit added is gone; the script that made it should leave <ogygia-region> subtrees alone.";
+/** Is this entry another build's (fragment federation): absolute, different origin. */
+function is_foreign_entry(entry) {
+	return boot_link().ABSOLUTE_URL_SCHEME.test(entry) && new URL(entry).origin !== location.origin;
+}
+let cached_wire;
+let cached_revivers;
+function region_prop_revivers() {
+	const wire = slots.wire;
+	if (wire === cached_wire) return cached_revivers;
+	cached_wire = wire;
+	cached_revivers = wire ? { [wire.REF_WIRE_KEY]: (d) => wire.resolve(d, true) } : { OgygiaRef: () => {
+		throw new Error("wired prop but no wire feature in this build — ogygia detection bug, please report");
+	} };
+	return cached_revivers;
+}
+/**
+* Parse a region's `<script data-ogygia-props>` sidecar (keyed at the end of the body, or adjacent —
+* runtime/sidecar.ts). Uses the client reviver (`remember: true`) so a named/shared transportable
+* reunites with its live instance. Returns `{}` when there is no props sidecar.
+*/
+function read_region_props(region, foreign = false) {
+	const sidecar = props_sidecar_of(region);
+	if (!sidecar) return {};
+	const base = foreign ? foreign_region_prop_revivers() : region_prop_revivers();
+	const doc = sidecar.ownerDocument;
+	const revivers = foreign ? base : {
+		...base,
+		[SEED_REF_KEY]: seed_ref_reviver(() => seed_data_of(doc))
+	};
+	return parse_sidecar_text(sidecar, revivers);
+}
+/**
+* DEV-ONLY props mutation guard. Island props cross the boundary as a serialized devalue snapshot
+* of the host — or, for a seed REFERENCE, as the page seed's own node, shared by reference with
+* `page.data` and every other island that references it. Writing to either inside the island is a
+* bug: the snapshot updates nothing, the reference leaks into page.data.
+*/
+var PropMutationGuard = class {
+	#warned = /* @__PURE__ */ new Set();
+	#warn(entry, prop_path) {
+		const key = entry + "" + prop_path;
+		if (this.#warned.has(key)) return;
+		this.#warned.add(key);
+		console.warn(`[ogygia] mutating prop '${prop_path}' inside island ${entry} — island props are a serialized snapshot of the host, or a reference into page.data shared with every island that reads it: the write updates nothing (or leaks into page.data). Move mutable state inside the island component.`);
+	}
+	#guard_map(map, entry, prop_path) {
+		const mutators = /* @__PURE__ */ new Set([
+			"set",
+			"delete",
+			"clear"
+		]);
+		return new Proxy(map, { get: (target, prop) => {
+			const value = Reflect.get(target, prop);
+			if (typeof value !== "function") return value;
+			if (typeof prop === "string" && mutators.has(prop)) return (...args) => {
+				this.#warn(entry, `${prop_path}.${prop}()`);
+				return value.apply(target, args);
+			};
+			return value.bind(target);
+		} });
+	}
+	#guard_set(set, entry, prop_path) {
+		const mutators = /* @__PURE__ */ new Set([
+			"add",
+			"delete",
+			"clear"
+		]);
+		return new Proxy(set, { get: (target, prop) => {
+			const value = Reflect.get(target, prop);
+			if (typeof value !== "function") return value;
+			if (typeof prop === "string" && mutators.has(prop)) return (...args) => {
+				this.#warn(entry, `${prop_path}.${prop}()`);
+				return value.apply(target, args);
+			};
+			return value.bind(target);
+		} });
+	}
+	#guard_value(value, entry, prop_path) {
+		if (value === null || typeof value !== "object") return value;
+		if (value instanceof Map) return this.#guard_map(value, entry, prop_path);
+		if (value instanceof Set) return this.#guard_set(value, entry, prop_path);
+		if (value instanceof Date || value instanceof RegExp || value instanceof URL) return value;
+		const proto = Object.getPrototypeOf(value);
+		if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) return value;
+		return new Proxy(value, {
+			get: (target, prop, receiver) => {
+				const child = Reflect.get(target, prop, receiver);
+				if (typeof prop === "symbol") return child;
+				return this.#guard_value(child, entry, prop_path ? `${prop_path}.${String(prop)}` : String(prop));
+			},
+			set: (target, prop, next, receiver) => {
+				if (typeof prop !== "symbol") this.#warn(entry, prop_path ? `${prop_path}.${String(prop)}` : String(prop));
+				return Reflect.set(target, prop, next, receiver);
+			},
+			deleteProperty: (target, prop) => {
+				if (typeof prop !== "symbol") this.#warn(entry, prop_path ? `${prop_path}.${String(prop)}` : String(prop));
+				return Reflect.deleteProperty(target, prop);
+			},
+			defineProperty: (target, prop, descriptor) => {
+				if (typeof prop !== "symbol") this.#warn(entry, prop_path ? `${prop_path}.${String(prop)}` : String(prop));
+				return Reflect.defineProperty(target, prop, descriptor);
+			}
+		});
+	}
+	wrap(props, entry) {
+		if (!(import.meta.env && import.meta.env.DEV)) return props;
+		return this.#guard_value(props, entry, "");
+	}
+};
+const prop_guard = new PropMutationGuard();
+/** Svelte's `unmount`, typed for the opaque app this module hands around. */
+const unmount_app = (app) => void unmount(app);
+/** A handle over a mounted Svelte app: dispose unmounts, `set_props` pushes through a host. */
+function handle(app, dispose_with, entry, host) {
+	const h = { dispose() {
+		try {
+			dispose_with(app);
+		} catch {}
+	} };
+	if (host) {
+		const live = app;
+		h.set_props = (props) => live.setProps?.(prop_guard.wrap(props, entry));
+	}
+	return h;
+}
+/**
+* THE island hydrate step — synchronous from here on (the element already awaited the module and
+* its scheduler turn): seeds, props, envelope, `hydrate()` through the provider, lake restore,
+* the mutation detector. Returns the handle, or `null` when the island is not ours to hydrate (a
+* Kit-hydrated page — marked `data-kit-hydrated`). Throws on a failed hydrate; the element reports.
+*/
+function hydrate_island(region, entry, mod, ssr_html = null, touched = true) {
+	seed_remote_once();
+	seed_page_once();
+	const Component = mod.default;
+	const foreign = is_foreign_entry(entry);
+	const props = capture_region_ids(region, () => read_region_props(region, foreign));
+	if (kit_hydrates_page() && !ours_on_kit_document(region)) {
+		region.setAttribute("data-kit-hydrated", "");
+		if (import.meta.env.DEV) console.warn(`[ogygia] island "${entry}" is on a csr=true page; Kit hydrates it, so the island directive is redundant here (it behaves as a normal component).`);
+		return null;
+	}
+	if (!kit_hydrates_page() && !head_markers_neutralized) {
+		head_markers_neutralized = true;
+		neutralize_head_hydration_markers();
+	}
+	if (import.meta.env.DEV && !is_deferred(region) && region_ssr_truncated(region)) console.warn(`[ogygia] island "${entry}" rendered a BLOCK element inline inside a <p> (or other phrasing-only context). The browser's HTML parser hoisted that block out of the paragraph before hydration, so this region is empty and a SECOND copy is about to mount here — the server-rendered copy is now an orphaned sibling of the paragraph. Fix: make the component render an inline element (e.g. <span> instead of <div>), or place the island on its own line (block context) rather than inside a sentence.`);
+	const head_before = new Set(document.head.children);
+	let lifted = slots.lakes.lift(region);
+	const drift = ssr_html !== null && touched && region.isConnected ? repair_if_drifted(region, ssr_html) : {
+		repaired: false,
+		reason: null,
+		conflict: null
+	};
+	const repaired = drift.repaired;
+	try {
+		if (!region.isConnected) return null;
+		const ssr_children = Array.from(region.children);
+		const foreign_delegate = foreign && typeof mod.__og_hydrate === "function";
+		const wrapped = foreign ? props : prop_guard.wrap(props, entry);
+		const KeepHost = slots.keep ?? slots.live;
+		const keep = region.hasAttribute("data-ogygia-keep") && !!KeepHost;
+		if (keep && import.meta.env.DEV && !document.querySelector("meta[name=\"ogygia-router\"]")) console.warn(`[ogygia] island "${entry}" has keep:'${region.getAttribute("data-ogygia-keep")}' but the SPA router is off (ogygia({ router: false })) — keep relies on SPA navigation; a full-page load replaces the DOM, so the attribute is a no-op here.`);
+		/**
+		* ONE hydrate attempt. `recover: false` makes Svelte THROW on a mismatch (`hydration_failed`)
+		* instead of silently discarding the server DOM and re-rendering — that silent path is what
+		* the self-heal below replaces; `recover: true` is that path, the last resort.
+		*
+		* Hydration envelope: `render()` (region endpoint / deferred swap) has BOTH anchor layers —
+		* do not wrap again or hydration mismatches. (Verified against svelte 5.56.) Hydrate through
+		* NestedProvider so descendants see the "inside a hydrated island" context — any nested
+		* island wrapper then degrades to a plain inline component (single hydration with this
+		* parent). The provider adds no DOM, so this matches SSR.
+		*/
+		const attempt = (recover) => {
+			if (!is_deferred(region) && !foreign_delegate) ensure_envelope(region);
+			set_current_region(region);
+			try {
+				if (foreign_delegate) {
+					set_foreign_hydrate({
+						origin: new URL(entry).origin,
+						entry
+					});
+					return handle(mod.__og_hydrate(region, wrapped, recover ? void 0 : { recover: false }), mod.__og_unmount ?? (() => {}), entry, false);
+				}
+				const provided_ctx = capture_region_ids(region, () => slots.context?.(region));
+				const recovery = recover ? {} : { recover: false };
+				if (keep) return handle(hydrate(KeepHost, {
+					target: region,
+					props: {
+						component: Component,
+						initialProps: wrapped
+					},
+					...provided_ctx ? { context: provided_ctx } : {},
+					...recovery
+				}), unmount_app, entry, true);
+				return handle(hydrate(NestedProvider, {
+					target: region,
+					props: {
+						component: Component,
+						props: wrapped
+					},
+					...provided_ctx ? { context: provided_ctx } : {},
+					...recovery
+				}), unmount_app, entry, false);
+			} finally {
+				set_current_region(null);
+				set_foreign_hydrate(null);
+			}
+		};
+		let out;
+		let healed = false;
+		let strict_error = null;
+		const host_classes = note_host_classes(region);
+		try {
+			out = quietly(() => attempt(false));
+			healed = repaired;
+		} catch (err) {
+			strict_error = err;
+			out = attempt(true);
+		}
+		keep_host_classes(host_classes);
+		if (healed) {
+			region.setAttribute("data-og-healed", drift.reason || "");
+			if (DEVTOOLS) emit({
+				domain: "runtime",
+				name: "region.hydrate.healed",
+				entry,
+				fp: region.getAttribute("data-og-fp") || void 0,
+				reason: drift.reason || void 0
+			});
+			if (import.meta.env.DEV) console.warn(HEALED_WARNING + (drift.reason ? `\nWhat drifted: ${drift.reason}` : ""), entry);
+		}
+		if (drift.conflict) {
+			if (DEVTOOLS) emit({
+				domain: "runtime",
+				name: "region.hydrate.conflict",
+				entry,
+				fp: region.getAttribute("data-og-fp") || void 0,
+				reason: drift.conflict
+			});
+			if (import.meta.env.DEV) console.warn(`[ogygia] ${drift.conflict}`, entry);
+		}
+		slots.lakes.restore(region, lifted);
+		lifted = null;
+		if (!region.isConnected) {
+			out.dispose();
+			return null;
+		}
+		if (ssr_children.length > 0 && !ssr_children.some((el) => region.contains(el))) {
+			region.setAttribute("data-og-recovered", drift.reason || "");
+			if (DEVTOOLS) emit({
+				domain: "runtime",
+				name: "region.hydrate.recovered",
+				entry,
+				fp: region.getAttribute("data-og-fp") || void 0,
+				reason: drift.reason || void 0
+			});
+			console.warn(`[ogygia] island "${entry}" discarded its ENTIRE server-rendered DOM during hydration and re-rendered client-side (Svelte hydration-mismatch recovery). Three things cause this. (1) Something changed this region's HTML between SSR and wake — a post-SSR transform (transformPageChunk / an HTML-rewriting middleware), an A/B-testing snippet, or an edge rewriter; whatever it injected (e.g. declarative shadow DOM) was just destroyed, and the swap is timing-dependent, so symptoms look erratic. (2) A component in this island reads a page/layout CONTEXT via plain Svelte setContext — on csr=false that runs only on the server, so getContext returns undefined on the client and the island renders a different tree. (3) A block in this island ({#if} / {:else if} / {#each} / {#await}) took a DIFFERENT branch on the client than on the server — its condition reads something that differs between the two (a browser global, a store's client default, url/page state, a Date). Svelte recovers a branch mismatch SILENTLY (no throw); the walk is then off and the rest of the tree follows.` + (drift.reason ? `\nWhat changed: ${drift.reason}` : "") + (strict_error ? `\nSvelte threw on the strict attempt (after repair): ${strict_error instanceof Error ? strict_error.message : String(strict_error)}` : drift.reason ? `\nSvelte did not throw after the repair — the mismatch is one this walk does not model.` : "\nThe server node sequence was INTACT and Svelte did not throw: nothing mutated this region's DOM, so this is (3) (or (2)). Find the block whose branch differs: in the server markup its anchor reads <!--[N--> where N is the branch the SERVER chose.") + "\nFix: for (1) make the mutation invisible to hydration (mutate only <head>, attributes, or shadow templates — never the region's light DOM), or freeze the foreign-owned subtree with a wake:'none' (lake) boundary; for (2) provide the value with setContext / <Provide> / createContext imported from 'ogygia', read it with the same getContext(key); for (3) make the condition read the same value on both sides (a prop / page.data), or move the browser-only branch behind an $effect / hydratedBy().");
+		}
+		if (!kit_hydrates_page()) boot_link().runtime_session.record_island_head(head_before);
+		return out;
+	} finally {
+		if (lifted) slots.lakes.restore(region, lifted);
+	}
+}
+/**
+* Hydrate a live region's swapped-in HTML through {@link LiveHost} (props-pushable). A live region's
+* HTML comes from svelte `render()` (both envelope layers) — same as the deferred swap path, so it
+* is NOT wrapped in extra `[..]` hydration comments. `null` when the live feature is absent.
+*/
+function hydrate_live(region, entry, mod, props) {
+	seed_remote_once();
+	seed_page_once();
+	const LiveHost = slots.live;
+	if (!LiveHost) {
+		if (import.meta.env.DEV) console.warn("[ogygia] live region needs the live feature plugin (LiveHost missing)");
+		return null;
+	}
+	const provided_ctx = capture_region_ids(region, () => slots.context?.(region));
+	const host_classes = note_host_classes(region);
+	const app = hydrate(LiveHost, {
+		target: region,
+		props: {
+			component: mod.default,
+			initialProps: prop_guard.wrap(props, entry)
+		},
+		...provided_ctx ? { context: provided_ctx } : {}
+	});
+	keep_host_classes(host_classes);
+	return handle(app, unmount_app, entry, true);
+}
+export { hydrate_island, hydrate_live, is_foreign_entry, kit_page_thread, neutralize_head_hydration_markers, read_region_props, repair_if_drifted, seed_page_once, seed_remote_once, sequence_differs };

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+import { bootDev } from "./full.js";
+export { bootDev };

package/dist/runtime/index.js

@@ -0,0 +1 @@
+export { bootDev } from "./full.js";

package/dist/runtime/interaction-replay.d.ts

@@ -0,0 +1,11 @@
+import { FieldSnapshot, QueuedClick } from "./interaction.js";
+/**
+ * Replay the queued clicks in arrival order at each click's address (tag-checked against drift).
+ * One frame later: hydration just (re)bound the island's web-component wiring (a dropdown web
+ * component's `target` element, set by a reactive statement) and many components apply such
+ * changes in their own render tick. A synchronous replay lands before that tick and toggles
+ * nothing; after a frame the component is settled.
+ */
+export declare function replay_clicks(region: Element, queued: QueuedClick[]): void;
+/** The island is live: fields back, focus back, clicks replayed. */
+export declare function after_wake(region: Element, fields: FieldSnapshot[], active_addr: number[] | null, queued: QueuedClick[]): void;