@ogygia/core 0.0.0 → 0.11.0

package/dist/runtime/schedule.js

@@ -0,0 +1,256 @@
+import { observe } from "./observe.js";
+// src/runtime/schedule.ts
+/**
+* THE HYDRATION SCHEDULER — one island per task, viewport first.
+*
+* `customElements.define` upgrades every region on the page in one task; with 21 `wake:'load'`
+* islands the old runtime then hydrated them back-to-back in microtasks — props parse + module
+* continuation + Svelte hydrate, 21 times, in ONE long task, in document order, with the header
+* nobody can see yet racing the hero everybody can. Here every island that is ready to hydrate
+* asks for a TURN; turns are handed out one per task (`scheduler.yield()`, else a `MessageChannel`
+* hop — never a timer), so the browser paints, scrolls and handles input between islands, and the
+* next turn goes to a region that intersects the viewport NOW (one shared IntersectionObserver
+* snapshot, taken at connect) before any that does not, document order within each group.
+*
+* What a turn covers is the island's whole synchronous hydrate step (props parse, Svelte hydrate,
+* lake restore). Module imports are NOT serialized — every island's `import()` starts at its wake,
+* in parallel; a turn is requested when the module has arrived. Arrivals are staggered (one task
+* each, in network order), so "viewport first" also means: a ready island BELOW the fold holds its
+* turn while a viewport island is still waiting for its module — bounded, so a chunk that never
+* comes cannot stall the rest of the page.
+*
+* The viewport snapshot is asynchronous (the observer reports after layout). A drain waits for
+* the snapshot of every queued region, bounded (a hidden document never lays out; a stalled
+* observer must not stall hydration), so the boot's first island is the right one, not merely the
+* first one.
+*/
+/** How long the drain waits for the observer's snapshot of a queued region before ignoring it. */
+const SNAPSHOT_WAIT_MS = 48;
+/** How long a ready below-the-fold island holds for a viewport island still loading its module. */
+const HOLD_FOR_VIEWPORT_MS = 1e3;
+const pending = [];
+let draining = false;
+/** Connect-order stamp per region — document order at upgrade, insertion order after a morph. */
+const order_of = /* @__PURE__ */ new WeakMap();
+let next_order = 0;
+/** The snapshot: intersecting now? Absent = the observer has not reported yet. */
+const in_viewport = /* @__PURE__ */ new WeakMap();
+const unobserve_of = /* @__PURE__ */ new WeakMap();
+/** Regions whose hydrate has STARTED (module in flight) and not yet taken its turn. */
+const loading = /* @__PURE__ */ new Set();
+let wait_timer = null;
+/**
+* Yield to the event loop: resolves in a NEW task, so whatever ran before is a finished task and
+* the browser may render and handle input in between. `scheduler.yield()` where it exists (it
+* keeps the continuation at the current task's priority); else a message hop — a `MessageChannel`
+* post lands as a task without the 4 ms clamp `setTimeout` carries.
+*/
+let channel = null;
+const hops = [];
+function yield_task() {
+	const s = globalThis.scheduler;
+	if (s && typeof s.yield === "function") return s.yield();
+	return new Promise((resolve) => {
+		if (!channel) {
+			channel = new MessageChannel();
+			channel.port1.onmessage = () => hops.shift()?.();
+		}
+		hops.push(resolve);
+		channel.port2.postMessage(null);
+	});
+}
+/**
+* Run `fn` at background priority, off the current task: `scheduler.postTask` at 'background' where
+* it exists, else a macrotask. This orders MAIN-THREAD work only — it lets a pending render or input
+* task go first. It does not hold back the network: while the page's resources download the main
+* thread is idle, so a background task runs at once and an `import()` it starts competes with them.
+* Holding island code back until the page has painted is `after_document_painted`'s job.
+*/
+function background_start(fn) {
+	background_queue.push(fn);
+	if (!background_armed) {
+		background_armed = true;
+		post_background(drain_background);
+	}
+}
+const background_queue = [];
+let background_armed = false;
+/** a drain yields to the page after this long, and continues in a new background task */
+const BACKGROUND_BUDGET_MS = 30;
+function drain_background() {
+	const until = performance.now() + BACKGROUND_BUDGET_MS;
+	let i = 0;
+	try {
+		while (i < background_queue.length) {
+			background_queue[i++]();
+			if (performance.now() >= until) break;
+		}
+	} finally {
+		background_queue.splice(0, i);
+		if (background_queue.length) post_background(drain_background);
+		else background_armed = false;
+	}
+}
+function post_background(fn) {
+	const s = globalThis.scheduler;
+	if (s && typeof s.postTask === "function") try {
+		s.postTask(fn, { priority: "background" });
+		return;
+	} catch {}
+	setTimeout(fn, 0);
+}
+let document_painted = null;
+/**
+* Resolves once the document is parsed AND painted: after `DOMContentLoaded`, then one rendered
+* frame. This is the moment SvelteKit starts hydrating (its start runs from a deferred module
+* script, so never before DOMContentLoaded), and an island's wake starts no earlier: the runtime
+* boots from a module script that runs BEFORE DOMContentLoaded — the app's other deferred scripts
+* may still be executing and the first paint (and its LCP image) not yet happened — and an island
+* `import()` started there takes bandwidth from both.
+*
+* `readyState` cannot tell "DOMContentLoaded fired" from "about to fire" (it reads `interactive` for
+* both), so the navigation timing entry decides; `load` backs up the listener where there is none.
+* A hidden document paints no frame (`requestAnimationFrame` never fires there) — nothing to protect,
+* so it waits one task instead. Once resolved it stays resolved: a late region (SPA swap, a hole's
+* answer) passes straight through.
+*/
+function after_document_painted() {
+	return document_painted ??= new Promise((resolve) => {
+		if (typeof document === "undefined") return resolve();
+		const painted = () => {
+			if (document.visibilityState === "hidden" || typeof requestAnimationFrame !== "function") setTimeout(resolve, 0);
+			else requestAnimationFrame(() => setTimeout(resolve, 0));
+		};
+		if (dom_content_loaded()) return painted();
+		let done = false;
+		const once = () => {
+			if (done) return;
+			done = true;
+			document.removeEventListener("DOMContentLoaded", once);
+			removeEventListener("load", once);
+			painted();
+		};
+		document.addEventListener("DOMContentLoaded", once);
+		addEventListener("load", once);
+	});
+}
+function dom_content_loaded() {
+	if (document.readyState === "complete") return true;
+	if (document.readyState === "loading") return false;
+	const nav = typeof performance !== "undefined" && performance.getEntriesByType?.("navigation")[0];
+	return !!nav && nav.domContentLoadedEventEnd > 0;
+}
+/** Test seam: forget the resolved gate (a test that fakes a fresh document). */
+function reset_document_painted() {
+	document_painted = null;
+}
+/**
+* Register a region with the scheduler at connect: stamp its order, start its viewport snapshot.
+* Cheap on purpose (a stamp and an `observe`) — connect runs for every region in one task.
+*/
+function register_region(el) {
+	if (!order_of.has(el)) order_of.set(el, next_order++);
+	if (unobserve_of.has(el)) return;
+	unobserve_of.set(el, observe(el, "0px", (intersecting) => {
+		in_viewport.set(el, intersecting);
+		if (pending.length) schedule_drain();
+	}));
+}
+/**
+* Drop a region from the scheduler (disconnect): its snapshot stops and any pending turn is handed
+* out at once — the waiting hydrate step then sees `isConnected === false` and stands down (or, if
+* the element was re-attached meanwhile, runs — exactly what an un-scheduled wait would have done).
+*/
+function unregister_region(el) {
+	stop_snapshot(el);
+	in_viewport.delete(el);
+	loading.delete(el);
+	for (let i = pending.length - 1; i >= 0; i--) {
+		if (pending[i].el !== el) continue;
+		const [turn] = pending.splice(i, 1);
+		turn.resolve();
+	}
+	if (pending.length) schedule_drain();
+}
+function stop_snapshot(el) {
+	unobserve_of.get(el)?.();
+	unobserve_of.delete(el);
+}
+/** The island's module is in flight: a viewport island here holds ready islands below the fold. */
+function hydrate_started(el) {
+	loading.add(el);
+}
+/** The hydrate attempt is over (turn taken, or it never got there — no entry, a failed import). */
+function hydrate_settled(el) {
+	if (!loading.delete(el)) return;
+	if (pending.length) schedule_drain();
+}
+/**
+* Wait for this region's turn. Resolves in a task of its own, after every region ahead of it in
+* priority has had its task. Call it when the island can hydrate right now (module loaded) — the
+* continuation after the `await` IS the turn: keep the whole synchronous hydrate step in it.
+*/
+function hydrate_turn(el) {
+	return new Promise((resolve) => {
+		pending.push({
+			el,
+			order: order_of.get(el) ?? (order_of.set(el, next_order), next_order++),
+			queued_at: now(),
+			resolve
+		});
+		schedule_drain();
+	});
+}
+function now() {
+	return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+}
+function schedule_drain() {
+	if (draining) return;
+	draining = true;
+	yield_task().then(drain);
+}
+/** Re-drain after `ms` (one timer at a time — the earliest wait wins, later ones ride it). */
+function drain_after(ms) {
+	if (wait_timer) return;
+	wait_timer = setTimeout(() => {
+		wait_timer = null;
+		schedule_drain();
+	}, Math.max(1, ms));
+}
+/** One turn per call: pick the best pending region, hand it its task; the next pick after a yield. */
+function drain() {
+	draining = false;
+	if (!pending.length) return;
+	const t = now();
+	const hidden = typeof document !== "undefined" && document.visibilityState === "hidden";
+	if (!hidden) for (const p of pending) {
+		if (in_viewport.has(p.el)) continue;
+		const left = SNAPSHOT_WAIT_MS - (t - p.queued_at);
+		if (left > 0) return drain_after(left);
+	}
+	let best = 0;
+	for (let i = 1; i < pending.length; i++) {
+		const a = pending[best];
+		const b = pending[i];
+		const va = in_viewport.get(a.el) === true;
+		const vb = in_viewport.get(b.el) === true;
+		if (vb !== va ? vb : b.order < a.order) best = i;
+	}
+	const turn = pending[best];
+	if (!hidden && in_viewport.get(turn.el) !== true) {
+		const left = HOLD_FOR_VIEWPORT_MS - (t - turn.queued_at);
+		if (left > 0) {
+			for (const el of loading) if (in_viewport.get(el) === true) return drain_after(left);
+		}
+	}
+	pending.splice(best, 1);
+	loading.delete(turn.el);
+	stop_snapshot(turn.el);
+	turn.resolve();
+	if (pending.length) schedule_drain();
+}
+/** Test seam: is a hydration turn queued or being drained right now? */
+function schedule_idle() {
+	return pending.length === 0 && !draining;
+}
+export { after_document_painted, background_start, hydrate_settled, hydrate_started, hydrate_turn, register_region, reset_document_painted, schedule_idle, unregister_region, yield_task };

