@barefootjs/jsx 0.6.0 → 0.7.0

package/src/expression-parser.ts

@@ -73,6 +73,49 @@ export type ParsedExpr =
       args: []
       comparator: SortComparator
     }
+  // `.reduce(fn, init)` (#1448 Tier C). Like sort, the reducer is
+  // extracted into a structured `ReduceOp` at parse time — the
+  // two-param arrow never reaches `args`, so adapters fold via a
+  // runtime helper instead of re-walking the callback. The accepted
+  // catalogue is the arithmetic-fold family only (`acc + key` /
+  // `acc * key`, numeric or string-concat); any other reducer body,
+  // or a missing initial value, falls through to `unsupported` so
+  // adapters surface BF101 with an @client suggestion. See
+  // `extractReduceOpFromTS` below.
+  | {
+      kind: 'array-method'
+      method: 'reduce' | 'reduceRight'
+      object: ParsedExpr
+      args: []
+      reduceOp: ReduceOp
+    }
+  // `.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`.
+  | {
+      kind: 'array-method'
+      method: 'flat'
+      object: ParsedExpr
+      args: []
+      flatDepth: FlatDepth
+    }
+  // `.flatMap(fn)` value-returning field projection (#1448 Tier C). The
+  // callback is extracted into a structured `FlatMapOp` (self / field
+  // projection) at parse time, mirroring sort / reduce. The projected
+  // per-item value is flattened one level (flatMap = map + flat(1)).
+  // Array-literal / complex callbacks fall through to `unsupported`; the
+  // JSX-returning `.flatMap` is handled as an `IRLoop` upstream and never
+  // reaches here. See `extractFlatMapOpFromTS` below.
+  | {
+      kind: 'array-method'
+      method: 'flatMap'
+      object: ParsedExpr
+      args: []
+      flatMapOp: FlatMapOp
+    }
   | { kind: 'unsupported'; raw: string; reason: string }
 
 /**
@@ -132,6 +175,95 @@ export type SortComparator = {
   method: 'sort' | 'toSorted'
 }
 
+/**
+ * Structured form of a JS `.reduce((acc, item) => …, init)` call,
+ * built once at parse time and consumed by both template adapters'
+ * `reduceMethod()` emit (#1448 Tier C). The shape is intentionally
+ * finite — only the arithmetic-fold family is lowerable in a
+ * declarative template; arbitrary accumulator bodies are not. See
+ * `extractReduceOpFromTS` for the accepted catalogue.
+ */
+export type ReduceOp = {
+  // The fold operator between accumulator and per-item value. `+`
+  // covers numeric sums and (with a string init) string concatenation;
+  // `*` covers numeric products. Subtraction / division are excluded —
+  // they're order-sensitive and rarely written as a `.reduce`.
+  op: '+' | '*'
+  // What value each item contributes to the fold:
+  //   { kind: 'self' }         → `acc + item`        (primitive array)
+  //   { kind: 'field', field } → `acc + item.field`  (struct-field accessor)
+  key: { kind: 'self' } | { kind: 'field'; field: string }
+  // Numeric fold vs string concatenation. Determined by the init
+  // literal's type: a number init folds numerically; a string init
+  // (only valid with `+`) concatenates. Both template runtimes apply
+  // the same coercion so their output stays byte-equal; this can
+  // diverge from JS for floating-point sums whose decimal expansion
+  // differs by runtime (rare in SSR data — integer sums agree).
+  type: 'numeric' | 'string'
+  // Decoded initial-accumulator value (never raw source). For a numeric
+  // fold this is TypeScript's canonical decimal form (`1_000` -> `1000`,
+  // `0x10` -> `16`) so `strconv.ParseFloat` / Perl agree; for a concat
+  // fold it's the contents of a quoted string literal (only single- or
+  // double-quoted `ts.StringLiteral` seeds are accepted — template
+  // literals and escape-carrying literals are refused at parse time, so
+  // the value is an escape-free single-line string, e.g. the empty
+  // string "" or a separator like ", "). Round-trip emitters re-quote a
+  // string init via `JSON.stringify`; a numeric init re-emits as-is.
+  init: string
+  // Original JS source of the reducer body (the returned expression
+  // for block bodies). Lets the `@client` fallback ship the user's
+  // exact arrow to the JS runtime.
+  raw: string
+  // The two parameter names the user wrote (e.g. `acc`/`item`, or
+  // `sum`/`t`). Only the `@client` fallback reads them — it binds them
+  // in a synthetic `(acc, item) => raw` arrow. Server-side lowering
+  // works off `op` / `key` / `init` and ignores them.
+  paramAcc: string
+  paramItem: string
+}
+
+/**
+ * Flatten depth for `.flat(depth?)` (#1448 Tier C). A finite non-negative
+ * integer flattens that many levels (`.flat()` defaults to `1`; a `0` or
+ * negative JS depth means "no flatten" → a shallow copy, normalised to
+ * `0` here); `'infinity'` is the `.flat(Infinity)` full-depth form. The
+ * depth must be a literal — a non-literal argument can't be resolved at
+ * template time and refuses with BF101.
+ */
+export type FlatDepth = number | 'infinity'
+
+/**
+ * A single non-computed projection leaf on the flatMap callback param —
+ * the item itself (`i`) or one of its fields (`i.field`). Shared by the
+ * scalar and tuple `FlatMapOp` projections.
+ */
+export type FlatMapLeaf = { kind: 'self' } | { kind: 'field'; field: string }
+
+/**
+ * Structured form of a value-returning `.flatMap(fn)` callback (#1448
+ * Tier C). The accepted catalogue:
+ *
+ *   i => i            → self  projection (flatten one level)
+ *   i => i.field      → field projection (flatten a per-item array field)
+ *   i => [i.a, i.b]   → tuple projection (gather per-item leaves)
+ *
+ * The scalar `self` / `field` projections return a value that is then
+ * flattened one level (flatMap = map + flat(1)) — a non-array value is
+ * kept as-is, matching JS. The `tuple` projection returns an array
+ * literal; flat(1) removes only that literal's wrapper, so each leaf is
+ * appended verbatim (an array-valued leaf is NOT spread). Leaves outside
+ * self / field (literals, `i.a + 1`, calls, deep access) refuse with
+ * BF101. See `extractFlatMapOpFromTS`.
+ */
+export type FlatMapOp = {
+  // What each item projects to before the one-level flatten.
+  projection: FlatMapLeaf | { kind: 'tuple'; elements: FlatMapLeaf[] }
+  // The callback param name the user wrote (for the `@client` round-trip).
+  param: string
+  // Original JS source of the callback body (for the `@client` fallback).
+  raw: string
+}
+
 export type TemplatePart =
   | { type: 'string'; value: string }
   | { type: 'expression'; expr: ParsedExpr }
