@barefootjs/erb 0.17.0

package/src/adapter/index.ts

@@ -0,0 +1,6 @@
+/**
+ * ERB Template Adapter Exports
+ */
+
+export { ErbAdapter, erbAdapter } from './erb-adapter.ts'
+export type { ErbAdapterOptions } from './erb-adapter.ts'

package/src/adapter/lib/constants.ts

@@ -0,0 +1,37 @@
+/**
+ * Compile-time constant tables for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `lib/constants.ts`.
+ */
+
+import type { PrimitiveSpec } from './types.ts'
+
+/**
+ * Single source of truth for the ERB adapter's template-primitive
+ * surface. Each entry pairs the expected arity with the emit function.
+ * Adding / removing a primitive is a one-line change.
+ *
+ * The emit fn returns a Ruby expression (no surrounding `<%= %>`)
+ * suitable for embedding inside the ERB template action —
+ * `bf.json(val)`, `bf.floor(val)`, etc. Args arrive already
+ * Ruby-rendered via `convertExpressionToRuby` recursion, so a caller
+ * passing `props.config` reaches the emit fn as `v[:config]`.
+ */
+export const ERB_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. Per-instance derivation would re-build the same Map on
+ * every `new ErbAdapter()` call.
+ */
+export const ERB_PRIMITIVE_EMIT_MAP: Record<string, (args: string[]) => string> =
+  Object.fromEntries(
+    Object.entries(ERB_TEMPLATE_PRIMITIVES).map(([k, v]) => [k, v.emit])
+  )

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

