@ogygia/core 0.0.0 → 0.11.1

package/dist/server/remote-seed-gate.js

@@ -0,0 +1,66 @@
+// src/server/remote-seed-gate.ts
+/**
+* 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.
+*/
+function remote_seed_wanted(remote_id, wanted) {
+	if (wanted === null) return true;
+	const slash = remote_id.indexOf("/");
+	if (slash === -1) return true;
+	return wanted.has(remote_id.slice(0, slash));
+}
+/**
+* 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.
+*/
+async function collect_remote_seed(implicit, wanted, opts) {
+	const data = {
+		q: {},
+		p: {},
+		l: {},
+		f: {}
+	};
+	for (const [internals, record] of implicit) {
+		if (!internals.id) continue;
+		if (!remote_seed_wanted(internals.id, wanted)) continue;
+		const type = internals.type;
+		const bucket = type === "query_live" ? "l" : type[0];
+		if (bucket !== "q" && bucket !== "p" && bucket !== "l" && bucket !== "f") continue;
+		for (const payload in record) {
+			const remote_key = type === "form" ? payload : opts.key(internals.id, payload);
+			const promise = opts.memo?.(internals)?.[payload] ?? record[payload]();
+			let resolved = true;
+			await Promise.race([Promise.resolve(promise).then((v) => {
+				if (resolved && !opts.skip_value?.(v)) data[bucket][remote_key] = { v };
+			}, () => {}), Promise.resolve().then(() => {
+				resolved = false;
+			})]);
+		}
+	}
+	return data;
+}
+export { collect_remote_seed, remote_seed_wanted };

package/dist/server/render-cache.d.ts

@@ -0,0 +1,26 @@
+/** Cache key for a region render — id + props payload + session seal. `exp`/`sig` (which rotate per
+ *  mint) and `ttl` (a cache-window declaration, not a render input) are DELIBERATELY excluded so
+ *  two renders of the same region+props+user hit; session is INCLUDED so users never cross. */
+export declare function render_cache_key(id: string, props_payload: string, session: string): string;
+/** Cached HTML for `key`, or null on miss/expiry. A live hit is an LRU touch. */
+export declare function render_cache_get(key: string, now: number): string | null;
+/** Cache `html` for `ttl_sec` seconds. No-op for `ttl_sec <= 0` (dynamic holes are never cached). */
+export declare function render_cache_set(key: string, html: string, ttl_sec: number, now: number): void;
+/** Test/ops hook: drop everything. */
+export declare function render_cache_clear(): void;
+/** Test/ops hook: live entries + resident bytes. */
+export declare function render_cache_stats(): {
+  entries: number;
+  bytes: number;
+};
+/**
+ * THE shared cache-fronted render (G2) — the ONE seam both the deferred-region endpoint
+ * (#render_component) and the inline-island page render (Region.svelte) call. A hit returns the
+ * memo; a miss renders via `render_body()` (the caller supplies it — the endpoint wraps its render
+ * in a concurrency gate + timeout, the inline path renders directly), then caches. `cache` is
+ * `undefined`/`ttl<=0` for a dynamic hole → always renders, never stores. `now` injected for tests.
+ */
+export declare function cached_render(render_body: () => string | null | Promise<string | null>, cache: {
+  key: string;
+  ttl: number;
+} | undefined, now: number, report?: (outcome: "hit" | "miss" | "none") => void): Promise<string | null>;

package/dist/server/render-cache.js

