@ogygia/core 0.12.3 → 0.13.0

package/dist/compiler/region/transform.js

@@ -6,6 +6,7 @@ import { regionId, regionIdentity, strategyKey } from "./identity.js";
 import { regionBindingVirtualId } from "../ids.js";
 import { island_entry_source, lake_wrapper_source, make_region_binding, make_wake_island, server_wrapper_source } from "./emit.js";
 import { blank_styles } from "../blank-styles.js";
+import { OgygiaError, warn } from "../../messages/build.js";
 import { parse } from "svelte/compiler";
 import MagicString from "magic-string";
 // src/compiler/region/transform.ts
@@ -16,7 +17,11 @@ function warn_unparsed(id, err) {
 	if (warned_unparsed.has(id)) return;
 	warned_unparsed.add(id);
 	const e = err;
-	console.warn(`[ogygia] regions: skipped ${id}: ${e.code ?? (e.message ?? "parse error").split("\n")[0].slice(0, 80)}${e.start?.line ? ` at ${e.start.line}:${(e.start.column ?? 0) + 1}` : ""} — its region imports stay plain imports`);
+	warn("region_host_skipped", {
+		file: id,
+		reason: e.code ?? (e.message ?? "parse error").split("\n")[0].slice(0, 80),
+		at: e.start?.line ? `${e.start.line}:${(e.start.column ?? 0) + 1}` : ""
+	});
 }
 const REGEXP_META = /[.*+?^${}()|[\]\\]/g;
 const PATH_SEP = /[/\\]/;
@@ -93,10 +98,10 @@ function line_col(src, offset) {
 }
 /** Once per key for the process — the ssr AND client passes both transform the same host. */
 const store_warned = /* @__PURE__ */ new Set();
