@barefootjs/jsx 0.17.0 → 0.18.0

package/src/expression-parser.ts

@@ -99,18 +99,40 @@ export type ParsedExpr =
       object: ParsedExpr
       args: ParsedExpr[]
     }
-  // `.flat(depth?)` (#1448 Tier C). The flatten depth is validated and
-  // normalised into a structured `FlatDepth` at parse time — the literal
-  // never reaches `args`, so adapters fold via a runtime helper instead of
-  // re-inspecting the depth argument. A non-literal depth refuses with
-  // BF101 (the depth must be known at template time). See the `.flat` arm
-  // in `convertNode`.
+  // `.flat(depth?)` (#1448 Tier C, dynamic depth #2094). The flatten depth
+  // is validated at parse time — a literal integer / `Infinity` /
+  // unary-minus-literal normalises into a structured `FlatDepth` and the
+  // literal never reaches `args`, so adapters fold via a runtime helper
+  // instead of re-inspecting the depth argument. A non-literal depth that
+  // itself parses to a SUPPORTED `ParsedExpr` (a numeric prop, signal read,
+  // arithmetic, …) becomes a DYNAMIC depth: `depthExpr` carries that
+  // expression and `flatDepth` is a meaningless placeholder (`1`) — every
+  // consumer must check `depthExpr` first. A depth expression that itself
+  // doesn't resolve (an `unsupported` shape) still refuses with BF101 (the
+  // depth must be *expressible*, even if not known until render time). See
+  // the `.flat` arm in `convertNode`.
+  //
+  // Runtime coercion contract for a dynamic depth (JS `ToIntegerOrInfinity`,
+  // pinned by the `flat_dynamic` golden-vector cases): truncate toward
+  // zero; a NaN-producing value coerces to `0`; negative coerces to `0`
+  // (JS: negative depth never recurses, same as `0` — a shallow copy);
+  // `Infinity` / a huge finite value flattens fully. This is intentionally
+  // NOT the same runtime helper as the literal-depth path: the literal path
+  // pre-normalises `Infinity` to a `-1` *sentinel* meaning "flatten fully"
+  // (see `FlatDepth`'s doc), and a genuinely dynamic value of `-1` means
+  // the OPPOSITE (JS: no flatten) — reusing one helper for both would
+  // silently invert that case. Each adapter therefore routes a dynamic
+  // depth through a SEPARATE runtime helper (Go: `bf_flat_dynamic` /
+  // `FlatDynamicDepth`, distinct from the literal path's `bf_flat` / `Flat`)
+  // that performs the coercion above from scratch, never reusing the
+  // literal path's `-1`-means-infinite convention.
   | {
       kind: 'array-method'
       method: 'flat'
       object: ParsedExpr
       args: []
       flatDepth: FlatDepth
+      depthExpr?: ParsedExpr
     }
   | { kind: 'unsupported'; raw: string; reason: string }
 