@@ -166,6 +298,13 @@ export interface SupportResult {
   supported: boolean
   level?: SupportLevel
   reason?: string
+  /**
+   * The `reason` already spells out the fix (the pre-compute / `@client`
+   * hint, or a tailored message like the `forEach` diagnostic), so adapters
+   * surface it as-is instead of appending their own remediation block.
+   * Low-level reasons (operators, comparators, predicates) leave this unset.
+   */
+  selfContained?: boolean
 }
 
 // JS Array / String prototype methods that the template-language
@@ -188,10 +327,30 @@ 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. The rest stay refused — see
-  // #1448 Tier C for the design questions.
+  // `map` is intercepted as an IRLoop. `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
+  // `array-method` + `ReduceOp` form *before* this gate (returning
+  // early), so only the unlowerable fall-throughs (a `.reduce(fn)` with
+  // no initial value, or a bare method reference) reach the gate and
+  // refuse. A 2-arg call whose reducer/init shape is off-catalogue
+  // returns an explicit `unsupported` from the call branch with a richer
+  // message. The rest stay refused — see #1448 Tier C for the design
+  // questions. `forEach` carries a tailored reason (see
+  // `UNSUPPORTED_METHOD_REASONS`).
+  // `flat` is no longer here — `.flat(depth?)` lowers via the
+  // `array-method` IR (structured `FlatDepth`) + `bf_flat` (Go) /
+  // `bf->flat` (Mojo). `flatMap` stays listed as a fallback: the
+  // field-projection form (`i => i` / `i => i.field`) lowers via a
+  // structured `FlatMapOp`. The convertNode arm intercepts EVERY
+  // `.flatMap(...)` call before this gate — matching shapes lower, and the
+  // off-catalogue / wrong-arity forms get a tailored `unsupported` reason
+  // there — so only a bare method *reference* (`arr.flatMap` uncalled)
+  // falls through to this gate. The JSX-returning `.flatMap` lowers as an
+  // `IRLoop` upstream. See #1448.
   'filter', 'map', 'reduce', 'reduceRight', 'every', 'some',
