@barefootjs/jsx 0.5.3 → 0.6.1

package/src/expression-parser.ts

@@ -46,6 +46,13 @@ export type ParsedExpr =
         | 'toLowerCase'
         | 'toUpperCase'
         | 'trim'
+        | 'split'
+        | 'startsWith'
+        | 'endsWith'
+        | 'replace'
+        | 'repeat'
+        | 'padStart'
+        | 'padEnd'
       object: ParsedExpr
       args: ParsedExpr[]
     }
@@ -66,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 }
 
 /**
@@ -125,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 }
@@ -159,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
@@ -181,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/.
@@ -225,12 +391,60 @@ const UNSUPPORTED_METHODS = new Set([
   // unsupported array methods above get), pointing users at the
   // `/* @client */` escape hatch. Each name drops off as its lowering
   // lands. See #1448 "Unsupported string methods" Tier B / Tier C.
-  'split', 'startsWith', 'endsWith', 'replace', 'replaceAll',
-  'repeat', 'padStart', 'padEnd',
+  // `split` is no longer here — `String.prototype.split(sep)` lowers
+  // via the `array-method` IR + `bf_split` (Go) / `bf->split` (Mojo),
+  // returning an array that composes with `.join()` / `.map()` / etc.
+  // See #1448 Tier B.
+  // `startsWith` / `endsWith` are no longer here — both lower via the
+  // `array-method` IR + `bf_starts_with` / `bf_ends_with` (Go) and
+  // `bf->starts_with` / `bf->ends_with` (Mojo). See #1448 Tier B.
+  // `replace` is no longer here — the string-pattern form lowers via
+  // the `array-method` IR + `bf_replace` (Go) / `bf->replace` (Mojo);
+  // the regex-pattern form is refused at the parse arm below (it would
+  // need the per-adapter regex-flavour decision). `replaceAll` stays
+  // refused. See #1448 Tier B.
+  // `repeat` is no longer here — `String.prototype.repeat(n)` lowers via
+  // the `array-method` IR + `bf_repeat` (Go) / `bf->repeat` (Mojo).
+  // See #1448 Tier B.
+  // `padStart` / `padEnd` are no longer here — both lower via the
+  // `array-method` IR + `bf_pad_start` / `bf_pad_end` (Go) and
+  // `bf->pad_start` / `bf->pad_end` (Mojo). See #1448 Tier B.
+  'replaceAll',
   'charAt', 'charCodeAt', 'codePointAt', 'normalize',
   '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
+// additional arrays of a variadic `.concat(a, b, …)`. The relaxed
+// per-method arms in `convertNode` accept every method's zero-arg
+// defaults (`.join()` / `.slice()` / `.concat()` / `.at()`) and
+// JS-ignored trailing arguments; this guard catches only the remaining
+// meaningful-extra forms, refusing them with BF101 because silently
+// dropping the argument would make the SSR output differ from the
+// client. See #1448.
+const LOWERED_ARRAY_METHODS = new Set([
+  'includes',
+  'indexOf',
+  'lastIndexOf',
+  'concat',
+])
+
 // =============================================================================
 // Expression Parser
 // =============================================================================
@@ -344,7 +558,10 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
     // etc. later means widening the IR discriminator, not adding more
     // branches to every adapter's call dispatch.
     if (callee.kind === 'member' && !callee.computed) {
-      if (callee.property === 'join' && args.length === 1) {
+      // `.join()` / `.join(sep)` — JS defaults the separator to `,` when
+      // omitted and ignores any extra arguments. Accept every arity; the
+      // adapters supply the default separator and read only `args[0]`.
+      if (callee.property === 'join') {
         return { kind: 'array-method', method: 'join', object: callee.object, args }
       }
       // `.includes(x)` — shared between `Array.prototype.includes` and
@@ -369,20 +586,28 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // element). Go has `bf_at` registered already (see runtime
       // FuncMap); Mojo's `bf->at` wraps the same arithmetic.
       // See #1448 Tier A.
-      if (callee.property === 'at' && args.length === 1) {
+      // `.at(i)` — JS ignores any argument past the first, and `.at()`
+      // with no argument is `.at(0)` (the first element). Accept every
+      // arity; the adapters read `args[0]` (defaulting the index to 0).
+      if (callee.property === 'at') {
         return { kind: 'array-method', method: 'at', object: callee.object, args }
       }
-      // `.concat(other)` — merges two arrays in order. Go uses
-      // `bf_concat` (reflect-based append into `[]any`); Mojo uses
-      // `bf->concat` (Perl list builder). Variadic shapes (`.concat(a, b)`)
-      // are out of scope for this PR — gated to single-arg here.
-      if (callee.property === 'concat' && args.length === 1) {
+      // `.concat()` / `.concat(other)` — `.concat()` returns a shallow
+      // copy (indistinguishable from the receiver in an SSR snapshot),
+      // and `.concat(other)` merges the two arrays. Go uses `bf_concat`
+      // (reflect-based append into `[]any`); Mojo uses `bf->concat`
+      // (Perl list builder). The VARIADIC form (`.concat(a, b, …)`) is
+      // not lowered yet — it's refused by the guard below rather than
+      // silently dropping the extra arrays.
+      if (callee.property === 'concat' && args.length <= 1) {
         return { kind: 'array-method', method: 'concat', object: callee.object, args }
       }
-      // `.slice(start)` / `.slice(start, end)` — both forms route
-      // through `bf_slice` (Go) / `bf->slice` (Mojo); the helpers
-      // treat a missing / undef `end` as "to length".
-      if (callee.property === 'slice' && (args.length === 1 || args.length === 2)) {
+      // `.slice()` / `.slice(start)` / `.slice(start, end)` — route
+      // through `bf_slice` (Go) / `bf->slice` (Mojo). A missing `start`
+      // defaults to 0 (full copy), a missing / undef `end` means "to
+      // length", and JS ignores any third+ argument. Accept every arity;
+      // the adapters read only `args[0]` / `args[1]`.
+      if (callee.property === 'slice') {
         return { kind: 'array-method', method: 'slice', object: callee.object, args }
       }
       // `.reverse()` and `.toReversed()` — both zero-arg shapes
@@ -390,28 +615,198 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
       // of state, so JS's mutate-and-return-receiver (`reverse`)
       // vs return-new-array (`toReversed`) distinction has no
       // template-level meaning; both produce a new reversed array.
-      if ((callee.property === 'reverse' || callee.property === 'toReversed') && args.length === 0) {
+      // JS takes no argument and ignores any that are passed.
+      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
       // pipeline matches). Go uses the existing `bf_lower` helper;
       // Mojo uses Perl's native `lc`. See #1448 Tier A.
-      if (callee.property === 'toLowerCase' && args.length === 0) {
+      if (callee.property === 'toLowerCase') {
         return { kind: 'array-method', method: 'toLowerCase', object: callee.object, args }
       }
       // `.toUpperCase()` — Go uses the existing `bf_upper` helper;
       // Mojo uses Perl's native `uc`.
-      if (callee.property === 'toUpperCase' && args.length === 0) {
+      if (callee.property === 'toUpperCase') {
         return { kind: 'array-method', method: 'toUpperCase', object: callee.object, args }
       }
       // `.trim()` — Go uses the existing `bf_trim` helper; Mojo uses
       // a new `bf->trim` method that mirrors JS's "strip leading +
       // trailing whitespace" semantic via a Perl regex.
-      if (callee.property === 'trim' && args.length === 0) {
+      if (callee.property === 'trim') {
         return { kind: 'array-method', method: 'trim', 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
+      // (literal) separator; the optional `limit` caps the number of
+      // pieces. JS ignores a third+ argument. Go uses `bf_split`
+      // (`strings.Split`, optional limit, normalised to `[]any`) and
+      // `bf_arr` for the no-separator whole-string case; Mojo uses
+      // `bf->split`. The regex-separator form stays refused (the parser
+      // never reaches here for it — a regex literal arg is `unsupported`
+      // and propagates). See #1448 Tier B.
+      if (callee.property === 'split') {
+        return { kind: 'array-method', method: 'split', object: callee.object, args }
+      }
+      // Arity guard for the forms whose EXTRA argument changes the
+      // result and is not yet lowered: the `fromIndex` of `.includes` /
+      // `.indexOf` / `.lastIndexOf` (the 2-arg form), and the additional
+      // arrays of a variadic `.concat(a, b, …)`. Silently dropping those
+      // would make the SSR output *differ* from the client (worse than a
+      // build error), so they refuse with BF101 until lowered. (The
+      // single-argument forms, zero-arg defaults, and JS-ignored
+      // trailing arguments of every method are accepted by the relaxed
+      // arms above.) See #1448.
+      if (LOWERED_ARRAY_METHODS.has(callee.property)) {
+        const argName = callee.property === 'concat' ? 'other' : 'x'
+        const detail =
+          callee.property === 'concat'
+            ? 'the variadic `.concat(a, b, …)` form'
+            : `\`.${callee.property}(…)\` with ${args.length} argument(s)`
+        return {
+          kind: 'unsupported',
+          raw,
+          reason: `${detail} is not yet lowered to the Go/Mojo template adapters. Use the single-argument \`.${callee.property}(${argName})\` form, or pre-compute the value before the template.`,
+        }
+      }
+      // `.startsWith(search, position?)` / `.endsWith(search, endPosition?)`
+      // — string → boolean, full JS arity. Go uses `bf_starts_with` /
+      // `bf_ends_with` (wrapping `strings.HasPrefix` / `strings.HasSuffix`,
+      // with an optional position that re-anchors the comparison); Mojo
+      // uses `bf->starts_with` / `bf->ends_with` (substr comparison). JS
+      // ignores a third+ argument. The zero-arg form (`.startsWith()`) is
+      // refused: JS coerces the missing search to the literal string
+      // "undefined", a degenerate result not worth lowering (mirrors the
+      // `.includes()` zero-arg refusal). See #1448 Tier B.
+      if (callee.property === 'startsWith' || callee.property === 'endsWith') {
+        if (args.length === 0) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason: `\`.${callee.property}()\` with no search string is not lowered — JS coerces the missing argument to the string "undefined", a degenerate result. Pass an explicit search string, or pre-compute the value before the template.`,
+          }
+        }
+        return { kind: 'array-method', method: callee.property, object: callee.object, args }
+      }
+      // `.replace(pattern, replacement)` — string-pattern form,
+      // replacing the FIRST occurrence (JS semantics for a string
+      // pattern). Go uses `bf_replace` (`strings.Replace` with n=1);
+      // Mojo uses `bf->replace` (index/substr splice, no regex). A
+      // regex-literal pattern parses as `unsupported` (convertNode has
+      // no regex arm), so it's refused explicitly here rather than
+      // emitting a broken `.Replace` — the Perl `s///` vs Go
+      // `regexp.ReplaceAllString` flavour gap is the open design
+      // question in #1448. `replaceAll` stays refused entirely.
+      //
+      // Full JS arity: a third+ argument is ignored (the adapter reads
+      // only the pattern + replacement). The one- and zero-argument
+      // forms are refused: JS coerces the missing replacement (and
+      // pattern) to the literal string "undefined", a degenerate result
+      // (mirrors the `.includes()` / `.startsWith()` zero-arg refusal).
+      if (callee.property === 'replace') {
+        if (args.length < 2) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason: `\`.replace(${args.length === 0 ? '' : 'pattern'})\` needs both a pattern and a replacement — JS coerces the missing argument to the string "undefined", a degenerate result. Pass both arguments, or pre-compute the value before the template.`,
+          }
+        }
+        // A regex-literal pattern is the deferred form (the Perl `s///`
+        // vs Go `regexp.ReplaceAllString` flavour gap, #1448) — detect it
+        // on the TS node so the message is accurate. Any OTHER unsupported
+        // pattern/replacement (an object literal, an unsupported call, …)
+        // surfaces ITS OWN reason rather than being mislabelled as the
+        // regex form.
+        const patternNode = node.arguments[0]
+        if (patternNode && ts.isRegularExpressionLiteral(patternNode)) {
+          return {
+            kind: 'unsupported',
+            raw,
+            reason:
+              'String.prototype.replace supports only a string pattern + string replacement (the regex form is deferred); use a string pattern or wrap the expression in /* @client */',
+          }
+        }
+        const badArg =
+          args[0].kind === 'unsupported'
+            ? args[0]
+            : args[1].kind === 'unsupported'
+              ? args[1]
+              : undefined
+        if (badArg && badArg.kind === 'unsupported') {
+          return { kind: 'unsupported', raw, reason: badArg.reason }
+        }
+        return { kind: 'array-method', method: 'replace', object: callee.object, args }
+      }
+      // `.repeat(n)` — string → string (the receiver concatenated `n`
+      // times). Go uses `bf_repeat` (`strings.Repeat`, clamping a
+      // negative count to "" instead of panicking); Mojo uses
+      // `bf->repeat` (Perl's `x` operator). JS throws RangeError for a
+      // negative count, but SSR templates degrade to the empty string
+      // rather than crashing the render. See #1448 Tier B.
+      // Full JS arity: `.repeat()` (no count) is `repeat(0)` → "" (JS
+      // coerces the missing count to 0, not a RangeError), and a
+      // second+ argument is ignored. The adapter supplies the `0` for
+      // the no-argument form. See #1448 Tier B.
+      if (callee.property === 'repeat') {
+        return { kind: 'array-method', method: 'repeat', object: callee.object, args }
+      }
+      // `.padStart(target, pad?)` / `.padEnd(target, pad?)` — string →
+      // string, padded to `target` length with `pad` (default a single
+      // space) repeated + truncated to fill. Go uses `bf_pad_start` /
+      // `bf_pad_end`; Mojo uses `bf->pad_start` / `bf->pad_end`. Both
+      // count length in code points (Go runes / Perl chars) so they
+      // stay byte-equal — this differs from JS's UTF-16-unit length
+      // only for astral-plane receivers, which are vanishingly rare in
+      // numeric / space padding. See #1448 Tier B.
+      // Full JS arity: `.padStart()` (no target) is `padStart(0)` → the
+      // receiver unchanged (JS coerces the missing target to 0), and a
+      // third+ argument is ignored. The adapter supplies the `0` for the
+      // no-argument form and reads only target + padString.
+      if (callee.property === 'padStart' || callee.property === 'padEnd') {
+        return { kind: 'array-method', method: callee.property, object: callee.object, args }
+      }
       // `.sort(cmp)` / `.toSorted(cmp)` (#1448 Tier B). The comparator
       // is extracted into a structured `SortComparator` at parse time;
       // unrecognised shapes fall through to `unsupported` so adapters
@@ -450,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 }
@@ -1036,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
@@ -1584,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':
@@ -1735,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).`,
           }
         }
       }
@@ -2050,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}]`
@@ -2112,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