@barefootjs/jinja 0.1.0

package/src/__tests__/jinja-spread-attrs.test.ts

@@ -0,0 +1,225 @@
+/**
+ * JinjaAdapter — conditional-spread / nullish-omission / hyphenated-key
+ * regression tests (#textarea / #checkbox Phase 2b parity).
+ *
+ * Ported from `packages/adapter-xslate/src/__tests__/xslate-spread-attrs.test.ts`,
+ * translating each expected template string to Jinja syntax. The shared
+ * adapter-conformance fixtures (`textarea`, `checkbox`) only exercise the
+ * falsy branch of the conditional spread and the unset branch of the
+ * optional attr, so these unit tests pin the truthy / present branches the
+ * fixtures can't reach.
+ *
+ * One test (`hyphenated child attr hash key`) is NOT a byte-for-byte
+ * translation: Jinja dict-literal keys are ALWAYS quoted (`jinjaHashKey`
+ * unconditionally single-quotes, unlike Kolon's bareword-key sugar —
+ * `{key: value}` in Jinja/Python means "look up variable `key`", not the
+ * string `"key"` — see `lib/jinja-naming.ts`'s docstring), so there is no
+ * "stays unquoted" case to assert for a bare-identifier-safe prop name like
+ * `size`; only that BOTH keys are correctly quoted.
+ */
+
+import { test, expect, describe } from 'bun:test'
+import { compileJSX } from '@barefootjs/jsx'
+import type { ComponentIR } from '@barefootjs/jsx'
+import { JinjaAdapter } from '../adapter'
+
+function compileToIR(source: string, adapter?: JinjaAdapter): ComponentIR {
+  const result = compileJSX(source.trimStart(), 'test.tsx', {
+    adapter: 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, adapter?: JinjaAdapter) {
+  const a = adapter ?? new JinjaAdapter()
+  const ir = compileToIR(source, a)
+  return a.generate(ir)
+}
+
+describe('JinjaAdapter - conditional inline-object spread (textarea aria-describedby)', () => {
+  // `{...(cond ? { 'aria-describedby': cond } : {})}` lowers to a Jinja inline
+  // ternary of dicts so the falsy `{}` branch OMITS the key
+  // (bf.spread_attrs does not emit empty entries). The shared fixture only
+  // exercises the falsy branch; this pins the truthy one.
+  test('emits a Jinja inline ternary of dicts through bf.spread_attrs', () => {
+    const { template } = compileAndGenerate(`
+function Box({ describedBy }: { describedBy?: string }) {
+  return <div {...(describedBy ? { 'aria-describedby': describedBy } : {})} />
+}
+`)
+    expect(template).toContain(
+      "bf.spread_attrs(({'aria-describedby': describedBy} if bf.truthy(describedBy) else {}))",
+    )
+  })
+
+  test('resolves the value reference and preserves the static key for a second prop', () => {
+    const { template } = compileAndGenerate(`
+function Box({ label }: { label: string }) {
+  return <div {...(label ? { 'data-label': label } : {})} />
+}
+`)
+    expect(template).toContain(
+      "bf.spread_attrs(({'data-label': label} if bf.truthy(label) else {}))",
+    )
+  })
+
+  test('falls back to BF101 for a computed (non-static) object key', () => {
+    const adapter = new JinjaAdapter()
+    const ir = compileToIR(`
+function Box({ k, v }: { k?: string; v?: string }) {
+  return <div {...(v ? { [k]: v } : {})} />
+}
+`, adapter)
+    adapter.generate(ir)
+    const errs = (adapter as unknown as { errors: { code: string }[] }).errors
+    expect(errs.some(e => e.code === 'BF101')).toBe(true)
+  })
+})
+
+describe('JinjaAdapter - local-const conditional-spread resolution (#checkbox icon)', () => {
+  // A FUNCTION-scope const holding a `cond ? {…} : {}` ternary, spread as a bare
+  // identifier (`{...attrs}`), resolves through the same Jinja
+  // ternary-of-dicts lowering as the inline form. CheckIcon's
+  // `const sizeAttrs = size ? {…} : {}` is exactly this shape.
+  test('resolves a bare-identifier spread of a function-scope conditional const', () => {
+    const { template } = compileAndGenerate(`
+function Box({ flag }: { flag?: boolean }) {
+  const attrs = flag ? { 'data-on': 'yes' } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain(
+      "bf.spread_attrs(({'data-on': 'yes'} if bf.truthy(flag) else {}))",
+    )
+  })
+
+  // A const that aliases another bare identifier must NOT be forwarded (loop
+  // guard): the resolver bails, so the spread falls through to the standard
+  // lowering emitting the bare `attrs` variable.
+  test('does not forward a const that aliases another identifier (loop guard)', () => {
+    const { template } = compileAndGenerate(`
+function Box({ other }: { other?: object }) {
+  const attrs = other
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain('bf.spread_attrs(attrs)')
+  })
+})
+
+describe('JinjaAdapter - Record<staticKeys,scalar>[propKey] spread value (#checkbox icon)', () => {
+  // `const sizeMap: Record<IconSize, number> = { sm: 16, ... }` indexed by a
+  // prop inside a conditional-spread object value lowers to an inline
+  // bracket-indexed Jinja dict `{...}[key]` — the SAME bracket-index syntax
+  // JS itself uses (unlike Kolon, which had to steer around Perl's
+  // arrow-deref `->{$key}` to the bracket form). This is CheckIcon's
+  // `{ width: sizeMap[size], height: sizeMap[size] }` shape.
+  test('lowers an indexed module-const map to an inline bracket-indexed dict', () => {
+    const { template } = compileAndGenerate(`
+const sizeMap: Record<string, number> = { sm: 16, md: 20, lg: 24, xl: 32 }
+function Box({ size }: { size?: string }) {
+  const attrs = size ? { width: sizeMap[size] } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain(
+      "{'sm': 16, 'md': 20, 'lg': 24, 'xl': 32}[size]",
+    )
+  })
+
+  test('lowers string-valued record maps too', () => {
+    const { template } = compileAndGenerate(`
+const labelMap: Record<string, string> = { a: 'Alpha', b: 'Beta' }
+function Box({ k }: { k?: string }) {
+  const attrs = k ? { 'data-label': labelMap[k] } : {}
+  return <div {...attrs} />
+}
+`)
+    expect(template).toContain("{'a': 'Alpha', 'b': 'Beta'}[k]")
+  })
+
+  // A non-scalar record value (object) is out of shape: the spread object value
+  // can't lower, so the whole spread falls back to BF101.
+  test('refuses a non-scalar record value with BF101 (out-of-shape fallback)', () => {
+    const adapter = new JinjaAdapter()
+    const ir = compileToIR(`
+const sizeMap: Record<string, object> = { sm: { w: 1 } }
+function Box({ size }: { size?: string }) {
+  const attrs = size ? { width: sizeMap[size] } : {}
+  return <div {...attrs} />
+}
+`, adapter)
+    adapter.generate(ir)
+    const errs = (adapter as unknown as { errors: { code: string }[] }).errors
+    expect(errs.some(e => e.code === 'BF101')).toBe(true)
+  })
+})
+
+describe('JinjaAdapter - props-object inherited-attribute enumeration (#checkbox)', () => {
+  // A SolidJS props-object component reads inherited attributes (`props.id`)
+  // not enumerated in `propsParams`. The bare optional attribute must be
+  // guarded so it's omitted when unset (Hono parity), even though `id`
+  // isn't a declared param.
+  test('guards a props-object bare optional attr (props.id) with is defined and is not none', () => {
+    const { template } = compileAndGenerate(`
+"use client"
+interface P { tone?: string }
+export function Widget(props: P) {
+  return <button id={props.id}>x</button>
+}
+`)
+    expect(template).toContain('{% if id is defined and id is not none %}')
+    expect(template).toContain('id="{{ bf.string(id) }}"')
+  })
+})
+
+describe('JinjaAdapter - hyphenated child attr dict key (#checkbox)', () => {
+  // A child component prop whose JSX name isn't a bare identifier
+  // (`<CheckIcon data-slot="..."/>`) must be quoted in the `render_child`
+  // dict — same as EVERY other key, since Jinja dict-literal keys are
+  // ALWAYS quoted (see the file header for why this diverges from the
+  // Kolon port's "only quote when non-bareword-safe" assertion).
+  test('quotes every child attribute name in render_child, hyphenated or not', () => {
+    const { template } = compileAndGenerate(`
+"use client"
+import { Leaf } from './leaf'
+export function Host() {
+  return <div><Leaf data-slot="indicator" size="sm" /></div>
+}
+`)
+    expect(template).toContain("'data-slot': 'indicator'")
+    expect(template).toContain("'size': 'sm'")
+  })
+})
+
+describe('JinjaAdapter - nullish optional-attribute omission (textarea rows)', () => {
+  // A no-destructure-default, nillable-typed prop is `None` when the caller
+  // omits it; guard its bare-reference attribute with a Jinja
+  // "is defined and is not none" test so it DROPS instead of rendering
+  // `attr=""` — matching Hono's nullish-attribute omission. Concrete/defaulted
+  // props are never `None` and stay unconditional.
+  test('guards a no-default nillable attr with a Jinja defined+not-none check', () => {
+    const { template } = compileAndGenerate(`
+function C({ rows }: { rows?: number }) {
+  return <textarea rows={rows} />
+}
+`)
+    expect(template).toContain('{% if rows is defined and rows is not none %}')
+    expect(template).toContain('rows="{{ bf.string(rows) }}"')
+  })
+
+  test('leaves a defaulted attr unconditional (scope did not widen)', () => {
+    const { template } = compileAndGenerate(`
+function C({ value = '' }: { value?: string }) {
+  return <textarea value={value} />
+}
+`)
+    // `value` has a destructure default → never None → unconditional, exactly
+    // like Hono's value="".
+    expect(template).toContain('value="{{ bf.string(value) }}"')
+    expect(template).not.toContain('is not none')
+  })
+})

package/src/adapter/analysis/component-tree.ts

@@ -0,0 +1,119 @@
+/**
+ * Component-tree analysis for the Jinja2 template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/analysis/component-tree.ts`.
+ * Pure functions over the IR — they read no adapter instance state.
+ * `collectImportedLoopChildComponentErrors` returns its diagnostics instead
+ * of pushing onto the adapter's error list, so the adapter stays the sole
+ * owner of `errors`.
+ */
+
+import type {
+  ComponentIR,
+  IRNode,
+  IRComponent,
+  IRElement,
+  IRFragment,
+  IRConditional,
+  IRLoop,
+  IRIfStatement,
+  IRProvider,
+  IRAsync,
+  CompilerError,
+} from '@barefootjs/jsx'
+
+/**
+ * Whether the component needs the client runtime — it owns reactive state
+ * (signals / effects / onMount) or the analyzer flagged it as needing init.
+ */
+export function hasClientInteractivity(ir: ComponentIR): boolean {
+  return (
+    ir.metadata.signals.length > 0 ||
+    ir.metadata.effects.length > 0 ||
+    ir.metadata.onMounts.length > 0 ||
+    (ir.metadata.clientAnalysis?.needsInit ?? false)
+  )
+}
+
+/**
+ * Build a `BF103` diagnostic for every component reference inside a loop body
+ * whose name is imported from a relative-path module. Mirror of the Go /
+ * Xslate adapter's check — the Jinja adapter has the same
+ * cross-template-registration constraint at request time (each `.jinja`
+ * component file must be registered with the shared `jinja2.Environment`
+ * loader alongside the parent). Returns the diagnostics so the caller pushes
+ * them onto its own error list.
+ */
+export function collectImportedLoopChildComponentErrors(
+  ir: ComponentIR,
+  componentName: string,
+): CompilerError[] {
+  const errors: CompilerError[] = []
+  const relativeImports = new Set<string>()
+  for (const imp of ir.metadata.templateImports ?? ir.metadata.imports ?? []) {
+    if (!imp.source.startsWith('./') && !imp.source.startsWith('../')) continue
+    if (imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      relativeImports.add(spec.alias ?? spec.name)
+    }
+  }
+  if (relativeImports.size === 0) return errors
+
+  const loc = { file: componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } }
+  const visit = (node: IRNode, inLoop: boolean): void => {
+    switch (node.type) {
+      case 'component': {
+        const comp = node as IRComponent
+        if (inLoop && relativeImports.has(comp.name)) {
+          errors.push({
+            code: 'BF103',
+            severity: 'error',
+            message: `Component <${comp.name}> is imported from a sibling module and used inside a loop. The Jinja adapter emits a cross-template call; the child template must be registered alongside the parent at render time.`,
+            loc: comp.loc ?? loc,
+            suggestion: {
+              message:
+                `Options:\n` +
+                `  1. Compile '${comp.name}' (its source file) with the same adapter and register the resulting Jinja template alongside the parent at render time.\n` +
+                `  2. Inline <${comp.name}> directly inside the loop body so no cross-file template lookup is needed.\n` +
+                `  3. Mark the loop position as @client-only so the template is materialised on the client instead of at SSR time.`,
+            },
+          })
+        }
+        for (const child of comp.children) visit(child, inLoop)
+        break
+      }
+      case 'element':
+        for (const child of (node as IRElement).children) visit(child, inLoop)
+        break
+      case 'fragment':
+        for (const child of (node as IRFragment).children) visit(child, inLoop)
+        break
+      case 'conditional': {
+        const cond = node as IRConditional
+        visit(cond.whenTrue, inLoop)
+        if (cond.whenFalse) visit(cond.whenFalse, inLoop)
+        break
+      }
+      case 'loop':
+        for (const child of (node as IRLoop).children) visit(child, true)
+        break
+      case 'if-statement': {
+        const stmt = node as IRIfStatement
+        visit(stmt.consequent, inLoop)
+        if (stmt.alternate) visit(stmt.alternate, inLoop)
+        break
+      }
+      case 'provider':
+        for (const child of (node as IRProvider).children) visit(child, inLoop)
+        break
+      case 'async': {
+        const a = node as IRAsync
+        visit(a.fallback, inLoop)
+        for (const child of a.children) visit(child, inLoop)
+        break
+      }
+    }
+  }
+  visit(ir.root, false)
+  return errors
+}

package/src/adapter/boolean-result.ts

@@ -0,0 +1,176 @@
+/**
+ * Structural classifier for JS expressions whose result is a boolean value
+ * (or unambiguously stringifies to "true"/"false" in JS).
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/boolean-result.ts`
+ * (itself ported from the Mojo adapter's `bf->bool_str` classifier). Used by
+ * the Jinja adapter for TWO purposes — one inherited from Xslate, one new:
+ *
+ * 1. **Attribute/text stringification** (inherited): route a boolean-shaped
+ *    reactive binding through the runtime `bf.bool_str` helper so the
+ *    serialised value matches JS `String(boolean)` ("true"/"false"). Python
+ *    has a real `bool` type (unlike Perl's `1`/`''`), but Python's own
+ *    `str(True)` == `"True"` (capitalised) — still wrong for HTML output —
+ *    so the same explicit routing is required.
+ * 2. **Condition-position truthy wrapping** (new — `isBooleanResultParsed` is
+ *    exported, not just the string-based `isBooleanResultExpr`): Python
+ *    truthiness diverges from JS specifically on empty containers (`[]` /
+ *    `{}` are JS-truthy, Python-falsy). Perl doesn't have this problem — a
+ *    Perl array/hash REFERENCE is always true, matching JS objects/arrays
+ *    being unconditionally truthy — which is why Xslate never needed a
+ *    truthy-routing layer for `if`/ternary/`&&`/`||` conditions. The Jinja
+ *    adapter's condition-emission call sites (see `jinja-adapter.ts`'s
+ *    `convertConditionToJinja`) reuse this SAME structural classifier: a
+ *    condition that is already unambiguously boolean-shaped emits directly;
+ *    everything else is wrapped in `bf.truthy(...)` (a JS-faithful
+ *    `ToBoolean`) before being used as an `{% if %}` / ternary test.
+ *
+ * The classifier walks a `ParsedExpr` produced by
+ * `@barefootjs/jsx::parseExpression` — same AST the filter / loop lowerings
+ * already use — so detection is structural rather than regex-text-matching.
+ * Wrapped expression text is left to the caller's existing
+ * `convertExpressionToJinja` pipeline; this module only decides whether to
+ * wrap.
+ *
+ * Detected shapes:
+ *   - `binary` with a comparison operator (`<`, `>`, `<=`, `>=`, `==`, `===`,
+ *     `!=`, `!==`)
+ *   - `unary` with logical `!`
+ *   - `literal` with `literalType: 'boolean'`
+ *   - `logical` (`&&` / `||` / `??`) when both sides are themselves
+ *     boolean-result (catches `x > 0 && y < 10`; intentionally does NOT
+ *     catch `x() || 'fallback'` whose right side stringifies as a regular
+ *     value)
+ *   - `conditional` (`?:`) when both branches are themselves boolean-result
+ *
+ * Anything else returns `false` — including bare identifiers (`accepted`)
+ * and call expressions (`accepted()`) whose return type the adapter has no
+ * way to infer from source text alone.
+ */
+
+import { parseExpression, type ParsedExpr } from '@barefootjs/jsx'
+
+const COMPARISON_OPS = new Set([
+  '<',
+  '>',
+  '<=',
+  '>=',
+  '==',
+  '===',
+  '!=',
+  '!==',
+])
+
+/**
+ * Structural boolean-result check over an already-parsed `ParsedExpr` tree.
+ * Exported (unlike Xslate's private equivalent) so the condition-position
+ * truthy-wrapping call sites can reuse it without a stringify → re-parse
+ * round-trip.
+ */
+export function isBooleanResultParsed(node: ParsedExpr): boolean {
+  switch (node.kind) {
+    case 'literal':
+      return node.literalType === 'boolean'
+    case 'binary':
+      return COMPARISON_OPS.has(node.op)
+    case 'unary':
+      return node.op === '!'
+    case 'logical':
+      // `x > 0 && y < 10` is boolean; `x() || 'fallback'` is not.
+      // Only both-sides-boolean qualifies.
+      return (
+        isBooleanResultParsed(node.left) && isBooleanResultParsed(node.right)
+      )
+    case 'conditional':
+      // `cond ? bool : bool` is boolean; `cond ? 'a' : 'b'` is not.
+      return (
+        isBooleanResultParsed(node.consequent) &&
+        isBooleanResultParsed(node.alternate)
+      )
+    default:
+      return false
+  }
+}
+
+export function isBooleanResultExpr(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  if (!parsed) return false
+  return isBooleanResultParsed(parsed)
+}
+
+/**
+ * True when `expr`'s top-level shape is an explicit JS `String(x)` call
+ * (the `EVAL_BUILTIN_IDENTS` builtin the compiler recognizes structurally —
+ * `packages/jsx/src/expression-parser.ts`'s `EVAL_BUILTIN_IDENTS`; lowered
+ * by this adapter's `String` template primitive to `bf.string(x)`, see
+ * `lib/constants.ts`).
+ *
+ * Guards the `isAriaBooleanAttr`-driven `bf.bool_str(...)` override in
+ * `jinja-adapter.ts`'s `elementAttrEmitter`: `bf.string` and `bf.bool_str`
+ * produce IDENTICAL text for a real Python `bool` (both are `"true"` /
+ * `"false"`), so applying `bf.bool_str` to `String(x)`'s ALREADY-STRINGIFIED
+ * result is not a no-op — it is a Python-truthiness test over that STRING
+ * ("false" is a non-empty Python string, hence truthy, so
+ * `bf.bool_str(bf.string(false))` would wrongly render `"true"`). The Kolon
+ * port has the identical double-wrap shape and "works" only by an
+ * unrelated accident (`JSON::PP::Boolean` stringifies to `"0"`/`"1"`, and
+ * Perl specifically treats the STRING `"0"` as falsy) that doesn't hold in
+ * Python. An author who explicitly writes `String(...)` has already opted
+ * into JS `String()` semantics — `bf.string(x)` alone (which DOES special-
+ * case booleans, see `runtime.js_string`) is the complete, correct
+ * lowering; no attribute-name-driven override should run again on top of
+ * it.
+ */
+export function isExplicitStringCall(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  return (
+    !!parsed &&
+    parsed.kind === 'call' &&
+    parsed.callee.kind === 'identifier' &&
+    parsed.callee.name === 'String' &&
+    parsed.args.length === 1
+  )
+}
+
+/**
+ * ARIA attributes whose spec values are `"true"`, `"false"`, and (for
+ * tri-state members) `"mixed"`. When a fixture binds one of these to an
+ * arbitrary JS expression (`aria-checked={accepted()}`), the expression's
+ * actual type isn't recoverable from source text — but the attribute name
+ * itself witnesses that the binding is boolean-shaped. Routing these through
+ * `bf.bool_str` produces the spec-canonical `"true"` / `"false"` even when
+ * the expression is opaque.
+ *
+ * Deliberately conservative — only includes ARIA attributes whose spec value
+ * set is exactly `true | false` or `true | false | mixed`. Tokenised ARIA
+ * attributes (`aria-current` is `page | step | …`, `aria-sort` is
+ * `ascending | descending | …`) are intentionally excluded so a
+ * string-valued binding doesn't get coerced to `"true"` / `"false"`.
+ */
+const ARIA_BOOLEAN_ATTRS = new Set([
+  // Strict boolean state (true | false; some allow `undefined` = attribute
+  // absent, which the runtime emits as no-attr regardless).
+  'aria-atomic',
+  'aria-busy',
+  'aria-disabled',
+  'aria-hidden',
+  'aria-modal',
+  'aria-multiline',
+  'aria-multiselectable',
+  'aria-readonly',
+  'aria-required',
+  // true | false | undefined (absent) — selection / disclosure state.
+  'aria-selected',
+  'aria-expanded',
+  // Tri-state (true | false | mixed). The `bool_str` helper only maps
+  // truthy / falsy to true / false — a fixture that wants the literal
+  // "mixed" would bind a string-valued JSX attr (`aria-checked="mixed"`),
+  // which lowers through the `literal` emit path and never touches this
+  // code.
+  'aria-checked',
+  'aria-pressed',
+])
+
+export function isAriaBooleanAttr(name: string): boolean {
+  return ARIA_BOOLEAN_ATTRS.has(name)
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,118 @@
+/**
+ * The contract the extracted expression-emitter modules depend on instead of
+ * the concrete `JinjaAdapter`.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/emit-context.ts`. The
+ * Jinja adapter's top-level expression lowering is mutually recursive with
+ * the adapter's own const/record resolution and its filter-predicate
+ * emitter, so the extracted `JinjaTopLevelEmitter` still needs to call back
+ * into shared per-compile state and recursive entry points.
+ * `JinjaEmitContext` is that seam: the emitter takes a `JinjaEmitContext`
+ * built by the adapter's private `emitCtx` getter (the adapter does NOT
+ * `implements` this interface, so the wrapped members stay private and off
+ * its exported public type). The emitter depends on this narrow interface
+ * rather than the full class, so the coupling is explicit and it's
+ * unit-testable against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling
+ * rather than re-exposing the whole adapter.
+ */
+
+import type { ParsedExpr, CompilerError, IRMetadata } from '@barefootjs/jsx'
+
+export interface JinjaEmitContext {
+  /**
+   * (#1922) Local binding names the request-scoped `searchParams()` env signal
+   * is imported under. Non-empty enables the env-signal method-call lowering.
+   */
+  readonly _searchParamsLocals: Set<string>
+
+  /**
+   * Inline a module-scope pure string-literal const by name as the resolved
+   * literal value, or null when the name is not such a const.
+   */
+  _resolveModuleStringConst(name: string): string | null
+
+  /** Resolve a literal const (`const totalPages = 5`) to its Jinja value, or null. */
+  _resolveLiteralConst(name: string): string | null
+
+  /**
+   * Resolve a static property access on a module object-literal const
+   * (`variantClasses.ghost`) to its Jinja value at compile time, or null.
+   */
+  _resolveStaticRecordLiteral(objectName: string, key: string): string | null
+
+  /** Record a BF101 unsupported-expression diagnostic. */
+  _recordExprBF101(message: string, reason?: string): void
+
+  /** Lower a filter/predicate body to its Jinja form, bound to `param`. */
+  _renderJinjaFilterExprPublic(expr: ParsedExpr, param: string): string
+}
+
+/**
+ * The contract the extracted object-literal / conditional-spread lowering
+ * (`spread/spread-codegen.ts`) depends on. Declared separately from
+ * `JinjaEmitContext` so each extracted module's real coupling is documented
+ * precisely. Mirror of the Xslate adapter's `XslateSpreadContext`.
+ */
+export interface JinjaSpreadContext {
+  /** Component name, for diagnostic source locations. */
+  readonly componentName: string
+
+  /** Per-compile diagnostic list the spread lowering appends to. */
+  readonly errors: CompilerError[]
+
+  /** Local-constant metadata, for resolving `Record[key]` spread values. */
+  readonly localConstants: IRMetadata['localConstants']
+
+  /** Prop params, for classifying a bare-identifier index as a prop. */
+  readonly propsParams: { name: string }[]
+
+  /**
+   * Lower a JS expression to its Jinja form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr`. With `preParsed` set, `expr` is unused for parsing
+   * (the converter derives any diagnostic text from the tree), so callers
+   * may pass `''`.
+   */
+  convertExpressionToJinja(expr: string, preParsed?: ParsedExpr): string
+
+  /**
+   * Lower a JS expression to a Jinja CONDITION (routes through `bf.truthy`
+   * unless the expression is structurally already boolean-shaped — see
+   * `boolean-result.ts`). Used for the conditional-spread ternary's test,
+   * which is a condition position, not a value position. Same `preParsed`
+   * contract as `convertExpressionToJinja`.
+   */
+  convertConditionToJinja(expr: string, preParsed?: ParsedExpr): string
+}
+
+/**
+ * The contract the extracted in-template memo / context seeding
+ * (`memo/seed.ts`) depends on. The seed lowering recurses into the core
+ * expression lowering to compute a derived signal/memo value or a context
+ * default; that recursive entry is its only adapter coupling.
+ */
+export interface JinjaMemoContext {
+  /**
+   * Lower a JS expression to its Jinja form (the core recursive entry). See
+   * `JinjaSpreadContext.convertExpressionToJinja` for the `preParsed` contract.
+   */
+  convertExpressionToJinja(expr: string, preParsed?: ParsedExpr): string
+
+  /**
+   * Per-compile diagnostic list `convertExpressionToJinja` appends to on an
+   * unsupported shape (`_recordExprBF101`). `memo/seed.ts`'s
+   * `generateDerivedMemoSeed` is a SPECULATIVE "try this in-template
+   * recomputation, else fall back to the static ssrDefault seed" attempt per
+   * plan step — unlike every other `convertExpressionToJinja` call site, a
+   * failure here must NOT become a hard compile error, so it snapshots this
+   * array's length before calling in and truncates back to it on failure
+   * (discarding whatever `_recordExprBF101` appended) rather than letting
+   * the error escape.
+   */
+  readonly errors: CompilerError[]
+}