-  'forEach', 'flatMap', 'flat',
+  'forEach', 'flatMap',
   // #1448 Tier A — Array methods. Each method PR adds the lowering
   // (typically a new `array-method` variant or runtime helper) and
   // removes its row here. See packages/adapter-tests/fixtures/methods/.
@@ -255,6 +414,20 @@ const UNSUPPORTED_METHODS = new Set([
   'substring', 'substr', 'match', 'matchAll', 'search',
 ])
 
+// Per-method override reasons for the BF101 refusal. A method here is still
+// refused via `UNSUPPORTED_METHODS` above; this only swaps the generic hint
+// for a tailored one. Add a row here rather than a branch in the support gate
+// when a method needs special wording.
+const UNSUPPORTED_METHOD_REASONS: Record<string, string> = {
+  // `forEach` returns `undefined`, so the generic pre-compute / @client hint
+  // is misleading (renders nothing either way) — steer to `.map(...)` /
+  // `createEffect`. Rationale pinned in foreach-client-only.test.ts.
+  forEach:
+    `'.forEach()' returns undefined and has no template-position meaning. ` +
+    `Use it for side effects inside an event handler or createEffect callback ` +
+    `(client JS), or use '.map(...)' if you meant to render each item.`,
+}
+
 // Methods that lower at their single-argument form but whose EXTRA
 // argument is meaningful and NOT yet lowered: the `fromIndex` of
 // `.includes` / `.indexOf` / `.lastIndexOf` (the 2-arg form) and the
@@ -446,6 +619,45 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       if (callee.property === 'reverse' || callee.property === 'toReversed') {
         return { kind: 'array-method', method: callee.property, object: callee.object, args }
       }
