@barefootjs/jinja 0.1.0

package/src/__tests__/jinja-adapter-unit.test.ts

@@ -0,0 +1,390 @@
+/**
+ * Ported from the Xslate-specific describes in
+ * `packages/adapter-xslate/src/__tests__/xslate-adapter.test.ts` (lines
+ * 152-400): SSR context propagation, memo seeding, signal seeding +
+ * data-key, #1966 @client attribute deferral, #2073 map_eval, #2018 P2
+ * predicate lowering, #2075 searchParams()-derived memo seeding. Expected
+ * template strings are translated to Jinja syntax. `runAdapterConformanceTests`
+ * itself (lines 24-150) and `src/test-render.ts` are workstream C and are NOT
+ * ported here.
+ *
+ * One describe (`prop-derived signal SSR seeding + data-key`) diverges
+ * behaviourally, not just syntactically: the "does NOT in-template-seed a
+ * same-name signal" Xslate test is inverted here to "DOES seed" — see
+ * `memo/seed.ts`'s file header for why Jinja's `{% set %}` doesn't have
+ * Kolon's `my`-shadowing hazard.
+ *
+ * The "#2075 searchParams()-derived memo seeding" describe also diverges: the
+ * "filter memo chained off the derived memo" case asserts a `bf.filter_eval(`
+ * seed (not Xslate's `$bf.filter(` lambda-closure), and asserts the
+ * evaluator's captured env dict (`{'tag': tag}`) rather than a bare `$tag`
+ * lambda-body reference — see `memo/seed.ts`'s file header on
+ * `materializeGetterCalls` (divergence 3: Jinja has no lambda fallback, so a
+ * sibling-getter call inside a predicate must materialize to a free var the
+ * evaluator can capture, instead of closing over the lexical directly).
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { JinjaAdapter } from '../adapter'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function compileToIR(source: string): ComponentIR {
+  const result = compileJSX(source.trimStart(), 'test.tsx', {
+    adapter: new JinjaAdapter(),
+    outputIR: true,
+  })
+  const irFile = result.files.find(f => f.type === 'ir')
+  if (!irFile) throw new Error('No IR output')
+  return JSON.parse(irFile.content) as ComponentIR
+}
+
+function compileAndGenerate(source: string) {
+  return new JinjaAdapter().generate(compileToIR(source))
+}
+
+// =============================================================================
+// Jinja-Specific Tests
+// =============================================================================
+
+describe('JinjaAdapter - SSR context propagation (#1297)', () => {
+  // `<Ctx.Provider value>` brackets its children with inline provide/revoke
+  // calls (both return '' so the `{{ … }}` interpolation discards them);
+  // descendant `useContext` consumers read the value during the same
+  // render.
+  test('provider brackets children with provide_context / revoke_context', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createContext, useContext } from '@barefootjs/client'
+const ThemeContext = createContext('light')
+export function ThemeRoot() {
+  return <div><ThemeContext.Provider value="dark"><ThemeLabel /></ThemeContext.Provider></div>
+}
+function ThemeLabel() { const theme = useContext(ThemeContext); return <span>{theme}</span> }
+`)
+    expect(template).toContain("bf.provide_context('ThemeContext', 'dark')")
+    expect(template).toContain("bf.revoke_context('ThemeContext')")
+    expect(template.indexOf('provide_context')).toBeLessThan(template.indexOf('render_child'))
+    expect(template.indexOf('render_child')).toBeLessThan(template.indexOf('revoke_context'))
+  })
+
+  test('consumer seeds its local from use_context with the createContext default', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createContext, useContext } from '@barefootjs/client'
+const ThemeContext = createContext('light')
+export function ThemeLabel() { const theme = useContext(ThemeContext); return <span>{theme}</span> }
+`)
+    expect(template).toContain("{% set theme = bf.use_context('ThemeContext', 'light') %}")
+  })
+})
+
+describe('JinjaAdapter - prop-derived memo SSR seeding (#1297)', () => {
+  // A memo whose body can't be statically folded (`props.value * 10`) gets a
+  // `null` SSR default; the adapter computes it in-template from the seeded
+  // prop var so the child renders the value instead of empty.
+  test('seeds a prop-derived memo from the prop var', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function Child(props: { value: number }) {
+  const displayValue = createMemo(() => props.value * 10)
+  return <span>{displayValue()}</span>
+}
+`)
+    expect(template).toContain('{% set displayValue = value * 10 %}')
+  })
+
+  test('seeds a memo over a destructured prop', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function Child({ value }: { value: number }) {
+  const displayValue = createMemo(() => value * 10)
+  return <span>{displayValue()}</span>
+}
+`)
+    expect(template).toContain('{% set displayValue = value * 10 %}')
+  })
+})
+
+describe('JinjaAdapter - prop-derived signal SSR seeding + data-key (#1297, toggle-shared)', () => {
+  test('seeds a prop-derived (different-name) signal from the prop var', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Item(props: { defaultOn?: boolean }) {
+  const [on, setOn] = createSignal(props.defaultOn ?? false)
+  return <button>{on() ? 'ON' : 'OFF'}</button>
+}
+`)
+    expect(template).toContain('{% set on = (defaultOn if (defaultOn is defined and defaultOn is not none) else false) %}')
+  })
+
+  // Divergence from the Kolon port: Jinja's `{% set x = x + 1 %}` safely
+  // resolves the right-hand `x` from the enclosing scope (no `my`-shadowing
+  // hazard), so a same-name signal IS seeded in-template here — strictly
+  // more correct than leaving it on the static default. See
+  // `memo/seed.ts`'s file header.
+  test('DOES in-template-seed a same-name signal (no Kolon `my`-shadow hazard in Jinja)', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function C(props: { x?: number }) {
+  const [x, setX] = createSignal(props.x ?? 7)
+  return <span>{x()}</span>
+}
+`)
+    expect(template).toContain('{% set x = (x if (x is defined and x is not none) else 7) %}')
+  })
+
+  test('emits data_key_attr on the component root', () => {
+    const { template } = compileAndGenerate(`
+export function Item() { return <div class="x">hi</div> }
+`)
+    expect(template).toContain('bf.data_key_attr()')
+  })
+
+  test('emits data_key_attr on each branch root of an if-statement root', () => {
+    const { template } = compileAndGenerate(`
+export function Item({ on }: { on?: boolean }) {
+  if (on) return <div class="a">A</div>
+  return <div class="b">B</div>
+}
+`)
+    const count = (template.match(/bf\.data_key_attr\(\)/g) ?? []).length
+    expect(count).toBe(2)
+  })
+})
+
+// =============================================================================
+// #1966 — `/* @client */` defers ATTRIBUTE bindings (not just child/text)
+// =============================================================================
+//
+// `renderAttributes` skips SSR emission for `attr.clientOnly`, so a
+// deferred attribute predicate is omitted from the Jinja template (and the
+// unsupported-expression lowering is never reached → no BF101/BF102). The
+// client runtime sets the attribute on hydrate. Mirrors the Go / Xslate pins.
+describe('JinjaAdapter - #1966 @client defers attribute bindings', () => {
+  function compileAttr(attrExpr: string) {
+    const adapter = new JinjaAdapter()
+    const ir = compileToIR(`
+"use client"
+import { createSignal } from "@barefootjs/client"
+export function C() {
+  const [sel] = createSignal(0)
+  const pred = (n: number) => sel() === n
+  return <div data-x={${attrExpr}}>hi</div>
+}
+`)
+    const template = adapter.generate(ir).template ?? ''
+    const errors = (adapter as unknown as { errors: { code: string }[] }).errors ?? []
+    return { errors, template }
+  }
+
+  test('bare emits data-x; @client omits it from SSR', () => {
+    expect(compileAttr('pred(1)').template).toContain('data-x')
+    const deferred = compileAttr('/* @client */ pred(1)')
+    expect(deferred.errors).toEqual([])
+    expect(deferred.template).not.toContain('data-x')
+  })
+})
+
+// #2018 P2: higher-order predicates lower through the runtime evaluator
+// (`bf.*_eval`), isomorphic with the Go / Xslate `*_eval` helpers. Jinja has
+// no lambda fallback (divergence 3 in `jinja-adapter.ts`'s header) — a
+// predicate the evaluator can't model surfaces BF101 instead.
+describe('JinjaAdapter - #2073 value-producing .map(cb)', () => {
+  // The blog-showcase shape (#1938/#1939): a value-returning `.map` (string
+  // projection, not JSX) lowers through the evaluator — `bf.map_eval`
+  // projects each element (no flatten) and composes through `bf.join`.
+  test('.map(t => `#${t}`).join(" ") emits bf.map_eval composed into bf.join', () => {
+    const { template } = compileAndGenerate(`
+function TagLine({ tags }: { tags: string[] }) {
+  return <p>{tags.map((t) => \`#\${t}\`).join(' ')}</p>
+}
+export { TagLine }
+`)
+    expect(template).toContain("bf.join(bf.map_eval(tags,")
+    expect(template).toContain('"kind":"template-literal"')
+  })
+
+  test('.map(u => u.name) emits bf.map_eval with the field projection', () => {
+    const { template } = compileAndGenerate(`
+function NameList({ users }: { users: { name: string }[] }) {
+  return <div>{users.map((u) => u.name).join(', ')}</div>
+}
+export { NameList }
+`)
+    expect(template).toContain('bf.map_eval(users,')
+    expect(template).toContain('"property":"name"')
+  })
+})
+
+describe('JinjaAdapter - higher-order predicate lowering (#2018 P2)', () => {
+  test('a serializable predicate lowers to bf.filter_eval with the JSON body + env', () => {
+    // A standalone `.filter().length` exercises the higher-order emitter (the
+    // `.filter().map()` form is a loop-hoist with an inline `{% if %}`,
+    // handled by renderLoop, not this emitter).
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.filter(x => x.done).length}</div>
+}
+export { A }
+`)
+    expect(template).toContain('bf.filter_eval(')
+    expect(template).toContain('"property":"done"')
+    expect(template).toContain("'x'")
+  })
+
+  test('.find / .findLast share bf.find_eval, distinguished by the forward flag', () => {
+    const find = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.find(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(find).toContain('bf.find_eval(')
+    // `forward` is a genuine Python bool literal here (`true`/`false`),
+    // unlike the Kolon port's Perl `1`/`0` — see `expr/array-method.ts`.
+    expect(find).toContain(", true, {})")
+
+    const findLast = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.findLast(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(findLast).toContain('bf.find_eval(')
+    expect(findLast).toContain(", false, {})")
+  })
+
+  // #2075: `.includes(x)` joined the evaluator's `array-method` surface
+  // (shared with the Perl/Go evaluator runtimes), so a predicate built from
+  // it now routes through `bf.every_eval` like any other pure predicate —
+  // no BF101, despite being a method-call predicate.
+  test('.includes() in a predicate now lowers via the evaluator, not a BF101 refusal', () => {
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { name: string }[] }) {
+  return <div>{items.every(x => x.name.includes('a')) ? 'y' : 'n'}</div>
+}
+export { A }
+`)
+    expect(template).toContain('bf.every_eval(')
+    expect(template).toContain('"method":"includes"')
+    expect(template).not.toContain('bf.truthy(\'\')')
+  })
+
+  // Divergence 3 (`jinja-adapter.ts`'s header): Jinja has no lambda
+  // expression, so a predicate the evaluator can't serialize (a method call
+  // outside the evaluator's `array-method` gate — only `includes` is
+  // recognized there) has NO fallback — unlike Kolon, which falls back to a
+  // `-> $x { … }` lambda passed to `$bf.every`. This surfaces BF101 instead.
+  test('a method-call predicate outside the evaluator surface has no lambda fallback — surfaces BF101', () => {
+    const adapter = new JinjaAdapter()
+    const ir = compileToIR(`
+function A({ items }: { items: { name: string }[] }) {
+  return <div>{items.every(x => x.name.toUpperCase() === 'A') ? 'y' : 'n'}</div>
+}
+export { A }
+`)
+    const { template } = adapter.generate(ir)
+    const errors = (adapter as unknown as { errors: { code: string; message: string }[] }).errors
+    expect(errors.some(e => e.code === 'BF101' && e.message.includes("'.every(...)'"))).toBe(true)
+    // No evaluator helper, and — critically — no lambda syntax either;
+    // the condition falls back to the safe `bf.truthy('')` empty-string
+    // sentinel (see `convertExpressionToJinja`'s BF101 path).
+    expect(template).not.toContain('every_eval')
+    expect(template).not.toContain('bf.every(')
+    expect(template).toContain("bf.truthy('')")
+  })
+})
+
+// #2075: derived signal/memo seeding now consumes the shared
+// `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts) instead of
+// re-deriving scope/support locally — same plan Xslate/Mojo consume, ported
+// to `{% set %}` syntax. Mirrors
+// `packages/adapter-xslate/src/__tests__/xslate-adapter.test.ts`'s
+// "#2075 searchParams()-derived memo seeding" describe.
+describe('JinjaAdapter - #2075 searchParams()-derived memo seeding', () => {
+  test('seeds an aliased scalar derived memo from the canonical reader', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function SortStatus() {
+  const [sp] = createSearchParams()
+  const sort = createMemo(() => sp().get('sort') ?? 'date')
+  return <p>sort: {sort()}</p>
+}
+`)
+    expect(template).toContain(
+      "{% set sort = (searchParams.get('sort') if (searchParams.get('sort') is defined and searchParams.get('sort') is not none) else 'date') %}",
+    )
+  })
+
+  // The evaluator-JSON `param` and the `bf` runtime object are
+  // lowering-internal, not out-of-scope template vars (#2075). Jinja routes
+  // the filter predicate through `bf.filter_eval` (divergence 3 — no lambda
+  // fallback), materializing the sibling getter call `tag()` into a bare
+  // free-var read (`materializeGetterCalls`) so the evaluator can serialize
+  // it at all; the captured env then resolves against the `tag` seed line
+  // emitted just above (see `memo/seed.ts`'s file header).
+  test('seeds a filter memo chained off the derived memo', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function TaggedList(props: { items: { title: string; tags: string[] }[] }) {
+  const [searchParams] = createSearchParams()
+  const tag = createMemo(() => searchParams().get('tag') ?? '')
+  const visible = createMemo(() => props.items.filter((p) => !tag() || p.tags.includes(tag())))
+  return <ul>{visible().map((p) => <li key={p.title}>{p.title}</li>)}</ul>
+}
+`)
+    expect(template).toContain(
+      "{% set tag = (searchParams.get('tag') if (searchParams.get('tag') is defined and searchParams.get('tag') is not none) else '') %}",
+    )
+    expect(template).toContain('{% set visible = bf.filter_eval(items,')
+    expect(template).toContain("{'tag': tag}")
+  })
+
+  // The seed-scope guard used to scan the LOWERED Jinja text for bare-word
+  // tokens. That let an outer, unbound `p` (shadowed only inside the
+  // callback) slip past as if it were the callback's own bound `p` —
+  // emitting a bogus seed line. The guard now walks the parsed SOURCE tree
+  // with proper lexical scoping (`freeIdentifiers`, inside
+  // `computeSsrSeedPlan`), so this shape seeds nothing and falls back to the
+  // static ssr-defaults path.
+  test('an outer unbound `p` shadowed only inside the callback does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { items: { ok: boolean }[] }) {
+  const visible = createMemo(() => props.items.filter((p) => p.ok) && p)
+  return <div>{String(visible())}</div>
+}
+`)
+    expect(template).not.toContain('{% set visible')
+  })
+
+  // An out-of-scope bare `_` reference must not seed either.
+  test('an out-of-scope bare `_` reference does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { count: number }) {
+  const doubled = createMemo(() => props.count * 2 + _)
+  return <div>{doubled()}</div>
+}
+`)
+    expect(template).not.toContain('{% set doubled')
+  })
+})
+
+// #2038 nested-callback-predicate loudness is pinned at the shared
+// conformance layer (workstream C): `filter-nested-callback-predicate` /
+// `filter-nested-find-predicate` (BF101 via `expectedDiagnostics`) and
+// `filter-nested-callback-predicate-client` (the `/* @client */` suppression
+// twin, which must render clean).

