@barefootjs/jsx 0.14.0 → 0.15.1

package/src/expression-parser.ts

@@ -17,6 +17,14 @@ export type ParsedExpr =
   | { kind: 'literal'; value: string | number | boolean | null; literalType: 'string' | 'number' | 'boolean' | 'null' }
   | { kind: 'call'; callee: ParsedExpr; args: ParsedExpr[] }
   | { kind: 'member'; object: ParsedExpr; property: string; computed: boolean }
+  // Element access with a NON-literal index (`selected()[index]`,
+  // `rows[i + 1]`). A literal-index access (`arr[0]`, `obj['key']`)
+  // stays a `member` (computed) since the key is statically known and
+  // folds into the same property path. The variable case can't, so the
+  // index travels as its own `ParsedExpr` for the adapter to lower
+  // (array `->[$i]` vs hash `->{$k}` in Perl, `[index]` in JS). #1897
+  // (data-table's per-row `selected()[index]`).
+  | { kind: 'index-access'; object: ParsedExpr; index: ParsedExpr }
   | { kind: 'binary'; op: string; left: ParsedExpr; right: ParsedExpr }
   | { kind: 'unary'; op: string; argument: ParsedExpr }
   | { kind: 'conditional'; test: ParsedExpr; consequent: ParsedExpr; alternate: ParsedExpr }
@@ -46,6 +54,7 @@ export type ParsedExpr =
         | 'toLowerCase'
         | 'toUpperCase'
         | 'trim'
+        | 'toFixed'
         | 'split'
         | 'startsWith'
         | 'endsWith'
@@ -476,6 +485,106 @@ export function extractArrowBodyExpression(source: string): string | null {
   return expr.body.getText(sf).trim()
 }
 
