@ogygia/core 0.0.0 → 0.11.0

package/dist/compiler/link/registry-stub.d.ts

@@ -0,0 +1,41 @@
+export declare const REGISTRY_STUB_PREFIX = "virtual:ogygia/registry-stub/";
+/** The query that names a registry's client-leg variant (its marks blanked, everything else kept). */
+export declare const REGISTRY_CLIENT_QUERY = "?og-registry-client";
+/** The client-leg variant id of a registry: its real absolute path (relative imports resolve from
+ *  the registry's own directory) plus {@link REGISTRY_CLIENT_QUERY}. */
+export declare function registry_client_id(abs_path: string): string;
+/** The registry path a client-leg variant id names, or `null` for any other id. */
+export declare function registry_client_path(id: string): string | null;
+/**
+ * The static VALUE import specifiers of a script module — `import … from`, side-effect `import '…'`,
+ * `export … from`, `export * from` (type-only forms skipped; dynamic `import()` skipped: Kit links
+ * no CSS for a node's dynamic chunks). `null` when the module does not parse.
+ */
+export declare function static_script_specs(source: string, file: string): string[] | null;
+/**
+ * The registry's source with its MARKS blanked and everything else kept, or `null` when it does not
+ * parse (the caller falls back to the names-only stub). A mark is an import whose `with { … }`
+ * carries a region key (`region_keys`: the app's wake / render / region / preset names), or a
+ * component handed to `import.meta.og.asRegion(…)`. Each blanked binding becomes
+ * `const X = undefined` so the module still links; the client leg never runs it anyway.
+ */
+export declare function registry_client_source(source: string, file: string, region_keys: ReadonlySet<string>): string | null;
+/** Root-relative posix path → the stub id. `names` are the exports the stub must declare. */
+export declare function registry_stub_id(rel_posix: string, names: Iterable<string>): string;
+/** True for a (resolved or bare) stub id. */
+export declare function is_registry_stub_id(id: string): boolean;
+/** The export names a stub id carries (`default` included when the registry has one). */
+export declare function registry_stub_names(id: string): string[];
+/** The stub module's source: every name as `undefined`, so the host links and nothing is shipped. */
+export declare function registry_stub_source(names: readonly string[]): string;
+/**
+ * The names a module exports, scanned from its source (declarations, `export { a, b as c }`,
+ * `export default`). A textual scan — registries are plain TypeScript lists, and a name the scan
+ * misses is covered by {@link imported_names} (what the host actually asks for).
+ */
+export declare function export_names(source: string): Set<string>;
+/**
+ * The names `importer_source` imports from `spec` (default → `default`, named → their exported
+ * names, `* as ns` → nothing extra: a namespace import links against whatever the stub declares).
+ */
+export declare function imported_names(importer_source: string, spec: string): Set<string>;

package/dist/compiler/link/registry-stub.js