@@ -0,0 +1,51 @@
+/**
+ * IR traversal helpers for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `lib/ir-scope.ts` (issue #2018
+ * track D lineage). Pure functions over the IR tree — no adapter instance
+ * state.
+ */
+
+import type { IRNode, IRProp, IRIfStatement, IRFragment } from '@barefootjs/jsx'
+
+/**
+ * Find the `children` prop's `jsx-children` payload (#1326). Narrowed
+ * via the AttrValue `kind` discriminator so adapter code stays type-
+ * safe if the IR shape evolves — adding a new AttrValue variant or
+ * renaming `children` to `jsxChildren` becomes a TS compile error
+ * here instead of silently dropping the children at runtime.
+ */
+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 (`consequent` + the `alternate`
+ * chain), since exactly one branch renders at runtime. Non-element branch
+ * tops (fragments / nested shapes) are walked one level so an
+ * `if (…) return <A/>` still resolves to `<A>`. (#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/ruby-naming.ts

@@ -0,0 +1,127 @@
+/**
+ * Ruby identifier / literal / hash-key conventions for the ERB adapter.
+ *
+ * Pure helpers, ported from (and extending) the Mojolicious adapter's
+ * `lib/perl-naming.ts` for Ruby's syntax. None read adapter instance
+ * state, so they live at module scope as the single source of truth for
+ * Ruby-identifier quoting, literal escaping, and marker-id encoding.
+ *
+ * ## Variable model
+ *
+ * Templates receive exactly two locals: `bf` (runtime) and `v` (vars Hash,
+ * symbol keys). Every prop / signal / memo / module-constant reference
+ * lowers to `v[:name]` — never a bare Ruby local — which sidesteps Ruby
+ * identifier-validity and reserved-word issues for that whole class of
+ * names (a prop literally named `class` or `Foo` is a non-issue: it's a
+ * *symbol* key, not a variable reference).
+ *
+ * The ONE place a bare Ruby local is still needed is a loop/block
+ * parameter (`todos().map(todo => ...)` → `|todo|`) — `rubyLocal` is the
+ * single naming rule for that case, matching the ERB adapter's binding
+ * architecture doc.
+ */
+
+/**
+ * Ruby's reserved words — cannot be used as a local variable / block
+ * parameter name (the parser reads them as keywords, not identifiers).
+ * `self`, `nil`, `true`, `false` are technically pseudo-variables/keywords
+ * with special meaning even in expression position, so they're included
+ * too — using one of these as a block param name is either a SyntaxError
+ * or silently shadows a builtin literal, either of which we want to avoid
+ * for the same "load-bearing loop var" reason the Perl side avoids
+ * `my $if = ...`.
+ */
+const RUBY_KEYWORDS: ReadonlySet<string> = new Set([
+  '__ENCODING__', '__LINE__', '__FILE__',
+  'BEGIN', 'END',
+  'alias', 'and', 'begin', 'break', 'case', 'class', 'def', 'defined?',
+  'do', 'else', 'elsif', 'end', 'ensure', 'false', 'for', 'if', 'in',
+  'module', 'next', 'nil', 'not', 'or', 'redo', 'rescue', 'retry',
+  'return', 'self', 'super', 'then', 'true', 'undef', 'unless', 'until',
+  'when', 'while', 'yield',
+  // Not Ruby keywords, but the two RESERVED locals every compiled template
+  // receives (the binding architecture contract: `bf` the runtime context,
+  // `v` the vars Hash). A loop/block param named `v` or `bf` (e.g.
+  // `items.values().map(v => ...)`, whose synthesized `.entries()` value
+  // binding is literally `v`) would otherwise shadow the vars Hash inside
+  // the loop body, silently breaking every subsequent `v[:name]` read for
+  // the rest of that scope. Route through the same collision-suffix path
+  // as a real keyword.
+  'bf', 'v',
+])
+
+/** A syntactically valid Ruby local-variable / block-parameter identifier
+ *  (must start lowercase-letter-or-underscore; a leading uppercase letter
+ *  parses as a constant reference, not a variable). */
+const VALID_RUBY_LOCAL = /^[a-z_][A-Za-z0-9_]*$/
+
+/**
+ * Map a JS loop/block parameter name (`todo`, `index`, `class`, `Item`) to
+ * a safe bare Ruby local. Appends a trailing `_` when the name collides
+ * with a Ruby keyword; when the name isn't even a syntactically valid
+ * local (leading uppercase — parses as a constant — or another invalid
+ * leading character), prefixes `_` instead so the result still starts
+ * lowercase/underscore. Every loop-var / block-param emission site in the
+ * adapter goes through this one helper — no inline mangling.
+ */
+export function rubyLocal(name: string): string {
+  if (RUBY_KEYWORDS.has(name)) return `${name}_`
+  if (VALID_RUBY_LOCAL.test(name)) return name
+  // Invalid leading character (most commonly a JS param starting with an
+  // uppercase letter, which Ruby would otherwise parse as a constant
+  // reference) — prefix rather than suffix so the fixed name still starts
+  // with a valid local-variable leading character.
+  return `_${name}`
+}
+
+/** Escape a string for a Ruby single-quoted literal: backslash first (so
+ *  it doesn't double-escape the quote we add next), then the quote. */
+export function escapeRubySingleQuoted(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+}
+
+/** Wrap a raw string value as a Ruby single-quoted literal. */
+export function rubyStringLiteral(s: string): string {
+  return `'${escapeRubySingleQuoted(s)}'`
+}
+
+/** A syntactically valid bare Ruby hash-key / symbol identifier. */
+const VALID_RUBY_SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*[?!]?$/
+
+/**
+ * Render `name` as a Ruby Hash literal SYMBOL key in `key: value` position.
+ * A JSX attribute / prop name like `data-slot` isn't a valid bare Ruby
+ * identifier — Ruby's `"quoted": value` symbol-key syntax accepts an
+ * arbitrary string, so a non-identifier name still renders as a valid
+ * symbol key (`"data-slot": value` → `{:"data-slot" => value}`).
+ * Identifier-safe names (`className`, `size`, `_bf_slot`) pass through
+ * unquoted (`size: value`) for readability.
+ */
+export function rubySymbolKey(name: string): string {
+  return VALID_RUBY_SYMBOL.test(name) ? `${name}:` : `"${name.replace(/"/g, '\\"')}":`
+}
+
+/**
+ * Render `name` as a Ruby symbol LITERAL (`:name` / `:"data-slot"`) — used
+ * for a compile-time-known Hash key read (`item[:field]`), as opposed to
+ * `rubySymbolKey`'s `key: value` Hash-literal position.
+ */
+export function rubySymbolLiteral(name: string): string {
+  return VALID_RUBY_SYMBOL.test(name) ? `:${name}` : `:"${name.replace(/"/g, '\\"')}"`
+}
+
+/**
+ * Encode an `IRLoop.markerId` into a Ruby-identifier-safe suffix for the
+ * `bf_iter_…` sort hoist local. Collision-free for marker ids that differ
+ * in any character — `-` and `_` map to distinct encodings (`_x2d` vs
+ * `__`) so `l-0` and `l_0` stay distinct.
+ *
+ * Today the IR only emits `l<digits>` so the encoding is mostly an
+ * identity, but pinning collision-freeness up front avoids a silent
+ * variable-shadow bug if a future marker generator widens the alphabet.
+ */
+export function rubyIdentifierFromMarkerId(markerId: string): string {
+  return markerId.replace(/[^a-zA-Z0-9]/g, (ch) =>
+    ch === '_' ? '__' : `_x${ch.charCodeAt(0).toString(16)}`
+  )
+}

package/src/adapter/lib/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared type aliases for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `lib/types.ts`. 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
+}
+
+/**
+ * ERB adapter's IRNode render context. The ERB lowering currently doesn't
+ * consume any render-position flags (`isRootOfClientComponent` is handled
+ * differently here than in Hono/Go), so the Ctx is empty. Kept as a named
+ * alias so future flags can extend it without changing the `IRNodeEmitter`
+ * interface.
+ */
+export type ErbRenderCtx = Record<string, never>
+
+export interface ErbAdapterOptions {
+  /** 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,75 @@
+/**
+ * In-template memo / context seeding for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `memo/seed.ts` (issue #2018 track D
+ * lineage). Free functions taking an `ErbMemoContext` (built by the
+ * adapter's `memoCtx` getter) so the cluster depends only on the recursive
+ * expression entry, not the whole adapter class. These emit `<% v[:x] =
+ * ...; %>` seed lines that let the template body's `v[:x]` resolve to a
+ * derived signal/memo value or an active context value at SSR time. Mirror
+ * of the Go adapter's `memo/*`, retargeted to the vars-Hash variable model.
+ */
+
+import {
+  type ComponentIR,
+  type ContextConsumer,
+  collectContextConsumers,
+  computeSsrSeedPlan,
+} from '@barefootjs/jsx'
+
+import type { ErbMemoContext } from '../emit-context.ts'
+import { rubyStringLiteral } from '../lib/ruby-naming.ts'
+
+/** Ruby literal for a context-consumer's `createContext` default. */
+export function contextDefaultRuby(c: ContextConsumer): string {
+  const d = c.defaultValue
+  if (d === null || d === undefined) return 'nil'
+  if (typeof d === 'string') return rubyStringLiteral(d)
+  if (typeof d === 'boolean') return d ? 'true' : 'false'
+  return String(d)
+}
+
+/**
+ * Emit one `<% v[:<local>] = bf.use_context(...) %>` seed line per context
+ * consumer so the template body's `v[:<local>]` resolves to the active
+ * provider value (or the `createContext` default).
+ */
+export function generateContextConsumerSeed(ir: ComponentIR): string {
+  const consumers = collectContextConsumers(ir.metadata)
+  if (consumers.length === 0) return ''
+  return (
+    consumers
+      .map(
+        c =>
+          `<% v[:${c.localName}] = bf.use_context('${c.contextName}', ${contextDefaultRuby(c)}) %>`,
+      )
+      .join('\n') + '\n'
+  )
+}
+
+/**
+ * Emit `<% v[:<name>] = <ruby> %>` seed lines 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 Ruby and applies the two
+ * backend-specific emit guards: skip an empty lowering, and skip a lowering
+ * that references no `v[:var]` at all (a constant init/body — e.g. a
+ * `derived` step with empty `frees` — keeps the existing static ssr-defaults
+ * seed instead). `env-reader` and `opaque` steps emit nothing (the runtime
+ * supplies the reader, or the adapter's ssr-defaults path already covers
+ * it). (#1297, #2075)
+ */
+export function generateDerivedMemoSeed(ctx: ErbMemoContext, 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 lines: string[] = []
+  for (const step of plan.steps) {
+    if (step.kind !== 'derived') continue
+    const ruby = ctx.convertExpressionToRuby(step.expr, step.parsed)
+    if (ruby === '' || !/v\[:[A-Za-z_]\w*\]/.test(ruby)) continue
+    lines.push(`<% v[:${step.name}] = ${ruby} %>`)
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : ''
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Prop classification for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `props/prop-classes.ts` (issue #2018
+ * track D lineage). 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'
+
+/**
+ * SSR-resolvable context-value names: props, signal getters, memos.
+ * A `<Ctx.Provider value>` member NOT in this set is a client-only function
+ * with no SSR value, lowered to `nil`.
+ */
+export function collectProviderDataNames(ir: ComponentIR): Set<string> {
+  return new Set<string>([
+    ...ir.metadata.propsParams.map(p => p.name),
+    ...(ir.metadata.signals ?? []).map(s => s.getter),
+    ...(ir.metadata.memos ?? []).map(m => m.name),
+  ])
+}
+
+/**
+ * Props whose declared TS type is boolean — a bare binding of one
+ * (`data-active={props.isActive}`) must stringify as JS `String(boolean)`
+ * ("true"/"false"), matching the `bf.bool_str` helper's output.
+ */
+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),
+  )
+}
+
+/**
+ * No-destructure-default props → `nil` when the caller omits them → guard
+ * their bare-reference attribute emission with a Ruby nil-check so the
+ * attribute drops instead of rendering `attr=""` (Hono-style nullish
+ * omission). A prop WITH a destructure default (`value = ''`) is never
+ * `nil` in the body and must stay unconditional, so it is excluded. Mirrors
+ * the Go adapter's nillable-field guard: there the witness is the resolved
+ * `interface{}` field type; here it is the absence of a default. Excludes
+ * concrete-primitive types (`string`/`number`/`boolean`) to match the Go
+ * adapter's scope, which guards only nillable fields and leaves concrete
+ * fields unconditional.
+ */
+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` (the analyzer infers this from a string-literal initial
+ * value) or, defensively, when its initial value is a bare string literal; a
+ * prop when its annotated type is `string`.
+ *
+ * Ruby's `==`/`!=` don't coerce operand types the way Perl's numeric `==`
+ * does, so this set does NOT drive equality-operator selection in the ERB
+ * adapter (unlike Mojo's `eq`/`ne` split). It still matters for **index
+ * access**: `obj[index]` lowers a string-typed `index` to a Hash lookup
+ * (`obj[index.to_sym]`, JSON-shaped Ruby hashes use symbol keys) and any
+ * other type to an Array lookup (`obj[index]`) — see
+ * `expr/operand.ts::isStringTypedOperand`.
+ */
+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,176 @@
+/**
+ * Object-literal / conditional-spread → Ruby Hash lowering for the ERB
+ * template adapter.
+ *
+ * Ported from the Mojolicious adapter's `spread/spread-codegen.ts` (issue
+ * #2018 track D lineage). Free functions taking an `ErbSpreadContext` (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. Mirror of the Go adapter's
+ * `spread/spread-codegen.ts`.
+ *
+ * The conditional-spread / object-literal entries read the IR-carried
+ * structured `ParsedExpr` tree instead of re-parsing the source with
+ * `ts.createSourceFile`. The condition and scalar values are threaded
+ * straight into `ctx.convertExpressionToRuby` as its `preParsed` argument
+ * (cf. go-template's `convertExpressionToGo(jsExpr, out?, preParsed?)`), so
+ * no stringify→re-parse round-trip occurs. The `ts.factory` rebuild in
+ * `recordIndexAccessToRuby` only reconstructs the `IDENT[KEY]` node the
+ * shared `parseRecordIndexAccess` parser accepts; no source-text re-parse.
+ * `stringifyParsedExpr` is retained solely for the BF101 diagnostic message
+ * (display purposes).
+ */
+
+import ts from 'typescript'
+import { parseRecordIndexAccess, stringifyParsedExpr } from '@barefootjs/jsx'
+import type { ParsedExpr } from '@barefootjs/jsx'
+
+import type { ErbSpreadContext } from '../emit-context.ts'
+import { rubySymbolKey, escapeRubySingleQuoted } from '../lib/ruby-naming.ts'
+
+/**
+ * Lower a `cond ? {…} : {…}` conditional-spread expression — carried as the
+ * IR's structured `ParsedExpr` tree — to a Ruby ternary over two Hashes, or
+ * null when it isn't that shape. `parseExpression` already strips redundant
+ * parentheses, so the conditional / object-literal shapes surface directly.
+ */
+export function conditionalSpreadToRuby(
+  ctx: ErbSpreadContext,
+  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` — no stringify→re-parse round-trip; `convertExpressionToRuby`
+  // uses the tree directly and derives any diagnostic text from it.
+  const condRuby = ctx.convertExpressionToRuby('', expr.test)
+  const trueRuby = objectLiteralToRubyHash(ctx, whenTrue)
+  const falseRuby = objectLiteralToRubyHash(ctx, whenFalse)
+  if (trueRuby === null || falseRuby === null) return null
+  // JS ternary tests JS truthiness — wrap, mirroring the top-level emitter's
+  // `conditional()`.
+  return `(bf.truthy?(${condRuby}) ? ${trueRuby} : ${falseRuby})`
+}
+
+/**
+ * Lower a bare object-literal expression (`{ align: 'start' }`), carried as
+ * the IR's structured `ParsedExpr` tree, to a Ruby Hash via
+ * `objectLiteralToRubyHash`, or null when it isn't a plain object literal.
+ * Used for inline object-literal child props (carousel `opts`).
+ */
+export function objectLiteralExprToRubyHash(
+  ctx: ErbSpreadContext,
+  expr: ParsedExpr | undefined,
+): string | null {
+  if (!expr || expr.kind !== 'object-literal') return null
+  return objectLiteralToRubyHash(ctx, expr)
+}
+
+/**
+ * Convert a static object literal into a Ruby Hash string for a conditional
+ * spread. Only static string/identifier keys are allowed; values resolve
+ * via `convertExpressionToRuby`. Returns null for any computed/spread/
+ * dynamic key. Empty object → `{}`.
+ */
+export function objectLiteralToRubyHash(
+  ctx: ErbSpreadContext,
+  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 = recordIndexAccessToRuby(ctx, val)
+    if (
+      indexed === null &&
+      val.kind === 'index-access' &&
+      !isLiteralIndex(val.index)
+    ) {
+      // Variable-index record access (`sizeMap[size]`) that the
+      // static-inline path couldn't resolve — a non-scalar record value,
+      // or a non-const receiver. Record BF101 and bail so the whole spread
+      // surfaces the out-of-shape diagnostic.
+      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 Ruby Hash.`,
+        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 valRuby =
+      indexed !== null
+        ? indexed
+        // Thread the carried `val` tree straight through as `preParsed` —
+        // no stringify→re-parse round-trip.
+        : ctx.convertExpressionToRuby('', val)
+    entries.push(`${rubySymbolKey(key)} ${valRuby}`)
+  }
+  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]` where:
+ *   - `IDENT` resolves via `localConstants` to a MODULE-scope object
+ *     literal whose property values are all scalar (number/string)
+ *     literals under static (string-literal or identifier) keys
+ *     (a `Record<staticKeys, scalar>` map like `sizeMap`), AND
+ *   - `KEY` is a bare identifier that is a prop.
+ * Emits an inline indexed Ruby Hash:
+ *   `{ sm: 16, md: 20 }[v[:size].to_sym]`
+ *
+ * Returns the Ruby string when convertible, else `null` so the caller falls
+ * back to its normal value lowering (which records BF101 for an unsupported
+ * shape). Mirror of the Go adapter's `recordIndexAccessToGoMap`.
+ */
+export function recordIndexAccessToRuby(ctx: ErbSpreadContext, val: ParsedExpr): string | null {
+  // `parseRecordIndexAccess` (the shared single-source-of-truth parser) takes a
+  // `ts.Expression`. The only shape it 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 needed. Any other shape can't match
+  // and short-circuits to `null` here.
+  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),
+  )
+  // Shared structural parse (single source of truth in `@barefootjs/jsx`);
+  // this wrapper only does the Ruby-specific emit (Hash literal + symbol
+  // key access) from the structured result.
+  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 : `'${escapeRubySingleQuoted(e.value.text)}'`
+    return `${rubySymbolKey(e.key)} ${mapVal}`
+  })
+  return `{ ${entries.join(', ')} }[v[:${parsed.indexPropName}].to_sym]`
+}

