@ogygia/core 0.0.0 → 0.11.1

package/dist/runtime/interaction-replay.js

@@ -0,0 +1,70 @@
+import { interaction_link } from "./slots.js";
+import { emit } from "../events/bus.js";
+// src/runtime/interaction-replay.ts
+const resolve_address = (region, addr) => interaction_link().resolve_address(region, addr);
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+/** Re-apply what the user typed while the island was waking, at each field's ADDRESS; sync `bind:`. */
+function restore_fields(region, fields) {
+	for (const s of fields) {
+		const el = resolve_address(region, s.addr);
+		if (!el || el.tagName !== s.tag) continue;
+		const f = el;
+		if (f === s.el) continue;
+		let changed = false;
+		if (f.value !== s.el.value) {
+			f.value = s.el.value;
+			changed = true;
+		}
+		if (s.el instanceof HTMLInputElement && f.checked !== s.el.checked) {
+			f.checked = s.el.checked;
+			changed = true;
+		}
+		if (changed) {
+			try {
+				const { selectionStart, selectionEnd } = s.el;
+				if (selectionStart != null && selectionEnd != null) f.setSelectionRange(selectionStart, selectionEnd);
+			} catch {}
+			f.dispatchEvent(new Event("input", { bubbles: true }));
+			f.dispatchEvent(new Event("change", { bubbles: true }));
+		}
+	}
+}
+/**
+* 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.
+*/
+function replay_clicks(region, queued) {
+	const replay = () => {
+		for (const q of queued) {
+			const t = resolve_address(region, q.addr);
+			if (!t || t.tagName !== q.tag) continue;
+			const deep = q.deep;
+			(deep && deep.isConnected && t.shadowRoot?.contains(deep) ? deep : t).dispatchEvent(new MouseEvent("click", q.init));
+		}
+		queued.length = 0;
+	};
+	if (typeof requestAnimationFrame === "function") requestAnimationFrame(replay);
+	else replay();
+}
+/** The island is live: fields back, focus back, clicks replayed. */
+function after_wake(region, fields, active_addr, queued) {
+	restore_fields(region, fields);
+	if (active_addr) {
+		const el = resolve_address(region, active_addr);
+		if (el instanceof HTMLElement && document.activeElement !== el) el.focus();
+	}
+	const replayed = queued.length;
+	replay_clicks(region, queued);
+	if (DEVTOOLS) emit({
+		domain: "runtime",
+		name: "interaction.replay",
+		entry: region.getAttribute("entry") || void 0,
+		fp: region.getAttribute("data-og-fp") || void 0,
+		clicks: replayed,
+		fields: fields.length
+	});
+}
+export { after_wake, replay_clicks };

package/dist/runtime/interaction.d.ts

@@ -0,0 +1,33 @@
+/** Feature entry: fill the `interaction` slot — wake a cold island on first use, warm on hover. */
+export declare function install(): void;
+/** Child-index path from `region` down to `el` — survives node replacement by position. */
+export declare function element_address(region: Element, el: Element): number[] | null;
+/** The element now sitting at `addr` under `region` (post-hydration), or null. */
+export declare function resolve_address(region: Element, addr: number[]): Element | null;
+export type FieldSnapshot = {
+  /** The PRE-hydration node. Values are read from it AT RESTORE TIME: the wake fires on the very
+   * first keydown — BEFORE that key's character has landed — and more keystrokes land in this
+   * node while the island loads. A detached node keeps its `.value`, so at restore it holds
+   * everything the user typed up to the moment hydration swapped it out. */
+  el: HTMLInputElement;
+  addr: number[];
+  tag: string;
+};
+export type QueuedClick = {
+  addr: number[];
+  /** The deepest node of the click's composed path when it lies INSIDE a web component's shadow
+   *  tree (a design-system button's inner <button>): a host-level replay never reaches the shadow-internal
+   *  handler that actually toggles the component, so the replay lands here instead. */
+  deep: EventTarget | null;
+  tag: string;
+  init: MouseEventInit;
+};
+/**
+ * Arm a cold `wake="interaction"` region.
+ *
+ * @param region the `<ogygia-region>` element
+ * @param warm   prefetch the island module (no hydrate) — wired to the pointer entering the region
+ * @param fire   begin hydration; resolves when the island is live
+ * @returns disarm() — forget the region (disconnected before any interaction)
+ */
+export declare function arm_interaction(region: Element, warm: () => void, fire: () => Promise<void> | void): () => void;