+      // `.flat(depth?)` — flatten nested arrays `depth` levels deep
+      // (default 1). The depth is validated to a literal and normalised
+      // into a structured `FlatDepth` here: `Infinity` becomes the
+      // full-depth form, a 0 / negative JS depth normalises to 0 ("no
+      // flatten" → shallow copy), and a fractional literal truncates
+      // toward zero (JS ToIntegerOrInfinity). A NON-literal depth can't be
+      // resolved at template time, so it refuses with BF101 rather than
+      // emitting a broken helper call. Go uses `bf_flat`; Mojo uses
+      // `bf->flat`. See #1448 Tier C.
+      if (callee.property === 'flat') {
+        const depthNode = node.arguments[0]
+        let flatDepth: FlatDepth
+        if (depthNode === undefined) {
+          flatDepth = 1
+        } else if (ts.isIdentifier(depthNode) && depthNode.text === 'Infinity') {
+          flatDepth = 'infinity'
+        } else {
+          let n: number | undefined
+          if (ts.isNumericLiteral(depthNode)) {
+            n = Number(depthNode.text)
+          } else if (
+            ts.isPrefixUnaryExpression(depthNode) &&
+            depthNode.operator === ts.SyntaxKind.MinusToken &&
+            ts.isNumericLiteral(depthNode.operand)
+          ) {
+            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.`,
+            }
+          }
+          const truncated = Math.trunc(n)
+          flatDepth = truncated < 0 ? 0 : truncated
+        }
+        return { 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`
       // label is a misnomer for string methods but the mechanical
@@ -633,6 +845,85 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
             `Wrap the call in /* @client */ to evaluate at hydration.`,
         }
       }
+
+      // `.reduce(fn, init)` / `.reduceRight(fn, init)` (#1448 Tier C).
+      // The reducer + init are extracted into a structured `ReduceOp` at
+      // parse time; the two-param arrow never reaches the standard
+      // convertNode path (which refuses it), so we read the raw TS AST.
+      // Only the arithmetic-fold catalogue lowers — anything else, or a
+      // missing init, falls through to `unsupported` (BF101 + @client
+      // hint). `reduceRight` shares the catalogue; the method name is
+      // preserved so adapters fold right-to-left (only observable for
+      // string concatenation — numeric sum / product are commutative).
+      if (
+        (callee.property === 'reduce' || callee.property === 'reduceRight') &&
+        node.arguments.length === 2
+      ) {
+        const reduceOp = extractReduceOpFromTS(node.arguments[0], node.arguments[1])
+        if (reduceOp) {
+          return {
+            kind: 'array-method',
+            method: callee.property,
+            object: callee.object,
+            args: [],
+            reduceOp,
+          }
+        }
+        const m = callee.property
+        return {
+          kind: 'unsupported',
+          raw,
+          reason:
+            `Reduce shape not supported. Accepted (arithmetic fold, explicit init):\n` +
+            `  arr.${m}((acc, x) => acc + x, 0)\n` +
+            `  arr.${m}((acc, x) => acc + x.field, 0)\n` +
+            `  arr.${m}((acc, x) => acc * x.field, 1)\n` +
+            `  arr.${m}((acc, x) => acc + x.field, '')   (string concat)\n` +
+            `The accumulator must be the left operand and the initial ` +
+            `value a number / string literal. ` +
+            `Wrap the call in /* @client */ to evaluate at hydration.`,
+        }
+      }
+      // A `.reduce(fn)` without an initial value can't be lowered: JS
+      // throws on an empty array, which a template can't mirror. Fall
+      // through to the BF101 gate with the @client escape hatch.
+
+      // `.flatMap(fn)` value-returning projection (#1448 Tier C). The
+      // callback is extracted into a structured `FlatMapOp` (self / field
+      // scalar projection, or an array-literal tuple of self / field
+      // leaves) from the raw TS AST. The JSX-returning form is handled as
+      // an `IRLoop` upstream and never reaches here; richer callbacks
+      // refuse with BF101 + the @client hint. Go uses `bf_flat_map` /
+      // `bf_flat_map_tuple`; Mojo uses `bf->flat_map` / `bf->flat_map_tuple`.
+      // Intercept EVERY `.flatMap(...)` call (not just the 1-arg form) so
+      // the off-catalogue and wrong-arity shapes get this tailored reason
+      // rather than the generic "flatMap has no template lowering" gate
+      // message, which now misleads (the field-projection form does lower).
+      if (callee.property === 'flatMap') {
+        const flatMapOp =
+          node.arguments.length === 1 ? extractFlatMapOpFromTS(node.arguments[0]) : null
+        if (flatMapOp) {
+          return {
+            kind: 'array-method',
+            method: 'flatMap',
+            object: callee.object,
+            args: [],
+            flatMapOp,
+          }
+        }
+        return {
+          kind: 'unsupported',
+          raw,
+          reason:
+            `flatMap shape not supported. Accepted (self / field leaves, no thisArg):\n` +
+            `  arr.flatMap(i => i)          (flatten one level)\n` +
+            `  arr.flatMap(i => i.field)    (flatten a per-item array field)\n` +
+            `  arr.flatMap(i => [i.a, i.b]) (gather per-item fields)\n` +
+            `Richer callbacks (computed / nested access, arithmetic, calls, ` +
+            `literal elements) and the 2-arg \`flatMap(fn, thisArg)\` form ` +
+            `aren't lowered. Wrap the call in /* @client */ to evaluate at hydration.`,
+        }
+      }
     }
 
     return { kind: 'call', callee, args }
@@ -1219,6 +1510,218 @@ function classifySortOperand(
   return null
 }
 
