@ogygia/core 0.12.3 → 0.13.0

package/dist/server/rules.js

@@ -0,0 +1,64 @@
+import { Rules } from "../rules.js";
+import { warn } from "../messages/server.js";
+import { observe } from "@ogygia/machine";
+// src/server/rules.ts
+/**
+* THE SERVER'S RULES (#313, ../rules.ts): what is always true of the server, checked a task after
+* each response ends (in dev, and in a build made with `OGYGIA_RULES=1`), printed with its code.
+*
+* - `rule_request_scope_open`: a request's scope (its timers, streams, fetches) is closed once its
+*   response has ended.
+* - `rule_flight_kept_failure`: no flight keeps a failure: an answer kept is never an error.
+*
+* Each area tells this module what it holds (`note_response_end`) only when rules are on: every call
+* site folds out of a build without them.
+*/
+/** The server's rules. */
+const server_rules = /* @__PURE__ */ new Rules();
+/** Request scopes whose response has ended, until a check sees them closed. */
+const ended = /* @__PURE__ */ new Set();
+/** A response ended (its body read to the end, cancelled, or none): its request's scope must be
+*  closed by the time the next check runs. */
+function note_response_end(owner) {
+	if (!installed) return;
+	ended.add(owner);
+	check_soon();
+}
+function request_scopes_closed() {
+	let open = 0;
+	for (const owner of ended) if (owner.closed) ended.delete(owner);
+	else open++;
+	return open === 0 ? null : `${open} request scope(s) still open after their response ended`;
+}
+/** The flights' entries that keep an error as their answer now, each with what it keeps. An entry
+*  leaves when it moves on (dropped, or a fresh answer kept): the rule is about what is kept now, so
+*  a check (a simulated run, the next response in dev) sees its own breaks, not an earlier one's. */
+const kept_failures = /* @__PURE__ */ new Map();
+function no_kept_failure() {
+	if (kept_failures.size === 0) return null;
+	return [...kept_failures.values()].slice(0, 10).join("; ");
+}
+let installed = false;
+let pending = false;
+/** Checks every rule a task from now (once, however many responses ask), and says what broke. */
+function check_soon() {
+	if (pending) return;
+	pending = true;
+	setTimeout(() => {
+		pending = false;
+		server_rules.say((code, detail) => warn(code, { detail }));
+	}, 0);
+}
+/** Rules on: checked after each response, and what broke is said with its code. */
+function install_server_rules() {
+	if (installed) return;
+	installed = true;
+	server_rules.add("rule_request_scope_open", request_scopes_closed);
+	server_rules.add("rule_flight_kept_failure", no_kept_failure);
+	observe((name, _from, to, machine) => {
+		const answer = to?.kind === "kept" ? to.answer : void 0;
+		if (answer instanceof Error) kept_failures.set(machine, `"${name}" kept ${answer.name}: ${answer.message.slice(0, 120)}`);
+		else if (kept_failures.size !== 0) kept_failures.delete(machine);
+	});
+}
+export { install_server_rules, note_response_end, server_rules };

package/dist/server/signing-key.js

@@ -1,3 +1,4 @@
+import { OgygiaError, warn } from "../messages/server.js";
 import { buildHadSecret, buildKey } from "virtual:ogygia/secret";
 import { sign } from "virtual:ogygia/sign";
 import { building } from "$app/env";
@@ -24,23 +25,27 @@ const SOURCE_NAME = {
 	env: "OGYGIA_SECRET",
 	build: "this build's random key"
 };
