@ogygia/core 0.0.0 → 0.11.0

package/dist/late-region-registry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LATE-REGION capture — the registry front for streamed `<Region of={promise}>` holes. Same shape
+ * as the page-seed / setContext recorders: the SERVER installs a request-scoped recorder (ALS-backed
+ * in `hooks.ts`), Region.svelte calls the plain function during SSR, and on the client (or with no
+ * recorder armed) it is a no-op returning `null` — the region keeps today's placeholder behavior.
+ *
+ * When armed, registering a promise returns the SLOT ID the region wraps its placeholder in
+ * (`<og-late-slot data-og-slot=…>`); the router's streamed-document path later drains the request's
+ * registered promises in completion order, baking each resolved region into a late template chunk
+ * down the same response. That is "streamed load data" in ogygia's model: a load hands a promise to
+ * a region, and the region resolves over the initial connection — no client refetch, no second
+ * round trip, islands inside waking on adoption.
+ */
+type LateRecorder = (promise: Promise<unknown>) => string | null;
+type ScopeOpener = () => void;
+/** Server (`hooks.ts`) installs the request-scoped scope opener. */
+export declare function set_late_scope_opener(fn: ScopeOpener | null): void;
+/**
+ * ONLY A RENDERER THAT DELIVERS LATE CHUNKS ARMS THEM. The server router's streamed document opens
+ * this request's late scope before it renders (and drains it after); anywhere else — a Kit page render
+ * — a promise `of` registers nothing, because nothing would ever fill its slot (a Kit page's header
+ * sat in an empty slot forever).
+ */
+export declare function open_late_scope(): void;
+/** Server (`hooks.ts`) installs the request-scoped recorder. */
+export declare function set_late_recorder(fn: LateRecorder | null): void;
+/** Region.svelte calls this with a promise `of` during SSR. `null` = not armed → no streaming. */
+export declare function register_late_region(promise: Promise<unknown>): string | null;
+export interface LateRegion {
+  id: string;
+  promise: Promise<unknown>;
+}
+type LateTaker = () => LateRegion[] | null;
+/** Server (`hooks.ts`) installs the request-scoped drain alongside the recorder. */
+export declare function set_late_taker(fn: LateTaker | null): void;
+/** The router drains THIS request's registered late regions after the document render (through
+ *  this seam, never by importing hooks — its `virtual:` imports don't resolve outside Vite).
+ *  `null` when nothing registered / nothing armed. Draining clears the request's list. */
+export declare function take_late_regions(): LateRegion[] | null;
+export {};

package/dist/late-region-registry.js

@@ -0,0 +1,36 @@
+// src/late-region-registry.ts
+let opener = null;
+/** Server (`hooks.ts`) installs the request-scoped scope opener. */
+function set_late_scope_opener(fn) {
+	opener = fn;
+}
+/**
+* ONLY A RENDERER THAT DELIVERS LATE CHUNKS ARMS THEM. The server router's streamed document opens
+* this request's late scope before it renders (and drains it after); anywhere else — a Kit page render
+* — a promise `of` registers nothing, because nothing would ever fill its slot (a Kit page's header
+* sat in an empty slot forever).
+*/
+function open_late_scope() {
+	opener?.();
+}
+let recorder = null;
+/** Server (`hooks.ts`) installs the request-scoped recorder. */
+function set_late_recorder(fn) {
+	recorder = fn;
+}
+/** Region.svelte calls this with a promise `of` during SSR. `null` = not armed → no streaming. */
+function register_late_region(promise) {
+	return recorder ? recorder(promise) : null;
+}
+let taker = null;
+/** Server (`hooks.ts`) installs the request-scoped drain alongside the recorder. */
+function set_late_taker(fn) {
+	taker = fn;
+}
+/** The router drains THIS request's registered late regions after the document render (through
+*  this seam, never by importing hooks — its `virtual:` imports don't resolve outside Vite).
+*  `null` when nothing registered / nothing armed. Draining clears the request's list. */
+function take_late_regions() {
+	return taker ? taker() : null;
+}
+export { open_late_scope, register_late_region, set_late_recorder, set_late_scope_opener, set_late_taker, take_late_regions };

package/dist/live-transport.d.ts

