@barefootjs/jsx 0.15.2 → 0.17.0

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   IRProp,
   ParamInfo,
   PropertyInfo,
+  MemoInfo,
   TypeInfo,
   TypeDefinition,
   SourceLocation,
@@ -76,7 +77,29 @@ export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
 export { emitParsedExpr } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
-export { importsSearchParams, searchParamsLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export { importsSearchParams, searchParamsLocalNames, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export { matchQueryHrefCall, queryHrefArgs, type QueryHrefCall, type QueryHrefTriple } from './query-href-lowering.ts'
+export {
+  registerLoweringPlugin,
+  getLoweringPlugins,
+  prepareLoweringMatchers,
+  matchLoweringCall,
+  __resetLoweringPluginsForTest,
+  type LoweringPlugin,
+  type LoweringNode,
+  type LoweringTriple,
+  type LoweringMatcher,
+} from './lowering-registry.ts'
+export {
+  queryHrefPlugin,
+  registerBuiltinLoweringPlugins,
+  BUILTIN_LOWERING_PLUGINS,
+} from './builtin-lowering-plugins.ts'
+// Register the built-in lowering plugins (queryHref, …) into the shared registry
+// on load, so every adapter that imports @barefootjs/jsx recognises them with no
+// explicit setup — queryHref is a default-applied plugin, not an adapter branch.
+import { registerBuiltinLoweringPlugins as __registerBuiltins } from './builtin-lowering-plugins.ts'
+__registerBuiltins()
 export { emitIRNode } from './adapters/ir-node-emitter.ts'
 export type { IRNodeEmitter, EmitIRNode } from './adapters/ir-node-emitter.ts'
 export { emitAttrValue } from './adapters/attr-value-emitter.ts'
@@ -253,9 +276,9 @@ export {
 export { ErrorCodes, createError, formatError, generateCodeFrame } from './errors.ts'
 
 // Expression Parser
-export { parseExpression, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember } from './expression-parser.ts'
+export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'
-export type { ParsedExpr, ParsedStatement, SortComparator, SortKey, ReduceOp, FlatDepth, FlatMapOp, FlatMapLeaf, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
+export type { ParsedExpr, ObjectLiteralProperty, ParsedStatement, SortComparator, SortKey, FlatDepth, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
 export { buildLoopChainExpr } from './loop-chain.ts'
 export type { LoopChainInputs } from './loop-chain.ts'
 export { isLowerableObjectRestDestructure } from './loop-destructure.ts'
@@ -308,6 +331,7 @@ export {
   formatWastedReReruns,
   analyzeBatchAdvisor,
   formatBatchAdvisor,
+  evaluateProfileGates,
 } from './profiler.ts'
 export type {
   StaticBudget,
@@ -335,6 +359,14 @@ export type {
   BatchAdvisorResult,
   BatchCandidate,
   BatchSafety,
+  ProfileSeverity,
+  ProfileStatus,
+  AgentFinding,
+  ScenarioGuidance,
+  GateName,
+  GateConfig,
+  GateCheck,
+  GateResult,
 } from './profiler.ts'
 
 // Reactive profile — findings layer (#1690 dogfood: Bug A/C/D fixes, batch-candidate dedup,

package/src/ir-to-client-js/csr-substitute.ts

@@ -380,6 +380,11 @@ export function buildSignalMemoEnv(
 ): CsrEnv {
   const substitutions = new Map<string, CsrSubstitution>()
   for (const s of signals) {
+    // Env signals (#2057) have no static initial value to bake — their getter
+    // is a live request-scoped read (`searchParams().get(k)`). Leave it in the
+    // CSR template as a real call, exactly as the pre-#2057 bare `searchParams()`
+    // import was (it was never a substitutable signal).
+    if (s.envReader) continue
     substitutions.set(s.getter, {
       kind: 'call',
       replacement: normalizeSignalInitial(s, propsObjectName),

package/src/ir-to-client-js/plan/build-declaration-emit.ts

@@ -13,6 +13,7 @@ import type { Declaration } from '../declaration-sort.ts'
 import type { ClientJsContext } from '../types.ts'
 import type { ParamInfo, SignalInfo } from '../../types.ts'
 import { inferDefaultValue, PROPS_PARAM } from '../utils.ts'
+import { ENV_SIGNAL_CLIENT_FACTORY } from '../../adapters/env-signal.ts'
 import type {
   ControlledSignalEffectPlan,
   DeclarationEmitPlan,
@@ -85,6 +86,21 @@ function buildSignalPlan(
   ctx: ClientJsContext,
   lookups: DeclarationEmitLookups,
 ): SignalEmitPlan {
+  if (signal.envReader) {
+    // Emit the factory as written (alias / namespace aware, #2057), falling back
+    // to the canonical name if the callee text wasn't captured.
+    const factory = signal.envFactory ?? ENV_SIGNAL_CLIENT_FACTORY[signal.envReader]
+    if (factory) {
+      return {
+        kind: 'signal',
+        getter: signal.getter,
+        setter: signal.setter,
+        initialValueExpr: '',
+        controlledEffect: null,
+        initializerOverride: `${factory}()`,
+      }
+    }
+  }
   const controlledEffect = buildControlledSignalEffect(signal, lookups)
   if (controlledEffect && ctx.profile) {
     controlledEffect.bfId = `${ctx.componentName}#effect:controlled:${signal.setter}`

package/src/ir-to-client-js/plan/declaration-emit.ts

@@ -54,6 +54,15 @@ export interface SignalEmitPlan {
   branchCondition?: string
   /** Profile-mode IR-aligned id, appended as the `createSignal` 2nd arg (#1690). */
   bfId?: string
+  /**
+   * When set, the full initializer expression to emit verbatim instead of
+   * `createSignal(<initialValueExpr>)`. Env signals (#2057) emit their own
+   * factory call — e.g. `createSearchParams()` — with no baked initial value,
+   * profile id, controlled effect, or branch condition (the tuple is a stable
+   * request-scoped view, not stored state). When present the stringifier emits
+   * `const [<getter>, <setter>] = <initializerOverride>` and nothing else.
+   */
+  initializerOverride?: string
 }
 
 export interface ControlledSignalEffectPlan {

package/src/ir-to-client-js/stringify/declaration-emit.ts

@@ -65,6 +65,17 @@ function bfIdArg(bfId: string | undefined): string {
 }
 
 function emitSignal(lines: string[], plan: SignalEmitPlan): void {
+  // Env signal (#2057): emit its own factory call verbatim (`createSearchParams()`)
+  // — a stable request-scoped view, so no baked initial value, profile id,
+  // controlled effect, or branch condition applies.
+  if (plan.initializerOverride) {
+    if (plan.setter) {
+      lines.push(`  const [${plan.getter}, ${plan.setter}] = ${plan.initializerOverride}`)
+    } else {
+      lines.push(`  const [${plan.getter}] = ${plan.initializerOverride}`)
+    }
+    return
+  }
   const id = bfIdArg(plan.bfId)
   if (plan.branchCondition) {
     // #1414 cell #8: signal declared inside an early-return `if`-block.

package/src/jsx-to-ir.ts

@@ -32,8 +32,9 @@ import {
   isReactiveOrigin,
   AttrValueOf,
 } from './types.ts'
-import { type AnalyzerContext, type MultiReturnJsxInfo, getSourceLocation } from './analyzer-context.ts'
-import { parseExpression, isSupported, parseBlockBody, extractSortComparatorFromTS, cssKebabCase, type ParsedExpr, type ParsedStatement, type SortComparator } from './expression-parser.ts'
+import { type AnalyzerContext, type MultiReturnJsxInfo, getSourceLocation, collectReactiveGetterNames } from './analyzer-context.ts'
+import { parseExpression, isSupported, parseBlockBody, foldBlockToExpr, predicateTernaryToLogical, tsNodeToParsedExpr, sortComparatorFromArrow, stringifyParsedExpr, cssKebabCase, type ParsedExpr } from './expression-parser.ts'
+import type { IRLoopSort } from './types.ts'
 import { createError, ErrorCodes, internalInvariant } from './errors.ts'
 import { CLIENT_BUILTIN_SOURCE, isClientBuiltinName, type ClientBuiltinTag } from './builtins.ts'
 import { containsReactiveExpression } from './reactivity-checker.ts'
@@ -186,18 +187,25 @@ function hasLeadingClientDirective(expr: ts.Expression, sourceFile: ts.SourceFil
   return false
 }
 
+/**
+ * The set of known reactive getter names (signal accessors + memo names) for the
+ * component, built once and cached on `ctx`. These reads are idempotent within a
+ * render, so consumers can treat `getter()` as a pure value (e.g. the block-fold
+ * purity oracle in {@link extractFilterPredicate}).
+ */
+function getReactiveGetterNames(ctx: TransformContext): Set<string> {
+  if (!ctx._reactiveGetterNames) {
+    ctx._reactiveGetterNames = collectReactiveGetterNames(ctx.analyzer.signals, ctx.analyzer.memos)
+  }
+  return ctx._reactiveGetterNames
+}
+
 /**
  * Walk an expression AST to check if it calls any known signal getter or memo.
  * Uses a pre-built Set for O(1) lookup per call expression.
  */
 function exprCallsReactiveGetters(expr: ts.Expression, ctx: TransformContext): boolean {
-  // Build reactive name set once per component (cached on ctx)
-  if (!ctx._reactiveGetterNames) {
-    ctx._reactiveGetterNames = new Set<string>()
-    for (const s of ctx.analyzer.signals) ctx._reactiveGetterNames.add(s.getter)
-    for (const m of ctx.analyzer.memos) ctx._reactiveGetterNames.add(m.name)
-  }
-  const names = ctx._reactiveGetterNames
+  const names = getReactiveGetterNames(ctx)
 
   let found = false
   function visit(n: ts.Node) {
@@ -554,7 +562,112 @@ function makeBindingEnv(ctx: TransformContext): BindingEnvironment {
 // Main Entry Point
 // =============================================================================
 
+/**
+ * Parse an attribute / prop / provider value expression. An inline object
+ * literal (`opts={{ align: 'start' }}`, `style={{ … }}`) parses as a block
+ * statement unless parenthesized, so a bare `{ … }` would land as `unsupported`
+ * instead of `object-literal` — the adapters that lower an inline object value
+ * (Go `objectLiteralToGoMap`, Perl `objectLiteralExprToPerlHashref`) then refuse
+ * it (BF101). Wrap a `{`-leading value in parens so it parses as the
+ * `object-literal` they expect; every other expression is unaffected (redundant
+ * parens are stripped on parse).
+ */
+function parseValueExpr(trimmed: string): ParsedExpr {
+  return parseExpression(trimmed.startsWith('{') ? `(${trimmed})` : trimmed)
+}
+
+/**
+ * Attach `parsed` (`parseExpression(expr.trim())`) to every `expression` node
+ * in the tree, so SSR adapters emit from the structured tree instead of each
+ * re-parsing the string at emit time. Best-effort: a node this walk misses (or
+ * an empty `expr`) simply has no `parsed`, and the adapter falls back to
+ * parsing — so under-coverage is safe, never a behavioural change.
+ */
+function attachParsedExpressions(node: IRNode): void {
+  if (node.type === 'expression') {
+    const trimmed = node.expr.trim()
+    if (trimmed) node.parsed = parseExpression(trimmed)
+  } else if (node.type === 'conditional' || node.type === 'if-statement') {
+    const trimmed = node.condition.trim()
+    if (trimmed) node.parsedCondition = parseExpression(trimmed)
+  }
+  // Attach `parsed` to every expression-valued attribute / prop so adapters can
+  // lower from the tree instead of re-parsing the string. Element attrs,
+  // component props (e.g. `opts={{ … }}` → Go map), and a provider's `value`
+  // prop all carry it; only `expression` values do (a `spread` / `template`
+  // value can't be the inline object literal the consumers read).
+  if (node.type === 'element') {
+    for (const attr of node.attrs) {
+      if (attr.value.kind === 'expression') {
+        const trimmed = attr.value.expr.trim()
+        if (trimmed) attr.value.parsed = parseValueExpr(trimmed)
+      } else if (attr.value.kind === 'spread') {
+        const trimmed = attr.value.expr.trim()
+        if (trimmed) attr.value.parsed = parseExpression(trimmed)
+      }
+    }
+  } else if (node.type === 'component') {
+    for (const prop of node.props) {
+      if (prop.value.kind === 'expression') {
+        const trimmed = prop.value.expr.trim()
+        if (trimmed) prop.value.parsed = parseValueExpr(trimmed)
+      }
+    }
+  } else if (node.type === 'provider') {
+    if (node.valueProp.value.kind === 'expression') {
+      const trimmed = node.valueProp.value.expr.trim()
+      if (trimmed) node.valueProp.value.parsed = parseValueExpr(trimmed)
+    }
+  }
+  switch (node.type) {
+    case 'element':
+    case 'component':
+    case 'fragment':
+    case 'provider':
+      for (const child of node.children) attachParsedExpressions(child)
+      break
+    case 'async':
+      attachParsedExpressions(node.fallback)
+      for (const child of node.children) attachParsedExpressions(child)
+      break
+    case 'loop': {
+      // Attach the parse of the SAME `array` string the adapters consume
+      // (the Go adapter's scalar-literal loop typing reads `loop.array` /
+      // `nested.loopArray`, which is exactly `loop.array`), so it can read
+      // the tree instead of re-parsing with `ts.createSourceFile`.
+      const trimmedArray = node.array.trim()
+      if (trimmedArray) node.arrayParsed = parseExpression(trimmedArray)
+      for (const child of node.children) attachParsedExpressions(child)
+      // Loops also hold expression nodes off the main `children` array.
+      if (node.childComponent) {
+        for (const child of node.childComponent.children) attachParsedExpressions(child)
+      }
+      for (const nested of node.nestedComponents ?? []) {
+        for (const child of nested.children) attachParsedExpressions(child)
+      }
+      for (const frag of node.flatMapCallback?.fragments ?? []) {
+        attachParsedExpressions(frag.ir)
+      }
+      break
+    }
+    case 'conditional':
+      attachParsedExpressions(node.whenTrue)
+      attachParsedExpressions(node.whenFalse)
+      break
+    case 'if-statement':
+      attachParsedExpressions(node.consequent)
+      if (node.alternate) attachParsedExpressions(node.alternate)
+      break
+  }
+}
+
 export function jsxToIR(analyzer: AnalyzerContext): IRNode | null {
+  const root = buildIRRoot(analyzer)
+  if (root) attachParsedExpressions(root)
+  return root
+}
+
+function buildIRRoot(analyzer: AnalyzerContext): IRNode | null {
   // If there are conditional returns (if statements with JSX returns),
   // build an if-statement chain instead of a single node
   if (analyzer.conditionalReturns.length > 0) {
@@ -2313,58 +2426,71 @@ function isIteratorShapeCall(
 }
 
 type SortExtractionResult = {
-  result: SortComparator | null
+  result: IRLoopSort | null
   unsupportedReason?: string
 }
 
 /**
  * Extract sort comparator info from a `.sort(cmp)` / `.toSorted(cmp)`
- * callback at the chained `.sort().map()` detection site. Delegates
- * to `extractSortComparatorFromTS` (#1448 Tier B) — the shared shape
- * also feeds the standalone `array-method` IR variant emitted by
- * `expression-parser.ts`. Accepted comparator catalogue: simple
- * subtraction (`a.f - b.f`, `a - b`, reverse for desc) and
- * `.localeCompare` (`a.localeCompare(b)`, `a.f.localeCompare(b.f)`,
- * reverse for desc).
+ * callback at the chained `.sort().map()` detection site (#2018 P5). Parses the
+ * callback into a generic `arrow` (params + body) and gates the loop-hoist on
+ * the same finite catalogue `sortComparatorFromArrow` recognises (so a
+ * comparator the localeCompare fallback can't model stays client-side, exactly
+ * as before). The carried {@link IRLoopSort} feeds the SSR adapter's evaluator
+ * (eval-first) and the client's JS round-trip. Accepted catalogue: subtraction
+ * (`a.f - b.f`, `a - b`, reverse for desc), `.localeCompare`, and the
+ * relational-ternary sign forms; any of them `||`-chained for multi-key.
  */
 function extractSortComparator(
   callback: ts.Expression,
-  method: 'sort' | 'toSorted',
+  _method: 'sort' | 'toSorted',
   ctx: TransformContext
 ): SortExtractionResult {
+  const unsupported = (): SortExtractionResult => {
+    // Surface the OUTER callback source — users see the string they wrote.
+    const raw = ctx.getJS(callback)
+    return {
+      result: null,
+      unsupportedReason:
+        `Sort comparator '${raw}' is not a supported shape. Accepted:\n` +
+        `  (a, b) => a - b\n` +
+        `  (a, b) => a.field - b.field\n` +
+        `  (a, b) => a.localeCompare(b)\n` +
+        `  (a, b) => a.field.localeCompare(b.field)\n` +
+        `  (a, b) => a.field > b.field ? 1 : a.field < b.field ? -1 : 0\n` +
+        `  any of the above '||'-chained for multi-key tie-breaks\n` +
+        `(reverse the operands for descending order).`,
+    }
+  }
   if (!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) {
     return {
       result: null,
       unsupportedReason: 'Sort comparator must be an arrow function or function expression',
     }
   }
-  const result = extractSortComparatorFromTS(callback, method)
-  if (result) return { result }
-  // For the unsupported-reason message, the OUTER callback source is
-  // more useful to surface than the body — users see the same string
-  // they wrote. The extractor's own `raw` (body-only) is for the
-  // server-side / @client lowering paths, which only run on success.
-  const raw = ctx.getJS(callback)
+  const arrow = tsNodeToParsedExpr(callback)
+  if (arrow.kind !== 'arrow' || arrow.params.length !== 2) return unsupported()
+  // Gate on the same catalogue the localeCompare fallback recovers, so the
+  // hoist decision (and thus the SSR/client split) is byte-for-byte unchanged.
+  if (sortComparatorFromArrow(arrow) === null) return unsupported()
   return {
-    result: null,
-    unsupportedReason:
-      `Sort comparator '${raw}' is not a supported shape. Accepted:\n` +
-      `  (a, b) => a - b\n` +
-      `  (a, b) => a.field - b.field\n` +
-      `  (a, b) => a.localeCompare(b)\n` +
-      `  (a, b) => a.field.localeCompare(b.field)\n` +
-      `(reverse the operands for descending order).`,
+    result: {
+      arrow,
+      paramA: arrow.params[0],
+      paramB: arrow.params[1],
+      raw: stringifyParsedExpr(arrow.body),
+    },
   }
 }
 
 /**
- * Result type for extractFilterPredicate.
- * Either has an expression body (predicate) or block body (blockBody).
+ * Result type for extractFilterPredicate. The predicate is always an expression:
+ * a block body is normalized to one via `foldBlockToExpr` +
+ * `predicateTernaryToLogical` (#2040).
  */
 type FilterPredicateResult = {
   param: string
-  predicate?: ParsedExpr        // Expression body
-  blockBody?: ParsedStatement[] // Block body
+  predicate?: ParsedExpr
   raw: string
 }
 
@@ -2426,7 +2552,7 @@ function extractFilterPredicate(
     if (parsed.kind === 'unsupported') {
       return { result: null, unsupportedReason: parsed.reason }
     }
-    if (parsed.kind === 'arrow-fn') {
+    if (parsed.kind === 'arrow') {
       const support = isSupported(parsed.body)
       if (!support.supported) {
         return { result: null, unsupportedReason: support.reason }
@@ -2437,16 +2563,29 @@ function extractFilterPredicate(
 
   const param = firstParam.name.getText(ctx.sourceFile)
 
-  // Block body arrow functions: filter(t => { const f = filter(); ... })
+  // Block body arrow functions: filter(t => { const f = filter(); ... }).
+  // Normalize the value-producing block into a single boolean predicate
+  // expression (#2040): let-inline + early-return/`if` → ternary, then the
+  // boolean-context ternary → `&&`/`||` so it flows through the same expression
+  // predicate path as `filter(t => !t.done)` — no per-adapter block-condition
+  // renderer. Idempotent reactive getter reads (`const f = filter()`) are
+  // treated as pure so a signal read on several branches still folds.
   if (ts.isBlock(callback.body)) {
     const raw = ctx.getJS(callback.body)
     const statements = parseBlockBody(callback.body, ctx.sourceFile, (n) => ctx.getJS(n))
     if (!statements) {
       return { result: null, unsupportedReason: 'Block body filter predicate cannot be parsed for server-side rendering' }
     }
-    // TODO: Check if all statements are supported for SSR
-    // For now, if parseBlockBody succeeds, we assume it's supported
-    return { result: { param, blockBody: statements, raw } }
+    const folded = foldBlockToExpr(statements, { pureCallNames: getReactiveGetterNames(ctx) })
+    if (!folded.ok) {
+      return { result: null, unsupportedReason: folded.reason }
+    }
+    const predicate = predicateTernaryToLogical(folded.expr)
+    const support = isSupported(predicate)
+    if (!support.supported) {
+      return { result: null, unsupportedReason: support.reason }
+    }
+    return { result: { param, predicate, raw } }
   }
 
   // Expression body: filter(t => !t.done)
@@ -2996,7 +3135,7 @@ function transformMapCall(
   // matches the fallback path at the bottom of this if/else chain.
   let arrayExpr: ts.Expression = mapSource
   let filterPredicate: FilterPredicateResult | undefined
-  let sortComparator: SortComparator | undefined
+  let sortComparator: IRLoopSort | undefined
   let chainOrder: 'filter-sort' | 'sort-filter' | undefined
   let mapPreamble: string | undefined
   let templateMapPreamble: string | undefined

package/src/lowering-registry.ts

@@ -0,0 +1,160 @@
+/**
+ * Call-lowering plugin registry (#2057).
+ *
+ * The compiler core carries no bespoke per-API recognition branches. Instead, a
+ * lowering plugin *recognises* a call — by the import it comes from and its
+ * argument shape — and returns a **backend-neutral `LoweringNode`**. Each adapter
+ * renders that node in its own template syntax. This is a deliberate two-layer
+ * split:
+ *
+ *   - **Layer 1 (this module + plugins):** adapter-agnostic. A plugin matches a
+ *     call to a neutral node and never mentions Go/Perl/… syntax.
+ *   - **Layer 2 (adapters):** plugin-agnostic. Each adapter has ONE renderer per
+ *     node kind, so SSR/CSR parity is enforced once, not per plugin.
+ *
+ * Everything flows through this one seam — including first-party APIs. A
+ * userland package registers its plugin via {@link registerLoweringPlugin}, and
+ * a built-in like `queryHref` is registered by the compiler *as a default
+ * plugin* (see `builtin-lowering-plugins.ts`), not as an adapter branch. So an
+ * adapter can't tell a shipped API from a third-party one: both are just entries
+ * in this registry. That uniformity is the point — there is no "special" path to
+ * keep in sync.
+ *
+ * This is NOT the "output-rewriting hook" CLAUDE.md forbids: a plugin returns a
+ * structured IR node, never a rewritten output string, so the compiler's output
+ * stays determined by the compiler, not by whatever munges the emitted text.
+ */
+
+import type { ParsedExpr } from './expression-parser.ts'
+import type { IRMetadata } from './types.ts'
+
+/**
+ * A backend-neutral include triple for a {@link LoweringNode} `guard-list`.
+ * `guard` is the conditional test of a `key: cond ? v : <omit>` include, or null
+ * for a plain `key: v` (included purely on value-truthiness). An adapter renders
+ * the guard to decide inclusion; the *runtime helper* then applies the emptiness
+ * / array-append rules to the value. (Structurally identical to the query-href
+ * lowering's own triple, which the `queryHref` plugin passes through unchanged.)
+ */
+export interface LoweringTriple {
+  guard: ParsedExpr | null
+  key: string
+  value: ParsedExpr
+}
+
+/**
+ * A backend-neutral lowering result. Adapters render each variant in their own
+ * template language; the shapes carry everything a renderer needs and nothing
+ * adapter-specific.
+ */
+export type LoweringNode =
+  /**
+   * A guard/key/value include list lowered to a query helper — the shape of
+   * `queryHref(base, { … })`. `helper` is the logical helper id (`'query'`),
+   * which each adapter maps to its own runtime helper (`bf_query` in go,
+   * `bf->query` in mojo, `$bf.query` in xslate). Each triple's `guard` controls
+   * inclusion; the runtime helper then applies the non-empty / array-append
+   * rules to the value (so an included-but-empty value is dropped and array
+   * members are appended), matching the client `queryHref` exactly. Adapters
+   * MUST switch on `helper` — a `guard-list` is not implicitly `query`.
+   */
+  | { kind: 'guard-list'; helper: string; base: ParsedExpr; triples: LoweringTriple[] }
+  /**
+   * A plain helper call `helper(...args)` — the general escape hatch for a pure
+   * builder that lowers to a single runtime-helper invocation. Unused today;
+   * present so the neutral vocabulary isn't single-purpose.
+   */
+  | { kind: 'helper-call'; helper: string; args: readonly ParsedExpr[] }
+
+/**
+ * A matcher bound to one component's metadata: given a parsed call's callee +
+ * args, returns a neutral node or null to decline. Produced by a plugin's
+ * {@link LoweringPlugin.prepare} so the per-component import-name resolution runs
+ * once (at adapter init), not on every emit.
+ */
+export type LoweringMatcher = (
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+) => LoweringNode | null
+
+/**
+ * A lowering plugin. `prepare` resolves the local names its import is bound
+ * under in this component and returns a bound {@link LoweringMatcher}, or null
+ * when the component doesn't use it (so the adapter skips it entirely). A
+ * plugin never emits adapter syntax — only neutral nodes.
+ */
+export interface LoweringPlugin {
+  /** Stable id, for dedup/diagnostics (e.g. `'my-pkg-url'`). */
+  name: string
+  prepare(metadata: IRMetadata): LoweringMatcher | null
+}
+
+const plugins: LoweringPlugin[] = []
+
+/**
+ * Register a lowering plugin. Idempotent by `name` — re-registering the same
+ * name replaces the prior plugin, so a double side-effect import can't stack
+ * duplicates. First-party packages call this at module load.
+ */
+export function registerLoweringPlugin(plugin: LoweringPlugin): void {
+  const existing = plugins.findIndex(p => p.name === plugin.name)
+  if (existing >= 0) plugins[existing] = plugin
+  else plugins.push(plugin)
+}
+
+/** The registered plugins, in registration order (a copy — mutating the result
+ *  can't reorder or corrupt the registry). */
+export function getLoweringPlugins(): readonly LoweringPlugin[] {
+  return [...plugins]
+}
+
+/**
+ * Bind every registered plugin to a component's metadata, returning the matchers
+ * that are active for it (import present). Adapters call this once at init and
+ * store the result, then try each matcher on the calls they lower — replacing a
+ * hardcoded per-API recognizer.
+ */
+export function prepareLoweringMatchers(metadata: IRMetadata): LoweringMatcher[] {
+  const matchers: LoweringMatcher[] = []
+  for (const plugin of plugins) {
+    const matcher = plugin.prepare(metadata)
+    if (matcher) matchers.push(matcher)
+  }
+  return matchers
+}
+
+/**
+ * Convenience one-shot match against all registered plugins for a given
+ * metadata. Prefer {@link prepareLoweringMatchers} on a hot path (it resolves
+ * import names once); this re-resolves per call and is meant for tests / cold
+ * call sites.
+ */
+export function matchLoweringCall(
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+  metadata: IRMetadata,
+): LoweringNode | null {
+  for (const matcher of prepareLoweringMatchers(metadata)) {
+    const node = matcher(callee, args)
+    if (node) return node
+  }
+  return null
+}
+
+/**
+ * Test-only: replace the registry contents wholesale. The double-underscore
+ * prefix marks it as an internal seam — tests use it to restore global state in
+ * `afterEach` so a sample plugin can't leak into other suites. Never call from
+ * production code.
+ */
+export function __resetLoweringPluginsForTest(next: readonly LoweringPlugin[] = []): void {
+  plugins.length = 0
+  plugins.push(...next)
+}
+
+// The compiler ships built-in plugins (e.g. `queryHref`) and registers them here
+// by default — see `builtin-lowering-plugins.ts`, wired up on load in `index.ts`.
+// Both first-party built-ins and userland plugins go through this one registry,
+// so adapters have a single uniform path with no special-cased API branch. See
+// the sample plugin + tests in `__tests__/lowering-registry.test.ts` for the
+// guaranteed contract.