+/**
+ * Recover a `ReduceOp` from the `(reducer, init)` args of
+ * `.reduce(...)` (#1448 Tier C). Operates on the raw TS AST because the
+ * standard `convertNode` arrow-fn path rejects two-param arrows.
+ *
+ * The accepted catalogue is intentionally finite — only the
+ * arithmetic-fold family lowers to a declarative template:
+ *
+ *   (acc, x) => acc + x          → self,  numeric (init: number)
+ *   (acc, x) => acc + x.field    → field, numeric (init: number)
+ *   (acc, x) => acc * x          → self,  numeric (init: number)
+ *   (acc, x) => acc * x.field    → field, numeric (init: number)
+ *   (acc, x) => acc + x          → self,  string  (init: string → concat)
+ *   (acc, x) => acc + x.field    → field, string  (init: string → concat)
+ *
+ * The accumulator must be the binary expression's *left* operand
+ * (canonical reduce form; reversed operands change string-concat
+ * order), the per-item value must be the item param itself or a
+ * single non-computed field access on it, and the init must be a
+ * number or string literal (negative numbers via prefix `-` allowed).
+ * String concatenation requires `+`. Block bodies reduce to a single
+ * `return`, mirroring the sort extractor. Anything else returns null
+ * and the caller emits `unsupported` (BF101).
+ */
+export function extractReduceOpFromTS(
+  reducerNode: ts.Node,
+  initNode: ts.Node,
+): ReduceOp | null {
+  const init = classifyReduceInit(initNode)
+  if (!init) return null
+
+  if (!ts.isArrowFunction(reducerNode) && !ts.isFunctionExpression(reducerNode)) return null
+  // Exactly `(acc, item)` — the index / array reducer params can't be
+  // expressed in a template fold, so refuse the 3- / 4-param forms.
+  if (reducerNode.parameters.length !== 2) return null
+  const pAcc = reducerNode.parameters[0]
+  const pItem = reducerNode.parameters[1]
+  if (!ts.isIdentifier(pAcc.name) || !ts.isIdentifier(pItem.name)) return null
+  const paramAcc = pAcc.name.text
+  const paramItem = pItem.name.text
+
+  // Resolve the reducer body: expression-bodied arrow directly; block
+  // bodies (arrow `=> { … }` and function expressions) must reduce to
+  // exactly one `return <expr>;` — mirrors `extractSortComparatorFromTS`.
+  let body: ts.Expression
+  if (ts.isArrowFunction(reducerNode) && !ts.isBlock(reducerNode.body)) {
+    body = reducerNode.body
+  } else {
+    const block = reducerNode.body as ts.Block
+    const stmts = block.statements
+    if (stmts.length !== 1 || !ts.isReturnStatement(stmts[0]) || !stmts[0].expression) return null
+    body = stmts[0].expression
+  }
+  const raw = body.getText()
+
+  const expr = unwrapParens(body)
+  if (!ts.isBinaryExpression(expr)) return null
+  let op: '+' | '*'
+  if (expr.operatorToken.kind === ts.SyntaxKind.PlusToken) op = '+'
+  else if (expr.operatorToken.kind === ts.SyntaxKind.AsteriskToken) op = '*'
+  else return null
+
+  // The accumulator must be the left operand (`acc + x`, not `x + acc`).
+  const left = unwrapParens(expr.left)
+  if (!ts.isIdentifier(left) || left.text !== paramAcc) return null
+
+  const key = classifyReduceKey(unwrapParens(expr.right), paramItem)
+  if (!key) return null
+
+  // String concatenation only makes sense with `+`.
+  const type: 'numeric' | 'string' = init.type
+  if (type === 'string' && op !== '+') return null
+
+  return { op, key, type, init: init.value, raw, paramAcc, paramItem }
+}
+
+/**
+ * Recover a `FlatMapOp` from the single-argument callback of a
+ * value-returning `.flatMap(fn)` (#1448 Tier C). Operates on the raw TS
+ * AST, mirroring `extractReduceOpFromTS`.
+ *
+ * The accepted catalogue:
+ *
+ *   i => i            → self  (flatMap(identity) === flat(1))
+ *   i => i.field      → field (flatten a per-item array field)
+ *   i => [i.a, i.b]   → tuple (gather per-item self / field leaves)
+ *
+ * The callback must take exactly one identifier param (the index / array
+ * params can't be expressed in a template projection), and the body must
+ * be the param itself, a single non-computed field access on it, or an
+ * array literal whose every element is one of those leaves. Block bodies
+ * reduce to a single `return`, like the reduce / sort extractors. Any
+ * other body (deep access, computed members, calls, arithmetic, a
+ * literal element) returns null and the caller emits `unsupported`
+ * (BF101).
+ */
+export function extractFlatMapOpFromTS(cbNode: ts.Node): FlatMapOp | null {
+  if (!ts.isArrowFunction(cbNode) && !ts.isFunctionExpression(cbNode)) return null
+  // Exactly `(item)` — a `(item, index)` / `(item, index, array)` callback
+  // can't be lowered to a declarative projection.
+  if (cbNode.parameters.length !== 1) return null
+  const p = cbNode.parameters[0]
+  if (!ts.isIdentifier(p.name)) return null
+  const param = p.name.text
+
+  let body: ts.Expression
+  if (ts.isArrowFunction(cbNode) && !ts.isBlock(cbNode.body)) {
+    body = cbNode.body
+  } else {
+    const block = cbNode.body as ts.Block
+    const stmts = block.statements
+    if (stmts.length !== 1 || !ts.isReturnStatement(stmts[0]) || !stmts[0].expression) return null
+    body = stmts[0].expression
+  }
+  const raw = body.getText()
+  const inner = unwrapParens(body)
+
+  // Array-literal body → tuple projection. Every element must be a
+  // self / field leaf; a literal / computed / nested element refuses the
+  // whole shape (the per-item evaluation of richer expressions isn't
+  // lowered). flat(1) removes only the literal's wrapper, so each leaf is
+  // appended verbatim — handled by the `bf_flat_map_tuple` runtime.
+  if (ts.isArrayLiteralExpression(inner)) {
+    // An empty tuple (`i => []`) is a degenerate no-op projection (always
+    // yields nothing). Refuse it so the emitters never produce a
+    // zero-arg `bf_flat_map_tuple` / `bf->flat_map_tuple(...,)` call.
+    if (inner.elements.length === 0) return null
+    const elements: FlatMapLeaf[] = []
+    for (const el of inner.elements) {
+      // Spread / holes (`[...xs]`, `[, x]`) aren't leaves.
+      if (ts.isSpreadElement(el) || ts.isOmittedExpression(el)) return null
+      const leaf = classifyReduceKey(unwrapParens(el), param)
+      if (!leaf) return null
+      elements.push(leaf)
+    }
+    return { projection: { kind: 'tuple', elements }, param, raw }
+  }
+
+  // Scalar body. Reuse the reduce key classifier — `i` → self,
+  // `i.field` → field, null for anything deeper (`i.a.b`, `i[k]`, a call).
+  const leaf = classifyReduceKey(inner, param)
+  if (!leaf) return null
+
+  return { projection: leaf, param, raw }
+}
+
+/**
+ * Classify a reduce per-item operand into a `ReduceOp` key. Accepts
+ * the bare item param (`x` → self) and a single non-computed field
+ * access (`x.field` → field); returns null for anything deeper
+ * (`x.a.b`, `x[k]`, a literal, a call, …).
+ */
+function classifyReduceKey(
+  expr: ts.Expression,
+  paramItem: string,
+): { kind: 'self' } | { kind: 'field'; field: string } | null {
+  if (ts.isIdentifier(expr)) {
+    return expr.text === paramItem ? { kind: 'self' } : null
+  }
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression)) {
+    if (expr.expression.text === paramItem) return { kind: 'field', field: expr.name.text }
+  }
+  return null
+}
+
+/**
+ * Classify a reduce initial-value node into the *decoded* fold seed.
+ * Accepts a numeric literal (optionally prefixed with `-`) and a string
+ * literal; returns `{ type, value }` where `value` is the canonical
+ * value — never the raw source text. Any other init (a variable, a
+ * call, an object) returns null — the fold start value must be
+ * statically known.
+ *
+ * Numeric: `node.text` is TypeScript's canonical decimal form, so
+ * separators and non-decimal radices fold uniformly across adapters
+ * (`1_000` → `1000`, `0x10` → `16`, `1e3` → `1000`). The Go runtime's
+ * `strconv.ParseFloat` and Perl both accept that decimal string —
+ * passing the raw source (`0x10`, `1_000`) would silently fold to 0 on
+ * Go while Perl accepted it (#1728 review).
+ *
+ * String: `node.text` is the *unescaped* contents. To keep the three
+ * adapters byte-equal without teaching each one to re-decode JS escapes
+ * (`\n`, `\u{…}`, `\\`, an escaped quote), we refuse any string literal
+ * whose contents differ from its raw inner source — i.e. any literal
+ * carrying an escape sequence. Accepted seeds are therefore escape-free
+ * single-line strings (`''`, `', '`, `'-'`), which embed safely in both
+ * the Go-template `"…"` operand and the Perl single-quoted literal. The
+ * realistic concat seed (`''`) is unaffected; richer seeds fall back to
+ * the `@client` escape hatch.
+ */
+function classifyReduceInit(
+  node: ts.Node,
+): { type: 'numeric' | 'string'; value: string } | null {
+  // Unwrap redundant parens (`(0)` / `(-1)`) so they classify like the
+  // bare literal — matches the extractor's `unwrapParens` use elsewhere.
+  let n: ts.Node = unwrapParens(node as ts.Expression)
+  // `-1` parses as a prefix-minus over a numeric literal.
+  if (ts.isPrefixUnaryExpression(n) && n.operator === ts.SyntaxKind.MinusToken) {
+    if (ts.isNumericLiteral(n.operand)) return { type: 'numeric', value: '-' + n.operand.text }
+    return null
+  }
+  if (ts.isNumericLiteral(n)) return { type: 'numeric', value: n.text }
+  if (ts.isStringLiteral(n)) {
+    // Refuse literals carrying escapes so the decoded value equals its
+    // raw inner source (and thus embeds safely + byte-equal everywhere).
+    const raw = n.getText()
+    if (raw.length < 2 || raw.slice(1, -1) !== n.text) return null
+    return { type: 'string', value: n.text }
+  }
+  return null
+}
+
 /**
  * Per-binding entry stored in `fieldMap`: the dotted path from the
  * synthetic param down to the field, plus an optional default
@@ -1767,6 +2270,22 @@ function substituteDestructuredFields(
           // enclosing destructure). Preserve verbatim.
           return { kind: 'array-method', method: e.method, object: walk(e.object), args: [], comparator: e.comparator }
         }
+        if (e.method === 'reduce' || e.method === 'reduceRight') {
+          // `ReduceOp` is a structured value referencing its own
+          // paramAcc / paramItem, never the enclosing destructure —
+          // preserve verbatim, same as the sort comparator above.
+          return { kind: 'array-method', method: e.method, object: walk(e.object), args: [], reduceOp: e.reduceOp }
+        }
+        if (e.method === 'flat') {
+          // `flatDepth` is a normalised literal — no destructure refs to
+          // substitute. Preserve verbatim, same as sort / reduce above.
+          return { kind: 'array-method', method: 'flat', object: walk(e.object), args: [], flatDepth: e.flatDepth }
+        }
+        if (e.method === 'flatMap') {
+          // `FlatMapOp` references its own callback param, never the
+          // enclosing destructure — preserve verbatim, like reduce / sort.
+          return { kind: 'array-method', method: 'flatMap', object: walk(e.object), args: [], flatMapOp: e.flatMapOp }
+        }
         return { kind: 'array-method', method: e.method, object: walk(e.object), args: e.args.map(walk) }
       case 'literal':
       case 'unsupported':
@@ -1918,11 +2437,17 @@ function checkSupport(expr: ParsedExpr): SupportResult {
       // This handles the case where the pattern wasn't recognized as higher-order
       if (expr.callee.kind === 'member') {
         const methodName = expr.callee.property
+        // No template lowering → BF101. `UNSUPPORTED_METHOD_REASONS` supplies
+        // a tailored reason for some methods (e.g. `forEach`); the rest get the
+        // generic hint. Both already carry next steps, hence `selfContained`.
         if (UNSUPPORTED_METHODS.has(methodName)) {
           return {
             supported: false,
             level: 'L5_UNSUPPORTED',
-            reason: `Method '${methodName}()' has no template lowering and requires client-side evaluation. Wrap the expression in /* @client */ to defer it to hydration, or pre-compute the value before rendering.`,
+            selfContained: true,
+            reason:
+              UNSUPPORTED_METHOD_REASONS[methodName] ??
+              `'${methodName}()' can't render on the server. Pre-compute the value, or add /* @client */ for client-only (no SSR).`,
           }
         }
       }
