@ogygia/core 0.12.2 → 0.13.0

package/dist/messages/define.d.ts

@@ -0,0 +1,62 @@
+/**
+ * THE MESSAGE SYSTEM ogygia and its first-party plugins share. Each package keeps its messages in two
+ * tables — its errors and its warnings: a code, its wording from its arguments, what to do about it —
+ * and makes its error class and its `warn()` from them:
+ *
+ *   export const ERRORS = { some_error: { text: (a: { entry: string }): string => …, details } }
+ *     satisfies MessageTableShape;
+ *   export const WARNINGS = { … } satisfies MessageTableShape;
+ *   const own: MessagesOf<typeof ERRORS, typeof WARNINGS> = define_messages(
+ *     import.meta.env.DEV ? ERRORS : null,
+ *     import.meta.env.DEV ? WARNINGS : null
+ *   );
+ *
+ *   throw new OgygiaError('goto_not_http');
+ *   console.error(new OgygiaError('island_load_failed', { entry }), err);   // a caught failure
+ *   warn('island_healed', { entry, drift });                                 // console.warn
+ *
+ * Every message ends with its code's page, `https://ogygiajs.dev/e/<code>?<args>` (the docs fill the
+ * wording in from the arguments). In dev it starts with the wording; in a production build it is the
+ * link alone: the tables are only passed under `import.meta.env.DEV`, so the bundler drops them and
+ * no wording reaches the bundle (the way Svelte ships `https://svelte.dev/e/<code>`). An error
+ * carries its code (`err.code`). Codes are one namespace across every package (the docs' `/e` pages
+ * list them all and check it).
+ */
+/** One message: its wording from its arguments, and its page (plain sentences, `code` in backticks,
+ *  one paragraph a line). `details` is a function so a table makes no call as it loads — the bundler
+ *  can then drop it whole from a production build. */
+export type MessageEntry<A> = {
+  text: (a: A) => string;
+  details: () => string;
+};
+/** What a table satisfies. Each `text` declares its own arguments (`(a: { entry: string }): string`),
+ *  the one place they are written; {@link MessagesOf} reads them back. */
+export type MessageTableShape = Record<string, MessageEntry<never>>;
+/** Each code's arguments, read off its `text` (`void`: none). */
+type ArgsOf<T> = { [C in keyof T]: T[C] extends {
+  text: () => string;
+} ? void : T[C] extends {
+  text: (a: infer A) => string;
+} ? A : never; };
+type Args<M, C extends keyof M> = M[C] extends void ? [] : [M[C]];
+/** A package's `OgygiaError` (its error codes) and `warn()` (its warning codes). */
+export type MessagesOf<E, W> = {
+  OgygiaError: new <C extends keyof E & string>(code: C, ...args: Args<ArgsOf<E>, C>) => Error & {
+    code: C;
+  };
+  warn: <C extends keyof W & string>(code: C, ...rest: [...Args<ArgsOf<W>, C>, ...unknown[]]) => void;
+  /** A code's line as a string, for a logger that takes one (Rollup's `this.warn`, an injected
+   *  `warn`): what `OgygiaError` and `warn` print. */
+  line: <C extends (keyof E | keyof W) & string>(code: C, ...args: Args<ArgsOf<E & W>, C & keyof (E & W)>) => string;
+};
+/** The line for a code: the wording and its link with the table, the link alone without it. */
+/** Dev, or a prerender (the server's handle publishes Kit's `building`, hooks.ts): the moments a
+ *  server-side message prints its wording. Asked when it prints, never as a module loads. */
+export declare function dev_or_prerender(): boolean;
+/**
+ * A package's `OgygiaError`, `warn` and `line` from its tables. A table left out (`null`) prints the
+ * link alone; `worded`, asked as each message prints, says whether a table it was given is used —
+ * a server bundle keeps its tables for a prerender and words a message only then (and in dev).
+ */
+export declare function define_messages<E extends MessageTableShape, W extends MessageTableShape>(errors_table: E | null, warnings_table: W | null, worded?: () => boolean): MessagesOf<E, W>;
+export {};

package/dist/messages/define.js

