@ogygia/core 0.11.5 → 0.12.0

package/dist/compiler/link/island-deps.js

@@ -1,4 +1,5 @@
 import { path } from "../host.js";
+import { dedent } from "../dedent.js";
 import { merge_page_keys } from "./page-keys.js";
 import { hydration_hazards } from "../../insights/hydration-hazards.js";
 import { OWN_FILE_RE, OWN_PACKAGE_NAMES } from "../../own-package.js";
@@ -499,27 +500,229 @@ function collect_inline_css(bundle, hrefs, threshold) {
 	return out;
 }
 function island_deps_module(ssr, is_dev, out_dir_rel = ".svelte-kit") {
-	if (!ssr) return `export function islandDeps(_entry) { return []; }\nexport function islandCss(_entry) { return []; }\nexport function islandCssInline(_href) { return null; }\nexport function contentCss(_id) { return []; }\nexport function islandReadsPage(_entry) { return false; }\nexport function islandPageKeys(_entry) { return null; }\nexport function islandPageWhy(_entry) { return null; }\nexport function islandRemotes(_entry) { return null; }\nexport function islandInteractivity(_entry) { return null; }\nexport function islandHazards(_entry) { return null; }\nexport function chunkContents(_href) { return null; }\nexport function chunkHeavy(_href) { return null; }\nexport function chunkBarrels(_href) { return null; }\nexport function chunkDuplicates() { return null; }\nexport function fnManifest() { return null; }\nexport function entryLocation(_identity) { return null; }`;
-	if (is_dev) return `export function islandDeps(_entry) { return []; }\nexport function islandCss(entry) { return entry ? [entry] : []; }\nexport function islandCssInline(_href) { return null; }\nexport function contentCss(_id) { return []; }\nexport function islandReadsPage(_entry) { return true; }\nexport function islandPageKeys(_entry) { return null; }\nexport function islandPageWhy(_entry) { return null; }\nexport function islandRemotes(_entry) { return null; }\nexport function islandInteractivity(_entry) { return null; }\nexport function islandHazards(_entry) { return null; }\nexport function chunkContents(_href) { return null; }\nexport function chunkHeavy(_href) { return null; }\nexport function chunkBarrels(_href) { return null; }\nexport function chunkDuplicates() { return null; }\nexport function fnManifest() { return null; }\nexport function entryLocation(_identity) { return null; }`;
-	return `import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-const __OG_INLINE = '__OGYGIA_ISLAND_DEPS_INLINE__';
-let cache = null;
-try { if (__OG_INLINE.charCodeAt(0) === 123) cache = JSON.parse(__OG_INLINE); } catch {}
-function candidates() {
-  const out = [];
-  try {
-    let dir = path.dirname(fileURLToPath(import.meta.url));
-    for (let i = 0; i < 8; i++) {
-      out.push(path.join(dir, 'og-region-deps.json'));
-      const parent = path.dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
-    }
-  } catch {}
-  if (typeof process !== 'undefined' && process.cwd) {
-    const cwd = process.cwd();
-    out.push(path.join(cwd, ${JSON.stringify(out_dir_rel)}, 'og-region-deps.json'));\n    out.push(path.join(cwd, ${JSON.stringify(out_dir_rel)}, 'output', 'server', 'og-region-deps.json'));\n  }\n  return out;\n}\nfunction load() {\n  if (cache) return cache;\n  for (const p of candidates()) {\n    try { cache = JSON.parse(fs.readFileSync(p, 'utf8')); return cache; } catch {}\n  }\n  cache = {};\n  return cache;\n}\n// map (pre-css build) degrades gracefully: js falls back to the root, css to [].\nfunction pick(kind, entry) {\n  const all = load();\n  const map = all && typeof all[kind] === 'object' ? all[kind] : kind === 'js' ? all : null;\n  const list = map ? map[entry] : null;\n  return Array.isArray(list) ? list : [];\n}\nexport function islandDeps(entry) {\n  return entry ? pick('js', entry) : [];\n}\nexport function islandCss(entry) {\n  return entry ? pick('css', entry) : [];\n}\nexport function islandCssInline(href) {\n  const all = load();\n  const map = all && typeof all.css_inline === 'object' && all.css_inline ? all.css_inline : null;\n  if (!map || !href) return null;\n  const v = map[href];\n  return typeof v === 'string' ? v : null;\n}\nexport function contentCss(id) {\n  return id ? pick('content_css', id) : [];\n}\nexport function islandReadsPage(entry) {\n  const all = load();\n  const map = all && typeof all.page === 'object' && all.page ? all.page : null;\n  if (!map || !entry) return true;\n  const v = map[entry];\n  return v === undefined ? true : !!v;\n}\nexport function islandPageKeys(entry) {\n  const all = load();\n  const map = all && typeof all.page_keys === 'object' && all.page_keys ? all.page_keys : null;\n  if (!map || !entry) return null;\n  const v = map[entry];\n  return Array.isArray(v) ? v : null;\n}\nexport function islandPageWhy(entry) {\n  const all = load();\n  const map = all && typeof all.page_why === 'object' && all.page_why ? all.page_why : null;\n  if (!map || !entry) return null;\n  const v = map[entry];\n  return Array.isArray(v) ? v : null;\n}\nexport function islandRemotes(entry) {\n  const all = load();\n  const map = all && typeof all.remotes === 'object' && all.remotes ? all.remotes : null;\n  if (!map || !entry) return null;\n  const v = map[entry];\n  return Array.isArray(v) ? v : null;\n}\nexport function islandInteractivity(entry) {\n  const all = load();\n  const map = all && typeof all.interactivity === 'object' && all.interactivity ? all.interactivity : null;\n  if (!map || !entry) return null;\n  const v = map[entry];\n  return v && typeof v === 'object' ? v : null;\n}\nexport function chunkContents(href) {\n  const all = load();\n  const map = all && typeof all.contents === 'object' && all.contents ? all.contents : null;\n  if (!map || !href) return null;\n  const key = href.startsWith('/') ? href : '/' + href.replace(/^\\.\\//, '');\n  const v = map[key] ?? map[href];\n  return Array.isArray(v) ? v : null;\n}\nexport function chunkHeavy(href) {\n  const all = load();\n  const map = all && typeof all.heavy === 'object' && all.heavy ? all.heavy : null;\n  if (!map || !href) return null;\n  const key = href.startsWith('/') ? href : '/' + href.replace(/^\\.\\//, '');\n  const v = map[key] ?? map[href];\n  return v && typeof v === 'object' && Array.isArray(v.top) ? v : null;\n}\nexport function chunkDuplicates() {\n  const all = load();\n  const v = all && Array.isArray(all.dupes) ? all.dupes : null;\n  return v && v.length ? v : null;\n}\nexport function islandHazards(entry) {\n  const all = load();\n  const map = all && typeof all.hazards === 'object' && all.hazards ? all.hazards : null;\n  if (!map || !entry) return null;\n  const v = map[entry];\n  return Array.isArray(v) ? v : null;\n}\nexport function chunkBarrels(href) {\n  const all = load();\n  const map = all && typeof all.barrels === 'object' && all.barrels ? all.barrels : null;\n  if (!map || !href) return null;\n  const key = href.startsWith('/') ? href : '/' + href.replace(/^\\.\\//, '');\n  const v = map[key] ?? map[href];\n  return Array.isArray(v) ? v : null;\n}\nexport function fnManifest() {\n  const m = load().fn_manifest;\n  return m && typeof m === 'object' && Object.keys(m).length ? m : null;\n}\nexport function entryLocation(identity) {\n  const m = load().entries;\n  const v = m && typeof m === 'object' && identity ? m[identity] : null;\n  return typeof v === 'string' ? v : null;\n}\n`;
+	if (!ssr) return dedent`
+			export function islandDeps(_entry) { return []; }
+			export function islandCss(_entry) { return []; }
+			export function islandCssInline(_href) { return null; }
+			export function contentCss(_id) { return []; }
+			export function islandReadsPage(_entry) { return false; }
+			export function islandPageKeys(_entry) { return null; }
+			export function islandPageWhy(_entry) { return null; }
+			export function islandRemotes(_entry) { return null; }
+			export function islandInteractivity(_entry) { return null; }
+			export function islandHazards(_entry) { return null; }
+			export function chunkContents(_href) { return null; }
+			export function chunkHeavy(_href) { return null; }
+			export function chunkBarrels(_href) { return null; }
+			export function chunkDuplicates() { return null; }
+			export function fnManifest() { return null; }
+			export function entryLocation(_identity) { return null; }
+			export function locationMap() { return null; }
+		`;
+	if (is_dev) return dedent`
+			export function islandDeps(_entry) { return []; }
+			export function islandCss(entry) { return entry ? [entry] : []; }
+			export function islandCssInline(_href) { return null; }
+			export function contentCss(_id) { return []; }
+			export function islandReadsPage(_entry) { return true; }
+			export function islandPageKeys(_entry) { return null; }
+			export function islandPageWhy(_entry) { return null; }
+			export function islandRemotes(_entry) { return null; }
+			export function islandInteractivity(_entry) { return null; }
+			export function islandHazards(_entry) { return null; }
+			export function chunkContents(_href) { return null; }
+			export function chunkHeavy(_href) { return null; }
+			export function chunkBarrels(_href) { return null; }
+			export function chunkDuplicates() { return null; }
+			export function fnManifest() { return null; }
+			export function entryLocation(identity) { return identity || null; }
+			export function locationMap() { return null; }
+		`;
+	const out_dir = JSON.stringify(out_dir_rel);
+	return dedent`
+		import fs from 'node:fs';
+		import path from 'node:path';
+		import { fileURLToPath } from 'node:url';
+
+		// PRIMARY source: a string slot the client build patches in place with the manifest JSON (see
+		// writeBundle). Inlined into the server bundle, it survives serverless tracing: Vercel/Netlify
+		// (@vercel/nft) bundle only imported files, not runtime fs reads, so the co-located JSON below
+		// is dropped there. The fs walk stays the fallback for adapter-node and dev-preview (the whole
+		// server dir ships). Unpatched, the token starts with '_' (char 95), the guard is false, and
+		// the walk runs. A bad patch degrades to the walk, never crashes the server at import.
+		const __OG_INLINE = '__OGYGIA_ISLAND_DEPS_INLINE__';
+		let cache = null;
+		try { if (__OG_INLINE.charCodeAt(0) === 123) cache = JSON.parse(__OG_INLINE); } catch {}
+
+		function candidates() {
+			const out = [];
+			try {
+				let dir = path.dirname(fileURLToPath(import.meta.url));
+				for (let i = 0; i < 8; i++) {
+					out.push(path.join(dir, 'og-region-deps.json'));
+					const parent = path.dirname(dir);
+					if (parent === dir) break;
+					dir = parent;
+				}
+			} catch {}
+			if (typeof process !== 'undefined' && process.cwd) {
+				const cwd = process.cwd();
+				out.push(path.join(cwd, ${out_dir}, 'og-region-deps.json'));
+				out.push(path.join(cwd, ${out_dir}, 'output', 'server', 'og-region-deps.json'));
+			}
+			return out;
+		}
+
+		function load() {
+			if (cache) return cache;
+			for (const p of candidates()) {
+				try { cache = JSON.parse(fs.readFileSync(p, 'utf8')); return cache; } catch {}
+			}
+			cache = {};
+			return cache;
+		}
+
+		// Handoff shape: { js: { entryUrl: [...] }, css: { entryUrl: [...] } }. A stale flat
+		// map (pre-css build) degrades gracefully: js falls back to the root, css to [].
+		function pick(kind, entry) {
+			const all = load();
+			const map = all && typeof all[kind] === 'object' ? all[kind] : kind === 'js' ? all : null;
+			const list = map ? map[entry] : null;
+			return Array.isArray(list) ? list : [];
+		}
+
+		/** One entry of a handoff map (\`field\`), or null: no map, no key, or the wrong shape. */
+		function lookup(field, key, ok) {
+			const all = load();
+			const map = all && typeof all[field] === 'object' && all[field] ? all[field] : null;
+			if (!map || !key) return null;
+			const v = map[key];
+			return ok(v) ? v : null;
+		}
+
+		/** A chunk href's key: root-absolute, as the build wrote it. */
+		function chunk_key(href) {
+			return href.startsWith('/') ? href : '/' + href.replace(/^\\.\\//, '');
+		}
+
+		export function islandDeps(entry) {
+			return entry ? pick('js', entry) : [];
+		}
+
+		export function islandCss(entry) {
+			return entry ? pick('css', entry) : [];
+		}
+
+		// INLINE REGION CSS: the text of a region CSS asset the build kept under Kit's
+		// inlineStyleThreshold (collect_inline_css), keyed by the same public href islandCss hands
+		// out. null = link it (over the threshold, no threshold, or a pre-inline handoff).
+		export function islandCssInline(href) {
+			return lookup('css_inline', href, (v) => typeof v === 'string');
+		}
+
+		export function contentCss(id) {
+			return id ? pick('content_css', id) : [];
+		}
+
+		// Does this island's client closure read $page? FAIL-OPEN: no map (a pre-page handoff), or an
+		// entry the build never saw (a foreign fragment's island mounted from another app) → true, so
+		// the seed ships and nothing that might read it finds it missing.
+		export function islandReadsPage(entry) {
+			const all = load();
+			const map = all && typeof all.page === 'object' && all.page ? all.page : null;
+			if (!map || !entry) return true;
+			const v = map[entry];
+			return v === undefined ? true : !!v;
+		}
+
+		// SEED SHAPING: which top-level page.data keys this island's closure reads. FAIL-OPEN as null
+		// ("ship all"): no map (a pre-shaping handoff), an entry the build never saw, or a closure
+		// whose reads could not be pinned to literal keys.
+		export function islandPageKeys(entry) {
+			return lookup('page_keys', entry, Array.isArray);
+		}
+
+		// Why this island ships all of page.data: the modules in its closure whose reads the build
+		// could not pin (file, line, why). Profiler builds only; null = none recorded.
+		export function islandPageWhy(entry) {
+			return lookup('page_why', entry, Array.isArray);
+		}
+
+		// Which remotes (Kit id-hashes) this island's client closure can call: REMOTE SEED ONLY WHEN
+		// REACHABLE. FAIL-OPEN as null ("may call anything"): no map (a pre-remotes handoff), or an
+		// entry the build never saw (a foreign fragment's island) → every SSR-resolved remote seeds.
+		export function islandRemotes(entry) {
+			return lookup('remotes', entry, Array.isArray);
+		}
+
+		// WAKE ADVISOR facts per entry (handlers / $state / bind: counts over the island's own
+		// components), for the profiler's Islands table. null = the handoff has none.
+		export function islandInteractivity(entry) {
+			return lookup('interactivity', entry, (v) => !!v && typeof v === 'object');
+		}
+
+		// each island's lines that draw differently in the browser (the profiler's mismatch findings)
+		export function islandHazards(entry) {
+			return lookup('hazards', entry, Array.isArray);
+		}
+
+		// WHAT IS INSIDE a chunk (readable source list): the profiler names hashed chunks with it
+		export function chunkContents(href) {
+			const all = load();
+			const map = all && typeof all.contents === 'object' && all.contents ? all.contents : null;
+			if (!map || !href) return null;
+			const v = map[chunk_key(href)] ?? map[href];
+			return Array.isArray(v) ? v : null;
+		}
+
+		// …and its heaviest modules with their rendered bytes (the report's heavy-module finding)
+		export function chunkHeavy(href) {
+			const all = load();
+			const map = all && typeof all.heavy === 'object' && all.heavy ? all.heavy : null;
+			if (!map || !href) return null;
+			const v = map[chunk_key(href)] ?? map[href];
+			return v && typeof v === 'object' && Array.isArray(v.top) ? v : null;
+		}
+
+		// …and the re-export barrels it still holds (the report's island-barrel note)
+		export function chunkBarrels(href) {
+			const all = load();
+			const map = all && typeof all.barrels === 'object' && all.barrels ? all.barrels : null;
+			if (!map || !href) return null;
+			const v = map[chunk_key(href)] ?? map[href];
+			return Array.isArray(v) ? v : null;
+		}
+
+		// the modules the build shipped twice, each copy's chunk (the report's duplicate-module finding)
+		export function chunkDuplicates() {
+			const all = load();
+			const v = all && Array.isArray(all.dupes) ? all.dupes : null;
+			return v && v.length ? v : null;
+		}
+
+		// og.$ factories for the page-inline registration script (CSP-clean prod path): written by
+		// the CLIENT build's writeBundle, read here at SSR render time, the same ordering-safe channel
+		// islandCss uses.
+		export function fnManifest() {
+			const m = load().fn_manifest;
+			return m && typeof m === 'object' && Object.keys(m).length ? m : null;
+		}
+
+		// IDENTITY → LOCATION: the content-hashed file an entry (an island's stable URL, the runtime's)
+		// is served from. null = no location known (a handoff from before hashing, a foreign island):
+		// the identity itself is written, and the browser finds it in the build's location maps.
+		export function entryLocation(identity) {
+			const m = load().entries;
+			const v = m && typeof m === 'object' && identity ? m[identity] : null;
+			return typeof v === 'string' ? v : null;
+		}
+
+		// The build's content-hashed location map (link/location-map.ts), the file the browser reads:
+		// its served path, base-less (asset() adds it), or null (no island, a handoff from before it).
+		export function locationMap() {
+			const v = load().locations;
+			return typeof v === 'string' ? v : null;
+		}
+	`;
 }
 export { chunk_module_bytes, collectIslandDepModulepreloads, collect_inline_css, duplicate_modules, interactivity_facts, islandDepsHandoffPath, island_deps_module, kit_remote_hash, module_key, module_origin, remote_hash_of, summarize_chunk_contents };