+const slots = globalThis;
 function slot() {
-	const g = globalThis;
-	return g[SLOT] ??= {};
+	return slots[SLOT] ?? { kind: "undecided" };
 }
 function signing_key() {
 	const s = slot();
-	if (s.key) return s.key;
+	if (s.kind === "decided") return s.key;
 	const from_env = typeof process !== "undefined" && process.env?.OGYGIA_SECRET || "";
-	const [secret, source] = s.option ? [s.option, "option"] : from_env ? [from_env, "env"] : [buildKey, "build"];
-	s.key = {
+	const [secret, source] = s.kind === "secret" ? [s.option, "option"] : from_env ? [from_env, "env"] : [buildKey, "build"];
+	const key = {
 		secret,
 		stable: source !== "build",
 		fp: key_fingerprint(secret),
 		source
 	};
-	if (!s.key.stable && !import.meta.env.DEV) warn_build_key();
-	return s.key;
+	slots[SLOT] = {
+		kind: "decided",
+		key
+	};
+	if (!key.stable && !import.meta.env.DEV) warn_build_key();
+	return key;
 }
 /**
 * Record the app's `handle({ secret })`. A blank one counts as none (an app can pass a value that may
@@ -50,15 +55,23 @@ function signing_key() {
 function configure_signing_secret(secret) {
 	if (!secret?.trim()) return;
 	const s = slot();
-	const decided = s.key?.secret ?? s.option;
-	if (decided === void 0 || decided === secret) {
-		s.option = secret;
+	if (s.kind === "undecided") {
+		slots[SLOT] = {
+			kind: "secret",
+			option: secret
+		};
 		return;
 	}
-	const from = s.key ? `${SOURCE_NAME[s.key.source]}, decided by an earlier mint or verify` : "another handle({ secret })";
-	const message = `[ogygia] handle({ secret }) names key ${key_fingerprint(secret)}, but this server already signs with key ${key_fingerprint(decided)} (from ${from}). The first key stays: pass one secret, before anything renders.`;
-	if (import.meta.env.DEV) throw new Error(message);
-	console.error(message);
+	const decided = s.kind === "decided" ? s.key.secret : s.option;
+	if (decided === secret) return;
+	const from = s.kind === "decided" ? `${SOURCE_NAME[s.key.source]}, decided by an earlier mint or verify` : "another handle({ secret })";
+	const error = new OgygiaError("secret_conflict", {
+		key: key_fingerprint(secret),
+		decided: key_fingerprint(decided),
+		from
+	});
+	if (import.meta.env.DEV) throw error;
+	console.error(error);
 }
 function key_fingerprint(secret) {
 	return sign(secret, "ogygia:key-fp").slice(0, 8);
@@ -70,12 +83,12 @@ function warn_build_key() {
 	const K = Symbol.for("ogygia.build-key-warned");
 	if (g[K]) return;
 	g[K] = true;
-	if (building) console.warn("[ogygia] prerendered page mints region capabilities signed with a per-build random key — they stop verifying after your next deploy while the static HTML lives on. Set a stable OGYGIA_SECRET env var (or pass it to handle({ secret })) so prerendered holes survive redeploys.");
-	else if (buildHadSecret) console.error("[ogygia] OGYGIA_SECRET was set when this app was built but is not set where it runs: region capabilities are signed with this build's random key, so every hole minted by another deployment (another backend behind the same CDN, the previous deploy) is refused (403, x-ogygia-deny: foreign-key). Set OGYGIA_SECRET in the server's runtime environment, or pass it to handle({ secret }) (e.g. from $env/static/private).");
-	else console.warn("[ogygia] OGYGIA_SECRET is not set: region capabilities are signed with this build's random key, so a page cached across a deploy, or served by another deployment than its islands endpoint, gets its holes refused (403, x-ogygia-deny: foreign-key). Set a stable OGYGIA_SECRET, or pass one to handle({ secret }).");
+	if (building) warn("build_key_prerender");
+	else if (buildHadSecret) console.error(new OgygiaError("secret_missing_at_runtime"));
+	else warn("secret_missing");
 }
 /** Tests: forget the decided key and the app's secret. */
 function reset_signing_key() {
-	delete globalThis[SLOT];
+	delete slots[SLOT];
 }
 export { configure_signing_secret, key_fingerprint, reset_signing_key, signing_key };

package/dist/server/stream-regions.d.ts

@@ -1,5 +1,18 @@
+import { Scope } from "@ogygia/machine";
 /** Build a parcel `<template data-ogygia-slot="…">…rendered html…</template>` (length-framed when
  *  the html carries a `</template` of its own). */
 export declare function build_parcel(slot: string, html: string): string;
 /** The done-sentinel parcel (empty template) the client watches to end the batch. */
-export declare function done_parcel(): string;
+export declare function done_parcel(): string;
+/** One region call's answer in a batch: its slot (the capability signature) and its HTML. Null:
+ *  the call is left out (the client fetches it on its own). */
+export type BatchAnswer = {
+  slot: string;
+  html: string;
+} | null;
+/**
+ * The batch's frame stream: every call renders at once, and each answer goes out as its parcel the
+ * moment it settles, whatever the order; the done sentinel ends it. `render` is handed the batch's
+ * signal: it aborts when the stream is cancelled, or when `owner` (the request's) ends first.
+ */
+export declare function batch_stream(calls: readonly string[], render: (endpoint: string, signal: AbortSignal) => Promise<BatchAnswer>, owner?: Scope): ReadableStream<Uint8Array>;

package/dist/server/stream-regions.js

@@ -1,3 +1,4 @@
+import { STALE, machine } from "@ogygia/machine";
 // src/server/stream-regions.ts
 /**
 * Region parcels for the batch endpoint (single-flight navigation, a page's first-load holes, OOO).
@@ -11,7 +12,7 @@
 * decoded string counts in — so its content can never close the box or forge a parcel for another
 * slot, and it no longer falls back to a second request.
 *
-* Pure (no I/O, no Kit) so it stays unit-testable.
+* No I/O and no Kit (the batch stream is handed its render), so it stays unit-testable.
 */
 /** Sentinel slot appended once a batch finishes, so waiting regions know it is complete. */
 const STREAM_DONE_SLOT = "__ogygia_done__";
@@ -33,4 +34,39 @@ function build_parcel(slot, html) {
 function done_parcel() {
 	return `<template data-ogygia-slot="${STREAM_DONE_SLOT}"></template>`;
 }
-export { build_parcel, done_parcel };
+const batch_def = machine()({
+	name: "batch stream",
+	initial: "streaming",
+	steps: {
+		streaming: ["ended", "cancelled"],
+		ended: [],
+		cancelled: []
+	}
+});
+/**
+* The batch's frame stream: every call renders at once, and each answer goes out as its parcel the
+* moment it settles, whatever the order; the done sentinel ends it. `render` is handed the batch's
+* signal: it aborts when the stream is cancelled, or when `owner` (the request's) ends first.
+*/
+function batch_stream(calls, render, owner) {
+	const encoder = new TextEncoder();
+	const batch = batch_def.create();
+	owner?.defer(() => {
+		batch.move("streaming", "cancelled");
+	});
+	return new ReadableStream({
+		async start(controller) {
+			const streaming = batch.now;
+			if (await batch.scope.task((signal) => Promise.all(calls.map(async (endpoint) => {
+				const out = await render(endpoint, signal).catch(() => null);
+				if (out && batch.now === streaming) controller.enqueue(encoder.encode(build_parcel(out.slot, out.html)));
+			}))) === STALE || !batch.move("streaming", "ended")) return;
+			controller.enqueue(encoder.encode(done_parcel()));
+			controller.close();
+		},
+		cancel() {
+			batch.move("streaming", "cancelled");
+		}
+	});
+}
+export { batch_stream, build_parcel, done_parcel };

package/dist/shared-state.js

@@ -1,3 +1,4 @@
+import { OgygiaError } from "./messages/island.js";
 import { parse, stringify } from "devalue";
 import { createSubscriber } from "svelte/reactivity";
 // src/shared-state.ts
@@ -46,7 +47,10 @@ function snapshot(name, value) {
 	try {
 		return parse(stringify(value));
 	} catch (e) {
-		throw new Error(`[ogygia] SharedState '${name}': values must be plain data (devalue-serializable — JSON, Date, Map, Set, BigInt, RegExp). Functions, class instances, and DOM nodes do not cross build boundaries — share facts, not live objects. (${e instanceof Error ? e.message : e})`);
+		throw new OgygiaError("shared_state_not_plain", {
+			name,
+			reason: e instanceof Error ? e.message : String(e)
+		});
 	}
 }
 var SharedState = class {

package/dist/shims/app-navigation.js

@@ -1,14 +1,15 @@
 import { kit_bridge } from "./kit-bridge.js";
 import { refresh_remote_instances } from "./kit-remote/remote-cache.js";
 import { bind_to_component } from "../runtime/nav-hooks.js";
+import { OgygiaError } from "../messages/island.js";
 // src/shims/app-navigation.ts
 const kit = () => kit_bridge()?.navigation ?? null;
 const og = () => globalThis[Symbol.for("ogygia.nav")] ?? null;
 /** No runtime on this document at all (neither Kit's nor ogygia's): the browser navigates. */
 function browser_goto(url, opts = {}) {
 	const target = new URL(url, location.href);
-	if (target.protocol !== "http:" && target.protocol !== "https:") throw new Error("[ogygia] goto() only supports http(s) URLs");
-	if (target.origin !== location.origin && !opts.external) throw new Error("[ogygia] goto() only supports same-origin URLs (pass { external: true } to leave)");
+	if (target.protocol !== "http:" && target.protocol !== "https:") throw new OgygiaError("goto_not_http");
+	if (target.origin !== location.origin && !opts.external) throw new OgygiaError("goto_cross_origin");
 	if (opts.replaceState) location.replace(target.href);
 	else location.assign(target.href);
 	return Promise.resolve();

package/dist/shims/page-store.svelte.js

@@ -1,4 +1,5 @@
 import { foreign_hydrate } from "../current-region.js";
+import { warn } from "../messages/island.js";
 // src/shims/page-store.svelte.ts
 const FALLBACK = {
 	url: typeof location !== "undefined" ? new URL(location.href) : new URL("http://localhost/"),
@@ -32,7 +33,9 @@ var PageState = class {
 		this.state = s.state ?? {};
 		for (const fn of this.#subscribers) try {
 			fn();
-		} catch {}
+		} catch (error) {
+			report_thrown(error);
+		}
 	}
 	reset() {
 		this.set({
@@ -51,6 +54,13 @@ var PageState = class {
 		return () => this.#subscribers.delete(fn);
 	}
 };
+/** report-thrown.ts's `report_thrown`, here in full: island-side code never imports a module the
+*  runtime's boot imports (runtime-boot-svelte-free.test.ts), and the boot's ref watchers use it. */
+function report_thrown(error) {
+	const report = globalThis.reportError;
+	if (typeof report === "function") report(error);
+	else console.error(error);
+}
 const PAGE_STATE_KEY = Symbol.for("ogygia.page-state");
 const global_scope = globalThis;
 const page_state = global_scope[PAGE_STATE_KEY] ??= new PageState();
@@ -72,6 +82,10 @@ function warn_foreign_page_read(expr) {
 	const f = foreign_hydrate();
 	if (!f || warned_foreign_entries.has(f.entry)) return;
 	warned_foreign_entries.add(f.entry);
-	console.warn(`[ogygia] ${expr} was read inside a mounted MFE island (${f.entry}, from ${f.origin}).\nIn the browser this is the SHELL's page, not the MFE's. The HTML you see was rendered with the MFE's own load data, so this island will repaint with different values after hydrate.\nPass the value as a prop, or read it with a remote function.`);
+	warn("foreign_page_read", {
+		expr,
+		entry: f.entry,
+		origin: f.origin
+	});
 }
 export { PageState, page_state, reset_page, set_page, subscribe_page, warn_foreign_page_read };

package/dist/source.js

@@ -1,4 +1,5 @@
 import { fnv1a } from "./runtime/hash.js";
+import { report_thrown } from "./report-thrown.js";
 // src/source.ts
 /**
 * DATA SOURCES — `import.meta.og.source(fn)`, the RUNTIME half (the compiler rewrites the macro to
@@ -29,10 +30,14 @@ function set_source_observer(fn) {
 function record_source_read(tag) {
 	try {
 		slots.recorder?.(tag);
-	} catch {}
+	} catch (error) {
+		report_thrown(error);
+	}
 	try {
 		slots.observer?.(tag);
-	} catch {}
+	} catch (error) {
+		report_thrown(error);
+	}
 }
 /** The identity stamp — read by `postrender.invalidate(fn, args)`. */
 const SOURCE_ID = Symbol.for("ogygia.source.id");

package/dist/store-transport.js

@@ -1,5 +1,6 @@
 import { wire } from "./live-transport.js";
 import { mint, register_kind, resolve } from "./ref.js";
+import { OgygiaError, warn } from "./messages/island.js";
 import { derived, get, writable } from "svelte/store";
 // src/store-transport.ts
 /**
@@ -81,7 +82,7 @@ function mark_store(store, tag) {
 			enumerable: false
 		});
 	} catch {
-		if (typeof console !== "undefined") console.warn(`[ogygia] store "${tag}": the store object is not extensible (frozen/sealed), so it cannot carry its factory brand — it will cross boundaries as a plain writable (custom methods unavailable). Brand before freezing, or leave the store extensible.`);
+		if (typeof console !== "undefined") warn("store_not_extensible", { tag });
 	}
 	return store;
 }
@@ -100,12 +101,15 @@ function register_store_kind() {
 			const t = ref.t ?? GENERIC_TAG;
 			const factory = t === GENERIC_TAG ? void 0 : store_registry().factories.get(t);
 			if (t !== GENERIC_TAG && factory === void 0) {
-				if (typeof console !== "undefined") console.warn(`[ogygia] store "${t}": factory not loaded in this bundle — degraded to a plain writable (custom methods unavailable). Import the factory's module in the island (or its graph) so \`__register_store_factory\` runs there.`);
+				if (typeof console !== "undefined") warn("store_factory_missing", { tag: t });
 				return writable(ref.d);
 			}
 			const built = factory ? factory(ref.d) : writable(ref.d);
 			if (built === null || typeof built !== "object") {
-				if (typeof console !== "undefined") console.warn(`[ogygia] store "${t}": factory returned ${type_of(built)} while rebuilding — degraded to a plain writable (custom methods unavailable). A store factory must return a store on every call; move environment guards inside the factory body.`);
+				if (typeof console !== "undefined") warn("store_factory_bad_rebuild", {
+					tag: t,
+					got: type_of(built)
+				});
 				return writable(ref.d);
 			}
 			return built;
@@ -160,7 +164,10 @@ function __og_store(tag, factory) {
 		if (product === null || typeof product !== "object") {
 			if (!warned_unbranded.has(tag) && typeof console !== "undefined") {
 				warned_unbranded.add(tag);
-				console.warn(`[ogygia] store "${tag}": factory returned ${type_of(product)} — nothing to brand, value passed through as-is. Fine for a client-only store; a store that must cross an island boundary has to exist on the server too — return e.g. writable(seed) under your guard and gate the side effects inside the factory instead.`);
+				warn("store_factory_unbranded", {
+					tag,
+					got: type_of(product)
+				});
 			}
 			return product;
 		}
@@ -221,7 +228,7 @@ function register_derived_kind() {
 		},
 		decode(ref) {
 			const d = ref.d;
-			if (typeof d.f !== "function") throw new Error("[ogygia] cannot resume og_derived: its formula did not cross — mark it with import.meta.og.$ at the og_derived call site so it travels as a fn ref.");
+			if (typeof d.f !== "function") throw new OgygiaError("og_derived_formula_missing");
 			return og_derived(d.single ? d.s[0] : d.s, d.f, d.seed);
 		}
 	});

package/dist/transport.js

@@ -6,6 +6,7 @@ import { register_wire_kind } from "./live-transport.js";
 import { register_derived_kind, register_store_kind } from "./store-transport.js";
 import { register_snippet_kind } from "./region-snippet.js";
 import { register_fn_kind } from "./fn-transport.js";
+import { OgygiaError } from "./messages/island.js";
 // src/transport.ts
 /**
 * `ogygiaTransport` — the SvelteKit `transport` entry that lets a held region cross the wire.
@@ -38,7 +39,7 @@ function encode_region(value) {
 			return pack(f.id, props, sign(f.id, props), f.module, f.hydrate, f.hydrateMargin, f.html);
 		}
 		if (typeof f.html === "string") return pack("", f.props ?? {}, "", "", void 0, void 0, f.html);
-		throw new Error("[ogygia] a held region reached the wire but its component is a plain import, so nothing built a chunk for it. `await` the region before returning it from a remote/load — an awaited region bakes its SSR HTML and crosses as an HTML-only ticket. Or import the component `with { region: 'raw' }` (or a `wake:` mark) to make it a signed, fetchable capability. On a csr=false page you can also skip the wire entirely: call `get()` in a universal `+page.ts` load / the component — its data reaches the render by reference.");
+		throw new OgygiaError("held_region_plain_import");
 	}
 }
 /** The region DECODE law (single-flight frame write for baked HTML + deferred rebuild),
@@ -88,7 +89,7 @@ function register_region_kind() {
 		},
 		encode(value) {
 			const packed = encode_region(value);
-			if (packed === false) throw new Error("[ogygia] region kind claimed a non-region value");
+			if (packed === false) throw new OgygiaError("region_kind_mismatch");
 			return { d: packed };
 		},
 		decode(ref) {

package/dist/vite/index.js

@@ -4,8 +4,8 @@ import { island_sourcemaps_plugin } from "./sourcemaps.js";
 import { server_sourcemaps_plugin } from "./server-sourcemaps.js";
 import { install_dev_client_maps, install_dev_maps, install_dev_page_keys } from "./dev-maps.js";
 import { CLIENT_BINDING_STUB, DEFAULT_IMPORT_KEYS, asRegionLocals, import_keys_hint, is_island_path, islandChunkFileName, islandId, islandPublicUrl, normalize_import_keys, wrapperVirtualId } from "../compiler/region/transform.js";
-import { regionId, regionIdentity, strategyKey } from "../compiler/region/identity.js";
 import { rewrite_lake_import_to_placeholder } from "../compiler/region/emit.js";
+import { regionId, regionIdentity, strategyKey } from "../compiler/region/identity.js";
 import { debarrel } from "../compiler/debarrel/plugin.js";
 import { definePlugin, find_plugins, resolve_plugins } from "./plugin-api.js";
 import { assert_no_legacy_options, resolve_options, validate_region_presets } from "./options.js";
@@ -34,7 +34,8 @@ import { async_twin_redirect, svelte_async_enabled } from "./late-island.js";
 import { flags_manifest } from "../compiler/flags.js";
 import { RESOLVED, V_ROUTER_CSS, V_ROUTE_CONFIG, V_ROUTE_CSR, V_SERVER_ISLANDS, V_SERVER_MANIFEST } from "../compiler/ids.js";
 import { OWN_PACKAGE_NAMES, is_own_specifier } from "../own-package.js";
-import { APP_SHIMS, CLIENT_BINDING_STUB_FILE, HMAC_MODULE, KIT_REMOTE_CLIENT, KIT_REMOTE_STATE, OGYGIA_INJECTED_FILES, OGYGIA_INJECTED_IMPORTS, OGYGIA_REGION_MODULES, PKG_ROOT, PKG_ROOT_ID, REGION_ENDPOINT_MODULE, RUNTIME_DIR, RUNTIME_HASH, STUB_CLIENT, STUB_PATHS, STUB_STATE, real_posix, scan_entry_pattern } from "./paths.js";
+import { APP_SHIMS, CLIENT_BINDING_STUB_FILE, HMAC_MODULE, KIT_REMOTE_CLIENT, KIT_REMOTE_STATE, OGYGIA_INJECTED_FILES, OGYGIA_INJECTED_IMPORTS, OGYGIA_REGION_MODULES, OGYGIA_VERSION, PKG_ROOT, PKG_ROOT_ID, REGION_ENDPOINT_MODULE, RUNTIME_DIR, RUNTIME_HASH, STUB_CLIENT, STUB_PATHS, STUB_STATE, real_posix, scan_entry_pattern } from "./paths.js";
+import { OgygiaError, line, warn } from "../messages/build.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -44,6 +45,7 @@ import { loadEnv } from "vite";
 const KIT_CLIENT_APP_RE = /\/generated\/(?:build\/|dev\/)?client(-optimized)?\/app\.js$/;
 const ROUTE_HOST_OR_OPTION_RE = /[\\/]\+(page|layout)(\.server)?\.(svelte|js|ts)$/;
 const KIT_PAGE_THREAD = "\nimport { page as __og_kit_page, navigating as __og_kit_nav } from '$app/state';\nimport * as __og_kit_navigation from '$app/navigation';\nglobalThis[Symbol.for('ogygia.kit-page')] = { page: __og_kit_page, navigating: __og_kit_nav, navigation: __og_kit_navigation };\n";
+const KIT_DISCLOSE_VERSION = `((globalThis.__ogygia ??= {}).v ??= new Set()).add(${JSON.stringify(OGYGIA_VERSION)});\n`;
 /** css-ish file the dev bridge manages (mirrors the bridge's glob). */
 const DEV_CSS_FILE_RE = /\.(css|scss|sass|less|styl)$/;
 const CSS_EXT_RE = /\.css$/;
@@ -290,9 +292,11 @@ function ogygia(options = {}) {
 							__OGYGIA_SERVER_DELTA__: JSON.stringify(server_delta),
 							__OGYGIA_DEVTOOLS__: JSON.stringify(devtools_effective),
 							__OGYGIA_DEVTOOLS_LAZY__: JSON.stringify(devtools_lazy),
+							__OGYGIA_RULES__: JSON.stringify(process.env.OGYGIA_RULES === "1"),
 							__OGYGIA_BEACON__: JSON.stringify(measure || devtools_effective),
 							__OGYGIA_CLIENT_PLUGINS__: JSON.stringify(client_plugins.length > 0),
-							__OGYGIA_KIT_MAJOR__: JSON.stringify(kit_major(path.resolve(userConfig.root ?? ".")))
+							__OGYGIA_KIT_MAJOR__: JSON.stringify(kit_major(path.resolve(userConfig.root ?? "."))),
+							__OGYGIA_VERSION__: JSON.stringify(OGYGIA_VERSION)
 						},
 						server: { fs: { allow: [PKG_ROOT] } },
 						build: { rolldownOptions: { preserveEntrySignatures: "exports-only" } }
@@ -305,7 +309,10 @@ function ogygia(options = {}) {
 				svelte_async = svelte_async_enabled(config.plugins);
 				if (config.command === "serve") {
 					const own = (config.optimizeDeps?.include ?? []).filter((d) => is_own_specifier(d));
-					if (own.length) config.logger.warn(`[ogygia] optimizeDeps.include lists ${own.join(", ")}: ogygia must not be pre-bundled in dev (the page would run two copies of its runtime, and islands with snippet props fail to hydrate). Remove ${own.length === 1 ? "it" : "them"}.`);
+					if (own.length) config.logger.warn(line("optimize_deps_includes_ogygia", {
+						specifiers: own.join(", "),
+						count: own.length
+					}));
 				}
 				const app_dir_define = config.define?.["__SVELTEKIT_APP_DIR__"];
 				if (typeof app_dir_define === "string") try {
@@ -338,7 +345,7 @@ function ogygia(options = {}) {
 				}
 				const env_secret = process.env.OGYGIA_SECRET?.trim() || "";
 				if (env_secret) {
-					if (is_build && !secret_has_min_entropy(env_secret)) throw new Error(`[ogygia] OGYGIA_SECRET is too short for production builds (need ≥16 UTF-8 bytes).`);
+					if (is_build && !secret_has_min_entropy(env_secret)) throw new OgygiaError("secret_too_short", { min_bytes: 16 });
 					id_salt = derive_id_salt(env_secret);
 				} else id_salt = "";
 				({kit_wire_path, kit_remote_index, universal_hooks, client_hooks, kit_transport_init} = resolve_kit_paths(root));
@@ -418,7 +425,7 @@ function ogygia(options = {}) {
 						emitRuntime: emit_runtime,
 						loaded
 					});
-					if (skipped && isMainThread) console.log(`[ogygia] ${skipped} island chunk(s) not emitted: their host modules are not in the server bundle (unreachable from this build's routes).`);
+					if (skipped && isMainThread) console.log(line("island_chunks_not_emitted", { count: skipped }));
 					compiled_css.clear();
 					const tree_css = tree_css_walk(this);
 					router_css_refs.clear();
@@ -504,7 +511,7 @@ function ogygia(options = {}) {
 					fs.mkdirSync(path.dirname(handoff), { recursive: true });
 					fs.writeFileSync(handoff, JSON.stringify(compiler.ssr_transformed_hosts()));
 				} catch (e) {
-					if (isMainThread) console.warn("[ogygia] could not write the server-leg island handoff:", e);
+					if (isMainThread) warn("island_handoff_write_failed", e);
 				}
 				if (__P) {
 					const keys = [...__outHash.keys()].sort();
@@ -571,7 +578,7 @@ function ogygia(options = {}) {
 				}
 				const ssr = options?.ssr === true;
 				if (!ssr && source === "__sveltekit/remote") {
-					if (!kit_remote_index) throw new Error("[ogygia] could not locate Kit's client remote-functions (src). Use an @sveltejs/kit that publishes its `src/` (2.70.2 or later, or 3.x).");
+					if (!kit_remote_index) throw new OgygiaError("kit_remote_src_missing");
 					return kit_remote_index;
 				}
 				if (!ssr && importer && importer.includes("/remote-functions/")) {
@@ -641,7 +648,7 @@ function ogygia(options = {}) {
 			},
 			async transform(code, id, options) {
 				let source = code;
-				if (!options?.ssr && KIT_CLIENT_APP_RE.test(id)) source += KIT_PAGE_THREAD;
+				if (!options?.ssr && KIT_CLIENT_APP_RE.test(id)) source += KIT_PAGE_THREAD + KIT_DISCLOSE_VERSION;
 				const result = await compiler.transform_module(source, id, {
 					ssr: options?.ssr === true,
 					emitFile: (chunk) => this.emitFile(chunk)
@@ -739,7 +746,7 @@ function ogygia(options = {}) {
 					fs.mkdirSync(dir, { recursive: true });
 					const manifest = flags_manifest(program.flag_sites);
 					fs.writeFileSync(path.join(dir, "flags-manifest.json"), JSON.stringify(manifest, null, "	") + "\n");
-					console.log(`[ogygia] flags manifest: ${manifest.names.length} flag(s) → node_modules/.ogygia/flags-manifest.json`);
+					console.log(line("flags_manifest_written", { count: manifest.names.length }));
 				} catch {}
 				await follow_pending_page_calls(program, (s, importer) => this.resolve(s, importer));
 				const remote_hash = (id) => remote_hash_of(id, process.cwd());

package/dist/vite/kit-dirs.js

@@ -1,4 +1,5 @@
 import { DEFAULT_KIT_DIRS, set_kit_dirs, set_kit_inline_style_threshold } from "../compiler/kit.js";
+import { warn } from "../messages/build.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -47,7 +48,12 @@ async function kit_options_from_file(root) {
 	try {
 		return (await import(pathToFileURL(file).href)).default?.kit ?? {};
 	} catch (e) {
-		console.warn(`[ogygia] could not read ${path.relative(root, file)} for kit.files.routes / kit.outDir — using the defaults (${DEFAULT_KIT_DIRS.routes}, ${DEFAULT_KIT_DIRS.out}). ${e instanceof Error ? e.message : String(e)}`);
+		warn("kit_config_unreadable", {
+			file: path.relative(root, file),
+			routes: DEFAULT_KIT_DIRS.routes,
+			out: DEFAULT_KIT_DIRS.out,
+			reason: e instanceof Error ? e.message : String(e)
+		});
 		return null;
 	}
 }

package/dist/vite/options.d.ts

@@ -178,7 +178,8 @@ export interface OgygiaOptions {
    */
   standalone?: boolean;
 }
-/** The rename map: a legacy key errors with its new spelling, never silently no-ops. */
+/** The rename map (`RETIRED_OPTIONS`, with the messages): a legacy key errors with its new
+ *  spelling, never silently no-ops. */
 export declare function assert_no_legacy_options(options: OgygiaOptions): void;
 /**
  * Config-time region-preset validation — the transform re-checks on USE (with file/line context), but

package/dist/vite/options.js

@@ -1,22 +1,9 @@
+import { OgygiaError, RETIRED_OPTIONS } from "../messages/build.js";
 // src/vite/options.ts
-/**
-* Retired option spellings. Detected at config load and answered with the exact new spelling — a
-* rename map, never silent aliasing (a legacy key that silently did nothing would un-tune real apps).
-*/
-const LEGACY_OPTION_RENAMES = {
-	regions: "`regions` is gone — its keys sit at the root now: write `visible`, `presets`, `ttl` and `maxPageAge` directly in `ogygia({ … })`.",
-	continuity: "`continuity` is gone — form continuity rides the router. Write `router: { forms: false }` to disable it.",
-	regionTtl: "`regionTtl` is `ttl` now — write `ogygia({ ttl: … })`.",
-	preload: "`preload` is gone — there is nothing to choose any more. The page carries each island’s chunk list as data, and the runtime preloads an island’s whole graph when it wakes (after the page has painted), so no island code moves before its wake and none waits on a waterfall after it. Remove the key.",
-	plugins: "`plugins` is gone — ogygia plugins are Vite plugins: list them beside `ogygia()` in vite.config, `plugins: [ogygia(), flags(), sveltekit()]`.",
-	freeze: "`freeze` is a plugin now, named postrender — install `@ogygia/postrender` and list `postrender({ ttl, default })` (from `@ogygia/postrender/vite`) beside `ogygia()` in vite.config `plugins`.",
-	content: "`content` is a plugin now — install `@ogygia/content` and list `content({ markdown, presets })` (from `@ogygia/content/vite`) beside `ogygia()` in vite.config `plugins`; the svelte config takes `preprocess()` / `extensions()` from there too.",
-	devtools: "`devtools` is a plugin now — install `@ogygia/devtools` and list `devtools()` (from `@ogygia/devtools/vite`) beside `ogygia()` in vite.config `plugins`; only where you want it, e.g. `...(mode !== 'production' ? [devtools()] : [])`.",
-	profiler: "`profiler` is part of the devtools plugin now — install `@ogygia/devtools` and list `devtools({ profiler: { … } })` (from `@ogygia/devtools/vite`) beside `ogygia()` in vite.config `plugins`."
-};
-/** The rename map: a legacy key errors with its new spelling, never silently no-ops. */
+/** The rename map (`RETIRED_OPTIONS`, with the messages): a legacy key errors with its new
+*  spelling, never silently no-ops. */
 function assert_no_legacy_options(options) {
-	for (const key of Object.keys(LEGACY_OPTION_RENAMES)) if (key in options) throw new Error(`[ogygia] ${LEGACY_OPTION_RENAMES[key]}`);
+	for (const key of Object.keys(RETIRED_OPTIONS)) if (key in options) throw new OgygiaError("option_retired", { option: key });
 }
 const REGION_PRESET_KEYS = /* @__PURE__ */ new Set([
 	"render",
@@ -36,8 +23,12 @@ const REGION_PRESET_KEYS = /* @__PURE__ */ new Set([
 */
 function validate_region_presets(presets) {
 	for (const [name, bag] of Object.entries(presets)) {
-		if (!bag || typeof bag !== "object" || Object.keys(bag).length === 0) throw new Error(`[ogygia] presets.${name} is empty — a preset with nothing is a mistake.`);
-		for (const k of Object.keys(bag)) if (!REGION_PRESET_KEYS.has(k)) throw new Error(`[ogygia] presets.${name}: unknown key \`${k}\`. A preset takes ${[...REGION_PRESET_KEYS].join(", ")}.`);
+		if (!bag || typeof bag !== "object" || Object.keys(bag).length === 0) throw new OgygiaError("preset_empty", { name });
+		for (const k of Object.keys(bag)) if (!REGION_PRESET_KEYS.has(k)) throw new OgygiaError("preset_key_unknown", {
+			name,
+			key: k,
+			allowed: [...REGION_PRESET_KEYS].join(", ")
+		});
 	}
 }
 /**
@@ -57,7 +48,7 @@ function resolve_options(options, defaultRegionTtl, defaultRenewWindow = 691200)
 	const session_cookie = typeof options.sessionCookie === "string" && options.sessionCookie.length > 0 ? options.sessionCookie : "";
 	const region_ttl = Math.min(86400, Math.max(60, Math.floor(options.ttl ?? defaultRegionTtl)));
 	const renew_raw = options.maxPageAge;
-	if (renew_raw !== void 0 && !(typeof renew_raw === "number" && Number.isFinite(renew_raw) && renew_raw >= 0)) throw new Error(`[ogygia] maxPageAge must be a number of seconds ≥ 0 (got ${String(renew_raw)}). Write e.g. \`30 * 24 * 3600\` for 30 days, or \`0\` to turn renewal off.`);
+	if (renew_raw !== void 0 && !(typeof renew_raw === "number" && Number.isFinite(renew_raw) && renew_raw >= 0)) throw new OgygiaError("max_page_age_invalid", { value: String(renew_raw) });
 	const renew_window = Math.min(31536e4, Math.floor(renew_raw ?? defaultRenewWindow));
 	const router_enabled = options.router !== false;
 	return {

package/dist/vite/package-files.js

@@ -1,4 +1,5 @@
 import { OWN_PACKAGE_NAMES } from "../own-package.js";
+import { OgygiaError, warn } from "../messages/build.js";
 import fs from "node:fs";
 import path from "node:path";
 import { globSync } from "tinyglobby";
@@ -37,7 +38,10 @@ function discover_package_files(app_root) {
 		const pkg_dir = path.join(app_root, "node_modules", ...name.split("/"));
 		const declared = (read_manifest(pkg_dir)?.ogygia)?.files;
 		if (declared == null) continue;
-		if (!Array.isArray(declared) || !declared.every((p) => typeof p === "string")) throw new Error(`[ogygia] ${name}: \`"ogygia": { "files": […] }\` must be an array of package-relative paths/globs (like npm's "files") — got ${JSON.stringify(declared)}.`);
+		if (!Array.isArray(declared) || !declared.every((p) => typeof p === "string")) throw new OgygiaError("package_files_not_array", {
+			package: name,
+			got: JSON.stringify(declared)
+		});
 		let root;
 		try {
 			root = fs.realpathSync(pkg_dir);
@@ -61,12 +65,18 @@ function discover_package_files(app_root) {
 				continue;
 			}
 			const abs = path.resolve(root, entry);
-			if (abs !== root && !abs.startsWith(root + path.sep)) throw new Error(`[ogygia] ${name}: ogygia.files entry '${entry}' escapes the package.`);
+			if (abs !== root && !abs.startsWith(root + path.sep)) throw new OgygiaError("package_files_escapes", {
+				package: name,
+				entry
+			});
 			let stat;
 			try {
 				stat = fs.statSync(abs);
 			} catch {
-				console.warn(`[ogygia] ${name}: ogygia.files entry '${entry}' does not exist — skipped.`);
+				warn("package_files_missing", {
+					package: name,
+					entry
+				});
 				continue;
 			}
 			if (stat.isDirectory()) dirs.push(posix(fs.realpathSync(abs)));