@barefootjs/mojolicious 0.17.1 → 0.18.0

package/src/__tests__/stock-route.test.ts

@@ -0,0 +1,203 @@
+// Stock-route smoke test for the Mojo scaffold contract (#2126).
+//
+// The scaffold's happy path is: `npm run dev` (which starts `bf build
+// --watch` and morbo *concurrently*), then open `/`. That page renders a
+// component whose EP template reads props/signals as bare scalars
+// (`% my $count = ($initial // 0);`), and Mojo templates compile under
+// `use strict` — so every one of those scalars must be declared by the
+// time the template runs. Two production bugs hid in that path:
+//
+//   1. The route passes no props, so the stash seeding has to come from
+//      the manifest's `ssrDefaults` via the plugin's `before_render`
+//      hook — including props only referenced through `props.X` reads.
+//   2. The plugin used to load the manifest once at register time, so
+//      booting before the first build wrote `manifest.json` disabled
+//      auto-init for the server's lifetime: every render of `/` died
+//      with `Global symbol "$initial" requires explicit package name`
+//      (HTTP 500) until a manual restart.
+//
+// This test boots a real Mojolicious app whose `app.pl` mirrors the
+// scaffold's (plugin + dist/templates renderer path + a `/` route that
+// passes NO props) against a template + manifest produced by the real
+// compiler, and asserts the page renders — in both boot orders. It is
+// the in-repo equivalent of "scaffold → build → curl / expects 200".
+//
+// Runs only when `perl` with Mojolicious is installed (same skip policy
+// as the conformance render tests). The DevReload plugin is omitted:
+// it's dev-only plumbing with its own coverage in t/dev_reload.t.
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { compileJSX } from '@barefootjs/jsx'
+import { MojoAdapter } from '../adapter/mojo-adapter'
+
+const MOJO_LIB_DIR = path.resolve(import.meta.dir, '../../lib')
+const PERL_CORE_LIB_DIR = path.resolve(import.meta.dir, '../../../adapter-perl/lib')
+
+function perlWithMojoAvailable(): boolean {
+  try {
+    const proc = Bun.spawnSync(['perl', '-MMojolicious', '-MTest::Mojo', '-e1'], {
+      env: process.env,
+    })
+    return proc.exitCode === 0
+  } catch {
+    return false
+  }
+}
+
+const PERL_AVAILABLE = perlWithMojoAvailable()
+
+// The starter-Counter shape: a prop read only through `props.X ?? …`
+// (never passed by the stock route) feeding a signal, plus a memo.
+// Exactly the pattern that dies under strict when seeding breaks.
+// `props.label` is read directly in the body (no signal/memo in
+// between) — that flattens to a bare `<%= $label %>` too, so it pins
+// that ssrDefaults seeds every declared prop, not just the ones a
+// signal initializer references.
+const COUNTER_TSX = `'use client'
+
+import { createSignal, createMemo } from '@barefootjs/client'
+
+interface CounterProps {
+  initial?: number
+  label?: string
+}
+
+export function Counter(props: CounterProps) {
+  const [count, setCount] = createSignal(props.initial ?? 0)
+  const doubled = createMemo(() => count() * 2)
+
+  return (
+    <div className="counter">
+      <p className="counter-label">{props.label}</p>
+      <p className="counter-value">count: {count()}</p>
+      <p className="counter-doubled">doubled: {doubled()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+`
+
+// Mirrors the scaffold's app.pl essentials. The `/` route deliberately
+// passes NO props — the manifest seeding alone must carry it. The
+// second route pins that a caller-supplied prop still wins.
+const APP_PL = `#!/usr/bin/env perl
+use Mojolicious::Lite -signatures;
+
+plugin 'BarefootJS';
+
+app->renderer->paths->[0] = app->home->child('dist/templates');
+
+get '/' => sub ($c) {
+    $c->render(template => 'Counter', layout => 'default');
+};
+
+get '/with-prop' => sub ($c) {
+    $c->render(template => 'Counter', layout => 'default', initial => 5);
+};
+
+app->start;
+
+__DATA__
+
+@@ layouts/default.html.ep
+<!DOCTYPE html>
+<html><body>
+<main><%== content %></main>
+%== $c->bf->scripts
+</body></html>
+`
+
+// Test::Mojo harness. SMOKE_SCENARIO picks the boot order:
+//   manifest-at-boot   — the manifest exists before the app loads
+//                        (server restarted after a completed build).
+//   manifest-after-boot — the app loads first, the manifest appears
+//                        afterwards (the concurrent `bf build --watch`
+//                        + morbo dev race on a fresh scaffold).
+const SMOKE_PL = `use Mojo::Base -strict;
+use Test::More;
+use Test::Mojo;
+use Mojo::File qw(curfile path);
+
+my $home     = curfile->dirname;
+my $scenario = $ENV{SMOKE_SCENARIO} // 'manifest-at-boot';
+my $staged   = $home->child('manifest.staged.json');
+my $manifest = $home->child('dist/templates/manifest.json');
+
+unlink "$manifest";
+$staged->copy_to("$manifest") if $scenario eq 'manifest-at-boot';
+
+my $t = Test::Mojo->new($home->child('app.pl'));
+
+$staged->copy_to("$manifest") if $scenario eq 'manifest-after-boot';
+
+# Stock route: no props passed — manifest ssrDefaults must seed every
+# bare template scalar ($initial included) or strict mode 500s.
+$t->get_ok('/')->status_is(200)
+  ->text_like('p.counter-value',   qr/count:\\s*0/)
+  ->text_like('p.counter-doubled', qr/doubled:\\s*0/)
+  ->content_like(qr/Counter\\.client\\.js/, 'auto-init registered the client bundle');
+
+# Caller-supplied prop wins over the manifest default.
+$t->get_ok('/with-prop')->status_is(200)
+  ->text_like('p.counter-value',   qr/count:\\s*5/)
+  ->text_like('p.counter-doubled', qr/doubled:\\s*10/);
+
+done_testing;
+`
+
+describe.skipIf(!PERL_AVAILABLE)('Mojo scaffold stock route (#2126)', () => {
+  let appDir: string
+
+  beforeAll(() => {
+    appDir = mkdtempSync(path.join(tmpdir(), 'bf-mojo-stock-route-'))
+    mkdirSync(path.join(appDir, 'dist/templates'), { recursive: true })
+
+    const result = compileJSX(COUNTER_TSX, 'Counter.tsx', { adapter: new MojoAdapter() })
+    const template = result.files.find(f => f.type === 'markedTemplate')
+    const ssrDefaults = result.files.find(f => f.type === 'ssrDefaults')
+    if (!template || !ssrDefaults) throw new Error('compileJSX produced no template/ssrDefaults')
+
+    writeFileSync(path.join(appDir, 'dist/templates/Counter.html.ep'), template.content)
+    // Same entry shape `bf build` writes to dist/templates/manifest.json.
+    writeFileSync(
+      path.join(appDir, 'manifest.staged.json'),
+      JSON.stringify({
+        Counter: {
+          markedTemplate: 'templates/Counter.html.ep',
+          ssrDefaults: JSON.parse(ssrDefaults.content),
+        },
+      }),
+    )
+    writeFileSync(path.join(appDir, 'app.pl'), APP_PL)
+    writeFileSync(path.join(appDir, 'smoke.pl'), SMOKE_PL)
+  })
+
+  async function runScenario(scenario: string): Promise<void> {
+    const perl5lib = [MOJO_LIB_DIR, PERL_CORE_LIB_DIR, process.env.PERL5LIB]
+      .filter(Boolean)
+      .join(':')
+    const proc = Bun.spawn(['perl', 'smoke.pl'], {
+      cwd: appDir,
+      env: { ...process.env, PERL5LIB: perl5lib, SMOKE_SCENARIO: scenario },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    expect(exitCode, `TAP output:\n${stdout}\n${stderr}`).toBe(0)
+  }
+
+  test('renders / with the manifest present at boot', async () => {
+    await runScenario('manifest-at-boot')
+  })
+
+  test('renders / when the manifest appears after boot (concurrent dev-startup race)', async () => {
+    await runScenario('manifest-after-boot')
+  })
+})

package/src/adapter/expr/array-method.ts

@@ -423,7 +423,28 @@ export function renderSortMethod(recv: string, c: SortComparator): string {
 // `.flat(depth?)` → `bf->flat($recv, $depth)`. The `Infinity` form lowers
 // to the `-1` sentinel (flatten fully); a finite depth flattens that many
 // levels (`0` = shallow copy). See `sub flat` in BarefootJS.pm. (#1448)
-export function renderFlatMethod(recv: string, depth: FlatDepth): string {
+export function renderFlatMethod(
+  recv: string,
+  depth: FlatDepth | { expr: ParsedExpr },
+  emit: (e: ParsedExpr) => string,
+): string {
+  if (typeof depth === 'object') {
+    // Dynamic depth (#2094): routed to a SEPARATE runtime helper
+    // (`bf->flat_dynamic`), not `bf->flat`. The literal-depth path below
+    // already uses `-1` as a compile-time SENTINEL baked into the template
+    // source meaning "the source literally said `Infinity`". A genuinely
+    // dynamic depth that happens to evaluate to `-1` at render time means
+    // the OPPOSITE in real JS (`[1,[2]].flat(-1)` never recurses — same as
+    // `.flat(0)`). Since both paths would otherwise hand the same
+    // literal-looking argument to one shared helper, that helper couldn't
+    // tell which case it's in — so `flat_dynamic` performs its own
+    // `ToIntegerOrInfinity`-style coercion (truncate toward zero; negative
+    // -> 0; NaN/non-numeric -> 0; +Infinity or a huge finite value ->
+    // flatten fully) and then delegates to `flat`. See `sub flat_dynamic`
+    // in BarefootJS.pm and the Go reference (`FlatDynamicDepth`/
+    // `coerceFlatDepth` in bf.go).
+    return `bf->flat_dynamic(${recv}, ${emit(depth.expr)})`
+  }
   const d = depth === 'infinity' ? -1 : depth
   return `bf->flat(${recv}, ${d})`
 }

package/src/adapter/expr/emitters.ts

@@ -232,8 +232,12 @@ export class MojoFilterEmitter implements ParsedExprEmitter {
     return renderArrayMethod(method, object, args, emit)
   }
 
-  flatMethod(object: ParsedExpr, depth: FlatDepth, emit: (e: ParsedExpr) => string): string {
-    return renderFlatMethod(emit(object), depth)
+  flatMethod(
+    object: ParsedExpr,
+    depth: FlatDepth | { expr: ParsedExpr },
+    emit: (e: ParsedExpr) => string,
+  ): string {
+    return renderFlatMethod(emit(object), depth, emit)
   }
 
   conditional(_test: ParsedExpr, _consequent: ParsedExpr, _alternate: ParsedExpr): string {
@@ -559,8 +563,12 @@ export class MojoTopLevelEmitter implements ParsedExprEmitter {
     return renderArrayMethod(method, object, args, emit)
   }
 
-  flatMethod(object: ParsedExpr, depth: FlatDepth, emit: (e: ParsedExpr) => string): string {
-    return renderFlatMethod(emit(object), depth)
+  flatMethod(
+    object: ParsedExpr,
+    depth: FlatDepth | { expr: ParsedExpr },
+    emit: (e: ParsedExpr) => string,
+  ): string {
+    return renderFlatMethod(emit(object), depth, emit)
   }
 
   conditional(
@@ -628,12 +636,16 @@ export class MojoTopLevelEmitter implements ParsedExprEmitter {
     return "''"
   }
 
-  objectLiteral(_properties: ObjectLiteralProperty[], _raw: string, _emit: (e: ParsedExpr) => string): string {
-    // Mirror `unsupported`: a bare object literal reaching the dispatcher
-    // lowers to the safe Perl empty-string literal, exactly as before the
-    // `object-literal` kind existed (byte-identical; Roadmap A-1). Object
-    // values that round-trip to a Perl hashref go through the dedicated
-    // `objectLiteralToPerlHashref` lowering in the conditional/attr paths.
-    return "''"
+  objectLiteral(properties: ObjectLiteralProperty[], _raw: string, _emit: (e: ParsedExpr) => string): string {
+    // The shared `isSupported` gate only ever lets this dispatcher see an
+    // object literal as the EMPTY (`?? {}`) fallback operand of `??`
+    // (expression-parser.ts, `logical` case) — any other object literal is
+    // refused before reaching here. Emit Perl's real empty hashref literal,
+    // matching the `'{}'` convention `objectLiteralToPerlHashref` already
+    // uses for the zero-property case in the spread path. A populated
+    // literal is structurally unreachable given the gate, but still
+    // degrades safely to the pre-existing empty-string sentinel rather
+    // than silently dropping keys.
+    return properties.length === 0 ? '{}' : "''"
   }
 }

package/src/adapter/mojo-adapter.ts

@@ -26,6 +26,7 @@ import type {
   CompilerError,
   TypeInfo,
   TemplatePrimitiveRegistry,
+  LoopBindingPathSegment,
 } from '@barefootjs/jsx'
 import {
   BaseAdapter,
@@ -49,14 +50,15 @@ import {
   parseRecordIndexAccess,
   extractArrowBodyExpression,
   collectContextConsumers,
-  isLowerableObjectRestDestructure,
   type ContextConsumer,
   collectModuleStringConsts,
   lookupStaticRecordLiteral,
   searchParamsLocalNames,
   prepareLoweringMatchers,
   queryHrefArgs,
+  isValidHelperId,
   sortComparatorFromArrow,
+  isLowerableLoopDestructure,
 } from '@barefootjs/jsx'
 import { isAriaBooleanAttr, isBooleanResultExpr } from './boolean-result.ts'
 import type { ParsedExpr, LoweringMatcher } from '@barefootjs/jsx'
@@ -94,6 +96,43 @@ import {
 export type { MojoAdapterOptions } from './lib/types.ts'
 import type { MojoAdapterOptions } from './lib/types.ts'
 
+/**
+ * Build a Perl accessor expression for a `.map()` destructure binding's
+ * structured `segments` path (#2087 Phase B), walking `field` (`->{key}`,
+ * quoted with `perlHashKey`'s convention when `!isIdent`) / `index`
+ * (`->[N]`) steps onto `base`. Never string-parses `LoopParamBinding.path` —
+ * see the repo-wide rule against regex-parsing JS/TS-derived syntax.
+ *
+ * Used both for a fixed binding's FULL accessor (`base` = `$__bf_item`,
+ * `segments` = the whole path) and a rest binding's PARENT-prefix accessor
+ * (`segments` may be empty, at the loop root, in which case this returns
+ * `base` unchanged) — see `LoopParamBinding.segments` jsdoc for which case
+ * a binding is in.
+ */
+function perlSegmentAccessor(base: string, segments: readonly LoopBindingPathSegment[]): string {
+  let expr = base
+  for (const seg of segments) {
+    expr +=
+      seg.kind === 'field'
+        ? `->{${seg.isIdent ? seg.key : perlHashKey(seg.key)}}`
+        : `->[${seg.index}]`
+  }
+  return expr
+}
+
+/**
+ * Quote a string as a Perl single-quoted literal (backslash first, then the
+ * quote, so the escape doesn't double up). Unlike `perlHashKey` — which
+ * intentionally leaves an identifier-safe name as a bareword for `->{key}` /
+ * `key => val` hash-key position — a plain list element (`bf->omit($x, [id,
+ * title])`) is NOT hash-key position: an unquoted bareword there is a sub
+ * call under `use strict subs`, so every object-rest exclude key needs an
+ * unconditional string literal.
+ */
+function perlStringLiteral(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+}
+
 export class MojoAdapter extends BaseAdapter implements IRNodeEmitter<MojoRenderCtx> {
   name = 'mojolicious'
   extension = '.html.ep'
@@ -705,41 +744,79 @@ export class MojoAdapter extends BaseAdapter implements IRNodeEmitter<MojoRender
       return `<%== bf->comment("loop:${loop.markerId}") %><%== bf->comment("/loop:${loop.markerId}") %>`
     }
 
-    // An array/object-destructure loop param (`([emoji, users]) => ...`
-    // or `({ name, age }) => ...`) lowers to invalid Perl — the adapter
-    // would otherwise emit `% my $[emoji, users] = $entries->[$_i];`,
-    // which is a parse error. Surface this at build time (#1266)
-    // instead of shipping the broken template line for the user to
-    // discover at request time.
+    // A `.map()` destructure loop param (`([k, v]) => ...` / `({ id, user: {
+    // name } }) => ...` / `({ id, ...rest }) => ...`) lowers to a Perl `my`
+    // local per binding, walking each binding's structured `segments` path
+    // (#2087 Phase B) into a native `->{key}` / `->[N]` accessor off the
+    // per-item var — so the body's `$id` / `$name` / `$rest->{flag}` /
+    // `{...rest}` all resolve natively, at any nesting depth.
     //
     // Check the IR's structured `paramBindings` field rather than
     // string-matching `loop.param`: Phase 1 populates `paramBindings`
     // iff the param is a destructure pattern (array or object); a
     // simple identifier leaves it `undefined`. The structured check is
     // robust to whitespace / formatting variants in the source.
-    // A destructure loop param is lowerable for the object-rest / simple-field
-    // shape (`.map(({ id, title, ...rest }) => …)`, `rest` read via member
-    // access): each binding becomes a Perl `my` local off the per-item var, so
-    // the body's `$id` / `$rest->{flag}` resolve natively. Array-index / nested
-    // / rest-spread shapes still can't unpack into scalar `my`s → BF104. (#1310)
+    //
+    // `isLowerableLoopDestructure` (#2087) still refuses: an object-rest
+    // binding used any way other than member access (`rest.flag`) or a
+    // `{...rest}` spread onto an intrinsic element (that needs the actual
+    // residual *object*, which isn't always safe to materialize — see the
+    // gate's own jsdoc for the full list); a `.filter().map(destructure)`
+    // chain (the filter-param rewrite is out of scope here); and a
+    // computed property key (`{ [k]: v }`, refused earlier as BF025).
     const destructure = !!(loop.paramBindings && loop.paramBindings.length > 0)
-    const supportableDestructure = destructure && isLowerableObjectRestDestructure(loop)
+    const supportableDestructure = destructure && isLowerableLoopDestructure(loop)
     if (destructure && !supportableDestructure) {
       this.errors.push({
         code: 'BF104',
         severity: 'error',
-        message: `Loop callback uses an array/object destructure pattern (\`${loop.param}\`) that the Mojo adapter cannot lower — Perl scalar bindings can't unpack a tuple in a single \`my\` declaration.`,
+        message: `Loop callback uses a destructure pattern (\`${loop.param}\`) that the Mojo adapter cannot lower — see the diagnostic detail for the specific shape.`,
         loc: loop.loc ?? { file: this.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
         suggestion: {
           message:
             `Options:\n` +
-            `  1. Rename the parameter to a single name and access tuple elements with index syntax in the body (e.g. \`entry => entry->[0]\` instead of \`([k, v]) => ...\`).\n` +
-            `  2. Mark the loop position as @client-only so the destructure runs in JS on the client.\n` +
-            `  3. Move the loop into a primitive that the adapter registers explicitly.`,
+            `  1. If this is an object-rest binding (\`{ ...rest }\`), only reading \`rest.field\` or spreading \`{...rest}\` onto an intrinsic element lowers — other uses (passing \`rest\` to a function, rendering it as text) need the client runtime.\n` +
+            `  2. If this is chained \`.filter().map(({ ... }) => ...)\`, hoist the destructure into a variable inside the callback body instead.\n` +
+            `  3. Mark the loop position as @client-only so the destructure runs in JS on the client.\n` +
+            `  4. Move the loop into a primitive that the adapter registers explicitly.`,
         },
       })
     }
 
+    // A `.map()` loop whose array is a bare identifier bound to a
+    // FUNCTION-scope local const with a non-statically-evaluable initializer
+    // that reads props/signals (e.g. `const entries =
+    // Object.entries(props.x ?? {}).filter(...)`) can't render correctly.
+    // Module-scope consts (`isModule`, e.g. `const payments = [...]` at the
+    // top of the file) are a DIFFERENT, already-working case handled
+    // elsewhere. Function-scope locals get no per-render stash slot — this
+    // adapter's only "elsewhere" for a local const is inlining its value at
+    // the use site (`resolveLiteralConst`'s numeric/single-quoted-string fast
+    // path, or a static-record-literal lookup), never binding one as a `my`
+    // template local. Left unchecked, `% for my $_i (0..$#{$entries}) {`
+    // over an undeclared `$entries` faults under `use strict` at request
+    // time instead of failing loudly at build time. Pre-existing, general
+    // limitation, orthogonal to #2087's destructure-binding work — newly
+    // reachable in this adapter's test corpus only because the widened
+    // destructure gate (#2087 Phase A/B) no longer refuses this fixture's
+    // `([emoji, users]) => ...` param first.
+    const arrayName = loop.array.trim()
+    if (/^[A-Za-z_$][\w$]*$/.test(arrayName)) {
+      const arrayConst = (this.localConstants ?? []).find(c => c.name === arrayName)
+      if (arrayConst && !arrayConst.isModule && this.resolveLiteralConst(arrayName) === null) {
+        this.errors.push({
+          code: 'BF101',
+          severity: 'error',
+          message: `Loop array \`${arrayName}\` is a local computed value (\`${arrayConst.value}\`) that the Mojo adapter cannot bind as a template variable — only numeric/string-literal locals inline at their use site.`,
+          loc: loop.loc ?? { file: this.componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
+          suggestion: {
+            message:
+              'Pre-compute the array server-side and pass it as a prop, or mark the loop position as @client-only so it runs in JS on the client.',
+          },
+        })
+      }
+    }
+
     const rawArray = this.convertExpressionToPerl(loop.array)
     // Apply sort if present (#1448 Tier B): wrap the loop array in the
     // shared sort helper. The same `renderSortEval` / `renderSortMethod`
@@ -844,15 +921,31 @@ export class MojoAdapter extends BaseAdapter implements IRNodeEmitter<MojoRender
     lines.push(`% for my ${indexVar} (0..$#{${array}}) {`)
     if (loop.iterationShape !== 'keys') {
       if (supportableDestructure) {
-        // Per-item var + one `my` local per binding; `rest` aliases the item
-        // so `$rest->{flag}` resolves (object-rest read via member access).
+        // Per-item var + one `my` local per binding, walking each binding's
+        // `segments` path (#2087 Phase B):
+        //   - fixed (`b.rest` unset): the FULL accessor from `$__bf_item`.
+        //   - array-rest: `bf->slice(parent, from, undef)` — the same
+        //     runtime helper `.slice()` JS-method calls lower to (see
+        //     `array-method.ts`), so the "no end → to length" arithmetic
+        //     stays in one place.
+        //   - object-rest: `bf->omit(parent, [...excluded keys...])` — a
+        //     TRUE residual hashref (not the whole item aliased), so both
+        //     `$rest->{flag}` (member-access use) and `bf->spread_attrs($rest)`
+        //     (spread-onto-element use) see only the non-destructured keys.
+        // `parent` is `$__bf_item` walked through the binding's PARENT-prefix
+        // `segments` (empty at the loop root, per the `LoopParamBinding`
+        // jsdoc) — NOT the same as a fixed binding's full-accessor segments.
         lines.push(`% my $__bf_item = ${array}->[${indexVar}];`)
         for (const b of loop.paramBindings ?? []) {
-          lines.push(
-            b.rest
-              ? `% my $${b.name} = $__bf_item;`
-              : `% my $${b.name} = $__bf_item->{${b.path.slice(1)}};`,
-          )
+          const parent = perlSegmentAccessor('$__bf_item', b.segments ?? [])
+          if (b.rest?.kind === 'object') {
+            const exclude = b.rest.exclude.map(k => perlStringLiteral(k.key)).join(', ')
+            lines.push(`% my $${b.name} = bf->omit(${parent}, [${exclude}]);`)
+          } else if (b.rest?.kind === 'array') {
+            lines.push(`% my $${b.name} = bf->slice(${parent}, ${b.rest.from}, undef);`)
+          } else {
+            lines.push(`% my $${b.name} = ${perlSegmentAccessor('$__bf_item', b.segments ?? [])};`)
+          }
         }
       } else {
         lines.push(`% my $${param} = ${array}->[${indexVar}];`)
@@ -1611,6 +1704,17 @@ export class MojoAdapter extends BaseAdapter implements IRNodeEmitter<MojoRender
           const argsGo = queryHrefArgs(node, n => this.renderParsedExprToPerl(n))
           return `bf->query(${argsGo.join(', ')})`
         }
+        // Generic `helper-call` (#2069) — the neutral vocabulary's escape
+        // hatch for a userland `LoweringPlugin` that lowers to a single
+        // runtime-helper invocation. `bf-><helper>(args…)` mirrors the
+        // `query` helper's own naming convention exactly: the framework
+        // renders the call, the plugin author registers `<helper>` as a
+        // method on their own Mojolicious `bf` helper object — same
+        // contract as `bf->query` itself, just not built in.
+        if (node?.kind === 'helper-call' && isValidHelperId(node.helper)) {
+          const argsX = node.args.map(a => this.renderParsedExprToPerl(a))
+          return `bf->${node.helper}(${argsX.join(', ')})`
+        }
       }
     }
 

package/src/conformance-pins.ts

@@ -0,0 +1,138 @@
+/**
+ * Per-fixture build-time contracts for shapes the Mojo adapter
+ * intentionally refuses to lower. Owned by this module (not by the
+ * shared fixtures) so adding a new adapter doesn't require touching any
+ * cross-adapter file. Consumed by this package's own conformance test
+ * (as `expectedDiagnostics`) and by `bf compat` (issue-URL attribution).
+ */
+
+import type { ConformancePins } from '@barefootjs/jsx'
+
+export const conformancePins: ConformancePins = {
+  // Sibling-imported child component in a loop body: Mojo emits
+  // a cross-template call that needs separate registration. BF103
+  // makes the requirement loud. (The barefoot CLI passes
+  // `siblingTemplatesRegistered: true` so CLI builds suppress it.)
+  'static-array-children': [{ code: 'BF103', severity: 'error' }],
+  // TodoApp / TodoAppSSR import `TodoItem` from a sibling file and
+  // call it inside a keyed `.map`. Same BF103 surface as the
+  // synthetic `static-array-children` above — pinned at adapter
+  // level so the shared-component corpus stays adapter-neutral.
+  'todo-app': [{ code: 'BF103', severity: 'error' }],
+  'todo-app-ssr': [{ code: 'BF103', severity: 'error' }],
+  // `([emoji, users]) => ...` / `([id, t]) => ...` are plain array-index
+  // (tuple) destructures, no rest — #2087 Phase B's `segments`-walking
+  // accessor lowers both to `$__bf_item->[0]` / `$__bf_item->[1]` `my`
+  // locals like any other fixed binding, so BF104 no longer fires for
+  // either fixture. Each now hits a DIFFERENT, pre-existing, orthogonal
+  // gap instead: the loop array (`entries`) is a function-scope local
+  // const with a computed initializer
+  // (`Object.entries(props.x ?? {}).filter(...)`) that the adapter can't
+  // bind as a template variable — see the dedicated `arrayConst` BF101
+  // check in `renderLoop`. This was always true; it was simply
+  // unreachable before because BF104 refused the destructure shape first.
+  'static-array-from-props': [{ code: 'BF101', severity: 'error' }],
+  // Both BF103 (sibling-imported `<Tag>` child component) and the BF101
+  // above fire; BF104 no longer does (see above).
+  'static-array-from-props-with-component': [
+    { code: 'BF103', severity: 'error' },
+    { code: 'BF101', severity: 'error' },
+  ],
+  // #1310 / #2087: rest destructure in .map() callback. All four shapes
+  // now lower via #2087 Phase B's `segments`-walking accessor:
+  //   - object-rest read via member access (`rest-destructure-object-in-map`):
+  //     `bf->omit($__bf_item, [...exclude keys...])`, `$rest->{flag}` reads
+  //     the residual hashref.
+  //   - object-rest spread onto the root element
+  //     (`rest-destructure-object-spread-in-map`): same `bf->omit(...)`
+  //     residual, forwarded via the existing `bf->spread_attrs($rest)` path.
+  //   - array-rest (`rest-destructure-array-in-map`): `bf->slice($__bf_item,
+  //     N, undef)` — the same runtime helper `.slice()` JS-method calls use.
+  //   - nested rest inside an object pattern (`rest-destructure-nested-in-map`):
+  //     the parent-prefix accessor (`$__bf_item->{cells}`) feeds the same
+  //     `bf->slice(...)` call.
+  // None of these are pinned here anymore.
+  // `style-3-signals` / `style-object-dynamic` no longer pinned — a
+  // `style={{ … }}` object literal now lowers to a CSS string with dynamic
+  // values interpolated (`background-color:<%= $color %>;padding:8px`) via
+  // `tryLowerStyleObject` (#1322).
+  // (`tagged-template-classname` graduated by #2092 — the tag resolves
+  // through the interleave-tag catalogue and desugars to an untagged
+  // template literal, so it lowers like any other className template.)
+  // #2038: a filter predicate containing a nested `.find(...)` callback.
+  // `find*` returns an element, not a boolean — there is no inline grep
+  // form, and the emitter used to degrade the call to its receiver.
+  // The nested `.some` sibling (`filter-nested-callback-predicate`) is
+  // NOT pinned: Mojo lowers it to a real inline Perl `grep` and must
+  // render to Hono parity instead.
+  // https://github.com/piconic-ai/barefootjs/issues/2038
+  'filter-nested-find-predicate': [
+    { code: 'BF101', severity: 'error', issue: 'https://github.com/piconic-ai/barefootjs/issues/2038' },
+  ],
+  // #1467 demo-corpus context providers (`radio-group`, `accordion`,
+  // `dialog`, `popover`, `select`, `dropdown-menu`, `combobox`,
+  // `command`) are no longer pinned — an object-literal provider value
+  // (`{ open: () => props.open ?? false, onOpenChange: (v) => {…} }`)
+  // lowers to a Perl hashref via `parseProviderObjectLiteral` (#1897):
+  // getter members snapshot their body's SSR value, handler /
+  // function-shaped members lower to `undef`. The command demo's
+  // `ref={(el) => {…}}` function prop on an imported component is
+  // skipped at SSR like `on*` handlers.
+  //
+  // #1467 Phase 2e: `data-table` is no longer pinned here either — it
+  // compiles clean (`selected()[index]` → `index-access`,
+  // `.toFixed(2)` → `bf->to_fixed`, `/* @client */` memo SSR-folded)
+  // and renders to Hono parity on real Mojolicious. The keyed-loop
+  // scope-ID divergence (#1896) was fixed by the body-children
+  // `inLoop` reset (loop-item children get `_bf_slot`); data-table is
+  // off `skipJsx` entirely and only kept in `skipMarkerConformance`
+  // below for the shared `/* @client */` keyed-map slot-id elision
+  // contract (same as `todo-app`), not a render or BF101 gap.
+  // #1443: `[a, b].filter(Boolean).join(' ')` (the registry Slot's
+  // shape) now lowers to `join(' ', @{[grep { $_ } @{[$a, $b]}]})`.
+  // No BF101 expected — pinned positively via the
+  // `branch-local-filter-join` template-output test below.
+  //
+  // #1448 Tier A — JS Array / String methods that the Mojo adapter
+  // hasn't lowered yet. Each row drops once the corresponding
+  // method PR lands. Hono / CSR pass these out of the box (they
+  // evaluate JS at runtime) so the pin only applies here.
+  //
+  // `array-includes` / `string-includes` no longer pinned — both
+  // shapes lower via the shared `array-method` IR + `bf->includes`
+  // runtime dispatch (#1448 Tier A first PR).
+  // `array-indexOf` / `array-lastIndexOf` no longer pinned —
+  // value-equality `bf->index_of` / `bf->last_index_of` helpers
+  // handle the shape (#1448 Tier A second PR).
+  // `array-at` no longer pinned — `bf->at` (Mojo) / `bf_at` (Go)
+  // handle the negative-index lookup (#1448 Tier A third PR).
+  // `array-concat` no longer pinned — `bf->concat` (Mojo) /
+  // `bf_concat` (Go) merge two arrays into a new array
+  // (#1448 Tier A fourth PR).
+  // `array-slice` no longer pinned — `bf->slice` (Mojo) /
+  // `bf_slice` (Go) carve out a sub-range with JS-compat
+  // negative-index / out-of-bounds clamping (#1448 Tier A
+  // fifth PR).
+  // `array-reverse` / `array-toReversed` no longer pinned —
+  // both share the `bf->reverse` / `bf_reverse` helper since
+  // SSR templates render a snapshot and the JS mutate-vs-new
+  // distinction has no template-level meaning (#1448 Tier A
+  // sixth PR).
+  // `string-toLowerCase` / `string-toUpperCase` no longer pinned —
+  // Perl's native `lc` / `uc` (Mojo) and pre-existing
+  // `bf_lower` / `bf_upper` (Go) handle the JS method names
+  // (#1448 Tier A seventh + eighth PRs).
+  // `string-trim` no longer pinned — pre-existing `bf_trim`
+  // (Go) and new `bf->trim` helper (Mojo) handle the strip
+  // (#1448 Tier A ninth PR, closing out Tier A).
+  // `.find` / `.findIndex` / `.findLast` / `.findLastIndex` are no longer
+  // pinned — the Mojo `callbackMethod` predicate arm now lowers them to the
+  // runtime `bf->find` / `find_index` / `find_last` / `find_last_index` helpers
+  // (per-element coderef predicate), matching Xslate. `.join` was never
+  // pinned (handled by `renderArrayMethod`'s `case 'join'`).
+  // #2073 follow-up: a function-reference `.map(format)` callback has no
+  // arrow body to serialize — not a CALLBACK_METHODS shape — so the
+  // UNSUPPORTED_METHODS gate refuses it with BF101 rather than emitting
+  // a broken template.
+  'array-map-function-reference': [{ code: 'BF101', severity: 'error' }],
+}