@barefootjs/jinja 0.1.0

package/src/adapter/lib/constants.ts

@@ -0,0 +1,33 @@
+/**
+ * Compile-time constant tables for the Jinja2 template adapter.
+ *
+ * Extracted the way `packages/adapter-xslate/src/adapter/lib/constants.ts` is.
+ */
+
+import type { PrimitiveSpec } from './types.ts'
+
+/**
+ * Single source of truth for the Jinja adapter's template-primitive
+ * surface. Each entry pairs the expected arity with the emit function.
+ *
+ * The emit fn returns a Jinja expression (no surrounding `{{ }}`) suitable
+ * for embedding inside an interpolation — `bf.json(val)`, `bf.floor(val)`,
+ * etc. The same primitive names as the Xslate adapter, but invoked as
+ * `bf.NAME(args)` (bare, no `$` sigil) instead of `$bf.NAME(args)`.
+ */
+export const JINJA_TEMPLATE_PRIMITIVES: Record<string, PrimitiveSpec> = {
+  'JSON.stringify': { arity: 1, emit: (args) => `bf.json(${args[0]})` },
+  'String':         { arity: 1, emit: (args) => `bf.string(${args[0]})` },
+  'Number':         { arity: 1, emit: (args) => `bf.number(${args[0]})` },
+  'Math.floor':     { arity: 1, emit: (args) => `bf.floor(${args[0]})` },
+  'Math.ceil':      { arity: 1, emit: (args) => `bf.ceil(${args[0]})` },
+  'Math.round':     { arity: 1, emit: (args) => `bf.round(${args[0]})` },
+}
+
+/**
+ * Module-scope `templatePrimitives` map derived once from the spec record.
+ */
+export const JINJA_PRIMITIVE_EMIT_MAP: Record<string, (args: string[]) => string> =
+  Object.fromEntries(
+    Object.entries(JINJA_TEMPLATE_PRIMITIVES).map(([k, v]) => [k, v.emit])
+  )

package/src/adapter/lib/ir-scope.ts

