@ogygia/core 0.0.0 → 0.11.0

package/dist/vite/kit-dirs.d.ts

@@ -0,0 +1,7 @@
+import { KitDirs } from "../compiler/kit.js";
+/** The plugin list as a Vite config holds it: plugins, arrays of them, promises of either, falsy. */
+type PluginOption = unknown;
+/** Resolve `{ routes_dir, out_dir }` for `root` from its Kit config (defaults when absent or
+ *  unreadable) and cache it for the compiler. `plugins`: the Vite config's plugin list. */
+export declare function load_kit_dirs(root: string, plugins?: PluginOption): Promise<KitDirs>;
+export {};

package/dist/vite/kit-dirs.js

@@ -0,0 +1,67 @@
+import { DEFAULT_KIT_DIRS, set_kit_dirs, set_kit_inline_style_threshold } from "../compiler/kit.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+// src/vite/kit-dirs.ts
+/**
+* Kit's two configurable directories, read from the app's Kit config: `files.routes` (default
+* `src/routes`) and `outDir` (default `.svelte-kit`). ogygia scans the routes tree (csr worlds, the
+* client-build keepalive, route options) and writes/reads its island-deps handoff under Kit's output
+* dir — every one of those must follow the app's configuration, not the defaults (an app building
+* two route trees from one source, `PES_MODE=v2 → src/routes-v2` + `.svelte-kit-v2`, had its
+* all-csr=false tree read as "no routes": Kit skipped the client build, the runtime chunk was never
+* emitted, every island 404'd).
+*
+* WHERE THE CONFIG IS. Kit's own plugin carries its validated config (`vite-plugin-sveltekit-setup`'s
+* `api.options`): on Kit 2 the svelte config, Kit's options under `kit`; on Kit 3, which takes its
+* config in `vite.config.js` only (a `svelte.config.js` is an error there), Kit's options at the top.
+* Read from there first; a Kit 2 app's `svelte.config.js` file is the fallback.
+*
+* Loaded once per root in the plugin's `config` hook (before Kit reads the routes); the compiler
+* reads the cached answer through `kit_dirs(root)` in compiler/kit.ts. Node-only (imports the
+* config module) — that is why it lives on the Vite side, not in the host-neutral compiler.
+*/
+const CONFIG_FILES = ["svelte.config.js", "svelte.config.mjs"];
+/** Every plugin in `option`, flattened (arrays nest; `sveltekit()` is a promise on Kit 3). */
+async function flatten_plugins(option) {
+	const out = [];
+	const walk = async (p) => {
+		const v = await p;
+		if (!v) return;
+		if (Array.isArray(v)) for (const x of v) await walk(x);
+		else if (typeof v === "object") out.push(v);
+	};
+	await walk(option);
+	return out;
+}
+/** Kit's options off its setup plugin: Kit 3's at the top of its config, Kit 2's under `kit`. */
+async function kit_options_from_plugins(plugins) {
+	const options = ((await flatten_plugins(plugins)).find((p) => p.name === "vite-plugin-sveltekit-setup")?.api)?.options;
+	if (!options) return null;
+	return options.kit ?? options;
+}
+/** Kit's options from a Kit 2 app's `svelte.config.js` (null when there is none). */
+async function kit_options_from_file(root) {
+	const file = CONFIG_FILES.map((f) => path.join(root, f)).find((f) => existsSync(f));
+	if (!file) return null;
+	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)}`);
+		return null;
+	}
+}
+/** Resolve `{ routes_dir, out_dir }` for `root` from its Kit config (defaults when absent or
+*  unreadable) and cache it for the compiler. `plugins`: the Vite config's plugin list. */
+async function load_kit_dirs(root, plugins) {
+	const kit = await kit_options_from_plugins(plugins) ?? await kit_options_from_file(root) ?? {};
+	const dirs = {
+		routes_dir: path.resolve(root, kit.files?.routes ?? DEFAULT_KIT_DIRS.routes),
+		out_dir: path.resolve(root, kit.outDir ?? DEFAULT_KIT_DIRS.out)
+	};
+	set_kit_dirs(root, dirs);
+	const threshold = kit.inlineStyleThreshold;
+	set_kit_inline_style_threshold(root, typeof threshold === "number" && Number.isFinite(threshold) && threshold > 0 ? threshold : 0);
+	return dirs;
+}
+export { load_kit_dirs };

package/dist/vite/late-island.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ASYNC TWINS: what Region imports where the app runs Svelte's async mode. A render that can WAIT does
+ * better than one that cannot, and only async mode lets a component `await` — without it an `await`
+ * does not compile. So each such component ships as a pair: the file Region imports (works anywhere)
+ * and its awaiting twin, which the plugin points that import at for an app with async mode on.
+ *
+ *  - LateIsland → LateIslandAwait: an inline island a Kit client navigation created has no component
+ *    yet; the twin awaits its load, so the navigation's update batch waits and Kit keeps the old page
+ *    until the whole new one is in (without it: an empty place, then the island).
+ *  - PromiseRegion → PromiseRegionAwait: a `<Region of={promise}>` — the twin awaits the promise IN the
+ *    server render (Kit seeds a remote query's result, hydration awaits the same value), so the page
+ *    arrives with the region in it; without it the server renders the placeholder and the browser
+ *    resolves the promise after hydration.
+ */
+/** Region's twin imports: the file it imports → its awaiting twin (beside it). */
+export declare const ASYNC_TWINS: Readonly<Record<string, string>>;
+/** Does the app compile with Svelte's async mode? Read off vite-plugin-svelte's resolved options (its
+ *  config plugin publishes them as `api.options`, resolved before any plugin's own configResolved). */
+export declare function svelte_async_enabled(plugins: readonly {
+  name?: string;
+  api?: unknown;
+}[] | undefined): boolean;
+/** The awaiting twin a Region twin import resolves to in an app with async mode on (beside Region,
+ *  whichever copy imported it), or null for any other import. */
+export declare function async_twin_redirect(source: string, importer: string | undefined, region_modules: ReadonlySet<string>): string | null;

package/dist/vite/late-island.js

@@ -0,0 +1,33 @@
+// src/vite/late-island.ts
+/**
+* ASYNC TWINS: what Region imports where the app runs Svelte's async mode. A render that can WAIT does
+* better than one that cannot, and only async mode lets a component `await` — without it an `await`
+* does not compile. So each such component ships as a pair: the file Region imports (works anywhere)
+* and its awaiting twin, which the plugin points that import at for an app with async mode on.
+*
+*  - LateIsland → LateIslandAwait: an inline island a Kit client navigation created has no component
+*    yet; the twin awaits its load, so the navigation's update batch waits and Kit keeps the old page
+*    until the whole new one is in (without it: an empty place, then the island).
+*  - PromiseRegion → PromiseRegionAwait: a `<Region of={promise}>` — the twin awaits the promise IN the
+*    server render (Kit seeds a remote query's result, hydration awaits the same value), so the page
+*    arrives with the region in it; without it the server renders the placeholder and the browser
+*    resolves the promise after hydration.
+*/
+/** Region's twin imports: the file it imports → its awaiting twin (beside it). */
+const ASYNC_TWINS = {
+	"./LateIsland.svelte": "LateIslandAwait.svelte",
+	"./PromiseRegion.svelte": "PromiseRegionAwait.svelte"
+};
+/** Does the app compile with Svelte's async mode? Read off vite-plugin-svelte's resolved options (its
+*  config plugin publishes them as `api.options`, resolved before any plugin's own configResolved). */
+function svelte_async_enabled(plugins) {
+	return (plugins?.find((p) => p.name === "vite-plugin-svelte:config")?.api)?.options?.compilerOptions?.experimental?.async === true;
+}
+/** The awaiting twin a Region twin import resolves to in an app with async mode on (beside Region,
+*  whichever copy imported it), or null for any other import. */
+function async_twin_redirect(source, importer, region_modules) {
+	const twin = ASYNC_TWINS[source];
+	if (!twin || !importer || !region_modules.has(importer)) return null;
+	return importer.slice(0, importer.lastIndexOf("/") + 1) + twin;
+}
+export { ASYNC_TWINS, async_twin_redirect, svelte_async_enabled };

package/dist/vite/module-map.d.ts

@@ -0,0 +1,8 @@
+export declare const MODULE_MAP_FILE = "ogygia-modules.json";
+/** chunk file (relative to the output dir) → [first line, last line, module id relative to root] */
+export type ModuleMap = {
+  v: 1;
+  chunks: Record<string, [number, number, string][]>;
+};
+export declare function build_module_map(bundle: Record<string, unknown>, root: string): ModuleMap;
+export declare function write_module_map(dir: string, bundle: Record<string, unknown>, root: string): void;

package/dist/vite/module-map.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+// src/vite/module-map.ts
+/**
+* THE MODULE MAP: for each server chunk, which source module's code sits at which lines — written
+* once per server build, beside the chunks (`ogygia-modules.json`), so it travels with them to
+* whatever host runs the build. A build without sourcemaps (the normal one) leaves the profiler
+* only chunk names; with this it still tells its own code, ogygia's runtime and a bundled package's
+* from the app's (profiler/module-map.ts reads it).
+*/
+const MODULE_MAP_FILE = "ogygia-modules.json";
+function count_lines(s, from, to) {
+	let n = 0;
+	for (let i = from; i < to; i++) if (s.charCodeAt(i) === 10) n++;
+	return n;
+}
+/** where a module's code starts in the chunk, found by its first line of real code (24+ characters,
+*  not an import / export-from / comment) and counted back to the module's first line: the chunk
+*  offset of that start, or -1. Lines before the anchor that the bundler dropped (the imports) make
+*  the start land a little early, never inside the previous module's own code by more than those */
+function by_solid_line(chunk, code, cursor) {
+	const lines = code.split("\n");
+	const dropped_line = (t) => t.startsWith("import ") || t.startsWith("export ") && t.includes(" from ");
+	for (let i = 0; i < lines.length && i < 80; i++) {
+		const l = lines[i].trim();
+		if (l.length < 24 || dropped_line(l) || l.startsWith("//") || l.startsWith("/*") || l.startsWith("*")) continue;
+		let at = chunk.indexOf(l, cursor);
+		if (at === -1) at = chunk.indexOf(l);
+		if (at === -1) continue;
+		let start = chunk.lastIndexOf("\n", at - 1) + 1;
+		let kept = 0;
+		let dropped = 0;
+		for (let j = 0; j < i; j++) if (dropped_line(lines[j].trim())) dropped++;
+		else kept++;
+		for (let k = 0; k < kept && start > 0; k++) start = chunk.lastIndexOf("\n", start - 2) + 1;
+		for (let j = i + 1; j < lines.length; j++) if (dropped_line(lines[j].trim())) dropped++;
+		return {
+			at: start,
+			dropped
+		};
+	}
+}
+/** a module id as the map keeps it: relative to the root, a package from its `node_modules/` */
+function clean_id(id, root) {
+	const q = id.indexOf("?");
+	const clean = (q === -1 ? id : id.slice(0, q)).replace(/^\0/, "");
+	const rel = path.isAbsolute(clean) ? path.relative(root, clean).split(path.sep).join("/") : clean;
+	const nm = rel.lastIndexOf("node_modules/");
+	return nm === -1 ? rel : rel.slice(nm);
+}
+/** THE BUNDLER'S OWN MARKERS: rolldown writes `//#region <module>` … `//#endregion` around each
+*  module's code — exact lines, no guessing. Undefined when the chunk has none (another bundler) */
+function by_regions(code, root) {
+	if (!code.includes("\n//#region ") && !code.startsWith("//#region ")) return void 0;
+	const out = [];
+	let line = 1;
+	const open = [];
+	const names_module = (id) => id.includes("/") || id.includes("\\") || id.includes(":") || /\.[a-z]+$/i.test(id);
+	for (let i = 0; i <= code.length;) {
+		const nl = code.indexOf("\n", i);
+		const end = nl === -1 ? code.length : nl;
+		if (code.startsWith("//#region ", i)) {
+			const id = code.slice(i + 10, end).trim();
+			open.push({
+				start: line + 1,
+				id,
+				module: names_module(id)
+			});
+		} else if (code.startsWith("//#endregion", i) && open.length) {
+			const top = open.pop();
+			if (top.module) {
+				let id = top.id;
+				while (id.startsWith("../")) id = id.slice(3);
+				if (line - 1 >= top.start) out.push([
+					top.start,
+					line - 1,
+					clean_id(id, root)
+				]);
+			}
+		}
+		if (nl === -1) break;
+		i = nl + 1;
+		line++;
+	}
+	return out.length ? out : void 0;
+}
+function build_module_map(bundle, root) {
+	const chunks = {};
+	for (const item of Object.values(bundle)) {
+		const c = item;
+		if (c.type !== "chunk" || !c.fileName || !c.code || !c.modules) continue;
+		const marked = by_regions(c.code, root);
+		if (marked) {
+			chunks[c.fileName] = marked;
+			continue;
+		}
+		const out = [];
+		let cursor = 0;
+		let line = 1;
+		for (const [id, m] of Object.entries(c.modules)) {
+			if (!m.code) continue;
+			const head = m.code.slice(0, Math.min(m.code.length, 120));
+			let at = c.code.indexOf(head, cursor);
+			if (at === -1) at = c.code.indexOf(head);
+			let dropped = 0;
+			if (at === -1) {
+				const found = by_solid_line(c.code, m.code, cursor);
+				if (!found) continue;
+				at = found.at;
+				dropped = found.dropped;
+			}
+			const start = at >= cursor ? line + count_lines(c.code, cursor, at) : 1 + count_lines(c.code, 0, at);
+			const span = Math.max(1, count_lines(m.code, 0, m.code.length) - dropped);
+			const end = start + span - (m.code.endsWith("\n") ? 1 : 0);
+			const q = id.indexOf("?");
+			const clean = (q === -1 ? id : id.slice(0, q)).replace(/^\0/, "");
+			const rel = path.isAbsolute(clean) ? path.relative(root, clean).split(path.sep).join("/") : clean;
+			const nm = rel.lastIndexOf("node_modules/");
+			out.push([
+				start,
+				end,
+				nm === -1 ? rel : rel.slice(nm)
+			]);
+			if (at >= cursor) {
+				line = start + span;
+				let p = at - 1;
+				for (let k = 0; k < span && p !== -1; k++) p = c.code.indexOf("\n", p + 1);
+				cursor = p === -1 ? c.code.length : p + 1;
+			}
+		}
+		out.sort((x, y) => x[0] - y[0]);
+		for (let i = 0; i + 1 < out.length; i++) if (out[i][1] >= out[i + 1][0]) out[i][1] = out[i + 1][0] - 1;
+		if (out.length) chunks[c.fileName] = out;
+	}
+	return {
+		v: 1,
+		chunks
+	};
+}
+function write_module_map(dir, bundle, root) {
+	const map = build_module_map(bundle, root);
+	if (Object.keys(map.chunks).length) fs.writeFileSync(path.join(dir, MODULE_MAP_FILE), JSON.stringify(map));
+}
+export { MODULE_MAP_FILE, build_module_map, write_module_map };