package/dist/runtime/seeds.d.ts

@@ -0,0 +1,50 @@
+import { PageSnapshot } from "../shims/page-store.svelte.js";
+export declare const PAGE_SEED_SELECTOR = "script[type=\"application/ogygia-page\"]";
+/** A seed or props script's payload, in its lane (wire-format.ts): JSON when the server marked
+ *  it plain, devalue with `revivers` otherwise. Every seed / props read goes through here. */
+export declare function parse_sidecar_text(el: Element, revivers?: Record<string, (d: never) => unknown>): unknown;
+type PageSeed = Partial<Omit<PageSnapshot, "url"> & {
+  url: string | URL;
+}>;
+/** Test seam: how many page-seed scripts were parsed since boot (one per document is the law). */
+export declare function seed_parse_count(): number;
+/**
+ * The parsed seed of a document that is NOT the live one (a navigation's incoming document): parsed
+ * on first ask, remembered on the document. The router asks in its preflight (off the view
+ * transition's critical path); the soft-invalidate and any kept island's props absorb reuse it.
+ */
+export declare function page_seed_of(doc: Document): PageSeed | null;
+/**
+ * The `data` a seed reference resolves against: the live page store for the live document (seeded
+ * on first ask), the once-parsed seed for a foreign one. `undefined` when the document has no seed.
+ */
+export declare function seed_data_of(doc: Document): unknown;
+export declare function seed_remote_once(): void;
+/** Document-level page seed (one script from ogygiaHandle) — once per document; then any page facts
+ *  an answer brought since. Every hydrate calls it, before the island reads `page`. */
+export declare function seed_page_once(): void;
+/**
+ * Soft invalidate: refresh document-level page + remote **seeds** from a fetched HTML document
+ * without replacing `<body>`, remounting islands, or clearing live query/live instance maps. The
+ * router runs it on every navigation (before the body morph — seeds first, DOM second) and
+ * `invalidateAll` runs it alone, so Kit remote `form()` success does not view-transition wipe live
+ * island state. It is the ONLY seed writer on a navigation and marks the document seeded, so the
+ * next island to wake never re-parses. Does **not** auto-refresh live queries — callers that need
+ * that use `.refresh()`, or `submit().updates(q)` with server `requested(q).refreshAll()`.
+ */
+export declare function apply_soft_invalidate_doc(doc: Document): void;
+/**
+ * Reset per-document session + SSR remote seeds before a new body connects.
+ *
+ * Do **not** clear `query_map` / `live_query_map` here — old islands are still mounted, and Kit's
+ * LiveQueryProxy throws if its cache entry vanishes mid-render. Instance sweep happens in
+ * {@link finish_spa_document} after the swap.
+ */
+export declare function prepare_spa_document(): void;
+/**
+ * After the body swap: old islands have disconnected; new ones have only queued their hydrate.
+ * Sweep Kit query/live instance maps so the next page cannot reuse a LiveQuery whose `#start` is
+ * already spent (`once`) — that reuse never opens SSE again and leaves "connecting…".
+ */
+export declare function finish_spa_document(): void;
+export {};