@@ -0,0 +1,95 @@
+/**
+ * IR traversal helpers for the Jinja2 template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/lib/ir-scope.ts`.
+ * `resolveJsxChildrenProp` and `collectRootScopeNodes` are byte-identical
+ * (adapter-agnostic IR walks).
+ *
+ * `extractTopLevelIdentifiers` scans the RENDERED template text (rather than
+ * re-deriving free vars from the original JS AST) so it stays exactly in
+ * sync with whatever the emitter actually produced — but Jinja identifiers
+ * have no sigil (unlike Kolon's `$`, which made a trivially safe
+ * `\$([A-Za-z_]\w*)` scan possible): a bare word in the rendered text could
+ * be a genuine context-var reference, a `bf.` runtime-helper method name, a
+ * Jinja grammar keyword emitted by this adapter's own condition/ternary
+ * lowering (`if`/`else`/`is`/`not`/`and`/`or`/`none`/`true`/`false`), or
+ * content inside a single-quoted string literal. This helper makes the scan
+ * sound: it strips quoted string spans first, then matches identifier tokens
+ * NOT immediately preceded by a `.` (excluding dotted property/method names
+ * — the same exclusion the `$` sigil gave Kolon for free, since Kolon's
+ * regex only ever matched right after `$`), then drops the closed set of
+ * tokens this adapter's own codegen can emit that aren't context vars (`bf`
+ * and the Jinja keywords above). `memo/seed.ts` uses it to detect a
+ * constant lowering (no top-level identifier at all) that should keep the
+ * static ssr-defaults seed instead of an in-template `{% set %}`; scope
+ * AVAILABILITY itself is now the shared `computeSsrSeedPlan`'s job
+ * (packages/jsx/src/ssr-seed-plan.ts), not this module's (#2075).
+ */
+
+import type { IRNode, IRProp, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/** Tokens this adapter's own codegen can emit that are never context vars. */
+const NON_VAR_TOKENS = new Set([
+  'bf', 'if', 'else', 'is', 'not', 'and', 'or', 'in', 'none', 'true', 'false',
+  // `is defined` — the nullish-coalescing (`??`) lowering's Undefined guard
+  // (`expr/emitters.ts`'s `logical`, and the nullable-optional-prop
+  // attribute-omission test in `jinja-adapter.ts`) emits this Jinja test
+  // keyword; it's never a context var.
+  'defined',
+])
+
+/**
+ * Extract the set of "top-level identifier" tokens from a rendered Jinja
+ * expression: bare words, excluding quoted-string content, dotted
+ * property/method names, and this adapter's own non-var keyword vocabulary.
+ * See the file header for why this replaces a direct `\w+` scan.
+ */
+export function extractTopLevelIdentifiers(jinjaExpr: string): string[] {
+  // Strip single-quoted string literals (this adapter only ever emits
+  // single-quoted string literals, backslash-escaped) so their content can't
+  // leak into the identifier scan.
+  const stripped = jinjaExpr.replace(/'(?:\\.|[^'\\])*'/g, ' ')
+  const out: string[] = []
+  for (const m of stripped.matchAll(/(?<!\.)\b([A-Za-z_]\w*)\b/g)) {
+    if (!NON_VAR_TOKENS.has(m[1])) out.push(m[1])
+  }
+  return out
+}
+
+/**
+ * Find the `children` prop's `jsx-children` payload. Narrowed via the
+ * AttrValue `kind` discriminator so adapter code stays type-safe if the IR
+ * shape evolves.
+ */
+export function resolveJsxChildrenProp(props: readonly IRProp[]): IRNode[] {
+  const prop = props.find(p => p.name === 'children')
+  if (!prop) return []
+  if (prop.value.kind !== 'jsx-children') return []
+  return prop.value.children
+}
+
+/**
+ * Collect the component's root scope element node(s) — the elements that
+ * become the rendered root and so carry `data-key` for a keyed loop item. A
+ * plain element root is itself; an `if-statement` (early-return) root
+ * contributes the top element of each branch, since exactly one renders at
+ * runtime. (#1297)
+ */
+export function collectRootScopeNodes(node: IRNode): Set<IRNode> {
+  const out = new Set<IRNode>()
+  const visit = (n: IRNode | null): void => {
+    if (!n) return
+    if (n.type === 'element') { out.add(n); return }
+    if (n.type === 'if-statement') {
+      const s = n as IRIfStatement
+      visit(s.consequent)
+      visit(s.alternate)
+      return
+    }
+    if (n.type === 'fragment') {
+      for (const c of (n as IRFragment).children) visit(c)
+    }
+  }
+  visit(node)
+  return out
+}

package/src/adapter/lib/jinja-naming.ts

