@barefootjs/erb 0.30.6 → 0.31.0

package/lib/barefoot_js.rb

@@ -68,6 +68,8 @@ module BarefootJS
     bf_accessor :backend
     bf_accessor :_scripts, default: -> { [] }
     bf_accessor :_script_seen, default: -> { {} }
+    bf_accessor :_preloads, default: -> { [] }
+    bf_accessor :_preload_seen, default: -> { {} }
     bf_accessor :_scope_id
     bf_accessor :_is_child, default: -> { false }
     bf_accessor :_bf_parent
@@ -217,8 +219,28 @@ module BarefootJS
       _scripts.push(path)
     end
 
+    # Register a `<link rel="modulepreload">` hint (mirrors `register_script`
+    # exactly: same dedup-by-path set, same insertion-order array, same
+    # lifetime/reset semantics, same no-output-string return so the compiled
+    # ERB template's `<% bf.register_preload(...) %>` produces no bytes
+    # where it sits). The `<link>` itself is only ever emitted by `scripts`
+    # below, never here -- a preload registration must never inject a node
+    # into a component's own template output (see the previous attempt's
+    # regression this guards against).
+    def register_preload(path)
+      return if _preload_seen.key?(path)
+
+      _preload_seen[path] = true
+      _preloads.push(path)
+    end
+
+    # Emits preload hints BEFORE script tags -- a hint that arrives after
+    # the script it describes is useless. Same escaping (none; paths are
+    # caller-trusted resolved URLs) as the script tags below.
     def scripts
-      _scripts.map { |path| %(<script type="module" src="#{path}"></script>) }.join("\n")
+      preload_tags = _preloads.map { |path| %(<link rel="modulepreload" crossorigin href="#{path}">) }
+      script_tags = _scripts.map { |path| %(<script type="module" src="#{path}"></script>) }
+      (preload_tags + script_tags).join("\n")
     end
 
     # -----------------------------------------------------------------
@@ -255,8 +277,9 @@ module BarefootJS
     # Bulk registration from build manifest
     # -----------------------------------------------------------------
     #
-    # `bf build` emits dist/templates/manifest.json describing every
-    # component the page might invoke. This walks that manifest and
+    # `vite build` (via `@barefootjs/erb/vite`'s `barefoot()` plugin) emits
+    # dist/templates/manifest.json describing every component the page
+    # might invoke. This walks that manifest and
     # registers one child renderer per UI registry entry (`ui/<name>/index`
     # -> slot key `<name>`), seeding each child's template vars from the
     # manifest's statically-derived `ssrDefaults` (prop destructure
@@ -300,6 +323,8 @@ module BarefootJS
           child_bf._child_renderers(parent._child_renderers)
           child_bf._scripts(parent._scripts)
           child_bf._script_seen(parent._script_seen)
+          child_bf._preloads(parent._preloads)
+          child_bf._preload_seen(parent._preload_seen)
 
           extra =
             if sig_init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/erb",
-  "version": "0.30.6",
+  "version": "0.31.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",
@@ -17,9 +17,9 @@
     "./test-render": {
       "bun": "./src/test-render.ts"
     },
-    "./build": {
-      "types": "./dist/build.d.ts",
-      "import": "./dist/build.js"
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
     }
   },
   "files": [
@@ -30,7 +30,7 @@
   ],
   "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:js": "bun build ./src/index.ts ./src/adapter/index.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared --external @barefootjs/vite --external vite && bun build ./src/vite.ts --outfile ./dist/vite.js --format esm --target node --external @barefootjs/vite --external vite --external typescript",
     "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
     "test": "bun test",
     "clean": "rm -rf dist",
@@ -54,14 +54,27 @@
     "directory": "packages/adapter-erb"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.30.6"
+    "@barefootjs/shared": "0.31.0"
   },
   "peerDependencies": {
-    "@barefootjs/jsx": ">=0.2.0"
+    "@barefootjs/jsx": ">=0.2.0",
+    "@barefootjs/vite": ">=0.2.0",
+    "vite": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@barefootjs/vite": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.30.6",
-    "typescript": "^5.0.0"
+    "@barefootjs/jsx": "0.31.0",
+    "@barefootjs/vite": "0.31.0",
+    "@barefootjs/client": "0.31.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0"
   }
 }

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

@@ -507,3 +507,147 @@ export function Parent() {
     expect(template).not.toContain('bf_prop_data')
   })
 })
