@barefootjs/erb 0.17.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@barefootjs/erb",
+  "version": "0.17.0",
+  "description": "ERB (Embedded Ruby) adapter for BarefootJS — compiles IR to .erb templates and ships the Ruby rendering backend; runs under any Rack app (Sinatra, Rails)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./test-render": {
+      "bun": "./src/test-render.ts"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/build.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "erb",
+    "ruby",
+    "sinatra",
+    "rack",
+    "rails",
+    "barefoot",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/adapter-erb"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "0.17.1"
+  },
+  "peerDependencies": {
+    "@barefootjs/jsx": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@barefootjs/adapter-tests": "0.1.0",
+    "@barefootjs/jsx": "0.17.1",
+    "typescript": "^5.0.0"
+  }
+}

package/src/__tests__/erb-adapter.test.ts

@@ -0,0 +1,298 @@
+/**
+ * ErbAdapter — Conformance Tests
+ *
+ * Runs the shared adapter conformance corpus (JSX fixtures, template
+ * primitives, marker conformance) against the ERB (Embedded Ruby)
+ * adapter, rendering each fixture end-to-end through real Ruby stdlib
+ * `erb` + `BarefootJS::Backend::Erb` via `renderErbComponent`.
+ *
+ * The ERB adapter was ported from the Mojolicious adapter (EP → ERB is a
+ * 1:1 embedded-language mapping — see `packages/adapter-erb/src/adapter/
+ * erb-adapter.ts`'s file docstring), so the skip / diagnostic sets below
+ * start from mojo's and diverge only where the engine genuinely differs.
+ * Every divergence carries a one-line rationale.
+ *
+ * Unlike Kolon (Text::Xslate), Ruby is a full general-purpose language:
+ * component-invocation Hash literals support a real double-splat
+ * (`**hash`), the direct analog of Perl's `%{$props}` flatten. So the
+ * `button` / `kbd` shapes that Xslate refuses (BF101 — Kolon has no
+ * "splat a runtime hash into named call args" form) LOWER cleanly on
+ * ERB, matching mojo rather than xslate.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { runAdapterConformanceTests } from '@barefootjs/adapter-tests'
+import { ErbAdapter } from '../adapter'
+import { renderErbComponent, ErbNotAvailableError } from '../test-render'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { conformancePins } from '../conformance-pins'
+
+runAdapterConformanceTests({
+  name: 'erb',
+  factory: () => new ErbAdapter(),
+  render: renderErbComponent,
+  // No JSX-render skips: every shared conformance fixture — including
+  // the composed `site/ui` demo corpus (#1467 / #1897) — renders to
+  // Hono parity on real Ruby `erb`. `data-table` came off via the
+  // body-children `inLoop` reset (#1896): the loop-item component
+  // (TableRow) still gets `ComponentName_<random>` scope IDs, but its
+  // body children (TableCell) now receive `_bf_slot` for deterministic
+  // parent-scope-derived IDs matching Hono.
+  // Per-fixture build-time contracts for shapes the ERB adapter
+  // intentionally refuses to lower. Lives in `../conformance-pins` —
+  // mirrors mojo's set (the lowering gates — `isLowerableLoopDestructure`,
+  // `collectImportedLoopChildComponentErrors`, `refuseUnsupportedAttr
+  // Expression`, the #2038 nested-higher-order-callback gate — are shared
+  // code in `@barefootjs/jsx` that every EP/ERB-family adapter reuses
+  // verbatim).
+  expectedDiagnostics: conformancePins,
+  // Template-primitive registry: `USER_IMPORT_VIA_CONST` and
+  // `NO_DOUBLE_REWRITE_OF_PROPS_OBJECT` now pass (#2069) — a bespoke user
+  // import can never be added to the string-keyed registry, but the
+  // shared `RelocateEnv.loweringMatchers` acceptance path recognises it
+  // via a `LoweringPlugin` the case setup registers around the compile
+  // (see `packages/adapter-tests/src/cases/template-primitives.ts`). No
+  // skips left, so `skipTemplatePrimitives` is omitted entirely.
+  skipMarkerConformance: new Set([
+    // Same as Hono / Mojo / Xslate: `/* @client */` markers on TodoApp's
+    // keyed `.map` intentionally elide a slot id from the SSR template
+    // that the IR still declares (s6). See hono-adapter.test for the
+    // contract.
+    'todo-app',
+    // #1467 Phase 2e: same `/* @client */` keyed-map elision (data-table).
+    'data-table',
+  ]),
+  onRenderError: (err, id) => {
+    if (err instanceof ErbNotAvailableError) {
+      console.log(`Skipping [${id}]: ${err.message}`)
+      return true
+    }
+    return false
+  },
+})
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function compileToIR(source: string): ComponentIR {
+  const result = compileJSX(source.trimStart(), 'test.tsx', {
+    adapter: new ErbAdapter(),
+    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) {
+  return new ErbAdapter().generate(compileToIR(source))
+}
+
+// =============================================================================
+// ERB-Specific Tests
+// =============================================================================
+
+describe('ErbAdapter - SSR context propagation (#1297)', () => {
+  test('provider brackets children with provide_context / revoke_context', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createContext, useContext } from '@barefootjs/client'
+const ThemeContext = createContext('light')
+export function ThemeRoot() {
+  return <div><ThemeContext.Provider value="dark"><ThemeLabel /></ThemeContext.Provider></div>
+}
+function ThemeLabel() { const theme = useContext(ThemeContext); return <span>{theme}</span> }
+`)
+    expect(template).toContain("bf.provide_context('ThemeContext', 'dark')")
+    expect(template).toContain("bf.revoke_context('ThemeContext')")
+    expect(template.indexOf('provide_context')).toBeLessThan(template.indexOf('render_child'))
+    expect(template.indexOf('render_child')).toBeLessThan(template.indexOf('revoke_context'))
+  })
+
+  test('consumer seeds its local from use_context with the createContext default', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createContext, useContext } from '@barefootjs/client'
+const ThemeContext = createContext('light')
+export function ThemeLabel() { const theme = useContext(ThemeContext); return <span>{theme}</span> }
+`)
+    expect(template).toContain("v[:theme] = bf.use_context('ThemeContext', 'light')")
+  })
+})
+
+describe('ErbAdapter - prop-derived memo SSR seeding (#1297)', () => {
+  test('seeds a prop-derived memo from the prop var', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function Child(props: { value: number }) {
+  const displayValue = createMemo(() => props.value * 10)
+  return <span>{displayValue()}</span>
+}
+`)
+    expect(template).toMatch(/v\[:displayValue\]\s*=\s*\(v\[:value\]\s*\*\s*10\)/)
+  })
+
+  test('seeds a memo over a destructured prop', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function Child({ value }: { value: number }) {
+  const displayValue = createMemo(() => value * 10)
+  return <span>{displayValue()}</span>
+}
+`)
+    expect(template).toMatch(/v\[:displayValue\]\s*=\s*\(v\[:value\]\s*\*\s*10\)/)
+  })
+})
+
+describe('ErbAdapter - #2075 searchParams()-derived memo seeding', () => {
+  // A memo derived from the createSearchParams() env signal must seed
+  // in-template from the canonical per-request `v[:search_params]` reader —
+  // including under a local alias (`const [sp] = …`), which the expression
+  // lowering canonicalises.
+  test('seeds an aliased scalar derived memo from the canonical reader', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function SortStatus() {
+  const [sp] = createSearchParams()
+  const sort = createMemo(() => sp().get('sort') ?? 'date')
+  return <p>sort: {sort()}</p>
+}
+`)
+    expect(template).toContain(
+      "v[:sort] = ((v[:search_params].get('sort')).nil? ? 'date' : v[:search_params].get('sort'))",
+    )
+  })
+
+  // A list-filter memo chained off the derived memo seeds too: the block
+  // param (`p`) is a lowering-internal binding, not an out-of-scope
+  // template var (the pre-#2075 availability check rejected them and the
+  // list rendered empty at SSR).
+  test('seeds a filter memo chained off the derived memo', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function TaggedList(props: { items: { title: string; tags: string[] }[] }) {
+  const [searchParams] = createSearchParams()
+  const tag = createMemo(() => searchParams().get('tag') ?? '')
+  const visible = createMemo(() => props.items.filter((p) => !tag() || p.tags.includes(tag())))
+  return <ul>{visible().map((p) => <li key={p.title}>{p.title}</li>)}</ul>
+}
+`)
+    expect(template).toContain(
+      "v[:tag] = ((v[:search_params].get('tag')).nil? ? '' : v[:search_params].get('tag'))",
+    )
+    expect(template).toMatch(/v\[:visible\] = v\[:items\]\.select \{ \|p\|/)
+  })
+
+  // The seed-scope guard used to scan the LOWERED Ruby string, allowing
+  // every arrow-callback param tree-wide. That let an outer, unbound `p`
+  // (shadowed only inside the callback) slip past the guard as if it were
+  // the callback's own bound `p` — emitting a bogus seed line that would
+  // read an un-seeded key. The guard now walks the parsed SOURCE tree with
+  // proper lexical scoping (`freeIdentifiers`), so this shape seeds nothing
+  // and falls back to the nil/ssr-defaults path.
+  test('an outer unbound `p` shadowed only inside the callback does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { items: { ok: boolean }[] }) {
+  const visible = createMemo(() => props.items.filter((p) => p.ok) && p)
+  return <div>{String(visible())}</div>
+}
+`)
+    expect(template).not.toMatch(/v\[:visible\] =/)
+  })
+
+  // An out-of-scope bare `_` reference (not a lowering-internal loop-index
+  // binding) must not seed either — the old unconditional allow-list masked
+  // this.
+  test('an out-of-scope bare `_` reference does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { count: number }) {
+  const doubled = createMemo(() => props.count * 2 + _)
+  return <div>{doubled()}</div>
+}
+`)
+    expect(template).not.toMatch(/v\[:doubled\] =/)
+  })
+})
+
+describe('ErbAdapter - prop-derived signal SSR seeding + data-key (#1297, toggle-shared)', () => {
+  test('seeds a prop-derived (different-name) signal from the prop var', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Item(props: { defaultOn?: boolean }) {
+  const [on, setOn] = createSignal(props.defaultOn ?? false)
+  return <button>{on() ? 'ON' : 'OFF'}</button>
+}
+`)
+    expect(template).toMatch(/v\[:on\]\s*=\s*\(\(v\[:defaultOn\]\)\.nil\?/)
+  })
+
+  test('emits data_key_attr on the component root', () => {
+    const { template } = compileAndGenerate(`
+export function Item() { return <div class="x">hi</div> }
+`)
+    expect(template).toContain('bf.data_key_attr')
+  })
+
+  test('emits data_key_attr on each branch root of an if-statement root', () => {
+    const { template } = compileAndGenerate(`
+export function Item({ on }: { on?: boolean }) {
+  if (on) return <div class="a">A</div>
+  return <div class="b">B</div>
+}
+`)
+    const count = (template.match(/bf\.data_key_attr/g) ?? []).length
+    expect(count).toBe(2)
+  })
+})
+
+describe('ErbAdapter - #1966 @client defers attribute bindings', () => {
+  function compileAttr(attrExpr: string) {
+    const adapter = new ErbAdapter()
+    const ir = compileToIR(`
+"use client"
+import { createSignal } from "@barefootjs/client"
+export function C() {
+  const [sel] = createSignal(0)
+  const pred = (n: number) => sel() === n
+  return <div data-x={${attrExpr}}>hi</div>
+}
+`)
+    const template = adapter.generate(ir).template ?? ''
+    const errors = (adapter as unknown as { errors: { code: string }[] }).errors ?? []
+    return { errors, template }
+  }
+
+  test('bare emits data-x; @client omits it from SSR', () => {
+    expect(compileAttr('pred(1)').template).toContain('data-x')
+    const deferred = compileAttr('/* @client */ pred(1)')
+    expect(deferred.errors).toEqual([])
+    expect(deferred.template).not.toContain('data-x')
+  })
+})
+
+describe('ErbAdapter - component-prop spread via Ruby **hash (button/kbd shape)', () => {
+  // The direct engine-divergence case from xslate: a `{...props}` spread
+  // into a CHILD component's invocation Hash lowers to Ruby's native
+  // double-splat, unlike Kolon (no such call-arg splat form).
+  test('spreads a rest-props bag into a child component call via **hash', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { Leaf } from './leaf'
+function Slot({ ...rest }: { [key: string]: unknown }) {
+  return <Leaf {...rest} />
+}
+export { Slot }
+`)
+    expect(template).toMatch(/\*\*v\[:rest\]/)
+  })
+})

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

@@ -0,0 +1,122 @@
+/**
+ * Component-tree analysis for the ERB template adapter.
+ *
+ * Ported from the Mojolicious adapter's `analysis/component-tree.ts` (issue
+ * #2018 track D lineage). 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 /
+ * Mojo adapters' check — the ERB adapter has the same cross-template-
+ * registration constraint at request time. Returns the diagnostics so the
+ * caller pushes them onto its own error list.
+ */
+export function collectImportedLoopChildComponentErrors(
+  ir: ComponentIR,
+  componentName: string,
+): CompilerError[] {
+  const errors: CompilerError[] = []
+  // Collect every name imported from a relative-path module (no
+  // case filter — `IRComponent` nodes only exist for PascalCase JSX
+  // usages, so a lowercase utility import in the set can't match
+  // anyway, and any heuristic on the import name itself would be
+  // strictly less robust than the structural IR check below).
+  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 ERB 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 ERB 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,157 @@
+/**
+ * Structural classifier for JS expressions whose result is a boolean
+ * value (or unambiguously stringifies to "true"/"false" in JS).
+ *
+ * Used by the ERB adapter's `emitExpression` to decide whether to
+ * route a reactive attribute binding through the `bf.bool_str` Ruby
+ * runtime helper (mirrors the Mojo/Xslate adapters' `bool_str` use).
+ * Ruby has no bare-comparison-to-string coercion either: `(count > 0)`
+ * evaluates to `true`/`false` objects, which `to_s` would render as
+ * the literal strings `"true"`/`"false"` — that part already matches
+ * JS `String(boolean)`. The wrapper still exists for parity with the
+ * Perl/Kolon family and for the cases below where the source
+ * expression is *opaque* (a bare call) but the attribute name
+ * witnesses a boolean value.
+ *
+ * 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 `convertExpressionToRuby` 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. Those
+ * carry their own (Ruby-coerced) value through unchanged, which
+ * stays correct for non-boolean shapes.
+ */
+
+import { parseExpression, type ParsedExpr } from '@barefootjs/jsx'
+
+const COMPARISON_OPS = new Set([
+  '<',
+  '>',
+  '<=',
+  '>=',
+  '==',
+  '===',
+  '!=',
+  '!==',
+])
+
+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)
+}
+
+/**
+ * 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
+  // Ruby truthy / falsy to true / false — a fixture that wants the
+  // literal `"mixed"` binds 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)
+}
+
+/**
+ * True when `expr` is (structurally) a top-level `String(...)` call — the
+ * one JS shape that has ALREADY fully stringified its argument per JS
+ * `String(boolean)` semantics before the attribute emitter's `bool_str`
+ * wrap decision runs. `convertExpressionToRuby` lowers `String(x)` through
+ * the `ERB_TEMPLATE_PRIMITIVES` registry to `bf.string(x)`, which for a
+ * real Ruby `true`/`false` already returns the JS-correct `"true"` /
+ * `"false"` text (`Context#string`'s `TrueClass`/`FalseClass` branch).
+ * Piping that STRING through `bf.bool_str` again is a bug, not a harmless
+ * no-op: Ruby has no falsy-string (only `nil`/`false` are falsy), so
+ * `bf.bool_str("false")` unconditionally returns `"true"` — every
+ * `aria-checked={String(props.checked ?? false)}`-shaped binding would
+ * render `"true"` regardless of the underlying value. Perl doesn't share
+ * this bug (`"0"` — what `JSON::PP::false` stringifies to — IS Perl-falsy),
+ * which is why the Mojo/Xslate emitters don't need this guard; ERB's
+ * truthiness model requires it. Detected structurally off the parsed
+ * expression (not a text scan), so a user-defined helper merely NAMED
+ * `String` elsewhere can't false-positive: the aria-attr / boolean-result
+ * detectors already need real parse trees, and a bespoke `String` lookalike
+ * would need to be a genuinely zero-ambiguity call-to-`String` shape to
+ * match here in the first place.
+ */
+export function isExplicitStringCall(expr: string): boolean {
+  const parsed = parseExpression(expr.trim())
+  if (!parsed) return false
+  return parsed.kind === 'call' && parsed.callee.kind === 'identifier' && parsed.callee.name === 'String'
+}