@barefootjs/go-template 0.16.0 → 0.17.0

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

@@ -226,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)
@@ -237,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)
@@ -267,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">
@@ -735,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
@@ -1715,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)', () => {
@@ -1745,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]')
@@ -1776,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}}')
     })
 
@@ -1837,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')
     })
   })
@@ -1855,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')
     })
 
@@ -1889,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"
@@ -1904,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', () => {
@@ -2428,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', () => {
@@ -2441,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')
     })
   })
 
@@ -2837,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}}' },
@@ -2894,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 }[] }) {
@@ -2910,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")')
   })
 })
 
@@ -2952,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')
   })
 })
 
@@ -3019,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

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')
+  })
+})

package/src/__tests__/query-href.test.ts

@@ -0,0 +1,179 @@
+/**
+ * `queryHref(base, { … })` → `bf_query` lowering for the Go adapter (#2042).
+ *
+ * The pure functional URL builder is a structured `call` + `object-literal` in
+ * the IR, so the adapter lowers it directly — no block-body recognizer, no
+ * re-parse. The lowering emits `(include) "key" value` triples and lets the
+ * `bf_query` runtime helper own the non-empty check (so it can also append array
+ * values member-by-member, #2048): a plain `key: v` → `(true) "key" v`; a
+ * conditional `key: cond ? a : undefined` → `(cond) "key" a` (the helper drops an
+ * empty `a`). The full value semantics are conformance-tested against
+ * URLSearchParams in the shared golden vectors (TestHelperVectors, fn "query").
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } 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)
+}
+
+describe('queryHref → bf_query (#2042)', () => {
+  test('a plain value passes a `true` include — bf_query drops it if empty', () => {
+    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)
+    expect(template).toContain('bf_query .Base (true) "tag" .Tag')
+    expect(template).not.toContain('.QueryHref')
+  })
+
+  test('a conditional include lowers to `(cond)` — the helper applies the non-empty check', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; sort: string; tag: string }) {
+  return (
+    <a href={queryHref(props.base, {
+      sort: props.sort !== 'date' ? props.sort : undefined,
+      tag: props.tag,
+    })}>x</a>
+  )
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain(
+      'bf_query .Base (ne (bf_string .Sort) "date") "sort" .Sort (true) "tag" .Tag',
+    )
+    // The `ne consequent ""` non-empty check is no longer folded into the
+    // include — bf_query owns it (so it can also append array values).
+    expect(template).not.toContain('(ne .Sort "")')
+  })
+
+  // A `&&` / `||` guard is NOT a comparison, so `lowerUrlGuard` can't emit it as
+  // a bare Go bool — `and`/`or` return one of their operands (a string), which
+  // `bf_query` type-asserts against. It must take the truthiness-wrap path,
+  // `ne (and …) ""`, yielding a real bool.
+  test('a `&&` guard is wrapped to a bool — `ne (and …) ""`, not a bare `and`', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; a: string; b: string }) {
+  return <a href={queryHref(props.base, { both: props.a && props.b ? props.a : undefined })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (ne (and .A .B) "") "both" .A')
+  })
+
+  test('null / empty-string alternates are both treated as the omit branch', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; mode: string; a: string; b: string }) {
+  return <a href={queryHref(props.base, {
+    a: props.mode !== 'off' ? props.a : '',
+    b: props.mode !== 'off' ? props.b : null,
+  })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // Both '' and null alternates fold to the same conditional-include form.
+    expect(template).toContain('(ne (bf_string .Mode) "off") "a" .A')
+    expect(template).toContain('(ne (bf_string .Mode) "off") "b" .B')
+  })
+
+  test('an array value lowers the slice expression; bf_query appends its members', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.tags })}>x</a>
+}
+`
+    const { template } = generate(src)
+    // The value is the raw slice field; member-append + non-empty omit happen in
+    // the helper at render time (verified against URLSearchParams in the golden
+    // vectors). The old `ne value ""` fold would have been invalid Go here.
+    expect(template).toContain('bf_query .Base (true) "tag" .Tags')
+  })
+
+  test('a conditional array value keeps the guard and passes the slice', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; on: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.on !== '' ? props.tags : undefined })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (ne (bf_string .On) "") "tag" .Tags')
+  })
+
+  test('an aliased import is still recognised', () => {
+    const src = `
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={qh(props.base, { tag: props.tag })}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base')
+    expect(template).toContain('"tag" .Tag')
+  })
+
+  test('a param-free expression-bodied helper wrapping queryHref inlines + lowers', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  const homeHref = () => queryHref(props.base, { view: 'home' })
+  return <a href={homeHref()}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).toContain('bf_query .Base (true) "view" "home"')
+    expect(template).not.toContain('.HomeHref')
+  })
+
+  // Known limitation (pre-existing, not queryHref-specific): the generic helper
+  // inliner declines a body whose object literal references the helper's params,
+  // because an object literal lowers opaquely from its `raw` source — so the
+  // param can't be substituted. queryHref's idiom is the direct call, so this is
+  // a minor gap; helper-delegation ergonomics are a follow-up (#2042).
+  test('a helper whose params-object references a param is not yet inlined (falls back)', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string }) {
+  const hrefFor = (s: string) => queryHref(props.base, { sort: s })
+  return <a href={hrefFor('title')}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+    expect(template).toContain('.HrefFor "title"')
+  })
+
+  test('a dynamic (non-literal) params object falls back to the generic lowering', () => {
+    const src = `
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; q: Record<string, string> }) {
+  return <a href={queryHref(props.base, props.q)}>x</a>
+}
+`
+    const { template } = generate(src)
+    expect(template).not.toContain('bf_query')
+  })
+})