@@ -0,0 +1,49 @@
+// src/messages/define.ts
+/** The line for a code: the wording and its link with the table, the link alone without it. */
+/** Dev, or a prerender (the server's handle publishes Kit's `building`, hooks.ts): the moments a
+*  server-side message prints its wording. Asked when it prints, never as a module loads. */
+function dev_or_prerender() {
+	return !!import.meta.env?.DEV || globalThis[Symbol.for("ogygia.prerendering")] === true;
+}
+function line(table, code, a) {
+	let link = "https://ogygiajs.dev/e/" + code;
+	if (a && typeof a === "object") {
+		const params = new URLSearchParams();
+		for (const name in a) {
+			const value = a[name];
+			if (value != null && value !== "") params.set(name, String(value).slice(0, 300));
+		}
+		const query = params.toString();
+		if (query) link += "?" + query;
+	}
+	const entry = table && table[code];
+	return entry ? "[ogygia] " + entry.text(a) + "\n" + link : "[ogygia] " + link;
+}
+/**
+* A package's `OgygiaError`, `warn` and `line` from its tables. A table left out (`null`) prints the
+* link alone; `worded`, asked as each message prints, says whether a table it was given is used —
+* a server bundle keeps its tables for a prerender and words a message only then (and in dev).
+*/
+function define_messages(errors_table, warnings_table, worded = () => true) {
+	const errors = () => errors_table && worded() ? errors_table : null;
+	const warnings = () => warnings_table && worded() ? warnings_table : null;
+	class OgygiaError extends Error {
+		code;
+		constructor(code, a) {
+			super(line(errors(), code, a));
+			this.name = "OgygiaError";
+			this.code = code;
+		}
+	}
+	return {
+		OgygiaError,
+		warn: ((code, ...rest) => {
+			const first = rest[0];
+			const proto = first !== null && typeof first === "object" ? Object.getPrototypeOf(first) : 0;
+			const has_args = proto === Object.prototype || proto === null;
+			console.warn(line(warnings(), code, has_args ? first : void 0), ...has_args ? rest.slice(1) : rest);
+		}),
+		line: ((code, a) => line(errors_table && code in errors_table ? errors() : warnings(), code, a))
+	};
+}
+export { define_messages, dev_or_prerender };

package/dist/messages/index.d.ts

@@ -0,0 +1,6 @@
+import { MessageEntry, MessageTableShape, MessagesOf, define_messages, dev_or_prerender } from "./define.js";
+import { prose } from "./prose.js";
+import { ERRORS, WARNINGS } from "./core.js";
+import { SERVER_ERRORS, SERVER_WARNINGS } from "./server.js";
+import { BUILD_ERRORS, BUILD_WARNINGS } from "./build.js";
+export { BUILD_ERRORS, BUILD_WARNINGS, ERRORS, type MessageEntry, type MessageTableShape, type MessagesOf, SERVER_ERRORS, SERVER_WARNINGS, WARNINGS, define_messages, dev_or_prerender, prose };

package/dist/messages/index.js

@@ -0,0 +1,6 @@
+import { define_messages, dev_or_prerender } from "./define.js";
+import { prose } from "./prose.js";
+import { ERRORS, WARNINGS } from "./core.js";
+import { SERVER_ERRORS, SERVER_WARNINGS } from "./server.js";
+import { BUILD_ERRORS, BUILD_WARNINGS } from "./build.js";
+export { BUILD_ERRORS, BUILD_WARNINGS, ERRORS, SERVER_ERRORS, SERVER_WARNINGS, WARNINGS, define_messages, dev_or_prerender, prose };

package/dist/messages/island.d.ts

@@ -0,0 +1,4 @@
+import { OgygiaError as OgygiaError$1, line as line$1, warn as warn$1 } from "./core.js";
+export declare const OgygiaError: typeof OgygiaError$1;
+export declare const warn: typeof warn$1;
+export declare const line: typeof line$1;

package/dist/messages/island.js

