@ogygia/core 0.0.0 → 0.11.0

package/dist/runtime/frame-store.d.ts

@@ -0,0 +1,62 @@
+import { Frame } from "../frame.js";
+export type FrameFetcher = (signal: AbortSignal) => Promise<string>;
+/** Applied content for an address, if any. */
+export declare function peek(a: string): {
+  v: number;
+  html: string;
+} | null;
+/** Nothing applied and nothing in flight at this address (a batch may take it on). */
+export declare function is_idle(a: string): boolean;
+/** Next request ticket for an address. External channels (streaming, mutations) use this too. */
+export declare function ticket(a: string): number;
+/**
+ * Write a frame. Applied only if strictly newer than the current content; stale writes are
+ * dropped and reported `false`. Subscribers are notified on apply.
+ */
+export declare function write(f: Frame): boolean;
+/**
+ * Reserve an address whose content is arriving via an EXTERNAL batch stream (single-flight navigation). A region
+ * binder that mounts before its frame lands calls `ensure()`, sees this reservation, and JOINS it
+ * instead of starting its own fetch — so a navigation that pulls N regions makes ONE batch request,
+ * not N. `write()` fulfils the reservation when the frame arrives; `release()` fails it if the batch
+ * ends without one (the binder then falls back to its own fetch). No-op if content or a fetch is
+ * already present.
+ */
+export declare function reserve(a: string): void;
+/**
+ * Fail an unfulfilled reservation (the batch ended and no frame carried this address). Joined binders
+ * reject out of `ensure()` and retry with their own fetch. No-op once content has arrived.
+ */
+export declare function release(a: string): void;
+/** The error a joined reservation rejects with when its batch ended without its frame: the binder's
+ *  own fetch runs at once (nothing failed — the batch just did not carry it). */
+export declare const BATCH_MISS = "OgygiaBatchMiss";
+/**
+ * Subscribe to writes at an address. If content is ALREADY applied, the callback fires immediately
+ * with it (a late binder — e.g. a region that mounts after a batch stream already delivered its
+ * frame — catches up without a request). Returns an unsubscribe fn. While subscribed the entry
+ * never evicts; after the last unsubscribe it lingers EVICT_TTL then drops (unless re-bound).
+ */
+export declare function subscribe(a: string, cb: (f: Frame) => void): () => void;
+/**
+ * Ensure an address has content, deduping concurrent callers onto one fetch.
+ *
+ * - Content already applied (and not `force`): resolves immediately with it.
+ * - A fetch is in flight (and not `force`): joins it — N regions, ONE request.
+ * - Otherwise starts `fetcher` with a fresh ticket; on success the response is WRITTEN (subject to
+ *   the staleness check) and the resolved value is whatever the store now holds.
+ * - `force` (SWR revalidate) always starts a new fetch; the ticket ordering still guarantees an
+ *   older in-flight response can't overwrite it.
+ *
+ * Rejections propagate to every joined caller; retry policy stays with the caller (the element).
+ */
+export declare function ensure(a: string, fetcher: FrameFetcher, opts?: {
+  force?: boolean;
+}): Promise<string>;
+/**
+ * A waiter is leaving (its element disconnected). Aborts the shared fetch only when the LAST
+ * waiter leaves — one unmounting element must not kill a fetch its twin still awaits.
+ */
+export declare function abandon(a: string): void;
+/** Test/HMR hook — drop everything. */
+export declare function _reset(): void;

package/dist/runtime/frame-store.js