package/dist/compiler/link/location-map.d.ts

@@ -0,0 +1,10 @@
+/** The fixed-name map's file, in the app dir (beside Kit's `version.json`). */
+export declare const CURRENT_LOCATIONS_FILE = "ogygia.json";
+/**
+ * Both maps, as output files: the content-hashed one first. `pairs`: identity file → hashed file,
+ * output-relative. Empty when there is nothing to map.
+ */
+export declare function location_map_files(app_dir: string, pairs: Iterable<readonly [string, string]>, hash: (source: string) => string): {
+  fileName: string;
+  source: string;
+}[];

package/dist/compiler/link/location-map.js

@@ -0,0 +1,53 @@
+import { path } from "../host.js";
+// src/compiler/link/location-map.ts
+/**
+* THE LOCATION MAPS. Island entries are content-hashed files under `immutable/`; an island's IDENTITY
+* (`<appDir>/ogygia/og-region.<iid>.js`, the name every key uses) is a name, not a file. The build
+* writes its identity → location pairs twice, as the same map:
+*
+*  - `<appDir>/immutable/og-locations.<hash>.json`, named by its content. The runtime's script names
+*    it (`data-og-locations`), and a load that arrives with an identity alone (a region the browser
+*    rendered, a held region from the wire, a portable snippet) reads it: this build's locations, for
+*    this build's page.
+*  - `<appDir>/ogygia.json`, the ONE file at a fixed name: the current build's, beside Kit's own
+*    `<appDir>/version.json` and found from an identity alone (its app dir is the identity's, so any
+*    app's is found). A page that outlived its build reads it when its own files are gone, and wakes
+*    on the current code. Outside `immutable/`: a host revalidates it, as it does Kit's.
+*
+* Every other file the build writes is named by its content and lives in `immutable/`, so a host's
+* year-long rule fits all of them; no directory of ogygia's own is written (`ogygia/` in an identity
+* is a name). Both sides of each pair are written relative to the file holding them: the browser
+* resolves them against wherever the build is served (a base, an assets CDN), and an identity that
+* resolves elsewhere (another app's) never matches.
+*/
+/** The fixed-name map's file, in the app dir (beside Kit's `version.json`). */
+const CURRENT_LOCATIONS_FILE = "ogygia.json";
+/** A path from `from_file`'s directory to `to_file` (both output-relative), always dot-led. */
+function relative_specifier(from_file, to_file) {
+	const rel = path.posix.relative(path.posix.dirname(from_file), to_file);
+	return rel.startsWith(".") ? rel : "./" + rel;
+}
+function map_source(file, pairs) {
+	const map = {};
+	for (const [identity, location] of pairs) map[relative_specifier(file, identity)] = relative_specifier(file, location);
+	return JSON.stringify(map);
+}
+/**
+* Both maps, as output files: the content-hashed one first. `pairs`: identity file → hashed file,
+* output-relative. Empty when there is nothing to map.
+*/
+function location_map_files(app_dir, pairs, hash) {
+	const list = [...pairs];
+	if (!list.length) return [];
+	const hashed_dir = `${app_dir}/immutable`;
+	const hashed_source = map_source(hashed_dir + "/og-locations.json", list);
+	const current = `${app_dir}/${CURRENT_LOCATIONS_FILE}`;
+	return [{
+		fileName: `${hashed_dir}/og-locations.${hash(hashed_source)}.json`,
+		source: hashed_source
+	}, {
+		fileName: current,
+		source: map_source(current, list)
+	}];
+}
+export { CURRENT_LOCATIONS_FILE, location_map_files };