@@ -0,0 +1,57 @@
+/** Feature entry: register every props-seam kind, then fill the `wire` slot so core resolves
+ *  ANY transportable kind from `data-ogygia-props` through the one hub key. */
+export declare function install(): void;
+/** Reserved key for the static codec — what `import.meta.og.wire` rewrites to. `Symbol.for` so it's
+ *  identical across every bundle. Internal: the public opt-in is the construct, not this symbol. */
+export declare const wire: unique symbol;
+/** The codec `import.meta.og.wire({ … })` carries (or a static method returning it). */
+export interface TransportCodec<T = unknown, D = unknown> {
+  /** Sending side: turn the live instance into devalue-safe data. */
+  encode: (value: T) => D;
+  /** Receiving side: rebuild a live instance from that data. */
+  decode: (data: D) => T;
+  /**
+   * CONTINUITY — a stable session name. Naming the codec promotes the instance from page
+   * lifetime to SESSION lifetime: it becomes a singleton in this browser tab, and a navigation
+   * reunites the next page's decode with the SAME live instance instead of rebuilding it. Tab-
+   * scoped only — the server stays per-request (never remembers), a reload starts fresh.
+   */
+  id?: string;
+  /**
+   * Reconcile a navigation: the tab already holds the live named instance and the new page's
+   * server snapshot just arrived (decoded as `fresh`). Apply whatever should carry over INTO
+   * `live` — its identity is preserved; `fresh` is discarded afterwards. Default: do nothing
+   * (live wins — continuity is the point; a cart mid-edit beats a server re-read). Override to
+   * pull server truth in (prices, stock, auth state).
+   */
+  merge?: (live: T, fresh: T) => void;
+}
+/** Devalue custom-type name used for transportable payloads on the wire. */
+export declare const TRANSPORT_WIRE_KEY = "OgygiaT";
+/** Legacy wire shape (`t` tag, `i` id, `d` data) — a hub Ref minus its kind discriminator. */
+interface TransportPayload {
+  t: string;
+  i: string;
+  d: unknown;
+}
+/**
+ * Register a class under a stable build-derived tag (root-relative module path + export
+ * name). Called by generated code appended to every exported class in app source; a class
+ * without a `[wire]` codec is silently skipped, so over-registration is harmless.
+ */
+export declare function __register_transportable(tag: string, cls: unknown): void;
+/** The hub kind: `[og.wire]` class instances. Identity/reunify/Keep live in the hub. */
+export declare function register_wire_kind(): void;
+/**
+ * Devalue reducer: encode a transportable instance, or return undefined to fall through to
+ * devalue's normal handling. Same instance → same wire id (hub-memoized), which is what lets
+ * the client reunite every copy of the prop into one live object.
+ */
+export declare function reduce_transportable(value: unknown): TransportPayload | undefined;
+/**
+ * Devalue reviver: rebuild a live instance from the wire payload via the hub.
+ * `remember: true` (browser) memoizes by wire id + honors the session Keep; `remember: false`
+ * (server, defer/streaming renders) always decodes fresh — per-request isolation.
+ */
+export declare function revive_transportable(payload: TransportPayload, remember: boolean): unknown;
+export {};

package/dist/live-transport.js