package/src/adapter/value/parsed-literal.ts

@@ -0,0 +1,29 @@
+/**
+ * String-type value helpers for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `value/parsed-literal.ts`
+ * (issue #2018 track D lineage). Pure functions over analyzer type info /
+ * const-initializer text — no adapter instance state.
+ *
+ * SHARED CANDIDATE: `isStringTypeInfo` and `isBareStringLiteral` are
+ * byte-identical to the Mojo/Xslate adapters' copies and adapter-agnostic.
+ *
+ * Module-scope pure-string-const inlining is owned by the shared
+ * `collectModuleStringConsts` in `@barefootjs/jsx` (consumed via
+ * `moduleStringConsts`), so no adapter-local source re-parse lives here.
+ */
+
+import type { TypeInfo } from '@barefootjs/jsx'
+
+/** True when `type` is the `string` primitive. */
+export function isStringTypeInfo(type: TypeInfo | undefined): boolean {
+  return type?.kind === 'primitive' && type.primitive === 'string'
+}
+
+/** True when `initialValue` is a bare string-literal expression (`'x'` /
+ *  `"x"`), used as a fallback for signals whose type wasn't inferred. */
+export function isBareStringLiteral(initialValue: string | undefined): boolean {
+  if (!initialValue) return false
+  const v = initialValue.trim()
+  return (v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))
+}

