@barefootjs/jsx 0.17.0 → 0.18.0

package/src/__tests__/tagged-template-interleave.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Tagged-template interleave-tag desugaring (#2092, Refs #2069).
+ *
+ * The classname-tag idiom:
+ *
+ *   function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+ *     return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+ *   }
+ *   className={cn`base ${tone()}`}
+ *
+ * Before #2092 the compiler treated `cn\`...\`` as an opaque scalar leaf: a
+ * `TaggedTemplateExpression` falls through `expression-parser.ts` as
+ * `unsupported`, and every non-JS template adapter refused it with BF101.
+ *
+ * #2092 resolves the tag identifier one hop through same-file scope (reusing
+ * #2090's `findLocalConst` / `findLocalFunction`), structurally proves the
+ * resolved function matches the "interleave tag" catalogue (see
+ * `isInterleaveTagFunction` in `jsx-to-ir.ts`), and — only then — REWRITES
+ * the whole tagged template to the equivalent untagged template literal
+ * (`\`base \${(tone()) ?? ''}\``) before the rest of the compiler ever sees
+ * it. Everything else (dep analysis, template-literal parts, adapter emit,
+ * client-JS binding) runs unchanged against the rewritten node.
+ *
+ * These tests exercise the recognizer directly against the IR (so assertions
+ * don't depend on any one adapter's output formatting) via `analyzeComponent`
+ * + `jsxToIR`, matching `ir-sort-comparator.test.ts`'s style for the sibling
+ * #2090 feature.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { analyzeComponent } from '../analyzer'
+import { jsxToIR } from '../jsx-to-ir'
+import type { IRElement, ExpressionAttr } from '../types'
+
+/** Compile `source` and return the root element's `className` attribute
+ *  value from the IR (the IR keeps the JSX name `className`; adapters
+ *  render it as `class` later). */
+function classAttrValue(source: string, filename = 'TagDemo.tsx') {
+  const ctx = analyzeComponent(source, filename)
+  const ir = jsxToIR(ctx)
+  expect(ir).not.toBeNull()
+  expect(ir!.type).toBe('element')
+  const el = ir as IRElement
+  const attr = el.attrs.find(a => a.name === 'className')
+  expect(attr).toBeDefined()
+  return attr!.value
+}
+
+describe('tagged-template interleave-tag recognition (#2092)', () => {
+  test('recognized cn`base ${tone()}` desugars to the untagged template literal', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone, setTone] = createSignal('primary')
+        return <div onClick={() => setTone('secondary')} className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    const expr = (value as ExpressionAttr).expr
+    // The tag call is gone — replaced by the equivalent untagged template
+    // literal, each span wrapped in `(span) ?? ''`.
+    expect(expr).not.toMatch(/\bcn`/)
+    expect(expr).toBe("`base ${(tone()) ?? ''}`")
+  })
+
+  test('const-bound arrow interleave tag also resolves (findLocalConst path)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      const cn = (parts: TemplateStringsArray, ...args: unknown[]): string =>
+        parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      export function TagDemo() {
+        const [tone, setTone] = createSignal('primary')
+        return <div onClick={() => setTone('secondary')} className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toBe("`base ${(tone()) ?? ''}`")
+  })
+
+  test('String(...)-wrapped span still matches the catalogue', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + String(args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toBe("`base ${(tone()) ?? ''}`")
+  })
+
+  test('no-substitution template (no interpolation) desugars cleanly', () => {
+    const source = `
+      'use client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        return <div className={cn\`base\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    // No spans at all — the rewrite produces a plain
+    // NoSubstitutionTemplateLiteral, not an "expression" carrying a call.
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toBe('`base`')
+    expect((value as ExpressionAttr).expr).not.toMatch(/\bcn`/)
+  })
+
+  test('escaped backtick / literal ${...} / backslash chunk survives the rewrite verbatim', () => {
+    // Chunk raw text (as written in source): `pre\` mid \${lit} end\\stop `
+    // — a literal backtick, a literal (non-substituting) `${lit}`, and a
+    // literal backslash, followed by the ONE real span `${tone()}`.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={cn\`pre\\\` mid \\\${lit} end\\\\stop \${tone()} post\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    const expr = (value as ExpressionAttr).expr
+    // The escape sequences (backtick, `${`, backslash) must survive
+    // byte-for-byte in the rewritten source — using the COOKED text
+    // instead of `rawText` would either mis-parse the reconstructed
+    // template or silently turn `${lit}` into a real (broken) substitution.
+    expect(expr).toBe("`pre\\` mid \\${lit} end\\\\stop ${(tone()) ?? ''} post`")
+  })
+
+  test('imported tag identifier is NOT resolved — left untouched (today\'s BF101 path)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { cn } from './cn-helper'
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    // Unresolved (no same-file binding) — the tag call is preserved verbatim.
+    expect((value as ExpressionAttr).expr).toContain('cn`base')
+  })
+
+  test('cross-kind name collision (const + function binding) is NOT resolved', () => {
+    // Same ambiguity rule as resolveSortComparatorIdentifier (#2091 review):
+    // a name bound both as a const and as a `function` declaration can only
+    // occur across scopes, and FunctionInfo carries emission placement (not
+    // lexical position), so resolution refuses rather than guessing which
+    // tag the call site actually sees. The node stays opaque (BF101 path).
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        const cn = (parts: TemplateStringsArray, ...args: unknown[]) =>
+          parts.reduce<string>((acc, p, i) => acc + p + '-' + (args[i] ?? ''), '')
+        return <div className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toContain('cn`base')
+  })
+
+  test('off-catalogue body (joins with a separator) is NOT recognized', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + '-' + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toContain('cn`base')
+  })
+
+  test('computed tag (member expression) is NOT recognized', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      const helpers = {
+        cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+          return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+        },
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={helpers.cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    // Not even an Identifier tag — the recognizer only matches a bare
+    // identifier tag (`tryDesugarInterleaveTaggedTemplate` requires
+    // `ts.isIdentifier(expr.tag)`), so a computed tag is never attempted.
+    expect((value as ExpressionAttr).expr).toContain('helpers.cn`base')
+  })
+
+  test('non-rest second parameter is NOT recognized', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone] = createSignal('primary')
+        return <div className={cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const value = classAttrValue(source)
+    expect(value.kind).toBe('expression')
+    expect((value as ExpressionAttr).expr).toContain('cn`base')
+  })
+
+  test('/* @client */ still defers a recognized interleave tag to the client', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function cn(parts: TemplateStringsArray, ...args: unknown[]): string {
+        return parts.reduce<string>((acc, p, i) => acc + p + (args[i] ?? ''), '')
+      }
+      export function TagDemo() {
+        const [tone, setTone] = createSignal('primary')
+        return <div onClick={() => setTone('secondary')} className={/* @client */ cn\`base \${tone()}\`}>x</div>
+      }
+    `
+    const ctx = analyzeComponent(source, 'TagDemo.tsx')
+    const ir = jsxToIR(ctx)
+    expect(ir).not.toBeNull()
+    const el = ir as IRElement
+    const attr = el.attrs.find(a => a.name === 'className')
+    expect(attr).toBeDefined()
+    // The desugar still applies (the client-only directive doesn't block
+    // recognition — it's read independently from the original node), and
+    // the attribute is still flagged clientOnly so it defers to hydrate.
+    expect(attr!.clientOnly).toBe(true)
+    expect(attr!.value.kind).toBe('expression')
+    expect((attr!.value as ExpressionAttr).expr).toBe("`base ${(tone()) ?? ''}`")
+  })
+})

