@ogygia/core 0.12.2 → 0.13.0

package/dist/runtime/session.js

@@ -1,9 +1,12 @@
 import { ConcurrencyGate } from "./concurrency.js";
 import { FROZEN_SELECTOR } from "./region-attrs.js";
+import { note_visit } from "./rules.js";
+import { scope } from "@ogygia/machine";
 // src/runtime/session.ts
 /**
-* Document-scoped runtime session: lake caches, seed flags, kit-page probe, server-island gate.
-* Cleared on SPA body swap via `reset()` so connecting regions never see the previous page.
+* Document-scoped runtime session: lake caches, seed flags, kit-page probe, server-island gate, and
+* the page visit. Cleared on SPA body swap via `reset()` so connecting regions never see the previous
+* page.
 */
 /** Soft cap on lake cache entries (unique lake ids). Evict oldest insertion on overflow. */
 const LAKE_CACHE_MAX = 64;
@@ -28,6 +31,31 @@ const LAKE_CACHE_MAX = 64;
 * copy could unstyle the page for a frame; a doubled sheet is harmless).
 */
 const STYLESHEET_REL_RE = /(?:^|\s)stylesheet(?:\s|$)/i;
+const RULES = import.meta.env?.DEV || (typeof __OGYGIA_RULES__ !== "undefined" ? __OGYGIA_RULES__ : false);
+function page_visit() {
+	const visit = {
+		scope: scope(),
+		facts: []
+	};
+	if (RULES) note_visit(visit, false);
+	return visit;
+}
+/**
+* The head's element children that a step added, from its child-list records: a node's first
+* record says whether it was a child before the step (removed first: it was; added first: it was
+* not), and it counts only if it is still a child at the end.
+*/
+function added_children(head, records) {
+	const was_child = /* @__PURE__ */ new Map();
+	for (const r of records) {
+		for (const n of r.removedNodes) if (!was_child.has(n)) was_child.set(n, true);
+		for (const n of r.addedNodes) if (!was_child.has(n)) was_child.set(n, false);
+	}
+	const out = [];
+	for (const [n, was] of was_child) if (!was && n.nodeType === 1 && n.parentNode === head) out.push(n);
+	if (out.length > 1) out.sort((a, b) => a.compareDocumentPosition(b) & 4 ? -1 : 1);
+	return out;
+}
 var RuntimeSession = class {
 	/** Page-owned head nodes (see above). Survives `reset()`: it is the document's, not a page's. */
 	page_head = /* @__PURE__ */ new WeakSet();
@@ -42,11 +70,38 @@ var RuntimeSession = class {
 		if (typeof document === "undefined") return;
 		for (const n of document.head.children) this.page_head.add(n);
 	}
-	/** 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) {
+	/**
+	* Before an island's hydrate step: start noting what lands in `<head>`. A MutationObserver on the
+	* head's own children, read synchronously when the step ends, so the record costs what the island
+	* added, not the whole head (a copy of the head per island grew as islands × head). Without
+	* MutationObserver: the head's elements, copied.
+	*/
+	mark_head() {
+		const head = document.head;
+		if (typeof MutationObserver === "undefined") {
+			const before = new Set(head.children);
+			return {
+				added: () => Array.from(head.children).filter((n) => !before.has(n)),
+				stop: () => {}
+			};
+		}
+		const delivered = [];
+		const watch = new MutationObserver((records) => delivered.push(...records));
+		watch.observe(head, { childList: true });
+		return {
+			added: () => {
+				const records = delivered.concat(watch.takeRecords());
+				watch.disconnect();
+				return added_children(head, records);
+			},
+			stop: () => watch.disconnect()
+		};
+	}
+	/** After an island's hydrate: the head elements it added (not there before the step, not
+	*  page-owned) are that island's; then retire the page's copies of them. */
+	record_island_head(mark) {
 		let added = false;
-		for (const n of document.head.children) if (!before.has(n) && !this.page_head.has(n)) {
+		for (const n of mark.added()) if (!this.page_head.has(n)) {
 			this.island_head.add(n);
 			added = true;
 		}
@@ -79,9 +134,16 @@ var RuntimeSession = class {
 	settled_lakes = /* @__PURE__ */ new WeakSet();
 	initialized_lakes = /* @__PURE__ */ new Set();
 	server_gate = new ConcurrencyGate(3);
-	/** 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). */
-	page_facts = [];
+	#visit = page_visit();
+	/** The visit of the page on screen (see {@link PageVisit}). */
+	get visit() {
+		return this.#visit;
+	}
+	/** The visit of the page a navigation brings, made before its swap: the navigation's (it ends
+	*  it when there is no swap) until `reset(next)` makes it the page. */
+	next_visit() {
+		return page_visit();
+	}
 	#remote_seeded = false;
 	#page_seeded = false;
 	#kit_page;
@@ -117,12 +179,18 @@ var RuntimeSession = class {
 		if (root instanceof Element && root.matches?.("ogygia-region[wake=\"none\"]")) this.settled_lakes.add(root);
 		for (const lake of root.querySelectorAll(FROZEN_SELECTOR)) this.settled_lakes.add(lake);
 	}
-	reset() {
+	/** The next page takes over (its visit, made by its navigation; a new one when none is given),
+	*  and the visit of the page it replaces ends. */
+	reset(next = page_visit()) {
+		const left = this.#visit;
+		this.#visit = next;
+		if (RULES) note_visit(next, true);
 		this.#kit_page = void 0;
 		this.#remote_seeded = false;
 		this.#page_seeded = false;
 		this.lake_cache.clear();
 		this.initialized_lakes.clear();
+		if (left !== next) left.scope.close();
 	}
 };
 /** Process-wide session for the islands runtime (one client module graph). */

package/dist/runtime/slots.d.ts

@@ -1,3 +1,4 @@
+import { WakeFn, resolve_address } from "./interaction.js";
 import { KitBoot, kit_hydrates_page } from "./kit-boot.js";
 import { register_island_graph } from "./island-graph-preload.js";
 import { is_warmed_module, warm_island_module } from "./region-endpoint-url.js";
@@ -6,15 +7,19 @@ import { props_sidecar_of } from "./sidecar.js";
 import { parse_region_html } from "./parse-html.js";
 import { runtime_session } from "./session.js";
 import { regions_in_shadow } from "./connected.js";
+import { release_sheets } from "./region-sheets.js";
 import { yield_task } from "./schedule.js";
 import { beacon_nav } from "./beacon.js";
-import { load_slot } from "./load-scheduler.js";
+import { LoadSlot } from "./load-scheduler.js";
 import { is_self_owned, record_server_body, server_body_attributes, server_body_child, walk_enters } from "./ownership.js";
-import { document_key, jump_to_hash, push_state, replace_state } from "./router.js";
-import { resolve_address } from "./interaction.js";
+import { devalue, load_devalue, needs_devalue, with_devalue } from "./devalue-lane.js";
+import { OgygiaError, warn } from "../messages/core.js";
+import { SoftRefresh } from "./soft-refresh.js";
+import { jump_to_hash } from "./router.js";
+import { PushableProps } from "./pushable-props.svelte.js";
 import { sync_attributes } from "./morph.js";
 import { Frame } from "../frame.js";
-import { Component } from "svelte";
+import { Scope, Stale } from "@ogygia/machine";
 /** Frozen SSR DOM detached before hydrate. */
 export type LiftedLake = {
   id: string;
@@ -38,9 +43,10 @@ export type LakeOps = {
   restore(parent: Element, lifted: LiftedLake[]): void;
   settle_in(root: ParentNode): void;
   mark_frozen_settled(region: HTMLElement): void;
+  /** After an answer swapped into `region`: a lake that settled wakes the regions waiting on it. */
   after_html_swap(region: HTMLElement, opts: {
     revalidate?: boolean;
-  }): void;
+  }, wake_children: () => void): void;
   after_fetch_exhausted(region: HTMLElement, opts: {
     revalidate?: boolean;
   }, wake_children: () => void): void;
@@ -50,8 +56,11 @@ export type FormOps = {
   snapshot(root: ParentNode, pathKey: string): void;
   restore(pathKey: string): void;
 };
-/** Wake a cold island when interaction lands inside it; returns a disarm fn. */
-export type ArmFn = (el: HTMLElement, fire: () => void) => void | (() => void);
+/** Wake a cold island when interaction lands inside it; returns a disarm fn (`over`: the region
+ *  left while it was waking — the clicks it queued are dropped, not replayed). `fire` gets what
+ *  replays the visitor's input (./interaction.ts `WakeFn`): the island goes live once it is in.
+ *  `owner`: the region's lifetime in the page, which the replay's frame belongs to. */
+export type ArmFn = (el: HTMLElement, fire: WakeFn, owner: Scope) => void | ((over?: boolean) => void);
 /** `target: 'walk'` = the hydration repair (the server sequence Svelte's walk binds); default = a live
  *  morph toward a new answer. Same ownership rules either way (runtime/ownership.ts). `stays`: a
  *  child of `parent` the morph steps over (the page's own, beside the render's). */
@@ -79,8 +88,9 @@ export type PageOps = {
   seed_page_once(): void;
   /** the `page.data` a seed reference in island props resolves against */
   seed_data_of(doc: Document): unknown;
-  /** on a Kit-hydrated document: the wait for Kit to apply its page (`null` once applied) */
-  kit_page_thread(): Promise<void> | null;
+  /** on a Kit-hydrated document: the wait for Kit to apply its page (`null` once applied), for as
+   *  long as `signal` (the waiting region's visit) lasts */
+  kit_page_thread(signal?: AbortSignal): Promise<unknown> | null;
 };
 /**
  * The client frame store, filled by the `frames` feature. Core reads it ONLY on the deferred /
@@ -89,17 +99,22 @@ export type PageOps = {
  */
 export type FrameOps = {
   subscribe(a: string, cb: (f: Frame) => void): () => void;
+  /** `STALE` when its `signal` aborted: only that caller leaves the fetch. */
   ensure(a: string, fetcher: (signal: AbortSignal) => Promise<string>, opts?: {
     force?: boolean;
-  }): Promise<string>;
-  abandon(a: string): void;
+    signal?: AbortSignal;
+  }): Promise<string | Stale>;
+  /** A renewal answered a fresh capability for this address; and the one it answered, if any. */
+  renew(a: string, fresh: string): void;
+  renewal(a: string): string | null;
   /**
    * SINGLE-FLIGHT NAVIGATION: batch a page's signed deferred endpoints into the store as one streamed response. Lives
    * on the seam (not a static router import) so an app with `router` but no deferred/live/lake region
    * — hence no `frames` feature — never bundles the frame store. The router optional-chains this: no
-   * frames feature ⇒ no `render="defer"` holes to batch ⇒ the call never fires anyway.
+   * frames feature ⇒ no `render="defer"` holes to batch ⇒ the call never fires anyway. `visit`: the
+   * scope of the page the holes are for (./session.ts `PageVisit`); the batch stops when it ends.
    */
-  stream(endpoints: string[]): Promise<void>;
+  stream(endpoints: string[], visit: import("@ogygia/machine").Scope): Promise<void>;
   /** Holes that start fetching in the same task go out as one batch (frame-nav.ts `join_batch`);
    *  await it, then `ensure` joins the batch's reservation. */
   join?(endpoint: string): Promise<void>;
@@ -143,11 +158,13 @@ export type BootLink = {
   parse_region_html: typeof parse_region_html;
   runtime_session: typeof runtime_session;
   regions_in_shadow: typeof regions_in_shadow;
+  /** the region sheets a navigation's head merge left, taken out but for those a region uses */
+  release_sheets: typeof release_sheets;
   yield_task: typeof yield_task;
   /** the router's navigation, timed for the profiler's beacon (a no-op without it) */
   beacon_nav: typeof beacon_nav;
   /** the load scheduler's queue (./load-scheduler.ts) */
-  load_slot: typeof load_slot;
+  LoadSlot: typeof LoadSlot;
   /** DOM ownership (./ownership.ts): which children Svelte's walk enters, and self-owned elements */
   walk_enters: typeof walk_enters;
   is_self_owned: typeof is_self_owned;
@@ -155,12 +172,29 @@ export type BootLink = {
   record_server_body: typeof record_server_body;
   server_body_attributes: typeof server_body_attributes;
   server_body_child: typeof server_body_child;
+  /** devalue, loaded when a page needs it (./devalue-lane.ts) */
+  load_devalue: typeof load_devalue;
+  devalue: typeof devalue;
+  with_devalue: typeof with_devalue;
+  needs_devalue: typeof needs_devalue;
+  /** the runtime's messages (../messages/core.ts), as a lazy chunk throws and logs them (../messages/lazy.ts) */
+  OgygiaError: typeof OgygiaError;
+  warn: typeof warn;
+  /** what a machine's task answers once its visit is left (`@ogygia/machine`, which the boot runs on) */
+  STALE: typeof import("@ogygia/machine").STALE;
+  /** keyed shared async work (`@ogygia/machine`): the router's page fetches */
+  flights: typeof import("@ogygia/machine").flights;
+  /** a change built off to the side and switched in at once (`@ogygia/machine`): the router's
+   *  swap and the soft refresh */
+  stage: typeof import("@ogygia/machine").stage;
+  /** a stamp that only moves forward (`@ogygia/machine`): the world the router's page cache is
+   *  made in */
+  world: typeof import("@ogygia/machine").world;
+  /** the page's soft refresh (./soft-refresh.ts): `invalidateAll`, with the router or without it */
+  soft: SoftRefresh;
 };
 export type RouterLink = {
-  document_key: typeof document_key;
   jump_to_hash: typeof jump_to_hash;
-  push_state: typeof push_state;
-  replace_state: typeof replace_state;
 };
 export type InteractionLink = {
   resolve_address: typeof resolve_address;
@@ -170,9 +204,8 @@ export type Slots = {
   forms: FormOps;
   interaction: ArmFn | null;
   morph: MorphFn | null;
-  live: Component<Record<string, unknown>> | null;
-  /** a kept island's host (the live feature fills it beside `live`) */
-  keep: Component<Record<string, unknown>> | null;
+  /** props a live region or a kept island is hydrated with, pushed in place later (./live.ts) */
+  Pushable: typeof PushableProps | null;
   wire: WireOps | null;
   /** The transportable classes an island's props, context and seeds need, loaded before it
    *  decodes (./wire-classes.ts). Null in an app without transportable classes: nothing to load. */

package/dist/runtime/slots.js

@@ -19,8 +19,7 @@ const slots = {
 	},
 	interaction: null,
 	morph: null,
-	live: null,
-	keep: null,
+	Pushable: null,
 	wire: null,
 	wire_classes: null,
 	remoteSeeds: null,
@@ -36,7 +35,7 @@ const slots = {
 /** A link a lazy chunk needs, or a loud error: every link is filled before its chunk can load, so a
 *  missing one means a chunk ran without the boot that owns it (a test that skipped `link_boot()`). */
 function linked(link, name) {
-	if (link === null) throw new Error(`[ogygia] runtime chunk used \`slots.${name}\` before the boot linked it`);
+	if (link === null) throw new Error("[ogygia] https://ogygiajs.dev/e/slot_not_linked?name=" + name);
 	return link;
 }
 const boot_link = () => linked(slots.boot, "boot");

package/dist/runtime/soft-refresh.d.ts

@@ -0,0 +1,16 @@
+import { Machine } from "@ogygia/machine";
+type States = {
+  idle: {};
+  refreshing: {
+    href: string;
+  };
+};
+declare const steps: {
+  readonly idle: readonly ["refreshing"];
+  readonly refreshing: readonly ["refreshing", "idle"];
+};
+/** The page's soft refresh machine. */
+export type SoftRefresh = Machine<States, typeof steps>;
+/** A soft refresh machine, idle. */
+export declare function create_soft_refresh(): SoftRefresh;
+export {};

package/dist/runtime/soft-refresh.js

@@ -0,0 +1,14 @@
+import { machine } from "@ogygia/machine";
+const definition = machine()({
+	name: "soft refresh",
+	initial: "idle",
+	steps: {
+		idle: ["refreshing"],
+		refreshing: ["refreshing", "idle"]
+	}
+});
+/** A soft refresh machine, idle. */
+function create_soft_refresh() {
+	return definition.create();
+}
+export { create_soft_refresh };

package/dist/runtime/svelte-warnings.d.ts

@@ -1,11 +1,4 @@
-/**
- * SVELTE'S HYDRATION WARNINGS, KEPT — in dev, Svelte says in the console when the server and the
- * browser disagreed while an island hydrated (`hydration_html_changed`, `hydration_attribute_changed`,
- * `hydration_mismatch`…). Svelte keeps the server's value, so nothing on screen shows it: the console
- * line is the only trace. This keeps each one (with the island hydrating at the time) for the devtools
- * and the profiler's browser half. Dev only (production Svelte has no such warnings); the console line
- * itself goes out unchanged. No regex: warnings are rare, read by string search.
- */
+import { Scope } from "@ogygia/machine";
 export interface SvelteWarning {
   code: string;
   message: string;
@@ -15,8 +8,9 @@ export interface SvelteWarning {
 }
 /** core.ts marks the island whose hydrate step is running. Svelte raises some warnings as the
  *  step's effects flush (a microtask after it returns): the mark holds until the task ends, and
- *  islands hydrate one per task, so the next one never inherits it. */
-export declare function set_hydrating(el: Element): void;
+ *  islands hydrate one per task, so the next one never inherits it. The task's end is `owner`'s to
+ *  wait for (the island's lifetime in the page): an island gone first takes its mark with it. */
+export declare function set_hydrating(el: Element, owner: Scope): void;
 export declare function svelte_warnings(): SvelteWarning[];
 export declare function on_svelte_warning(cb: (w: SvelteWarning) => void): void;
 /** `%c[svelte] code\n%cmessage …` → the parts (null: not a Svelte hydration warning). */

package/dist/runtime/svelte-warnings.js

@@ -5,12 +5,15 @@ const kept = [];
 const listeners = [];
 /** core.ts marks the island whose hydrate step is running. Svelte raises some warnings as the
 *  step's effects flush (a microtask after it returns): the mark holds until the task ends, and
-*  islands hydrate one per task, so the next one never inherits it. */
-function set_hydrating(el) {
+*  islands hydrate one per task, so the next one never inherits it. The task's end is `owner`'s to
+*  wait for (the island's lifetime in the page): an island gone first takes its mark with it. */
+function set_hydrating(el, owner) {
 	hydrating = el;
-	setTimeout(() => {
+	const clear = () => {
 		if (hydrating === el) hydrating = null;
-	}, 0);
+	};
+	owner.timeout(clear, 0);
+	owner.defer(clear);
 }
 function svelte_warnings() {
 	return kept.slice();

package/dist/runtime/wire-classes.js

@@ -1,6 +1,9 @@
+import { import_again } from "./import-again.js";
 import { props_sidecar_of } from "./sidecar.js";
 import { yield_task } from "./schedule.js";
 import { slots } from "./slots.js";
+import { download } from "../policies.js";
+import { flights } from "@ogygia/machine";
 import { wire_all, wire_loaders } from "virtual:ogygia/transportables";
 // src/runtime/wire-classes.ts
 /**
@@ -16,6 +19,10 @@ import { wire_all, wire_loaders } from "virtual:ogygia/transportables";
 * through Kit's `transport` (`wire_all`: remote functions, loads) gets every class with every island,
 * as before: those values decode synchronously whenever they arrive. Each module loads once.
 *
+* A download that fails is tried again at once, and a failure is never kept: the wake it failed for
+* decodes without the class (the decode says which class is missing), and the next wake that needs
+* it loads it afresh, under a fresh URL (./import-again.ts: the browser keeps the failed one).
+*
 * A BOOT-phase feature (link/runtime-entry.ts), installed only when the app has transportable
 * classes: without one the loader map is empty, but the bundler cannot see that through the virtual
 * module, so this code shipped to every island page for a lookup that always found nothing.
@@ -26,15 +33,21 @@ function install() {
 }
 const loaders = wire_loaders;
 const paths = Object.keys(loaders);
-const loading = /* @__PURE__ */ new Map();
+/** Each class module's loader: what it asks for next (its file, or a fresh URL after a failure). */
+const imports = /* @__PURE__ */ new Map();
+/** Each class module's load, by path, kept once it succeeds (a failure is never kept). */
+const loads = flights({
+	name: "wire class",
+	run: (path) => {
+		let import_class = imports.get(path);
+		if (!import_class) imports.set(path, import_class = import_again(loaders[path]));
+		return yield_task().then(import_class);
+	},
+	retry: download
+});
 function load(path) {
-	let p = loading.get(path);
-	if (!p) {
-		const loader = loaders[path];
-		p = loader ? yield_task().then(loader).catch(() => void 0) : Promise.resolve();
-		loading.set(path, p);
-	}
-	return p;
+	if (!loaders[path]) return Promise.resolve();
+	return loads.get(path).catch(() => void 0);
 }
 /** The classes a text names (`"<tag path>#…` appears in it), into `want`. */
 function scan(text, want) {

package/dist/runtime/wire-format.js

@@ -1,10 +1,11 @@
-import { parse } from "devalue";
+import { boot_link } from "./slots.js";
 // src/runtime/wire-format.ts
 /**
 * THE WIRE FORMAT of a side-channel script, read back. The server emits two lanes
 * (server/props-wire.ts): plain JSON under `data-og-format="json"` (a payload with nothing devalue
 * exists for — the common CMS props and seed), and devalue otherwise. This is the ONE place the
-* client tells them apart: every seed / props / remote read goes through `parse_wire_text`.
+* client tells them apart: every seed / props / remote read goes through `parse_wire_text`. devalue
+* itself is loaded only for a page that has a devalue-lane script (./devalue-lane.ts).
 *
 * Pure (no DOM types beyond an attribute read) so the runtime, the shims and the tests share it.
 */
@@ -17,7 +18,9 @@ function wire_is_json(el) {
 /** Parse a side-channel's text in its lane: `JSON.parse` for the JSON lane (nothing to revive by
 *  construction), devalue `parse` with the caller's revivers otherwise. */
 function parse_wire_text(text, json, revivers) {
-	return json ? JSON.parse(text) : parse(text, revivers);
+	if (json) return JSON.parse(text);
+	const { parse } = boot_link().devalue();
+	return parse(text, revivers);
 }
 /** A seed or props script's payload, in its lane: JSON when the server marked it plain, devalue
 *  with `revivers` otherwise. Every seed / props read goes through here. */

package/dist/script.js

@@ -1,4 +1,5 @@
 import { escape_attr, escape_script_text } from "./escape.js";
+import { OgygiaError } from "./messages/island.js";
 // src/script.ts
 /**
 * `script()` — an inline `<script>` tag as a string, for the work a csr=false page must do in the
@@ -45,7 +46,7 @@ function script(input, ...rest) {
 	let kinds = 0;
 	if (o.run !== void 0) {
 		kinds++;
-		if (typeof o.run !== "function") throw new TypeError("[ogygia] script(): `run` must be a function");
+		if (typeof o.run !== "function") throw new OgygiaError("script_run_not_function");
 		const module = o.type === "module";
 		if (module) type = "module";
 		const args = o.args ?? [];
@@ -56,13 +57,13 @@ function script(input, ...rest) {
 		}
 		let lines = "";
 		if (o.imports !== void 0) {
-			if (!module) throw new TypeError("[ogygia] script(): `imports` needs `type: 'module'` (a static import only works in a module)");
+			if (!module) throw new OgygiaError("script_imports_need_module");
 			let mods = "";
 			let n = 0;
 			const imports = o.imports;
 			for (const name in imports) {
 				const url = imports[name];
-				if (typeof url !== "string" || !url) throw new TypeError(`[ogygia] script(): \`imports.${name}\` must be a URL string`);
+				if (typeof url !== "string" || !url) throw new OgygiaError("script_import_not_url", { name });
 				lines += `import * as __og_m${n} from ${escape_script_text(JSON.stringify(url))};`;
 				mods += (n ? "," : "") + `${escape_script_text(JSON.stringify(name))}:__og_m${n}`;
 				n++;
@@ -70,7 +71,7 @@ function script(input, ...rest) {
 			call = `{${mods}}` + (call ? "," + call : "");
 		}
 		const src = fn_source(o.run);
-		if (src.indexOf("__vite_ssr_") !== -1) throw new TypeError("[ogygia] script(): `run` was rewritten by the bundler (it holds `__vite_ssr_…`): an `import()` or an imported binding inside it cannot cross into the browser. Declare the module in `imports` (with `type: 'module'`) and read it from `run`'s first parameter.");
+		if (src.indexOf("__vite_ssr_") !== -1) throw new OgygiaError("script_run_rewritten");
 		body = `${lines}${module ? "await " : ""}(${close_safe(src)})(${call});`;
 	} else body = "";
 	for (const [key, kind] of DATA_KINDS) {
@@ -78,16 +79,16 @@ function script(input, ...rest) {
 		kinds++;
 		type = kind;
 		const json = JSON.stringify(o[key]);
-		if (json === void 0) throw new TypeError(`[ogygia] script(): \`${key}\` must be JSON-serializable`);
+		if (json === void 0) throw new OgygiaError("script_not_json", { key });
 		body = escape_script_text(json);
 	}
-	if (kinds !== 1) throw new TypeError(`[ogygia] script(): pass exactly one of \`run\`, \`json\`, \`ld\`, \`importmap\`, \`speculation\` (got ${kinds})`);
+	if (kinds !== 1) throw new OgygiaError("script_one_kind", { count: kinds });
 	let attrs = type ? ` type="${type}"` : "";
 	for (const key in o) {
 		if (RESERVED.has(key)) continue;
 		const v = o[key];
 		if (v === void 0 || v === null || v === false) continue;
-		if (!is_attr_name(key)) throw new TypeError(`[ogygia] script(): \`${key}\` is not an attribute name`);
+		if (!is_attr_name(key)) throw new OgygiaError("script_bad_attribute", { key });
 		attrs += v === true ? " " + key : ` ${key}="${escape_attr(String(v))}"`;
 	}
 	return `<script${attrs}>${body}<\/script>`;

package/dist/seed-ref-reviver.d.ts

@@ -1,12 +1,3 @@
-/**
- * The CLIENT half of seed references (seed-refs.ts): the devalue type tag and the reviver that
- * resolves a reference against the page seed. Its own module because the hydrate core is a lazy
- * runtime chunk that shares modules with Kit's client graph (route components compiled for the
- * browser, never loaded on a csr=false page). The bundler keeps a shared module whole — every
- * export ANY importer uses — so while the reviver lived beside the server-side index and planner,
- * every island page downloaded the planner (~4 kB) for the Kit graph's sake. A leaf holds only
- * what the hydrate core runs.
- */
 /** The devalue type tag. */
 export declare const SEED_REF_KEY = "OgygiaSeedRef";
 export type SeedPath = (string | number)[];

package/dist/seed-ref-reviver.js

@@ -1,3 +1,4 @@
+import { warn } from "./messages/lazy.js";
 // src/seed-ref-reviver.ts
 /**
 * The CLIENT half of seed references (seed-refs.ts): the devalue type tag and the reviver that
@@ -37,7 +38,7 @@ function seed_ref_reviver(get_data) {
 			resolved = true;
 		}
 		const node = resolve_seed_ref(data, path);
-		if (node === void 0 && typeof console !== "undefined" && import.meta.env?.DEV) console.warn(`[ogygia] island props reference page.data at ${JSON.stringify(path)} but the page seed does not carry it — the island receives undefined there.`);
+		if (node === void 0 && typeof console !== "undefined" && import.meta.env?.DEV) warn("page_seed_ref_missing", { path: JSON.stringify(path) });
 		return node;
 	};
 }

package/dist/seed-refs.d.ts

@@ -1,33 +1,4 @@
 import { SEED_REF_KEY, SeedPath, resolve_seed_ref, seed_ref_reviver } from "./seed-ref-reviver.js";
-export interface SeedIndex {
-  /** node → its path from `page.data` (identity matches: the app passed the seed's own object).
-   *  The path is materialised on the first ask — an indexed node that no island references
-   *  never allocates one. */
-  readonly by_identity: {
-    get(node: object): SeedPath | undefined;
-    has(node: object): boolean;
-  };
-  /**
-   * The seed nodes with exactly this byte estimate — the only ones a props node of that size can
-   * be a clone of. Structure matching hashes just those few candidates (memoised per seed node)
-   * instead of the whole seed, so an app that passes the seed's own objects never hashes a seed
-   * node at all, and a cloning app hashes only what it has to. The buckets are built on the first
-   * ask — a page whose islands only pass seed objects by identity never builds them.
-   */
-  candidates(bytes: number): readonly object[];
-  /** Structural hash of an indexed seed node, memoised for the request. */
-  hash_of(node: object): string | null;
-  /** nodes indexed (for tests / devtools). */
-  readonly size: number;
-  /**
-   * SEED SHAPING: the top-level `page.data` keys under which a props node was matched
-   * (`plan_seed_refs` records the first path segment of every reference it plans). The handle
-   * renders the tail against the FULL index, then ships every touched key — a key no island's
-   * code reads but whose node an island's props point into still ships, so a reference always
-   * has something to point at.
-   */
-  readonly touched: Set<string>;
-}
 /** Exact structural equality for the shapes `hash_subtree` accepts — the check behind a hash hit. */
 export declare function deep_equal_plain(a: unknown, b: unknown): boolean;
 /** What one walk learns about a subtree. */
@@ -61,15 +32,53 @@ export declare function analyze(value: unknown): Measure;
  */
 export declare function json_culprit(value: unknown, max_depth?: number): string | null;
 /**
- * Index the seed's `data` for referencing: every referenceable node at or above `min_bytes`, by
+ * The seed's `data` indexed for referencing: every referenceable node at or above `min_bytes`, by
  * identity now and by structural hash on demand (first occurrence wins — the shortest path is not
- * guaranteed, the first in key order is, which is deterministic). Cached per `data` object: one
- * index per request, however many islands ask. It reads the one measuring walk (`analyze`) and
- * prunes: a node below `min_bytes` cannot hold a child at or above it (a child is never larger
- * than its parent), so its subtree is skipped BEFORE anything is materialised — on a CMS tree that
- * is most of the nodes.
+ * guaranteed, the first in key order is, which is deterministic). It reads the one measuring walk
+ * (`analyze`) and prunes: a node below `min_bytes` cannot hold a child at or above it (a child is
+ * never larger than its parent), so its subtree is skipped BEFORE anything is materialised — on a
+ * CMS tree that is most of the nodes. Data that is not a plain object or array indexes nothing.
  */
-export declare function index_seed(data: unknown, min_bytes?: number): SeedIndex;
+export declare class SeedIndex {
+  #private;
+  /** nodes indexed (for tests / devtools). */
+  readonly size: number;
+  /**
+   * SEED SHAPING: the top-level `page.data` keys under which a props node was matched
+   * (`plan_seed_refs` records the first path segment of every reference it plans). The handle
+   * renders the tail against the FULL index, then ships every touched key — a key no island's
+   * code reads but whose node an island's props point into still ships, so a reference always
+   * has something to point at.
+   */
+  readonly touched: Set<string>;
+  /** The index of `data`, cached per `data` object: one index per request, however many islands
+   *  ask. */
+  static of(data: unknown, min_bytes?: number): SeedIndex;
+  constructor(data: unknown, min_bytes: number);
+  /** node → its path from `page.data` (identity matches: the app passed the seed's own object).
+   *  The path is materialised on the first ask — an indexed node that no island references
+   *  never allocates one. */
+  path(node: object): SeedPath | undefined;
+  /** Whether `node` is an indexed seed node (by identity). */
+  has(node: object): boolean;
+  /**
+   * The seed nodes with exactly this byte estimate — the only ones a props node of that size can
+   * be a clone of. Structure matching hashes just those few candidates (memoised per seed node)
+   * instead of the whole seed, so an app that passes the seed's own objects never hashes a seed
+   * node at all, and a cloning app hashes only what it has to. The buckets are built on the first
+   * ask — a page whose islands only pass seed objects by identity never builds them.
+   */
+  candidates(bytes: number): readonly object[];
+  /**
+   * The first seed node of exactly this byte estimate whose structural hash is `hash` (bucket
+   * order, as `candidates(bytes).find(...)` gives it), in one map lookup. The bucket is hashed in
+   * order only as far as an ask needs, each hash keeping its first node, so the many same-sized
+   * records of a list cost one hash each however many props nodes ask.
+   */
+  match(bytes: number, hash: string): object | undefined;
+  /** Structural hash of an indexed seed node, memoised for the request. */
+  hash_of(node: object): string | null;
+}
 export interface SeedRefPlan {
   /** The devalue reducer for the `OgygiaSeedRef` type: `(value) => path | undefined`. */
   reducer: (value: unknown) => SeedPath | undefined;
@@ -86,6 +95,7 @@ export interface SeedRefPlan {
  * ride inside the reference), and neither is anything under a node below `min_bytes` (no child
  * of it can be referenced). The props' own measures come from the request memo, so the plan adds
  * no walk of its own beyond the pointer lookups.
+ * @heisenbench linear in props
  */
 export declare function plan_seed_refs(index: SeedIndex, props: unknown, min_bytes?: number): SeedRefPlan;
 export { SEED_REF_KEY, type SeedPath, resolve_seed_ref, seed_ref_reviver };