@ogygia/core 0.0.0 → 0.11.0

package/dist/server/props-wire.d.ts

@@ -0,0 +1,56 @@
+import { SeedIndex } from "../seed-refs.js";
+/** The sidecar attribute naming a non-devalue payload format; absent = devalue. */
+export declare const WIRE_FORMAT_ATTR = "data-og-format";
+/** The one non-devalue format: plain JSON, read with `JSON.parse`. */
+export declare const WIRE_FORMAT_JSON = "json";
+/** On a props sidecar: the transportable classes its props carry (tag paths, space-separated) —
+ *  what the browser loads before it decodes them. */
+export declare const WIRE_CLASSES_ATTR = "data-og-wire";
+/**
+ * devalue-serialize an island's props with the prop families' reducers, plus the seed-reference
+ * reducer when the caller has one. Throws a teaching error on a non-serializable prop.
+ */
+export declare function stringify_props(value: unknown, entry: string, seed_refs?: ((v: unknown) => unknown) | null, wire_out?: Set<string> | null): string;
+/** A sidecar's text and the lane it is in. */
+export interface WireText {
+  text: string;
+  json: boolean;
+}
+export interface PropsWire {
+  /** The canonical, seed-independent text — what the fingerprint hashes. */
+  readonly canonical: string;
+  /** Whether the canonical text is plain JSON (the lane the props qualify for). */
+  readonly json: boolean;
+  /** Live region-snippet entry URLs riding in these props (the preloads they need). Only a
+   *  devalue payload can carry one — a live snippet is a branded function, never plain JSON. */
+  readonly live_entries: readonly string[];
+  /** The transportable classes these props carry, by tag path (root-relative module): the browser
+   *  loads just these before decoding (it no longer loads every transportable up front). */
+  readonly wire_modules: readonly string[];
+  /** The sidecar text for the wire. `seed` is the page seed's index when the seed ships (then a
+   *  props subtree that is a seed node crosses as a reference), `null` when it does not. */
+  wire(seed: SeedIndex | null): WireText;
+  /** The references the LAST `wire()` wrote: how many, into which top-level `page.data` keys. */
+  readonly refs: {
+    count: number;
+    keys: readonly string[];
+  };
+  /** Why the canonical text is not JSON (the first disqualifying leaf); `null` on the JSON lane.
+   *  A separate walk, run on demand — the profiler's explainer, never the render path. */
+  culprit(): string | null;
+}
+/**
+ * Plan an island's sidecar: lane, canonical text, live snippet entries — and a `wire(seed)` that
+ * produces the final text once the request knows about the seed (the document tail's render).
+ * The wire text is produced once per seed: identical islands share one plan, and a tail rendered
+ * twice against the same index (a test, a re-render) plans and serializes once.
+ */
+export declare function plan_props_wire(value: unknown, entry: string): PropsWire;
+/** Where a sidecar sits: the document tail (one per fingerprint for the page) or next to its region. */
+export type SidecarPlace = "tail" | "adjacent";
+/**
+ * The sidecar `<script>` for one island: keyed by fingerprint when it has one (`data-ogygia-props`
+ * for the reconciler; in the TAIL also `id`, for an O(1) `getElementById` lookup by the runtime),
+ * unkeyed otherwise; the format attribute names the JSON lane.
+ */
+export declare function props_sidecar(fp: string, w: WireText, place?: SidecarPlace, wire_modules?: readonly string[]): string;

package/dist/server/props-wire.js