package/dist/vite/options.d.ts

@@ -0,0 +1,208 @@
+import { ImportKeys } from "../compiler/region/transform.js";
+import { DebarrelOptions } from "../compiler/debarrel/options.js";
+/**
+ * Named strategy bundle referenced from source via `with { preset: 'name' }`
+ * (or the renamed `importKeys.preset` key).
+ *
+ * A preset speaks the SAME grammar as an inline import: a `render` mode with its timing (`fetch` for
+ * a `deferred` hole, `wake` for an island), plus the tuning options that aren't allowed inline
+ * (`margin`, `maxAge`, …).
+ */
+export interface OgygiaPreset {
+  /**
+   * Delivery mode (the `render` import attribute): `'static'` (default — an island that hydrates)
+   * | `'deferred'` (a hole whose HTML is fetched, on its `fetch` timing) | `'live'` (a hole that
+   * revalidates).
+   */
+  render?: "static" | "deferred" | "live";
+  /**
+   * When an island's JS runs (the `wake` import attribute): `'load'` | `'idle'` | `'visible'` |
+   * `'interaction'` | a CSS media query | `'none'` (a frozen lake). With `render: 'live'`, the
+   * revalidate schedule. Never a `deferred` hole's timing — that is `fetch`.
+   */
+  wake?: string;
+  /**
+   * A `render: 'deferred'` hole's timing — when its HTML arrives (the `fetch` import attribute):
+   * `'load'` (default) | `'idle'` | `'visible'` | `'interaction'` | a CSS media query.
+   */
+  fetch?: string;
+  /** `IntersectionObserver` `rootMargin` when the schedule is `'visible'`. */
+  margin?: string;
+  /**
+   * A hole (`fetch`) — response cache max-age for the hole's HTML: seconds (number) or a
+   * duration string (`'30s'` | `'5m'` | `'1h'`). Absent or `0` → `no-store`: the hole is dynamic,
+   * re-rendered on every request. A positive value opts into a `private, max-age` browser cache.
+   * Signed into the hole's endpoint so a harvested URL can't be re-pointed at a longer cache.
+   *
+   * With `render: 'live'` this is instead the client revalidate staleness — use a duration string
+   * to stay unit-explicit across both.
+   */
+  maxAge?: number | string;
+  /** `render: 'live'` — past `maxAge`, whether to clear the hole (`'empty'`) or refetch (`'fetch'`). */
+  onExpire?: "empty" | "fetch";
+  /**
+   * A hole (`fetch`) — warm the hole's HTML into the frame store on this schedule (`'load'` |
+   * `'idle'` | `'visible'` | a media query) while `fetch` still decides when it swaps in. An
+   * on-demand hole (`fetch: 'interaction'`) then has its bytes before the first hover: the gesture
+   * joins the warm frame instead of paying the origin round trip. Never `'interaction'` — that is
+   * the swap schedule, `fetch`'s job.
+   */
+  prefetch?: string;
+  /** `render: 'live'` — the revalidate schedule (`false` disables). Defaults to `wake`. */
+  revalidate?: false | string;
+  /** Continuity name (the `keep` import attribute): the live island relocates across SPA
+   *  navigation instead of remounting when the next page carries the same name. */
+  keep?: string;
+}
+/** Per-IP budget for the signed deferred-region / lake-remount endpoint. */
+export interface OgygiaRateLimit {
+  /** Max requests per window (default `60`). `0` disables allowing any. */
+  max?: number;
+  /** Sliding window length in milliseconds (default `60_000`). */
+  windowMs?: number;
+}
+/**
+ * Options for the {@link ogygia} Vite plugin. The root is the region system itself — its defaults
+ * (`visible`), its named presets (referenced from a use site by a LITERAL `preset: 'name'`:
+ * `import X from '…' with { preset: 'name' }`), its holes' capability lifetimes — beside the client
+ * router. Feature packages are Vite plugins listed beside it (`plugins: [ogygia(), flags(), sveltekit()]`).
+ *
+ * @example
+ * ```ts
+ * import { ogygia } from 'ogygia/vite';
+ * export default defineConfig({
+ *   plugins: [
+ *     ogygia({
+ *       visible: { margin: '200px' },
+ *       presets: { chart: { wake: 'visible', margin: '200px' } },
+ *       ttl: 3600
+ *     }),
+ *     sveltekit()
+ *   ]
+ * });
+ * ```
+ */
+export interface OgygiaOptions {
+  /**
+   * Defaults for regions that wake `'visible'` (`wake: 'visible'` / `render` + `wake: 'visible'`)
+   * without their own `margin` (via a preset).
+   */
+  visible?: {
+    /** Default `IntersectionObserver` `rootMargin` (e.g. `'200px'`). */
+    margin?: string;
+  };
+  /**
+   * Named strategy bundles. Reference one from an import:
+   * `import Chart from '$lib/Chart.svelte' with { preset: 'chart' };`
+   */
+  presets?: Record<string, OgygiaPreset>;
+  /**
+   * How long a deferred/live hole's signed capability URL stays valid, in seconds (default `3600`).
+   * Clamped to `[60, 86400]`. Keep short for harvested-URL risk. Holes outlive this automatically
+   * where they must: on prerendered and postrendered pages, and on a page a load marks shared-cacheable
+   * (`setHeaders({ 'cache-control': 'public, s-maxage=…' })`), where an anonymous hole is signed for
+   * the page's cache life; a hole on an older cached copy renews itself when it wakes.
+   */
+  ttl?: number;
+  /**
+   * The oldest a cached copy of a page can be and still get its holes, in seconds (default
+   * `691200`, 8 days). An anonymous hole whose capability expired while a cache kept its page
+   * renews itself for up to this long after that expiry; past it, the hole keeps its fallback.
+   * Raise it to the longest your CDN may serve a page when the page does not say so in its
+   * `cache-control`. `0` turns renewal off. Unlike `ttl` it never lengthens a hole URL's life (a
+   * renewed URL lives `ttl`), and a hole bound to a session never renews. A renewable URL replays its
+   * props: keep hole props to routing keys (a locale, a page), and read anything sensitive at render.
+   */
+  maxPageAge?: number;
+  /**
+   * Client-side SPA router — app-wide, on by default. It intercepts same-origin links, swaps
+   * `<body>`, merges `<head>`, and keeps `data-ogygia-keep` chrome across navigations. No component
+   * to place: the server handle injects the runtime + the `ogygia-router` meta into every page.
+   *
+   * - `true` (default) — router on, View Transitions on, form continuity on.
+   * - `false` — router off (the whole feature is tree-shaken out; same-origin links do full MPA
+   *   loads, and form continuity — which rides SPA navigation — goes with it).
+   * - `{ viewTransitions: false }` — router on, but no View Transitions API on navigation.
+   * - `{ forms: false }` — router on, but an island's half-filled form fields are NOT carried
+   *   across SPA navigation (continuity off).
+   * - `{ serverDelta: true }` — opt IN to server-delta nav: an SPA nav tells the server (via an
+   *   `x-ogygia-known` header) which islands it already has live, so the server SKIPS re-rendering
+   *   the unchanged ones and the client keeps them running. OFF by default (it is a new client↔server
+   *   protocol); when off the client never sends the header and the server always full-renders.
+   *
+   * Per-page escape hatch (no second config): a page opts *itself* out of View Transitions by
+   * emitting `<svelte:head><meta name="ogygia-router" content="plain" /></svelte:head>` — the handle
+   * injects the app default but a page that sets its own meta wins.
+   */
+  router?: boolean | {
+    viewTransitions?: boolean;
+    forms?: boolean;
+    serverDelta?: boolean;
+  };
+  /**
+   * Rename the import-attribute keys claimed by the transform.
+   * Defaults stay `hydrate` / `defer` / `preset`. Escape hatch if another tool already
+   * uses those names on the same imports.
+   *
+   * Preset **definitions** ({@link OgygiaOptions.presets}) still use canonical `hydrate` /
+   * `defer` / `margin` / `remount` — only the `with { … }` spellings in source change.
+   */
+  importKeys?: Partial<ImportKeys>;
+  /**
+   * Per-IP budget for the signed island endpoint served by `ogygiaHandle()`.
+   * Default `{ max: 60, windowMs: 60_000 }`. Pass `false` to disable.
+   */
+  rateLimit?: false | OgygiaRateLimit;
+  /**
+   * Cookie name to seal into the region MAC (opt-in). Empty/prerender stays unbound.
+   * Harvested capability URLs then fail verification without that cookie.
+   * Default `false` (unbound).
+   */
+  sessionCookie?: false | string;
+  /**
+   * Barrel imports become leaf imports at transform time — `import { Button } from '$lib'` (an
+   * `index.ts` that re-exports forty files) becomes `import Button from '…/Button.svelte'`, so the
+   * module graph (dev) and the chunk graph (build) hold only the leaves a file uses.
+   *
+   * - `true` — every PURE barrel in the project (outside `node_modules`) is bypassed.
+   * - `{ packages, force, keep, … }` — opt dependencies in, force impure barrels, keep some.
+   *
+   * Independent of islands: an import that carries region marks (`with { wake }` …) is never
+   * rewritten — a barrel binding is marked through `asRegion` or a mark in the barrel, as before.
+   * The same plugin is `debarrel()` from `'ogygia/vite'` for any Vite app.
+   */
+  barrels?: boolean | DebarrelOptions;
+  /**
+   * @internal Recreate this plugin instance inside the standalone client build.
+   * App authors should not set this.
+   */
+  standalone?: boolean;
+}
+/** The rename map: 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
+ * a broken preset nobody references yet should still fail the build, not lurk.
+ */
+export declare function validate_region_presets(presets: Record<string, unknown>): void;
+/** The router/capability config resolved from `OgygiaOptions` — pure derivation the factory reads. */
+export interface ResolvedOgygiaConfig {
+  rate_limit: {
+    max: number;
+    windowMs: number;
+  };
+  session_cookie: string;
+  region_ttl: number;
+  renew_window: number;
+  router_enabled: boolean;
+  router_view_transitions: boolean;
+  continuity_forms: boolean;
+  server_delta: boolean;
+}
+/**
+ * Normalize the router / rate-limit / session / ttl / continuity / server-delta options into the flat
+ * config the factory threads into `CompileCtx` + `Program`. Pure — no defaults leak back into `options`.
+ * `defaultRegionTtl` / `defaultRenewWindow` are passed in (the endpoint's DEFAULT_REGION_TTL_SEC,
+ * shared-cache's RENEW_WINDOW_SEC) to keep this Vite-free.
+ */
+export declare function resolve_options(options: OgygiaOptions, defaultRegionTtl: number, defaultRenewWindow?: number): ResolvedOgygiaConfig;