package/dist/compiler/link/manifest.js

@@ -1,9 +1,13 @@
+import { dedent } from "../dedent.js";
 // src/compiler/link/manifest.ts
 /**
 * `virtual:ogygia/manifest` emitter — a legacy stub. Hydrate modules are loaded via
 * `<ogygia-region entry>` URLs, not this map; only the `dev` flag is still read.
 */
 function manifest_module(is_dev) {
-	return `export const dev = ${is_dev ? "true" : "false"};\nexport const regions = {};`;
+	return dedent`
+		export const dev = ${is_dev ? "true" : "false"};
+		export const regions = {};
+	`;
 }
 export { manifest_module };

package/dist/compiler/link/server-manifest.js

@@ -1,4 +1,5 @@
 import { V_SERVER_ISLANDS } from "../ids.js";
+import { dedent } from "../dedent.js";
 // src/compiler/link/server-manifest.ts
 /** The SERVER-island ids the manifest carries right now (deferred / server-picked regions). */
 function server_island_ids(program) {
@@ -7,7 +8,14 @@ function server_island_ids(program) {
 	return ids;
 }
 function server_manifest_module(ssr, program, is_dev, devUrlFor, publicUrlFor) {
-	if (!ssr) return `export const load_islands = () => Promise.resolve({ islands: {} });\nexport const island_url = {};\nexport const island_name = {};\nexport const island_render = {};\nexport const render_island = {};\nexport const island_reads_page_data = null;`;
+	if (!ssr) return dedent`
+			export const load_islands = () => Promise.resolve({ islands: {} });
+			export const island_url = {};
+			export const island_name = {};
+			export const island_render = {};
+			export const render_island = {};
+			export const island_reads_page_data = null;
+		`;
 	const urls = [];
 	const names = [];
 	const renders = [];
@@ -17,25 +25,53 @@ function server_manifest_module(ssr, program, is_dev, devUrlFor, publicUrlFor) {
 		const reg = program.registry.get(virtualPath);
 		if (!reg?.server) continue;
 		if (reg.renderId) {
-			renders.push(`  ${JSON.stringify(iid)}: ${JSON.stringify(reg.renderId)}`);
+			renders.push(`${JSON.stringify(iid)}: ${JSON.stringify(reg.renderId)}`);
 			const seen = by_render.get(reg.renderId);
 			if (seen === void 0 || iid < seen) by_render.set(reg.renderId, iid);
 		}
 		const file = reg.componentPath ?? "";
 		const base = file.slice(file.lastIndexOf("/") + 1);
-		if (base.endsWith(".svelte")) names.push(`  ${JSON.stringify(iid)}: ${JSON.stringify(base.slice(0, -7))}`);
-		urls.push(`  ${JSON.stringify(iid)}: ${JSON.stringify(is_dev ? devUrlFor(virtualPath) : publicUrlFor(iid))}`);
+		if (base.endsWith(".svelte")) names.push(`${JSON.stringify(iid)}: ${JSON.stringify(base.slice(0, -7))}`);
+		urls.push(`${JSON.stringify(iid)}: ${JSON.stringify(is_dev ? devUrlFor(virtualPath) : publicUrlFor(iid))}`);
 	}
-	return `export const load_islands = () => import(${JSON.stringify(V_SERVER_ISLANDS)});\nexport const island_url = {\n${urls.join(",\n")}\n};\nexport const island_name = {\n${names.join(",\n")}\n};\nexport const island_render = {\n${renders.join(",\n")}\n};\nexport const render_island = {\n${[...by_render].map(([r, iid]) => `  ${JSON.stringify(r)}: ${JSON.stringify(iid)}`).join(",\n")}\n};\nexport const island_reads_page_data = ${is_dev ? "null" : PAGE_DATA_READS_PLACEHOLDER};`;
+	const entries = [...by_render].map(([r, iid]) => `${JSON.stringify(r)}: ${JSON.stringify(iid)}`);
+	return dedent`
+		export const load_islands = () => import(${JSON.stringify(V_SERVER_ISLANDS)});
+
+		export const island_url = {
+			${urls.join(",\n	")}
+		};
+
+		export const island_name = {
+			${names.join(",\n	")}
+		};
+
+		export const island_render = {
+			${renders.join(",\n	")}
+		};
+
+		export const render_island = {
+			${entries.join(",\n	")}
+		};
+
+		// id → does the hole's SERVER tree read \`page.data\` (the page lookup a hole needs: server/
+		// render-page.ts). Known only once every module is transformed: a build patches the
+		// placeholder in renderChunk (driver \`patch_page_data_reads\`); dev leaves \`null\` (unknown → look up).
+		export const island_reads_page_data = ${is_dev ? "null" : PAGE_DATA_READS_PLACEHOLDER};
+	`;
 }
 /** `virtual:ogygia/server-islands`: each SERVER island's loader, `id → () => import(entry)` (empty on
 *  the client). Imported only by the manifest's `load_islands()` — never statically. */
 function server_islands_module(ssr, program) {
 	const entries = [];
 	if (ssr) {
-		for (const [iid, virtualPath] of program.by_id) if (program.registry.get(virtualPath)?.server) entries.push(`  ${JSON.stringify(iid)}: () => import(${JSON.stringify(virtualPath)})`);
+		for (const [iid, virtualPath] of program.by_id) if (program.registry.get(virtualPath)?.server) entries.push(`${JSON.stringify(iid)}: () => import(${JSON.stringify(virtualPath)})`);
 	}
-	return `export const islands = {\n${entries.join(",\n")}\n};\n`;
+	return dedent`
+		export const islands = {
+			${entries.join(",\n	")}
+		};
+	`;
 }
 /** The token the build replaces with its answer (driver `patch_page_data_reads`), inside a string
 *  literal the bundler cannot fold: a plain `null` placeholder was inlined into every reader as the

package/dist/compiler/link/transport.js

@@ -1,4 +1,5 @@
 import { OWN_SPECIFIER_SOURCE } from "../../own-package.js";
+import { dedent } from "../dedent.js";
 // src/compiler/link/transport.ts
 /**
 * `virtual:ogygia/transport` emitter — re-exports the app's universal `transport` hook (or an empty
@@ -6,10 +7,29 @@ import { OWN_SPECIFIER_SOURCE } from "../../own-package.js";
 * Pure over the resolved absolute path to the app's universal hooks module (or null).
 */
 function transport_module(universal_hooks, kit_codec = null) {
-	if (!universal_hooks) return `export const transport = {};\nexport const encoders = {};\nexport const decoders = {};`;
-	const src = `import * as hooks from ${JSON.stringify(universal_hooks)};\nexport const transport = hooks.transport || {};\nconst codecs = Object.entries(transport);\nexport const encoders = Object.fromEntries(codecs.map(([k, v]) => [k, v.encode]));\nexport const decoders = Object.fromEntries(codecs.map(([k, v]) => [k, v.decode]));`;
+	if (!universal_hooks) return dedent`
+			export const transport = {};
+			export const encoders = {};
+			export const decoders = {};
+		`;
+	const src = dedent`
+		import * as hooks from ${JSON.stringify(universal_hooks)};
+
+		export const transport = hooks.transport || {};
+		const codecs = Object.entries(transport);
+		export const encoders = Object.fromEntries(codecs.map(([k, v]) => [k, v.encode]));
+		export const decoders = Object.fromEntries(codecs.map(([k, v]) => [k, v.decode]));
+	`;
 	if (!kit_codec) return src;
-	return `import { init_transport } from ${JSON.stringify(kit_codec)};\n${src}\ninit_transport(transport);`;
+	return dedent`
+		import { init_transport } from ${JSON.stringify(kit_codec)};
+		${src}
+
+		// Kit 3 (client leg): Kit's own codec module is a reader too — its remote argument encoding
+		// reads it, and only Kit's client boot fills it otherwise (never on a csr=false page). Kit's
+		// boot later fills it again with the same transport.
+		init_transport(transport);
+	`;
 }
 /**
 * `virtual:ogygia/kit-transport` emitter — the value behind the barrel's `ogygia.transport` (the Kit
@@ -22,8 +42,10 @@ function transport_module(universal_hooks, kit_codec = null) {
 * `transport_spec` is the resolvable path to ogygia's own `transport.js` (dist).
 */
 function kit_transport_module(app_crosses_wire, transport_spec) {
-	if (!app_crosses_wire) return `export const transport = {};\n`;
-	return `export { ogygiaTransport as transport } from ${JSON.stringify(transport_spec)};\n`;
+	if (!app_crosses_wire) return `export const transport = {};`;
+	return dedent`
+		export { ogygiaTransport as transport } from ${JSON.stringify(transport_spec)};
+	`;
 }
 const OGYGIA_WIRE_NAMED = new RegExp(`import\\s+(?:type\\s+)?\\{([\\s\\S]*?)\\}\\s*from\\s*['"]${OWN_SPECIFIER_SOURCE}['"]`, "g");
 const WIRE_API = /\b(?:region|Region|site)\b/;
@@ -58,10 +80,20 @@ function transportables_module(modules, ssr, rel, crosses_wire = false) {
 	if (ssr) {
 		const imports = [];
 		for (const abs of modules) imports.push(`import ${JSON.stringify(abs)};`);
-		return imports.join("\n") + "\nexport const wire_loaders = {};\nexport const wire_all = false;\n";
+		return dedent`
+			${imports.join("\n")}
+
+			export const wire_loaders = {};
+			export const wire_all = false;
+		`;
 	}
 	const entries = [];
 	for (const abs of modules) entries.push(`${JSON.stringify(rel(abs))}: () => import(${JSON.stringify(abs)})`);
-	return `export const wire_loaders = {${entries.join(", ")}};\nexport const wire_all = ${crosses_wire && entries.length > 0};\n`;
+	return dedent`
+		export const wire_loaders = {
+			${entries.join(",\n	")}
+		};
+		export const wire_all = ${crosses_wire && entries.length > 0};
+	`;
 }
 export { kit_transport_module, source_crosses_wire, transport_module, transportables_module };

package/dist/compiler/macros/source.js

@@ -6,12 +6,12 @@ import { og_member } from "./wire.js";
 * `import.meta.og.source(fn)` — declared data sources, as a compile construct (the postrender
 * reverse index; internal/notes/freeze.md §L2):
 *
-*   export const loadBuilderContent = import.meta.og.source(async (event, category) => { … });
+*   export const loadCmsContent = import.meta.og.source(async (event, category) => { … });
 *
 * The macro stamps the id from THIS definition's `file#export` (root-relative; the ogygia.files
 * identity rail applies to package paths upstream) and rewrites to
 * `__og_source('<id>', fn, opts?)` with the runtime-wrapper import injected. Loads stay