@@ -0,0 +1,178 @@
+import { escape_script_text } from "../escape.js";
+import { REF_WIRE_KEY, ref_reducer } from "../ref.js";
+import { register_wire_kind } from "../live-transport.js";
+import { register_derived_kind, register_store_kind } from "../store-transport.js";
+import { register_snippet_kind } from "../region-snippet.js";
+import { register_fn_kind } from "../fn-transport.js";
+import { SEED_REF_KEY, analyze, json_culprit, plan_seed_refs } from "../seed-refs.js";
+import { stringify } from "devalue";
+// src/server/props-wire.ts
+/**
+* PROPS ON THE WIRE — one plan per island for what its props sidecar says, and how.
+*
+* Two facts about an island's props decide its sidecar, and both come from ONE walk of the props
+* (`analyze`, seed-refs.ts):
+*
+*  1. THE LANE. A payload that is plain JSON — objects, arrays, strings, finite numbers, booleans,
+*     null, nothing else — goes out as `JSON.stringify` output (native, ~10× cheaper than devalue's
+*     JavaScript flatten + per-character escape, which was the single hottest thing in a profiled
+*     CMS page's render) under `data-og-format="json"`, and the runtime reads it with `JSON.parse`.
+*     Anything devalue exists for (a Date, a Map, undefined, a bigint, a wired class, a store, a
+*     snippet, an og.$ fn) keeps the devalue lane with the usual reducers.
+*
+*  2. THE FINGERPRINT INPUT. `data-og-fp` hashes the CANONICAL text — the lane's text WITHOUT seed
+*     references. That makes the fingerprint a function of the props alone: the same props give the
+*     same fingerprint whether or not the page seed ships, and whichever island rendered first.
+*     (Before, an island rendered ahead of the page's first `$page` reader hashed a full copy and one
+*     rendered after it hashed the referenced text — two fingerprints for one island.)
+*
+* The wire text itself is produced LAST, when the document tail renders (server/document-tail.ts):
+* by then the request knows whether the seed ships, so `wire(seed)` serializes relative to it when
+* a props subtree is a seed node (seed-refs.ts) and falls back to the canonical text otherwise.
+* Every island on the page gets references, first island included — the old "islands before the
+* first reader ship copies" limitation is gone with the render-time decision.
+*
+* devalue output is `<`-safe by construction (it writes `<`); the JSON lane goes through
+* `escape_script_text` once. Neither is escaped a second time.
+*
+* Universal module (no Node imports): Region.svelte imports it on both legs; nothing here runs on
+* the client.
+*/
+/** The sidecar attribute naming a non-devalue payload format; absent = devalue. */
+const WIRE_FORMAT_ATTR = "data-og-format";
+/** The one non-devalue format: plain JSON, read with `JSON.parse`. */
+const WIRE_FORMAT_JSON = "json";
+/** On a props sidecar: the transportable classes its props carry (tag paths, space-separated) —
+*  what the browser loads before it decodes them. */
+const WIRE_CLASSES_ATTR = "data-og-wire";
+/** Island props cross classes, stores, snippets, og.$ fns and resumable deriveds. */
+const PROP_FAMILIES = /* @__PURE__ */ new Set([
+	"wire",
+	"store",
+	"snippet",
+	"fn",
+	"derived"
+]);
+let kinds_registered = false;
+function register_prop_kinds() {
+	if (kinds_registered) return;
+	kinds_registered = true;
+	register_wire_kind();
+	register_store_kind();
+	register_snippet_kind();
+	register_fn_kind();
+	register_derived_kind();
+}
+/**
+* devalue-serialize an island's props with the prop families' reducers, plus the seed-reference
+* reducer when the caller has one. Throws a teaching error on a non-serializable prop.
+*/
+function stringify_props(value, entry, seed_refs = null, wire_out = null) {
+	register_prop_kinds();
+	try {
+		const reducers = {};
+		if (seed_refs) reducers[SEED_REF_KEY] = seed_refs;
+		const minted = ref_reducer(PROP_FAMILIES);
+		reducers[REF_WIRE_KEY] = wire_out ? (v) => {
+			const ref = minted(v);
+			if (ref && ref.k === "wire" && typeof ref.t === "string") {
+				const hash = ref.t.lastIndexOf("#");
+				wire_out.add(hash === -1 ? ref.t : ref.t.slice(0, hash));
+			}
+			return ref;
+		} : minted;
+		return stringify(value, reducers);
+	} catch (e) {
+		const detail = e instanceof Error ? e.message : String(e);
+		throw new Error(`[ogygia] island "${entry}": a captured prop is not serializable — ${detail}. Captured host values cross the boundary via devalue; functions/Promises cannot, and a class instance only can when the class declares a static [ogygia.wire] codec. Pass a serializable value, add a codec, or move that logic inside the island component.`);
+	}
+}
+/**
+* Plan an island's sidecar: lane, canonical text, live snippet entries — and a `wire(seed)` that
+* produces the final text once the request knows about the seed (the document tail's render).
+* The wire text is produced once per seed: identical islands share one plan, and a tail rendered
+* twice against the same index (a test, a re-render) plans and serializes once.
+*/
+function plan_props_wire(value, entry) {
+	const shape = analyze(value);
+	const refs = {
+		count: 0,
+		keys: []
+	};
+	const referenced = (seed) => {
+		refs.count = 0;
+		refs.keys = [];
+		if (seed === null || seed.size === 0) return null;
+		const plan = plan_seed_refs(seed, value);
+		if (plan.count === 0) return null;
+		refs.count = plan.count;
+		refs.keys = [...plan.keys].sort();
+		return {
+			text: stringify_props(value, entry, plan.reducer),
+			json: false
+		};
+	};
+	let last_seed;
+	let last_text;
+	const once = (seed, plain) => {
+		if (seed === last_seed) return last_text;
+		last_seed = seed;
+		return last_text = referenced(seed) ?? plain();
+	};
+	if (shape.json) {
+		const canonical = JSON.stringify(value);
+		let escaped = null;
+		return {
+			canonical,
+			json: true,
+			live_entries: [],
+			wire_modules: [],
+			wire: (seed) => once(seed, () => escaped ??= {
+				text: escape_script_text(canonical),
+				json: true
+			}),
+			refs,
+			culprit: () => null
+		};
+	}
+	const wire_modules = /* @__PURE__ */ new Set();
+	const canonical = stringify_props(value, entry, null, wire_modules);
+	const plain = {
+		text: canonical,
+		json: false
+	};
+	let culprit;
+	return {
+		canonical,
+		json: false,
+		live_entries: live_entries_in(canonical),
+		wire_modules: [...wire_modules],
+		wire: (seed) => once(seed, () => plain),
+		refs,
+		culprit: () => culprit === void 0 ? culprit = json_culprit(value) : culprit
+	};
+}
+const LIVE_ENTRY_MARK = "/immutable/og-region.";
+const LIVE_ENTRY_RE = /^\/[^"\s]+\/immutable\/og-region\.[0-9a-f]+\.js$/;
+function live_entries_in(text) {
+	const out = [];
+	let at = text.indexOf(LIVE_ENTRY_MARK);
+	while (at !== -1) {
+		const start = text.lastIndexOf("\"", at) + 1;
+		const end = text.indexOf("\"", at);
+		if (end === -1) break;
+		const url = text.slice(start, end);
+		if (LIVE_ENTRY_RE.test(url) && !out.includes(url)) out.push(url);
+		at = text.indexOf(LIVE_ENTRY_MARK, end);
+	}
+	return out;
+}
+/**
+* The sidecar `<script>` for one island: keyed by fingerprint when it has one (`data-ogygia-props`
+* for the reconciler; in the TAIL also `id`, for an O(1) `getElementById` lookup by the runtime),
+* unkeyed otherwise; the format attribute names the JSON lane.
+*/
+function props_sidecar(fp, w, place = "adjacent", wire_modules = []) {
+	return "<script type=\"application/ogygia-props\" data-ogygia-props" + (fp ? `="${fp}"` + (place === "tail" ? ` id="og-props-${fp}"` : "") : "") + (w.json ? ` ${WIRE_FORMAT_ATTR}="${WIRE_FORMAT_JSON}"` : "") + (wire_modules.length ? ` ${WIRE_CLASSES_ATTR}="${wire_modules.join(" ").replaceAll("\"", "&quot;")}"` : "") + ">" + w.text + "<\/script>";
+}
+export { WIRE_CLASSES_ATTR, WIRE_FORMAT_ATTR, WIRE_FORMAT_JSON, plan_props_wire, props_sidecar, stringify_props };

package/dist/server/rate-limit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared rate-limit bucket for the region endpoint.
+ * - Hard-caps map size with LRU eviction (Map insertion order).
+ * - Render limiter: charge AFTER a valid MAC (RATE-BURN).
+ * - Probe limiter: charge BEFORE HMAC (HMAC-CPU-DOS).
+ */
+export type RateBucket = {
+  n: number;
+  t: number;
+};
+export declare class RateLimiter {
+  #private;
+  constructor(opts: {
+    max: number;
+    windowMs: number;
+    cap?: number;
+  });
+  /** @returns true if this IP is over budget (request should 429). */
+  limited(ip: string): boolean;
+  get size(): number;
+  clear(): void;
+}

package/dist/server/rate-limit.js

@@ -0,0 +1,63 @@
+// src/server/rate-limit.ts
+const DEFAULT_CAP = 4096;
+var RateLimiter = class {
+	#buckets = /* @__PURE__ */ new Map();
+	#cap;
+	#max;
+	#windowMs;
+	#since_prune = 0;
+	constructor(opts) {
+		this.#max = opts.max;
+		this.#windowMs = opts.windowMs;
+		this.#cap = Math.max(1, opts.cap ?? DEFAULT_CAP);
+	}
+	/** Mark `ip` as most-recently used (Map: delete + set → end of iteration order). */
+	#touch(ip, b) {
+		this.#buckets.delete(ip);
+		this.#buckets.set(ip, b);
+	}
+	#evict_lru() {
+		while (this.#buckets.size > this.#cap) {
+			const oldest = this.#buckets.keys().next().value;
+			if (oldest === void 0) return;
+			this.#buckets.delete(oldest);
+		}
+	}
+	#maybe_prune(now) {
+		this.#since_prune++;
+		if (this.#since_prune >= 64) {
+			this.#since_prune = 0;
+			for (const [k, v] of this.#buckets) if (now - v.t >= this.#windowMs) this.#buckets.delete(k);
+		}
+		this.#evict_lru();
+	}
+	/** @returns true if this IP is over budget (request should 429). */
+	limited(ip) {
+		if (this.#max <= 0) return false;
+		const now = Date.now();
+		const b = this.#buckets.get(ip);
+		if (!b || now - b.t >= this.#windowMs) {
+			this.#buckets.set(ip, {
+				n: 1,
+				t: now
+			});
+			this.#maybe_prune(now);
+			return false;
+		}
+		if (b.n >= this.#max) {
+			this.#touch(ip, b);
+			return true;
+		}
+		b.n++;
+		this.#touch(ip, b);
+		return false;
+	}
+	get size() {
+		return this.#buckets.size;
+	}
+	clear() {
+		this.#buckets.clear();
+		this.#since_prune = 0;
+	}
+};
+export { RateLimiter };