+
+describe('ErbAdapter - scriptAssets (Vite late-binding, PR1)', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('emits one register_script per URL, in order, when scriptAssets is set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+    })
+    const runtimeIdx = template.indexOf("bf.register_script('/assets/runtime-abc123.js')")
+    const compIdx = template.indexOf("bf.register_script('/assets/counter-def456.js')")
+    expect(runtimeIdx).toBeGreaterThanOrEqual(0)
+    expect(compIdx).toBeGreaterThanOrEqual(0)
+    expect(runtimeIdx).toBeLessThan(compIdx)
+    // Legacy computed paths must not leak in.
+    expect(template).not.toContain('/static/components/barefoot.js')
+    expect(template).not.toContain('Counter.client.js')
+  })
+
+  test('emits a single registration for a single-element scriptAssets array', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/only-one.js'],
+    })
+    expect(template).toContain("bf.register_script('/assets/only-one.js')")
+    expect(template.match(/register_script/g)?.length).toBe(1)
+  })
+
+  test('an empty scriptAssets array emits no script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, { scriptAssets: [] })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration still wins when scriptAssets is also set', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/should-not-appear.js'],
+    })
+    expect(template).not.toContain('register_script')
+  })
+
+  test('absent scriptAssets falls back to adapter-computed script paths', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const computed = new ErbAdapter().generate(ir).template
+    const explicitUndefined = new ErbAdapter().generate(ir, { scriptAssets: undefined }).template
+    expect(computed).toContain("bf.register_script('/static/components/barefoot.js')")
+    expect(computed).toContain("bf.register_script('/static/components/Counter.client.js')")
+    expect(explicitUndefined).toBe(computed)
+  })
+})
+
+describe('ErbAdapter - preloadAssets', () => {
+  const CLIENT_COMPONENT = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+  return <button onClick={() => setCount(count() + 1)}>{count()}</button>
+}
+`
+
+  test('non-empty preloadAssets + non-empty scriptAssets: preload registrations emitted, in order, before script registrations', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js', '/assets/counter-def456.js'],
+      preloadAssets: ['/assets/index-pre1.js', '/assets/shared-pre2.js'],
+    })
+    const pre1Idx = template.indexOf("<%- bf.register_preload('/assets/index-pre1.js') -%>")
+    const pre2Idx = template.indexOf("<%- bf.register_preload('/assets/shared-pre2.js') -%>")
+    const script1Idx = template.indexOf("<%- bf.register_script('/assets/runtime-abc123.js') -%>")
+    const script2Idx = template.indexOf("<%- bf.register_script('/assets/counter-def456.js') -%>")
+    expect(pre1Idx).toBeGreaterThanOrEqual(0)
+    expect(pre2Idx).toBeGreaterThan(pre1Idx)
+    expect(script1Idx).toBeGreaterThan(pre2Idx)
+    expect(script2Idx).toBeGreaterThan(script1Idx)
+  })
+
+  test('preloadAssets: [] emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: [],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("<%- bf.register_script('/assets/runtime-abc123.js') -%>")
+  })
+
+  test('preloadAssets: undefined emits no preload registration', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: undefined,
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).toContain("<%- bf.register_script('/assets/runtime-abc123.js') -%>")
+  })
+
+  test('preloadAssets non-empty but scriptAssets: [] emits no preload registration (preloads are only meaningful alongside a real script)', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: [],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  test('skipScriptRegistration: true suppresses both preloads and scripts', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      skipScriptRegistration: true,
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('register_preload')
+    expect(template).not.toContain('register_script')
+  })
+
+  // Regression guard: a previous attempt emitted a literal
+  // `<link rel="modulepreload">` tag directly into the component template,
+  // which injected a rendered DOM node before the component's root and
+  // broke hydration across all eight integrations (blade, erb,
+  // go-template, jinja, mojolicious, rust, twig, xslate). Preload hints
+  // must ONLY ever be emitted as no-output register statements (here,
+  // `<%- bf.register_preload(...) -%>`) that the adapter's runtime later
+  // renders itself — never as literal markup baked into the template.
+  test('never emits a literal <link tag into the template', () => {
+    const ir = compileToIR(CLIENT_COMPONENT)
+    const { template } = new ErbAdapter().generate(ir, {
+      scriptAssets: ['/assets/runtime-abc123.js'],
+      preloadAssets: ['/assets/index-pre1.js'],
+    })
+    expect(template).not.toContain('<link')
+  })
+})

package/src/__tests__/vite.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Coverage of `@barefootjs/erb/vite`'s `barefoot()`:
+ *
+ * - one real `vite build()` end to end (mirrors `@barefootjs/go-template/
+ *   vite`, `@barefootjs/hono/vite`, `@barefootjs/blade/vite`, and
+ *   `@barefootjs/jinja/vite`'s own `vite.test.ts` rigor — a plugin that
+ *   only passes mocked unit tests hasn't been shown to work) against a
+ *   checked-in fixture (not a system tmpdir) so `@barefootjs/client`
+ *   resolves through the monorepo's real node_modules symlinks;
+ * - the `assets` → generated `bf-assets.json` behavior, exercised the same
+ *   way (a real build, since it needs the real manifest Vite writes).
+ *
+ * Unlike Go, there is no `afterEmit`-driven type-combination step to test
+ * here (see `vite.ts`'s module docstring) — `ErbAdapter.generate()` never
+ * produces a `types` section at all, so `barefoot()` always returns a
+ * single-element array unless `assets` is set.
+ */
+import { describe, test, expect } from 'bun:test'
+import { build } from 'vite'
+import { mkdtemp, rm, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { barefoot, barefoot as defaultBarefoot } from '../vite.ts'
+
+const FIXTURE_ROOT = resolve(import.meta.dirname, '../../e2e-fixture')
+
+describe('@barefootjs/erb/vite: real vite build', () => {
+  test('exports the same function as both named `barefoot` and default', () => {
+    expect(defaultBarefoot).toBe(barefoot)
+  })
+
+  test('returns a single-element plugin array when `assets` is omitted', () => {
+    const plugins = barefoot({ components: ['src/components'], templates: 'views' })
+    expect(plugins).toHaveLength(1)
+  })
+
+  test('writes a self-contained .erb template with scriptAssets baked in, same as core alone would do', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-dist-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-views-'))
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: { outDir, emptyOutDir: true },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+        }),
+      })
+
+      const template = await readFile(join(templatesDir, 'Counter.erb'), 'utf8')
+      expect(template).toContain("bf.register_script(")
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` resolves a non-component entry\'s manifest-hashed URL into a generated JSON asset map', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-dist-assets-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-views-assets-'))
+    const assetsPath = join(FIXTURE_ROOT, 'dist/bf-assets.json')
+
+    try {
+      await build({
+        configFile: false,
+        root: FIXTURE_ROOT,
+        base: '/static/build/',
+        logLevel: 'warn',
+        build: {
+          outDir,
+          emptyOutDir: true,
+          // Registering the non-component entry is the CALLER's job (stock
+          // Vite config) — `assets` below only resolves the URL Vite
+          // already bundled it to, it doesn't request the bundling.
+          rollupOptions: { input: { bootstrap: resolve(FIXTURE_ROOT, 'client/bootstrap.ts') } },
+        },
+        plugins: barefoot({
+          components: ['src/components'],
+          templates: templatesDir,
+          assets: { Bootstrap: 'client/bootstrap.ts' },
+        }),
+      })
+
+      const manifest = JSON.parse(await readFile(join(outDir, '.vite/manifest.json'), 'utf8'))
+      const expectedUrl = `/static/build/${manifest['client/bootstrap.ts'].file}`
+
+      const content = JSON.parse(await readFile(assetsPath, 'utf8'))
+      expect(content).toEqual({ Bootstrap: expectedUrl })
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+
+  test('`assets` throws an actionable error when the entry was never registered as a Rollup input', async () => {
+    const outDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-dist-assets-missing-'))
+    const templatesDir = await mkdtemp(join(tmpdir(), 'barefoot-erb-vite-views-assets-missing-'))
+
+    try {
+      await expect(
+        build({
+          configFile: false,
+          root: FIXTURE_ROOT,
+          base: '/static/build/',
+          logLevel: 'silent',
+          build: { outDir, emptyOutDir: true },
+          plugins: barefoot({
+            components: ['src/components'],
+            templates: templatesDir,
+            assets: { Bootstrap: 'client/bootstrap.ts' },
+          }),
+        }),
+      ).rejects.toThrow(/was not found in the build manifest/)
+    } finally {
+      await rm(outDir, { recursive: true, force: true })
+      await rm(templatesDir, { recursive: true, force: true })
+      await rm(join(FIXTURE_ROOT, 'dist'), { recursive: true, force: true })
+    }
+  }, 60_000)
+})