package/dist/runtime/interaction.js

@@ -0,0 +1,217 @@
+import { slots } from "./slots.js";
+import { warm_island_module } from "./region-endpoint-url.js";
+import { island_entry_of } from "./entry-locations.js";
+// src/runtime/interaction.ts
+/**
+* WHAT A VISITOR DOES BEFORE AN ISLAND IS LIVE IS NOT LOST. `wake: 'interaction'` — the island sleeps
+* until someone uses it; and every scheduled island (`load` / `idle` / `visible` / media) is armed the
+* same way until it is live, since its server markup has no handlers either: a press on it wakes it at
+* once (a gesture), and the click is replayed when it is live.
+*
+* WAKE (capture-phase): `pointerdown` | `keydown` | `focusin` | `click`. The first of these starts
+* hydration. WARM (not a wake): the pointer moving over the region prefetches the island module, so
+* by the time the press lands the chunk is usually cached and the wake is one microtask.
+*
+* DELEGATED: the listeners live on the DOCUMENT, once — five per armed island used to be five
+* hundred on a page of interaction islands. An event resolves to the nearest ARMED region above its
+* target (`closest`, walking up past nested regions that are not armed) and that region's state
+* handles it exactly as its own capture listener did.
+*
+* HYDRATION REPLACES NODES. Svelte's hydrate pass may recreate the region's DOM, so nothing
+* captured before the wake can be replayed/restored by node reference — the original elements are
+* disconnected afterwards. Everything below is therefore re-resolved POSITIONALLY: an element is
+* recorded as its child-index path from the region ("address"), and after hydration the element
+* now sitting at that address receives the replay/restore. The hydrated markup mirrors the SSR
+* markup (same component, same props), so addresses stay valid; a tag-name check guards drift.
+*
+* WHAT SURVIVES THE WAKE:
+* - **Clicks are queued + replayed.** While waking, `click` events are `preventDefault()`ed and
+*   recorded (address + coordinates); after hydration each re-dispatches at its address. Cancel-
+*   then-replay means a checkbox / link / summary activates exactly ONCE — on the replay, where
+*   the island's handlers exist. Enter/Space activation arrives as a derived click → same path.
+* - **Typing lands natively and is restored.** Characters are in the DOM before hydration starts;
+*   hydration resets `.value` from SSR state, so field values (+ checkedness + selection) are
+*   snapshotted at wake and re-applied at the field's address, with `input`/`change` events so
+*   `bind:` syncs. Keydowns are never synthetically replayed (untrusted keys produce no text).
+* - **Focus is restored** at the focused element's address.
+*
+* Replayed events are NOT trusted user gestures (`event.isTrusted === false`): `window.open`,
+* clipboard, fullscreen from the first interaction will be blocked by the browser, and a component
+* that ignores untrusted clicks ignores the replay. Components can detect the situation via
+* `hydratedBy() === 'interaction'`. A click that opens a link elsewhere (a modifier or the middle
+* button) is never canceled: the browser does it on the server markup, and an untrusted replay could not.
+*
+* The capture (this module) is what must run synchronously inside the first event. The RESTORE +
+* REPLAY half (./interaction-replay.ts) is only needed once an island has woken, so it loads when a
+* pointer reaches an armed island or input lands — off the boot path, ahead of the replay.
+*/
+/** Feature entry: fill the `interaction` slot — wake a cold island on first use, warm on hover. */
+function install() {
+	slots.interaction = (el, fire) => {
+		const warm = () => {
+			const entry = island_entry_of(el);
+			if (entry) warm_island_module(entry, void 0, "user");
+		};
+		return arm_interaction(el, warm, () => Promise.resolve(fire()));
+	};
+}
+const WAKE_EVENTS = [
+	"pointerdown",
+	"keydown",
+	"focusin",
+	"click"
+];
+const ARMED_SELECTOR = "ogygia-region";
+/** Form controls whose typed value must survive hydration. */
+const VALUE_SELECTOR = "input, textarea, select";
+/** Child-index path from `region` down to `el` — survives node replacement by position. */
+function element_address(region, el) {
+	const addr = [];
+	let node = el;
+	while (node !== region) {
+		const parent = node.parentElement;
+		if (!parent) return null;
+		addr.unshift(Array.prototype.indexOf.call(parent.children, node));
+		node = parent;
+	}
+	return addr;
+}
+/** The element now sitting at `addr` under `region` (post-hydration), or null. */
+function resolve_address(region, addr) {
+	let node = region;
+	for (const i of addr) {
+		const next = node.children[i];
+		if (!next) return null;
+		node = next;
+	}
+	return node;
+}
+function snapshot_fields(region) {
+	const out = [];
+	for (const el of region.querySelectorAll(VALUE_SELECTOR)) {
+		const addr = element_address(region, el);
+		if (!addr) continue;
+		out.push({
+			el,
+			addr,
+			tag: el.tagName
+		});
+	}
+	return out;
+}
+const armed = /* @__PURE__ */ new Map();
+let installed = false;
+let replay_promise = null;
+function replay() {
+	slots.interaction_link ??= { resolve_address };
+	return replay_promise ??= import("./interaction-replay.js");
+}
+/** The nearest ARMED region above an event's target (past nested regions that are not armed), never
+*  past a live one: a click inside an awake island is that island's, whatever sleeps around it. */
+function armed_region_of(target) {
+	let el = target instanceof Element ? target.closest(ARMED_SELECTOR) : null;
+	while (el) {
+		const a = armed.get(el);
+		if (a) return a;
+		if (el.hasAttribute("data-hydrated")) return null;
+		el = el.parentElement?.closest(ARMED_SELECTOR) ?? null;
+	}
+	return null;
+}
+/** A click that opens a link elsewhere (a new tab or window): the browser does it on the server markup,
+*  and a replayed — untrusted — click could not. */
+function opens_elsewhere(e, target) {
+	return (e.button !== 0 || e.ctrlKey || e.metaKey || e.shiftKey) && !!target.closest("a[href]");
+}
+function on_wake_event(e) {
+	if (armed.size === 0) return;
+	const a = armed_region_of(e.target);
+	if (a) wake(a, e);
+}
+/** `pointerover` bubbles (unlike `pointerenter`) — the pointer crossing INTO an armed region, from
+*  any descendant, warms its module once. */
+function on_warm_event(e) {
+	if (armed.size === 0) return;
+	const a = armed_region_of(e.target);
+	if (!a || a.warmed) return;
+	a.warmed = true;
+	a.warm();
+	replay();
+}
+function install_listeners() {
+	if (installed) return;
+	installed = true;
+	for (const type of WAKE_EVENTS) document.addEventListener(type, on_wake_event, { capture: true });
+	document.addEventListener("pointerover", on_warm_event, {
+		capture: true,
+		passive: true
+	});
+}
+function wake(a, e) {
+	const { region, queued } = a;
+	if (e.type === "click" && e.target instanceof Element && !opens_elsewhere(e, e.target)) {
+		const addr = element_address(region, e.target);
+		if (addr) {
+			const me = e;
+			e.preventDefault();
+			const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+			const deep = path.length && path[0] !== e.target ? path[0] : null;
+			queued.push({
+				addr,
+				deep,
+				tag: e.target.tagName,
+				init: {
+					bubbles: true,
+					cancelable: true,
+					composed: true,
+					clientX: me.clientX,
+					clientY: me.clientY,
+					button: me.button,
+					ctrlKey: me.ctrlKey,
+					metaKey: me.metaKey,
+					shiftKey: me.shiftKey,
+					altKey: me.altKey,
+					detail: me.detail
+				}
+			});
+		}
+	}
+	if (a.woken) return;
+	a.woken = true;
+	region.setAttribute("data-og-woke", "interaction");
+	const fields = snapshot_fields(region);
+	const active = document.activeElement;
+	const active_addr = active instanceof Element && region.contains(active) ? element_address(region, active) : null;
+	const disarm = () => armed.delete(region);
+	Promise.all([replay(), Promise.resolve(a.fire())]).then(([r]) => {
+		disarm();
+		r.after_wake(region, fields, active_addr, queued);
+	}, (err) => {
+		disarm();
+		replay().then((r) => r.replay_clicks(region, queued));
+		console.error("[ogygia] interaction island failed to hydrate — leaving it static.", err);
+	});
+}
+/**
+* Arm a cold `wake="interaction"` region.
+*
+* @param region the `<ogygia-region>` element
+* @param warm   prefetch the island module (no hydrate) — wired to the pointer entering the region
+* @param fire   begin hydration; resolves when the island is live
+* @returns disarm() — forget the region (disconnected before any interaction)
+*/
+function arm_interaction(region, warm, fire) {
+	armed.set(region, {
+		region,
+		warm,
+		fire,
+		woken: false,
+		warmed: false,
+		queued: []
+	});
+	install_listeners();
+	return () => {
+		armed.delete(region);
+	};
+}
+export { arm_interaction, element_address, install, resolve_address };