@@ -0,0 +1,51 @@
+import { SizedLru } from "./sized-lru.js";
+const store = new SizedLru(67108864, 500);
+/** Cache key for a region render — id + props payload + session seal. `exp`/`sig` (which rotate per
+*  mint) and `ttl` (a cache-window declaration, not a render input) are DELIBERATELY excluded so
+*  two renders of the same region+props+user hit; session is INCLUDED so users never cross. */
+function render_cache_key(id, props_payload, session) {
+	return id + " " + props_payload + " " + session;
+}
+/** Cached HTML for `key`, or null on miss/expiry. A live hit is an LRU touch. */
+function render_cache_get(key, now) {
+	return store.get(key, now);
+}
+/** Cache `html` for `ttl_sec` seconds. No-op for `ttl_sec <= 0` (dynamic holes are never cached). */
+function render_cache_set(key, html, ttl_sec, now) {
+	if (ttl_sec <= 0) return;
+	store.set(key, html, html.length, now + ttl_sec * 1e3);
+}
+/** Test/ops hook: drop everything. */
+function render_cache_clear() {
+	store.clear();
+}
+/** Test/ops hook: live entries + resident bytes. */
+function render_cache_stats() {
+	return {
+		entries: store.size,
+		bytes: store.bytes
+	};
+}
+/**
+* THE shared cache-fronted render (G2) — the ONE seam both the deferred-region endpoint
+* (#render_component) and the inline-island page render (Region.svelte) call. A hit returns the
+* memo; a miss renders via `render_body()` (the caller supplies it — the endpoint wraps its render
+* in a concurrency gate + timeout, the inline path renders directly), then caches. `cache` is
+* `undefined`/`ttl<=0` for a dynamic hole → always renders, never stores. `now` injected for tests.
+*/
+async function cached_render(render_body, cache, now, report) {
+	if (cache !== void 0 && cache.ttl > 0) {
+		const hit = render_cache_get(cache.key, now);
+		if (hit !== null) {
+			report?.("hit");
+			return hit;
+		}
+	}
+	const body = await render_body();
+	if (cache !== void 0 && cache.ttl > 0 && body !== null) {
+		render_cache_set(cache.key, body, cache.ttl, now);
+		report?.("miss");
+	} else report?.("none");
+	return body;
+}
+export { cached_render, render_cache_clear, render_cache_get, render_cache_key, render_cache_set, render_cache_stats };

package/dist/server/render-page.d.ts

@@ -0,0 +1,51 @@
+import { KitPage } from "./kit-context.js";
+import { PageSnapshot } from "../page-seed-registry.js";
+import { SeedAsk } from "./seed-shape.js";
+import { RequestEvent } from "@sveltejs/kit";
+type Transport = Record<string, {
+  decode: (v: unknown) => unknown;
+  encode: (v: unknown) => unknown;
+}>;
+/** Where a dev warning goes (the handle's setting). */
+export declare function configure_render_page(o: {
+  warn: ((message: string) => void) | null;
+}): void;
+/** A request rendering on behalf of a page it is not: the islands endpoint or a remote call. */
+export declare function renders_for_a_page(event: RequestEvent): boolean;
+/** The page a request renders for: the same-origin Referer of a request rendering for a page, else
+ *  the request's own url. */
+export declare function page_url_of(event: RequestEvent): URL;
+/**
+ * Before an async render root starts: in a request rendering FOR a page, that page's facts, looked
+ * up once. `reads_data`: does this render read `page.data` (`null`: unknown here — a remote call
+ * looks up, a hole relies on its tree's build answer). The venue is the request's kind, as Kit and
+ * the islands endpoint name it — never whether some per-request state happens to exist.
+ */
+export declare function prepare_render_page(event: RequestEvent | undefined, transport: Transport | undefined, reads_data: boolean | null): Promise<void> | void;
+/**
+ * The page a render sees. `snapshot`: what this request's page render recorded, if anything. `null`
+ * when there is neither a snapshot nor a request (a render off-request: the caller's empty page).
+ */
+export declare function render_page(snapshot: PageSnapshot | undefined, event: RequestEvent | undefined): KitPage | null;
+/**
+ * A HOLE'S ADDRESS NAMES ITS PAGE: the call (id + props) and the page facts its tree renders from.
+ * A region refreshed after the page's data changed (a locale saved) re-mints its holes with a new
+ * version, so each fetches its new answer; a refresh that changed nothing keeps the address and the
+ * answer it has. The version of this request's page: its looked-up facts (a render for a page) or
+ * its recorded snapshot (in the page) — hashed once per request; `''` when there is no data.
+ */
+export declare function render_page_version(event: RequestEvent | undefined, snapshot: PageSnapshot | undefined): string;
+/**
+ * An island rendering FOR a page asks for the `page.data` keys its client reads (Region.svelte's
+ * record, the build's answer): kept for the answer's facts. `true` when the request renders for a
+ * page — the ask is this model's, never a page render's snapshot.
+ */
+export declare function note_render_page_ask(event: RequestEvent, seed: SeedAsk): boolean;
+/**
+ * ONE PAGE, NOT TWO: what an answer rendered FOR a page carries — the looked-up `page.data` keys its
+ * islands read, so they hydrate against the values their HTML was rendered from (the runtime merges
+ * them into the page store: seeds.ts). `''` when no island in it reads the page, the page was not
+ * looked up, or a value does not serialize (a still-streaming promise).
+ */
+export declare function render_page_facts_script(event: RequestEvent | undefined, transport: Transport | undefined): string;
+export {};