package/src/adapter/erb-adapter.ts

@@ -160,10 +160,6 @@ export class ErbAdapter extends BaseAdapter implements IRNodeEmitter<ErbRenderCt
   name = 'erb'
   extension = '.erb'
   templatesPerComponent = true
-  // Template-string target with no component layer: `bf build` emits a
-  // static `barefoot-importmap.html` to include in the page <head>, same as
-  // the Mojo/Go adapters.
-  importMapInjection = 'html-snippet' as const
 
   /**
    * Identifier-path callees the ERB runtime can render in template scope.
@@ -328,7 +324,7 @@ export class ErbAdapter extends BaseAdapter implements IRNodeEmitter<ErbRenderCt
     // Generate script registration
     const scriptReg = options?.skipScriptRegistration
       ? ''
-      : this.generateScriptRegistrations(ir, options?.scriptBaseName)
+      : this.generateScriptRegistrations(ir, options?.scriptBaseName, options?.scriptAssets, options?.preloadAssets)
 
     // SSR context consumers (`const x = useContext(Ctx)`): seed each local
     // from the active provider value (or the `createContext` default) so
@@ -480,7 +476,32 @@ export class ErbAdapter extends BaseAdapter implements IRNodeEmitter<ErbRenderCt
   // Script Registration
   // ===========================================================================
 
-  private generateScriptRegistrations(ir: ComponentIR, scriptBaseName?: string): string {
+  private generateScriptRegistrations(
+    ir: ComponentIR,
+    scriptBaseName?: string,
+    scriptAssets?: string[],
+    preloadAssets?: string[],
+  ): string {
+    // `scriptAssets`, when present (including `[]`), fully supersedes the
+    // adapter-computed `barefootJsPath` / `clientJsBasePath` pair — see
+    // `AdapterGenerateOptions.scriptAssets`. The caller (e.g. the Vite
+    // plugin) has already decided the exact ordered URL list, including
+    // whether any script is needed at all.
+    if (scriptAssets) {
+      if (scriptAssets.length === 0) return ''
+      // `preloadAssets` is only meaningful alongside a non-empty
+      // `scriptAssets` (see `AdapterGenerateOptions.preloadAssets`), and
+      // every preload registration is emitted BEFORE every script
+      // registration — a hint that arrives after the script it describes
+      // is useless. Same `<%- ... -%>` no-output ERB tag as
+      // `register_script`: the `<link rel="modulepreload">` itself is only
+      // ever rendered by `Context#scripts` (barefoot_js.rb), never here.
+      const lines = (preloadAssets ?? []).map((url) => `<%- bf.register_preload('${url}') -%>`)
+      lines.push(...scriptAssets.map((url) => `<%- bf.register_script('${url}') -%>`))
+      lines.push('')
+      return lines.join('\n')
+    }
+
     const hasInteractivity = hasClientInteractivity(ir)
     if (!hasInteractivity) return ''
 

package/src/adapter/expr/emitters.ts

@@ -88,38 +88,60 @@ function unusedIsStringName(_n: string): boolean {
 }
 
 export class ErbFilterEmitter implements ParsedExprEmitter {
+  // Plain field declarations + assignment, NOT TS constructor-parameter-
+  // property shorthand: Vite's `bundleConfigFile` externalizes any bare
+  // (non-relative) import when loading `vite.config.ts` (see
+  // `@barefootjs/erb/vite`'s docstring), so this file can be loaded
+  // directly by Node's OWN native TypeScript type-stripping (enabled by
+  // default since Node 22.18/23.6) rather than esbuild — and Node's
+  // strip-only mode does not support parameter properties (`SyntaxError
+  // [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]`), only plain type annotations.
+  private readonly param: string
+  private readonly localVarMap: Map<string, string>
+  // Whether `name` currently names a bare Ruby local bound by an
+  // ENCLOSING loop/block (distinct from `this.param`, which is this
+  // predicate's own — possibly nested — loop param). See
+  // `ErbEmitContext.isLoopBoundName`'s docstring for why ERB needs this
+  // and EP does not.
+  private readonly isLoopBoundOuter: (n: string) => boolean
+  // Reports whether a getter/prop name is string-typed, for the Hash-vs-
+  // Array index-access split (#operand.ts). Defaults to "never" for
+  // callers that don't thread it through.
+  private readonly isStringName: (n: string) => boolean
+  // Records a BF101 for nested callback shapes this emitter can only
+  // degrade — `find*` and the non-predicate methods. Optional so emitter
+  // construction stays possible without an adapter; a missing hook keeps
+  // the old silent-degrade emit.
+  private readonly onUnsupported?: (message: string, reason?: string) => void
+  // The Ruby local to EMIT for a reference matching `this.param` — as
+  // opposed to `this.param` itself, which is only the name to MATCH.
+  // These two are the SAME value everywhere in this file except the
+  // `filter().map()` loop-gating `<if>` (erb-adapter.ts's `renderLoop`,
+  // #2245): `todos.filter(t => t.done).map(todo => ...)` parses the
+  // predicate against the filter callback's OWN param (`t`), but the
+  // Ruby local actually bound by the loop is the MAP callback's param
+  // (`todo`) — Ruby has no per-callback block scope there (unlike the
+  // real nested `.select { |t| ... }` block `callbackMethod` below
+  // builds, where match and render are naturally the same param).
+  // Defaults to `rubyLocal(param)`, i.e. every other construction site is
+  // unaffected.
+  private readonly renderParamAs: string
+
   constructor(
-    private readonly param: string,
-    private readonly localVarMap: Map<string, string>,
-    // Whether `name` currently names a bare Ruby local bound by an
-    // ENCLOSING loop/block (distinct from `this.param`, which is this
-    // predicate's own — possibly nested — loop param). See
-    // `ErbEmitContext.isLoopBoundName`'s docstring for why ERB needs this
-    // and EP does not.
-    private readonly isLoopBoundOuter: (n: string) => boolean = () => false,
-    // Reports whether a getter/prop name is string-typed, for the Hash-vs-
-    // Array index-access split (#operand.ts). Defaults to "never" for
-    // callers that don't thread it through.
-    private readonly isStringName: (n: string) => boolean = unusedIsStringName,
-    // Records a BF101 for nested callback shapes this emitter can only
-    // degrade — `find*` and the non-predicate methods. Optional so emitter
-    // construction stays possible without an adapter; a missing hook keeps
-    // the old silent-degrade emit.
-    private readonly onUnsupported?: (message: string, reason?: string) => void,
-    // The Ruby local to EMIT for a reference matching `this.param` — as
-    // opposed to `this.param` itself, which is only the name to MATCH.
-    // These two are the SAME value everywhere in this file except the
-    // `filter().map()` loop-gating `<if>` (erb-adapter.ts's `renderLoop`,
-    // #2245): `todos.filter(t => t.done).map(todo => ...)` parses the
-    // predicate against the filter callback's OWN param (`t`), but the
-    // Ruby local actually bound by the loop is the MAP callback's param
-    // (`todo`) — Ruby has no per-callback block scope there (unlike the
-    // real nested `.select { |t| ... }` block `callbackMethod` below
-    // builds, where match and render are naturally the same param).
-    // Defaults to `rubyLocal(this.param)`, i.e. every other construction
-    // site is unaffected.
-    private readonly renderParamAs: string = rubyLocal(param),
-  ) {}
+    param: string,
+    localVarMap: Map<string, string>,
+    isLoopBoundOuter: (n: string) => boolean = () => false,
+    isStringName: (n: string) => boolean = unusedIsStringName,
+    onUnsupported?: (message: string, reason?: string) => void,
+    renderParamAs: string = rubyLocal(param),
+  ) {
+    this.param = param
+    this.localVarMap = localVarMap
+    this.isLoopBoundOuter = isLoopBoundOuter
+    this.isStringName = isStringName
+    this.onUnsupported = onUnsupported
+    this.renderParamAs = renderParamAs
+  }
 
   identifier(name: string): string {
     if (name === this.param) return this.renderParamAs
@@ -315,7 +337,13 @@ export class ErbFilterEmitter implements ParsedExprEmitter {
  *   - the `unsupported` fallback returns the safe empty-string Ruby literal.
  */
 export class ErbTopLevelEmitter implements ParsedExprEmitter {
-  constructor(private readonly ctx: ErbEmitContext) {}
+  // Plain field + assignment, not a parameter property — see
+  // `ErbFilterEmitter`'s constructor comment above for why.
+  private readonly ctx: ErbEmitContext
+
+  constructor(ctx: ErbEmitContext) {
+    this.ctx = ctx
+  }
 
   identifier(name: string): string {
     // `undefined` / `null` nested inside a larger expression tree (e.g.