@@ -0,0 +1,145 @@
+import { slots } from "./runtime/slots.js";
+import { register_snippet_kind } from "./region-snippet.js";
+import { register_derived_kind, register_store_kind } from "./store-transport.js";
+import { register_fn_kind } from "./fn-transport.js";
+import { REF_WIRE_KEY, mint, register_kind, resolve } from "./ref.js";
+// src/live-transport.ts
+/**
+* Transportable objects — `static [import.meta.og.wire]` codecs, as the hub's WIRE kind.
+*
+* A class instance normally cannot cross an island boundary (devalue rejects it). A class
+* opts in by declaring how it travels:
+*
+* ```ts
+* export class Cart {
+* 	items = $state<Item[]>([]);
+* 	add(item: Item) { this.items.push(item); }
+*
+* 	static wire = import.meta.og.wire({
+* 		encode: (c: Cart) => $state.snapshot(c.items),
+* 		decode: (items: Item[]) => Object.assign(new Cart(), { items })
+* 	});
+* }
+* ```
+*
+* `import.meta.og.wire()` is a COMPILE construct — the plugin consumes the member and mints the
+* key: `static [Symbol.for('ogygia.wire')] = <codec>`. No import, no value to pass around, and
+* STRICT: that member shape is the only legal position (build error anywhere else). ONE contract,
+* always explicit — `{ encode, decode }`, plus optional `id`/`merge` for session continuity.
+*
+* IDENTITY IS THE HUB'S (see ref.ts): mint memoizes one id per instance; the browser resolves
+* by id so five islands share one live object; `codec.id` names the ref into the session Keep
+* (a navigation reunites with the SAME instance, `codec.merge` reconciling fresh server data);
+* the server never remembers. This module owns only what is wire-SPECIFIC: the class registry
+* (build tag → class) and the codec protocol.
+*/
+/** Feature entry: register every props-seam kind, then fill the `wire` slot so core resolves
+*  ANY transportable kind from `data-ogygia-props` through the one hub key. */
+function install() {
+	register_wire_kind();
+	register_snippet_kind();
+	register_store_kind();
+	register_fn_kind();
+	register_derived_kind();
+	slots.wire = {
+		REF_WIRE_KEY,
+		resolve: (ref, remember) => resolve(ref, remember)
+	};
+}
+/** Reserved key for the static codec — what `import.meta.og.wire` rewrites to. `Symbol.for` so it's
+*  identical across every bundle. Internal: the public opt-in is the construct, not this symbol. */
+const wire = Symbol.for("ogygia.wire");
+const REGISTRY_KEY = Symbol.for("ogygia.transportables");
+function wire_registry() {
+	const g = globalThis;
+	return g[REGISTRY_KEY] ??= {
+		classes: /* @__PURE__ */ new Map(),
+		tags: /* @__PURE__ */ new WeakMap()
+	};
+}
+/** Devalue custom-type name used for transportable payloads on the wire. */
+const TRANSPORT_WIRE_KEY = "OgygiaT";
+/**
+* Register a class under a stable build-derived tag (root-relative module path + export
+* name). Called by generated code appended to every exported class in app source; a class
+* without a `[wire]` codec is silently skipped, so over-registration is harmless.
+*/
+function __register_transportable(tag, cls) {
+	if (typeof cls !== "function") return;
+	const candidate = cls;
+	if (!candidate[wire]) return;
+	const reg = wire_registry();
+	reg.classes.set(tag, candidate);
+	reg.tags.set(cls, tag);
+}
+function codec_of(cls) {
+	const raw = cls[wire];
+	return typeof raw === "function" ? raw.call(cls) : raw;
+}
+function class_for(tag) {
+	const cls = tag === void 0 ? void 0 : wire_registry().classes.get(tag);
+	if (cls === void 0) throw new Error(`[ogygia] cannot revive transportable "${tag}": its class is not loaded on this side. The island must import the class as a VALUE (not \`import type\`) so its codec travels with the island's bundle.`);
+	return cls;
+}
+/** The hub kind: `[og.wire]` class instances. Identity/reunify/Keep live in the hub. */
+function register_wire_kind() {
+	register_kind({
+		k: "wire",
+		match(value) {
+			const cls = value.constructor;
+			return typeof cls === "function" && !!cls[wire];
+		},
+		encode(value) {
+			const cls = value.constructor;
+			const tag = wire_registry().tags.get(cls);
+			if (tag === void 0) throw new Error(`[ogygia] class "${cls.name ?? "?"}" has a [import.meta.og.wire] codec but was never registered. Transportable classes must be declared in a module the ogygia vite plugin transforms (an \`export class\` in your app source, not node_modules or a dynamic eval).`);
+			return {
+				t: tag,
+				d: codec_of(cls).encode(value)
+			};
+		},
+		decode(ref) {
+			return codec_of(class_for(ref.t)).decode(ref.d);
+		},
+		keep_name(ref) {
+			const codec = codec_of(class_for(ref.t));
+			return typeof codec.id === "string" ? codec.id : void 0;
+		},
+		merge(kept, ref) {
+			const codec = codec_of(class_for(ref.t));
+			if (typeof codec.merge === "function") codec.merge(kept, codec.decode(ref.d));
+		}
+	});
+}
+const WIRE_ONLY = /* @__PURE__ */ new Set(["wire"]);
+/**
+* Devalue reducer: encode a transportable instance, or return undefined to fall through to
+* devalue's normal handling. Same instance → same wire id (hub-memoized), which is what lets
+* the client reunite every copy of the prop into one live object.
+*/
+function reduce_transportable(value) {
+	register_wire_kind();
+	const ref = mint(value, WIRE_ONLY);
+	if (ref === void 0) return void 0;
+	return {
+		t: ref.t,
+		i: ref.i,
+		d: ref.d
+	};
+}
+/**
+* Devalue reviver: rebuild a live instance from the wire payload via the hub.
+* `remember: true` (browser) memoizes by wire id + honors the session Keep; `remember: false`
+* (server, defer/streaming renders) always decodes fresh — per-request isolation.
+*/
+function revive_transportable(payload, remember) {
+	register_wire_kind();
+	const ref = {
+		k: "wire",
+		i: payload.i,
+		t: payload.t,
+		d: payload.d
+	};
+	return resolve(ref, remember);
+}
+export { TRANSPORT_WIRE_KEY, __register_transportable, install, reduce_transportable, register_wire_kind, revive_transportable, wire };