package/dist/runtime/island-graph-preload.d.ts

@@ -0,0 +1,13 @@
+/** Marks a link this module inserted (tests and devtools tell them from the HTML's own). */
+export declare const GRAPH_PRELOAD_ATTR = "data-ogygia-graph-preload";
+/** Merge one graph script's text; hrefs resolve against `base` (the document the text came from).
+ *  Its locations (`s`) go to the runtime's one identity → location map. */
+export declare function register_island_graph(text: string, base?: string): void;
+/**
+ * Start fetching every chunk `entry`'s code needs: one modulepreload link per chunk not linked yet.
+ * Call it in the same task as the entry's `import()`. An entry the page has no graph for (dev, an
+ * island inside a fetched hole answer) preloads nothing — its `import()` still finds its chunks.
+ */
+export declare function preload_island_graph(entry: string, base?: string, priority?: "high" | "auto" | "low"): void;
+/** Test seam: forget every graph read and every chunk linked. */
+export declare function reset_island_graph(): void;

package/dist/runtime/island-graph-preload.js

@@ -0,0 +1,99 @@
+import { ISLAND_GRAPH_ATTR, decode_island_graph, decode_island_locations } from "../island-graph.js";
+import { note_entry_location } from "./entry-locations.js";
+import { runtime_session } from "./session.js";
+// src/runtime/island-graph-preload.ts
+/**
+* PRELOAD AN ISLAND'S GRAPH AT WAKE — the runtime half of the island graph (../island-graph.ts).
+*
+* The page carries, as data, the chunks each island entry needs. When an island starts to load (its
+* wake, after the wake gate; a hover or router warm), `preload_island_graph(entry)` inserts one
+* `<link rel="modulepreload">` per chunk not yet linked, in the same task as the entry's `import()`.
+* The browser then fetches the entry and its whole graph at once — no waterfall of discovering each
+* import after the last one parsed — and only for islands that actually start.
+*
+* The graph is read lazily from every `script[data-ogygia-graph]` in the document (the document
+* tail, a head copy a self-contained render emitted, the body a router swap brought in), each script
+* once. Chunks are content-hashed URLs and entries are identities (their files, content-hashed too,
+* resolve through runtime/entry-locations.ts), so a list read on one page is never wrong on the
+* next: nothing to invalidate. A router warm reads the NEXT page's graph out of its fetched HTML
+* (`register_island_graph`) before that page is in the DOM.
+*/
+const GRAPH_SELECTOR = `script[${ISLAND_GRAPH_ATTR}]`;
+const MODULEPRELOAD_SELECTOR = "link[rel=\"modulepreload\"]";
+/** Marks a link this module inserted (tests and devtools tell them from the HTML's own). */
+const GRAPH_PRELOAD_ATTR = "data-ogygia-graph-preload";
+/** entry URL (absolute) → its chunk URLs (absolute). */
+const graph = /* @__PURE__ */ new Map();
+let read_scripts = /* @__PURE__ */ new WeakSet();
+/** Chunk URLs (absolute) already linked — ours, or a modulepreload the HTML carried. */
+let linked = null;
+function absolute(href, base) {
+	try {
+		return new URL(href, base).href;
+	} catch {
+		return null;
+	}
+}
+/** Merge one graph script's text; hrefs resolve against `base` (the document the text came from).
+*  Its locations (`s`) go to the runtime's one identity → location map. */
+function register_island_graph(text, base = location.href) {
+	for (const [entry, src] of decode_island_locations(text)) note_entry_location(entry, src, base);
+	for (const [entry, hrefs] of decode_island_graph(text)) {
+		const key = absolute(entry, base);
+		if (!key || graph.has(key)) continue;
+		const list = [];
+		for (const href of hrefs) {
+			const url = absolute(href, base);
+			if (url) list.push(url);
+		}
+		graph.set(key, list);
+	}
+}
+function read_document_graphs() {
+	for (const s of document.querySelectorAll(GRAPH_SELECTOR)) {
+		if (read_scripts.has(s)) continue;
+		read_scripts.add(s);
+		register_island_graph(s.textContent ?? "");
+	}
+}
+function linked_set() {
+	if (linked) return linked;
+	linked = /* @__PURE__ */ new Set();
+	for (const l of document.querySelectorAll(MODULEPRELOAD_SELECTOR)) {
+		const url = absolute(l.getAttribute("href") ?? "", location.href);
+		if (url) linked.add(url);
+	}
+	return linked;
+}
+/**
+* Start fetching every chunk `entry`'s code needs: one modulepreload link per chunk not linked yet.
+* Call it in the same task as the entry's `import()`. An entry the page has no graph for (dev, an
+* island inside a fetched hole answer) preloads nothing — its `import()` still finds its chunks.
+*/
+function preload_island_graph(entry, base = location.href, priority = "auto") {
+	if (typeof document === "undefined") return;
+	const key = absolute(entry, base);
+	if (!key) return;
+	if (!graph.has(key)) read_document_graphs();
+	const hrefs = graph.get(key);
+	if (!hrefs || hrefs.length === 0) return;
+	const seen = linked_set();
+	for (const href of hrefs) {
+		if (seen.has(href)) continue;
+		seen.add(href);
+		const link = document.createElement("link");
+		link.rel = "modulepreload";
+		if (priority !== "auto") link.setAttribute("fetchpriority", priority);
+		link.href = href;
+		link.setAttribute(GRAPH_PRELOAD_ATTR, "");
+		runtime_session.claim_page_head(link);
+		document.head.appendChild(link);
+	}
+}
+/** Test seam: forget every graph read and every chunk linked. */
+function reset_island_graph() {
+	graph.clear();
+	read_scripts = /* @__PURE__ */ new WeakSet();
+	linked = null;
+}
+export { GRAPH_PRELOAD_ATTR, preload_island_graph, register_island_graph, reset_island_graph };