@@ -0,0 +1,214 @@
+import { notify, watch, watcher_count } from "../ref-watch.js";
+// src/runtime/frame-store.ts
+/** Frame addresses live in the hub's watcher space under a namespace, so region binders subscribe
+*  through the ONE hub `watch`/`notify` primitive (hub v2 phase W) — the frame store no longer owns
+*  a parallel subscriber set. Fetch orchestration (ticket, inflight, reserve, evict) stays here. */
+const frame_id = (a) => "frame:" + a;
+/** Entries with no subscribers linger this long (ms) so quick remounts / SPA swaps reuse content. */
+const EVICT_TTL = 6e4;
+const GLOBAL_KEY = "__ogygia_frames__";
+const store_host = typeof globalThis !== "undefined" ? globalThis : {};
+const entries = store_host[GLOBAL_KEY] ?? (store_host[GLOBAL_KEY] = /* @__PURE__ */ new Map());
+function entry(a) {
+	let e = entries.get(a);
+	if (!e) {
+		e = {
+			v: 0,
+			html: null,
+			seq: 0,
+			inflight: null,
+			evict: null
+		};
+		entries.set(a, e);
+	}
+	return e;
+}
+/**
+* Let an idle entry (no subscribers, no in-flight fetch) linger EVICT_TTL, then drop it. A late binder
+* that mounts inside the window still catches its content (prefetch / batch-stream ahead of the DOM);
+* nothing bound means nothing to keep. Idempotent — resets the timer. Both channels that leave an
+* entry idle call this: a subscriber unbinding, AND a `write()` that lands where nothing is listening
+* (a single-flight mutation for an unmounted region, or a live tick whose address keeps changing).
+* Without the write path, those orphan entries would accumulate forever — they never had a subscriber
+* to trigger eviction.
+*/
+function schedule_evict(a, e) {
+	if (watcher_count(frame_id(a)) > 0 || e.inflight) return;
+	if (e.evict) clearTimeout(e.evict);
+	e.evict = setTimeout(() => {
+		const cur = entries.get(a);
+		if (cur === e && watcher_count(frame_id(a)) === 0 && !cur.inflight) entries.delete(a);
+	}, EVICT_TTL);
+}
+/** Applied content for an address, if any. */
+function peek(a) {
+	const e = entries.get(a);
+	return e && e.html != null ? {
+		v: e.v,
+		html: e.html
+	} : null;
+}
+/** Nothing applied and nothing in flight at this address (a batch may take it on). */
+function is_idle(a) {
+	const e = entries.get(a);
+	return !e || e.html == null && !e.inflight;
+}
+/** Next request ticket for an address. External channels (streaming, mutations) use this too. */
+function ticket(a) {
+	return ++entry(a).seq;
+}
+/**
+* Write a frame. Applied only if strictly newer than the current content; stale writes are
+* dropped and reported `false`. Subscribers are notified on apply.
+*/
+function write(f) {
+	const e = entry(f.a);
+	if (f.v <= e.v) return false;
+	if (f.v > e.seq) e.seq = f.v;
+	e.v = f.v;
+	e.html = f.html;
+	const held = e.inflight;
+	if (held?.settle) {
+		e.inflight = null;
+		held.settle(f.html);
+	}
+	notify(frame_id(f.a), f);
+	schedule_evict(f.a, e);
+	return true;
+}
+/**
+* Reserve an address whose content is arriving via an EXTERNAL batch stream (single-flight navigation). A region
+* binder that mounts before its frame lands calls `ensure()`, sees this reservation, and JOINS it
+* instead of starting its own fetch — so a navigation that pulls N regions makes ONE batch request,
+* not N. `write()` fulfils the reservation when the frame arrives; `release()` fails it if the batch
+* ends without one (the binder then falls back to its own fetch). No-op if content or a fetch is
+* already present.
+*/
+function reserve(a) {
+	const e = entry(a);
+	if (e.html != null || e.inflight) return;
+	if (e.evict) {
+		clearTimeout(e.evict);
+		e.evict = null;
+	}
+	let settle;
+	let fail;
+	const promise = new Promise((res, rej) => {
+		settle = res;
+		fail = rej;
+	});
+	promise.catch(() => {});
+	e.inflight = {
+		ticket: ticket(a),
+		promise,
+		controller: new AbortController(),
+		waiters: 0,
+		settle,
+		fail
+	};
+}
+/**
+* Fail an unfulfilled reservation (the batch ended and no frame carried this address). Joined binders
+* reject out of `ensure()` and retry with their own fetch. No-op once content has arrived.
+*/
+function release(a) {
+	const e = entries.get(a);
+	const held = e?.inflight;
+	if (!e || !held?.fail || e.html != null) return;
+	e.inflight = null;
+	const miss = /* @__PURE__ */ new Error("ogygia batch: no frame for " + a);
+	miss.name = BATCH_MISS;
+	held.fail(miss);
+	schedule_evict(a, e);
+}
+/** The error a joined reservation rejects with when its batch ended without its frame: the binder's
+*  own fetch runs at once (nothing failed — the batch just did not carry it). */
+const BATCH_MISS = "OgygiaBatchMiss";
+/**
+* Subscribe to writes at an address. If content is ALREADY applied, the callback fires immediately
+* with it (a late binder — e.g. a region that mounts after a batch stream already delivered its
+* frame — catches up without a request). Returns an unsubscribe fn. While subscribed the entry
+* never evicts; after the last unsubscribe it lingers EVICT_TTL then drops (unless re-bound).
+*/
+function subscribe(a, cb) {
+	const e = entry(a);
+	if (e.evict) {
+		clearTimeout(e.evict);
+		e.evict = null;
+	}
+	const off = watch(frame_id(a), cb);
+	if (e.html != null) cb({
+		a,
+		v: e.v,
+		html: e.html
+	});
+	return () => {
+		off();
+		schedule_evict(a, e);
+	};
+}
+/**
+* Ensure an address has content, deduping concurrent callers onto one fetch.
+*
+* - Content already applied (and not `force`): resolves immediately with it.
+* - A fetch is in flight (and not `force`): joins it — N regions, ONE request.
+* - Otherwise starts `fetcher` with a fresh ticket; on success the response is WRITTEN (subject to
+*   the staleness check) and the resolved value is whatever the store now holds.
+* - `force` (SWR revalidate) always starts a new fetch; the ticket ordering still guarantees an
+*   older in-flight response can't overwrite it.
+*
+* Rejections propagate to every joined caller; retry policy stays with the caller (the element).
+*/
+function ensure(a, fetcher, opts = {}) {
+	const e = entry(a);
+	if (!opts.force) {
+		if (e.html != null) return Promise.resolve(e.html);
+		if (e.inflight) {
+			e.inflight.waiters++;
+			return e.inflight.promise;
+		}
+	}
+	const controller = new AbortController();
+	const t = ticket(a);
+	const inflight = {
+		ticket: t,
+		controller,
+		waiters: 1,
+		promise: fetcher(controller.signal).then((html) => {
+			if (e.inflight === inflight) e.inflight = null;
+			write({
+				a,
+				v: t,
+				html
+			});
+			return e.html ?? html;
+		}, (err) => {
+			if (e.inflight === inflight) e.inflight = null;
+			throw err;
+		})
+	};
+	e.inflight = inflight;
+	return inflight.promise;
+}
+/**
+* A waiter is leaving (its element disconnected). Aborts the shared fetch only when the LAST
+* waiter leaves — one unmounting element must not kill a fetch its twin still awaits.
+*/
+function abandon(a) {
+	const e = entries.get(a);
+	if (!e?.inflight) return;
+	if (--e.inflight.waiters <= 0) {
+		e.inflight.controller.abort();
+		e.inflight = null;
+	}
+}
+/** Test/HMR hook — drop everything. */
+function _reset() {
+	for (const e of entries.values()) {
+		if (e.evict) clearTimeout(e.evict);
+		e.inflight?.fail?.(/* @__PURE__ */ new Error("reset"));
+		e.inflight?.controller.abort();
+	}
+	entries.clear();
+}
+export { BATCH_MISS, _reset, abandon, ensure, is_idle, peek, release, reserve, subscribe, ticket, write };

