@pyreon/compiler 0.18.0 → 0.20.0

package/src/jsx.ts

@@ -28,10 +28,28 @@
  * Implementation: Rust native binary (napi-rs) when available, JS fallback via oxc-parser.
  */
 
+import MagicString from 'magic-string'
 import { parseSync } from 'oxc-parser'
 import { REACT_EVENT_REMAP } from './event-names'
 import { loadNativeBinding } from './load-native'
 
+/**
+ * V3 source map shape returned by the JS backend. Structurally exactly
+ * magic-string's `SourceMap` (a valid V3 map plus `.toString()`/`.toUrl()`),
+ * declared locally so `TransformResult` carries no hard type dependency on
+ * magic-string's exported types.
+ */
+export interface GeneratedSourceMap {
+  version: number
+  file?: string
+  sources: string[]
+  sourcesContent?: (string | null)[]
+  names: string[]
+  mappings: string
+  toString(): string
+  toUrl(): string
+}
+
 // ─── Native binary auto-detection ────────────────────────────────────────────
 // Two-path resolution: in-tree binary first (dev mode), then per-platform
 // npm package (production install via optionalDependencies). Falls through
@@ -39,7 +57,13 @@ import { loadNativeBinding } from './load-native'
 // environment, WASM runtime like StackBlitz, missing per-platform package).
 //
 // See `load-native.ts` for the resolution logic.
-type NativeTransformFn = (code: string, filename: string, ssr: boolean, knownSignals: string[] | null) => TransformResult
+type NativeTransformFn = (
+  code: string,
+  filename: string,
+  ssr: boolean,
+  knownSignals: string[] | null,
+  reactivityLens: boolean,
+) => TransformResult
 const nativeBinding = loadNativeBinding(import.meta.url)
 const nativeTransformJsx: NativeTransformFn | null = nativeBinding
   ? (nativeBinding.transformJsx as NativeTransformFn)
@@ -60,6 +84,41 @@ export interface CompilerWarning {
     | 'circular-prop-derived'
 }
 