@@ -0,0 +1,212 @@
+import { parse_module } from "../parse/oxc.js";
+import { walk } from "estree-walker";
+// src/compiler/link/registry-stub.ts
+/**
+* `virtual:ogygia/registry-stub/…` — keep a REGION REGISTRY out of a csr=false page's client graph.
+*
+* THE LEAK: a `.ts` registry (`import Card from './Card.svelte' with { wake: 'visible' }` × N, the
+* Builder / CMS block-factory shape) is a plain module to Kit. A csr=false route host that imports
+* it pulls every marked component's WRAPPER — and through it the real component, its scoped CSS and
+* its chunk closure — into that page node's client graph. Kit then links `node.stylesheets` for the
+* whole registry on every page the host serves: one large landing page linked 163 stylesheets
+* (337 registry marks) for 21 rendered islands, all render-blocking. The client never runs any of it
+* — a csr=false document ships no Kit client at all; the node's JS exists only so Kit can link CSS.
+*
+* THE RULE: what a page needs is decided at SSR, by the render pass — Region.svelte links the CSS of
+* every region that actually renders (`island_css_html` / `region_css_html`, claimed per request) and
+* preloads its chunk. So on the csr=false CLIENT leg of a BUILD a route host's import of a registry
+* resolves to this stub: a module exporting the same NAMES (as `undefined`) so the bundle links, and
+* nothing else. The registry module itself is untouched — a csr=true page (Kit hydrates it, so it
+* needs the real wrappers) and the island world keep importing the real thing. Dev keeps the graph
+* (Vite serves CSS as modules there; a stub would unstyle the page).
+*
+* PLAIN IMPORTS STAY. A registry also holds PLAIN imports (a heading, a banner wrapper: no `with`).
+* Those render on the server and never pass through Region, so the page node's client graph is the
+* only thing that links their CSS — a names-only stub left them unstyled on every deploy (dev keeps
+* the graph, so it never showed there). The client-leg registry is therefore the registry ITSELF
+* with only its marks blanked ({@link registry_client_source}): every plain import, re-export,
+* barrel and style import keeps its edge, resolved from the registry's own directory (the module id
+* is the real path plus {@link REGISTRY_CLIENT_QUERY}), so Kit links their CSS exactly as before the
+* stub. Their CSS is linked whether they render or not — the price of the graph deciding; marked
+* imports stay out, which is the leak this module exists for.
+*/
+const REGISTRY_STUB_PREFIX = "virtual:ogygia/registry-stub/";
+/** The query that names a registry's client-leg variant (its marks blanked, everything else kept). */
+const REGISTRY_CLIENT_QUERY = "?og-registry-client";
+/** The client-leg variant id of a registry: its real absolute path (relative imports resolve from
+*  the registry's own directory) plus {@link REGISTRY_CLIENT_QUERY}. */
+function registry_client_id(abs_path) {
+	return abs_path + REGISTRY_CLIENT_QUERY;
+}
+/** The registry path a client-leg variant id names, or `null` for any other id. */
+function registry_client_path(id) {
+	return id.endsWith("?og-registry-client") ? id.slice(0, -19) : null;
+}
+/** True when `node` is `import.meta.og.<prop>`. */
+function is_og_macro(node, prop) {
+	return node?.type === "MemberExpression" && node.property?.name === prop && node.object?.type === "MemberExpression" && node.object.property?.name === "og" && node.object.object?.type === "MetaProperty" && node.object.object.meta?.name === "import" && node.object.object.property?.name === "meta";
+}
+/**
+* The static VALUE import specifiers of a script module — `import … from`, side-effect `import '…'`,
+* `export … from`, `export * from` (type-only forms skipped; dynamic `import()` skipped: Kit links
+* no CSS for a node's dynamic chunks). `null` when the module does not parse.
+*/
+function static_script_specs(source, file) {
+	const parsed = parse_module(source, file);
+	if (!parsed.ok || !parsed.program) return null;
+	const specs = [];
+	for (const node of parsed.program.body) {
+		if (!(node.type === "ImportDeclaration" || node.type === "ExportAllDeclaration" || node.type === "ExportNamedDeclaration" && node.source) || node.importKind === "type" || node.exportKind === "type") continue;
+		const value = node.source?.value;
+		if (typeof value === "string") specs.push(value);
+	}
+	return specs;
+}
+/** `const a = undefined, b = undefined;` for the given locals (empty string for none). */
+function undefined_consts(locals) {
+	return locals.length ? `const ${locals.map((l) => `${l} = undefined`).join(", ")};` : "";
+}
+/**
+* The registry's source with its MARKS blanked and everything else kept, or `null` when it does not
+* parse (the caller falls back to the names-only stub). A mark is an import whose `with { … }`
+* carries a region key (`region_keys`: the app's wake / render / region / preset names), or a
+* component handed to `import.meta.og.asRegion(…)`. Each blanked binding becomes
+* `const X = undefined` so the module still links; the client leg never runs it anyway.
+*/
+function registry_client_source(source, file, region_keys) {
+	const parsed = parse_module(source, file);
+	if (!parsed.ok || !parsed.program) return null;
+	const body = parsed.program.body;
+	const edits = [];
+	const as_region_args = /* @__PURE__ */ new Set();
+	walk(parsed.program, { enter(n) {
+		const node = n;
+		if (node.type !== "CallExpression") return;
+		if (is_og_macro(node.callee, "regions")) {
+			edits.push({
+				start: node.start,
+				end: node.end,
+				text: "({})"
+			});
+			this.skip();
+			return;
+		}
+		if (!is_og_macro(node.callee, "asRegion")) return;
+		const arg = node.arguments?.[0];
+		if (arg?.type === "Identifier") as_region_args.add(arg.name);
+		edits.push({
+			start: node.start,
+			end: node.end,
+			text: "undefined"
+		});
+		this.skip();
+	} });
+	for (const node of body) {
+		if (node.type !== "ImportDeclaration" || node.importKind === "type") continue;
+		const specifiers = node.specifiers ?? [];
+		const marked = (node.attributes ?? []).some((a) => region_keys.has(a.key?.name ?? a.key?.value));
+		const dropped = specifiers.filter((s) => marked || s.importKind !== "type" && as_region_args.has(s.local.name));
+		if (!dropped.length) continue;
+		const kept = specifiers.filter((s) => !dropped.includes(s));
+		const consts = undefined_consts(dropped.map((s) => s.local.name));
+		if (!kept.length) {
+			edits.push({
+				start: node.start,
+				end: node.end,
+				text: consts
+			});
+			continue;
+		}
+		const head = kept.filter((s) => s.type !== "ImportSpecifier").map((s) => source.slice(s.start, s.end));
+		const named = kept.filter((s) => s.type === "ImportSpecifier").map((s) => source.slice(s.start, s.end));
+		if (named.length) head.push(`{ ${named.join(", ")} }`);
+		const spec = source.slice(node.source.start, node.source.end);
+		edits.push({
+			start: node.start,
+			end: node.end,
+			text: `import ${head.join(", ")} from ${spec}; ${consts}`
+		});
+	}
+	if (!edits.length) return source;
+	edits.sort((a, b) => b.start - a.start);
+	let out = source;
+	for (const e of edits) out = out.slice(0, e.start) + e.text + out.slice(e.end);
+	return out;
+}
+const NAMES_PARAM = "?names=";
+const EXPORT_DECL_G = /^\s*export\s+(?:async\s+)?(?:const|let|var|function\*?|class|enum|abstract\s+class)\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_LIST_G = /^\s*export\s*\{([^}]*)\}/gm;
+const EXPORT_DEFAULT_RE = /^\s*export\s+default\b/m;
+const IMPORT_FROM_G = /import\s+(?:type\s+)?([^'";]*?)\s*from\s*(['"])([^'"]+)\2/g;
+const IMPORT_SIDE_EFFECT_RE = /^\s*$/;
+const AS_RE = /\s+as\s+/;
+const WS_G = /\s+/g;
+/** Root-relative posix path → the stub id. `names` are the exports the stub must declare. */
+function registry_stub_id(rel_posix, names) {
+	const sorted = [...new Set(names)].sort();
+	return `${REGISTRY_STUB_PREFIX}${encodeURIComponent(rel_posix)}.js${NAMES_PARAM}${sorted.map(encodeURIComponent).join(",")}`;
+}
+/** True for a (resolved or bare) stub id. */
+function is_registry_stub_id(id) {
+	return (id.startsWith("\0") ? id.slice(1) : id).startsWith(REGISTRY_STUB_PREFIX);
+}
+/** The export names a stub id carries (`default` included when the registry has one). */
+function registry_stub_names(id) {
+	const at = id.indexOf(NAMES_PARAM);
+	if (at < 0) return [];
+	return id.slice(at + 7).split(",").filter(Boolean).map(decodeURIComponent);
+}
+/** The stub module's source: every name as `undefined`, so the host links and nothing is shipped. */
+function registry_stub_source(names) {
+	let out = "";
+	for (const n of names) if (n === "default") out += "export default undefined;\n";
+	else if (/^[A-Za-z_$][\w$]*$/.test(n)) out += `export const ${n} = undefined;\n`;
+	return out || "export {};\n";
+}
+/**
+* The names a module exports, scanned from its source (declarations, `export { a, b as c }`,
+* `export default`). A textual scan — registries are plain TypeScript lists, and a name the scan
+* misses is covered by {@link imported_names} (what the host actually asks for).
+*/
+function export_names(source) {
+	const names = /* @__PURE__ */ new Set();
+	EXPORT_DECL_G.lastIndex = 0;
+	let m;
+	while (m = EXPORT_DECL_G.exec(source)) names.add(m[1]);
+	EXPORT_LIST_G.lastIndex = 0;
+	while (m = EXPORT_LIST_G.exec(source)) for (const part of m[1].split(",")) {
+		const p = part.trim();
+		if (!p) continue;
+		const [, alias] = p.split(AS_RE);
+		const name = (alias ?? p).trim();
+		if (name === "default" || /^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+	}
+	if (EXPORT_DEFAULT_RE.test(source)) names.add("default");
+	return names;
+}
+/**
+* The names `importer_source` imports from `spec` (default → `default`, named → their exported
+* names, `* as ns` → nothing extra: a namespace import links against whatever the stub declares).
+*/
+function imported_names(importer_source, spec) {
+	const names = /* @__PURE__ */ new Set();
+	IMPORT_FROM_G.lastIndex = 0;
+	let m;
+	while (m = IMPORT_FROM_G.exec(importer_source)) {
+		if (m[3] !== spec) continue;
+		const clause = m[1].replace(WS_G, " ").trim();
+		if (IMPORT_SIDE_EFFECT_RE.test(clause)) continue;
+		const brace = clause.indexOf("{");
+		const head = (brace >= 0 ? clause.slice(0, brace) : clause).replace(",", "").trim();
+		if (head && !head.startsWith("*")) names.add("default");
+		if (brace >= 0) for (const part of clause.slice(brace + 1, clause.indexOf("}")).split(",")) {
+			const p = part.trim().replace(/^type\s+/, "");
+			if (!p) continue;
+			const [exported] = p.split(AS_RE);
+			const name = exported.trim();
+			if (name) names.add(name);
+		}
+	}
+	return names;
+}
+export { REGISTRY_CLIENT_QUERY, REGISTRY_STUB_PREFIX, export_names, imported_names, is_registry_stub_id, registry_client_id, registry_client_path, registry_client_source, registry_stub_id, registry_stub_names, registry_stub_source, static_script_specs };

package/dist/compiler/link/router-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `virtual:ogygia/router-config` emitter.
+ *
+ * The handle reads this to inject the runtime + `ogygia-router` meta into every page head (app-wide
+ * SPA router). With the router OFF (MPA mode) the handle injects static Speculation Rules instead
+ * (`mpaSpeculationRules`, built by the handle: they leave out its islands endpoint, which the handle
+ * knows and the build does not).
+ *
+ * Pure over the two resolved router flags.
+ */
+export declare function router_config_module(router_enabled: boolean, router_view_transitions: boolean): string;

package/dist/compiler/link/router-config.js

@@ -0,0 +1,15 @@
+// src/compiler/link/router-config.ts
+/**
+* `virtual:ogygia/router-config` emitter.
+*
+* The handle reads this to inject the runtime + `ogygia-router` meta into every page head (app-wide
+* SPA router). With the router OFF (MPA mode) the handle injects static Speculation Rules instead
+* (`mpaSpeculationRules`, built by the handle: they leave out its islands endpoint, which the handle
+* knows and the build does not).
+*
+* Pure over the two resolved router flags.
+*/
+function router_config_module(router_enabled, router_view_transitions) {
+	return `export const enabled = ${router_enabled};\nexport const viewTransitions = ${router_view_transitions};`;
+}
+export { router_config_module };

package/dist/compiler/link/router-css.d.ts

@@ -0,0 +1,22 @@
+export declare const ROUTER_CSS_KEY_PREFIX = "rcss:";
+/** The handoff css-map key for one root component (posix-rel to the app root). */
+export declare function router_css_key(root: string, abs: string): string;
+/**
+ * The `.svelte` ROOTS of the app's router modules: BFS from every page module (`b.pageModules()`),
+ * through relative/`$lib` `.ts`/`.js` re-exports (barrels — resolved as build
+ * DATA, imports untouched), collecting `.svelte` leaves. `module_specs` is the prescan's import-spec
+ * record (module abs path → its import/export-from specifiers). Sorted for determinism across legs.
+ */
+export declare function router_css_roots(router_modules: ReadonlySet<string>, module_specs: ReadonlyMap<string, readonly string[]>, lib_dir: string, exists?: (p: string) => boolean): string[];
+/**
+ * Emit the `virtual:ogygia/router-css` source. Empty (`export {}`) when the app has no router
+ * modules — the router's dynamic import of this virtual then registers nothing, zero cost.
+ */
+export declare function router_css_module(roots: readonly string[], opts: {
+  root: string;
+  lib_dir: string;
+  is_dev: boolean;
+  read_file: (p: string) => string | null;
+  /** the bundler's resolver, for the dev tree-CSS walk (compiler/fouc-css.ts) */
+  resolve?: (spec: string, importer: string) => Promise<string | null>;
+}): Promise<string>;

package/dist/compiler/link/router-css.js

@@ -0,0 +1,142 @@
+import { fs, path } from "../host.js";
+import { collectFoucCssReachable, compileFoucScopedCss, resolveFoucImportSpec } from "../fouc-css.js";
+// src/compiler/link/router-css.ts
+/**
+* `virtual:ogygia/router-css` — how a SERVER-ROUTER page's `<style>` reaches the document.
+*
+* THE GAP: Kit links a route's stylesheets from its file-derived route manifest. `@ogygia/router`
+* routes are VALUES (`r.page(Home)`) rendered through `document()` — no route, so nothing ever
+* emitted or linked their CSS: a router page's scoped `<style>` (and its plain `.css` imports)
+* silently never loaded. (The router fixture app's own rtr components are style-less for exactly this reason.)
+*
+* THE FIX, from existing primitives — no user file is modified, no `r.*` call-site analysis:
+*  1. CLOSURE (build data): a router MODULE is a PAGE MODULE a plugin named (`b.pageModules()`): any
+*     module importing one of its specifiers (`'@ogygia/router'`), or a file it names — wherever it
+*     lives, however many routers it defines, whatever function wraps them. Its transitive `.svelte`
+*     imports (followed through relative/$lib `.ts`/`.js` barrels — build-data resolution, not import
+*     rewriting) are the components any of its routers could render: the ROOTS.
+*  2. EMISSION (client leg, vite/index.ts): each root's whole transitive CSS (its own scoped styles +
+*     every child component's + plain `.css` imports, in cascade order) is compiled and emitted as ONE
+*     dedicated asset — resolved to a handoff `rcss:<rel>` href in writeBundle. A dedicated asset (not
+*     a chunk's `importedCss`) is immune to rolldown's shared-chunk CSS hoisting, which otherwise
+*     scatters a shared child's scoped CSS onto whatever chunk rolldown parks it on — an island's, off
+*     the router's static graph entirely (every profiler page shares Shell → this bites in practice).
+*  3. REGISTRATION (this virtual, SSR): imports each root by absolute path — the same module instance
+*     the router module holds, so identity survives barrels — and registers it in the runtime WeakMap
+*     with a thunk resolving its stylesheet entries (prod: handoff hrefs + `$app/paths` base; dev:
+*     inline CSS compiled here, Kit-style).
+*  4. LINKING (render): the router hands the components it actually renders to `componentCssHead()`
+*     (`ogygia/plugin/css`), which claims through
+*     `claim_region_css` (deduped with held-region links), and hands `document()` the head tags.
+*/
+const PATH_SEP = /[/\\]/;
+const SVELTE_RE = /\.svelte$/;
+const BARREL_RE = /\.(?:ts|js|mjs)$/;
+const CSS_EXT_RE = /\.css$/;
+/** Candidate suffixes for an extensionless spec, Vite resolution order-ish. */
+const RESOLVE_SUFFIXES = [
+	"",
+	".ts",
+	".js",
+	".mjs",
+	".svelte",
+	"/index.ts",
+	"/index.js"
+];
+const ROUTER_CSS_KEY_PREFIX = "rcss:";
+const posix = (p) => p.split(PATH_SEP).join("/");
+/** The handoff css-map key for one root component (posix-rel to the app root). */
+function router_css_key(root, abs) {
+	return ROUTER_CSS_KEY_PREFIX + posix(path.relative(root, abs));
+}
+/**
+* The `.svelte` ROOTS of the app's router modules: BFS from every page module (`b.pageModules()`),
+* through relative/`$lib` `.ts`/`.js` re-exports (barrels — resolved as build
+* DATA, imports untouched), collecting `.svelte` leaves. `module_specs` is the prescan's import-spec
+* record (module abs path → its import/export-from specifiers). Sorted for determinism across legs.
+*/
+function router_css_roots(router_modules, module_specs, lib_dir, exists = (p) => {
+	try {
+		return fs.statSync(p).isFile();
+	} catch {
+		return false;
+	}
+}) {
+	const roots = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const resolve_spec = (spec, importer) => {
+		const base = resolveFoucImportSpec(spec.split("?")[0], importer, lib_dir);
+		if (!base) return null;
+		for (const suffix of RESOLVE_SUFFIXES) {
+			const candidate = path.normalize(base + suffix);
+			if (exists(candidate)) return candidate;
+		}
+		return null;
+	};
+	const visit = (mod) => {
+		if (visited.has(mod)) return;
+		visited.add(mod);
+		for (const spec of module_specs.get(mod) ?? []) {
+			const resolved = resolve_spec(spec, mod);
+			if (!resolved) continue;
+			if (SVELTE_RE.test(resolved)) roots.add(resolved);
+			else if (BARREL_RE.test(resolved)) visit(resolved);
+		}
+	};
+	for (const mod of router_modules) visit(mod);
+	return [...roots].sort();
+}
+/**
+* Emit the `virtual:ogygia/router-css` source. Empty (`export {}`) when the app has no router
+* modules — the router's dynamic import of this virtual then registers nothing, zero cost.
+*/
+async function router_css_module(roots, opts) {
+	if (roots.length === 0) return "export {};\n";
+	const lines = [`import { register_router_css } from 'ogygia/internal/register';`];
+	if (opts.is_dev) {
+		const assignments = [];
+		for (const abs of roots) {
+			const entries = [];
+			for (const e of await collectFoucCssReachable(abs, {
+				resolve: opts.resolve,
+				root: opts.root,
+				libDir: opts.lib_dir,
+				readFile: opts.read_file
+			})) {
+				const e_rel = posix(path.relative(opts.root, e.abs));
+				if (e.kind === "scoped") {
+					const source = opts.read_file(e.abs);
+					if (source == null) continue;
+					const css = compileFoucScopedCss(e.abs, source);
+					if (css) entries.push({
+						key: `rcss-dev:${e_rel}`,
+						css
+					});
+				} else {
+					if (!CSS_EXT_RE.test(e.abs)) continue;
+					const css = opts.read_file(e.abs);
+					if (css) entries.push({
+						key: `rcss-dev:${e_rel}`,
+						css
+					});
+				}
+			}
+			if (!entries.length) continue;
+			const abs_key = JSON.stringify(posix(abs));
+			const rel = posix(path.relative(opts.root, abs));
+			const keys = rel.startsWith("..") || path.isAbsolute(rel) ? [abs_key] : [abs_key, JSON.stringify(rel)];
+			assignments.push(`m[${keys.join("] = m[")}] = ${JSON.stringify(entries)};`);
+		}
+		return `import { register_router_css_paths } from 'ogygia/internal/register';\nconst m = {};\n${assignments.join("\n")}\nregister_router_css_paths(m);\n`;
+	}
+	lines.push(`import { islandCss } from 'virtual:ogygia/island-deps';`);
+	lines.push(`const base = typeof __SVELTEKIT_PATHS_BASE__ !== 'undefined' ? __SVELTEKIT_PATHS_BASE__ : '';`);
+	for (let i = 0; i < roots.length; i++) {
+		const abs = roots[i];
+		const key = router_css_key(opts.root, abs);
+		lines.push(`import __OgRcss${i} from ${JSON.stringify(abs)};`);
+		lines.push(`register_router_css(__OgRcss${i}, () => islandCss(${JSON.stringify(key)}).map((h) => ({ key: h, href: base + h })));`);
+	}
+	return lines.join("\n") + "\n";
+}
+export { ROUTER_CSS_KEY_PREFIX, router_css_key, router_css_module, router_css_roots };

package/dist/compiler/link/runtime-entry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime feature catalog — maps build-time marks → installable plugins.
+ * Module paths are absolute file URLs resolved by the Vite plugin against dist/src.
+ */
+export type RuntimeMarks = {
+  /** When false/undefined, emit kitchen-sink (safe default). */
+  complete?: boolean;
+  hydrate?: string[];
+  defer?: string[];
+  persist?: boolean;
+  persistKeys?: string[];
+  router?: boolean;
+  live?: boolean;
+  morph?: boolean;
+  lakes?: boolean;
+  forms?: boolean;
+  wire?: boolean;
+  remoteSeeds?: boolean;
+  /** App imports an ogygia context provider (`Provide` / `setContext` / `createContext`). Set by the
+   *  driver's import scan; gates the cross-island context bridge (~4.7 kB) out of apps that never
+   *  provide context. Read-only providers (`getContext`) don't set it — there's nothing to bridge. */
+  context?: boolean;
+};
+export type FeatureId = "remote-seeds" | "wire" | "frames" | "lakes" | "morph" | "live" | "interaction" | "forms" | "router" | "context";
+/**
+ * WHICH CHUNK a feature lives in. The runtime ships as two static, feature-sized phases:
+ *
+ * - `boot` — the runtime entry (`og-runtime.*.js`), loaded by the `<script>` in `<head>`. Defines
+ *   `<ogygia-region>`, schedules wakes, fetches holes, morphs, routes. It must never reach Svelte:
+ *   in a real app Svelte's client runtime is ONE shared chunk (~200 KB), and anything in the boot's
+ *   static graph downloads first, ahead of the page's own LCP image, before any island needs it.
+ * - `hydrate` — the hydrate core (`runtime/hydrate-core.js`), loaded by the runtime's single existing
+ *   `import()` when the first island wakes, together with Svelte (which `hydrate()` needs anyway). A
+ *   feature whose slot only the hydrate core reads belongs here, installed as the chunk evaluates.
+ *
+ * Both phases are generated from the same marks, so each is exactly as big as the app needs; no
+ * feature adds a dynamic import of its own. `test/runtime-boot-svelte-free.test.ts` pins the boot.
+ */
+export type FeaturePhase = "boot" | "hydrate";
+export type FeatureDef = {
+  /** Path relative to `runtime/` (no leading ./). */
+  module: string;
+  deps: FeatureId[];
+  detect: (m: RuntimeMarks) => boolean;
+  /** Default `boot`. See {@link FeaturePhase}. */
+  phase?: FeaturePhase;
+};
+export declare const FEATURES: Record<FeatureId, FeatureDef>;
+export declare const FEATURE_ORDER: FeatureId[];
+/** Resolve the closed feature set for a marks manifest. */
+export declare function resolveFeatures(marks: RuntimeMarks): FeatureId[];
+/** The selected features of one {@link FeaturePhase}, in FEATURE_ORDER. */
+export declare function phaseFeatures(marks: RuntimeMarks, phase: FeaturePhase): FeatureId[];
+/**
+ * Emit the BOOT entry: core + the selected boot-phase features (see {@link FeaturePhase}).
+ * @param runtimeDir Absolute directory containing `core.js` + the feature modules.
+ */
+export declare function generateRuntimeEntrySource(marks: RuntimeMarks, runtimeDir: string, clientPlugins?: readonly string[]): {
+  code: string;
+  features: FeatureId[];
+};
+/**
+ * Emit the HYDRATE-phase feature module (`virtual:ogygia/hydrate-features`), which the hydrate core
+ * imports statically and installs as its chunk evaluates — so these features ride the hydrate core's
+ * one existing `import()`, sized by the same marks as the boot. `all` (dev / no marks): every one.
+ * @param runtimeDir Absolute directory containing the feature modules.
+ */
+export declare function generateHydrateFeaturesSource(marks: RuntimeMarks, runtimeDir: string, all?: boolean): {
+  code: string;
+  features: FeatureId[];
+};

package/dist/compiler/link/runtime-entry.js

@@ -0,0 +1,132 @@
+// src/compiler/link/runtime-entry.ts
+const HYPHEN = /-/g;
+const BACKSLASH = /\\/g;
+const FEATURES = {
+	interaction: {
+		module: "interaction.js",
+		deps: [],
+		detect: (m) => (m.hydrate || []).some((w) => w !== "none")
+	},
+	forms: {
+		module: "form-continuity.js",
+		deps: [],
+		detect: (m) => m.forms === true || m.forms !== false && m.router === true
+	},
+	router: {
+		module: "router.js",
+		deps: [],
+		detect: (m) => m.router === true
+	},
+	lakes: {
+		module: "lakes.js",
+		deps: [],
+		detect: (m) => m.lakes === true || (m.hydrate || []).includes("none")
+	},
+	morph: {
+		module: "morph.js",
+		deps: [],
+		detect: (m) => m.live === true || m.morph === true || m.router === true || (m.defer || []).length > 0
+	},
+	live: {
+		module: "live.js",
+		deps: [],
+		phase: "hydrate",
+		detect: (m) => m.live === true || m.persist === true || (m.persistKeys || []).length > 0
+	},
+	wire: {
+		module: "../live-transport.js",
+		deps: [],
+		phase: "hydrate",
+		detect: (m) => m.wire === true
+	},
+	"remote-seeds": {
+		module: "remote-seeds.js",
+		deps: [],
+		phase: "hydrate",
+		detect: (m) => m.remoteSeeds !== false
+	},
+	frames: {
+		module: "frames.js",
+		deps: [],
+		detect: (m) => (m.defer || []).length > 0 || m.live === true || m.morph === true || m.lakes === true
+	},
+	context: {
+		module: "context.js",
+		deps: [],
+		phase: "hydrate",
+		detect: (m) => m.context === true
+	}
+};
+const FEATURE_ORDER = [
+	"remote-seeds",
+	"wire",
+	"frames",
+	"lakes",
+	"morph",
+	"live",
+	"interaction",
+	"forms",
+	"router",
+	"context"
+];
+/** Resolve the closed feature set for a marks manifest. */
+function resolveFeatures(marks) {
+	if (!marks.complete) return [...FEATURE_ORDER];
+	const selected = /* @__PURE__ */ new Set();
+	for (const id of FEATURE_ORDER) if (FEATURES[id].detect(marks)) selected.add(id);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const id of Array.from(selected)) for (const d of FEATURES[id].deps) if (!selected.has(d)) {
+			selected.add(d);
+			changed = true;
+		}
+	}
+	return FEATURE_ORDER.filter((id) => selected.has(id));
+}
+const to_alias = (id) => id.replace(HYPHEN, "_");
+const runtime_path = (runtimeDir, mod) => `${runtimeDir}/${mod}`.replace(BACKSLASH, "/");
+/** The selected features of one {@link FeaturePhase}, in FEATURE_ORDER. */
+function phaseFeatures(marks, phase) {
+	return resolveFeatures(marks).filter((id) => (FEATURES[id].phase ?? "boot") === phase);
+}
+/**
+* Emit the BOOT entry: core + the selected boot-phase features (see {@link FeaturePhase}).
+* @param runtimeDir Absolute directory containing `core.js` + the feature modules.
+*/
+function generateRuntimeEntrySource(marks, runtimeDir, clientPlugins = []) {
+	const features = phaseFeatures(marks, "boot");
+	const lines = [];
+	lines.push(`/** generated ogygia runtime — features: ${features.join(", ") || "(core only)"} */`);
+	lines.push(`import { boot } from ${JSON.stringify(runtime_path(runtimeDir, "core.js"))};`);
+	for (const id of features) lines.push(`import * as ${to_alias(id)} from ${JSON.stringify(runtime_path(runtimeDir, FEATURES[id].module))};`);
+	clientPlugins.forEach((spec, i) => lines.push(`import __og_client_${i} from ${JSON.stringify(spec)};`));
+	lines.push("");
+	lines.push("boot([");
+	for (const id of features) lines.push(`  ${to_alias(id)}.install,`);
+	lines.push(clientPlugins.length ? `], [${clientPlugins.map((_, i) => `__og_client_${i}`).join(", ")}]);` : "]);");
+	return {
+		code: lines.join("\n") + "\n",
+		features
+	};
+}
+/**
+* Emit the HYDRATE-phase feature module (`virtual:ogygia/hydrate-features`), which the hydrate core
+* imports statically and installs as its chunk evaluates — so these features ride the hydrate core's
+* one existing `import()`, sized by the same marks as the boot. `all` (dev / no marks): every one.
+* @param runtimeDir Absolute directory containing the feature modules.
+*/
+function generateHydrateFeaturesSource(marks, runtimeDir, all = false) {
+	const features = all ? FEATURE_ORDER.filter((id) => FEATURES[id].phase === "hydrate") : phaseFeatures(marks, "hydrate");
+	const lines = [];
+	lines.push(`/** generated ogygia hydrate-phase features: ${features.join(", ") || "(none)"} */`);
+	for (const id of features) lines.push(`import * as ${to_alias(id)} from ${JSON.stringify(runtime_path(runtimeDir, FEATURES[id].module))};`);
+	lines.push("export function install() {");
+	for (const id of features) lines.push(`  ${to_alias(id)}.install();`);
+	lines.push("}");
+	return {
+		code: lines.join("\n") + "\n",
+		features
+	};
+}
+export { FEATURES, FEATURE_ORDER, generateHydrateFeaturesSource, generateRuntimeEntrySource, phaseFeatures, resolveFeatures };