package/dist/runtime/frames.d.ts

@@ -0,0 +1 @@
+export declare function install(): void;

package/dist/runtime/frames.js

@@ -0,0 +1,25 @@
+import { slots } from "./slots.js";
+import { abandon, ensure, subscribe } from "./frame-store.js";
+import { batch_times, join_batch, streamFrames } from "./frame-nav.js";
+// src/runtime/frames.ts
+/**
+* frames feature: hand the client frame store to core through the {@link ./slots.js slots} seam.
+*
+* Core drives deferred / live / SWR-lake regions off this store (subscribe → apply, ensure →
+* single-flight fetch, abandon → cleanup), and the router single-flights a route's deferred holes through
+* `stream` — but NEITHER may statically import the store, or the ~10 kB store + nav-stream graph
+* lands in every build, including a plain router app with no such region. The generated runtime entry
+* installs this feature only when the app actually ships a deferred / live / lake region, so a
+* static-islands app (and a router app without deferred regions) tree-shakes the whole graph away.
+*/
+function install() {
+	slots.frames = {
+		subscribe,
+		ensure,
+		abandon,
+		stream: streamFrames,
+		join: join_batch,
+		batch_times
+	};
+}
+export { install };

package/dist/runtime/full.d.ts

@@ -0,0 +1,4 @@
+import { ClientPlugin } from "../plugin/client.js";
+/** Boot the kitchen-sink runtime (all boot-phase features) with the plugins' browser halves.
+ *  Idempotent via {@link ./core.js boot}. */
+export declare function bootDev(client_plugins?: readonly ClientPlugin[]): void;

