@barefootjs/jsx 0.33.3 → 0.33.6

package/src/__tests__/namespace-import-primitive.test.ts

@@ -0,0 +1,244 @@
+/**
+ * #2771 — `import * as bf from '@barefootjs/client'` followed by
+ * `bf.createSignal(0)` (or any other reactive primitive accessed off the
+ * namespace binding) compiled with ZERO diagnostics, but `resolvePrimitiveKind`'s
+ * fast path only matches a bare identifier callee — the checker-based slow
+ * path that DOES understand a namespace-qualified call only runs when a
+ * shared `ts.Program` is supplied (`CompileOptions.program`). Without one,
+ * the declaration is silently dropped from the compiled output and every
+ * reference to it throws `ReferenceError` at hydrate.
+ *
+ * BF013 refuses loudly instead, gated on NON-recognition — a compile that
+ * DOES supply a program (see `primitive-resolver-alias.test.ts`'s pattern)
+ * must never see this diagnostic, since that path already lowers the shape
+ * correctly.
+ */
+import { describe, test, expect } from 'bun:test'
+import path from 'path'
+import ts from 'typescript'
+import { compileJSX } from '../compiler'
+import { analyzeComponent } from '../index'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function errorsFor(source: string): Array<{ code?: string; severity: string }> {
+  const result = compileJSX(source, 'Counter.tsx', { adapter })
+  return result.errors.map(e => ({ code: e.code, severity: e.severity }))
+}
+
+function bf013(source: string) {
+  return errorsFor(source).find(e => e.code === 'BF013')
+}
+
+describe('#2771 — BF013: reactive primitive called through an unresolved namespace import', () => {
+  test('bf.createSignal(...) (array destructure) fires BF013', () => {
+    const result = compileJSX(
+      `
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        const [n, setN] = bf.createSignal(0)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `,
+      'Counter.tsx',
+      { adapter },
+    )
+    const err = result.errors.find(e => e.code === 'BF013')
+    expect(err).toBeDefined()
+    expect(err!.severity).toBe('error')
+    expect(err!.message).toContain('bf.createSignal')
+    expect(err!.suggestion?.escape).toEqual([{ kind: 'rewrite' }])
+  })
+
+  test('bf.createMemo(...) (array destructure) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      import { createSignal } from '@barefootjs/client'
+      export function Counter() {
+        const [n] = createSignal(1)
+        const [doubled] = bf.createMemo(() => n() * 2)
+        return <div>{doubled()}</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('bf.createEffect(...) (expression statement) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      import { createSignal } from '@barefootjs/client'
+      export function Counter() {
+        const [n] = createSignal(0)
+        bf.createEffect(() => { console.log(n()) })
+        return <div>{n()}</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('bf.onMount(...) (expression statement) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        bf.onMount(() => { console.log('mounted') })
+        return <div>static</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('bf.onCleanup(...) (expression statement) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        bf.onCleanup(() => { console.log('cleaned up') })
+        return <div>static</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('bf.createSearchParams(...) (array destructure) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        const [searchParams] = bf.createSearchParams()
+        return <div>{searchParams().get('sort')}</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('bf.createSignal(0)[0] (element access) fires BF013', () => {
+    const err = bf013(`
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        const n = bf.createSignal(0)[0]
+        return <div>{n()}</div>
+      }
+    `)
+    expect(err).toBeDefined()
+  })
+
+  test('a bare named import is unaffected (no BF013)', () => {
+    const errs = errorsFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      export function Counter() {
+        const [n, setN] = createSignal(0)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `)
+    expect(errs.find(e => e.code === 'BF013')).toBeUndefined()
+  })
+
+  test('a namespace import of a DIFFERENT module is unaffected (no BF013)', () => {
+    const result = compileJSX(
+      `
+      'use client'
+      import * as store from './store'
+      export function Counter() {
+        const [n, setN] = store.createSignal(0)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `,
+      'Counter.tsx',
+      { adapter },
+    )
+    expect(result.errors.find(e => e.code === 'BF013')).toBeUndefined()
+  })
+
+  test('a component-local binding shadowing the namespace name is unaffected (no BF013)', () => {
+    const result = compileJSX(
+      `
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        const bf = { createSignal: (x: number) => [() => x, (v: number) => {}] as const }
+        const [n, setN] = bf.createSignal(0)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `,
+      'Counter.tsx',
+      { adapter },
+    )
+    expect(result.errors.find(e => e.code === 'BF013')).toBeUndefined()
+  })
+
+  test('a type-only namespace import is unaffected (no BF013)', () => {
+    const result = compileJSX(
+      `
+      'use client'
+      import type * as bf from '@barefootjs/client'
+      export function Counter() {
+        return <div>static</div>
+      }
+    `,
+      'Counter.tsx',
+      { adapter },
+    )
+    expect(result.errors.find(e => e.code === 'BF013')).toBeUndefined()
+  })
+})
+
+describe('#2771 — checker-path pin: a shared Program resolves the namespace and never fires BF013', () => {
+  const CLIENT_DIR = path.resolve(__dirname, '../../../client/src')
+
+  function programFor(filePath: string, source: string): ts.Program {
+    const absolute = path.resolve(filePath)
+    const compilerOptions: ts.CompilerOptions = {
+      target: ts.ScriptTarget.Latest,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      jsx: ts.JsxEmit.ReactJSX,
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
+      esModuleInterop: true,
+      baseUrl: path.dirname(absolute),
+    }
+    const defaultHost = ts.createCompilerHost(compilerOptions)
+    const host: ts.CompilerHost = {
+      ...defaultHost,
+      getSourceFile(fileName, languageVersion) {
+        if (path.resolve(fileName) === absolute) {
+          return ts.createSourceFile(fileName, source, languageVersion, true, ts.ScriptKind.TSX)
+        }
+        return defaultHost.getSourceFile(fileName, languageVersion)
+      },
+      fileExists(fileName) {
+        if (path.resolve(fileName) === absolute) return true
+        return defaultHost.fileExists(fileName)
+      },
+      readFile(fileName) {
+        if (path.resolve(fileName) === absolute) return source
+        return defaultHost.readFile(fileName)
+      },
+    }
+    return ts.createProgram([absolute], compilerOptions, host)
+  }
+
+  test('with a shared Program, bf.createSignal resolves and BF013 never fires', () => {
+    const source = `
+      'use client'
+      import * as bf from '@barefootjs/client'
+      export function Counter() {
+        const [n, setN] = bf.createSignal(0)
+        return <button onClick={() => setN(n() + 1)}>{n()}</button>
+      }
+    `
+    const testFile = path.join(CLIENT_DIR, '__ns_primitive_checker_pin__.tsx')
+    const program = programFor(testFile, source)
+    const ctx = analyzeComponent(source, testFile, undefined, program)
+    expect(ctx.signals.length).toBe(1)
+    expect(ctx.errors.find(e => e.code === 'BF013')).toBeUndefined()
+  })
+})

package/src/__tests__/preamble-declarations.test.ts

@@ -205,3 +205,45 @@ export function Rows(props: { rows: Row[] }) {
     expect(dslErrors(source)).toEqual([])
   })
 })
+
+describe('preamble value declarations — function-literal elision (#2797)', () => {
+  // An event handler hoisted into the preamble (rather than written inline in
+  // the JSX attribute) has no template-expression form on any DSL backend —
+  // but every adapter's own SSR prop-builder already skips an event-handler
+  // prop outright, so a name read ONLY that way needs no SSR representation
+  // at all. Elided, not refused: `declarations` legally ends up `[]`.
+  test('a handler read only as an event-handler prop value elides clean, no refusal', () => {
+    const source = ROWS(`const handleClick = () => {}`, `<li key={r.id} onClick={handleClick}>{r.label}</li>`)
+    expect(loopOf(source).preamble?.declarations).toEqual([])
+    expect(dslErrors(source)).toEqual([])
+  })
+
+  test('an elided handler coexists with a genuinely lowered declaration', () => {
+    const loop = loopOf(
+      ROWS(
+        `const cls = r.done ? 'done' : 'open'\n        const handleClick = () => {}`,
+        `<li key={r.id} class={cls} onClick={handleClick}>{r.label}</li>`,
+      ),
+    )
+    // Only the lowerable declaration survives — the elided one contributes no entry.
+    expect(loop.preamble?.declarations?.map(d => d.name)).toEqual(['cls'])
+  })
+
+  // Soundness: a function-valued local read ANYWHERE other than an
+  // event-handler prop value still refuses — elision only widens what's
+  // SAFE, it never lets an SSR-relevant function read through unassigned.
+  test('a handler also read in a non-event position still refuses', () => {
+    const errors = dslErrors(
+      ROWS(`const handleClick = () => {}`, `<li key={r.id}>{handleClick.name}</li>`),
+    )
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toMatch(/not a sequence of value declarations/)
+  })
+
+  test('a handler passed to a NON-event child prop still refuses', () => {
+    const errors = dslErrors(
+      ROWS(`const handleClick = () => {}`, `<li key={r.id} data-fn={handleClick}>{r.label}</li>`),
+    )
+    expect(errors.length).toBeGreaterThan(0)
+  })
+})

package/src/__tests__/rewrite-destructured-props.test.ts

@@ -71,3 +71,56 @@ export { Btn }
     expect(js).not.toMatch(/\(_p\.size[^)]*\)-[0-9]/)
   })
 })
+
+// #2741: `rewriteDestructuredPropsInExpr` (the reactive `createEffect`
+// update path) used to run a bare `\b<prop>\b` regex over the whole
+// expression text, so an object-literal property whose KEY happened to
+// share a prop's name (`{ tag: tag }`) had the KEY rewritten too
+// (`{ _p.tag: _p.tag }`), which is not valid JS — the whole client module
+// failed to parse, silently (no diagnostic). Now delegates to the same
+// AST-based `rewriteBarePropRefs` (`prop-rewrite.ts`) the hydrate template
+// lambda already used, which distinguishes a key from a value reference.
+describe('reactive-effect prop rewrite does not touch object-literal keys (#2741)', () => {
+  test('an explicit-key object literal used in a reactive attribute keeps its keys', () => {
+    const source = `
+"use client"
+import { queryHref } from '@barefootjs/client'
+function Comp({ base, tag, page }: { base: string; tag: string; page: string }) {
+  return <a href={queryHref(base, { tag: tag, page: page ? page : '' })}>filter</a>
+}
+export { Comp }
+`
+    const js = compileClientJs(source)
+    expect(js).toContain("{ tag: _p.tag, page: _p.page ? _p.page : '' }")
+    expect(js).not.toContain('_p.tag:')
+    expect(js).not.toContain('_p.page:')
+  })
+
+  test('a keyed prop with a destructure default still gets the (_p.x ?? default) wrap only in value position', () => {
+    const source = `
+"use client"
+import { queryHref } from '@barefootjs/client'
+function Comp({ base, tag = 'all', page }: { base: string; tag?: string; page: string }) {
+  return <a href={queryHref(base, { tag: tag, page: page ? page : '' })}>filter</a>
+}
+export { Comp }
+`
+    const js = compileClientJs(source)
+    expect(js).toContain("{ tag: (_p.tag ?? 'all'), page: _p.page ? _p.page : '' }")
+    expect(js).not.toContain("(_p.tag ?? 'all'):")
+  })
+
+  test('a prop name shadowed by an inner callback parameter is not rewritten inside that callback', () => {
+    const source = `
+"use client"
+import { createSignal } from '@barefootjs/client'
+function Comp({ tag, items }: { tag: string; items: { a: string }[] }) {
+  const [n] = createSignal(0)
+  return <div data-x={n() + items.map((tag) => tag.a).join(',') + tag}></div>
+}
+export { Comp }
+`
+    const js = compileClientJs(source)
+    expect(js).toContain("items.map((tag) => tag.a).join(',') + _p.tag")
+  })
+})

package/src/__tests__/static-loop-csr-materialize.test.ts

@@ -242,7 +242,7 @@ describe('#1247 — static-loop CSR self-heal', () => {
     expect(clientJs).toMatch(/if \(!__iterEl\)/)
     // The cloned template body is a single `renderChild('Tag', ...)`
     // expression — props read from the destructured forEach param.
-    const matMatch = clientJs.match(/__tpl\.innerHTML = `([^`]*)`/)
+    const matMatch = clientJs.match(/__tpl\.innerHTML = withParentScope\(__scopeId, \(\) => `([^`]*)`\)/)
     expect(matMatch).toBeTruthy()
     const inner = matMatch![1]
     expect(inner).toMatch(/\$\{renderChild\('Tag', \{[^}]*id: id[^}]*variant: t\.variant[^}]*\}, id/)
@@ -287,7 +287,7 @@ describe('#1247 — static-loop CSR self-heal', () => {
     // Materialize branch present.
     expect(clientJs).toMatch(/if \(!__iterEl\)/)
     // Per-iteration template is `<li ...>...renderChild('Cell', ...)...</li>`.
-    const matMatch = clientJs.match(/__tpl\.innerHTML = `([^`]*)`/)
+    const matMatch = clientJs.match(/__tpl\.innerHTML = withParentScope\(__scopeId, \(\) => `([^`]*)`\)/)
     expect(matMatch).toBeTruthy()
     const inner = matMatch![1]
     expect(inner).toMatch(/^<li\b/)

package/src/adapters/child-scope.ts

@@ -20,3 +20,26 @@ export function derivesScopeFromSlot(
 ): boolean {
   return comp.slotId != null && comp.loopItemRoot !== true
 }
+
+/**
+ * The `renderChild(name, props, key, <here>)` tail arguments — the single
+ * decision point both CSR template emitters (`html-template.ts`'s two
+ * `case 'component'` branches) share, so they can't drift on it the way
+ * #2444 happened for `derivesScopeFromSlot` itself.
+ *
+ * A loop item root (`!derivesScopeFromSlot`) still gets its `slotId` and the
+ * `loopItemRoot` flag (#2833) rather than dropping the slot argument
+ * entirely as before: Hono stamps `bf-h`/`bf-m` on a row root too (just
+ * without deriving its `bf-s` from them), and a pure-CSR mount's static
+ * `qsaChildScopes` init selector needs that same marker to find the row.
+ */
+export function renderChildScopeArgs(
+  comp: Pick<IRComponent, 'slotId' | 'loopItemRoot'>,
+  keyArg: string
+): string {
+  if (comp.slotId == null) return keyArg
+  const key = keyArg || ', undefined'
+  return derivesScopeFromSlot(comp)
+    ? `${key}, '${comp.slotId}'`
+    : `${key}, '${comp.slotId}', true`
+}

package/src/analyzer.ts

@@ -3058,9 +3058,25 @@ function collectConstant(
       const value = defaultValueExpr ? `${baseValue} ?? ${defaultValueExpr}` : baseValue
       const containsArrow = el.initializer ? nodeContainsArrow(el.initializer) : false
       const freeIdentifiers = el.initializer ? extractFreeIdentifiersFromNode(el.initializer) : new Set([propsName])
+      // Structured parse of `value`, same as the plain-identifier branch
+      // below (#2724 review finding): without this, a RENAMED destructure
+      // (`const { items: rows } = props`) left `parsed` undefined forever,
+      // so `isArrayExprDirectPropRef`'s member-access recognition (which
+      // reads `.parsed`, not `.name`) never saw it — `rows` stayed
+      // classified `isStaticArray: true` even though it's `props.items`
+      // itself. Since #2835, the name-only branch reads `boundPropNames`
+      // (empty for a whole-`props`-param component) rather than the
+      // type-member-name set, so this `.parsed` is the only path for the
+      // un-renamed case too, not just the rename case. `parseExpression`
+      // naturally keeps a defaulted destructure (`value` ends in
+      // `?? <default>`) OUT of the
+      // `kind: 'member'` shape (it parses as a logical-or instead), which
+      // is what keeps that case correctly static per #2806.
+      const parsed = parseExpression(`(${value.trim()})`)
       ctx.localConstants.push({
         name: localName,
         value,
+        parsed,
         declarationKind,
         isExported,
         type: null,
@@ -3889,6 +3905,11 @@ function validateContext(ctx: AnalyzerContext): void {
   // failures before factory inlining landed (#931).
   validateReactiveFactoryCalls(ctx)
 
+  // BF013: flag a reactive primitive invoked through a namespace import
+  // that the analyzer could not resolve (#2771) — same "silently dropped,
+  // ReferenceError at hydrate" failure shape as BF011.
+  validateNamespaceQualifiedPrimitives(ctx)
+
   // BF003: a `"use client"` file may not import a component from a
   // non-`"use client"` source file (#1501). Server-side knowledge must
   // not transitively cross into the client bundle, and hydration-marker
@@ -5864,6 +5885,115 @@ export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
   }
 }
 
+/**
+ * BF013 (#2771): a reactive primitive called through a namespace import
+ * (`import * as bf from '@barefootjs/client'`, `bf.createSignal(...)`)
+ * that `resolvePrimitiveKind`'s checker-based slow path could not resolve
+ * — no shared `ts.Program` was supplied for this compile. Fast-path
+ * recognition only matches a bare identifier callee, so the call is
+ * silently dropped from `ctx.signals`/`ctx.memos`/etc. while every
+ * reference to its result survives in the emitted output, throwing
+ * ReferenceError at hydrate.
+ *
+ * Gated on non-recognition, not on the namespace-import shape itself:
+ * when a checker IS available (vite always supplies one via
+ * `corpus-program.ts`), `resolvePrimitiveKind` already resolves this
+ * shape soundly end-to-end, and this pass must not flag what the
+ * checker-aided path already handles correctly.
+ *
+ * Scoped to the component's own top-level statements, mirroring
+ * `validateReactiveFactoryCalls` above — a namespace-qualified call
+ * inside a handler/effect body is emitted verbatim and runs fine at
+ * hydrate (the namespace import itself is re-emitted, #2767 follow-up),
+ * so walking into nested bodies would produce false refusals.
+ */
+function validateNamespaceQualifiedPrimitives(ctx: AnalyzerContext): void {
+  if (!ctx.componentNode) return
+  const body = ts.isFunctionDeclaration(ctx.componentNode)
+    ? ctx.componentNode.body
+    : (ts.isBlock(ctx.componentNode.body) ? ctx.componentNode.body : null)
+  if (!body) return
+
+  for (const stmt of body.statements) {
+    const calls: ts.CallExpression[] = []
+    if (ts.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        let init = decl.initializer
+        // `const [n] = bf.createSignal(0)[0]` — vanishingly rare, but the
+        // element-access wrapper must not hide the call underneath it.
+        if (init && ts.isElementAccessExpression(init)) init = init.expression
+        if (init && ts.isCallExpression(init)) calls.push(init)
+      }
+    } else if (ts.isExpressionStatement(stmt) && ts.isCallExpression(stmt.expression)) {
+      calls.push(stmt.expression)
+    }
+
+    for (const call of calls) {
+      const callee = call.expression
+      if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)) continue
+      const primitive = callee.name.text
+      if (!(primitive in PRIMITIVE_CANONICAL_NAMES)) continue
+      if (resolvePrimitiveKind(call, ctx) !== null) continue // checker resolved it — sound, no diagnostic
+      const ns = callee.expression.text
+      if (!isClientNamespaceImportName(ns, ctx)) continue // import identity, not the bare name
+      if (isNamespaceNameShadowedAtComponentTopLevel(ns, body, ctx)) continue
+
+      const loc = getSourceLocation(stmt, ctx.sourceFile, ctx.filePath)
+      ctx.errors.push(
+        createError(ErrorCodes.PRIMITIVE_VIA_NAMESPACE_IMPORT, loc, {
+          severity: 'error',
+          message:
+            `'${ns}.${primitive}(...)' calls a @barefootjs/client reactive primitive through the namespace ` +
+            `import 'import * as ${ns}' and was not recognized by the analyzer. The declaration is dropped ` +
+            `from the compiled output and every reference to it throws ReferenceError at hydrate.`,
+          suggestion: {
+            message:
+              `Import the primitive by name: import { ${primitive} } from '@barefootjs/client' and call ` +
+              `${primitive}(...) directly. (A shared ts.Program passed via CompileOptions.program lets the ` +
+              `analyzer resolve the namespace through the TypeChecker; without one the named form is required.)`,
+            escape: [{ kind: 'rewrite' }],
+          },
+        })
+      )
+    }
+  }
+}
+
+function isClientNamespaceImportName(name: string, ctx: AnalyzerContext): boolean {
+  return ctx.imports.some(
+    imp =>
+      imp.source === '@barefootjs/client' &&
+      !imp.isTypeOnly &&
+      imp.specifiers.some(s => s.isNamespace && s.name === name)
+  )
+}
+
+/**
+ * A component-top-level binding that shadows the namespace import name
+ * (a local `const bf = ...`/function `bf`, or a prop param/props-object
+ * named `bf`) means `bf.createSignal` in THIS component isn't the client
+ * namespace at all — refusing would be a false positive. Does not model a
+ * shadow introduced in a nested block above the call site (same accepted
+ * posture as the checker-aided fast path).
+ */
+function isNamespaceNameShadowedAtComponentTopLevel(
+  name: string,
+  body: ts.Block,
+  ctx: AnalyzerContext
+): boolean {
+  if (ctx.propsObjectName === name) return true
+  if (ctx.propsParams.some(p => p.name === name)) return true
+  for (const stmt of body.statements) {
+    if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === name) return true
+    if (ts.isVariableStatement(stmt)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === name) return true
+      }
+    }
+  }
+  return false
+}
+
 /**
  * Object-destructure half of `validateReactiveFactoryCalls` (#2325). Split
  * out so the tuple path above stays a straight read of the pre-#2325 logic

package/src/errors.ts

@@ -19,8 +19,18 @@ export const ErrorCodes = {
   MISSING_USE_CLIENT: 'BF001',
   CLIENT_IMPORTING_SERVER: 'BF003',
 
-  // Signal/Memo errors (BF011-BF019)
+  // Signal/Memo errors (BF011-BF019). BF012 is retired (see
+  // `invalid-signal-usage.audit.test.ts`) — BF013 is the next free slot.
   SIGNAL_OUTSIDE_COMPONENT: 'BF011',
+  // A reactive primitive (createSignal/createMemo/createEffect/onMount/
+  // onCleanup/createSearchParams) called through a namespace import
+  // (`import * as bf from '@barefootjs/client'`, `bf.createSignal(...)`)
+  // that the analyzer could not resolve — no shared `ts.Program` was
+  // supplied, so `resolvePrimitiveKind`'s checker-based slow path never
+  // ran. Same failure shape as BF011: the declaration is silently dropped
+  // from the compiled output and every reference to it throws
+  // ReferenceError at hydrate. #2771.
+  PRIMITIVE_VIA_NAMESPACE_IMPORT: 'BF013',
 
   // JSX errors (BF021-BF029). BF022 was retired (see
   // `invalid-jsx-attribute.audit.test.ts`) and BF026 is reserved by
@@ -150,6 +160,9 @@ const errorMessages: Record<ErrorCode, string> = {
     'Module-level reactive declaration (createSignal / createMemo) is not allowed. ' +
     'The downstream codegen drops the declaration silently and every reference becomes a ReferenceError at SSR and at hydrate. ' +
     'Move the declaration inside a component function so each mount gets its own state.',
+  [ErrorCodes.PRIMITIVE_VIA_NAMESPACE_IMPORT]:
+    "Reactive primitive called through a namespace import of '@barefootjs/client' (import * as ns) is not recognized; " +
+    'the declaration is dropped and its references throw ReferenceError at hydrate. Import the primitive by name instead.',
 
   [ErrorCodes.UNSUPPORTED_JSX_PATTERN]: 'Unsupported JSX pattern',
   [ErrorCodes.MISSING_KEY_IN_LIST]:

package/src/index.ts

@@ -15,6 +15,12 @@ export { extractSsrDefaults, deriveStashFromDefaults } from './ssr-defaults.ts'
 export { propsDestructureBinding, buildPropAliasMap, isIdentifierName } from './props-binding.ts'
 export type { SsrDefault } from './ssr-defaults.ts'
 
+// Import-alias resolution (#2777 client-JS registry key; #2822 SSR cross-template
+// call names) — a local alias -> declared/exported name map built from
+// `ir.metadata.imports`. DSL adapters build this once per compile and look up
+// `aliasMap.get(comp.name) ?? comp.name` at each cross-template-call-name site.
+export { buildImportAliasMap } from './ir-to-client-js/component-scope.ts'
+
 // Backend-neutral SSR seed plan (in-template derived signal/memo seeding)
 export { computeSsrSeedPlan } from './ssr-seed-plan.ts'
 export type { SsrSeedPlan, SsrSeedStep } from './ssr-seed-plan.ts'
@@ -63,6 +69,7 @@ export type {
   ConformancePin,
   ConformancePins,
   RenderDivergences,
+  ImportInfo,
 } from './types.ts'
 
 // Analyzer

package/src/ir-to-client-js/build-references.ts

@@ -302,6 +302,13 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
         if (v && attr.value.kind !== 'literal') addExprEdges(ROOT_SOURCE, v, 'template-closure')
       }
       for (const ev of el.events) addExprEdges(ROOT_SOURCE, ev.handler, 'init-body')
+      // A `ref` callback runs in `initX`'s closure, same context as an event
+      // handler — not the template closure. Without this edge, a ref inside
+      // a loop nested past the top level (`elem.innerLoops`, never walked by
+      // Phase 1's dedicated ref traces) is invisible to reachability, so
+      // `computeDeclarationScopes` (compute-scope.ts) drops its declaration
+      // as dead code while the emitter still emits the call site (#2750).
+      if (el.ref) addExprEdges(ROOT_SOURCE, el.ref, 'init-body')
       descend()
     },
     component: ({ node: c, descend, descendJsxChildren }) => {

package/src/ir-to-client-js/child-components.ts

@@ -10,6 +10,7 @@
 
 import type { IRNode } from '../types.ts'
 import type { ClientJsContext, ConditionalElement } from './types.ts'
+import { resolveImportedComponentName } from './component-scope.ts'
 
 /** Emit child-component import marker lines for every component name
  *  reachable from the current component's IR (minus siblings). */
@@ -39,7 +40,13 @@ export function emitChildComponentImports(
   }
   for (const childName of childComponentNames) {
     if (!siblingSet.has(childName)) {
-      lines.push(`import '/* @bf-child:${childName} */'`)
+      // #2777 — resolve an import alias (`import { Foo as Bar }`, `<Bar/>`)
+      // to the declared name (`Foo`) the child's own module registers
+      // under, so `packages/vite`'s child-name index (keyed by exported
+      // names) and `combine-client-js.ts`'s `hydrate('Name')` scan both
+      // find it. `siblingSet` is checked against the LOCAL name above —
+      // a same-file sibling is never reached through an import alias.
+      lines.push(`import '/* @bf-child:${resolveImportedComponentName(childName)} */'`)
     }
   }
 }