package/dist/compiler/link/server-manifest.d.ts

@@ -0,0 +1,12 @@
+import { Program } from "../program.js";
+/** The SERVER-island ids the manifest carries right now (deferred / server-picked regions). */
+export declare function server_island_ids(program: Program): string[];
+export declare function server_manifest_module(ssr: boolean, program: Program, is_dev: boolean, devUrlFor: (virtualPath: string) => string, publicUrlFor: (iid: string) => string): string;
+/** `virtual:ogygia/server-islands`: each SERVER island's loader, `id → () => import(entry)` (empty on
+ *  the client). Imported only by the manifest's `load_islands()` — never statically. */
+export declare function server_islands_module(ssr: boolean, program: Program): string;
+/** The token the build replaces with its answer (driver `patch_page_data_reads`), inside a string
+ *  literal the bundler cannot fold: a plain `null` placeholder was inlined into every reader as the
+ *  constant it was (every hole then looked its page up). Unpatched it parses to nothing → `null`. */
+export declare const PAGE_DATA_READS_TOKEN = "__OGYGIA_PAGE_DATA_READS__";
+export declare const PAGE_DATA_READS_PLACEHOLDER: `(() => { try { return JSON.parse("${typeof PAGE_DATA_READS_TOKEN}"); } catch { return null; } })()`;