@pyreon/compiler 0.14.0 → 0.16.0

package/lib/index.js

@@ -7,6 +7,152 @@ import * as fs from "node:fs";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import ts from "typescript";
 
+//#region src/event-names.ts
+/**
+* React-style → DOM event-name remap.
+*
+* The compiler translates JSX event handler attributes (`onClick`,
+* `onMouseEnter`, ...) to DOM event names by stripping the `on` prefix
+* and lowercasing. That rule covers MOST React event-name conventions
+* because the underlying DOM event name happens to be the lowercased
+* multi-word form (e.g. `onKeyDown` → `keydown`, `onMouseEnter` →
+* `mouseenter`, `onPointerLeave` → `pointerleave`,
+* `onAnimationStart` → `animationstart`, `onContextMenu` → `contextmenu`).
+*
+* **The exceptions** — where lowercasing produces the WRONG DOM event
+* name — are listed in `REACT_EVENT_REMAP` below. Each entry maps the
+* lowercased React form to the actual DOM event name.
+*
+* Today there is exactly ONE remap: `doubleclick → dblclick`. React
+* inherits this mismatch from the DOM spec — `dblclick` is the canonical
+* event name (RFC at `https://dom.spec.whatwg.org/#interface-mouseevent`),
+* while React's component-prop convention is the `onDoubleClick` shape.
+*
+* **Audit completeness.** The full React event-prop list from
+* `https://react.dev/reference/react-dom/components/common` was checked
+* against canonical DOM event names. Every multi-word event other than
+* `onDoubleClick` lowercases correctly:
+*   - Pointer family: `onPointerDown` → `pointerdown`, `onGotPointerCapture` → `gotpointercapture`, …
+*   - Mouse family: `onMouseEnter` → `mouseenter`, `onMouseLeave` → `mouseleave`, …
+*   - Drag family: `onDragStart` → `dragstart`, `onDragEnd` → `dragend`, …
+*   - Touch family: `onTouchStart` → `touchstart`, `onTouchEnd` → `touchend`, …
+*   - Composition family: `onCompositionEnd` → `compositionend`, …
+*   - Animation/transition: `onAnimationStart` → `animationstart`, `onTransitionEnd` → `transitionend`, …
+*   - Media family: `onCanPlayThrough` → `canplaythrough`, `onLoadedData` → `loadeddata`, `onTimeUpdate` → `timeupdate`, `onVolumeChange` → `volumechange`, …
+*   - Form family: `onContextMenu` → `contextmenu`, `onBeforeInput` → `beforeinput`, …
+*
+* If a future React release adds a new event-prop with a non-trivial
+* mismatch, append the entry here. Both compiler backends (JS and Rust)
+* read the same shape — the Rust port lives in `native/src/lib.rs` next
+* to `emit_event_listener`. Keep them in sync.
+*
+* **Testing.** `packages/core/compiler/src/tests/runtime/events.test.ts`
+* exercises this table end-to-end via a real-Chromium harness:
+*   - `onDoubleClick fires (multi-word + delegated)` — locks in the remap.
+*   - `onContextMenu fires (multi-word, lowercases to contextmenu)` —
+*     locks in the no-remap default for an adjacent multi-word event.
+*   - `event-name-remap-table sanity` — asserts that every entry in
+*     `REACT_EVENT_REMAP` has a corresponding runtime test.
+*/
+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
 /**
 * JSX transform — wraps dynamic JSX expressions in `() =>` so the Pyreon runtime
@@ -37,11 +183,8 @@ import ts from "typescript";
 *
 * 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([
@@ -555,16 +698,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");
@@ -572,11 +715,11 @@ 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) result = `import { _rp } from "@pyreon/core";\n` + result;
+	if (needsRpImport) output = `import { _rp } from "@pyreon/core";\n` + output;
 	return {
-		code: result,
+		code: output,
 		usesTemplates: needsTplImport,
 		warnings
 	};
@@ -661,7 +804,8 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			else bindLines.push(`{ const __r = ${sliceExpr(expr)}; if (typeof __r === "function") __r(${varName}); else if (__r) __r.current = ${varName} }`);
 		}
 		function emitEventListener(attr, attrName, varName) {
-			const eventName = (attrName[2] ?? "").toLowerCase() + attrName.slice(3);
+			const lowered = attrName.slice(2).toLowerCase();
+			const eventName = REACT_EVENT_REMAP[lowered] ?? lowered;
 			if (!attr.value || attr.value.type !== "JSXExpressionContainer") return;
 			const expr = attr.value.expression;
 			if (!expr || expr.type === "JSXEmptyExpression") return;
@@ -702,6 +846,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		function attrSetter(htmlAttrName, varName, expr) {
 			if (htmlAttrName === "class") return `${varName}.className = ${expr}`;
 			if (htmlAttrName === "style") return `${varName}.style.cssText = ${expr}`;
+			if (DOM_PROPS.has(htmlAttrName)) return `${varName}.${htmlAttrName} = ${expr}`;
 			return `${varName}.setAttribute("${htmlAttrName}", ${expr})`;
 		}
 		function emitDynamicAttr(_expr, exprNode, htmlAttrName, varName) {
@@ -714,7 +859,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			if (directRef) {
 				needsBindDirectImport = true;
 				const d = nextDisp();
-				const updater = htmlAttrName === "class" ? `(v) => { ${varName}.className = v == null ? "" : String(v) }` : htmlAttrName === "style" ? `(v) => { if (typeof v === "string") ${varName}.style.cssText = v; else if (v) Object.assign(${varName}.style, v) }` : `(v) => { ${varName}.setAttribute("${htmlAttrName}", v == null ? "" : String(v)) }`;
+				const updater = htmlAttrName === "class" ? `(v) => { ${varName}.className = v == null ? "" : String(v) }` : htmlAttrName === "style" ? `(v) => { if (typeof v === "string") ${varName}.style.cssText = v; else if (v) Object.assign(${varName}.style, v) }` : DOM_PROPS.has(htmlAttrName) ? `(v) => { ${varName}.${htmlAttrName} = v }` : `(v) => { ${varName}.setAttribute("${htmlAttrName}", v == null ? "" : String(v)) }`;
 				bindLines.push(`const ${d} = _bindDirect(${directRef}, ${updater})`);
 				return;
 			}
@@ -798,10 +943,10 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		}
 		function classifyJsxChild(child, out, elemIdxRef, recurse) {
 			if (child.type === "JSXText") {
-				const trimmed = (child.value ?? child.raw ?? "").replace(/\n\s*/g, "").trim();
-				if (trimmed) out.push({
+				const cleaned = cleanJsxText(child.value ?? child.raw ?? "");
+				if (cleaned) out.push({
 					kind: "text",
-					text: trimmed
+					text: cleaned
 				});
 				return;
 			}
@@ -834,10 +979,10 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		}
 		function analyzeChildren(flatChildren) {
 			const hasElem = flatChildren.some((c) => c.kind === "element");
-			const hasNonElem = flatChildren.some((c) => c.kind !== "element");
+			const hasText = flatChildren.some((c) => c.kind === "text");
 			const exprCount = flatChildren.filter((c) => c.kind === "expression").length;
 			return {
-				useMixed: hasElem && hasNonElem,
+				useMixed: (hasElem ? 1 : 0) + (hasText ? 1 : 0) + (exprCount > 0 ? 1 : 0) > 1,
 				useMultiExpr: exprCount > 1
 			};
 		}
