@pyreon/compiler 0.18.0 → 0.20.0

package/lib/index.js

@@ -1,11 +1,12 @@
 import { parseSync } from "oxc-parser";
+import MagicString from "magic-string";
 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
 /**
@@ -14,40 +15,38 @@ import ts from "typescript";
 * Rewrites:
 *
 *     import { Modal } from './Modal'
-*     <Defer when={open()}><Modal /></Defer>
+*     <Defer when={open()}><Modal title="hi" /></Defer>
 *
 * into:
 *
-*     <Defer when={open()} chunk={() => import('./Modal').then(m => ({ default: m.Modal }))}>
-*       {C => <C />}
+*     <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 of v1 (this file):
-*   - Single Defer element per file (no nested handling — bail otherwise).
-*   - Children: exactly ONE JSXElement, self-closing, capitalised name
-*     (component reference), no props. Props or multiple children → leave
-*     the Defer untransformed (user must use the explicit `chunk` form).
-*   - Imports: named OR default. Namespace imports (`import * as Mod`)
-*     and destructured-renamed (`{ X as Y }`) not handled in v1.
+* 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. v2 follow-ups can relax these
-* constraints with closure-capture handling, namespace imports, etc.
-*
-* Pipeline: this runs BEFORE `transformJSX()` in the vite plugin. The
-* output is still JSX — `transformJSX` then converts it to `h()` /
-* `_tpl()` calls as usual.
-*/
-/**
-* Detect the language for `parseSync`. `oxc-parser` infers from filename
-* by extension — we mirror the same logic for the few extensions we
-* support so the parser is invoked correctly.
+* 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";
@@ -57,9 +56,9 @@ function getLang$1(filename) {
 }
 /**
 * Returns the JSX tag name as a string when the opening element's name
-* is a simple identifier (the only shape we recognise as a "named JSX
-* element"). Member-expression names (`<obj.X />`) and namespaced names
-* (`<svg:rect />`) return null — the caller treats those as non-matches.
+* 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;
@@ -69,33 +68,83 @@ function getJsxName(node) {
 	return name.name;
 }
 /**
-* `<Tag />` qualifies as a "bare component reference child" when:
-*   - It's a JSXElement (not text, fragment, or expression container).
-*   - The opening name is a capitalised JSXIdentifier (component).
-*   - It has no attributes (no props passed).
-*   - It's self-closing OR has zero non-whitespace children.
+* 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 isBareComponentChild(node) {
-	if (node.type !== "JSXElement") return null;
-	const tag = getJsxName(node);
-	if (!tag || !/^[A-Z]/.test(tag)) return null;
-	if ((node.openingElement.attributes ?? []).length > 0) return null;
-	const children = node.children ?? [];
-	for (const child of children) {
-		if (child.type === "JSXText" && /^\s*$/.test(child.value)) continue;
-		return null;
-	}
-	return { name: tag };
+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
+	};
 }
 /**
-* Filter whitespace-only JSXText nodes; return remaining children. JSX
-* source like `<Defer>\n  <Modal />\n</Defer>` has 3 children at the AST
-* level: text, element, text. The text nodes are formatting noise.
+* 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) {
+function findDeferMatches(program, warnings, code) {
 	const matches = [];
 	const walk = (node) => {
 		if (!node || typeof node !== "object") return;
@@ -103,20 +152,36 @@ function findDeferMatches(program) {
 			const open = node.openingElement;
 			if (!(open.attributes ?? []).some((a) => a.type === "JSXAttribute" && a.name?.type === "JSXIdentifier" && a.name.name === "chunk")) {
 				const live = nonWhitespaceChildren(node);
-				if (live.length === 1) {
-					const childInfo = isBareComponentChild(live[0]);
-					if (childInfo) {
+				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],
-							childName: childInfo.name,
+							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"
+						});
 					}
 				}
 			}
@@ -131,69 +196,117 @@ function findDeferMatches(program) {
 	walk(program);
 	return matches;
 }
-function findImportFor(program, name) {
+/**
+* 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 === name) return {
-				node: stmt,
+			if (spec.local.name === localName) return {
+				declaration: stmt,
+				specifier: spec,
 				source: stmt.source.value,
-				kind: "default"
+				kind: "default",
+				importedName: "default"
 			};
 		} else if (spec.type === "ImportSpecifier") {
-			const local = spec.local.name;
-			const imported = spec.imported?.name;
-			if (local === name && imported !== void 0 && imported === local) return {
-				node: stmt,
+			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"
+				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 `name` outside the given JSXElement subtree. The
-* static import can only be safely removed if the binding is used
-* EXCLUSIVELY inside that subtree.
+* 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, name, skipSubtree) {
+function countReferencesOutside(program, localName, skipSubtree, skipDeclaration) {
 	let count = 0;
 	const skipStart = skipSubtree.start;
 	const skipEnd = skipSubtree.end;
-	const countInNode = (node) => {
+	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" && ns >= skipStart && ne <= skipEnd) return;
-		if (node.type === "Identifier" && node.name === name) count++;
-		if (node.type === "JSXIdentifier" && node.name === name) count++;
+		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) countInNode(item);
-			else if (v && typeof v === "object" && typeof v.type === "string") countInNode(v);
+			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) {
-		if (stmt.type === "ImportDeclaration") continue;
-		countInNode(stmt);
-	}
+	for (const stmt of body) visit(stmt);
 	return count;
 }
-/** Build the chunk={...} attribute string for a default or named import. */
-function buildChunkAttr(source, kind, name) {
+/**
+* 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.${name} }))}`;
+	return ` chunk={() => import('${source}').then((__m) => ({ default: __m.${exportName} }))}`;
 }
 /**
-* Apply edits to the source string. Edits MUST be non-overlapping; we
-* sort by start descending and splice each into the source so earlier
-* positions stay valid as we work backwards.
+* 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;
@@ -201,22 +314,44 @@ function applyEdits(source, edits) {
 	return out;
 }
 /**
-* Main entry. Returns the (possibly transformed) source plus the list
-* of warnings for cases the transform deliberately skipped.
-*
-* Bails (returns input unchanged with `changed: false`) when:
-*   - No `<Defer>` JSX element appears in the file (fast path).
-*   - The file fails to parse (syntax error — let downstream handle).
-*   - No `<Defer>` matches the inline-eligible shape.
-*
-* Per-Defer skips with a warning:
-*   - Multiple children → user must use render-prop form
-*   - Child has props → user must use render-prop form
-*   - Child name isn't imported → can't resolve the chunk source
-*   - Child binding is used outside the Defer subtree → can't remove
-*     the static import (dynamic import would be a no-op via Rolldown's
-*     same-module dedup)
+* 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 {
@@ -237,7 +372,7 @@ function transformDeferInline(code, filename = "input.tsx") {
 			warnings
 		};
 	}
-	const matches = findDeferMatches(program);
+	const matches = findDeferMatches(program, warnings, code);
 	if (matches.length === 0) return {
 		code,
 		changed: false,
@@ -246,45 +381,51 @@ function transformDeferInline(code, filename = "input.tsx") {
 	const edits = [];
 	let changed = false;
 	for (const m of matches) {
-		const importInfo = findImportFor(program, m.childName);
+		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 <${m.childName} /> isn't imported — can't resolve a chunk source. Use the explicit \`chunk\` prop, or import ${m.childName} from a module.`,
+				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 (countReferencesOutside(program, m.childName, m.node) > 0) {
+		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 <${m.childName} /> is also referenced elsewhere in this file. Inline form requires the import to be used exclusively inside this Defer. Use the explicit \`chunk\` prop form to split despite shared usage.`,
+				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, m.childName)
+			replacement: buildChunkAttr(importInfo.source, importInfo.kind, exportName)
 		});
 		edits.push({
 			start: m.childrenRange.start,
 			end: m.childrenRange.end,
-			replacement: `{(__C) => <__C />}`
-		});
-		const impStart = importInfo.node.start;
-		let impEnd = importInfo.node.end;
-		if (code[impEnd] === "\n") impEnd += 1;
-		edits.push({
-			start: impStart,
-			end: impEnd,
-			replacement: ""
+			replacement: buildRenderPropBody(code, m.childAnalysis, m.childrenRange)
 		});
+		edits.push(buildImportRemovalEdit(code, importInfo));
 		changed = true;
 	}
 	if (!changed) return {
@@ -298,7 +439,6 @@ function transformDeferInline(code, filename = "input.tsx") {
 		warnings
 	};
 }
-/** Resolve a byte offset into 1-based line + 0-based column. */
 function getLoc(code, offset) {
 	let line = 1;
 	let lastNl = -1;
@@ -518,6 +658,21 @@ const DELEGATED_EVENTS = new Set([
 	"touchmove",
 	"submit"
 ]);
+/**
+* Canonical key for a collapsible rocketstyle call site. The Vite plugin
+* computes this when it resolves a site; the compiler recomputes the
+* IDENTICAL key from the JSX node to look the resolution up. Stable
+* ordering of props so attribute order in source doesn't change the key.
+*/
+function rocketstyleCollapseKey(componentName, props, childrenText) {
+	const src = `${componentName}\u0000${Object.keys(props).sort().map((k) => `${k}=${props[k]}`).join("
")}\u0000${childrenText}`;
+	let h = 2166136261;
+	for (let i = 0; i < src.length; i++) {
+		h ^= src.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+}
 function getLang(filename) {
 	if (filename.endsWith(".jsx")) return "jsx";
 	return "tsx";
@@ -570,9 +725,165 @@ function jsxAttrs(node) {
 function jsxChildren(node) {
 	return node.children ?? [];
 }
+/**
+* Build a `localName → { imported, source }` table from a module's
+* import declarations. Only named imports (`import { X as Y }`) are
+* relevant — the collapsible components are always named exports.
+*/
+function collectImportTable(program) {
+	const table = /* @__PURE__ */ new Map();
+	for (const stmt of program.body ?? []) {
+		if (stmt.type !== "ImportDeclaration") continue;
+		const source = stmt.source?.value;
+		if (typeof source !== "string") continue;
+		for (const spec of stmt.specifiers ?? []) {
+			if (spec.type !== "ImportSpecifier") continue;
+			const local = spec.local?.name;
+			const imported = spec.imported?.name ?? local;
+			if (typeof local === "string") table.set(local, {
+				imported,
+				source
+			});
+		}
+	}
+	return table;
+}
+/**
+* Pure detector — finds every collapsible rocketstyle call site in a
+* module. Used by `@pyreon/vite-plugin` to know which (component, props,
+* text) tuples to SSR-resolve. The bail catalogue here MUST stay
+* byte-identical to `tryRocketstyleCollapse`'s (RFC decision 3): a
+* candidate PascalCase tag whose import source is in `collapsibleSources`,
+* every attr a plain string literal (no spread, no `{expr}`, no boolean
+* attr), children empty or static text only. A consistency test asserts
+* the keys this produces equal the keys the compiler looks up.
+*/
+function scanCollapsibleSites(code, filename, collapsibleSources) {
+	let program;
+	try {
+		program = parseSync(filename, code, {
+			sourceType: "module",
+			lang: getLang(filename)
+		}).program;
+	} catch {
+		return [];
+	}
+	const imports = collectImportTable(program);
+	const out = [];
+	const visit = (node) => {
+		if (!node || typeof node !== "object") return;
+		if (node.type === "JSXElement") {
+			const tag = jsxTagName(node);
+			const imp = tag ? imports.get(tag) : void 0;
+			if (tag && tag.charAt(0) !== tag.charAt(0).toLowerCase() && imp && collapsibleSources.has(imp.source)) {
+				const site = detectCollapsibleShape(node, tag);
+				if (site) out.push({
+					componentName: tag,
+					source: imp.source,
+					importedName: imp.imported,
+					props: site.props,
+					childrenText: site.childrenText,
+					key: rocketstyleCollapseKey(tag, site.props, site.childrenText)
+				});
+			}
+		}
+		for (const k in node) {
+			const v = node[k];
+			if (Array.isArray(v)) for (const c of v) visit(c);
+			else if (v && typeof v === "object" && typeof v.type === "string") visit(v);
+		}
+	};
+	visit(program);
+	return out;
+}
+/**
+* The shared bail catalogue — every attr a string literal (no spread, no
+* `{expr}`, no boolean attr), children empty or static text. Returns the
+* extracted {props, childrenText} or null (bail). `tryRocketstyleCollapse`
+* inlines the identical checks; a consistency test locks them together.
+*/
+function detectCollapsibleShape(node, _tag) {
+	const props = {};
+	for (const attr of jsxAttrs(node)) {
+		if (attr.type !== "JSXAttribute") return null;
+		const nm = attr.name?.type === "JSXIdentifier" ? attr.name.name : null;
+		if (!nm) return null;
+		const v = attr.value;
+		if (!v) return null;
+		if (!(v.type === "StringLiteral" || v.type === "Literal" && typeof v.value === "string")) return null;
+		props[nm] = String(v.value);
+	}
+	let childrenText = "";
+	for (const c of jsxChildren(node)) if (c.type === "JSXText") childrenText += c.value ?? "";
+	else return null;
+	return {
+		props,
+		childrenText: childrenText.trim()
+	};
+}
+/**
+* Partial-collapse detector — PR 1 of the partial-collapse spec
+* (`.claude/plans/open-work-2026-q3.md` → #1). The `on*`-handler-only
+* subset the bail-reason census measured at 7.8% of all
+* `@pyreon/ui-components` call sites (`collapse-bail-census.test.ts`).
+*
+* It is the EXACT `detectCollapsibleShape` bail catalogue with ONE
+* relaxation: a `{expr}`-valued attribute whose name matches `on[A-Z]…`
+* (an event handler) does NOT bail — it is peeled into `handlers[]`
+* instead. Handlers are orthogonal to the SSR-resolved styler class (an
+* event binding never changes rendered CSS), so the literal-prop subset
+* still feeds the UNCHANGED `rocketstyleCollapseKey` and the resolver's
+* pre-resolved `templateHtml` / `lightClass` / `darkClass` are
+* byte-identical to a full-collapse site's. The collapsed runtime node
+* just re-attaches the residual handlers (PR 2 — `_rsCollapseH`).
+*
+* Every OTHER non-literal shape still bails (spread, non-handler
+* `{expr}` prop, boolean attr, element/expression child) — conservative
+* by construction, exactly like the full detector. Returns `null` when
+* there are ZERO handlers so the full-collapse path stays byte-unchanged
+* and the two detectors never both claim the same site (full-collapse
+* sites have no handlers; partial sites have ≥1). A consistency test
+* will lock this catalogue against the plugin scan in PR 3, mirroring
+* the existing `detectCollapsibleShape` ↔ `scanCollapsibleSites`
+* invariant — keys cannot drift.
+*/
+function detectPartialCollapsibleShape(node, _tag) {
+	const props = {};
+	const handlers = [];
+	for (const attr of jsxAttrs(node)) {
+		if (attr.type !== "JSXAttribute") return null;
+		const nm = attr.name?.type === "JSXIdentifier" ? attr.name.name : null;
+		if (!nm) return null;
+		const v = attr.value;
+		if (!v) return null;
+		if (v.type === "StringLiteral" || v.type === "Literal" && typeof v.value === "string") {
+			props[nm] = String(v.value);
+			continue;
+		}
+		if (/^on[A-Z]/.test(nm) && v.type === "JSXExpressionContainer" && v.expression && typeof v.expression.start === "number" && typeof v.expression.end === "number") {
+			handlers.push({
+				name: nm,
+				exprStart: v.expression.start,
+				exprEnd: v.expression.end
+			});
+			continue;
+		}
+		return null;
+	}
+	let childrenText = "";
+	for (const c of jsxChildren(node)) if (c.type === "JSXText") childrenText += c.value ?? "";
+	else return null;
+	if (handlers.length === 0) return null;
+	return {
+		props,
+		childrenText: childrenText.trim(),
+		handlers
+	};
+}
 function transformJSX(code, filename = "input.tsx", options = {}) {
+	if (options.collapseRocketstyle) return transformJSX_JS(code, filename, 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);
 }
@@ -603,6 +914,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. */
@@ -645,6 +973,102 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 	let needsBindImportGlobal = false;
 	let needsApplyPropsImportGlobal = false;
 	let needsMountSlotImportGlobal = false;
+	let needsCollapse = false;
+	let needsCollapseH = false;
+	const collapseRuleKeys = /* @__PURE__ */ new Set();
+	const collapseRules = [];
+	/**
+	* Detect + collapse a literal-prop rocketstyle call site. Conservative
+	* bail catalogue (RFC decision 3): PascalCase candidate, every attr a
+	* StringLiteral (no spread, no `{expr}`, no boolean attr), children
+	* empty or a single static JSXText. The plugin must already have
+	* SSR-resolved this exact (component, props, text) tuple — an absent
+	* `sites` entry is a hard bail (covers resolver-bailed shapes,
+	* cross-package-without-data, anything uncertain). Emits ONE
+	* `_rsCollapse(tpl, light, dark, () => mode()==='dark')` (dual-emit)
+	* plus a once-per-module idempotent `injectRules`. A false negative is
+	* correct-but-slow; a false positive is wrong output — so every
+	* uncertain signal returns false.
+	*/
+	function tryRocketstyleCollapse(node) {
+		const cfg = options.collapseRocketstyle;
+		if (!cfg) return false;
+		const tag = jsxTagName(node);
+		if (!tag || tag.charAt(0) === tag.charAt(0).toLowerCase()) return false;
+		if (!cfg.candidates.has(tag)) return false;
+		const shape = detectCollapsibleShape(node, tag);
+		if (!shape) return tryPartialCollapse(node, tag);
+		const { props, childrenText } = shape;
+		const key = rocketstyleCollapseKey(tag, props, childrenText);
+		const site = cfg.sites.get(key);
+		if (!site) return false;
+		const call = `__rsCollapse(${JSON.stringify(site.templateHtml)}, ${JSON.stringify(site.lightClass)}, ${JSON.stringify(site.darkClass)}, () => __pyrMode() === "dark")`;
+		const start = node.start;
+		const end = node.end;
+		const parent = findParent(node);
+		const needsBraces = parent && (parent.type === "JSXElement" || parent.type === "JSXFragment");
+		replacements.push({
+			start,
+			end,
+			text: needsBraces ? `{${call}}` : call
+		});
+		needsCollapse = true;
+		if (!collapseRuleKeys.has(site.ruleKey)) {
+			collapseRuleKeys.add(site.ruleKey);
+			collapseRules.push({
+				ruleKey: site.ruleKey,
+				rules: site.rules
+			});
+		}
+		return true;
+	}
+	/**
+	* PR 3 of the partial-collapse build (open-work #1). The `on*`-handler-
+	* only fallback `tryRocketstyleCollapse` defers to when the FULL
+	* `detectCollapsibleShape` bails. Identical site-resolution contract as
+	* the full path — handlers are orthogonal to the SSR-resolved styler
+	* class, so the literal-prop subset feeds the UNCHANGED
+	* `rocketstyleCollapseKey` and the resolver's pre-resolved
+	* `templateHtml`/`lightClass`/`darkClass` are byte-identical to a
+	* full-collapse site's. The ONLY difference vs the full emit is
+	* `__rsCollapseH(...)` with a handlers object literal built from the
+	* sliced source spans `detectPartialCollapsibleShape` (PR 1) returned;
+	* the runtime helper (`_rsCollapseH`, PR 2 / #681) re-attaches them
+	* through the canonical event path. Same conservative discipline: an
+	* unresolved key, the option absent, or any non-handler non-literal
+	* shape ⇒ keep the normal mount (return false).
+	*/
+	function tryPartialCollapse(node, tag) {
+		const cfg = options.collapseRocketstyle;
+		if (!cfg) return false;
+		const partial = detectPartialCollapsibleShape(node, tag);
+		if (!partial) return false;
+		const { props, childrenText, handlers } = partial;
+		const key = rocketstyleCollapseKey(tag, props, childrenText);
+		const site = cfg.sites.get(key);
+		if (!site) return false;
+		const handlerObj = `{ ${handlers.map((h) => `${JSON.stringify(h.name)}: (${code.slice(h.exprStart, h.exprEnd)})`).join(", ")} }`;
+		const call = `__rsCollapseH(${JSON.stringify(site.templateHtml)}, ${JSON.stringify(site.lightClass)}, ${JSON.stringify(site.darkClass)}, () => __pyrMode() === "dark", ${handlerObj})`;
+		const start = node.start;
+		const end = node.end;
+		const parent = findParent(node);
+		const needsBraces = parent && (parent.type === "JSXElement" || parent.type === "JSXFragment");
+		replacements.push({
+			start,
+			end,
+			text: needsBraces ? `{${call}}` : call
+		});
+		needsCollapse = true;
+		needsCollapseH = true;
+		if (!collapseRuleKeys.has(site.ruleKey)) {
+			collapseRuleKeys.add(site.ruleKey);
+			collapseRules.push({
+				ruleKey: site.ruleKey,
+				rules: site.rules
+			});
+		}
+		return true;
+	}
 	function maybeHoist(node) {
 		if ((node.type === "JSXElement" || node.type === "JSXFragment") && isStaticJSXNode(node)) {
 			const name = `_$h${hoistIdx++}`;
@@ -653,6 +1077,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;
@@ -667,6 +1092,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);
@@ -763,6 +1189,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);
 	}
@@ -786,6 +1213,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 	}
 	const propsNames = /* @__PURE__ */ new Set();
 	const propDerivedVars = /* @__PURE__ */ new Map();
+	const elementVars = /* @__PURE__ */ new Set();
 	const signalVars = new Set(options.knownSignals);
 	const shadowedSignals = /* @__PURE__ */ new Set();
 	/** Check if an identifier name is an active (non-shadowed) signal variable. */
@@ -851,6 +1279,11 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 					for (const el of decl.id.elements ?? []) if (el?.type === "Identifier") propsNames.add(el.name);
 				}
 			}
+			if ((node.kind === "const" || node.kind === "let") && decl.id?.type === "Identifier" && decl.init) {
+				let initNode = decl.init;
+				while (initNode?.type === "ParenthesizedExpression") initNode = initNode.expression;
+				if (initNode?.type === "JSXElement" || initNode?.type === "JSXFragment") elementVars.add(decl.id.name);
+			}
 			if (node.kind !== "const") continue;
 			if (callbackDepth > 0) continue;
 			if (decl.id?.type === "Identifier" && decl.init) {
@@ -911,11 +1344,68 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 	function resolveIdentifiersInText(text, baseOffset, sourceNode) {
 		const endOffset = baseOffset + text.length;
 		const idents = [];
+		const shadowed = /* @__PURE__ */ new Set();
+		/** Collect identifier names bound by a pattern (params / declarators). */
+		function patternBindingNames(p, out) {
+			if (!p) return;
+			switch (p.type) {
+				case "Identifier":
+					out.push(p.name);
+					break;
+				case "ObjectPattern":
+					for (const pr of p.properties ?? []) if (pr.type === "RestElement") patternBindingNames(pr.argument, out);
+					else patternBindingNames(pr.value ?? pr.key, out);
+					break;
+				case "ArrayPattern":
+					for (const el of p.elements ?? []) patternBindingNames(el, out);
+					break;
+				case "AssignmentPattern":
+					patternBindingNames(p.left, out);
+					break;
+				case "RestElement":
+					patternBindingNames(p.argument, out);
+					break;
+			}
+		}
+		/**
+		* Prop-derived names bound by `node` FOR ITS OWN SUBTREE (block-accurate
+		* lexical scoping). Excludes the prop-derived const's own defining
+		* declaration (matched by init span) so the binding we inline FROM is
+		* never mistaken for a shadow of itself.
+		*/
+		function scopeBoundPropDerived(node) {
+			const out = [];
+			const t = node.type;
+			const declNames = (declNode) => {
+				for (const d of declNode.declarations ?? []) {
+					if (d.id?.type === "Identifier" && propDerivedVars.has(d.id.name)) {
+						const span = propDerivedVars.get(d.id.name);
+						if (d.init && d.init.start === span.start) continue;
+					}
+					patternBindingNames(d.id, out);
+				}
+			};
+			if (t === "ArrowFunctionExpression" || t === "FunctionExpression" || t === "FunctionDeclaration") for (const p of node.params ?? []) patternBindingNames(p, out);
+			else if (t === "CatchClause") patternBindingNames(node.param, out);
+			else if (t === "ForStatement") {
+				if (node.init?.type === "VariableDeclaration") declNames(node.init);
+			} else if (t === "ForInStatement" || t === "ForOfStatement") {
+				if (node.left?.type === "VariableDeclaration") declNames(node.left);
+			} else if (t === "BlockStatement" || t === "Program" || t === "StaticBlock") {
+				const stmts = node.body ?? node.statements;
+				if (Array.isArray(stmts)) {
+					for (const s of stmts) if (s.type === "VariableDeclaration") declNames(s);
+					else if (s.type === "FunctionDeclaration" && s.id?.type === "Identifier") out.push(s.id.name);
+					else if (s.type === "ClassDeclaration" && s.id?.type === "Identifier") out.push(s.id.name);
+				}
+			}
+			return out.filter((n) => propDerivedVars.has(n));
+		}
 		function findIdents(node, parent) {
 			const nodeStart = node.start;
 			const nodeEnd = node.end;
 			if (nodeStart >= endOffset || nodeEnd <= baseOffset) return;
-			if (node.type === "Identifier" && propDerivedVars.has(node.name)) {
+			if (node.type === "Identifier" && propDerivedVars.has(node.name) && !shadowed.has(node.name)) {
 				if (parent) {
 					if (parent.type === "MemberExpression" && parent.property === node && !parent.computed) {} else if (parent.type === "VariableDeclarator" && parent.id === node) {} else if (parent.type === "Property" && parent.key === node && !parent.computed) {} else if (parent.type === "Property" && parent.shorthand) {} else if (nodeStart >= baseOffset && nodeEnd <= endOffset) idents.push({
 						start: nodeStart,
@@ -928,7 +1418,10 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 					name: node.name
 				});
 			}
+			const introduced = scopeBoundPropDerived(node).filter((n) => !shadowed.has(n));
+			for (const n of introduced) shadowed.add(n);
 			forEachChildFast(node, (child) => findIdents(child, node));
+			for (const n of introduced) shadowed.delete(n);
 		}
 		findIdents(program, null);
 		if (idents.length === 0) return text;
@@ -1016,6 +1509,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		}
 		if (node.type === "VariableDeclaration") collectPropDerivedFromDecl(node, _callbackDepth);
 		if (node.type === "JSXElement") {
+			if (tryRocketstyleCollapse(node)) return;
 			if (!isSelfClosing(node) && tryTemplateEmit(node)) return;
 			checkForWarnings(node);
 			for (const attr of jsxAttrs(node)) if (attr.type === "JSXAttribute") handleJsxAttribute(attr, node);
@@ -1036,21 +1530,20 @@ 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
 	};
 	replacements.sort((a, b) => a.start - b.start);
-	const outParts = [];
-	let outPos = 0;
-	for (const r of replacements) {
-		outParts.push(code.slice(outPos, r.start));
-		outParts.push(r.text);
-		outPos = r.end;
-	}
-	outParts.push(code.slice(outPos));
-	let output = outParts.join("");
-	if (hoists.length > 0) output = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join("") + output;
+	const s = new MagicString(code);
+	for (const r of replacements) if (r.start === r.end) s.appendLeft(r.start, r.text);
+	else s.update(r.start, r.end, r.text);
+	let preamble = "";
+	if (hoists.length > 0) preamble = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join("") + preamble;
 	if (needsTplImport) {
 		const runtimeDomImports = ["_tpl"];
 		if (needsBindDirectImportGlobal) runtimeDomImports.push("_bindDirect");
@@ -1058,18 +1551,39 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 		if (needsApplyPropsImportGlobal) runtimeDomImports.push("_applyProps");
 		if (needsMountSlotImportGlobal) runtimeDomImports.push("_mountSlot");
 		const reactivityImports = needsBindImportGlobal ? `\nimport { _bind } from "@pyreon/reactivity";` : "";
-		output = `import { ${runtimeDomImports.join(", ")} } from "@pyreon/runtime-dom";${reactivityImports}\n` + output;
+		preamble = `import { ${runtimeDomImports.join(", ")} } from "@pyreon/runtime-dom";${reactivityImports}\n` + preamble;
 	}
 	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 {
+		preamble = `import { ${coreImports.join(", ")} } from "@pyreon/core";\n` + preamble;
+	}
+	if (needsCollapse) {
+		const cfg = options.collapseRocketstyle;
+		const rd = cfg.runtimeDomSource ?? "@pyreon/runtime-dom";
+		const st = cfg.stylerSource ?? "@pyreon/styler";
+		const inj = collapseRules.map((r) => `__rsSheet.injectRules(${JSON.stringify(r.rules)},${JSON.stringify(r.ruleKey)});`).join("");
+		preamble = `import { _rsCollapse as __rsCollapse${needsCollapseH ? ", _rsCollapseH as __rsCollapseH" : ""} } from "${rd}";\nimport { sheet as __rsSheet } from "${st}";\nimport { ${cfg.mode.name} as __pyrMode } from "${cfg.mode.source}";\n${inj}\n` + preamble;
+	}
+	if (preamble) s.prepend(preamble);
+	const output = s.toString();
+	const map = s.generateMap({
+		source: filename,
+		includeContent: true,
+		hires: true
+	});
+	return collectLens ? {
 		code: output,
 		usesTemplates: needsTplImport,
-		warnings
+		warnings,
+		map,
+		reactivityLens
+	} : {
+		code: output,
+		usesTemplates: needsTplImport,
+		warnings,
+		map
 	};
 	function hasBailAttr(node, isRoot = false) {
 		for (const attr of jsxAttrs(node)) {
@@ -1203,6 +1717,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;
@@ -1356,14 +1871,20 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 			}
 			const needsPlaceholder = useMixed || useMultiExpr;
 			const { expr, isReactive } = unwrapAccessor(child.expression);
-			if (isChildrenExpression(child.expression, expr)) {
+			const isElementValuedIdent = child.expression?.type === "Identifier" && elementVars.has(child.expression.name) || !isReactive && /^[A-Za-z_$][\w$]*$/.test(expr) && elementVars.has(expr);
+			if (isChildrenExpression(child.expression, expr) || isElementValuedIdent) {
 				needsMountSlotImport = true;
 				const placeholder = `${parentRef}.childNodes[${childNodeIdx}]`;
 				const d = nextDisp();
 				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) {
@@ -1444,12 +1965,64 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 	}
 	/** Auto-insert () after signal variable references in the expression source.
 	*  Uses the AST to find exact Identifier positions — never scans raw text. */
+	function sigPatternNames(p, out) {
+		if (!p) return;
+		switch (p.type) {
+			case "Identifier":
+				out.push(p.name);
+				break;
+			case "ObjectPattern":
+				for (const pr of p.properties ?? []) if (pr.type === "RestElement") sigPatternNames(pr.argument, out);
+				else sigPatternNames(pr.value ?? pr.key, out);
+				break;
+			case "ArrayPattern":
+				for (const el of p.elements ?? []) sigPatternNames(el, out);
+				break;
+			case "AssignmentPattern":
+				sigPatternNames(p.left, out);
+				break;
+			case "RestElement":
+				sigPatternNames(p.argument, out);
+				break;
+		}
+	}
+	function scopeBoundSignals(node) {
+		const out = [];
+		const t = node.type;
+		const declNames = (declNode) => {
+			for (const d of declNode.declarations ?? []) {
+				if (d.id?.type === "Identifier" && d.init && isSignalCall(d.init)) continue;
+				sigPatternNames(d.id, out);
+			}
+		};
+		if (t === "ArrowFunctionExpression" || t === "FunctionExpression" || t === "FunctionDeclaration") for (const p of node.params ?? []) sigPatternNames(p, out);
+		else if (t === "CatchClause") sigPatternNames(node.param, out);
+		else if (t === "ForStatement") {
+			if (node.init?.type === "VariableDeclaration") declNames(node.init);
+		} else if (t === "ForInStatement" || t === "ForOfStatement") {
+			if (node.left?.type === "VariableDeclaration") declNames(node.left);
+		} else if (t === "BlockStatement" || t === "StaticBlock") {
+			const stmts = node.body ?? node.statements;
+			if (Array.isArray(stmts)) {
+				for (const s of stmts) if (s.type === "VariableDeclaration") declNames(s);
+				else if (s.type === "FunctionDeclaration" && s.id?.type === "Identifier") out.push(s.id.name);
+				else if (s.type === "ClassDeclaration" && s.id?.type === "Identifier") out.push(s.id.name);
+			}
+		}
+		return out.filter((n) => signalVars.has(n));
+	}
 	function autoCallSignals(text, expr) {
 		const start = expr.start;
 		const idents = [];
+		const shadowed = /* @__PURE__ */ new Set();
 		function findSignalIdents(node) {
 			if (node.start >= start + text.length || node.end <= start) return;
-			if (node.type === "Identifier" && isActiveSignal(node.name)) {
+			const introduced = [];
+			for (const n of scopeBoundSignals(node)) if (!shadowed.has(n)) {
+				shadowed.add(n);
+				introduced.push(n);
+			}
+			if (node.type === "Identifier" && isActiveSignal(node.name) && !shadowed.has(node.name)) {
 				const parent = findParent(node);
 				if (parent && parent.type === "MemberExpression" && parent.property === node && !parent.computed) return;
 				if (parent && parent.type === "MemberExpression" && parent.object === node) {
@@ -1468,6 +2041,7 @@ function transformJSX_JS(code, filename = "input.tsx", options = {}) {
 				});
 			}
 			forEachChildFast(node, findSignalIdents);
+			for (const n of introduced) shadowed.delete(n);
 		}
 		findSignalIdents(expr);
 		if (idents.length === 0) return text;
@@ -1666,1266 +2240,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)
-				});
-			}
-		}
-	}
-	return routes;
+function getJsxTagName$1(node) {
+	const t = node.tagName;
+	if (ts.isIdentifier(t)) return t.text;
+	return "";
 }
-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 components;
+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 extractIslands(files, cwd) {
-	const islands = [];
-	for (const file of files) {
-		let code;
-		try {
-			code = fs.readFileSync(file, "utf-8");
-		} catch {
-			continue;
+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;
 		}
-		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;
+	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 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 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 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";
-	}
+/**
+* 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 cur;
 }
-
-//#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.
+* 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.
 *
-* Two modes:
-*  - `detectReactPatterns(code)` — returns diagnostics only (non-destructive)
-*  - `migrateReactCode(code)` — applies auto-fixes and returns transformed code
+* 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.
 *
-* 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)
+* 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.
 */
-/** 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 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);
+		}
+		ts.forEachChild(n, walk);
 	}
+	for (const stmt of body.statements) walk(stmt);
 }
-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 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 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 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 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 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 detectUseRef(ctx, node) {
+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 && (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 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);
+	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 isCallToReactDot(callee, methodName) {
-	return ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === "React" && callee.name.text === methodName;
+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 detectMemoWrapper(ctx, node) {
+function detectRawEventListener(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);
-	}
+	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 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 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 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);
+function subtreeHas(node, predicate) {
+	let found = false;
+	function walk(n) {
+		if (found) return;
+		if (predicate(n)) {
+			found = true;
+			return;
 		}
+		ts.forEachChild(n, walk);
 	}
-	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);
+	walk(node);
+	return found;
 }
-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);
+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 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);
-	}
+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 isCallToHook(node, hookName) {
-	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === hookName;
+/**
+* Walks the file and collects every identifier bound to a `signal(...)` or
+* `computed(...)` call. Only `const` declarations are tracked — `let`/`var`
+* may be reassigned to non-signal values, so a use-site call wouldn't be a
+* reliable signal-write.
+*
+* The collection is intentionally scope-blind: a name shadowed in a nested
+* scope (`const x = signal(0); function f() { const x = 5; x(7) }`) would
+* produce a false positive on `x(7)`. That tradeoff is acceptable because
+* (1) shadowing a signal name with a non-signal is itself unusual and
+* (2) the detector message points at exactly the wrong-shape call so a
+* human reviewer can dismiss the rare false positive in seconds.
+*/
+function collectSignalBindings(sf) {
+	const names = /* @__PURE__ */ new Set();
+	function isSignalFactoryCall(init) {
+		if (!init || !ts.isCallExpression(init)) return false;
+		const callee = init.expression;
+		if (!ts.isIdentifier(callee)) return false;
+		return callee.text === "signal" || callee.text === "computed";
+	}
+	function walk(node) {
+		if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+			const list = node.parent;
+			if (ts.isVariableDeclarationList(list) && (list.flags & ts.NodeFlags.Const) !== 0 && isSignalFactoryCall(node.initializer)) names.add(node.name.text);
+		}
+		ts.forEachChild(node, walk);
+	}
+	walk(sf);
+	return names;
 }
-function isCallToEffectHook(node) {
-	return ts.isCallExpression(node) && ts.isIdentifier(node.expression) && (node.expression.text === "useEffect" || node.expression.text === "useLayoutEffect");
+function detectSignalWriteAsCall(ctx, node) {
+	if (ctx.signalBindings.size === 0) return;
+	const callee = node.expression;
+	if (!ts.isIdentifier(callee)) return;
+	if (!ctx.signalBindings.has(callee.text)) return;
+	if (node.arguments.length === 0) return;
+	pushDiag(ctx, node, "signal-write-as-call", `\`${callee.text}(value)\` does NOT write the signal — \`signal()\` is the read-only callable surface and ignores its arguments. Use \`${callee.text}.set(value)\` to assign or \`${callee.text}.update((prev) => …)\` to derive from the previous value. Pyreon's runtime warns about this pattern in dev, but the warning fires AFTER the silent no-op.`, getNodeText(ctx, node), `${callee.text}.set(${node.arguments.map((a) => getNodeText(ctx, a)).join(", ")})`, false);
 }
-function isMapCallExpression(node) {
-	return ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.name) && node.expression.name.text === "map";
+/**
+* `if (cond) return null` at the top of a component body runs ONCE — Pyreon
+* components mount and never re-execute their function bodies. A signal
+* change inside `cond` therefore never re-evaluates the condition; the
+* component is permanently stuck on whichever branch the first run picked.
+*
+* The fix is to wrap the conditional in a returned reactive accessor:
+*   return (() => { if (!cond()) return null; return <div /> })
+*
+* Detection:
+*  - The function contains JSX (i.e. it's a component)
+*  - The function body has an `IfStatement` whose `thenStatement` is
+*    `return null` (either bare `return null` or `{ return null }`)
+*  - The `if` is at the function body's top level, NOT inside a returned
+*    arrow / IIFE (those are reactive scopes — flagging them would be a
+*    false positive)
+*/
+function returnsNullStatement(stmt) {
+	if (ts.isReturnStatement(stmt)) {
+		const expr = stmt.expression;
+		return !!expr && expr.kind === ts.SyntaxKind.NullKeyword;
+	}
+	if (ts.isBlock(stmt)) return stmt.statements.length === 1 && returnsNullStatement(stmt.statements[0]);
+	return false;
 }
-function isDotValueAccess(node) {
-	return ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name) && node.name.text === "value" && ts.isIdentifier(node.expression);
+/**
+* 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 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 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 detectVisit(ctx, node) {
+/**
+* `JSX.Element` (which is what JSX evaluates to) is already assignable to
+* `VNodeChild`. The `as unknown as VNodeChild` double-cast is unnecessary
+* — it's been showing up in `@pyreon/ui-primitives` as a defensive habit
+* carried over from earlier framework versions. The cast is never load-
+* bearing today; removing it never changes runtime behavior. Pure cosmetic
+* but a useful proxy for non-idiomatic Pyreon code in primitives.
+*/
+function detectAsUnknownAsVNodeChild(ctx, node) {
+	const outerType = node.type;
+	if (!ts.isTypeReferenceNode(outerType)) return;
+	if (!ts.isIdentifier(outerType.typeName) || outerType.typeName.text !== "VNodeChild") return;
+	const inner = node.expression;
+	if (!ts.isAsExpression(inner)) return;
+	if (inner.type.kind !== ts.SyntaxKind.UnknownKeyword) return;
+	pushDiag(ctx, node, "as-unknown-as-vnodechild", "`as unknown as VNodeChild` is unnecessary — `JSX.Element` (the type produced by JSX) is already assignable to `VNodeChild`. Remove the double cast; it is pure noise that hides genuine type issues if they ever appear at this site.", getNodeText(ctx, node), getNodeText(ctx, inner.expression), false);
+}
+/**
+* Pre-pass: walk the source for `island(loader, { name: 'X', hydrate: 'never' })`
+* call expressions and collect the `name` field of each never-strategy island.
+*
+* Recognized shape (mirrors `@pyreon/vite-plugin`'s `scanIslandDeclarations`):
+*
+*   island(() => import('./X'), { name: 'X', hydrate: 'never' })
+*
+* Edge cases the AST-walker deliberately doesn't cover (unrecognized calls
+* fall through and don't populate the set — false-negatives, not false
+* positives):
+*
+*   - Loader is a variable, not an inline arrow
+*   - Name is a variable / template / spread, not a string literal
+*   - Options come from a spread (`island(loader, opts)`)
+*
+* The same rules apply on the registry side (`detectIslandNeverWithRegistry`):
+* unrecognized keys won't match. Both halves are syntactic — a semantic
+* cross-package audit lives in `pyreon doctor --check-islands` (separate PR).
+*/
+function collectNeverIslandNames(sf) {
+	const names = /* @__PURE__ */ new Set();
+	function walk(node) {
+		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "island" && node.arguments.length >= 2) {
+			const opts = node.arguments[1];
+			if (opts && ts.isObjectLiteralExpression(opts)) {
+				let nameVal;
+				let hydrateVal;
+				for (const prop of opts.properties) {
+					if (!ts.isPropertyAssignment(prop)) continue;
+					const key = prop.name;
+					const keyText = ts.isIdentifier(key) ? key.text : ts.isStringLiteral(key) ? key.text : "";
+					if (keyText === "name" && ts.isStringLiteral(prop.initializer)) nameVal = prop.initializer.text;
+					else if (keyText === "hydrate" && ts.isStringLiteral(prop.initializer)) hydrateVal = prop.initializer.text;
+				}
+				if (nameVal && hydrateVal === "never") names.add(nameVal);
+			}
+		}
+		ts.forEachChild(node, walk);
+	}
+	walk(sf);
+	return names;
+}
+/**
+* Flag entries in `hydrateIslands({ X: () => import('./X'), ... })` whose
+* key matches an `island()` name declared with `hydrate: 'never'` in the
+* same file. Each matching entry produces one diagnostic at the property's
+* location so the IDE highlights exactly which key needs to go.
+*/
+function detectIslandNeverWithRegistry(ctx, node) {
+	if (ctx.neverIslandNames.size === 0) return;
+	const callee = node.expression;
+	if (!ts.isIdentifier(callee) || callee.text !== "hydrateIslands") return;
+	const arg = node.arguments[0];
+	if (!arg || !ts.isObjectLiteralExpression(arg)) return;
+	for (const prop of arg.properties) {
+		if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) continue;
+		const key = prop.name;
+		const keyText = ts.isIdentifier(key) ? key.text : ts.isStringLiteral(key) ? key.text : "";
+		if (!keyText || !ctx.neverIslandNames.has(keyText)) continue;
+		pushDiag(ctx, prop, "island-never-with-registry-entry", `island "${keyText}" was declared with \`hydrate: 'never'\` and MUST NOT be registered in \`hydrateIslands({ ... })\`. The whole point of the \`'never'\` strategy is shipping zero client JS — registering pulls the component module into the client bundle graph (the runtime short-circuits never-strategy before the registry lookup, but the bundler still includes the import). Drop this entry; the framework handles never-strategy islands at SSR with no client-side wiring.`, getNodeText(ctx, prop), `// remove the "${keyText}" entry — never-strategy islands need no registry entry`, false);
+	}
+}
+function visitNode(ctx, node) {
+	if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) detectForKeying(ctx, node);
+	if (ts.isArrowFunction(node) || ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) {
+		detectPropsDestructured(ctx, node);
+		detectPropsDestructuredBody(ctx, node);
+		detectStaticReturnNullConditional(ctx, node);
+	}
+	if (ts.isBinaryExpression(node)) {
+		detectProcessDevGate(ctx, node);
+		detectDateMathRandomId(ctx, node);
+	}
+	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 visit(ctx, node) {
 	ts.forEachChild(node, (child) => {
-		detectVisitNode(ctx, child);
-		detectVisit(ctx, child);
+		visitNode(ctx, child);
+		visit(ctx, child);
 	});
 }
-function detectReactPatterns(code, filename = "input.tsx") {
+function detectPyreonPatterns(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: collectSignalBindings(sf),
+		neverIslandNames: collectNeverIslandNames(sf)
 	};
-	detectVisit(ctx, sf);
+	visit(ctx, sf);
+	ctx.diagnostics.sort((a, b) => a.line - b.line || a.column - b.column);
 	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
-	});
+/** 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);
 }
-function migrateGetNodeText(ctx, node) {
-	return ctx.code.slice(node.getStart(ctx.sf), node.getEnd());
+
+//#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
+	};
 }
-function migrateGetLine(ctx, node) {
-	return ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf)).line + 1;
+/**
+* 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 = [];
+	}
+	const findings = spans.map(spanToFinding);
+	let footguns = [];
+	try {
+		footguns = detectPyreonPatterns(code, filename);
+	} catch {
+		footguns = [];
+	}
+	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 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);
+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);
+	}
+	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}`);
 		}
 	}
-	ctx.importsToRemove.add(node);
+	return out.join("\n");
 }
-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 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)"
-		});
-	}
-}
-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 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)"
-		});
-	}
-}
-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)"
-		});
-	}
+
+//#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 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 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 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$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)`
+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)
 				});
 			}
 		}
 	}
-	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"
-		});
-	}
+	return routes;
 }
-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"
-		});
-	}
-	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;
+function extractComponents(files, cwd) {
+	const components = [];
+	for (const file of files) {
+		let code;
+		try {
+			code = fs.readFileSync(file, "utf-8");
+		} catch {
+			continue;
 		}
-		if (!overlaps && !applied.has(key)) {
-			applied.add(key);
-			deduped.push(r);
+		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
+			});
 		}
 	}
-	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("");
-}
-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) => {
-		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 components;
 }
-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 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 null;
-}
-function getJsxTagName$1(node) {
-	const tagName = node.tagName;
-	if (ts.isIdentifier(tagName)) return tagName.text;
-	return "";
+	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
@@ -4019,5 +4838,5 @@ function formatSsgAudit(result, _options = {}) {
 }
 
 //#endregion
-export { auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, transformDeferInline, transformJSX, transformJSX_JS };
+export { analyzeReactivity, auditIslands, auditSsg, auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatIslandAudit, formatReactivityLens, formatSsgAudit, formatTestAudit, generateContext, hasPyreonPatterns, hasReactPatterns, migrateReactCode, rocketstyleCollapseKey, scanCollapsibleSites, transformDeferInline, transformJSX, transformJSX_JS };
 //# sourceMappingURL=index.js.map