@ogygia/core 0.0.0 → 0.11.0

package/dist/server/document-tail.d.ts

@@ -0,0 +1,113 @@
+import { SeedIndex } from "../seed-refs.js";
+import { WireText } from "./props-wire.js";
+import { HoleStat, IslandInteractivity, IslandStat } from "./request-stats.js";
+/** What the tail needs of a props plan (server/props-wire.ts `PropsWire`, or a test's stand-in). */
+export interface SidecarWire {
+  wire(seed: SeedIndex | null): WireText;
+  readonly json?: boolean;
+  readonly canonical?: string;
+  readonly refs?: {
+    count: number;
+    keys: readonly string[];
+  };
+  culprit?(): string | null;
+  /** the transportable classes the props carry (stamped on the sidecar for the browser) */
+  readonly wire_modules?: readonly string[];
+}
+/** The island facts a region hands over with its plan, for the profiler's Islands table. */
+/** A short, safe preview of a hole's props for the profiler (`{"forProduct":"P1"}`), so two holes
+ *  of one component read apart; empty for no props, truncated past 80 chars. */
+export declare function props_preview(props: unknown, max?: number): string;
+export interface IslandMeta {
+  entry: string;
+  /** the component's SSR function name (Svelte names it after the file); '' when unknown */
+  name?: string;
+  module_url: string;
+  wake: string;
+  interactivity?: IslandInteractivity | null;
+}
+/**
+ * THE module-preload hint for one island chunk. EVERY hint is `fetchpriority="low"`: a hint's job
+ * is discovery (no parse-then-import waterfall), not priority — nothing an island downloads is
+ * needed for first paint, the server painted the content — so island code must never outrank the
+ * CSS and the LCP image (Region.svelte has the measured story). Regions hand the tail hrefs, not
+ * tags: one string per hint, built once here, never parsed back out of markup.
+ */
+export declare function modulepreload_tag(href: string): string;
+/**
+ * The runtime bootstrap: its module script, then a `modulepreload` for each of its static imports
+ * (the build's handoff — the few chunks the runtime shares with the rest of the app, e.g. Vite's
+ * preload helper and the modules Kit's client transport also uses). The browser only discovers a
+ * module's imports after downloading and parsing it; hinted here, they download ALONGSIDE the
+ * runtime instead of one round trip after it. Normal priority — the runtime cannot run without
+ * them. `data-ogygia-runtime-dep` keeps them attached to the script when the handle moves it
+ * (head-presence.ts `runtime_first`).
+ */
+export declare function runtime_bootstrap_tags(src: string, deps: readonly string[]): string;
+/**
+ * The island graph (island-graph.ts) as one inert JSON script: entry → the chunks its code needs.
+ * The runtime turns an entry's list into modulepreload links when that island wakes. Empty map →
+ * no script.
+ */
+export declare function island_graph_script(graph: ReadonlyMap<string, readonly string[]>, locations?: ReadonlyMap<string, string> | null): string;
+/** What the server minted for one deferred hole on a Kit-hydrated document (see `hole()`). */
+export type HoleRecord = {
+  /** The signed capability URL the hole's `endpoint` attribute carries. */
+  endpoint: string;
+  /** The adjacent props sidecar HTML of a hydrating hole, or `''` for a static one. */
+  sidecar: string;
+};
+export declare class DocumentTail {
+  #private;
+  /** Add a region's module-preload hrefs; each href is hinted once (first wins). With `fp`, the
+   *  hrefs are also remembered as that island's JS closure. */
+  hints(hrefs: readonly string[], fp?: string): void;
+  /** The list already recorded for an entry, if any — a second instance of an island reuses it. */
+  graph_of(entry: string): readonly string[] | undefined;
+  /** Record the chunks an island entry's code needs (the island graph — data, not hints: the
+   *  runtime preloads them when the island wakes). One list per entry — its identity — (first wins).
+   *  With `fp`, the list is also remembered as that island's JS closure for the profiler, led by the
+   *  file the island actually loads: `src`, its location (the identity when it has none). */
+  graph(entry: string, hrefs: readonly string[], fp?: string, src?: string): void;
+  /** Record where an entry no element carries is served from (the graph script's `s`). */
+  locate(identity: string, src: string): void;
+  /** Register an island's props sidecar under its fingerprint; identical islands share one (the
+   *  count still says how many). `meta` is what the profiler's Islands table shows. */
+  props(fp: string, wire: SidecarWire, meta?: IslandMeta | null): void;
+  /** Note a deferred hole the page rendered (every document, not only Kit-hydrated ones): its
+   *  schedule and cache policy, for the profiler's hole economics. */
+  note_hole(id: string, when: string, hydrate: string | null, ttl: number, name?: string, props?: unknown, copy?: string): void;
+  /** The holes noted on this page. */
+  hole_rows(): HoleStat[];
+  /** The per-island facts of the last `render()` — `null` before it ran. */
+  island_rows(): IslandStat[] | null;
+  /**
+   * Record a deferred hole's server-minted facts under its identity (`data-og-hole`), for a
+   * KIT-HYDRATED document only. Kit can give up hydrating such a document (a component threw, the
+   * markup mismatched): Svelte clears Kit's root and mounts it fresh, and every hole is rendered
+   * again by the client leg — with no address, since only the server can mint one. The tail sits
+   * OUTSIDE Kit's root, so this record survives that rebuild, and the runtime hands each rebuilt
+   * hole its address (and a hydrating hole its props sidecar) back by identity — never by
+   * position. Identical holes (same id + props → same identity) share one record.
+   */
+  hole(identity: string, endpoint: string, sidecar: string): void;
+  get empty(): boolean;
+  /** Hint count + graph entry count + sidecar count + hole-record count, for tests and devtools. */
+  get size(): {
+    hints: number;
+    graph: number;
+    props: number;
+    holes: number;
+  };
+  /** The tail's HTML: hints, the island graph, then props (each rendered now, against `seed`), then
+   *  the holes record (one script, JSON, `<`-escaped). Empty string when nothing was recorded. With
+   *  `detail`, the per-island rows (bytes, lane, references, the devalue culprit) are kept for
+   *  the profiler — a little extra work, only while it records. */
+  render(seed?: SeedIndex | null, detail?: boolean): string;
+}
+type TailReader = () => DocumentTail | null;
+/** Server (`hooks.ts`) installs a request-scoped reader; `null` uninstalls. */
+export declare function set_tail_reader(fn: TailReader | null): void;
+/** The current request's tail, or `null` when this render has none (client, endpoint, test). */
+export declare function document_tail(): DocumentTail | null;
+export {};

