@pyreon/compiler 0.16.0 → 0.19.0

package/lib/index.js

@@ -3,10 +3,455 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { dirname, join, relative, resolve } from "node:path";
+import ts from "typescript";
 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 title="hi" /></Defer>
+*
+* into:
+*
+*     <Defer when={open()} chunk={() => import('./Modal').then((__m) => ({ default: __m.Modal }))}>
+*       {(__C) => <__C title="hi" />}
+*     </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 (v2 — post #587 + this PR):
+*   - Multiple Defer elements per file: each rewritten independently.
+*   - Children: exactly ONE JSXElement, capitalised name (component
+*     reference). Self-closing OR with children. **Props ARE allowed**
+*     (post-v2) and pass through unchanged into the render-prop body —
+*     closure capture works naturally because the render-prop arrow
+*     captures the surrounding lexical scope.
+*   - Multiple non-whitespace children → bail with a warning.
+*     User must use the explicit `chunk` form with a render-prop.
+*   - Imports: default, named, **renamed** (`{ X as Y }`). Namespace
+*     imports (`* as M` + `<M.X />`) NOT supported — bail with a warning.
+*   - **Multi-specifier imports** (`{ A, B } from './x'`): only the
+*     binding used in Defer is removed; siblings stay intact.
+*   - 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. Pipeline: runs BEFORE
+* `transformJSX()` in the vite plugin. The output is still JSX —
+* `transformJSX` then converts to runtime calls as usual.
+*/
+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 (`<Modal />`). Member-expression names
+* (`<M.Modal />`) and namespaced names (`<svg:rect />`) return null —
+* use `getJsxMemberName()` for the namespace-import case.
+*/
+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;
+}
+/**
+* For `<M.Modal />` — returns `{ object: 'M', property: 'Modal' }` when
+* the JSX name is a depth-1 JSXMemberExpression. Returns null for any
+* other shape (deeper nesting like `<M.Sub.X />`, JSXNamespacedName,
+* non-identifier). The depth-1 restriction keeps the rewrite simple:
+* `M.Modal` is replaced with `__C` in the source.
+*/
+function getJsxMemberName(node) {
+	const open = node.openingElement;
+	if (!open) return null;
+	const name = open.name;
+	if (!name || name.type !== "JSXMemberExpression") return null;
+	const obj = name.object;
+	const prop = name.property;
+	if (!obj || obj.type !== "JSXIdentifier") return null;
+	if (!prop || prop.type !== "JSXIdentifier") return null;
+	return {
+		object: obj.name,
+		property: prop.name
+	};
+}
+/**
+* Verify a JSX child node is a single component-element we can rewrite.
+* Handles two shapes:
+*   1. `<Modal />` — identifier name, capitalised (component, not HTML).
+*   2. `<M.Modal />` — depth-1 member expression with capitalised
+*      property name. The object (`M`) is the local binding to look up;
+*      the property (`Modal`) is the actual export to extract.
+*
+* Both shapes allow props (post-v2). Deeper nesting (`<M.Sub.X />`),
+* JSXNamespacedName (`<svg:rect />`), and non-component lowercase names
+* return null.
+*/
+function analyzeChildElement(node) {
+	if (node.type !== "JSXElement") return null;
+	const openName = node.openingElement.name;
+	const close = node.closingElement;
+	const identName = getJsxName(node);
+	if (identName) {
+		if (!/^[A-Z]/.test(identName)) return null;
+		return {
+			kind: "identifier",
+			lookupName: identName,
+			propertyName: "",
+			openNameRange: {
+				start: openName.start,
+				end: openName.end
+			},
+			closeNameRange: close ? {
+				start: close.name.start,
+				end: close.name.end
+			} : null
+		};
+	}
+	const memberName = getJsxMemberName(node);
+	if (memberName) {
+		if (!/^[A-Z]/.test(memberName.property)) return null;
+		return {
+			kind: "member",
+			lookupName: memberName.object,
+			propertyName: memberName.property,
+			openNameRange: {
+				start: openName.start,
+				end: openName.end
+			},
+			closeNameRange: close ? {
+				start: close.name.start,
+				end: close.name.end
+			} : null
+		};
+	}
+	return null;
+}
+/** Filter whitespace-only JSXText nodes (formatting noise between JSX elements). */
+function nonWhitespaceChildren(node) {
+	return (node.children ?? []).filter((c) => !(c.type === "JSXText" && /^\s*$/.test(c.value)));
+}
+function findDeferMatches(program, warnings, code) {
+	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 loc = getLoc(code, node.start ?? 0);
+					warnings.push({
+						message: `<Defer> inline form requires exactly one component child (got ${live.length}). Wrap the children in a single component, or use the explicit \`chunk\` prop with a render-prop body.`,
+						line: loc.line,
+						column: loc.column,
+						code: "defer-inline/multiple-children"
+					});
+				} else if (live.length === 1) {
+					const analysis = analyzeChildElement(live[0]);
+					if (analysis) {
+						const close = node.closingElement;
+						matches.push({
+							node,
+							child: live[0],
+							childAnalysis: analysis,
+							insertChunkAt: open.end - 1,
+							childrenRange: {
+								start: open.end,
+								end: close?.start ?? node.end
+							}
+						});
+					} else {
+						const loc = getLoc(code, live[0].start ?? 0);
+						warnings.push({
+							message: `<Defer> inline form requires a single component-element child (capitalised JSX identifier). Use the explicit \`chunk\` prop for any other shape.`,
+							line: loc.line,
+							column: loc.column,
+							code: "defer-inline/non-component-child"
+						});
+					}
+				}
+			}
+		}
+		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;
+}
+/**
+* Locate the import declaration that binds `localName`.
+*
+* For namespace imports (`import * as M`), `localName` is the namespace
+* identifier (`M`). The caller's `propertyName` provides the actual
+* export name to extract — `findImportFor` returns `importedName: ''`
+* for the namespace case and the caller substitutes its own property.
+*/
+function findImportFor(program, localName) {
+	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 === localName) return {
+				declaration: stmt,
+				specifier: spec,
+				source: stmt.source.value,
+				kind: "default",
+				importedName: "default"
+			};
+		} else if (spec.type === "ImportSpecifier") {
+			const lname = spec.local.name;
+			const iname = spec.imported?.name;
+			if (lname === localName && iname !== void 0) return {
+				declaration: stmt,
+				specifier: spec,
+				source: stmt.source.value,
+				kind: "named",
+				importedName: iname
+			};
+		} else if (spec.type === "ImportNamespaceSpecifier") {
+			if (spec.local.name === localName) return {
+				declaration: stmt,
+				specifier: spec,
+				source: stmt.source.value,
+				kind: "namespace",
+				importedName: ""
+			};
+		}
+	}
+	return null;
+}
+/**
+* Count references to `localName` outside the given Defer subtree, AND
+* outside the import declaration that defines it. The static import can
+* only be safely removed when the local binding is used EXCLUSIVELY
+* inside that Defer subtree — otherwise removing the import would break
+* the other usage AND the dynamic import would be a no-op (Rolldown
+* static-bundles the module on shared usage).
+*/
+function countReferencesOutside(program, localName, skipSubtree, skipDeclaration) {
+	let count = 0;
+	const skipStart = skipSubtree.start;
+	const skipEnd = skipSubtree.end;
+	const declStart = skipDeclaration.start;
+	const declEnd = skipDeclaration.end;
+	const inSkip = (s, e) => s >= skipStart && e <= skipEnd || s >= declStart && e <= declEnd;
+	const visit = (node) => {
+		if (!node || typeof node !== "object") return;
+		const ns = node.start;
+		const ne = node.end;
+		if (typeof ns === "number" && typeof ne === "number" && inSkip(ns, ne)) return;
+		if (node.type === "Identifier" && node.name === localName) count++;
+		if (node.type === "JSXIdentifier" && node.name === localName) count++;
+		for (const key in node) {
+			if (key === "parent") continue;
+			const v = node[key];
+			if (Array.isArray(v)) for (const item of v) visit(item);
+			else if (v && typeof v === "object" && typeof v.type === "string") visit(v);
+		}
+	};
+	const body = program.body ?? [];
+	for (const stmt of body) visit(stmt);
+	return count;
+}
+/**
+* Build the chunk={...} attribute string.
+*
+* - `default` → `chunk={() => import('./x')}`. The default export IS the
+*   component; no re-wrapping needed.
+* - `named` / `namespace` → `chunk={() => import('./x').then((__m) => ({
+*   default: __m.X }))}`. The `default` slot points at the named export
+*   (for `named`) or the member-expression property (for `namespace`).
+*
+* The caller picks `exportName` — for `named`, it's `info.importedName`;
+* for `namespace`, it's the JSX member-expression property.
+*/
+function buildChunkAttr(source, kind, exportName) {
+	if (kind === "default") return ` chunk={() => import('${source}')}`;
+	return ` chunk={() => import('${source}').then((__m) => ({ default: __m.${exportName} }))}`;
+}
+/**
+* Build the render-prop body from the original child JSX. Replaces the
+* component name (in both opening and closing tags) with `__C` — every
+* other character of the original source survives verbatim. Props /
+* nested children / event handlers / closure captures all flow through
+* unchanged. The render-prop arrow's lexical scope captures whatever
+* was in scope at the call site.
+*/
+function buildRenderPropBody(code, analysis, childRange) {
+	const start = childRange.start;
+	const end = childRange.end;
+	let body = code.slice(start, end);
+	if (analysis.closeNameRange) {
+		const r = analysis.closeNameRange;
+		body = body.slice(0, r.start - start) + "__C" + body.slice(r.end - start);
+	}
+	body = body.slice(0, analysis.openNameRange.start - start) + "__C" + body.slice(analysis.openNameRange.end - start);
+	return `{(__C) => ${body}}`;
+}
+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;
+}
+/**
+* Compute the edit that removes the import binding for the given match.
+* Handles three shapes:
+*   1. Single-specifier declaration → remove the entire ImportDeclaration
+*      (including its trailing newline).
+*   2. Multi-specifier declaration where this is the FIRST specifier →
+*      remove the specifier + the comma + whitespace that follows it.
+*   3. Multi-specifier declaration where this is a LATER specifier →
+*      remove the preceding comma + whitespace + the specifier.
+*
+* Case (1) is the simple v1 path; cases (2) and (3) are the v2
+* multi-specifier handling.
+*/
+function buildImportRemovalEdit(code, info) {
+	const specifiers = info.declaration.specifiers ?? [];
+	if (specifiers.length === 1) {
+		const start = info.declaration.start;
+		let end = info.declaration.end;
+		if (code[end] === "\n") end += 1;
+		return {
+			start,
+			end,
+			replacement: ""
+		};
+	}
+	const idx = specifiers.indexOf(info.specifier);
+	const specStart = info.specifier.start;
+	const specEnd = info.specifier.end;
+	if (idx === 0) return {
+		start: specStart,
+		end: specifiers[1].start,
+		replacement: ""
+	};
+	return {
+		start: specifiers[idx - 1].end,
+		end: specEnd,
+		replacement: ""
+	};
+}
+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, warnings, code);
+	if (matches.length === 0) return {
+		code,
+		changed: false,
+		warnings
+	};
+	const edits = [];
+	let changed = false;
+	for (const m of matches) {
+		const displayName = m.childAnalysis.kind === "member" ? `${m.childAnalysis.lookupName}.${m.childAnalysis.propertyName}` : m.childAnalysis.lookupName;
+		const importInfo = findImportFor(program, m.childAnalysis.lookupName);
+		if (!importInfo) {
+			const loc = getLoc(code, m.child.start ?? 0);
+			warnings.push({
+				message: `<Defer>'s inline child <${displayName} /> isn't imported — can't resolve a chunk source. Use the explicit \`chunk\` prop, or import ${m.childAnalysis.lookupName} from a module.`,
+				line: loc.line,
+				column: loc.column,
+				code: "defer-inline/import-not-found"
+			});
+			continue;
+		}
+		if (m.childAnalysis.kind === "member" && importInfo.kind !== "namespace") {
+			const loc = getLoc(code, m.child.start ?? 0);
+			warnings.push({
+				message: `<Defer>'s inline child <${displayName} /> uses a member expression but \`${m.childAnalysis.lookupName}\` isn't a namespace import. Inline form requires \`import * as ${m.childAnalysis.lookupName} from '...'\`. Use the explicit \`chunk\` prop for other shapes.`,
+				line: loc.line,
+				column: loc.column,
+				code: "defer-inline/unsupported-import-shape"
+			});
+			continue;
+		}
+		if (m.childAnalysis.kind === "identifier" && importInfo.kind === "namespace") continue;
+		if (countReferencesOutside(program, m.childAnalysis.lookupName, m.node, importInfo.declaration) > 0) {
+			const loc = getLoc(code, m.node.start ?? 0);
+			warnings.push({
+				message: `<Defer>'s inline child <${displayName} /> 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;
+		}
+		const exportName = importInfo.kind === "namespace" ? m.childAnalysis.propertyName : importInfo.importedName;
+		edits.push({
+			start: m.insertChunkAt,
+			end: m.insertChunkAt,
+			replacement: buildChunkAttr(importInfo.source, importInfo.kind, exportName)
+		});
+		edits.push({
+			start: m.childrenRange.start,
+			end: m.childrenRange.end,
+			replacement: buildRenderPropBody(code, m.childAnalysis, m.childrenRange)
+		});
+		edits.push(buildImportRemovalEdit(code, importInfo));
+		changed = true;
+	}
+	if (!changed) return {
+		code,
+		changed: false,
+		warnings
+	};
+	return {
+		code: applyEdits(code, edits),
+		changed: true,
+		warnings
+	};
+}
+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.
@@ -266,7 +711,7 @@ function jsxChildren(node) {
 }
 function transformJSX(code, filename = "input.tsx", options = {}) {
 	if (nativeTransformJsx) try {
-		return nativeTransformJsx(code, filename, options.ssr === true, options.knownSignals ?? null);
+		return nativeTransformJsx(code, filename, options.ssr === true, options.knownSignals ?? null, options.reactivityLens === true);
 	} catch {}
 	return transformJSX_JS(code, filename, options);
 }
@@ -297,6 +742,23 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			code: warnCode
 		});
 	}
+	const collectLens = options.reactivityLens === true;
+	const reactivityLens = [];
+	function lens(start, end, kind, detail) {
+		if (!collectLens) return;
+		const a = locate(start);
+		const b = locate(end);
+		reactivityLens.push({
+			start,
+			end,
+			line: a.line,
+			column: a.column,
+			endLine: b.line,
+			endColumn: b.column,
+			kind,
+			detail
+		});
+	}
 	const parentMap = /* @__PURE__ */ new WeakMap();
 	const childrenMap = /* @__PURE__ */ new WeakMap();
 	/** Build parent pointers + cached children arrays for the entire AST. */
@@ -333,6 +795,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;
@@ -346,6 +809,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 				name,
 				text
 			});
+			lens(node.start, node.end, "hoisted-static", "static — hoisted once to module scope, never re-evaluated");
 			return name;
 		}
 		return null;
@@ -360,6 +824,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			end,
 			text
 		});
+		lens(start, end, "reactive", "live — re-evaluates whenever its signals change");
 	}
 	function hoistOrWrap(expr) {
 		const hoistName = maybeHoist(expr);
@@ -392,6 +857,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;
@@ -421,6 +921,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 					text: `_rp(() => ${inner})`
 				});
 				needsRpImport = true;
+				lens(start, end, "reactive-prop", "live prop — signal reads here are tracked into the component");
 			}
 		} else hoistOrWrap(expr);
 	}
@@ -677,6 +1178,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;
@@ -693,7 +1195,11 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		if (scopeShadows) for (const name of scopeShadows) shadowedSignals.delete(name);
 	}
 	walkNode(program);
-	if (replacements.length === 0 && hoists.length === 0) return {
+	if (replacements.length === 0 && hoists.length === 0) return collectLens ? {
+		code,
+		warnings,
+		reactivityLens
+	} : {
 		code,
 		warnings
 	};
@@ -717,8 +1223,18 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		const reactivityImports = needsBindImportGlobal ? `\nimport { _bind } from "@pyreon/reactivity";` : "";
 		output = `import { ${runtimeDomImports.join(", ")} } from "@pyreon/runtime-dom";${reactivityImports}\n` + output;
 	}
-	if (needsRpImport) output = `import { _rp } from "@pyreon/core";\n` + output;
-	return {
+	if (needsRpImport || needsWrapSpreadImport) {
+		const coreImports = [];
+		if (needsRpImport) coreImports.push("_rp");
+		if (needsWrapSpreadImport) coreImports.push("_wrapSpread");
+		output = `import { ${coreImports.join(", ")} } from "@pyreon/core";\n` + output;
+	}
+	return collectLens ? {
+		code: output,
+		usesTemplates: needsTplImport,
+		warnings,
+		reactivityLens
+	} : {
 		code: output,
 		usesTemplates: needsTplImport,
 		warnings
@@ -855,6 +1371,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 				bindLines.push(attrSetter(htmlAttrName, varName, expr));
 				return;
 			}
+			lens(exprNode.start, exprNode.end, "reactive-attr", `live attribute — \`${htmlAttrName}\` re-applies whenever its signals change`);
 			const directRef = tryDirectSignalRef(exprNode);
 			if (directRef) {
 				needsBindDirectImport = true;
@@ -1015,7 +1532,12 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 				bindLines.push(`const ${d} = _mountSlot(${expr}, ${parentRef}, ${placeholder})`);
 				return "<!>";
 			}
-			if (isReactive) return emitReactiveTextChild(expr, child.expression, varName, parentRef, childNodeIdx, needsPlaceholder);
+			const cx = child.expression;
+			if (isReactive) {
+				lens(cx.start, cx.end, "reactive", "live — this text re-renders whenever its signals change");
+				return emitReactiveTextChild(expr, child.expression, varName, parentRef, childNodeIdx, needsPlaceholder);
+			}
+			lens(cx.start, cx.end, "static-text", "baked once into the DOM — never re-renders (no signal read here)");
 			return emitStaticTextChild(expr, varName, parentRef, childNodeIdx, needsPlaceholder);
 		}
 		function processChildren(el, varName, accessor) {
@@ -1318,1266 +1840,1511 @@ function isPureStaticCall(node) {
 }
 
 //#endregion
-//#region src/project-scanner.ts
+//#region src/pyreon-intercept.ts
 /**
-* Project scanner — extracts route, component, and island information from source files.
+* Pyreon Pattern Interceptor — detects Pyreon-specific anti-patterns in
+* code that has ALREADY committed to the framework (imports are Pyreon,
+* not React). Complements `react-intercept.ts` — the React detector
+* catches "coming from React" mistakes; this one catches "using Pyreon
+* wrong" mistakes.
+*
+* Catalog of detected patterns (grounded in `.claude/rules/anti-patterns.md`):
+*
+*  - `for-missing-by` — `<For each={...}>` without a `by` prop
+*  - `for-with-key`   — `<For key={...}>` (JSX reserves `key`; the keying
+*                       prop is `by` in Pyreon)
+*  - `props-destructured` — `({ foo }: Props) => <JSX />` destructures at
+*                       the component signature; reading is captured once
+*                       and loses reactivity. Access `props.foo` instead
+*                       or use `splitProps(props, [...])`.
+*  - `props-destructured-body` — `const { foo } = props` written
+*                       SYNCHRONOUSLY in a component body — the body-scope
+*                       companion to `props-destructured`. Same capture-
+*                       once death; nested-function destructures (handler
+*                       / effect / returned accessor) are NOT flagged
+*                       (they re-read `props` per invocation).
+*  - `process-dev-gate` — `typeof process !== 'undefined' &&
+*                       process.env.NODE_ENV !== 'production'` is dead
+*                       code in real Vite browser bundles. Use
+*                       `import.meta.env?.DEV` instead.
+*  - `empty-theme`    — `.theme({})` chain is a no-op; remove it.
+*  - `raw-add-event-listener` — raw `addEventListener(...)` in a component
+*                       or hook body. Use `useEventListener(...)` from
+*                       `@pyreon/hooks` for auto-cleanup.
+*  - `raw-remove-event-listener` — same, for removeEventListener.
+*  - `date-math-random-id` — `Date.now() + Math.random()` / template-concat
+*                       variants. Under rapid operations (paste, clone)
+*                       collision probability is non-trivial. Use a
+*                       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
+*  - `hasPyreonPatterns(code)`   — fast regex pre-filter
+*
+* ## fixable: false (invariant)
+*
+* Every Pyreon diagnostic reports `fixable: false` — no exceptions.
+* The `migrate_react` MCP tool only knows React mappings, so claiming
+* a Pyreon code is auto-fixable would mislead a consumer who wires
+* their UX off the flag and finds nothing applies the fix. Flip to
+* `true` ONLY when a companion `migrate_pyreon` tool ships in a
+* subsequent PR. The invariant is locked in
+* `tests/pyreon-intercept.test.ts` under "fixable contract".
+*
+* Designed for three consumers:
+*  1. Compiler pre-pass warnings during build
+*  2. CLI `pyreon doctor`
+*  3. MCP server `validate` tool
 */
-function generateContext(cwd) {
-	const files = collectSourceFiles(cwd);
-	return {
-		framework: "pyreon",
-		version: readVersion(cwd),
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		routes: extractRoutes(files, cwd),
-		components: extractComponents(files, cwd),
-		islands: extractIslands(files, cwd)
-	};
+function getNodeText(ctx, node) {
+	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
 }
-function collectSourceFiles(cwd) {
-	const results = [];
-	const extensions = new Set([
-		".tsx",
-		".jsx",
-		".ts",
-		".js"
-	]);
-	const ignoreDirs = new Set([
-		"node_modules",
-		"dist",
-		"lib",
-		".pyreon",
-		".git",
-		"build"
-	]);
-	function walk(dir) {
-		let entries;
-		try {
-			entries = fs.readdirSync(dir, { withFileTypes: true });
-		} catch {
-			return;
-		}
-		for (const entry of entries) {
-			if (entry.name.startsWith(".") && entry.isDirectory()) continue;
-			if (ignoreDirs.has(entry.name) && entry.isDirectory()) continue;
-			const fullPath = path.join(dir, entry.name);
-			if (entry.isDirectory()) walk(fullPath);
-			else if (entry.isFile() && extensions.has(path.extname(entry.name))) results.push(fullPath);
-		}
-	}
-	walk(cwd);
-	return results;
+function pushDiag(ctx, node, code, message, current, suggested, fixable) {
+	const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
+	ctx.diagnostics.push({
+		code,
+		message,
+		line: line + 1,
+		column: character,
+		current: current.trim(),
+		suggested: suggested.trim(),
+		fixable
+	});
 }
-function extractRoutes(files, _cwd) {
-	const routes = [];
-	for (const file of files) {
-		let code;
-		try {
-			code = fs.readFileSync(file, "utf-8");
-		} catch {
-			continue;
-		}
-		const routeArrayRe = /(?:createRouter\s*\(\s*\[|(?:const|let)\s+routes\s*(?::\s*RouteRecord\[\])?\s*=\s*\[)([\s\S]*?)\]/g;
-		let match;
-		for (match = routeArrayRe.exec(code); match; match = routeArrayRe.exec(code)) {
-			const block = match[1] ?? "";
-			const routeObjRe = /path\s*:\s*["']([^"']+)["']/g;
-			let routeMatch;
-			for (routeMatch = routeObjRe.exec(block); routeMatch; routeMatch = routeObjRe.exec(block)) {
-				const routePath = routeMatch[1] ?? "";
-				const surroundingStart = Math.max(0, routeMatch.index - 50);
-				const surroundingEnd = Math.min(block.length, routeMatch.index + 200);
-				const surrounding = block.slice(surroundingStart, surroundingEnd);
-				routes.push({
-					path: routePath,
-					name: surrounding.match(/name\s*:\s*["']([^"']+)["']/)?.[1],
-					hasLoader: /loader\s*:/.test(surrounding),
-					hasGuard: /beforeEnter\s*:|beforeLeave\s*:/.test(surrounding),
-					params: extractParams(routePath)
-				});
-			}
+function getJsxTagName$1(node) {
+	const t = node.tagName;
+	if (ts.isIdentifier(t)) return t.text;
+	return "";
+}
+function findJsxAttribute(node, name) {
+	for (const attr of node.attributes.properties) if (ts.isJsxAttribute(attr) && ts.isIdentifier(attr.name) && attr.name.text === name) return attr;
+}
+function detectForKeying(ctx, node) {
+	if (getJsxTagName$1(node) !== "For") return;
+	const keyAttr = findJsxAttribute(node, "key");
+	if (keyAttr) pushDiag(ctx, keyAttr, "for-with-key", "`key` on <For> is reserved by JSX for VNode reconciliation and is extracted before the prop reaches the runtime. In Pyreon, use `by` for list identity.", getNodeText(ctx, keyAttr), getNodeText(ctx, keyAttr).replace(/^key\b/, "by"), false);
+	const eachAttr = findJsxAttribute(node, "each");
+	const byAttr = findJsxAttribute(node, "by");
+	if (eachAttr && !byAttr && !keyAttr) pushDiag(ctx, node, "for-missing-by", "<For each={...}> requires a `by` prop so the keyed reconciler can preserve item identity across reorders. Without `by`, every update remounts the full list.", getNodeText(ctx, node), "<For each={items} by={(item) => item.id}>", false);
+}
+function containsJsx(node) {
+	let found = false;
+	function walk(n) {
+		if (found) return;
+		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n) || ts.isJsxOpeningElement(n)) {
+			found = true;
+			return;
 		}
+		ts.forEachChild(n, walk);
 	}
-	return routes;
+	ts.forEachChild(node, walk);
+	if (!found) {
+		if (ts.isArrowFunction(node) && !ts.isBlock(node.body) && (ts.isJsxElement(node.body) || ts.isJsxSelfClosingElement(node.body) || ts.isJsxFragment(node.body))) found = true;
+	}
+	return found;
 }
-function extractComponents(files, cwd) {
-	const components = [];
-	for (const file of files) {
-		let code;
-		try {
-			code = fs.readFileSync(file, "utf-8");
-		} catch {
-			continue;
-		}
-		const componentRe = /(?:export\s+)?(?:const|function)\s+([A-Z]\w*)\s*(?::\s*ComponentFn<[^>]+>\s*)?=?\s*\(?(?:\s*\{?\s*([^)]*?)\s*\}?\s*)?\)?\s*(?:=>|{)/g;
-		let match;
-		for (match = componentRe.exec(code); match; match = componentRe.exec(code)) {
-			const name = match[1] ?? "Unknown";
-			const props = (match[2] ?? "").split(/[,;]/).map((p) => p.trim().replace(/[{}]/g, "").trim().split(":")[0]?.split("=")[0]?.trim() ?? "").filter((p) => p && p !== "props");
-			const bodyStart = match.index + match[0].length;
-			const body = code.slice(bodyStart, Math.min(code.length, bodyStart + 2e3));
-			const signalNames = [];
-			const signalRe = /(?:const|let)\s+(\w+)\s*=\s*signal\s*[<(]/g;
-			let sigMatch;
-			for (sigMatch = signalRe.exec(body); sigMatch; sigMatch = signalRe.exec(body)) if (sigMatch[1]) signalNames.push(sigMatch[1]);
-			components.push({
-				name,
-				file: path.relative(cwd, file),
-				hasSignals: signalNames.length > 0,
-				signalNames,
-				props
-			});
-		}
+function detectPropsDestructured(ctx, node) {
+	if (!node.parameters.length) return;
+	const first = node.parameters[0];
+	if (!first || !ts.isObjectBindingPattern(first.name)) return;
+	if (first.name.elements.length === 0) return;
+	if (!containsJsx(node)) return;
+	pushDiag(ctx, first, "props-destructured", "Destructuring props at the component signature captures the values ONCE during setup — subsequent signal writes in the parent do not update the destructured locals. Access `props.x` directly, or use `splitProps(props, [...])` to carve out a group while preserving reactivity.", getNodeText(ctx, first), "(props: Props) => /* read props.x directly */", false);
+}
+/**
+* Strip the wrappers that can sit between `=` and the props identifier
+* (`const { x } = (props as Props)!`) so we can compare the base
+* expression's identity to the component's first-parameter name.
+*/
+function unwrapInitializer(expr) {
+	let cur = expr;
+	let prev;
+	while (cur !== prev) {
+		prev = cur;
+		if (ts.isParenthesizedExpression(cur)) cur = cur.expression;
+		else if (ts.isAsExpression(cur)) cur = cur.expression;
+		else if (ts.isSatisfiesExpression(cur)) cur = cur.expression;
+		else if (ts.isNonNullExpression(cur)) cur = cur.expression;
 	}
-	return components;
+	return cur;
 }
-function extractIslands(files, cwd) {
-	const islands = [];
-	for (const file of files) {
-		let code;
-		try {
-			code = fs.readFileSync(file, "utf-8");
-		} catch {
-			continue;
+/**
+* Body-scope companion to {@link detectPropsDestructured}. Flags
+* `const { x } = props` (also `let` / `var`, aliases, defaults, rest,
+* nested patterns) written SYNCHRONOUSLY in a component's body.
+*
+* Why this is the footgun: the compiler emits `<C prop={sig()} />` as a
+* getter-shaped reactive prop. `const { x } = props` fires that getter
+* exactly ONCE at setup — `x` is a dead snapshot, never re-reads when
+* the signal changes. `props.x` (live member access inside a tracking
+* scope) or `splitProps(props, ['x'])` preserve the subscription.
+*
+* Precision (zero false positives is the priority — a missed body-scope
+* destructure is acceptable, a wrong one is not):
+*  - Only PascalCase, JSX-rendering functions (`isComponentShapedFunction`
+*    + `containsJsx`) — a plain helper that happens to destructure an
+*    options bag named `props` is NOT a component and is left alone.
+*  - The initializer must be the bare first-parameter identifier
+*    (`= props`), unwrapped through paren / `as` / `satisfies` / `!`.
+*    `const { x } = props.nested` and `= someOtherObject` are NOT
+*    flagged (rarer shapes; out of the canonical scope).
+*  - The destructure must be at the component-body top scope. A nested
+*    function boundary (`onClick` handler, `effect(() => …)`, a returned
+*    reactive accessor) re-reads `props` on each invocation, so those
+*    destructures are reactivity-correct — the walk does NOT descend
+*    into nested functions.
+*  - The first parameter must itself be a plain identifier; the
+*    parameter-destructure shape (`({ x }) => …`) is the existing
+*    `detectPropsDestructured`'s job, not this one.
+*/
+function detectPropsDestructuredBody(ctx, node) {
+	if (!isComponentShapedFunction(node)) return;
+	if (!containsJsx(node)) return;
+	if (!node.parameters.length) return;
+	const first = node.parameters[0];
+	if (!first || !ts.isIdentifier(first.name)) return;
+	const paramName = first.name.text;
+	const body = node.body;
+	if (!body || !ts.isBlock(body)) return;
+	function walk(n) {
+		if (ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n) || ts.isMethodDeclaration(n) || ts.isGetAccessorDeclaration(n) || ts.isSetAccessorDeclaration(n)) return;
+		if (ts.isVariableDeclaration(n) && ts.isObjectBindingPattern(n.name) && n.name.elements.length > 0 && n.initializer) {
+			const base = unwrapInitializer(n.initializer);
+			if (ts.isIdentifier(base) && base.text === paramName) pushDiag(ctx, n, "props-destructured-body", `Destructuring \`${paramName}\` in the component body captures the values ONCE during setup — the compiler emits signal-driven props as getters, so the destructured locals are dead snapshots that never update when the parent rewrites them. Read \`${paramName}.x\` directly inside the reactive scope (JSX / effect / computed), or use \`splitProps(${paramName}, ['x', ...])\` to carve out a group while preserving reactivity.`, getNodeText(ctx, n), `// read ${paramName}.x directly, or: const [local] = splitProps(${paramName}, ['x'])`, false);
 		}
-		const islandRe = /island\s*\(\s*\(\)\s*=>\s*import\(.+?\)\s*,\s*\{[^}]*name\s*:\s*["']([^"']+)["'][^}]*?(?:hydrate\s*:\s*["']([^"']+)["'])?[^}]*\}/g;
-		let match;
-		for (match = islandRe.exec(code); match; match = islandRe.exec(code)) if (match[1]) islands.push({
-			name: match[1],
-			file: path.relative(cwd, file),
-			hydrate: match[2] ?? "load"
-		});
+		ts.forEachChild(n, walk);
 	}
-	return islands;
+	for (const stmt of body.statements) walk(stmt);
 }
-function extractParams(routePath) {
-	const params = [];
-	const paramRe = /:(\w+)\??/g;
-	let match;
-	for (match = paramRe.exec(routePath); match; match = paramRe.exec(routePath)) if (match[1]) params.push(match[1]);
-	return params;
+function isTypeofProcess(node) {
+	if (!ts.isBinaryExpression(node)) return false;
+	if (node.operatorToken.kind !== ts.SyntaxKind.ExclamationEqualsEqualsToken) return false;
+	if (!ts.isTypeOfExpression(node.left)) return false;
+	if (!ts.isIdentifier(node.left.expression) || node.left.expression.text !== "process") return false;
+	return ts.isStringLiteral(node.right) && node.right.text === "undefined";
 }
-function readVersion(cwd) {
-	try {
-		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
-		const deps = {
-			...pkg.dependencies,
-			...pkg.devDependencies
-		};
-		for (const [name, ver] of Object.entries(deps)) if (name.startsWith("@pyreon/") && typeof ver === "string") return ver.replace(/^[\^~]/, "");
-		return pkg.version || "unknown";
-	} catch {
-		return "unknown";
+function isProcessNodeEnvProdGuard(node) {
+	if (!ts.isBinaryExpression(node)) return false;
+	if (node.operatorToken.kind !== ts.SyntaxKind.ExclamationEqualsEqualsToken) return false;
+	const left = node.left;
+	if (!ts.isPropertyAccessExpression(left)) return false;
+	if (!ts.isIdentifier(left.name) || left.name.text !== "NODE_ENV") return false;
+	if (!ts.isPropertyAccessExpression(left.expression)) return false;
+	if (!ts.isIdentifier(left.expression.name) || left.expression.name.text !== "env") return false;
+	if (!ts.isIdentifier(left.expression.expression)) return false;
+	if (left.expression.expression.text !== "process") return false;
+	return ts.isStringLiteral(node.right) && node.right.text === "production";
+}
+function detectProcessDevGate(ctx, node) {
+	if (node.operatorToken.kind !== ts.SyntaxKind.AmpersandAmpersandToken) return;
+	if (!(isTypeofProcess(node.left) && isProcessNodeEnvProdGuard(node.right) || isTypeofProcess(node.right) && isProcessNodeEnvProdGuard(node.left))) return;
+	pushDiag(ctx, node, "process-dev-gate", "The `typeof process !== \"undefined\" && process.env.NODE_ENV !== \"production\"` gate is DEAD CODE in real Vite browser bundles — Vite does not polyfill `process`. Unit tests pass (vitest has `process`) but the warning never fires in production. Use `import.meta.env?.DEV` instead, which Vite literal-replaces at build time.", getNodeText(ctx, node), "import.meta.env?.DEV === true", false);
+}
+function detectEmptyTheme(ctx, node) {
+	const callee = node.expression;
+	if (!ts.isPropertyAccessExpression(callee)) return;
+	if (!ts.isIdentifier(callee.name) || callee.name.text !== "theme") return;
+	if (node.arguments.length !== 1) return;
+	const arg = node.arguments[0];
+	if (!arg || !ts.isObjectLiteralExpression(arg)) return;
+	if (arg.properties.length !== 0) return;
+	pushDiag(ctx, node, "empty-theme", "`.theme({})` is a no-op chain. If the component needs no base theme, skip `.theme()` entirely rather than calling it with an empty object.", getNodeText(ctx, node), getNodeText(ctx, callee.expression), false);
+}
+const QUERY_OPTS_HOOKS = new Set([
+	"useQuery",
+	"useInfiniteQuery",
+	"useQueries",
+	"useSuspenseQuery"
+]);
+function detectQueryOptionsAsFunction(ctx, node) {
+	if (!ts.isIdentifier(node.expression)) return;
+	const hook = node.expression.text;
+	if (!QUERY_OPTS_HOOKS.has(hook)) return;
+	const arg0 = node.arguments[0];
+	if (!arg0 || !ts.isObjectLiteralExpression(arg0)) return;
+	const objText = getNodeText(ctx, arg0);
+	pushDiag(ctx, node, "query-options-as-function", `\`${hook}\` takes options as a FUNCTION so \`queryKey\` can read signals and refetch reactively — an object literal is captured once and never reacts. Wrap it: \`${hook}(() => (...))\`.`, getNodeText(ctx, node), `${hook}(() => (${objText}))`, false);
+}
+function detectRawEventListener(ctx, node) {
+	const callee = node.expression;
+	if (!ts.isPropertyAccessExpression(callee)) return;
+	if (!ts.isIdentifier(callee.name)) return;
+	const method = callee.name.text;
+	if (method !== "addEventListener" && method !== "removeEventListener") return;
+	const target = callee.expression;
+	const targetName = ts.isIdentifier(target) ? target.text : ts.isPropertyAccessExpression(target) && ts.isIdentifier(target.name) ? target.name.text : "";
+	if (!new Set([
+		"window",
+		"document",
+		"body",
+		"el",
+		"element",
+		"node",
+		"target"
+	]).has(targetName)) return;
+	if (method === "addEventListener") pushDiag(ctx, node, "raw-add-event-listener", "Raw `addEventListener` in a component / hook body bypasses Pyreon's lifecycle cleanup — listeners leak on unmount. Use `useEventListener` from `@pyreon/hooks` for auto-cleanup.", getNodeText(ctx, node), "useEventListener(target, event, handler)", false);
+	else pushDiag(ctx, node, "raw-remove-event-listener", "Raw `removeEventListener` is the symptom of manual listener management. Replace the paired `addEventListener` with `useEventListener` from `@pyreon/hooks` — it registers the cleanup automatically.", getNodeText(ctx, node), "useEventListener(target, event, handler) // cleanup is automatic", false);
+}
+function isCallTo(node, object, method) {
+	return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === object && ts.isIdentifier(node.expression.name) && node.expression.name.text === method;
+}
+function subtreeHas(node, predicate) {
+	let found = false;
+	function walk(n) {
+		if (found) return;
+		if (predicate(n)) {
+			found = true;
+			return;
+		}
+		ts.forEachChild(n, walk);
 	}
+	walk(node);
+	return found;
+}
+function detectDateMathRandomId(ctx, node) {
+	if (!subtreeHas(node, (n) => isCallTo(n, "Date", "now"))) return;
+	if (!subtreeHas(node, (n) => isCallTo(n, "Math", "random"))) return;
+	pushDiag(ctx, node, "date-math-random-id", "Combining `Date.now()` + `Math.random()` for unique IDs is collision-prone under rapid operations (paste, clone) — `Date.now()` returns the same value within a millisecond and `Math.random().toString(36).slice(2, 6)` has only ~1.67M combinations. Use a monotonic counter instead.", getNodeText(ctx, node), "let _counter = 0; const nextId = () => String(++_counter)", false);
+}
+function detectOnClickUndefined(ctx, node) {
+	if (!ts.isIdentifier(node.name)) return;
+	const attrName = node.name.text;
+	if (!attrName.startsWith("on") || attrName.length < 3) return;
+	if (!node.initializer || !ts.isJsxExpression(node.initializer)) return;
+	const expr = node.initializer.expression;
+	if (!expr) return;
+	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);
 }
-
-//#endregion
-//#region src/react-intercept.ts
 /**
-* React Pattern Interceptor — detects React/Vue patterns in code and provides
-* structured diagnostics with exact fix suggestions for AI-assisted migration.
-*
-* Two modes:
-*  - `detectReactPatterns(code)` — returns diagnostics only (non-destructive)
-*  - `migrateReactCode(code)` — applies auto-fixes and returns transformed code
+* 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.
 *
-* Designed for three consumers:
-*  1. Compiler pre-pass (warnings during build)
-*  2. CLI `pyreon doctor` (project-wide scanning)
-*  3. MCP server `migrate_react` / `validate` tools (AI agent integration)
-*/
-/** React import sources → Pyreon equivalents */
-const IMPORT_REWRITES = {
-	react: "@pyreon/core",
-	"react-dom": "@pyreon/runtime-dom",
-	"react-dom/client": "@pyreon/runtime-dom",
-	"react-dom/server": "@pyreon/runtime-server",
-	"react-router": "@pyreon/router",
-	"react-router-dom": "@pyreon/router"
-};
-/** React specifiers that map to specific Pyreon imports */
-const SPECIFIER_REWRITES = {
-	useState: {
-		name: "signal",
-		from: "@pyreon/reactivity"
-	},
-	useEffect: {
-		name: "effect",
-		from: "@pyreon/reactivity"
-	},
-	useLayoutEffect: {
-		name: "effect",
-		from: "@pyreon/reactivity"
-	},
-	useMemo: {
-		name: "computed",
-		from: "@pyreon/reactivity"
-	},
-	useReducer: {
-		name: "signal",
-		from: "@pyreon/reactivity"
-	},
-	useRef: {
-		name: "signal",
-		from: "@pyreon/reactivity"
-	},
-	createContext: {
-		name: "createContext",
-		from: "@pyreon/core"
-	},
-	useContext: {
-		name: "useContext",
-		from: "@pyreon/core"
-	},
-	Fragment: {
-		name: "Fragment",
-		from: "@pyreon/core"
-	},
-	Suspense: {
-		name: "Suspense",
-		from: "@pyreon/core"
-	},
-	lazy: {
-		name: "lazy",
-		from: "@pyreon/core"
-	},
-	memo: {
-		name: "",
-		from: ""
-	},
-	forwardRef: {
-		name: "",
-		from: ""
-	},
-	createRoot: {
-		name: "mount",
-		from: "@pyreon/runtime-dom"
-	},
-	hydrateRoot: {
-		name: "hydrateRoot",
-		from: "@pyreon/runtime-dom"
-	},
-	useNavigate: {
-		name: "useRouter",
-		from: "@pyreon/router"
-	},
-	useParams: {
-		name: "useRoute",
-		from: "@pyreon/router"
-	},
-	useLocation: {
-		name: "useRoute",
-		from: "@pyreon/router"
-	},
-	Link: {
-		name: "RouterLink",
-		from: "@pyreon/router"
-	},
-	NavLink: {
-		name: "RouterLink",
-		from: "@pyreon/router"
-	},
-	Outlet: {
-		name: "RouterView",
-		from: "@pyreon/router"
-	},
-	useSearchParams: {
-		name: "useSearchParams",
-		from: "@pyreon/router"
-	}
-};
-/** JSX attribute rewrites (React → standard HTML) */
-const JSX_ATTR_REWRITES = {
-	className: "class",
-	htmlFor: "for"
-};
-function detectGetNodeText(ctx, node) {
-	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
-}
-function detectDiag(ctx, node, diagCode, message, current, suggested, fixable) {
-	const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
-	ctx.diagnostics.push({
-		code: diagCode,
-		message,
-		line: line + 1,
-		column: character,
-		current: current.trim(),
-		suggested: suggested.trim(),
-		fixable
-	});
-}
-function detectImportDeclaration(ctx, node) {
-	if (!node.moduleSpecifier) return;
-	const source = node.moduleSpecifier.text;
-	const pyreonSource = IMPORT_REWRITES[source];
-	if (pyreonSource !== void 0) {
-		if (node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)) for (const spec of node.importClause.namedBindings.elements) ctx.reactImportedHooks.add(spec.name.text);
-		detectDiag(ctx, node, source.startsWith("react-router") ? "react-router-import" : source.startsWith("react-dom") ? "react-dom-import" : "react-import", `Import from '${source}' is a React package. Use Pyreon equivalent.`, detectGetNodeText(ctx, node), pyreonSource ? `import { ... } from "${pyreonSource}"` : "Remove this import — not needed in Pyreon", true);
-	}
-}
-function detectUseState(ctx, node) {
-	const parent = node.parent;
-	if (ts.isVariableDeclaration(parent) && parent.name && ts.isArrayBindingPattern(parent.name) && parent.name.elements.length >= 1) {
-		const firstEl = parent.name.elements[0];
-		const valueName = firstEl && ts.isBindingElement(firstEl) ? firstEl.name.text : "value";
-		const initArg = node.arguments[0] ? detectGetNodeText(ctx, node.arguments[0]) : "undefined";
-		detectDiag(ctx, node, "use-state", `useState is a React API. In Pyreon, use signal(). Read: ${valueName}(), Write: ${valueName}.set(x)`, detectGetNodeText(ctx, parent), `${valueName} = signal(${initArg})`, true);
-	} else detectDiag(ctx, node, "use-state", "useState is a React API. In Pyreon, use signal().", detectGetNodeText(ctx, node), "signal(initialValue)", true);
-}
-function callbackHasCleanup(callbackArg) {
-	if (!ts.isArrowFunction(callbackArg) && !ts.isFunctionExpression(callbackArg)) return false;
-	const body = callbackArg.body;
-	if (!ts.isBlock(body)) return false;
-	for (const stmt of body.statements) if (ts.isReturnStatement(stmt) && stmt.expression) return true;
-	return false;
-}
-function detectUseEffect(ctx, node) {
-	const hookName = node.expression.text;
-	const depsArg = node.arguments[1];
-	const callbackArg = node.arguments[0];
-	if (depsArg && ts.isArrayLiteralExpression(depsArg) && depsArg.elements.length === 0) {
-		const hasCleanup = callbackArg ? callbackHasCleanup(callbackArg) : false;
-		detectDiag(ctx, node, "use-effect-mount", `${hookName} with empty deps [] means "run once on mount". Use onMount() in Pyreon.`, detectGetNodeText(ctx, node), hasCleanup ? "onMount(() => {\n  // setup...\n  return () => { /* cleanup */ }\n})" : "onMount(() => {\n  // setup...\n})", true);
-	} else if (depsArg && ts.isArrayLiteralExpression(depsArg)) detectDiag(ctx, node, "use-effect-deps", `${hookName} with dependency array. In Pyreon, effect() auto-tracks dependencies — no array needed.`, detectGetNodeText(ctx, node), "effect(() => {\n  // reads are auto-tracked\n})", true);
-	else if (!depsArg) detectDiag(ctx, node, "use-effect-no-deps", `${hookName} with no dependency array. In Pyreon, use effect() — it auto-tracks signal reads.`, detectGetNodeText(ctx, node), "effect(() => {\n  // runs when accessed signals change\n})", true);
-}
-function detectUseMemo(ctx, node) {
-	const computeFn = node.arguments[0];
-	const computeText = computeFn ? detectGetNodeText(ctx, computeFn) : "() => value";
-	detectDiag(ctx, node, "use-memo", "useMemo is a React API. In Pyreon, use computed() — dependencies auto-tracked.", detectGetNodeText(ctx, node), `computed(${computeText})`, true);
-}
-function detectUseCallback(ctx, node) {
-	const callbackFn = node.arguments[0];
-	const callbackText = callbackFn ? detectGetNodeText(ctx, callbackFn) : "() => {}";
-	detectDiag(ctx, node, "use-callback", "useCallback is not needed in Pyreon. Components run once, so closures never go stale. Use a plain function.", detectGetNodeText(ctx, node), callbackText, true);
-}
-function detectUseRef(ctx, node) {
-	const arg = node.arguments[0];
-	if (arg && (arg.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(arg) && arg.text === "undefined")) detectDiag(ctx, node, "use-ref-dom", "useRef(null) for DOM refs. In Pyreon, use createRef() from @pyreon/core.", detectGetNodeText(ctx, node), "createRef()", true);
-	else {
-		const initText = arg ? detectGetNodeText(ctx, arg) : "undefined";
-		detectDiag(ctx, node, "use-ref-box", "useRef for mutable values. In Pyreon, use signal() — it works the same way but is reactive.", detectGetNodeText(ctx, node), `signal(${initText})`, true);
+* 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 detectUseReducer(ctx, node) {
-	detectDiag(ctx, node, "use-reducer", "useReducer is a React API. In Pyreon, use signal() with update() for reducer patterns.", detectGetNodeText(ctx, node), "const state = signal(initialState)\nconst dispatch = (action) => state.update(s => reducer(s, action))", false);
-}
-function isCallToReactDot(callee, methodName) {
-	return ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "React" && callee.name.text === methodName;
-}
-function detectMemoWrapper(ctx, node) {
-	const callee = node.expression;
-	if (ts.isIdentifier(callee) && callee.text === "memo" || isCallToReactDot(callee, "memo")) {
-		const inner = node.arguments[0];
-		const innerText = inner ? detectGetNodeText(ctx, inner) : "Component";
-		detectDiag(ctx, node, "memo-wrapper", "memo() is not needed in Pyreon. Components run once — only signals trigger updates, not re-renders.", detectGetNodeText(ctx, node), innerText, true);
+	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 detectForwardRef(ctx, node) {
+function detectSignalWriteAsCall(ctx, node) {
+	if (ctx.signalBindings.size === 0) return;
 	const callee = node.expression;
-	if (ts.isIdentifier(callee) && callee.text === "forwardRef" || isCallToReactDot(callee, "forwardRef")) detectDiag(ctx, node, "forward-ref", "forwardRef is not needed in Pyreon. Pass ref as a regular prop.", detectGetNodeText(ctx, node), "// Just pass ref as a prop:\nconst MyInput = (props) => <input ref={props.ref} />", true);
+	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);
 }
-function detectJsxAttributes(ctx, node) {
-	const attrName = node.name.text;
-	if (attrName in JSX_ATTR_REWRITES) {
-		const htmlAttr = JSX_ATTR_REWRITES[attrName];
-		detectDiag(ctx, node, attrName === "className" ? "class-name-prop" : "html-for-prop", `'${attrName}' is a React JSX attribute. Use '${htmlAttr}' in Pyreon (standard HTML).`, detectGetNodeText(ctx, node), detectGetNodeText(ctx, node).replace(attrName, htmlAttr), true);
-	}
-	if (attrName === "onChange") {
-		const jsxElement = findParentJsxElement(node);
-		if (jsxElement) {
-			const tagName = getJsxTagName$1(jsxElement);
-			if (tagName === "input" || tagName === "textarea" || tagName === "select") detectDiag(ctx, node, "on-change-input", `onChange on <${tagName}> fires on blur in Pyreon (native DOM behavior). For keypress-by-keypress updates, use onInput.`, detectGetNodeText(ctx, node), detectGetNodeText(ctx, node).replace("onChange", "onInput"), true);
-		}
+/**
+* `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 (attrName === "dangerouslySetInnerHTML") detectDiag(ctx, node, "dangerously-set-inner-html", "dangerouslySetInnerHTML is React-specific. Use innerHTML prop in Pyreon.", detectGetNodeText(ctx, node), "innerHTML={htmlString}", true);
-}
-function detectDotValueSignal(ctx, node) {
-	const varName = node.expression.text;
-	const parent = node.parent;
-	if (ts.isBinaryExpression(parent) && parent.left === node) detectDiag(ctx, node, "dot-value-signal", `'${varName}.value' looks like a Vue ref pattern. Pyreon signals are callable functions. Use ${varName}.set(x) to write.`, detectGetNodeText(ctx, parent), `${varName}.set(${detectGetNodeText(ctx, parent.right)})`, false);
+	if (ts.isBlock(stmt)) return stmt.statements.length === 1 && returnsNullStatement(stmt.statements[0]);
+	return false;
 }
-function detectArrayMapJsx(ctx, node) {
+/**
+* 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 (ts.isJsxExpression(parent)) {
-		const arrayExpr = detectGetNodeText(ctx, node.expression.expression);
-		const mapCallback = node.arguments[0];
-		const mapCallbackText = mapCallback ? detectGetNodeText(ctx, mapCallback) : "item => <li>{item}</li>";
-		detectDiag(ctx, node, "array-map-jsx", "Array.map() in JSX is not reactive in Pyreon. Use <For> for efficient keyed list rendering.", detectGetNodeText(ctx, node), `<For each={${arrayExpr}} by={item => item.id}>\n  {${mapCallbackText}}\n</For>`, false);
-	}
-}
-function isCallToHook(node, hookName) {
-	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === hookName;
-}
-function isCallToEffectHook(node) {
-	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (node.expression.text === "useEffect" || node.expression.text === "useLayoutEffect");
-}
-function isMapCallExpression(node) {
-	return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.name) && node.expression.name.text === "map";
-}
-function isDotValueAccess(node) {
-	return ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name) && node.name.text === "value" && ts.isIdentifier(node.expression);
-}
-function detectVisitNode(ctx, node) {
-	if (ts.isImportDeclaration(node)) detectImportDeclaration(ctx, node);
-	if (isCallToHook(node, "useState")) detectUseState(ctx, node);
-	if (isCallToEffectHook(node)) detectUseEffect(ctx, node);
-	if (isCallToHook(node, "useMemo")) detectUseMemo(ctx, node);
-	if (isCallToHook(node, "useCallback")) detectUseCallback(ctx, node);
-	if (isCallToHook(node, "useRef")) detectUseRef(ctx, node);
-	if (isCallToHook(node, "useReducer")) detectUseReducer(ctx, node);
-	if (ts.isCallExpression(node)) detectMemoWrapper(ctx, node);
-	if (ts.isCallExpression(node)) detectForwardRef(ctx, node);
-	if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name)) detectJsxAttributes(ctx, node);
-	if (isDotValueAccess(node)) detectDotValueSignal(ctx, node);
-	if (isMapCallExpression(node)) detectArrayMapJsx(ctx, node);
-}
-function detectVisit(ctx, node) {
-	ts.forEachChild(node, (child) => {
-		detectVisitNode(ctx, child);
-		detectVisit(ctx, child);
-	});
-}
-function detectReactPatterns(code, filename = "input.tsx") {
-	const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
-	const ctx = {
-		sf,
-		code,
-		diagnostics: [],
-		reactImportedHooks: /* @__PURE__ */ new Set()
-	};
-	detectVisit(ctx, sf);
-	return ctx.diagnostics;
-}
-function migrateAddImport(ctx, source, specifier) {
-	if (!source || !specifier) return;
-	let specs = ctx.pyreonImports.get(source);
-	if (!specs) {
-		specs = /* @__PURE__ */ new Set();
-		ctx.pyreonImports.set(source, specs);
-	}
-	specs.add(specifier);
-}
-function migrateReplace(ctx, node, text) {
-	ctx.replacements.push({
-		start: node.getStart(ctx.sf),
-		end: node.getEnd(),
-		text
-	});
-}
-function migrateGetNodeText(ctx, node) {
-	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
-}
-function migrateGetLine(ctx, node) {
-	return ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf)).line + 1;
+	if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) return /^[A-Z]/.test(parent.name.text);
+	return false;
 }
-function migrateImportDeclaration(ctx, node) {
-	if (!node.moduleSpecifier) return;
-	if (!(node.moduleSpecifier.text in IMPORT_REWRITES)) return;
-	if (node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)) for (const spec of node.importClause.namedBindings.elements) {
-		const rewrite = SPECIFIER_REWRITES[spec.name.text];
-		if (rewrite) {
-			if (rewrite.name) migrateAddImport(ctx, rewrite.from, rewrite.name);
-			ctx.specifierRewrites.set(spec, rewrite);
-		}
+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;
 	}
-	ctx.importsToRemove.add(node);
 }
-function migrateUseState(ctx, node) {
-	const parent = node.parent;
-	if (ts.isVariableDeclaration(parent) && parent.name && ts.isArrayBindingPattern(parent.name) && parent.name.elements.length >= 1) {
-		const firstEl = parent.name.elements[0];
-		const valueName = firstEl && ts.isBindingElement(firstEl) ? firstEl.name.text : "value";
-		const initArg = node.arguments[0] ? migrateGetNodeText(ctx, node.arguments[0]) : "undefined";
-		const declStart = parent.getStart(ctx.sf);
-		const declEnd = parent.getEnd();
-		ctx.replacements.push({
-			start: declStart,
-			end: declEnd,
-			text: `${valueName} = signal(${initArg})`
-		});
-		migrateAddImport(ctx, "@pyreon/reactivity", "signal");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: `useState → signal: ${valueName}`
-		});
-	}
+/**
+* `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);
 }
-function migrateUseEffect(ctx, node) {
-	const depsArg = node.arguments[1];
-	const callbackArg = node.arguments[0];
-	const hookName = node.expression.text;
-	if (depsArg && ts.isArrayLiteralExpression(depsArg) && depsArg.elements.length === 0 && callbackArg) {
-		migrateReplace(ctx, node, `onMount(${migrateGetNodeText(ctx, callbackArg)})`);
-		migrateAddImport(ctx, "@pyreon/core", "onMount");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: `${hookName}(fn, []) → onMount(fn)`
-		});
-	} else if (callbackArg) {
-		migrateReplace(ctx, node, `effect(${migrateGetNodeText(ctx, callbackArg)})`);
-		migrateAddImport(ctx, "@pyreon/reactivity", "effect");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: `${hookName} → effect (auto-tracks deps)`
-		});
+/**
+* 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;
 }
-function migrateUseMemo(ctx, node) {
-	const computeFn = node.arguments[0];
-	if (computeFn) {
-		migrateReplace(ctx, node, `computed(${migrateGetNodeText(ctx, computeFn)})`);
-		migrateAddImport(ctx, "@pyreon/reactivity", "computed");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: "useMemo → computed (auto-tracks deps)"
-		});
+/**
+* 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 migrateUseCallback(ctx, node) {
-	const callbackFn = node.arguments[0];
-	if (callbackFn) {
-		migrateReplace(ctx, node, migrateGetNodeText(ctx, callbackFn));
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: "useCallback → plain function (not needed in Pyreon)"
-		});
+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);
+		detectPropsDestructuredBody(ctx, node);
+		detectStaticReturnNullConditional(ctx, node);
 	}
-}
-function migrateUseRef(ctx, node) {
-	const arg = node.arguments[0];
-	if (arg && (arg.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(arg) && arg.text === "undefined") || !arg) {
-		migrateReplace(ctx, node, "createRef()");
-		migrateAddImport(ctx, "@pyreon/core", "createRef");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: "useRef(null) → createRef()"
-		});
-	} else {
-		migrateReplace(ctx, node, `signal(${migrateGetNodeText(ctx, arg)})`);
-		migrateAddImport(ctx, "@pyreon/reactivity", "signal");
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: "useRef(value) → signal(value)"
-		});
+	if (ts.isBinaryExpression(node)) {
+		detectProcessDevGate(ctx, node);
+		detectDateMathRandomId(ctx, node);
 	}
-}
-function migrateMemoWrapper(ctx, node) {
-	const callee = node.expression;
-	if ((ts.isIdentifier(callee) && callee.text === "memo" || isCallToReactDot(callee, "memo")) && node.arguments[0]) {
-		migrateReplace(ctx, node, migrateGetNodeText(ctx, node.arguments[0]));
-		ctx.changes.push({
-			type: "remove",
-			line: migrateGetLine(ctx, node),
-			description: "Removed memo() wrapper (not needed in Pyreon)"
-		});
+	if (ts.isTemplateExpression(node)) detectDateMathRandomId(ctx, node);
+	if (ts.isCallExpression(node)) {
+		detectEmptyTheme(ctx, node);
+		detectRawEventListener(ctx, node);
+		detectSignalWriteAsCall(ctx, node);
+		detectIslandNeverWithRegistry(ctx, node);
+		detectQueryOptionsAsFunction(ctx, node);
 	}
+	if (ts.isJsxAttribute(node)) detectOnClickUndefined(ctx, node);
+	if (ts.isAsExpression(node)) detectAsUnknownAsVNodeChild(ctx, node);
 }
-function migrateForwardRef(ctx, node) {
-	const callee = node.expression;
-	if ((ts.isIdentifier(callee) && callee.text === "forwardRef" || isCallToReactDot(callee, "forwardRef")) && node.arguments[0]) {
-		migrateReplace(ctx, node, migrateGetNodeText(ctx, node.arguments[0]));
-		ctx.changes.push({
-			type: "remove",
-			line: migrateGetLine(ctx, node),
-			description: "Removed forwardRef wrapper (pass ref as normal prop in Pyreon)"
-		});
-	}
+function visit(ctx, node) {
+	ts.forEachChild(node, (child) => {
+		visitNode(ctx, child);
+		visit(ctx, child);
+	});
 }
-function migrateJsxAttributes(ctx, node) {
-	const attrName = node.name.text;
-	if (attrName in JSX_ATTR_REWRITES) {
-		const htmlAttr = JSX_ATTR_REWRITES[attrName];
-		ctx.replacements.push({
-			start: node.name.getStart(ctx.sf),
-			end: node.name.getEnd(),
-			text: htmlAttr
-		});
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: `${attrName} → ${htmlAttr}`
-		});
+function detectPyreonPatterns(code, filename = "input.tsx") {
+	const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
+	const ctx = {
+		sf,
+		code,
+		diagnostics: [],
+		signalBindings: collectSignalBindings(sf),
+		neverIslandNames: collectNeverIslandNames(sf)
+	};
+	visit(ctx, sf);
+	ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
+	return ctx.diagnostics;
+}
+/** 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(?:const|let|var)\s+\{[^}]*\}\s*=\s*[A-Za-z_$]/.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) || /\b(?:useQuery|useInfiniteQuery|useQueries|useSuspenseQuery)\s*\(\s*\{/.test(code) || /\bisland\s*\(/.test(code) && /\bhydrate\s*:\s*['"]never['"]/.test(code);
+}
+
+//#endregion
+//#region src/reactivity-lens.ts
+/**
+* Reactivity Lens — surface the compiler's already-computed reactivity
+* analysis back to the author at the source.
+*
+* Pyreon's #1 silent footgun class: whether code is reactive is invisible at
+* the moment you write it. `const {x}=props` compiles fine, types fine,
+* renders once, and is dead. `<div>{x}</div>` where `x` isn't a signal bakes
+* once. The `@pyreon/compiler` ALREADY decides this per-expression (it has to,
+* for codegen) and then throws the analysis away. This module pipes it back.
+*
+* `analyzeReactivity()` is the single entry point. It returns a sorted list of
+* {@link ReactivityFinding}s built from TWO faithful sources, neither of which
+* is a fresh approximation:
+*
+*  1. **Compiler structural facts** — `TransformResult.reactivityLens`. Each
+*     span is a *record* of a codegen decision (`_bind`/`_bindText`/`_rp`/
+*     hoist/static-text). The positive "this is live" claim is the codegen
+*     branch itself, so it is correct by construction (drift-gated).
+*  2. **Footgun negatives** — the existing `detectPyreonPatterns` AST
+*     detectors (`props-destructured`, `signal-write-as-call`, …). Already
+*     shipped, already AST-based; the lens just unifies them under one
+*     editor-facing taxonomy.
+*
+* Absence of a finding is "not asserted", NEVER an implicit static claim —
+* see the asymmetric-precision commitment in `.claude/plans/reactivity-lens.md`.
+*
+* JS-backend only (Phase 1). The native Rust binary emits byte-identical
+* codegen (527 cross-backend equivalence tests), so the JS path is a sound
+* oracle for the analysis; Rust-path parity is Phase 3.
+*
+* @module
+*/
+function spanToFinding(s) {
+	return {
+		kind: s.kind,
+		line: s.line,
+		column: s.column,
+		endLine: s.endLine,
+		endColumn: s.endColumn,
+		detail: s.detail
+	};
+}
+/**
+* Analyze a source file's reactivity. Pure, side-effect-free, deterministic.
+*
+* @param code      Source text (`.tsx` / `.jsx` / `.ts`).
+* @param filename  Used only for parse-mode (`tsx` vs `jsx`) detection.
+* @param options   `knownSignals` is forwarded to the compiler so
+*                   cross-module imported signals are auto-call-aware.
+*
+* @example
+* const { findings } = analyzeReactivity(
+*   `function C(){ const {x}=props; return <div>{count()}</div> }`,
+* )
+* // → footgun(props-destructured) on `{x}`, reactive on `count()`
+*/
+function analyzeReactivity(code, filename = "input.tsx", options = {}) {
+	let spans = [];
+	try {
+		spans = transformJSX_JS(code, filename, {
+			reactivityLens: true,
+			...options.knownSignals ? { knownSignals: options.knownSignals } : {}
+		}).reactivityLens ?? [];
+	} catch {
+		spans = [];
 	}
-	if (attrName === "onChange") {
-		const jsxElement = findParentJsxElement(node);
-		if (jsxElement) {
-			const tagName = getJsxTagName$1(jsxElement);
-			if (tagName === "input" || tagName === "textarea" || tagName === "select") {
-				ctx.replacements.push({
-					start: node.name.getStart(ctx.sf),
-					end: node.name.getEnd(),
-					text: "onInput"
-				});
-				ctx.changes.push({
-					type: "replace",
-					line: migrateGetLine(ctx, node),
-					description: `onChange on <${tagName}> → onInput (native DOM events)`
-				});
-			}
-		}
+	const findings = spans.map(spanToFinding);
+	let footguns = [];
+	try {
+		footguns = detectPyreonPatterns(code, filename);
+	} catch {
+		footguns = [];
 	}
-	if (attrName === "dangerouslySetInnerHTML") migrateDangerouslySetInnerHTML(ctx, node);
-}
-function migrateDangerouslySetInnerHTML(ctx, node) {
-	if (!node.initializer || !ts.isJsxExpression(node.initializer) || !node.initializer.expression) return;
-	const expr = node.initializer.expression;
-	if (!ts.isObjectLiteralExpression(expr)) return;
-	const htmlProp = expr.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "__html");
-	if (htmlProp) {
-		migrateReplace(ctx, node, `innerHTML={${migrateGetNodeText(ctx, htmlProp.initializer)}}`);
-		ctx.changes.push({
-			type: "replace",
-			line: migrateGetLine(ctx, node),
-			description: "dangerouslySetInnerHTML → innerHTML"
+	for (const d of footguns) {
+		const firstLineLen = d.current.split("\n")[0]?.length ?? d.current.length;
+		findings.push({
+			kind: "footgun",
+			line: d.line,
+			column: d.column,
+			endLine: d.line,
+			endColumn: d.column + firstLineLen,
+			detail: d.message,
+			code: d.code,
+			fixable: d.fixable
 		});
 	}
+	findings.sort((a, b) => a.line - b.line || a.column - b.column);
+	return {
+		findings,
+		spans
+	};
 }
-function applyReplacements(code, ctx) {
-	for (const imp of ctx.importsToRemove) {
-		ctx.replacements.push({
-			start: imp.getStart(ctx.sf),
-			end: imp.getEnd(),
-			text: ""
-		});
-		ctx.changes.push({
-			type: "remove",
-			line: ctx.sf.getLineAndCharacterOfPosition(imp.getStart(ctx.sf)).line + 1,
-			description: "Removed React import"
-		});
+const KIND_BADGE = {
+	reactive: "◆ live",
+	"reactive-prop": "◆ live prop",
+	"reactive-attr": "◆ live attr",
+	"static-text": "○ baked once",
+	"hoisted-static": "○ hoisted static",
+	footgun: "⚠ footgun"
+};
+/**
+* Render an annotated source view for CLI / debugging — every analyzed line
+* followed by its reactivity findings. Not the production surface (that's the
+* LSP inlay hints); this is the spike's "can you see reactivity flow" probe
+* and a stable diff target for tests.
+*/
+function formatReactivityLens(code, result) {
+	const lines = code.split("\n");
+	const byLine = /* @__PURE__ */ new Map();
+	for (const f of result.findings) {
+		const arr = byLine.get(f.line) ?? [];
+		arr.push(f);
+		byLine.set(f.line, arr);
 	}
-	ctx.replacements.sort((a, b) => b.start - a.start);
-	const applied = /* @__PURE__ */ new Set();
-	const deduped = [];
-	for (const r of ctx.replacements) {
-		const key = `${r.start}:${r.end}`;
-		let overlaps = false;
-		for (const d of deduped) if (r.start < d.end && r.end > d.start) {
-			overlaps = true;
-			break;
+	const out = [];
+	for (let i = 0; i < lines.length; i++) {
+		const lineNo = i + 1;
+		out.push(`${String(lineNo).padStart(4)} | ${lines[i]}`);
+		const fs = byLine.get(lineNo);
+		if (fs) for (const f of fs) {
+			const pad = " ".repeat(7 + f.column);
+			const tag = f.code ? ` [${f.code}]` : "";
+			out.push(`${pad}^ ${KIND_BADGE[f.kind]}${tag} — ${f.detail}`);
 		}
-		if (!overlaps && !applied.has(key)) {
-			applied.add(key);
-			deduped.push(r);
+	}
+	return out.join("\n");
+}
+
+//#endregion
+//#region src/project-scanner.ts
+/**
+* Project scanner — extracts route, component, and island information from source files.
+*/
+function generateContext(cwd) {
+	const files = collectSourceFiles(cwd);
+	return {
+		framework: "pyreon",
+		version: readVersion(cwd),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		routes: extractRoutes(files, cwd),
+		components: extractComponents(files, cwd),
+		islands: extractIslands(files, cwd)
+	};
+}
+function collectSourceFiles(cwd) {
+	const results = [];
+	const extensions = new Set([
+		".tsx",
+		".jsx",
+		".ts",
+		".js"
+	]);
+	const ignoreDirs = new Set([
+		"node_modules",
+		"dist",
+		"lib",
+		".pyreon",
+		".git",
+		"build"
+	]);
+	function walk(dir) {
+		let entries;
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+			if (ignoreDirs.has(entry.name) && entry.isDirectory()) continue;
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) walk(fullPath);
+			else if (entry.isFile() && extensions.has(path.extname(entry.name))) results.push(fullPath);
 		}
 	}
-	deduped.sort((a, b) => a.start - b.start);
-	const parts = [];
-	let lastPos = 0;
-	for (const r of deduped) {
-		parts.push(code.slice(lastPos, r.start));
-		parts.push(r.text);
-		lastPos = r.end;
-	}
-	parts.push(code.slice(lastPos));
-	return parts.join("");
+	walk(cwd);
+	return results;
 }
-function insertPyreonImports(code, pyreonImports) {
-	if (pyreonImports.size === 0) return code;
-	const importLines = [];
-	const sorted = [...pyreonImports.entries()].sort(([a], [b]) => a.localeCompare(b));
-	for (const [source, specs] of sorted) {
-		const specList = [...specs].sort().join(", ");
-		importLines.push(`import { ${specList} } from "${source}"`);
+function extractRoutes(files, _cwd) {
+	const routes = [];
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
+		}
+		const routeArrayRe = /(?:createRouter\s*\(\s*\[|(?:const|let)\s+routes\s*(?::\s*RouteRecord\[\])?\s*=\s*\[)([\s\S]*?)\]/g;
+		let match;
+		for (match = routeArrayRe.exec(code); match; match = routeArrayRe.exec(code)) {
+			const block = match[1] ?? "";
+			const routeObjRe = /path\s*:\s*["']([^"']+)["']/g;
+			let routeMatch;
+			for (routeMatch = routeObjRe.exec(block); routeMatch; routeMatch = routeObjRe.exec(block)) {
+				const routePath = routeMatch[1] ?? "";
+				const surroundingStart = Math.max(0, routeMatch.index - 50);
+				const surroundingEnd = Math.min(block.length, routeMatch.index + 200);
+				const surrounding = block.slice(surroundingStart, surroundingEnd);
+				routes.push({
+					path: routePath,
+					name: surrounding.match(/name\s*:\s*["']([^"']+)["']/)?.[1],
+					hasLoader: /loader\s*:/.test(surrounding),
+					hasGuard: /beforeEnter\s*:|beforeLeave\s*:/.test(surrounding),
+					params: extractParams(routePath)
+				});
+			}
+		}
 	}
-	const importBlock = importLines.join("\n");
-	const lastImportEnd = findLastImportEnd(code);
-	if (lastImportEnd > 0) return `${code.slice(0, lastImportEnd)}\n${importBlock}${code.slice(lastImportEnd)}`;
-	return `${importBlock}\n\n${code}`;
-}
-function migrateVisitNode(ctx, node) {
-	if (ts.isImportDeclaration(node)) migrateImportDeclaration(ctx, node);
-	if (isCallToHook(node, "useState")) migrateUseState(ctx, node);
-	if (isCallToEffectHook(node)) migrateUseEffect(ctx, node);
-	if (isCallToHook(node, "useMemo")) migrateUseMemo(ctx, node);
-	if (isCallToHook(node, "useCallback")) migrateUseCallback(ctx, node);
-	if (isCallToHook(node, "useRef")) migrateUseRef(ctx, node);
-	if (ts.isCallExpression(node)) migrateMemoWrapper(ctx, node);
-	if (ts.isCallExpression(node)) migrateForwardRef(ctx, node);
-	if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name)) migrateJsxAttributes(ctx, node);
-}
-function migrateVisit(ctx, node) {
-	ts.forEachChild(node, (child) => {
-		migrateVisitNode(ctx, child);
-		migrateVisit(ctx, child);
-	});
-}
-function migrateReactCode(code, filename = "input.tsx") {
-	const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
-	const diagnostics = detectReactPatterns(code, filename);
-	const ctx = {
-		sf,
-		code,
-		replacements: [],
-		changes: [],
-		pyreonImports: /* @__PURE__ */ new Map(),
-		importsToRemove: /* @__PURE__ */ new Set(),
-		specifierRewrites: /* @__PURE__ */ new Map()
-	};
-	migrateVisit(ctx, sf);
-	let result = applyReplacements(code, ctx);
-	result = insertPyreonImports(result, ctx.pyreonImports);
-	result = result.replace(/\n{3,}/g, "\n\n");
-	return {
-		code: result,
-		diagnostics,
-		changes: ctx.changes
-	};
+	return routes;
 }
-function findParentJsxElement(node) {
-	let current = node.parent;
-	while (current) {
-		if (ts.isJsxOpeningElement(current) || ts.isJsxSelfClosingElement(current)) return current;
-		if (ts.isJsxElement(current)) return current.openingElement;
-		if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) return null;
-		current = current.parent;
+function extractComponents(files, cwd) {
+	const components = [];
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
+		}
+		const componentRe = /(?:export\s+)?(?:const|function)\s+([A-Z]\w*)\s*(?::\s*ComponentFn<[^>]+>\s*)?=?\s*\(?(?:\s*\{?\s*([^)]*?)\s*\}?\s*)?\)?\s*(?:=>|{)/g;
+		let match;
+		for (match = componentRe.exec(code); match; match = componentRe.exec(code)) {
+			const name = match[1] ?? "Unknown";
+			const props = (match[2] ?? "").split(/[,;]/).map((p) => p.trim().replace(/[{}]/g, "").trim().split(":")[0]?.split("=")[0]?.trim() ?? "").filter((p) => p && p !== "props");
+			const bodyStart = match.index + match[0].length;
+			const body = code.slice(bodyStart, Math.min(code.length, bodyStart + 2e3));
+			const signalNames = [];
+			const signalRe = /(?:const|let)\s+(\w+)\s*=\s*signal\s*[<(]/g;
+			let sigMatch;
+			for (sigMatch = signalRe.exec(body); sigMatch; sigMatch = signalRe.exec(body)) if (sigMatch[1]) signalNames.push(sigMatch[1]);
+			components.push({
+				name,
+				file: path.relative(cwd, file),
+				hasSignals: signalNames.length > 0,
+				signalNames,
+				props
+			});
+		}
 	}
-	return null;
+	return components;
 }
-function getJsxTagName$1(node) {
-	const tagName = node.tagName;
-	if (ts.isIdentifier(tagName)) return tagName.text;
-	return "";
+function extractIslands(files, cwd) {
+	const islands = [];
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
+		}
+		const islandRe = /island\s*\(\s*\(\)\s*=>\s*import\(.+?\)\s*,\s*\{[^}]*name\s*:\s*["']([^"']+)["'][^}]*?(?:hydrate\s*:\s*["']([^"']+)["'])?[^}]*\}/g;
+		let match;
+		for (match = islandRe.exec(code); match; match = islandRe.exec(code)) if (match[1]) islands.push({
+			name: match[1],
+			file: path.relative(cwd, file),
+			hydrate: match[2] ?? "load"
+		});
+	}
+	return islands;
 }
-function findLastImportEnd(code) {
-	const importRe = /^import\s.+$/gm;
-	let lastEnd = 0;
+function extractParams(routePath) {
+	const params = [];
+	const paramRe = /:(\w+)\??/g;
 	let match;
-	while (true) {
-		match = importRe.exec(code);
-		if (!match) break;
-		lastEnd = match.index + match[0].length;
-	}
-	return lastEnd;
+	for (match = paramRe.exec(routePath); match; match = paramRe.exec(routePath)) if (match[1]) params.push(match[1]);
+	return params;
 }
-/** Fast regex check — returns true if code likely contains React patterns worth analyzing */
-function hasReactPatterns(code) {
-	return /\bfrom\s+['"]react/.test(code) || /\bfrom\s+['"]react-dom/.test(code) || /\bfrom\s+['"]react-router/.test(code) || /\buseState\s*[<(]/.test(code) || /\buseEffect\s*\(/.test(code) || /\buseMemo\s*\(/.test(code) || /\buseCallback\s*\(/.test(code) || /\buseRef\s*[<(]/.test(code) || /\buseReducer\s*[<(]/.test(code) || /\bReact\.memo\b/.test(code) || /\bforwardRef\s*[<(]/.test(code) || /\bclassName[=\s]/.test(code) || /\bhtmlFor[=\s]/.test(code) || /\.value\s*=/.test(code);
+function readVersion(cwd) {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
+		const deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+		for (const [name, ver] of Object.entries(deps)) if (name.startsWith("@pyreon/") && typeof ver === "string") return ver.replace(/^[\^~]/, "");
+		return pkg.version || "unknown";
+	} catch {
+		return "unknown";
+	}
 }
-const ERROR_PATTERNS = [
-	{
-		pattern: /Cannot read properties of undefined \(reading '(set|update|peek|subscribe)'\)/,
-		diagnose: (m) => ({
-			cause: `Calling .${m[1]}() on undefined. The signal variable is likely out of scope, misspelled, or not yet initialized.`,
-			fix: "Check that the signal is defined and in scope. Signals must be created with signal() before use.",
-			fixCode: `const mySignal = signal(initialValue)\nmySignal.${m[1]}(newValue)`
-		})
+
+//#endregion
+//#region src/react-intercept.ts
+/**
+* React Pattern Interceptor — detects React/Vue patterns in code and provides
+* structured diagnostics with exact fix suggestions for AI-assisted migration.
+*
+* Two modes:
+*  - `detectReactPatterns(code)` — returns diagnostics only (non-destructive)
+*  - `migrateReactCode(code)` — applies auto-fixes and returns transformed code
+*
+* Designed for three consumers:
+*  1. Compiler pre-pass (warnings during build)
+*  2. CLI `pyreon doctor` (project-wide scanning)
+*  3. MCP server `migrate_react` / `validate` tools (AI agent integration)
+*/
+/** React import sources → Pyreon equivalents */
+const IMPORT_REWRITES = {
+	react: "@pyreon/core",
+	"react-dom": "@pyreon/runtime-dom",
+	"react-dom/client": "@pyreon/runtime-dom",
+	"react-dom/server": "@pyreon/runtime-server",
+	"react-router": "@pyreon/router",
+	"react-router-dom": "@pyreon/router"
+};
+/** React specifiers that map to specific Pyreon imports */
+const SPECIFIER_REWRITES = {
+	useState: {
+		name: "signal",
+		from: "@pyreon/reactivity"
+	},
+	useEffect: {
+		name: "effect",
+		from: "@pyreon/reactivity"
+	},
+	useLayoutEffect: {
+		name: "effect",
+		from: "@pyreon/reactivity"
+	},
+	useMemo: {
+		name: "computed",
+		from: "@pyreon/reactivity"
+	},
+	useReducer: {
+		name: "signal",
+		from: "@pyreon/reactivity"
+	},
+	useRef: {
+		name: "signal",
+		from: "@pyreon/reactivity"
+	},
+	createContext: {
+		name: "createContext",
+		from: "@pyreon/core"
+	},
+	useContext: {
+		name: "useContext",
+		from: "@pyreon/core"
+	},
+	Fragment: {
+		name: "Fragment",
+		from: "@pyreon/core"
 	},
-	{
-		pattern: /(\w+) is not a function/,
-		diagnose: (m) => ({
-			cause: `'${m[1]}' is not callable. If this is a signal, you need to call it: ${m[1]}()`,
-			fix: "Pyreon signals are callable functions. Read: signal(), Write: signal.set(value)",
-			fixCode: `// Read value:\nconst value = ${m[1]}()\n// Set value:\n${m[1]}.set(newValue)`
-		})
+	Suspense: {
+		name: "Suspense",
+		from: "@pyreon/core"
 	},
-	{
-		pattern: /Cannot find module '(@pyreon\/\w[\w-]*)'/,
-		diagnose: (m) => ({
-			cause: `Package ${m[1]} is not installed.`,
-			fix: `Run: bun add ${m[1]}`,
-			fixCode: `bun add ${m[1]}`
-		})
+	lazy: {
+		name: "lazy",
+		from: "@pyreon/core"
 	},
-	{
-		pattern: /Cannot find module 'react'/,
-		diagnose: () => ({
-			cause: "Importing from 'react' in a Pyreon project.",
-			fix: "Replace React imports with Pyreon equivalents.",
-			fixCode: "// Instead of:\nimport { useState } from \"react\"\n// Use:\nimport { signal } from \"@pyreon/reactivity\""
-		})
+	memo: {
+		name: "",
+		from: ""
 	},
-	{
-		pattern: /Property '(\w+)' does not exist on type 'Signal<\w+>'/,
-		diagnose: (m) => ({
-			cause: `Accessing .${m[1]} on a signal. Pyreon signals don't have a .${m[1]} property.`,
-			fix: m[1] === "value" ? "Pyreon signals are callable functions, not .value getters. Call signal() to read, signal.set() to write." : `Signals have these methods: .set(), .update(), .peek(), .subscribe(). '${m[1]}' is not one of them.`,
-			fixCode: m[1] === "value" ? "// Read: mySignal()\n// Write: mySignal.set(newValue)" : void 0
-		})
+	forwardRef: {
+		name: "",
+		from: ""
 	},
-	{
-		pattern: /Type '(\w+)' is not assignable to type 'VNode'/,
-		diagnose: (m) => ({
-			cause: `Component returned ${m[1]} instead of VNode. Components must return JSX, null, or a string.`,
-			fix: "Make sure your component returns a JSX element, null, or a string.",
-			fixCode: "const MyComponent = (props) => {\n  return <div>{props.children}</div>\n}"
-		})
+	createRoot: {
+		name: "mount",
+		from: "@pyreon/runtime-dom"
 	},
-	{
-		pattern: /onMount callback must return/,
-		diagnose: () => ({
-			cause: "onMount expects a callback that optionally returns a CleanupFn.",
-			fix: "Return a cleanup function, or return nothing.",
-			fixCode: "onMount(() => {\n  // setup code\n})"
-		})
+	hydrateRoot: {
+		name: "hydrateRoot",
+		from: "@pyreon/runtime-dom"
 	},
-	{
-		pattern: /Expected 'by' prop on <For>/,
-		diagnose: () => ({
-			cause: "<For> requires a 'by' prop for efficient keyed reconciliation.",
-			fix: "Add a by prop that returns a unique key for each item.",
-			fixCode: "<For each={items()} by={item => item.id}>\n  {item => <li>{item.name}</li>}\n</For>"
-		})
+	useNavigate: {
+		name: "useRouter",
+		from: "@pyreon/router"
 	},
-	{
-		pattern: /useHook.*outside.*component/i,
-		diagnose: () => ({
-			cause: "Hook called outside a component function. Pyreon hooks must be called during component setup.",
-			fix: "Move the hook call inside a component function body."
-		})
+	useParams: {
+		name: "useRoute",
+		from: "@pyreon/router"
 	},
-	{
-		pattern: /Hydration mismatch/,
-		diagnose: () => ({
-			cause: "Server-rendered HTML doesn't match client-rendered output.",
-			fix: "Ensure SSR and client render the same initial content. Check for browser-only APIs (window, document) in SSR code.",
-			related: "Use typeof window !== 'undefined' checks or onMount() for client-only code."
-		})
-	}
-];
-/** Diagnose an error message and return structured fix information */
-function diagnoseError(error) {
-	for (const { pattern, diagnose } of ERROR_PATTERNS) {
-		const match = error.match(pattern);
-		if (match) return diagnose(match);
+	useLocation: {
+		name: "useRoute",
+		from: "@pyreon/router"
+	},
+	Link: {
+		name: "RouterLink",
+		from: "@pyreon/router"
+	},
+	NavLink: {
+		name: "RouterLink",
+		from: "@pyreon/router"
+	},
+	Outlet: {
+		name: "RouterView",
+		from: "@pyreon/router"
+	},
+	useSearchParams: {
+		name: "useSearchParams",
+		from: "@pyreon/router"
 	}
-	return null;
-}
-
-//#endregion
-//#region src/pyreon-intercept.ts
+};
+/** JSX attribute rewrites (React → standard HTML) */
+const JSX_ATTR_REWRITES = {
+	className: "class",
+	htmlFor: "for"
+};
 /**
-* Pyreon Pattern Interceptor — detects Pyreon-specific anti-patterns in
-* code that has ALREADY committed to the framework (imports are Pyreon,
-* not React). Complements `react-intercept.ts` — the React detector
-* catches "coming from React" mistakes; this one catches "using Pyreon
-* wrong" mistakes.
-*
-* Catalog of detected patterns (grounded in `.claude/rules/anti-patterns.md`):
-*
-*  - `for-missing-by` — `<For each={...}>` without a `by` prop
-*  - `for-with-key`   — `<For key={...}>` (JSX reserves `key`; the keying
-*                       prop is `by` in Pyreon)
-*  - `props-destructured` — `({ foo }: Props) => <JSX />` destructures at
-*                       the component signature; reading is captured once
-*                       and loses reactivity. Access `props.foo` instead
-*                       or use `splitProps(props, [...])`.
-*  - `process-dev-gate` — `typeof process !== 'undefined' &&
-*                       process.env.NODE_ENV !== 'production'` is dead
-*                       code in real Vite browser bundles. Use
-*                       `import.meta.env?.DEV` instead.
-*  - `empty-theme`    — `.theme({})` chain is a no-op; remove it.
-*  - `raw-add-event-listener` — raw `addEventListener(...)` in a component
-*                       or hook body. Use `useEventListener(...)` from
-*                       `@pyreon/hooks` for auto-cleanup.
-*  - `raw-remove-event-listener` — same, for removeEventListener.
-*  - `date-math-random-id` — `Date.now() + Math.random()` / template-concat
-*                       variants. Under rapid operations (paste, clone)
-*                       collision probability is non-trivial. Use a
-*                       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
-*  - `hasPyreonPatterns(code)`   — fast regex pre-filter
-*
-* ## fixable: false (invariant)
-*
-* Every Pyreon diagnostic reports `fixable: false` — no exceptions.
-* The `migrate_react` MCP tool only knows React mappings, so claiming
-* a Pyreon code is auto-fixable would mislead a consumer who wires
-* their UX off the flag and finds nothing applies the fix. Flip to
-* `true` ONLY when a companion `migrate_pyreon` tool ships in a
-* subsequent PR. The invariant is locked in
-* `tests/pyreon-intercept.test.ts` under "fixable contract".
-*
-* Designed for three consumers:
-*  1. Compiler pre-pass warnings during build
-*  2. CLI `pyreon doctor`
-*  3. MCP server `validate` tool
+* Collects every identifier bound to a signal factory call. Mirrors
+* `pyreon-intercept.ts:collectSignalBindings` but also recognises the
+* `useSignal` / `createSignal` aliases (Solid / hook-style) so the React
+* detector — which runs on cross-framework migration input — doesn't miss a
+* genuine `mySignal.value = x` written by someone coming from Solid/Vue.
 */
-function getNodeText(ctx, node) {
+function collectDetectSignalBindings(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" || callee.text === "useSignal" || callee.text === "createSignal";
+	}
+	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 detectGetNodeText(ctx, node) {
 	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
 }
-function pushDiag(ctx, node, code, message, current, suggested, fixable) {
-	const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
-	ctx.diagnostics.push({
-		code,
-		message,
-		line: line + 1,
-		column: character,
-		current: current.trim(),
-		suggested: suggested.trim(),
-		fixable
-	});
+function detectDiag(ctx, node, diagCode, message, current, suggested, fixable) {
+	const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
+	ctx.diagnostics.push({
+		code: diagCode,
+		message,
+		line: line + 1,
+		column: character,
+		current: current.trim(),
+		suggested: suggested.trim(),
+		fixable
+	});
+}
+function detectImportDeclaration(ctx, node) {
+	if (!node.moduleSpecifier) return;
+	const source = node.moduleSpecifier.text;
+	const pyreonSource = IMPORT_REWRITES[source];
+	if (pyreonSource !== void 0) {
+		if (node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)) for (const spec of node.importClause.namedBindings.elements) ctx.reactImportedHooks.add(spec.name.text);
+		detectDiag(ctx, node, source.startsWith("react-router") ? "react-router-import" : source.startsWith("react-dom") ? "react-dom-import" : "react-import", `Import from '${source}' is a React package. Use Pyreon equivalent.`, detectGetNodeText(ctx, node), pyreonSource ? `import { ... } from "${pyreonSource}"` : "Remove this import — not needed in Pyreon", true);
+	}
+}
+function detectUseState(ctx, node) {
+	const parent = node.parent;
+	if (ts.isVariableDeclaration(parent) && parent.name && ts.isArrayBindingPattern(parent.name) && parent.name.elements.length >= 1) {
+		const firstEl = parent.name.elements[0];
+		const valueName = firstEl && ts.isBindingElement(firstEl) ? firstEl.name.text : "value";
+		const initArg = node.arguments[0] ? detectGetNodeText(ctx, node.arguments[0]) : "undefined";
+		detectDiag(ctx, node, "use-state", `useState is a React API. In Pyreon, use signal(). Read: ${valueName}(), Write: ${valueName}.set(x)`, detectGetNodeText(ctx, parent), `${valueName} = signal(${initArg})`, true);
+	} else detectDiag(ctx, node, "use-state", "useState is a React API. In Pyreon, use signal().", detectGetNodeText(ctx, node), "signal(initialValue)", true);
+}
+function callbackHasCleanup(callbackArg) {
+	if (!ts.isArrowFunction(callbackArg) && !ts.isFunctionExpression(callbackArg)) return false;
+	const body = callbackArg.body;
+	if (!ts.isBlock(body)) return false;
+	for (const stmt of body.statements) if (ts.isReturnStatement(stmt) && stmt.expression) return true;
+	return false;
+}
+function detectUseEffect(ctx, node) {
+	const hookName = node.expression.text;
+	const depsArg = node.arguments[1];
+	const callbackArg = node.arguments[0];
+	if (depsArg && ts.isArrayLiteralExpression(depsArg) && depsArg.elements.length === 0) {
+		const hasCleanup = callbackArg ? callbackHasCleanup(callbackArg) : false;
+		detectDiag(ctx, node, "use-effect-mount", `${hookName} with empty deps [] means "run once on mount". Use onMount() in Pyreon.`, detectGetNodeText(ctx, node), hasCleanup ? "onMount(() => {\n  // setup...\n  return () => { /* cleanup */ }\n})" : "onMount(() => {\n  // setup...\n})", true);
+	} else if (depsArg && ts.isArrayLiteralExpression(depsArg)) detectDiag(ctx, node, "use-effect-deps", `${hookName} with dependency array. In Pyreon, effect() auto-tracks dependencies — no array needed.`, detectGetNodeText(ctx, node), "effect(() => {\n  // reads are auto-tracked\n})", true);
+	else if (!depsArg) detectDiag(ctx, node, "use-effect-no-deps", `${hookName} with no dependency array. In Pyreon, use effect() — it auto-tracks signal reads.`, detectGetNodeText(ctx, node), "effect(() => {\n  // runs when accessed signals change\n})", true);
+}
+function detectUseMemo(ctx, node) {
+	const computeFn = node.arguments[0];
+	const computeText = computeFn ? detectGetNodeText(ctx, computeFn) : "() => value";
+	detectDiag(ctx, node, "use-memo", "useMemo is a React API. In Pyreon, use computed() — dependencies auto-tracked.", detectGetNodeText(ctx, node), `computed(${computeText})`, true);
 }
-function getJsxTagName(node) {
-	const t = node.tagName;
-	if (ts.isIdentifier(t)) return t.text;
-	return "";
+function detectUseCallback(ctx, node) {
+	const callbackFn = node.arguments[0];
+	const callbackText = callbackFn ? detectGetNodeText(ctx, callbackFn) : "() => {}";
+	detectDiag(ctx, node, "use-callback", "useCallback is not needed in Pyreon. Components run once, so closures never go stale. Use a plain function.", detectGetNodeText(ctx, node), callbackText, true);
 }
-function findJsxAttribute(node, name) {
-	for (const attr of node.attributes.properties) if (ts.isJsxAttribute(attr) && ts.isIdentifier(attr.name) && attr.name.text === name) return attr;
+function detectUseRef(ctx, node) {
+	const arg = node.arguments[0];
+	if (arg && (arg.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(arg) && arg.text === "undefined")) detectDiag(ctx, node, "use-ref-dom", "useRef(null) for DOM refs. In Pyreon, use createRef() from @pyreon/core.", detectGetNodeText(ctx, node), "createRef()", true);
+	else {
+		const initText = arg ? detectGetNodeText(ctx, arg) : "undefined";
+		detectDiag(ctx, node, "use-ref-box", "useRef for mutable values. In Pyreon, use signal() — it works the same way but is reactive.", detectGetNodeText(ctx, node), `signal(${initText})`, true);
+	}
 }
-function detectForKeying(ctx, node) {
-	if (getJsxTagName(node) !== "For") return;
-	const keyAttr = findJsxAttribute(node, "key");
-	if (keyAttr) pushDiag(ctx, keyAttr, "for-with-key", "`key` on <For> is reserved by JSX for VNode reconciliation and is extracted before the prop reaches the runtime. In Pyreon, use `by` for list identity.", getNodeText(ctx, keyAttr), getNodeText(ctx, keyAttr).replace(/^key\b/, "by"), false);
-	const eachAttr = findJsxAttribute(node, "each");
-	const byAttr = findJsxAttribute(node, "by");
-	if (eachAttr && !byAttr && !keyAttr) pushDiag(ctx, node, "for-missing-by", "<For each={...}> requires a `by` prop so the keyed reconciler can preserve item identity across reorders. Without `by`, every update remounts the full list.", getNodeText(ctx, node), "<For each={items} by={(item) => item.id}>", false);
+function detectUseReducer(ctx, node) {
+	detectDiag(ctx, node, "use-reducer", "useReducer is a React API. In Pyreon, use signal() with update() for reducer patterns.", detectGetNodeText(ctx, node), "const state = signal(initialState)\nconst dispatch = (action) => state.update(s => reducer(s, action))", false);
 }
-function containsJsx(node) {
-	let found = false;
-	function walk(n) {
-		if (found) return;
-		if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n) || ts.isJsxOpeningElement(n)) {
-			found = true;
-			return;
+function isCallToReactDot(callee, methodName) {
+	return ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "React" && callee.name.text === methodName;
+}
+function detectMemoWrapper(ctx, node) {
+	const callee = node.expression;
+	if (ts.isIdentifier(callee) && callee.text === "memo" || isCallToReactDot(callee, "memo")) {
+		const inner = node.arguments[0];
+		const innerText = inner ? detectGetNodeText(ctx, inner) : "Component";
+		detectDiag(ctx, node, "memo-wrapper", "memo() is not needed in Pyreon. Components run once — only signals trigger updates, not re-renders.", detectGetNodeText(ctx, node), innerText, true);
+	}
+}
+function detectForwardRef(ctx, node) {
+	const callee = node.expression;
+	if (ts.isIdentifier(callee) && callee.text === "forwardRef" || isCallToReactDot(callee, "forwardRef")) detectDiag(ctx, node, "forward-ref", "forwardRef is not needed in Pyreon. Pass ref as a regular prop.", detectGetNodeText(ctx, node), "// Just pass ref as a prop:\nconst MyInput = (props) => <input ref={props.ref} />", true);
+}
+function detectJsxAttributes(ctx, node) {
+	const attrName = node.name.text;
+	if (attrName in JSX_ATTR_REWRITES) {
+		const htmlAttr = JSX_ATTR_REWRITES[attrName];
+		detectDiag(ctx, node, attrName === "className" ? "class-name-prop" : "html-for-prop", `'${attrName}' is a React JSX attribute. Use '${htmlAttr}' in Pyreon (standard HTML).`, detectGetNodeText(ctx, node), detectGetNodeText(ctx, node).replace(attrName, htmlAttr), true);
+	}
+	if (attrName === "onChange") {
+		const jsxElement = findParentJsxElement(node);
+		if (jsxElement) {
+			const tagName = getJsxTagName(jsxElement);
+			if (tagName === "input" || tagName === "textarea" || tagName === "select") detectDiag(ctx, node, "on-change-input", `onChange on <${tagName}> fires on blur in Pyreon (native DOM behavior). For keypress-by-keypress updates, use onInput.`, detectGetNodeText(ctx, node), detectGetNodeText(ctx, node).replace("onChange", "onInput"), true);
 		}
-		ts.forEachChild(n, walk);
 	}
-	ts.forEachChild(node, walk);
-	if (!found) {
-		if (ts.isArrowFunction(node) && !ts.isBlock(node.body) && (ts.isJsxElement(node.body) || ts.isJsxSelfClosingElement(node.body) || ts.isJsxFragment(node.body))) found = true;
+	if (attrName === "dangerouslySetInnerHTML") detectDiag(ctx, node, "dangerously-set-inner-html", "dangerouslySetInnerHTML is React-specific. Use innerHTML prop in Pyreon.", detectGetNodeText(ctx, node), "innerHTML={htmlString}", true);
+}
+function detectDotValueSignal(ctx, node) {
+	const varName = node.expression.text;
+	if (!ctx.signalBindings.has(varName)) return;
+	const parent = node.parent;
+	if (ts.isBinaryExpression(parent) && parent.left === node) detectDiag(ctx, node, "dot-value-signal", `'${varName}.value' looks like a Vue ref pattern. Pyreon signals are callable functions. Use ${varName}.set(x) to write.`, detectGetNodeText(ctx, parent), `${varName}.set(${detectGetNodeText(ctx, parent.right)})`, false);
+}
+function detectArrayMapJsx(ctx, node) {
+	const parent = node.parent;
+	if (ts.isJsxExpression(parent)) {
+		const arrayExpr = detectGetNodeText(ctx, node.expression.expression);
+		const mapCallback = node.arguments[0];
+		const mapCallbackText = mapCallback ? detectGetNodeText(ctx, mapCallback) : "item => <li>{item}</li>";
+		detectDiag(ctx, node, "array-map-jsx", "Array.map() in JSX is not reactive in Pyreon. Use <For> for efficient keyed list rendering.", detectGetNodeText(ctx, node), `<For each={${arrayExpr}} by={item => item.id}>\n  {${mapCallbackText}}\n</For>`, false);
 	}
-	return found;
 }
-function detectPropsDestructured(ctx, node) {
-	if (!node.parameters.length) return;
-	const first = node.parameters[0];
-	if (!first || !ts.isObjectBindingPattern(first.name)) return;
-	if (first.name.elements.length === 0) return;
-	if (!containsJsx(node)) return;
-	pushDiag(ctx, first, "props-destructured", "Destructuring props at the component signature captures the values ONCE during setup — subsequent signal writes in the parent do not update the destructured locals. Access `props.x` directly, or use `splitProps(props, [...])` to carve out a group while preserving reactivity.", getNodeText(ctx, first), "(props: Props) => /* read props.x directly */", false);
+function isCallToHook(node, hookName) {
+	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === hookName;
 }
-function isTypeofProcess(node) {
-	if (!ts.isBinaryExpression(node)) return false;
-	if (node.operatorToken.kind !== ts.SyntaxKind.ExclamationEqualsEqualsToken) return false;
-	if (!ts.isTypeOfExpression(node.left)) return false;
-	if (!ts.isIdentifier(node.left.expression) || node.left.expression.text !== "process") return false;
-	return ts.isStringLiteral(node.right) && node.right.text === "undefined";
+function isCallToEffectHook(node) {
+	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (node.expression.text === "useEffect" || node.expression.text === "useLayoutEffect");
 }
-function isProcessNodeEnvProdGuard(node) {
-	if (!ts.isBinaryExpression(node)) return false;
-	if (node.operatorToken.kind !== ts.SyntaxKind.ExclamationEqualsEqualsToken) return false;
-	const left = node.left;
-	if (!ts.isPropertyAccessExpression(left)) return false;
-	if (!ts.isIdentifier(left.name) || left.name.text !== "NODE_ENV") return false;
-	if (!ts.isPropertyAccessExpression(left.expression)) return false;
-	if (!ts.isIdentifier(left.expression.name) || left.expression.name.text !== "env") return false;
-	if (!ts.isIdentifier(left.expression.expression)) return false;
-	if (left.expression.expression.text !== "process") return false;
-	return ts.isStringLiteral(node.right) && node.right.text === "production";
+function isMapCallExpression(node) {
+	return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.name) && node.expression.name.text === "map";
 }
-function detectProcessDevGate(ctx, node) {
-	if (node.operatorToken.kind !== ts.SyntaxKind.AmpersandAmpersandToken) return;
-	if (!(isTypeofProcess(node.left) && isProcessNodeEnvProdGuard(node.right) || isTypeofProcess(node.right) && isProcessNodeEnvProdGuard(node.left))) return;
-	pushDiag(ctx, node, "process-dev-gate", "The `typeof process !== \"undefined\" && process.env.NODE_ENV !== \"production\"` gate is DEAD CODE in real Vite browser bundles — Vite does not polyfill `process`. Unit tests pass (vitest has `process`) but the warning never fires in production. Use `import.meta.env?.DEV` instead, which Vite literal-replaces at build time.", getNodeText(ctx, node), "import.meta.env?.DEV === true", false);
+function isDotValueAccess(node) {
+	return ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name) && node.name.text === "value" && ts.isIdentifier(node.expression);
 }
-function detectEmptyTheme(ctx, node) {
-	const callee = node.expression;
-	if (!ts.isPropertyAccessExpression(callee)) return;
-	if (!ts.isIdentifier(callee.name) || callee.name.text !== "theme") return;
-	if (node.arguments.length !== 1) return;
-	const arg = node.arguments[0];
-	if (!arg || !ts.isObjectLiteralExpression(arg)) return;
-	if (arg.properties.length !== 0) return;
-	pushDiag(ctx, node, "empty-theme", "`.theme({})` is a no-op chain. If the component needs no base theme, skip `.theme()` entirely rather than calling it with an empty object.", getNodeText(ctx, node), getNodeText(ctx, callee.expression), false);
+function detectVisitNode(ctx, node) {
+	if (ts.isImportDeclaration(node)) detectImportDeclaration(ctx, node);
+	if (isCallToHook(node, "useState")) detectUseState(ctx, node);
+	if (isCallToEffectHook(node)) detectUseEffect(ctx, node);
+	if (isCallToHook(node, "useMemo")) detectUseMemo(ctx, node);
+	if (isCallToHook(node, "useCallback")) detectUseCallback(ctx, node);
+	if (isCallToHook(node, "useRef")) detectUseRef(ctx, node);
+	if (isCallToHook(node, "useReducer")) detectUseReducer(ctx, node);
+	if (ts.isCallExpression(node)) detectMemoWrapper(ctx, node);
+	if (ts.isCallExpression(node)) detectForwardRef(ctx, node);
+	if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name)) detectJsxAttributes(ctx, node);
+	if (isDotValueAccess(node)) detectDotValueSignal(ctx, node);
+	if (isMapCallExpression(node)) detectArrayMapJsx(ctx, node);
 }
-function detectRawEventListener(ctx, node) {
-	const callee = node.expression;
-	if (!ts.isPropertyAccessExpression(callee)) return;
-	if (!ts.isIdentifier(callee.name)) return;
-	const method = callee.name.text;
-	if (method !== "addEventListener" && method !== "removeEventListener") return;
-	const target = callee.expression;
-	const targetName = ts.isIdentifier(target) ? target.text : ts.isPropertyAccessExpression(target) && ts.isIdentifier(target.name) ? target.name.text : "";
-	if (!new Set([
-		"window",
-		"document",
-		"body",
-		"el",
-		"element",
-		"node",
-		"target"
-	]).has(targetName)) return;
-	if (method === "addEventListener") pushDiag(ctx, node, "raw-add-event-listener", "Raw `addEventListener` in a component / hook body bypasses Pyreon's lifecycle cleanup — listeners leak on unmount. Use `useEventListener` from `@pyreon/hooks` for auto-cleanup.", getNodeText(ctx, node), "useEventListener(target, event, handler)", false);
-	else pushDiag(ctx, node, "raw-remove-event-listener", "Raw `removeEventListener` is the symptom of manual listener management. Replace the paired `addEventListener` with `useEventListener` from `@pyreon/hooks` — it registers the cleanup automatically.", getNodeText(ctx, node), "useEventListener(target, event, handler) // cleanup is automatic", false);
+function detectVisit(ctx, node) {
+	ts.forEachChild(node, (child) => {
+		detectVisitNode(ctx, child);
+		detectVisit(ctx, child);
+	});
 }
-function isCallTo(node, object, method) {
-	return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === object && ts.isIdentifier(node.expression.name) && node.expression.name.text === method;
+function detectReactPatterns(code, filename = "input.tsx") {
+	const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
+	const ctx = {
+		sf,
+		code,
+		diagnostics: [],
+		reactImportedHooks: /* @__PURE__ */ new Set(),
+		signalBindings: collectDetectSignalBindings(sf)
+	};
+	detectVisit(ctx, sf);
+	return ctx.diagnostics;
 }
-function subtreeHas(node, predicate) {
-	let found = false;
-	function walk(n) {
-		if (found) return;
-		if (predicate(n)) {
-			found = true;
-			return;
+function migrateAddImport(ctx, source, specifier) {
+	if (!source || !specifier) return;
+	let specs = ctx.pyreonImports.get(source);
+	if (!specs) {
+		specs = /* @__PURE__ */ new Set();
+		ctx.pyreonImports.set(source, specs);
+	}
+	specs.add(specifier);
+}
+function migrateReplace(ctx, node, text) {
+	ctx.replacements.push({
+		start: node.getStart(ctx.sf),
+		end: node.getEnd(),
+		text
+	});
+}
+function migrateGetNodeText(ctx, node) {
+	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
+}
+function migrateGetLine(ctx, node) {
+	return ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf)).line + 1;
+}
+function migrateImportDeclaration(ctx, node) {
+	if (!node.moduleSpecifier) return;
+	if (!(node.moduleSpecifier.text in IMPORT_REWRITES)) return;
+	if (node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)) for (const spec of node.importClause.namedBindings.elements) {
+		const rewrite = SPECIFIER_REWRITES[spec.name.text];
+		if (rewrite) {
+			if (rewrite.name) migrateAddImport(ctx, rewrite.from, rewrite.name);
+			ctx.specifierRewrites.set(spec, rewrite);
 		}
-		ts.forEachChild(n, walk);
 	}
-	walk(node);
-	return found;
-}
-function detectDateMathRandomId(ctx, node) {
-	if (!subtreeHas(node, (n) => isCallTo(n, "Date", "now"))) return;
-	if (!subtreeHas(node, (n) => isCallTo(n, "Math", "random"))) return;
-	pushDiag(ctx, node, "date-math-random-id", "Combining `Date.now()` + `Math.random()` for unique IDs is collision-prone under rapid operations (paste, clone) — `Date.now()` returns the same value within a millisecond and `Math.random().toString(36).slice(2, 6)` has only ~1.67M combinations. Use a monotonic counter instead.", getNodeText(ctx, node), "let _counter = 0; const nextId = () => String(++_counter)", false);
+	ctx.importsToRemove.add(node);
+}
+function migrateUseState(ctx, node) {
+	const parent = node.parent;
+	if (ts.isVariableDeclaration(parent) && parent.name && ts.isArrayBindingPattern(parent.name) && parent.name.elements.length >= 1) {
+		const firstEl = parent.name.elements[0];
+		const valueName = firstEl && ts.isBindingElement(firstEl) ? firstEl.name.text : "value";
+		const initArg = node.arguments[0] ? migrateGetNodeText(ctx, node.arguments[0]) : "undefined";
+		const declStart = parent.getStart(ctx.sf);
+		const declEnd = parent.getEnd();
+		ctx.replacements.push({
+			start: declStart,
+			end: declEnd,
+			text: `${valueName} = signal(${initArg})`
+		});
+		migrateAddImport(ctx, "@pyreon/reactivity", "signal");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: `useState → signal: ${valueName}`
+		});
+	}
+}
+function migrateUseEffect(ctx, node) {
+	const depsArg = node.arguments[1];
+	const callbackArg = node.arguments[0];
+	const hookName = node.expression.text;
+	if (depsArg && ts.isArrayLiteralExpression(depsArg) && depsArg.elements.length === 0 && callbackArg) {
+		migrateReplace(ctx, node, `onMount(${migrateGetNodeText(ctx, callbackArg)})`);
+		migrateAddImport(ctx, "@pyreon/core", "onMount");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: `${hookName}(fn, []) → onMount(fn)`
+		});
+	} else if (callbackArg) {
+		migrateReplace(ctx, node, `effect(${migrateGetNodeText(ctx, callbackArg)})`);
+		migrateAddImport(ctx, "@pyreon/reactivity", "effect");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: `${hookName} → effect (auto-tracks deps)`
+		});
+	}
 }
-function detectOnClickUndefined(ctx, node) {
-	if (!ts.isIdentifier(node.name)) return;
-	const attrName = node.name.text;
-	if (!attrName.startsWith("on") || attrName.length < 3) return;
-	if (!node.initializer || !ts.isJsxExpression(node.initializer)) return;
-	const expr = node.initializer.expression;
-	if (!expr) return;
-	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);
+function migrateUseMemo(ctx, node) {
+	const computeFn = node.arguments[0];
+	if (computeFn) {
+		migrateReplace(ctx, node, `computed(${migrateGetNodeText(ctx, computeFn)})`);
+		migrateAddImport(ctx, "@pyreon/reactivity", "computed");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: "useMemo → computed (auto-tracks deps)"
+		});
+	}
 }
-/**
-* 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 migrateUseCallback(ctx, node) {
+	const callbackFn = node.arguments[0];
+	if (callbackFn) {
+		migrateReplace(ctx, node, migrateGetNodeText(ctx, callbackFn));
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: "useCallback → plain function (not needed in Pyreon)"
+		});
 	}
-	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);
+}
+function migrateUseRef(ctx, node) {
+	const arg = node.arguments[0];
+	if (arg && (arg.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(arg) && arg.text === "undefined") || !arg) {
+		migrateReplace(ctx, node, "createRef()");
+		migrateAddImport(ctx, "@pyreon/core", "createRef");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: "useRef(null) → createRef()"
+		});
+	} else {
+		migrateReplace(ctx, node, `signal(${migrateGetNodeText(ctx, arg)})`);
+		migrateAddImport(ctx, "@pyreon/reactivity", "signal");
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: "useRef(value) → signal(value)"
+		});
 	}
-	walk(sf);
-	return names;
 }
-function detectSignalWriteAsCall(ctx, node) {
-	if (ctx.signalBindings.size === 0) return;
+function migrateMemoWrapper(ctx, node) {
 	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.isIdentifier(callee) && callee.text === "memo" || isCallToReactDot(callee, "memo")) && node.arguments[0]) {
+		migrateReplace(ctx, node, migrateGetNodeText(ctx, node.arguments[0]));
+		ctx.changes.push({
+			type: "remove",
+			line: migrateGetLine(ctx, node),
+			description: "Removed memo() wrapper (not needed in Pyreon)"
+		});
 	}
-	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;
+function migrateForwardRef(ctx, node) {
+	const callee = node.expression;
+	if ((ts.isIdentifier(callee) && callee.text === "forwardRef" || isCallToReactDot(callee, "forwardRef")) && node.arguments[0]) {
+		migrateReplace(ctx, node, migrateGetNodeText(ctx, node.arguments[0]));
+		ctx.changes.push({
+			type: "remove",
+			line: migrateGetLine(ctx, node),
+			description: "Removed forwardRef wrapper (pass ref as normal prop in Pyreon)"
+		});
 	}
 }
-/**
-* `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);
+function migrateJsxAttributes(ctx, node) {
+	const attrName = node.name.text;
+	if (attrName in JSX_ATTR_REWRITES) {
+		const htmlAttr = JSX_ATTR_REWRITES[attrName];
+		ctx.replacements.push({
+			start: node.name.getStart(ctx.sf),
+			end: node.name.getEnd(),
+			text: htmlAttr
+		});
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: `${attrName} → ${htmlAttr}`
+		});
+	}
+	if (attrName === "onChange") {
+		const jsxElement = findParentJsxElement(node);
+		if (jsxElement) {
+			const tagName = getJsxTagName(jsxElement);
+			if (tagName === "input" || tagName === "textarea" || tagName === "select") {
+				ctx.replacements.push({
+					start: node.name.getStart(ctx.sf),
+					end: node.name.getEnd(),
+					text: "onInput"
+				});
+				ctx.changes.push({
+					type: "replace",
+					line: migrateGetLine(ctx, node),
+					description: `onChange on <${tagName}> → onInput (native DOM events)`
+				});
 			}
 		}
-		ts.forEachChild(node, walk);
-	}
-	walk(sf);
-	return names;
+	}
+	if (attrName === "dangerouslySetInnerHTML") migrateDangerouslySetInnerHTML(ctx, node);
 }
-/**
-* 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 migrateDangerouslySetInnerHTML(ctx, node) {
+	if (!node.initializer || !ts.isJsxExpression(node.initializer) || !node.initializer.expression) return;
+	const expr = node.initializer.expression;
+	if (!ts.isObjectLiteralExpression(expr)) return;
+	const htmlProp = expr.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "__html");
+	if (htmlProp) {
+		migrateReplace(ctx, node, `innerHTML={${migrateGetNodeText(ctx, htmlProp.initializer)}}`);
+		ctx.changes.push({
+			type: "replace",
+			line: migrateGetLine(ctx, node),
+			description: "dangerouslySetInnerHTML → innerHTML"
+		});
 	}
 }
-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);
-		detectStaticReturnNullConditional(ctx, node);
+function applyReplacements(code, ctx) {
+	for (const imp of ctx.importsToRemove) {
+		ctx.replacements.push({
+			start: imp.getStart(ctx.sf),
+			end: imp.getEnd(),
+			text: ""
+		});
+		ctx.changes.push({
+			type: "remove",
+			line: ctx.sf.getLineAndCharacterOfPosition(imp.getStart(ctx.sf)).line + 1,
+			description: "Removed React import"
+		});
 	}
-	if (ts.isBinaryExpression(node)) {
-		detectProcessDevGate(ctx, node);
-		detectDateMathRandomId(ctx, node);
+	ctx.replacements.sort((a, b) => b.start - a.start);
+	const applied = /* @__PURE__ */ new Set();
+	const deduped = [];
+	for (const r of ctx.replacements) {
+		const key = `${r.start}:${r.end}`;
+		let overlaps = false;
+		for (const d of deduped) if (r.start < d.end && r.end > d.start) {
+			overlaps = true;
+			break;
+		}
+		if (!overlaps && !applied.has(key)) {
+			applied.add(key);
+			deduped.push(r);
+		}
 	}
-	if (ts.isTemplateExpression(node)) detectDateMathRandomId(ctx, node);
-	if (ts.isCallExpression(node)) {
-		detectEmptyTheme(ctx, node);
-		detectRawEventListener(ctx, node);
-		detectSignalWriteAsCall(ctx, node);
-		detectIslandNeverWithRegistry(ctx, node);
+	deduped.sort((a, b) => a.start - b.start);
+	const parts = [];
+	let lastPos = 0;
+	for (const r of deduped) {
+		parts.push(code.slice(lastPos, r.start));
+		parts.push(r.text);
+		lastPos = r.end;
 	}
-	if (ts.isJsxAttribute(node)) detectOnClickUndefined(ctx, node);
-	if (ts.isAsExpression(node)) detectAsUnknownAsVNodeChild(ctx, node);
+	parts.push(code.slice(lastPos));
+	return parts.join("");
 }
-function visit(ctx, node) {
+function insertPyreonImports(code, pyreonImports) {
+	if (pyreonImports.size === 0) return code;
+	const importLines = [];
+	const sorted = [...pyreonImports.entries()].sort(([a], [b]) => a.localeCompare(b));
+	for (const [source, specs] of sorted) {
+		const specList = [...specs].sort().join(", ");
+		importLines.push(`import { ${specList} } from "${source}"`);
+	}
+	const importBlock = importLines.join("\n");
+	const lastImportEnd = findLastImportEnd(code);
+	if (lastImportEnd > 0) return `${code.slice(0, lastImportEnd)}\n${importBlock}${code.slice(lastImportEnd)}`;
+	return `${importBlock}\n\n${code}`;
+}
+function migrateVisitNode(ctx, node) {
+	if (ts.isImportDeclaration(node)) migrateImportDeclaration(ctx, node);
+	if (isCallToHook(node, "useState")) migrateUseState(ctx, node);
+	if (isCallToEffectHook(node)) migrateUseEffect(ctx, node);
+	if (isCallToHook(node, "useMemo")) migrateUseMemo(ctx, node);
+	if (isCallToHook(node, "useCallback")) migrateUseCallback(ctx, node);
+	if (isCallToHook(node, "useRef")) migrateUseRef(ctx, node);
+	if (ts.isCallExpression(node)) migrateMemoWrapper(ctx, node);
+	if (ts.isCallExpression(node)) migrateForwardRef(ctx, node);
+	if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name)) migrateJsxAttributes(ctx, node);
+}
+function migrateVisit(ctx, node) {
 	ts.forEachChild(node, (child) => {
-		visitNode(ctx, child);
-		visit(ctx, child);
+		migrateVisitNode(ctx, child);
+		migrateVisit(ctx, child);
 	});
 }
-function detectPyreonPatterns(code, filename = "input.tsx") {
+function migrateReactCode(code, filename = "input.tsx") {
 	const sf = ts.createSourceFile(filename, code, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TSX);
+	const diagnostics = detectReactPatterns(code, filename);
 	const ctx = {
 		sf,
 		code,
-		diagnostics: [],
-		signalBindings: collectSignalBindings(sf),
-		neverIslandNames: collectNeverIslandNames(sf)
+		replacements: [],
+		changes: [],
+		pyreonImports: /* @__PURE__ */ new Map(),
+		importsToRemove: /* @__PURE__ */ new Set(),
+		specifierRewrites: /* @__PURE__ */ new Map()
+	};
+	migrateVisit(ctx, sf);
+	let result = applyReplacements(code, ctx);
+	result = insertPyreonImports(result, ctx.pyreonImports);
+	result = result.replace(/\n{3,}/g, "\n\n");
+	return {
+		code: result,
+		diagnostics,
+		changes: ctx.changes
 	};
-	visit(ctx, sf);
-	ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
-	return ctx.diagnostics;
 }
-/** 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) || /\bisland\s*\(/.test(code) && /\bhydrate\s*:\s*['"]never['"]/.test(code);
+function findParentJsxElement(node) {
+	let current = node.parent;
+	while (current) {
+		if (ts.isJsxOpeningElement(current) || ts.isJsxSelfClosingElement(current)) return current;
+		if (ts.isJsxElement(current)) return current.openingElement;
+		if (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) return null;
+		current = current.parent;
+	}
+	return null;
+}
+function getJsxTagName(node) {
+	const tagName = node.tagName;
+	if (ts.isIdentifier(tagName)) return tagName.text;
+	return "";
+}
+function findLastImportEnd(code) {
+	const importRe = /^import\s.+$/gm;
+	let lastEnd = 0;
+	let match;
+	while (true) {
+		match = importRe.exec(code);
+		if (!match) break;
+		lastEnd = match.index + match[0].length;
+	}
+	return lastEnd;
+}
+/** Fast regex check — returns true if code likely contains React patterns worth analyzing */
+function hasReactPatterns(code) {
+	return /\bfrom\s+['"]react/.test(code) || /\bfrom\s+['"]react-dom/.test(code) || /\bfrom\s+['"]react-router/.test(code) || /\buseState\s*[<(]/.test(code) || /\buseEffect\s*\(/.test(code) || /\buseMemo\s*\(/.test(code) || /\buseCallback\s*\(/.test(code) || /\buseRef\s*[<(]/.test(code) || /\buseReducer\s*[<(]/.test(code) || /\bReact\.memo\b/.test(code) || /\bforwardRef\s*[<(]/.test(code) || /\bclassName[=\s]/.test(code) || /\bhtmlFor[=\s]/.test(code) || /\.value\s*=/.test(code);
+}
+const ERROR_PATTERNS = [
+	{
+		pattern: /Cannot read properties of undefined \(reading '(set|update|peek|subscribe)'\)/,
+		diagnose: (m) => ({
+			cause: `Calling .${m[1]}() on undefined. The signal variable is likely out of scope, misspelled, or not yet initialized.`,
+			fix: "Check that the signal is defined and in scope. Signals must be created with signal() before use.",
+			fixCode: `const mySignal = signal(initialValue)\nmySignal.${m[1]}(newValue)`
+		})
+	},
+	{
+		pattern: /(\w+) is not a function/,
+		diagnose: (m) => ({
+			cause: `'${m[1]}' is not callable. If this is a signal, you need to call it: ${m[1]}()`,
+			fix: "Pyreon signals are callable functions. Read: signal(), Write: signal.set(value)",
+			fixCode: `// Read value:\nconst value = ${m[1]}()\n// Set value:\n${m[1]}.set(newValue)`
+		})
+	},
+	{
+		pattern: /Cannot find module '(@pyreon\/\w[\w-]*)'/,
+		diagnose: (m) => ({
+			cause: `Package ${m[1]} is not installed.`,
+			fix: `Run: bun add ${m[1]}`,
+			fixCode: `bun add ${m[1]}`
+		})
+	},
+	{
+		pattern: /Cannot find module 'react'/,
+		diagnose: () => ({
+			cause: "Importing from 'react' in a Pyreon project.",
+			fix: "Replace React imports with Pyreon equivalents.",
+			fixCode: "// Instead of:\nimport { useState } from \"react\"\n// Use:\nimport { signal } from \"@pyreon/reactivity\""
+		})
+	},
+	{
+		pattern: /Property '(\w+)' does not exist on type 'Signal<\w+>'/,
+		diagnose: (m) => ({
+			cause: `Accessing .${m[1]} on a signal. Pyreon signals don't have a .${m[1]} property.`,
+			fix: m[1] === "value" ? "Pyreon signals are callable functions, not .value getters. Call signal() to read, signal.set() to write." : `Signals have these methods: .set(), .update(), .peek(), .subscribe(). '${m[1]}' is not one of them.`,
+			fixCode: m[1] === "value" ? "// Read: mySignal()\n// Write: mySignal.set(newValue)" : void 0
+		})
+	},
+	{
+		pattern: /Type '(\w+)' is not assignable to type 'VNode'/,
+		diagnose: (m) => ({
+			cause: `Component returned ${m[1]} instead of VNode. Components must return JSX, null, or a string.`,
+			fix: "Make sure your component returns a JSX element, null, or a string.",
+			fixCode: "const MyComponent = (props) => {\n  return <div>{props.children}</div>\n}"
+		})
+	},
+	{
+		pattern: /onMount callback must return/,
+		diagnose: () => ({
+			cause: "onMount expects a callback that optionally returns a CleanupFn.",
+			fix: "Return a cleanup function, or return nothing.",
+			fixCode: "onMount(() => {\n  // setup code\n})"
+		})
+	},
+	{
+		pattern: /Expected 'by' prop on <For>/,
+		diagnose: () => ({
+			cause: "<For> requires a 'by' prop for efficient keyed reconciliation.",
+			fix: "Add a by prop that returns a unique key for each item.",
+			fixCode: "<For each={items()} by={item => item.id}>\n  {item => <li>{item.name}</li>}\n</For>"
+		})
+	},
+	{
+		pattern: /useHook.*outside.*component/i,
+		diagnose: () => ({
+			cause: "Hook called outside a component function. Pyreon hooks must be called during component setup.",
+			fix: "Move the hook call inside a component function body."
+		})
+	},
+	{
+		pattern: /Hydration mismatch/,
+		diagnose: () => ({
+			cause: "Server-rendered HTML doesn't match client-rendered output.",
+			fix: "Ensure SSR and client render the same initial content. Check for browser-only APIs (window, document) in SSR code.",
+			related: "Use typeof window !== 'undefined' checks or onMount() for client-only code."
+		})
+	}
+];
+/** Diagnose an error message and return structured fix information */
+function diagnoseError(error) {
+	for (const { pattern, diagnose } of ERROR_PATTERNS) {
+		const match = error.match(pattern);
+		if (match) return diagnose(match);
+	}
+	return null;
 }
 
 //#endregion
@@ -3671,5 +4438,5 @@ function formatSsgAudit(result, _options = {}) {
 }
 
 //#endregion
-export { auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformJSX, transformJSX_JS };
+export { analyzeReactivity, auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatReactivityLens, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformDeferInline, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index.js.map