package/dist/runtime/kit-boot.d.ts

@@ -0,0 +1,29 @@
+export declare class KitBoot {
+  #private;
+  /**
+   * The route fact, when the server stamped it: `<meta name="ogygia-csr" content="true">` on a
+   * csr=true document. `null` when the document carries no such meta (an older document, a
+   * fragment) — then the inline-script probe below decides.
+   */
+  static meta_of(doc: ParentNode): boolean | null;
+  /** Meta first; else ONE probe over the document's inline scripts (side-channel scripts skipped). */
+  static document_has(doc?: ParentNode): boolean;
+  /**
+   * Same check over an HTML string, bounded to the last 64 KB before `end` (pass the index of
+   * `</body>`; defaults to the end of the string). A 2.6 MB document is never scanned whole: Kit's
+   * boot sits at the end of the body, so the window is exact, not a heuristic. The side-channel
+   * strip still applies inside the window (P0 above); a side-channel script cut by the window's
+   * start cannot false-match either — its payload never carries a literal `<script` (devalue and
+   * JSON escape `<`), and `#INLINE` needs one.
+   */
+  static html_has(html: string, end?: number): boolean;
+}
+/**
+ * Mixed mode: on a csr=true page, Kit boots and hydrates the whole tree (including our island
+ * components). THE one answer for the live document — read once (the meta, else the probe), cached
+ * on the session, cleared when the router prepares the next document. Every caller (the region
+ * element's guards, the router's start, the wrapper's client leg) reads this cache; none probes
+ * the document on its own.
+ */
+export declare function kit_hydrates_page(): boolean;
+export declare const html_has_kit_bootstrap: typeof KitBoot.html_has;

