@barefootjs/blade 0.1.0

package/src/adapter/boolean-result.ts

@@ -0,0 +1,168 @@
+/**
+ * Structural classifier for JS expressions whose result is a boolean value
+ * (or unambiguously stringifies to "true"/"false" in JS).
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/boolean-result.ts`
+ * (itself ported from the Xslate/Mojo adapters' `bf->bool_str` classifier).
+ * Used by the Blade adapter for TWO purposes:
+ *
+ * 1. **Attribute/text stringification**: route a boolean-shaped reactive
+ *    binding through the runtime `bf.bool_str` helper so the serialised
+ *    value matches JS `String(boolean)` ("true"/"false"). PHP has a real
+ *    `bool` type, but PHP's own `(string) true` == `"1"` (not `"true"`) and
+ *    `(string) false` == `""` — still wrong for HTML output — so the same
+ *    explicit routing is required.
+ * 2. **Condition-position truthy wrapping**: PHP truthiness diverges from JS
+ *    specifically on the string `'0'` (falsy in PHP, truthy in JS) and empty
+ *    arrays (`[]` — JS objects/arrays are unconditionally truthy; a PHP
+ *    empty array is falsy). The Blade adapter's condition-emission call sites
+ *    (see `blade-adapter.ts`'s `convertConditionToBlade`) reuse this SAME
+ *    structural classifier: a condition that is already unambiguously
+ *    boolean-shaped emits directly; everything else is wrapped in
+ *    `bf.truthy(...)` (a JS-faithful `ToBoolean`) before being used as an
+ *    `{% if %}` / ternary test.
+ *
+ * The classifier walks a `ParsedExpr` produced by
+ * `@barefootjs/jsx::parseExpression` — same AST the filter / loop lowerings
+ * already use — so detection is structural rather than regex-text-matching.
+ * Wrapped expression text is left to the caller's existing
+ * `convertExpressionToBlade` pipeline; this module only decides whether to
+ * wrap.
+ *
+ * Detected shapes:
+ *   - `binary` with a comparison operator (`<`, `>`, `<=`, `>=`, `==`, `===`,
+ *     `!=`, `!==`)
+ *   - `unary` with logical `!`
+ *   - `literal` with `literalType: 'boolean'`
+ *   - `logical` (`&&` / `||` / `??`) when both sides are themselves
+ *     boolean-result (catches `x > 0 && y < 10`; intentionally does NOT
+ *     catch `x() || 'fallback'` whose right side stringifies as a regular
+ *     value)
+ *   - `conditional` (`?:`) when both branches are themselves boolean-result
+ *
+ * Anything else returns `false` — including bare identifiers (`accepted`)
+ * and call expressions (`accepted()`) whose return type the adapter has no
+ * way to infer from source text alone.
+ */
+
+import { parseExpression, type ParsedExpr } from '@barefootjs/jsx'
+
+const COMPARISON_OPS = new Set([
+  '<',
+  '>',
+  '<=',
+  '>=',
+  '==',
+  '===',
+  '!=',
+  '!==',
+])
+
+/**
+ * Structural boolean-result check over an already-parsed `ParsedExpr` tree.
+ * Exported so the condition-position truthy-wrapping call sites can reuse it
+ * without a stringify → re-parse round-trip.
+ */
+export function isBooleanResultParsed(node: ParsedExpr): boolean {
+  switch (node.kind) {
+    case 'literal':
+      return node.literalType === 'boolean'
+    case 'binary':
+      return COMPARISON_OPS.has(node.op)
+    case 'unary':
+      return node.op === '!'
+    case 'logical':
+      // `x > 0 && y < 10` is boolean; `x() || 'fallback'` is not.
+      // Only both-sides-boolean qualifies.
+      return (
+        isBooleanResultParsed(node.left) && isBooleanResultParsed(node.right)
+      )
+    case 'conditional':
+      // `cond ? bool : bool` is boolean; `cond ? 'a' : 'b'` is not.
+      return (
+        isBooleanResultParsed(node.consequent) &&
+        isBooleanResultParsed(node.alternate)
+      )
+    default:
+      return false
+  }
+}
+
+export function isBooleanResultExpr(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  if (!parsed) return false
+  return isBooleanResultParsed(parsed)
+}
+
+/**
+ * True when `expr`'s top-level shape is an explicit JS `String(x)` call
+ * (the `EVAL_BUILTIN_IDENTS` builtin the compiler recognizes structurally —
+ * `packages/jsx/src/expression-parser.ts`'s `EVAL_BUILTIN_IDENTS`; lowered
+ * by this adapter's `String` template primitive to `bf.string(x)`, see
+ * `lib/constants.ts`).
+ *
+ * Guards the `isAriaBooleanAttr`-driven `bf.bool_str(...)` override in
+ * `blade-adapter.ts`'s `elementAttrEmitter`: `bf.string` and `bf.bool_str`
+ * produce IDENTICAL text for a real PHP `bool` (both are `"true"` /
+ * `"false"`), so applying `bf.bool_str` to `String(x)`'s ALREADY-STRINGIFIED
+ * result is not a no-op — it is a PHP-truthiness test over that STRING
+ * ("false" is a non-empty PHP string, hence truthy, so
+ * `bf.bool_str(bf.string(false))` would wrongly render `"true"`). An author
+ * who explicitly writes `String(...)` has already opted into JS `String()`
+ * semantics — `bf.string(x)` alone (which DOES special-case booleans, see
+ * the PHP runtime's `string()` helper) is the complete, correct lowering; no
+ * attribute-name-driven override should run again on top of it.
+ */
+export function isExplicitStringCall(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  return (
+    !!parsed &&
+    parsed.kind === 'call' &&
+    parsed.callee.kind === 'identifier' &&
+    parsed.callee.name === 'String' &&
+    parsed.args.length === 1
+  )
+}
+
+/**
+ * ARIA attributes whose spec values are `"true"`, `"false"`, and (for
+ * tri-state members) `"mixed"`. When a fixture binds one of these to an
+ * arbitrary JS expression (`aria-checked={accepted()}`), the expression's
+ * actual type isn't recoverable from source text — but the attribute name
+ * itself witnesses that the binding is boolean-shaped. Routing these through
+ * `bf.bool_str` produces the spec-canonical `"true"` / `"false"` even when
+ * the expression is opaque.
+ *
+ * Deliberately conservative — only includes ARIA attributes whose spec value
+ * set is exactly `true | false` or `true | false | mixed`. Tokenised ARIA
+ * attributes (`aria-current` is `page | step | …`, `aria-sort` is
+ * `ascending | descending | …`) are intentionally excluded so a
+ * string-valued binding doesn't get coerced to `"true"` / `"false"`.
+ */
+const ARIA_BOOLEAN_ATTRS = new Set([
+  // Strict boolean state (true | false; some allow `undefined` = attribute
+  // absent, which the runtime emits as no-attr regardless).
+  'aria-atomic',
+  'aria-busy',
+  'aria-disabled',
+  'aria-hidden',
+  'aria-modal',
+  'aria-multiline',
+  'aria-multiselectable',
+  'aria-readonly',
+  'aria-required',
+  // true | false | undefined (absent) — selection / disclosure state.
+  'aria-selected',
+  'aria-expanded',
+  // Tri-state (true | false | mixed). The `bool_str` helper only maps
+  // truthy / falsy to true / false — a fixture that wants the literal
+  // "mixed" would bind a string-valued JSX attr (`aria-checked="mixed"`),
+  // which lowers through the `literal` emit path and never touches this
+  // code.
+  'aria-checked',
+  'aria-pressed',
+])
+
+export function isAriaBooleanAttr(name: string): boolean {
+  return ARIA_BOOLEAN_ATTRS.has(name)
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,117 @@
+/**
+ * The contract the extracted expression-emitter modules depend on instead of
+ * the concrete `BladeAdapter`.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/emit-context.ts`. The Blade
+ * adapter's top-level expression lowering is mutually recursive with the
+ * adapter's own const/record resolution and its filter-predicate emitter, so
+ * the extracted `BladeTopLevelEmitter` still needs to call back into shared
+ * per-compile state and recursive entry points. `BladeEmitContext` is that
+ * seam: the emitter takes a `BladeEmitContext` built by the adapter's private
+ * `emitCtx` getter (the adapter does NOT `implements` this interface, so the
+ * wrapped members stay private and off its exported public type). The
+ * emitter depends on this narrow interface rather than the full class, so
+ * the coupling is explicit and it's unit-testable against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling
+ * rather than re-exposing the whole adapter.
+ */
+
+import type { ParsedExpr, CompilerError, IRMetadata } from '@barefootjs/jsx'
+
+export interface BladeEmitContext {
+  /**
+   * (#1922) Local binding names the request-scoped `searchParams()` env signal
+   * is imported under. Non-empty enables the env-signal method-call lowering.
+   */
+  readonly _searchParamsLocals: Set<string>
+
+  /**
+   * Inline a module-scope pure string-literal const by name as the resolved
+   * literal value, or null when the name is not such a const.
+   */
+  _resolveModuleStringConst(name: string): string | null
+
+  /** Resolve a literal const (`const totalPages = 5`) to its Blade value, or null. */
+  _resolveLiteralConst(name: string): string | null
+
+  /**
+   * Resolve a static property access on a module object-literal const
+   * (`variantClasses.ghost`) to its Blade value at compile time, or null.
+   */
+  _resolveStaticRecordLiteral(objectName: string, key: string): string | null
+
+  /** Record a BF101 unsupported-expression diagnostic. */
+  _recordExprBF101(message: string, reason?: string): void
+
+  /** Lower a filter/predicate body to its Blade form, bound to `param`. */
+  _renderBladeFilterExprPublic(expr: ParsedExpr, param: string): string
+}
+
+/**
+ * The contract the extracted object-literal / conditional-spread lowering
+ * (`spread/spread-codegen.ts`) depends on. Declared separately from
+ * `BladeEmitContext` so each extracted module's real coupling is documented
+ * precisely. Mirror of the Jinja adapter's `JinjaSpreadContext`.
+ */
+export interface BladeSpreadContext {
+  /** Component name, for diagnostic source locations. */
+  readonly componentName: string
+
+  /** Per-compile diagnostic list the spread lowering appends to. */
+  readonly errors: CompilerError[]
+
+  /** Local-constant metadata, for resolving `Record[key]` spread values. */
+  readonly localConstants: IRMetadata['localConstants']
+
+  /** Prop params, for classifying a bare-identifier index as a prop. */
+  readonly propsParams: { name: string }[]
+
+  /**
+   * Lower a JS expression to its Blade form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr`. With `preParsed` set, `expr` is unused for parsing
+   * (the converter derives any diagnostic text from the tree), so callers
+   * may pass `''`.
+   */
+  convertExpressionToBlade(expr: string, preParsed?: ParsedExpr): string
+
+  /**
+   * Lower a JS expression to a Blade CONDITION (routes through `bf.truthy`
+   * unless the expression is structurally already boolean-shaped — see
+   * `boolean-result.ts`). Used for the conditional-spread ternary's test,
+   * which is a condition position, not a value position. Same `preParsed`
+   * contract as `convertExpressionToBlade`.
+   */
+  convertConditionToBlade(expr: string, preParsed?: ParsedExpr): string
+}
+
+/**
+ * The contract the extracted in-template memo / context seeding
+ * (`memo/seed.ts`) depends on. The seed lowering recurses into the core
+ * expression lowering to compute a derived signal/memo value or a context
+ * default; that recursive entry is its only adapter coupling.
+ */
+export interface BladeMemoContext {
+  /**
+   * Lower a JS expression to its Blade form (the core recursive entry). See
+   * `BladeSpreadContext.convertExpressionToBlade` for the `preParsed` contract.
+   */
+  convertExpressionToBlade(expr: string, preParsed?: ParsedExpr): string
+
+  /**
+   * Per-compile diagnostic list `convertExpressionToBlade` appends to on an
+   * unsupported shape (`_recordExprBF101`). `memo/seed.ts`'s
+   * `generateDerivedMemoSeed` is a SPECULATIVE "try this in-template
+   * recomputation, else fall back to the static ssrDefault seed" attempt per
+   * plan step — unlike every other `convertExpressionToBlade` call site, a
+   * failure here must NOT become a hard compile error, so it snapshots this
+   * array's length before calling in and truncates back to it on failure
+   * (discarding whatever `_recordExprBF101` appended) rather than letting
+   * the error escape.
+   */
+  readonly errors: CompilerError[]
+}

package/src/adapter/expr/array-method.ts

@@ -0,0 +1,345 @@
+/**
+ * Array / string method lowering for the Blade template adapter.
+ *
+ * Ported from `packages/adapter-jinja/src/adapter/expr/array-method.ts`.
+ * Pure free functions shared by both the filter-context emitter and the
+ * top-level emitter — they take an `emit` callback for receiver / argument
+ * recursion and read no adapter instance state.
+ *
+ * The receiver/array helpers are the same runtime methods the Jinja adapter
+ * calls, invoked as `$bf->NAME(...)`.
+ */
+
+import {
+  serializeParsedExpr,
+  freeVarsInBody,
+} from '@barefootjs/jsx'
+import type {
+  ParsedExpr,
+  ArrayMethod,
+  SortComparator,
+  FlatDepth,
+} from '@barefootjs/jsx'
+import { escapeBladeSingleQuoted, bladeHashKey } from '../lib/blade-naming.ts'
+
+export function renderArrayMethod(
+  method: ArrayMethod,
+  object: ParsedExpr,
+  args: ParsedExpr[],
+  emit: (e: ParsedExpr) => string,
+): string {
+  switch (method) {
+    case 'join': {
+      // Route through the runtime (`$bf->join`) rather than a Blade builtin, so
+      // the JS-compat element handling (undef → empty, default separator) is
+      // applied consistently.
+      const obj = emit(object)
+      const sep = args.length >= 1 ? emit(args[0]) : `','`
+      return `$bf->join(${obj}, ${sep})`
+    }
+    case 'includes': {
+      const obj = emit(object)
+      const needle = emit(args[0])
+      return `$bf->includes(${obj}, ${needle})`
+    }
+    case 'indexOf':
+    case 'lastIndexOf': {
+      const fn = method === 'indexOf' ? 'index_of' : 'last_index_of'
+      const obj = emit(object)
+      const needle = emit(args[0])
+      return `$bf->${fn}(${obj}, ${needle})`
+    }
+    case 'at': {
+      const obj = emit(object)
+      const idx = args.length >= 1 ? emit(args[0]) : '0'
+      return `$bf->at(${obj}, ${idx})`
+    }
+    case 'concat': {
+      if (args.length === 0) {
+        return emit(object)
+      }
+      const a = emit(object)
+      const b = emit(args[0])
+      return `$bf->concat(${a}, ${b})`
+    }
+    case 'slice': {
+      const recv = emit(object)
+      const start = args.length >= 1 ? emit(args[0]) : '0'
+      // Blade's undefined-literal is `null`, not Kolon's `nil` or Jinja's
+      // `none` — the runtime `slice` treats it as "to end".
+      const end = args.length >= 2 ? emit(args[1]) : 'null'
+      return `$bf->slice(${recv}, ${start}, ${end})`
+    }
+    case 'reverse':
+    case 'toReversed': {
+      const recv = emit(object)
+      return `$bf->reverse(${recv})`
+    }
+    case 'toLowerCase': {
+      // Route through the runtime (consistent with bf.includes / bf.slice /
+      // etc.) rather than a bare `|lower` filter, so a non-string operand
+      // still gets JS-compatible coercion first.
+      const recv = emit(object)
+      return `$bf->lc(${recv})`
+    }
+    case 'toUpperCase': {
+      const recv = emit(object)
+      return `$bf->uc(${recv})`
+    }
+    case 'trim': {
+      const recv = emit(object)
+      return `$bf->trim(${recv})`
+    }
+    case 'toFixed': {
+      // `.toFixed(digits?)` — `$bf->to_fixed` mirrors JS rounding +
+      // zero-padding (default 0 digits). #1897.
+      const recv = emit(object)
+      const digits = args.length >= 1 ? emit(args[0]) : '0'
+      return `$bf->to_fixed(${recv}, ${digits})`
+    }
+    case 'split': {
+      const recv = emit(object)
+      if (args.length === 0) {
+        return `$bf->split(${recv})`
+      }
+      const sep = emit(args[0])
+      if (args.length === 1) {
+        return `$bf->split(${recv}, ${sep})`
+      }
+      const limit = emit(args[1])
+      return `$bf->split(${recv}, ${sep}, ${limit})`
+    }
+    case 'startsWith':
+    case 'endsWith': {
+      const fn = method === 'startsWith' ? 'starts_with' : 'ends_with'
+      const recv = emit(object)
+      const arg = emit(args[0])
+      if (args.length >= 2) {
+        return `$bf->${fn}(${recv}, ${arg}, ${emit(args[1])})`
+      }
+      return `$bf->${fn}(${recv}, ${arg})`
+    }
+    case 'replace': {
+      const recv = emit(object)
+      const oldS = emit(args[0])
+      const newS = emit(args[1])
+      return `$bf->replace(${recv}, ${oldS}, ${newS})`
+    }
+    case 'repeat': {
+      const recv = emit(object)
+      const count = args.length === 0 ? '0' : emit(args[0])
+      return `$bf->repeat(${recv}, ${count})`
+    }
+    case 'padStart':
+    case 'padEnd': {
+      const fn = method === 'padStart' ? 'pad_start' : 'pad_end'
+      const recv = emit(object)
+      if (args.length === 0) {
+        return `$bf->${fn}(${recv}, 0)`
+      }
+      const target = emit(args[0])
+      if (args.length === 1) {
+        return `$bf->${fn}(${recv}, ${target})`
+      }
+      const pad = emit(args[1])
+      return `$bf->${fn}(${recv}, ${target}, ${pad})`
+    }
+    default: {
+      // TS-level exhaustiveness guard.
+      const _exhaustive: never = method
+      throw new Error(
+        `renderArrayMethod: unhandled ArrayMethod '${(_exhaustive as string)}'`,
+      )
+    }
+  }
+}
+
+/**
+ * Build the `base_env` PHP-array argument for an evaluator call: the
+ * comparator / reducer body's free variables (body idents minus the
+ * callback params), each materialised to its SSR value via `emit`. An
+ * empty capture set yields `[]` — the runtime's seed-once env.
+ */
+function emitEvalEnvArg(
+  body: ParsedExpr,
+  params: string[],
+  emit: (e: ParsedExpr) => string,
+): string {
+  const free = freeVarsInBody(body, new Set(params))
+  if (free.length === 0) return '[]'
+  const pairs = free.map(
+    n => `${bladeHashKey(n)} => ${emit({ kind: 'identifier', name: n })}`,
+  )
+  return `[${pairs.join(', ')}]`
+}
+
+/**
+ * Emit a `.sort(cmp)` / `.toSorted(cmp)` via the runtime evaluator (#2018):
+ * the comparator body travels as serialized-ParsedExpr JSON, evaluated per
+ * comparison against `{paramA, paramB, …captured}`. Returns null when the
+ * body is outside the evaluator surface (e.g. a `localeCompare` comparator —
+ * `serializeParsedExpr` refuses it), so the caller falls back to the
+ * structured `$bf->sort`. `params` are the comparator arrow's two params
+ * (`[paramA, paramB]`).
+ */
+export function renderSortEval(
+  recv: string,
+  body: ParsedExpr,
+  params: string[],
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  // A comparator needs both params; a wrong-arity arrow would emit an
+  // 'undefined' param name, so fail over to the structured fallback / BF101
+  // (mirrors the Go / Jinja guards).
+  if (params.length < 2) return null
+  const [paramA, paramB] = params
+  const env = emitEvalEnvArg(body, params, emit)
+  return `$bf->sort_eval(${recv}, '${escapeBladeSingleQuoted(json)}', '${paramA}', '${paramB}', ${env})`
+}
+
+/**
+ * Emit a `.reduce(fn, init)` / `.reduceRight(fn, init)` via the runtime
+ * evaluator (#2018): the reducer body travels as serialized-ParsedExpr JSON,
+ * folded over the receiver from `init` in `direction` order. `params` are the
+ * reducer arrow's params (`[paramAcc, paramItem]`); `init` is the initial-value
+ * `ParsedExpr` from the call's trailing argument. Returns null when the body is
+ * outside the evaluator surface, or when `init` is not a literal string/number
+ * (→ caller refuses with BF101). A numeric seed passes through as a bare
+ * Blade number; a string seed as a single-quoted literal.
+ */
+export function renderReduceEval(
+  recv: string,
+  body: ParsedExpr,
+  params: string[],
+  init: ParsedExpr,
+  direction: 'left' | 'right',
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  if (init.kind !== 'literal') return null
+  const initOut =
+    init.literalType === 'string'
+      ? `'${escapeBladeSingleQuoted(String(init.value))}'`
+      : init.literalType === 'number'
+        ? String(init.value)
+        : null
+  if (initOut === null) return null
+  // A reducer needs both the accumulator and element param; refuse a
+  // wrong-arity arrow cleanly (→ BF101) rather than emitting an 'undefined'
+  // param name (mirrors the Go / Jinja guards).
+  if (params.length < 2) return null
+  const [paramAcc, paramItem] = params
+  const env = emitEvalEnvArg(body, params, emit)
+  return `$bf->reduce_eval(${recv}, '${escapeBladeSingleQuoted(json)}', '${paramAcc}', '${paramItem}', ${initOut}, '${direction}', ${env})`
+}
+
+/**
+ * Emit a higher-order predicate call via the runtime evaluator (#2018, P2):
+ * `$bf->filter_eval` / `$bf->every_eval` / `$bf->some_eval` / `$bf->find_eval` /
+ * `$bf->find_index_eval`, carrying the serialized predicate body + captured env
+ * dict. Generalizes the lambda lowering to the same JS-faithful evaluator
+ * the Go/Jinja adapters use. Returns null when the predicate is outside the
+ * evaluator surface (e.g. a method-call predicate — `serializeParsedExpr`
+ * refuses it), so the caller falls back to the lambda form. `forward`
+ * (find / findIndex family only) selects the search direction — `false` =
+ * findLast / findLastIndex.
+ */
+export function renderPredicateEval(
+  funcName: string,
+  recv: string,
+  predicate: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+  forward?: boolean,
+): string | null {
+  const json = serializeParsedExpr(predicate)
+  if (json === null) return null
+  const env = emitEvalEnvArg(predicate, [param], emit)
+  const fwd = forward === undefined ? '' : `, ${forward ? 'true' : 'false'}`
+  return `$bf->${funcName}(${recv}, '${escapeBladeSingleQuoted(json)}', '${param}'${fwd}, ${env})`
+}
+
+/**
+ * Emit a `.flatMap(proj)` via the runtime evaluator (#2018, P3): the projection
+ * body serializes to JSON and `$bf->flat_map_eval` projects + flattens one
+ * level. `param` is the projection arrow's single param. Returns null when the
+ * projection is outside the evaluator surface (→ caller refuses with BF101).
+ */
+export function renderFlatMapEval(
+  recv: string,
+  body: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  const env = emitEvalEnvArg(body, [param], emit)
+  return `$bf->flat_map_eval(${recv}, '${escapeBladeSingleQuoted(json)}', '${param}', ${env})`
+}
+
+/**
+ * Emit a value-producing `.map(cb)` via the runtime evaluator (#2073): the
+ * projection body serializes to JSON and `$bf->map_eval` projects each element,
+ * one result per element (no flatten — the JS `.map` contract). Composes
+ * through the array-method chain (`.map(cb).join(' ')`). Returns null when
+ * the projection is outside the evaluator surface (→ caller refuses with
+ * BF101). The JSX-returning `.map` is an IRLoop upstream and never reaches
+ * this emit.
+ */
+export function renderMapEval(
+  recv: string,
+  body: ParsedExpr,
+  param: string,
+  emit: (e: ParsedExpr) => string,
+): string | null {
+  const json = serializeParsedExpr(body)
+  if (json === null) return null
+  const env = emitEvalEnvArg(body, [param], emit)
+  return `$bf->map_eval(${recv}, '${escapeBladeSingleQuoted(json)}', '${param}', ${env})`
+}
+
+/**
+ * Shared Blade emit for `.sort(cmp)` / `.toSorted(cmp)`. Used by both the
+ * filter-context emitter and the top-level emitter, plus the loop-array
+ * wrap in `renderLoop`. The runtime `$bf->sort` accepts an opts dict and
+ * returns a fresh list.
+ */
+export function renderSortMethod(recv: string, c: SortComparator): string {
+  const keyDicts = c.keys.map((k) => {
+    const keyEntry =
+      k.key.kind === 'self'
+        ? `'key_kind' => 'self'`
+        : `'key_kind' => 'field', 'key' => '${k.key.field}'`
+    return `[${keyEntry}, 'compare_type' => '${k.type}', 'direction' => '${k.direction}']`
+  })
+  return `$bf->sort(${recv}, ['keys' => [${keyDicts.join(', ')}]])`
+}
+
+// `.flat(depth?)` → `$bf->flat(recv, depth)`.
+export function renderFlatMethod(
+  recv: string,
+  depth: FlatDepth | { expr: ParsedExpr },
+  emit: (e: ParsedExpr) => string,
+): string {
+  if (typeof depth === 'object') {
+    // Dynamic depth (#2094): routed to a distinct runtime helper,
+    // `$bf->flat_dynamic`, rather than reusing `$bf->flat`. The literal-depth
+    // path (`$bf->flat`) bakes `-1` in as a compile-time SENTINEL meaning "the
+    // source literally said `Infinity`". A genuinely dynamic depth value
+    // that happens to evaluate to `-1` at render time means the OPPOSITE in
+    // real JS (`[1,[2]].flat(-1)` never recurses — same as `.flat(0)`).
+    // Since both paths would otherwise hand the same literal-looking `-1`
+    // argument to one shared function, that function cannot tell which case
+    // it's in — so it must be two different runtime entry points.
+    // `$bf->flat_dynamic` performs the JS `ToIntegerOrInfinity` coercion on its
+    // second argument at render time (truncate toward zero; negative → 0;
+    // NaN/non-numeric → 0; +Infinity or a huge finite value → flatten
+    // fully) before delegating to the same recursive flattening as `flat`.
+    return `$bf->flat_dynamic(${recv}, ${emit(depth.expr)})`
+  }
+  const d = depth === 'infinity' ? -1 : depth
+  return `$bf->flat(${recv}, ${d})`
+}