package/dist/server/region-css.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param href the handoff's public href (the `islandCss()` value — the inline lookup key)
+ * @param resolved the same href through `asset()` (base / assets applied) — what the tag carries
+ */
+export declare function region_css_tag(href: string, resolved: string): string;

package/dist/server/region-css.js

@@ -0,0 +1,30 @@
+import { escape_attr } from "../escape.js";
+import { islandCssInline } from "virtual:ogygia/island-deps";
+// src/server/region-css.ts
+/**
+* THE REGION-CSS TAG — one place that turns a region's CSS href into head markup, for every emitter
+* (Region.svelte's island / held dual / content body sheets, the handle's hole-answer sheets).
+*
+* Two shapes, one channel: under Kit's `inlineStyleThreshold` the build kept the asset's text in
+* the island-deps handoff (`islandCssInline`), and the tag is `<style data-ogygia-region-css="href">`
+* — no request before first paint; otherwise it is the `<link rel="stylesheet" … data-ogygia-region-css>`
+* it always was. Both carry the resolved href as the channel's identity: the runtime hoists either
+* from a fetched answer into `<head>` and dedupes them against what the page already has by that
+* value, and the router keys a head `<style>` on it across swaps.
+*/
+/**
+* @param href the handoff's public href (the `islandCss()` value — the inline lookup key)
+* @param resolved the same href through `asset()` (base / assets applied) — what the tag carries
+*/
+function region_css_tag(href, resolved) {
+	const text = islandCssInline(href);
+	if (text !== null) return `<style data-ogygia-region-css="${escape_attr(resolved)}">${text}</style>`;
+	if (!is_css_href(href)) return `<link rel="modulepreload" href="${escape_attr(resolved)}" data-ogygia-region-css>`;
+	return `<link rel="stylesheet" href="${escape_attr(resolved)}" data-ogygia-region-css>`;
+}
+/** `….css` or `….css?…` (string search: one per region CSS tag). */
+function is_css_href(href) {
+	const q = href.indexOf("?");
+	return (q === -1 ? href : href.slice(0, q)).endsWith(".css");
+}
+export { region_css_tag };

