@pyreon/compiler 0.15.0 → 0.18.0

package/lib/index.js

@@ -7,6 +7,312 @@ import * as fs from "node:fs";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import ts from "typescript";
 
+//#region src/defer-inline.ts
+/**
+* Inline-children transform for `<Defer>`.
+*
+* Rewrites:
+*
+*     import { Modal } from './Modal'
+*     <Defer when={open()}><Modal /></Defer>
+*
+* into:
+*
+*     <Defer when={open()} chunk={() => import('./Modal').then(m => ({ default: m.Modal }))}>
+*       {C => <C />}
+*     </Defer>
+*
+* The static `import { Modal } from './Modal'` is removed when `Modal` is
+* referenced ONLY inside the Defer subtree — otherwise Rolldown would
+* bundle the module statically and the dynamic import becomes a no-op.
+*
+* Scope of v1 (this file):
+*   - Single Defer element per file (no nested handling — bail otherwise).
+*   - Children: exactly ONE JSXElement, self-closing, capitalised name
+*     (component reference), no props. Props or multiple children → leave
+*     the Defer untransformed (user must use the explicit `chunk` form).
+*   - Imports: named OR default. Namespace imports (`import * as Mod`)
+*     and destructured-renamed (`{ X as Y }`) not handled in v1.
+*   - Triggers (`when={...}`, `on="visible"`, `on="idle"`) pass through.
+*   - Other props on `<Defer>` (e.g. `fallback`) pass through.
+*
+* The transform is intentionally conservative — anything unusual leaves
+* the source unchanged + emits a warning. v2 follow-ups can relax these
+* constraints with closure-capture handling, namespace imports, etc.
+*
+* Pipeline: this runs BEFORE `transformJSX()` in the vite plugin. The
+* output is still JSX — `transformJSX` then converts it to `h()` /
+* `_tpl()` calls as usual.
+*/
+/**
+* Detect the language for `parseSync`. `oxc-parser` infers from filename
+* by extension — we mirror the same logic for the few extensions we
+* support so the parser is invoked correctly.
+*/
+function getLang$1(filename) {
+	if (filename.endsWith(".tsx")) return "tsx";
+	if (filename.endsWith(".jsx")) return "jsx";
+	if (filename.endsWith(".ts")) return "ts";
+	return "js";
+}
+/**
+* Returns the JSX tag name as a string when the opening element's name
+* is a simple identifier (the only shape we recognise as a "named JSX
+* element"). Member-expression names (`<obj.X />`) and namespaced names
+* (`<svg:rect />`) return null — the caller treats those as non-matches.
+*/
+function getJsxName(node) {
+	const open = node.openingElement;
+	if (!open) return null;
+	const name = open.name;
+	if (!name || name.type !== "JSXIdentifier") return null;
+	return name.name;
+}
+/**
+* `<Tag />` qualifies as a "bare component reference child" when:
+*   - It's a JSXElement (not text, fragment, or expression container).
+*   - The opening name is a capitalised JSXIdentifier (component).
+*   - It has no attributes (no props passed).
+*   - It's self-closing OR has zero non-whitespace children.
+*/
+function isBareComponentChild(node) {
+	if (node.type !== "JSXElement") return null;
+	const tag = getJsxName(node);
+	if (!tag || !/^[A-Z]/.test(tag)) return null;
+	if ((node.openingElement.attributes ?? []).length > 0) return null;
+	const children = node.children ?? [];
+	for (const child of children) {
+		if (child.type === "JSXText" && /^\s*$/.test(child.value)) continue;
+		return null;
+	}
+	return { name: tag };
+}
+/**
+* Filter whitespace-only JSXText nodes; return remaining children. JSX
+* source like `<Defer>\n  <Modal />\n</Defer>` has 3 children at the AST
+* level: text, element, text. The text nodes are formatting noise.
+*/
+function nonWhitespaceChildren(node) {
+	return (node.children ?? []).filter((c) => !(c.type === "JSXText" && /^\s*$/.test(c.value)));
+}
+function findDeferMatches(program) {
+	const matches = [];
+	const walk = (node) => {
+		if (!node || typeof node !== "object") return;
+		if (node.type === "JSXElement" && getJsxName(node) === "Defer") {
+			const open = node.openingElement;
+			if (!(open.attributes ?? []).some((a) => a.type === "JSXAttribute" && a.name?.type === "JSXIdentifier" && a.name.name === "chunk")) {
+				const live = nonWhitespaceChildren(node);
+				if (live.length === 1) {
+					const childInfo = isBareComponentChild(live[0]);
+					if (childInfo) {
+						const close = node.closingElement;
+						matches.push({
+							node,
+							child: live[0],
+							childName: childInfo.name,
+							insertChunkAt: open.end - 1,
+							childrenRange: {
+								start: open.end,
+								end: close?.start ?? node.end
+							}
+						});
+					}
+				}
+			}
+		}
+		for (const key in node) {
+			if (key === "parent") continue;
+			const v = node[key];
+			if (Array.isArray(v)) for (const item of v) walk(item);
+			else if (v && typeof v === "object" && typeof v.type === "string") walk(v);
+		}
+	};
+	walk(program);
+	return matches;
+}
+function findImportFor(program, name) {
+	const body = program.body ?? [];
+	for (const stmt of body) {
+		if (stmt.type !== "ImportDeclaration") continue;
+		const specifiers = stmt.specifiers ?? [];
+		for (const spec of specifiers) if (spec.type === "ImportDefaultSpecifier") {
+			if (spec.local.name === name) return {
+				node: stmt,
+				source: stmt.source.value,
+				kind: "default"
+			};
+		} else if (spec.type === "ImportSpecifier") {
+			const local = spec.local.name;
+			const imported = spec.imported?.name;
+			if (local === name && imported !== void 0 && imported === local) return {
+				node: stmt,
+				source: stmt.source.value,
+				kind: "named"
+			};
+		}
+	}
+	return null;
+}
+/**
+* Count references to `name` outside the given JSXElement subtree. The
+* static import can only be safely removed if the binding is used
+* EXCLUSIVELY inside that subtree.
+*/
+function countReferencesOutside(program, name, skipSubtree) {
+	let count = 0;
+	const skipStart = skipSubtree.start;
+	const skipEnd = skipSubtree.end;
+	const countInNode = (node) => {
+		if (!node || typeof node !== "object") return;
+		const ns = node.start;
+		const ne = node.end;
+		if (typeof ns === "number" && typeof ne === "number" && ns >= skipStart && ne <= skipEnd) return;
+		if (node.type === "Identifier" && node.name === name) count++;
+		if (node.type === "JSXIdentifier" && node.name === name) count++;
+		for (const key in node) {
+			if (key === "parent") continue;
+			const v = node[key];
+			if (Array.isArray(v)) for (const item of v) countInNode(item);
+			else if (v && typeof v === "object" && typeof v.type === "string") countInNode(v);
+		}
+	};
+	const body = program.body ?? [];
+	for (const stmt of body) {
+		if (stmt.type === "ImportDeclaration") continue;
+		countInNode(stmt);
+	}
+	return count;
+}
+/** Build the chunk={...} attribute string for a default or named import. */
+function buildChunkAttr(source, kind, name) {
+	if (kind === "default") return ` chunk={() => import('${source}')}`;
+	return ` chunk={() => import('${source}').then((__m) => ({ default: __m.${name} }))}`;
+}
+/**
+* Apply edits to the source string. Edits MUST be non-overlapping; we
+* sort by start descending and splice each into the source so earlier
+* positions stay valid as we work backwards.
+*/
+function applyEdits(source, edits) {
+	const sorted = [...edits].sort((a, b) => b.start - a.start);
+	let out = source;
+	for (const e of sorted) out = out.slice(0, e.start) + e.replacement + out.slice(e.end);
+	return out;
+}
+/**
+* Main entry. Returns the (possibly transformed) source plus the list
+* of warnings for cases the transform deliberately skipped.
+*
+* Bails (returns input unchanged with `changed: false`) when:
+*   - No `<Defer>` JSX element appears in the file (fast path).
+*   - The file fails to parse (syntax error — let downstream handle).
+*   - No `<Defer>` matches the inline-eligible shape.
+*
+* Per-Defer skips with a warning:
+*   - Multiple children → user must use render-prop form
+*   - Child has props → user must use render-prop form
+*   - Child name isn't imported → can't resolve the chunk source
+*   - Child binding is used outside the Defer subtree → can't remove
+*     the static import (dynamic import would be a no-op via Rolldown's
+*     same-module dedup)
+*/
+function transformDeferInline(code, filename = "input.tsx") {
+	const warnings = [];
+	if (!code.includes("Defer")) return {
+		code,
+		changed: false,
+		warnings
+	};
+	let program;
+	try {
+		program = parseSync(filename, code, {
+			sourceType: "module",
+			lang: getLang$1(filename)
+		}).program;
+	} catch {
+		return {
+			code,
+			changed: false,
+			warnings
+		};
+	}
+	const matches = findDeferMatches(program);
+	if (matches.length === 0) return {
+		code,
+		changed: false,
+		warnings
+	};
+	const edits = [];
+	let changed = false;
+	for (const m of matches) {
+		const importInfo = findImportFor(program, m.childName);
+		if (!importInfo) {
+			const loc = getLoc(code, m.child.start ?? 0);
+			warnings.push({
+				message: `<Defer>'s inline child <${m.childName} /> isn't imported — can't resolve a chunk source. Use the explicit \`chunk\` prop, or import ${m.childName} from a module.`,
+				line: loc.line,
+				column: loc.column,
+				code: "defer-inline/import-not-found"
+			});
+			continue;
+		}
+		if (countReferencesOutside(program, m.childName, m.node) > 0) {
+			const loc = getLoc(code, m.node.start ?? 0);
+			warnings.push({
+				message: `<Defer>'s inline child <${m.childName} /> is also referenced elsewhere in this file. Inline form requires the import to be used exclusively inside this Defer. Use the explicit \`chunk\` prop form to split despite shared usage.`,
+				line: loc.line,
+				column: loc.column,
+				code: "defer-inline/import-used-elsewhere"
+			});
+			continue;
+		}
+		edits.push({
+			start: m.insertChunkAt,
+			end: m.insertChunkAt,
+			replacement: buildChunkAttr(importInfo.source, importInfo.kind, m.childName)
+		});
+		edits.push({
+			start: m.childrenRange.start,
+			end: m.childrenRange.end,
+			replacement: `{(__C) => <__C />}`
+		});
+		const impStart = importInfo.node.start;
+		let impEnd = importInfo.node.end;
+		if (code[impEnd] === "\n") impEnd += 1;
+		edits.push({
+			start: impStart,
+			end: impEnd,
+			replacement: ""
+		});
+		changed = true;
+	}
+	if (!changed) return {
+		code,
+		changed: false,
+		warnings
+	};
+	return {
+		code: applyEdits(code, edits),
+		changed: true,
+		warnings
+	};
+}
+/** Resolve a byte offset into 1-based line + 0-based column. */
+function getLoc(code, offset) {
+	let line = 1;
+	let lastNl = -1;
+	for (let i = 0; i < offset && i < code.length; i++) if (code.charCodeAt(i) === 10) {
+		line++;
+		lastNl = i;
+	}
+	return {
+		line,
+		column: offset - lastNl - 1
+	};
+}
+
+//#endregion
 //#region src/event-names.ts
 /**
 * React-style → DOM event-name remap.
@@ -56,6 +362,102 @@ import ts from "typescript";
 */
 const REACT_EVENT_REMAP = Object.freeze({ doubleclick: "dblclick" });
 
