@barefootjs/go-template 0.15.2 → 0.17.0

package/src/__tests__/go-template-adapter.test.ts

@@ -42,12 +42,15 @@ runAdapterConformanceTests({
   // `TemplateFuncMap`). Shapes the adapter intentionally refuses at
   // build time are pinned in `expectedDiagnostics` below.
   //
-  // `data-table` is the one remaining #1896 gap: its table body is a
-  // keyed `.map` over a `/* @client */`-sorted MEMO whose data is a
-  // module-const object array — a memo-derived dynamic loop of imported
-  // components, which the nested-component slice constructor can't bake
-  // yet (`item.ID` is on the loop datum, not the child's Input). Full
-  // coverage remains at the Hono SSR + fixture-hydrate layers.
+  // `data-table` — the last #1896 holdout — now renders to Hono byte
+  // parity on real Go and is fully un-skipped (run in CI). Its table
+  // body is a keyed `.map` over a `/* @client */`-sorted MEMO whose
+  // data is a module-const object array (a memo-derived dynamic loop of
+  // imported components); the nested-component slice constructor bakes
+  // it via loop-body children companion defines, a wrapper struct +
+  // constructor, and block-body memo folding (#1897). On Go it is
+  // un-skipped everywhere — including `skipMarkerConformance` below,
+  // since the SSR template emits the slot ids the IR declares.
   //
   // `search-params` (router v0.5) now renders on Go: `logical()` parenthesises
   // its multi-token operands so `searchParams().get(k) ?? d` lowers to
@@ -223,8 +226,9 @@ describe('GoTemplateAdapter - searchParams() env-signal lowering (#1922)', () =>
   test('lowers searchParams().get(k) to .SearchParams.Get and emits the struct binding', () => {
     const adapter = new GoTemplateAdapter()
     const ir = compileToIR(`
-import { searchParams } from '@barefootjs/client'
+import { createSearchParams } from '@barefootjs/client'
 export function SortLabel() {
+  const [searchParams] = createSearchParams()
   return <p>{searchParams().get('sort') ?? 'none'}</p>
 }
 `, adapter)
@@ -234,14 +238,15 @@ export function SortLabel() {
     expect(types).toContain('SearchParams: in.SearchParams')
   })
 
-  // An aliased import binds the env signal to a different local name; the
-  // call `sp()` still resolves to the canonical `.SearchParams` field (the
-  // generated struct field name is fixed, not derived from the JS alias).
-  test('aliased import (`searchParams as sp`) resolves sp() to canonical .SearchParams', () => {
+  // An aliased destructured getter binds the env signal to a different local
+  // name; the call `sp()` still resolves to the canonical `.SearchParams` field
+  // (the generated struct field name is fixed, not derived from the JS name).
+  test('aliased env-signal getter (`const [sp] = createSearchParams()`) resolves sp() to canonical .SearchParams', () => {
     const adapter = new GoTemplateAdapter()
     const ir = compileToIR(`
-import { searchParams as sp } from '@barefootjs/client'
+import { createSearchParams } from '@barefootjs/client'
 export function SortLabel() {
+  const [sp] = createSearchParams()
   return <p>{sp().get('sort') ?? 'none'}</p>
 }
 `, adapter)
@@ -264,8 +269,9 @@ describe('GoTemplateAdapter - template-literal text lowering (#1933)', () => {
     const adapter = new GoTemplateAdapter()
     const ir = compileToIR(`
 'use client'
-import { createMemo, searchParams } from '@barefootjs/client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
 export function StatusLine() {
+  const [searchParams] = createSearchParams()
   const tag = createMemo(() => searchParams().get('tag') ?? '')
   return (
     <div className="status">
@@ -732,6 +738,28 @@ export function Tags() {
       )
     })
 
+    test('bakes a numeric scalar array from the carried tree (Roadmap A-3)', () => {
+      // The analyzer carries `SignalInfo.parsed`, so the scalar-array bake
+      // reads the structured tree (`parsedLiteralToGo`) instead of re-parsing
+      // the value string with `ts.createSourceFile`. Each numeric element uses
+      // the carried raw token (= `NumericLiteral.text`), so the bake matches
+      // the fallback byte-for-byte — including TS's `.text` normalisation of
+      // `1e3` → `1000` and `0x10` → `16`.
+      const adapter = new GoTemplateAdapter()
+      const ir = compileToIR(`
+"use client"
+import { createSignal } from "@barefootjs/client"
+
+export function Nums() {
+  const [ns] = createSignal<number[]>([1, 2, 1e3, 0x10])
+  return <ul>{ns().map((n) => <li key={n}>{n}</li>)}</ul>
+}
+`)
+      expect(adapter.generate(ir).types!).toContain(
+        'Ns: []int{1, 2, 1000, 16},',
+      )
+    })
+
     test('synthesises a struct for an untyped object array and bakes it (#1680)', () => {
       // An untyped object array has no element type to bake against. Rather
       // than leave it nil (empty SSR loop), infer a struct from the literal's
@@ -1712,7 +1740,9 @@ export function TodoStatus() {
   return <div>{todos().every(t => t.done)}</div>
 }
 `)
-      expect(result.template).toContain('bf_every .Todos "Done"')
+      // #2018 P2: `.every(t => t.done)` now lowers through the evaluator —
+      // the predicate body travels as serialized ParsedExpr JSON.
+      expect(result.template).toContain('bf_every_eval .Todos')
     })
 
     test('nested .filter(...).length in filter predicate lowers via len (bf_filter ...) (#1443 PR4)', () => {
@@ -1742,7 +1772,7 @@ export function TodoList() {
 }
 `, adapter)
       expect(result.errors?.filter(e => e.code === 'BF101') ?? []).toEqual([])
-      expect(result.template).toContain('gt (len (bf_filter .Tags "Active" true)) 0')
+      expect(result.template).toContain('gt (len (bf_filter_eval .Tags')
       // No degenerate fallbacks
       expect(result.template).not.toContain('{{if false}}')
       expect(result.template).not.toContain('[UNSUPPORTED-FILTER-EXPR]')
@@ -1773,7 +1803,7 @@ export function TodoList() {
   )
 }
 `, adapter)
-      expect(result.template).toContain('gt (len (bf_filter .Tags "Active" true)) 0')
+      expect(result.template).toContain('gt (len (bf_filter_eval .Tags')
       expect(result.template).toContain('{{if not .Done}}')
     })
 
@@ -1834,7 +1864,10 @@ export function ItemChecker() {
   return <div>{items().find(t => t.done) ? 'Found' : 'Not found'}</div>
 }
 `)
-      expect(result.template).toContain('bf_find .Items "Done" true')
+      // #2018 P2: `.find(t => t.done)` lowers through the evaluator; the
+      // trailing `true` is the forward-search flag (find / findIndex).
+      expect(result.template).toContain('bf_find_eval .Items')
+      expect(result.template).toContain('true bf_env')
       expect(result.template).toContain('Found')
     })
   })
@@ -1852,7 +1885,10 @@ export function ItemChecker() {
   return <div>{items().findLast(t => t.done) ? 'Found' : 'Not found'}</div>
 }
 `)
-      expect(result.template).toContain('bf_find_last .Items "Done" true')
+      // #2018 P2: `.findLast(t => t.done)` shares `bf_find_eval` with `.find`,
+      // distinguished by the `false` (backward) forward-flag.
+      expect(result.template).toContain('bf_find_eval .Items')
+      expect(result.template).toContain('false bf_env')
       expect(result.template).toContain('Found')
     })
 
@@ -1886,10 +1922,20 @@ export function ItemChecker() {
   return <div>idx: {items().findLastIndex(t => t.done)}</div>
 }
 `)
-      expect(result.template).toContain('bf_find_last_index .Items "Done" true')
-    })
-
-    test('renders findLastIndex() with complex predicate via range', () => {
+      // #2018 P2: `.findLastIndex` lowers via `bf_find_index_eval` with the
+      // `false` (backward) forward-flag.
+      expect(result.template).toContain('bf_find_index_eval .Items')
+      expect(result.template).toContain('false bf_env')
+    })
+
+    test('renders findLastIndex() with a pure complex predicate via the evaluator', () => {
+      // #2018 P2: a pure (call-free) complex predicate like
+      // `t.price > 50 && t.active` is no longer confined to the
+      // field-equality catalogue — it serializes to a ParsedExpr and lowers
+      // through `bf_find_index_eval` (backward `false` flag), replacing the
+      // old `{{range}}` $bf_r accumulator. The range fallback is now reserved
+      // for predicates the evaluator can't model (e.g. a signal-getter call,
+      // covered by the findLast test above).
       const result = compileAndGenerate(`
 "use client"
 import { createSignal } from "@barefootjs/client"
@@ -1901,10 +1947,9 @@ export function ItemFinder() {
   return <div>{items().findLastIndex(t => t.price > 50 && t.active)}</div>
 }
 `)
-      const varMatch = result.template.match(/(\$bf_r\d+) := -1/)
-      expect(varMatch).not.toBeNull()
-      expect(result.template).toContain(`${varMatch![1]} = $i`)
-      expect(result.template).not.toContain('{{break}}')
+      expect(result.template).toContain('bf_find_index_eval .Items')
+      expect(result.template).toContain('false bf_env')
+      expect(result.template).not.toContain('$bf_r')
     })
 
     test('findLast() complex predicate in IR-level ternary works via preamble splitting', () => {
@@ -2425,7 +2470,9 @@ export function C() {
   return <ul>{items().filter(({done}) => done).map(t => <li key={t.id}>{t.name}</li>)}</ul>
 }`)
       expect(result.errors?.filter(e => e.code === 'BF101') ?? []).toEqual([])
-      expect(result.template).toContain('bf_filter .Items "Done" true')
+      // #2018 P2: the normalised `_t => _t.done` predicate lowers through the
+      // evaluator (`bf_filter_eval`).
+      expect(result.template).toContain('bf_filter_eval .Items')
     })
 
     test('.filter(function (x) { return x.done }).map(...) lowers cleanly', () => {
@@ -2438,7 +2485,9 @@ export function C() {
   return <ul>{items().filter(function (x) { return x.done }).map(t => <li key={t.id}>{t.name}</li>)}</ul>
 }`)
       expect(result.errors?.filter(e => e.code === 'BF101') ?? []).toEqual([])
-      expect(result.template).toContain('bf_filter .Items "Done" true')
+      // #2018 P2: the normalised `_t => _t.done` predicate lowers through the
+      // evaluator (`bf_filter_eval`).
+      expect(result.template).toContain('bf_filter_eval .Items')
     })
   })
 
@@ -2834,19 +2883,23 @@ describe('GoTemplateAdapter - #1448 Tier A/B fixture-driven lowering pins', () =
     // #1448 Tier B — string → string, padded to a target width.
     { fixture: stringPadStartFixture,   expect: 'bf_pad_start .Value 5 "0"' },
     { fixture: stringPadEndFixture,     expect: 'bf_pad_end .Value 5 "."' },
-    // #1448 Tier B — sort / toSorted. Loop-chained shapes wrap the
-    // iterable in `bf_sort .Items <kind> <key> <type> <dir>`;
-    // standalone shapes inline the helper at the call site.
-    { fixture: arraySortFieldAscFixture,  expect: 'bf_sort .Items "field" "Price" "numeric" "asc"' },
-    { fixture: arraySortFieldDescFixture, expect: 'bf_sort .Items "field" "Price" "numeric" "desc"' },
-    { fixture: arraySortPrimitiveFixture, expect: 'bf_sort .Nums "self" "" "numeric" "asc"' },
+    // #1448 Tier B — sort / toSorted. Both the standalone shapes and the
+    // `.sort().map()` loop-hoist now lower through the evaluator (#2018 P1/P3):
+    // the comparator body travels as serialized ParsedExpr to `bf_sort_eval`.
+    { fixture: arraySortFieldAscFixture,  expect: 'bf_sort_eval .Items' },
+    { fixture: arraySortFieldDescFixture, expect: 'bf_sort_eval .Items' },
+    { fixture: arraySortPrimitiveFixture, expect: 'bf_sort_eval .Nums' },
+    // localeCompare can't be evaluated, so it keeps the legacy `bf_sort` path
+    // (both standalone and loop-hoist fall back).
     { fixture: arraySortLocaleFixture,    expect: 'bf_sort .Names "self" "" "string" "asc"' },
-    // Multi-key (`||`-chain): one 4-string group per comparison key,
-    // applied in priority order as tie-breakers.
+    // Multi-key (`||`-chain) here ends in a `localeCompare`, so the whole
+    // comparator falls back to the structured `bf_sort` (one 4-string group
+    // per comparison key, applied in priority order as tie-breakers).
     { fixture: arraySortMultiKeyFixture,  expect: 'bf_sort .Items "field" "Price" "numeric" "asc" "field" "Name" "string" "asc"' },
-    // Relational-ternary comparator lowers to a single `auto` key.
-    { fixture: arraySortTernaryFixture,   expect: 'bf_sort .Items "field" "Rank" "auto" "asc"' },
-    { fixture: arrayToSortedFixture,      expect: 'bf_sort .Nums "self" "" "numeric" "asc"' },
+    // Relational-ternary comparator — a pure body, so it lowers via the
+    // evaluator like the other field sorts.
+    { fixture: arraySortTernaryFixture,   expect: 'bf_sort_eval .Items' },
+    { fixture: arrayToSortedFixture,      expect: 'bf_sort_eval .Nums' },
     // #1448 Tier B — iteration shapes. These are loop-level
     // patterns (range binding order), not helper function calls.
     { fixture: arrayEntriesFixture,       expect: '{{range $i, $v := .Items}}' },
@@ -2891,14 +2944,14 @@ describe('GoTemplateAdapter - #1448 Tier A/B fixture-driven lowering pins', () =
 // now listed in `UNSUPPORTED_METHODS`, so `isSupported` refuses them
 // and `convertExpressionToGo` records BF101 — the same treatment the
 // unsupported array methods already got. These tests pin that parity.
-describe('GoTemplateAdapter - #1448 Tier C reduce field capitalisation', () => {
-  // #1728 review: `bf_reduce`'s projected field name must use the same
-  // initialism-aware capitalisation the adapter applies when generating
-  // struct fields (`capitalizeFieldName`), or the runtime reflect lookup
-  // misses the exported field (`id` → struct `ID`, not `Id`) and folds a
-  // zero value. Pin the emitted key so a regression to plain
-  // first-letter capitalisation fails here.
-  test('reduce over an initialism field emits the Go-initialism key (ID, not Id)', () => {
+describe('GoTemplateAdapter - #2018 reduce via the evaluator', () => {
+  // A standalone `.reduce(fn, init)` now lowers through the evaluator: the
+  // reducer body is serialized to ParsedExpr JSON and folded by `bf_reduce_eval`.
+  // The body carries the JS field name (`x.id`); the runtime field reader
+  // (`getFieldValue`) resolves it case-variantly against the Go struct field
+  // (`ID`) at render time, so no compile-time capitalisation is needed (the
+  // former #1728 initialism gotcha is moot on this path).
+  test('reduce over a field lowers to bf_reduce_eval with the serialized body', () => {
     const adapter = new GoTemplateAdapter()
     const ir = compileToIR(`
 function C({ items }: { items: { id: number }[] }) {
@@ -2907,8 +2960,9 @@ function C({ items }: { items: { id: number }[] }) {
 export { C }
 `, adapter)
     const template = adapter.generate(ir).template ?? ''
-    expect(template).toContain('bf_reduce .Items "+" "field" "ID" "numeric" "0"')
-    expect(template).not.toContain('"Id"')
+    expect(template).toContain('bf_reduce_eval .Items')
+    // The seed is threaded through bf_number; the body is the serialized tree.
+    expect(template).toContain('(bf_number "0")')
   })
 })
 
@@ -2949,20 +3003,32 @@ export { C }
     return adapter.generate(ir).template ?? ''
   }
 
-  test('.flatMap(i => i.field) emits bf_flat_map with the Go-capitalised field', () => {
-    expect(emitFlatMap('rows.flatMap(i => i.tags).join(" ")')).toContain('bf_flat_map .Rows "field" "Tags"')
+  // #2018 P3: `.flatMap(proj)` lowers through the evaluator — the projection
+  // body serializes to ParsedExpr JSON and `bf_flat_map_eval` flattens the
+  // results one level. The raw (lowercase) field name travels in the JSON; the
+  // runtime field reader resolves it case-insensitively against Go data.
+  // (The serialized projection JSON is embedded in a Go-template double-quoted
+  // string — its quotes are backslash-escaped — so these pins assert the helper
+  // + receiver; the projection JSON itself is verified by the render
+  // conformance fixtures + the runtime TestFlatMapEval.)
+  test('.flatMap(i => i.field) emits bf_flat_map_eval', () => {
+    expect(emitFlatMap('rows.flatMap(i => i.tags).join(" ")')).toContain('bf_flat_map_eval .Rows')
   })
 
-  test('.flatMap(i => i) emits the self projection', () => {
-    expect(emitFlatMap('rows.flatMap(i => i).join(" ")')).toContain('bf_flat_map .Rows "self" ""')
+  test('.flatMap(i => i) emits bf_flat_map_eval (self projection)', () => {
+    expect(emitFlatMap('rows.flatMap(i => i).join(" ")')).toContain('bf_flat_map_eval .Rows')
   })
 
-  test('.flatMap(i => [i.a, i.b]) emits bf_flat_map_tuple with capitalised leaves', () => {
-    expect(emitFlatMap('rows.flatMap(i => [i.a, i.b]).join(" ")')).toContain('bf_flat_map_tuple .Rows "field" "A" "field" "B"')
+  test('.flatMap(i => [i.a, i.b]) emits bf_flat_map_eval (array-literal projection)', () => {
+    expect(emitFlatMap('rows.flatMap(i => [i.a, i.b]).join(" ")')).toContain('bf_flat_map_eval .Rows')
   })
 
-  test('tuple self + field leaves', () => {
-    expect(emitFlatMap('rows.flatMap(i => [i, i.a]).join(" ")')).toContain('bf_flat_map_tuple .Rows "self" "" "field" "A"')
+  // (#2018 P5) A tuple with a string-literal element lowers the same way: the
+  // whole array-literal body serializes and `bf_flat_map_eval` evaluates it per
+  // item, so a non-member element no longer refuses (it did under the structured
+  // `bf_flat_map_tuple` catalogue).
+  test('.flatMap(i => [i.name, "x"]) emits bf_flat_map_eval (literal element)', () => {
+    expect(emitFlatMap('rows.flatMap(i => [i.name, "x"]).join(" ")')).toContain('bf_flat_map_eval .Rows')
   })
 })
 
@@ -3016,9 +3082,10 @@ export function C() {
     // the no-initial-value form stays refused — JS throws on an empty
     // array there, which a template can't mirror.
     { name: 'reduce (no init)', expr: `items().reduce((a, b) => a + b.n)`, badEmit: '.Reduce' },
-    // Self / field / field-tuple `.flatMap` now lowers (#1448 Tier C); a
-    // tuple with a non-leaf element (here a string literal) stays refused.
-    { name: 'flatMap (literal element)', expr: `items().flatMap(i => [i.name, "x"])`, badEmit: '.FlatMap' },
+    // (#2018 P5) The literal-element tuple `.flatMap(i => [i.name, "x"])` now
+    // lowers through the evaluator (`bf_flat_map_eval` serializes the array-
+    // literal body and flattens), so it is no longer refused — pinned positively
+    // in the `.flatMap` describe block alongside the `[i.a, i.b]` form.
     // Lowered methods whose MEANINGFUL extra argument isn't lowered yet
     // (#1448): the `fromIndex` of `.includes`/`.indexOf`/`.lastIndexOf`
     // and the variadic `.concat`. The parser refuses these (silently
@@ -3183,3 +3250,87 @@ export function C() {
     }
   })
 })
+
+// =============================================================================
+// #1966 — `/* @client */` defers ATTRIBUTE bindings (not just child/text)
+// =============================================================================
+//
+// Before #1966 the directive was honoured for JSX child/text expressions
+// but silently ignored on attribute initializers: a Go-unsupported
+// predicate in `data-x={/* @client */ pred(x)}` still got lowered, raising
+// BF101/BF102 even though the author had explicitly opted out of SSR. That
+// made the BF102 remediation ("defer it with /* @client */") misleading for
+// attribute-only reactive state (the Calendar case in #1467 / PR #1965).
+//
+// The fix carries the existing `attr.clientOnly` flag (already set in
+// jsx-to-ir, already honoured by the client-JS reactive-attribute path —
+// CSR template omits the attr and a mount effect sets it) through to the
+// adapter: `renderAttributes` skips SSR emission for `clientOnly` attrs, so
+// the unsupported-expression lowering is never reached.
+describe('GoTemplateAdapter - #1966 @client defers attribute bindings', () => {
+  function compileAttr(attrExpr: string) {
+    const adapter = new GoTemplateAdapter()
+    const result = compileJSX(`
+"use client"
+import { createSignal } from "@barefootjs/client"
+export function C() {
+  const [sel] = createSignal(0)
+  const [s] = createSignal("a")
+  const pred = (n: number) => sel() === n
+  return <div data-x={${attrExpr}}>hi</div>
+}
+`.trimStart(), 'test.tsx', { adapter })
+    const template = result.files?.find(f => f.path.endsWith('.tmpl'))?.content ?? ''
+    return { errors: result.errors ?? [], template }
+  }
+
+  test('Go-lowerable predicate: bare emits data-x; @client omits it from SSR', () => {
+    // `sel() === 1` lowers to `{{eq .Sel 1}}`, so the bare form is valid
+    // Go and emits the attribute — the directive is what removes it.
+    const bare = compileAttr('pred(1)')
+    expect(bare.errors).toEqual([])
+    expect(bare.template).toContain('data-x=')
+
+    const deferred = compileAttr('/* @client */ pred(1)')
+    expect(deferred.errors).toEqual([])
+    // Server omits the attribute; the client patches it on hydrate.
+    expect(deferred.template).not.toContain('data-x')
+  })
+
+  test('Go-unsupported predicate: bare raises BF101; @client clears it and omits the attr', () => {
+    const bare = compileAttr('/[0-9]/.test(s())')
+    expect(bare.errors.some(e => e.code === 'BF101' || e.code === 'BF102')).toBe(true)
+
+    const deferred = compileAttr('/* @client */ /[0-9]/.test(s())')
+    // No BF101/BF102 — the lowering is never reached for a deferred attr.
+    expect(deferred.errors).toEqual([])
+    expect(deferred.template).not.toContain('data-x')
+  })
+
+  test('@client attribute inside a keyed .map() loop body is also deferred', () => {
+    const adapter = new GoTemplateAdapter()
+    const result = compileJSX(`
+"use client"
+import { createSignal } from "@barefootjs/client"
+type Day = { n: number }
+export function C() {
+  const [sel] = createSignal(0)
+  const pred = (d: Day) => sel() === d.n
+  const days: Day[] = [{ n: 1 }, { n: 2 }]
+  return (
+    <div>
+      {days.map((day: Day) => (
+        <div key={day.n} data-x={/* @client */ pred(day)}>cell</div>
+      ))}
+    </div>
+  )
+}
+`.trimStart(), 'test.tsx', { adapter })
+    const template = result.files?.find(f => f.path.endsWith('.tmpl'))?.content ?? ''
+    expect(result.errors ?? []).toEqual([])
+    // The loop still renders (the array is a static const) but the deferred
+    // attribute is absent from the emitted `<div>` cell.
+    expect(template).toContain('range')
+    expect(template).not.toContain('data-x')
+  })
+})

package/src/__tests__/lowering-plugin.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Registry → adapter end-to-end (#2057). Every lowering — first-party built-ins
+ * (like `queryHref`) and userland plugins alike — flows through the one
+ * lowering-plugin *registry*. This test guarantees that seam works all the way
+ * through: a SAMPLE plugin (registered via the public `registerLoweringPlugin`)
+ * recognises a call from an arbitrary package and returns a backend-neutral
+ * `guard-list` node, and the Go adapter renders it via its own `bf_query`
+ * mapping — no adapter code knows the sample plugin exists.
+ *
+ * The plugin reuses the `'query'` helper id so it exercises the exact same
+ * renderer path as the built-in `queryHref` plugin, proving that a userland
+ * plugin and a default-registered built-in are indistinguishable to the adapter
+ * (which is the whole point of the neutral-node layer).
+ */
+import { describe, test, expect, afterEach } from 'bun:test'
+import {
+  compileJSX,
+  registerLoweringPlugin,
+  getLoweringPlugins,
+  __resetLoweringPluginsForTest,
+  type ComponentIR,
+  type LoweringPlugin,
+} from '@barefootjs/jsx'
+import { GoTemplateAdapter } from '../adapter/go-template-adapter'
+
+function generate(src: string) {
+  const adapter = new GoTemplateAdapter()
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter, outputIR: true })
+  const irFile = result.files.find(f => f.type === 'ir')
+  if (!irFile) throw new Error('no IR')
+  const ir = JSON.parse(irFile.content) as ComponentIR
+  return adapter.generate(ir)
+}
+
+// A userland-style plugin: active only when the component imports `demoUrl` from
+// `@sample/pkg`, lowering `demoUrl(base, { key: value })` to a neutral
+// `guard-list` on the `'query'` helper. It reuses the sub-parts of the parsed
+// call directly (base = first arg, one triple per object property) so no
+// adapter syntax leaks into the plugin.
+const samplePlugin: LoweringPlugin = {
+  name: 'sample-demo-url',
+  prepare(metadata) {
+    const spec = metadata.imports
+      .filter(i => i.source === '@sample/pkg' && !i.isTypeOnly)
+      .flatMap(i => i.specifiers)
+      .filter(s => !s.isTypeOnly && !s.isNamespace && !s.isDefault)
+      .find(s => s.name === 'demoUrl')
+    if (!spec) return null
+    const local = spec.alias ?? spec.name // the name it's bound under in this file
+    return (callee, args) => {
+      if (callee.kind !== 'identifier' || callee.name !== local) return null
+      const [base, obj] = args
+      if (!base || obj?.kind !== 'object-literal') return null
+      return {
+        kind: 'guard-list',
+        helper: 'query',
+        base,
+        triples: obj.properties.map(p => ({ guard: null, key: p.key, value: p.value })),
+      }
+    }
+  },
+}
+
+afterEach(() => {
+  __resetLoweringPluginsForTest(getLoweringPlugins().filter(p => p.name !== 'sample-demo-url'))
+})
+
+describe('lowering-plugin registry → Go adapter (#2057)', () => {
+  test('a registered plugin lowers its call to the neutral node the adapter renders', () => {
+    registerLoweringPlugin(samplePlugin)
+    const src = `
+'use client'
+import { demoUrl } from '@sample/pkg'
+export function P(props: { base: string; tag: string }) {
+  return <a href={demoUrl(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Same render path as built-in queryHref: guard-list → bf_query.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+  })
+
+  test('without the plugin registered the same call falls back to the generic lowering', () => {
+    // No registerLoweringPlugin call — the registry is empty for this component.
+    const src = `
+'use client'
+import { demoUrl } from '@sample/pkg'
+export function P(props: { base: string; tag: string }) {
+  return <a href={demoUrl(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+  })
+
+  test('the plugin is inert when the component does not import from its package', () => {
+    registerLoweringPlugin(samplePlugin)
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={queryHref(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Built-in queryHref still lowers; the sample plugin simply isn't active.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+  })
+})