package/dist/server/region-endpoint.d.ts

@@ -0,0 +1,35 @@
+import { CapabilityLifetime } from "./capability-lifetime.js";
+import { encode_region_props } from "./region-props.js";
+import { island_fingerprint } from "./fingerprint.js";
+/** A hole's own stylesheet hrefs, by region id — the list its endpoint answer links (hooks.ts
+ *  `region_css_links`), for a render that inlines the hole in the page instead (Region.svelte). */
+export declare function holeCss(entry: string): string[];
+/** The app's capability lifetime, bound to its settings: every hole it signs (these, and the
+ *  plugins' `app.capability`, which the handle hands it) expires and renews by this one rule. */
+export declare const app_lifetime: CapabilityLifetime;
+export declare function known_region_fps(): ReadonlySet<string>;
+/**
+ * Shared minting core for signed region capabilities — the ONE source of truth for the
+ * `/__ogygia__?id&props&exp&sig` URL, its MAC message, TTL policy, and session sealing. Both held regions
+ * (via {@link makeRegionEndpoint}) and server islands (Region.svelte's server branch) sign through this,
+ * each deriving/validating its own `payload` first (held regions degrade to `''` on failure, server
+ * islands throw). Given a valid encoded `payload`, the emitted URL/MAC/exp is identical to both.
+ *
+ * @param entry region id (server-manifest key baked into the MAC)
+ * @param payload b64url props blob (already encoded + size-checked by the caller)
+ * @param ttl response cache max-age in **seconds** (`0` = no-store, the default). Signed into the MAC
+ *   and echoed as a `ttl` query param so the handle sets `Cache-Control` from it — a harvested URL
+ *   can't be re-pointed at a longer browser cache.
+ */
+export declare function mint_region_capability(entry: string, payload: string, ttl?: number): string;
+/**
+ * Server-island mint: encode `props` (devalue + wire codec), enforce the size cap (THROW — a server
+ * island with oversized/non-serializable props is an author bug the handle would reject anyway), and
+ * sign. The one place `Region.svelte`'s `__mode: 'server'` branch signs its hole; routed through the
+ * `virtual:ogygia/region-endpoint` virtual so the client build stubs it to `''` (server islands never
+ * mint on the client — the runtime fetches the endpoint). Mirrors the old `ServerIsland.svelte`.
+ */
+export declare function mintServerIsland(entry: string, props: Record<string, unknown>, ttl?: number): string;
+/** HMAC-signed `<endpoint>?id&props&exp&sig` (`handle({ endpoint })`, default `/__ogygia__`) for re-rendering `entry` with `props`. */
+export declare function makeRegionEndpoint(entry: string, props?: Record<string, unknown>): string;
+export { encode_region_props, island_fingerprint as islandFingerprint };