package/dist/server/document-tail.js

@@ -0,0 +1,208 @@
+import { escape_script_text } from "../escape.js";
+import { HOLES_SCRIPT_TYPE } from "../holes-record.js";
+import { ISLAND_GRAPH_ATTR, encode_island_graph } from "../island-graph.js";
+import { props_sidecar } from "./props-wire.js";
+// src/server/document-tail.ts
+/** The island facts a region hands over with its plan, for the profiler's Islands table. */
+/** A short, safe preview of a hole's props for the profiler (`{"forProduct":"P1"}`), so two holes
+*  of one component read apart; empty for no props, truncated past 80 chars. */
+function props_preview(props, max = 80) {
+	if (!props || typeof props !== "object") return "";
+	try {
+		const s = JSON.stringify(props, (_k, v) => typeof v === "bigint" ? String(v) : v);
+		if (!s || s === "{}" || s === "[]") return "";
+		return s.length > max ? s.slice(0, max - 1) + "…" : s;
+	} catch {
+		return "";
+	}
+}
+/**
+* THE module-preload hint for one island chunk. EVERY hint is `fetchpriority="low"`: a hint's job
+* is discovery (no parse-then-import waterfall), not priority — nothing an island downloads is
+* needed for first paint, the server painted the content — so island code must never outrank the
+* CSS and the LCP image (Region.svelte has the measured story). Regions hand the tail hrefs, not
+* tags: one string per hint, built once here, never parsed back out of markup.
+*/
+function modulepreload_tag(href) {
+	return "<link rel=\"modulepreload\" href=\"" + href + "\" fetchpriority=\"low\">";
+}
+/**
+* The runtime bootstrap: its module script, then a `modulepreload` for each of its static imports
+* (the build's handoff — the few chunks the runtime shares with the rest of the app, e.g. Vite's
+* preload helper and the modules Kit's client transport also uses). The browser only discovers a
+* module's imports after downloading and parsing it; hinted here, they download ALONGSIDE the
+* runtime instead of one round trip after it. Normal priority — the runtime cannot run without
+* them. `data-ogygia-runtime-dep` keeps them attached to the script when the handle moves it
+* (head-presence.ts `runtime_first`).
+*/
+function runtime_bootstrap_tags(src, deps) {
+	let html = "<script type=\"module\" data-ogygia-runtime src=\"" + src + "\"><\/script>";
+	for (const dep of deps) html += "<link rel=\"modulepreload\" href=\"" + dep + "\" data-ogygia-runtime-dep>";
+	return html;
+}
+/**
+* The island graph (island-graph.ts) as one inert JSON script: entry → the chunks its code needs.
+* The runtime turns an entry's list into modulepreload links when that island wakes. Empty map →
+* no script.
+*/
+function island_graph_script(graph, locations) {
+	if (graph.size === 0 && !locations?.size) return "";
+	return "<script type=\"application/json\" " + ISLAND_GRAPH_ATTR + ">" + escape_script_text(encode_island_graph(graph, locations ?? void 0)) + "<\/script>";
+}
+/** The holes record (`hole()`), read by runtime/hole-facts.ts. */
+const HOLES_SCRIPT_OPEN = `<script type="${HOLES_SCRIPT_TYPE}" data-ogygia-holes>`;
+const HOLES_SCRIPT_CLOSE = "<\/script>";
+var DocumentTail = class {
+	#hints = /* @__PURE__ */ new Set();
+	#graph = /* @__PURE__ */ new Map();
+	/** entry identity → location, for entries no element carries (a portable snippet's live entry) */
+	#locations = /* @__PURE__ */ new Map();
+	#props = /* @__PURE__ */ new Map();
+	#holes = /* @__PURE__ */ new Map();
+	#hole_notes = /* @__PURE__ */ new Map();
+	/** per-fingerprint facts of the last `render()` (the profiler's Islands table) */
+	#island_rows = null;
+	/** Add a region's module-preload hrefs; each href is hinted once (first wins). With `fp`, the
+	*  hrefs are also remembered as that island's JS closure. */
+	hints(hrefs, fp) {
+		for (const href of hrefs) this.#hints.add(href);
+		if (fp) {
+			const s = this.#props.get(fp);
+			if (s && s.hints.length === 0) s.hints = [...hrefs];
+		}
+	}
+	/** The list already recorded for an entry, if any — a second instance of an island reuses it. */
+	graph_of(entry) {
+		return this.#graph.get(entry);
+	}
+	/** Record the chunks an island entry's code needs (the island graph — data, not hints: the
+	*  runtime preloads them when the island wakes). One list per entry — its identity — (first wins).
+	*  With `fp`, the list is also remembered as that island's JS closure for the profiler, led by the
+	*  file the island actually loads: `src`, its location (the identity when it has none). */
+	graph(entry, hrefs, fp, src) {
+		if (!this.#graph.has(entry)) this.#graph.set(entry, hrefs);
+		if (fp) {
+			const s = this.#props.get(fp);
+			if (s && s.hints.length === 0) s.hints = [src || entry, ...hrefs];
+		}
+	}
+	/** Record where an entry no element carries is served from (the graph script's `s`). */
+	locate(identity, src) {
+		if (!this.#locations.has(identity)) this.#locations.set(identity, src);
+	}
+	/** Register an island's props sidecar under its fingerprint; identical islands share one (the
+	*  count still says how many). `meta` is what the profiler's Islands table shows. */
+	props(fp, wire, meta = null) {
+		const have = this.#props.get(fp);
+		if (have) have.count++;
+		else this.#props.set(fp, {
+			wire,
+			meta,
+			count: 1,
+			hints: []
+		});
+	}
+	/** Note a deferred hole the page rendered (every document, not only Kit-hydrated ones): its
+	*  schedule and cache policy, for the profiler's hole economics. */
+	note_hole(id, when, hydrate, ttl, name = "", props = void 0, copy = "") {
+		const key = `${id}\0${when}\0${hydrate ?? ""}\0${ttl}`;
+		let have = this.#hole_notes.get(key);
+		if (have) have.count++;
+		else this.#hole_notes.set(key, have = {
+			id,
+			name,
+			props: props_preview(props),
+			when,
+			hydrate,
+			ttl,
+			count: 1
+		});
+		if (copy && (have.copies?.length ?? 0) < 12 && !have.copies?.some((c) => c.p === copy)) (have.copies ??= []).push({
+			p: copy,
+			props: have.count === 1 ? have.props : props_preview(props)
+		});
+	}
+	/** The holes noted on this page. */
+	hole_rows() {
+		return [...this.#hole_notes.values()];
+	}
+	/** The per-island facts of the last `render()` — `null` before it ran. */
+	island_rows() {
+		return this.#island_rows;
+	}
+	/**
+	* Record a deferred hole's server-minted facts under its identity (`data-og-hole`), for a
+	* KIT-HYDRATED document only. Kit can give up hydrating such a document (a component threw, the
+	* markup mismatched): Svelte clears Kit's root and mounts it fresh, and every hole is rendered
+	* again by the client leg — with no address, since only the server can mint one. The tail sits
+	* OUTSIDE Kit's root, so this record survives that rebuild, and the runtime hands each rebuilt
+	* hole its address (and a hydrating hole its props sidecar) back by identity — never by
+	* position. Identical holes (same id + props → same identity) share one record.
+	*/
+	hole(identity, endpoint, sidecar) {
+		if (identity && endpoint && !this.#holes.has(identity)) this.#holes.set(identity, {
+			endpoint,
+			sidecar
+		});
+	}
+	get empty() {
+		return this.#hints.size === 0 && this.#graph.size === 0 && this.#locations.size === 0 && this.#props.size === 0 && this.#holes.size === 0;
+	}
+	/** Hint count + graph entry count + sidecar count + hole-record count, for tests and devtools. */
+	get size() {
+		return {
+			hints: this.#hints.size,
+			graph: this.#graph.size,
+			props: this.#props.size,
+			holes: this.#holes.size
+		};
+	}
+	/** The tail's HTML: hints, the island graph, then props (each rendered now, against `seed`), then
+	*  the holes record (one script, JSON, `<`-escaped). Empty string when nothing was recorded. With
+	*  `detail`, the per-island rows (bytes, lane, references, the devalue culprit) are kept for
+	*  the profiler — a little extra work, only while it records. */
+	render(seed = null, detail = false) {
+		let out = "";
+		for (const href of this.#hints) out += modulepreload_tag(href);
+		out += island_graph_script(this.#graph, this.#locations);
+		const rows = detail ? [] : null;
+		for (const [fp, s] of this.#props) {
+			const w = s.wire.wire(seed);
+			out += props_sidecar(fp, w, "tail", s.wire.wire_modules);
+			if (rows) rows.push({
+				fp,
+				entry: s.meta?.entry ?? "",
+				name: s.meta?.name ?? "",
+				module_url: s.meta?.module_url ?? "",
+				wake: s.meta?.wake ?? "",
+				props_bytes: w.text.length,
+				canonical_bytes: s.wire.canonical?.length ?? w.text.length,
+				...s.wire.canonical !== void 0 && s.wire.canonical.length <= 4096 ? { canonical: s.wire.canonical } : {},
+				json: w.json,
+				culprit: w.json ? null : s.wire.culprit?.() ?? null,
+				refs: s.wire.refs?.count ?? 0,
+				ref_keys: [...s.wire.refs?.keys ?? []],
+				hints: s.hints,
+				interactivity: s.meta?.interactivity ?? null,
+				count: s.count
+			});
+		}
+		this.#island_rows = rows;
+		if (this.#holes.size) {
+			const record = {};
+			for (const [identity, facts] of this.#holes) record[identity] = facts;
+			out += HOLES_SCRIPT_OPEN + escape_script_text(JSON.stringify(record)) + HOLES_SCRIPT_CLOSE;
+		}
+		return out;
+	}
+};
+let reader = null;
+/** Server (`hooks.ts`) installs a request-scoped reader; `null` uninstalls. */
+function set_tail_reader(fn) {
+	reader = fn;
+}
+/** The current request's tail, or `null` when this render has none (client, endpoint, test). */
+function document_tail() {
+	return reader ? reader() : null;
+}
+export { DocumentTail, document_tail, island_graph_script, modulepreload_tag, props_preview, runtime_bootstrap_tags, set_tail_reader };

package/dist/server/endpoint.d.ts

@@ -0,0 +1,51 @@
+export declare const DEFAULT_ISLANDS_ENDPOINT = "/__ogygia__";
+/** The islands endpoint path (without the app's base: matched by suffix, minted through `resolve`). */
+export declare function islands_endpoint(): string;
+/** Set by the handle (`handle({ endpoint })`); the default when none is given. */
+export declare function configure_islands_endpoint(path: string | undefined): void;
+/** Max b64url props blob accepted by the region handle (and refused at mint time). */
+export declare const MAX_REGION_PROPS_LEN = 8192;
+/**
+ * Default capability TTL (seconds) for DYNAMIC pages. Shorter than a day so harvested URLs age
+ * out; override via `ogygia({ ttl })`.
+ */
+export declare const DEFAULT_REGION_TTL_SEC = 3600;
+/**
+ * Capability TTL for PRERENDERED pages (10 years — effectively the life of the deploy). A static
+ * file lives on the CDN indefinitely, so an aging capability would strand every hole on it after
+ * `ttl` (real PPR would silently die in an hour). Safe: the capability's props are already
+ * baked into the public static HTML, and the mint seals an EMPTY session at prerender — signing
+ * that same public tuple for longer reveals nothing new. Redeploy survival additionally needs a
+ * stable `OGYGIA_SECRET` (the default per-build key rotates; ServerIsland warns at build).
+ */
+export declare const PRERENDER_REGION_TTL_SEC: number;
+/**
+ * WHEN a capability minted now expires — aligned to a window, not `now + ttl`.
+ *
+ * Every render of the same hole (same id, props, session) in the same window mints the SAME
+ * `exp`, hence the SAME signature and URL: the hole's HTML is byte-identical across requests. That
+ * is what lets anything keyed on the page's bytes hit — a host app's post-render component cache,
+ * a CDN or postrender store comparing documents, an ETag. With `now + ttl` every request minted a new
+ * URL and a header block wrapping five holes was re-processed on every request (measured: seconds
+ * of server time per page on a Lambda-class host).
+ *
+ * The window is half the TTL: `exp` is the end of the window after the current one, so a
+ * capability is always valid for at least `ttl / 2` and at most `ttl` (harvested URLs still age
+ * out on the same order); consecutive windows overlap by construction, so a page rendered at the
+ * end of a window and fetched a moment later still verifies.
+ */
+export declare function capability_expiry(now_sec: number, ttl_sec: number): number;
+/** Region ids are always 12 lowercase hex chars from the transform. */
+export declare const REGION_ID_RE: RegExp;
+/**
+ * A hole's optional cache `ttl` (max-age seconds) as it rides in the endpoint URL: empty (no-store,
+ * the default) or 1–7 digits (up to ~115 days). Charset-gated before HMAC so a forged value can't
+ * reach the response header, though the MAC is the real guard.
+ */
+export declare const REGION_TTL_RE: RegExp;
+/** {@link REGION_ID_RE}: exactly 12 lowercase hex chars. */
+export declare function is_region_id(s: string): boolean;
+/** {@link REGION_TTL_RE}: empty, or 1–7 ASCII digits. */
+export declare function is_region_ttl(s: string): boolean;
+/** Exactly `n` chars of `[0-9a-f]`. */
+export declare function is_lower_hex(s: string, n: number): boolean;

package/dist/server/endpoint.js

@@ -0,0 +1,90 @@
+// src/server/endpoint.ts
+const DEFAULT_ISLANDS_ENDPOINT = "/__ogygia__";
+/**
+* THE ISLANDS ENDPOINT — one path for everything that names it: the handle answers on it, every
+* capability is minted against it, a render knows it is serving a hole by it, the profiler counts
+* its requests by it. `handle({ endpoint })` sets it as the app's hooks load, before any render
+* (Kit loads the server hooks before it renders anything, prerender included). It used to move only
+* the handler: pages still minted `/__ogygia__?…`, and behind a proxy that forwards only the app's
+* own prefixes every hole was empty.
+*
+* Process-wide on `globalThis`, not module state: this file can load under two module ids in one
+* server (the plugin points the mint at the package's built file while an app's hooks import it from
+* a linked package's source), and a module variable set by the handle was then never read by the mint.
+*/
+const ENDPOINT_KEY = Symbol.for("ogygia.islands-endpoint");
+const endpoint_slot = globalThis;
+/** The islands endpoint path (without the app's base: matched by suffix, minted through `resolve`). */
+function islands_endpoint() {
+	return endpoint_slot[ENDPOINT_KEY] ?? "/__ogygia__";
+}
+/** Set by the handle (`handle({ endpoint })`); the default when none is given. */
+function configure_islands_endpoint(path) {
+	endpoint_slot[ENDPOINT_KEY] = !path ? DEFAULT_ISLANDS_ENDPOINT : path.startsWith("/") ? path : "/" + path;
+}
+/** Max b64url props blob accepted by the region handle (and refused at mint time). */
+const MAX_REGION_PROPS_LEN = 8192;
+/**
+* Default capability TTL (seconds) for DYNAMIC pages. Shorter than a day so harvested URLs age
+* out; override via `ogygia({ ttl })`.
+*/
+const DEFAULT_REGION_TTL_SEC = 3600;
+/**
+* Capability TTL for PRERENDERED pages (10 years — effectively the life of the deploy). A static
+* file lives on the CDN indefinitely, so an aging capability would strand every hole on it after
+* `ttl` (real PPR would silently die in an hour). Safe: the capability's props are already
+* baked into the public static HTML, and the mint seals an EMPTY session at prerender — signing
+* that same public tuple for longer reveals nothing new. Redeploy survival additionally needs a
+* stable `OGYGIA_SECRET` (the default per-build key rotates; ServerIsland warns at build).
+*/
+const PRERENDER_REGION_TTL_SEC = 31536e4;
+/**
+* WHEN a capability minted now expires — aligned to a window, not `now + ttl`.
+*
+* Every render of the same hole (same id, props, session) in the same window mints the SAME
+* `exp`, hence the SAME signature and URL: the hole's HTML is byte-identical across requests. That
+* is what lets anything keyed on the page's bytes hit — a host app's post-render component cache,
+* a CDN or postrender store comparing documents, an ETag. With `now + ttl` every request minted a new
+* URL and a header block wrapping five holes was re-processed on every request (measured: seconds
+* of server time per page on a Lambda-class host).
+*
+* The window is half the TTL: `exp` is the end of the window after the current one, so a
+* capability is always valid for at least `ttl / 2` and at most `ttl` (harvested URLs still age
+* out on the same order); consecutive windows overlap by construction, so a page rendered at the
+* end of a window and fetched a moment later still verifies.
+*/
+function capability_expiry(now_sec, ttl_sec) {
+	const half = Math.max(1, Math.floor(ttl_sec / 2));
+	return (Math.floor(now_sec / half) + 2) * half;
+}
+/** Region ids are always 12 lowercase hex chars from the transform. */
+const REGION_ID_RE = /^[0-9a-f]{12}$/;
+/**
+* A hole's optional cache `ttl` (max-age seconds) as it rides in the endpoint URL: empty (no-store,
+* the default) or 1–7 digits (up to ~115 days). Charset-gated before HMAC so a forged value can't
+* reach the response header, though the MAC is the real guard.
+*/
+const REGION_TTL_RE = /^(|[0-9]{1,7})$/;
+/** {@link REGION_ID_RE}: exactly 12 lowercase hex chars. */
+function is_region_id(s) {
+	return is_lower_hex(s, 12);
+}
+/** {@link REGION_TTL_RE}: empty, or 1–7 ASCII digits. */
+function is_region_ttl(s) {
+	if (s.length > 7) return false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s.charCodeAt(i);
+		if (c < 48 || c > 57) return false;
+	}
+	return true;
+}
+/** Exactly `n` chars of `[0-9a-f]`. */
+function is_lower_hex(s, n) {
+	if (s.length !== n) return false;
+	for (let i = 0; i < n; i++) {
+		const c = s.charCodeAt(i);
+		if (!(c >= 48 && c <= 57 || c >= 97 && c <= 102)) return false;
+	}
+	return true;
+}
+export { DEFAULT_ISLANDS_ENDPOINT, DEFAULT_REGION_TTL_SEC, MAX_REGION_PROPS_LEN, PRERENDER_REGION_TTL_SEC, REGION_ID_RE, REGION_TTL_RE, capability_expiry, configure_islands_endpoint, is_lower_hex, is_region_id, is_region_ttl, islands_endpoint };

package/dist/server/entry-location.d.ts

@@ -0,0 +1,8 @@
+/** The file an entry is loaded from: its content-hashed location, else the identity itself. */
+export declare function entry_src(identity: string): string;
+/**
+ * The runtime bootstrap for a document: the runtime's script (its location) and a preload per chunk
+ * it statically imports, so they download with it. `resolve` applies the base / assets prefix (Kit's
+ * `asset()`); a routeless document passes none. Empty when no runtime is built.
+ */
+export declare function runtime_bootstrap(resolve?: (url: string) => string): string;

package/dist/server/entry-location.js

@@ -0,0 +1,29 @@
+import { runtime_bootstrap_tags } from "./document-tail.js";
+import runtime_url from "virtual:ogygia/runtime-url";
+import { entryLocation, islandDeps } from "virtual:ogygia/island-deps";
+// src/server/entry-location.ts
+/**
+* ENTRY IDENTITY → LOCATION, on the server. A hydrate island's entry and the runtime each have an
+* IDENTITY — the stable URL the compiler bakes (`/<appDir>/immutable/og-region.<iid>.js`, the
+* runtime's stable name) and every map keys by — and a LOCATION: the content-hashed file the build
+* emitted, the one a browser loads. A stable name served `immutable` would be kept for a year after
+* its content changed; a hashed name cannot go stale. The server bundle is built before the client
+* bundle, so the location is looked up at render time through the build handoff (`entryLocation`).
+*
+* No location (the dev server, a handoff from before hashing, an island from another app): the
+* identity itself is served — in a build, the stable-name shim that re-exports the current file.
+*/
+/** The file an entry is loaded from: its content-hashed location, else the identity itself. */
+function entry_src(identity) {
+	return identity && entryLocation(identity) || identity;
+}
+/**
+* The runtime bootstrap for a document: the runtime's script (its location) and a preload per chunk
+* it statically imports, so they download with it. `resolve` applies the base / assets prefix (Kit's
+* `asset()`); a routeless document passes none. Empty when no runtime is built.
+*/
+function runtime_bootstrap(resolve = (url) => url) {
+	if (!runtime_url) return "";
+	return runtime_bootstrap_tags(resolve(entry_src(runtime_url)), islandDeps(runtime_url).map(resolve));
+}
+export { entry_src, runtime_bootstrap };

package/dist/server/fingerprint.d.ts

@@ -0,0 +1 @@
+export declare function island_fingerprint(entry: string, canonical: string): string;

package/dist/server/fingerprint.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+// src/server/fingerprint.ts
+/**
+* ISLAND FINGERPRINT (`data-og-fp`) — the server's identity for one island instance: its module
+* URL + the canonical text of its props (server/props-wire.ts), 64 bits as 16 hex chars.
+*
+* What reads it: the runtime's sidecar lookup (`id="og-props-<fp>"`), the hydration self-heal
+* copy, the reconciler's data-key on a client navigation, and the server-delta skip (the client
+* sends the fingerprints it holds back in `x-ogygia-known`). Every one of them READS the emitted
+* attribute — the client never recomputes an island's fingerprint (runtime/reconcile.ts computes
+* one only for a region that carries none) — so the server is free to hash however is cheapest
+* here, as long as two servers agree on the same input: SHA-1 through Node's native digest,
+* ~4× the speed of the pure-JS lane hash on a 130 KB props text, and identical on every instance
+* behind a load balancer.
+*
+* NOT for a hole's identity (`data-og-hole`): the client leg of a Kit-hydrated document recomputes
+* that one, so it stays on the universal `fingerprint_of` (runtime/hash.ts) on both legs.
+*
+* Server-only (`node:crypto`), reached from Region.svelte through the client-stubbed
+* `virtual:ogygia/region-endpoint` — Region computes a fingerprint only on the server.
+*/
+function island_fingerprint(entry, canonical) {
+	return createHash("sha1").update(entry).update(" ").update(canonical).digest("hex").slice(0, 16);
+}
+export { island_fingerprint };

package/dist/server/head-presence.d.ts

@@ -0,0 +1,45 @@
+export declare function page_declares_router_meta(html: string): boolean;
+export declare function page_declares_runtime_script(html: string): boolean;
+export declare function page_declares_dev_hmr_script(html: string): boolean;
+export declare function page_declares_speculation_rules(html: string): boolean;
+/**
+ * Drop duplicate `<link>` tags in the HEAD — one pass over the head slice, two families:
+ *
+ *  - `rel="stylesheet"`: same href → first occurrence wins. Kit links a route's client-graph CSS
+ *    and Region.svelte links a rendered island's CSS from the render pass; a layout island compiled
+ *    as a real wrapper (a csr=true-capable layout host) is in both, so its sheet was linked twice —
+ *    two render-blocking fetches of one asset. `<style>` tags are untouched.
+ *  - `rel="modulepreload"`: same href → first occurrence wins. Each island's SSR emits its own
+ *    dep-hint block, so islands sharing dep chunks — or one island rendered N times — repeat
+ *    identical hints (a real page carried ~44 duplicate tags). Every hint ogygia emits is
+ *    `fetchpriority="low"` (Region.svelte), so there is no priority to arbitrate between copies.
+ *
+ * Every other `<link>` passes through byte-identical. The handle calls this on the HEAD SLICE of
+ * the document only (everything before `</head>`, tens of KB): the hints and the sheets live there,
+ * so the 2.6 MB body is never scanned for them.
+ */
+export declare function dedupe_head_links(head: string): string;
+/**
+ * Put the runtime bootstrap BEFORE ALL OF THE PAGE'S JAVASCRIPT in `<head>` — immediately ahead of
+ * the first `<script>` or `<link rel="modulepreload">` the app's template and the page carry, and
+ * no earlier. `runtime` is the tag to place when the head has none yet (`null` = only reorder what
+ * is there; the tag an island page emits sits wherever Kit's head slot is, after the app's own
+ * scripts in `app.html`). With no JavaScript in the head it goes last in it. Returns `head` itself
+ * when there is nothing to move.
+ *
+ * Why BEFORE THE JS: module and deferred scripts run in document order once parsing ends, and the
+ * runtime's custom-element definition is what makes every `<ogygia-region>` connect and keep its
+ * server markup — the copy an island hydrates against when something edited it while it slept
+ * (runtime/core.ts `#ssr_html`). A design-system runtime loaded from the app template ran BEFORE the
+ * runtime on a customer page and stripped the whitespace nodes of every island in the header before
+ * the runtime ever saw them, so the "server copy" was the edited DOM and the login island still
+ * re-rendered client-side on its first tap. Ahead of every script, the runtime sees the document as
+ * the server sent it, whatever the app loads after it.
+ *
+ * Why NOT FIRST IN THE HEAD: that ordering guarantee is about execution, and only needs "before the
+ * other scripts". Heading the whole `<head>` also made the runtime the page's FIRST REQUEST, ahead of
+ * its stylesheets and its LCP image preload. Everything that is not JavaScript — the charset and
+ * other `<meta>`, the `<title>`, stylesheets, preconnects, image/font preloads — keeps its place in
+ * front of it.
+ */
+export declare function runtime_first(head: string, runtime: string | null): string;