package/dist/runtime/seeds.js

@@ -0,0 +1,208 @@
+import { parse_wire_text, wire_is_json } from "./wire-format.js";
+import { page_state, reset_page, set_page } from "../shims/page-store.svelte.js";
+import { kit_bridge } from "../shims/kit-bridge.js";
+import { install_page_defer, page_defer_revivers } from "./page-defer.js";
+import { transport_decoders } from "./app-transport.js";
+import { boot_link, slots } from "./slots.js";
+// src/runtime/seeds.ts
+/**
+* THE PAGE SEED on the client — parsed ONCE per document, kept in ONE place.
+*
+* The handle ships `page.data` (and url/params/route/…) as `<script type="application/ogygia-page">`
+* so islands can read `$page`, and a seed REFERENCE in an island's props (`seed-refs.ts`) points into
+* that same tree. Both readers resolve here:
+*   • the LIVE document's seed is `page_state` — the `$app/state` store the shims already read. It is
+*     parsed once (`seed_page_once`, lazily on the first hydrate) and every seed reference resolves
+*     against `page_state.data` — the exact object the islands' `page.data` is, not a second parse.
+*   • a FOREIGN document (the one a navigation fetched) is parsed once per `Document` and remembered
+*     on it: a kept island absorbs the incoming page's props BEFORE the router applies that page's
+*     seed, so its references must resolve against the incoming seed, not the current one. The
+*     navigation's soft-invalidate then applies the SAME parse — never a second one.
+* A parse count of one per document is what `test/browser/seed-single-parse.test.ts` pins; the old
+* two-cache shape (a per-element cache the morph reused across pages) handed a navigated page the
+* previous page's data — the stale-reference regression that test also carries.
+*
+* WIRE FORMATS: a seed or props script carries `data-og-format="json"` when its payload is plain
+* JSON (no custom types, no seed references) — then it is `JSON.parse`d, nothing else. Without the
+* attribute it is devalue text and parses with the revivers the caller hands in. One helper
+* (`parse_sidecar_text`) is the only place that decision is made.
+*
+* After a successful parse the seed's TEXT is blanked (router on, devtools off): the graph lives in
+* `page_state` from here on and nothing reads the script again — 690 KB of text on a CMS page has
+* no second reader, and the morph carries the next page's seed in (already blank, parsed in the
+* navigation's preflight). Devtools keeps the text: its byte ledger reads it. A props SIDECAR is
+* never blanked: a region can read it again — an island moved by its host's snippet adoption
+* disconnects, reconnects and hydrates anew (the island-children shape).
+*/
+const session = () => boot_link().runtime_session;
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+const PAGE_SEED_SELECTOR = "script[type=\"application/ogygia-page\"]";
+const REMOTE_SEED_SELECTOR = "script[type=\"application/ogygia-remote\"]";
+/** A seed or props script's payload, in its lane (wire-format.ts): JSON when the server marked
+*  it plain, devalue with `revivers` otherwise. Every seed / props read goes through here. */
+function parse_sidecar_text(el, revivers) {
+	return parse_wire_text(el.textContent ?? "", wire_is_json(el), revivers);
+}
+let parses = 0;
+/** Test seam: how many page-seed scripts were parsed since boot (one per document is the law). */
+function seed_parse_count() {
+	return parses;
+}
+/** Parse one page-seed script; `null` when malformed. Blanks the text once parsed (see above). */
+function parse_page_seed(el) {
+	parses++;
+	try {
+		install_page_defer(transport_decoders);
+		const raw = parse_sidecar_text(el, page_defer_revivers(transport_decoders));
+		if (slots.nav && !DEVTOOLS) el.textContent = "";
+		return raw;
+	} catch {
+		return null;
+	}
+}
+/** Feed a parsed seed into the `$app/state` page store (the devalue href string becomes a `URL`). */
+function apply_page_seed(raw) {
+	if (!raw) return;
+	let url;
+	if (raw.url instanceof URL) url = raw.url;
+	else if (typeof raw.url === "string") try {
+		url = new URL(raw.url);
+	} catch {
+		url = void 0;
+	}
+	set_page({
+		...raw,
+		url
+	});
+}
+/** Foreign (fetched) documents' seeds, one parse per `Document`. */
+const foreign_seeds = /* @__PURE__ */ new WeakMap();
+/**
+* The parsed seed of a document that is NOT the live one (a navigation's incoming document): parsed
+* on first ask, remembered on the document. The router asks in its preflight (off the view
+* transition's critical path); the soft-invalidate and any kept island's props absorb reuse it.
+*/
+function page_seed_of(doc) {
+	const hit = foreign_seeds.get(doc);
+	if (hit !== void 0) return hit;
+	const el = doc.querySelector(PAGE_SEED_SELECTOR);
+	const seed = el ? parse_page_seed(el) : null;
+	foreign_seeds.set(doc, seed);
+	return seed;
+}
+/**
+* The `data` a seed reference resolves against: the live page store for the live document (seeded
+* on first ask), the once-parsed seed for a foreign one. `undefined` when the document has no seed.
+*/
+function seed_data_of(doc) {
+	if (typeof document !== "undefined" && doc === document) {
+		seed_page_once();
+		return page_state.data;
+	}
+	return page_seed_of(doc)?.data;
+}
+/** Apply `application/ogygia-remote` text into the reused Kit query seed bag. */
+function apply_remote_seed_text(text) {
+	if (!text) return;
+	slots.remoteSeeds?.seed_query_responses(text);
+}
+function seed_remote_once() {
+	if (session().remote_seeded) return;
+	session().mark_remote_seeded();
+	if (typeof document === "undefined") return;
+	apply_remote_seed_text(document.querySelector(REMOTE_SEED_SELECTOR)?.textContent);
+}
+/** Document-level page seed (one script from ogygiaHandle) — once per document; then any page facts
+*  an answer brought since. Every hydrate calls it, before the island reads `page`. */
+function seed_page_once() {
+	if (!session().page_seeded) {
+		session().mark_page_seeded();
+		if (typeof document === "undefined") return;
+		const el = document.querySelector(PAGE_SEED_SELECTOR);
+		if (el) apply_page_seed(parse_page_seed(el));
+	}
+	if (session().page_facts.length) absorb_page_facts();
+}
+/**
+* ONE PAGE, NOT TWO (server/render-page.ts): an answer rendered outside its page — a hole, a region a
+* remote call refreshed — carries the `page.data` keys its islands read, as the server just looked
+* them up. They join the page store before those islands wake, so the islands hydrate against the
+* values their HTML was rendered from, and every island reading the same keys sees them too (the
+* page's data changed: a locale saved, a sign-in). On a Kit-hydrated page Kit owns `page.data`: the
+* page's data is older than the answer's, and dev says to refresh it (`invalidateAll()`) first.
+*/
+function absorb_page_facts() {
+	const queued = session().page_facts.splice(0);
+	let merged = null;
+	for (const text of queued) {
+		let facts;
+		try {
+			facts = parse_wire_text(text, false, transport_decoders);
+		} catch {
+			continue;
+		}
+		if (!facts || typeof facts !== "object") continue;
+		merged = merged ? Object.assign(merged, facts) : { ...facts };
+	}
+	if (!merged) return;
+	const kit = kit_bridge();
+	if (kit) {
+		if (import.meta.env.DEV) {
+			const data = kit.page.data ?? {};
+			const older = Object.keys(merged).filter((k) => data[k] !== merged[k] && JSON.stringify(data[k]) !== JSON.stringify(merged[k]));
+			if (older.length) console.warn(`[ogygia] a region came back rendered with newer page.data (${older.join(", ")}) than this Kit page holds. Refresh the page's data (invalidateAll()) before refreshing the region, or the islands inside it hydrate against the older values.`);
+		}
+		return;
+	}
+	set_page({
+		url: page_state.url,
+		params: page_state.params,
+		route: page_state.route,
+		status: page_state.status,
+		data: {
+			...page_state.data,
+			...merged
+		},
+		form: page_state.form,
+		error: page_state.error,
+		state: page_state.state
+	});
+}
+/**
+* Soft invalidate: refresh document-level page + remote **seeds** from a fetched HTML document
+* without replacing `<body>`, remounting islands, or clearing live query/live instance maps. The
+* router runs it on every navigation (before the body morph — seeds first, DOM second) and
+* `invalidateAll` runs it alone, so Kit remote `form()` success does not view-transition wipe live
+* island state. It is the ONLY seed writer on a navigation and marks the document seeded, so the
+* next island to wake never re-parses. Does **not** auto-refresh live queries — callers that need
+* that use `.refresh()`, or `submit().updates(q)` with server `requested(q).refreshAll()`.
+*/
+function apply_soft_invalidate_doc(doc) {
+	if (typeof document === "undefined") return;
+	slots.remoteSeeds?.clear_remote_seeds();
+	apply_remote_seed_text(doc.querySelector(REMOTE_SEED_SELECTOR)?.textContent);
+	session().mark_remote_seeded();
+	apply_page_seed(page_seed_of(doc));
+	session().mark_page_seeded();
+}
+/**
+* Reset per-document session + SSR remote seeds before a new body connects.
+*
+* Do **not** clear `query_map` / `live_query_map` here — old islands are still mounted, and Kit's
+* LiveQueryProxy throws if its cache entry vanishes mid-render. Instance sweep happens in
+* {@link finish_spa_document} after the swap.
+*/
+function prepare_spa_document() {
+	session().reset();
+	slots.remoteSeeds?.clear_remote_seeds();
+	reset_page();
+}
+/**
+* After the body swap: old islands have disconnected; new ones have only queued their hydrate.
+* Sweep Kit query/live instance maps so the next page cannot reuse a LiveQuery whose `#start` is
+* already spent (`once`) — that reuse never opens SSE again and leaves "connecting…".
+*/
+function finish_spa_document() {
+	slots.remoteSeeds?.clear_remote_instances();
+}
+export { PAGE_SEED_SELECTOR, apply_soft_invalidate_doc, finish_spa_document, page_seed_of, parse_sidecar_text, prepare_spa_document, seed_data_of, seed_page_once, seed_parse_count, seed_remote_once };