-* untouched plain TS forever; `postrender.invalidate(loadBuilderContent, [args])` reads the stamp
+* untouched plain TS forever; `postrender.invalidate(loadCmsContent, [args])` reads the stamp
 * off the function — no strings anywhere.
 *
 * STRICT BY CONSTRUCTION — legal in exactly ONE position:

package/dist/compiler/region/transform.d.ts

@@ -110,12 +110,21 @@ export declare function import_keys_hint(import_keys: ImportKeys): RegExp;
  * Paths are always posix so SSR/client builds agree across OS path separators. */
 export declare function islandId(relHostPath: string, index: string | number, salt?: string): string;
 /**
- * Deterministic client chunk path for a hydrate island (mirrors `og-runtime.<hash>.js`).
- * SSR bakes this into `<ogygia-region entry>` so the sticky runtime can `import(entry)` with no
- * app-wide regions map — Kit builds server before client, so content-hashed Vite names can't hand off.
+ * The directory, under the app dir, of the STABLE names (an island's identity, the runtime's): not
+ * `immutable/`. A host serves `immutable/` for a year by name (every adapter, every CDN rule written
+ * for it), and a stable name keeps its name while its content follows each build: a year-old copy
+ * would load another build's code. Here a host's ordinary rule revalidates them. The content-hashed
+ * files they point at stay in `immutable/`.
+ */
+export declare const STABLE_NAME_DIR = "ogygia";
+/**
+ * Deterministic client path of a hydrate island's stable name (mirrors the runtime's). SSR bakes it
+ * into `<ogygia-region entry>` as the island's identity — a name, not a file: the content-hashed
+ * entry is found through the handoff (the server) and the location maps (the browser,
+ * link/location-map.ts), since Kit builds server before client.
  */
 export declare function islandChunkFileName(iid: string, appDir?: string): string;