+//#endregion
+//#region src/load-native.ts
+/**
+* Native binding loader — resolves the @pyreon/compiler napi-rs binary
+* via two paths in priority order:
+*
+*   1. **In-tree binary** at `<package>/native/pyreon-compiler.node`.
+*      Populated by `scripts/build-native.ts` during local development
+*      (Phase 2). Faster path because it skips npm-package resolution.
+*
+*   2. **Per-platform npm package** (Phase 5b — not active until per-
+*      platform packages are published). Resolves `@pyreon/compiler-
+*      <platform>-<arch>[-<libc>]` via the standard Node module
+*      resolution algorithm. End users on machines without a local
+*      `cargo` install will hit this path: `bun install` resolves
+*      `optionalDependencies` to the matching per-platform package and
+*      this loader picks it up.
+*
+*   3. **JS fallback** (caller's responsibility) — if both paths fail,
+*      `loadNativeBinding()` returns `null` and the caller uses the
+*      pure-JS implementation. Slower but correctness-equivalent.
+*
+* Platform detection follows the napi-rs convention. Linux variants
+* include a `libc` suffix (`gnu` for glibc, `musl` for musl) per
+* https://napi.rs/docs/cli/build#deployment.
+*
+* The two-path resolution lets dev-mode (where `cargo build` produced
+* an in-tree binary) and production-mode (where the user has only the
+* published per-platform package) coexist with no flag flipping.
+*/
+const nodeProcess = process;
+/**
+* Resolve the per-platform package name following the napi-rs naming
+* convention: `@pyreon/compiler-<platform>-<arch>[-<libc>]`.
+*
+* Examples:
+*   darwin + arm64        → @pyreon/compiler-darwin-arm64
+*   darwin + x64          → @pyreon/compiler-darwin-x64
+*   linux + x64 + gnu     → @pyreon/compiler-linux-x64-gnu
+*   linux + arm64 + gnu   → @pyreon/compiler-linux-arm64-gnu
+*   win32 + x64 + msvc    → @pyreon/compiler-win32-x64-msvc
+*
+* Returns `null` for unsupported (platform, arch) combinations — caller
+* skips per-platform resolution entirely and falls through to JS.
+*/
+function getPlatformPackageName(platform = nodeProcess.platform, arch = nodeProcess.arch, libc = detectLibc(platform)) {
+	const suffix = libc ? `-${libc}` : "";
+	if (!{
+		darwin: ["arm64", "x64"],
+		linux: ["x64", "arm64"],
+		win32: ["x64"]
+	}[platform]?.includes(arch)) return null;
+	return `@pyreon/compiler-${platform}-${arch}${suffix}`;
+}
+/**
+* Detect the libc family for the current Linux runtime. Returns:
+*   - `'gnu'` on glibc-based distros (Debian, Ubuntu, RHEL, …)
+*   - `'musl'` on musl-based distros (Alpine, …)
+*   - `null` on macOS / Windows (no libc differentiation)
+*   - `'msvc'` on Windows (we only ship MSVC binaries)
+*
+* `process.report.getReport().header.glibcVersionRuntime` is the
+* Node-canonical detection: present on glibc, absent on musl. Falls
+* back to `gnu` on read failure since glibc is the more common case.
+*/
+function detectLibc(platform) {
+	if (platform === "win32") return "msvc";
+	if (platform !== "linux") return null;
+	try {
+		const report = nodeProcess.report?.getReport();
+		if (typeof report === "object" && report !== null) return report.header?.glibcVersionRuntime ? "gnu" : "musl";
+	} catch {}
+	return "gnu";
+}
+/**
+* Load the native binding by trying paths in order:
+*   1. In-tree binary (`<package>/native/pyreon-compiler.node`)
+*   2. Per-platform npm package (`@pyreon/compiler-<triple>`)
+*
+* Returns `null` if both paths fail — caller falls back to the
+* pure-JS implementation. NEVER throws — every error path swallows
+* silently because a missing native binary is a perf optimization
+* miss, not a correctness failure.
+*/
+function loadNativeBinding(metaUrl) {
+	const nativeRequire = createRequire(metaUrl);
+	try {
+		return nativeRequire(join(dirname(fileURLToPath(metaUrl)), "..", "native", "pyreon-compiler.node"));
+	} catch {}
+	const pkgName = getPlatformPackageName();
+	if (pkgName !== null) try {
+		return nativeRequire(pkgName);
+	} catch {}
+	return null;
+}
+
 //#endregion
 //#region src/jsx.ts
 /**
@@ -87,11 +489,8 @@ const REACT_EVENT_REMAP = Object.freeze({ doubleclick: "dblclick" });
 *
 * Implementation: Rust native binary (napi-rs) when available, JS fallback via oxc-parser.
 */
