@barefootjs/blade 0.1.0

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

@@ -0,0 +1,392 @@
+/**
+ * Ported from `packages/adapter-twig/src/__tests__/twig-adapter-unit.test.ts`
+ * (itself ported from the Jinja-specific describes, ultimately from
+ * Xslate's): 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 Blade syntax (`$bf->method(...)`,
+ * `@php($x = ...)`, `[]` empty-env arrays instead of Twig's `{}`).
+ * `runAdapterConformanceTests` itself and `src/test-render.ts` are
+ * workstream C and are NOT ported here (they live in this same package,
+ * but as their own files).
+ *
+ * One divergence from the byte-for-byte Twig port: `emitEvalEnvArg`'s empty
+ * capture set is PHP's empty ARRAY `[]`, not Twig's empty HASH `{}` (see
+ * `expr/array-method.ts`'s docstring) — every `", true, {})"` / `", false,
+ * {})"` / `"{'tag': tag}"` expectation below becomes `", true, [])"` / `",
+ * false, [])"` / `"['tag' => $tag]"`.
+ *
+ * The "in-template self-reference seeding" behaviour is UNCHANGED from Twig
+ * (not inverted back to Kolon's skip): verified empirically (this package's
+ * `php/` smoke tests) that Blade's `@php($x = $x + 1)` resolves the
+ * right-hand `$x` from the enclosing scope before assignment (PHP has no
+ * block-level shadowing the way Kolon's `my` does) — so a same-name signal
+ * IS seeded in-template here too.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { BladeAdapter } from '../adapter'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function compileToIR(source: string): ComponentIR {
+  const result = compileJSX(source.trimStart(), 'test.tsx', {
+    adapter: new BladeAdapter(),
+    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 BladeAdapter().generate(compileToIR(source))
+}
+
+// =============================================================================
+// Blade-Specific Tests
+// =============================================================================
+
+describe('BladeAdapter - 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("@php($theme = $bf->use_context('ThemeContext', 'light'))")
+  })
+})
+
+describe('BladeAdapter - 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('@php($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('@php($displayValue = $value * 10)')
+  })
+})
+
+describe('BladeAdapter - 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('@php($on = ($defaultOn ?? false))')
+  })
+
+  // Verified empirically (this package's `php/` smoke tests): a plain PHP
+  // assignment `@php($x = $x + 1)` reads the SAME `$x` the render already
+  // extracted, no 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 shadow hazard in Blade)', () => {
+    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('@php($x = ($x ?? 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 Blade template (and the
+// unsupported-expression lowering is never reached → no BF101/BF102). The
+// client runtime sets the attribute on hydrate. Mirrors the Go / Twig / Jinja
+// pins.
+describe('BladeAdapter - #1966 @client defers attribute bindings', () => {
+  function compileAttr(attrExpr: string) {
+    const adapter = new BladeAdapter()
+    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 / Jinja / Twig / Xslate `*_eval`
+// helpers. Blade has no lambda fallback (`expr/emitters.ts`'s file header,
+// divergence 9) — a predicate the evaluator can't model surfaces BF101
+// instead.
+describe('BladeAdapter - #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('BladeAdapter - 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 boolean literal here (`true`/`false`).
+    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('')")
+  })
+
+  // `expr/emitters.ts`'s file header, divergence 9: Blade 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 — same as Jinja/Twig, unlike Kolon,
+  // which falls back to a Perl 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 BladeAdapter()
+    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 `convertExpressionToBlade`'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 Jinja/Twig/Xslate/Mojo
+// consume, ported to `@php(...)` + `??` syntax. Mirrors
+// `packages/adapter-twig/src/__tests__/twig-adapter-unit.test.ts`'s
+// "#2075 searchParams()-derived memo seeding" describe.
+describe('BladeAdapter - #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(
+      "@php($sort = ($searchParams->get('sort') ?? 'date'))",
+    )
+  })
+
+  // The evaluator-JSON `param` and the `bf` runtime object are
+  // lowering-internal, not out-of-scope template vars (#2075). Blade routes
+  // the filter predicate through `$bf->filter_eval` (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(
+      "@php($tag = ($searchParams->get('tag') ?? ''))",
+    )
+    expect(template).toContain('@php($visible = $bf->filter_eval($items,')
+    expect(template).toContain("['tag' => $tag]")
+  })
+
+  // The seed-scope guard used to scan the LOWERED template 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('@php($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('@php($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__/blade-adapter.test.ts

@@ -0,0 +1,52 @@
+/**
+ * BladeAdapter — Conformance Tests
+ *
+ * Runs the shared adapter conformance corpus (JSX fixtures, template
+ * primitives, marker conformance) against the Blade adapter, rendering
+ * each fixture end-to-end through real Blade + the bundled
+ * `Barefoot\BladeBackend` PHP runtime via `renderBladeComponent`.
+ *
+ * The Blade adapter was ported from the Twig adapter, so the skip /
+ * diagnostic sets below start from Twig's and diverge only where the
+ * engine genuinely differs. Every divergence carries a one-line rationale.
+ */
+
+import { runAdapterConformanceTests } from '@barefootjs/adapter-tests'
+import { BladeAdapter } from '../adapter'
+import { renderBladeComponent, BladeNotAvailableError } from '../test-render'
+import { conformancePins } from '../conformance-pins'
+
+runAdapterConformanceTests({
+  name: 'blade',
+  factory: () => new BladeAdapter(),
+  render: renderBladeComponent,
+  // Per-fixture build-time contracts for shapes the Blade adapter
+  // intentionally refuses to lower. Lives in `../conformance-pins` —
+  // mirrors Twig'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 / Twig / Jinja: `/* @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 BladeNotAvailableError) {
+      console.log(`Skipping [${id}]: ${err.message}`)
+      return true
+    }
+    return false
+  },
+})

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