-/** App-internal URL for {@link islandChunkFileName}: `/<appDir>/immutable/…` (leading slash, appDir,
+/** App-internal URL for {@link islandChunkFileName}: `/<appDir>/ogygia/…` (leading slash, appDir,
  *  NO base). It is what SSR bakes onto `<ogygia-region entry>`; `Region.svelte` runs it through Kit's
  *  `asset()` at render time, which is the sole authority on `base` / the assets CDN / relative paths —
  *  so a base is never baked here (that would double-apply it). NOT the on-disk output filename. */

package/dist/compiler/region/transform.js

@@ -200,14 +200,23 @@ function islandId(relHostPath, index, salt = "") {
 	return createHash("md5").update(msg).digest("hex").slice(0, 12);
 }
 /**
-* Deterministic client chunk path for a hydrate island (mirrors `og-runtime.<hash>.js`).
-* SSR bakes this into `<ogygia-region entry>` so the sticky runtime can `import(entry)` with no
-* app-wide regions map — Kit builds server before client, so content-hashed Vite names can't hand off.
+* The directory, under the app dir, of the STABLE names (an island's identity, the runtime's): not
+* `immutable/`. A host serves `immutable/` for a year by name (every adapter, every CDN rule written
+* for it), and a stable name keeps its name while its content follows each build: a year-old copy
+* would load another build's code. Here a host's ordinary rule revalidates them. The content-hashed
+* files they point at stay in `immutable/`.
+*/
+const STABLE_NAME_DIR = "ogygia";
+/**
+* Deterministic client path of a hydrate island's stable name (mirrors the runtime's). SSR bakes it
+* into `<ogygia-region entry>` as the island's identity — a name, not a file: the content-hashed
+* entry is found through the handoff (the server) and the location maps (the browser,
+* link/location-map.ts), since Kit builds server before client.
 */
 function islandChunkFileName(iid, appDir = "_app") {
-	return `${appDir}/immutable/og-region.${iid}.js`;
+	return `${appDir}/${STABLE_NAME_DIR}/og-region.${iid}.js`;
 }