package/dist/markup.d.ts

@@ -0,0 +1,4 @@
+import { LiftResult, LiftedRegion, RegionKind, RegionSpan, liftRegions, restoreRegions, scanRegions } from "./server/split-regions.js";
+import { Settled, TransformKind, check_script, localizeMarks, transformMarkup } from "./server/reversible.js";
+import { restore } from "./runtime/restore.js";
+export { type LiftResult, type LiftedRegion, type RegionKind, type RegionSpan, type Settled, type TransformKind, check_script as checkScript, liftRegions, localizeMarks, restore, restoreRegions, scanRegions, transformMarkup };

package/dist/markup.js

@@ -0,0 +1,4 @@
+import { liftRegions, restoreRegions, scanRegions } from "./server/split-regions.js";
+import { check_script, localizeMarks, transformMarkup } from "./server/reversible.js";
+import { restore } from "./runtime/restore.js";
+export { check_script as checkScript, liftRegions, localizeMarks, restore, restoreRegions, scanRegions, transformMarkup };

package/dist/own-package.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Core's own identity. Core is reached by two package names: `ogygia`, the package apps install (a
+ * thin layer that re-exports core subpath for subpath), and `@ogygia/core`, what plugins import.
+ * Every "is this ogygia itself" check asks here instead of comparing one literal name.
+ */
+/** The package names core answers to. */
+export declare const OWN_PACKAGE_NAMES: readonly string[];
+/** A bare specifier that names core, by either name, or one of its subpaths. */
+export declare function is_own_specifier(spec: string): boolean;
+/** Core's names as a regex alternation, for import-clause scanners (`from 'ogygia'`). */
+export declare const OWN_SPECIFIER_SOURCE = "(?:ogygia|@ogygia/core)";
+/** A file inside core or the `ogygia` package, source or build: `…/node_modules/ogygia/dist/…`,
+ *  `…/node_modules/@ogygia/core/dist/…`, and a checkout's `packages/ogygia/src/…` and
+ *  `packages/core/src/…`. Either separator. */
+export declare const OWN_FILE_RE: RegExp;

package/dist/own-package.js

@@ -0,0 +1,20 @@
+// src/own-package.ts
+/**
+* Core's own identity. Core is reached by two package names: `ogygia`, the package apps install (a
+* thin layer that re-exports core subpath for subpath), and `@ogygia/core`, what plugins import.
+* Every "is this ogygia itself" check asks here instead of comparing one literal name.
+*/
+/** The package names core answers to. */
+const OWN_PACKAGE_NAMES = ["ogygia", "@ogygia/core"];
+/** A bare specifier that names core, by either name, or one of its subpaths. */
+function is_own_specifier(spec) {
+	for (const name of OWN_PACKAGE_NAMES) if (spec === name || spec.startsWith(name + "/")) return true;
+	return false;
+}
+/** Core's names as a regex alternation, for import-clause scanners (`from 'ogygia'`). */
+const OWN_SPECIFIER_SOURCE = "(?:ogygia|@ogygia/core)";
+/** A file inside core or the `ogygia` package, source or build: `…/node_modules/ogygia/dist/…`,
+*  `…/node_modules/@ogygia/core/dist/…`, and a checkout's `packages/ogygia/src/…` and
+*  `packages/core/src/…`. Either separator. */
+const OWN_FILE_RE = /[\\/](?:ogygia|@ogygia[\\/]core|packages[\\/]core)[\\/](?:src|dist)[\\/]/;
+export { OWN_FILE_RE, OWN_PACKAGE_NAMES, OWN_SPECIFIER_SOURCE, is_own_specifier };