package/dist/vite/options.js

@@ -0,0 +1,74 @@
+// 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. */
+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]}`);
+}
+const REGION_PRESET_KEYS = /* @__PURE__ */ new Set([
+	"render",
+	"wake",
+	"fetch",
+	"margin",
+	"maxAge",
+	"onExpire",
+	"revalidate",
+	"keep",
+	"stitch",
+	"prefetch"
+]);
+/**
+* Config-time region-preset validation — the transform re-checks on USE (with file/line context), but
+* a broken preset nobody references yet should still fail the build, not lurk.
+*/
+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(", ")}.`);
+	}
+}
+/**
+* Normalize the router / rate-limit / session / ttl / continuity / server-delta options into the flat
+* config the factory threads into `CompileCtx` + `Program`. Pure — no defaults leak back into `options`.
+* `defaultRegionTtl` / `defaultRenewWindow` are passed in (the endpoint's DEFAULT_REGION_TTL_SEC,
+* shared-cache's RENEW_WINDOW_SEC) to keep this Vite-free.
+*/
+function resolve_options(options, defaultRegionTtl, defaultRenewWindow = 691200) {
+	const rate_limit = options.rateLimit === false ? {
+		max: 0,
+		windowMs: 6e4
+	} : {
+		max: Math.max(0, options.rateLimit?.max ?? 60),
+		windowMs: Math.max(1, options.rateLimit?.windowMs ?? 6e4)
+	};
+	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.`);
+	const renew_window = Math.min(31536e4, Math.floor(renew_raw ?? defaultRenewWindow));
+	const router_enabled = options.router !== false;
+	return {
+		rate_limit,
+		session_cookie,
+		region_ttl,
+		renew_window,
+		router_enabled,
+		router_view_transitions: options.router === false ? false : typeof options.router === "object" ? options.router.viewTransitions !== false : true,
+		continuity_forms: router_enabled && (typeof options.router === "object" ? options.router.forms !== false : true),
+		server_delta: router_enabled && typeof options.router === "object" && options.router.serverDelta === true
+	};
+}
+export { assert_no_legacy_options, resolve_options, validate_region_presets };

package/dist/vite/package-files.d.ts

@@ -0,0 +1,3 @@
+import { PackageScan } from "../compiler/ctx.js";
+export declare function discover_package_files(app_root: string): PackageScan[];
+export type { PackageScan };

package/dist/vite/package-files.js

@@ -0,0 +1,84 @@
+import { OWN_PACKAGE_NAMES } from "../own-package.js";
+import fs from "node:fs";
+import path from "node:path";
+import { globSync } from "tinyglobby";
+// src/vite/package-files.ts
+/**
+* `ogygia.files` — a dependency package DECLARES its ogygia compile surface in its OWN
+* package.json, npm-`files`-style (bare dirs recurse, globs allowed):
+*
+*     { "ogygia": { "files": ["./src/components", "./src/admin-routes.ts", "./dist/**\/*.js"] } }
+*
+* Only declared packages are ever scanned — walking every dependency would be slow AND wrong —
+* and only their declared paths. The consumer configures NOTHING: discovery reads the app's
+* direct dependencies' manifests (a handful of tiny file reads), and the plugin turns each
+* declaration into ssr.noExternal + optimizeDeps.exclude + prescan roots + transform gates.
+*
+* Everything is realpath'd: Vite resolves module ids through symlinks (pnpm), so gate matching
+* must speak real paths or every check silently misses.
+*/
+const posix = (p) => p.split(path.sep).join("/");
+/** npm-glob magic — a bare path is stat'd, anything magic goes through the glob expander. */
+const GLOB_MAGIC_RE = /[*?{}[\]!]/;
+function read_manifest(dir) {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function discover_package_files(app_root) {
+	const app = read_manifest(app_root);
+	if (!app) return [];
+	const deps = [...Object.keys(app.dependencies ?? {}), ...Object.keys(app.devDependencies ?? {})];
+	const found = [];
+	for (const name of deps) {
+		if (OWN_PACKAGE_NAMES.includes(name)) continue;
+		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)}.`);
+		let root;
+		try {
+			root = fs.realpathSync(pkg_dir);
+		} catch {
+			continue;
+		}
+		const dirs = [];
+		const files = /* @__PURE__ */ new Set();
+		for (const entry of declared) {
+			if (GLOB_MAGIC_RE.test(entry)) {
+				for (const m of globSync(entry, {
+					cwd: root,
+					absolute: true,
+					dot: false
+				})) {
+					if (!posix(m).startsWith(posix(root) + "/")) continue;
+					try {
+						files.add(posix(fs.realpathSync(m)));
+					} catch {}
+				}
+				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.`);
+			let stat;
+			try {
+				stat = fs.statSync(abs);
+			} catch {
+				console.warn(`[ogygia] ${name}: ogygia.files entry '${entry}' does not exist — skipped.`);
+				continue;
+			}
+			if (stat.isDirectory()) dirs.push(posix(fs.realpathSync(abs)));
+			else files.add(posix(fs.realpathSync(abs)));
+		}
+		if (dirs.length || files.size) found.push({
+			name,
+			root: posix(root),
+			dirs,
+			files: [...files]
+		});
+	}
+	return found;
+}
+export { discover_package_files };