@barefootjs/jsx 0.31.0 → 0.31.2

package/src/analyzer.ts

@@ -8,9 +8,10 @@
 
 import ts from 'typescript'
 import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo, DeclinedReactiveFactory, RequiredFactoryImport, FactoryRenameSite, SourceLocation } from './types.ts'
-import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
+import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr, tsNodeToParsedExpr } from './expression-parser.ts'
 import type { CallbackBodyAcceptor } from './adapters/interface.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
+import { buildPropAliasMap } from './props-binding.ts'
 import { incrementCounter } from './instrumentation.ts'
 import {
   type AnalyzerContext,
@@ -1273,7 +1274,8 @@ function collectSignal(node: ts.VariableDeclaration, ctx: AnalyzerContext): void
   if (!ctx.propsObjectName && callExpr.arguments[0]) {
     const propNames = new Set(ctx.propsParams.map(p => p.name))
     if (propNames.size > 0) {
-      templateInitialValue = rewriteBarePropRefs(initialValue, callExpr.arguments[0], propNames)
+      const propAliases = buildPropAliasMap(ctx.propsParams)
+      templateInitialValue = rewriteBarePropRefs(initialValue, callExpr.arguments[0], propNames, undefined, propAliases)
     }
   }
 
@@ -1613,7 +1615,8 @@ function collectMemo(node: ts.VariableDeclaration, ctx: AnalyzerContext): void {
   if (!ctx.propsObjectName && callExpr.arguments[0]) {
     const propNames = new Set(ctx.propsParams.map(p => p.name))
     if (propNames.size > 0) {
-      templateComputation = rewriteBarePropRefs(computation, callExpr.arguments[0], propNames)
+      const propAliases = buildPropAliasMap(ctx.propsParams)
+      templateComputation = rewriteBarePropRefs(computation, callExpr.arguments[0], propNames, undefined, propAliases)
     }
   }
 
@@ -3129,9 +3132,15 @@ function collectConstant(
   let templateValue: string | undefined
   if (value && ctx.propsParams.length > 0 && node.initializer) {
     let propNames: Set<string>
+    // Local → caller-facing key (#2524 CSR half) — only Case 1 propsParams
+    // entries can carry `sourceName`; Case 2's alias set below is keyed by
+    // the destructured-from-`props.X` local name, which by its own
+    // `isPureAlias` construction always equals the source key.
+    let propAliases: Map<string, string> | undefined
     if (!ctx.propsObjectName) {
       // Case 1: destructured-arg — all propsParams are bare locals.
       propNames = new Set(ctx.propsParams.map(p => p.name))
+      propAliases = buildPropAliasMap(ctx.propsParams)
     } else {
       // Case 2: `(props)`-arg — restrict to body-destructured pure aliases
       // of `props.X` (entries pushed by the body-destructure expansion at
@@ -3157,7 +3166,7 @@ function collectConstant(
       )
     }
     if (propNames.size > 0) {
-      const rewritten = rewriteBarePropRefs(value, node.initializer, propNames)
+      const rewritten = rewriteBarePropRefs(value, node.initializer, propNames, undefined, propAliases)
       if (rewritten !== undefined) {
         templateValue = rewritten
         // For the body-destructure case, also rewrite the init-body
@@ -3307,6 +3316,12 @@ function extractProps(param: ts.ParameterDeclaration, ctx: AnalyzerContext): voi
         const resolvedType: TypeInfo = member?.type ?? { kind: 'unknown', raw: 'unknown' }
 
         const defaultContainsArrow = element.initializer ? nodeContainsArrow(element.initializer) : false
+        // Structured mirror of `defaultValue`, from the binding element's OWN
+        // `initializer` node — `tsNodeToParsedExpr` converts the already-parsed
+        // AST directly, no re-parse of the `defaultValue` text (same convention
+        // as `SignalInfo.parsed`). An unsupported shape leaves `parsed` unset;
+        // consumers fall back to `defaultValue` text.
+        const parsedDefault = element.initializer ? tsNodeToParsedExpr(element.initializer) : undefined
         ctx.propsParams.push({
           name: localName,
           type: resolvedType,
@@ -3314,6 +3329,7 @@ function extractProps(param: ts.ParameterDeclaration, ctx: AnalyzerContext): voi
           // the caller may omit the prop.
           optional: !!member?.optional || !!element.initializer,
           defaultValue,
+          ...(parsedDefault && parsedDefault.kind !== 'unsupported' && { parsed: parsedDefault }),
           defaultContainsArrow: defaultContainsArrow || undefined,
           // Only aliased bindings carry the source key — see ParamInfo.sourceName.
           ...(sourcePropName !== localName && { sourceName: sourcePropName }),
@@ -3631,21 +3647,47 @@ function inferTypeFromValue(value: string): TypeInfo {
   return { kind: 'unknown', raw: 'unknown' }
 }
 
+/**
+ * Identifiers that appear as a direct call (`name(...)`) in `code`,
+ * collected off a real TS parse — never a regex over the raw text, which
+ * false-matches inside comments and string literals (the repo-wide
+ * "no regex over JS syntax" rule). A doc comment mentioning
+ * `otherSignal()` inside a memo body must NOT become a dependency
+ * (phantom `internalValue`/`controlledValue` deps on slider's
+ * `percentage`, #2581 review). A raw token scan is not enough either:
+ * without a parser driving `reScanTemplateToken`, everything between a
+ * substitution's closing `}` and the next backtick is mis-lexed as code
+ * (and the template tail swallows real code after it), so a read
+ * following a `${...}` template — xyflow's `visibleClass` reading
+ * `animated()` after the `${BF_FLOW_EDGE_SELECTED}` line — would vanish.
+ */
+function collectCalledIdentifiers(code: string): Set<string> {
+  const called = new Set<string>()
+  const sf = ts.createSourceFile('__deps__.tsx', code, ts.ScriptTarget.Latest, false, ts.ScriptKind.TSX)
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      called.add(node.expression.text)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return called
+}
+
 function extractDependencies(code: string, ctx: AnalyzerContext): string[] {
+  const called = collectCalledIdentifiers(code)
   const deps: string[] = []
 
   // Find signal getter calls: signalName()
   for (const signal of ctx.signals) {
-    const pattern = new RegExp(`\\b${signal.getter}\\s*\\(`, 'g')
-    if (pattern.test(code)) {
+    if (called.has(signal.getter)) {
       deps.push(signal.getter)
     }
   }
 
   // Find memo calls: memoName()
   for (const memo of ctx.memos) {
-    const pattern = new RegExp(`\\b${memo.name}\\s*\\(`, 'g')
-    if (pattern.test(code)) {
+    if (called.has(memo.name)) {
       deps.push(memo.name)
     }
   }

package/src/compiler.ts

@@ -11,6 +11,7 @@ import type {
   CompileResult,
   FileOutput,
 } from './types.ts'
+import ts from 'typescript'
 import type { TemplateAdapter } from './adapters/interface.ts'
 import { analyzeComponent, listComponentFunctions, createProgramForFile, needsTypeBasedDetection } from './analyzer.ts'
 import { jsxToIR } from './jsx-to-ir.ts'
@@ -21,12 +22,13 @@ import { emitModuleLevelDeclarations } from './ir-to-client-js/emit-module-level
 import { RUNTIME_MODULE, detectUsedImports as detectUsedImportsFromCode, makeValueUsageTest } from './ir-to-client-js/imports.ts'
 import { setActiveComponentScope, computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { generateModuleExports, collectInlineExportedNames } from './module-exports.ts'
-import { applyCssLayerPrefix } from './css-layer-prefixer.ts'
+import { applyCssLayerPrefix, applyCssLayerPrefixToFile } from './css-layer-prefixer.ts'
 import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.ts'
 import { extractSsrDefaults } from './ssr-defaults.ts'
 import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
 import { checkRichTypeMethodCalls } from './rich-type-refusal.ts'
-import { ErrorCodes } from './errors.ts'
+import { ErrorCodes, createError } from './errors.ts'
+import { collectComponentNamesFromIR } from './ir-to-client-js/child-components.ts'
 
 /**
  * Extended compile options with required adapter
@@ -163,11 +165,88 @@ function compileMultipleComponents(
     // call for why this must run before adapter.generate/generateClientJs.
     decideClientOnlyElision(componentIR.root)
 
-    if (options.cssLayerPrefix) {
-      applyCssLayerPrefix(componentIR, options.cssLayerPrefix)
+    entries.push({ componentIR, ctx })
+  }
+
+  // BF048 — refuse loudly when an emitted component template references a
+  // same-file sibling that was in `componentNames` (so `listComponentFunctions`
+  // treated it as a component to compile — the 'use client' branch of #932
+  // does exactly that for multi-return JSX dispatch shapes) but never made
+  // it into `entries` (its own `analyzeComponent`/`jsxToIR` pass produced no
+  // usable IR — most commonly a top-level `switch` dispatch, which
+  // `visitComponentBody` preserves as a verbatim init statement rather than
+  // folding into `conditionalReturns`, so `ctx.jsxReturn` stays null).
+  // Pre-fix this compiled clean and the emitted `renderChild`/`initChild`/
+  // `createComponent` call threw `ReferenceError: <Name> is not defined` at
+  // SSR/hydrate time (#2556) — the silence itself is the bug. Detection
+  // walks the IR component-reference graph (the same walk that drives
+  // `@bf-child` import markers, `collectComponentNamesFromIR`), never the
+  // emitted template text.
+  //
+  // Restricted to TOP-LEVEL declarations: `listComponentFunctions` recurses
+  // into function bodies, so `componentNames` also carries component-scope
+  // local factories (`const Inner = () => <span/>` inside a component).
+  // Those never compile to standalone templates either, but their call
+  // sites are handled by the JSX-function-inlining pass — flagging them
+  // here would fail legal programs (the ir-dynamic-tag / resolver-alias
+  // corpus shapes). Only a name declared at module top level can be the
+  // dropped-sibling shape this diagnostic exists for.
+  //
+  // Restricted to 'use client' FILES: only the 'use client' branch of #932
+  // widens `listComponentFunctions` to multi-return dispatch shapes; in a
+  // non-client file an uncompiled sibling is preserved verbatim (that is
+  // the escape hatch the message below recommends), so flagging it there
+  // would fail exactly the programs the fix tells users to write.
+  if (entries.some(e => e.componentIR.metadata.isClientComponent)) {
+    const topLevelNames = new Set<string>()
+    {
+      const sf = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+      for (const stmt of sf.statements) {
+        if (ts.isFunctionDeclaration(stmt) && stmt.name) topLevelNames.add(stmt.name.text)
+        else if (ts.isVariableStatement(stmt)) {
+          for (const d of stmt.declarationList.declarations) {
+            if (ts.isIdentifier(d.name)) topLevelNames.add(d.name.text)
+          }
+        }
+      }
+    }
+    const compiledNames = new Set(entries.map(e => e.componentIR.metadata.componentName))
+    const uncompiledSiblings = new Set(
+      componentNames.filter(name => !compiledNames.has(name) && topLevelNames.has(name)),
+    )
+    if (uncompiledSiblings.size > 0) {
+      for (const { componentIR } of entries) {
+        const referenced = new Set<string>()
+        collectComponentNamesFromIR([componentIR.root], referenced)
+        for (const name of referenced) {
+          if (!uncompiledSiblings.has(name)) continue
+          errors.push(createError(
+            ErrorCodes.SIBLING_COMPONENT_NOT_COMPILED,
+            componentIR.root.loc,
+            {
+              message:
+                `Component '${componentIR.metadata.componentName}' references sibling ` +
+                `'<${name}>', which did not compile to a template in this 'use client' file ` +
+                `(likely a multi-return JSX dispatch — a \`switch\` or \`if\`/\`else\` chain ` +
+                `across multiple JSX-returning branches). This reference would throw ` +
+                `\`ReferenceError: ${name} is not defined\` at SSR/hydrate time. Extract '${name}' ` +
+                `to a separate non-"use client" file (where #932 preserves it verbatim), or ` +
+                `rewrite it as a single-return ternary/conditional chain so the component ` +
+                `pipeline can compile it.`,
+            },
+          ))
+        }
+      }
     }
+  }
 
-    entries.push({ componentIR, ctx })
+  // CSS layer prefixing must be FILE-WIDE: per-IR application diverges the
+  // per-component copies of a shared module-scope constant (prefixed in the
+  // components whose class attrs reference it, raw elsewhere), and module
+  // shape emission (#2570) would then declare the constant twice. See
+  // `applyCssLayerPrefixToFile`.
+  if (options.cssLayerPrefix) {
+    applyCssLayerPrefixToFile(entries.map(e => e.componentIR), options.cssLayerPrefix)
   }
 
   // BF050 is a per-FILE diagnostic (it points at the brand-package import
@@ -220,13 +299,35 @@ function compileMultipleComponents(
     }
   }
 
-  // Module-scope statements (e.g. SSR-side context bindings) are file-wide:
-  // every component in the same source file generates the same block, so we
-  // collect via exact-string dedup and emit once at the file level rather
-  // than per component (per-line dedup of imports drops repeated lines like
-  // closing `})` that recur across multiple multi-line bindings).
-  const moduleConstantsSet = new Set<string>()
-  const moduleConstantsOrdered: string[] = []
+  // Module-scope statements (types, consts, functions, SSR-side context
+  // bindings) are file-wide, but each component's IR may carry a different
+  // SUBSET — the analyzer collects the module declarations lexically
+  // preceding the component, so in a file that interleaves constants with
+  // component functions the blocks are unequal prefixes of one another
+  // (carousel does this). Whole-block string dedup would then emit every
+  // prefix and redeclare each name (TS2300/TS2451), while per-LINE dedup
+  // would corrupt multi-line declarations (repeated `})` lines collapse).
+  // So dedup at the TOP-LEVEL-STATEMENT level via a TS parse of each block
+  // — the repo-wide idiom for splitting emitted source (never regex/line
+  // matching). Identical statements re-collected across components dedup
+  // to their first occurrence, preserving source order.
+  const moduleStatementSeen = new Set<string>()
+  const moduleStatementsOrdered: string[] = []
+  const collectModuleStatements = (block: string): void => {
+    const sf = ts.createSourceFile(
+      '__bf_module_decls.tsx',
+      block,
+      ts.ScriptTarget.Latest,
+      /* setParentNodes */ false,
+      ts.ScriptKind.TSX,
+    )
+    for (const stmt of sf.statements) {
+      const text = stmt.getText(sf)
+      if (moduleStatementSeen.has(text)) continue
+      moduleStatementSeen.add(text)
+      moduleStatementsOrdered.push(text)
+    }
+  }
 
   // Component-name scope: rewrite `hydrate` / `renderChild` / `initChild` /
   // `createComponent` / `upsertChild` keys for non-exported helpers
@@ -271,6 +372,7 @@ function compileMultipleComponents(
       componentIR,
       fileWideInlineExported,
       options.rewriteRelativeImport,
+      { skipValueDeclarations: adapterOutput.sections.moduleConstantsIncludeExports },
     )
 
     const s = adapterOutput.sections
@@ -278,10 +380,7 @@ function compileMultipleComponents(
     const types = s.types
     const component = s.component + (s.defaultExport || '')
     const mc = s.moduleConstants
-    if (mc && !moduleConstantsSet.has(mc)) {
-      moduleConstantsSet.add(mc)
-      moduleConstantsOrdered.push(mc)
-    }
+    if (mc) collectModuleStatements(mc)
 
     allOutputs.push({
       componentName: componentIR.metadata.componentName,
@@ -415,7 +514,7 @@ function compileMultipleComponents(
   // Combine all components
   const combinedTemplate = [
     mergedImports,
-    moduleConstantsOrdered.join('\n\n'),
+    moduleStatementsOrdered.join('\n\n'),
     uniqueTypes.join('\n\n'),
     uniqueModuleExports.length > 0 ? uniqueModuleExports.join('\n') : '',
     ...allOutputs.map(o => o.component),
@@ -721,7 +820,9 @@ export function compileJSX(
   if (adapter.templatesPerComponent) {
     content = adapterOutput.template
   } else {
-    const moduleExports = generateModuleExports(componentIR, undefined, options.rewriteRelativeImport)
+    const moduleExports = generateModuleExports(componentIR, undefined, options.rewriteRelativeImport, {
+      skipValueDeclarations: s.moduleConstantsIncludeExports,
+    })
     content = [s.imports, s.moduleConstants ?? '', s.types, moduleExports, s.component]
       .filter(Boolean).join('\n\n') + (s.defaultExport || '')
   }

package/src/css-layer-prefixer.ts

@@ -80,9 +80,87 @@ export function prefixConstantValue(rawValue: string, layerName: string): string
  * Prefixes static class attributes and class-related constant values.
  */
 export function applyCssLayerPrefix(ir: ComponentIR, layerName: string): void {
+  applyCssLayerPrefixToFile([ir], layerName)
+}
+
+/**
+ * File-wide variant: apply the prefix across ALL of a file's component IRs
+ * with ONE union of referenced constants.
+ *
+ * Each component's IR carries its own `ConstantInfo` copies of the file's
+ * module-scope constants, and per-IR application prefixed only the copies
+ * the component's own class attributes referenced. That was invisible while
+ * every component re-declared the constants inside its body, but module
+ * shape emission (#2570) hoists them to ONE module-scope declaration —
+ * per-component divergence then emits the same constant twice with
+ * different values ("tabsClasses has already been declared", tabs in the
+ * site/ui build). Applying the union keeps every IR's copy byte-identical,
+ * so the compiler's statement-level dedup collapses them to a single,
+ * consistently-prefixed declaration.
+ */
+export function applyCssLayerPrefixToFile(irs: readonly ComponentIR[], layerName: string): void {
   const referencedConstants = new Set<string>()
-  const constantNames = new Set(ir.metadata.localConstants.map(c => c.name))
+  const constantNames = new Set<string>()
+  for (const ir of irs) {
+    for (const c of ir.metadata.localConstants) constantNames.add(c.name)
+  }
+
+  // Walk every IR tree and process className/class attributes, collecting
+  // referenced constants into the shared union.
+  for (const ir of irs) {
+    collectAndPrefixAttrs(ir, layerName, referencedConstants, constantNames)
+  }
+
+  // Resolve transitive references (constants referencing other constants) —
+  // against every IR's constant list, since a name may only carry a value
+  // in the IRs whose lexical prefix includes it.
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const constName of [...referencedConstants]) {
+      for (const ir of irs) {
+        const constant = ir.metadata.localConstants.find(c => c.name === constName)
+        if (!constant || !constant.value) continue
+        for (const id of extractIdentifiers(constant.value)) {
+          if (constantNames.has(id) && !referencedConstants.has(id)) {
+            referencedConstants.add(id)
+            changed = true
+          }
+        }
+      }
+    }
+  }
 
+  // Apply prefixing to every IR's copy of each referenced constant.
+  //
+  // `typedValue` (the type-annotation-preserving initializer text used by
+  // `preserveTypes` emitters — Hono's `generateModuleScopeDeclarations` /
+  // SSR body block prefer `typedValue ?? value`) is a separate string that
+  // must be prefixed in lockstep with `value`, or an `as const` / annotated
+  // class-map constant is emitted unprefixed even though the class
+  // attributes referencing it were prefixed (#2575). `prefixConstantValue`
+  // only rewrites string-literal contents (see its docstring), so an `as
+  // const` suffix or type annotation elsewhere in the text passes through
+  // unchanged.
+  for (const ir of irs) {
+    for (const constant of ir.metadata.localConstants) {
+      if (!referencedConstants.has(constant.name)) continue
+      if (constant.value) {
+        constant.value = prefixConstantValue(constant.value, layerName)
+      }
+      if (constant.typedValue) {
+        constant.typedValue = prefixConstantValue(constant.typedValue, layerName)
+      }
+    }
+  }
+}
+
+function collectAndPrefixAttrs(
+  ir: ComponentIR,
+  layerName: string,
+  referencedConstants: Set<string>,
+  constantNames: ReadonlySet<string>,
+): void {
   // Walk IR tree and process className/class attributes
   walkIR(ir.root, (node) => {
     if (node.type !== 'element') return
@@ -118,28 +196,6 @@ export function applyCssLayerPrefix(ir: ComponentIR, layerName: string): void {
     }
   })
 
-  // Resolve transitive references (constants referencing other constants)
-  let changed = true
-  while (changed) {
-    changed = false
-    for (const constName of [...referencedConstants]) {
-      const constant = ir.metadata.localConstants.find(c => c.name === constName)
-      if (!constant || !constant.value) continue
-      for (const id of extractIdentifiers(constant.value)) {
-        if (constantNames.has(id) && !referencedConstants.has(id)) {
-          referencedConstants.add(id)
-          changed = true
-        }
-      }
-    }
-  }
-
-  // Apply prefixing to referenced constants
-  for (const constant of ir.metadata.localConstants) {
-    if (referencedConstants.has(constant.name) && constant.value) {
-      constant.value = prefixConstantValue(constant.value, layerName)
-    }
-  }
 }
 
 // =============================================================================
@@ -168,7 +224,7 @@ function prefixIRTemplateParts(parts: IRTemplatePart[], layerName: string): void
 function collectConstantRefs(
   expr: string,
   refs: Set<string>,
-  validNames: Set<string>,
+  validNames: ReadonlySet<string>,
 ): void {
   for (const id of extractIdentifiers(expr)) {
     if (validNames.has(id)) {

package/src/errors.ts

@@ -43,6 +43,16 @@ export const ErrorCodes = {
   // ReferenceError at hydrate. Fail loud with workaround pointers
   // (#1414 cell 5).
   JSX_BRANCH_LOCAL_IN_CALLBACK: 'BF047',
+  // A `'use client'` file's emitted template references a same-file
+  // sibling component (`<NavIcon .../>`, a `.map()` child, …) whose own
+  // body never produced a template — most commonly a multi-return JSX
+  // dispatch (`switch` / `if`-`else` chain) that `compileMultipleComponents`
+  // silently dropped from its output. Pre-fix this compiled clean and threw
+  // `ReferenceError: <Name> is not defined` at SSR/hydrate time (#2556). The
+  // equivalent shape in a NON-"use client" file is fine — #932 preserves the
+  // helper verbatim instead of compiling it as a component — so this code
+  // fires only for the client-component compilation path.
+  SIBLING_COMPONENT_NOT_COMPILED: 'BF048',
 
   // Import errors (BF050-BF059)
   SHARED_PROGRAM_REQUIRED: 'BF050',
@@ -146,6 +156,14 @@ const errorMessages: Record<ErrorCode, string> = {
     "JSX-typed local declared inside an `if`-block cannot be referenced from a callback body (ref / event handler). " +
     "Render it as a child instead: `<div ref={...}>{local}</div>`.",
 
+  [ErrorCodes.SIBLING_COMPONENT_NOT_COMPILED]:
+    "Referenced component did not compile to a template, so this reference would throw " +
+    "`ReferenceError` at render time. Multi-return JSX dispatch (a `switch` or `if`/`else` " +
+    "chain across multiple JSX-returning branches) cannot compile as a component in a " +
+    "'use client' file. Extract it to a separate non-\"use client\" file (where it is preserved " +
+    "verbatim, see #932), or rewrite it as a single-return ternary/conditional chain so the " +
+    "component pipeline can compile it.",
+
   [ErrorCodes.SHARED_PROGRAM_REQUIRED]:
     'Shared ts.Program required for type-based reactivity classification. This source imports a Reactive<T>-branded library (e.g. @barefootjs/form) whose getters cannot be classified by regex alone. Pass `options.program` (built via `createProgramForCorpus`) so the analyzer can resolve the brand through the TypeChecker.',
 

package/src/html-types.ts

@@ -248,6 +248,30 @@ export interface SVGPresentationAttributes {
   filter?: string
 }
 
+// ============================================================================
+// SVG Root (`<svg>`) Attributes
+// ============================================================================
+
+/**
+ * Attributes for the root `<svg>` element, narrowed to `SVGSVGElement` for
+ * `ref`. A curated subset mirroring the intrinsic `svg` entry — not the full
+ * SVG attribute surface.
+ *
+ * Public so components that render an `<svg>` as their root and accept
+ * passthrough props (icons, spinners, and similar) can type their props with
+ * this instead of `HTMLBaseAttributes` — spreading `HTMLBaseAttributes` onto
+ * an `<svg>` fails to type-check because its `ref` is `(element: HTMLElement)
+ * => void`, incompatible with the `<svg>` intrinsic's
+ * `(element: SVGSVGElement) => void` (#2573).
+ */
+export type SVGSVGAttributes = SVGBaseAttributes & SVGPresentationAttributes & {
+  viewBox?: string
+  xmlns?: string
+  width?: number | string
+  height?: number | string
+  ref?: (element: SVGSVGElement) => void
+}
+
 /**
  * Marker reference attributes shared by `<path>`, `<line>`, `<polyline>`,
  * and `<polygon>`. Accepts both camelCase and kebab-case spellings.

package/src/index.ts

@@ -9,7 +9,10 @@ export { compileJSX, buildMetadata } from './compiler.ts'
 export type { CompileResult, CompileOptions, CompileOptionsWithAdapter, FileOutput } from './compiler.ts'
 
 // SSR template-variable defaults (manifest seeds for stash-based adapters)
-export { extractSsrDefaults } from './ssr-defaults.ts'
+export { extractSsrDefaults, deriveStashFromDefaults } from './ssr-defaults.ts'
+
+// Shared props-destructure binding + alias-map helpers (#2524)
+export { propsDestructureBinding, buildPropAliasMap, isIdentifierName } from './props-binding.ts'
 export type { SsrDefault } from './ssr-defaults.ts'
 
 // Backend-neutral SSR seed plan (in-template derived signal/memo seeding)
@@ -358,4 +361,7 @@ export type {
   ImgHTMLAttributes,
   LabelHTMLAttributes,
   OptionHTMLAttributes,
+
+  // SVG attributes (for components whose root is an `<svg>`, e.g. icons)
+  SVGSVGAttributes,
 } from './html-types.ts'

package/src/ir-to-client-js/collect-elements.ts

@@ -933,8 +933,11 @@ function collectFromElement(element: IRElement, ctx: ClientJsContext, insideCond
           // alone was wrong on both counts — it keys on HTML attr names
           // (`aria-invalid` ≠ source key `error`) and omits event handlers.
           // (#1467)
+          // `applyRestAttrs` filters `Object.keys(_p)` — which is always
+          // caller-keyed (#2524 CSR half) — so the exclude list must use
+          // the caller-facing key too, not the local binding name.
           const consumedKeys =
-            spreadVal === elemRestName ? ctx.propsParams.map(p => p.name) : []
+            spreadVal === elemRestName ? ctx.propsParams.map(p => p.sourceName ?? p.name) : []
           const staticAttrKeys = element.attrs
             .filter(a => a.name !== '...')
             .map(a => a.name)

package/src/ir-to-client-js/emit-reactive.ts

@@ -91,10 +91,12 @@ export function rewriteDestructuredPropsInExpr(expr: string, ctx: ClientJsContex
     const pattern = new RegExp(`(?<![-.])\\b${prop.name}\\b`, 'g')
     if (!pattern.test(result)) continue
 
+    // `_p` is always keyed by the caller-facing name (#2524 CSR half).
+    const callerKey = prop.sourceName ?? prop.name
     const defaultVal = prop.defaultValue
     const replacement = defaultVal
-      ? `(${PROPS_PARAM}.${prop.name} ?? ${prop.defaultContainsArrow ? `(${defaultVal})` : defaultVal})`
-      : `${PROPS_PARAM}.${prop.name}`
+      ? `(${PROPS_PARAM}.${callerKey} ?? ${prop.defaultContainsArrow ? `(${defaultVal})` : defaultVal})`
+      : `${PROPS_PARAM}.${callerKey}`
     result = result.replace(new RegExp(`(?<![-.])\\b${prop.name}\\b`, 'g'), replacement)
   }
 

package/src/ir-to-client-js/phases/props-event-handlers.ts

@@ -25,9 +25,10 @@ export function emitPropsEventHandlers(
   for (const handlerName of usedFunctions) {
     if (localNames.has(handlerName)) continue
     if (neededProps.has(handlerName)) continue
-    const isProp = ctx.propsParams.some(p => p.name === handlerName)
-    if (!isProp) continue
-    lines.push(`  const ${handlerName} = ${PROPS_PARAM}.${handlerName}`)
+    const prop = ctx.propsParams.find(p => p.name === handlerName)
+    if (!prop) continue
+    // `_p` is always keyed by the caller-facing name (#2524 CSR half).
+    lines.push(`  const ${handlerName} = ${PROPS_PARAM}.${prop.sourceName ?? handlerName}`)
     addedAny = true
   }
   if (addedAny) lines.push('')

package/src/ir-to-client-js/phases/props-extraction.ts

@@ -41,23 +41,26 @@ export function emitPropsExtraction(
 
   for (const propName of neededProps) {
     const prop = ctx.propsParams.find(p => p.name === propName)
+    // `_p` is always keyed by the caller-facing name (#2524 CSR half); the
+    // local binding on the left of `const` stays `propName`.
+    const callerKey = prop?.sourceName ?? propName
     const usage = propUsage.get(propName)
     const defaultVal = prop?.defaultValue
     if (defaultVal) {
       // `props.onInput ?? () => {}` is a syntax error — `??` binds tighter
       // than the arrow head. Wrap arrow defaults in parens.
       const wrappedDefault = prop?.defaultContainsArrow ? `(${defaultVal})` : defaultVal
-      lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? ${wrappedDefault}`)
+      lines.push(`  const ${propName} = ${PROPS_PARAM}.${callerKey} ?? ${wrappedDefault}`)
     } else if (usage?.usedAsLoopArray) {
-      lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? []`)
+      lines.push(`  const ${propName} = ${PROPS_PARAM}.${callerKey} ?? []`)
     } else if (propHasPropertyAccess(usage) && !propsUsedAsConditions.has(propName)) {
-      lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName} ?? {}`)
+      lines.push(`  const ${propName} = ${PROPS_PARAM}.${callerKey} ?? {}`)
     } else {
       // No synthesized default for a defaultless optional (`{ size }:
       // { size?: number }`): the JS binding is `undefined` when absent, and
       // a zero default would diverge from SSR (`size ?? 1` seeds 1
       // server-side; a `_p.size ?? 0` extraction would hydrate to 0).
-      lines.push(`  const ${propName} = ${PROPS_PARAM}.${propName}`)
+      lines.push(`  const ${propName} = ${PROPS_PARAM}.${callerKey}`)
     }
   }
   lines.push('')

package/src/ir-to-client-js/plan/build-declaration-emit.ts

@@ -159,7 +159,8 @@ function resolveSignalInitialValue(
     // Case 2b: synthesize the prop accessor + default.
     const prop = lookups.propByName.get(controlled.propName)
     const defaultVal = prop?.defaultValue ?? inferDefaultValue(signal.type)
-    return `${PROPS_PARAM}.${controlled.propName} ?? ${defaultVal}`
+    // `_p` is always keyed by the caller-facing name (#2524 CSR half).
+    return `${PROPS_PARAM}.${prop?.sourceName ?? controlled.propName} ?? ${defaultVal}`
   }
 
   // Case 3: non-controlled `propsObjectName.X` (only when destructured-
@@ -181,9 +182,11 @@ function buildControlledSignalEffect(
   if (!signal.setter) return null // read-only — no sync needed
 
   const prop = lookups.propByName.get(controlled.propName)
+  // `_p` is always keyed by the caller-facing name (#2524 CSR half).
+  const callerKey = prop?.sourceName ?? controlled.propName
   const accessorExpr = prop?.defaultValue
-    ? `(${PROPS_PARAM}.${controlled.propName} ?? ${prop.defaultValue})`
-    : `${PROPS_PARAM}.${controlled.propName}`
+    ? `(${PROPS_PARAM}.${callerKey} ?? ${prop.defaultValue})`
+    : `${PROPS_PARAM}.${callerKey}`
 
   return { setter: signal.setter, accessorExpr }
 }