package/dist/runtime/full.js

@@ -0,0 +1,32 @@
+import { boot } from "./core.js";
+import { install } from "./frames.js";
+import { install as install$1 } from "./lakes.js";
+import { install as install$2 } from "./morph.js";
+import { install as install$3 } from "./interaction.js";
+import { install as install$4 } from "./form-continuity.js";
+import { install as install$5 } from "./router.js";
+// src/runtime/full.ts
+/**
+* Kitchen-sink browser runtime — every BOOT-phase feature installed. The dev / no-marks entry: the
+* ogygia compiler injects `bootDev()` (see the plugin's `virtual:ogygia-runtime`); a per-app production
+* build instead emits a generated entry (see `vite/runtime-entry.ts`) that boots only the features it
+* uses. Both boot through {@link ./core.js core} in the same {@link ../vite/runtime-entry.js FEATURE_ORDER}.
+* HYDRATE-phase features (context, live, wire, remote-seeds) are never in the boot, dev included: the
+* hydrate core installs them from `virtual:ogygia/hydrate-features` (every one, in dev).
+*
+* Exposed as an explicit FUNCTION, not a top-level side effect: the compiler always calls it, so the
+* boot never depends on a bundler honouring `sideEffects` to survive tree-shaking / dep-prebundling.
+*/
+/** Boot the kitchen-sink runtime (all boot-phase features) with the plugins' browser halves.
+*  Idempotent via {@link ./core.js boot}. */
+function bootDev(client_plugins = []) {
+	boot([
+		install,
+		install$1,
+		install$2,
+		install$3,
+		install$4,
+		install$5
+	], client_plugins);
+}
+export { bootDev };