package/dist/page-defer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared constants for streaming a load `Promise` in `$page.data` into an island on a csr=false page.
+ *
+ * Kit lets `load` return a Promise at any level of `data` and STREAMS its resolution to the client
+ * (render the shell with `{#await}` pending, then flush `<script>` chunks that settle it). A csr=false
+ * page has no hydration, so Kit's own stream is dead there — but an ISLAND has a client. We mirror
+ * Kit's shape with our OWN registry: the page seed carries a DEFER MARKER for each pending promise
+ * (a real pending Promise on the client), and streamed resolve `<script>`s settle them live.
+ *
+ * Constants only — safe to import from both the server (staging/serialization) and the client
+ * (registry/reviver), with no code crossing the boundary.
+ */
+/** devalue reducer/reviver name for a deferred-promise leaf in the page seed. The encoded payload is
+ *  the promise's integer id (assigned in walk order). */
+export declare const PAGE_DEFER_KEY = "OgygiaDefer";
+/** devalue reducer/reviver name for an already-SETTLED promise leaf — used on the non-navigate
+ *  (SPA/router) path, which can't run streamed scripts, so each promise is awaited server-side and
+ *  revived as a resolved/rejected Promise at parse time. Keeps `page.data.x` a Promise on BOTH paths
+ *  (matches Kit) and lets a rejection show `{#await …:catch}` without ever crashing the render. */
+export declare const PAGE_SETTLED_KEY = "OgygiaSettled";
+/** Global the streamed resolve `<script>`s call: `__ogygia_page_resolve(id, ok, encoded)` where
+ *  `encoded` is the devalue-stringified resolved value (or the error). Installed by an inline
+ *  bootstrap in the first body chunk so it exists BEFORE any resolve script runs. */
+export declare const PAGE_DEFER_GLOBAL = "__ogygia_page_resolve";
+/** One registry per document, shared by the inline bootstrap and the runtime reviver via globalThis
+ *  (dev serves the runtime twice; a Symbol.for handle stays one instance — PAGE-STATE-SINGLETON). */
+export declare const PAGE_DEFER_REGISTRY_KEY: unique symbol;
+/** Inline bootstrap the handle emits in the body (before the resolve scripts, which stream after
+ *  `</body>`): defines the resolve global, queuing calls into the shared registry until the runtime
+ *  installs the live parser. Each call stamps when it arrived (`t[id]`, ms from the navigation): the
+ *  devtools Page tab names the streamed `page.data` key that held the document open. Emitted as a classic `<script>` so it runs during parse, before any
+ *  streamed resolve script. Kept in sync with the runtime's `install_page_defer` registry shape. */
+export declare const PAGE_DEFER_BOOTSTRAP: string;

package/dist/page-defer.js

@@ -0,0 +1,35 @@
+// src/page-defer.ts
+/**
+* Shared constants for streaming a load `Promise` in `$page.data` into an island on a csr=false page.
+*
+* Kit lets `load` return a Promise at any level of `data` and STREAMS its resolution to the client
+* (render the shell with `{#await}` pending, then flush `<script>` chunks that settle it). A csr=false
+* page has no hydration, so Kit's own stream is dead there — but an ISLAND has a client. We mirror
+* Kit's shape with our OWN registry: the page seed carries a DEFER MARKER for each pending promise
+* (a real pending Promise on the client), and streamed resolve `<script>`s settle them live.
+*
+* Constants only — safe to import from both the server (staging/serialization) and the client
+* (registry/reviver), with no code crossing the boundary.
+*/
+/** devalue reducer/reviver name for a deferred-promise leaf in the page seed. The encoded payload is
+*  the promise's integer id (assigned in walk order). */
+const PAGE_DEFER_KEY = "OgygiaDefer";
+/** devalue reducer/reviver name for an already-SETTLED promise leaf — used on the non-navigate
+*  (SPA/router) path, which can't run streamed scripts, so each promise is awaited server-side and
+*  revived as a resolved/rejected Promise at parse time. Keeps `page.data.x` a Promise on BOTH paths
+*  (matches Kit) and lets a rejection show `{#await …:catch}` without ever crashing the render. */
+const PAGE_SETTLED_KEY = "OgygiaSettled";
+/** Global the streamed resolve `<script>`s call: `__ogygia_page_resolve(id, ok, encoded)` where
+*  `encoded` is the devalue-stringified resolved value (or the error). Installed by an inline
+*  bootstrap in the first body chunk so it exists BEFORE any resolve script runs. */
+const PAGE_DEFER_GLOBAL = "__ogygia_page_resolve";
+/** One registry per document, shared by the inline bootstrap and the runtime reviver via globalThis
+*  (dev serves the runtime twice; a Symbol.for handle stays one instance — PAGE-STATE-SINGLETON). */
+const PAGE_DEFER_REGISTRY_KEY = Symbol.for("ogygia.page-defer");
+/** Inline bootstrap the handle emits in the body (before the resolve scripts, which stream after
+*  `</body>`): defines the resolve global, queuing calls into the shared registry until the runtime
+*  installs the live parser. Each call stamps when it arrived (`t[id]`, ms from the navigation): the
+*  devtools Page tab names the streamed `page.data` key that held the document open. Emitted as a classic `<script>` so it runs during parse, before any
+*  streamed resolve script. Kept in sync with the runtime's `install_page_defer` registry shape. */
+const PAGE_DEFER_BOOTSTRAP = `(function(){var K=Symbol.for('ogygia.page-defer'),r=globalThis[K]||(globalThis[K]={});r.q=r.q||[];globalThis.${PAGE_DEFER_GLOBAL}=function(i,o,e){(r.t||(r.t={}))[i]=performance.now();if(r.live)r.live(i,o,e);else r.q.push([i,o,e]);};})();`;
+export { PAGE_DEFER_BOOTSTRAP, PAGE_DEFER_GLOBAL, PAGE_DEFER_KEY, PAGE_DEFER_REGISTRY_KEY, PAGE_SETTLED_KEY };