@@ -0,0 +1,34 @@
+// src/messages/island.ts
+const runtime = () => globalThis[Symbol.for("ogygia.messages")];
+/** The code's link with its arguments — what a production build prints (./define.ts `line`). */
+function link(code, a) {
+	let url = "[ogygia] https://ogygiajs.dev/e/" + code;
+	if (a && typeof a === "object") {
+		const params = new URLSearchParams();
+		for (const name in a) {
+			const value = a[name];
+			if (value != null && value !== "") params.set(name, String(value).slice(0, 300));
+		}
+		const query = params.toString();
+		if (query) url += "?" + query;
+	}
+	return url;
+}
+const OgygiaError = function(code, a) {
+	const own = runtime();
+	return own ? new own.OgygiaError(code, a) : Object.assign(new Error(link(code, a)), { code });
+};
+const warn = ((code, ...rest) => {
+	const own = runtime();
+	if (own) own.warn(code, ...rest);
+	else {
+		const first = rest[0];
+		const proto = first !== null && typeof first === "object" ? Object.getPrototypeOf(first) : 0;
+		console.warn(link(code, proto === Object.prototype || proto === null ? first : void 0));
+	}
+});
+const line = ((code, a) => {
+	const own = runtime();
+	return own ? own.line(code, a) : link(code, a);
+});
+export { OgygiaError, line, warn };

package/dist/messages/lazy.d.ts

@@ -0,0 +1,3 @@
+import { OgygiaError as OgygiaError$1, warn as warn$1 } from "./core.js";
+export declare const OgygiaError: typeof OgygiaError$1;
+export declare const warn: typeof warn$1;

package/dist/messages/lazy.js

@@ -0,0 +1,22 @@
+import { slots } from "../runtime/slots.js";
+// src/messages/lazy.ts
+/**
+* `OgygiaError` and `warn` for the runtime's lazy chunks (the hydrate core, the router's navigation)
+* and what only they import. A lazy chunk never imports a boot module — one both import is split
+* into a chunk of its own — so these are the boot's own (./core.ts), reached through the boot link;
+* where no boot linked them (the server's render of the same module, a test), the copy the server's
+* handle publishes (./island.ts), else the code's link alone. Same calls:
+* `throw new OgygiaError(code, args)`, `warn(code, args, ...rest)`.
+*/
+const own = () => slots.boot ?? globalThis[Symbol.for("ogygia.messages")];
+const link = (code) => "[ogygia] https://ogygiajs.dev/e/" + code;
+const OgygiaError = function(code, a) {
+	const m = own();
+	return m ? new m.OgygiaError(code, a) : Object.assign(new Error(link(code)), { code });
+};
+const warn = ((code, ...rest) => {
+	const m = own();
+	if (m) m.warn(code, ...rest);
+	else console.warn(link(code));
+});
+export { OgygiaError, warn };