package/dist/server/render-page.js

@@ -0,0 +1,176 @@
+import { islands_endpoint } from "./endpoint.js";
+import { look_up_page } from "./page-facts.js";
+import { merge_seed_ask, shape_page_data } from "./seed-shape.js";
+import { PAGE_FACTS_SCRIPT_TYPE } from "../page-facts-script.js";
+import * as devalue from "devalue";
+// src/server/render-page.ts
+let warn = null;
+/** Where a dev warning goes (the handle's setting). */
+function configure_render_page(o) {
+	warn = o.warn;
+}
+/** A request rendering on behalf of a page it is not: the islands endpoint or a remote call. */
+function renders_for_a_page(event) {
+	return event.url.pathname.endsWith(islands_endpoint()) || event.isRemoteRequest === true;
+}
+/** The page a request renders for: the same-origin Referer of a request rendering for a page, else
+*  the request's own url. */
+function page_url_of(event) {
+	if (!renders_for_a_page(event)) return event.url;
+	const referer = event.request.headers.get("referer");
+	if (!referer) return event.url;
+	try {
+		const page = new URL(referer);
+		if (page.origin === event.url.origin) return page;
+	} catch {}
+	return event.url;
+}
+const looked_up = /* @__PURE__ */ new WeakMap();
+const facts_of = /* @__PURE__ */ new WeakMap();
+/**
+* Before an async render root starts: in a request rendering FOR a page, that page's facts, looked
+* up once. `reads_data`: does this render read `page.data` (`null`: unknown here — a remote call
+* looks up, a hole relies on its tree's build answer). The venue is the request's kind, as Kit and
+* the islands endpoint name it — never whether some per-request state happens to exist.
+*/
+function prepare_render_page(event, transport, reads_data) {
+	if (!event || !renders_for_a_page(event)) return;
+	if (!(reads_data ?? event.isRemoteRequest === true)) return;
+	const request = event.request;
+	const known = looked_up.get(request);
+	if (known) return known;
+	const page = page_url_of(event);
+	if (page === event.url) return;
+	const decoders = {};
+	for (const name in transport ?? {}) decoders[name] = transport[name].decode;
+	const p = look_up_page(page, event.fetch, decoders).then((facts) => {
+		if ("miss" in facts) warn?.(`[ogygia] ${page.pathname}: the page's data for a render outside it is unavailable: ${facts.miss}. The render sees an empty page.data.`);
+		else facts_of.set(request, facts);
+	});
+	looked_up.set(request, p);
+	return p;
+}
+/**
+* The page a render sees. `snapshot`: what this request's page render recorded, if anything. `null`
+* when there is neither a snapshot nor a request (a render off-request: the caller's empty page).
+*/
+function render_page(snapshot, event) {
+	if (!snapshot && !event) return null;
+	if (event && renders_for_a_page(event)) {
+		const facts = facts_of.get(event.request);
+		return {
+			url: facts?.url ?? page_url_of(event),
+			params: facts?.params ?? {},
+			route: facts?.route ?? { id: null },
+			status: 200,
+			data: facts && warn ? watched_data(facts, warn) : facts?.data ?? {},
+			form: null,
+			error: null,
+			state: {}
+		};
+	}
+	const snap = snapshot ?? {};
+	return {
+		url: snap.url?.href ? new URL(snap.url.href) : event?.url,
+		params: snap.params ?? event?.params ?? {},
+		route: snap.route ?? { id: event?.route.id ?? null },
+		status: snap.status ?? 200,
+		data: snap.data ?? {},
+		form: snap.form ?? null,
+		error: snap.error ?? null,
+		state: {}
+	};
+}
+/** Reads a component makes without meaning a page key (Svelte, devalue, a thenable check). */
+const NOT_A_KEY = /* @__PURE__ */ new Set([
+	"then",
+	"toJSON",
+	"constructor",
+	"valueOf",
+	"toString",
+	"$$typeof",
+	"nodeType"
+]);
+const warned_keys = /* @__PURE__ */ new WeakMap();
+/**
+* DEV: a render for a page reading a `page.data` key the page's server loads did not produce — most
+* often one a UNIVERSAL load (`+page.ts` / `+layout.ts`) makes, which exists only inside a full page
+* render. Said once per key, naming it, instead of rendering `undefined` silently (a header that
+* comes out "signed out" with no error anywhere).
+*/
+function watched_data(facts, say) {
+	return new Proxy(facts.data, { get(target, key, receiver) {
+		if (typeof key === "string" && !NOT_A_KEY.has(key) && !(key in target)) {
+			let seen = warned_keys.get(facts);
+			if (!seen) warned_keys.set(facts, seen = /* @__PURE__ */ new Set());
+			if (!seen.has(key)) {
+				seen.add(key);
+				say(`[ogygia] ${facts.url.pathname}: a region rendered outside its page read page.data.${key}, which this page's server loads do not produce. A key a universal load (+page.ts / +layout.ts) returns exists only inside a full page render: return it from a server load, or pass it as a prop.`);
+			}
+		}
+		return Reflect.get(target, key, receiver);
+	} });
+}
+const versions = /* @__PURE__ */ new WeakMap();
+/**
+* A HOLE'S ADDRESS NAMES ITS PAGE: the call (id + props) and the page facts its tree renders from.
+* A region refreshed after the page's data changed (a locale saved) re-mints its holes with a new
+* version, so each fetches its new answer; a refresh that changed nothing keeps the address and the
+* answer it has. The version of this request's page: its looked-up facts (a render for a page) or
+* its recorded snapshot (in the page) — hashed once per request; `''` when there is no data.
+*/
+function render_page_version(event, snapshot) {
+	if (!event) return "";
+	const known = versions.get(event.request);
+	if (known !== void 0) return known;
+	const data = renders_for_a_page(event) ? facts_of.get(event.request)?.data : snapshot?.data;
+	let v = "";
+	if (data && typeof data === "object") try {
+		v = fnv1a(JSON.stringify(data));
+	} catch {}
+	if (v) versions.set(event.request, v);
+	return v;
+}
+/** 32-bit FNV-1a, base36: a version tag, not a security boundary. */
+function fnv1a(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+}
+const asks_of = /* @__PURE__ */ new WeakMap();
+/**
+* An island rendering FOR a page asks for the `page.data` keys its client reads (Region.svelte's
+* record, the build's answer): kept for the answer's facts. `true` when the request renders for a
+* page — the ask is this model's, never a page render's snapshot.
+*/
+function note_render_page_ask(event, seed) {
+	if (!renders_for_a_page(event)) return false;
+	if (seed !== false) {
+		const merged = merge_seed_ask(asks_of.get(event.request) ?? null, seed);
+		if (merged) asks_of.set(event.request, merged);
+	}
+	return true;
+}
+/**
+* ONE PAGE, NOT TWO: what an answer rendered FOR a page carries — the looked-up `page.data` keys its
+* islands read, so they hydrate against the values their HTML was rendered from (the runtime merges
+* them into the page store: seeds.ts). `''` when no island in it reads the page, the page was not
+* looked up, or a value does not serialize (a still-streaming promise).
+*/
+function render_page_facts_script(event, transport) {
+	if (!event || !renders_for_a_page(event)) return "";
+	const facts = facts_of.get(event.request);
+	const keys = asks_of.get(event.request);
+	if (!facts || !keys) return "";
+	const encoders = {};
+	for (const name in transport ?? {}) encoders[name] = transport[name].encode;
+	try {
+		return `<script type="${PAGE_FACTS_SCRIPT_TYPE}">${devalue.stringify(shape_page_data(facts.data, keys), encoders)}<\/script>`;
+	} catch {
+		return "";
+	}
+}
+export { configure_render_page, note_render_page_ask, page_url_of, prepare_render_page, render_page, render_page_facts_script, render_page_version, renders_for_a_page };