package/dist/page-facts-script.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The script an answer carries with the page facts it rendered with (server/render-page.ts writes it,
+ * the runtime's answer seam `region_fragment` takes it out, seeds.ts merges it). Isomorphic: both
+ * halves name it from here.
+ */
+export declare const PAGE_FACTS_SCRIPT_TYPE = "application/ogygia-page-facts";
+export declare const PAGE_FACTS_SELECTOR: `script[type="${typeof PAGE_FACTS_SCRIPT_TYPE}"]`;

package/dist/page-facts-script.js

@@ -0,0 +1,9 @@
+// src/page-facts-script.ts
+/**
+* The script an answer carries with the page facts it rendered with (server/render-page.ts writes it,
+* the runtime's answer seam `region_fragment` takes it out, seeds.ts merges it). Isomorphic: both
+* halves name it from here.
+*/
+const PAGE_FACTS_SCRIPT_TYPE = "application/ogygia-page-facts";
+const PAGE_FACTS_SELECTOR = `script[type="${PAGE_FACTS_SCRIPT_TYPE}"]`;
+export { PAGE_FACTS_SCRIPT_TYPE, PAGE_FACTS_SELECTOR };

package/dist/page-seed-registry.d.ts

@@ -0,0 +1,72 @@
+import { SeedAsk as SeedAsk$1, SeedKeys } from "./server/seed-shape.js";
+/**
+ * Server-side capture for the page snapshot ($page.data / form / error / status) islands read through
+ * the `$app/state` shim. The handle CANNOT read the resolved load data: Kit merges it locally in
+ * `render.js` (`data = { ...data, ...branch[i].data }`) and never stores it on `RequestState`, and
+ * reading `$app/state`'s `page` inside a handle hook throws `lifecycle_outside_component`. So a
+ * COMPONENT rendered during SSR (Region.svelte) — where Kit's REAL `$app/state` page is available —
+ * records it HERE, and the handle merges it into the `application/ogygia-page` seed. That's how
+ * `$page.data` works inside islands on a csr=false page (boundary law: page.data crosses).
+ *
+ * Same shape as the setContext recorder: the server installs the recorder (request-scoped in
+ * `hooks.ts`), so it is universal-safe — on the client `record_page` is a no-op (no recorder
+ * installed).
+ */
+export type PageSnapshot = {
+  data?: unknown;
+  form?: unknown;
+  error?: unknown;
+  status?: number;
+  /** Set by the routeless document root (the router's seed) so nested island renders under the
+   *  server router see the page's real url/params/route, not the request's bare event. */
+  url?: {
+    href?: string;
+  };
+  params?: Record<string, string | undefined>;
+  route?: {
+    id: string | null;
+  };
+};
+/**
+ * `seed` — does this record WANT the client seed shipped? Region.svelte passes the build's answer
+ * for its island (`islandReadsPage`); the snapshot itself is always recorded (the handle also
+ * reads it for the postrender verdict — a load with a streaming promise is per-request by intent — and
+ * for server-side page reads), only the serialized seed is gated on it. Whether the seed ships is
+ * read ONCE, by the handle, when the document tail renders — no region asks during the render.
+ *
+ * `remotes` — the same question for the REMOTE seed (`application/ogygia-remote`): which remote
+ * modules (Kit id-hashes) this region's client code can call (`islandRemotes`, the build's chunk-
+ * closure answer). `[]` = none (a lake, a static hole, the routeless document root); `null` =
+ * fail-open, "may call anything" (a promise `of` whose module SSR cannot see, an entry the handoff
+ * does not know, dev). The handle unions every record and seeds only the remotes some region can
+ * reach — REMOTE SEED ONLY WHEN REACHABLE.
+ */
+/**
+ * `seed` is now an ASK, not a flag (SEED SHAPING): `false` — this region's client never reads the
+ * page (record the snapshot, ship nothing for it); `'all'` — it reads the page and the build could
+ * not pin its `page.data` reads to literal keys (or does not know the entry: a promise `of`, a
+ * foreign fragment, dev); a `string[]` — exactly these top-level `page.data` keys. The handle
+ * unions the asks: any `'all'` ships the whole `page.data`, otherwise the union of keys.
+ */
+export type SeedAsk = SeedAsk$1;
+type Recorder = (snapshot: PageSnapshot, seed: SeedAsk, remotes: readonly string[] | null, entry: string) => void;
+/** Server (`hooks.ts`) installs a request-scoped recorder. */
+export declare function set_page_recorder(fn: Recorder | null): void;
+/** What the page's regions asked for so far this request: whether any wants the seed, and which
+ *  `page.data` keys (`'all'` or a set; `null` until one asks). Undefined outside a request the
+ *  handle owns (no reader installed, or no bag). The server router's document reads it after its
+ *  render, so a router page seeds like a Kit page: only when an island reads it, only what is read. */
+type AskReader = () => {
+  wanted: boolean;
+  keys: SeedKeys | null;
+} | undefined;
+/** Server (`hooks.ts`) installs the reader beside the recorder. */
+export declare function set_seed_ask_reader(fn: AskReader | null): void;
+export declare function read_seed_ask(): ReturnType<AskReader>;
+export declare function set_ask_scope_opener(fn: (() => void) | null): void;
+export declare function open_ask_scope(): void;
+/** Region.svelte calls this during SSR with Kit's real page; the client is a no-op. `seed: false`
+ *  records the snapshot without asking for the client seed (no island on the page reads it);
+ *  `remotes` names the remote modules this region's client can call (`null` = any). */
+export declare function record_page(snapshot: PageSnapshot, seed?: SeedAsk, remotes?: readonly string[] | null, entry?: string): void;
+export {};

package/dist/page-seed-registry.js

@@ -0,0 +1,31 @@
+// src/page-seed-registry.ts
+let recorder = null;
+/** Server (`hooks.ts`) installs a request-scoped recorder. */
+function set_page_recorder(fn) {
+	recorder = fn;
+}
+let ask_reader = null;
+/** Server (`hooks.ts`) installs the reader beside the recorder. */
+function set_seed_ask_reader(fn) {
+	ask_reader = fn;
+}
+function read_seed_ask() {
+	return ask_reader?.();
+}
+/** Start collecting the regions' asks for a render outside a Kit page (the server router's document,
+*  answered before a Kit page bag exists): the next `record_page` calls of this request count, and
+*  `read_seed_ask` returns them. A no-op on the client or outside a request. */
+let ask_opener = null;
+function set_ask_scope_opener(fn) {
+	ask_opener = fn;
+}
+function open_ask_scope() {
+	ask_opener?.();
+}
+/** Region.svelte calls this during SSR with Kit's real page; the client is a no-op. `seed: false`
+*  records the snapshot without asking for the client seed (no island on the page reads it);
+*  `remotes` names the remote modules this region's client can call (`null` = any). */
+function record_page(snapshot, seed = "all", remotes = null, entry = "") {
+	recorder?.(snapshot, seed, remotes, entry);
+}
+export { open_ask_scope, read_seed_ask, record_page, set_ask_scope_opener, set_page_recorder, set_seed_ask_reader };

package/dist/plugin/capability.d.ts

@@ -0,0 +1,14 @@
+import { PluginCapabilities } from "./index.js";
+import { CapabilityLifetime } from "../server/capability-lifetime.js";
+/** Why a plugin capability is refused (the region endpoint's reasons of the same name). */
+export type CapabilityDeny = "expired" | "renew-window" | "sig";
+/** What the handle hands in: the app's key, its hole lifetime, and the refusal a region request
+ *  gets. (Handed in, never imported: this module stays free of the app's virtual modules, so the
+ *  plugin test harness runs it as it is.) */
+export interface CapabilitySigner {
+  sign(message: string): string;
+  verify(message: string, signature: string): boolean;
+  lifetime: CapabilityLifetime;
+  deny(why: CapabilityDeny): Response;
+}
+export declare function plugin_capabilities(name: string, signer: CapabilitySigner): PluginCapabilities;

package/dist/plugin/capability.js

@@ -0,0 +1,44 @@
+import { expiry_refusal } from "../server/shared-cache.js";
+// src/plugin/capability.ts
+function plugin_capabilities(name, signer) {
+	const scoped = (message) => `cap.${name}.${message}`;
+	const { lifetime } = signer;
+	return {
+		mint(message) {
+			const exp = String(lifetime.mint_expiry(""));
+			return {
+				exp,
+				sig: signer.sign(scoped(message(exp)))
+			};
+		},
+		open(url, message) {
+			const params = url.searchParams;
+			const exp = params.get("exp") ?? "";
+			const renewal = params.get("renew") === "1";
+			const now = Math.floor(Date.now() / 1e3);
+			const refused = expiry_refusal(exp, now, renewal, lifetime.renew_window);
+			if (refused) return {
+				ok: false,
+				response: signer.deny(refused)
+			};
+			if (!signer.verify(scoped(message(exp)), params.get("sig") ?? "")) return {
+				ok: false,
+				response: signer.deny("sig")
+			};
+			if (!renewal) return {
+				ok: true,
+				headers: {}
+			};
+			const fresh = String(lifetime.renewed_expiry());
+			const next = new URLSearchParams(params);
+			next.delete("renew");
+			next.set("exp", fresh);
+			next.set("sig", signer.sign(scoped(message(fresh))));
+			return {
+				ok: true,
+				headers: { "x-ogygia-capability": `${url.pathname}?${next}` }
+			};
+		}
+	};
+}
+export { plugin_capabilities };

package/dist/plugin/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `ogygia/plugin/client` — the BROWSER realm of a plugin (design: internal/notes/packages.md, plugin
+ * API v2). A plugin package exports `./client`; its default export is `defineClient({ … })`. The
+ * build finds it by the plugin's name and imports it statically into the runtime's boot entry, so it
+ * ships to every page the runtime boots on. Keep it small: it is in the boot's static graph — load
+ * anything heavy with a dynamic import of its own, on demand.
+ *
+ *   export default defineClient({
+ *     boot({ kitPage }) { … },                  // once, as the runtime boots (before any region wakes)
+ *     regionMount(el, { entry, urls }) { … },  // a region's component started in the browser
+ *     regionUnmount(el, { entry }) { … }       // …and left the page
+ *   });
+ *
+ * With no plugin's client realm in the build, core's calls into these fold away entirely.
+ */
+/** What `boot` is told about the page. */
+export interface ClientBootContext {
+  /** A page Kit hydrates (csr = true): ogygia's runtime does not boot there and no region hook
+   *  fires; the realm boots on its own (dev only). */
+  readonly kitPage: boolean;
+}
+/** A region whose component runs in the browser, as the region hooks see it. */
+export interface ClientRegion {
+  /** The region's entry (its component's stable module URL). */
+  readonly entry: string;
+}
+/** A plugin's browser half. */
+export interface ClientPlugin {
+  /** Once, as the runtime boots: after core's features, before the first region wakes. */
+  boot?(ctx: ClientBootContext): void;
+  /** A region's component started (hydrated, or mounted live). `urls`: the files it runs from. */
+  regionMount?(el: Element, region: ClientRegion & {
+    readonly urls: readonly string[];
+  }): void;
+  /** A region's component left the page. */
+  regionUnmount?(el: Element, region: ClientRegion): void;
+}
+/** Typed identity: a plugin's browser half. */
+export declare function defineClient(plugin: ClientPlugin): ClientPlugin;

package/dist/plugin/client.js

@@ -0,0 +1,6 @@
+// src/plugin/client.ts
+/** Typed identity: a plugin's browser half. */
+function defineClient(plugin) {
+	return plugin;
+}
+export { defineClient };

package/dist/plugin/css.d.ts

@@ -0,0 +1,3 @@
+/** Head tags for the components ONE render places (a layout chain + its page or error component):
+ *  each component's whole-tree CSS, linked once per request. */
+export declare function componentCssHead(components: readonly unknown[]): Promise<string>;