package/dist/runtime/session.d.ts

@@ -0,0 +1,52 @@
+import { ConcurrencyGate } from "./concurrency.js";
+/** Cached SSR DOM (+ optional SWR endpoint) for `{#if}` remount of hydrate:none regions.
+ * Keyed by lake entry id — size is O(unique lakes on the page), not O(toggles).
+ * Cleared on SPA body swap via `reset()`. SWR refresh replaces the entry (does not grow). */
+export type LakeCacheEntry = {
+  frag: Node;
+  endpoint: string;
+  when: string;
+  /** `Date.now()` when this entry was first cached or last successfully revalidated. */
+  cachedAt: number;
+  /** Client TTL in ms; `0` = no expiry. */
+  maxAgeMs: number;
+};
+export declare class RuntimeSession {
+  #private;
+  /** Page-owned head nodes (see above). Survives `reset()`: it is the document's, not a page's. */
+  readonly page_head: WeakSet<Node>;
+  /** Island-owned head ELEMENTS still to watch (pruned when they leave the document). */
+  readonly island_head: Set<Element>;
+  /** Mark a node this document's page owns (the router / runtime inserted it for the page). */
+  claim_page_head(node: Node): void;
+  /** At boot: everything already in <head> came from the server — the page owns it. */
+  adopt_document_head(): void;
+  /** After an island's hydrate: the head elements it added (not in `before`, not page-owned) are
+   *  that island's; then retire the page's copies of them. */
+  record_island_head(before: ReadonlySet<Node>): void;
+  /**
+   * Remove every PAGE-owned head element that duplicates a live island-owned one (same markup), and
+   * the page's `<title>` once an island renders its own (the browser honours the first title, and
+   * the island's is the reactive one). Runs after an island hydrates and after a navigation merge.
+   */
+  retire_page_head_copies(): void;
+  readonly lake_cache: Map<string, LakeCacheEntry>;
+  readonly settled_lakes: WeakSet<Element>;
+  readonly initialized_lakes: Set<string>;
+  readonly server_gate: ConcurrencyGate;
+  /** The page facts answers rendered with (server/render-page.ts), queued at the answer seam
+   *  (`region_fragment`) for the next hydrate to merge into the page store (seeds.ts). */
+  readonly page_facts: string[];
+  get remote_seeded(): boolean;
+  mark_remote_seeded(): void;
+  get page_seeded(): boolean;
+  mark_page_seeded(): void;
+  get kit_page(): boolean | undefined;
+  set kit_page(v: boolean | undefined);
+  /** Insert/replace a lake cache entry; evict oldest if over LAKE_CACHE_MAX. */
+  set_lake_cache(id: string, entry: LakeCacheEntry): void;
+  settle_lakes_in(root: ParentNode): void;
+  reset(): void;
+}
+/** Process-wide session for the islands runtime (one client module graph). */
+export declare const runtime_session: RuntimeSession;