@@ -914,7 +1059,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			bindLines.push(`const ${combinedName} = _bind(() => { ${combinedBody} })`);
 		}
 		if (bindLines.length === 0 && disposerNames.length === 0) return `_tpl("${escaped}", () => null)`;
-		let body = bindLines.map((l) => `  ${l}`).join("\n");
+		let body = bindLines.map((l) => `  ${l};`).join("\n");
 		if (disposerNames.length > 0) body += `\n  return () => { ${disposerNames.map((d) => `${d}()`).join("; ")} }`;
 		else body += "\n  return null";
 		return `_tpl("${escaped}", (__root) => {\n${body}\n})`;
@@ -934,6 +1079,10 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		if (node.type === "Identifier" && isActiveSignal(node.name)) {
 			const parent = findParent(node);
 			if (parent && parent.type === "MemberExpression" && parent.property === node && !parent.computed) return false;
+			if (parent && parent.type === "MemberExpression" && parent.object === node) {
+				const grand = findParent(parent);
+				if (grand && grand.type === "CallExpression" && grand.callee === parent) return false;
+			}
 			if (parent && parent.type === "CallExpression" && parent.callee === node) return false;
 			return true;
 		}
@@ -955,6 +1104,10 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			if (node.type === "Identifier" && isActiveSignal(node.name)) {
 				const parent = findParent(node);
 				if (parent && parent.type === "MemberExpression" && parent.property === node && !parent.computed) return;
+				if (parent && parent.type === "MemberExpression" && parent.object === node) {
+					const grand = findParent(parent);
+					if (grand && grand.type === "CallExpression" && grand.callee === parent) return;
+				}
 				if (parent && parent.type === "CallExpression" && parent.callee === node) return;
 				if (parent && parent.type === "VariableDeclarator" && parent.id === node) return;
 				if (parent && (parent.type === "Property" || parent.type === "ObjectProperty")) {
@@ -1002,6 +1155,15 @@ const JSX_TO_HTML_ATTR = {
 	className: "class",
 	htmlFor: "for"
 };
+const DOM_PROPS = new Set([
+	"value",
+	"checked",
+	"selected",
+	"disabled",
+	"multiple",
+	"readOnly",
+	"indeterminate"
+]);
 const STATEFUL_CALLS = new Set([
 	"signal",
 	"computed",
@@ -1054,6 +1216,23 @@ function escapeHtmlAttr(s) {
 function escapeHtmlText(s) {
 	return s.replace(/&(?!(?:#\d+|#x[\da-fA-F]+|[a-zA-Z]\w*);)/g, "&amp;").replace(/</g, "&lt;");
 }
+function cleanJsxText(raw) {
+	if (!raw.includes("\n") && !raw.includes("\r")) return raw;
+	const lines = raw.split(/\r\n|\n|\r/);
+	let lastNonEmpty = -1;
+	for (let i = 0; i < lines.length; i++) if (/[^ \t]/.test(lines[i] ?? "")) lastNonEmpty = i;
+	let str = "";
+	for (let i = 0; i < lines.length; i++) {
+		let line = (lines[i] ?? "").replace(/\t/g, " ");
+		if (i !== 0) line = line.replace(/^ +/, "");
+		if (i !== lines.length - 1) line = line.replace(/ +$/, "");
+		if (line) {
+			if (i !== lastNonEmpty) line += " ";
+			str += line;
+		}
+	}
+	return str;
+}
 function isStaticJSXNode(node) {
 	if (node.type === "JSXElement" && node.openingElement?.selfClosing) return isStaticAttrs(node.openingElement.attributes ?? []);
 	if (node.type === "JSXFragment") return (node.children ?? []).every(isStaticChild);
@@ -2004,6 +2183,26 @@ function diagnoseError(error) {
 *                       monotonic counter.
 *  - `on-click-undefined` — `onClick={undefined}` explicitly; the runtime
 *                       used to crash on this pattern. Omit the prop.
+*  - `signal-write-as-call` — `sig(value)` is a no-op read that ignores
+*                       its argument; the runtime warns in dev. Static
+*                       detector spots it pre-runtime when `sig` was
+*                       declared as `const sig = signal(...)` /
+*                       `computed(...)` and called with ≥1 argument.
+*  - `static-return-null-conditional` — `if (cond) return null` at the
+*                       top of a component body runs ONCE; signal changes
+*                       in `cond` never re-evaluate the early-return.
+*                       Wrap in a returned reactive accessor.
+*  - `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
@@ -2164,9 +2363,185 @@ function detectOnClickUndefined(ctx, node) {
 	if (!(ts.isIdentifier(expr) && expr.text === "undefined" || expr.kind === ts.SyntaxKind.VoidExpression)) return;
 	pushDiag(ctx, node, "on-click-undefined", `\`${attrName}={undefined}\` explicitly passes undefined as a listener. Pyreon's runtime guards against this, but the cleanest pattern is to omit the attribute entirely or use a conditional: \`${attrName}={condition ? handler : undefined}\`.`, getNodeText(ctx, node), `/* omit ${attrName} when the handler is not defined */`, false);
 }
+/**
+* Walks the file and collects every identifier bound to a `signal(...)` or
+* `computed(...)` call. Only `const` declarations are tracked — `let`/`var`
+* may be reassigned to non-signal values, so a use-site call wouldn't be a
+* reliable signal-write.
+*
+* The collection is intentionally scope-blind: a name shadowed in a nested
+* scope (`const x = signal(0); function f() { const x = 5; x(7) }`) would
+* produce a false positive on `x(7)`. That tradeoff is acceptable because
+* (1) shadowing a signal name with a non-signal is itself unusual and
+* (2) the detector message points at exactly the wrong-shape call so a
+* human reviewer can dismiss the rare false positive in seconds.
+*/
+function collectSignalBindings(sf) {
+	const names = /* @__PURE__ */ new Set();
+	function isSignalFactoryCall(init) {
+		if (!init || !ts.isCallExpression(init)) return false;
+		const callee = init.expression;
+		if (!ts.isIdentifier(callee)) return false;
+		return callee.text === "signal" || callee.text === "computed";
+	}
+	function walk(node) {
+		if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+			const list = node.parent;
+			if (ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Const) !== 0 && isSignalFactoryCall(node.initializer)) names.add(node.name.text);
+		}
+		ts.forEachChild(node, walk);
+	}
+	walk(sf);
+	return names;
+}
+function detectSignalWriteAsCall(ctx, node) {
+	if (ctx.signalBindings.size === 0) return;
+	const callee = node.expression;
+	if (!ts.isIdentifier(callee)) return;
+	if (!ctx.signalBindings.has(callee.text)) return;
+	if (node.arguments.length === 0) return;
+	pushDiag(ctx, node, "signal-write-as-call", `\`${callee.text}(value)\` does NOT write the signal — \`signal()\` is the read-only callable surface and ignores its arguments. Use \`${callee.text}.set(value)\` to assign or \`${callee.text}.update((prev) => …)\` to derive from the previous value. Pyreon's runtime warns about this pattern in dev, but the warning fires AFTER the silent no-op.`, getNodeText(ctx, node), `${callee.text}.set(${node.arguments.map((a) => getNodeText(ctx, a)).join(", ")})`, false);
+}
+/**
+* `if (cond) return null` at the top of a component body runs ONCE — Pyreon
+* components mount and never re-execute their function bodies. A signal
+* change inside `cond` therefore never re-evaluates the condition; the
+* component is permanently stuck on whichever branch the first run picked.
+*
+* The fix is to wrap the conditional in a returned reactive accessor:
+*   return (() => { if (!cond()) return null; return <div /> })
+*
+* Detection:
+*  - The function contains JSX (i.e. it's a component)
+*  - The function body has an `IfStatement` whose `thenStatement` is
+*    `return null` (either bare `return null` or `{ return null }`)
+*  - The `if` is at the function body's top level, NOT inside a returned
+*    arrow / IIFE (those are reactive scopes — flagging them would be a
+*    false positive)
+*/
+function returnsNullStatement(stmt) {
+	if (ts.isReturnStatement(stmt)) {
+		const expr = stmt.expression;
+		return !!expr && expr.kind === ts.SyntaxKind.NullKeyword;
+	}
+	if (ts.isBlock(stmt)) return stmt.statements.length === 1 && returnsNullStatement(stmt.statements[0]);
+	return false;
+}
+/**
+* Returns true if the function looks like a top-level component:
+*  - `function PascalName(...) { ... }` (FunctionDeclaration with PascalCase id), OR
+*  - `const PascalName = (...) => { ... }` (arrow inside a VariableDeclaration whose name is PascalCase).
+*
+* Anonymous nested arrows — most importantly the reactive accessor
+* `return (() => { if (!cond()) return null; return <div /> })` — are
+* NOT considered components here, even when they contain JSX. Without
+* this filter the detector would fire on the very pattern the
+* diagnostic recommends as the fix.
+*/
+function isComponentShapedFunction(node) {
+	if (ts.isFunctionDeclaration(node)) return !!node.name && /^[A-Z]/.test(node.name.text);
+	const parent = node.parent;
+	if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) return /^[A-Z]/.test(parent.name.text);
+	return false;
+}
+function detectStaticReturnNullConditional(ctx, node) {
+	if (!isComponentShapedFunction(node)) return;
+	if (!containsJsx(node)) return;
+	const body = node.body;
+	if (!body || !ts.isBlock(body)) return;
+	for (const stmt of body.statements) {
+		if (!ts.isIfStatement(stmt)) continue;
+		if (!returnsNullStatement(stmt.thenStatement)) continue;
+		pushDiag(ctx, stmt, "static-return-null-conditional", "Pyreon components run ONCE — `if (cond) return null` at the top of a component body is evaluated exactly once at mount. Reading a signal inside `cond` will NOT re-trigger the early return when the signal changes; the component is stuck on whichever branch the first run picked. Wrap the conditional in a returned reactive accessor: `return (() => { if (!cond()) return null; return <div /> })` — the accessor re-runs whenever its tracked signals change.", getNodeText(ctx, stmt), "return (() => { if (!cond()) return null; return <JSX /> })", false);
+		return;
+	}
+}
+/**
+* `JSX.Element` (which is what JSX evaluates to) is already assignable to
+* `VNodeChild`. The `as unknown as VNodeChild` double-cast is unnecessary
+* — it's been showing up in `@pyreon/ui-primitives` as a defensive habit
+* carried over from earlier framework versions. The cast is never load-
+* bearing today; removing it never changes runtime behavior. Pure cosmetic
+* but a useful proxy for non-idiomatic Pyreon code in primitives.
+*/
+function detectAsUnknownAsVNodeChild(ctx, node) {
+	const outerType = node.type;
+	if (!ts.isTypeReferenceNode(outerType)) return;
+	if (!ts.isIdentifier(outerType.typeName) || outerType.typeName.text !== "VNodeChild") return;
+	const inner = node.expression;
+	if (!ts.isAsExpression(inner)) return;
+	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)) detectPropsDestructured(ctx, node);
+	if (ts.isArrowFunction(node) || ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
+		detectPropsDestructured(ctx, node);
+		detectStaticReturnNullConditional(ctx, node);
+	}
 	if (ts.isBinaryExpression(node)) {
 		detectProcessDevGate(ctx, node);
 		detectDateMathRandomId(ctx, node);
@@ -2175,8 +2550,11 @@ function visitNode(ctx, node) {
 	if (ts.isCallExpression(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);
 }
 function visit(ctx, node) {
 	ts.forEachChild(node, (child) => {
@@ -2189,7 +2567,9 @@ function detectPyreonPatterns(code, filename = "input.tsx") {
 	const ctx = {
 		sf,
 		code,
-		diagnostics: []
+		diagnostics: [],
+		signalBindings: collectSignalBindings(sf),
+		neverIslandNames: collectNeverIslandNames(sf)
 	};
 	visit(ctx, sf);
 	ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
@@ -2197,7 +2577,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);
+	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
@@ -2231,7 +2611,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 {
@@ -2397,7 +2777,7 @@ function classifyRisk(entry) {
 	return "medium";
 }
 function auditTestEnvironment(startDir) {
-	const root = findMonorepoRoot(startDir);
+	const root = findMonorepoRoot$2(startDir);
 	if (!root) return {
 		root: null,
 		entries: [],
@@ -2512,5 +2892,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, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index.js.map