@@ -247,8 +269,12 @@ export interface SupportResult {
 const UNSUPPORTED_METHODS = new Set([
   // Higher-order array methods. Seven of these (`filter`, `every`,
   // `some`, `find`, `findIndex`, `findLast`, `findLastIndex`) are
-  // intercepted as `higher-order` IR before reaching this gate;
-  // `map` is intercepted as an IRLoop. `reduce` / `reduceRight` stay
+  // intercepted as `higher-order` IR before reaching this gate.
+  // `map` is intercepted as an IRLoop when its callback returns JSX,
+  // and as a `CALLBACK_METHODS` evaluator lowering (`map_eval`, #2073)
+  // when it returns a value — it stays listed here so the fall-throughs
+  // (a bare `arr.map` reference, a function-reference callback) still
+  // refuse loudly. `reduce` / `reduceRight` stay
   // listed here so the shapes the Tier C catalogue can't lower still
   // refuse loudly: the `convertNode` call branch intercepts a matching
   // `.reduce(fn, init)` / `.reduceRight(fn, init)` into the structured
@@ -603,11 +629,12 @@ export function tsNodeToParsedExpr(node: ts.Node): ParsedExpr {
  * Higher-order array methods whose callback body the runtime evaluator drives
  * (#2018). Recognised generically as a `call` whose callee is `<recv>.<method>`
  * and whose first argument is an `arrow`; the adapter serializes the arrow body
- * to the evaluator. `map` is excluded — a JSX-returning `.map` is an IRLoop
- * upstream, and a value-returning `.map` has no template lowering.
+ * to the evaluator. A JSX-returning `.map` / `.flatMap` is an IRLoop upstream
+ * and never reaches this recognition; the value-returning `.map(cb)` form
+ * (e.g. `tags.map(t => \`#${t}\`).join(' ')`) lowers via `map_eval` (#2073).
  */
 export const CALLBACK_METHODS: ReadonlySet<string> = new Set([
-  'filter', 'every', 'some', 'find', 'findIndex', 'findLast', 'findLastIndex',
+  'filter', 'map', 'every', 'some', 'find', 'findIndex', 'findLast', 'findLastIndex',
   'sort', 'toSorted', 'reduce', 'reduceRight', 'flatMap',
 ])
 
@@ -790,6 +817,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       if (callee.property === 'flat') {
         const depthNode = node.arguments[0]
         let flatDepth: FlatDepth
+        let depthExpr: ParsedExpr | undefined
         if (depthNode === undefined) {
           flatDepth = 1
         } else if (ts.isIdentifier(depthNode) && depthNode.text === 'Infinity') {
@@ -806,16 +834,34 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
             n = -Number(depthNode.operand.text)
           }
           if (n === undefined || Number.isNaN(n)) {
-            return {
-              kind: 'unsupported',
-              raw,
-              reason: `\`.flat(depth)\` needs a literal integer or \`Infinity\` depth — a computed depth can't be resolved at template time. Use a literal depth, or pre-compute the value before the template.`,
+            // Not a literal — try a DYNAMIC depth: an expression that
+            // itself resolves to a supported `ParsedExpr` (a numeric prop,
+            // signal read, arithmetic, …) can be lowered through a runtime
+            // helper that coerces it at render time (JS
+            // `ToIntegerOrInfinity`; see the `depthExpr` doc on the
+            // `array-method`/`flat` type). Still refuse with BF101 when
+            // the depth expression itself is outside the supported
+            // surface — the depth must be *expressible*, even if not
+            // known until render time.
+            const parsedDepth = convertNode(depthNode, raw)
+            if (checkSupport(parsedDepth).supported) {
+              depthExpr = parsedDepth
+              flatDepth = 1 // unused placeholder — consumers must check `depthExpr` first
+            } else {
+              return {
+                kind: 'unsupported',
+                raw,
+                reason: `\`.flat(depth)\` needs a literal integer, \`Infinity\`, or a supported dynamic depth expression — this depth can't be resolved. Use a literal depth, a supported expression (prop/signal/arithmetic), or pre-compute the value before the template.`,
+              }
             }
+          } else {
+            const truncated = Math.trunc(n)
+            flatDepth = truncated < 0 ? 0 : truncated
           }
-          const truncated = Math.trunc(n)
-          flatDepth = truncated < 0 ? 0 : truncated
         }
-        return { kind: 'array-method', method: 'flat', object: callee.object, args: [], flatDepth }
+        return depthExpr !== undefined
+          ? { kind: 'array-method', method: 'flat', object: callee.object, args: [], flatDepth, depthExpr }
+          : { kind: 'array-method', method: 'flat', object: callee.object, args: [], flatDepth }
       }
       // `.toLowerCase()` — string-only (the IR carries a value-builtin
       // tag, not a receiver-type discriminator, so the `array-method`
@@ -1864,6 +1910,7 @@ function validateRestUsage(
       case 'array-method':
         walk(e.object)
         for (const a of e.args) walk(a)
+        if (e.method === 'flat' && e.depthExpr) walk(e.depthExpr)
         return
       case 'literal':
       case 'unsupported':
@@ -1976,6 +2023,7 @@ function collectIdentifiers(expr: ParsedExpr, out: Set<string>): void {
     case 'array-method':
       collectIdentifiers(expr.object, out)
       expr.args.forEach(e => collectIdentifiers(e, out))
+      if (expr.method === 'flat' && expr.depthExpr) collectIdentifiers(expr.depthExpr, out)
       return
     case 'literal':
     case 'regex':
@@ -2073,8 +2121,16 @@ function substituteDestructuredFields(
       case 'array-method':
         if (e.method === 'flat') {
           // `flatDepth` is a normalised literal — no destructure refs to
-          // substitute. Preserve verbatim.
-          return { kind: 'array-method', method: 'flat', object: walk(e.object), args: [], flatDepth: e.flatDepth }
+          // substitute. `depthExpr` (a dynamic depth) DOES need the same
+          // substitution as any other value position.
+          return {
+            kind: 'array-method',
+            method: 'flat',
+            object: walk(e.object),
+            args: [],
+            flatDepth: e.flatDepth,
+            ...(e.depthExpr ? { depthExpr: walk(e.depthExpr) } : {}),
+          }
         }
         return { kind: 'array-method', method: e.method, object: walk(e.object), args: e.args.map(walk) }
       case 'literal':
@@ -2197,6 +2253,16 @@ function checkSupport(expr: ParsedExpr): SupportResult {
         const argSupport = checkSupport(arg)
         if (!argSupport.supported) return argSupport
       }
+      // A dynamic `.flat(depth)` carries its depth expression outside
+      // `args` (see the `depthExpr` doc) — check it too. The parser
+      // already gated this at parse time (only a SUPPORTED depth
+      // expression becomes `depthExpr`), so this re-check is defensive:
+      // it keeps `isSupported` total for 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)
+        if (!depthSupport.supported) return depthSupport
+      }
       return { supported: true, level: 'L2' }
     }
 
@@ -2207,8 +2273,12 @@ function checkSupport(expr: ParsedExpr): SupportResult {
       // the receiver and the callback BODY are supported. Recognised before the
       // `UNSUPPORTED_METHODS` gate so the eval-lowered shapes aren't refused
       // (a BARE method reference — `arr.filter` uncalled, no arrow arg — still
-      // falls through to the gate). A nested callback inside the body refuses
-      // at the adapter's `serializeParsedExpr` purity gate, not here.
+      // falls through to the gate). A nested callback inside the body is NOT
+      // refused here: the evaluator refuses it (`serializeParsedExpr` → null)
+      // and each adapter then either lowers it faithfully (Mojo's inline
+      // `grep`, Go's `len (bf_filter_eval …)`) or surfaces BF101 at its
+      // predicate fallback's exact degrade points (#2038) — a blanket refusal
+      // here would break the faithful shapes (#1443 PR4).
       const cb = asCallbackMethodCall(expr)
       if (cb) {
         const objSupport = checkSupport(cb.object)
@@ -2329,6 +2399,31 @@ function checkSupport(expr: ParsedExpr): SupportResult {
     case 'logical': {
       const leftSupport = checkSupport(expr.left)
       if (!leftSupport.supported) return leftSupport
+
+      // `x ?? {}` — admit an EMPTY object-literal fallback as the right
+      // operand of `??` only. A standalone object literal stays refused
+      // (the `object-literal` case above), and a non-empty one here still
+      // falls through to the general `checkSupport(expr.right)` refusal
+      // below. This is deliberately narrow, scoped to the one shape that
+      // needs it (chart's `<Ctx.Provider value={{ config: props.config ??
+      // {} }}>`):
+      //   - `??` only, not `&&` / `||` — a `{}` operand there plays a
+      //     different (always-truthy) role that each adapter's
+      //     boolean/filter dispatcher already handles by treating an
+      //     object-literal leaf as an unconditional-truthy sentinel; that
+      //     path doesn't need a real emitted value the way `??`'s value
+      //     position does.
+      //   - EMPTY object literal only (`properties.length === 0`) — the
+      //     one caller of this shape never needs populated fallback keys,
+      //     and restricting to empty means every adapter's `objectLiteral`
+      //     value-emitter only has to special-case the zero-property case
+      //     (emit its language's empty dict/hashref literal) rather than
+      //     also lowering arbitrary member values through the general
+      //     expression pipeline for SSR/CSR parity.
+      if (expr.op === '??' && expr.right.kind === 'object-literal' && expr.right.properties.length === 0) {
+        return { supported: true, level: 'L4' }
+      }
+
       const rightSupport = checkSupport(expr.right)
       if (!rightSupport.supported) return rightSupport
 
@@ -2388,7 +2483,11 @@ export function containsHigherOrder(expr: ParsedExpr): boolean {
     case 'array-literal':
       return expr.elements.some(containsHigherOrder)
     case 'array-method':
-      return containsHigherOrder(expr.object) || expr.args.some(containsHigherOrder)
+      return (
+        containsHigherOrder(expr.object) ||
+        expr.args.some(containsHigherOrder) ||
+        (expr.method === 'flat' && expr.depthExpr !== undefined && containsHigherOrder(expr.depthExpr))
+      )
     default:
       return false
   }
@@ -2741,7 +2840,10 @@ function usesPerPath(name: string, expr: ParsedExpr): { min: number; max: number
       case 'array-literal':
         return sum(e.elements)
       case 'array-method':
-        return add(walk(e.object), e.method === 'flat' ? { min: 0, max: 0 } : sum(e.args))
+        if (e.method === 'flat') {
+          return add(walk(e.object), e.depthExpr ? walk(e.depthExpr) : { min: 0, max: 0 })
+        }
+        return add(walk(e.object), sum(e.args))
       case 'object-literal':
         return sum(e.properties.map(p => p.value))
       case 'arrow':
@@ -2817,7 +2919,14 @@ function inlineBinding(
         return { kind: 'array-literal', elements: e.elements.map(el => walk(el, enclosing)) }
       case 'array-method':
         if (e.method === 'flat') {
-          return { kind: 'array-method', method: 'flat', object: walk(e.object, enclosing), args: [], flatDepth: e.flatDepth }
+          return {
+            kind: 'array-method',
+            method: 'flat',
+            object: walk(e.object, enclosing),
+            args: [],
+            flatDepth: e.flatDepth,
+            ...(e.depthExpr ? { depthExpr: walk(e.depthExpr, enclosing) } : {}),
+          }
         }
         return { kind: 'array-method', method: e.method, object: walk(e.object, enclosing), args: e.args.map(a => walk(a, enclosing)) }
       case 'object-literal':
@@ -3033,8 +3142,12 @@ export function exprToString(expr: ParsedExpr): string {
       return `[${expr.elements.map(exprToString).join(', ')}]`
     case 'array-method':
       if (expr.method === 'flat') {
-        // Preserve the normalised depth so diagnostics don't misleadingly
-        // print `.flat()` for a `.flat(2)` / `.flat(Infinity)` source.
+        // Preserve the normalised / dynamic depth so diagnostics don't
+        // misleadingly print `.flat()` for a `.flat(2)` / `.flat(Infinity)`
+        // / `.flat(depthProp)` source.
+        if (expr.depthExpr) {
+          return `${exprToString(expr.object)}.flat(${exprToString(expr.depthExpr)})`
+        }
         const d = expr.flatDepth
         const depthSrc = d === 'infinity' ? 'Infinity' : String(d)
         return `${exprToString(expr.object)}.flat(${d === 1 ? '' : depthSrc})`
@@ -3106,8 +3219,12 @@ export function stringifyParsedExpr(expr: ParsedExpr): string {
       return `[${expr.elements.map(stringifyParsedExpr).join(', ')}]`
     case 'array-method':
       if (expr.method === 'flat') {
-        // Round-trip the normalised depth back to JS for the CSR / Hono
-        // path: `'infinity'` → `Infinity`, `1` is left implicit (`.flat()`).
+        // Round-trip the normalised / dynamic depth back to JS for the
+        // CSR / Hono path: `'infinity'` → `Infinity`, `1` is left implicit
+        // (`.flat()`), a dynamic depth round-trips its own expression.
+        if (expr.depthExpr) {
+          return `${stringifyParsedExpr(expr.object)}.flat(${stringifyParsedExpr(expr.depthExpr)})`
+        }
         const d = expr.flatDepth
         const depthSrc = d === 'infinity' ? 'Infinity' : String(d)
         return `${stringifyParsedExpr(expr.object)}.flat(${d === 1 ? '' : depthSrc})`
@@ -3121,6 +3238,85 @@ export function stringifyParsedExpr(expr: ParsedExpr): string {
   }
 }
 
+/**
+ * Rewrite every zero-arg `call` node whose callee is a bare identifier in
+ * `names` into that identifier — `tag()` → `tag` — leaving everything else
+ * untouched. Returns a new tree; the input is never mutated.
+ *
+ * Rationale: in an SSR seed/constructor context a signal/memo getter call
+ * reads the already-computed SEEDED value, so `tag()` reduces to "the value
+ * bound to `tag`". Materialising the call lets the runtime evaluator (which
+ * refuses any non-builtin call, {@link toEvalNode}'s `evalBuiltinCalleeName`
+ * gate) evaluate a predicate that reads sibling memos — e.g. a `.filter`
+ * predicate `(p) => !tag() || p.tags.includes(tag())` — with the getter's
+ * value supplied through the evaluator's `base_env` instead of an
+ * unsupported call node. `names` is caller-supplied (typically the sibling
+ * signals/memos seeded alongside the derived memo being lowered), so a call
+ * to an unrelated function is left as a `call` node and still refused by the
+ * evaluator's builtin gate if it reaches `serializeParsedExpr`.
+ */
+export function materializeGetterCalls(expr: ParsedExpr, names: ReadonlySet<string>): ParsedExpr {
+  const rw = (e: ParsedExpr): ParsedExpr => materializeGetterCalls(e, names)
+  switch (expr.kind) {
+    case 'call':
+      if (
+        expr.args.length === 0 &&
+        expr.callee.kind === 'identifier' &&
+        names.has(expr.callee.name)
+      ) {
+        return { kind: 'identifier', name: expr.callee.name }
+      }
+      return { kind: 'call', callee: rw(expr.callee), args: expr.args.map(rw) }
+    case 'binary':
+      return { kind: 'binary', op: expr.op, left: rw(expr.left), right: rw(expr.right) }
+    case 'logical':
+      return { kind: 'logical', op: expr.op, left: rw(expr.left), right: rw(expr.right) }
+    case 'unary':
+      return { kind: 'unary', op: expr.op, argument: rw(expr.argument) }
+    case 'conditional':
+      return {
+        kind: 'conditional',
+        test: rw(expr.test),
+        consequent: rw(expr.consequent),
+        alternate: rw(expr.alternate),
+      }
+    case 'member':
+      return { kind: 'member', object: rw(expr.object), property: expr.property, computed: expr.computed }
+    case 'index-access':
+      return { kind: 'index-access', object: rw(expr.object), index: rw(expr.index) }
+    case 'template-literal':
+      return {
+        kind: 'template-literal',
+        parts: expr.parts.map(p => (p.type === 'string' ? p : { type: 'expression', expr: rw(p.expr) })),
+      }
+    case 'array-literal':
+      return { kind: 'array-literal', elements: expr.elements.map(rw) }
+    case 'array-method':
+      // `flat`'s `args` is always `[]` (the depth is carried structurally in
+      // `flatDepth` / `depthExpr`, not `args`) — still rewrite `object` (and
+      // `depthExpr`, when dynamic), just skip the `args.map` that every
+      // other method needs.
+      if (expr.method === 'flat') {
+        return { ...expr, object: rw(expr.object), ...(expr.depthExpr ? { depthExpr: rw(expr.depthExpr) } : {}) }
+      }
+      return { ...expr, object: rw(expr.object), args: expr.args.map(rw) }
+    case 'object-literal':
+      return {
+        kind: 'object-literal',
+        raw: expr.raw,
+        properties: expr.properties.map(p => ({ ...p, value: rw(p.value) })),
+      }
+    case 'arrow':
+      return { kind: 'arrow', params: expr.params, body: rw(expr.body) }
+    // Leaves / opaque shapes — nothing to rewrite.
+    case 'identifier':
+    case 'literal':
+    case 'regex':
+    case 'unsupported':
+      return expr
+  }
+}
+
 /**
  * Serialize a pure-expression `ParsedExpr` (a higher-order callback body) into
  * the minimal JSON the runtime evaluator consumes — the format pinned by the
@@ -3155,30 +3351,36 @@ export function serializeParsedExpr(expr: ParsedExpr): string | null {
  */
 export function freeVarsInBody(body: ParsedExpr, params: ReadonlySet<string>): string[] {
   const found = new Set<string>()
-  const visit = (e: ParsedExpr): void => {
+  // `bound` starts as the outer callback's own `params` and grows when the
+  // walk descends into a nested `map`/`filter` callback arrow (#2094) — a
+  // NESTED arrow's own params shadow the outer ones for its body only,
+  // mirroring {@link freeIdentifiers}'s lexical scoping. Before #2094 a
+  // serializable body never contained a nested arrow, so this parameter
+  // didn't need to change per call; it does now.
+  const visit = (e: ParsedExpr, bound: ReadonlySet<string>): void => {
     switch (e.kind) {
       case 'identifier':
-        if (!params.has(e.name)) found.add(e.name)
+        if (!bound.has(e.name)) found.add(e.name)
         return
       case 'binary':
       case 'logical':
-        visit(e.left)
-        visit(e.right)
+        visit(e.left, bound)
+        visit(e.right, bound)
         return
       case 'unary':
-        visit(e.argument)
+        visit(e.argument, bound)
         return
       case 'conditional':
-        visit(e.test)
-        visit(e.consequent)
-        visit(e.alternate)
+        visit(e.test, bound)
+        visit(e.consequent, bound)
+        visit(e.alternate, bound)
         return
       case 'member':
-        visit(e.object)
+        visit(e.object, bound)
         return
       case 'index-access':
-        visit(e.object)
-        visit(e.index)
+        visit(e.object, bound)
+        visit(e.index, bound)
         return
       case 'call':
         // A builtin callee (`String`/`Number`/`Boolean`, or `Math.<fn>`) is
@@ -3186,35 +3388,137 @@ export function freeVarsInBody(body: ParsedExpr, params: ReadonlySet<string>): s
         // captured free var. Visiting it would add `Math` / `String` to the
         // env, making the adapter emit an undefined `$Math` / `.Math` base_env
         // entry (Copilot review #2031). Skip the callee identifier in that
-        // case; the arguments are still real references and are visited.
-        if (evalBuiltinCalleeName(e.callee) === null) visit(e.callee)
-        e.args.forEach(visit)
+        // case; the arguments are still real references and are visited
+        // (a nested `.map(cb)` / `.filter(cb)` callback call's `args[0]` is
+        // the callback `arrow`, visited below with its own params bound).
+        if (evalBuiltinCalleeName(e.callee) === null) visit(e.callee, bound)
+        e.args.forEach((a) => visit(a, bound))
         return
       case 'template-literal':
-        for (const p of e.parts) if (p.type === 'expression') visit(p.expr)
+        for (const p of e.parts) if (p.type === 'expression') visit(p.expr, bound)
         return
       case 'array-literal':
-        e.elements.forEach(visit)
+        e.elements.forEach((el) => visit(el, bound))
         return
       case 'object-literal':
         // Object *values* are references; keys are not. (Shorthand `{ x }`
         // carries the ref on its `value` identifier, which is visited here.)
-        for (const p of e.properties) visit(p.value)
+        for (const p of e.properties) visit(p.value, bound)
+        return
+      case 'array-method':
+        // `.includes(x)` / `.join(sep?)` are serializable ({@link
+        // toEvalNode}); their `object` (the receiver) and `args` (needle /
+        // separator) are the value positions serialized, so visit both when
+        // the tree reaches here with either method. A nested `.map`/`.filter`
+        // reaches this walk as a `call` (above), not an `array-method` — see
+        // {@link asCallbackMethodCall}. Every other `array-method` is
+        // non-serializable and doesn't occur in a serializable body.
+        if (e.method === 'includes' || e.method === 'join') {
+          visit(e.object, bound)
+          e.args.forEach((a) => visit(a, bound))
+        }
         return
+      // A nested callback arrow (the `.map`/`.filter` callback argument,
+      // #2094): its own params shadow the outer bound set for its body only.
+      case 'arrow': {
+        const inner = e.params.length === 0 ? bound : new Set([...bound, ...e.params])
+        visit(e.body, inner)
+        return
+      }
       // Non-serializable kinds don't occur in a serializable body
       // (serializeParsedExpr returns null for them); nothing to collect.
       case 'literal':
-      case 'array-method':
-      case 'arrow':
       case 'regex':
       case 'unsupported':
         return
     }
   }
-  visit(body)
+  visit(body, params)
   return [...found].sort()
 }
 
+/**
+ * Every value-position identifier in `expr` NOT bound by an enclosing arrow's
+ * own parameters — with proper lexical scoping: an arrow's params bind only
+ * within that arrow's body, and nested arrows accumulate onto the enclosing
+ * bound set. Unlike {@link freeVarsInBody} (which assumes a single flat param
+ * set and never recurses into nested `arrow` nodes, since a serializable
+ * evaluator body never contains one), this walks the full source-level tree —
+ * including arrows — so a caller can ask "is this name free ANYWHERE in the
+ * expression, honoring each arrow's own scope" rather than only within one
+ * callback body.
+ *
+ * Walks the same value positions as {@link serializeParsedExpr} /
+ * {@link freeVarsInBody}: call callee (skipped when it resolves to an
+ * evaluator builtin — see {@link evalBuiltinCalleeName} — so `Math.floor(x)`
+ * doesn't report `Math` as free) + args, binary/logical/unary operands,
+ * conditional branches, a member's OBJECT only (the property name is not a
+ * reference), an index-access's object + index, template-literal expression
+ * parts, array-literal elements, array-method object + args, and an
+ * object-literal's property VALUES (not keys). An `arrow` recurses into its
+ * body with its own params added to the bound set.
+ *
+ * Returns `null` when the tree contains an `unsupported` node (or any other
+ * shape this walk can't analyze) — the caller must fail safe rather than
+ * assume nothing is free.
+ */
+export function freeIdentifiers(expr: ParsedExpr): Set<string> | null {
+  const free = new Set<string>()
+
+  function visit(e: ParsedExpr, bound: ReadonlySet<string>): boolean {
+    switch (e.kind) {
+      case 'literal':
+      case 'regex':
+        return true
+      case 'identifier':
+        if (!bound.has(e.name)) free.add(e.name)
+        return true
+      case 'call': {
+        const isBuiltinCallee = evalBuiltinCalleeName(e.callee) !== null
+        if (!isBuiltinCallee && !visit(e.callee, bound)) return false
+        for (const a of e.args) if (!visit(a, bound)) return false
+        return true
+      }
+      case 'member':
+        return visit(e.object, bound)
+      case 'index-access':
+        return visit(e.object, bound) && visit(e.index, bound)
+      case 'binary':
+      case 'logical':
+        return visit(e.left, bound) && visit(e.right, bound)
+      case 'unary':
+        return visit(e.argument, bound)
+      case 'conditional':
+        return visit(e.test, bound) && visit(e.consequent, bound) && visit(e.alternate, bound)
+      case 'template-literal':
+        for (const p of e.parts) {
+          if (p.type === 'expression' && !visit(p.expr, bound)) return false
+        }
+        return true
+      case 'array-literal':
+        for (const el of e.elements) if (!visit(el, bound)) return false
+        return true
+      case 'array-method':
+        if (!visit(e.object, bound)) return false
+        for (const a of e.args) if (!visit(a, bound)) return false
+        if (e.method === 'flat' && e.depthExpr && !visit(e.depthExpr, bound)) return false
+        return true
+      case 'object-literal':
+        for (const p of e.properties) if (!visit(p.value, bound)) return false
+        return true
+      case 'arrow': {
+        const inner = new Set(bound)
+        for (const p of e.params) inner.add(p)
+        return visit(e.body, inner)
+      }
+      case 'unsupported':
+        return false
+    }
+  }
+
+  return visit(expr, new Set()) ? free : null
+}
+
 // Operators the evaluator implements (Go `eval.go` evalBinary / evalUnary, Perl
 // `Evaluator.pm` _binary / _unary). An op outside these sets — loose `==`,
 // `instanceof`, `**`, bitwise/shift, or the parser's `'unknown'` sentinel — is
@@ -3302,6 +3606,44 @@ function toEvalNode(e: ParsedExpr): Record<string, unknown> | null {
       return object && index ? { kind: 'index-access', object, index } : null
     }
     case 'call': {
+      // A nested `.map(cb)` / `.filter(cb)` callback call (#2094) — the
+      // SAME recognition `callbackMethod()` dispatch uses. Only these two
+      // widen into the evaluator's surface: they are order-preserving,
+      // per-element, and produce a bounded result, so the pure gate can
+      // still reason about them structurally. `sort` / `reduce` /
+      // `reduceRight` / `flat` / `flatMap` / `every` / `some` / `find*`
+      // nested INSIDE an eval body stay refused — `asCallbackMethodCall`
+      // recognizes them too, but they fall through to the generic
+      // non-builtin-callee refusal below because `cb.method` doesn't match
+      // either case here.
+      const cb = asCallbackMethodCall(e)
+      if (cb && (cb.method === 'map' || cb.method === 'filter')) {
+        const object = toEvalNode(cb.object)
+        if (!object) return null
+        const body = toEvalNode(cb.arrow.body)
+        if (!body) return null
+        // `cb.arrow.params` is always plain identifier names (the `ParsedExpr`
+        // `arrow` variant only carries destructure-rewritten / plain params —
+        // an array-binding-pattern param stays `unsupported` upstream and
+        // never reaches here). 1- and 2-param arrows are both supported for
+        // `map`/`filter` (element, and index when declared); the Go/eval-cases
+        // reference pins the 2-param contract.
+        //
+        // Re-serialized in the SAME `call` / `member` / `arrow` shape
+        // `asCallbackMethodCall` recognizes — NOT a bespoke wrapper — because
+        // the `eval-vectors.json` golden corpus carries the genuine
+        // `ParsedExpr` `parseExpression` produces (unfiltered by
+        // `toEvalNode`; see `eval-generate.ts`), which is exactly this
+        // shape. Using the same shape here means the compiled-template
+        // embedded body and the golden-vector corpus reach the evaluator in
+        // one encoding, so a single `EvalNode`/`evaluate` recognition path
+        // (Go `eval.go`, `eval-reference.ts`) covers both.
+        return {
+          kind: 'call',
+          callee: { kind: 'member', object, property: cb.method, computed: false },
+          args: [{ kind: 'arrow', params: cb.arrow.params, body }],
+        }
+      }
       // The evaluator executes only the builtin allowlist; a non-builtin callee
       // would evaluate to nil at runtime, so refuse it here (the purity gate).
       if (evalBuiltinCalleeName(e.callee) === null) return null
@@ -3346,10 +3688,39 @@ function toEvalNode(e: ParsedExpr): Record<string, unknown> | null {
       }
       return { kind: 'object-literal', properties }
     }
+    case 'array-method': {
+      // `.includes(x)` is one `array-method` the evaluator executes
+      // (Go `eval.go` / Perl `Evaluator.pm`, includes support): the
+      // receiver-type dispatch (array SameValueZero membership vs string
+      // substring) happens at evaluator runtime, same as the SSR template
+      // lowering's `bf_includes` / `$bf->includes`.
+      if (e.method === 'includes' && e.args.length === 1) {
+        const object = toEvalNode(e.object)
+        const arg = toEvalNode(e.args[0])
+        return object && arg ? { kind: 'array-method', method: 'includes', object, args: [arg] } : null
+      }
+      // `.join(sep?)` (#2094) — 0 or 1 serializable separator arg. Lets a
+      // nested `.map`/`.filter` chain feed straight into `.join(' ')` inside
+      // an eval body (the #1938 blog-showcase shape:
+      // `p.tags.map(t => '#' + t)` is joined by the OUTER `.join`, which is
+      // already the caller-visible template expression, not inside the eval
+      // body — this arm is for a `.join` that itself appears NESTED inside
+      // an eval body, e.g. a `.map(p => p.tags.join(','))` projection).
+      if (e.method === 'join' && e.args.length <= 1) {
+        const object = toEvalNode(e.object)
+        if (!object) return null
+        if (e.args.length === 0) return { kind: 'array-method', method: 'join', object, args: [] }
+        const sep = toEvalNode(e.args[0])
+        return sep ? { kind: 'array-method', method: 'join', object, args: [sep] } : null
+      }
+      // Every other `array-method` (`slice`, `flat`, `flatMap` [handled as
+      // its own `call` shape when it has an arrow, so not reached here],
+      // …) is outside the evaluator's surface and refuses.
+      return null
+    }
     // Outside the evaluator's pure-expression surface — refuse so the caller
     // falls back to BF101 / `@client`. A nested `arrow` (a callback inside the
     // body) is refused here, keeping the evaluator non-recursive.
-    case 'array-method':
     case 'arrow':
     case 'regex':
     case 'unsupported':