package/dist/server/region-endpoint.js

@@ -0,0 +1,142 @@
+import { signing_key } from "./signing-key.js";
+import { MAX_REGION_PROPS_LEN, islands_endpoint } from "./endpoint.js";
+import { capability_lifetime } from "./capability-lifetime.js";
+import { encode_region_props, ensure_prop_kinds } from "./region-props.js";
+import { record_server_event } from "../events/server-registry.js";
+import { B64Url } from "./payload.js";
+import { REF_WIRE_KEY, ref_reducer } from "../ref.js";
+import { island_fingerprint } from "./fingerprint.js";
+import { stringify } from "devalue";
+import { getRequestEvent } from "virtual:ogygia/request-event";
+import { islandCss } from "virtual:ogygia/island-deps";
+import { island_render, island_url } from "virtual:ogygia/server-manifest";
+import { region_mac_message, sign } from "virtual:ogygia/sign";
+import { building } from "$app/env";
+import { sessionCookie } from "virtual:ogygia/session-cookie";
+import { resolve } from "$app/paths";
+import { regionTtl, renewWindow } from "virtual:ogygia/region-ttl";
+// src/server/region-endpoint.ts
+/**
+* Build a signed region capability URL (same shape as server-island holes).
+* Used by Region's lake branch for `render: 'live'`. Client build gets a stub that returns ''.
+*/
+const DEVTOOLS = typeof __OGYGIA_DEVTOOLS__ !== "undefined" ? __OGYGIA_DEVTOOLS__ : false;
+/** A hole's own stylesheet hrefs, by region id — the list its endpoint answer links (hooks.ts
+*  `region_css_links`), for a render that inlines the hole in the page instead (Region.svelte). */
+function holeCss(entry) {
+	const url = island_url[entry];
+	return url ? islandCss(url) : [];
+}
+/** Same families as encode_region_props — one seam law for island props. */
+const PROP_FAMILIES = /* @__PURE__ */ new Set([
+	"wire",
+	"store",
+	"snippet",
+	"fn",
+	"derived"
+]);
+/** The request being rendered (null off-request: prerender, a test). */
+function current_request() {
+	try {
+		return getRequestEvent().request;
+	} catch {
+		return null;
+	}
+}
+/** The app's capability lifetime, bound to its settings: every hole it signs (these, and the
+*  plugins' `app.capability`, which the handle hands it) expires and renews by this one rule. */
+const app_lifetime = capability_lifetime({
+	building,
+	region_ttl: regionTtl,
+	renew_window: renewWindow,
+	request: current_request
+});
+/** Session sealed into the MAC when `ogygia({ sessionCookie })` is set; empty at prerender. */
+function region_session() {
+	if (!sessionCookie) return "";
+	try {
+		return getRequestEvent().cookies.get(sessionCookie) ?? "";
+	} catch {
+		return "";
+	}
+}
+/**
+* SERVER-DELTA NAV (D3) — the set of region fingerprints the CLIENT already has live, sent on an
+* SPA nav via `x-ogygia-known`. Region.svelte consults this to SKIP re-rendering an island the
+* client is keeping. Honored ONLY on an SPA nav (`x-ogygia-spa`); a full page load has no header →
+* empty set → everything renders. Memoized per request-event (parsed once). Client-stubbed to empty.
+* A missing/oversized header is always the SAFE full render — this is a pure optimization signal.
+*/
+const KNOWN_FPS = /* @__PURE__ */ new WeakMap();
+const EMPTY_FPS = /* @__PURE__ */ new Set();
+function known_region_fps() {
+	let event;
+	try {
+		event = getRequestEvent();
+	} catch {
+		return EMPTY_FPS;
+	}
+	const cached = KNOWN_FPS.get(event);
+	if (cached !== void 0) return cached;
+	let set;
+	try {
+		const known = event.request.headers.get("x-ogygia-spa") ? event.request.headers.get("x-ogygia-known") : null;
+		set = known ? new Set(known.split(",")) : /* @__PURE__ */ new Set();
+	} catch {
+		set = /* @__PURE__ */ new Set();
+	}
+	KNOWN_FPS.set(event, set);
+	return set;
+}
+/**
+* Shared minting core for signed region capabilities — the ONE source of truth for the
+* `/__ogygia__?id&props&exp&sig` URL, its MAC message, TTL policy, and session sealing. Both held regions
+* (via {@link makeRegionEndpoint}) and server islands (Region.svelte's server branch) sign through this,
+* each deriving/validating its own `payload` first (held regions degrade to `''` on failure, server
+* islands throw). Given a valid encoded `payload`, the emitted URL/MAC/exp is identical to both.
+*
+* @param entry region id (server-manifest key baked into the MAC)
+* @param payload b64url props blob (already encoded + size-checked by the caller)
+* @param ttl response cache max-age in **seconds** (`0` = no-store, the default). Signed into the MAC
+*   and echoed as a `ttl` query param so the handle sets `Cache-Control` from it — a harvested URL
+*   can't be re-pointed at a longer browser cache.
+*/
+function mint_region_capability(entry, payload, ttl = 0) {
+	const session = region_session();
+	const exp = app_lifetime.mint_expiry(session);
+	const key = signing_key();
+	const ttl_field = ttl > 0 ? String(Math.floor(ttl)) : "";
+	const render = island_render[entry] ?? "";
+	const sig = sign(key.secret, region_mac_message(entry, exp, payload, session, ttl_field, render));
+	const ttl_param = ttl_field ? `&ttl=${ttl_field}` : "";
+	if (DEVTOOLS) record_server_event({
+		domain: "server",
+		name: "server.capability.minted",
+		id: entry,
+		ttl
+	});
+	return `${resolve(islands_endpoint())}?id=${encodeURIComponent(entry)}${render ? `&r=${render}` : ""}&props=${payload}&exp=${exp}${ttl_param}&sig=${sig}&k=${key.fp}`;
+}
+/**
+* Server-island mint: encode `props` (devalue + wire codec), enforce the size cap (THROW — a server
+* island with oversized/non-serializable props is an author bug the handle would reject anyway), and
+* sign. The one place `Region.svelte`'s `__mode: 'server'` branch signs its hole; routed through the
+* `virtual:ogygia/region-endpoint` virtual so the client build stubs it to `''` (server islands never
+* mint on the client — the runtime fetches the endpoint). Mirrors the old `ServerIsland.svelte`.
+*/
+function mintServerIsland(entry, props, ttl = 0) {
+	ensure_prop_kinds();
+	const payload = B64Url.encode(stringify(props, { [REF_WIRE_KEY]: ref_reducer(PROP_FAMILIES) }));
+	if (payload.length > 8192) throw new Error(`[ogygia] server island "${entry}": props payload is ${payload.length} b64 chars (max ${MAX_REGION_PROPS_LEN}). Shrink what you pass into the deferred region — the handle would reject this capability anyway.`);
+	return mint_region_capability(entry, payload, ttl);
+}
+/** HMAC-signed `<endpoint>?id&props&exp&sig` (`handle({ endpoint })`, default `/__ogygia__`) for re-rendering `entry` with `props`. */
+function makeRegionEndpoint(entry, props = {}) {
+	const payload = encode_region_props(props);
+	if (payload == null) {
+		console.warn(`[ogygia] render:'live' region ${entry} has props that cannot cross the wire (non-serializable or >${MAX_REGION_PROPS_LEN} b64 chars) — no revalidate endpoint minted (behaves like a static lake).`);
+		return "";
+	}
+	return mint_region_capability(entry, payload);
+}
+export { app_lifetime, encode_region_props, holeCss, island_fingerprint as islandFingerprint, known_region_fps, makeRegionEndpoint, mintServerIsland, mint_region_capability };