package/dist/runtime/hash.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Region fingerprint — the PURE core (no DOM, no imports) shared by the client reconciler AND the
+ * server (Region.svelte, server-delta nav). Kept dependency-free so it is safe in BOTH bundles and
+ * so client↔server fingerprints are IDENTICAL BY CONSTRUCTION: the server emits `data-og-fp =
+ * fingerprint_of(entry, '', props_payload)` on each island, and the client's `region_props_fp`
+ * reads the same entry attribute + '' endpoint + props-script text → the same hash. That parity is
+ * what makes server-delta nav safe (the server skips exactly the regions the client says it has).
+ *
+ *   • signature   — WHICH region slot (entry + the endpoint's stable id/props, minus exp/sig).
+ *   • fingerprint — DID ITS INPUTS CHANGE (hash of entry + endpoint + the props seed).
+ */
+/** 64-bit fingerprint over a string → 16-char hex. Two independent 32-bit lanes (FNV-1a-32 and an
+ *  FNV-style lane with murmur's mixing constant + an xorshift), concatenated. 64 bits on purpose:
+ *  the server-delta SKIPS a region on a fingerprint match, so a collision would keep stale/wrong
+ *  content silently — 64 bits makes that a non-risk on any real page. NOT canonical FNV-1a-64: the
+ *  previous BigInt implementation cost 20 ms per island on a CMS page whose props run to 480 KB
+ *  (one BigInt allocation per character — 0.4 s of a 3.7 s server render, seen in the profiler);
+ *  this loop is pure int32 arithmetic and hashes the same page in about a millisecond. Parity is by
+ *  construction — the same function runs on both legs — so the algorithm is free to change. */
+export declare function fnv1a(s: string): string;
+/** WHICH COPY of a hole: copies of one component share its id, and differ by their props. The key is
+ *  a short hash of the props PAYLOAD as it rides in the hole's signed endpoint (`?props=`) — the one
+ *  string the server's request, the page's note and the browser's report all hold, verbatim. */
+export declare function hole_copy_key(payload: string): string;
+/** The copy key of a hole endpoint (its `props` parameter), or '' when it has none. */
+export declare function hole_copy_of(endpoint: string): string;
+/** FNV-1a 32-bit over a string → uint32. The NUMERIC sibling for callers that bucket/mod rather
+ *  than compare (experiment splits, build-cache keys) — no BigInt, no hex round-trip. This is THE
+ *  one shared implementation; the driver/vite copies were folded into it. */
+export declare function fnv1a32(s: string): number;
+/**
+ * The stable part of a signed endpoint URL: everything up to the volatile `&exp=…&sig=…` tail.
+ * A deferred region's endpoint encodes `?id=…&props=…&exp=…&sig=…`; exp/sig rotate per render, so
+ * they must NOT enter identity or two renders of the same region would never match. Returns the
+ * `id`+`props` portion; empty string when there is no endpoint.
+ */
+export declare function endpoint_key(endpoint: string): string;
+/** Match key: WHICH region slot this is (testable without a DOM). */
+export declare function signature_of(entry: string, endpoint: string): string;
+/** Change key: DID this region's inputs change (testable without a DOM). */
+export declare function fingerprint_of(entry: string, endpoint: string, props_text: string): string;

package/dist/runtime/hash.js

@@ -0,0 +1,79 @@
+// src/runtime/hash.ts
+/**
+* Region fingerprint — the PURE core (no DOM, no imports) shared by the client reconciler AND the
+* server (Region.svelte, server-delta nav). Kept dependency-free so it is safe in BOTH bundles and
+* so client↔server fingerprints are IDENTICAL BY CONSTRUCTION: the server emits `data-og-fp =
+* fingerprint_of(entry, '', props_payload)` on each island, and the client's `region_props_fp`
+* reads the same entry attribute + '' endpoint + props-script text → the same hash. That parity is
+* what makes server-delta nav safe (the server skips exactly the regions the client says it has).
+*
+*   • signature   — WHICH region slot (entry + the endpoint's stable id/props, minus exp/sig).
+*   • fingerprint — DID ITS INPUTS CHANGE (hash of entry + endpoint + the props seed).
+*/
+/** 64-bit fingerprint over a string → 16-char hex. Two independent 32-bit lanes (FNV-1a-32 and an
+*  FNV-style lane with murmur's mixing constant + an xorshift), concatenated. 64 bits on purpose:
+*  the server-delta SKIPS a region on a fingerprint match, so a collision would keep stale/wrong
+*  content silently — 64 bits makes that a non-risk on any real page. NOT canonical FNV-1a-64: the
+*  previous BigInt implementation cost 20 ms per island on a CMS page whose props run to 480 KB
+*  (one BigInt allocation per character — 0.4 s of a 3.7 s server render, seen in the profiler);
+*  this loop is pure int32 arithmetic and hashes the same page in about a millisecond. Parity is by
+*  construction — the same function runs on both legs — so the algorithm is free to change. */
+function fnv1a(s) {
+	let a = 2166136261;
+	let b = 522970236;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		a ^= c;
+		a = Math.imul(a, 16777619);
+		b ^= c;
+		b = Math.imul(b, 668265263);
+		b ^= b >>> 15;
+	}
+	return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+}
+/** WHICH COPY of a hole: copies of one component share its id, and differ by their props. The key is
+*  a short hash of the props PAYLOAD as it rides in the hole's signed endpoint (`?props=`) — the one
+*  string the server's request, the page's note and the browser's report all hold, verbatim. */
+function hole_copy_key(payload) {
+	return fnv1a32(payload).toString(36);
+}
+/** The copy key of a hole endpoint (its `props` parameter), or '' when it has none. */
+function hole_copy_of(endpoint) {
+	let at = endpoint.indexOf("&props=");
+	if (at === -1) at = endpoint.indexOf("?props=");
+	if (at === -1) return "";
+	at += 7;
+	const end = endpoint.indexOf("&", at);
+	return hole_copy_key(endpoint.slice(at, end === -1 ? endpoint.length : end));
+}
+/** FNV-1a 32-bit over a string → uint32. The NUMERIC sibling for callers that bucket/mod rather
+*  than compare (experiment splits, build-cache keys) — no BigInt, no hex round-trip. This is THE
+*  one shared implementation; the driver/vite copies were folded into it. */
+function fnv1a32(s) {
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return h >>> 0;
+}
+/**
+* The stable part of a signed endpoint URL: everything up to the volatile `&exp=…&sig=…` tail.
+* A deferred region's endpoint encodes `?id=…&props=…&exp=…&sig=…`; exp/sig rotate per render, so
+* they must NOT enter identity or two renders of the same region would never match. Returns the
+* `id`+`props` portion; empty string when there is no endpoint.
+*/
+function endpoint_key(endpoint) {
+	if (!endpoint) return "";
+	const exp = endpoint.indexOf("&exp=");
+	return exp === -1 ? endpoint : endpoint.slice(0, exp);
+}
+/** Match key: WHICH region slot this is (testable without a DOM). */
+function signature_of(entry, endpoint) {
+	return entry + " " + endpoint_key(endpoint);
+}
+/** Change key: DID this region's inputs change (testable without a DOM). */
+function fingerprint_of(entry, endpoint, props_text) {
+	return fnv1a(entry + " " + endpoint_key(endpoint) + " " + props_text);
+}
+export { endpoint_key, fingerprint_of, fnv1a, fnv1a32, hole_copy_key, hole_copy_of, signature_of };