@@ -2233,6 +2758,24 @@ export function exprToString(expr: ParsedExpr): string {
         const { paramA, paramB, raw } = expr.comparator
         return `${exprToString(expr.object)}.${expr.method}((${paramA},${paramB}) => ${raw})`
       }
+      if (expr.method === 'reduce' || expr.method === 'reduceRight') {
+        const { paramAcc, paramItem, raw, type, init } = expr.reduceOp
+        // `init` is the decoded value: re-quote a string seed, re-emit a
+        // numeric seed as-is (it's already a valid number literal).
+        const initSrc = type === 'string' ? JSON.stringify(init) : init
+        return `${exprToString(expr.object)}.${expr.method}((${paramAcc},${paramItem}) => ${raw}, ${initSrc})`
+      }
+      if (expr.method === 'flat') {
+        // Preserve the normalised depth so diagnostics don't misleadingly
+        // print `.flat()` for a `.flat(2)` / `.flat(Infinity)` source.
+        const d = expr.flatDepth
+        const depthSrc = d === 'infinity' ? 'Infinity' : String(d)
+        return `${exprToString(expr.object)}.flat(${d === 1 ? '' : depthSrc})`
+      }
+      if (expr.method === 'flatMap') {
+        const { param, raw } = expr.flatMapOp
+        return `${exprToString(expr.object)}.flatMap(${param} => ${raw})`
+      }
       return `${exprToString(expr.object)}.${expr.method}(${expr.args.map(exprToString).join(', ')})`
     case 'unsupported':
       return `[UNSUPPORTED: ${expr.raw}]`