package/src/__tests__/unsupported-expression.test.ts

@@ -136,12 +136,14 @@ describe('Unsupported Expression Error (BF021)', () => {
 })
 
 describe('Unsupported Sort Comparator (BF021)', () => {
-  test('emits BF021 for function-reference comparator — outside accepted catalogue', () => {
+  test('function-reference comparator resolves through scope — no BF021 (#2090)', () => {
     // #1448 Tier B follow-up widened the catalogue to include
     // multi-key (`a.x - b.x || a.y - b.y`), relational ternary, and
-    // single-`return` block bodies. Function-reference comparators
-    // (`arr.sort(cmp)` where `cmp` is a named function) are still out
-    // of scope — they need scope resolution and refuse here.
+    // single-`return` block bodies. #2090 closes the remaining gap:
+    // a bare identifier callback (`arr.sort(cmp)`) is now resolved
+    // through the analyzer's scope machinery (one hop, same-file
+    // only) to the const-bound arrow, then fed through the same
+    // catalogue as an inline comparator.
     const source = `
       'use client'
       import { createSignal } from '@barefootjs/client'
@@ -152,7 +154,73 @@ describe('Unsupported Sort Comparator (BF021)', () => {
         return (
           <ul>
             {items().sort(cmp).map(t => (
-              <li>{t.name}</li>
+              <li key={t.name}>{t.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { ir, errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(0)
+    expect(ir).not.toBeNull()
+    if (ir!.type === 'element') {
+      const loop = ir!.children.find(c => c.type === 'loop')
+      expect(loop).toBeDefined()
+      if (loop?.type === 'loop') {
+        expect(loop.sortComparator).toBeDefined()
+        expect(loop.sortComparator!.raw).toBe('a.priority - b.priority')
+      }
+    }
+  })
+
+  test('function-declaration comparator reference resolves — no BF021 (#2090)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      function cmp(a, b) { return a.priority - b.priority }
+
+      export function TodoList() {
+        const [items, setItems] = createSignal<any[]>([])
+        return (
+          <ul>
+            {items().toSorted(cmp).map(t => (
+              <li key={t.name}>{t.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { ir, errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(0)
+    expect(ir).not.toBeNull()
+    if (ir!.type === 'element') {
+      const loop = ir!.children.find(c => c.type === 'loop')
+      if (loop?.type === 'loop') {
+        expect(loop.sortComparator).toBeDefined()
+        expect(loop.sortComparator!.raw).toBe('a.priority - b.priority')
+      }
+    }
+  })
+
+  test('identifier resolving to a non-function const emits BF021 (#2090)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function TodoList() {
+        const [items, setItems] = createSignal<any[]>([])
+        const cmp = 5
+        return (
+          <ul>
+            {items().sort(cmp).map(t => (
+              <li key={t.name}>{t.name}</li>
             ))}
           </ul>
         )
@@ -163,16 +231,135 @@ describe('Unsupported Sort Comparator (BF021)', () => {
     const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
 
     expect(bf021).toHaveLength(1)
+    expect(bf021[0].message).toContain('could not be resolved')
   })
 
-  test('@client suppresses BF021 for unsupported sort comparator', () => {
+  test('cross-kind shadowing (component const over module function) emits BF021, not the shadowed function (#2090)', () => {
+    // A name bound both as a const and as a `function` declaration can
+    // only happen across scopes, and FunctionInfo does not carry lexical
+    // scope (component-body functions are hoisted for client emission).
+    // Resolution refuses the ambiguity rather than guessing — pre-fix
+    // this wrongly compiled against the shadowed module function
+    // (Copilot review on #2091).
     const source = `
       'use client'
       import { createSignal } from '@barefootjs/client'
 
+      function cmp(a, b) { return a.priority - b.priority }
+
+      export function TodoList() {
+        const [items, setItems] = createSignal<any[]>([])
+        const cmp = 5
+        return (
+          <ul>
+            {items().sort(cmp).map(t => (
+              <li key={t.name}>{t.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(1)
+    expect(bf021[0].message).toContain('could not be resolved')
+  })
+
+  test('cross-kind shadowing (component function over module const) also refuses with BF021 (#2090)', () => {
+    // The safe half of the same ambiguity: JS would use the component
+    // function here, but resolution cannot prove which binding the call
+    // site sees, so it refuses loudly instead of risking the WRONG
+    // (opposite-direction) comparator.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      const byPrice = (a, b) => a.price - b.price
+
+      export function ProductList() {
+        const [products, setProducts] = createSignal<any[]>([])
+        function byPrice(a, b) { return b.price - a.price }
+        return (
+          <ul>
+            {products().sort(byPrice).map(p => (
+              <li key={p.name}>{p.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(1)
+    expect(bf021[0].message).toContain('could not be resolved')
+  })
+
+  test('unresolved (imported) identifier comparator emits BF021 (#2090)', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { cmp } from './cmp'
+
+      export function TodoList() {
+        const [items, setItems] = createSignal<any[]>([])
+        return (
+          <ul>
+            {items().sort(cmp).map(t => (
+              <li key={t.name}>{t.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(1)
+    expect(bf021[0].message).toContain('could not be resolved')
+  })
+
+  test('resolved-but-off-catalogue comparator body emits BF021 naming the comparator (#2090)', () => {
+    // `a.deep.x - b.deep.x` has operand depth > 1 — `classifySortOperand`
+    // only accepts the param itself or a single-level field access, so this
+    // stays refused even once the identifier resolves to the arrow.
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+
+      export function TodoList() {
+        const [items, setItems] = createSignal<any[]>([])
+        const cmp = (a, b) => a.deep.x - b.deep.x
+        return (
+          <ul>
+            {items().sort(cmp).map(t => (
+              <li key={t.name}>{t.name}</li>
+            ))}
+          </ul>
+        )
+      }
+    `
+
+    const { errors } = compileToIR(source)
+    const bf021 = errors.filter(e => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+
+    expect(bf021).toHaveLength(1)
+    expect(bf021[0].message).toContain("'cmp'")
+    expect(bf021[0].message).toContain('not a supported shape')
+  })
+
+  test('@client suppresses BF021 for an unresolved sort comparator identifier', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { cmp } from './cmp'
+
       export function TodoList() {
         const [items, setItems] = createSignal<any[]>([])
-        const cmp = (a, b) => a.priority - b.priority
         return (
           <ul>
             {/* @client */ items().sort(cmp).map(t => (

package/src/adapters/env-signal.ts

@@ -22,28 +22,76 @@ export const ENV_SIGNAL_CLIENT_FACTORY: Record<string, string> = {
 }
 
 /**
- * The getter name(s) of the `searchParams` env signal in this component.
+ * One env signal's SSR-reader surface — the single place a future env signal
+ * registers itself so the adapter seed / memo paths stay open-closed:
+ * registering a new env signal is an analyzer factory entry + one registry
+ * entry here; adapter seed/memo paths consume the registry and need no edits.
+ */
+export interface EnvSignalReader {
+  /** The analyzer's `envReader` key (`'search'`). */
+  key: string
+  /**
+   * Canonical per-request reader binding every adapter's lowering
+   * canonicalises to (`searchParams` → Perl `$searchParams`, Go
+   * `in.SearchParams` via capitalisation).
+   */
+  canonicalName: string
+  /** Reader method names the SSR lowerings recognise (`.get(key)`). */
+  methods: ReadonlySet<string>
+}
+
+/**
+ * Env-signal key → its {@link EnvSignalReader} descriptor. The open-closed
+ * contract: adding a new env signal is an analyzer factory entry
+ * (`ENV_SIGNAL_FACTORIES`, #2057) + one entry here — the adapter seed / memo
+ * paths consume this registry (via {@link envSignalReaderFor} /
+ * {@link envSignalLocalNames}) and need no edits.
+ */
+export const ENV_SIGNAL_READERS: ReadonlyMap<string, EnvSignalReader> = new Map([
+  ['search', { key: 'search', canonicalName: 'searchParams', methods: new Set(['get']) }],
+])
+
+/** Look up an env signal's reader descriptor by its `envReader` key, or `null` when unregistered/absent. */
+export function envSignalReaderFor(key: string | undefined): EnvSignalReader | null {
+  if (key === undefined) return null
+  return ENV_SIGNAL_READERS.get(key) ?? null
+}
+
+/**
+ * The getter name(s) of env signal(s) in this component, optionally filtered
+ * to one `envReader` key.
  *
- * Recognised **structurally** (#2057): the env signal is now declared as a
+ * Recognised **structurally** (#2057): an env signal is declared as a
  * `createSignal`-shaped `const [searchParams, setSearchParams] =
  * createSearchParams()`, so the analyzer collects it into `metadata.signals`
- * with `envReader: 'search'` — exactly like any other signal, but tagged. This
+ * with `envReader: '<key>'` — exactly like any other signal, but tagged. This
  * function returns those getters (whatever the destructured name is —
  * `searchParams`, or an alias), so adapters match the reader `.get()` call
- * against the binding actually used, with **no `searchParams`-name allow-list**
- * (this supersedes the import-name matching, and the closed #2055).
+ * against the binding actually used, with **no name allow-list** (this
+ * supersedes the import-name matching, and the closed #2055).
  *
- * Empty when the component declares no env signal (the component keeps the
- * generic signal lowering).
+ * With `key` omitted, collects every env signal's getters regardless of
+ * which reader they belong to; with `key` given, only that reader's
+ * (`searchParamsLocalNames` is the `'search'`-filtered convenience below).
+ *
+ * Empty when the component declares no matching env signal (the component
+ * keeps the generic signal lowering).
  */
-export function searchParamsLocalNames(metadata: IRMetadata): Set<string> {
+export function envSignalLocalNames(metadata: IRMetadata, key?: string): Set<string> {
   const names = new Set<string>()
   for (const s of metadata.signals) {
-    if (s.envReader === 'search') names.add(s.getter)
+    if (s.envReader !== undefined && (key === undefined || s.envReader === key)) {
+      names.add(s.getter)
+    }
   }
   return names
 }
 
+/** The getter name(s) of the `searchParams` env signal in this component. See {@link envSignalLocalNames}. */
+export function searchParamsLocalNames(metadata: IRMetadata): Set<string> {
+  return envSignalLocalNames(metadata, 'search')
+}
+
 /**
  * True when the component declares the `searchParams` env signal. Convenience
  * for adapters/harnesses that only need to gate on presence (the lowering

package/src/adapters/interface.ts

@@ -96,9 +96,23 @@ export type TemplatePrimitiveEmit = (args: string[]) => string
  * Keys are the textual callee path as it appears in the JSX expression
  * (`JSON.stringify`, `Math.floor`, `String`).
  *
- * V1 scope: identifier-path callees only. Method calls on values whose type
- * the analyzer must resolve (`props.name.toUpperCase()`) are out of scope —
- * see #1187 R1. Users can fall back to `/* @client *\/` for those.
+ * V1 scope (#1187): identifier-path callees only, and only names the adapter
+ * knows about AHEAD OF TIME — this map is fixed at adapter-construction
+ * time, so it can never contain a name from a component's own (unknown in
+ * advance) imports. Method calls on values whose type the analyzer must
+ * resolve (`props.name.toUpperCase()`) are ALSO out of scope — see #1187 R1.
+ * Users can fall back to `/* @client *\/` for either limitation.
+ *
+ * V2 (#2069) does not widen this map — it adds a separate, orthogonal
+ * acceptance path instead: `RelocateEnv.loweringMatchers`, bound once per
+ * component from the global `LoweringPlugin` registry
+ * (`prepareLoweringMatchers`, `packages/jsx/src/lowering-registry.ts`). A
+ * plugin's `prepare(metadata)` resolves the component's ACTUAL import list,
+ * so it can recognise a call this string-keyed map structurally never could
+ * (a bespoke user import, unknown until compile time). `templatePrimitives`
+ * remains the right home for well-known JS builtins (`JSON.stringify`,
+ * `Math.floor`) that every component might reasonably use, with no import
+ * to key a plugin against.
  */
 export type TemplatePrimitiveRegistry = Record<string, TemplatePrimitiveEmit>
 
@@ -110,7 +124,9 @@ export type TemplatePrimitiveRegistry = Record<string, TemplatePrimitiveEmit>
  *
  * Adapters whose template runtime can't execute arbitrary JS (Go, Perl,
  * other server-side template languages) should leave this undefined and
- * rely on the explicit `templatePrimitives` map alone.
+ * rely on the explicit `templatePrimitives` map alone (plus, since #2069,
+ * whatever `LoweringPlugin`s are registered — see `TemplatePrimitiveRegistry`
+ * above).
  */
 export type TemplateCallAcceptor = (calleeName: string) => boolean
 

package/src/adapters/parsed-expr-emitter.ts

@@ -177,9 +177,22 @@ export interface ParsedExprEmitter {
   // a structured `FlatDepth` (the validated literal / `'infinity'`) rather
   // than a `ParsedExpr[]` args list. Non-callback, so it is NOT routed
   // through `callbackMethod`.
+  //
+  // `depth` is `FlatDepth` for the literal path (unchanged: adapters keep
+  // their existing `bf_flat`-family emit exactly as before) or
+  // `{ expr: ParsedExpr }` for a DYNAMIC depth (#2094) — an adapter renders
+  // `expr` with the `emit` callback and passes the result to a SEPARATE
+  // runtime helper that coerces it at render time (JS `ToIntegerOrInfinity`;
+  // see the `depthExpr` doc on `ParsedExpr`'s `array-method`/`flat` variant
+  // for why this must NOT be the same helper as the literal path — the
+  // literal path's `-1` sentinel means "flatten fully", but a genuinely
+  // dynamic `-1` means the opposite per JS). Every adapter emits its
+  // `flat_dynamic`-family helper for the dynamic form, and every runtime
+  // implements the coercion; parity is pinned by the `flat_dynamic`
+  // golden helper vectors.
   flatMethod(
     object: ParsedExpr,
-    depth: FlatDepth,
+    depth: FlatDepth | { expr: ParsedExpr },
     emit: (e: ParsedExpr) => string,
   ): string
   unsupported(raw: string, reason: string): string
@@ -232,7 +245,11 @@ export function emitParsedExpr(expr: ParsedExpr, emitter: ParsedExprEmitter): st
       return emitter.objectLiteral(expr.properties, expr.raw, emit)
     case 'array-method':
       if (expr.method === 'flat') {
-        return emitter.flatMethod(expr.object, expr.flatDepth, emit)
+        return emitter.flatMethod(
+          expr.object,
+          expr.depthExpr ? { expr: expr.depthExpr } : expr.flatDepth,
+          emit,
+        )
       }
       return emitter.arrayMethod(expr.method, expr.object, expr.args, emit)
     case 'unsupported':