@ozsarman/clarityjs 0.6.0

package/src/codegen.js

@@ -0,0 +1,1934 @@
+/**
+ * Clarity.js Code Generator
+ *
+ * Transforms a Clarity AST into vanilla JavaScript that uses the Clarity runtime.
+ * Output is clean, readable, and debuggable — not minified soup.
+ * Every generated line is traceable to the original .clarity source.
+ *
+ * Author: Claude (Anthropic)
+ */
+
+import { processSourceMarkers } from './sourcemap.js';
+
+// ─── Signal method names ──────────────────────────────────────────────────────
+// These are the built-in methods of a Clarity signal object.
+// When we see signal.METHOD(...) in statement context we must NOT wrap the signal
+// receiver with .get() — the caller wants the signal itself, not its value.
+const _SIGNAL_METHODS = new Set(['get', 'set', 'update', 'peek', 'subscribe']);
+
+// ─── CodegenError ─────────────────────────────────────────────────────────────
+export class CodegenError extends Error {
+  constructor(message, node) {
+    super(
+      `[Clarity Codegen] ${message}\n` +
+      `  → Node: ${node?.type ?? 'unknown'} at ${node?.loc?.line ?? '?'}:${node?.loc?.col ?? '?'}\n` +
+      `  LLM-hint: This is likely a parser output mismatch. Check the AST node type.`
+    );
+    this.name = 'CodegenError';
+    this.node = node;
+  }
+}
+
+// ─── Code Generator ───────────────────────────────────────────────────────────
+export class CodeGenerator {
+  constructor(options = {}) {
+    this.runtimePath    = options.runtimePath ?? './clarity-runtime.js';
+    this.routerPath     = options.routerPath  ?? './clarity-router.js';
+    this.sourceMap      = options.sourceMap   ?? false;
+    this.sourceFile     = options.sourceFile  ?? '<anonymous>';
+    this.outputFile     = options.outputFile  ?? '<output>';
+    this.sourceContent  = options.sourceContent ?? '';
+    this._indent        = 0;
+    this._output        = [];
+    this._usedRuntime   = new Set();
+    this._usedRouter    = new Set(); // router symbols used in this file
+  }
+
+  generate(ast) {
+    this._output    = [];
+    this._usedRuntime = new Set(['signal', 'effect', 'computed', 'h', 'appendChild', 'mount', 'batch', '_callCleanup']);
+    this._usedRouter  = new Set();
+
+    // Collect store names so they can be injected into every component's signal list
+    const storeDecls = ast.stores ?? [];
+    this._storeNames = storeDecls.map(s => s.name);
+
+    // Process all components — only the last one gets `export default`
+    const lastIdx = ast.components.length - 1;
+    const componentCode = ast.components.map((c, i) => this._genComponent(c, i === lastIdx)).join('\n\n');
+
+    // Build header with runtime imports
+    const runtimeImports = `import { ${[...this._usedRuntime].join(', ')} } from '${this.runtimePath}';`;
+
+    // Router imports — only emitted when the file uses <Route> / <Link> / navigate
+    // Internal names are aliased to avoid conflicts with user-defined variables.
+    const routerAlias = {
+      navigate:        '_clarityNavigate',
+      navigateReplace: '_clarityNavReplace',
+      currentPath:     '_clarityCurrentPath',
+      routeParams:     '_clarityRouteParams',
+      matchRoute:      '_clarityMatchRoute',
+      Switch:          '_claritySwitch',
+      Outlet:          '_clarityOutlet',
+      beforeEnter:     '_clarityBeforeEnter',
+    };
+    let routerImports = '';
+    if (this._usedRouter.size > 0) {
+      const needed = [...this._usedRouter].map(alias => {
+        const original = Object.entries(routerAlias).find(([, v]) => v === alias)?.[0] ?? alias;
+        return `${original} as ${alias}`;
+      });
+      routerImports = `import { ${needed.join(', ')} } from '${this.routerPath}';`;
+    }
+
+    // User imports
+    const userImports = ast.imports.map(i => this._genImport(i)).join('\n');
+
+    // Store declarations — emitted as exported signals before components
+    const storeCode = storeDecls.length > 0
+      ? storeDecls.map(s => `export const ${s.name} = signal(${this._genExpr(s.init)});`).join('\n')
+      : null;
+
+    const parts = [
+      `// Generated by Clarity.js compiler v0.1.0`,
+      `// DO NOT EDIT — edit the .clarity source file instead`,
+      ``,
+      runtimeImports,
+      routerImports || null,
+      userImports,
+      ``,
+      storeCode || null,
+      storeCode ? `` : null,
+      componentCode,
+    ].filter(p => p !== null);
+
+    const annotatedCode = parts.join('\n');
+
+    // Strip //@ SM:N markers and build V3 source map if requested
+    if (this.sourceMap) {
+      return processSourceMarkers(annotatedCode, {
+        filename:      this.outputFile,
+        sourceFile:    this.sourceFile,
+        sourceContent: this.sourceContent,
+        inline:        true,
+      });
+    }
+
+    // Without source maps: strip markers silently (they're just comments anyway,
+    // but cleaner output without them). Allow leading whitespace (indented markers).
+    const cleanCode = annotatedCode.replace(/^\s*\/\/@ SM:\d+\s*\n?/gm, '');
+    return { code: cleanCode, map: null };
+  }
+
+  // ── Import ──
+  _genImport(node) {
+    const names = node.names.join(', ');
+    return `import { ${names} } from '${node.source}';`;
+  }
+
+  // ── Component ──
+  _genComponent(comp, isLast = true) {
+    // Param names (without children) — used for duck-typing reactive props
+    const compParamNames = comp.params.map(p => p.name);
+
+    // Collect scoped style blocks
+    const styleBlocks = comp.body.filter(n => n.type === 'StyleBlock');
+    const hasScopedCSS = styleBlocks.length > 0;
+    const scopeClass   = `_c-${comp.name}`; // e.g. _c-Button
+
+    // Separate body nodes by type
+    const stateDecls      = comp.body.filter(n => n.type === 'StateDecl');
+    const asyncStateDecls = comp.body.filter(n => n.type === 'AsyncStateDecl');
+    const refDecls        = comp.body.filter(n => n.type === 'RefDecl');
+    const computedDecls   = comp.body.filter(n => n.type === 'ComputedDecl');
+    const effectDecls     = comp.body.filter(n => n.type === 'EffectDecl');
+    const renderBlock     = comp.body.find(n => n.type === 'RenderBlock');
+    const serverBlock     = comp.body.find(n => n.type === 'ServerBlock');
+    // Names declared via `data name = expr` inside server { } — these will be
+    // pre-populated by the server runner and passed as __ssr prop.
+    const serverVarNames  = new Set(serverBlock?.data?.map(d => d.name) ?? []);
+
+    // Destructured prop list — always include 'children' so <slot /> works.
+    // When the component has a server block we also destructure __ssr so that
+    // signal initialisers can reference it: signal(__ssr?.posts ?? [])
+    const destructuredParams = [...compParamNames, 'children'];
+    if (serverVarNames.size > 0) destructuredParams.push('__ssr');
+    const paramStr = `{ ${destructuredParams.join(', ')} } = {}`;
+
+    const aiDecls         = comp.body.filter(n => n.type === 'AIDecl');
+    const beforeMountBlocks = comp.body.filter(n => n.type === 'BeforeMountBlock');
+    const onMountBlocks   = comp.body.filter(n => n.type === 'OnMountBlock');
+    const onCleanupBlocks = comp.body.filter(n => n.type === 'OnCleanupBlock');
+    const actionDecls     = comp.body.filter(n => n.type === 'ActionDecl');
+    const hasLifecycle    = beforeMountBlocks.length > 0 || onMountBlocks.length > 0 || onCleanupBlocks.length > 0;
+
+    // All reactive names (state signals + computed signals + refs + async state signals + stores)
+    // — used for .get() codegen
+    const asyncStateSignalNames = asyncStateDecls.flatMap(a => [
+      a.name,
+      `${a.name}Loading`,
+      `${a.name}Error`,
+    ]);
+    const signalNames = [
+      ...stateDecls.map(s => s.name),
+      ...asyncStateSignalNames,
+      ...refDecls.map(r => r.name),
+      ...computedDecls.map(c => c.name),
+      ...(this._storeNames ?? []),
+    ];
+    // Store on instance so _genAssignTarget and _genStmt can reach them
+    this._currentSignals = signalNames;
+    this._currentParams  = compParamNames;
+
+    const lines = [];
+    const sm = (loc) => loc?.line ? `//@ SM:${loc.line}` : null;  // source map marker helper
+
+    sm(comp.loc) && lines.push(sm(comp.loc));
+    lines.push(`export function ${comp.name}(${paramStr}) {`);
+    this._indent++;
+
+    // Effect disposer tracking — collect all effect() return values so we can
+    // dispose them on unmount and avoid memory leaks.
+    lines.push(this._i(`const _disposes = [];`));
+    lines.push(this._i(`const _e = (d) => { _disposes.push(d); return d; };`));
+    lines.push('');
+
+    // CSS Scoping — inject component-scoped <style> once into document.head.
+    // Each CSS selector is prefixed with ._c-ComponentName so rules are isolated.
+    // The style tag is identified by a unique id so it is only injected once
+    // even when multiple instances of the component are mounted.
+    if (hasScopedCSS) {
+      const rawCSS    = styleBlocks.map(s => s.css).join('\n');
+      const scopedCSS = this._scopeCSS(rawCSS, `.${scopeClass}`);
+      const cssLiteral = JSON.stringify(scopedCSS);
+      lines.push(this._i(`// Scoped CSS — injected once per component type`));
+      lines.push(this._i(`if (!document.getElementById('clarity-scope-${comp.name}')) {`));
+      this._indent++;
+      lines.push(this._i(`const _style = document.createElement('style');`));
+      lines.push(this._i(`_style.id = 'clarity-scope-${comp.name}';`));
+      lines.push(this._i(`_style.textContent = ${cssLiteral};`));
+      lines.push(this._i(`document.head.appendChild(_style);`));
+      this._indent--;
+      lines.push(this._i(`}`));
+      lines.push('');
+    }
+
+    // AI contract (as JSDoc comment for tooling)
+    if (aiDecls.length > 0) {
+      lines.push(this._i(`// AI Contract`));
+      for (const ai of aiDecls) {
+        lines.push(this._i(`// ai:${ai.capability} = [${ai.targets.join(', ')}]`));
+      }
+      lines.push('');
+    }
+
+    // State declarations → signals
+    // Forbidden signals are wrapped with _protectedSignal() so AI actions can't write them.
+    // Server-seeded signals use __ssr?.name (passed from the server runner) as the
+    // initial value, falling back to the declared default on the client.
+    const forbDecl0  = aiDecls.find(a => a.capability === 'forbidden');
+    const forbNames  = new Set(forbDecl0 ? forbDecl0.targets : []);
+    if (stateDecls.length > 0) {
+      lines.push(this._i(`// State`));
+      for (const s of stateDecls) {
+        sm(s.loc) && lines.push(this._i(sm(s.loc)));
+        // Compute the initial-value expression — server-seeded signals prefer __ssr
+        const defaultExpr = this._genExpr(s.init);
+        const initExpr = serverVarNames.has(s.name)
+          ? `(__ssr !== undefined && __ssr.${s.name} !== undefined) ? __ssr.${s.name} : ${defaultExpr}`
+          : defaultExpr;
+        if (forbNames.has(s.name)) {
+          // Wrap with _protectedSignal for runtime AI permission enforcement
+          lines.push(this._i(`const ${s.name} = _protectedSignal(signal(${initExpr}), '${comp.name}', '${s.name}');`));
+          this._usedRuntime.add('_protectedSignal');
+        } else {
+          lines.push(this._i(`const ${s.name} = signal(${initExpr});`));
+        }
+      }
+      lines.push('');
+    }
+
+    // Async state declarations → data signal + loading + error signals
+    if (asyncStateDecls.length > 0) {
+      lines.push(this._i(`// Async State`));
+      for (const a of asyncStateDecls) {
+        sm(a.loc) && lines.push(this._i(sm(a.loc)));
+        lines.push(this._i(`const ${a.name} = signal(${this._genExpr(a.init)});`));
+        lines.push(this._i(`const ${a.name}Loading = signal(true);`));
+        lines.push(this._i(`const ${a.name}Error = signal("");`));
+      }
+      lines.push('');
+    }
+
+    // Ref declarations → signal(null) that gets auto-populated when element is created
+    if (refDecls.length > 0) {
+      lines.push(this._i(`// Refs`));
+      for (const r of refDecls) {
+        sm(r.loc) && lines.push(this._i(sm(r.loc)));
+        lines.push(this._i(`const ${r.name} = signal(null);`));
+      }
+      lines.push('');
+    }
+
+    // Computed declarations
+    if (computedDecls.length > 0) {
+      lines.push(this._i(`// Computed`));
+      for (const c of computedDecls) {
+        sm(c.loc) && lines.push(this._i(sm(c.loc)));
+        // FIX: use _genExprRead so signal refs inside computed bodies call .get()
+        lines.push(this._i(`const ${c.name} = computed(() => ${this._genExprRead(c.expr, signalNames)});`));
+      }
+      lines.push('');
+    }
+
+    // Effect declarations
+    if (effectDecls.length > 0) {
+      lines.push(this._i(`// Effects`));
+      for (const eff of effectDecls) {
+        sm(eff.loc) && lines.push(this._i(sm(eff.loc)));
+        lines.push(...this._genEffect(eff));
+      }
+      lines.push('');
+    }
+
+    // Render block → DOM construction
+    if (renderBlock) {
+      lines.push(this._i(`// Render`));
+      // Pass state+computed names AND param names; params use duck-typing (.get() if signal)
+      const [renderLines, rootVar] = this._genJSX(renderBlock.root, signalNames, { n: 0 }, compParamNames);
+      lines.push(...renderLines.map(l => this._i(l)));
+
+      // Apply the scope class to the root element so scoped CSS rules match
+      if (hasScopedCSS) {
+        lines.push(this._i(`if (${rootVar} instanceof Element) ${rootVar}.classList.add('${scopeClass}');`));
+      }
+      lines.push('');
+
+      // Lifecycle hooks — attached to root element as special properties.
+      // mount() in the runtime calls __clarity_mount__ after DOM insertion,
+      // and returns an unmount() that calls __clarity_cleanup__.
+      if (onMountBlocks.length > 0) {
+        lines.push(this._i(`// onMount — runs after component is inserted into the DOM`));
+        lines.push(this._i(`${rootVar}.__clarity_mount__ = () => {`));
+        this._indent++;
+        for (const block of onMountBlocks) {
+          for (const stmt of this._genBlockStmts(block.body.body)) {
+            lines.push(this._i(stmt));
+          }
+        }
+        this._indent--;
+        lines.push(this._i(`};`));
+        lines.push('');
+      }
+
+      if (onCleanupBlocks.length > 0 || true /* always generate cleanup for effect disposal */) {
+        lines.push(this._i(`// onCleanup — runs on unmount, disposes all reactive effects`));
+        lines.push(this._i(`${rootVar}.__clarity_cleanup__ = () => {`));
+        this._indent++;
+        // User-defined cleanup code
+        for (const block of onCleanupBlocks) {
+          for (const stmt of this._genBlockStmts(block.body.body)) {
+            lines.push(this._i(stmt));
+          }
+        }
+        // Always dispose all tracked effects
+        lines.push(this._i(`_disposes.forEach(d => d());`));
+        this._indent--;
+        lines.push(this._i(`};`));
+        lines.push('');
+      }
+
+      // Action declarations — AI-callable functions
+      // Each `action name(params) { body }` becomes a plain JS function that
+      // closes over the component's state signals. The AI bridge calls them
+      // through act() with full audit instrumentation.
+      if (actionDecls.length > 0) {
+        lines.push(this._i(`// AI Actions`));
+        for (const a of actionDecls) {
+          const paramList = a.params.join(', ');
+          lines.push(this._i(`function ${a.name}(${paramList}) {`));
+          this._indent++;
+          for (const stmt of this._genBlockStmts(a.body.body)) {
+            lines.push(this._i(stmt));
+          }
+          this._indent--;
+          lines.push(this._i(`}`));
+        }
+        lines.push('');
+      }
+
+      // AI Runtime Bridge ─────────────────────────────────────────────────────
+      // Attaches __clarity_ai__ to the root element so AI agents can:
+      //   contract.readable['field']()       → audited read of declared-readable state
+      //   contract.snapshot()                → audited snapshot of all readable state
+      //   contract.act('name', ...args)      → audited, guarded action call
+      //   contract.forbidden                 → list of off-limits field names
+      //   contract.batch(fn)                 → multiple actions as one atomic audit entry
+      if (aiDecls.length > 0 || actionDecls.length > 0) {
+        lines.push(this._i(`// AI Runtime Bridge`));
+        lines.push(this._i(`${rootVar}.__clarity_ai__ = {`));
+        this._indent++;
+        lines.push(this._i(`component: '${comp.name}',`));
+
+        // readable — audited getters for each declared-readable signal
+        const readDecl = aiDecls.find(a => a.capability === 'readable');
+        if (readDecl) {
+          const entries = readDecl.targets.map(t => {
+            const base = t.split('.')[0];
+            return `'${t}': () => { _aiAuditRecord({ type: 'read', component: '${comp.name}', field: '${t}', value: ${base}.get() }); return ${base}.get(); }`;
+          }).join(', ');
+          lines.push(this._i(`readable: { ${entries} },`));
+          // snapshot — reads all readable fields at once, logged as a single entry
+          const snapFields = readDecl.targets.map(t => {
+            const base = t.split('.')[0];
+            return `'${t}': ${base}.get()`;
+          }).join(', ');
+          lines.push(this._i(`snapshot: () => { const _s = { ${snapFields} }; _aiAuditRecord({ type: 'snapshot', component: '${comp.name}', value: _s }); return _s; },`));
+          this._usedRuntime.add('_aiAuditRecord');
+        } else {
+          lines.push(this._i(`readable: {},`));
+          lines.push(this._i(`snapshot: () => ({}),`));
+        }
+
+        // read(field) — the single sanctioned read entrypoint for agents. Returns
+        // a declared-readable value, or throws ClarityAIForbiddenError (audited)
+        // for forbidden / undeclared fields.
+        lines.push(this._i(`read(name) { if (Object.prototype.hasOwnProperty.call(this.readable, name)) return this.readable[name](); _aiThrowForbidden('${comp.name}', name, 'read'); },`));
+        this._usedRuntime.add('_aiThrowForbidden');
+
+        // actionable — callable action functions, each wrapped with audit + context guard
+        // Prefers explicit `action` declarations; falls back to ai:actionable targets.
+        const actDecl = aiDecls.find(a => a.capability === 'actionable');
+        const explicitActionNames = actionDecls.map(a => a.name);
+        const declaredActionNames = actDecl ? actDecl.targets : [];
+        // Merge: explicit action declarations + ai:actionable references
+        const allActionNames = [...new Set([...explicitActionNames, ...declaredActionNames])];
+
+        if (allActionNames.length > 0) {
+          const entries = allActionNames.map(t =>
+            `'${t}': (...args) => { ` +
+            `_aiAuditRecord({ type: 'act', component: '${comp.name}', action: '${t}', args }); ` +
+            `_setAIActionContext(true); ` +
+            `try { return ${t}(...args); } finally { _setAIActionContext(false); } }`
+          ).join(', ');
+          lines.push(this._i(`actionable: { ${entries} },`));
+          lines.push(this._i(`act(name, ...args) {`));
+          this._indent++;
+          lines.push(this._i(`if (name in this.actionable) return this.actionable[name](...args);`));
+          lines.push(this._i(`_aiAuditRecord({ type: 'unknown_action', component: '${comp.name}', action: name });`));
+          lines.push(this._i(`throw new Error('[Clarity AI] Unknown action \\'' + name + '\\' on ${comp.name}. Declared: ${allActionNames.join(', ')}');`));
+          this._indent--;
+          lines.push(this._i(`},`));
+          this._usedRuntime.add('_aiAuditRecord');
+          this._usedRuntime.add('_setAIActionContext');
+        } else {
+          lines.push(this._i(`actionable: {},`));
+          lines.push(this._i(`act(name) { _aiAuditRecord({ type: 'unknown_action', component: '${comp.name}', action: name }); throw new Error('[Clarity AI] No actions declared on ${comp.name}'); },`));
+          this._usedRuntime.add('_aiAuditRecord');
+        }
+
+        // batch — execute multiple actions as one logical unit
+        lines.push(this._i(`batch(fn) { return fn(this); },`));
+
+        // forbidden — field names AI must never read or write
+        const forbList2 = forbNames.size > 0
+          ? [...forbNames].map(t => `'${t}'`).join(', ')
+          : '';
+        lines.push(this._i(`forbidden: [${forbList2}],`));
+
+        this._indent--;
+        lines.push(this._i(`};`));
+        lines.push('');
+      }
+
+      // beforeMount — runs after the root node is built but BEFORE it is
+      // returned/inserted into the DOM (Vue onBeforeMount semantics).
+      if (beforeMountBlocks.length > 0) {
+        lines.push(this._i(`// beforeMount — runs after render, before DOM insertion`));
+        for (const block of beforeMountBlocks) {
+          for (const stmt of this._genBlockStmts(block.body.body)) {
+            lines.push(this._i(stmt));
+          }
+        }
+        lines.push('');
+      }
+
+      lines.push(this._i(`return ${rootVar};`));
+    } else {
+      lines.push(this._i(`return document.createComment('${comp.name}: no render block');`));
+    }
+
+    this._indent--;
+    lines.push(`}`);
+    lines.push('');
+
+    // __clarity_server__ — async data loader called by renderToStringAsync (SSR).
+    // Receives the same props as the component, runs all `data name = expr` bindings
+    // (which may use `await`), and returns a plain object { name: value, ... }.
+    // The result is passed back as the __ssr prop so signal initialisers can pick it up.
+    if (serverBlock && serverBlock.data && serverBlock.data.length > 0) {
+      const paramDestructure = compParamNames.length > 0
+        ? `const { ${compParamNames.join(', ')} } = _props;`
+        : '';
+      lines.push(`${comp.name}.__clarity_server__ = async function(_props = {}, _ctx = {}) {`);
+      this._indent++;
+      if (paramDestructure) lines.push(this._i(paramDestructure));
+      for (const d of serverBlock.data) {
+        lines.push(this._i(`const ${d.name} = ${this._genExpr(d.init)};`));
+      }
+      const returnFields = serverBlock.data.map(d => d.name).join(', ');
+      lines.push(this._i(`return { ${returnFields} };`));
+      this._indent--;
+      lines.push(`};`);
+      lines.push('');
+    }
+
+    if (isLast) lines.push(`export default ${comp.name};`);
+
+    return lines.join('\n');
+  }
+
+  // ── Effect ──
+  _genEffect(eff) {
+    const lines = [];
+    const bodyLines = this._genBlockStmts(eff.body.body);
+
+    // Wrap with _e() so the dispose function is tracked for cleanup on unmount
+    lines.push(this._i(`_e(effect(() => {`));
+    this._indent++;
+
+    // Read each dependency to subscribe
+    for (const dep of eff.deps) {
+      lines.push(this._i(`const _${dep} = ${dep}.get(); // tracked`));
+    }
+
+    for (const stmt of bodyLines) {
+      lines.push(this._i(stmt));
+    }
+
+    this._indent--;
+    lines.push(this._i(`}));`));
+    return lines;
+  }
+
+  // ── JSX → h() calls ──
+  // Returns [lines, varName]
+  // params: component param names that may receive signals — use duck-typing
+  _genJSX(jsxNode, signals = [], counter = { n: 0 }, params = []) {
+    if (!jsxNode) return [[], 'null'];
+
+    const varName = `_el${counter.n++}`;
+
+    if (jsxNode.type === 'JSXText') {
+      // The parser already collapses internal whitespace and adds at most one
+      // boundary space; preserve it so inline text spacing is correct
+      // (e.g. "The " + <span> + " framework"). Do NOT trim here.
+      const escaped = JSON.stringify(jsxNode.value);
+      return [[`const ${varName} = document.createTextNode(${escaped});`], varName];
+    }
+
+    if (jsxNode.type === 'JSXExpr') {
+      // Reactive expression → text node with effect
+      // Generate the expression in "read" mode (signals use .get())
+      const expr = this._genExprRead(jsxNode.expr, signals, params);
+      const isSignalRef = this._exprReadsSignals(jsxNode.expr, signals, params);
+
+      if (isSignalRef) {
+        return [
+          [
+            `const ${varName} = document.createTextNode('');`,
+            `_e(effect(() => { ${varName}.textContent = String(${expr}); }));`,
+          ],
+          varName,
+        ];
+      } else {
+        return [[`const ${varName} = document.createTextNode(String(${expr}));`], varName];
+      }
+    }
+
+    if (jsxNode.type !== 'JSXElement') {
+      return [[`const ${varName} = document.createComment('unknown node');`], varName];
+    }
+
+    const tag = jsxNode.tag;
+
+    // ── Built-in directives ──────────────────────────────────────────────────
+
+    // <slot /> or <slot name="header" /> or <slot name="row" :data="item" />
+    // Renders children passed from the parent component into a DocumentFragment.
+    //
+    // Children are now passed as:
+    //   { default: [...], header: [...], footer: [...] }
+    // for named slots.  A legacy flat-array format is also accepted for backward
+    // compat with old-style  children: [...]  usage.
+    //
+    // SCOPED SLOTS — if the slot has a :data attribute (or any :propName attr),
+    // the slot content is treated as a render function that receives the data:
+    //
+    //   Component body:   <slot name="row" :data="item" />
+    //   Generated code:   children.row(item)  (returns Node[])
+    //
+    //   Parent template:  <template slot="row" let:data> <td>{data.name}</td> </template>
+    //   Generated code:   row: (data) => [<rendered nodes>]
+    //
+    // Usage inside a component:
+    //   <slot />                       → renders children.default (array)
+    //   <slot name="header" />         → renders children.header (array)
+    //   <slot name="row" :data="item"> → calls children.row(item) (function)
+    if (tag === 'slot') {
+      const nameAttr  = jsxNode.attrs.find(a => a.name === 'name');
+      const slotName  = nameAttr?.value?.type === 'Literal' ? nameAttr.value.value : null;
+
+      // Detect scoped slot (:data="expr" or any :propName="expr")
+      const dataAttr = jsxNode.attrs.find(
+        a => a.type === 'Attr' && a.name.startsWith(':') && a.name !== ':key'
+      );
+
+      if (dataAttr) {
+        // Scoped slot — children.slotName is a render function
+        const dataExpr    = this._genExprRead(dataAttr.value, signals, params);
+        const slotFnExpr  = slotName ? `children?.${slotName}` : `children?.default`;
+        const lines = [
+          `const ${varName} = document.createDocumentFragment();`,
+          `if (typeof ${slotFnExpr} === 'function') {`,
+          `  const _scopedNodes = [${slotFnExpr}(${dataExpr})].flat(Infinity);`,
+          `  _scopedNodes.forEach(_n => _n && ${varName}.appendChild(_n));`,
+          `} else if (Array.isArray(${slotFnExpr})) {`,
+          `  ${slotFnExpr}.forEach(_c => _c && ${varName}.appendChild(_c));`,
+          `}`,
+        ];
+        return [lines, varName];
+      }
+
+      // Regular slot — children is an array
+      const contentExpr = slotName
+        ? `(children?.${slotName} ?? [])`
+        : `(children?.default ?? (Array.isArray(children) ? children : []))`;
+      return [
+        [
+          `const ${varName} = document.createDocumentFragment();`,
+          `(Array.isArray(${contentExpr}) ? ${contentExpr} : [${contentExpr}]).forEach(_c => _c && ${varName}.appendChild(_c));`,
+        ],
+        varName,
+      ];
+    }
+
+    // <when cond={expr}> thenChild </when>
+    // <when cond={expr}> thenChild <else/> elseChild </when>
+    if (tag === 'when') {
+      // Support both `test` (documented API) and legacy `cond`
+      const condAttr = jsxNode.attrs.find(a => a.name === 'test' || a.name === 'cond');
+      const condExpr = condAttr ? this._genExprRead(condAttr.value, signals, params) : 'true';
+      const allLines2 = [];
+
+      // Split children at <else> marker.
+      // Two supported forms:
+      //   Form A (wrapping): <when><span>yes</span><else><span>no</span></else></when>
+      //                      → then = children before <else>, else = children of <else> node
+      //   Form B (self-close): <when><span>yes</span></when><else/><span>no</span>
+      //                        (not currently supported — Form A is canonical)
+      const elseIdx = jsxNode.children.findIndex(c => c.type === 'JSXElement' && c.tag === 'else');
+      const thenChildren = elseIdx >= 0 ? jsxNode.children.slice(0, elseIdx) : jsxNode.children;
+      // Else children are the children INSIDE the <else> element, not siblings after it
+      const elseEl       = elseIdx >= 0 ? jsxNode.children[elseIdx] : null;
+      const elseChildren = elseEl ? (elseEl.children ?? []) : [];
+
+      const whenN = counter.n;
+      allLines2.push(`const ${varName} = document.createComment('clarity:when');`);
+      allLines2.push(`let _when${whenN}_nodes = [];`);
+      // Defer so effect runs after the comment node is inserted into the DOM tree
+      allLines2.push(`queueMicrotask(() => _e(effect(() => {`);
+      allLines2.push(`  _when${whenN}_nodes.forEach(n => { n.parentNode?.removeChild(n); _callCleanup(n); });`);
+      allLines2.push(`  _when${whenN}_nodes = [];`);
+      allLines2.push(`  if (${condExpr}) {`);
+
+      const thenCounter = { n: counter.n + 100 };
+      for (const child of thenChildren) {
+        const [cl, cv] = this._genJSX(child, signals, thenCounter, params);
+        allLines2.push(...cl.map(l => '    ' + l));
+        allLines2.push(`    ${varName}.parentNode?.insertBefore(${cv}, ${varName});`);
+        allLines2.push(`    _when${whenN}_nodes.push(${cv});`);
+      }
+      counter.n = thenCounter.n;
+
+      if (elseChildren.length > 0) {
+        allLines2.push(`  } else {`);
+        const elseCounter = { n: counter.n + 200 };
+        for (const child of elseChildren) {
+          const [cl, cv] = this._genJSX(child, signals, elseCounter, params);
+          allLines2.push(...cl.map(l => '    ' + l));
+          allLines2.push(`    ${varName}.parentNode?.insertBefore(${cv}, ${varName});`);
+          allLines2.push(`    _when${whenN}_nodes.push(${cv});`);
+        }
+        counter.n = elseCounter.n;
+      }
+
+      allLines2.push(`  }`);
+      allLines2.push(`})));`);
+      this._usedRuntime.add('effect');
+      return [allLines2, varName];
+    }
+
+    // ── Error boundary ───────────────────────────────────────────────────────
+
+    // <catch fallback={expr}> risky children </catch>
+    // Wraps child rendering in try/catch. If any child throws during initial
+    // render, the fallback expression is rendered instead.
+    //
+    // Usage:
+    //   <catch fallback={ <p>Oops! Something broke.</p> }>
+    //     <UserProfile />
+    //   </catch>
+    if (tag === 'catch') {
+      const fallbackAttr = jsxNode.attrs.find(a => a.name === 'fallback');
+      const allLines2 = [];
+      const catchN = counter.n++;
+
+      allLines2.push(`const ${varName} = document.createComment('clarity:catch');`);
+      allLines2.push(`let _catch${catchN}_nodes = [];`);
+      allLines2.push(`const _catch${catchN}_remove = () => {`);
+      allLines2.push(`  _catch${catchN}_nodes.forEach(n => n.parentNode?.removeChild(n));`);
+      allLines2.push(`  _catch${catchN}_nodes = [];`);
+      allLines2.push(`};`);
+      allLines2.push(`try {`);
+
+      const tryCounter = { n: counter.n + 700 };
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXText' && !child.value.trim()) continue;
+        const [cl, cv] = this._genJSX(child, signals, tryCounter, params);
+        allLines2.push(...cl.map(l => '  ' + l));
+        allLines2.push(`  ${varName}.parentNode?.insertBefore(${cv}, ${varName});`);
+        allLines2.push(`  _catch${catchN}_nodes.push(${cv});`);
+      }
+      counter.n = tryCounter.n;
+
+      allLines2.push(`} catch (_err${catchN}) {`);
+      allLines2.push(`  _catch${catchN}_remove();`);
+
+      // Fallback: if fallback attr is an expression, evaluate it
+      if (fallbackAttr) {
+        const fbExpr = this._genExpr(fallbackAttr.value);
+        allLines2.push(`  const _fb${catchN} = (() => {`);
+        allLines2.push(`    try { const _v = ${fbExpr}; return typeof _v === 'string' ? document.createTextNode(_v) : _v; }`);
+        allLines2.push(`    catch (_) { return document.createTextNode('[render error]'); }`);
+        allLines2.push(`  })();`);
+        allLines2.push(`  ${varName}.parentNode?.insertBefore(_fb${catchN}, ${varName});`);
+        allLines2.push(`  _catch${catchN}_nodes.push(_fb${catchN});`);
+      } else {
+        // No fallback attr — render a default error text node
+        allLines2.push(`  const _fb${catchN} = document.createTextNode('[render error: ' + (_err${catchN}?.message ?? _err${catchN}) + ']');`);
+        allLines2.push(`  ${varName}.parentNode?.insertBefore(_fb${catchN}, ${varName});`);
+        allLines2.push(`  _catch${catchN}_nodes.push(_fb${catchN});`);
+      }
+
+      allLines2.push(`  if (typeof console !== 'undefined') console.error('[Clarity] <catch> boundary caught:', _err${catchN});`);
+      allLines2.push(`}`);
+      return [allLines2, varName];
+    }
+
+    // ── Router directives ────────────────────────────────────────────────────
+
+    // <Provider ctx={MyCtx} value={someValue}> children </Provider>
+    // Pushes a context value for all children during the synchronous render,
+    // then pops it after — equivalent to React <Context.Provider value={}>.
+    // If value is a signal, useContext() inside effects will track it reactively.
+    if (tag === 'Provider') {
+      const ctxAttr   = jsxNode.attrs.find(a => a.name === 'ctx');
+      const valAttr   = jsxNode.attrs.find(a => a.name === 'value');
+      const ctxExpr   = ctxAttr ? this._genExpr(ctxAttr.value) : 'undefined';
+      const valExpr   = valAttr ? this._genExpr(valAttr.value) : 'undefined';
+      const provN     = counter.n++;
+      const allLines2 = [];
+
+      allLines2.push(`_pushContext(${ctxExpr}, ${valExpr});`);
+      allLines2.push(`const ${varName} = document.createDocumentFragment();`);
+
+      const provCounter = { n: counter.n + 400 };
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXText' && !child.value.trim()) continue;
+        const [cl, cv] = this._genJSX(child, signals, provCounter, params);
+        allLines2.push(...cl);
+        allLines2.push(`if (${cv} instanceof Node) ${varName}.appendChild(${cv});`);
+      }
+      counter.n = provCounter.n;
+
+      allLines2.push(`_popContext(${ctxExpr});`);
+      this._usedRuntime.add('_pushContext');
+      this._usedRuntime.add('_popContext');
+      return [allLines2, varName];
+    }
+
+    // <Outlet /> — renders a placeholder where nested child routes appear.
+    // Equivalent to <Outlet> from React Router v6.
+    // In simple mode (no children) it just returns a comment anchor and the
+    // nested <Route> nodes rendered as siblings handle conditional display.
+    if (tag === 'Outlet') {
+      const outletN   = counter.n++;
+      const allLines2 = [];
+
+      const routesAttr   = jsxNode.attrs.find(a => a.name === 'routes');
+      const fallbackAttr = jsxNode.attrs.find(a => a.name === 'fallback');
+
+      if (routesAttr || fallbackAttr) {
+        // Advanced mode: explicit routes prop
+        const routesExpr   = routesAttr   ? this._genExpr(routesAttr.value)   : '[]';
+        const fallbackExpr = fallbackAttr ? this._genExpr(fallbackAttr.value) : 'null';
+        allLines2.push(`const ${varName} = _clarityOutlet({ routes: ${routesExpr}, fallback: ${fallbackExpr} });`);
+        this._usedRouter.add('_clarityOutlet');
+      } else {
+        // Simple mode: transparent comment anchor — nested routes render after it
+        allLines2.push(`const ${varName} = document.createComment('clarity:outlet');`);
+      }
+      return [allLines2, varName];
+    }
+
+    // <Route path="/about"> children </Route>
+    // Renders children only when the current hash path matches the pattern.
+    // Named params (:id) are injected as 'params' into child signals.
+    // v0.3 additions: guard={fn}, exact={true}
+    if (tag === 'Route') {
+      const pathAttr  = jsxNode.attrs.find(a => a.name === 'path');
+      const guardAttr = jsxNode.attrs.find(a => a.name === 'guard');
+      const exactAttr = jsxNode.attrs.find(a => a.name === 'exact');
+      const pattern   = pathAttr  ? this._genExpr(pathAttr.value)  : '"/"';
+      const guardExpr = guardAttr ? this._genExpr(guardAttr.value)  : 'null';
+      const exactExpr = exactAttr ? this._genExpr(exactAttr.value)  : 'false';
+      const routeN    = counter.n++;
+      const allLines2 = [];
+
+      allLines2.push(`const ${varName} = document.createComment('clarity:route(' + ${pattern} + ')');`);
+      allLines2.push(`let _route${routeN}_nodes = [];`);
+      // Defer route effect so it runs after mount() inserts the component into the DOM.
+      allLines2.push(`queueMicrotask(() => _e(effect(() => {`);
+      allLines2.push(`  const _rpath = _clarityCurrentPath.get();`);
+      // Support exact matching
+      allLines2.push(`  const _rparams = (${exactExpr})`);
+      allLines2.push(`    ? (() => { const _p = _clarityMatchRoute(${pattern}, _rpath); if (!_p) return null; const _pp = ${pattern}.split('/').filter(Boolean); const _ap = _rpath.split('/').filter(Boolean); return _pp.length === _ap.length ? _p : null; })()`);
+      allLines2.push(`    : _clarityMatchRoute(${pattern}, _rpath);`);
+      allLines2.push(`  _route${routeN}_nodes.forEach(n => n.parentNode?.removeChild(n));`);
+      allLines2.push(`  _route${routeN}_nodes = [];`);
+      allLines2.push(`  if (_rparams !== null) {`);
+      // Inline guard check
+      allLines2.push(`    const _guard${routeN} = ${guardExpr};`);
+      allLines2.push(`    if (typeof _guard${routeN} === 'function') {`);
+      allLines2.push(`      const _gr = _guard${routeN}({ path: _rpath, params: _rparams });`);
+      allLines2.push(`      if (_gr === false) return;`);
+      allLines2.push(`      if (typeof _gr === 'string') { _clarityNavigate(_gr); return; }`);
+      allLines2.push(`    }`);
+
+      const routeCounter = { n: counter.n + 600 };
+      const childSignals = [...signals, '_rparams'];
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXText' && !child.value.trim()) continue;
+        const [cl, cv] = this._genJSX(child, childSignals, routeCounter, params);
+        allLines2.push(...cl.map(l => '    ' + l));
+        allLines2.push(`    ${varName}.parentNode?.insertBefore(${cv}, ${varName});`);
+        allLines2.push(`    _route${routeN}_nodes.push(${cv});`);
+      }
+      counter.n = routeCounter.n;
+
+      allLines2.push(`  }`);
+      allLines2.push(`})));`);
+      this._usedRuntime.add('effect');
+      this._usedRouter.add('_clarityCurrentPath');
+      this._usedRouter.add('_clarityMatchRoute');
+      this._usedRouter.add('_clarityNavigate');
+      return [allLines2, varName];
+    }
+
+    // <Link to="/about"> label or children </Link>
+    // Renders an <a> element that calls navigate() on click.
+    // Adds 'clarity-link-active' class when the current path matches.
+    if (tag === 'Link') {
+      const toAttr    = jsxNode.attrs.find(a => a.name === 'to');
+      const toExpr    = toAttr ? this._genExpr(toAttr.value) : '"/"';
+      const linkN     = counter.n++;
+      const allLines2 = [];
+      const linkChildren = [];
+
+      for (const child of jsxNode.children) {
+        const [cl, cv] = this._genJSX(child, signals, counter, params);
+        allLines2.push(...cl);
+        linkChildren.push(cv);
+      }
+
+      allLines2.push(`const ${varName} = document.createElement('a');`);
+      allLines2.push(`${varName}.href = '#' + ${toExpr};`);
+      if (linkChildren.length > 0) {
+        allLines2.push(`[${linkChildren.join(', ')}].forEach(_c => ${varName}.appendChild(_c));`);
+      }
+      allLines2.push(`${varName}.addEventListener('click', (e) => { e.preventDefault(); _clarityNavigate(${toExpr}); });`);
+      allLines2.push(`_e(effect(() => {`);
+      allLines2.push(`  const _active = _clarityMatchRoute(${toExpr}, _clarityCurrentPath.get()) !== null;`);
+      allLines2.push(`  ${varName}.classList.toggle('clarity-link-active', _active);`);
+      allLines2.push(`  ${varName}.setAttribute('aria-current', _active ? 'page' : 'false');`);
+      allLines2.push(`}));`);
+      this._usedRuntime.add('effect');
+      this._usedRouter.add('_clarityNavigate');
+      this._usedRouter.add('_clarityCurrentPath');
+      this._usedRouter.add('_clarityMatchRoute');
+      return [allLines2, varName];
+    }
+
+    // <list items={signal} key="fieldName"> child template </list>
+    if (tag === 'list') {
+      const itemsAttr = jsxNode.attrs.find(a => a.name === 'items');
+      const itemsExpr = itemsAttr ? this._genExpr(itemsAttr.value) : '[]';
+      const keyAttr   = jsxNode.attrs.find(a => a.name === 'key');
+      const keyField  = keyAttr
+        ? (typeof keyAttr.value === 'object' && keyAttr.value.type === 'Literal' ? keyAttr.value.value : null)
+        : null;
+      const keyExpr   = keyField ? `String(item.${keyField})` : 'String(_idx)';
+      const keysExpr  = keyField
+        ? `_items.map((item) => String(item.${keyField}))`
+        : `_items.map((_, i) => String(i))`;
+      const allLines2 = [];
+      const listN = counter.n++;
+
+      allLines2.push(`const ${varName} = document.createComment('clarity:list');`);
+      // Map stores an ARRAY of nodes per key so fragment templates don't leak.
+      // Old design stored one node per key → if a template rendered siblings,
+      // only the last node was tracked and the rest were never removed (node leak).
+      allLines2.push(`const _list${listN}_map = new Map(); // key → Node[]`);
+      // Defer so effect runs after the comment node is inserted into the DOM tree
+      allLines2.push(`queueMicrotask(() => _e(effect(() => {`);
+      allLines2.push(`  const _items = ${itemsExpr}.get ? ${itemsExpr}.get() : ${itemsExpr};`);
+      allLines2.push(`  const _keys = ${keysExpr};`);
+      // Snapshot map entries to avoid mutation-during-iteration bugs
+      allLines2.push(`  for (const [k, nodes] of [..._list${listN}_map]) {`);
+      allLines2.push(`    if (!_keys.includes(k)) {`);
+      allLines2.push(`      nodes.forEach(_n => { _n.parentNode?.removeChild(_n); _callCleanup(_n); });`);
+      allLines2.push(`      _list${listN}_map.delete(k);`);
+      allLines2.push(`    }`);
+      allLines2.push(`  }`);
+      allLines2.push(`  _items.forEach((item, _idx) => {`);
+      allLines2.push(`    const _key = ${keyExpr};`);
+      allLines2.push(`    if (!_list${listN}_map.has(_key)) {`);
+      allLines2.push(`      const _list${listN}_batch = []; // all nodes for this key`);
+
+      // Generate template for each item — 'item' is a plain loop variable (not a signal).
+      // We pass it via params so duck-typing handles the case where array elements ARE signals.
+      const tmplCounter = { n: counter.n + 500 };
+      const itemParams  = [...params, 'item'];
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXText') continue;
+        const [cl, cv] = this._genJSX(child, signals, tmplCounter, itemParams);
+        allLines2.push(...cl.map(l => '      ' + l));
+        allLines2.push(`      ${varName}.parentNode?.insertBefore(${cv}, ${varName});`);
+        allLines2.push(`      _list${listN}_batch.push(${cv});`);
+      }
+      counter.n = tmplCounter.n;
+
+      allLines2.push(`      _list${listN}_map.set(_key, _list${listN}_batch);`);
+      allLines2.push(`    }`);
+      allLines2.push(`  });`);
+      allLines2.push(`})));`);
+      this._usedRuntime.add('effect');
+      return [allLines2, varName];
+    }
+
+    // ── Portal ──────────────────────────────────────────────────────────────────
+    //
+    // <portal target="body">  children  </portal>
+    // <portal target="#modal-root">  children  </portal>
+    //
+    // Renders children directly into  document.querySelector(target)  instead of
+    // the current DOM tree.  This lets modal overlays, drawers, and tooltips escape
+    // ancestor overflow:hidden / z-index stacking contexts — the same pattern as
+    // React's ReactDOM.createPortal().
+    //
+    // The portal leaves a comment node ( clarity:portal ) as a placeholder in the
+    // normal document flow.  All portal children are tracked in _portal_N_nodes[] and
+    // removed when the host component unmounts (registered via _disposes).
+    //
+    // Reactive content inside the portal (signals, <when>, <list>) works exactly as
+    // normal — effect closures still close over the host component's signals.
+    if (tag === 'portal') {
+      const targetAttr = jsxNode.attrs.find(a => a.name === 'target');
+      const targetExpr = targetAttr ? this._genExpr(targetAttr.value) : '"body"';
+      const portalN    = counter.n++;
+      const allLines2  = [];
+
+      allLines2.push(`const ${varName} = document.createComment('clarity:portal');`);
+      allLines2.push(`const _portal${portalN}_el = document.querySelector(${targetExpr}) ?? document.body;`);
+      allLines2.push(`const _portal${portalN}_nodes = [];`);
+
+      const portalCounter = { n: counter.n + 400 };
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXText' && !child.value.trim()) continue;
+        const [cl, cv] = this._genJSX(child, signals, portalCounter, params);
+        allLines2.push(...cl);
+        allLines2.push(`_portal${portalN}_el.appendChild(${cv});`);
+        allLines2.push(`_portal${portalN}_nodes.push(${cv});`);
+      }
+      counter.n = portalCounter.n;
+
+      // Register cleanup so portal nodes are removed when the host component unmounts
+      allLines2.push(`_disposes.push(() => _portal${portalN}_nodes.forEach(_n => _n.parentNode?.removeChild(_n)));`);
+
+      return [allLines2, varName];
+    }
+
+    // ── Suspense boundary: <Suspense fallback="…"> lazy children </Suspense> ────
+    //
+    // Shows a fallback while any direct lazy() child is loading, then replaces it
+    // with the real content once all lazy components have resolved.
+    //
+    // Fallback can be:
+    //   fallback="Loading…"         → text node
+    //   fallback={<Spinner />}      → JSX element (if parser supports JSX in attrs)
+    //   <p slot="fallback">…</p>    → named slot child (preferred for complex fallbacks)
+    //
+    // Implementation strategy:
+    //   1. Children are rendered into a hidden <div> wrapper (display:none) so they
+    //      ARE in the live DOM — lazy() self-swap needs placeholder.parentNode to work.
+    //   2. If any child registers a lazy promise (via _registerLazy), show the fallback.
+    //   3. When all promises resolve, remove the fallback and show the wrapper
+    //      (display:contents — transparent to CSS layout).
+    //
+    // The extra <div> uses display:contents when visible, so it's invisible to
+    // flex/grid layout algorithms and won't break any parent CSS.
+    if (tag === 'Suspense') {
+      const fallbackAttr = jsxNode.attrs.find(a => a.name === 'fallback');
+      const suspN    = counter.n++;
+      const allLines2 = [];
+
+      // Wrapper div that holds children — hidden during load
+      allLines2.push(`const ${varName} = document.createComment('clarity:suspense');`);
+      allLines2.push(`const _susp${suspN}_wrap = document.createElement('div');`);
+      allLines2.push(`_susp${suspN}_wrap.style.display = 'none';`);
+      allLines2.push(`const _susp${suspN}_ctx = { _pending: [] };`);
+
+      // Push suspense context — lazy() children will register their promises here
+      allLines2.push(`_pushSuspense(_susp${suspN}_ctx);`);
+
+      // ── Generate real (non-fallback) children ──────────────────────────────
+      const susChildVars  = [];
+      const susChildNodes = [];
+      // Split children: fallback slot vs. default content
+      for (const child of jsxNode.children) {
+        if (child.type === 'JSXElement') {
+          const sf = child.attrs?.find(a => a.type === 'Attr' && a.name === 'slot' && a.value?.value === 'fallback');
+          if (sf) continue; // handled separately below
+        }
+        if (child.type === 'JSXText' && !child.value.trim()) continue;
+        const [cl, cv] = this._genJSX(child, signals, counter, params);
+        allLines2.push(...cl);
+        susChildVars.push(cv);
+        susChildNodes.push(child);
+      }
+
+      // Append content children into wrapper
+      for (const cv of susChildVars) {
+        allLines2.push(`_susp${suspN}_wrap.appendChild(${cv});`);
+      }
+
+      // Pop suspense context
+      allLines2.push(`_popSuspense();`);
+
+      // ── Generate fallback ──────────────────────────────────────────────────
+      // Prefer slot="fallback" child, then fallback attr, then default text
+      const fallbackSlotChild = jsxNode.children.find(
+        c => c.type === 'JSXElement' &&
+             c.attrs?.find(a => a.type === 'Attr' && a.name === 'slot' && a.value?.value === 'fallback')
+      );
+
+      const fbLines = [];
+      let fbVar;
+      if (fallbackSlotChild) {
+        const fbChild = { ...fallbackSlotChild, attrs: fallbackSlotChild.attrs.filter(a => a.name !== 'slot') };
+        const [fl, fv] = this._genJSX(fbChild, signals, counter, params);
+        fbLines.push(...fl);
+        fbVar = fv;
+      } else if (fallbackAttr) {
+        if (fallbackAttr.value?.type === 'JSXElement') {
+          const [fl, fv] = this._genJSX(fallbackAttr.value, signals, counter, params);
+          fbLines.push(...fl);
+          fbVar = fv;
+        } else {
+          const fbExpr = this._genExprRead(fallbackAttr.value, signals, params);
+          const fbN = counter.n++;
+          fbLines.push(`const _susp${suspN}_fbv${fbN} = ${fbExpr};`);
+          fbLines.push(`const _susp${suspN}_fbn${fbN} = typeof _susp${suspN}_fbv${fbN} === 'string' ? document.createTextNode(_susp${suspN}_fbv${fbN}) : (_susp${suspN}_fbv${fbN} instanceof Node ? _susp${suspN}_fbv${fbN} : document.createTextNode(String(_susp${suspN}_fbv${fbN} ?? 'Loading…')));`);
+          fbVar = `_susp${suspN}_fbn${fbN}`;
+        }
+      } else {
+        const fbN = counter.n++;
+        fbLines.push(`const ${`_susp${suspN}_fb_default${fbN}`} = document.createTextNode('Loading\u2026');`);
+        fbVar = `_susp${suspN}_fb_default${fbN}`;
+      }
+
+      // ── Mount + show/hide logic ────────────────────────────────────────────
+      allLines2.push(`let _susp${suspN}_fb = null;`);
+      allLines2.push(`queueMicrotask(() => {`);
+      allLines2.push(`  ${varName}.parentNode?.insertBefore(_susp${suspN}_wrap, ${varName});`);
+      allLines2.push(`  if (_susp${suspN}_ctx._pending.length === 0) {`);
+      allLines2.push(`    _susp${suspN}_wrap.style.display = 'contents';`);
+      allLines2.push(`  } else {`);
+      // generate fallback inside the microtask
+      for (const l of fbLines) allLines2.push(`    ${l}`);
+      allLines2.push(`    _susp${suspN}_fb = ${fbVar};`);
+      allLines2.push(`    ${varName}.parentNode?.insertBefore(_susp${suspN}_fb, ${varName});`);
+      allLines2.push(`    Promise.all(_susp${suspN}_ctx._pending).then(() => {`);
+      allLines2.push(`      setTimeout(() => {`);
+      allLines2.push(`        _susp${suspN}_wrap.style.display = 'contents';`);
+      allLines2.push(`        if (_susp${suspN}_fb?.parentNode) _susp${suspN}_fb.parentNode.removeChild(_susp${suspN}_fb);`);
+      allLines2.push(`        _susp${suspN}_fb = null;`);
+      allLines2.push(`      }, 0);`);
+      allLines2.push(`    });`);
+      allLines2.push(`  }`);
+      allLines2.push(`});`);
+
+      // Register cleanup for wrapper and fallback
+      allLines2.push(`_disposes.push(() => {`);
+      allLines2.push(`  _susp${suspN}_wrap.parentNode?.removeChild(_susp${suspN}_wrap);`);
+      allLines2.push(`  if (_susp${suspN}_fb?.parentNode) _susp${suspN}_fb.parentNode.removeChild(_susp${suspN}_fb);`);
+      allLines2.push(`});`);
+
+      this._usedRuntime.add('_pushSuspense');
+      this._usedRuntime.add('_popSuspense');
+
+      return [allLines2, varName];
+    }
+
+    // ── Dynamic component: <Component is={expr} /> ─────────────────────────────
+    //
+    // Allows the rendered component to be determined at runtime:
+    //
+    //   <Component is={CounterDemo} />              — static: always CounterDemo
+    //   <Component is={activeTab} />                — reactive: switches when signal changes
+    //   <Component is={tabs[idx]} title="Hello" />  — reactive with extra props
+    //
+    // Props (excluding `is`) are forwarded as-is.  Named slots and spread props work
+    // the same as regular component calls.
+    //
+    // When `is` is NOT reactive (e.g. a plain identifier or object literal):
+    //   → generates a direct call:  const _el0 = (CounterDemo)({ ...props });
+    //
+    // When `is` IS reactive (reads a signal):
+    //   → generates a comment placeholder + effect that unmounts the old component
+    //     and mounts the new one whenever the signal changes.
+    if (tag === 'Component') {
+      const isAttr    = jsxNode.attrs.find(a => a.type === 'Attr' && a.name === 'is');
+      const dynN      = counter.n++;
+      const allLines2 = [];
+
+      // Missing `is` — emit a warning placeholder and bail
+      if (!isAttr) {
+        allLines2.push(`const ${varName} = document.createComment('clarity:dynamic:missing-is');`);
+        if (typeof console !== 'undefined') {
+          allLines2.push(`console.warn('[Clarity] <Component> requires an \`is\` prop');`);
+        }
+        return [allLines2, varName];
+      }
+
+      // ── Generate children (same as regular component call) ──────────────────
+      const dynChildVars  = [];
+      const dynChildNodes = [];
+      for (const child of jsxNode.children) {
+        const [cl, cv] = this._genJSX(child, signals, counter, params);
+        allLines2.push(...cl);
+        dynChildVars.push(cv);
+        dynChildNodes.push(child);
+      }
+
+      // ── Build attrProps — all attrs except `is` ─────────────────────────────
+      const passAttrs  = jsxNode.attrs.filter(a => a.name !== 'is');
+      const attrProps2 = passAttrs.flatMap(a => {
+        if (a.type === 'SpreadAttr') {
+          return [`...(${this._genExprRead(a.expr, signals, params)} ?? {})`];
+        }
+        if (a.type === 'EventAttr') {
+          const modifiers = a.modifiers ?? [];
+          const handler   = this._genExprWithSignalAwareness(a.handler);
+          const wrapped   = this._wrapWithModifiers(handler, modifiers);
+          return [`on${this._capitalize(a.event)}: (e) => { ${wrapped} }`];
+        }
+        if (a.type === 'BindAttr') return [`${a.prop}: ${this._genExpr(a.signal)}`];
+
+        const isDirectSignal = a.value?.type === 'Ident' && signals.includes(a.value.name);
+        const isReactProp    = !isDirectSignal && this._exprReadsSignals(a.value, signals, params);
+        let valCode;
+        if (isDirectSignal) {
+          valCode = this._genExpr(a.value);
+        } else if (isReactProp) {
+          valCode = `computed(() => ${this._genExprRead(a.value, signals, params)})`;
+          this._usedRuntime.add('computed');
+        } else {
+          valCode = this._genExpr(a.value);
+        }
+        return [`${a.name}: ${valCode}`];
+      });
+
+      // ── Slot grouping ────────────────────────────────────────────────────────
+      const dynSlotGroups = {};
+      for (let _ci = 0; _ci < dynChildVars.length; _ci++) {
+        const childVar  = dynChildVars[_ci];
+        if (!childVar || childVar === 'null') continue;
+        const childNode = dynChildNodes[_ci];
+        let slotName = 'default';
+        if (childNode?.type === 'JSXElement') {
+          const slotAttr = childNode.attrs?.find(
+            a => a.type === 'Attr' && a.name === 'slot' && a.value?.type === 'Literal'
+          );
+          if (slotAttr) slotName = String(slotAttr.value.value);
+        }
+        (dynSlotGroups[slotName] ??= []).push(childVar);
+      }
+      const dynSlotEntries = Object.entries(dynSlotGroups);
+      if (dynSlotEntries.length > 0) {
+        const childrenObj = dynSlotEntries.map(([name, vars]) => `${name}: [${vars.join(', ')}]`).join(', ');
+        attrProps2.push(`children: { ${childrenObj} }`);
+      }
+      const propsStr2 = attrProps2.join(', ');
+
+      // ── Emit code ───────────────────────────────────────────────────────────
+      const isExprStatic = this._genExpr(isAttr.value);
+      const isExprRead   = this._genExprRead(isAttr.value, signals, params);
+      const isReactive   = this._exprReadsSignals(isAttr.value, signals, params);
+
+      if (!isReactive) {
+        // Static: direct call — zero overhead, same as writing <CounterDemo /> directly
+        allLines2.push(`const ${varName} = (${isExprStatic})({ ${propsStr2} });`);
+      } else {
+        // Reactive: effect-driven — swap component when the signal changes
+        allLines2.push(`const ${varName} = document.createComment('clarity:dynamic');`);
+        allLines2.push(`let _dyn${dynN}_node = null;`);
+        allLines2.push(`queueMicrotask(() => _e(effect(() => {`);
+        allLines2.push(`  if (_dyn${dynN}_node) { _dyn${dynN}_node.parentNode?.removeChild(_dyn${dynN}_node); _dyn${dynN}_node = null; }`);
+        allLines2.push(`  const _DynComp${dynN} = ${isExprRead};`);
+        allLines2.push(`  if (typeof _DynComp${dynN} === 'function') {`);
+        allLines2.push(`    _dyn${dynN}_node = _DynComp${dynN}({ ${propsStr2} });`);
+        allLines2.push(`    ${varName}.parentNode?.insertBefore(_dyn${dynN}_node, ${varName});`);
+        allLines2.push(`  }`);
+        allLines2.push(`})));`);
+        this._usedRuntime.add('effect');
+      }
+
+      return [allLines2, varName];
+    }
+
+    // ── Fragment <> ... </> ─────────────────────────────────────────────────────
+    // Empty tag name signals a fragment: render all children into a DocumentFragment
+    // with no wrapper DOM element. This lets a component return sibling nodes freely.
+    if (tag === '') {
+      const fragLines = [];
+      if (jsxNode.loc?.line) fragLines.push(`//@ SM:${jsxNode.loc.line}`);
+      fragLines.push(`const ${varName} = document.createDocumentFragment();`);
+      for (const child of jsxNode.children) {
+        const [childLines, childVar] = this._genJSX(child, signals, counter, params);
+        fragLines.push(...childLines);
+        fragLines.push(`${varName}.appendChild(${childVar});`);
+      }
+      return [fragLines, varName];
+    }
+
+    const isComponent = tag[0] === tag[0].toUpperCase();
+    const allLines = [];
+
+    // Source map marker for this element
+    if (jsxNode.loc?.line) allLines.push(`//@ SM:${jsxNode.loc.line}`);
+
+    // Generate children first (bottom-up).
+    // We keep childNodes in parallel so that, for component calls, we can inspect
+    // the slot="name" attribute on each child and route it to the correct slot bucket.
+    //
+    // Special case: <template slot="name">...</template>
+    // The <template> element is transparent — its children are inlined with the
+    // slot attribute copied onto a synthetic wrapper so the slot router picks it up.
+    const childVars  = [];
+    const childNodes = []; // original JSX nodes, parallel to childVars
+    for (const child of jsxNode.children) {
+      // Expand <template slot="name"> and <template slot="name" let:data> transparently
+      //
+      // SCOPED SLOTS: <template slot="row" let:data> wraps children in (data) => [...]
+      // The `let:data` attribute binds the slot data variable name.
+      // Multiple let: bindings are supported: let:data let:index → (data, index) => [...]
+      if (
+        child.type === 'JSXElement' &&
+        child.tag === 'template' &&
+        child.attrs?.some(a => a.type === 'Attr' && a.name === 'slot')
+      ) {
+        const slotAttr  = child.attrs.find(a => a.type === 'Attr' && a.name === 'slot');
+        // Collect let: bindings for scoped slots
+        const letAttrs  = child.attrs.filter(a => a.type === 'Attr' && a.name.startsWith('let:'));
+        const letParams = letAttrs.map(a => a.name.slice(4)); // strip 'let:'
+
+        if (letParams.length > 0) {
+          // SCOPED SLOT — generate a render function instead of a fragment
+          // Template children are compiled with letParams added to the params scope
+          const scopedParams = [...params, ...letParams];
+          const innerVars = [];
+          const innerLines = [];
+          for (const templateChild of child.children) {
+            const [childLines, childVar] = this._genJSX(templateChild, signals, counter, scopedParams);
+            innerLines.push(...childLines);
+            innerVars.push(childVar);
+          }
+          // Build a render function: (data, index) => { ... return [nodes] }
+          const fnVar = `_el${counter.n++}`;
+          const paramList = letParams.join(', ');
+          allLines.push(`const ${fnVar} = (${paramList}) => {`);
+          allLines.push(...innerLines.map(l => '  ' + l));
+          allLines.push(`  return [${innerVars.filter(Boolean).join(', ')}];`);
+          allLines.push(`};`);
+          childVars.push(fnVar);
+          childNodes.push({ type: 'JSXElement', tag: '__scoped_slot__', attrs: [slotAttr], children: [], __scoped: true });
+          continue;
+        }
+
+        // Regular named slot (no let: bindings) — generate a DocumentFragment
+        const fragVar = `_el${counter.n++}`;
+        allLines.push(`const ${fragVar} = document.createDocumentFragment();`);
+        for (const templateChild of child.children) {
+          const [childLines, childVar] = this._genJSX(templateChild, signals, counter, params);
+          allLines.push(...childLines);
+          allLines.push(`if (${childVar} != null) ${fragVar}.appendChild(${childVar});`);
+        }
+        childVars.push(fragVar);
+        // Attach a synthetic JSX node with slot="name" so the slot router sees it
+        childNodes.push({ type: 'JSXElement', tag: '__template_slot__', attrs: [slotAttr], children: [] });
+        continue;
+      }
+      const [childLines, childVar] = this._genJSX(child, signals, counter, params);
+      allLines.push(...childLines);
+      childVars.push(childVar);
+      childNodes.push(child);
+    }
+
+    if (isComponent) {
+      // Component call: const _el0 = MyComponent({ prop: value, children: { default: [...], header: [...] } })
+      // PROPS REACTIVITY: pass signal references as-is (not .get()) so children
+      // receive live signals and stay reactive. The child uses duck-typing to read them.
+      const attrProps = jsxNode.attrs.flatMap(a => {
+        if (a.type === 'SpreadAttr') {
+          // Spread: {...obj} → ...(obj ?? {})  — flattens into the props object at call site
+          return [`...(${this._genExprRead(a.expr, signals, params)} ?? {})`];
+        }
+        if (a.type === 'EventAttr') {
+          const modifiers = a.modifiers ?? [];
+          const handler   = this._genExprWithSignalAwareness(a.handler);
+          const wrapped   = this._wrapWithModifiers(handler, modifiers);
+          return [`on${this._capitalize(a.event)}: (e) => { ${wrapped} }`];
+        }
+        if (a.type === 'BindAttr') return [`${a.prop}: ${this._genExpr(a.signal)}`];
+
+        // Prop reactivity strategy:
+        // • Direct signal ref (count, color) → pass signal object by reference; child duck-types it
+        // • Reactive expression (count * 2)  → wrap in computed() so child sees a live signal
+        // • Static value ("hello", 42)       → pass as-is
+        const isDirectSignal = a.value?.type === 'Ident' && signals.includes(a.value.name);
+        const isReactive     = !isDirectSignal && this._exprReadsSignals(a.value, signals, params);
+        let valCode;
+        if (isDirectSignal) {
+          valCode = this._genExpr(a.value); // raw signal reference
+        } else if (isReactive) {
+          // Computed derived prop — stays reactive in child without extra effort
+          valCode = `computed(() => ${this._genExprRead(a.value, signals, params)})`;
+          this._usedRuntime.add('computed');
+        } else {
+          valCode = this._genExpr(a.value); // static
+        }
+        return [`${a.name}: ${valCode}`];
+      });
+
+      // Pass children categorised by slot name.
+      //
+      // A child JSXElement with  slot="name"  attribute goes to children.name.
+      // Everything else (text, expressions, unslotted elements) goes to children.default.
+      //
+      // The component receives:  { default: [...], header: [...], footer: [...] }
+      // <slot />          renders children.default
+      // <slot name="x" /> renders children.x
+      //
+      // This is backward-compatible: components that don't use named slots only see
+      // children.default, and the <slot /> handler still accepts legacy flat arrays.
+      const slotGroups = {};
+      for (let _ci = 0; _ci < childVars.length; _ci++) {
+        const childVar  = childVars[_ci];
+        if (!childVar || childVar === 'null') continue;
+        const childNode = childNodes[_ci];
+        // Determine slot target: JSXElement with slot="name" → that name; else default
+        let slotName = 'default';
+        let isScoped = false;
+        if (childNode?.type === 'JSXElement') {
+          const slotAttr = childNode.attrs?.find(
+            a => a.type === 'Attr' && a.name === 'slot' && a.value?.type === 'Literal'
+          );
+          if (slotAttr) slotName = String(slotAttr.value.value);
+          isScoped = childNode.__scoped === true;
+        }
+        // Scoped slots are render functions; regular slots are nodes in an array
+        if (isScoped) {
+          // Scoped slot: store the render function directly (not in an array)
+          slotGroups[slotName] = { __scopedFn: childVar };
+        } else {
+          if (!slotGroups[slotName] || slotGroups[slotName].__scopedFn) {
+            slotGroups[slotName] = [];
+          }
+          slotGroups[slotName].push(childVar);
+        }
+      }
+      const slotEntries = Object.entries(slotGroups);
+      if (slotEntries.length > 0) {
+        const childrenObj = slotEntries.map(([name, val]) => {
+          if (val?.__scopedFn) return `${name}: ${val.__scopedFn}`; // scoped → function
+          return `${name}: [${val.join(', ')}]`;                    // regular → array
+        }).join(', ');
+        attrProps.push(`children: { ${childrenObj} }`);
+      }
+
+      const propsStr = attrProps.join(', ');
+      allLines.push(`const ${varName} = ${tag}({ ${propsStr} });`);
+    } else {
+      // HTML element
+      allLines.push(`const ${varName} = document.createElement('${tag}');`);
+
+      // Attributes
+      for (const attr of jsxNode.attrs) {
+        if (attr.type === 'SpreadAttr') {
+          // Spread props onto an HTML element: {...obj} → Object.entries(obj).forEach(...)
+          const spreadExpr = this._genExprRead(attr.expr, signals, params);
+          allLines.push(`Object.entries(${spreadExpr} ?? {}).forEach(([_k, _v]) => {`);
+          allLines.push(`  if (_k === 'class') ${varName}.className = _v;`);
+          allLines.push(`  else if (_k === 'style') ${varName}.style.cssText = _v;`);
+          allLines.push(`  else ${varName}.setAttribute(_k, String(_v ?? ''));`);
+          allLines.push(`});`);
+        } else if (attr.type === 'EventAttr') {
+          // Event handlers with optional modifiers
+          // Modifiers: .prevent → e.preventDefault()   .stop → e.stopPropagation()
+          //            .enter .escape .space .tab       → key guards
+          const handler   = this._genExprWithSignalAwareness(attr.handler);
+          const modifiers = attr.modifiers ?? [];
+          const innerCode = this._wrapWithModifiers(`${handler};`, modifiers);
+          allLines.push(`${varName}.addEventListener('${attr.event}', (e) => { ${innerCode} });`);
+        } else if (attr.type === 'BindAttr') {
+          const sigExpr = this._genExpr(attr.signal);
+
+          // Peek at sibling attributes to infer input type / element context
+          const typeAttr = jsxNode.attrs.find(a => a.name === 'type' && a.value?.type === 'Literal');
+          const inputType = typeAttr?.value?.value?.toLowerCase() ?? '';
+
+          if (attr.prop === 'group') {
+            // bind:group — checkbox/radio group backed by an array signal
+            // Effect: keep element checked based on array membership
+            allLines.push(`_e(effect(() => {`);
+            allLines.push(`  const _gv = ${sigExpr}.get();`);
+            allLines.push(`  ${varName}.checked = Array.isArray(_gv) ? _gv.includes(${varName}.value) : false;`);
+            allLines.push(`}));`);
+            // On change: add/remove from array
+            allLines.push(`${varName}.addEventListener('change', () => {`);
+            allLines.push(`  const _prev = ${sigExpr}.get() ?? [];`);
+            allLines.push(`  if (${varName}.checked) ${sigExpr}.set([..._prev, ${varName}.value]);`);
+            allLines.push(`  else ${sigExpr}.set(_prev.filter(_v => _v !== ${varName}.value));`);
+            allLines.push(`});`);
+          } else if (attr.prop === 'checked') {
+            // bind:checked — boolean binding for checkboxes
+            allLines.push(`_e(effect(() => { ${varName}.checked = !!${sigExpr}.get(); }));`);
+            allLines.push(`${varName}.addEventListener('change', () => { ${sigExpr}.set(${varName}.checked); });`);
+          } else if (tag === 'select') {
+            // bind:value on <select> — use 'change' event, support multiple attribute
+            allLines.push(`_e(effect(() => {`);
+            allLines.push(`  const _sv = ${sigExpr}.get();`);
+            allLines.push(`  if (Array.isArray(_sv)) {`);
+            allLines.push(`    [...${varName}.options].forEach(o => { o.selected = _sv.includes(o.value); });`);
+            allLines.push(`  } else { ${varName}.value = _sv ?? ''; }`);
+            allLines.push(`}));`);
+            allLines.push(`${varName}.addEventListener('change', () => {`);
+            allLines.push(`  if (${varName}.multiple) {`);
+            allLines.push(`    ${sigExpr}.set([...${varName}.selectedOptions].map(o => o.value));`);
+            allLines.push(`  } else { ${sigExpr}.set(${varName}.value); }`);
+            allLines.push(`});`);
+          } else if (inputType === 'number' || inputType === 'range') {
+            // bind:value on number/range inputs — coerce to number
+            allLines.push(`_e(effect(() => { ${varName}.value = String(${sigExpr}.get() ?? ''); }));`);
+            allLines.push(`${varName}.addEventListener('input', () => {`);
+            allLines.push(`  const _nv = ${varName}.valueAsNumber;`);
+            allLines.push(`  ${sigExpr}.set(isNaN(_nv) ? '' : _nv);`);
+            allLines.push(`});`);
+          } else if (tag === 'textarea') {
+            // bind:value on <textarea>
+            allLines.push(`_e(effect(() => { ${varName}.value = ${sigExpr}.get() ?? ''; }));`);
+            allLines.push(`${varName}.addEventListener('input', () => { ${sigExpr}.set(${varName}.value); });`);
+          } else {
+            // Default: bind:value on <input type="text"> and similar
+            allLines.push(`_e(effect(() => { ${varName}.value = String(${sigExpr}.get() ?? ''); }));`);
+            allLines.push(`${varName}.addEventListener('input', () => { ${sigExpr}.set(${varName}.value); });`);
+          }
+        } else if (attr.name === 'ref') {
+          // ref — store DOM node reference into a signal or callback
+          // <input ref={myRef} /> → myRef.set(el)  (if signal)
+          //                       → myRef(el)       (if callback)
+          const refExpr = this._genExpr(attr.value);
+          allLines.push(`if (typeof ${refExpr} === 'function') ${refExpr}(${varName});`);
+          allLines.push(`else if (${refExpr}?._type === 'signal') ${refExpr}.set(${varName});`);
+        } else if (tag === 'form' && attr.name === 'action' && attr.value && attr.value.type !== 'Literal') {
+          // <form action={serverAction}> — Server Actions form integration.
+          // Intercept submit, collect FormData as a plain object, and invoke the
+          // action. Accepts a useServerAction() client ({ execute }) or a plain
+          // function. A string literal action (action="/url") is left as a native
+          // form post (handled by the generic attribute branch below).
+          const actionExpr = this._genExpr(attr.value);
+          allLines.push(`${varName}.addEventListener('submit', (e) => {`);
+          allLines.push(`  e.preventDefault();`);
+          allLines.push(`  const _data = Object.fromEntries(new FormData(${varName}).entries());`);
+          allLines.push(`  const _act = ${actionExpr};`);
+          allLines.push(`  const _fn = (_act && typeof _act.execute === 'function') ? _act.execute.bind(_act) : _act;`);
+          allLines.push(`  Promise.resolve(typeof _fn === 'function' ? _fn(_data) : undefined)`);
+          allLines.push(`    .catch((_err) => console.error('[Clarity] form action failed:', _err));`);
+          allLines.push(`});`);
+        } else {
+          const isReactive = this._exprReadsSignals(attr.value, signals, params);
+          const val = isReactive
+            ? this._genExprRead(attr.value, signals, params)
+            : this._genExpr(attr.value);
+          if (attr.name === 'class') {
+            if (isReactive) {
+              allLines.push(`_e(effect(() => { ${varName}.className = ${val}; }));`);
+            } else {
+              allLines.push(`${varName}.className = ${val};`);
+            }
+          } else {
+            if (isReactive) {
+              allLines.push(`_e(effect(() => { ${varName}.setAttribute('${attr.name}', ${val}); }));`);
+            } else {
+              allLines.push(`${varName}.setAttribute('${attr.name}', ${val});`);
+            }
+          }
+        }
+      }
+
+      // Append children
+      for (const childVar of childVars) {
+        allLines.push(`${varName}.appendChild(${childVar});`);
+      }
+    }
+
+    return [allLines, varName];
+  }
+
+  // ── Expression Generator ──
+  _genExpr(node) {
+    if (!node) return 'undefined';
+
+    switch (node.type) {
+      case 'Literal':
+        return JSON.stringify(node.value);
+
+      case 'Ident':
+        return node.name;
+
+      case 'BinaryExpr':
+        return `(${this._genExpr(node.left)} ${node.op} ${this._genExpr(node.right)})`;
+
+      case 'UnaryExpr':
+        return `${node.op}(${this._genExpr(node.expr)})`;
+
+      case 'UpdateExpr':
+        return this._genUpdateExpr(node);
+
+      case 'TernaryExpr':
+        return `(${this._genExpr(node.cond)} ? ${this._genExpr(node.then)} : ${this._genExpr(node.else)})`;
+
+      case 'AssignExpr': {
+        const target = this._genAssignTarget(node.target, node.op, node.value);
+        return target;
+      }
+
+      case 'MemberExpr':
+        if (node.computed) {
+          return `${this._genExpr(node.obj)}[${this._genExpr(node.prop)}]`;
+        }
+        return `${this._genExpr(node.obj)}.${this._genExpr(node.prop)}`;
+
+      case 'CallExpr': {
+        const calleeCode = this._genExpr(node.callee);
+        // Arrow functions as callees need parens: (() => {})() not () => {}()
+        const callee = node.callee.type === 'ArrowFn' ? `(${calleeCode})` : calleeCode;
+        const args   = node.args.map(a => this._genExpr(a)).join(', ');
+        return `${callee}(${args})`;
+      }
+
+      case 'ArrowFn': {
+        const params = node.params.map(p => p.name).join(', ');
+        const body = node.body.type === 'Block'
+          ? `{\n${this._genBlockStmts(node.body.body).join('\n')}\n}`
+          : this._genExpr(node.body);
+        return `(${params}) => ${body}`;
+      }
+
+      case 'CommaExpr':
+        return node.parts.map(p => this._genExprWithSignalAwareness(p)).join(', ');
+
+      case 'NewExpr': {
+        const callee = this._genExpr(node.callee);
+        const args   = node.args.map(a => a.type === 'SpreadExpr' ? `...${this._genExpr(a.expr)}` : this._genExpr(a)).join(', ');
+        return `new ${callee}(${args})`;
+      }
+
+      case 'SpreadExpr':
+        return `...${this._genExpr(node.expr)}`;
+
+      case 'ArrayExpr':
+        return `[${node.elements.map(e => this._genExpr(e)).join(', ')}]`;
+
+      case 'ObjectExpr': {
+        const props = node.properties.map(p => `${p.key}: ${this._genExpr(p.value)}`);
+        return `{ ${props.join(', ')} }`;
+      }
+
+      case 'TemplateLiteral': {
+        // Reconstruct as a JS template literal. In _genExpr we don't call .get()
+        // on signals — use _genExprRead only when in reactive read context.
+        const inner = node.parts.map(p =>
+          p.type === 'str' ? p.value : '${' + this._genExpr(p.expr) + '}'
+        ).join('');
+        return '`' + inner + '`';
+      }
+
+      case 'AwaitExpr':
+        return `await ${this._genExpr(node.expr)}`;
+
+      default:
+        return `/* unknown expr: ${node?.type} */`;
+    }
+  }
+
+  // State signal assignment: count = 5 → count.set(5)
+  _genAssignTarget(target, op, value) {
+    // FIX: use _genExprRead for the value so signal refs inside RHS call .get()
+    // e.g. todos = [...todos, {text: inputValue}] → todos.set([...todos.get(), {text: inputValue.get()}])
+    const sigs   = this._currentSignals ?? [];
+    const params = this._currentParams  ?? [];
+    if (target.type === 'Ident') {
+      const valExpr = this._genExprRead(value, sigs, params);
+      if (op === '=')  return `${target.name}.set(${valExpr})`;
+      if (op === '+=') return `${target.name}.set(${target.name}.get() + (${valExpr}))`;
+      if (op === '-=') return `${target.name}.set(${target.name}.get() - (${valExpr}))`;
+    }
+    // Non-signal assignment (member access, etc.)
+    return `${this._genExpr(target)} ${op} ${this._genExprRead(value, sigs, params)}`;
+  }
+
+  // Unused — kept for clarity
+  _genUpdateTarget(expr) { return this._genExpr(expr); }
+
+  // Signal-aware update: count++ → count.set(count.get() + 1)
+  // In event handler context we don't need the return value, so keep it simple.
+  _genUpdateExpr(node) {
+    if (node.expr.type === 'Ident') {
+      const name = node.expr.name;
+      if (node.op === '++') return `${name}.set(${name}.get() + 1)`;
+      if (node.op === '--') return `${name}.set(${name}.get() - 1)`;
+    }
+    // Fallback for non-signal identifiers
+    return node.prefix
+      ? `${node.op}${this._genExpr(node.expr)}`
+      : `${this._genExpr(node.expr)}${node.op}`;
+  }
+
+  // ── Statement Generator ──
+  _genBlockStmts(stmts) {
+    return stmts.map(stmt => this._genStmt(stmt)).filter(Boolean);
+  }
+
+  _genBlock(blockNode, inline = false) {
+    return this._genBlockStmts(blockNode.body ?? []);
+  }
+
+  _genStmt(stmt) {
+    if (!stmt) return null;
+    switch (stmt.type) {
+      case 'ExprStmt':
+        return `${this._genExprWithSignalAwareness(stmt.expr)};`;
+      case 'ReturnStmt':
+        // Read-aware: a returned signal must yield its VALUE (signal.get()), not
+        // the signal object. Critical for ai:forbidden — `return secret` compiles
+        // to `secret.get()`, which the protected-signal guard blocks in AI context.
+        return stmt.value ? `return ${this._genReadValue(stmt.value)};` : 'return;';
+      case 'VarDecl':
+        return `${stmt.kind} ${stmt.name} = ${this._genReadValue(stmt.init)};`;
+      case 'MultiVarDecl': {
+        const parts = stmt.declarators.map(d => `${d.name} = ${this._genReadValue(d.init)}`).join(', ');
+        return `${stmt.kind} ${parts};`;
+      }
+      case 'IfStmt': {
+        let s = `if (${this._genReadValue(stmt.cond)}) {\n${this._genBlockStmts(stmt.then.body).join('\n')}\n}`;
+        if (stmt.else) s += ` else {\n${this._genBlockStmts(stmt.else.body).join('\n')}\n}`;
+        return s;
+      }
+      default:
+        return `/* unknown stmt: ${stmt?.type} */`;
+    }
+  }
+
+  // Read-aware value generator for statement positions (return / var init / if
+  // condition). Signal identifiers become `signal.get()`, object/array/template
+  // values are read-expanded, but signal-method calls (items.set(...)) keep their
+  // raw receiver. This makes signal reads consistent and closes ai:forbidden leaks
+  // (you cannot return/alias a forbidden signal object to escape the guard).
+  _genReadValue(expr) {
+    if (!expr) return 'undefined';
+    switch (expr.type) {
+      case 'UpdateExpr':
+      case 'AssignExpr':
+      case 'CommaExpr':
+      case 'CallExpr':
+        return this._genExprWithSignalAwareness(expr);
+      default:
+        return this._genExprRead(expr, this._currentSignals ?? [], this._currentParams ?? []);
+    }
+  }
+
+  // In statement context, handle signal updates
+  _genExprWithSignalAwareness(expr) {
+    if (!expr) return '';
+    if (expr.type === 'UpdateExpr') return this._genUpdateExpr(expr);
+    if (expr.type === 'AssignExpr') return this._genAssignTarget(expr.target, expr.op, expr.value);
+    // FIX: CommaExpr in event handlers must be ; separated statements, not , expressions
+    // e.g. on:click={ a = 1, b = 2 } → a.set(1); b.set(2)   (not a.set(1), b.set(2))
+    if (expr.type === 'CommaExpr') return expr.parts.map(p => this._genExprWithSignalAwareness(p)).join('; ');
+    // For CallExpr in event handlers and action bodies, use signal-aware read mode.
+    // Special case: signal.set/update/peek/subscribe(...) — the signal itself is
+    // the receiver, so we must NOT wrap it with .get(). Only its arguments need read expansion.
+    // e.g.  items.set([...items, x])  →  items.set([...items.get(), x])
+    //        myRef.get().focus()      →  myRef.get().focus()   (no change — not a signal method)
+    if (expr.type === 'CallExpr') {
+      const sigs   = this._currentSignals ?? [];
+      const params = this._currentParams  ?? [];
+      const { callee } = expr;
+      if (
+        callee.type === 'MemberExpr' && !callee.computed &&
+        callee.obj.type === 'Ident'  && sigs.includes(callee.obj.name) &&
+        _SIGNAL_METHODS.has(callee.prop.name ?? callee.prop)
+      ) {
+        // signal.method(args…) — keep the raw signal reference, expand args reactively
+        const method = this._genExpr(callee.prop);
+        const args   = expr.args.map(a => this._genExprRead(a, sigs, params)).join(', ');
+        return `${callee.obj.name}.${method}(${args})`;
+      }
+      return this._genExprRead(expr, sigs, params);
+    }
+    return this._genExpr(expr);
+  }
+
+  // Generate expression in "read mode" — signal references become signal.get()
+  // params: component params that may be signals from parent (duck-typing)
+  _genExprRead(node, signals, params = []) {
+    if (!node) return 'undefined';
+    switch (node.type) {
+      case 'Ident':
+        if (signals.includes(node.name)) return `${node.name}.get()`;
+        // Props duck-typing: parent may pass a signal OR a plain value.
+        // At runtime, check the _type tag and call .get() only when it's a signal.
+        if (params.includes(node.name))
+          return `(${node.name}?._type === 'signal' ? ${node.name}.get() : ${node.name})`;
+        return node.name;
+      case 'Literal':
+        return JSON.stringify(node.value);
+      case 'BinaryExpr':
+        return `(${this._genExprRead(node.left, signals, params)} ${node.op} ${this._genExprRead(node.right, signals, params)})`;
+      case 'UnaryExpr':
+        return `${node.op}(${this._genExprRead(node.expr, signals, params)})`;
+      case 'TernaryExpr':
+        return `(${this._genExprRead(node.cond, signals, params)} ? ${this._genExprRead(node.then, signals, params)} : ${this._genExprRead(node.else, signals, params)})`;
+      case 'MemberExpr':
+        if (node.computed) return `${this._genExprRead(node.obj, signals, params)}[${this._genExprRead(node.prop, signals, params)}]`;
+        return `${this._genExprRead(node.obj, signals, params)}.${this._genExpr(node.prop)}`;
+      case 'CallExpr': {
+        const calleeCode = this._genExprRead(node.callee, signals, params);
+        const callee = node.callee.type === 'ArrowFn' ? `(${calleeCode})` : calleeCode;
+        const args   = node.args.map(a => this._genExprRead(a, signals, params)).join(', ');
+        return `${callee}(${args})`;
+      }
+      case 'NewExpr': {
+        const callee = this._genExprRead(node.callee, signals, params);
+        const args   = node.args.map(a => a.type === 'SpreadExpr' ? `...${this._genExprRead(a.expr, signals, params)}` : this._genExprRead(a, signals, params)).join(', ');
+        return `new ${callee}(${args})`;
+      }
+      case 'SpreadExpr':
+        return `...${this._genExprRead(node.expr, signals, params)}`;
+      case 'ArrayExpr':
+        return `[${node.elements.map(e => this._genExprRead(e, signals, params)).join(', ')}]`;
+      case 'ObjectExpr': {
+        const props = node.properties.map(p => `${p.key}: ${this._genExprRead(p.value, signals, params)}`);
+        return `{ ${props.join(', ')} }`;
+      }
+      case 'TemplateLiteral': {
+        // Reactive template: signal references inside ${} become .get() calls
+        const inner = node.parts.map(p =>
+          p.type === 'str' ? p.value : '${' + this._genExprRead(p.expr, signals, params) + '}'
+        ).join('');
+        return '`' + inner + '`';
+      }
+      case 'ArrowFn': {
+        // Arrow fn params shadow signals — exclude them from the reactive signal list inside
+        const ownParams = node.params.map(p => p.name);
+        const innerSignals = signals.filter(s => !ownParams.includes(s));
+        const innerParams  = params.filter(p => !ownParams.includes(p));
+        const paramStr = ownParams.join(', ');
+        if (node.body.type === 'Block') {
+          const bodyLines = this._genBlockStmtsReactive(node.body.body, innerSignals, innerParams);
+          return `(${paramStr}) => {\n${bodyLines.join('\n')}\n}`;
+        }
+        return `(${paramStr}) => ${this._genExprRead(node.body, innerSignals, innerParams)}`;
+      }
+      default:
+        return this._genExpr(node);
+    }
+  }
+
+  // ── Reactive statement generation (for computed block bodies & arrow fns) ──
+  // Like _genStmt but threads signal reactivity through all expressions.
+  _genStmtReactive(stmt, signals, params) {
+    if (!stmt) return null;
+    switch (stmt.type) {
+      case 'ExprStmt':
+        return `${this._genExprRead(stmt.expr, signals, params)};`;
+      case 'ReturnStmt':
+        return stmt.value ? `return ${this._genExprRead(stmt.value, signals, params)};` : 'return;';
+      case 'VarDecl':
+        return `${stmt.kind} ${stmt.name} = ${this._genExprRead(stmt.init, signals, params)};`;
+      case 'MultiVarDecl': {
+        const parts = stmt.declarators.map(d => `${d.name} = ${this._genExprRead(d.init, signals, params)}`).join(', ');
+        return `${stmt.kind} ${parts};`;
+      }
+      case 'IfStmt': {
+        let s = `if (${this._genExprRead(stmt.cond, signals, params)}) {\n${this._genBlockStmtsReactive(stmt.then.body, signals, params).join('\n')}\n}`;
+        if (stmt.else) s += ` else {\n${this._genBlockStmtsReactive(stmt.else.body, signals, params).join('\n')}\n}`;
+        return s;
+      }
+      default:
+        return this._genStmt(stmt);
+    }
+  }
+
+  _genBlockStmtsReactive(stmts, signals, params) {
+    return (stmts ?? []).map(s => this._genStmtReactive(s, signals, params)).filter(Boolean);
+  }
+
+  // ── Helpers ──
+  // params: component params that may carry signal values — treated as potentially reactive
+  _exprReadsSignals(expr, signals, params = []) {
+    if (!expr) return false;
+    if (expr.type === 'Ident' && signals.includes(expr.name)) return true;
+    // A param could be a signal from the parent — treat as reactive to be safe
+    if (expr.type === 'Ident' && params.includes(expr.name)) return true;
+    if (expr.type === 'MemberExpr') return this._exprReadsSignals(expr.obj, signals, params);
+    if (expr.type === 'CallExpr') {
+      return this._exprReadsSignals(expr.callee, signals, params) ||
+             expr.args.some(a => this._exprReadsSignals(a, signals, params));
+    }
+    if (expr.type === 'BinaryExpr') {
+      return this._exprReadsSignals(expr.left, signals, params) ||
+             this._exprReadsSignals(expr.right, signals, params);
+    }
+    if (expr.type === 'TernaryExpr') {
+      return this._exprReadsSignals(expr.cond, signals, params) ||
+             this._exprReadsSignals(expr.then, signals, params) ||
+             this._exprReadsSignals(expr.else, signals, params);
+    }
+    if (expr.type === 'UnaryExpr') return this._exprReadsSignals(expr.expr, signals, params);
+    if (expr.type === 'TemplateLiteral')
+      return expr.parts.some(p => p.type === 'expr' && this._exprReadsSignals(p.expr, signals, params));
+    return false;
+  }
+
+  // ── Event modifier wrapper ──
+  // Wraps a handler code string with modifier guards.
+  // Supported modifiers:
+  //   .prevent → e.preventDefault()
+  //   .stop    → e.stopPropagation()
+  //   .enter   → if (e.key !== 'Enter') return;
+  //   .escape  → if (e.key !== 'Escape') return;
+  //   .space   → if (e.key !== ' ') return;
+  //   .tab     → if (e.key !== 'Tab') return;
+  // Multiple modifiers are combined: .enter.escape → if (e.key!=='Enter' && e.key!=='Escape') return;
+  _wrapWithModifiers(handlerCode, modifiers = []) {
+    const KEY_MAP = { enter: 'Enter', escape: 'Escape', space: ' ', tab: 'Tab' };
+    let code = handlerCode;
+
+    // Key guards — if multiple key modifiers, allow any of them through
+    const keyMods = modifiers.filter(m => KEY_MAP[m]);
+    if (keyMods.length > 0) {
+      const checks = keyMods.map(m => `e.key !== ${JSON.stringify(KEY_MAP[m])}`).join(' && ');
+      code = `if (${checks}) return; ${code}`;
+    }
+
+    // Propagation modifiers — prepended so they run before key guards
+    if (modifiers.includes('stop'))    code = `e.stopPropagation(); ${code}`;
+    if (modifiers.includes('prevent')) code = `e.preventDefault(); ${code}`;
+
+    return code;
+  }
+
+  // ── CSS scoper ──
+  // Prefixes every CSS selector with scopeClass (e.g. "._c-Button") so that
+  // component styles don't leak out.  Uses a brace-paired scanner instead of
+  // a naive regex to avoid matching across closing braces.
+  //
+  //   .card { color: red; }  →  ._c-Button .card { color: red; }
+  //   @media (…) { .x {} }  →  @media (…) { ._c-Button .x {} }  (inner scoped)
+  _scopeCSS(css, scopeClass) {
+    let result = '';
+    let remaining = css;
+
+    while (remaining.length > 0) {
+      const braceIdx = remaining.indexOf('{');
+      if (braceIdx < 0) { result += remaining; break; }
+
+      const selectorText = remaining.slice(0, braceIdx);
+      remaining = remaining.slice(braceIdx + 1); // skip '{'
+
+      // Find matching '}'
+      let depth = 1, bodyEnd = 0;
+      while (bodyEnd < remaining.length && depth > 0) {
+        if      (remaining[bodyEnd] === '{') depth++;
+        else if (remaining[bodyEnd] === '}') depth--;
+        if (depth > 0) bodyEnd++;
+      }
+      const body    = remaining.slice(0, bodyEnd);
+      remaining     = remaining.slice(bodyEnd + 1); // skip '}'
+
+      const selector = selectorText.trim();
+
+      if (!selector) {
+        // Empty selector — just re-emit the block unchanged
+        result += `${selectorText}{${body}}`;
+        continue;
+      }
+
+      if (selector.startsWith('@')) {
+        // @-rule (e.g. @media, @keyframes) — scope inner rules recursively
+        result += `${selectorText}{${this._scopeCSS(body, scopeClass)}}`;
+        continue;
+      }
+
+      // Regular rule — scope each comma-separated selector
+      const scoped = selector.split(',').map(s => {
+        const t = s.trim();
+        if (!t || t.startsWith(scopeClass)) return t;
+        // Global selectors — don't isolate
+        if (t === ':root' || t === 'html' || t === 'body' || t === '*') return t;
+        return `${scopeClass} ${t}`;
+      }).join(',\n');
+
+      result += `${scoped} {${body}}`;
+    }
+
+    return result;
+  }
+
+  _i(str = '') {
+    return '  '.repeat(this._indent) + str;
+  }
+
+  _capitalize(str) {
+    return str[0].toUpperCase() + str.slice(1);
+  }
+}
+
+// ─── Convenience export ───────────────────────────────────────────────────────
+export function generate(ast, options) {
+  return new CodeGenerator(options).generate(ast);
+}