package/src/__tests__/jinja-adapter.test.ts

@@ -0,0 +1,53 @@
+/**
+ * JinjaAdapter — Conformance Tests
+ *
+ * Runs the shared adapter conformance corpus (JSX fixtures, template
+ * primitives, marker conformance) against the Jinja2 adapter, rendering
+ * each fixture end-to-end through real Jinja2 + the bundled
+ * `barefootjs.backend_jinja.JinjaBackend` via `renderJinjaComponent`.
+ *
+ * The Jinja adapter was ported from the Text::Xslate (Kolon) adapter, so
+ * the skip / diagnostic sets below start from xslate's and diverge only
+ * where the engine genuinely differs. Every divergence carries a one-line
+ * rationale.
+ */
+
+import { runAdapterConformanceTests } from '@barefootjs/adapter-tests'
+import { JinjaAdapter } from '../adapter'
+import { renderJinjaComponent, PythonNotAvailableError } from '../test-render'
+import { conformancePins } from '../conformance-pins'
+
+runAdapterConformanceTests({
+  name: 'jinja',
+  factory: () => new JinjaAdapter(),
+  render: renderJinjaComponent,
+  // Per-fixture build-time contracts for shapes the Jinja adapter
+  // intentionally refuses to lower. Lives in `../conformance-pins` —
+  // mirrors xslate's set (the lowering gates are shared code paths in
+  // the ported adapter; BF103/BF104 are structural: cross-template
+  // child registration / destructure-loop-param limits that apply
+  // identically regardless of target template language).
+  expectedDiagnostics: conformancePins,
+  // Template-primitive registry: `USER_IMPORT_VIA_CONST` and
+  // `NO_DOUBLE_REWRITE_OF_PROPS_OBJECT` now pass (#2069) — a bespoke user
+  // import can never be added to the string-keyed registry, but the
+  // shared `RelocateEnv.loweringMatchers` acceptance path recognises it
+  // via a `LoweringPlugin` the case setup registers around the compile
+  // (see `packages/adapter-tests/src/cases/template-primitives.ts`). No
+  // skips left, so `skipTemplatePrimitives` is omitted entirely.
+  skipMarkerConformance: new Set([
+    // Same as Hono / Xslate: `/* @client */` markers on TodoApp's keyed
+    // `.map` intentionally elide a slot id from the SSR template that
+    // the IR still declares (s6). See hono-adapter.test for the contract.
+    'todo-app',
+    // Same `/* @client */` keyed-map elision (data-table).
+    'data-table',
+  ]),
+  onRenderError: (err, id) => {
+    if (err instanceof PythonNotAvailableError) {
+      console.log(`Skipping [${id}]: ${err.message}`)
+      return true
+    }
+    return false
+  },
+})