package/dist/server/render-region-html.d.ts

@@ -0,0 +1,2 @@
+import { Component } from "svelte";
+export declare function render_region_html(component: Component<Record<string, unknown>>, module_url: string, props: Record<string, unknown>): Promise<string>;

package/dist/server/render-region-html.js

@@ -0,0 +1,19 @@
+import { region_css_tags } from "./html-scan.js";
+import { kit_page_facts_tail, kit_page_ready, kit_render_context } from "./kit-context.js";
+import { render } from "svelte/server";
+import { islandCss } from "virtual:ogygia/island-deps";
+/** context.ts's LAKE key (`isInLake`), by its global name — context.ts reaches virtual modules. */
+const LAKE_SUBTREE_KEY = Symbol.for("ogygia.lake-subtree");
+async function render_region_html(component, module_url, props) {
+	await kit_page_ready();
+	const context = kit_render_context();
+	context.set(LAKE_SUBTREE_KEY, true);
+	const r = await render(component, {
+		props,
+		context
+	});
+	let own = "";
+	for (const href of islandCss(module_url)) own += "<link rel=\"stylesheet\" href=\"" + href + "\" data-ogygia-region-css>";
+	return own + region_css_tags(r.head) + r.body + kit_page_facts_tail();
+}
+export { render_region_html };