package/dist/runtime/hole-facts.d.ts

@@ -0,0 +1,8 @@
+export type HoleFacts = {
+  /** The signed capability URL the server minted. */
+  endpoint: string;
+  /** A hydrating hole's props sidecar, rebuilt from the recorded HTML; `null` for a static hole. */
+  sidecar: HTMLScriptElement | null;
+};
+/** The server-minted facts of the hole with this identity on `doc`, or `null`. */
+export declare function hole_facts_of(doc: Document, identity: string): HoleFacts | null;

package/dist/runtime/hole-facts.js

@@ -0,0 +1,57 @@
+import { HOLES_SCRIPT_TYPE } from "../holes-record.js";
+// src/runtime/hole-facts.ts
+/**
+* THE HOLES RECORD — what the server minted for each deferred hole on a KIT-HYDRATED document,
+* keyed by the hole's identity (`data-og-hole`: the fingerprint of region id + canonical props,
+* computed the same way on both legs). The handle emits it in the document tail
+* (`<script type="application/ogygia-holes">`, server/document-tail.ts), OUTSIDE Kit's root.
+*
+* Why it exists: Kit can give up hydrating such a document — a component threw while hydrating,
+* the markup mismatched — and Svelte then clears Kit's root and mounts it fresh. Every hole is
+* rendered again by the client leg, which cannot mint a signed address: `endpoint=""`, no props
+* sidecar, the fallback standing forever (a site header's account holes went dark this way for
+* signed-in visitors). The record survives the rebuild, so a rebuilt hole gets its facts back the
+* moment it connects, by identity — never by position — and fetches exactly as the SSR element
+* would have. Read lazily, parsed once per document.
+*/
+const HOLES_SELECTOR = `script[type="${HOLES_SCRIPT_TYPE}"]`;
+/** One parse per document: the record, or `null` when the document carries none. */
+const records = /* @__PURE__ */ new WeakMap();
+function parse_record(doc) {
+	const el = doc.querySelector(HOLES_SELECTOR);
+	if (!el) return null;
+	let raw;
+	try {
+		raw = JSON.parse(el.textContent || "");
+	} catch {
+		return null;
+	}
+	const map = /* @__PURE__ */ new Map();
+	for (const identity in raw) {
+		const entry = raw[identity];
+		if (!entry || typeof entry.endpoint !== "string" || !entry.endpoint) continue;
+		map.set(identity, {
+			endpoint: entry.endpoint,
+			sidecar: typeof entry.sidecar === "string" && entry.sidecar ? sidecar_element(doc, entry.sidecar) : null
+		});
+	}
+	return map;
+}
+/** The recorded sidecar HTML back into a script element (off the DOM; a `<template>` parses it
+*  without running anything — the sidecar is a data script, never executable). */
+function sidecar_element(doc, html) {
+	const holder = doc.createElement("template");
+	holder.innerHTML = html;
+	const el = holder.content.firstElementChild;
+	return el && el.tagName === "SCRIPT" ? el : null;
+}
+/** The server-minted facts of the hole with this identity on `doc`, or `null`. */
+function hole_facts_of(doc, identity) {
+	let record = records.get(doc);
+	if (record === void 0) {
+		record = parse_record(doc);
+		records.set(doc, record);
+	}
+	return record?.get(identity) ?? null;
+}
+export { hole_facts_of };

