@barefootjs/jsx 0.2.0 → 0.4.0

package/src/debug.ts

@@ -139,7 +139,14 @@ export interface EventBinding {
 export interface SetterRef {
   setter: string
   signal: string | null
-  via?: string
+  /**
+   * Call chain from the handler to the setter, when the setter is reached
+   * through one or more local helper functions. For a handler that calls
+   * the setter directly this is omitted. For `onClick={handlePointerDown}`
+   * where `handlePointerDown` calls `setValue` which calls `setInternalValue`,
+   * this is `['handlePointerDown', 'setValue']`.
+   */
+  via?: string[]
 }
 
 export interface EventSummary {
@@ -175,6 +182,49 @@ export interface LoopSummary {
   loops: LoopInfo[]
 }
 
+// -- Why-update analysis types ------------------------------------------------
+
+export interface WhyUpdateResult {
+  binding: string
+  expression: string | null
+  deps: WhyUpdateDep[]
+  classification?: 'reactive' | 'fallback'
+  wrapReason?: WrapReason
+  ambiguous?: Array<{ label: string; slotId: string }>
+}
+
+export interface WhyUpdateDep {
+  name: string
+  kind: 'signal' | 'memo'
+  dependsOn: string[]
+  changedBy: WhyUpdateSource[]
+}
+
+export interface WhyUpdateSource {
+  handler: string
+  setter: string
+  elementContext: string
+  via?: string[]
+}
+
+// -- Component summary types --------------------------------------------------
+
+export interface ComponentSummary {
+  componentName: string
+  sourceFile: string
+  hydrated: boolean
+  clientBundle: string | null
+  signals: number
+  memos: number
+  effects: number
+  loops: number
+  eventHandlers: number
+  dynamicTextBindings: number
+  dynamicAttributes: number
+  conditionals: number
+  fallbacks: number
+}
+
 // -- Component analysis (shared IR + graph) -----------------------------------
 
 export interface ComponentAnalysis {
@@ -379,11 +429,11 @@ export function buildEventSummary(source: string, filePath: string, componentNam
   }
 }
 
-function escapeForIdBoundary(name: string): string {
+export function escapeForIdBoundary(name: string): string {
   return name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
-function makeIdCallRegex(name: string): RegExp {
+export function makeIdCallRegex(name: string): RegExp {
   return new RegExp(`(?:^|[^\\w$])${escapeForIdBoundary(name)}\\s*\\(`)
 }
 
@@ -391,26 +441,87 @@ function makeIdRefRegex(name: string): RegExp {
   return new RegExp(`(?:^|[^\\w$])${escapeForIdBoundary(name)}(?:[^\\w$]|$)`)
 }
 
-function buildLocalFunctionSetterMap(
+/**
+ * A setter reachable from a local function, with the chain of intermediate
+ * function names between that function and the setter (excluding the function
+ * itself). For a direct call the chain is empty.
+ */
+export interface FnSetterResolution {
+  setter: string
+  chain: string[]
+}
+
+export function buildLocalFunctionSetterMap(
   meta: IRMetadata,
   setterToSignal: Map<string, string>,
-): Map<string, string[]> {
+): Map<string, FnSetterResolution[]> {
   const setterPatterns = [...setterToSignal.keys()].map(s => ({ name: s, re: makeIdCallRegex(s) }))
-  const result = new Map<string, string[]>()
-  for (const fn of meta.localFunctions) {
+
+  // Collect every local function-like binding: `function foo() {}` declarations
+  // plus arrow/function-expression consts (`const foo = () => {}`), which land
+  // in localConstants rather than localFunctions.
+  const bodies = new Map<string, string>()
+  for (const fn of meta.localFunctions) bodies.set(fn.name, fn.body)
+  for (const c of meta.localConstants) {
+    if (c.containsArrow && c.value) bodies.set(c.name, c.value)
+  }
+
+  // Direct setters and direct local-function calls per binding.
+  const fnNamePatterns = [...bodies.keys()].map(n => ({ name: n, re: makeIdCallRegex(n) }))
+  const directSetters = new Map<string, string[]>()
+  const directCalls = new Map<string, string[]>()
+  for (const [name, body] of bodies) {
     const setters: string[] = []
-    for (const { name, re } of setterPatterns) {
-      if (re.test(fn.body)) setters.push(name)
+    for (const { name: setter, re } of setterPatterns) {
+      if (re.test(body)) setters.push(setter)
+    }
+    directSetters.set(name, setters)
+    const calls: string[] = []
+    for (const { name: callee, re } of fnNamePatterns) {
+      if (callee !== name && re.test(body)) calls.push(callee)
+    }
+    directCalls.set(name, calls)
+  }
+
+  // Resolve transitively: a handler may reach a setter through a chain of
+  // helper functions (handler -> setValue -> setInternalValue). `stack`
+  // guards against cycles (mutual recursion between helpers). Component
+  // helper graphs are tiny, so a plain DFS per binding is fine.
+  const resolve = (name: string, stack: Set<string>): FnSetterResolution[] => {
+    const out: FnSetterResolution[] = []
+    const seen = new Set<string>()
+    for (const setter of directSetters.get(name) ?? []) {
+      if (!seen.has(setter)) {
+        out.push({ setter, chain: [] })
+        seen.add(setter)
+      }
+    }
+    for (const callee of directCalls.get(name) ?? []) {
+      if (stack.has(callee)) continue
+      const sub = resolve(callee, new Set([...stack, callee]))
+      for (const r of sub) {
+        if (!seen.has(r.setter)) {
+          out.push({ setter: r.setter, chain: [callee, ...r.chain] })
+          seen.add(r.setter)
+        }
+      }
     }
-    if (setters.length > 0) result.set(fn.name, setters)
+    return out
+  }
+
+  const result = new Map<string, FnSetterResolution[]>()
+  for (const name of bodies.keys()) {
+    const resolved = resolve(name, new Set([name]))
+    if (resolved.length > 0) result.set(name, resolved)
   }
+
   return result
 }
 
 function collectEventBindings(
   node: IRNode,
   setterToSignal: Map<string, string>,
-  fnSetters: Map<string, string[]>,
+  fnSetters: Map<string, FnSetterResolution[]>,
 ): EventBinding[] {
   const events: EventBinding[] = []
   walkForEvents(node, events, setterToSignal, fnSetters)
@@ -421,7 +532,7 @@ function walkForEvents(
   node: IRNode,
   events: EventBinding[],
   setterToSignal: Map<string, string>,
-  fnSetters: Map<string, string[]>,
+  fnSetters: Map<string, FnSetterResolution[]>,
 ): void {
   switch (node.type) {
     case 'element': {
@@ -494,10 +605,10 @@ function walkForEvents(
   }
 }
 
-function resolveSetters(
+export function resolveSetters(
   handler: string,
   setterToSignal: Map<string, string>,
-  fnSetters: Map<string, string[]>,
+  fnSetters: Map<string, FnSetterResolution[]>,
 ): SetterRef[] {
   const refs: SetterRef[] = []
   const seen = new Set<string>()
@@ -512,12 +623,16 @@ function resolveSetters(
     }
   }
 
-  for (const [fnName, setters] of fnSetters) {
+  for (const [fnName, resolutions] of fnSetters) {
     if (trimmed === fnName || makeIdCallRegex(fnName).test(handler)) {
-      for (const setter of setters) {
-        if (!seen.has(setter)) {
-          refs.push({ setter, signal: setterToSignal.get(setter) ?? null, via: fnName })
-          seen.add(setter)
+      for (const r of resolutions) {
+        if (!seen.has(r.setter)) {
+          refs.push({
+            setter: r.setter,
+            signal: setterToSignal.get(r.setter) ?? null,
+            via: [fnName, ...r.chain],
+          })
+          seen.add(r.setter)
         }
       }
     }
@@ -562,7 +677,7 @@ export function formatEventSummary(summary: EventSummary, graph: ComponentGraph)
     lines.push(`  ${event.elementContext}`)
 
     const setterParts = event.setterCalls.map(s => {
-      const chain = s.via ? `${s.via} -> ${s.setter}` : s.setter
+      const chain = s.via && s.via.length > 0 ? `${s.via.join(' -> ')} -> ${s.setter}` : s.setter
       return chain
     })
 
@@ -893,6 +1008,121 @@ function buildUpdateEntry(consumer: string, graph: ComponentGraph, visited: Set<
   return { name: consumer, kind: 'effect', label: consumer, children: [] }
 }
 
+// =============================================================================
+// Analysis: Why-Update (binding → reason)
+// =============================================================================
+
+export function buildWhyUpdate(
+  source: string,
+  filePath: string,
+  bindingLabel: string,
+  componentName?: string,
+): WhyUpdateResult | null {
+  const { graph, ir } = buildComponentAnalysis(source, filePath, componentName)
+
+  const matches = graph.domBindings.filter(d =>
+    d.label === bindingLabel ||
+    d.slotId === bindingLabel,
+  )
+  if (matches.length === 0) return null
+  if (matches.length > 1) {
+    return {
+      binding: bindingLabel,
+      expression: null,
+      deps: [],
+      ambiguous: matches.map(d => ({ label: d.label, slotId: d.slotId })),
+    }
+  }
+  const binding = matches[0]
+
+  const setterToSignal = new Map<string, string>()
+  for (const s of ir.metadata.signals) {
+    if (s.setter) setterToSignal.set(s.setter, s.getter)
+  }
+  const fnSetters = buildLocalFunctionSetterMap(ir.metadata, setterToSignal)
+  const events = collectEventBindings(ir.root, setterToSignal, fnSetters)
+
+  const deps: WhyUpdateDep[] = []
+  const visited = new Set<string>()
+
+  function traceDep(name: string): void {
+    if (visited.has(name)) return
+    visited.add(name)
+
+    const signal = graph.signals.find(s => s.name === name)
+    if (signal) {
+      const changedBy: WhyUpdateSource[] = []
+      for (const ev of events) {
+        for (const sc of ev.setterCalls) {
+          if (sc.signal === name) {
+            changedBy.push({
+              handler: ev.eventName,
+              setter: sc.setter,
+              elementContext: ev.elementContext,
+              via: sc.via,
+            })
+          }
+        }
+      }
+      deps.push({ name, kind: 'signal', dependsOn: [], changedBy })
+      return
+    }
+
+    const memo = graph.memos.find(m => m.name === name)
+    if (memo) {
+      deps.push({ name, kind: 'memo', dependsOn: memo.deps, changedBy: [] })
+      for (const dep of memo.deps) traceDep(dep)
+    }
+  }
+
+  for (const dep of binding.deps) traceDep(dep)
+
+  const stableId = binding.type === 'attribute' ? binding.label : binding.slotId
+  return {
+    binding: stableId,
+    expression: binding.expression ?? null,
+    deps,
+    ...(binding.classification === 'fallback' && { classification: binding.classification as 'fallback' }),
+    ...(binding.wrapReason && { wrapReason: binding.wrapReason }),
+  }
+}
+
+export function formatWhyUpdate(result: WhyUpdateResult): string {
+  const lines: string[] = []
+
+  lines.push(`${result.binding} updates because:`)
+  if (result.expression) {
+    lines.push(`  ${result.expression}`)
+  }
+
+  if (result.classification === 'fallback') {
+    lines.push('')
+    lines.push(`note: this is a fallback-wrapped binding (${result.wrapReason ?? 'unknown'})`)
+    lines.push('  the compiler could not statically prove reactivity — deps are determined at runtime')
+  }
+
+  for (const dep of result.deps) {
+    lines.push('')
+    if (dep.kind === 'memo') {
+      lines.push(`${dep.name} depends on:`)
+      for (const d of dep.dependsOn) lines.push(`  ${d}`)
+    } else {
+      lines.push(`${dep.name} changes from:`)
+      if (dep.changedBy.length === 0) {
+        lines.push('  (no event handlers found)')
+      }
+      for (const src of dep.changedBy) {
+        const chain = src.via && src.via.length > 0
+          ? `${src.elementContext} ${src.handler} -> ${src.via.join(' -> ')} -> ${src.setter}`
+          : `${src.elementContext} ${src.handler} -> ${src.setter}`
+        lines.push(`  ${chain}`)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
 // =============================================================================
 // Formatting: Human-readable output
 // =============================================================================
@@ -1132,6 +1362,206 @@ export function formatSignalTrace(traces: SignalTrace[]): string {
   }).join('\n')
 }
 
+// =============================================================================
+// Fallback explanation
+// =============================================================================
+
+export interface FallbackExplanation {
+  label: string
+  expression: string
+  reason: string
+  runtimeDeps: string
+  suggestion: string
+  loc?: { file: string; line: number }
+  isEventHandler: boolean
+}
+
+export function describeFallback(binding: DomBinding): FallbackExplanation {
+  const isEventHandler = binding.type === 'event' ||
+    (binding.type === 'attribute' && /^on[A-Z]/.test(binding.label.split('.').pop() ?? ''))
+
+  const reason = describeFallbackReason(binding.wrapReason, binding.type, isEventHandler)
+  const runtimeDeps = binding.deps.length > 0
+    ? binding.deps.join(', ')
+    : isEventHandler
+      ? 'likely none (event handler captures values, does not track reactively)'
+      : 'unknown — subscribes to whatever signals it reads at runtime'
+
+  const suggestion = isEventHandler
+    ? 'event handlers intentionally capture scope values; this fallback is typically safe to ignore'
+    : binding.wrapReason === 'fallback-function-calls'
+      ? 'inline the reactive source or wrap the result in createMemo so the compiler can prove the dependency'
+      : binding.wrapReason === 'fallback-getter-calls'
+        ? 'the call looks like a signal getter but is not a known signal; verify the function is pure or extract as createMemo'
+        : 'rewrite to use a known signal/memo reference so the compiler can statically prove reactivity'
+
+  return {
+    label: binding.label,
+    expression: binding.expression ?? '(expression not captured)',
+    reason,
+    runtimeDeps,
+    suggestion,
+    loc: binding.loc ? { file: binding.loc.file, line: binding.loc.start.line } : undefined,
+    isEventHandler,
+  }
+}
+
+function describeFallbackReason(
+  wrapReason: WrapReason | undefined,
+  bindingType: string,
+  isEventHandler: boolean,
+): string {
+  const context = bindingType === 'attribute'
+    ? 'an attribute expression'
+    : bindingType === 'text'
+      ? 'a text interpolation'
+      : bindingType === 'conditional'
+        ? 'a conditional expression'
+        : bindingType === 'loop'
+          ? 'a loop array expression'
+          : 'an expression'
+
+  switch (wrapReason) {
+    case 'fallback-function-calls':
+      return isEventHandler
+        ? `function call in ${context} (event handler prop)`
+        : `opaque function call in ${context} — the compiler cannot prove it is reactive or pure`
+    case 'fallback-getter-calls':
+      return `call pattern resembles a signal getter in ${context}, but is not a recognized signal`
+    case 'string-reactive':
+      return `string-level match found a signal/memo name in ${context}`
+    case 'props-access':
+      return `props.xxx reference in ${context} — reactive via prop forwarding`
+    case 'proven-reactive':
+      return `statically proven reactive in ${context}`
+    default:
+      return `unknown fallback trigger in ${context}`
+  }
+}
+
+export function formatFallbackExplanations(
+  componentName: string,
+  fallbacks: DomBinding[],
+): string {
+  const lines: string[] = []
+
+  if (fallbacks.length === 0) {
+    lines.push(`${componentName} — no fallback-wrapped expressions.`)
+    return lines.join('\n')
+  }
+
+  lines.push(`${componentName} — ${fallbacks.length} fallback-wrapped expression(s)`)
+
+  for (const f of fallbacks) {
+    const ex = describeFallback(f)
+    lines.push('')
+    if (ex.loc) {
+      const locFile = ex.loc.file.split('/').pop() ?? ex.loc.file
+      lines.push(`  ${locFile}:${ex.loc.line}`)
+    }
+    lines.push(`  ${ex.label} fallback:`)
+    lines.push(`    expression: ${ex.expression}`)
+    lines.push(`    reason: ${ex.reason}`)
+    lines.push(`    runtime deps: ${ex.runtimeDeps}`)
+    lines.push(`    suggestion: ${ex.suggestion}`)
+  }
+
+  return lines.join('\n')
+}
+
+// =============================================================================
+// Component Summary (hydration/size overview)
+// =============================================================================
+
+export function buildComponentSummary(source: string, filePath: string, componentName?: string): ComponentSummary {
+  const { graph, ir } = buildComponentAnalysis(source, filePath, componentName)
+  const meta = ir.metadata
+  const clientNeeds = analyzeClientNeeds(ir)
+  const hasReactiveState = meta.signals.length > 0 || meta.memos.length > 0 || meta.effects.length > 0
+  const needsClient = clientNeeds.needsInit && hasReactiveState
+
+  let loopCount = 0
+  countNodeType(ir.root, 'loop', () => { loopCount++ })
+
+  let conditionalCount = 0
+  countNodeType(ir.root, 'conditional', () => { conditionalCount++ })
+
+  const eventHandlers = graph.domBindings.filter(d => d.type === 'event').length
+  const textBindings = graph.domBindings.filter(d => d.type === 'text').length
+  const attrBindings = graph.domBindings.filter(d => d.type === 'attribute').length
+  const fallbacks = graph.domBindings.filter(d => d.classification === 'fallback').length
+
+  let clientBundle: string | null = null
+  if (needsClient) {
+    const base = filePath.replace(/\.[^.]+$/, '').split('/').pop() ?? meta.componentName
+    clientBundle = `${base}.client.js`
+  }
+
+  return {
+    componentName: graph.componentName,
+    sourceFile: graph.sourceFile,
+    hydrated: needsClient,
+    clientBundle,
+    signals: graph.signals.length,
+    memos: graph.memos.length,
+    effects: graph.effects.length,
+    loops: loopCount,
+    eventHandlers,
+    dynamicTextBindings: textBindings,
+    dynamicAttributes: attrBindings,
+    conditionals: conditionalCount,
+    fallbacks,
+  }
+}
+
+function countNodeType(node: IRNode, targetType: string, cb: () => void): void {
+  if (node.type === targetType) cb()
+  switch (node.type) {
+    case 'element':
+    case 'fragment':
+    case 'provider':
+      for (const child of node.children) countNodeType(child, targetType, cb)
+      break
+    case 'component':
+      for (const child of node.children) countNodeType(child, targetType, cb)
+      break
+    case 'conditional':
+      countNodeType(node.whenTrue, targetType, cb)
+      countNodeType(node.whenFalse, targetType, cb)
+      break
+    case 'loop':
+      for (const child of node.children) countNodeType(child, targetType, cb)
+      break
+    case 'if-statement':
+      countNodeType(node.consequent, targetType, cb)
+      if (node.alternate) countNodeType(node.alternate, targetType, cb)
+      break
+    case 'async':
+      countNodeType(node.fallback, targetType, cb)
+      for (const child of node.children) countNodeType(child, targetType, cb)
+      break
+  }
+}
+
+export function formatComponentSummary(summary: ComponentSummary): string {
+  const lines: string[] = []
+  lines.push(summary.componentName)
+  lines.push(`  hydrated: ${summary.hydrated ? 'yes' : 'no'}`)
+  if (summary.clientBundle) {
+    lines.push(`  client bundle: ${summary.clientBundle}`)
+  }
+  lines.push(`  signals: ${summary.signals}`)
+  lines.push(`  memos: ${summary.memos}`)
+  if (summary.effects > 0) lines.push(`  effects: ${summary.effects}`)
+  lines.push(`  loops: ${summary.loops}`)
+  lines.push(`  event handlers: ${summary.eventHandlers}`)
+  lines.push(`  dynamic text bindings: ${summary.dynamicTextBindings}`)
+  lines.push(`  dynamic attributes: ${summary.dynamicAttributes}`)
+  if (summary.conditionals > 0) lines.push(`  conditionals: ${summary.conditionals}`)
+  if (summary.fallbacks > 0) lines.push(`  fallbacks: ${summary.fallbacks}`)
+  return lines.join('\n')
+}
+
 // =============================================================================
 // Helpers
 // =============================================================================

package/src/index.ts

@@ -250,16 +250,25 @@ export {
   buildGraphFromIR,
   buildEventSummary,
   buildLoopSummary,
+  buildWhyUpdate,
   traceUpdatePath,
   formatComponentGraph,
   formatUpdatePath,
   formatEventSummary,
   formatLoopSummary,
+  formatWhyUpdate,
+  describeFallback,
+  formatFallbackExplanations,
+  buildComponentSummary,
+  formatComponentSummary,
   formatSignalTrace,
   generateStaticTrace,
   graphToJSON,
+  resolveSetters,
+  buildLocalFunctionSetterMap,
+  makeIdCallRegex,
 } from './debug'
-export type { ComponentGraph, ComponentAnalysis, SignalNode, MemoNode, EffectNode, DomBinding, UpdatePath, SignalTrace, EventBinding, SetterRef, EventSummary, LoopInfo, LoopChildBinding, LoopSummary } from './debug'
+export type { ComponentGraph, ComponentAnalysis, SignalNode, MemoNode, EffectNode, DomBinding, UpdatePath, SignalTrace, EventBinding, SetterRef, FnSetterResolution, EventSummary, LoopInfo, LoopChildBinding, LoopSummary, WhyUpdateResult, WhyUpdateDep, WhyUpdateSource, FallbackExplanation, ComponentSummary } from './debug'
 export type { WrapReason } from './ir-to-client-js/reactivity'
 
 // HTML constants

package/src/ir-to-client-js/html-template.ts

@@ -1040,6 +1040,14 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
       return `\${${transformExpr(node.expr, node.templateExpr)}}`
 
     case 'conditional': {
+      // A client-only conditional (auto-deferred brand read or manual
+      // `/* @client */`) is owned by init's `insert()`, not the module-scope
+      // template lambda. Match the SSR adapter: emit empty cond markers so
+      // the client-render path (`createComponent`) produces the same DOM SSR
+      // does, instead of evaluating an init-scope condition here (#1645).
+      if (node.clientOnly && node.slotId) {
+        return `<!--bf-cond-start:${node.slotId}--><!--bf-cond-end:${node.slotId}-->`
+      }
       const trueBranch = recurse(node.whenTrue)
       const falseBranch = recurse(node.whenFalse)
       const trueHtml = node.slotId ? addCondAttrToTemplate(trueBranch, node.slotId) : trueBranch
@@ -1418,6 +1426,15 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
       }
 
     case 'conditional': {
+      // An auto-deferred conditional (e.g. `{form.field('x').error() && …}`)
+      // reads per-instance init-scope state the module-scope template lambda
+      // can't evaluate — re-deriving it here yields `undefined.field(...)` or
+      // a throwaway re-inlined `createForm({...})`. Match the SSR adapter:
+      // emit empty cond markers and let init's `insert()` populate the branch
+      // at hydrate time via the reactive binding (#1645).
+      if (node.clientOnly && node.slotId) {
+        return `<!--bf-cond-start:${node.slotId}--><!--bf-cond-end:${node.slotId}-->`
+      }
       const trueBranch = recurse(node.whenTrue)
       const falseBranch = recurse(node.whenFalse)
       const trueHtml = node.slotId ? addCondAttrToTemplate(trueBranch, node.slotId) : trueBranch

package/src/jsx-to-ir.ts

@@ -1323,7 +1323,10 @@ function transformExpressionInner(
     // IRLoop handles `isClientOnly` internally via `transformMapCall`; other
     // shapes (IRElement / IRFragment / IRLoop / IRComponent from inline JSX
     // helpers) are unchanged. Mirror that exactly here.
-    if (isClientOnly && ir.type === 'conditional') {
+    // A reactive brand-package condition (e.g. `form.field('x').error() &&
+    // …`) can't be SSR-evaluated, so defer the whole conditional rather
+    // than raising BF061 — same routing as a manual `/* @client */` (#1638).
+    if ((isClientOnly || shouldAutoDeferReactiveBrand(expr, ctx)) && ir.type === 'conditional') {
       ir.clientOnly = true
       if (!ir.slotId) {
         ir.slotId = generateSlotId(ctx)
@@ -3510,7 +3513,12 @@ function processAttributes(
       // Downstream routing: collect-elements wires this into
       // `reactiveAttrs` for elements; html-template strips it from
       // the SSR template (and from `renderChild` for components).
-      if (hasLeadingClientDirective(attr.initializer.expression, ctx.sourceFile)) {
+      //
+      // Reactive brand-package reads (`value={form.field('x').value()}`)
+      // are auto-deferred the same way: the SSR lambda can't evaluate the
+      // init-scope form state, so defer instead of raising BF061 (#1638).
+      if (hasLeadingClientDirective(attr.initializer.expression, ctx.sourceFile)
+        || shouldAutoDeferReactiveBrand(attr.initializer.expression, ctx)) {
         clientOnly = true
       }
     }
@@ -4229,6 +4237,35 @@ function isReactiveExpression(expr: string, ctx: TransformContext, astNode?: ts.
   return false
 }
 
+/**
+ * Decide whether a JSX expression should be auto-deferred to the client
+ * (treated as if it carried `/* @client *​/`) because it reads reactive
+ * brand-package state the SSR template lambda cannot evaluate (#1638).
+ *
+ * The motivating case is `@barefootjs/form`: `const form = createForm(...)`
+ * is per-instance init-scope state, so `form.field('x').value()` /
+ * `form.isSubmitting()` resolve to an init-local with no compiler-derivable
+ * SSR value. Referencing them from a template position (element attribute,
+ * conditional condition) otherwise raises BF061 and forces a manual
+ * `/* @client *​/` on every binding.
+ *
+ * Gated tightly so it never demotes server-renderable reads:
+ *  - Requires the TypeChecker AND a `Reactive<T>` brand on the expression
+ *    (`containsReactiveExpression`), so plain values are untouched.
+ *  - Excludes native `createSignal` / `createMemo` getters (and their
+ *    chained-const aliases): they carry the same brand but DO have a
+ *    derivable initial value, so they must keep rendering server-side.
+ */
+function shouldAutoDeferReactiveBrand(expr: ts.Expression, ctx: TransformContext): boolean {
+  const checker = ctx.analyzer.checker
+  if (!checker) return false
+  if (!containsReactiveExpression(expr, checker)) return false
+  // Native signals/memos (incl. chained-const aliases) are SSR-derivable —
+  // leave them to the normal template path so their initial value renders.
+  if (isSignalOrMemoReference(ctx.getJS(expr), ctx)) return false
+  return true
+}
+
 /**
  * Regex-based signal/memo detection.
  * Complements TypeChecker for cases where imported types can't be resolved.