-/** App-internal URL for {@link islandChunkFileName}: `/<appDir>/immutable/…` (leading slash, appDir,
+/** App-internal URL for {@link islandChunkFileName}: `/<appDir>/ogygia/…` (leading slash, appDir,
 *  NO base). It is what SSR bakes onto `<ogygia-region entry>`; `Region.svelte` runs it through Kit's
 *  `asset()` at render time, which is the sole authority on `base` / the assets CDN / relative paths —
 *  so a base is never baked here (that would double-apply it). NOT the on-disk output filename. */
@@ -1930,4 +1939,4 @@ var TsRegionCompilation = class {
 		};
 	}
 };
-export { CLIENT_BINDING_STUB, DEFAULT_IMPORT_KEYS, ISLAND_DIR, asRegionLocals, foucCssVirtualId, import_keys_hint, is_island_path, islandChunkFileName, islandId, islandPublicUrl, normalize_hydrate_value, normalize_import_keys, normalize_region_value, regionBindingVirtualId, regionId, regionIdentity, strategyKey, transformHost, transformTsRegions, wrapperVirtualId };
+export { CLIENT_BINDING_STUB, DEFAULT_IMPORT_KEYS, ISLAND_DIR, STABLE_NAME_DIR, asRegionLocals, foucCssVirtualId, import_keys_hint, is_island_path, islandChunkFileName, islandId, islandPublicUrl, normalize_hydrate_value, normalize_import_keys, normalize_region_value, regionBindingVirtualId, regionId, regionIdentity, strategyKey, transformHost, transformTsRegions, wrapperVirtualId };