package/src/__tests__/jinja-counter.test.ts

@@ -0,0 +1,62 @@
+/**
+ * Ported from `packages/adapter-xslate/src/__tests__/xslate-counter.test.ts`.
+ *
+ * Only the FIRST (structural "compiles to a template") test is ported here.
+ * Xslate's second test renders the compiled template through REAL
+ * Text::Xslate via a `renderXslateComponent`-equivalent test-render harness
+ * (`Bun.spawn(['perl', ...])`). The Jinja analog of that harness
+ * (`renderJinjaComponent`, spawning `python3` against the bundled Python
+ * runtime) is `src/test-render.ts` — explicitly workstream C, not written
+ * here (see `packages/adapter-jinja/CHANGELOG.md` / the task's workstream
+ * split). Once `test-render.ts` lands, a real-render counterpart to this
+ * test belongs in the conformance test file, not here.
+ */
+
+import { test, expect } from 'bun:test'
+import { compileJSX } from '@barefootjs/jsx'
+import { JinjaAdapter } from '../adapter'
+
+const COUNTER_SRC = `"use client"
+import { createSignal } from '@barefootjs/client'
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = createSignal(initial)
+  const doubled = () => count() * 2
+  return (
+    <div class="counter">
+      <p>count: {count()}</p>
+      <p>doubled: {doubled()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}`
+
+test('Counter compiles to a Jinja .jinja template', () => {
+  const result = compileJSX(COUNTER_SRC, 'Counter.tsx', {
+    adapter: new JinjaAdapter(),
+    outputIR: true,
+  })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  expect(errors).toEqual([])
+
+  const tpl = result.files.find(f => f.type === 'markedTemplate')
+  expect(tpl).toBeDefined()
+  const content = tpl!.content
+  // Script registration as `{% set %}` statements (Jinja's `{% %}` tag never
+  // prints, so — unlike Kolon's bare `:` line — no throwaway-bind trick is
+  // needed to suppress a leaked return value; see `jinja-adapter.ts`'s
+  // `generateScriptRegistrations`).
+  expect(content).toContain(`bf.register_script('/static/components/barefoot.js')`)
+  expect(content).toContain(`bf.register_script('/static/components/Counter.client.js')`)
+  // Hydration markers
+  expect(content).toContain(`bf-s="{{ bf.scope_attr() }}"`)
+  expect(content).toContain(`{{ bf.hydration_attrs() | safe }}`)
+  expect(content).toContain(`{{ bf.props_attr() | safe }}`)
+  // Text slots — every text interpolation routes through `bf.string(...)`
+  // (divergence 2: Python's default stringification diverges from JS's
+  // further than Perl's does, so this port wraps every text-position value,
+  // unlike the Kolon port's bare `<: $count :>`).
+  expect(content).toContain(`{{ bf.text_start("s0") | safe }}{{ bf.string(count) }}{{ bf.text_end() | safe }}`)
+  expect(content).toContain(`{{ bf.text_start("s2") | safe }}{{ bf.string(doubled) }}{{ bf.text_end() | safe }}`)
+  // Button stays a plain element (onClick is client-only)
+  expect(content).toContain(`+1</button>`)
+})

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