@@ -0,0 +1,114 @@
+/**
+ * Jinja2/Python identifier and dict-key conventions for the Jinja adapter.
+ *
+ * Pure helpers, ported from the Kolon equivalent
+ * (`packages/adapter-xslate/src/adapter/lib/kolon-naming.ts`) but adjusted for
+ * two real syntax divergences between Kolon and Jinja2:
+ *
+ * 1. **Dict-literal keys are always quoted.** Kolon's hashref fat-comma
+ *    (`key => value`) auto-quotes a bareword key, so `kolonHashKey` only
+ *    quotes a non-identifier-safe name (`'data-slot'`). A Jinja/Python dict
+ *    LITERAL has no such bareword-key sugar — `{key: value}` means "look up
+ *    the *variable* `key` and use its value as the key", not the string
+ *    `"key"`. `jinjaHashKey` therefore ALWAYS emits a quoted string literal,
+ *    identifier-safe or not — the one place this port is NOT a bare 1:1
+ *    syntax substitution, because treating it as one would silently change
+ *    dict keys into undefined-variable lookups.
+ * 2. **Reserved-word identifier mangling.** Verified empirically against
+ *    Jinja 3.1 that most Python keywords (`class`, `import`, `for`, …) parse
+ *    fine as bare Jinja variable / loop-target names — Jinja compiles every
+ *    user template name to an internally-prefixed Python local (`l_0_…`), so
+ *    the template layer itself mostly sidesteps Python's own reserved-word
+ *    rules. The genuinely Jinja-reserved bare words are `not` / `and` / `or`
+ *    / `in` / `is` / `if` / `else` (grammar keywords) plus the three
+ *    constants `true` / `false` / `none` (rejected specifically as
+ *    assignment targets). Per the adapter plan, `jinjaIdent` mangles the
+ *    FULL Python reserved-word list (a conservative superset of what Jinja's
+ *    grammar strictly requires) with a trailing-underscore suffix, trivial
+ *    and easy to keep in lock-step with the Python runtime's identical rule
+ *    (`barefootjs.runtime.jinja_ident`) — the runtime applies the SAME
+ *    mangling when it builds the per-render context dict, so a prop/signal
+ *    named e.g. `class` is threaded through as context key `'class_'` on
+ *    both sides.
+ */
+
+import type { LoopBindingPathSegment } from '@barefootjs/jsx'
+
+/**
+ * Escape a string for a Jinja/Python single-quoted literal: backslash first
+ * (so it doesn't double-escape the quote we add next), then the quote.
+ * Python string-literal escaping treats `\\` / `\'` identically to Perl's,
+ * so this is byte-identical to `escapeKolonSingleQuoted`.
+ */
+export function escapeJinjaSingleQuoted(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+}
+
+/**
+ * Quote a dict-literal KEY for Jinja. UNLIKE Kolon's `kolonHashKey`, this
+ * always quotes — see the file header for why a bareword key would silently
+ * become a variable lookup instead of a string key.
+ */
+export function jinjaHashKey(name: string): string {
+  return `'${escapeJinjaSingleQuoted(name)}'`
+}
+
+/**
+ * Python reserved words (the plan's list) that must not appear as a bare
+ * Jinja identifier — see the file header. Kept as the single source of
+ * truth; the Python runtime's `jinja_ident` mirrors this exact set.
+ */
+const RESERVED_WORDS = new Set([
+  'if', 'else', 'for', 'in', 'is', 'not', 'and', 'or', 'none', 'true', 'false',
+  'import', 'from', 'class', 'def', 'pass', 'del', 'return', 'lambda', 'global',
+  'with', 'as', 'raise', 'try', 'except', 'finally', 'while', 'break',
+  'continue', 'elif', 'yield', 'assert', 'nonlocal',
+])
+
+/**
+ * Mangle a JS identifier (prop name, signal getter, loop param, …) into a
+ * Jinja-safe variable name: reserved words get a trailing `_` suffix,
+ * everything else passes through unchanged. Applied at every point the
+ * adapter emits a bare Jinja variable reference or `{% set %}` target —
+ * mirrors Kolon's `$name` sigil giving those references collision immunity
+ * for free; Jinja has no sigil, so the adapter mangles instead.
+ */
+export function jinjaIdent(name: string): string {
+  return RESERVED_WORDS.has(name) ? `${name}_` : name
+}
+
+/**
+ * Build a native Jinja accessor expression from a `.map()` destructure
+ * binding's structured {@link LoopBindingPathSegment} path (#2087 Phase B) —
+ * the per-adapter counterpart to the JS accessor suffix carried in
+ * `LoopParamBinding.path`. Walks `segments` (never string-parses `path` —
+ * repo rule) appending, per step:
+ *
+ *   - `{ kind: 'index', index }` → `[N]` (a Python list index — same postfix
+ *     Jinja uses for dict-key lookup, so this is unambiguous either way).
+ *   - `{ kind: 'field', key, isIdent: true }` → `.key` (bare attribute
+ *     access — Jinja resolves it against a dict transparently).
+ *   - `{ kind: 'field', key, isIdent: false }` → `[<quoted key>]` (e.g. a
+ *     `'data-priority'` sibling key can't be a bare Jinja attribute, same
+ *     reasoning as `jinjaHashKey` on dict-literal keys).
+ *
+ * `base` is the already-`jinjaIdent`-mangled loop variable (or a parent
+ * accessor expression when called recursively); an empty `segments` array
+ * (a rest binding sitting at the loop root) returns `base` unchanged.
+ */
+export function jinjaAccessorFromSegments(
+  base: string,
+  segments: readonly LoopBindingPathSegment[],
+): string {
+  let acc = base
+  for (const seg of segments) {
+    if (seg.kind === 'index') {
+      acc += `[${seg.index}]`
+    } else if (seg.isIdent) {
+      acc += `.${seg.key}`
+    } else {
+      acc += `[${jinjaHashKey(seg.key)}]`
+    }
+  }
+  return acc
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared type aliases for the Jinja2 template adapter.
+ *
+ * Extracted the way `packages/adapter-xslate/src/adapter/lib/types.ts` is:
+ * pure type declarations — no runtime behaviour — so the extracted emit
+ * modules and the main adapter share one definition rather than
+ * re-declaring the render context / options shape.
+ */
+
+/** A template-primitive spec: expected call arity + the emit fn. */
+export interface PrimitiveSpec {
+  arity: number
+  emit: (args: string[]) => string
+}
+
+/**
+ * Jinja adapter's IRNode render context. Like the Xslate adapter, Jinja's
+ * lowering doesn't consume any render-position flags, so the Ctx is empty.
+ * Kept as a named alias so future flags can extend it without changing the
+ * `IRNodeEmitter` interface.
+ */
+export type JinjaRenderCtx = Record<string, never>
+
+export interface JinjaAdapterOptions {
+  /** Base path for client JS files (default: '/static/components/') */
+  clientJsBasePath?: string
+
+  /** Path to barefoot.js runtime (default: '/static/components/barefoot.js') */
+  barefootJsPath?: string
+}

package/src/adapter/memo/seed.ts

@@ -0,0 +1,132 @@
+/**
+ * In-template memo / context seeding for the Jinja template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/memo/seed.ts`. Free
+ * functions taking a `JinjaMemoContext` (built by the adapter's `memoCtx`
+ * getter) so the cluster depends only on the recursive expression entry, not
+ * the whole adapter class. These emit the `{% set x = ... %}` statements
+ * that let the body's bare `x` resolve to a derived signal/memo value or an
+ * active context value at SSR time.
+ *
+ * One deliberate behavioural IMPROVEMENT over the Kolon port: Kolon's `my`
+ * declares a NEW lexical, so `: my $x = … $x …;` reads the not-yet-assigned
+ * lexical on its own right-hand side — broken. Xslate therefore skips
+ * in-template seeding for a same-name signal/memo (a `refsSelf` guard in its
+ * `generateDerivedMemoSeed`). Jinja's `{% set %}` has no such shadowing
+ * hazard — `{% set x = x + 1 %}` resolves the right-hand `x` against the
+ * value ALREADY bound in the enclosing scope (verified empirically against
+ * Jinja 3.1: `env.from_string("{% set x = x + 1 %}{{ x }}").render(x=5)` →
+ * `"6"`, not an error or a stale `5`). This adapter therefore seeds a
+ * same-name signal/memo too, which is strictly more correct — the seed then
+ * re-derives from the already-bound prop instead of leaving the render var
+ * on its static (possibly per-callsite-wrong) default. No self-ref guard is
+ * ported for this reason.
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+  materializeGetterCalls,
+} from '@barefootjs/jsx'
+
+import type { JinjaMemoContext } from '../emit-context.ts'
+import { extractTopLevelIdentifiers } from '../lib/ir-scope.ts'
+import { jinjaIdent, escapeJinjaSingleQuoted } from '../lib/jinja-naming.ts'
+
+/** Jinja literal for a context-consumer's `createContext` default. */
+export function contextDefaultJinja(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'none'
+  if (typeof d === 'string') return `'${escapeJinjaSingleQuoted(d)}'`
+  if (typeof d === 'boolean') return d ? 'true' : 'false'
+  return String(d)
+}
+
+/**
+ * Emit one `{% set <local> = bf.use_context(...) %}` statement per context
+ * consumer so the body's bare `<local>` resolves to the active provider
+ * value (or the `createContext` default). (#1297)
+ */
+export function generateContextConsumerSeed(ir: ComponentIR): string {
+  const consumers = collectContextConsumers(ir.metadata)
+  if (consumers.length === 0) return ''
+  return (
+    consumers
+      .map(
+        c =>
+          `{% set ${jinjaIdent(c.localName)} = bf.use_context('${c.contextName}', ${contextDefaultJinja(c)}) %}`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `{% set <name> = <jinja> %}` statements for every `derived` step of
+ * the backend-neutral SSR seed plan — the scope/availability/ordering
+ * analysis lives in `computeSsrSeedPlan` (packages/jsx/src/ssr-seed-plan.ts);
+ * this only lowers each step's expression to Jinja and applies the
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no top-level identifier at all (a constant init/body —
+ * e.g. a `derived` step with empty `frees` — keeps the existing static
+ * ssr-defaults seed instead). Unlike the Kolon port there is no self-ref
+ * guard — see the file header. `env-reader` and `opaque` steps emit nothing
+ * (the runtime supplies the reader, or the adapter's ssr-defaults path
+ * already covers it). (#1297, #2075)
+ *
+ * `convertExpressionToJinja` can still fail DEEPER than the plan's
+ * structural `isSupported` pre-check — e.g. a `.filter(predicate)` whose
+ * predicate isn't evaluator-serializable has NO lambda fallback on this
+ * adapter (divergence 3, `jinja-adapter.ts`'s file header: unlike Kolon/Perl,
+ * Jinja has no lambda-expression form), so the lowering records a HARD
+ * BF101 as a side effect rather than degrading. That's correct for every
+ * OTHER `convertExpressionToJinja` call site (which commit to using the
+ * lowered text), but wrong here: this is a SPECULATIVE "recompute the memo
+ * in-template, else keep the static ssrDefault seed" attempt, so a deeper
+ * refusal must degrade silently, not fail the whole component compile.
+ * Snapshot the diagnostic list and roll back any errors appended during each
+ * step's attempt before moving on.
+ *
+ * A second, related Jinja-only gap divergence 3 opens up: a predicate
+ * referencing a SIBLING getter (`props.items.filter((p) => !tag() || …)`,
+ * `tag` a sibling memo) contains a zero-arg CALL node (`tag()`), which the
+ * evaluator's pure-expression surface refuses (`toEvalNode`'s `call` arm
+ * only allows a builtin callee, e.g. `Math.floor`) — with no lambda
+ * fallback to fall back to, the whole predicate would refuse. Kolon/Perl
+ * never hit this: their lambda form closes over the sibling's ALREADY-SEEDED
+ * lexical directly, without going through the evaluator at all. Go hits the
+ * identical gap (it also has no closures at SSR-constructor time) and fixes
+ * it the same way its `memo/memo-compute.ts` (`matchFilterArmMemo`) does:
+ * `materializeGetterCalls` rewrites a getter call into a bare identifier
+ * BEFORE serialization, so the evaluator captures it as a free-var read from
+ * `base_env` instead of an unsupported call node — and that free var then
+ * resolves against the sibling's own `{% set %}` line, which (being an
+ * EARLIER step per the plan's ordering guarantee) is always already bound.
+ * `env-reader` names are excluded from the materializable set — the runtime
+ * supplies those via the per-request reader, not a template-var lexical, so
+ * a call to one (`searchParams()`) must stay a real call, not a bare var.
+ */
+export function generateDerivedMemoSeed(ctx: JinjaMemoContext, ir: ComponentIR): string {
+  // Package G attached this to metadata at compile time; the `??` fallback
+  // only covers hand-built metadata in older tests that predate the attached
+  // plan — same shared function, so there's no divergence from the compiler.
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata)
+  const knownGetterNames = new Set<string>(
+    plan.steps.filter(s => s.kind !== 'env-reader').map(s => s.name),
+  )
+  const lines: string[] = []
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const materialized = materializeGetterCalls(step.parsed, knownGetterNames)
+    const errorsBefore = ctx.errors.length
+    const jinja = ctx.convertExpressionToJinja('', materialized)
+    if (ctx.errors.length > errorsBefore) {
+      ctx.errors.length = errorsBefore
+      continue
+    }
+    if (jinja === '' || extractTopLevelIdentifiers(jinja).length === 0) continue
+    lines.push(`{% set ${jinjaIdent(step.name)} = ${jinja} %}`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}

package/src/adapter/props/prop-classes.ts

@@ -0,0 +1,65 @@
+/**
+ * Prop classification for the Jinja2 template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/props/prop-classes.ts`.
+ * Pure functions over `ir.metadata` that derive the per-compile prop/name
+ * sets the adapter consults during lowering. No adapter instance state.
+ */
+
+import type { ComponentIR } from '@barefootjs/jsx'
+import { isStringTypeInfo, isBareStringLiteral } from '../value/parsed-literal.ts'
+
+/**
+ * Props whose declared TS type is boolean — a bare binding of one
+ * (`data-active={props.isActive}`) must stringify as JS `String(boolean)`
+ * ("true"/"false"), not Python's `str(bool)` ("True"/"False") (#1897,
+ * pagination's data-active).
+ */
+export function collectBooleanTypedProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(prop => prop.type?.primitive === 'boolean' || prop.type?.raw === 'boolean')
+      .map(prop => prop.name),
+  )
+}
+
+/**
+ * Bare references to optional, no-default, non-primitive props (e.g.
+ * textarea's `rows`) are `None` when omitted → guarded with
+ * `is defined and is not none` in `emitExpression`. See the
+ * `nullableOptionalProps` field docstring in `jinja-adapter.ts`.
+ */
+export function collectNullableOptionalProps(ir: ComponentIR): Set<string> {
+  return new Set(
+    ir.metadata.propsParams
+      .filter(
+        p =>
+          p.defaultValue === undefined &&
+          !p.isRest &&
+          p.type?.kind !== 'primitive',
+      )
+      .map(p => p.name),
+  )
+}
+
+/**
+ * String-typed signals and props. A signal is string-typed when its inferred
+ * type is `string` (or, defensively, when its initial value is a bare string
+ * literal); a prop when its annotated type is `string`. In the Mojo adapter
+ * this drives `eq`/`ne` selection for string equality; neither the Kolon nor
+ * the Jinja emitters consume the distinction (both languages' `==`/`!=`
+ * compare strings and numbers correctly), so this set is carried for parity
+ * with the Perl-family adapters, not because Jinja needs it today.
+ */
+export function collectStringValueNames(ir: ComponentIR): Set<string> {
+  const names = new Set<string>()
+  for (const s of ir.metadata.signals) {
+    if (isStringTypeInfo(s.type) || isBareStringLiteral(s.initialValue)) {
+      names.add(s.getter)
+    }
+  }
+  for (const p of ir.metadata.propsParams) {
+    if (isStringTypeInfo(p.type)) names.add(p.name)
+  }
+  return names
+}

package/src/adapter/spread/spread-codegen.ts

@@ -0,0 +1,166 @@
+/**
+ * Object-literal / conditional-spread → Jinja dict lowering for the Jinja
+ * template adapter.
+ *
+ * Ported from `packages/adapter-xslate/src/adapter/spread/spread-codegen.ts`.
+ * Free functions taking a `JinjaSpreadContext` (built by the adapter's
+ * `spreadCtx` getter) so the cluster depends on the narrow seam — the
+ * recursive expression entry plus per-compile bookkeeping — rather than the
+ * whole adapter class.
+ *
+ * The conditional-spread / object-literal entries read the IR-carried
+ * structured `ParsedExpr` tree (#2018) instead of re-parsing the source with
+ * `ts.createSourceFile`. The condition and scalar values are threaded
+ * straight into `ctx.convertExpressionToJinja` as its `preParsed` argument,
+ * so no stringify→re-parse round-trip occurs. The `ts.factory` rebuild in
+ * `recordIndexAccessToJinja` only reconstructs the `IDENT[KEY]` node the
+ * shared `parseRecordIndexAccess` parser accepts; no source-text re-parse.
+ */
+
+import ts from 'typescript'
+import { parseRecordIndexAccess, stringifyParsedExpr } from '@barefootjs/jsx'
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { JinjaSpreadContext } from '../emit-context.ts'
+import { escapeJinjaSingleQuoted, jinjaHashKey, jinjaIdent } from '../lib/jinja-naming.ts'
+
+/**
+ * Lower a conditional inline-object spread
+ *   `COND ? { 'aria-describedby': describedBy } : {}`
+ * to a Jinja inline ternary of dicts
+ *   `({'aria-describedby': describedBy} if bf.truthy(describedBy) else {})`.
+ * Reads the IR-carried structured `ParsedExpr` tree; both branches must be
+ * object literals; the condition + values route through
+ * `convertExpressionToJinja`. Returns `null` for any other shape so the
+ * caller falls back to its normal lowering.
+ */
+export function conditionalSpreadToJinja(
+  ctx: JinjaSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'conditional') return null
+  const whenTrue = expr.consequent
+  const whenFalse = expr.alternate
+  if (whenTrue.kind !== 'object-literal' || whenFalse.kind !== 'object-literal') {
+    return null
+  }
+  // Thread the condition's carried `ParsedExpr` tree straight through as
+  // `preParsed` (#2018) — no stringify→re-parse round-trip.
+  const condJinja = ctx.convertConditionToJinja('', expr.test)
+  const trueJinja = objectLiteralToJinjaDict(ctx, whenTrue)
+  const falseJinja = objectLiteralToJinjaDict(ctx, whenFalse)
+  if (trueJinja === null || falseJinja === null) return null
+  return `(${trueJinja} if ${condJinja} else ${falseJinja})`
+}
+
+/**
+ * (#1971) Lower a bare object-literal expression (`{ align: 'start' }`),
+ * carried as the IR's structured `ParsedExpr` tree, to a Jinja dict via
+ * `objectLiteralToJinjaDict`, or null when it isn't a plain object literal.
+ * Used for inline object-literal child props (carousel `opts`).
+ */
+export function objectLiteralExprToJinjaDict(
+  ctx: JinjaSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'object-literal') return null
+  return objectLiteralToJinjaDict(ctx, expr)
+}
+
+/**
+ * Convert a static object literal into a Jinja dict string for a
+ * conditional spread. Only static string/identifier keys are allowed; values
+ * resolve via `convertExpressionToJinja` (or the `Record[propKey]` index
+ * lowering). Returns `null` for any computed/spread/dynamic key. Empty
+ * object → `{}`.
+ */
+export function objectLiteralToJinjaDict(
+  ctx: JinjaSpreadContext,
+  obj: Extract<ParsedExpr, { kind: 'object-literal' }>,
+): string | null {
+  const entries: string[] = []
+  for (const prop of obj.properties) {
+    // Shorthand `{ a }` was a `ShorthandPropertyAssignment` (not a
+    // `PropertyAssignment`), so the former parser rejected it — keep refusing.
+    if (prop.shorthand) return null
+    // A numeric key (`{ 1: x }`) was rejected by the former parser (only
+    // identifier / string-literal names were accepted); `keyKind`
+    // distinguishes it from a same-text string `'1'` key.
+    if (prop.keyKind === 'numeric') return null
+    const key = prop.key
+    const val = prop.value
+    const indexed = recordIndexAccessToJinja(ctx, val)
+    if (
+      indexed === null &&
+      val.kind === 'index-access' &&
+      !isLiteralIndex(val.index)
+    ) {
+      // Variable-index record access (`sizeMap[size]`) the static-inline
+      // path couldn't resolve (non-scalar value / non-const receiver).
+      // Record BF101 and bail so the spread surfaces the out-of-shape
+      // diagnostic, matching the Kolon port.
+      ctx.errors.push({
+        code: 'BF101',
+        severity: 'error',
+        message: `Spread object value '${stringifyParsedExpr(val)}' indexes a record map whose values aren't scalar literals — it can't lower to an inline Jinja dict.`,
+        loc: { file: ctx.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
+        suggestion: {
+          message: 'Index a record whose values are number/string literals, or move the spread into a \'use client\' component so hydration computes it.',
+        },
+      })
+      return null
+    }
+    const valJinja =
+      indexed !== null
+        ? indexed
+        // Thread the carried `val` tree straight through as `preParsed`
+        // (#2018) — no stringify→re-parse round-trip.
+        : ctx.convertExpressionToJinja('', val)
+    entries.push(`${jinjaHashKey(key)}: ${valJinja}`)
+  }
+  return entries.length === 0 ? '{}' : `{${entries.join(', ')}}`
+}
+
+/** True when a parsed index is a numeric or string literal (`arr[0]`, `m['k']`). */
+function isLiteralIndex(index: ParsedExpr): boolean {
+  return (
+    index.kind === 'literal' &&
+    (index.literalType === 'number' || index.literalType === 'string')
+  )
+}
+
+/**
+ * Lower a spread-object VALUE of the form `IDENT[KEY]` (CheckIcon's
+ * `sizeMap[size]`) to an inline indexed Jinja dict
+ *   `{'sm': 16, 'md': 20, ...}[size]`.
+ * Reuses the shared structural parse (`parseRecordIndexAccess`) — rebuilding
+ * the `IDENT[KEY]` node from the carried tree via `ts.factory` rather than
+ * re-parsing source text; this wrapper only does the single-quote escaping +
+ * bracket-index emit. Jinja indexes a dict literal with the SAME bracket
+ * syntax `{…}[key]` a JS object index would use — no Kolon-style divergence
+ * to steer around here.
+ */
+export function recordIndexAccessToJinja(ctx: JinjaSpreadContext, val: ParsedExpr): string | null {
+  // The only shape `parseRecordIndexAccess` accepts is `IDENT[KEY]` with
+  // identifier object and index, so rebuild exactly that node from the
+  // carried tree via `ts.factory` — no source-text re-parse.
+  if (
+    val.kind !== 'index-access' ||
+    val.object.kind !== 'identifier' ||
+    val.index.kind !== 'identifier'
+  ) {
+    return null
+  }
+  const tsVal = ts.factory.createElementAccessExpression(
+    ts.factory.createIdentifier(val.object.name),
+    ts.factory.createIdentifier(val.index.name),
+  )
+  const parsed = parseRecordIndexAccess(tsVal, ctx.localConstants ?? [], ctx.propsParams)
+  if (!parsed) return null
+  const entries = parsed.entries.map(e => {
+    const mapVal =
+      e.value.kind === 'number' ? e.value.text : `'${escapeJinjaSingleQuoted(e.value.text)}'`
+    return `${jinjaHashKey(e.key)}: ${mapVal}`
+  })
+  return `{${entries.join(', ')}}[${jinjaIdent(parsed.indexPropName)}]`
+}