package/dist/hooks.d.ts

@@ -17,6 +17,22 @@ export interface OgygiaHandleOptions {
    * (`/_app/…`): Kit answers those itself, before any handle runs.
    */
   endpoint?: string;
+  /**
+   * The secret that signs region capabilities (hole and live-region URLs). Takes precedence over
+   * the `OGYGIA_SECRET` environment variable, for a host whose server process never sees its
+   * runtime env. Pass a build-time private env value:
+   *
+   * ```ts
+   * import { OGYGIA_SECRET } from '$env/static/private';
+   * export const handle = ogygia.handle({ secret: OGYGIA_SECRET });
+   * ```
+   *
+   * An empty or blank value counts as not given (`OGYGIA_SECRET`, then a per-build random key, sign
+   * instead). It signs exactly as the same value in `OGYGIA_SECRET` does, so pages from either
+   * verify on the other. In production it needs ≥16 UTF-8 bytes. Every deployment that serves your
+   * pages or your islands endpoint needs the same secret.
+   */
+  secret?: string;
   /**
    * Post-process the HTML ogygia sends — every document (the chunk carrying `</head>`; a streamed
    * tail passes untouched) and every region answer (a hole, a lake remount) — e.g. a web-component

package/dist/hooks.js

@@ -1,5 +1,5 @@
 import { REGION_BRAND } from "./region-brand.js";
-import { signing_key } from "./server/signing-key.js";
+import { configure_signing_secret, signing_key } from "./server/signing-key.js";
 import { mpaSpeculationRules } from "./compiler/link/speculation.js";
 import { set_page_route_config } from "./plugin/routes.js";
 import { kit_page_facts_tail, kit_page_ready, kit_render_context, set_kit_event_reader, set_kit_page_reader, set_render_page_port } from "./server/kit-context.js";
@@ -9,7 +9,7 @@ import { absolutize_hole_html } from "./server/hole-urls.js";
 import { is_keep_fallback } from "./keep-fallback.js";
 import { set_source_recorder } from "./source.js";
 import { kit_asset } from "./kit-paths.js";
-import { region_mac_message, sign, verify } from "./server/hmac.js";
+import { region_mac_message, secret_has_min_entropy, sign, verify } from "./server/hmac.js";
 import { expiry_refusal, note_cache_control } from "./server/shared-cache.js";
 import { app_lifetime } from "./server/region-endpoint.js";
 import { cached_render, render_cache_key } from "./server/render-cache.js";
@@ -435,6 +435,8 @@ var OgygiaHandle = class {
 		this.#transform = options.transform;
 		configure_islands_endpoint(options.endpoint);
 		this.#endpoint = islands_endpoint();
+		if (options.secret?.trim() && !import.meta.env.DEV && !secret_has_min_entropy(options.secret)) throw new Error(`[ogygia] handle({ secret }) is too short for production (need ≥16 UTF-8 bytes).`);
+		configure_signing_secret(options.secret);
 		this.#speculation_rules = enabled ? "" : mpaSpeculationRules(this.#endpoint);
 		this.render_rate = new RateLimiter({
 			max: rateLimit.max,