package/dist/server/region-props.d.ts

@@ -0,0 +1,6 @@
+/** Ensure the island-prop kinds are registered (called per encode; Map.has-cheap). */
+export declare function ensure_prop_kinds(): void;
+/**
+ * @returns b64url payload, or null when props cannot cross the wire (non-devalue or oversized).
+ */
+export declare function encode_region_props(props: Record<string, unknown>): string | null;

package/dist/server/region-props.js

@@ -0,0 +1,44 @@
+import { B64Url } from "./payload.js";
+import "./endpoint.js";
+import { REF_WIRE_KEY, ref_reducer } from "../ref.js";
+import { register_wire_kind } from "../live-transport.js";
+import { register_derived_kind, register_store_kind } from "../store-transport.js";
+import { register_snippet_kind } from "../region-snippet.js";
+import { register_fn_kind } from "../fn-transport.js";
+import { stringify } from "devalue";
+// src/server/region-props.ts
+/**
+* Encode region capability props (devalue → b64url) with the same size bound the handle enforces.
+* No virtual imports — safe to unit-test and share between mint paths.
+*/
+/** Ensure the island-prop kinds are registered (called per encode; Map.has-cheap). */
+function ensure_prop_kinds() {
+	register_wire_kind();
+	register_store_kind();
+	register_snippet_kind();
+	register_fn_kind();
+	register_derived_kind();
+}
+/** Island props carry classes, stores, snippets, og.$ fns and resumable deriveds. */
+const PROP_FAMILIES = /* @__PURE__ */ new Set([
+	"wire",
+	"store",
+	"snippet",
+	"fn",
+	"derived"
+]);
+/**
+* @returns b64url payload, or null when props cannot cross the wire (non-devalue or oversized).
+*/
+function encode_region_props(props) {
+	ensure_prop_kinds();
+	let payload;
+	try {
+		payload = B64Url.encode(stringify(props, { [REF_WIRE_KEY]: ref_reducer(PROP_FAMILIES) }));
+	} catch {
+		return null;
+	}
+	if (payload.length > 8192) return null;
+	return payload;
+}
+export { encode_region_props, ensure_prop_kinds };