package/dist/runtime/kit-boot.js

@@ -0,0 +1,60 @@
+import { runtime_session } from "./session.js";
+// src/runtime/kit-boot.ts
+/**
+* Detect whether a document is a Kit csr=true page (Kit boots and hydrates the tree).
+* Must NOT treat ogygia side-channel scripts as evidence — their payloads can reflect
+* attacker-controlled URL substrings like `__sveltekit_` (P0).
+*/
+var KitBoot = class KitBoot {
+	static #ASSIGN = /__sveltekit_\w+\s*=/;
+	static #SIDECHANNEL = /<script\b[^>]*(?:\bdata-ogygia-(?:props|page|remote)\b|type=["']application\/ogygia-(?:props|page|remote)["'])[^>]*>[\s\S]*?<\/script>/gi;
+	static #INLINE = /<script\b(?![^>]*\bsrc=)[^>]*>[^<]*__sveltekit_\w+\s*=/i;
+	/**
+	* The route fact, when the server stamped it: `<meta name="ogygia-csr" content="true">` on a
+	* csr=true document. `null` when the document carries no such meta (an older document, a
+	* fragment) — then the inline-script probe below decides.
+	*/
+	static meta_of(doc) {
+		const meta = doc.querySelector("meta[name=\"ogygia-csr\"]");
+		return meta ? meta.getAttribute("content") === "true" : null;
+	}
+	/** Meta first; else ONE probe over the document's inline scripts (side-channel scripts skipped). */
+	static document_has(doc = document) {
+		const meta = KitBoot.meta_of(doc);
+		if (meta !== null) return meta;
+		for (const s of doc.querySelectorAll("script:not([src])")) {
+			if ((s.getAttribute("type") || "").startsWith("application/ogygia-")) continue;
+			if (s.hasAttribute("data-ogygia-props") || s.hasAttribute("data-ogygia-page") || s.hasAttribute("data-ogygia-remote")) continue;
+			if (KitBoot.#ASSIGN.test(s.textContent || "")) return true;
+		}
+		return false;
+	}
+	/** How far before `end` the string check looks. Kit appends its boot script at the END of the
+	*  body (render.js), right before `</body>`, so this window holds it whenever it exists. */
+	static #WINDOW = 65536;
+	/**
+	* Same check over an HTML string, bounded to the last 64 KB before `end` (pass the index of
+	* `</body>`; defaults to the end of the string). A 2.6 MB document is never scanned whole: Kit's
+	* boot sits at the end of the body, so the window is exact, not a heuristic. The side-channel
+	* strip still applies inside the window (P0 above); a side-channel script cut by the window's
+	* start cannot false-match either — its payload never carries a literal `<script` (devalue and
+	* JSON escape `<`), and `#INLINE` needs one.
+	*/
+	static html_has(html, end = html.length) {
+		const window = html.slice(Math.max(0, end - KitBoot.#WINDOW), end);
+		return KitBoot.#INLINE.test(window.replace(KitBoot.#SIDECHANNEL, ""));
+	}
+};
+/**
+* Mixed mode: on a csr=true page, Kit boots and hydrates the whole tree (including our island
+* components). THE one answer for the live document — read once (the meta, else the probe), cached
+* on the session, cleared when the router prepares the next document. Every caller (the region
+* element's guards, the router's start, the wrapper's client leg) reads this cache; none probes
+* the document on its own.
+*/
+function kit_hydrates_page() {
+	if (runtime_session.kit_page === void 0) runtime_session.kit_page = typeof document !== "undefined" && KitBoot.document_has(document);
+	return runtime_session.kit_page;
+}
+const html_has_kit_bootstrap = KitBoot.html_has.bind(KitBoot);
+export { KitBoot, html_has_kit_bootstrap, kit_hydrates_page };

package/dist/runtime/kit-page-thread.svelte.d.ts

@@ -0,0 +1 @@
+export declare function kit_page_thread(): Promise<void> | null;

package/dist/runtime/kit-page-thread.svelte.js

@@ -0,0 +1,116 @@
+// src/runtime/kit-page-thread.svelte.ts
+/**
+* KIT-WORLD PAGE THREAD (wait side). On a Kit-hydrated (csr=true) document the handle ships no
+* `application/ogygia-page` seed — Kit's own data blob is the truth, and the `$app/state` shim reads
+* it through the bridge Kit's generated client entry publishes on `Symbol.for('ogygia.kit-page')`
+* (KIT_PAGE_THREAD in vite/index.ts; read side in shims/page-store.svelte.ts).
+*
+* That entry arrives by Kit's boot `import()` — a network fetch — while an island of OURS on that
+* document (inside a lake, inside a hole's answer) is already in the SSR tree and wakes on its own
+* schedule. `wake:'idle'` fires while the browser waits for Kit's chunks. The island then hydrated
+* against an empty `page.data` → a `{#if page.data.x}` took the other branch → Svelte discarded the
+* island's server DOM and re-rendered it EMPTY (a customer's header search bar, ~1 in 3 loads — a
+* race, so it looked erratic). So an island of ours on a Kit document waits before its hydrate turn.
+* Its server HTML stays on screen meanwhile — waiting costs nothing visible, a discard costs the island.
+*
+* WHAT IS WAITED FOR — two moments, both exact, neither a guess:
+*
+*  1. The bridge is PUBLISHED. An accessor latch on the symbol: Kit's entry's plain assignment
+*     resolves it, whatever order the two worlds load in.
+*  2. Kit has APPLIED its page. The bridge holds a LIVE reference to Kit's `$app/state` page, assigned
+*     when the entry EVALUATES — but that page is still Kit's pre-start default until `start()`'s
+*     `initialize()` runs `update(result.props.page)`, ~150–350 ms later (field: bridge=Y with
+*     data.keys=0, the island hydrates and collapses, data lands 200 ms too late). A wait that
+*     resolved on (1) alone closed only the first window. Kit's page object carries the marker
+*     itself: it is constructed with `status = -1` (and a placeholder URL) and `update()` assigns the
+*     real status. `status !== -1` is "Kit applied its page" — for an EMPTY-data page too, which is
+*     why this is not "data has keys" (that cannot tell empty-applied from not-yet-applied, and only
+*     a timeout could paper over it). Every field of that page is a `$state.raw`, so the assignment
+*     is a reactive write and an effect reading `status` re-runs on it: the exact moment, no polling.
+*
+* Nothing here touches the `$page` store (removed in Kit 3): the `$app/state` page object is what
+* both Kit 2 and Kit 3 publish. No timeout either: a Kit document whose `start()` never runs has no
+* page truth for such an island to hydrate against, and its own Kit components are equally dead —
+* the island stays as its visible server HTML, which is the honest state.
+*
+* `null` when the page is already applied (the common late-wake case: a fetched hole's islands, a
+* click long after boot) — the caller skips the await entirely.
+*/
+const KIT_PAGE_KEY = Symbol.for("ogygia.kit-page");
+/** Kit constructs its `$app/state` page with this status; `initialize()` replaces it with the real one. */
+const KIT_PRE_START_STATUS = -1;
+let pending = null;
+function bridge_of() {
+	return globalThis[KIT_PAGE_KEY];
+}
+/** Reads Kit's live `status` — a reactive read when called inside an effect. */
+function page_applied(bridge) {
+	if (bridge == null) return false;
+	try {
+		return bridge.page?.status !== KIT_PRE_START_STATUS;
+	} catch {
+		return false;
+	}
+}
+/**
+* DEV ONLY: after this long still waiting, say so once. The wait itself has no timeout by design (an
+* island of ours has no page truth to hydrate against until Kit applies its page, and its server HTML
+* is the honest state meanwhile) — but a Kit boot that never happens must be diagnosable, not silent.
+* Dead code in a production build.
+*/
+const DEV_STILL_WAITING_MS = 5e3;
+function kit_page_thread() {
+	if (page_applied(bridge_of())) return null;
+	return pending ??= new Promise((resolve) => {
+		let slow = null;
+		if (import.meta.env.DEV) slow = setTimeout(() => {
+			const bridge = bridge_of();
+			console.warn(`[ogygia] islands inside a lake / hole answer on this Kit (csr=true) page have waited ${DEV_STILL_WAITING_MS / 1e3}s for Kit to apply its page and are still holding their server HTML. ` + (bridge == null ? `Kit's client entry has not evaluated (no page bridge yet) — Kit's boot script may be blocked, failing, or missing.` : `Kit's client entry evaluated but start() has not applied the page (status is still -1) — Kit's start() may have thrown; check the console above.`) + ` They hydrate the moment Kit does; nothing is discarded meanwhile.`);
+		}, DEV_STILL_WAITING_MS);
+		const done = () => {
+			if (slow !== null) clearTimeout(slow);
+			pending = null;
+			resolve();
+		};
+		await_bridge((bridge) => await_applied(bridge, done));
+	});
+}
+/** Moment 1: the symbol is assigned. Calls back synchronously if it already is. */
+function await_bridge(cb) {
+	const g = globalThis;
+	if (g[KIT_PAGE_KEY] != null) return cb(g[KIT_PAGE_KEY]);
+	let value;
+	const settle = (v) => {
+		value = v;
+		Object.defineProperty(g, KIT_PAGE_KEY, {
+			value: v,
+			writable: true,
+			configurable: true,
+			enumerable: true
+		});
+		cb(v);
+	};
+	try {
+		Object.defineProperty(g, KIT_PAGE_KEY, {
+			configurable: true,
+			enumerable: true,
+			get: () => value,
+			set: settle
+		});
+	} catch {
+		const tick = () => g[KIT_PAGE_KEY] != null ? settle(g[KIT_PAGE_KEY]) : setTimeout(tick, 50);
+		tick();
+	}
+}
+/** Moment 2: Kit assigns the real status onto its live page — observed by an effect, resolved once. */
+function await_applied(bridge, done) {
+	if (page_applied(bridge)) return done();
+	const stop = $effect.root(() => {
+		$effect(() => {
+			if (!page_applied(bridge)) return;
+			queueMicrotask(stop);
+			done();
+		});
+	});
+}
+export { kit_page_thread };

package/dist/runtime/lake-anchors.d.ts

@@ -0,0 +1,13 @@
+export interface NodeLike {
+  nodeType: number;
+  data?: string;
+}
+export interface ParentLike {
+  appendChild(node: NodeLike): unknown;
+}
+export interface FragmentLike {
+  lastChild: NodeLike | null;
+  removeChild(node: NodeLike): unknown;
+}
+/** Relocate trailing empty comments from `frag` into `lake`. Returns how many moved. */
+export declare function relocate_trailing_empty_comments(frag: FragmentLike, lake: ParentLike): number;