package/dist/server/request-stats.d.ts

@@ -0,0 +1,174 @@
+/**
+ * OGYGIA'S OWN COST PER REQUEST — what the handle added to a Kit page: the transform's wall time,
+ * how many islands' sidecars and hints went to the tail, and the bytes of every side-channel
+ * (page seed, remote seed, props tail, fn manifest, context bridge).
+ *
+ * The handle (hooks.ts) writes one record per page request; the profiler reads it back when it
+ * finalizes the request's log entry, so a report can say "ogygia: 4 ms, seed 292 KB, props 131 KB
+ * over 21 islands" and a finding can point at an oversized seed. Keyed by the `Request` in a
+ * WeakMap — the record dies with the request, nothing is deleted, and the two modules never
+ * import each other (hooks.ts imports the profiler lazily; the profiler must not import hooks).
+ *
+ * DETAIL is opt-in (`set_request_stats_detail`): the profiler turns it on for the length of a
+ * recording, and only then does the handle spend anything on the per-island rows, the seed
+ * explainer and the hole notes below. Off, a request pays one WeakMap write of the totals.
+ */
+/** One island's row in the report's Islands table. */
+export interface IslandStat {
+  fp: string;
+  /** the island's source entry (what the handoff keys on) */
+  entry: string;
+  /** the component's name (Svelte's SSR function name, `ProductCard`); '' when unknown */
+  name: string;
+  /** the client module URL the region imports: its LOCATION (the content-hashed file served), not
+   *  its identity (`entry`) */
+  module_url: string;
+  /** `load` | `idle` | `visible` | `interaction` | a media query */
+  wake: string;
+  /** the props sidecar as shipped */
+  props_bytes: number;
+  /** canonical (unreferenced) props size — what the fingerprint hashes */
+  canonical_bytes: number;
+  /** that canonical text itself, when it is short (≤ 4 KB): the report compares an island across its
+   *  renders and names the prop that moved its fingerprint */
+  canonical?: string;
+  /** the sidecar took the JSON lane */
+  json: boolean;
+  /** the first leaf that kept the props off the JSON lane, when devalue was used */
+  culprit: string | null;
+  /** seed references written into the sidecar, and the top-level page.data keys they point at */
+  refs: number;
+  ref_keys: string[];
+  /** the module-preload hrefs this island contributed (its JS closure) */
+  hints: string[];
+  /** what the build saw in the island's components (handlers, $state, bind:, use:) */
+  interactivity: IslandInteractivity | null;
+  /** how many regions on the page share this fingerprint */
+  count: number;
+  /** a grouped row (`group_islands`): how many distinct fingerprints it merged */
+  variants?: number;
+}
+export interface IslandInteractivity {
+  handlers: number;
+  state: number;
+  effects: number;
+  binds: number;
+  actions: number;
+  /** remote functions its code can call (a query that streams, a form, a command) and `await` in
+   *  its markup: what changes it after it wakes without a handler of its own (older builds: absent) */
+  remotes?: number;
+  awaits?: number;
+  /** context reads and rune-module imports: state another island can change */
+  shared?: number;
+  /** `.svelte` files in the island's closure that were scanned */
+  files: number;
+}
+/** One top-level `page.data` key in the seed explainer. */
+export interface SeedKeyStat {
+  key: string;
+  /** serialized size estimate of the value */
+  bytes: number;
+  /** islands whose client code reads this key (the build's answer) */
+  readers: string[];
+  /** islands whose props sidecar points into this key (seed references) */
+  referenced_by: string[];
+  shipped: boolean;
+  /** why it ships: read by an island, referenced by a sidecar, or some island reads the page whole */
+  reason: "read" | "referenced" | "whole" | null;
+}
+/** A deferred hole the page rendered (its fallback in the shell, its content on the endpoint). */
+export interface HoleStat {
+  /** region id (the server manifest key) */
+  id: string;
+  /** the component's name (`Recommendations`); '' when unknown */
+  name: string;
+  /** a short preview of the props (`{"forProduct":"P1"}`), what tells two holes of one component apart */
+  props: string;
+  /** fetch schedule (`load` | `visible` | …) */
+  when: string;
+  /** phase-2 wake, when it hydrates */
+  hydrate: string | null;
+  /** response cache max-age in seconds (0 = no-store) */
+  ttl: number;
+  count: number;
+  /** each copy by its key (runtime/hash.ts `hole_copy_key`) with its props preview — what the
+   *  browser's report and the hole's requests name a copy by (at most 12) */
+  copies?: {
+    p: string;
+    props: string;
+  }[];
+}
+export interface OgygiaRequestStats {
+  /** wall ms of `inject_client_seeds` (locate, dedupe, tail render, seed serialize, assemble) */
+  transform_ms: number;
+  /** props sidecars in the tail (one per distinct island fingerprint) */
+  islands: number;
+  /** module-preload hints in the tail */
+  hints: number;
+  /** deferred holes recorded in the tail (Kit-hydrated documents only) */
+  holes: number;
+  /** bytes of the `application/ogygia-page` seed ('' → 0) */
+  seed_bytes: number;
+  /** bytes of the `application/ogygia-remote` seed */
+  remote_seed_bytes: number;
+  /** bytes of the whole tail (hints + props sidecars + holes record) */
+  tail_bytes: number;
+  /** bytes of the og.$ factory manifest script */
+  fnm_bytes: number;
+  /** bytes of the drop-in setContext bridge */
+  ctx_bytes: number;
+  /** whether the seed went out on the JSON lane (else devalue) */
+  seed_json: boolean;
+  /** the first leaf that kept the SEED off the JSON lane, when devalue was used */
+  seed_culprit?: string | null;
+  island_rows?: IslandStat[];
+  seed?: {
+    keys: SeedKeyStat[];
+    /** islands that read `page.data` whole (`'all'` asks) — the reason everything ships */
+    whole_by: string[];
+  };
+  hole_rows?: HoleStat[];
+}
+/** What the islands endpoint did for one hole request. */
+export interface HoleRequestStats {
+  kind: "hole";
+  id: string;
+  /** `hit` served from the render cache; `miss` rendered and stored; `none` = no cache (ttl 0) */
+  cache: "hit" | "miss" | "none";
+  ttl: number;
+  /** ms it waited for a render slot (the server renders a few holes at a time); absent on a hit */
+  queue_ms?: number;
+  /** its component's name (the server manifest's): names the hole where no page row does */
+  name?: string;
+  /** which copy (runtime/hash.ts `hole_copy_key` of its props payload): copies share the id */
+  p?: string;
+}
+/** A reader of these stats is installed (the profiler, from `@ogygia/devtools`): the handle records
+ *  each request's totals. Off, it records nothing — no stats object per request in an app without one. */
+export declare function want_request_stats(): void;
+export declare function request_stats_wanted(): boolean;
+export declare function record_request_stats(request: Request, s: OgygiaRequestStats): void;
+export declare function request_stats_of(request: Request): OgygiaRequestStats | undefined;
+export declare function record_hole_stats(request: Request, s: HoleRequestStats): void;
+export declare function hole_stats_of(request: Request): HoleRequestStats | undefined;
+/** One hole rendered inside a BATCH request (the page's first-load holes, a navigation's): the
+ *  profiler logs each as its own hole request, timed by its own render within the batch. */
+export interface BatchHoleStats extends HoleRequestStats {
+  /** the hole's own time in the batch: its wait for a slot and its render (ms) */
+  ms: number;
+  /** 200 rendered; 500 its render failed */
+  status: number;
+}
+export declare function set_batch_hole_listener(fn: ((request: Request, s: BatchHoleStats) => void) | null): void;
+export declare function has_batch_hole_listener(): boolean;
+export declare function record_batch_hole_stats(request: Request, s: BatchHoleStats): void;
+/**
+ * The profiler turns detail on for a recording; off, the handle records totals only. COUNTED, not a
+ * switch: the flag is the process's, while a recorder lock is one profiler instance's — and two can
+ * live at once (the dev server re-runs the app's hooks on an edit and `ogygia.handle()` builds a new
+ * profiler, while the old one's sample and trap timers still record). The first window to end then
+ * turned detail off under the other's render: its report kept no island rows ("islands 1, rows 0")
+ * and named its islands by their files. On while any window records.
+ */
+export declare function set_request_stats_detail(on: boolean): void;
+export declare function request_stats_detailed(): boolean;