-function warn_once(key, msg) {
+function warn_once(key, say) {
 	if (store_warned.has(key)) return;
 	store_warned.add(key);
-	console.warn(msg);
+	say();
 }
 const KNOWN_STRATEGIES = /* @__PURE__ */ new Set([
 	"load",
@@ -158,14 +163,17 @@ function normalize_import_keys_uncached(overrides) {
 		["render", render],
 		["preset", preset],
 		["region", region]
-	]) if (!name || !JS_IDENT.test(name)) throw new Error(`[ogygia] importKeys.${role} must be a non-empty JS identifier (got ${JSON.stringify(overrides?.[role])}).`);
+	]) if (!name || !JS_IDENT.test(name)) throw new OgygiaError("import_key_invalid", {
+		role,
+		got: String(JSON.stringify(overrides?.[role]))
+	});
 	if ((/* @__PURE__ */ new Set([
 		wake,
 		fetch,
 		render,
 		preset,
 		region
-	])).size !== 5) throw new Error("[ogygia] importKeys.wake, importKeys.fetch, importKeys.render, importKeys.preset, and importKeys.region must be distinct.");
+	])).size !== 5) throw new OgygiaError("import_keys_not_distinct");
 	return {
 		wake,
 		fetch,
@@ -339,7 +347,10 @@ function parse_ts_as_region_options(arg, fail, regionKey, wakeKey, renderKey, fe
 */
 function normalize_region_value(raw, where, regionKey = "region") {
 	if ((raw ?? "").trim() === "raw") return;
-	throw new Error(`[ogygia] ${where}: \`${regionKey}\` only takes the value 'raw' (a held region with no baked schedule). To bake a schedule use a \`wake:\` mark, or set it at the \`region()\` call.`);
+	throw new OgygiaError("region_value_not_raw", {
+		host: where,
+		key: regionKey
+	});
 }
 /**
 * Validate a `wake:` schedule value on a held import (a `.ts` registry / remote). Accepts the wake
@@ -349,7 +360,11 @@ function normalize_region_value(raw, where, regionKey = "region") {
 function normalize_hydrate_value(raw, where, wakeKey = "wake") {
 	const v = (raw ?? "").trim();
 	if (HYDRATE_STRATEGIES.has(v) || is_media_query(v)) return v;
-	throw new Error(`[ogygia] ${where}: unknown \`${wakeKey}\` strategy '${v}'. Use 'load' | 'idle' | 'visible' | 'interaction' | a media query.`);
+	throw new OgygiaError("wake_strategy_unknown", {
+		host: where,
+		key: wakeKey,
+		value: v
+	});
 }
 /** Reconstruct an import declaration without its `with { ... }` attributes clause. */
 function clean_import_text(source, node) {
@@ -613,7 +628,10 @@ function assert_swr_lake_crossable(node, err) {
 */
 function resolve_component_path(spec, host_id, ctx) {
 	if (typeof spec !== "string" || !spec.trim()) return null;
-	if (spec.startsWith(".") && VIRTUAL_HOST_RE.test(host_id)) throw new Error(`[ogygia] ${host_id}: cannot resolve the relative import '${spec}' from a generated module — it has no directory. Its real origin must be threaded (HostCtx.originOf); this is an ogygia bug, please report it.`);
+	if (spec.startsWith(".") && VIRTUAL_HOST_RE.test(host_id)) throw new OgygiaError("generated_module_relative_import", {
+		host: host_id,
+		specifier: spec
+	});
 	if (spec === "$lib" || spec.startsWith("$lib/")) return ctx.pathModule.join(ctx.libDir, spec === "$lib" ? "" : spec.slice(5));
 	if (spec.startsWith(".")) return ctx.pathModule.resolve(ctx.pathModule.dirname(host_id), spec);
 	return spec;
@@ -736,21 +754,19 @@ var FileCompilation = class {
 		if (early) return early.done;
 		return this.#lower();
 	}
-	/** Walk an AST subtree for an Identifier / Component reference to `local`. Pure over the AST. */
-	#ast_refs_local(root, local) {
-		let found = false;
+	/** Every name the host's code references outside its imports and the `skip`ped instance
+	*  statements: Identifier names, Component names and each dotted prefix of one (`<Ui.Card>`
+	*  references `Ui`). ONE walk answers every "is `local` used?" question — asking per import walked
+	*  the whole file once per island, quadratic in the island count. Pure over the AST. */
+	#referenced_names(skip) {
+		const names = /* @__PURE__ */ new Set();
 		const walk = (node) => {
-			if (found || !node || typeof node !== "object") return;
-			if (node.type === "Identifier" && node.name === local) {
-				found = true;
-				return;
-			}
-			if (node.type === "Component") {
+			if (!node || typeof node !== "object") return;
+			if (node.type === "Identifier") names.add(node.name);
+			else if (node.type === "Component") {
 				const n = node.name || "";
-				if (n === local || n.startsWith(local + ".")) {
-					found = true;
-					return;
-				}
+				names.add(n);
+				for (let i = n.indexOf("."); i !== -1; i = n.indexOf(".", i + 1)) names.add(n.slice(0, i));
 			}
 			for (const k of Object.keys(node)) {
 				if (k === "start" || k === "end" || k === "loc") continue;
@@ -759,21 +775,15 @@ var FileCompilation = class {
 				else if (v && typeof v === "object" && typeof v.type === "string") walk(v);
 			}
 		};
-		if (Array.isArray(root)) for (const n of root) walk(n);
-		else walk(root);
-		return found;
+		for (const n of this.#instance_body) if (n.type !== "ImportDeclaration" && !skip?.has(n)) walk(n);
+		for (const n of this.#module_body) if (n.type !== "ImportDeclaration") walk(n);
+		for (const n of this.#ast.fragment?.nodes ?? []) walk(n);
+		return names;
 	}
+	#used_names;
 	/** Is a marked import's `local` used anywhere but its own import (else it is dead, strip it)? */
 	#marked_import_referenced(local) {
-		for (const n of this.#instance_body) {
-			if (n.type === "ImportDeclaration") continue;
-			if (this.#ast_refs_local(n, local)) return true;
-		}
-		for (const n of this.#module_body) {
-			if (n.type === "ImportDeclaration") continue;
-			if (this.#ast_refs_local(n, local)) return true;
-		}
-		return this.#ast_refs_local(this.#ast.fragment?.nodes ?? [], local);
+		return (this.#used_names ??= this.#referenced_names()).has(local);
 	}
 	#resolve_region_mark(inline, fail) {
 		const import_keys = this.#import_keys;
@@ -841,7 +851,14 @@ var FileCompilation = class {
 		const said = from_preset ? `preset '${from_preset}'` : "this import";
 		if (render_mode === "deferred" && wake_val != null) {
 			if (fetch_val != null) throw fail(`${said} times a \`${import_keys.render}: 'deferred'\` hole twice, with \`${import_keys.fetch}: '${fetch_val}'\` and \`${import_keys.wake}: '${wake_val}'\`. Keep \`${import_keys.fetch}\`: it says when a hole's HTML arrives.`);
-			warn_once(`deferred-wake:${rel_host}:${said}:${wake_val}`, `[ogygia] ${rel_host}: ${said} times a \`${import_keys.render}: 'deferred'\` hole with \`${import_keys.wake}: '${wake_val}'\`, which is deprecated. Write \`${import_keys.render}: 'deferred', ${import_keys.fetch}: '${wake_val}'\` instead: \`${import_keys.fetch}\` says when a hole's HTML arrives. (\`${import_keys.wake}\` is when an island's JS runs; a hole ships no JS.)`);
+			warn_once(`deferred-wake:${rel_host}:${said}:${wake_val}`, () => warn("hole_wake_deprecated", {
+				host: rel_host,
+				said,
+				render_key: import_keys.render,
+				wake_key: import_keys.wake,
+				fetch_key: import_keys.fetch,
+				value: wake_val
+			}));
 			fetch_val = wake_val;
 		}
 		if (fetch_val != null && render_mode !== "deferred") throw fail(`${said} sets \`${import_keys.fetch}: '${fetch_val}'\` without \`${import_keys.render}: 'deferred'\` — \`${import_keys.fetch}\` is a hole's timing. Write \`${import_keys.render}: 'deferred', ${import_keys.fetch}: '${fetch_val}'\` for a hole` + (render_mode == null ? `, or \`${import_keys.wake}: '${fetch_val}'\` for an island.` : "."));
@@ -944,7 +961,11 @@ var FileCompilation = class {
 		const kids = (node.fragment?.nodes ?? []).filter((n) => !(n.type === "Text" && !String(n.data ?? "").trim()));
 		if (kids.length === 0) return;
 		if (is_server && kids.length === 1 && kids[0].type === "SnippetBlock" && kids[0].expression?.name === "ogygiaFallback") return;
-		throw new Error(`[ogygia] ${this.#rel_host}: <${local}> has host children/snippets that cannot cross the island boundary. Under portable bindings, pass serializable props and put UI inside the island component` + (is_server ? ` (only the reserved \`{#snippet ogygiaFallback()}\` may appear at the call site).` : `.`));
+		throw new OgygiaError("region_children_not_portable", {
+			host: this.#rel_host,
+			tag: local,
+			server: is_server
+		});
 	}
 	/** Walk the markup: enforce region-usage rules + surface whether a hydrate island has real
 	*  children (the app then needs the wire slot revivers). Mutates #has_island_children. */
@@ -954,7 +975,11 @@ var FileCompilation = class {
 				const name = node.name || "";
 				if (name.includes(".")) {
 					const root = name.split(".")[0];
-					if (this.#marked_components.has(root) && this.#marked_components.get(root).strategy !== "lake") throw new Error(`[ogygia] ${this.#rel_host}: dotted tag \`<${name}>\` is not supported for region import '${root}'. Import the leaf component with \`with { hydrate|defer }\` instead.`);
+					if (this.#marked_components.has(root) && this.#marked_components.get(root).strategy !== "lake") throw new OgygiaError("region_dotted_tag", {
+						host: this.#rel_host,
+						tag: name,
+						import: root
+					});
 				} else if (this.#marked_components.has(name)) {
 					this.#static_placed.add(name);
 					const mark = this.#marked_components.get(name);
@@ -983,13 +1008,22 @@ var FileCompilation = class {
 		if (!this.#ctx.pathModule.isAbsolute(p)) return p;
 		return (typeof this.#ctx.pkg_identity === "function" ? this.#ctx.pkg_identity(p) : null) ?? this.#posix_rel(p);
 	}
-	/** `[ogygia] host: import { … } — msg` — the region-import error formatter. */
+	/** `host: import { … } — msg` (`region_import_invalid`) — the region-import error formatter. */
 	#err(specifiers, msg) {
-		return /* @__PURE__ */ new Error(`[ogygia] ${this.#rel_host}: import { ${specifiers} } — ${msg}`);
+		return new OgygiaError("region_import_invalid", {
+			host: this.#rel_host,
+			names: specifiers,
+			problem: msg
+		});
 	}
-	/** `[ogygia] host: import.meta.og.asRegion (local) — msg` — the asRegion error formatter. */
+	/** `host: import.meta.og.asRegion (local) — msg` (`as_region_invalid`) — the asRegion error
+	*  formatter. */
 	#as_err(local, msg) {
-		return /* @__PURE__ */ new Error(`[ogygia] ${this.#rel_host}: import.meta.og.asRegion (${local}) — ${msg}`);
+		return new OgygiaError("as_region_invalid", {
+			host: this.#rel_host,
+			name: local,
+			problem: msg
+		});
 	}
 	/** Read asRegion's options object into the same key→value map an import attribute produces, so the
 	*  SHARED parser gives asRegion EXACTLY the import-attribute option surface. Object-only and
@@ -1035,12 +1069,17 @@ var FileCompilation = class {
 		const lang = script_lang_attr(ast.instance) || script_lang_attr(ast.module);
 		const path = ctx.pathModule;
 		const rel_host = this.#rel_host = path.relative(ctx.root, id).split(PATH_SEP).join("/");
-		reject_dynamic_region_imports(instance_body, import_keys, (keys) => {
-			throw new Error(`[ogygia] ${rel_host}: dynamic import() with { with: { ${keys.join(", ")} } } is not supported. Mark islands with a static \`import X from '…' with { ${import_keys.wake}: '…' }\` (or \`${import_keys.render}\` / \`${import_keys.preset}\`) — the binding becomes a portable island component. For a click-loaded chunk that is not an island, use plain \`await import('./Comp.svelte')\` (no region attributes) inside a host island. To delay a real island until click, gate a static region import with \`{#if}\`.`);
-		});
-		reject_dynamic_region_imports(module_body, import_keys, (keys) => {
-			throw new Error(`[ogygia] ${rel_host}: dynamic import() with { with: { ${keys.join(", ")} } } is not supported. Mark islands with a static \`import X from '…' with { ${import_keys.wake}: '…' }\` (or \`${import_keys.render}\` / \`${import_keys.preset}\`) — the binding becomes a portable island component. For a click-loaded chunk that is not an island, use plain \`await import('./Comp.svelte')\` (no region attributes) inside a host island. To delay a real island until click, gate a static region import with \`{#if}\`.`);
-		});
+		const reject_dynamic = (keys) => {
+			throw new OgygiaError("dynamic_region_import", {
+				host: rel_host,
+				keys: keys.join(", "),
+				wake_key: import_keys.wake,
+				render_key: import_keys.render,
+				preset_key: import_keys.preset
+			});
+		};
+		reject_dynamic_region_imports(instance_body, import_keys, reject_dynamic);
+		reject_dynamic_region_imports(module_body, import_keys, reject_dynamic);
 		/** localName -> { node, cleaned } */
 		const imports = /* @__PURE__ */ new Map();
 		/** localName -> { strategy, options } */
@@ -1140,7 +1179,7 @@ var FileCompilation = class {
 	* Lower — the compilation's fields → rewritten source + `IslandDescriptor[]`. Consumes ONLY the
 	* analyze pass's fields (it never re-reads the file): creates the MagicString, rewrites each marked
 	* import to its wrapper / binding / stub, mints the island records, and brands portable snippets.
-	* `err` / `ast_refs_local` / `marked_import_referenced` are rebuilt here from those fields — pure
+	* `err` / `referenced_names` / `marked_import_referenced` are rebuilt here from those fields — pure
 	* over the AST + host path.
 	*/
 	#lower() {
@@ -1251,7 +1290,11 @@ var FileCompilation = class {
 			}
 			const entry_spec = info.node.source?.value;
 			const componentPath = resolve_component_path(entry_spec, origin, ctx);
-			if (!componentPath) throw new Error(`[ogygia] ${rel_host}: region import '${local}' needs a module specifier ($lib/…, relative, or a package specifier like 'pkg/component').`);
+			if (!componentPath) throw new OgygiaError("region_import_no_specifier", {
+				host: rel_host,
+				name: local,
+				held: false
+			});
 			const exportName = synthetic_export.get(local);
 			const comp_rel = this.#component_identity(componentPath);
 			const id_base = exportName && exportName !== "default" ? `${comp_rel}#${exportName}` : comp_rel;
@@ -1344,17 +1387,8 @@ var FileCompilation = class {
 		}
 		const as_region_locals = new Set(as_regions.map((r) => r.compLocal));
 		if (as_region_locals.size) {
-			const referenced_outside = (local) => {
-				for (const n of instance_body) {
-					if (n.type === "ImportDeclaration" || as_region_nodes.has(n)) continue;
-					if (this.#ast_refs_local(n, local)) return true;
-				}
-				for (const n of module_body) {
-					if (n.type === "ImportDeclaration") continue;
-					if (this.#ast_refs_local(n, local)) return true;
-				}
-				return this.#ast_refs_local(ast.fragment?.nodes ?? [], local);
-			};
+			const outside = this.#referenced_names(as_region_nodes);
+			const referenced_outside = (local) => outside.has(local);
 			const seen = /* @__PURE__ */ new Set();
 			for (const compLocal of as_region_locals) {
 				const info = imports.get(compLocal);
@@ -1394,7 +1428,16 @@ var FileCompilation = class {
 			}
 		};
 		if (portable_allowed) walk_portable(ast.fragment?.nodes ?? []);
-		const outer_candidates = portable_candidates.filter((c) => !portable_candidates.some((o) => o !== c && c.snip.start >= o.snip.start && c.snip.end <= o.snip.end));
+		const by_start = [...portable_candidates].sort(outer_spans_first);
+		const nested = /* @__PURE__ */ new Set();
+		let reach = -Infinity;
+		for (let i = 0; i < by_start.length; i++) {
+			const c = by_start[i];
+			const twin = by_start[i + 1];
+			if (c.snip.end <= reach || twin && twin.snip.start === c.snip.start && twin.snip.end === c.snip.end) nested.add(c);
+			if (c.snip.end > reach) reach = c.snip.end;
+		}
+		const outer_candidates = portable_candidates.filter((c) => !nested.has(c));
 		const block_bound = /* @__PURE__ */ new Set();
 		const bind_pattern = (n) => {
 			if (!n || typeof n !== "object") return;
@@ -1476,7 +1519,11 @@ var FileCompilation = class {
 			const store_captures = [];
 			const store_rewrites = [];
 			for (const [nm, sites] of stores) {
-				if (nm.startsWith("$$")) throw new Error(`[ogygia] ${rel_host}: {#snippet ${name}} crosses an island boundary but reads \`${nm}\` — the host's $$-props cannot cross. Read the value into a plain host variable outside the snippet and use that instead.`);
+				if (nm.startsWith("$$")) throw new OgygiaError("snippet_reads_dollar_props", {
+					host: rel_host,
+					snippet: name,
+					name: nm
+				});
 				const base = nm.slice(1);
 				const prop = `__og_sub_${base}`;
 				store_captures.push({
@@ -1489,8 +1536,18 @@ var FileCompilation = class {
 					prop
 				});
 				const trace = sites.map((p) => `${rel_host}:${line_col(source, p.start)}`).join(", ");
-				if (host_declared.has(base) || imports.has(base)) warn_once(`${id}\0${name}\0${nm}\0frozen`, `[ogygia] ${rel_host}: {#snippet ${name}} crosses an island boundary and reads \`${nm}\` (at ${trace}) — captured as a FROZEN snapshot of the store's value at render time; later store updates never reach the island. To make the snapshot explicit (and silence this), read it at host scope outside the snippet — e.g. \`const ${base}_value = ${nm};\` — and use that.`);
-				else warn_once(`${id}\0${name}\0${nm}\0unresolved`, `[ogygia] ${rel_host}: {#snippet ${name}} reads \`${nm}\` (at ${trace}), but \`${base}\` is not a host declaration or import, so ogygia cannot verify it is a store. Its value is captured at the host anyway — if the build now errors in ${rel_host}, start there.`);
+				if (host_declared.has(base) || imports.has(base)) warn_once(`${id}\0${name}\0${nm}\0frozen`, () => warn("snippet_store_snapshot", {
+					host: rel_host,
+					snippet: name,
+					store: nm,
+					at: trace
+				}));
+				else warn_once(`${id}\0${name}\0${nm}\0unresolved`, () => warn("snippet_store_unverified", {
+					host: rel_host,
+					snippet: name,
+					store: nm,
+					at: trace
+				}));
 			}
 			const cleaned_imports = [];
 			const seen_imports = /* @__PURE__ */ new Set();
@@ -1506,7 +1563,11 @@ var FileCompilation = class {
 						cleaned_imports.push(text);
 					}
 				} else if (host_declared.has(nm)) {
-					if (store_like.has(nm)) warn_once(`${id}\0${name}\0${nm}\0object`, `[ogygia] ${rel_host}: {#snippet ${name}} crosses an island boundary and captures the store \`${nm}\` as an OBJECT — a host-declared store cannot cross (its functions don't serialize). Use its value (\`$${nm}\`) inside the snippet, or share live state with a wired class instead.`);
+					if (store_like.has(nm)) warn_once(`${id}\0${name}\0${nm}\0object`, () => warn("snippet_captures_store", {
+						host: rel_host,
+						snippet: name,
+						store: nm
+					}));
 					captures.push(nm);
 				} else if (module_imports.has(nm)) {
 					const text = module_imports.get(nm).trim();
@@ -1604,6 +1665,10 @@ var FileCompilation = class {
 * @param raw the text between the `with {` and `}`
 * @returns
 */
+/** Span order for the portable-snippet nesting sweep: by start, the longer span first on a tie. */
+function outer_spans_first(a, b) {
+	return a.snip.start - b.snip.start || b.snip.end - a.snip.end;
+}
 function parse_import_attrs(raw) {
 	const attrs = /* @__PURE__ */ new Map();
 	IMPORT_ATTR_PAIR_G.lastIndex = 0;
@@ -1640,7 +1705,10 @@ function ts_literal_ranges(source, id) {
 	const ranges = [];
 	const walk = (n) => {
 		if (!n || typeof n !== "object") return;
-		if (Array.isArray(n)) return void n.forEach(walk);
+		if (Array.isArray(n)) {
+			n.forEach(walk);
+			return;
+		}
 		const node = n;
 		const t = node.type;
 		const is_str = (t === "Literal" || t === "StringLiteral") && typeof node.value === "string";
@@ -1699,9 +1767,13 @@ var TsRegionCompilation = class {
 	#posix_rel(abs) {
 		return this.#path.relative(this.#root, abs).split(PATH_SEP).join("/");
 	}
-	/** `[ogygia] host: import.meta.og.asRegion (local) — msg`. */
+	/** `host: import.meta.og.asRegion (local) — msg` (`as_region_invalid`). */
 	#as_err(local, msg) {
-		return /* @__PURE__ */ new Error(`[ogygia] ${this.#rel_host}: import.meta.og.asRegion (${local}) — ${msg}`);
+		return new OgygiaError("as_region_invalid", {
+			host: this.#rel_host,
+			name: local,
+			problem: msg
+		});
 	}
 	/**
 	* Same policy as transformHost's resolve_component_path: $lib/relative → absolute file path,
@@ -1732,18 +1804,49 @@ var TsRegionCompilation = class {
 		const id_base = exportName && exportName !== "default" ? `${comp_rel}#${exportName}` : comp_rel;
 		const fetchKey = this.#import_keys.fetch;
 		const renderKey = this.#import_keys.render;
-		if (marker.fetch != null && marker.render == null) throw new Error(`[ogygia] ${this.#rel_host}: \`${fetchKey}: '${marker.fetch}'\` without \`${renderKey}: 'deferred'\` — \`${fetchKey}\` is a hole's timing. Write \`${renderKey}: 'deferred', ${fetchKey}: '${marker.fetch}'\` for a hole, or \`${this.#wakeKey}: '${marker.fetch}'\` for an island.`);
+		if (marker.fetch != null && marker.render == null) throw new OgygiaError("held_fetch_without_render", {
+			host: this.#rel_host,
+			fetch_key: fetchKey,
+			render_key: renderKey,
+			wake_key: this.#wakeKey,
+			value: marker.fetch
+		});
 		if (marker.render != null) {
-			if (marker.render !== "deferred") throw new Error(marker.render === "live" ? `[ogygia] ${this.#rel_host}: \`${renderKey}: 'live'\` is not supported on a .ts import — use it in a .svelte file.` : `[ogygia] ${this.#rel_host}: unknown \`${renderKey}\` '${marker.render}'. Use 'deferred'.`);
+			if (marker.render !== "deferred") throw marker.render === "live" ? new OgygiaError("held_render_live", {
+				host: this.#rel_host,
+				render_key: renderKey
+			}) : new OgygiaError("held_render_unknown", {
+				host: this.#rel_host,
+				render_key: renderKey,
+				value: marker.render
+			});
 			if (marker.wake != null) {
-				if (marker.fetch != null) throw new Error(`[ogygia] ${this.#rel_host}: a \`${renderKey}: 'deferred'\` hole timed twice, with \`${fetchKey}: '${marker.fetch}'\` and \`${this.#wakeKey}: '${marker.wake}'\`. Keep \`${fetchKey}\`: it says when a hole's HTML arrives.`);
-				warn_once(`deferred-wake:${this.#rel_host}:ts:${marker.wake}`, `[ogygia] ${this.#rel_host}: a \`${renderKey}: 'deferred'\` hole timed with \`${this.#wakeKey}: '${marker.wake}'\`, which is deprecated. Write \`${renderKey}: 'deferred', ${fetchKey}: '${marker.wake}'\` instead: \`${fetchKey}\` says when a hole's HTML arrives. (\`${this.#wakeKey}\` is when an island's JS runs; a hole ships no JS.)`);
+				if (marker.fetch != null) throw new OgygiaError("held_hole_timed_twice", {
+					host: this.#rel_host,
+					render_key: renderKey,
+					fetch_key: fetchKey,
+					wake_key: this.#wakeKey,
+					fetch: marker.fetch,
+					wake: marker.wake
+				});
+				const wake = marker.wake;
+				warn_once(`deferred-wake:${this.#rel_host}:ts:${wake}`, () => warn("hole_wake_deprecated", {
+					host: this.#rel_host,
+					render_key: renderKey,
+					wake_key: this.#wakeKey,
+					fetch_key: fetchKey,
+					value: wake
+				}));
 			}
 			const dval = marker.fetch ?? marker.wake ?? "load";
 			let when;
 			if (DEFER_STRATEGIES.has(dval)) when = dval;
 			else if (is_media_query(dval)) when = dval;
-			else throw new Error(`[ogygia] ${this.#rel_host}: \`${fetchKey}: '${dval}'\` is not a timing. Use \`${fetchKey}: 'load' | 'idle' | 'visible' | 'interaction'\` or a media query (a hole must fetch — not 'none').`);
+			else throw new OgygiaError("held_fetch_not_timing", {
+				host: this.#rel_host,
+				fetch_key: fetchKey,
+				value: dval
+			});
 			const options = { when };
 			if (when === "visible" && this.#ctx.visibleMargin != null) options.margin = this.#ctx.visibleMargin;
 			const identity = regionIdentity(id_base, {
@@ -1853,9 +1956,20 @@ var TsRegionCompilation = class {
 			const has_fetch = attrs.has(fetchKey);
 			if (!has_render && !has_region && !has_wake && !has_fetch) continue;
 			if (inside_literal(m.index)) continue;
-			if (has_region && attrs.size > 1 || has_render && [...attrs.keys()].some((k) => k !== renderKey && k !== wakeKey && k !== fetchKey) || !has_render && has_wake && attrs.size > 1) throw new Error(`[ogygia] ${rel_host}: a held-region import on '${local}' takes ONE marker — \`${regionKey}: 'raw'\`, \`${wakeKey}: '…'\`, or \`${renderKey}: 'deferred'\` (with \`${fetchKey}\` as its timing).`);
+			if (has_region && attrs.size > 1 || has_render && [...attrs.keys()].some((k) => k !== renderKey && k !== wakeKey && k !== fetchKey) || !has_render && has_wake && attrs.size > 1) throw new OgygiaError("held_marker_mixed", {
+				host: rel_host,
+				name: local,
+				region_key: regionKey,
+				wake_key: wakeKey,
+				render_key: renderKey,
+				fetch_key: fetchKey
+			});
 			const componentPath = this.#resolve_spec(spec);
-			if (!componentPath) throw new Error(`[ogygia] ${rel_host}: held-region import '${local}' needs a module specifier ($lib/…, relative, or a package specifier like 'pkg/component').`);
+			if (!componentPath) throw new OgygiaError("region_import_no_specifier", {
+				host: rel_host,
+				name: local,
+				held: true
+			});
 			const marker = has_render ? {
 				render: attrs.get(renderKey),
 				wake: attrs.get(wakeKey),

package/dist/context-bridge.js

@@ -1,12 +1,13 @@
-import { batch } from "./ref-watch.js";
 import { REF_WIRE_KEY, ref_reducer, ref_reviver } from "./ref.js";
+import { batch } from "./ref-watch.js";
 import { register_wire_kind } from "./live-transport.js";
 import { register_derived_kind, register_store_kind } from "./store-transport.js";
 import { register_snippet_kind } from "./region-snippet.js";
 import { is_branded_fn, register_fn_kind } from "./fn-transport.js";
-import { boundary_problems, format_boundary_finding } from "./boundary.js";
+import { boundary_problems } from "./boundary.js";
 import { PAGE_CTX_MARKER, record_ctx } from "./context-registry.js";
 import { escape_script_text } from "./escape.js";
+import { warn } from "./messages/island.js";
 import { getContext, setContext as setContext$1 } from "svelte";
 import { DEV } from "esm-env";
 import { parse, stringify } from "devalue";
@@ -102,16 +103,23 @@ function warn_ctx_size(map, total) {
 	} catch {}
 	sizes.sort((a, b) => b[1] - a[1]);
 	const top = sizes.slice(0, 3).map(([k, n]) => `'${k}' ~${(n / 1024).toFixed(1)}kB`).join(", ");
-	console.warn(`[ogygia] the island context marker is ${(total / 1024).toFixed(1)}kB — it ships in every page's HTML. Biggest keys: ${top}. Slim the values, or mark host-only keys with setContext(key, value, { islands: false }).`);
+	warn("context_marker_large", {
+		size: (total / 1024).toFixed(1),
+		top
+	});
 }
 /** DEV: explain a dropped (or degraded-but-bridged) context key via the classifier. */
 function warn_boundary(key, value, dropped) {
 	const problems = boundary_problems(value, key);
 	if (dropped && problems.length === 0) {
-		console.warn(`[ogygia] context '${key}' could not be serialized for islands and was dropped.`);
+		warn("context_dropped", { key });
 		return;
 	}
-	for (const f of problems) if (dropped || f.kind === "warn") console.warn(format_boundary_finding(key, f));
+	for (const f of problems) if (dropped || f.kind === "warn") warn("context_unserializable", {
+		key,
+		path: f.path || void 0,
+		detail: f.detail
+	});
 }
 /** Decode one serialized provider payload; a corrupt payload yields nothing (never breaks hydration). */
 function parse_ctx(text) {

package/dist/context.d.ts

@@ -60,4 +60,13 @@ export declare function claim_region_css(hrefs: string[]): string[];
  * Client / no-request → false (SSR already emitted).
  */
 export declare function claimRuntimeEmit(): boolean;
+/**
+ * Note a top-level `defer: 'load'` hole's endpoint for this request: the head starts its request
+ * during the parse (early-holes.ts), written once by the handle or `document()`, which take the
+ * list. Identical holes share one endpoint, and one request. Client / no-request: nothing to note.
+ */
+export declare function note_early_hole(endpoint: string): void;
+/** This request's noted `load` hole endpoints, taken once (the head that writes them). `request`: the
+ *  one the caller holds (the handle's event); else the current render's. */
+export declare function take_early_holes(request?: Request): string[];
 export { isNested, setNested };

package/dist/context.js

@@ -140,4 +140,33 @@ function claimRuntimeEmit() {
 		return false;
 	}
 }
-export { claimRuntimeEmit, claim_kit_island, claim_region_css, documentIsCsrTrue, error_route_is_csr_true, isHoleInline, isInLake, isInLiveSnippet, isNested, isOgygiaPage, route_is_csr_true, setHoleInline, setInLake, setInLiveSnippet, setNested };
+/** Each request's noted `load` hole endpoints, by its `Request`: the render's event and the handle's
+*  are not one object, the request they carry is. */
+const early_holes = /* @__PURE__ */ new WeakMap();
+/**
+* Note a top-level `defer: 'load'` hole's endpoint for this request: the head starts its request
+* during the parse (early-holes.ts), written once by the handle or `document()`, which take the
+* list. Identical holes share one endpoint, and one request. Client / no-request: nothing to note.
+*/
+function note_early_hole(endpoint) {
+	try {
+		const { request } = getRequestEvent();
+		let seen = early_holes.get(request);
+		if (!seen) early_holes.set(request, seen = /* @__PURE__ */ new Set());
+		seen.add(endpoint);
+	} catch {}
+}
+/** This request's noted `load` hole endpoints, taken once (the head that writes them). `request`: the
+*  one the caller holds (the handle's event); else the current render's. */
+function take_early_holes(request) {
+	if (!request) try {
+		request = getRequestEvent().request;
+	} catch {
+		return [];
+	}
+	const seen = early_holes.get(request);
+	if (!seen) return [];
+	early_holes.delete(request);
+	return [...seen];
+}
+export { claimRuntimeEmit, claim_kit_island, claim_region_css, documentIsCsrTrue, error_route_is_csr_true, isHoleInline, isInLake, isInLiveSnippet, isNested, isOgygiaPage, note_early_hole, route_is_csr_true, setHoleInline, setInLake, setInLiveSnippet, setNested, take_early_holes };

package/dist/document.d.ts

@@ -13,7 +13,7 @@ export interface DocumentOptions {
   lang?: string;
   /** Seed for `$app/state` inside islands (`page.data`/`params`/`url`, `route.id`, `form`). The router
    *  passes it so islands on a rendered page read `$page` just like on a Kit-served page. Promises in
-   *  `data`/`form` aren't streamed here — a non-serializable leaf drops that one field. */
+   *  `data`/`form` aren't streamed here — a non-serializable leaf is left out where it sits. */
   pageState?: {
     url?: {
       href?: string;

package/dist/document.js

@@ -8,6 +8,9 @@ import { kit_render_context } from "./server/kit-context.js";
 import { open_ask_scope, read_seed_ask, record_page } from "./page-seed-registry.js";
 import { shape_page_data } from "./server/seed-shape.js";
 import { escape_text } from "./escape.js";
+import { take_early_holes } from "./context.js";
+import { early_holes_head } from "./early-holes-head.js";
+import { add_early_holes_csp, with_early_holes_meta_csp } from "./server/early-holes-csp.js";
 import { page_declares_dev_hmr_script, page_declares_router_meta, page_declares_runtime_script, runtime_first } from "./server/head-presence.js";
 import { render } from "svelte/server";
 import { stringify } from "devalue";
@@ -95,6 +98,8 @@ async function document(of, options = {}) {
 	if (enabled && !page_declares_router_meta(head_so_far())) head.push(`<meta name="ogygia-router" content="${viewTransitions ? "vt" : "plain"}">`);
 	if (runtime_url && !page_declares_runtime_script(head_so_far())) head.push(runtime_bootstrap());
 	if (dev_hmr_url && !page_declares_dev_hmr_script(head_so_far())) head.push(`<script type="module" data-ogygia-dev-hmr src="${dev_hmr_url}"><\/script>`);
+	const early = take_early_holes();
+	head.push(early_holes_head(early));
 	const ask = options.pageState ? read_seed_ask() : void 0;
 	if (options.pageState && (!ask || ask.wanted)) {
 		const s = options.pageState;
@@ -113,10 +118,11 @@ async function document(of, options = {}) {
 			head.push(`<script type="application/ogygia-page" data-ogygia-page${format}>${payload.text}<\/script>`);
 		}
 	}
-	const html = `<!doctype html>\n<html lang="${escape_text(options.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">` + runtime_first(head.join(""), null) + `</head><body>${r.body}</body></html>`;
+	const html = `<!doctype html>\n<html lang="${escape_text(options.lang ?? "en")}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">` + (early.length ? with_early_holes_meta_csp(runtime_first(head.join(""), null)) : runtime_first(head.join(""), null)) + `</head><body>${r.body}</body></html>`;
 	const headers = new Headers({ "content-type": "text/html; charset=utf-8" });
 	if (!current_facts()?.storable) headers.set("cache-control", "no-store");
 	if (options.headers) for (const [k, v] of new Headers(options.headers)) headers.set(k, v);
+	if (early.length) add_early_holes_csp(headers);
 	return new Response(html, {
 		status: options.status ?? 200,
 		headers

package/dist/early-holes-head.d.ts

@@ -0,0 +1,5 @@
+/** The early start's script tag, the same bytes on every page (its CSP hash is computed from it). */
+export declare const EARLY_HOLES_TAG: string;
+/** The head's early start for `endpoints` (the request's `load` holes, each once): the data block,
+ *  then the script that reads it. Nothing for none. */
+export declare function early_holes_head(endpoints: readonly string[]): string;

package/dist/early-holes-head.js

@@ -0,0 +1,20 @@
+import { EARLY_HOLES_ID, EARLY_HOLES_KEY, start_early_holes } from "./early-holes.js";
+import { script } from "./script.js";
+// src/early-holes-head.ts
+/**
+* The head's early start (./early-holes.ts), as tags: written by the handle and `document()`, and
+* read by the tests that run it. Kept apart from ./early-holes.ts so the runtime, which only reads
+* the global, never loads `script()`.
+*/
+/** The early start's script tag, the same bytes on every page (its CSP hash is computed from it). */
+const EARLY_HOLES_TAG = script(start_early_holes, EARLY_HOLES_ID, EARLY_HOLES_KEY);
+/** The head's early start for `endpoints` (the request's `load` holes, each once): the data block,
+*  then the script that reads it. Nothing for none. */
+function early_holes_head(endpoints) {
+	if (endpoints.length === 0) return "";
+	return script({
+		json: [...endpoints],
+		id: EARLY_HOLES_ID
+	}) + EARLY_HOLES_TAG;
+}
+export { EARLY_HOLES_TAG, early_holes_head };