@barefootjs/jsx 0.15.2 → 0.17.0

package/src/analyzer-context.ts

@@ -344,11 +344,21 @@ function propertyNameText(
 
 export function typeNodeToTypeInfo(
   typeNode: ts.TypeNode | undefined,
-  sourceFile: ts.SourceFile
+  sourceFile: ts.SourceFile,
+  // When set, `raw` is derived from this extractor instead of
+  // `node.getText(sourceFile)`. Synthetic nodes (from `checker.typeToTypeNode`,
+  // used by `tsTypeToTypeInfo`) have no source positions, so `getText()` would
+  // throw — callers pass a printer-based extractor. In that mode the
+  // object-literal / function branches that need member/param source text emit
+  // a `raw`-only shape (those consumers only run on real source).
+  rawOf?: (node: ts.TypeNode) => string
 ): TypeInfo | null {
   if (!typeNode) return null
 
-  const raw = typeNode.getText(sourceFile)
+  const synthetic = rawOf !== undefined
+  const raw = rawOf ? rawOf(typeNode) : typeNode.getText(sourceFile)
+  const recurse = (n: ts.TypeNode): TypeInfo =>
+    typeNodeToTypeInfo(n, sourceFile, rawOf) ?? { kind: 'unknown', raw: 'unknown' }
 
   // Primitive types (check by SyntaxKind)
   switch (typeNode.kind) {
@@ -366,26 +376,12 @@ export function typeNodeToTypeInfo(
 
   // Array types
   if (ts.isArrayTypeNode(typeNode)) {
-    return {
-      kind: 'array',
-      raw,
-      elementType: typeNodeToTypeInfo(typeNode.elementType, sourceFile) ?? {
-        kind: 'unknown',
-        raw: 'unknown',
-      },
-    }
+    return { kind: 'array', raw, elementType: recurse(typeNode.elementType) }
   }
 
   // Union types
   if (ts.isUnionTypeNode(typeNode)) {
-    return {
-      kind: 'union',
-      raw,
-      unionTypes: typeNode.types.map(
-        (t) =>
-          typeNodeToTypeInfo(t, sourceFile) ?? { kind: 'unknown', raw: 'unknown' }
-      ),
-    }
+    return { kind: 'union', raw, unionTypes: typeNode.types.map(recurse) }
   }
 
   // Type literal (object type)
@@ -393,7 +389,9 @@ export function typeNodeToTypeInfo(
     return {
       kind: 'object',
       raw,
-      properties: membersToProperties(typeNode.members, sourceFile),
+      // Synthetic members have no source positions for membersToProperties'
+      // getText(); emit a property-less object in that mode.
+      ...(synthetic ? {} : { properties: membersToProperties(typeNode.members, sourceFile) }),
     }
   }
 
@@ -407,14 +405,7 @@ export function typeNodeToTypeInfo(
       (refName === 'Array' || refName === 'ReadonlyArray') &&
       typeNode.typeArguments?.length === 1
     ) {
-      return {
-        kind: 'array',
-        raw,
-        elementType: typeNodeToTypeInfo(typeNode.typeArguments[0], sourceFile) ?? {
-          kind: 'unknown',
-          raw: 'unknown',
-        },
-      }
+      return { kind: 'array', raw, elementType: recurse(typeNode.typeArguments[0]) }
     }
     return {
       kind: 'interface',
@@ -424,6 +415,8 @@ export function typeNodeToTypeInfo(
 
   // Function type
   if (ts.isFunctionTypeNode(typeNode)) {
+    // Param names/defaults come from getText — skip them for synthetic nodes.
+    if (synthetic) return { kind: 'function', raw }
     return {
       kind: 'function',
       raw,
@@ -443,6 +436,40 @@ export function typeNodeToTypeInfo(
   return { kind: 'unknown', raw }
 }
 
+// Printer + blank source file reused across calls so checker-driven type
+// conversion never allocates a fresh `ts.createSourceFile` per memo on the
+// build hot path (the blank file is only printer context for synthetic
+// nodes, created once at module load).
+const _typePrinter = ts.createPrinter({ removeComments: true, omitTrailingSemicolon: true })
+const _blankTypeSourceFile = ts.createSourceFile('__bf_types__.ts', '', ts.ScriptTarget.Latest)
+
+/**
+ * Convert a resolved `ts.Type` to `TypeInfo` via the type checker. Used to
+ * sharpen `createMemo` field types the syntactic `inferTypeFromValue`
+ * heuristic can't reach — e.g. `createMemo(() => generateDays())` whose body
+ * is a local-function call (→ `CalendarDay[][]`) or a ternary of typed
+ * arrays (→ `string[]`). Without this the Go adapter renders such memos as
+ * `map[string]interface{}` / `bool` placeholders, so a typed backend can't
+ * populate the SSR data (#1968). Returns `null` when the type can't be
+ * lowered to a `ts.TypeNode`.
+ *
+ * Shares the structural lowering in `typeNodeToTypeInfo` (via the `rawOf`
+ * extractor) so node→TypeInfo logic lives in one place; the synthetic nodes
+ * from `typeToTypeNode` have no source text, so `raw` comes from the printer.
+ */
+export function tsTypeToTypeInfo(type: ts.Type, checker: ts.TypeChecker): TypeInfo | null {
+  const node = checker.typeToTypeNode(type, undefined, ts.NodeBuilderFlags.NoTruncation)
+  if (!node) return null
+  const rawOf = (n: ts.TypeNode): string => {
+    try {
+      return _typePrinter.printNode(ts.EmitHint.Unspecified, n, _blankTypeSourceFile)
+    } catch {
+      return 'unknown'
+    }
+  }
+  return typeNodeToTypeInfo(node, _blankTypeSourceFile, rawOf)
+}
+
 // =============================================================================
 // AST Helpers
 // =============================================================================
@@ -474,3 +501,21 @@ export function isArrowComponentFunction(
   if (!node.initializer || !ts.isArrowFunction(node.initializer)) return false
   return true
 }
+
+/**
+ * The set of reactive getter names for a component — signal accessors plus memo
+ * names. Single source of truth for "what counts as a reactive getter", shared
+ * by the analyzer's block-memo fold purity oracle (#2040) and `jsx-to-ir`'s
+ * `getReactiveGetterNames`. A reactive read is idempotent within a render, so
+ * callers treat `getter()` as pure. If a third reactive kind is added, update
+ * this one function.
+ */
+export function collectReactiveGetterNames(
+  signals: ReadonlyArray<{ getter: string }>,
+  memos: ReadonlyArray<{ name: string }>,
+): Set<string> {
+  const names = new Set<string>()
+  for (const s of signals) names.add(s.getter)
+  for (const m of memos) names.add(m.name)
+  return names
+}

package/src/analyzer.ts

@@ -8,6 +8,7 @@
 
 import ts from 'typescript'
 import type { ImportSpecifier, TypeInfo, ParamInfo, ReactiveFactoryInfo } from './types.ts'
+import { parseExpression, parseBlockBodyTolerant, foldBlockToExpr } from './expression-parser.ts'
 import { rewriteBarePropRefs } from './prop-rewrite.ts'
 import { incrementCounter } from './instrumentation.ts'
 import {
@@ -16,9 +17,11 @@ import {
   createAnalyzerContext,
   getSourceLocation,
   typeNodeToTypeInfo,
+  tsTypeToTypeInfo,
   membersToProperties,
   isComponentFunction,
   isArrowComponentFunction,
+  collectReactiveGetterNames,
 } from './analyzer-context.ts'
 import { createError, createWarning, ErrorCodes } from './errors.ts'
 import path from 'node:path'
@@ -260,6 +263,37 @@ export function analyzeComponent(
   // Post-processing validations
   validateContext(ctx)
 
+  // Roadmap A: carry a best-effort structured parse of each signal's initial
+  // value so adapters lower a literal init (`useState(['a', 'b'])`) from the
+  // tree instead of re-parsing the string with `ts.createSourceFile`. The value
+  // is parenthesised before parsing so a bare object-literal init
+  // (`createSignal({ a: 1 })`) resolves to an `object-literal` rather than being
+  // read as a block statement; `parseExpression` unwraps the parens, so arrays /
+  // scalars / prop refs are unchanged. An unsupported shape leaves `parsed`
+  // undefined and the adapter falls back. Runs after `scanImportedClientSignals`
+  // so imported signals are covered too.
+  for (const signal of ctx.signals) {
+    if (!signal.initialValue) continue
+    const parsed = parseExpression(`(${signal.initialValue})`)
+    if (parsed.kind !== 'unsupported') signal.parsed = parsed
+  }
+
+  // #2040: fold a complete, value-producing block-bodied memo into a single
+  // expression so it flows through the same `parsed` path as an expression-bodied
+  // memo, instead of relying on per-idiom block recognizers (#1897 / #1945 /
+  // #2015). Runs after all signals/memos are collected so the reactive-getter
+  // set (used as the purity oracle — an idempotent signal/memo read may be
+  // inlined on several branches) is complete. An incomplete block (the tolerant
+  // parser dropped a statement it couldn't represent) or one that doesn't fold
+  // (imperative residue) leaves `parsed` undefined and consumers keep their
+  // existing `parsedBlock` fallback.
+  const reactiveGetterNames = collectReactiveGetterNames(ctx.signals, ctx.memos)
+  for (const memo of ctx.memos) {
+    if (memo.parsed || !memo.parsedBlock || !memo.parsedBlockComplete) continue
+    const folded = foldBlockToExpr(memo.parsedBlock, { pureCallNames: reactiveGetterNames })
+    if (folded.ok) memo.parsed = folded.expr
+  }
+
   return ctx
 }
 
@@ -960,6 +994,24 @@ const PRIMITIVE_CANONICAL_NAMES: Record<string, 'signal' | 'memo' | 'effect' | '
   createEffect: 'effect',
   onMount: 'onMount',
   onCleanup: 'onCleanup',
+  // Request-scoped env-signal factories (#2057) are `createSignal`-shaped, so
+  // they resolve to the `signal` kind and flow through the normal signal
+  // collection + fold purity oracle. Their env key (see ENV_SIGNAL_FACTORIES)
+  // is recorded separately on the collected signal so adapters can lower the
+  // reader value; the reactivity kind itself is just `signal`.
+  createSearchParams: 'signal',
+}
+
+/**
+ * Env-signal factories → the request-env key their getter reads
+ * (`createSearchParams` → `'search'`, matching the runtime's
+ * `createEnvSignal('search', …)`). Recognising the *factory* is a general
+ * mechanism (like the reactive-primitive names above); the resulting signal is
+ * tagged with the key so adapters lower its reader value from structure, with
+ * no `searchParams`-name allow-list (#2057, superseding #2055).
+ */
+const ENV_SIGNAL_FACTORIES: Record<string, string> = {
+  createSearchParams: 'search',
 }
 
 type PrimitiveKind = (typeof PRIMITIVE_CANONICAL_NAMES)[keyof typeof PRIMITIVE_CANONICAL_NAMES]
@@ -1020,6 +1072,22 @@ function resolveCalleeViaChecker(
   ident: ts.Identifier,
   ctx: AnalyzerContext
 ): PrimitiveKind | null {
+  const name = resolveCanonicalClientExportName(ident, ctx)
+  return name ? (PRIMITIVE_CANONICAL_NAMES[name] ?? null) : null
+}
+
+/**
+ * Resolve an identifier back to the canonical export name it was imported under
+ * from `@barefootjs/client`, following alias chains
+ * (`import { createSignal as sig }`). Returns null when the checker is
+ * unavailable, the symbol doesn't resolve, or its declaration doesn't live in
+ * `@barefootjs/client` — so a user-defined function that happens to share a
+ * name never matches. Shared by the primitive-kind and env-signal resolvers.
+ */
+function resolveCanonicalClientExportName(
+  ident: ts.Identifier,
+  ctx: AnalyzerContext
+): string | null {
   if (!ctx.checker) return null
   let symbol: ts.Symbol | undefined
   try {
@@ -1039,20 +1107,41 @@ function resolveCalleeViaChecker(
       return null
     }
   }
-  const originalName = target.getName()
-  const hit = PRIMITIVE_CANONICAL_NAMES[originalName]
-  if (!hit) return null
   // Confirm the declaration actually lives in @barefootjs/client so we
   // don't match a user-defined function that happens to share the name.
   for (const decl of target.declarations ?? []) {
     const sourceName = decl.getSourceFile().fileName
     if (sourceName.includes('@barefootjs/client') || sourceName.includes('packages/client/')) {
-      return hit
+      return target.getName()
     }
   }
   return null
 }
 
+/**
+ * Resolve a call expression to the request-env key of the env-signal factory it
+ * calls (`createSearchParams()` → `'search'`), or null if it isn't one. Mirrors
+ * {@link resolvePrimitiveKind}'s fast/slow paths (direct name, alias via
+ * checker, `bf.createSearchParams` namespace access) against
+ * {@link ENV_SIGNAL_FACTORIES}.
+ */
+function resolveEnvSignalKey(
+  callExpr: ts.CallExpression,
+  ctx: AnalyzerContext
+): string | null {
+  if (ts.isIdentifier(callExpr.expression)) {
+    const key = ENV_SIGNAL_FACTORIES[callExpr.expression.text]
+    if (key) return key
+    const canonical = resolveCanonicalClientExportName(callExpr.expression, ctx)
+    return canonical ? (ENV_SIGNAL_FACTORIES[canonical] ?? null) : null
+  }
+  if (ts.isPropertyAccessExpression(callExpr.expression)) {
+    const key = ENV_SIGNAL_FACTORIES[callExpr.expression.name.text]
+    if (key && isBarefootClientNamespace(callExpr.expression.expression, ctx)) return key
+  }
+  return null
+}
+
 /**
  * Check whether an expression refers to a namespace import of
  * `@barefootjs/client`, e.g. `import * as bf from '@barefootjs/client'` →
@@ -1127,6 +1216,11 @@ function collectSignal(node: ts.VariableDeclaration, ctx: AnalyzerContext): void
     type = inferTypeFromValue(initialValue)
   }
 
+  const envReader = resolveEnvSignalKey(callExpr, ctx) ?? undefined
+  // The factory as written (identifier, alias, or `ns.factory`), so emit re-emits
+  // the binding actually in scope rather than a hardcoded canonical name (#2057).
+  const envFactory = envReader ? callExpr.expression.getText(ctx.sourceFile) : undefined
+
   ctx.signals.push({
     getter,
     setter,
@@ -1137,6 +1231,8 @@ function collectSignal(node: ts.VariableDeclaration, ctx: AnalyzerContext): void
     initialFreeIdentifiers: callExpr.arguments[0]
       ? extractFreeIdentifiersFromNode(callExpr.arguments[0])
       : new Set(),
+    envReader,
+    envFactory,
   })
 }
 
@@ -1334,6 +1430,28 @@ function isMemoDeclaration(node: ts.VariableDeclaration, ctx: AnalyzerContext):
   return resolvePrimitiveKind(node.initializer, ctx) === 'memo'
 }
 
+/**
+ * Does the memo arrow's effective body resolve to a template literal? Mirrors
+ * the Go adapter's former `isTemplateLiteralMemo` (which re-parsed `computation`
+ * with `ts.createSourceFile`) but runs on the real arrow node at analysis time:
+ * unwrap parens, descend a block body to its first `return`, and check for a
+ * template expression / no-substitution template literal.
+ */
+function memoBodyIsTemplateLiteral(memoArrow: ts.Expression | undefined): boolean {
+  let node: ts.Node | undefined = memoArrow
+  while (node && ts.isParenthesizedExpression(node)) node = node.expression
+  if (!node || !ts.isArrowFunction(node)) return false
+  let body: ts.Node = node.body
+  while (ts.isParenthesizedExpression(body)) body = body.expression
+  if (ts.isBlock(body)) {
+    const ret = body.statements.find(ts.isReturnStatement)
+    if (!ret || !ret.expression) return false
+    body = ret.expression
+    while (ts.isParenthesizedExpression(body)) body = body.expression
+  }
+  return ts.isTemplateExpression(body) || ts.isNoSubstitutionTemplateLiteral(body)
+}
+
 function collectMemo(node: ts.VariableDeclaration, ctx: AnalyzerContext): void {
   const name = (node.name as ts.Identifier).text
   const callExpr = node.initializer as ts.CallExpression
@@ -1363,10 +1481,76 @@ function collectMemo(node: ts.VariableDeclaration, ctx: AnalyzerContext): void {
     }
   }
 
+  // When the syntactic heuristic above can't resolve a precise type
+  // (`object`/`unknown` — e.g. a local-function call or a ternary of typed
+  // arrays), ask the type checker for the memo body's actual type. This is
+  // what lets the Go adapter emit `[][]CalendarDay` / `[]string` / `bool`
+  // instead of `map[string]interface{}` / `bool` placeholders (#1968), so a
+  // typed backend can populate the SSR data. Only upgrades imprecise results —
+  // already-precise syntactic types are left untouched.
+  if (
+    ctx.checker &&
+    (type.kind === 'unknown' || type.kind === 'object') &&
+    callExpr.arguments[0] &&
+    (ts.isArrowFunction(callExpr.arguments[0]) || ts.isFunctionExpression(callExpr.arguments[0]))
+  ) {
+    const fnType = ctx.checker.getTypeAtLocation(callExpr.arguments[0])
+    const sig = fnType.getCallSignatures()[0]
+    if (sig) {
+      const inferred = tsTypeToTypeInfo(ctx.checker.getReturnTypeOfSignature(sig), ctx.checker)
+      if (inferred && inferred.kind !== 'unknown') type = inferred
+    }
+  }
+
+  // Structured parse of the arrow BODY, so adapters can shape-match the memo
+  // on a tree instead of re-parsing `computation`. Parse from the type-STRIPPED
+  // body (`ctx.getJS`, same source as `computation`) — `getText` would keep
+  // TypeScript-only syntax (`as T`, `!`, `satisfies`) that `parseExpression`
+  // rejects, leaving `parsed` undefined for typed bodies that the stripped
+  // `computation` would match. Expression-bodied arrows only — block bodies
+  // (`() => { … }`) and unsupported shapes leave `parsed` undefined and
+  // consumers fall back to `computation`.
+  const memoArrow = callExpr.arguments[0]
+  const parsedBody =
+    memoArrow && ts.isArrowFunction(memoArrow) && !ts.isBlock(memoArrow.body)
+      ? parseExpression(ctx.getJS(memoArrow.body))
+      : undefined
+  // `object-literal` is excluded alongside `unsupported`: an object-returning
+  // memo (`() => ({ … })`) isn't lowered from the parsed tree yet, so leaving
+  // `parsed` undefined keeps the adapter on its existing object-memo lowering
+  // (byte-identical; flipped in a later Roadmap A unit).
+  const parsed =
+    parsedBody && parsedBody.kind !== 'unsupported' && parsedBody.kind !== 'object-literal'
+      ? parsedBody
+      : undefined
+
+  // Block-bodied memos: carry the statements (tolerant — unparseable ones are
+  // omitted) so adapters can pattern-match block shapes (e.g. a guard-and-
+  // return-const memo) without re-parsing `computation`. Unwrap parens around
+  // the arrow to match the former adapter walks.
+  let arrowNode: ts.Node | undefined = memoArrow
+  while (arrowNode && ts.isParenthesizedExpression(arrowNode)) arrowNode = arrowNode.expression
+  const blockBody =
+    arrowNode && ts.isArrowFunction(arrowNode) && ts.isBlock(arrowNode.body)
+      ? arrowNode.body
+      : undefined
+  const parsedBlock = blockBody
+    ? parseBlockBodyTolerant(blockBody, ctx.sourceFile, node => ctx.getJS(node))
+    : undefined
+  // `parseBlockBodyTolerant` runs `parseStatement` once per source statement and
+  // pushes only the non-null results, so equal lengths mean every statement was
+  // represented — nothing silently omitted (see `MemoInfo.parsedBlockComplete`).
+  const parsedBlockComplete =
+    parsedBlock && blockBody ? parsedBlock.length === blockBody.statements.length : undefined
+
   ctx.memos.push({
     name,
     computation,
+    parsedBlock,
+    parsedBlockComplete,
     typedComputation: typedComputation !== computation ? typedComputation : undefined,
+    parsed,
+    bodyIsTemplateLiteral: memoBodyIsTemplateLiteral(memoArrow),
     type,
     deps,
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
@@ -1648,10 +1832,15 @@ const CLIENT_EXPORTS = new Set([
   'forwardProps', 'unwrap', '__slot',
   'createContext', 'useContext', 'provideContext',
   'createPortal', 'isSSRPortal', 'findSiblingSlot', 'cleanupPortalPlaceholder',
-  // Request-scoped environment signal (router v0.5) — a real user-facing
-  // reactive export the compiler lowers like any other `@barefootjs/client`
-  // signal read (SSR: a template binding; client: a `createEffect`).
-  'searchParams',
+  // Request-scoped environment signal factory (router v0.5) — `createSignal`-
+  // shaped, recognised structurally (#2057) so its getter is just a signal
+  // getter; the compiler lowers the reader value per adapter via the signal's
+  // `envReader` key, with no `searchParams`-name allow-list.
+  'createSearchParams',
+  // Pure URL-query builder (#2042) — the functional counterpart to
+  // `searchParams`. Runs natively on the client; SSR adapters lower a
+  // `queryHref(base, { … })` call to their query helper (go-template: `bf_query`).
+  'queryHref',
   // Compile-away JSX built-ins (#1915) — importing them is what scopes the
   // compiler's `<Async>` / `<Region>` recognition; the import is elided on emit.
   'Async', 'Region',
@@ -2713,9 +2902,28 @@ function collectConstant(
     }
   }
 
+  // Structure a module-scope constant's value for adapters (Roadmap A). Only
+  // module consts are carried — they're the ones adapters resolve as
+  // compile-time records (e.g. a `strokePaths` icon map). Parse the
+  // PARENTHESISED value so a bare object literal (`{ … }`), which TS reads as
+  // a block at statement position, resolves to an `object-literal` instead of
+  // failing. Best-effort and inert for inlined JSX (no usable value tree).
+  //
+  // Carried for component-scope consts too (#2018 P5): the Go constructor
+  // lowerers (`lowerCtorExpr`, helper inlining) read this single generic tree —
+  // which now models the multi-param-arrow and regex shapes the former
+  // Go-only `parsed2` carried — to inline a derived component const's value
+  // (`base || '/'`) recursively. Best-effort; an unrepresentable shape leaves
+  // `parsed` undefined and consumers fall back to the string.
+  const parsed =
+    value && !isJsx && !isJsxFunction
+      ? parseExpression(`(${value.trim()})`)
+      : undefined
+
   ctx.localConstants.push({
     name,
     value,
+    parsed,
     typedValue: typedValue !== value ? typedValue : undefined,
     valueBranches,
     declarationKind,
@@ -3097,8 +3305,11 @@ function validateContext(ctx: AnalyzerContext): void {
   // their implementations live in `@barefootjs/client/runtime` and require
   // compiler emission to run correctly.
   if (!ctx.hasUseClientDirective) {
+    // Env signals (`createSearchParams()`, #2057) are exempt: reading the
+    // request query is SSR-safe and hydrates without `use client`, exactly as
+    // the pre-#2057 bare `searchParams()` import did (it was not a signal).
     const usesBrowserOnlyApi =
-      ctx.signals.length > 0 || importsBrowserOnlyClientApi(ctx)
+      ctx.signals.some(s => !s.envReader) || importsBrowserOnlyClientApi(ctx)
     if (usesBrowserOnlyApi) {
       ctx.errors.push(
         createError(ErrorCodes.MISSING_USE_CLIENT, {
@@ -3827,6 +4038,12 @@ export function validateReactiveFactoryCalls(ctx: AnalyzerContext): void {
       if (!ts.isIdentifier(decl.initializer.expression)) continue
       const callee = decl.initializer.expression.text
       if (callee === 'createSignal' || callee === 'createMemo') continue
+      // Env-signal factories (`createSearchParams`, #2057) are `createSignal`-
+      // shaped and recognised structurally — a valid tuple destructure. Resolve
+      // via the same path as recognition (`resolveEnvSignalKey`) so an aliased
+      // import (`import { createSearchParams as csp }`) is accepted here too,
+      // rather than falling through to a spurious BF110.
+      if (resolveEnvSignalKey(decl.initializer, ctx)) continue
       // Inlined factories were rewritten away before this analysis, so
       // anything still matching the shape is a destructure of an
       // unrecognised callee (imported helper, ad-hoc tuple fn, factory

package/src/builtin-lowering-plugins.ts

@@ -0,0 +1,54 @@
+/**
+ * Built-in lowering plugins — shipped with the compiler and applied by default,
+ * with no `barefoot.config.ts` registration required (#2057).
+ *
+ * These use the *exact same* {@link LoweringPlugin} seam as userland plugins.
+ * "Built-in" means only that the compiler registers them itself, so consumers
+ * get them for free. This is deliberate: it keeps a first-party API like
+ * `queryHref` from being a bespoke special-case branch in every adapter. Instead
+ * of each adapter carrying an `if (isQueryHref) …` recognizer, `queryHref` is a
+ * pre-registered plugin — indistinguishable, at the adapter, from any other. The
+ * adapters have one path (registry matcher → neutral node → render), and the
+ * only queryHref-specific knowledge left is the plugin registration below.
+ */
+
+import type { LoweringPlugin } from './lowering-registry.ts'
+import { registerLoweringPlugin } from './lowering-registry.ts'
+import { queryHrefLocalNames } from './adapters/env-signal.ts'
+import { matchQueryHrefCall } from './query-href-lowering.ts'
+
+/**
+ * `queryHref(base, { … })` — the pure URL-query builder (#2042). Its runtime
+ * lives in `@barefootjs/client`; this plugin recognises the call structurally
+ * and returns a backend-neutral `guard-list` on the `query` helper, which each
+ * adapter maps to its own runtime helper (`bf_query` / `bf->query` / `$bf.query`).
+ * `prepare` resolves the local names `queryHref` is imported under once per
+ * component; a component that never imports it gets no matcher (the adapter skips
+ * it entirely).
+ */
+export const queryHrefPlugin: LoweringPlugin = {
+  name: 'queryHref',
+  prepare(metadata) {
+    const locals = queryHrefLocalNames(metadata)
+    if (locals.size === 0) return null
+    return (callee, args) => {
+      const q = matchQueryHrefCall(callee, args, locals)
+      return q
+        ? { kind: 'guard-list', helper: 'query', base: q.base, triples: q.triples }
+        : null
+    }
+  },
+}
+
+/** Every plugin the compiler ships and applies by default. */
+export const BUILTIN_LOWERING_PLUGINS: readonly LoweringPlugin[] = [queryHrefPlugin]
+
+/**
+ * Register the built-in plugins into the shared registry. Called for its side
+ * effect when `@barefootjs/jsx` is loaded (see `index.ts`), so adapters see
+ * `queryHref` without any explicit setup. Idempotent — `registerLoweringPlugin`
+ * dedups by name, so re-invoking (e.g. after a test reset) can't stack copies.
+ */
+export function registerBuiltinLoweringPlugins(): void {
+  for (const plugin of BUILTIN_LOWERING_PLUGINS) registerLoweringPlugin(plugin)
+}