package/dist/server/request-stats.js

@@ -0,0 +1,54 @@
+// src/server/request-stats.ts
+const stats = /* @__PURE__ */ new WeakMap();
+const hole_stats = /* @__PURE__ */ new WeakMap();
+let detailed = false;
+let wanted = false;
+/** A reader of these stats is installed (the profiler, from `@ogygia/devtools`): the handle records
+*  each request's totals. Off, it records nothing — no stats object per request in an app without one. */
+function want_request_stats() {
+	wanted = true;
+}
+function request_stats_wanted() {
+	return wanted;
+}
+function record_request_stats(request, s) {
+	stats.set(request, s);
+}
+function request_stats_of(request) {
+	return stats.get(request);
+}
+function record_hole_stats(request, s) {
+	hole_stats.set(request, s);
+}
+function hole_stats_of(request) {
+	return hole_stats.get(request);
+}
+/** The batch streams: its holes settle AFTER the handle returned (and the profiler logged the
+*  request), so each is handed on as it lands — to the profiler that asked, or nowhere. */
+let batch_listener = null;
+function set_batch_hole_listener(fn) {
+	batch_listener = fn;
+}
+function has_batch_hole_listener() {
+	return batch_listener !== null;
+}
+function record_batch_hole_stats(request, s) {
+	batch_listener?.(request, s);
+}
+/**
+* The profiler turns detail on for a recording; off, the handle records totals only. COUNTED, not a
+* switch: the flag is the process's, while a recorder lock is one profiler instance's — and two can
+* live at once (the dev server re-runs the app's hooks on an edit and `ogygia.handle()` builds a new
+* profiler, while the old one's sample and trap timers still record). The first window to end then
+* turned detail off under the other's render: its report kept no island rows ("islands 1, rows 0")
+* and named its islands by their files. On while any window records.
+*/
+function set_request_stats_detail(on) {
+	detail_depth = on ? detail_depth + 1 : Math.max(0, detail_depth - 1);
+	detailed = detail_depth > 0;
+}
+let detail_depth = 0;
+function request_stats_detailed() {
+	return detailed;
+}
+export { has_batch_hole_listener, hole_stats_of, record_batch_hole_stats, record_hole_stats, record_request_stats, request_stats_detailed, request_stats_of, request_stats_wanted, set_batch_hole_listener, set_request_stats_detail, want_request_stats };