package/dist/runtime/host-classes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A WEB COMPONENT'S OWN CLASS TOKENS SURVIVE HYDRATION. A custom element's `class` has two writers:
+ * Svelte (the author's classes) and the component itself, which may put state on its own host (a
+ * theme over a dark image, an indicator position). Svelte's hydration writes `class` WHOLE whenever
+ * it differs from Svelte's value (svelte `set_class`), so every token the component added before
+ * the island woke was dropped — and a component that does not render again never puts it back.
+ *
+ * Ogygia knows which tokens are Svelte's for each custom element the restorer reset
+ * (runtime/restore.ts records them as `__og_svelte_class`): everything else on that host is the
+ * component's. So around an island's hydrate: before it, note each such host's non-Svelte tokens;
+ * after it, put back the ones Svelte's write removed. The tokens are read JUST BEFORE the hydrate,
+ * not as served: between restore and hydrate the component's own first render (or a script of its)
+ * may have added or dropped one from client state, and that is what it wants now. Either order of
+ * that render and the hydrate ends the same. Svelte's own tokens are never touched (a
+ * client value that differs from the server's still wins), and an element hydration replaced is
+ * skipped. An app without a server transform has no such hosts and pays one property read per
+ * custom element in the island.
+ */
+/** The expando the restorer writes on a custom element it reset: Svelte's class, as Svelte rendered it. */
+export declare const SVELTE_CLASS = "__og_svelte_class";
+/** Each restored custom element under `region` with tokens that are not Svelte's: [host, tokens]. */
+export declare function note_host_classes(region: Element): Array<[Element, string[]]> | null;
+/** Put back the component's tokens a hydration write removed. */
+export declare function keep_host_classes(noted: Array<[Element, string[]]> | null): void;

package/dist/runtime/host-classes.js

@@ -0,0 +1,43 @@
+// src/runtime/host-classes.ts
+/**
+* A WEB COMPONENT'S OWN CLASS TOKENS SURVIVE HYDRATION. A custom element's `class` has two writers:
+* Svelte (the author's classes) and the component itself, which may put state on its own host (a
+* theme over a dark image, an indicator position). Svelte's hydration writes `class` WHOLE whenever
+* it differs from Svelte's value (svelte `set_class`), so every token the component added before
+* the island woke was dropped — and a component that does not render again never puts it back.
+*
+* Ogygia knows which tokens are Svelte's for each custom element the restorer reset
+* (runtime/restore.ts records them as `__og_svelte_class`): everything else on that host is the
+* component's. So around an island's hydrate: before it, note each such host's non-Svelte tokens;
+* after it, put back the ones Svelte's write removed. The tokens are read JUST BEFORE the hydrate,
+* not as served: between restore and hydrate the component's own first render (or a script of its)
+* may have added or dropped one from client state, and that is what it wants now. Either order of
+* that render and the hydrate ends the same. Svelte's own tokens are never touched (a
+* client value that differs from the server's still wins), and an element hydration replaced is
+* skipped. An app without a server transform has no such hosts and pays one property read per
+* custom element in the island.
+*/
+/** The expando the restorer writes on a custom element it reset: Svelte's class, as Svelte rendered it. */
+const SVELTE_CLASS = "__og_svelte_class";
+/** Each restored custom element under `region` with tokens that are not Svelte's: [host, tokens]. */
+function note_host_classes(region) {
+	let out = null;
+	for (const el of region.getElementsByTagName("*")) {
+		const svelte = el[SVELTE_CLASS];
+		if (svelte === void 0) continue;
+		const own = new Set(svelte.split(" "));
+		let theirs = null;
+		for (const t of el.classList) if (!own.has(t)) (theirs ??= []).push(t);
+		if (theirs) (out ??= []).push([el, theirs]);
+	}
+	return out;
+}
+/** Put back the component's tokens a hydration write removed. */
+function keep_host_classes(noted) {
+	if (!noted) return;
+	for (const [el, theirs] of noted) {
+		if (!el.isConnected) continue;
+		for (const t of theirs) if (!el.classList.contains(t)) el.classList.add(t);
+	}
+}
+export { SVELTE_CLASS, keep_host_classes, note_host_classes };