-let nativeTransformJsx = null;
-try {
-	const __dirname = dirname(fileURLToPath(import.meta.url));
-	nativeTransformJsx = createRequire(import.meta.url)(join(__dirname, "..", "native", "pyreon-compiler.node")).transformJsx;
-} catch {}
+const nativeBinding = loadNativeBinding(import.meta.url);
+const nativeTransformJsx = nativeBinding ? nativeBinding.transformJsx : null;
 const SKIP_PROPS = new Set(["key", "ref"]);
 const EVENT_RE = /^on[A-Z]/;
 const DELEGATED_EVENTS = new Set([
@@ -240,6 +639,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 	let hoistIdx = 0;
 	let needsTplImport = false;
 	let needsRpImport = false;
+	let needsWrapSpreadImport = false;
 	let needsBindTextImportGlobal = false;
 	let needsBindDirectImportGlobal = false;
 	let needsBindImportGlobal = false;
@@ -299,6 +699,41 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		if (jsxTagName(node) !== "For") return;
 		if (!jsxAttrs(node).some((p) => p.type === "JSXAttribute" && p.name?.type === "JSXIdentifier" && p.name.name === "by")) warn(node.openingElement?.name ?? node, `<For> without a "by" prop will use index-based diffing, which is slower and may cause bugs with stateful children. Add by={(item) => item.id} for efficient keyed reconciliation.`, "missing-key-on-for");
 	}
+	/**
+	* Wrap component-JSX spread arguments with `_wrapSpread(...)` so
+	* getter-shaped reactive props survive esbuild's JS-level spread emit.
+	*
+	* esbuild compiles `<Comp {...source}>` to `jsx(Comp, { ...source })`.
+	* The JS spread fires every getter on `source` and stores the resolved
+	* values — collapsing compiler-emitted reactive props (`_rp` thunks
+	* later converted to getters by `makeReactiveProps`) to static values
+	* before the receiving component sees them.
+	*
+	* `_wrapSpread` replaces getter descriptors with `_rp`-branded thunks,
+	* so the JS-level spread carries function values instead. The runtime
+	* `makeReactiveProps` step converts them back to getters on the
+	* component's props object — preserving the live signal subscription.
+	*
+	* Lowercase tags (DOM elements) go through the template path's
+	* `_applyProps` which already handles spread reactively — no need to
+	* wrap there.
+	*/
+	function handleJsxSpreadAttribute(attr, parentElement) {
+		const tagName = jsxTagName(parentElement);
+		if (!(tagName.length > 0 && tagName.charAt(0) !== tagName.charAt(0).toLowerCase())) return;
+		const arg = attr.argument;
+		if (!arg) return;
+		if (arg.type === "CallExpression" && arg.callee?.type === "Identifier" && arg.callee.name === "_wrapSpread") return;
+		const start = arg.start;
+		const end = arg.end;
+		const sliced = sliceExpr(arg);
+		replacements.push({
+			start,
+			end,
+			text: `_wrapSpread(${sliced})`
+		});
+		needsWrapSpreadImport = true;
+	}
 	function handleJsxAttribute(node, parentElement) {
 		const name = node.name?.type === "JSXIdentifier" ? node.name.name : "";
 		if (SKIP_PROPS.has(name) || EVENT_RE.test(name)) return;
@@ -584,6 +1019,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			if (!isSelfClosing(node) && tryTemplateEmit(node)) return;
 			checkForWarnings(node);
 			for (const attr of jsxAttrs(node)) if (attr.type === "JSXAttribute") handleJsxAttribute(attr, node);
+			else if (attr.type === "JSXSpreadAttribute") handleJsxSpreadAttribute(attr, node);
 			for (const child of jsxChildren(node)) if (child.type === "JSXExpressionContainer") handleJsxExpression(child);
 			else walkNode(child);
 			return;
@@ -605,16 +1041,16 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		warnings
 	};
 	replacements.sort((a, b) => a.start - b.start);
-	const parts = [];
-	let lastPos = 0;
+	const outParts = [];
+	let outPos = 0;
 	for (const r of replacements) {
-		parts.push(code.slice(lastPos, r.start));
-		parts.push(r.text);
-		lastPos = r.end;
+		outParts.push(code.slice(outPos, r.start));
+		outParts.push(r.text);
+		outPos = r.end;
 	}
-	parts.push(code.slice(lastPos));
-	let result = parts.join("");
-	if (hoists.length > 0) result = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join("") + result;
+	outParts.push(code.slice(outPos));
+	let output = outParts.join("");
+	if (hoists.length > 0) output = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join("") + output;
 	if (needsTplImport) {
 		const runtimeDomImports = ["_tpl"];
 		if (needsBindDirectImportGlobal) runtimeDomImports.push("_bindDirect");
@@ -622,11 +1058,16 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		if (needsApplyPropsImportGlobal) runtimeDomImports.push("_applyProps");
 		if (needsMountSlotImportGlobal) runtimeDomImports.push("_mountSlot");
 		const reactivityImports = needsBindImportGlobal ? `\nimport { _bind } from "@pyreon/reactivity";` : "";
-		result = `import { ${runtimeDomImports.join(", ")} } from "@pyreon/runtime-dom";${reactivityImports}\n` + result;
+		output = `import { ${runtimeDomImports.join(", ")} } from "@pyreon/runtime-dom";${reactivityImports}\n` + output;
+	}
+	if (needsRpImport || needsWrapSpreadImport) {
+		const coreImports = [];
+		if (needsRpImport) coreImports.push("_rp");
+		if (needsWrapSpreadImport) coreImports.push("_wrapSpread");
+		output = `import { ${coreImports.join(", ")} } from "@pyreon/core";\n` + output;
 	}
-	if (needsRpImport) result = `import { _rp } from "@pyreon/core";\n` + result;
 	return {
-		code: result,
+		code: output,
 		usesTemplates: needsTplImport,
 		warnings
 	};
@@ -2102,6 +2543,14 @@ function diagnoseError(error) {
 *  - `as-unknown-as-vnodechild` — defensive `as unknown as VNodeChild`
 *                       cast on JSX returns is unnecessary (`JSX.Element`
 *                       is already assignable to `VNodeChild`).
+*  - `island-never-with-registry-entry` — an `island()` declared with
+*                       `hydrate: 'never'` is also registered in the same
+*                       file's `hydrateIslands({ ... })` call. The whole
+*                       point of `'never'` is shipping zero client JS;
+*                       registering pulls the component module into the
+*                       client bundle graph (the runtime short-circuits
+*                       and never calls the loader, but the bundler still
+*                       includes the import). Drop the registry entry.
 *
 * Two-mode surface mirrors `react-intercept.ts`:
 *  - `detectPyreonPatterns(code)` — diagnostics only
@@ -2372,6 +2821,69 @@ function detectAsUnknownAsVNodeChild(ctx, node) {
 	if (inner.type.kind !== ts.SyntaxKind.UnknownKeyword) return;
 	pushDiag(ctx, node, "as-unknown-as-vnodechild", "`as unknown as VNodeChild` is unnecessary — `JSX.Element` (the type produced by JSX) is already assignable to `VNodeChild`. Remove the double cast; it is pure noise that hides genuine type issues if they ever appear at this site.", getNodeText(ctx, node), getNodeText(ctx, inner.expression), false);
 }
+/**
+* Pre-pass: walk the source for `island(loader, { name: 'X', hydrate: 'never' })`
+* call expressions and collect the `name` field of each never-strategy island.
+*
+* Recognized shape (mirrors `@pyreon/vite-plugin`'s `scanIslandDeclarations`):
+*
+*   island(() => import('./X'), { name: 'X', hydrate: 'never' })
+*
+* Edge cases the AST-walker deliberately doesn't cover (unrecognized calls
+* fall through and don't populate the set — false-negatives, not false
+* positives):
+*
+*   - Loader is a variable, not an inline arrow
+*   - Name is a variable / template / spread, not a string literal
+*   - Options come from a spread (`island(loader, opts)`)
+*
+* The same rules apply on the registry side (`detectIslandNeverWithRegistry`):
+* unrecognized keys won't match. Both halves are syntactic — a semantic
+* cross-package audit lives in `pyreon doctor --check-islands` (separate PR).
+*/
+function collectNeverIslandNames(sf) {
+	const names = /* @__PURE__ */ new Set();
+	function walk(node) {
+		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "island" && node.arguments.length >= 2) {
+			const opts = node.arguments[1];
+			if (opts && ts.isObjectLiteralExpression(opts)) {
+				let nameVal;
+				let hydrateVal;
+				for (const prop of opts.properties) {
+					if (!ts.isPropertyAssignment(prop)) continue;
+					const key = prop.name;
+					const keyText = ts.isIdentifier(key) ? key.text : ts.isStringLiteral(key) ? key.text : "";
+					if (keyText === "name" && ts.isStringLiteral(prop.initializer)) nameVal = prop.initializer.text;
+					else if (keyText === "hydrate" && ts.isStringLiteral(prop.initializer)) hydrateVal = prop.initializer.text;
+				}
+				if (nameVal && hydrateVal === "never") names.add(nameVal);
+			}
+		}
+		ts.forEachChild(node, walk);
+	}
+	walk(sf);
+	return names;
+}
+/**
+* Flag entries in `hydrateIslands({ X: () => import('./X'), ... })` whose
+* key matches an `island()` name declared with `hydrate: 'never'` in the
+* same file. Each matching entry produces one diagnostic at the property's
+* location so the IDE highlights exactly which key needs to go.
+*/
+function detectIslandNeverWithRegistry(ctx, node) {
+	if (ctx.neverIslandNames.size === 0) return;
+	const callee = node.expression;
+	if (!ts.isIdentifier(callee) || callee.text !== "hydrateIslands") return;
+	const arg = node.arguments[0];
+	if (!arg || !ts.isObjectLiteralExpression(arg)) return;
+	for (const prop of arg.properties) {
+		if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) continue;
+		const key = prop.name;
+		const keyText = ts.isIdentifier(key) ? key.text : ts.isStringLiteral(key) ? key.text : "";
+		if (!keyText || !ctx.neverIslandNames.has(keyText)) continue;
+		pushDiag(ctx, prop, "island-never-with-registry-entry", `island "${keyText}" was declared with \`hydrate: 'never'\` and MUST NOT be registered in \`hydrateIslands({ ... })\`. The whole point of the \`'never'\` strategy is shipping zero client JS — registering pulls the component module into the client bundle graph (the runtime short-circuits never-strategy before the registry lookup, but the bundler still includes the import). Drop this entry; the framework handles never-strategy islands at SSR with no client-side wiring.`, getNodeText(ctx, prop), `// remove the "${keyText}" entry — never-strategy islands need no registry entry`, false);
+	}
+}
 function visitNode(ctx, node) {
 	if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) detectForKeying(ctx, node);
 	if (ts.isArrowFunction(node) || ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
@@ -2387,6 +2899,7 @@ function visitNode(ctx, node) {
 		detectEmptyTheme(ctx, node);
 		detectRawEventListener(ctx, node);
 		detectSignalWriteAsCall(ctx, node);
+		detectIslandNeverWithRegistry(ctx, node);
 	}
 	if (ts.isJsxAttribute(node)) detectOnClickUndefined(ctx, node);
 	if (ts.isAsExpression(node)) detectAsUnknownAsVNodeChild(ctx, node);
@@ -2403,7 +2916,8 @@ function detectPyreonPatterns(code, filename = "input.tsx") {
 		sf,
 		code,
 		diagnostics: [],
-		signalBindings: collectSignalBindings(sf)
+		signalBindings: collectSignalBindings(sf),
+		neverIslandNames: collectNeverIslandNames(sf)
 	};
 	visit(ctx, sf);
 	ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
@@ -2411,7 +2925,7 @@ function detectPyreonPatterns(code, filename = "input.tsx") {
 }
 /** Fast regex pre-filter — returns true if the code is worth a full AST walk. */
 function hasPyreonPatterns(code) {
-	return /\bFor\b[^=]*\beach\s*=/.test(code) || /\btypeof\s+process\b/.test(code) || /\.theme\s*\(\s*\{\s*\}\s*\)/.test(code) || /\b(?:add|remove)EventListener\s*\(/.test(code) || /\bDate\.now\s*\(/.test(code) && /\bMath\.random\s*\(/.test(code) || /on[A-Z]\w*\s*=\s*\{\s*undefined\s*\}/.test(code) || /=\s*\(\s*\{[^}]+\}\s*[:)]/.test(code) || /\b(?:signal|computed)\s*[<(]/.test(code) || /\bif\s*\([^)]+\)\s*\{?\s*return\s+null\b/.test(code) || /\bas\s+unknown\s+as\s+VNodeChild\b/.test(code);
+	return /\bFor\b[^=]*\beach\s*=/.test(code) || /\btypeof\s+process\b/.test(code) || /\.theme\s*\(\s*\{\s*\}\s*\)/.test(code) || /\b(?:add|remove)EventListener\s*\(/.test(code) || /\bDate\.now\s*\(/.test(code) && /\bMath\.random\s*\(/.test(code) || /on[A-Z]\w*\s*=\s*\{\s*undefined\s*\}/.test(code) || /=\s*\(\s*\{[^}]+\}\s*[:)]/.test(code) || /\b(?:signal|computed)\s*[<(]/.test(code) || /\bif\s*\([^)]+\)\s*\{?\s*return\s+null\b/.test(code) || /\bas\s+unknown\s+as\s+VNodeChild\b/.test(code) || /\bisland\s*\(/.test(code) && /\bhydrate\s*:\s*['"]never['"]/.test(code);
 }
 
 //#endregion
@@ -2445,7 +2959,7 @@ function hasPyreonPatterns(code) {
 * tell an agent what to write; this one tells an agent which existing
 * tests need strengthening.
 */
-function findMonorepoRoot(startDir) {
+function findMonorepoRoot$2(startDir) {
 	let dir = resolve(startDir);
 	for (let i = 0; i < 30; i++) {
 		try {
@@ -2611,7 +3125,7 @@ function classifyRisk(entry) {
 	return "medium";
 }
 function auditTestEnvironment(startDir) {
-	const root = findMonorepoRoot(startDir);
+	const root = findMonorepoRoot$2(startDir);
 	if (!root) return {
 		root: null,
 		entries: [],
@@ -2726,5 +3240,784 @@ function describeRisk(risk) {
 }
 
 //#endregion
-export { auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformJSX, transformJSX_JS };
+//#region src/island-audit.ts
+/**
+* Project-wide islands audit for the `audit_islands` MCP tool +
+* `pyreon doctor --check-islands` CLI flag (PR C of the islands DX
+* roadmap).
+*
+* Companion gates that pre-date this module:
+*
+*   - PR G's `island-never-with-registry-entry` detector (in
+*     `pyreon-intercept.ts`) catches the same shape per FILE — it only
+*     fires when the `island()` declaration AND `hydrateIslands({...})`
+*     call are in the same source.
+*   - PR B's auto-registry (`@pyreon/vite-plugin` `islands: true`)
+*     eliminates the manual sync entirely — the registry is generated
+*     from `island()` declarations, so it can't drift.
+*
+* What this audit adds: cross-file analysis. Five findings:
+*
+*   1. `never-with-registry-entry` — project-wide cross-file version of
+*      the per-file detector. Fires when ANY file's `island()` with
+*      `hydrate: 'never'` matches a key in ANY file's `hydrateIslands`
+*      call.
+*   2. `duplicate-name` — two `island()` declarations with the same
+*      `name`. Runtime would only hydrate the first; the second fails
+*      silently.
+*   3. `registry-mismatch` — a `hydrateIslands({ X })` entry with no
+*      matching `island()` declaration anywhere in the project. Catches
+*      the manual-form drift foot-gun (typo / removed island /
+*      forgotten import).
+*   4. `nested-island` — an `island()` whose loader-imported file ALSO
+*      contains an `island()` call. Statically reachable nesting; the
+*      outer's `hydrateRoot` would replace the inner before its loader
+*      runs.
+*   5. `dead-island` — an `island()` declared in a file that no other
+*      file imports (statically OR dynamically). Heuristic catches the
+*      common shape of "declared but never wired up." False negatives
+*      possible (file imported but the island binding within it isn't
+*      used) — that's the cost of staying syntactic + cheap.
+*
+* Architectural note. This is intentionally syntactic, not semantic.
+* The audit reads source files as text + AST and never resolves through
+* type-checking. False negatives are acceptable; false positives must
+* be rare. Every finding includes file paths + line/column + actionable
+* fix suggestion so the user can verify in seconds.
+*/
+function findMonorepoRoot$1(startDir) {
+	let dir = resolve(startDir);
+	for (let i = 0; i < 30; i++) {
+		try {
+			if (statSync(join(dir, "packages")).isDirectory()) return dir;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+function walkSourceFiles(dir, out, depth = 0) {
+	if (depth > 12) return;
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name.startsWith(".")) continue;
+		if (name === "node_modules" || name === "lib" || name === "dist") continue;
+		if (name === "__tests__" || name === "tests") continue;
+		const full = join(dir, name);
+		let isDir = false;
+		try {
+			isDir = statSync(full).isDirectory();
+		} catch {
+			continue;
+		}
+		if (isDir) {
+			walkSourceFiles(full, out, depth + 1);
+			continue;
+		}
+		if (/\.(tsx?|jsx?)$/.test(name) && !/\.(test|spec)\.(tsx?|jsx?)$/.test(name)) out.push(full);
+	}
+}
+function lineColAt(sf, pos) {
+	const lc = sf.getLineAndCharacterOfPosition(pos);
+	return {
+		line: lc.line + 1,
+		column: lc.character + 1
+	};
+}
+/** Strip surrounding quotes from a string literal as parsed by TS. */
+function stringLiteralValue(node) {
+	if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+}
+/**
+* Extract `island()` declarations recognized in the file. Mirrors the
+* shape recognized by `@pyreon/vite-plugin`'s `scanIslandDeclarations`
+* and PR G's `collectNeverIslandNames` — only inline-arrow loaders +
+* string-literal options are captured. Other shapes fall through (false
+* negatives, by design).
+*/
+function extractIslandDecls(sf, absPath, root) {
+	const decls = [];
+	const fileDir = dirname(absPath);
+	const relPath = relative(root, absPath);
+	function visit(node) {
+		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "island" && node.arguments.length >= 2) {
+			const loaderArg = node.arguments[0];
+			const optsArg = node.arguments[1];
+			let importPath;
+			if (loaderArg && ts.isArrowFunction(loaderArg)) {
+				const body = loaderArg.body;
+				const callTarget = ts.isCallExpression(body) ? body : void 0;
+				if (callTarget && callTarget.expression.kind === ts.SyntaxKind.ImportKeyword) {
+					const arg0 = callTarget.arguments[0];
+					if (arg0) importPath = stringLiteralValue(arg0);
+				}
+			}
+			if (optsArg && ts.isObjectLiteralExpression(optsArg)) {
+				let nameVal;
+				let hydrateVal;
+				for (const prop of optsArg.properties) {
+					if (!ts.isPropertyAssignment(prop)) continue;
+					const keyText = ts.isIdentifier(prop.name) ? prop.name.text : ts.isStringLiteral(prop.name) ? prop.name.text : "";
+					if (keyText === "name") nameVal = stringLiteralValue(prop.initializer);
+					else if (keyText === "hydrate") {
+						const v = stringLiteralValue(prop.initializer);
+						hydrateVal = v?.startsWith("interaction") ? "interaction" : v;
+					}
+				}
+				if (nameVal) {
+					const lc = lineColAt(sf, node.getStart(sf));
+					decls.push({
+						name: nameVal,
+						hydrate: hydrateVal ?? "load",
+						importPath,
+						loc: {
+							path: absPath,
+							relPath,
+							line: lc.line,
+							column: lc.column
+						},
+						fileDir
+					});
+				}
+			}
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(sf);
+	return decls;
+}
+/**
+* Extract `hydrateIslands({...})` registry entries. Recognizes both
+* shorthand (`{ Counter }`) and property-assignment (`{ Counter: () =>
+* import('./Counter') }`) forms.
+*/
+function extractRegistryEntries(sf, absPath, root) {
+	const entries = [];
+	const relPath = relative(root, absPath);
+	function visit(node) {
+		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "hydrateIslands" && node.arguments.length >= 1) {
+			const arg = node.arguments[0];
+			if (arg && ts.isObjectLiteralExpression(arg)) for (const prop of arg.properties) {
+				if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) continue;
+				const keyNode = prop.name;
+				const key = ts.isIdentifier(keyNode) ? keyNode.text : ts.isStringLiteral(keyNode) ? keyNode.text : "";
+				if (!key) continue;
+				const lc = lineColAt(sf, prop.getStart(sf));
+				entries.push({
+					key,
+					loc: {
+						path: absPath,
+						relPath,
+						line: lc.line,
+						column: lc.column
+					}
+				});
+			}
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(sf);
+	return entries;
+}
+/**
+* Extract every import target (static `import` declarations + dynamic
+* `import()` expressions) and resolve relative paths to absolute paths
+* for the imports map. Bare specifiers (`@pyreon/server`) are kept as-is
+* — we only use this for the dead-island heuristic, which compares
+* against absolute file paths of declared islands, so bare specs simply
+* never match.
+*/
+function extractImports(sf, absPath) {
+	const out = /* @__PURE__ */ new Set();
+	const fileDir = dirname(absPath);
+	function record(spec) {
+		if (spec.startsWith(".")) out.add(resolve(fileDir, spec));
+		else out.add(spec);
+	}
+	function visit(node) {
+		if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) record(node.moduleSpecifier.text);
+		else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+			const arg0 = node.arguments[0];
+			const v = arg0 ? stringLiteralValue(arg0) : void 0;
+			if (v) record(v);
+		} else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) record(node.moduleSpecifier.text);
+		ts.forEachChild(node, visit);
+	}
+	visit(sf);
+	return out;
+}
+function extractFromFile(absPath, root) {
+	let code = "";
+	try {
+		code = readFileSync(absPath, "utf8");
+	} catch {
+		return {
+			islands: [],
+			registryEntries: [],
+			imports: /* @__PURE__ */ new Set()
+		};
+	}
+	const sf = ts.createSourceFile(absPath, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
+	return {
+		islands: extractIslandDecls(sf, absPath, root),
+		registryEntries: extractRegistryEntries(sf, absPath, root),
+		imports: extractImports(sf, absPath)
+	};
+}
+const TS_EXTS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+/**
+* Try common extensions + index files to land an absolute path on a
+* concrete file. Used by both helpers below.
+*/
+function resolveAbsToFile(absBase) {
+	try {
+		if (statSync(absBase).isFile()) return absBase;
+	} catch {}
+	for (const ext of TS_EXTS) try {
+		const candidate = `${absBase}${ext}`;
+		if (statSync(candidate).isFile()) return candidate;
+	} catch {}
+	for (const ext of TS_EXTS) try {
+		const candidate = join(absBase, `index${ext}`);
+		if (statSync(candidate).isFile()) return candidate;
+	} catch {}
+	return null;
+}
+/**
+* Resolve `import './Counter'` (or similar) to an absolute file path.
+* Used by `nested-island` to follow an island's loader to its target.
+*/
+function resolveImport(fromDir, spec) {
+	if (!spec.startsWith(".")) return null;
+	return resolveAbsToFile(resolve(fromDir, spec));
+}
+function detectDuplicateName(declsByFile, findings) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const decls of declsByFile.values()) for (const d of decls) {
+		const list = byName.get(d.name) ?? [];
+		list.push(d);
+		byName.set(d.name, list);
+	}
+	for (const [name, list] of byName) {
+		if (list.length < 2) continue;
+		for (let i = 0; i < list.length; i++) {
+			const self = list[i];
+			if (!self) continue;
+			const others = list.filter((_, j) => j !== i).map((d) => d.loc);
+			findings.push({
+				code: "duplicate-name",
+				message: `Two or more \`island()\` declarations share the name "${name}". The client-side hydration registry is keyed by name; only the FIRST loader fires — every other declaration fails silently with no error flag, and the user sees broken interactivity on the second component without any signal pointing at the cause. Rename one to make the names unique.`,
+				location: self.loc,
+				related: others
+			});
+		}
+	}
+}
+function detectNeverWithRegistry(decls, registry, findings) {
+	const neverByName = /* @__PURE__ */ new Map();
+	for (const d of decls) if (d.hydrate === "never") neverByName.set(d.name, d);
+	for (const entry of registry) {
+		const decl = neverByName.get(entry.key);
+		if (!decl) continue;
+		findings.push({
+			code: "never-with-registry-entry",
+			message: `island "${entry.key}" was declared with \`hydrate: 'never'\` (at ${decl.loc.relPath}:${decl.loc.line}) but is registered in \`hydrateIslands({...})\`. The whole point of the \`'never'\` strategy is shipping zero client JS — registering pulls the component module into the client bundle graph (the runtime short-circuits never-strategy before the registry lookup, so the loader never fires, but the bundler still includes the import). Drop this entry; the framework handles never-strategy islands at SSR with no client-side wiring. Auto-registry under \`@pyreon/vite-plugin\` (\`pyreon({ islands: true })\`) automatically omits never-strategy islands — switch to \`hydrateIslandsAuto(registry)\` to eliminate the manual sync entirely.`,
+			location: entry.loc,
+			related: [decl.loc]
+		});
+	}
+}
+function detectRegistryMismatch(decls, registry, findings) {
+	const declaredNames = new Set(decls.map((d) => d.name));
+	for (const entry of registry) {
+		if (declaredNames.has(entry.key)) continue;
+		findings.push({
+			code: "registry-mismatch",
+			message: `\`hydrateIslands({ ${entry.key}: ... })\` references "${entry.key}" but no \`island()\` in the project declares this name. Common causes: (1) typo (the registry key must EXACTLY match the \`name\` field on the \`island()\` declaration, including case), (2) the \`island()\` was renamed or deleted but the registry entry wasn't updated, (3) the file declaring the island isn't part of the scanned source tree (audit walks \`packages/\` and \`examples/\` by default). Switch to \`hydrateIslandsAuto(registry)\` from \`@pyreon/server/client\` (with \`@pyreon/vite-plugin\` \`islands: true\`) to eliminate manual-sync drift.`,
+			location: entry.loc
+		});
+	}
+}
+function detectNestedIsland(decls, declsByFile, findings) {
+	for (const outer of decls) {
+		if (!outer.importPath) continue;
+		const resolved = resolveImport(outer.fileDir, outer.importPath);
+		if (!resolved) continue;
+		const innerDecls = declsByFile.get(resolved);
+		if (!innerDecls || innerDecls.length === 0) continue;
+		for (const inner of innerDecls) findings.push({
+			code: "nested-island",
+			message: `island "${outer.name}" loads a file that ALSO contains an \`island()\` declaration ("${inner.name}" at ${inner.loc.relPath}:${inner.loc.line}). Nested islands are unsupported — the outer's \`hydrateRoot\` would replace the inner subtree before its loader runs, so the inner never hydrates. Refactor to flatten (move the inner island's content into the outer, OR remove the inner \`island()\` wrapper and let the outer render the component directly).`,
+			location: outer.loc,
+			related: [inner.loc]
+		});
+	}
+}
+function detectDeadIslands(decls, importedFiles, findings) {
+	for (const d of decls) {
+		if (importedFiles.has(d.loc.path)) continue;
+		findings.push({
+			code: "dead-island",
+			message: `island "${d.name}" is declared in ${d.loc.relPath} but no other file in the project imports from this module (statically OR dynamically). The island's component will never reach a rendered tree — it's effectively unreachable code. Either (1) wire it up by importing + rendering the component from a route, or (2) remove the \`island()\` declaration. Note: the audit's heuristic flags files that no other source imports; if your island is registered via \`hydrateIslandsAuto()\`, the auto-registry's \`() => import('PATH')\` loader DOES count as an import, so a flagged island is genuinely orphaned.`,
+			location: d.loc
+		});
+	}
+}
+function auditIslands(rootDir) {
+	const root = findMonorepoRoot$1(rootDir);
+	const findings = [];
+	const summary = {
+		filesScanned: 0,
+		islandsDeclared: 0,
+		registryEntries: 0,
+		findingsByCode: {
+			"never-with-registry-entry": 0,
+			"duplicate-name": 0,
+			"registry-mismatch": 0,
+			"nested-island": 0,
+			"dead-island": 0
+		}
+	};
+	if (!root) return {
+		root: null,
+		findings,
+		summary
+	};
+	const files = [];
+	walkSourceFiles(join(root, "packages"), files);
+	walkSourceFiles(join(root, "examples"), files);
+	summary.filesScanned = files.length;
+	const declsByFile = /* @__PURE__ */ new Map();
+	const allDecls = [];
+	const allRegistry = [];
+	const resolvedImports = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		const ex = extractFromFile(file, root);
+		if (ex.islands.length > 0) {
+			declsByFile.set(file, ex.islands);
+			allDecls.push(...ex.islands);
+		}
+		allRegistry.push(...ex.registryEntries);
+		for (const spec of ex.imports) {
+			if (!spec.startsWith("/")) continue;
+			const resolved = resolveAbsToFile(spec);
+			if (resolved) resolvedImports.add(resolved);
+		}
+	}
+	summary.islandsDeclared = allDecls.length;
+	summary.registryEntries = allRegistry.length;
+	detectDuplicateName(declsByFile, findings);
+	detectNeverWithRegistry(allDecls, allRegistry, findings);
+	detectRegistryMismatch(allDecls, allRegistry, findings);
+	detectNestedIsland(allDecls, declsByFile, findings);
+	detectDeadIslands(allDecls, resolvedImports, findings);
+	for (const f of findings) summary.findingsByCode[f.code] = (summary.findingsByCode[f.code] ?? 0) + 1;
+	findings.sort((a, b) => {
+		const pathCmp = a.location.relPath.localeCompare(b.location.relPath);
+		if (pathCmp !== 0) return pathCmp;
+		return a.location.line - b.location.line || a.location.column - b.location.column;
+	});
+	return {
+		root,
+		findings,
+		summary
+	};
+}
+const CODE_HEADERS = {
+	"never-with-registry-entry": "Never-strategy island in client registry — defeats zero-JS strategy",
+	"duplicate-name": "Duplicate island names — only the first hydrates",
+	"registry-mismatch": "Registry references unknown island — runtime warns + skips",
+	"nested-island": "Nested island — outer hydrateRoot replaces inner before its loader runs",
+	"dead-island": "Declared but unused island — no other file imports its module"
+};
+function formatIslandAudit(result, options = {}) {
+	if (options.json) return JSON.stringify(result, null, 2);
+	if (!result.root) return "No monorepo root found. The islands audit walks `packages/` and `examples/` starting from the cwd. Run `pyreon doctor --check-islands` from the Pyreon repo root.";
+	const parts = [];
+	parts.push(`# Islands audit — ${result.summary.filesScanned} files scanned, ${result.summary.islandsDeclared} \`island()\` declaration${result.summary.islandsDeclared === 1 ? "" : "s"}, ${result.summary.registryEntries} \`hydrateIslands\` registry entr${result.summary.registryEntries === 1 ? "y" : "ies"}`);
+	parts.push("");
+	if (result.findings.length === 0) {
+		parts.push("✓ No island findings. Project-wide cross-file checks are clean:");
+		parts.push("  - No duplicate names");
+		parts.push("  - No `hydrate: \"never\"` islands in any client registry");
+		parts.push("  - No registry entries pointing at undeclared names");
+		parts.push("  - No nested islands");
+		parts.push("  - No declared-but-unimported islands");
+		return parts.join("\n");
+	}
+	parts.push(`Findings: ${result.findings.length} (` + Object.entries(result.summary.findingsByCode).filter(([, n]) => n > 0).map(([code, n]) => `${code}: ${n}`).join(", ") + ")");
+	parts.push("");
+	const byCode = /* @__PURE__ */ new Map();
+	for (const f of result.findings) {
+		const list = byCode.get(f.code) ?? [];
+		list.push(f);
+		byCode.set(f.code, list);
+	}
+	for (const [code, list] of byCode) {
+		parts.push(`## ${code} — ${list.length} finding${list.length === 1 ? "" : "s"}`);
+		parts.push("");
+		parts.push(`> ${CODE_HEADERS[code]}`);
+		parts.push("");
+		for (const f of list) {
+			parts.push(`  ${f.location.relPath}:${f.location.line}:${f.location.column}`);
+			parts.push(`    ${f.message}`);
+			if (f.related && f.related.length > 0) for (const r of f.related) parts.push(`    related: ${r.relPath}:${r.line}:${r.column}`);
+			parts.push("");
+		}
+	}
+	return parts.join("\n");
+}
+
+//#endregion
+//#region src/ssg-audit.ts
+/**
+* Project-wide SSG audit — scans route files for SSG / ISR foot-guns
+* surfaced by the SSG roadmap PRs (L5, A, I). Three detector codes ship
+* today:
+*
+*  - **`404-outside-layout-dir`** (PR L5 carve-out): a `_404.tsx` (or
+*    `_not-found.tsx`) file NOT co-located with a `_layout.tsx`. PR L5's
+*    `findNotFoundFallback` filters to layout records with `children`;
+*    a standalone `_404.tsx` outside a layout directory renders via the
+*    SSG entry's pre-L5 standalone path (no layout chrome). The audit
+*    catches this at the filesystem level so users move their
+*    `_404.tsx` into the canonical `_layout` directory.
+*
+*  - **`dynamic-route-missing-get-static-paths`** (PR A consequence): a
+*    dynamic route file (`[id].tsx`, `[...slug].tsx`) that lacks a
+*    `getStaticPaths` export. The SSG plugin silently SKIPS the route
+*    during auto-detect — the user thinks `/posts/1` etc. are
+*    prerendered but the dist has no `dist/posts/<id>/index.html`. The
+*    audit catches this at scan time so users add the enumerator OR
+*    declare the route as runtime-only.
+*
+*  - **`non-literal-revalidate-export`** (PR I limitation): a route
+*    file exports `export const revalidate = TTL` (variable reference)
+*    or `export const revalidate = ...` (expression). The literal-
+*    capture path in `extractLiteralExport` skips non-literals — the
+*    manifest's revalidate entry is omitted, platform-driven ISR is
+*    silently unconfigured for that route. The audit catches this so
+*    users inline the literal (`export const revalidate = 60`).
+*
+* Real-app coverage:
+*   - Per-code synthetic-fixture tests in `tests/ssg-audit.test.ts`
+*     (one fixture per finding type, bisect-verified by reverting the
+*     detector's match condition)
+*   - Doctor wiring at `packages/tools/cli/src/doctor.ts:checkSsg`,
+*     CLI flag `pyreon doctor --check-ssg [--json]`
+*
+* Same syntactic-only style as `island-audit.ts` — no type-check pass,
+* no module resolution. False negatives acceptable; false positives
+* must be rare. Every finding ships with file path + line/column +
+* actionable fix suggestion.
+*/
+function findMonorepoRoot(startDir) {
+	let dir = resolve(startDir);
+	for (let i = 0; i < 30; i++) {
+		try {
+			if (statSync(join(dir, "packages")).isDirectory()) return dir;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Walk a directory looking for files under any `routes/` subdirectory.
+* fs-router treats files under `src/routes/` as routes; we mirror the
+* convention. Skips node_modules / lib / dist / test directories.
+*/
+function findRouteFiles(rootDir, out, depth = 0) {
+	if (depth > 12) return;
+	let entries;
+	try {
+		entries = readdirSync(rootDir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name.startsWith(".")) continue;
+		if (name === "node_modules" || name === "lib" || name === "dist") continue;
+		if (name === "__tests__" || name === "tests") continue;
+		const full = join(rootDir, name);
+		let isDir = false;
+		try {
+			isDir = statSync(full).isDirectory();
+		} catch {
+			continue;
+		}
+		if (isDir) {
+			if (name === "routes") walkRoutesDir(full, out);
+			else findRouteFiles(full, out, depth + 1);
+			continue;
+		}
+	}
+}
+function walkRoutesDir(dir, out) {
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name.startsWith(".")) continue;
+		if (name === "node_modules") continue;
+		const full = join(dir, name);
+		let stat;
+		try {
+			stat = statSync(full);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) {
+			walkRoutesDir(full, out);
+			continue;
+		}
+		if (/\.(tsx?|jsx?)$/.test(name) && !/\.(test|spec)\.(tsx?|jsx?)$/.test(name)) out.push(full);
+	}
+}
+function parseSourceFile(filePath) {
+	let source;
+	try {
+		source = readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+	return ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+}
+function locOf(source, node) {
+	const pos = source.getLineAndCharacterOfPosition(node.getStart(source));
+	return {
+		line: pos.line + 1,
+		column: pos.character + 1
+	};
+}
+function makeLocation(absPath, source, node, rootForRel) {
+	const { line, column } = locOf(source, node);
+	return {
+		path: absPath,
+		relPath: relative(rootForRel, absPath),
+		line,
+		column
+	};
+}
+/**
+* 1) `_404.tsx` / `_not-found.tsx` outside a `_layout.tsx` directory.
+*
+* fs-router scans `_404.tsx` / `_not-found.tsx` and attaches the default
+* export as `notFoundComponent` on its parent layout's RouteRecord. PR L5's
+* `findNotFoundFallback` filters to records with `Array.isArray(r.children)
+* && r.children.length > 0` — i.e. layouts only. A standalone `_404.tsx`
+* outside a layout directory:
+*   - Becomes attached to a page record (no children)
+*   - PR L5's walker skips it
+*   - SSG entry falls back to the pre-L5 standalone render (no chrome)
+*
+* The audit catches this at filesystem-walk time, fast and structural.
+*/
+function detect404OutsideLayoutDir(routeFiles, rootForRel) {
+	const findings = [];
+	const layoutDirs = /* @__PURE__ */ new Set();
+	for (const file of routeFiles) {
+		const base = file.split("/").pop() ?? "";
+		if (/^_layout\.(tsx?|jsx?)$/.test(base)) layoutDirs.add(dirname(file));
+	}
+	for (const file of routeFiles) {
+		const base = file.split("/").pop() ?? "";
+		if (!/^_(404|not-found)\.(tsx?|jsx?)$/.test(base)) continue;
+		const dir = dirname(file);
+		if (layoutDirs.has(dir)) continue;
+		findings.push({
+			code: "404-outside-layout-dir",
+			message: `${base} is not co-located with a _layout.tsx — without a parent layout, PR L5's findNotFoundFallback won't pick it up at SSG time and the 404 will render WITHOUT layout chrome (nav, footer, providers). Move ${base} into a directory that contains _layout.tsx (the canonical pattern: src/routes/_layout.tsx + src/routes/_404.tsx).`,
+			location: {
+				path: file,
+				relPath: relative(rootForRel, file),
+				line: 1,
+				column: 1
+			}
+		});
+	}
+	return findings;
+}
+/**
+* 2) Dynamic route file missing `getStaticPaths` export.
+*
+* `[id].tsx`, `[...slug].tsx` — under SSG mode without a `getStaticPaths`,
+* the auto-detect step silently skips the route. User expects
+* `dist/posts/1/index.html` but never gets it.
+*
+* We syntactically scan for `export const getStaticPaths` or
+* `export function getStaticPaths`. Re-exports / async-function form
+* supported. Same literal-extraction shape used in fs-router's scanner.
+*/
+function detectDynamicRouteMissingGetStaticPaths(routeFiles, rootForRel) {
+	const findings = [];
+	for (const file of routeFiles) {
+		const base = file.split("/").pop() ?? "";
+		if (!/\[.+\]/.test(base)) continue;
+		if (/^_(layout|error|loading|404|not-found)\./.test(base)) continue;
+		if (/[/\\]routes[/\\]api[/\\]/.test(file)) continue;
+		const source = parseSourceFile(file);
+		if (!source) continue;
+		let hasGetStaticPaths = false;
+		let hasDefaultExport = false;
+		function visit(node) {
+			if (hasGetStaticPaths && hasDefaultExport) return;
+			if (ts.isVariableStatement(node)) {
+				if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+					for (const decl of node.declarationList.declarations) if (ts.isIdentifier(decl.name) && decl.name.text === "getStaticPaths") hasGetStaticPaths = true;
+				}
+			}
+			if (ts.isFunctionDeclaration(node)) {
+				const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+				const isDefault = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+				if (hasExport && node.name?.text === "getStaticPaths") hasGetStaticPaths = true;
+				if (hasExport && isDefault) hasDefaultExport = true;
+			}
+			if (ts.isExportAssignment(node) && !node.isExportEquals) hasDefaultExport = true;
+			ts.forEachChild(node, visit);
+		}
+		visit(source);
+		if (!hasDefaultExport) continue;
+		if (!hasGetStaticPaths) findings.push({
+			code: "dynamic-route-missing-get-static-paths",
+			message: `Dynamic route "${base}" has no \`getStaticPaths\` export — under \`mode: 'ssg'\` the auto-detect step SILENTLY SKIPS this route, so the dist won't contain prerendered HTML. Either add \`export const getStaticPaths = () => [{ params: { ... } }, ...]\` enumerating the concrete values, OR declare the route as runtime-only by switching to mode: 'ssr' / 'isr'.`,
+			location: {
+				path: file,
+				relPath: relative(rootForRel, file),
+				line: 1,
+				column: 1
+			}
+		});
+	}
+	return findings;
+}
+/**
+* 3) `export const revalidate = X` where X is NOT a pure literal.
+*
+* PR I's `extractLiteralExport` skips re-export forms (`const x = 60;
+* export { x as revalidate }`) and non-literal expressions
+* (`export const revalidate = TTL` where TTL is a const elsewhere). The
+* manifest emission skips the entry silently — user thinks ISR is wired
+* but `_pyreon-revalidate.json` is missing the path. The audit catches
+* the syntactic shape and warns.
+*
+* Valid literals: NumericLiteral (`60`), FalseKeyword (`false`).
+* Anything else — Identifier reference, BinaryExpression, CallExpression,
+* TemplateLiteral — flagged.
+*/
+function detectNonLiteralRevalidateExport(routeFiles, rootForRel) {
+	const findings = [];
+	for (const file of routeFiles) {
+		const parsed = parseSourceFile(file);
+		if (!parsed) continue;
+		const source = parsed;
+		function visit(node) {
+			if (ts.isVariableStatement(node)) {
+				if (!node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+					ts.forEachChild(node, visit);
+					return;
+				}
+				for (const decl of node.declarationList.declarations) {
+					if (!ts.isIdentifier(decl.name) || decl.name.text !== "revalidate") continue;
+					const init = decl.initializer;
+					if (!init) continue;
+					if (ts.isNumericLiteral(init)) continue;
+					if (init.kind === ts.SyntaxKind.FalseKeyword) continue;
+					findings.push({
+						code: "non-literal-revalidate-export",
+						message: "`export const revalidate` must be a NUMERIC LITERAL (e.g. `60`, `3600`) or `false` — non-literal expressions (variable references, math, function calls, template literals) are silently dropped from the build-time ISR manifest (PR I's extractLiteralExport limitation). Inline the value: `export const revalidate = 60`.",
+						location: makeLocation(file, source, init, rootForRel)
+					});
+				}
+			}
+			ts.forEachChild(node, visit);
+		}
+		visit(source);
+	}
+	return findings;
+}
+function auditSsg(rootDir) {
+	const root = findMonorepoRoot(rootDir) ?? rootDir;
+	const routeFiles = [];
+	findRouteFiles(rootDir, routeFiles);
+	let dynamicRoutes = 0;
+	let revalidateExports = 0;
+	for (const file of routeFiles) {
+		const base = file.split("/").pop() ?? "";
+		if (/\[.+\]/.test(base) && !/^_(layout|error|loading|404|not-found)\./.test(base)) dynamicRoutes++;
+		const source = parseSourceFile(file);
+		if (!source) continue;
+		function visit(node) {
+			if (ts.isVariableStatement(node)) {
+				if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+					for (const decl of node.declarationList.declarations) if (ts.isIdentifier(decl.name) && decl.name.text === "revalidate") revalidateExports++;
+				}
+			}
+			ts.forEachChild(node, visit);
+		}
+		visit(source);
+	}
+	const findings = [
+		...detect404OutsideLayoutDir(routeFiles, root),
+		...detectDynamicRouteMissingGetStaticPaths(routeFiles, root),
+		...detectNonLiteralRevalidateExport(routeFiles, root)
+	];
+	const findingsByCode = {
+		"404-outside-layout-dir": 0,
+		"dynamic-route-missing-get-static-paths": 0,
+		"non-literal-revalidate-export": 0
+	};
+	for (const f of findings) findingsByCode[f.code]++;
+	return {
+		root,
+		findings,
+		summary: {
+			filesScanned: routeFiles.length,
+			routesScanned: routeFiles.length,
+			dynamicRoutes,
+			revalidateExports,
+			findingsByCode
+		}
+	};
+}
+function formatSsgAudit(result, _options = {}) {
+	const lines = [];
+	lines.push("── SSG audit ─────────────────────────────────────────────────────");
+	lines.push("");
+	lines.push(`Scanned ${result.summary.routesScanned} route file(s), ${result.summary.dynamicRoutes} dynamic route(s), ${result.summary.revalidateExports} revalidate export(s).`);
+	lines.push("");
+	if (result.findings.length === 0) {
+		lines.push("✓ No SSG / ISR issues found.");
+		lines.push("");
+		return lines.join("\n");
+	}
+	lines.push(`Found ${result.findings.length} issue(s):`);
+	for (const f of result.findings) {
+		lines.push("");
+		lines.push(`  [${f.code}] ${f.location.relPath}:${f.location.line}:${f.location.column}`);
+		lines.push(`    ${f.message}`);
+	}
+	lines.push("");
+	lines.push("Run `pyreon doctor --check-ssg --json` for machine-readable output.");
+	lines.push("");
+	return lines.join("\n");
+}
+
+//#endregion
+export { auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformDeferInline, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index.js.map