package/src/build.ts

@@ -0,0 +1,37 @@
+// ERB build config factory for barefoot.config.ts
+
+import type { BuildOptions } from '@barefootjs/jsx'
+import { ErbAdapter } from './adapter/index.ts'
+import type { ErbAdapterOptions } from './adapter/index.ts'
+
+export interface ErbBuildOptions extends BuildOptions {
+  /** Adapter-specific options passed to ErbAdapter */
+  adapterOptions?: ErbAdapterOptions
+}
+
+/**
+ * Create a BarefootBuildConfig for ERB (Embedded Ruby) template projects.
+ *
+ * Uses structural typing — does not import BarefootBuildConfig to avoid a
+ * circular dependency between @barefootjs/erb and @barefootjs/cli.
+ */
+export function createConfig(options: ErbBuildOptions = {}) {
+  return {
+    adapter: new ErbAdapter(options.adapterOptions),
+    paths: options.paths,
+    components: options.components,
+    outDir: options.outDir,
+    minify: options.minify,
+    contentHash: options.contentHash,
+    externals: options.externals,
+    externalsBasePath: options.externalsBasePath,
+    bundleEntries: options.bundleEntries,
+    localImportPrefixes: options.localImportPrefixes,
+    outputLayout: options.outputLayout ?? {
+      templates: 'templates',
+      clientJs: 'client',
+      runtime: 'client',
+    },
+    postBuild: options.postBuild,
+  }
+}