package/dist/messages/prose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Write a message as it reads: an indented paragraph in the source, one line in the console.
+ *
+ *   prose`
+ *     island "${a.entry}" was edited while it slept, so its server HTML
+ *     was put back and hydrated.
+ *
+ *     ${a.drift && `What drifted: ${a.drift}`}
+ *   `
+ *
+ * The indentation goes, the lines of a paragraph join with a space, a blank line starts a new one
+ * (`\n`), and a paragraph left empty (a value that is `''`, `false`, `null`) is dropped. Values go in
+ * as they are. Dev only: it runs inside a message table, which a production build drops.
+ */
+export declare function prose(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/messages/prose.js

@@ -0,0 +1,43 @@
+// src/messages/prose.ts
+/**
+* Write a message as it reads: an indented paragraph in the source, one line in the console.
+*
+*   prose`
+*     island "${a.entry}" was edited while it slept, so its server HTML
+*     was put back and hydrated.
+*
+*     ${a.drift && `What drifted: ${a.drift}`}
+*   `
+*
+* The indentation goes, the lines of a paragraph join with a space, a blank line starts a new one
+* (`\n`), and a paragraph left empty (a value that is `''`, `false`, `null`) is dropped. Values go in
+* as they are. Dev only: it runs inside a message table, which a production build drops.
+*/
+function prose(strings, ...values) {
+	const paragraphs = [];
+	let current = "";
+	const end_paragraph = () => {
+		const text = current.trim();
+		if (text) paragraphs.push(text);
+		current = "";
+	};
+	strings.forEach((part, i) => {
+		const lines = part.split("\n");
+		const last = lines.length - 1;
+		lines.forEach((line, j) => {
+			if (j > 0) {
+				if (line.trim() === "" && j < last) end_paragraph();
+				else current += " ";
+			}
+			const text = j === 0 ? line : line.trimStart();
+			current += j === last ? text : text.trimEnd();
+		});
+		if (i < values.length) {
+			const value = values[i];
+			if (value !== null && value !== void 0 && value !== false) current += String(value);
+		}
+	});
+	end_paragraph();
+	return paragraphs.join("\n");
+}
+export { prose };

package/dist/messages/server.d.ts

@@ -0,0 +1,142 @@
+import { MessagesOf } from "./define.js";
+/** The errors: `throw new OgygiaError(code, args)`, or `console.error(new OgygiaError(…))`. */
+export declare const SERVER_ERRORS: {
+  handle_secret_too_short: {
+    text: (a: {
+      min: number;
+    }) => string;
+    details: () => string;
+  };
+  secret_conflict: {
+    text: (a: {
+      key: string;
+      decided: string;
+      from: string;
+    }) => string;
+    details: () => string;
+  };
+  secret_missing_at_runtime: {
+    text: () => string;
+    details: () => string;
+  };
+  hole_props_too_large: {
+    text: (a: {
+      entry: string;
+      length: number;
+      max: number;
+    }) => string;
+    details: () => string;
+  };
+  prop_not_serializable: {
+    text: (a: {
+      entry: string;
+      detail: string;
+    }) => string;
+    details: () => string;
+  };
+};
+/** The warnings: `warn(code, args, ...rest)`. */
+export declare const SERVER_WARNINGS: {
+  region_render_failed: {
+    text: () => string;
+    details: () => string;
+  };
+  region_render_abandoned: {
+    text: (a: {
+      ms: number;
+    }) => string;
+    details: () => string;
+  };
+  endpoint_props_decode_failed: {
+    text: () => string;
+    details: () => string;
+  };
+  endpoint_foreign_key: {
+    text: (a: {
+      id: string;
+      key: string;
+      own: string;
+    }) => string;
+    details: () => string;
+  };
+  endpoint_bad_signature: {
+    text: (a: {
+      id: string;
+    }) => string;
+    details: () => string;
+  };
+  endpoint_unknown_id: {
+    text: (a: {
+      id: string;
+      component?: string;
+      known: number;
+    }) => string;
+    details: () => string;
+  };
+  live_props_not_serializable: {
+    text: (a: {
+      entry: string;
+      max: number;
+    }) => string;
+    details: () => string;
+  };
+  build_key_prerender: {
+    text: () => string;
+    details: () => string;
+  };
+  secret_missing: {
+    text: () => string;
+    details: () => string;
+  };
+  outside_page_data_unavailable: {
+    text: (a: {
+      path: string;
+      miss: string;
+    }) => string;
+    details: () => string;
+  };
+  outside_page_data_key: {
+    text: (a: {
+      path: string;
+      key: string;
+    }) => string;
+    details: () => string;
+  };
+  router_css_inactive: {
+    text: () => string;
+    details: () => string;
+  };
+  plugin_hook_failed: {
+    text: (a: {
+      name: string;
+    }) => string;
+    details: () => string;
+  };
+  personal_response_unmarked: {
+    text: (a: {
+      status: number;
+    }) => string;
+    details: () => string;
+  };
+  request_cleanup_failed: {
+    text: () => string;
+    details: () => string;
+  };
+  rule_request_scope_open: {
+    text: (a: {
+      detail: string;
+    }) => string;
+    details: () => string;
+  };
+  rule_flight_kept_failure: {
+    text: (a: {
+      detail: string;
+    }) => string;
+    details: () => string;
+  };
+};
+type Server = MessagesOf<typeof SERVER_ERRORS, typeof SERVER_WARNINGS>;
+export declare const OgygiaError: Server["OgygiaError"];
+export declare const warn: Server["warn"];
+export declare const line: Server["line"];
+export {};

package/dist/messages/server.js

@@ -0,0 +1,246 @@
+import { define_messages, dev_or_prerender } from "./define.js";
+import { prose } from "./prose.js";
+// src/messages/server.ts
+/**
+* EVERY MESSAGE OGYGIA'S SERVER PRINTS — the handle, the islands endpoint, region capabilities, the
+* page a render outside Kit reads: their code, their wording, what to do about them. Same calls as
+* the runtime's (./core.ts): the wording and the code's page in dev and while prerendering; a
+* production server prints the page's link alone.
+*
+*   throw new OgygiaError('handle_secret_too_short', { min });
+*   warn('endpoint_bad_signature', { id });
+*/
+const SECRET_FIX = "Set a stable `OGYGIA_SECRET` in the server environment, or pass one to `handle({ secret })`.";
+/** The errors: `throw new OgygiaError(code, args)`, or `console.error(new OgygiaError(…))`. */
+const SERVER_ERRORS = {
+	handle_secret_too_short: {
+		text: (a) => `handle({ secret }) is too short for production (need ≥${a.min} UTF-8 bytes).`,
+		details: () => prose`
+			A production build signs region capabilities with the secret passed to
+			\`handle({ secret })\`, and a short one can be guessed. Use a random secret at least as long
+			as the message says, from the server's environment.
+		`
+	},
+	secret_conflict: {
+		text: (a) => prose`
+			handle({ secret }) names key ${a.key}, but this server already signs with key ${a.decided}
+			(from ${a.from}). The first key stays: pass one secret, before anything renders.
+		`,
+		details: () => prose`
+			The server decides its signing key once, the first time it mints or verifies a region
+			capability. A second, different secret arrived after that, and is ignored: every
+			capability keeps verifying with the first key.
+
+			Pass one secret, to the one \`handle()\`, before anything renders.
+		`
+	},
+	secret_missing_at_runtime: {
+		text: () => prose`
+			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).
+		`,
+		details: () => prose`
+			The build saw \`OGYGIA_SECRET\` but the running server does not, so it signs with a random
+			key of its own. A page from another deployment carries capabilities signed with another
+			key, and the islands endpoint refuses them (\`x-ogygia-deny: foreign-key\`).
+
+			${SECRET_FIX}
+		`
+	},
+	hole_props_too_large: {
+		text: (a) => prose`
+			server island "${a.entry}": props payload is ${a.length} b64 chars (max ${a.max}). Shrink
+			what you pass into the deferred region — the handle would reject this capability anyway.
+		`,
+		details: () => prose`
+			A deferred region's props travel inside its signed address, so they have a size limit.
+			Pass less: an id the region looks up on the server instead of the record itself.
+		`
+	},
+	prop_not_serializable: {
+		text: (a) => prose`
+			island "${a.entry}": a captured prop is not serializable — ${a.detail}. Captured host values
+			cross the boundary via devalue; functions/Promises cannot, and a class instance only can
+			when the class declares a static [ogygia.wire] codec. Pass a serializable value, add a
+			codec, or move that logic inside the island component.
+		`,
+		details: () => prose`
+			An island's props are serialized into the page so the browser can hydrate it. Functions
+			and promises cannot be serialized, and a class instance can only when its class declares
+			a wire codec.
+
+			Pass plain data, give the class a codec, or move the logic inside the island.
+		`
+	}
+};
+/** The warnings: `warn(code, args, ...rest)`. */
+const SERVER_WARNINGS = {
+	region_render_failed: {
+		text: () => "region render failed:",
+		details: () => prose`
+			Dev only. A region's server render threw, so the islands endpoint answered 500 and the page
+			keeps the region's fallback. The error follows the message.
+		`
+	},
+	region_render_abandoned: {
+		text: (a) => `a region render ran past ${a.ms} ms and was abandoned: its hole kept its fallback`,
+		details: () => prose`
+			A hole's render did not finish within its deadline, so the islands endpoint answered with
+			the fallback and gave the render's slot to the next hole. The render still runs (a render
+			cannot be cancelled) until what it awaits ends. Renders that outlive their deadline usually
+			await an upstream that hangs: give that fetch a timeout of its own. Said once each time a
+			render is abandoned while no other is.
+		`
+	},
+	endpoint_props_decode_failed: {
+		text: () => "region endpoint 403: island module load / props decode failed",
+		details: () => prose`
+			Dev only. The islands endpoint could not load the region's module, or could not decode
+			the props in its address, so it refused the request. The error follows the message.
+		`
+	},
+	endpoint_foreign_key: {
+		text: (a) => `region endpoint 403: id "${a.id}" was signed by key ${a.key}, this server signs with ${a.own}`,
+		details: () => prose`
+			Dev only. The region's address was signed by another deployment's key. Route the islands
+			endpoint to the deployment that served the page, or give every deployment the same
+			\`OGYGIA_SECRET\`.
+		`
+	},
+	endpoint_bad_signature: {
+		text: (a) => `region endpoint 403: bad signature for id "${a.id}"`,
+		details: () => prose`
+			Dev only. The region's address does not carry a valid signature: it was edited, or
+			truncated on the way. The endpoint refuses it.
+		`
+	},
+	endpoint_unknown_id: {
+		text: (a) => `region endpoint 403: id "${a.id}"${a.component ? ` (component ${a.component})` : ""} is not in the server manifest (${a.known} known)`,
+		details: () => prose`
+			Dev only. The address names a region this server's build does not have: the page came
+			from another build, or the region was renamed. After a deploy the page reloads its
+			regions from the current build.
+		`
+	},
+	live_props_not_serializable: {
+		text: (a) => prose`
+			render:'live' region ${a.entry} has props that cannot cross the wire (non-serializable or
+			>${a.max} b64 chars) — no revalidate endpoint minted (behaves like a static lake).
+		`,
+		details: () => prose`
+			A live region refreshes from a signed address that carries its props. These props cannot
+			be serialized, or are too large, so the region gets no address and never refreshes. Pass
+			plain, small props.
+		`
+	},
+	build_key_prerender: {
+		text: () => prose`
+			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.
+		`,
+		details: () => prose`
+			A prerendered page keeps the addresses of its holes in static HTML. Signed with a random
+			per-build key, they stop verifying after the next deploy. ${SECRET_FIX}
+		`
+	},
+	secret_missing: {
+		text: () => prose`
+			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 }).
+		`,
+		details: () => prose`
+			Without a secret, each deployment signs with its own random key. A page cached across a
+			deploy, or served by one backend while another answers its islands endpoint, gets its holes
+			refused. ${SECRET_FIX}
+		`
+	},
+	outside_page_data_unavailable: {
+		text: (a) => `${a.path}: the page's data for a render outside it is unavailable: ${a.miss}. The render sees an empty page.data.`,
+		details: () => prose`
+			A region rendered outside its page (an islands endpoint request) reads that page's
+			\`page.data\`, which ogygia looks up from the page. The lookup failed for the reason given,
+			so the region rendered with an empty \`page.data\`.
+		`
+	},
+	outside_page_data_key: {
+		text: (a) => prose`
+			${a.path}: a region rendered outside its page read page.data.${a.key}, which this page's
+			server loads do not produce. A key a universal load (+page.ts / +layout.ts) returns exists
+			only inside a full page render: return it from a server load, or pass it as a prop.
+		`,
+		details: () => prose`
+			Outside a full page render only the server loads run. A key a universal load returns
+			(\`+page.ts\`, \`+layout.ts\`) is missing there. Return it from a server load, or pass it
+			to the region as a prop.
+		`
+	},
+	router_css_inactive: {
+		text: () => prose`
+			a page rendered outside Kit's routes, but no plugin declared page modules, so its
+			components' CSS is not linked. Using \`@ogygia/router\`? List \`router()\` from
+			\`@ogygia/router/vite\` beside \`ogygia()\` in vite.config \`plugins\`.
+		`,
+		details: () => prose`
+			Dev only. A page rendered outside Kit's routes needs a plugin to name its modules so their
+			CSS can be linked. With \`@ogygia/router\`, add \`router()\` from \`@ogygia/router/vite\` to
+			the Vite plugins.
+		`
+	},
+	plugin_hook_failed: {
+		text: (a) => `a \`${a.name}\` hook failed —`,
+		details: () => prose`
+			A plugin's hook threw. ogygia logs it and goes on with the next plugin. The error follows
+			the message.
+		`
+	},
+	personal_response_unmarked: {
+		text: (a) => prose`
+			a page made for one browser (status ${a.status}) could not be marked private: its headers
+			cannot be changed —
+		`,
+		details: () => prose`
+			A page that carries something for one browser (its devtools events, the profiler's beacon,
+			the devtools switch's cookie) is marked \`cache-control: private, no-store\` so no shared
+			cache keeps it. This response's headers cannot be changed (a Response from \`fetch()\`, or
+			\`Response.redirect()\`, handed back as it is), so it goes out with the headers it has, and a
+			shared cache could keep it. The error follows the message. Return a new Response
+			(\`new Response(res.body, res)\`) from the hook or route that made it.
+		`
+	},
+	request_cleanup_failed: {
+		text: () => `a cleanup at the end of a request failed —`,
+		details: () => prose`
+			Work a request started (a timer, a stream, a fetch) is let go when its response ends or
+			its visitor leaves. One of those cleanups threw. The response was not affected. The error
+			follows the message.
+		`
+	},
+	rule_request_scope_open: {
+		text: (a) => `rule broken, a request's work ends with its response: ${a.detail}`,
+		details: () => prose`
+			Dev and e2e builds only (a rule ogygia checks on itself). The work a request starts (its
+			timers, streams, fetches) is let go once its response ends. A response ended with its
+			request's work still held, which leaks with every request: an ogygia bug, please report it.
+		`
+	},
+	rule_flight_kept_failure: {
+		text: (a) => `rule broken, no shared work keeps a failure: ${a.detail}`,
+		details: () => prose`
+			Dev and e2e builds only (a rule ogygia checks on itself). Shared work (a render, a fetch
+			that callers join) keeps its answer for the next caller, but never a failure: the next
+			caller tries again. One kept an error as its answer, so every later caller gets it.
+		`
+	}
+};
+const server = /* @__PURE__ */ define_messages(import.meta.env?.DEV || import.meta.env?.SSR ? SERVER_ERRORS : null, import.meta.env?.DEV || import.meta.env?.SSR ? SERVER_WARNINGS : null, dev_or_prerender);
+const OgygiaError = server.OgygiaError;
+const warn = server.warn;
+const line = server.line;
+export { OgygiaError, SERVER_ERRORS, SERVER_WARNINGS, line, warn };

package/dist/nested.d.ts

@@ -4,6 +4,9 @@
  * hydrates again (the nearest-boundary rule — DESIGN.md).
  */
 export declare function setNested(value?: boolean): void;
+/** The context an island is hydrated with: `base` (a `<Provide>` above it), marked "inside an
+ *  island" — what a wrapper's `setNested()` gave its children, with no wrapper in the tree. */
+export declare function nested_context(base?: Map<unknown, unknown> | null): Map<unknown, unknown>;
 /**
  * True when an ancestor island wrapper already marked the subtree. `getContext` returns `undefined`
  * when no ancestor set it (a top-level island) — that absence is exactly "not nested".

package/dist/nested.js

@@ -9,6 +9,13 @@ const NESTED_KEY = Symbol.for("ogygia.nested-island");
 function setNested(value = true) {
 	setContext(NESTED_KEY, value);
 }
+/** The context an island is hydrated with: `base` (a `<Provide>` above it), marked "inside an
+*  island" — what a wrapper's `setNested()` gave its children, with no wrapper in the tree. */
+function nested_context(base) {
+	const context = new Map(base ?? void 0);
+	context.set(NESTED_KEY, true);
+	return context;
+}
 /**
 * True when an ancestor island wrapper already marked the subtree. `getContext` returns `undefined`
 * when no ancestor set it (a top-level island) — that absence is exactly "not nested".
@@ -16,4 +23,4 @@ function setNested(value = true) {
 function isNested() {
 	return getContext(NESTED_KEY) === true;
 }
-export { isNested, setNested };
+export { isNested, nested_context, setNested };