+/**
+ * Reactivity-lens kinds. Each is a RECORD of a codegen decision the compiler
+ * already made — never an approximation. Positive claims (`reactive*`) are
+ * emitted ONLY where the compiler provably wrapped/tracked the span; absence
+ * of a span is "not asserted", never an implicit static claim. `static-text`
+ * is the high-precision negative: the literal `else` branch of the
+ * reactive-vs-static text decision (the "this `{x}` is baked once / dead"
+ * footgun signal when the author expected reactivity).
+ */
+export type ReactivityKind =
+  | 'reactive' // expression re-evaluates on signal change (_bind/_bindText/`() =>` wrap)
+  | 'reactive-prop' // component prop tracked into the child (_rp(() => …))
+  | 'reactive-attr' // DOM attribute re-applied on signal change
+  | 'static-text' // text expression baked once into the DOM, never re-renders
+  | 'hoisted-static' // JSX hoisted to module scope, never re-evaluated
+
+export interface ReactivitySpan {
+  /** Source byte offset (start) of the spanned expression in the INPUT. */
+  start: number
+  /** Source byte offset (end). */
+  end: number
+  /** 1-based start line. */
+  line: number
+  /** 0-based start column. */
+  column: number
+  /** 1-based end line. */
+  endLine: number
+  /** 0-based end column. */
+  endColumn: number
+  /** Which codegen decision this span records. */
+  kind: ReactivityKind
+  /** Human-readable, editor-facing one-liner explaining the decision. */
+  detail: string
+}
+
 export interface TransformResult {
   /** Transformed source code (JSX preserved, only expression containers modified) */
   code: string
@@ -67,6 +126,22 @@ export interface TransformResult {
   usesTemplates?: boolean
   /** Compiler warnings for common mistakes */
   warnings: CompilerWarning[]
+  /**
+   * Source map (V3) for the transform — present on the JS backend whenever a
+   * transformation actually occurred. `undefined` when nothing changed (the
+   * emitted code is byte-identical to the input, so no remapping is needed)
+   * and on the native backend (a Rust-side map is a scoped follow-up). The
+   * object is magic-string's `SourceMap`: it is a valid V3 map AND has
+   * `.toString()` / `.toUrl()`, so Vite/Rollup consume it directly.
+   */
+  map?: GeneratedSourceMap
+  /**
+   * Reactivity-lens spans — populated ONLY when `TransformOptions.reactivityLens`
+   * is `true`. Additive: codegen output is byte-identical whether or not this is
+   * collected. Each span is a faithful record of a reactivity decision the
+   * compiler made for that source range. See {@link ReactivitySpan}.
+   */
+  reactivityLens?: ReactivitySpan[]
 }
 
 // Props that should never be wrapped in a reactive getter
@@ -103,6 +178,73 @@ export interface TransformOptions {
    * // {count} in JSX → {() => count()}
    */
   knownSignals?: string[]
+
+  /**
+   * Collect the {@link ReactivitySpan} sidecar (`TransformResult.reactivityLens`).
+   * Default `false`. Purely additive — the emitted `code` is byte-identical
+   * whether this is on or off (asserted by the compiler equivalence tests).
+   * The lens records reactivity decisions the compiler ALREADY makes for
+   * codegen; it never runs a second analysis pass.
+   */
+  reactivityLens?: boolean
+
+  /**
+   * P0 — compile-time rocketstyle wrapper collapse. OFF unless the Vite
+   * plugin supplies this (opt-in `pyreon({ collapse: true })`). The plugin
+   * scans the module's imports for collapsible component candidates,
+   * SSR-resolves each literal-prop call site once (real component, light
+   * + dark), and passes the resolved `sites` map keyed by
+   * {@link rocketstyleCollapseKey}. The compiler only DETECTS the
+   * collapsible shape (bail catalogue — every dimension prop a string
+   * literal, no spread, static-text children) and EMITS the collapsed
+   * `_rsCollapse` call + the once-per-module rule injection; it never
+   * runs the rocketstyle chain itself (RFC decision 2).
+   */
+  collapseRocketstyle?: {
+    /** Component names imported into this module that MAY collapse. */
+    candidates: Set<string>
+    /** key → resolved emission data (absent ⇒ bail, keep normal mount). */
+    sites: Map<
+      string,
+      {
+        templateHtml: string
+        lightClass: string
+        darkClass: string
+        rules: string[]
+        ruleKey: string
+      }
+    >
+    /** Live mode accessor to thread for dual-emit (RFC decision 1). */
+    mode: { name: string; source: string }
+    /** Module specifier for `_rsCollapse`. Default `@pyreon/runtime-dom`. */
+    runtimeDomSource?: string
+    /** Module specifier for the styler `sheet`. Default `@pyreon/styler`. */
+    stylerSource?: string
+  }
+}
+
+/**
+ * Canonical key for a collapsible rocketstyle call site. The Vite plugin
+ * computes this when it resolves a site; the compiler recomputes the
+ * IDENTICAL key from the JSX node to look the resolution up. Stable
+ * ordering of props so attribute order in source doesn't change the key.
+ */
+export function rocketstyleCollapseKey(
+  componentName: string,
+  props: Record<string, string>,
+  childrenText: string,
+): string {
+  const propStr = Object.keys(props)
+    .sort()
+    .map((k) => `${k}=${props[k]}`)
+    .join('\u0001')
+  const src = `${componentName}\u0000${propStr}\u0000${childrenText}`
+  let h = 2166136261
+  for (let i = 0; i < src.length; i++) {
+    h ^= src.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return (h >>> 0).toString(36)
 }
 
 // ─── oxc ESTree helpers ───────────────────────────────────────────────────────
@@ -176,6 +318,215 @@ function jsxChildren(node: N): N[] {
   return node.children ?? []
 }
 
+/**
+ * A collapsible call site found by {@link scanCollapsibleSites}.
+ * `componentName` is the LOCAL JSX tag (post-import-alias) — it MUST be
+ * what `rocketstyleCollapseKey` is computed from on BOTH sides so the
+ * plugin's resolved `sites` map keys match the compiler's lookups.
+ */
+export interface CollapsibleSite {
+  /** Local JSX tag name (the key + the compiler's detection use this). */
+  componentName: string
+  /** Module specifier the component was imported from (for the resolver). */
+  source: string
+  /** Imported binding name at `source` (may differ from local if aliased). */
+  importedName: string
+  /** Literal string-valued props (the only shape the slice collapses). */
+  props: Record<string, string>
+  /** Static text children (trimmed; empty ⇒ none). */
+  childrenText: string
+  /** `rocketstyleCollapseKey(componentName, props, childrenText)`. */
+  key: string
+}
+
+/**
+ * Build a `localName → { imported, source }` table from a module's
+ * import declarations. Only named imports (`import { X as Y }`) are
+ * relevant — the collapsible components are always named exports.
+ */
+function collectImportTable(program: N): Map<string, { imported: string; source: string }> {
+  const table = new Map<string, { imported: string; source: string }>()
+  for (const stmt of program.body ?? []) {
+    if (stmt.type !== 'ImportDeclaration') continue
+    const source = stmt.source?.value
+    if (typeof source !== 'string') continue
+    for (const spec of stmt.specifiers ?? []) {
+      if (spec.type !== 'ImportSpecifier') continue
+      const local = spec.local?.name
+      const imported = spec.imported?.name ?? local
+      if (typeof local === 'string') table.set(local, { imported, source })
+    }
+  }
+  return table
+}
+
+/**
+ * Pure detector — finds every collapsible rocketstyle call site in a
+ * module. Used by `@pyreon/vite-plugin` to know which (component, props,
+ * text) tuples to SSR-resolve. The bail catalogue here MUST stay
+ * byte-identical to `tryRocketstyleCollapse`'s (RFC decision 3): a
+ * candidate PascalCase tag whose import source is in `collapsibleSources`,
+ * every attr a plain string literal (no spread, no `{expr}`, no boolean
+ * attr), children empty or static text only. A consistency test asserts
+ * the keys this produces equal the keys the compiler looks up.
+ */
+export function scanCollapsibleSites(
+  code: string,
+  filename: string,
+  collapsibleSources: Set<string>,
+): CollapsibleSite[] {
+  let program: N
+  try {
+    program = parseSync(filename, code, { sourceType: 'module', lang: getLang(filename) }).program
+  } catch {
+    return []
+  }
+  const imports = collectImportTable(program)
+  const out: CollapsibleSite[] = []
+  const visit = (node: N): void => {
+    if (!node || typeof node !== 'object') return
+    if (node.type === 'JSXElement') {
+      const tag = jsxTagName(node)
+      const imp = tag ? imports.get(tag) : undefined
+      if (
+        tag &&
+        tag.charAt(0) !== tag.charAt(0).toLowerCase() &&
+        imp &&
+        collapsibleSources.has(imp.source)
+      ) {
+        const site = detectCollapsibleShape(node, tag)
+        if (site) {
+          out.push({
+            componentName: tag,
+            source: imp.source,
+            importedName: imp.imported,
+            props: site.props,
+            childrenText: site.childrenText,
+            key: rocketstyleCollapseKey(tag, site.props, site.childrenText),
+          })
+        }
+      }
+    }
+    for (const k in node) {
+      const v = node[k]
+      if (Array.isArray(v)) for (const c of v) visit(c)
+      else if (v && typeof v === 'object' && typeof v.type === 'string') visit(v)
+    }
+  }
+  visit(program)
+  return out
+}
+
+/**
+ * The shared bail catalogue — every attr a string literal (no spread, no
+ * `{expr}`, no boolean attr), children empty or static text. Returns the
+ * extracted {props, childrenText} or null (bail). `tryRocketstyleCollapse`
+ * inlines the identical checks; a consistency test locks them together.
+ */
+function detectCollapsibleShape(
+  node: N,
+  _tag: string,
+): { props: Record<string, string>; childrenText: string } | null {
+  const props: Record<string, string> = {}
+  for (const attr of jsxAttrs(node)) {
+    if (attr.type !== 'JSXAttribute') return null // spread → bail
+    const nm = attr.name?.type === 'JSXIdentifier' ? attr.name.name : null
+    if (!nm) return null
+    const v = attr.value
+    if (!v) return null // boolean attr → bail
+    const isStr =
+      v.type === 'StringLiteral' || (v.type === 'Literal' && typeof v.value === 'string')
+    if (!isStr) return null // `{expr}` / dynamic → bail
+    props[nm] = String(v.value)
+  }
+  let childrenText = ''
+  for (const c of jsxChildren(node)) {
+    if (c.type === 'JSXText') childrenText += (c.value ?? '') as string
+    else return null // element / expression child → bail
+  }
+  return { props, childrenText: childrenText.trim() }
+}
+
+/** A residual event handler peeled off a partially-collapsible site. */
+export interface CollapsibleHandler {
+  /** JSX attribute name, e.g. `onClick`. */
+  name: string
+  /** Source span of the handler expression (the `{...}` contents). */
+  exprStart: number
+  exprEnd: number
+}
+
+/**
+ * Partial-collapse detector — PR 1 of the partial-collapse spec
+ * (`.claude/plans/open-work-2026-q3.md` → #1). The `on*`-handler-only
+ * subset the bail-reason census measured at 7.8% of all
+ * `@pyreon/ui-components` call sites (`collapse-bail-census.test.ts`).
+ *
+ * It is the EXACT `detectCollapsibleShape` bail catalogue with ONE
+ * relaxation: a `{expr}`-valued attribute whose name matches `on[A-Z]…`
+ * (an event handler) does NOT bail — it is peeled into `handlers[]`
+ * instead. Handlers are orthogonal to the SSR-resolved styler class (an
+ * event binding never changes rendered CSS), so the literal-prop subset
+ * still feeds the UNCHANGED `rocketstyleCollapseKey` and the resolver's
+ * pre-resolved `templateHtml` / `lightClass` / `darkClass` are
+ * byte-identical to a full-collapse site's. The collapsed runtime node
+ * just re-attaches the residual handlers (PR 2 — `_rsCollapseH`).
+ *
+ * Every OTHER non-literal shape still bails (spread, non-handler
+ * `{expr}` prop, boolean attr, element/expression child) — conservative
+ * by construction, exactly like the full detector. Returns `null` when
+ * there are ZERO handlers so the full-collapse path stays byte-unchanged
+ * and the two detectors never both claim the same site (full-collapse
+ * sites have no handlers; partial sites have ≥1). A consistency test
+ * will lock this catalogue against the plugin scan in PR 3, mirroring
+ * the existing `detectCollapsibleShape` ↔ `scanCollapsibleSites`
+ * invariant — keys cannot drift.
+ */
+export function detectPartialCollapsibleShape(
+  node: N,
+  _tag: string,
+): { props: Record<string, string>; childrenText: string; handlers: CollapsibleHandler[] } | null {
+  const props: Record<string, string> = {}
+  const handlers: CollapsibleHandler[] = []
+  for (const attr of jsxAttrs(node)) {
+    if (attr.type !== 'JSXAttribute') return null // spread → bail
+    const nm = attr.name?.type === 'JSXIdentifier' ? attr.name.name : null
+    if (!nm) return null
+    const v = attr.value
+    if (!v) return null // boolean attr → bail
+    const isStr =
+      v.type === 'StringLiteral' || (v.type === 'Literal' && typeof v.value === 'string')
+    if (isStr) {
+      props[nm] = String(v.value)
+      continue
+    }
+    // Non-literal: ONLY an `on[A-Z]…` handler in a `{expr}` container is
+    // peelable. Everything else (non-handler dynamic prop, shorthand
+    // `onClick` without a container, etc.) is a hard bail — same
+    // conservatism as the full detector.
+    if (
+      /^on[A-Z]/.test(nm) &&
+      v.type === 'JSXExpressionContainer' &&
+      v.expression &&
+      typeof v.expression.start === 'number' &&
+      typeof v.expression.end === 'number'
+    ) {
+      handlers.push({ name: nm, exprStart: v.expression.start, exprEnd: v.expression.end })
+      continue
+    }
+    return null // `{expr}` non-handler / dynamic → bail
+  }
+  let childrenText = ''
+  for (const c of jsxChildren(node)) {
+    if (c.type === 'JSXText') childrenText += (c.value ?? '') as string
+    else return null // element / expression child → bail
+  }
+  // Zero handlers ⇒ this is the FULL-collapse shape; defer to
+  // `detectCollapsibleShape` so the existing path stays byte-unchanged.
+  if (handlers.length === 0) return null
+  return { props, childrenText: childrenText.trim(), handlers }
+}
+
 // ─── Main transform ─────────────────────────────────────────────────────────
 
 export function transformJSX(
@@ -183,13 +534,25 @@ export function transformJSX(
   filename = 'input.tsx',
   options: TransformOptions = {},
 ): TransformResult {
+  // `collapseRocketstyle` emission lives only in the JS path (the Rust
+  // binary doesn't implement it and isn't passed the option). Force the
+  // JS path when collapse is requested so it isn't silently skipped —
+  // same pattern as `analyzeReactivity` forcing `transformJSX_JS`.
+  if (options.collapseRocketstyle) return transformJSX_JS(code, filename, options)
+
   // Try Rust native binary first (3.7-8.2x faster).
   // Per-call try/catch: if the native binary panics on an edge case
   // (bad UTF-8, unexpected AST shape), fall back gracefully instead
   // of crashing the Vite dev server.
   if (nativeTransformJsx) {
     try {
-      return nativeTransformJsx(code, filename, options.ssr === true, options.knownSignals ?? null)
+      return nativeTransformJsx(
+        code,
+        filename,
+        options.ssr === true,
+        options.knownSignals ?? null,
+        options.reactivityLens === true,
+      )
     } catch {
       // Native transform failed — fall through to JS implementation
     }
@@ -227,6 +590,25 @@ export function transformJSX_JS(
     warnings.push({ message, line, column, code: warnCode })
   }
 
+  // ── Reactivity lens (opt-in, additive — never affects `result`) ───────────
+  const collectLens = options.reactivityLens === true
+  const reactivityLens: ReactivitySpan[] = []
+  function lens(start: number, end: number, kind: ReactivityKind, detail: string): void {
+    if (!collectLens) return
+    const a = locate(start)
+    const b = locate(end)
+    reactivityLens.push({
+      start,
+      end,
+      line: a.line,
+      column: a.column,
+      endLine: b.line,
+      endColumn: b.column,
+      kind,
+      detail,
+    })
+  }
+
   // ── Parent + children maps (built once, eliminates repeated Object.keys) ──
   const parentMap = new WeakMap<object, N>()
   const childrenMap = new WeakMap<object, N[]>()
@@ -280,6 +662,109 @@ export function transformJSX_JS(
   let needsApplyPropsImportGlobal = false
   let needsMountSlotImportGlobal = false
 
+  // ── P0 rocketstyle-collapse state ─────────────────────────────────────────
+  let needsCollapse = false
+  let needsCollapseH = false
+  const collapseRuleKeys = new Set<string>()
+  const collapseRules: Array<{ ruleKey: string; rules: string[] }> = []
+
+  /**
+   * Detect + collapse a literal-prop rocketstyle call site. Conservative
+   * bail catalogue (RFC decision 3): PascalCase candidate, every attr a
+   * StringLiteral (no spread, no `{expr}`, no boolean attr), children
+   * empty or a single static JSXText. The plugin must already have
+   * SSR-resolved this exact (component, props, text) tuple — an absent
+   * `sites` entry is a hard bail (covers resolver-bailed shapes,
+   * cross-package-without-data, anything uncertain). Emits ONE
+   * `_rsCollapse(tpl, light, dark, () => mode()==='dark')` (dual-emit)
+   * plus a once-per-module idempotent `injectRules`. A false negative is
+   * correct-but-slow; a false positive is wrong output — so every
+   * uncertain signal returns false.
+   */
+  function tryRocketstyleCollapse(node: N): boolean {
+    const cfg = options.collapseRocketstyle
+    if (!cfg) return false
+    const tag = jsxTagName(node)
+    if (!tag || tag.charAt(0) === tag.charAt(0).toLowerCase()) return false
+    if (!cfg.candidates.has(tag)) return false
+    // Shared bail catalogue — IDENTICAL to scanCollapsibleSites (the
+    // plugin scans with the same predicate, so its resolved `sites`
+    // keys match these lookups exactly; no drift possible).
+    const shape = detectCollapsibleShape(node, tag)
+    if (!shape) return tryPartialCollapse(node, tag) // PR 3: on*-handler-only fallback
+    const { props, childrenText } = shape
+    const key = rocketstyleCollapseKey(tag, props, childrenText)
+    const site = cfg.sites.get(key)
+    if (!site) return false // not resolved → keep normal rocketstyle mount
+    const call =
+      `__rsCollapse(${JSON.stringify(site.templateHtml)}, ` +
+      `${JSON.stringify(site.lightClass)}, ${JSON.stringify(site.darkClass)}, ` +
+      `() => __pyrMode() === "dark")`
+    const start = node.start as number
+    const end = node.end as number
+    const parent = findParent(node)
+    const needsBraces =
+      parent && (parent.type === 'JSXElement' || parent.type === 'JSXFragment')
+    replacements.push({ start, end, text: needsBraces ? `{${call}}` : call })
+    needsCollapse = true
+    if (!collapseRuleKeys.has(site.ruleKey)) {
+      collapseRuleKeys.add(site.ruleKey)
+      collapseRules.push({ ruleKey: site.ruleKey, rules: site.rules })
+    }
+    return true
+  }
+
+  /**
+   * PR 3 of the partial-collapse build (open-work #1). The `on*`-handler-
+   * only fallback `tryRocketstyleCollapse` defers to when the FULL
+   * `detectCollapsibleShape` bails. Identical site-resolution contract as
+   * the full path — handlers are orthogonal to the SSR-resolved styler
+   * class, so the literal-prop subset feeds the UNCHANGED
+   * `rocketstyleCollapseKey` and the resolver's pre-resolved
+   * `templateHtml`/`lightClass`/`darkClass` are byte-identical to a
+   * full-collapse site's. The ONLY difference vs the full emit is
+   * `__rsCollapseH(...)` with a handlers object literal built from the
+   * sliced source spans `detectPartialCollapsibleShape` (PR 1) returned;
+   * the runtime helper (`_rsCollapseH`, PR 2 / #681) re-attaches them
+   * through the canonical event path. Same conservative discipline: an
+   * unresolved key, the option absent, or any non-handler non-literal
+   * shape ⇒ keep the normal mount (return false).
+   */
+  function tryPartialCollapse(node: N, tag: string): boolean {
+    const cfg = options.collapseRocketstyle
+    if (!cfg) return false
+    const partial = detectPartialCollapsibleShape(node, tag)
+    if (!partial) return false
+    const { props, childrenText, handlers } = partial
+    const key = rocketstyleCollapseKey(tag, props, childrenText)
+    const site = cfg.sites.get(key)
+    if (!site) return false // not resolved → keep normal rocketstyle mount
+    // `{ "onClick": (<sliced expr>), … }` — each handler expression is
+    // re-emitted verbatim from its source span (paren-wrapped so an
+    // arrow / sequence expr stays a single argument).
+    const handlerObj =
+      `{ ${handlers
+        .map((h) => `${JSON.stringify(h.name)}: (${code.slice(h.exprStart, h.exprEnd)})`)
+        .join(', ')} }`
+    const call =
+      `__rsCollapseH(${JSON.stringify(site.templateHtml)}, ` +
+      `${JSON.stringify(site.lightClass)}, ${JSON.stringify(site.darkClass)}, ` +
+      `() => __pyrMode() === "dark", ${handlerObj})`
+    const start = node.start as number
+    const end = node.end as number
+    const parent = findParent(node)
+    const needsBraces =
+      parent && (parent.type === 'JSXElement' || parent.type === 'JSXFragment')
+    replacements.push({ start, end, text: needsBraces ? `{${call}}` : call })
+    needsCollapse = true
+    needsCollapseH = true
+    if (!collapseRuleKeys.has(site.ruleKey)) {
+      collapseRuleKeys.add(site.ruleKey)
+      collapseRules.push({ ruleKey: site.ruleKey, rules: site.rules })
+    }
+    return true
+  }
+
   function maybeHoist(node: N): string | null {
     if (
       (node.type === 'JSXElement' || node.type === 'JSXFragment') &&
@@ -288,6 +773,12 @@ export function transformJSX_JS(
       const name = `_$h${hoistIdx++}`
       const text = code.slice(node.start as number, node.end as number)
       hoists.push({ name, text })
+      lens(
+        node.start as number,
+        node.end as number,
+        'hoisted-static',
+        'static — hoisted once to module scope, never re-evaluated',
+      )
       return name
     }
     return null
@@ -301,6 +792,7 @@ export function transformJSX_JS(
       ? `() => (${sliced})`
       : `() => ${sliced}`
     replacements.push({ start, end, text })
+    lens(start, end, 'reactive', 'live — re-evaluates whenever its signals change')
   }
 
   function hoistOrWrap(expr: N): void {
@@ -411,6 +903,7 @@ export function transformJSX_JS(
         const inner = expr.type === 'ObjectExpression' ? `(${sliced})` : sliced
         replacements.push({ start, end, text: `_rp(() => ${inner})` })
         needsRpImport = true
+        lens(start, end, 'reactive-prop', 'live prop — signal reads here are tracked into the component')
       }
     } else {
       hoistOrWrap(expr)
@@ -435,6 +928,15 @@ export function transformJSX_JS(
   // ── Prop-derived variable tracking (collected during the single walk) ─────
   const propsNames = new Set<string>()
   const propDerivedVars = new Map<string, { start: number; end: number }>()
+  // Round 9 fix: names of const/let bindings whose initializer is a JSX
+  // element (`const x = <El/>`). A bare `{x}` child of such a binding must be
+  // MOUNTED, not text-coerced — pre-fix it emitted `createTextNode(x)` which
+  // stringifies the NativeItem to "[object Object]". Routing through
+  // `_mountSlot` (the general child-insert `props.children` already uses) is
+  // safe even if a same-named binding is later shadowed by a string/number:
+  // `_mountSlot` renders those correctly too — the only cost of imprecision
+  // is skipping the createTextNode fast path, never a correctness regression.
+  const elementVars = new Set<string>()
 
   // ── Signal variable tracking (for auto-call in JSX) ──────────────────────
   // Tracks `const x = signal(...)` declarations. In JSX expressions, bare
@@ -541,6 +1043,18 @@ export function transformJSX_JS(
           }
         }
       }
+      // Round 9: track element-valued bindings (`const`/`let`, any depth) so
+      // a bare `{x}` child routes to _mountSlot instead of createTextNode.
+      // Tight: only a DIRECT JSX element/fragment initializer (optionally
+      // parenthesized) — conditionals/calls go the existing reactive/text
+      // paths and must not be reclassified here.
+      if ((node.kind === 'const' || node.kind === 'let') && decl.id?.type === 'Identifier' && decl.init) {
+        let initNode = decl.init
+        while (initNode?.type === 'ParenthesizedExpression') initNode = initNode.expression
+        if (initNode?.type === 'JSXElement' || initNode?.type === 'JSXFragment') {
+          elementVars.add(decl.id.name)
+        }
+      }
       if (node.kind !== 'const') continue
       if (callbackDepth > 0) continue
       if (decl.id?.type === 'Identifier' && decl.init) {
@@ -617,13 +1131,99 @@ export function transformJSX_JS(
     const endOffset = baseOffset + text.length
     const idents: { start: number; end: number; name: string }[] = []
 
+    // ── Scope-aware shadow tracking ──────────────────────────────────────────
+    // Prop-derived consts are only ever COLLECTED at component top level
+    // (callbackDepth === 0), so ANY same-named binding in a deeper lexical
+    // scope necessarily shadows it. Substituting a shadowed reference (or a
+    // binding occurrence) miscompiles idiomatic code — e.g.
+    // `const a = props.x; items.map(a => <li>{a}</li>)` would rewrite the
+    // arrow PARAMETER `a` into `(props.x)` (invalid `(props.x) =>`) and the
+    // body `{a}` (the map item) into `props.x`. The signal-auto-call pass is
+    // already scope-aware via `shadowedSignals`; this mirrors that discipline
+    // for the prop-derived inlining pass.
+    const shadowed = new Set<string>()
+
+    /** Collect identifier names bound by a pattern (params / declarators). */
+    function patternBindingNames(p: N, out: string[]): void {
+      if (!p) return
+      switch (p.type) {
+        case 'Identifier':
+          out.push(p.name)
+          break
+        case 'ObjectPattern':
+          for (const pr of p.properties ?? []) {
+            if (pr.type === 'RestElement') patternBindingNames(pr.argument, out)
+            else patternBindingNames(pr.value ?? pr.key, out)
+          }
+          break
+        case 'ArrayPattern':
+          for (const el of p.elements ?? []) patternBindingNames(el, out)
+          break
+        case 'AssignmentPattern':
+          patternBindingNames(p.left, out)
+          break
+        case 'RestElement':
+          patternBindingNames(p.argument, out)
+          break
+      }
+    }
+
+    /**
+     * Prop-derived names bound by `node` FOR ITS OWN SUBTREE (block-accurate
+     * lexical scoping). Excludes the prop-derived const's own defining
+     * declaration (matched by init span) so the binding we inline FROM is
+     * never mistaken for a shadow of itself.
+     */
+    function scopeBoundPropDerived(node: N): string[] {
+      const out: string[] = []
+      const t = node.type
+      const declNames = (declNode: N): void => {
+        for (const d of declNode.declarations ?? []) {
+          // The prop-derived defining declaration is NOT a shadow.
+          if (d.id?.type === 'Identifier' && propDerivedVars.has(d.id.name)) {
+            const span = propDerivedVars.get(d.id.name)!
+            if (d.init && (d.init.start as number) === span.start) continue
+          }
+          patternBindingNames(d.id, out)
+        }
+      }
+      if (
+        t === 'ArrowFunctionExpression' ||
+        t === 'FunctionExpression' ||
+        t === 'FunctionDeclaration'
+      ) {
+        for (const p of node.params ?? []) patternBindingNames(p, out)
+      } else if (t === 'CatchClause') {
+        patternBindingNames(node.param, out)
+      } else if (t === 'ForStatement') {
+        if (node.init?.type === 'VariableDeclaration') declNames(node.init)
+      } else if (t === 'ForInStatement' || t === 'ForOfStatement') {
+        if (node.left?.type === 'VariableDeclaration') declNames(node.left)
+      } else if (t === 'BlockStatement' || t === 'Program' || t === 'StaticBlock') {
+        const stmts = node.body ?? node.statements
+        if (Array.isArray(stmts)) {
+          for (const s of stmts) {
+            if (s.type === 'VariableDeclaration') declNames(s)
+            else if (s.type === 'FunctionDeclaration' && s.id?.type === 'Identifier') out.push(s.id.name)
+            else if (s.type === 'ClassDeclaration' && s.id?.type === 'Identifier') out.push(s.id.name)
+          }
+        }
+      }
+      return out.filter((n) => propDerivedVars.has(n))
+    }
+
     // Walk the AST to find identifiers in the span, passing parent context
     // to skip non-reference positions (property names, declarations, etc.)
+    // and a lexical shadow set so a same-named inner binding is never inlined.
     function findIdents(node: N, parent: N | null): void {
       const nodeStart = node.start as number
       const nodeEnd = node.end as number
       if (nodeStart >= endOffset || nodeEnd <= baseOffset) return
-      if (node.type === 'Identifier' && propDerivedVars.has(node.name)) {
+      if (
+        node.type === 'Identifier' &&
+        propDerivedVars.has(node.name) &&
+        !shadowed.has(node.name)
+      ) {
         if (parent) {
           if (parent.type === 'MemberExpression' && parent.property === node && !parent.computed) { /* skip */ }
           else if (parent.type === 'VariableDeclarator' && parent.id === node) { /* skip */ }
@@ -636,7 +1236,12 @@ export function transformJSX_JS(
           idents.push({ start: nodeStart, end: nodeEnd, name: node.name })
         }
       }
+      // Names this node binds for its subtree shadow the top-level prop-derived
+      // const within that subtree (and the binding occurrence itself).
+      const introduced = scopeBoundPropDerived(node).filter((n) => !shadowed.has(n))
+      for (const n of introduced) shadowed.add(n)
       forEachChildFast(node, (child) => findIdents(child, node))
+      for (const n of introduced) shadowed.delete(n)
     }
     findIdents(program, null)
 
@@ -767,6 +1372,11 @@ export function transformJSX_JS(
 
     // ── JSX processing (was pass 3) ──
     if (node.type === 'JSXElement') {
+      if (tryRocketstyleCollapse(node)) {
+        // Collapsed to _rsCollapse — children are baked into the SSR-
+        // resolved template; do not recurse into the subtree.
+        return
+      }
       if (!isSelfClosing(node) && tryTemplateEmit(node)) {
         // Template emitted — don't recurse into this subtree (JSXElement is never a function)
         return
@@ -803,22 +1413,35 @@ export function transformJSX_JS(
 
   walkNode(program)
 
-  if (replacements.length === 0 && hoists.length === 0) return { code, warnings }
+  if (replacements.length === 0 && hoists.length === 0) {
+    return collectLens ? { code, warnings, reactivityLens } : { code, warnings }
+  }
 
   replacements.sort((a, b) => a.start - b.start)
-  const outParts: string[] = []
-  let outPos = 0
+  // R12 fix: apply the disjoint, sorted {start,end,text} edits through
+  // MagicString instead of manual slice/join. `toString()` is byte-identical
+  // to the old concatenation (the full 1200-test suite + native-equivalence
+  // assert exact emitted strings), but `generateMap()` now yields a correct
+  // V3 source map — the previous transform emitted none AND shifted line
+  // counts (template emission expands one-line JSX into a multi-line _tpl
+  // factory), so every stack frame / breakpoint in a Pyreon component
+  // mislocated app-wide.
+  const s = new MagicString(code)
   for (const r of replacements) {
-    outParts.push(code.slice(outPos, r.start))
-    outParts.push(r.text)
-    outPos = r.end
+    if (r.start === r.end) s.appendLeft(r.start, r.text)
+    else s.update(r.start, r.end, r.text)
   }
-  outParts.push(code.slice(outPos))
-  let output = outParts.join('')
+
+  // Build the generated preamble (hoists + auto-imports + collapse prologue)
+  // in the SAME final top-to-bottom order the previous chained `X + output`
+  // produced, then `prepend` it ONCE. magic-string's prepend shifts every
+  // source mapping down by the preamble's line count, so original positions
+  // resolve to the correct OUTPUT lines despite the inserted preamble — the
+  // exact line-shift R12 measured. Innermost (closest to code) first.
+  let preamble = ''
 
   if (hoists.length > 0) {
-    const preamble = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join('')
-    output = preamble + output
+    preamble = hoists.map((h) => `const ${h.name} = /*@__PURE__*/ ${h.text}\n`).join('') + preamble
   }
 
   if (needsTplImport) {
@@ -830,19 +1453,53 @@ export function transformJSX_JS(
     const reactivityImports = needsBindImportGlobal
       ? `\nimport { _bind } from "@pyreon/reactivity";`
       : ''
-    output =
+    preamble =
       `import { ${runtimeDomImports.join(', ')} } from "@pyreon/runtime-dom";${reactivityImports}\n` +
-      output
+      preamble
   }
 
   if (needsRpImport || needsWrapSpreadImport) {
     const coreImports: string[] = []
     if (needsRpImport) coreImports.push('_rp')
     if (needsWrapSpreadImport) coreImports.push('_wrapSpread')
-    output = `import { ${coreImports.join(', ')} } from "@pyreon/core";\n` + output
+    preamble = `import { ${coreImports.join(', ')} } from "@pyreon/core";\n` + preamble
   }
 
-  return { code: output, usesTemplates: needsTplImport, warnings }
+  if (needsCollapse) {
+    const cfg = options.collapseRocketstyle!
+    const rd = cfg.runtimeDomSource ?? '@pyreon/runtime-dom'
+    const st = cfg.stylerSource ?? '@pyreon/styler'
+    // One idempotent injectRules per distinct rule bundle — keyed by the
+    // resolver's FNV so a re-eval (HMR) or another module's identical
+    // bundle is a no-op (styler dedupes by key). Runs at module-eval,
+    // before any collapsed site mounts, so the sheet is populated
+    // without a prior runtime mount of the real component.
+    const inj = collapseRules
+      .map(
+        (r) =>
+          `__rsSheet.injectRules(${JSON.stringify(r.rules)},${JSON.stringify(r.ruleKey)});`,
+      )
+      .join('')
+    preamble =
+      `import { _rsCollapse as __rsCollapse${needsCollapseH ? ', _rsCollapseH as __rsCollapseH' : ''} } from "${rd}";\n` +
+      `import { sheet as __rsSheet } from "${st}";\n` +
+      `import { ${cfg.mode.name} as __pyrMode } from "${cfg.mode.source}";\n` +
+      `${inj}\n` +
+      preamble
+  }
+
+  if (preamble) s.prepend(preamble)
+
+  const output = s.toString()
+  const map = s.generateMap({
+    source: filename,
+    includeContent: true,
+    hires: true,
+  }) as unknown as GeneratedSourceMap
+
+  return collectLens
+    ? { code: output, usesTemplates: needsTplImport, warnings, map, reactivityLens }
+    : { code: output, usesTemplates: needsTplImport, warnings, map }
 
   // ── Template emission helpers ─────────────────────────────────────────────
 
@@ -1017,6 +1674,12 @@ export function transformJSX_JS(
         bindLines.push(attrSetter(htmlAttrName, varName, expr))
         return
       }
+      lens(
+        exprNode.start as number,
+        exprNode.end as number,
+        'reactive-attr',
+        `live attribute — \`${htmlAttrName}\` re-applies whenever its signals change`,
+      )
       const directRef = tryDirectSignalRef(exprNode)
       if (directRef) {
         needsBindDirectImport = true
@@ -1214,16 +1877,36 @@ export function transformJSX_JS(
       }
       const needsPlaceholder = useMixed || useMultiExpr
       const { expr, isReactive } = unwrapAccessor(child.expression)
-      if (isChildrenExpression(child.expression, expr)) {
+      // Round 9 fix: a bare `{el}` where `el` is an element-valued binding
+      // (`const el = <X/>`) must be MOUNTED via _mountSlot, not text-coerced
+      // via createTextNode (which stringifies the NativeItem). Same emission
+      // as the children-slot path; _mountSlot handles every child type.
+      const isElementValuedIdent =
+        (child.expression?.type === 'Identifier' && elementVars.has(child.expression.name)) ||
+        (!isReactive && /^[A-Za-z_$][\w$]*$/.test(expr) && elementVars.has(expr))
+      if (isChildrenExpression(child.expression, expr) || isElementValuedIdent) {
         needsMountSlotImport = true
         const placeholder = `${parentRef}.childNodes[${childNodeIdx}]`
         const d = nextDisp()
         bindLines.push(`const ${d} = _mountSlot(${expr}, ${parentRef}, ${placeholder})`)
         return '<!>'
       }
+      const cx = child.expression
       if (isReactive) {
+        lens(
+          cx.start as number,
+          cx.end as number,
+          'reactive',
+          'live — this text re-renders whenever its signals change',
+        )
         return emitReactiveTextChild(expr, child.expression, varName, parentRef, childNodeIdx, needsPlaceholder)
       }
+      lens(
+        cx.start as number,
+        cx.end as number,
+        'static-text',
+        'baked once into the DOM — never re-renders (no signal read here)',
+      )
       return emitStaticTextChild(expr, varName, parentRef, childNodeIdx, needsPlaceholder)
     }
 
@@ -1360,14 +2043,95 @@ export function transformJSX_JS(
 
   /** Auto-insert () after signal variable references in the expression source.
    *  Uses the AST to find exact Identifier positions — never scans raw text. */
+  // Recursively collect identifier names bound by a pattern (params /
+  // declarators). Self-contained twin of resolveIdentifiersInText's
+  // `patternBindingNames` (different closure scope; kept local to avoid a
+  // risky shared-helper hoist).
+  function sigPatternNames(p: N, out: string[]): void {
+    if (!p) return
+    switch (p.type) {
+      case 'Identifier':
+        out.push(p.name)
+        break
+      case 'ObjectPattern':
+        for (const pr of p.properties ?? []) {
+          if (pr.type === 'RestElement') sigPatternNames(pr.argument, out)
+          else sigPatternNames(pr.value ?? pr.key, out)
+        }
+        break
+      case 'ArrayPattern':
+        for (const el of p.elements ?? []) sigPatternNames(el, out)
+        break
+      case 'AssignmentPattern':
+        sigPatternNames(p.left, out)
+        break
+      case 'RestElement':
+        sigPatternNames(p.argument, out)
+        break
+    }
+  }
+
+  // Signal names a scope-introducing node binds FOR ITS OWN SUBTREE
+  // (block-accurate lexical scoping). Mirrors scopeBoundPropDerived but
+  // against `signalVars` — a same-named inner binding (callback param,
+  // nested const, catch/loop var) shadows the signal and must NOT be
+  // auto-called (doing so emits `paramValue()` → runtime TypeError).
+  function scopeBoundSignals(node: N): string[] {
+    const out: string[] = []
+    const t = node.type
+    const declNames = (declNode: N): void => {
+      for (const d of declNode.declarations ?? []) {
+        // A `const x = signal(...)` re-declaration is itself a signal, not a
+        // shadow — leave it for the normal signalVars path.
+        if (d.id?.type === 'Identifier' && d.init && isSignalCall(d.init)) continue
+        sigPatternNames(d.id, out)
+      }
+    }
+    if (
+      t === 'ArrowFunctionExpression' ||
+      t === 'FunctionExpression' ||
+      t === 'FunctionDeclaration'
+    ) {
+      for (const p of node.params ?? []) sigPatternNames(p, out)
+    } else if (t === 'CatchClause') {
+      sigPatternNames(node.param, out)
+    } else if (t === 'ForStatement') {
+      if (node.init?.type === 'VariableDeclaration') declNames(node.init)
+    } else if (t === 'ForInStatement' || t === 'ForOfStatement') {
+      if (node.left?.type === 'VariableDeclaration') declNames(node.left)
+    } else if (t === 'BlockStatement' || t === 'StaticBlock') {
+      const stmts = node.body ?? node.statements
+      if (Array.isArray(stmts)) {
+        for (const s of stmts) {
+          if (s.type === 'VariableDeclaration') declNames(s)
+          else if (s.type === 'FunctionDeclaration' && s.id?.type === 'Identifier') out.push(s.id.name)
+          else if (s.type === 'ClassDeclaration' && s.id?.type === 'Identifier') out.push(s.id.name)
+        }
+      }
+    }
+    return out.filter((n) => signalVars.has(n))
+  }
+
   function autoCallSignals(text: string, expr: N): string {
     const start = expr.start as number
     // Collect signal identifier positions that need auto-calling
     const idents: { start: number; end: number }[] = []
+    // Local lexical shadow set — a signal-named binding introduced INSIDE
+    // the rewritten expression (callback param, nested const, …) is NOT the
+    // signal and must not get `()` (R11: scope-blind rewrite emitted
+    // `({x}) => <li>{x()}</li>` → `1()` runtime crash).
+    const shadowed = new Set<string>()
 
     function findSignalIdents(node: N): void {
       if ((node.start as number) >= start + text.length || (node.end as number) <= start) return
-      if (node.type === 'Identifier' && isActiveSignal(node.name)) {
+      const introduced: string[] = []
+      for (const n of scopeBoundSignals(node)) {
+        if (!shadowed.has(n)) {
+          shadowed.add(n)
+          introduced.push(n)
+        }
+      }
+      if (node.type === 'Identifier' && isActiveSignal(node.name) && !shadowed.has(node.name)) {
         const parent = findParent(node)
         // Skip property name positions (obj.name)
         if (parent && parent.type === 'MemberExpression' && parent.property === node && !parent.computed) return
@@ -1405,6 +2169,7 @@ export function transformJSX_JS(
         idents.push({ start: node.start as number, end: node.end as number })
       }
       forEachChildFast(node, findSignalIdents)
+      for (const n of introduced) shadowed.delete(n)
     }
     findSignalIdents(expr)