+/**
+ * One member of a context-provider object-literal value
+ * (`<Ctx.Provider value={{ open: () => …, onOpenChange: … }}>`), classified
+ * for SSR lowering:
+ *
+ * - `getter` — a ZERO-parameter arrow with an expression body. At SSR time
+ *   the provider value is fixed for the render, so the getter is equivalent
+ *   to its body's value snapshot (`open: () => props.open ?? false` reads as
+ *   `props.open ?? false`). Arrows with parameters are NOT getters — their
+ *   body references the parameter, which has no SSR value.
+ * - `function` — any other function shape (parameterised / block-bodied
+ *   arrow, function expression, or a `??` / `||` chain with a function
+ *   operand). These are behavior, not data: SSR never invokes them, so
+ *   adapters lower them to their nil value (`undef` / `nil`).
+ * - `expression` — everything else; lowers through the adapter's normal
+ *   expression pipeline (so signal getters, props, memo calls keep their
+ *   existing SSR seeding semantics).
+ */
+export type ProviderObjectMember =
+  | { name: string; kind: 'getter'; body: string }
+  | { name: string; kind: 'function' }
+  | { name: string; kind: 'expression'; expr: string }
+
+/**
+ * Structurally parse a `<Ctx.Provider value={{ … }}>` object literal into
+ * per-member SSR lowering classifications (see `ProviderObjectMember`).
+ *
+ * Returns `null` when the source is not a plain object literal, or when it
+ * contains a shape with no per-member story (spread entry, computed key,
+ * get/set accessor) — callers fall back to their existing whole-expression
+ * path (typically a BF101 refusal). Shorthand members (`{ search }`) yield
+ * an `expression` member with the identifier as the expression; method
+ * members (`{ open() {…} }`) classify as `function` like block-bodied
+ * arrows.
+ */
+export function parseProviderObjectLiteral(source: string): ProviderObjectMember[] | null {
+  const sf = ts.createSourceFile(
+    '__provider__.ts',
+    `const __x = (${source});`,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */ true,
+  )
+  const stmt = sf.statements[0]
+  if (!stmt || !ts.isVariableStatement(stmt)) return null
+  let init = stmt.declarationList.declarations[0]?.initializer
+  while (init && ts.isParenthesizedExpression(init)) init = init.expression
+  if (!init || !ts.isObjectLiteralExpression(init)) return null
+
+  const isFunctionShaped = (e: ts.Expression): boolean => {
+    let v: ts.Expression = e
+    while (ts.isParenthesizedExpression(v)) v = v.expression
+    if (ts.isArrowFunction(v) || ts.isFunctionExpression(v)) return true
+    // `props.onX ?? (() => {})` — a fallback chain with a function operand
+    // is function-typed regardless of which side wins at runtime.
+    if (
+      ts.isBinaryExpression(v) &&
+      (v.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
+        v.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+    ) {
+      return isFunctionShaped(v.left) || isFunctionShaped(v.right)
+    }
+    return false
+  }
+
+  const members: ProviderObjectMember[] = []
+  for (const prop of init.properties) {
+    if (ts.isShorthandPropertyAssignment(prop)) {
+      members.push({ name: prop.name.text, kind: 'expression', expr: prop.name.text })
+      continue
+    }
+    if (ts.isMethodDeclaration(prop)) {
+      // `{ open() {…} }` — function-shaped behavior, same as a
+      // block-bodied arrow member.
+      const name = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : null
+      if (name === null) return null // computed key
+      members.push({ name, kind: 'function' })
+      continue
+    }
+    if (!ts.isPropertyAssignment(prop)) return null // spread / accessor
+    const name = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)
+      ? prop.name.text
+      : null
+    if (name === null) return null // computed key
+    let v: ts.Expression = prop.initializer
+    while (ts.isParenthesizedExpression(v)) v = v.expression
+    if (ts.isArrowFunction(v) && v.parameters.length === 0 && !ts.isBlock(v.body)) {
+      members.push({ name, kind: 'getter', body: v.body.getText(sf).trim() })
+      continue
+    }
+    if (isFunctionShaped(v)) {
+      members.push({ name, kind: 'function' })
+      continue
+    }
+    members.push({ name, kind: 'expression', expr: v.getText(sf).trim() })
+  }
+  return members
+}
+
 /**
  * A single entry of a JSX `style={{ … }}` object, lowered for SSR. The key is
  * already CSS-cased (`backgroundColor` → `background-color`); the value is
@@ -757,6 +866,14 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       if (callee.property === 'trim') {
         return { kind: 'array-method', method: 'trim', object: callee.object, args }
       }
+      // `.toFixed(digits?)` — Number → fixed-decimal string. The digit
+      // count (default 0) travels as the single arg; all adapters route
+      // through a `to_fixed` runtime helper (Perl) / `fmt.Sprintf` (Go)
+      // so JS's rounding + zero-padding semantics match. #1897
+      // (data-table's `payment.amount.toFixed(2)`).
+      if (callee.property === 'toFixed') {
+        return { kind: 'array-method', method: 'toFixed', object: callee.object, args }
+      }
       // `.split()` / `.split(sep)` / `.split(sep, limit)` — string →
       // array, full JS arity. `.split()` (no separator) returns the
       // whole string as a single element; `.split(sep)` splits on the
@@ -1028,6 +1145,13 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
   if (ts.isElementAccessExpression(node)) {
     const object = convertNode(node.expression, raw)
     const argNode = node.argumentExpression
+    // `argumentExpression` is non-optional in the TS types but CAN be
+    // undefined on an AST recovered from incomplete source (`arr[`). Guard
+    // so a half-typed expression surfaces a recoverable BF101 instead of
+    // throwing inside `ts.isNumericLiteral(undefined)`.
+    if (!argNode) {
+      return { kind: 'unsupported', raw, reason: 'Element access with no index expression' }
+    }
     // For simple number/string access, store as property
     if (ts.isNumericLiteral(argNode)) {
       return { kind: 'member', object, property: argNode.text, computed: true }
@@ -1035,8 +1159,13 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
     if (ts.isStringLiteral(argNode)) {
       return { kind: 'member', object, property: argNode.text, computed: true }
     }
-    // Complex computed access
-    return { kind: 'unsupported', raw, reason: 'Complex computed property access' }
+    // Variable / expression index (`selected()[index]`, `rows[i + 1]`):
+    // carry the index as its own ParsedExpr so the adapter can lower it
+    // (the literal forms above fold into a static property path; this
+    // one can't). #1897 (data-table).
+    const index = convertNode(argNode, raw)
+    if (index.kind === 'unsupported') return index
+    return { kind: 'index-access', object, index }
   }
 
   // Binary expression: a === b, count > 0, a + b
@@ -1988,6 +2117,8 @@ function findImpureDefaultNode(expr: ParsedExpr): string | null {
       return null
     case 'member':
       return findImpureDefaultNode(expr.object)
+    case 'index-access':
+      return findImpureDefaultNode(expr.object) ?? findImpureDefaultNode(expr.index)
     case 'unary':
       return findImpureDefaultNode(expr.argument)
     case 'binary':
@@ -2217,6 +2348,10 @@ function collectIdentifiers(expr: ParsedExpr, out: Set<string>): void {
     case 'member':
       collectIdentifiers(expr.object, out)
       return
+    case 'index-access':
+      collectIdentifiers(expr.object, out)
+      collectIdentifiers(expr.index, out)
+      return
     case 'binary':
     case 'logical':
       collectIdentifiers(expr.left, out)
@@ -2311,6 +2446,8 @@ function substituteDestructuredFields(
           }
         }
         return { kind: 'member', object: walk(e.object), property: e.property, computed: e.computed }
+      case 'index-access':
+        return { kind: 'index-access', object: walk(e.object), index: walk(e.index) }
       case 'binary':
         return { kind: 'binary', op: e.op, left: walk(e.left), right: walk(e.right) }
       case 'logical':
@@ -2559,6 +2696,17 @@ function checkSupport(expr: ParsedExpr): SupportResult {
       return { supported: true, level: 'L2' }
     }
 
+    case 'index-access': {
+      // `arr[index]` — supported when both the receiver and the index
+      // expression are themselves supported (the index is typically a
+      // loop variable or arithmetic over one). #1897 (data-table).
+      const objSupport = checkSupport(expr.object)
+      if (!objSupport.supported) return objSupport
+      const indexSupport = checkSupport(expr.index)
+      if (!indexSupport.supported) return indexSupport
+      return { supported: true, level: 'L2' }
+    }
+
     case 'binary': {
       const leftSupport = checkSupport(expr.left)
       if (!leftSupport.supported) return leftSupport
@@ -2640,6 +2788,8 @@ export function containsHigherOrder(expr: ParsedExpr): boolean {
       return expr.args.some(containsHigherOrder) || containsHigherOrder(expr.callee)
     case 'member':
       return containsHigherOrder(expr.object)
+    case 'index-access':
+      return containsHigherOrder(expr.object) || containsHigherOrder(expr.index)
     case 'binary':
       return containsHigherOrder(expr.left) || containsHigherOrder(expr.right)
     case 'unary':
@@ -2811,6 +2961,8 @@ export function exprToString(expr: ParsedExpr): string {
       return `${exprToString(expr.callee)}(${expr.args.map(exprToString).join(', ')})`
     case 'member':
       return `${exprToString(expr.object)}.${expr.property}`
+    case 'index-access':
+      return `${exprToString(expr.object)}[${exprToString(expr.index)}]`
     case 'binary':
       return `${exprToString(expr.left)} ${expr.op} ${exprToString(expr.right)}`
     case 'unary':
@@ -2892,6 +3044,8 @@ export function stringifyParsedExpr(expr: ParsedExpr): string {
         : JSON.stringify(expr.property)
       return `${obj}[${key}]`
     }
+    case 'index-access':
+      return `${stringifyParsedExpr(expr.object)}[${stringifyParsedExpr(expr.index)}]`
     case 'binary':
       return `${stringifyParsedExpr(expr.left)} ${expr.op} ${stringifyParsedExpr(expr.right)}`
     case 'unary':

package/src/index.ts

@@ -76,6 +76,7 @@ export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
 export { emitParsedExpr } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
+export { importsSearchParams, searchParamsLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
 export { emitIRNode } from './adapters/ir-node-emitter.ts'
 export type { IRNodeEmitter, EmitIRNode } from './adapters/ir-node-emitter.ts'
 export { emitAttrValue } from './adapters/attr-value-emitter.ts'
@@ -149,6 +150,11 @@ export type ExternalSpec =
 /**
  * An entry point to bundle directly with esbuild.
  * Externals declared in `BuildOptions.externals` are applied automatically.
+ * `@barefootjs/client`, `@barefootjs/client/runtime`, and
+ * `@barefootjs/client/reactive` are always kept external, so you never need
+ * to list them here. They resolve through the page's import map to the shared
+ * `barefoot.js` runtime; inlining them would fork the reactive runtime and
+ * duplicate signals (#927).
  * Use this for modules that are not barefoot components (e.g. plain TS entry
  * points that import external vendor packages).
  */