package/dist/server/remote-seed-gate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * REMOTE SEED ONLY WHEN REACHABLE — the handle's per-remote decision when it builds the
+ * `application/ogygia-remote` seed: does any region rendered on this page have client code that
+ * can call this remote? The seed exists so a hydrating island that re-runs the same query resolves
+ * it from the document (zero-flash, no re-fetch). A remote no island on the page imports — a lake
+ * or a page script awaiting a query for its own server render — has no such reader, and its
+ * result is pure download weight (a CMS footer entry: 12.5 KB, measured).
+ *
+ * `wanted` is the union of every rendered region's `islandRemotes(entry)` (Region.svelte →
+ * page-seed-registry → the request bag): Kit id-hashes, the prefix of a remote's `internals.id`
+ * (`${hash}/${name}`). `null` = some region answered fail-open ("may call anything": a promise `of`,
+ * an entry the build handoff does not know, dev) → every remote seeds, exactly as before the gate.
+ * Pure, so it is unit-tested on its own.
+ */
+export declare function remote_seed_wanted(remote_id: string, wanted: ReadonlySet<string> | null): boolean;
+/** Kit's `RequestState.remote.implicit` entry: the remote's internals + its per-payload results. */
+export interface ImplicitRemote {
+  id?: string;
+  type: string;
+}
+export type ImplicitMap = Iterable<[ImplicitRemote, Record<string, () => unknown>]>;
+export type SeedBuckets = Record<"q" | "p" | "l" | "f", Record<string, {
+  v: unknown;
+}>>;
+/**
+ * Mirror Kit's OWN seed bucketing (server/remote.js) over the side-channel — Kit only serializes
+ * remote data inline when csr===true, so on csr=false pages the handle does it here. Buckets every
+ * implicit remote by type: q(query) / p(prerender) / l(query.live) / f(form). Seeding PRERENDER
+ * remotes (not only queries) is the fix for the async-island FOUC: a prerender remote awaited inside
+ * an island otherwise re-fetches on hydrate, so the component re-renders and Svelte RE-MOUNTS the
+ * subtree — a frame of unstyled DOM. With the seed in `prerender_responses`, the client resolves it
+ * synchronously and never re-fetches. Keys use `create_remote_key`, exactly like Kit's client.
+ *
+ * Skips, in order: a PRIVATE remote (no id — must never be serialized), a remote NO REGION'S
+ * CLIENT CAN CALL (`wanted`, above), an ERRORED or still-PENDING result (the client fetches it
+ * itself; an entry without `v` would hydrate as `undefined`), and a value carrying a BAKED region
+ * (`skip_value`: SSR HTML in the ticket — a page body from a `doc`-style remote is a page-sized
+ * RENDER the page already rendered; seeding it ships the body twice, ~130 KB/page measured).
+ *
+ * Pure over what it is handed (the implicit map, the request's memo of results, the two
+ * predicates); the handle serializes what comes back. Unit-tested across every permutation.
+ */
+export declare function collect_remote_seed(implicit: ImplicitMap, wanted: ReadonlySet<string> | null, opts: {
+  /** Kit's per-request memo of results already awaited (`state.remote.data`); a miss re-invokes. */
+  memo?: (internals: ImplicitRemote) => Record<string, unknown> | undefined;
+  /** A resolved value that must NOT seed (a baked region). */
+  skip_value?: (v: unknown) => boolean;
+  /** Kit's `create_remote_key(id, payload)`. */
+  key: (id: string, payload: string) => string;
+}): Promise<SeedBuckets>;