@barefootjs/jsx 0.33.4 → 0.34.0

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/expression-parser.ts

@@ -7,6 +7,7 @@
  */
 
 import ts from 'typescript'
+import { loweringNodeChildren, type LoweringMatcher } from './lowering-registry.ts'
 
 // =============================================================================
 // Parsed Expression Types
@@ -1049,7 +1050,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
             // surface — the depth must be *expressible*, even if not
             // known until render time.
             const parsedDepth = convertNode(depthNode, raw)
-            if (checkSupport(parsedDepth, 'rendered').supported) {
+            if (checkSupport(parsedDepth, 'rendered', []).supported) {
               depthExpr = parsedDepth
               flatDepth = 1 // unused placeholder — consumers must check `depthExpr` first
             } else {
@@ -2419,9 +2420,20 @@ function getUnaryOperatorString(op: ts.PrefixUnaryOperator): string {
  * reaches the page. See {@link isSupportedValue} for the sibling VALUE-
  * position entry point, and `checkSupport`'s `pos` parameter for why the two
  * never converge partway through a tree.
+ *
+ * `opts.loweringMatchers` (#2843), when given, lets a call recognised by a
+ * registered lowering plugin (`queryHref`, or any userland plugin) admit
+ * its params regardless of nesting position — a ternary branch, a
+ * template-literal interpolation, a binary operand, … — matching the
+ * top-level attribute path, which already consulted the same registry
+ * before this gate ever ran. Omit it (every existing caller does) for
+ * byte-identical prior behaviour.
  */
-export function isSupported(expr: ParsedExpr): SupportResult {
-  return checkSupport(expr, 'rendered')
+export function isSupported(
+  expr: ParsedExpr,
+  opts?: { loweringMatchers?: readonly LoweringMatcher[] },
+): SupportResult {
+  return checkSupport(expr, 'rendered', opts?.loweringMatchers ?? [])
 }
 
 /**
@@ -2430,10 +2442,13 @@ export function isSupported(expr: ParsedExpr): SupportResult {
  * assignment, never a render). The one behavioural difference from
  * {@link isSupported}: an `object-literal` anywhere in the tree is admitted
  * when every property value is itself supported, instead of being refused
- * outright.
+ * outright. See {@link isSupported}'s doc for `opts.loweringMatchers`.
  */
-export function isSupportedValue(expr: ParsedExpr): SupportResult {
-  return checkSupport(expr, 'value')
+export function isSupportedValue(
+  expr: ParsedExpr,
+  opts?: { loweringMatchers?: readonly LoweringMatcher[] },
+): SupportResult {
+  return checkSupport(expr, 'value', opts?.loweringMatchers ?? [])
 }
 
 /**
@@ -2453,7 +2468,7 @@ export function isSupportedValue(expr: ParsedExpr): SupportResult {
  */
 type ExprPos = 'rendered' | 'value'
 
-function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
+function checkSupport(expr: ParsedExpr, pos: ExprPos, matchers: readonly LoweringMatcher[]): SupportResult {
   switch (expr.kind) {
     case 'unsupported':
       return { supported: false, reason: expr.reason }
@@ -2471,7 +2486,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         // A spread entry's SOURCE must itself be supported at `value`
         // position — the same criterion as an explicit property's value,
         // since the spread source is read (not rendered) at merge time.
-        const propSupport = checkSupport(prop.kind === 'spread' ? prop.expr : prop.value, pos)
+        const propSupport = checkSupport(prop.kind === 'spread' ? prop.expr : prop.value, pos, matchers)
         if (!propSupport.supported) return propSupport
       }
       return { supported: true, level: 'L2' }
@@ -2498,7 +2513,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // method, not here, because we can't see which adapter is consuming
       // the IR at this point.
       for (const el of expr.elements) {
-        const elSupport = checkSupport(el, pos)
+        const elSupport = checkSupport(el, pos, matchers)
         if (!elSupport.supported) return elSupport
       }
       return { supported: true, level: 'L2' }
@@ -2518,10 +2533,10 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         }
       }
       // Receiver/args inherit `pos` (see `ExprPos`'s doc).
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) return objSupport
       for (const arg of expr.args) {
-        const argSupport = checkSupport(arg, pos)
+        const argSupport = checkSupport(arg, pos, matchers)
         if (!argSupport.supported) return argSupport
       }
       // A dynamic `.flat(depth)` carries its depth expression outside
@@ -2532,7 +2547,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // any `array-method`/`flat` node regardless of how it was constructed
       // (e.g. by a rewrite walker).
       if (expr.method === 'flat' && expr.depthExpr) {
-        const depthSupport = checkSupport(expr.depthExpr, pos)
+        const depthSupport = checkSupport(expr.depthExpr, pos, matchers)
         if (!depthSupport.supported) return depthSupport
       }
       return { supported: true, level: 'L2' }
@@ -2540,6 +2555,25 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
 
     case 'call': {
+      // #2843: a call a registered lowering plugin recognises (`queryHref`,
+      // or any userland plugin) is admitted regardless of where it sits in
+      // the tree — the neutral node's OWN children (`loweringNodeChildren`)
+      // are re-checked at the current `pos` instead of the call's raw
+      // `args`, so e.g. `queryHref`'s params object literal (refused at
+      // `rendered` position by the `object-literal` case above) doesn't
+      // reach that refusal at all: the plugin already took responsibility
+      // for it. Tried before `asCallbackMethodCall` and the generic per-arg
+      // loop below, matching the precedence the top-level attribute path
+      // already gives the registry.
+      for (const matcher of matchers) {
+        const node = matcher(expr.callee, expr.args)
+        if (!node) continue
+        for (const child of loweringNodeChildren(node)) {
+          const childSupport = checkSupport(child, pos, matchers)
+          if (!childSupport.supported) return childSupport
+        }
+        return { supported: true, level: 'L2' }
+      }
       // Higher-order callback methods (`.filter`/`.sort`/`.reduce`/… with an
       // arrow argument) lower via the runtime evaluator (#2018). Supported iff
       // the receiver and the callback BODY are supported. Recognised before the
@@ -2558,9 +2592,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // one (a signal/memo initializer) admits it.
       const cb = asCallbackMethodCall(expr)
       if (cb) {
-        const objSupport = checkSupport(cb.object, pos)
+        const objSupport = checkSupport(cb.object, pos, matchers)
         if (!objSupport.supported) return objSupport
-        const bodySupport = checkSupport(cb.arrow.body, pos)
+        const bodySupport = checkSupport(cb.arrow.body, pos, matchers)
         if (!bodySupport.supported) {
           return {
             supported: false,
@@ -2569,7 +2603,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
           }
         }
         for (const rest of cb.args) {
-          const restSupport = checkSupport(rest, pos)
+          const restSupport = checkSupport(rest, pos, matchers)
           if (!restSupport.supported) return restSupport
         }
         return { supported: true, level: 'L5' }
@@ -2577,7 +2611,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
       // Check if callee is supported. Not container contents — inherits
       // the CURRENT `pos` (see `ExprPos`'s doc).
-      const calleeSupport = checkSupport(expr.callee, pos)
+      const calleeSupport = checkSupport(expr.callee, pos, matchers)
       if (!calleeSupport.supported) {
         return calleeSupport
       }
@@ -2610,7 +2644,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // recognised callback/array-method (that path returned above) —
       // inherits the CURRENT `pos` (see `ExprPos`'s doc).
       for (const arg of expr.args) {
-        const argSupport = checkSupport(arg, pos)
+        const argSupport = checkSupport(arg, pos, matchers)
         if (!argSupport.supported) {
           return argSupport
         }
@@ -2620,7 +2654,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'member': {
       // Not container contents — inherits the CURRENT `pos`.
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) {
         return objSupport
       }
@@ -2636,9 +2670,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // expression are themselves supported (the index is typically a
       // loop variable or arithmetic over one). #1897 (data-table). Neither
       // is container contents — both inherit the CURRENT `pos`.
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) return objSupport
-      const indexSupport = checkSupport(expr.index, pos)
+      const indexSupport = checkSupport(expr.index, pos, matchers)
       if (!indexSupport.supported) return indexSupport
       return { supported: true, level: 'L2' }
     }
@@ -2646,9 +2680,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
     case 'binary': {
       // Operands inherit the CURRENT `pos` (see `ExprPos`'s doc) — a binary
       // operand isn't container contents.
-      const leftSupport = checkSupport(expr.left, pos)
+      const leftSupport = checkSupport(expr.left, pos, matchers)
       if (!leftSupport.supported) return leftSupport
-      const rightSupport = checkSupport(expr.right, pos)
+      const rightSupport = checkSupport(expr.right, pos, matchers)
       if (!rightSupport.supported) return rightSupport
 
       // Comparison operators are L3
@@ -2666,7 +2700,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'unary': {
       // Inherits the CURRENT `pos` — not container contents.
-      const argSupport = checkSupport(expr.argument, pos)
+      const argSupport = checkSupport(expr.argument, pos, matchers)
       if (!argSupport.supported) return argSupport
 
       // Negation is L4
@@ -2683,7 +2717,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'logical': {
       // Operands inherit the CURRENT `pos` — not container contents.
-      const leftSupport = checkSupport(expr.left, pos)
+      const leftSupport = checkSupport(expr.left, pos, matchers)
       if (!leftSupport.supported) return leftSupport
 
       // `x ?? {}` — admit an EMPTY object-literal fallback as the right
@@ -2710,7 +2744,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         return { supported: true, level: 'L4' }
       }
 
-      const rightSupport = checkSupport(expr.right, pos)
+      const rightSupport = checkSupport(expr.right, pos, matchers)
       if (!rightSupport.supported) return rightSupport
 
       return { supported: true, level: 'L4' }
@@ -2722,11 +2756,11 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // position both branches are themselves rendered — `cond ? {a:1} :
       // {b:2}` stays refused there, not admitted just for being a
       // sub-expression.
-      const testSupport = checkSupport(expr.test, pos)
+      const testSupport = checkSupport(expr.test, pos, matchers)
       if (!testSupport.supported) return testSupport
-      const consSupport = checkSupport(expr.consequent, pos)
+      const consSupport = checkSupport(expr.consequent, pos, matchers)
       if (!consSupport.supported) return consSupport
-      const altSupport = checkSupport(expr.alternate, pos)
+      const altSupport = checkSupport(expr.alternate, pos, matchers)
       if (!altSupport.supported) return altSupport
 
       return { supported: true, level: 'L4' }
@@ -2738,7 +2772,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // object-literal hole has no sensible rendering either way).
       for (const part of expr.parts) {
         if (part.type === 'expression') {
-          const partSupport = checkSupport(part.expr, pos)
+          const partSupport = checkSupport(part.expr, pos, matchers)
           if (!partSupport.supported) return partSupport
         }
       }

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
@@ -94,7 +101,7 @@ export { JsxAdapter } from './adapters/jsx-adapter.ts'
 export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate, rewriteDynamicImportsInSource } from './adapters/template-imports.ts'
 export { emitParsedExpr, groupBinaryOperand, groupObjectLiteralSegments, isStringTypedOperand, isStringConcatBinary } from './adapters/parsed-expr-emitter.ts'
-export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
+export type { ParsedExprEmitter, LoweringEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
 export { collectLoopBoundNames } from './adapters/loop-bound-names.ts'
 export { derivesScopeFromSlot } from './adapters/child-scope.ts'
 export { evaluateStaticLiteral, isFullyStaticLiteral, resolveStaticLoopSource } from './static-literal.ts'
@@ -107,6 +114,7 @@ export {
   prepareLoweringMatchers,
   matchLoweringCall,
   isValidHelperId,
+  loweringNodeChildren,
   __resetLoweringPluginsForTest,
   type LoweringPlugin,
   type LoweringNode,

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)} */'`)
     }
   }
 }

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

@@ -6,7 +6,7 @@ import { type IRNode, type IRElement, type IRComponent, type IRLoop, type IRProp
 import type { ClientJsContext, ConditionalBranchChildComponent, ConditionalBranchReactiveAttr, BranchLoop, ConditionalBranchTextEffect, ConditionalElement, LoopChildBindings, LoopChildBranchSummary, LoopChildConditional, LoopOffset, NestedLoop } from './types.ts'
 import { attrValueToString, freeIdsFromRefs, quotePropName, PROPS_PARAM } from './utils.ts'
 import { classifyReactivity, decideWrapForAttr, decideWrapForChildProp, decideWrapFromAstFlags, collectEventHandlersFromIR, collectConditionalBranchEvents, collectConditionalBranchRefs, collectConditionalBranchChildComponents, collectLoopChildEventsWithNesting, collectLoopChildReactiveAttrs, collectLoopChildReactiveTexts, collectLoopChildRefs, emptyLoopChildBindings, buildLoopRowScope, anyNameIn } from './reactivity.ts'
-import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, renderFlatMapClientBody, renderFlatMapProjectionClientBody, flatMapCallbackHasKeyedLeaf, type SkeletonSlotPaths } from './html-template.ts'
+import { irToHtmlTemplate, irToPlaceholderTemplate, irChildrenToJsExpr, jsxChildrenPropGetterExpr, buildLoopSkeletonTemplate, computeSkeletonSlotPaths, renderFlatMapClientBody, renderFlatMapProjectionClientBody, flatMapCallbackHasKeyedLeaf, type SkeletonSlotPaths } from './html-template.ts'
 import { detectRootNamespaceWrapTag } from './control-flow/stringify/template-parse.ts'
 import { expandDynamicPropValue, expandConstantForReactivity, resolveRestSpreadOrigin, resolveRestSpreadNames } from './prop-handling.ts'
 import { extractFreeIdentifiersFromText } from './csr-substitute.ts'
@@ -475,29 +475,6 @@ function jsxChildrenContainComponent(nodes: IRNode[]): boolean {
   return false
 }
 
-/**
- * Narrow gate for branding a `jsx-children` getter's value with `bfMarkup()`
- * (#2651). The constructor (`jsx-to-ir.ts`'s `processComponentProps`) always
- * stores exactly one node here (`AttrValueOf.jsxChildren([...])`), so
- * `nodes[0]` is the whole payload; `irChildrenToJsExpr` (`html-template.ts`)
- * turns a single `'element'` node into ONE HTML-string template literal —
- * the same shape the `renderChild` / `irToComponentTemplateWithOpts` /
- * `generateCsrTemplateWithOpts` "jsx-children" doors always produce (they
- * join every child into one string regardless of shape), and the shape
- * this fixture's `header={<strong>Title</strong>}` exercises.
- *
- * Deliberately narrow — NOT a general "does this reduce to one string"
- * check: a `'fragment'` node (`header={<>text<strong/></>}`, multiple
- * children) or a `'conditional'` node reduces through `irChildrenToJsExpr`
- * to an array literal or a nested ternary of un-escaped-vs-escaped parts,
- * for which `escapeTextOrNode`/`escapeTextOrMarkup` have no (array) or an
- * unproven (ternary) contract. Those shapes are left unbranded — see
- * #2651's door inventory — rather than guessed at here.
- */
-function isSingleElementJsxChildren(nodes: IRNode[]): boolean {
-  return nodes.length === 1 && nodes[0].type === 'element'
-}
-
 /** Build propsExpr for a child component from its IR props. */
 function buildComponentPropsExpr(props: IRProp[], ctx: ClientJsContext): string {
   const knownSpreadProp = props.find(p => {
@@ -526,19 +503,13 @@ function buildComponentPropsExpr(props: IRProp[], ctx: ClientJsContext): string
     }
     switch (prop.value.kind) {
       case 'jsx-children': {
-        const jsxExpr = irChildrenToJsExpr(prop.value.children)
         if (jsxChildrenContainComponent(prop.value.children)) {
+          const jsxExpr = irChildrenToJsExpr(prop.value.children)
           propsForInit.push(`get ${quotePropName(prop.name)}() { return __slot(() => ${jsxExpr}) }`)
-        } else if (prop.name !== 'children' && isSingleElementJsxChildren(prop.value.children)) {
-          // Brand (#2651): `jsxExpr` is the single HTML-string template
-          // literal `irChildrenToJsExpr` builds for a lone 'element' node —
-          // see `isSingleElementJsxChildren`'s docstring for why only this
-          // shape is branded here. Excludes an explicit `children={<jsx/>}`
-          // prop (out of scope, unchanged) — the child's `{children}`
-          // interpolation is a bare passthrough with no unwrap call, so a
-          // branded object there would stringify to `[object Object]`.
-          propsForInit.push(`get ${quotePropName(prop.name)}() { return bfMarkup(${jsxExpr}) }`)
         } else {
+          // Brand via the shared door (#2651/#2702) — see
+          // `jsxChildrenPropGetterExpr`'s docstring.
+          const jsxExpr = jsxChildrenPropGetterExpr(prop.value.children, prop.name)
           propsForInit.push(`get ${quotePropName(prop.name)}() { return ${jsxExpr} }`)
         }
         break
@@ -772,10 +743,11 @@ export function collectElements(
         // passed), matching the plain-element path's `staticItemTemplate`.
         if (l.isStaticArray && l.children[0]) {
           // `l.children[0]` is the loop's row-root component — already
-          // tagged `loopItemRoot` in the IR, so `derivesScopeFromSlot`
-          // drops the parent's slot suffix automatically. Each iteration
-          // owns a distinct scope identified by `data-key`, mirroring the
-          // SSR template's renderChild emit.
+          // tagged `loopItemRoot` in the IR, so `renderChildScopeArgs`
+          // passes its slotId with the `loopItemRoot` flag (#2833) instead
+          // of deriving its own scope from the parent slot. Each iteration
+          // still owns a distinct scope identified by `data-key`, mirroring
+          // the SSR template's renderChild emit.
           staticItemTemplate = irToHtmlTemplate(l.children[0], resolveRestSpreadNames(ctx), 0, undefined, undefined)
         }
       } else if (l.children[0] && !projectionInner) {

package/src/ir-to-client-js/component-scope.ts

@@ -1,3 +1,5 @@
+import type { ImportInfo } from '../types.ts'
+
 /**
  * File-scoped component name disambiguation for the runtime registry.
  *
@@ -63,8 +65,66 @@ export function setActiveComponentScope(scope: { fileScope: string; nonExportedS
   _activeScope = scope
 }
 
+/**
+ * #2777 — a client component referenced under an import alias
+ * (`import { Foo as Bar } from './Foo'`, `<Bar/>`) must resolve its
+ * registry key to the DECLARED/exported name (`Foo`, what the child's own
+ * module registers under via `hydrate('Foo', ...)`), not the caller-local
+ * binding (`Bar`) — the registry is keyed by string name, so a mismatch
+ * here left `initChild('Bar', ...)` unable to find `Foo`'s registration
+ * and hydration silently never ran.
+ *
+ * A local alias → exported name map, active per client-JS generation the
+ * same way `_activeScope` is (module-level state, installed/cleared by
+ * `generateClientJsWithSourceMap`) rather than threaded through every
+ * recursive emitter — same rationale as `_activeScope` above.
+ */
+let _activeImportAliases: ReadonlyMap<string, string> | null = null
+
+/**
+ * Build a local-alias → exported-name map from a component's parsed
+ * imports. Only VALUE, non-default, non-namespace, ALIASED specifiers
+ * produce an entry — a bare `import { Foo }` needs no rewrite (`name`
+ * already equals what's registered), and default/namespace imports can't
+ * be resolved this way (a default's exported name isn't recorded here,
+ * and a namespace member reference isn't an aliased specifier at all).
+ */
+export function buildImportAliasMap(imports: readonly ImportInfo[]): Map<string, string> {
+  const aliases = new Map<string, string>()
+  for (const imp of imports) {
+    if (imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      if (spec.isTypeOnly || spec.isDefault || spec.isNamespace || spec.alias === null) continue
+      aliases.set(spec.alias, spec.name)
+    }
+  }
+  return aliases
+}
+
+export function setActiveImportAliases(aliases: ReadonlyMap<string, string> | null): void {
+  _activeImportAliases = aliases
+}
+
+/**
+ * Resolve a local JSX tag name to the name the referenced component's own
+ * module registers under (`hydrate(<name>, ...)`) — the caller-facing
+ * alias if imported under one, otherwise the name unchanged. Used
+ * anywhere a name needs to reach the runtime registry WITHOUT also going
+ * through the non-exported-sibling rewrite below (the `@bf-child:` marker
+ * comment, which must never carry a same-file sibling's hash).
+ */
+export function resolveImportedComponentName(name: string): string {
+  return _activeImportAliases?.get(name) ?? name
+}
+
 /** Resolve a component name to its registry key under the active file scope. */
 export function nameForRegistryRef(name: string): string {
+  // An aliased IMPORT always wins over the non-exported-sibling rewrite:
+  // `import { Foo as Bar } from './Foo'` plus a private same-file
+  // `function Foo() {}` must still resolve `<Bar/>` to the imported
+  // `Foo`, not hash the sibling's `Foo` key onto it.
+  const imported = _activeImportAliases?.get(name)
+  if (imported !== undefined) return imported
   if (!_activeScope) return name
   if (!_activeScope.fileScope) return name
   if (!_activeScope.nonExportedSiblings.has(name)) return name