@@ -247,7 +253,7 @@ export {
 export { ErrorCodes, createError, formatError, generateCodeFrame } from './errors.ts'
 
 // Expression Parser
-export { parseExpression, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries } from './expression-parser.ts'
+export { parseExpression, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'
 export type { ParsedExpr, ParsedStatement, SortComparator, SortKey, ReduceOp, FlatDepth, FlatMapOp, FlatMapLeaf, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
 export { buildLoopChainExpr } from './loop-chain.ts'
@@ -354,7 +360,7 @@ export type {
 export { BOOLEAN_ATTRS, isBooleanAttr } from './html-constants.ts'
 
 // Shared props-object-pattern helpers for the Go / Mojo template adapters
-export { augmentInheritedPropAccesses, parseRecordIndexAccess, evalStringArrayJoin, collectContextConsumers } from './augment-inherited-props.ts'
+export { augmentInheritedPropAccesses, parseRecordIndexAccess, evalStringArrayJoin, collectModuleStringConsts, lookupStaticRecordLiteral, collectContextConsumers } from './augment-inherited-props.ts'
 export type { RecordIndexAccess, RecordIndexEntry, ContextConsumer } from './augment-inherited-props.ts'
 
 // HTML element attribute types

package/src/ir-to-client-js/imports.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ComponentIR, IRNode } from '../types.ts'
+import { isClientBuiltinName } from '../builtins.ts'
 
 // All exports from @barefootjs/client/runtime that may be used in generated code
 export const RUNTIME_IMPORT_CANDIDATES = [
@@ -62,6 +63,10 @@ export function collectUserDomImports(ir: ComponentIR): string[] {
     if (runtimeSources.has(imp.source) && !imp.isTypeOnly) {
       for (const spec of imp.specifiers) {
         if (!spec.isDefault && !spec.isNamespace) {
+          // Compile-away built-ins (`<Async>` / `<Region>`) are lowered into
+          // the template — never emit their import into the client bundle,
+          // where it would be a phantom runtime import (#1915).
+          if (isClientBuiltinName(spec.name)) continue
           userImports.push(spec.alias ? `${spec.name} as ${spec.alias}` : spec.name)
         }
       }

package/src/jsx-to-ir.ts

@@ -35,12 +35,14 @@ import {
 import { type AnalyzerContext, type MultiReturnJsxInfo, getSourceLocation } from './analyzer-context.ts'
 import { parseExpression, isSupported, parseBlockBody, extractSortComparatorFromTS, cssKebabCase, type ParsedExpr, type ParsedStatement, type SortComparator } from './expression-parser.ts'
 import { createError, ErrorCodes, internalInvariant } from './errors.ts'
+import { CLIENT_BUILTIN_SOURCE, isClientBuiltinName, type ClientBuiltinTag } from './builtins.ts'
 import { containsReactiveExpression } from './reactivity-checker.ts'
 import {
   rewriteBarePropRefs as rewriteBarePropRefsCore,
   collectAstPropRefs,
 } from './prop-rewrite.ts'
 import { resolveFreeRefs, type BindingEnvironment } from './free-refs.ts'
+import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
 
@@ -78,6 +80,8 @@ interface TransformContext {
   loopParams: Set<string>
   /** Counter for async boundary IDs (a0, a1, ...) */
   asyncIdCounter: number
+  /** Counter for <Region> structural index (0, 1, ...) within a file. */
+  regionIdCounter: number
   /** Counter for loop marker IDs (l0, l1, ...) — separate from slot IDs so element bf="sN" numbering stays stable across versions (#1087). */
   loopMarkerCounter: number
   /**
@@ -137,6 +141,14 @@ interface TransformContext {
    * See #1425.
    */
   _branchScopePropDeps?: Map<string, Set<string>>
+  /**
+   * Lazily computed map of local JSX tag name → compile-away built-in
+   * (`Async` / `Region`), derived from `@barefootjs/client` imports (#1915).
+   * Recognition is import-scoped (not a bare tag-name match) so a user's own
+   * `<Async>` / `<Region>` component doesn't collide with the built-in, and an
+   * aliased `import { Async as Boundary }` maps `<Boundary>` to the built-in.
+   */
+  _clientBuiltinTags?: Map<string, ClientBuiltinTag>
 }
 
 /**
@@ -366,6 +378,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     filePath: analyzer.filePath,
     slotIdCounter: 0,
     asyncIdCounter: 0,
+    regionIdCounter: 0,
     loopMarkerCounter: 0,
     spreadIdCounter: 0,
     isRoot: true,
@@ -705,6 +718,101 @@ function transformNode(node: ts.Node, ctx: TransformContext): IRNode | null {
 // JSX Element Transformation
 // =============================================================================
 
+/**
+ * Map a local JSX tag name to its compile-away built-in (`Async` / `Region`)
+ * if it was imported from `@barefootjs/client` (#1915). Recognition is
+ * import-scoped — keyed off `imports` metadata, never a bare tag-name match —
+ * so a user's own `<Async>` / `<Region>` component does not collide with the
+ * built-in, and `import { Async as Boundary }` maps `<Boundary>` to it.
+ * Memoized on `ctx`; the import list is fixed for the compile.
+ */
+function clientBuiltinTags(ctx: TransformContext): Map<string, ClientBuiltinTag> {
+  if (ctx._clientBuiltinTags) return ctx._clientBuiltinTags
+  const map = new Map<string, ClientBuiltinTag>()
+  for (const imp of ctx.analyzer.imports) {
+    // Require a *value* import: the tag is used as a JSX value, and the design
+    // is import-value-required. `import type { Async }` brings no value binding
+    // into scope (and is never a runtime import), so it does not scope the
+    // built-in — `<Async>` then falls through to BF054 (#1915 review).
+    if (imp.source !== CLIENT_BUILTIN_SOURCE || imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      // Skip per-specifier `import { type Async }` — no value binding.
+      if (spec.isDefault || spec.isNamespace || spec.isTypeOnly) continue
+      if (isClientBuiltinName(spec.name)) {
+        map.set(spec.alias ?? spec.name, spec.name)
+      }
+    }
+  }
+  ctx._clientBuiltinTags = map
+  return map
+}
+
+/**
+ * Whether `name` resolves to any in-scope value binding — an import (by its
+ * local name), a local function / constant, or an ambient `declare`. Used to
+ * keep the BF054 "import the built-in" diagnostic from firing when the author
+ * legitimately has their own `<Async>` / `<Region>` binding.
+ */
+function isNameBound(ctx: TransformContext, name: string): boolean {
+  const a = ctx.analyzer
+  if (a.ambientGlobals.has(name)) return true
+  if (a.localFunctions.some(f => f.name === name)) return true
+  if (a.localConstants.some(c => c.name === name)) return true
+  for (const imp of a.imports) {
+    // Type-only imports create a type binding, not a value one — they can't
+    // back a JSX value tag, so they must not suppress BF054. Applies to both
+    // `import type { ... }` and per-specifier `import { type X }` (#1915 review).
+    if (imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      if (spec.isTypeOnly) continue
+      if ((spec.alias ?? spec.name) === name) return true
+    }
+  }
+  return false
+}
+
+function reportBuiltinNotImported(
+  ctx: TransformContext,
+  node: ts.Node,
+  tagName: ClientBuiltinTag,
+): void {
+  ctx.analyzer.errors.push(
+    createError(
+      ErrorCodes.BUILTIN_REQUIRES_IMPORT,
+      getSourceLocation(node, ctx.sourceFile, ctx.filePath),
+      {
+        severity: 'error',
+        message: `<${tagName}> must be imported from '${CLIENT_BUILTIN_SOURCE}' to be recognised as a compiler built-in.`,
+        suggestion: {
+          message: `Add: import { ${tagName} } from '${CLIENT_BUILTIN_SOURCE}'`,
+        },
+      },
+    ),
+  )
+}
+
+/**
+ * Dispatch a built-in JSX tag (`Async` / `Region`) when import-scoped
+ * recognition matches, or emit BF054 when the bare built-in name is used
+ * without the import and without any other in-scope binding. Returns the
+ * lowered IR node, or `null` to fall through to normal component handling.
+ */
+function dispatchClientBuiltin(
+  tagName: string,
+  ctx: TransformContext,
+  diagNode: ts.Node,
+  transformAsync: () => IRNode,
+  transformRegion: () => IRNode,
+): IRNode | null {
+  const builtin = clientBuiltinTags(ctx).get(tagName)
+  if (builtin === 'Async') return transformAsync()
+  if (builtin === 'Region') return transformRegion()
+  if (isClientBuiltinName(tagName) && !isNameBound(ctx, tagName)) {
+    reportBuiltinNotImported(ctx, diagNode, tagName)
+  }
+  return null
+}
+
 function transformJsxElement(
   node: ts.JsxElement,
   ctx: TransformContext
@@ -716,10 +824,16 @@ function transformJsxElement(
     return transformProviderElement(node, ctx, tagName)
   }
 
-  // Detect Async streaming boundary: <Async fallback={...}>
-  if (tagName === 'Async') {
-    return transformAsyncElement(node, ctx)
-  }
+  // Detect compile-away built-ins (`<Async>` / `<Region>`), recognised by
+  // their `@barefootjs/client` import rather than by tag name (#1915).
+  const builtin = dispatchClientBuiltin(
+    tagName,
+    ctx,
+    node.openingElement,
+    () => transformAsyncElement(node, ctx),
+    () => transformRegionElement(node, ctx),
+  )
+  if (builtin) return builtin
 
   const isComponent = /^[A-Z]/.test(tagName)
 
@@ -782,10 +896,16 @@ function transformSelfClosingElement(
     return transformSelfClosingProviderElement(node, ctx, tagName)
   }
 
-  // Detect Async streaming boundary: <Async ... />
-  if (tagName === 'Async') {
-    return transformSelfClosingAsyncElement(node, ctx)
-  }
+  // Detect compile-away built-ins (`<Async />` / `<Region />`), recognised by
+  // their `@barefootjs/client` import rather than by tag name (#1915).
+  const builtin = dispatchClientBuiltin(
+    tagName,
+    ctx,
+    node,
+    () => transformSelfClosingAsyncElement(node, ctx),
+    () => transformSelfClosingRegionElement(node, ctx),
+  )
+  if (builtin) return builtin
 
   const isComponent = /^[A-Z]/.test(tagName)
 
@@ -1007,6 +1127,67 @@ function transformSelfClosingAsyncElement(
   }
 }
 
+/**
+ * Lower `<Region>{children}</Region>` to a plain wrapper element carrying the
+ * `bf-region` marker (spec/router.md "Regions"). The id is deterministic —
+ * `<file scope>:<index>` — so a layout that compiles to one shared partial
+ * emits the *same* id across every page that composes it, which is what the
+ * client router matches on. `<Region>` is recognised by its `@barefootjs/client`
+ * import (import-scoped, not a bare tag-name match — #1915).
+ */
+function regionId(ctx: TransformContext): string {
+  return `${computeFileScope(ctx.filePath)}:${ctx.regionIdCounter++}`
+}
+
+function transformRegionElement(
+  node: ts.JsxElement,
+  ctx: TransformContext
+): IRElement {
+  const id = regionId(ctx)
+
+  // Mirror transformHtmlElement's isRoot bookkeeping so the region's children
+  // are not mistaken for component roots.
+  const needsScope = ctx.isRoot
+  ctx.isRoot = false
+
+  const children = transformChildren(node.children, ctx)
+
+  return {
+    type: 'element',
+    tag: 'div',
+    attrs: [],
+    events: [],
+    ref: null,
+    children,
+    slotId: null,
+    needsScope,
+    regionId: id,
+    loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
+  }
+}
+
+function transformSelfClosingRegionElement(
+  node: ts.JsxSelfClosingElement,
+  ctx: TransformContext
+): IRElement {
+  const id = regionId(ctx)
+  const needsScope = ctx.isRoot
+  ctx.isRoot = false
+
+  return {
+    type: 'element',
+    tag: 'div',
+    attrs: [],
+    events: [],
+    ref: null,
+    children: [],
+    slotId: null,
+    needsScope,
+    regionId: id,
+    loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
+  }
+}
+
 // =============================================================================
 // Component Transformation
 // =============================================================================

package/src/ssr-defaults.ts

@@ -65,6 +65,12 @@ export interface SsrDefault {
 const UNRESOLVED = Symbol('unresolved')
 type EvalResult = unknown | typeof UNRESOLVED
 
+// Sentinel: a statement list ran to its end without hitting a `return`
+// (so the enclosing branch falls through to the next statement). Kept
+// distinct from `UNRESOLVED` (couldn't evaluate) so a falsy guard
+// (`if (!key) return X`) continues evaluation instead of bailing.
+const NO_RETURN = Symbol('no-return')
+
 interface EvalContext {
   /** Identifier name → previously-resolved value (signal getters, memos). */
   bindings: Record<string, EvalResult>
@@ -230,6 +236,53 @@ function tryStaticEval(expr: string, ctx: EvalContext): EvalResult {
   return evalNode(node, ctx)
 }
 
+/**
+ * Evaluate a block-body's statements for its returned value. Handles
+ * `const` declarations (bound into `ctx.bindings`, which mutate in
+ * place so later statements and nested branches see them), `return`
+ * statements, and `if (cond) …` guards whose condition is statically
+ * resolvable — the early-return-on-default-state shape of
+ * an `@client`-annotated memo (`const key = sortKey(); if (!key)
+ * return payments; … sort …`). A resolvable-but-falsy guard continues
+ * to the next statement (`NO_RETURN` from the skipped branch); an
+ * unresolvable condition or any other statement kind bails to
+ * `UNRESOLVED`. #1897 (data-table's `sortedData`).
+ */
+function evalStatementsForReturn(
+  statements: readonly ts.Statement[],
+  ctx: EvalContext,
+): EvalResult | typeof NO_RETURN {
+  for (const stmt of statements) {
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || !d.initializer) continue
+        const v = evalNode(d.initializer, ctx)
+        // Leave unresolved locals unbound; only a `return` / guard
+        // referencing one would then surface UNRESOLVED.
+        if (v !== UNRESOLVED) ctx.bindings[d.name.text] = v
+      }
+    } else if (ts.isReturnStatement(stmt)) {
+      return stmt.expression ? evalNode(stmt.expression, ctx) : UNRESOLVED
+    } else if (ts.isIfStatement(stmt)) {
+      const cond = evalNode(stmt.expression, ctx)
+      if (cond === UNRESOLVED) return UNRESOLVED
+      const branch = cond ? stmt.thenStatement : stmt.elseStatement
+      if (branch) {
+        const taken = evalStatementsForReturn(
+          ts.isBlock(branch) ? branch.statements : [branch],
+          ctx,
+        )
+        if (taken !== NO_RETURN) return taken
+      }
+      // Guard not taken (or its branch fell through) — continue.
+    } else {
+      // Any other statement (loop, side-effecting call) — bail.
+      return UNRESOLVED
+    }
+  }
+  return NO_RETURN
+}
+
 function parseExpression(expr: string): ts.Expression | null {
   // Wrap in parens so a leading `{}` parses as an object literal rather
   // than an empty block statement.
@@ -269,23 +322,8 @@ function evalNode(node: ts.Expression, ctx: EvalContext): EvalResult {
     if (!ts.isBlock(node.body)) return evalNode(node.body as ts.Expression, ctx)
     const localBindings: Record<string, EvalResult> = { ...ctx.bindings }
     const localCtx: EvalContext = { ...ctx, bindings: localBindings }
-    for (const stmt of node.body.statements) {
-      if (ts.isVariableStatement(stmt)) {
-        for (const d of stmt.declarationList.declarations) {
-          if (!ts.isIdentifier(d.name) || !d.initializer) continue
-          const v = evalNode(d.initializer, localCtx)
-          // Leave unresolved locals unbound; only the `return` referencing
-          // one would then surface UNRESOLVED.
-          if (v !== UNRESOLVED) localBindings[d.name.text] = v
-        }
-      } else if (ts.isReturnStatement(stmt)) {
-        return stmt.expression ? evalNode(stmt.expression, localCtx) : UNRESOLVED
-      } else {
-        // Any other statement (a branch, a side-effecting call) — bail.
-        return UNRESOLVED
-      }
-    }
-    return UNRESOLVED
+    const result = evalStatementsForReturn(node.body.statements, localCtx)
+    return result === NO_RETURN ? UNRESOLVED : result
   }
 
   if (ts.isNumericLiteral(node)) return Number(node.text)