@@ -0,0 +1,99 @@
+/**
+ * `queryHref(base, { … })` → `bf.query(...)` lowering for the Jinja adapter
+ * (#2042). Ported from
+ * `packages/adapter-xslate/src/__tests__/query-href.test.ts`. Parity with
+ * the go-template / Xslate lowering: the call + object literal are
+ * structured IR, so it lowers directly. The shared `query` runtime helper
+ * (`barefootjs.runtime`) includes a pair iff its guard is truthy AND its
+ * value is a non-empty string, so a plain `key: v` passes guard `true` and a
+ * conditional `key: cond ? v : undefined` passes the lowered condition.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { JinjaAdapter } from '../adapter/jinja-adapter'
+
+function template(src: string): string {
+  const a = new JinjaAdapter()
+  const r = compileJSX(src.trimStart(), 'T.tsx', { adapter: a, outputIR: true })
+  const ir = JSON.parse(r.files.find(f => f.type === 'ir')!.content) as ComponentIR
+  return a.generate(ir).template
+}
+
+describe('queryHref → bf.query (Jinja, #2042)', () => {
+  test('a plain value passes guard true', () => {
+    const t = template(`
+'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>
+}
+`)
+    expect(t).toContain("bf.query(base, 1, 'tag', tag)")
+  })
+
+  test('a conditional include passes the lowered condition as the guard', () => {
+    const t = template(`
+'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>
+}
+`)
+    // Jinja's `!=` handles string inequality directly (like Kolon's `!=`;
+    // unlike Perl's `ne`).
+    expect(t).toContain("bf.query(base, (sort != 'date'), 'sort', sort, 1, 'tag', tag)")
+  })
+
+  // A bare-value guard (`flag ? v : undefined`) is JS *string* truthiness —
+  // `'0'` is a truthy string in JS. The lowering must normalise it to a
+  // non-empty-string test so SSR matches the client / go (where
+  // `lowerUrlGuard` emits `ne <value> ""`). Jinja renders the `!== ''` test
+  // as `!= ''` (its string inequality), matching the comparison guard above.
+  test('a bare-value guard is normalised to a non-empty-string test', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; flag: string; val: string }) {
+  return <a href={queryHref(props.base, { q: props.flag ? props.val : undefined })}>x</a>
+}
+`)
+    expect(t).toContain("bf.query(base, (flag != ''), 'q', val)")
+  })
+
+  // An array value (`{ tag: props.tags }`) lowers to the bare receiver
+  // expression; the shared `query` runtime helper detects the list at
+  // runtime and appends one pair per non-empty member (#2048). No
+  // adapter-side change beyond passing the value through.
+  test('an array value passes the receiver expression for the helper to append', () => {
+    const t = template(`
+'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>
+}
+`)
+    expect(t).toContain("bf.query(base, 1, 'tag', tags)")
+  })
+
+  test('an aliased import is recognised', () => {
+    const t = template(`
+'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>
+}
+`)
+    expect(t).toContain("bf.query(base, 1, 'tag', tag)")
+  })
+
+  test('a dynamic (non-literal) params object falls back (no bf.query)', () => {
+    const t = template(`
+'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>
+}
+`)
+    expect(t).not.toContain('.query')
+  })
+})