@ogygia/core 0.0.0 → 0.11.0

package/dist/compiler/ownership-stamps.js

@@ -0,0 +1,144 @@
+import { blank_styles } from "./blank-styles.js";
+import { strip_bom } from "./bom.js";
+import { HTML_PARENT_ATTR, OPAQUE_ATTR } from "../runtime/ownership.js";
+import { parse } from "svelte/compiler";
+import MagicString from "magic-string";
+// src/compiler/ownership-stamps.ts
+/**
+* OWNERSHIP STAMPS — declared, not inferred (internal/notes/dom-ownership.md §4).
+*
+* The runtime's pre-hydration repair keeps an island's DOM in the shape Svelte's hydration walk
+* binds by position, and must leave alone what the walk never reads — but the runtime cannot tell the
+* two apart from the DOM: Svelte's PROD output opens an `{@html}` block with the same `<!---->` it uses
+* as a separator everywhere. The compiler can. This server-leg pass stamps `data-og-opaque` on the
+* element shapes whose CHILDREN Svelte's hydration never walks (svelte 5 client: `html.js`,
+* `RegularElement.js`, `fragment.js` `is_static_element`):
+*
+*  - an element whose only non-whitespace child is `{@html}` — the controlled form: the walk takes the
+*    element and never descends;
+*  - an element with `bind:innerHTML` / `bind:textContent` / `bind:innerText` — Svelte owns its
+*    content wholesale, by value, not by walking it;
+*  - a custom element whose descendants are all static (no expression, block, component, render tag,
+*    `{@html}` or directive, only literal attributes) — Svelte keeps a reference to the host and never
+*    descends its children.
+*
+* A web component living there can rework its own light DOM before the island wakes and the repair,
+* the drift watch and the morph leave it alone (runtime/ownership.ts). The stamp is an attribute on
+* the SERVER render only: hydration never compares or strips static attributes, it adds no node (a
+* node would shift the positional walk), and the client template is untouched.
+*/
+/** A cheap presence test before parsing: one of the three shapes could be in this file. */
+const MAY_STAMP_RE = /\{@html|bind:(?:innerHTML|textContent|innerText)|<[a-z][\w.]*-[\w-]*[\s/>]|\sis=/;
+const WHOLESALE_BINDS = /* @__PURE__ */ new Set([
+	"innerHTML",
+	"textContent",
+	"innerText"
+]);
+/** Template node kinds that make content dynamic (anything Svelte must walk to bind). */
+const DYNAMIC_KINDS = /* @__PURE__ */ new Set([
+	"ExpressionTag",
+	"HtmlTag",
+	"RenderTag",
+	"ConstTag",
+	"DebugTag",
+	"AttachTag",
+	"IfBlock",
+	"EachBlock",
+	"AwaitBlock",
+	"KeyBlock",
+	"SnippetBlock",
+	"Component",
+	"SvelteComponent",
+	"SvelteElement",
+	"SvelteSelf",
+	"SvelteFragment",
+	"SvelteBoundary",
+	"SlotElement"
+]);
+const is_blank = (n) => n.type === "Text" && !String(n.data ?? "").trim();
+/** Every attribute on an element is a plain literal (no `{expr}`), and it carries no directive. */
+function literal_attributes(el) {
+	for (const a of el.attributes ?? []) {
+		if (a.type !== "Attribute") return false;
+		const v = a.value;
+		if (v === true) continue;
+		if ((Array.isArray(v) ? v : [v]).some((p) => p.type !== "Text")) return false;
+	}
+	return true;
+}
+/** Every descendant of `nodes` is static: plain text, comments, elements with literal attributes. */
+function all_static(nodes) {
+	for (const n of nodes) {
+		if (n.type === "Text" || n.type === "Comment") continue;
+		if (DYNAMIC_KINDS.has(n.type)) return false;
+		if (n.type !== "RegularElement") return false;
+		if (!literal_attributes(n)) return false;
+		if (!all_static(n.fragment?.nodes ?? [])) return false;
+	}
+	return true;
+}
+function is_custom_element(el) {
+	return String(el.name).includes("-") || (el.attributes ?? []).some((a) => a.type === "Attribute" && a.name === "is");
+}
+/** Does Svelte's hydration walk never enter this element's children? */
+function opaque(el) {
+	if ((el.attributes ?? []).some((a) => a.type === "Attribute" && a.name === "data-og-opaque")) return false;
+	const kids = (el.fragment?.nodes ?? []).filter((n) => !is_blank(n));
+	if (kids.length === 1 && kids[0].type === "HtmlTag") return true;
+	if ((el.attributes ?? []).some((a) => a.type === "BindDirective" && WHOLESALE_BINDS.has(a.name))) return true;
+	return is_custom_element(el) && all_static(el.fragment?.nodes ?? []);
+}
+const CHILD_KEYS = [
+	"fragment",
+	"consequent",
+	"alternate",
+	"body",
+	"pending",
+	"then",
+	"catch",
+	"fallback"
+];
+/**
+* `source` with every opaque element stamped, or `null` when there is nothing to stamp (or the file
+* does not parse — the real compile reports that). Outermost wins: nothing is stamped inside a stamped
+* element (the repair never enters it anyway).
+*/
+function stamp_opaque(raw, filename) {
+	const source = strip_bom(raw);
+	if (!MAY_STAMP_RE.test(source)) return null;
+	let ast;
+	try {
+		ast = parse(blank_styles(source), {
+			modern: true,
+			filename
+		});
+	} catch {
+		return null;
+	}
+	const at = [];
+	const visit = (nodes) => {
+		for (const n of nodes ?? []) {
+			if (n.type === "RegularElement" && opaque(n)) {
+				at.push({
+					pos: n.start + 1 + String(n.name).length,
+					attr: OPAQUE_ATTR
+				});
+				continue;
+			}
+			if (n.type === "RegularElement" && (n.fragment?.nodes ?? []).some((c) => c.type === "HtmlTag") && !(n.attributes ?? []).some((a) => a.type === "Attribute" && (a.name === "data-og-html" || a.name === "data-og-opaque"))) at.push({
+				pos: n.start + 1 + String(n.name).length,
+				attr: HTML_PARENT_ATTR
+			});
+			for (const k of CHILD_KEYS) {
+				const child = n[k];
+				if (child && Array.isArray(child.nodes)) visit(child.nodes);
+			}
+		}
+	};
+	visit(ast.fragment?.nodes);
+	if (!at.length) return null;
+	const s = new MagicString(source);
+	for (const { pos, attr } of at) s.appendLeft(pos, " " + attr);
+	return s.toString();
+}
+export { stamp_opaque };

package/dist/compiler/parse/oxc.d.ts

@@ -0,0 +1,34 @@
+/**
+ * An AST node as the compiler's passes read it: the parser seam's output (oxc's ESTree, or whatever
+ * parser {@link set_parser} installed) and Svelte's template AST, walked generically and read by field
+ * name. Kept loose on purpose: the walkers index arbitrary fields (`node[key]`), and some passes accept
+ * node shapes beyond oxc's (store.ts also matches Babel's `StringLiteral` / `ObjectProperty`), which a
+ * precise ESTree union would rule out. The one loose node type every pass shares.
+ */
+export type AstNode = Record<string, any>;
+type Node = AstNode;
+export type Comment = {
+  start: number;
+  end: number;
+};
+export type ParseResult = {
+  program: Node | null;
+  ok: boolean;
+  comments: Comment[];
+};
+/** The raw oxc parse signature (`(id, code) → { program, errors, comments }`). */
+export type RawParse = (id: string, code: string) => {
+  program?: Node;
+  errors?: unknown[];
+  comments?: Comment[];
+};
+/** Install a browser (or test) parser with the same call shape. No-arg reset restores the default. */
+export declare function set_parser(fn?: RawParse): void;
+/**
+ * Parse `code` (named by `id`, whose extension picks the dialect) to an oxc/ESTree program. Never
+ * throws: a syntax error (or a half-typed file mid-edit) yields `{ program: null, ok: false }`, and
+ * callers fall back (scanner) or skip. Offsets on the returned nodes are exact against `code`.
+ * `comments` carries trivia (block/line) with byte offsets — not present in the AST body.
+ */
+export declare function parse_module(code: string, id: string): ParseResult;
+export {};

package/dist/compiler/parse/oxc.js

@@ -0,0 +1,59 @@
+import { createRequire } from "node:module";
+// src/compiler/parse/oxc.ts
+/**
+* The one parser the `import.meta.og.*` transforms use. It must (a) parse TypeScript — the constructs
+* live in `.ts`/`.svelte.ts` and `<script lang="ts">` — and (b) preserve BYTE OFFSETS against the
+* original source, because every transform splices by span. That rules out `parseAst` (rollup's
+* parser: no TS) and type-stripping (shifts offsets).
+*
+* The parser comes from the app's required `vite` peer: Vite 8 re-exports the TS-capable oxc parser
+* as `parseSync` (byte-identical to `rolldown/utils`' — verified), so ogygia carries no `rolldown`
+* dependency of its own for this. NOT a shaky choice: `parseAst` is the rollup-compat parser (throws
+* on TS); `parseSync` is the oxc parser. One import, one decision.
+*/
+/**
+* The parser is INJECTABLE so the SAME oxc can run in the browser (the Observatory / Rung 1). Node
+* uses the default `rolldown/utils` (native); a browser build installs `@rolldown/browser/utils`
+* (WASM, the SAME rolldown version → byte-identical AST) via {@link set_parser}, after awaiting the
+* WASM init. This is the seam, not a parser swap for Node: the default below is unchanged, so the
+* production build parses exactly as before. (bake() keeps rolldown too, so this is consistency —
+* same parser both realms — not a new dependency.)
+*/
+let node_parse_sync;
+function node_default_parse(id, code) {
+	if (!node_parse_sync) node_parse_sync = createRequire(import.meta.url)("vite").parseSync;
+	return node_parse_sync(id, code);
+}
+let raw_parse = node_default_parse;
+/** Install a browser (or test) parser with the same call shape. No-arg reset restores the default. */
+function set_parser(fn) {
+	raw_parse = fn ?? node_default_parse;
+}
+/**
+* Parse `code` (named by `id`, whose extension picks the dialect) to an oxc/ESTree program. Never
+* throws: a syntax error (or a half-typed file mid-edit) yields `{ program: null, ok: false }`, and
+* callers fall back (scanner) or skip. Offsets on the returned nodes are exact against `code`.
+* `comments` carries trivia (block/line) with byte offsets — not present in the AST body.
+*/
+function parse_module(code, id) {
+	try {
+		const result = raw_parse(id, code);
+		if (result.errors && result.errors.length > 0) return {
+			program: null,
+			ok: false,
+			comments: []
+		};
+		return {
+			program: result.program ?? null,
+			ok: !!result.program,
+			comments: result.comments ?? []
+		};
+	} catch {
+		return {
+			program: null,
+			ok: false,
+			comments: []
+		};
+	}
+}
+export { parse_module, set_parser };

package/dist/compiler/parse/scan.d.ts

@@ -0,0 +1,43 @@
+/** A `/` begins a regex (not division) when the previous significant char is an operator/opener —
+ *  always the case for a regex option value (`{ page: /…/ }`, `[/…/, /…/]`). */
+export declare function regex_context(prev: string): boolean;
+/** Index of the `)` matching the `(` at `open`, skipping strings, comments, and regex literals
+ *  (incl. `[…]` char classes, which may hold an unescaped `/`). -1 if unbalanced. */
+export declare function match_close(src: string, open: number): number;
+/** One located `import.meta.og.<method>(<args>)` call. `args` is the VERBATIM text between the
+ *  parens; `method` is the dotted tail after the shared prefix (`loader.git`, `code`, `regions`). */
+export type OgCall = {
+  start: number;
+  end: number;
+  method: string;
+  args: string;
+};
+/**
+ * Find every `<prefix><method>(…)` call in `src`. `prefix` is the literal namespace head
+ * (`import.meta.og.`); `method` is the dotted identifier chain that follows, up to the `(`. Skips
+ * strings/comments/regex so a marker in prose is never a false hit. Pure.
+ */
+export declare function find_og_calls(src: string, prefix: string): OgCall[];
+/** Split a call's argument text into the first string-literal (unquoted) and the verbatim rest.
+ *  Throws (with `who` in the message) when the first argument is not a STATIC string literal — a
+ *  bare identifier, or a template literal with `${…}` interpolation (not build-determinable). */
+export declare function split_first_string(args: string, who: string): {
+  value: string;
+  rest: string;
+};
+/** A slice of JS/TS to analyze, plus where it starts in the original source (for offset mapping). */
+export type JsRegion = {
+  code: string;
+  offset: number;
+};
+/** Does `id` (a module path, maybe with a `?query`) end in a plain JS/TS extension? */
+export declare function is_js_module(id: string): boolean;
+/** Does `id` end in one of the configured MARKUP extensions (`.svelte`, `.svx`, `.md`)? */
+export declare function is_markup_module(id: string, markup_exts: readonly string[]): boolean;
+/**
+ * Extract the JS regions of a module for construct analysis. Returns `null` when the extension is not
+ * a recognized construct host (the caller then leaves the file untouched). A JS/TS module is one
+ * region; a markup file is its `<script>` blocks. `.svelte.ts`/`.svelte.js` hit the JS branch first
+ * (they end in `.ts`/`.js`), so a `.svelte`-suffixed markup ext never shadows them.
+ */
+export declare function og_js_regions(src: string, id: string, markup_exts: readonly string[]): JsRegion[] | null;

package/dist/compiler/parse/scan.js

@@ -0,0 +1,232 @@
+// src/compiler/parse/scan.ts
+/**
+* The string-aware macro SCANNER — the cheap-bailout front-end for `import.meta.og.*`.
+*
+* Two jobs, no full parse:
+*   • the LEXER (`find_og_calls` / `match_close` / `split_first_string`) locates
+*     `import.meta.og.<path>(…)` CALLS in a module's source with a single left-to-right pass that
+*     skips strings, comments, and regex literals, so a marker inside a doc comment or a string is
+*     never mistaken for a call.
+*   • the EXTRACTOR (`og_js_regions` / `is_js_module` / `is_markup_module`) decides where those
+*     constructs are recognized per file type, and yields the JS slices to analyze.
+*
+* Why not an AST? These rewrites run in the Vite `transform` hook on EVERY module (svelte/ts/js) —
+* a parse per module per construct is the tax we refuse. The scanner is O(n), allocation-light, and
+* (critically) survives partial/invalid syntax mid-edit in dev. The git loader proved it; this is
+* that scanner, generalized so all constructs share one code path.
+*/
+const REGEX_FLAG_RE = /[a-z]/i;
+const WS_RE = /\s/;
+const TEMPLATE_INTERPOLATION_RE = /\$\{/;
+/** A `/` begins a regex (not division) when the previous significant char is an operator/opener —
+*  always the case for a regex option value (`{ page: /…/ }`, `[/…/, /…/]`). */
+function regex_context(prev) {
+	return prev === "" || "([{,;:=!&|?+-~^<>*%".includes(prev);
+}
+/** Index of the `)` matching the `(` at `open`, skipping strings, comments, and regex literals
+*  (incl. `[…]` char classes, which may hold an unescaped `/`). -1 if unbalanced. */
+function match_close(src, open) {
+	let depth = 0;
+	let prev = "";
+	for (let i = open; i < src.length; i++) {
+		const c = src[i];
+		const c2 = src[i + 1];
+		if (c === "'" || c === "\"" || c === "`") {
+			const q = c;
+			for (i++; i < src.length; i++) if (src[i] === "\\") i++;
+			else if (src[i] === q) break;
+			prev = c;
+			continue;
+		}
+		if (c === "/" && c2 === "/") {
+			for (i += 2; i < src.length && src[i] !== "\n"; i++);
+			continue;
+		}
+		if (c === "/" && c2 === "*") {
+			for (i += 2; i < src.length && !(src[i] === "*" && src[i + 1] === "/"); i++);
+			i++;
+			continue;
+		}
+		if (c === "/" && regex_context(prev)) {
+			let in_class = false;
+			for (i++; i < src.length; i++) {
+				const r = src[i];
+				if (r === "\\") i++;
+				else if (r === "[") in_class = true;
+				else if (r === "]") in_class = false;
+				else if (r === "/" && !in_class) break;
+			}
+			while (i + 1 < src.length && REGEX_FLAG_RE.test(src[i + 1])) i++;
+			prev = "/";
+			continue;
+		}
+		if (c === "(" || c === "{" || c === "[") {
+			depth++;
+			prev = c;
+			continue;
+		}
+		if (c === ")" || c === "}" || c === "]") {
+			if (--depth === 0) return i;
+			prev = c;
+			continue;
+		}
+		if (!WS_RE.test(c)) prev = c;
+	}
+	return -1;
+}
+const IDENT = /[A-Za-z0-9_$.]/;
+/**
+* Find every `<prefix><method>(…)` call in `src`. `prefix` is the literal namespace head
+* (`import.meta.og.`); `method` is the dotted identifier chain that follows, up to the `(`. Skips
+* strings/comments/regex so a marker in prose is never a false hit. Pure.
+*/
+function find_og_calls(src, prefix) {
+	const calls = [];
+	const head = prefix[0];
+	let prev = "";
+	for (let i = 0; i < src.length; i++) {
+		const c = src[i];
+		const c2 = src[i + 1];
+		if (c === "'" || c === "\"" || c === "`") {
+			const q = c;
+			for (i++; i < src.length; i++) if (src[i] === "\\") i++;
+			else if (src[i] === q) break;
+			prev = c;
+			continue;
+		}
+		if (c === "/" && c2 === "/") {
+			for (i += 2; i < src.length && src[i] !== "\n"; i++);
+			continue;
+		}
+		if (c === "/" && c2 === "*") {
+			for (i += 2; i < src.length && !(src[i] === "*" && src[i + 1] === "/"); i++);
+			i++;
+			continue;
+		}
+		if (c === "/" && regex_context(prev)) {
+			let in_class = false;
+			for (i++; i < src.length; i++) {
+				const r = src[i];
+				if (r === "\\") i++;
+				else if (r === "[") in_class = true;
+				else if (r === "]") in_class = false;
+				else if (r === "/" && !in_class) break;
+			}
+			while (i + 1 < src.length && REGEX_FLAG_RE.test(src[i + 1])) i++;
+			prev = "/";
+			continue;
+		}
+		if (c === head && src.startsWith(prefix, i)) {
+			let p = i + prefix.length;
+			const name_start = p;
+			while (p < src.length && IDENT.test(src[p])) p++;
+			const method = src.slice(name_start, p);
+			let q = p;
+			while (q < src.length && WS_RE.test(src[q])) q++;
+			if (method && src[q] === "(") {
+				const close = match_close(src, q);
+				if (close >= 0) {
+					calls.push({
+						start: i,
+						end: close + 1,
+						method,
+						args: src.slice(q + 1, close)
+					});
+					i = close;
+					prev = ")";
+					continue;
+				}
+			}
+			i = p - 1;
+			prev = "t";
+			continue;
+		}
+		if (!WS_RE.test(c)) prev = c;
+	}
+	return calls;
+}
+/** Split a call's argument text into the first string-literal (unquoted) and the verbatim rest.
+*  Throws (with `who` in the message) when the first argument is not a STATIC string literal — a
+*  bare identifier, or a template literal with `${…}` interpolation (not build-determinable). */
+function split_first_string(args, who) {
+	let i = 0;
+	while (i < args.length && WS_RE.test(args[i])) i++;
+	const q = args[i];
+	if (q !== "'" && q !== "\"" && q !== "`") throw new Error(`[ogygia] ${who}: the first argument must be a static string literal, got '${args.slice(0, 24)}…'`);
+	let j = i + 1;
+	for (; j < args.length; j++) if (args[j] === "\\") j++;
+	else if (args[j] === q) break;
+	const value = args.slice(i + 1, j);
+	if (q === "`" && TEMPLATE_INTERPOLATION_RE.test(value)) throw new Error(`[ogygia] ${who}: the first argument must be a static string literal — a template literal with \${…} interpolation is a runtime value the build cannot resolve.`);
+	let k = j + 1;
+	while (k < args.length && WS_RE.test(args[k])) k++;
+	if (k < args.length && args[k] !== ",") throw new Error(`[ogygia] ${who}: the first argument must be a static string literal, but it is part of a larger expression (near '${args.slice(i, k + 8)}…'). Use one plain string.`);
+	if (args[k] === ",") k++;
+	return {
+		value,
+		rest: args.slice(k).trim()
+	};
+}
+const JS_EXT = /\.(ts|js|mjs|cjs|mts|cts)$/;
+/** Does `id` (a module path, maybe with a `?query`) end in a plain JS/TS extension? */
+function is_js_module(id) {
+	const clean = id.split("?")[0];
+	return JS_EXT.test(clean);
+}
+/** Does `id` end in one of the configured MARKUP extensions (`.svelte`, `.svx`, `.md`)? */
+function is_markup_module(id, markup_exts) {
+	const clean = id.split("?")[0];
+	return markup_exts.some((ext) => clean.endsWith(ext));
+}
+/**
+* Extract the JS regions of a module for construct analysis. Returns `null` when the extension is not
+* a recognized construct host (the caller then leaves the file untouched). A JS/TS module is one
+* region; a markup file is its `<script>` blocks. `.svelte.ts`/`.svelte.js` hit the JS branch first
+* (they end in `.ts`/`.js`), so a `.svelte`-suffixed markup ext never shadows them.
+*/
+function og_js_regions(src, id, markup_exts) {
+	if (is_js_module(id)) return [{
+		code: src,
+		offset: 0
+	}];
+	if (is_markup_module(id, markup_exts)) return script_blocks(src);
+	return null;
+}
+/**
+* Find every `<script …>…<\/script>` block and return its inner JS + byte offset. A single forward
+* scan (not a regex) so a `<\/script>` inside a JS string can't end a block early: we only close on a
+* `<\/script>` found while scanning raw text, and Svelte itself forbids an unescaped `<\/script>` in
+* script text, so this matches the compiler's own tokenization.
+*/
+function script_blocks(src) {
+	const regions = [];
+	const lower = src.toLowerCase();
+	let i = 0;
+	for (;;) {
+		const open = lower.indexOf("<script", i);
+		if (open < 0) break;
+		const gt = tag_end(src, open);
+		if (gt < 0) break;
+		const close = lower.indexOf("<\/script>", gt + 1);
+		if (close < 0) break;
+		regions.push({
+			code: src.slice(gt + 1, close),
+			offset: gt + 1
+		});
+		i = close + 9;
+	}
+	return regions;
+}
+/** Index of the `>` that ends the tag opened at `open`, honoring quoted attribute values. */
+function tag_end(src, open) {
+	for (let i = open; i < src.length; i++) {
+		const c = src[i];
+		if (c === "\"" || c === "'") {
+			for (i++; i < src.length && src[i] !== c; i++);
+			continue;
+		}
+		if (c === ">") return i;
+	}
+	return -1;
+}
+export { find_og_calls, is_js_module, is_markup_module, match_close, og_js_regions, regex_context, split_first_string };

package/dist/compiler/program.d.ts

@@ -0,0 +1,140 @@
+import { FlagSite } from "./flags.js";
+import { AllReason, PageKeys, PendingCall } from "./link/page-keys.js";
+import { RuntimeMarks } from "./link/runtime-entry.js";
+/** Strip a `?query` off a module id (host vs component vs Vite watch paths). */
+export declare const strip_id: (id: string) => string;
+/** Canonical absolute host key (query-stripped, resolved) — the registry's cross-host dedupe key. */
+export declare const host_key: (hostPath: string) => string;
+/** One row in the virtual-module registry — an island's entry / wrapper / region-binding artifact.
+ *  Loose by design: the three roles carry different legs (source vs ssrSource/clientSource). */
+export interface RegistryEntry {
+  source?: string;
+  ssrSource?: string;
+  clientSource?: string;
+  hostPath?: string | null;
+  id: string;
+  server?: boolean;
+  lakes?: string[];
+  componentPath?: string | null;
+  role?: "entry" | "wrapper" | "region" | "lazy";
+  portable?: boolean;
+  /** a server entry's render identity (identity.ts `renderId`): what its endpoint renders */
+  renderId?: string;
+}
+/** What a host's last transform indexed: the region ids + virtual paths it minted. */
+interface HostIndexEntry {
+  ids: Set<string>;
+  vpaths: Set<string>;
+}
+/** One island a file's Lower phase minted — the `register`-relevant fields of a lowered descriptor.
+ *  Loose (most fields optional) because the three legs — entry / wrapper / region binding — differ. */
+export interface IslandDescriptor {
+  id: string;
+  kind?: "hydrate" | "defer" | "lake";
+  server?: boolean;
+  fetchWhen?: string;
+  strategy?: string;
+  wakeAfter?: string;
+  held?: boolean;
+  lakes?: string[];
+  keep?: string;
+  portable?: boolean;
+  wrapperPath?: string;
+  wrapperSource?: string;
+  /** the wrapper's client leg (lazy component; see emit.ts `island_wrapper_client_source`) */
+  wrapperClientSource?: string;
+  /** the lazy component module the client wrapper imports (`lazyEntryVirtualId`) */
+  lazyPath?: string;
+  lazySource?: string;
+  bindingPath?: string;
+  bindingSsrSource?: string;
+  bindingClientSource?: string;
+  hostPath?: string | null;
+  componentPath?: string | null;
+  virtualPath?: string;
+  source?: string;
+  /** the region identity (identity.ts `regionIdentity`) the id was hashed from */
+  identity?: string;
+}
+/** The relevant shape of a file's transform result the linker registers. */
+export interface RegisterResult {
+  islands?: IslandDescriptor[];
+  /** THE one wire question a compilation answers: can this file cross live content into an island?
+   *  The transform owns all the evidence — static placement with children, a portable `{#snippet}`,
+   *  a wake binding with no static placement (registry/each/`svelte:component`/prop hand-off, where
+   *  call sites are compile-invisible), a `.ts`-minted wake region. One flag here, one rule below;
+   *  the server encoder is not gated, so a missed case is a production app whose islands ALL fail
+   *  with "Unknown type OgygiaRef" (the factory-registry regression). */
+  hasWireCrossing?: boolean;
+}
+export declare class Program {
+  /** keyed by virtual path → the island's registry row (entry / wrapper / region binding) */
+  readonly registry: Map<string, RegistryEntry>;
+  /** Absolute module ids in an island's CLIENT dependency graph. `$app/*` resolves to shims
+   *  for these importers (virtual island module AND its transitive component imports). */
+  readonly island_graph: Set<string>;
+  /** iid -> entry virtual path (hydrate / defer / swr-lake) */
+  readonly by_id: Map<string, string>;
+  /** every region id -> kind (server manifest / emit) */
+  readonly region_kinds: Map<string, "hydrate" | "defer" | "lake">;
+  /** host abs path → region ids + virtual paths discovered on last transform of that host */
+  readonly host_index: Map<string, HostIndexEntry>;
+  /** region id → hosts still claiming it (cross-host dedupe: don't drop shared wrappers) */
+  readonly id_hosts: Map<string, Set<string>>;
+  /** Client-leg: hydrate island ids whose deterministic chunk has been emitFile'd (dedup across the
+   *  buildStart prescan emit AND the transform-time emit that catches islands prescan can't see —
+   *  those declared inside LIBRARY components, where the host lives outside the app's `src`). */
+  readonly emitted_island_chunks: Set<string>;
+  /** BUILD, server leg: every module id Vite actually transformed (`host_key`-normalised) — the
+   *  server bundle's real graph. Handed to the client leg, which emits island chunks only for
+   *  islands whose HOST is in it: the prescan registers every marked import under `src/`, but a
+   *  host nothing imports (a second route tree's pages, a retired component) must not cost a
+   *  chunk — or drag its imports into a client build whose server pass never saw them (a
+   *  `.remote.ts` there fails Kit's "expected to find metadata" check). */
+  readonly ssr_transformed: Set<string>;
+  /** Absolute paths of app modules that define a transportable class (built during prescan). */
+  readonly transportable_modules: Set<string>;
+  /** PAGE MODULES (`b.pageModules()`: importers of a page specifier such as `'@ogygia/router'`, plus
+   *  files named directly — server-router definition sites) + every walked
+   *  module's import specifiers — the build data `virtual:ogygia/router-css` computes its
+   *  component closure from (see link/router-css.ts). Filled during the prescan walk. */
+  readonly router_modules: Set<string>;
+  readonly module_specs: Map<string, string[]>;
+  /** flag()/experiment() call sites the prescan OBSERVED (modules importing 'ogygia' only) —
+   *  written to node_modules/.ogygia/flags-manifest.json at build for CI flag-debt diffs. */
+  readonly flag_sites: FlagSite[];
+  /** SEED SHAPING: per module (query-less id, forward slashes), the top-level `page.data` keys its
+   *  code reads — `'all'` when a read could not be pinned to a literal key. Recorded by the driver's
+   *  transform for every module that imports Kit's page store (link/page-keys.ts); the client
+   *  `writeBundle` unions them over each island's chunk closure (link/island-deps.ts), and the
+   *  handle ships only those keys of `page.data`. */
+  readonly page_keys: Map<string, PageKeys>;
+  /** Per module that answered `'all'`: why, and on which line — the build report names it, so a
+   *  developer sees the one read that makes a page ship its whole `page.data`. */
+  readonly page_key_reasons: Map<string, AllReason>;
+  /** Per module: the `helper(page)` calls into IMPORTED helpers the build follows at `writeBundle`
+   *  (resolve the specifier, summarize the export, fold the answer into `page_keys`). */
+  readonly page_pending: Map<string, PendingCall[]>;
+  /** App crosses a held region / transportable value through Kit's `transport` hook — a `.remote.*`
+   *  file, or a `region`/`site`/content import (loads & remotes that carry regions or wired values).
+   *  Set during the prescan walk; with `runtime_marks.wire` it decides whether `ogygia.transport`
+   *  (the generated `virtual:ogygia/kit-transport`) carries the codec cluster or is an empty map. */
+  crosses_wire: boolean;
+  /** Build-time capability marks for the sticky runtime entry. Incomplete → kitchen-sink. */
+  readonly runtime_marks: RuntimeMarks;
+  /** The resolved feature set folded into the runtime chunk name (busts the immutable URL when the
+   *  app's feature set changes, not only when ogygia's source does). Filled by the driver's prescan;
+   *  empty until then (dev serves the package entry). Both build legs prescan the same source → same
+   *  hash → the server↔client filename handoff holds. */
+  runtime_feature_hash: string;
+  constructor(init: {
+    forms: boolean;
+    router: boolean;
+  });
+  note_runtime_mark(patch: Partial<RuntimeMarks>): void;
+  /** Drop this host's claims; shared region ids (cross-host dedupe) stay until unused. */
+  unregister_host(hostPath: string): void;
+  /** Replace this host's claims; shared ids keep one registry entry (path+strategy dedupe). */
+  register(result: RegisterResult, hostId: string): void;
+}
+export {};