@@ -2295,6 +2838,29 @@ export function stringifyParsedExpr(expr: ParsedExpr): string {
         const { paramA, paramB, raw } = expr.comparator
         return `${stringifyParsedExpr(expr.object)}.${expr.method}((${paramA},${paramB}) => ${raw})`
       }
+      if (expr.method === 'reduce' || expr.method === 'reduceRight') {
+        // Round-trip the user's param names + init so downstream
+        // re-parsers (the CSR / Hono JS path, templatePrimitive
+        // substitution) see valid JS — `raw` references the names
+        // verbatim. `init` is the decoded value: re-quote a string
+        // seed via JSON.stringify, re-emit a numeric seed as-is.
+        const { paramAcc, paramItem, raw, type, init } = expr.reduceOp
+        const initSrc = type === 'string' ? JSON.stringify(init) : init
+        return `${stringifyParsedExpr(expr.object)}.${expr.method}((${paramAcc},${paramItem}) => ${raw}, ${initSrc})`
+      }
+      if (expr.method === 'flat') {
+        // Round-trip the normalised depth back to JS for the CSR / Hono
+        // path: `'infinity'` → `Infinity`, `1` is left implicit (`.flat()`).
+        const d = expr.flatDepth
+        const depthSrc = d === 'infinity' ? 'Infinity' : String(d)
+        return `${stringifyParsedExpr(expr.object)}.flat(${d === 1 ? '' : depthSrc})`
+      }
+      if (expr.method === 'flatMap') {
+        // Round-trip the user's callback param + body so the CSR / Hono
+        // path re-parses valid JS (`raw` references the param verbatim).
+        const { param, raw } = expr.flatMapOp
+        return `${stringifyParsedExpr(expr.object)}.flatMap(${param} => ${raw})`
+      }
       return `${stringifyParsedExpr(expr.object)}.${expr.method}(${expr.args.map(stringifyParsedExpr).join(', ')})`
     case 'unsupported':
       return expr.raw

package/src/index.ts

@@ -245,7 +245,7 @@ export { ErrorCodes, createError, formatError, generateCodeFrame } from './error
 
 // Expression Parser
 export { parseExpression, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, containsHigherOrder } from './expression-parser'
-export type { ParsedExpr, ParsedStatement, SortComparator, SortKey, SupportLevel, SupportResult, TemplatePart } from './expression-parser'
+export type { ParsedExpr, ParsedStatement, SortComparator, SortKey, ReduceOp, FlatDepth, FlatMapOp, FlatMapLeaf, SupportLevel, SupportResult, TemplatePart } from './expression-parser'
 export { buildLoopChainExpr } from './loop-chain'
 export type { LoopChainInputs } from './loop-chain'