@barefootjs/jsx 0.13.0 → 0.15.0

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/profiler.ts

@@ -32,8 +32,30 @@ import {
 import { listComponentFunctions, createProgramForFile } from './analyzer.ts'
 import type { ProfilerEvent } from '@barefootjs/shared'
 
+/**
+ * Schema version for the machine-readable `bf debug profile --json` output
+ * (#1841). Bumped when the shape of `StaticBudget` / `ProfileReport` /
+ * `BudgetDiff` changes in a way a consumer must notice. An agent can branch on
+ * this before trusting any other field — the contract is "same major version =
+ * additive only".
+ */
+export const PROFILE_SCHEMA_VERSION = 1
+
 // -- Static budget (SR5) ------------------------------------------------------
 
+/** An event handler the IR knows about — the unit `--scenario auto` fires. */
+export interface BudgetHandler {
+  /**
+   * `<eventName>@<slotId>` (e.g. `click@s1`). The slotId is the stable join
+   * key: it is the element marker `--scenario auto` dispatches against and the
+   * id the coverage report counts, so an agent can map a handler listed here to
+   * its dynamic coverage without running first.
+   */
+  name: string
+  /** Source location of the handler binding (1-indexed line). */
+  loc: { file: string; line: number }
+}
+
 export interface FanOutEntry {
   /** Signal name (the reactive source whose change fans out). */
   signal: string
@@ -55,6 +77,8 @@ export interface FanOutEntry {
 }
 
 export interface StaticBudget {
+  /** Machine-readable output contract version (#1841). See `PROFILE_SCHEMA_VERSION`. */
+  schemaVersion: number
   componentName: string
   sourceFile: string
   kind: 'static-budget'
@@ -70,6 +94,14 @@ export interface StaticBudget {
   memoChainLongest: string[]
   /** Per-signal fan-out, descending, hottest first. */
   fanOut: FanOutEntry[]
+  /**
+   * Event handlers the IR knows about — the exact set `--scenario auto` would
+   * fire — as name + source location (#1841). Exposed statically so an agent
+   * can predict the coverage gap and reference handler names *before* any run.
+   * Empty when this component binds no handlers (they may live in composed
+   * children — see `crossComponentOnly`).
+   */
+  handlers: BudgetHandler[]
   /**
    * True when the component declares reactive state (signals/memos) but nothing
    * in *this* component subscribes to it — every consumer is in a composed child
@@ -124,6 +156,22 @@ export function buildStaticBudget(
     })
     .sort((a, b) => b.subscribers - a.subscribers)
 
+  // Event handlers, in source order — the same `graph.domBindings` event slots
+  // the auto scenario fires (scenario-driver discovers handlers from here), so
+  // the static list and the dynamic coverage share one identity (slotId).
+  const handlers: BudgetHandler[] = graph.domBindings
+    .filter(b => b.type === 'event')
+    // Event bindings always carry `loc` (IREvent.loc is required), and coverage's
+    // turn→binding join keys on it too — so skip any loc-less binding rather than
+    // emit an invalid (line 0) location that a consumer would have to special-case.
+    .flatMap(b => {
+      if (!b.loc) return []
+      // Label is `<event> handler "<slot>"` — the same parse the scenario driver
+      // and coverage join use. Fall back to a neutral `event` if it ever drifts.
+      const eventName = b.label.match(/^(\w+)\s+handler/)?.[1] ?? 'event'
+      return [{ name: `${eventName}@${b.slotId}`, loc: { file: b.loc.file, line: b.loc.start.line } }]
+    })
+
   const { depth, chain } = longestMemoChain(graph)
 
   // Reactive state exists, yet nothing in *this* component observes it. The
@@ -141,6 +189,7 @@ export function buildStaticBudget(
   const crossComponentOnly = hasReactiveState && !observedInComponent
 
   return {
+    schemaVersion: PROFILE_SCHEMA_VERSION,
     componentName: summary.componentName,
     sourceFile: summary.sourceFile,
     kind: 'static-budget',
@@ -152,6 +201,7 @@ export function buildStaticBudget(
     memoChainDepth: depth,
     memoChainLongest: chain,
     fanOut,
+    handlers,
     crossComponentOnly,
   }
 }
@@ -254,6 +304,13 @@ export function formatStaticBudget(b: StaticBudget): string {
       lines.push(`    ${f.signal.padEnd(12)} → ${f.subscribers} subscribers${detail}${f.hot ? '   ⚠ high' : ''}`)
     }
   }
+  if (b.handlers.length > 0) {
+    lines.push(`  handlers (${b.handlers.length}):`)
+    for (const h of b.handlers) {
+      const file = h.loc.file.split('/').pop() ?? h.loc.file
+      lines.push(`    ${h.name.padEnd(16)} ${file}:${h.loc.line}`)
+    }
+  }
   if (b.crossComponentOnly) {
     lines.push(
       `  ⓘ compound: ${b.signals} signal(s) / ${b.memos} memo(s) but 0 in-component subscriptions —`,
@@ -281,6 +338,8 @@ export interface BudgetDiff {
    * component with no reactive state (#1849 B2).
    */
   kind: 'diff'
+  /** Machine-readable output contract version (#1841). See `PROFILE_SCHEMA_VERSION`. */
+  schemaVersion: number
   componentName: string
   signals: number
   memos: number
@@ -318,6 +377,7 @@ export function diffStaticBudget(base: StaticBudget, head: StaticBudget): Budget
 
   const d: Omit<BudgetDiff, 'regressed'> = {
     kind: 'diff',
+    schemaVersion: PROFILE_SCHEMA_VERSION,
     componentName: head.componentName,
     signals: head.signals - base.signals,
     memos: head.memos - base.memos,
@@ -1312,6 +1372,8 @@ export interface ProfileCoverage {
 
 export interface ProfileReport {
   kind: 'profile'
+  /** Machine-readable output contract version (#1841). See `PROFILE_SCHEMA_VERSION`. */
+  schemaVersion: number
   componentName: string
   sourceFile: string
   /** Scenario label (e.g. `'auto'` or a scenario file name). */
@@ -1464,6 +1526,7 @@ export function buildProfileReport(input: ProfileReportInput): ProfileReport {
 
   return {
     kind: 'profile',
+    schemaVersion: PROFILE_SCHEMA_VERSION,
     componentName: primary.componentName,
     sourceFile: primary.sourceFile,
     scenario,

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)

package/src/types.ts

@@ -302,6 +302,13 @@ export interface IRElement {
   children: IRNode[]
   slotId: string | null
   needsScope: boolean
+  /**
+   * Page-lifecycle boundary id for an element lowered from `<Region>`
+   * (spec/router.md). Set only on region host elements; adapters emit it as
+   * `bf-region="<id>"`. Deterministic (`<file scope>:<index>`) so a layout's
+   * shared partial carries the same id across every page that composes it.
+   */
+  regionId?: string
   loc: SourceLocation
 }
 
@@ -1206,6 +1213,15 @@ export interface ImportSpecifier {
   alias: string | null
   isDefault: boolean
   isNamespace: boolean
+  /**
+   * Per-specifier type-only import (`import { type Foo } from '...'`). Distinct
+   * from `ImportInfo.isTypeOnly` (the whole `import type { ... }` statement).
+   * A type-only specifier introduces no runtime/value binding, so consumers
+   * enforcing a value import (e.g. the `<Async>`/`<Region>` built-ins, #1915)
+   * must ignore it. Absent/false for value specifiers and for default /
+   * namespace imports (which cannot be per-specifier type-only).
+   */
+  isTypeOnly?: boolean
 }
 
 export interface FunctionInfo {