@@ -0,0 +1,63 @@
+/**
+ * Ported from `packages/adapter-jinja/src/__tests__/jinja-counter.test.ts`
+ * (itself ported from Xslate's counter test).
+ *
+ * Only the FIRST (structural "compiles to a template") test is ported here.
+ * The Jinja analog's second test renders the compiled template through REAL
+ * Jinja2 via `renderJinjaComponent`; the Blade analog of that harness
+ * (`renderBladeComponent`, spawning `php` against the bundled PHP runtime) is
+ * `src/test-render.ts` — workstream C, exercised end-to-end by
+ * `blade-adapter.test.ts`'s conformance suite, not duplicated here.
+ */
+
+import { test, expect } from 'bun:test'
+import { compileJSX } from '@barefootjs/jsx'
+import { BladeAdapter } 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 Blade .blade.php template', () => {
+  const result = compileJSX(COUNTER_SRC, 'Counter.tsx', {
+    adapter: new BladeAdapter(),
+    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 `@php(...)` statements (`@php(...)` never
+  // prints, so — unlike Kolon's bare `:` line — no throwaway-bind trick is
+  // needed to suppress a leaked return value; see `blade-adapter.ts`'s
+  // `generateScriptRegistrations`).
+  expect(content).toContain(`@php($bf->register_script('/static/components/barefoot.js'))`)
+  expect(content).toContain(`@php($bf->register_script('/static/components/Counter.client.js'))`)
+  // Hydration markers
+  expect(content).toContain(`bf-s="{!! e($bf->scope_attr()) !!}"`)
+  expect(content).toContain(`{!! $bf->hydration_attrs() !!}`)
+  expect(content).toContain(`{!! $bf->props_attr() !!}`)
+  // Text slots — every text interpolation routes through `$bf->string(...)`,
+  // wrapped in `{!! e(...) !!}` rather than Blade's own `{{ }}` (its
+  // regex-based tag matcher breaks on evaluator-JSON payload text containing
+  // a literal `}}` — see `blade-adapter.ts`'s file header, divergence 0).
+  // ("Stringification": PHP'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") !!}{!! e($bf->string($count)) !!}{!! $bf->text_end() !!}`)
+  expect(content).toContain(`{!! $bf->text_start("s2") !!}{!! e($bf->string($doubled)) !!}{!! $bf->text_end() !!}`)
+  // Button stays a plain element (onClick is client-only)
+  expect(content).toContain(`+1</button>`)
+})

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

@@ -0,0 +1,113 @@
+/**
+ * `queryHref(base, { … })` → `$bf->query(...)` lowering for the Blade
+ * adapter (#2042). Ported from
+ * `packages/adapter-twig/src/__tests__/twig-query-href.test.ts`. Parity
+ * with the go-template / Jinja / Twig / Xslate lowering: the call + object
+ * literal are structured IR, so it lowers directly. The shared `query`
+ * runtime helper (the PHP `Barefoot\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 `1` (true) and a conditional `key: cond ? v :
+ * undefined` passes the lowered condition.
+ *
+ * One test (the `!==`-derived guard) diverges from the byte-for-byte Jinja
+ * port (unchanged from the Twig port): Jinja's native `!=` is Python
+ * value-equality, so it's safe to route straight through. PHP's own `!=`/
+ * `!==` are either LOOSE inequality (`'0' != 0` is false, even though JS
+ * `'0' !== 0` is true) or number-representation-sensitive (`1 !== 1.0` is
+ * true in PHP; false in JS) — wrong for a JS strict-inequality source
+ * operator either way. Per the adapter's uniform emit policy
+ * (`expr/emitters.ts`'s file header, divergence 8), EVERY `===`/`!==` —
+ * including ones the URL-guard lowering (`lowerUrlGuard`) synthesizes
+ * internally for a bare-value guard's non-empty-string test — routes
+ * through `$bf->eq`/`$bf->neq` regardless of operand type, so both
+ * queryHref guard shapes below assert `$bf->neq(...)` rather than a bare
+ * `!=`.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { BladeAdapter } from '../adapter/blade-adapter'
+
+function template(src: string): string {
+  const a = new BladeAdapter()
+  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 (Blade, #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>
+}
+`)
+    expect(t).toContain("$bf->query($base, ($bf->neq($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> ""`). The Blade adapter's uniform
+  // strict-equality policy routes this synthesized inequality through
+  // `$bf->neq` too, same as any other `!==`.
+  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, ($bf->neq($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')
+  })
+})