@barefootjs/mojolicious 0.17.0 → 0.18.0

package/dist/index.js

@@ -2,23 +2,24 @@
 import {
   BaseAdapter,
   isBooleanAttr,
-  parseExpression as parseExpression3,
+  parseExpression as parseExpression2,
   stringifyParsedExpr as stringifyParsedExpr2,
   parseStyleObjectEntries,
-  isSupported as isSupported2,
+  isSupported,
   exprToString,
   parseProviderObjectLiteral,
   emitParsedExpr as emitParsedExpr2,
   emitIRNode,
   emitAttrValue,
   augmentInheritedPropAccesses,
-  isLowerableObjectRestDestructure,
   collectModuleStringConsts,
   lookupStaticRecordLiteral,
   searchParamsLocalNames,
   prepareLoweringMatchers,
   queryHrefArgs,
-  sortComparatorFromArrow as sortComparatorFromArrow2
+  isValidHelperId,
+  sortComparatorFromArrow as sortComparatorFromArrow2,
+  isLowerableLoopDestructure
 } from "@barefootjs/jsx";
 
 // src/adapter/boolean-result.ts
@@ -128,13 +129,6 @@ function collectRootScopeNodes(node) {
   visit(node);
   return out;
 }
-function referencedVarsAreAvailable(expr, available) {
-  for (const m of expr.matchAll(/\$([A-Za-z_]\w*)/g)) {
-    if (!available.has(m[1]))
-      return false;
-  }
-  return true;
-}
 
 // src/adapter/expr/array-method.ts
 import {
@@ -307,6 +301,13 @@ function renderFlatMapEval(recv, body, param, emit) {
   const env = emitEvalEnvArg(body, [param], emit);
   return `bf->flat_map_eval(${recv}, '${escapePerlSingleQuote(json)}', '${param}', ${env})`;
 }
+function renderMapEval(recv, body, param, emit) {
+  const json = serializeParsedExpr(body);
+  if (json === null)
+    return null;
+  const env = emitEvalEnvArg(body, [param], emit);
+  return `bf->map_eval(${recv}, '${escapePerlSingleQuote(json)}', '${param}', ${env})`;
+}
 function renderSortMethod(recv, c) {
   const keyHashes = c.keys.map((k) => {
     const keyEntry = k.key.kind === "self" ? `key_kind => 'self'` : `key_kind => 'field', key => '${k.key.field}'`;
@@ -314,7 +315,10 @@ function renderSortMethod(recv, c) {
   });
   return `bf->sort(${recv}, { keys => [${keyHashes.join(", ")}] })`;
 }
-function renderFlatMethod(recv, depth) {
+function renderFlatMethod(recv, depth, emit) {
+  if (typeof depth === "object") {
+    return `bf->flat_dynamic(${recv}, ${emit(depth.expr)})`;
+  }
   const d = depth === "infinity" ? -1 : depth;
   return `bf->flat(${recv}, ${d})`;
 }
@@ -360,10 +364,12 @@ class MojoFilterEmitter {
   param;
   localVarMap;
   isStringName;
-  constructor(param, localVarMap, isStringName = () => false) {
+  onUnsupported;
+  constructor(param, localVarMap, isStringName = () => false, onUnsupported) {
     this.param = param;
     this.localVarMap = localVarMap;
     this.isStringName = isStringName;
+    this.onUnsupported = onUnsupported;
   }
   identifier(name) {
     if (name === this.param)
@@ -442,12 +448,14 @@ class MojoFilterEmitter {
     return `(${l} // ${r})`;
   }
   callbackMethod(method, object, arrow, _restArgs, emit) {
-    if (!PREDICATE_METHODS.has(method))
+    if (!PREDICATE_METHODS.has(method)) {
+      this.onUnsupported?.(`Filter predicate contains a nested '.${method}(...)' callback, which has no Perl scalar form`, `Rewrite the predicate without a nested callback method, or add /* @client */ for client-only evaluation (no SSR).`);
       return "1";
+    }
     const param = arrow.params[0];
     const predicate = arrow.body;
     const arrayExpr = emit(object);
-    const predBody = emitParsedExpr(predicate, new MojoFilterEmitter(param, this.localVarMap, this.isStringName));
+    const predBody = emitParsedExpr(predicate, new MojoFilterEmitter(param, this.localVarMap, this.isStringName, this.onUnsupported));
     const grepBody = predBody.replace(new RegExp(`\\$${param}\\b`, "g"), "$_");
     if (method === "filter")
       return `[grep { ${grepBody} } @{${arrayExpr}}]`;
@@ -455,6 +463,7 @@ class MojoFilterEmitter {
       return `!(grep { !(${grepBody}) } @{${arrayExpr}})`;
     if (method === "some")
       return `!!(grep { ${grepBody} } @{${arrayExpr}})`;
+    this.onUnsupported?.(`Filter predicate contains a nested '.${method}(...)' callback, which has no Perl scalar form`, `Rewrite the predicate without a nested callback method, or add /* @client */ for client-only evaluation (no SSR).`);
     return arrayExpr;
   }
   arrayLiteral(elements, emit) {
@@ -464,7 +473,7 @@ class MojoFilterEmitter {
     return renderArrayMethod(method, object, args, emit);
   }
   flatMethod(object, depth, emit) {
-    return renderFlatMethod(emit(object), depth);
+    return renderFlatMethod(emit(object), depth, emit);
   }
   conditional(_test, _consequent, _alternate) {
     return "1";
@@ -620,6 +629,13 @@ class MojoTopLevelEmitter {
       this.ctx._recordExprBF101(`.flatMap(...) projection is not lowerable to a template flat-map`, `Pre-compute the projection in the route handler, or mark the loop @client-only.`);
       return "''";
     }
+    if (method === "map") {
+      const evalForm = renderMapEval(recv, body, params[0], emit);
+      if (evalForm !== null)
+        return evalForm;
+      this.ctx._recordExprBF101(`.map(...) projection is not lowerable to a template map`, `Pre-compute the projection in the route handler, or mark the position @client-only.`);
+      return "''";
+    }
     const cb = {
       method,
       object,
@@ -672,7 +688,7 @@ class MojoTopLevelEmitter {
     return renderArrayMethod(method, object, args, emit);
   }
   flatMethod(object, depth, emit) {
-    return renderFlatMethod(emit(object), depth);
+    return renderFlatMethod(emit(object), depth, emit);
   }
   conditional(test, consequent, alternate, emit) {
     return `(${emit(test)} ? ${emit(consequent)} : ${emit(alternate)})`;
@@ -703,8 +719,8 @@ class MojoTopLevelEmitter {
   unsupported(_raw, _reason) {
     return "''";
   }
-  objectLiteral(_properties, _raw, _emit) {
-    return "''";
+  objectLiteral(properties, _raw, _emit) {
+    return properties.length === 0 ? "{}" : "''";
   }
 }
 
@@ -863,9 +879,7 @@ function recordIndexAccessToPerl(ctx, val) {
 // src/adapter/memo/seed.ts
 import {
   collectContextConsumers,
-  extractArrowBodyExpression,
-  isSupported,
-  parseExpression as parseExpression2
+  computeSsrSeedPlan
 } from "@barefootjs/jsx";
 function contextDefaultPerl(c) {
   const d = c.defaultValue;
@@ -886,42 +900,20 @@ function generateContextConsumerSeed(ir) {
 `;
 }
 function generateDerivedMemoSeed(ctx, ir) {
-  const memos = ir.metadata.memos ?? [];
-  const signals = ir.metadata.signals ?? [];
-  if (memos.length === 0 && signals.length === 0)
-    return "";
-  const available = new Set(ir.metadata.propsParams.map((p) => p.name));
+  const plan = ir.metadata.ssrSeedPlan ?? computeSsrSeedPlan(ir.metadata);
   const lines = [];
-  for (const signal of signals) {
-    const perl = tryLowerToPerl(ctx, signal.initialValue, available);
-    if (perl !== null)
-      lines.push(`% my $${signal.getter} = ${perl};`);
-    available.add(signal.getter);
-  }
-  for (const memo of memos) {
-    const body = extractArrowBodyExpression(memo.computation);
-    if (body !== null) {
-      const perl = tryLowerToPerl(ctx, body, available);
-      if (perl !== null)
-        lines.push(`% my $${memo.name} = ${perl};`);
-    }
-    available.add(memo.name);
+  for (const step of plan.steps) {
+    if (step.kind !== "derived")
+      continue;
+    const perl = ctx.convertExpressionToPerl(step.expr, step.parsed);
+    if (perl === "" || !/\$[A-Za-z_]\w*/.test(perl))
+      continue;
+    lines.push(`% my $${step.name} = ${perl};`);
   }
   return lines.length > 0 ? lines.join(`
 `) + `
 ` : "";
 }
-function tryLowerToPerl(ctx, expr, available) {
-  const trimmed = expr.trim();
-  if (!trimmed)
-    return null;
-  if (!isSupported(parseExpression2(trimmed)).supported)
-    return null;
-  const perl = ctx.convertExpressionToPerl(trimmed);
-  if (perl === "" || !/\$[A-Za-z_]\w*/.test(perl))
-    return null;
-  return referencedVarsAreAvailable(perl, available) ? perl : null;
-}
 
 // src/adapter/value/parsed-literal.ts
 function isStringTypeInfo(type) {
@@ -963,6 +955,17 @@ function collectStringValueNames(ir) {
 }
 
 // src/adapter/mojo-adapter.ts
+function perlSegmentAccessor(base, segments) {
+  let expr = base;
+  for (const seg of segments) {
+    expr += seg.kind === "field" ? `->{${seg.isIdent ? seg.key : perlHashKey(seg.key)}}` : `->[${seg.index}]`;
+  }
+  return expr;
+}
+function perlStringLiteral(s) {
+  return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+
 class MojoAdapter extends BaseAdapter {
   name = "mojolicious";
   extension = ".html.ep";
@@ -1043,7 +1046,7 @@ class MojoAdapter extends BaseAdapter {
     return this.booleanTypedProps.has(bare);
   }
   parseUndefinedAlternateTernary(expr) {
-    const parsed = parseExpression3(expr.trim());
+    const parsed = parseExpression2(expr.trim());
     if (parsed?.kind !== "conditional")
       return null;
     const alt = parsed.alternate;
@@ -1291,24 +1294,41 @@ ${whenTrue}
     return `<%== bf->comment("cond-start:${condId}") %>${content}<%== bf->comment("cond-end:${condId}") %>`;
   }
   renderLoop(loop) {
-    if (loop.clientOnly)
-      return "";
+    if (loop.clientOnly) {
+      return `<%== bf->comment("loop:${loop.markerId}") %><%== bf->comment("/loop:${loop.markerId}") %>`;
+    }
     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:
-` + `  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]) => ...\`).
-` + `  2. Mark the loop position as @client-only so the destructure runs in JS on the client.
-` + `  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.
+` + `  2. If this is chained \`.filter().map(({ ... }) => ...)\`, hoist the destructure into a variable inside the callback body instead.
+` + `  3. Mark the loop position as @client-only so the destructure runs in JS on the client.
+` + `  4. Move the loop into a primitive that the adapter registers explicitly.`
         }
       });
     }
+    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);
     let sortedHoist = null;
     let array = rawArray;
@@ -1363,7 +1383,15 @@ ${renderedChildren}` : renderedChildren;
       if (supportableDestructure) {
         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}];`);
@@ -1547,7 +1575,7 @@ ${children}`;
         if (localConst?.value !== undefined) {
           const initTrimmed = localConst.value.trim();
           if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(initTrimmed)) {
-            const resolved = conditionalSpreadToPerl(this.spreadCtx, parseExpression3(initTrimmed));
+            const resolved = conditionalSpreadToPerl(this.spreadCtx, parseExpression2(initTrimmed));
             if (resolved !== null) {
               return `<%== bf->spread_attrs(${resolved}) %>`;
             }
@@ -1565,7 +1593,7 @@ ${children}`;
     if (!entries)
       return null;
     for (const e of entries) {
-      if (e.kind === "expr" && !isSupported2(parseExpression3(e.expr)).supported)
+      if (e.kind === "expr" && !isSupported(parseExpression2(e.expr)).supported)
         return null;
     }
     return entries.map((e) => e.kind === "literal" ? `${this.escapeAttrText(e.cssKey)}:${this.escapeAttrText(e.value)}` : `${this.escapeAttrText(e.cssKey)}:<%= ${this.convertExpressionToPerl(e.expr)} %>`).join(";");
@@ -1601,7 +1629,7 @@ ${children}`;
     return `${BF_COND}="${condId}"`;
   }
   renderPerlFilterExpr(expr, param, localVarMap = new Map) {
-    return emitParsedExpr2(expr, new MojoFilterEmitter(param, localVarMap, (n) => this._isStringValueName(n)));
+    return emitParsedExpr2(expr, new MojoFilterEmitter(param, localVarMap, (n) => this._isStringValueName(n), (message, reason) => this._recordExprBF101(message, reason)));
   }
   convertTemplateLiteralPartsToPerl(literalParts) {
     const parts = [];
@@ -1646,8 +1674,8 @@ ${children}`;
     const hasTaggedTemplate = /[A-Za-z_$][\w$]*\s*`/.test(probe);
     if (!startsAsObjectLiteral && !hasTaggedTemplate)
       return false;
-    const parsed = parseExpression3(expr.trim());
-    const support = isSupported2(parsed);
+    const parsed = parseExpression2(expr.trim());
+    const support = isSupported(parsed);
     if (parsed.kind !== "unsupported" && support.supported)
       return false;
     const reason = support.reason ?? (parsed.kind === "unsupported" ? parsed.reason : undefined);
@@ -1695,7 +1723,7 @@ ${reason}` : "";
       const trimmed = expr.trim();
       if (trimmed === "")
         return "''";
-      parsed = parseExpression3(trimmed);
+      parsed = parseExpression2(trimmed);
     }
     if (parsed.kind === "call") {
       for (const matcher of this._loweringMatchers) {
@@ -1704,9 +1732,13 @@ ${reason}` : "";
           const argsGo = queryHrefArgs(node, (n) => this.renderParsedExprToPerl(n));
           return `bf->query(${argsGo.join(", ")})`;
         }
+        if (node?.kind === "helper-call" && isValidHelperId(node.helper)) {
+          const argsX = node.args.map((a) => this.renderParsedExprToPerl(a));
+          return `bf->${node.helper}(${argsX.join(", ")})`;
+        }
       }
     }
-    const support = isSupported2(parsed);
+    const support = isSupported(parsed);
     if (!support.supported) {
       this.errors.push({
         code: "BF101",
@@ -1755,7 +1787,23 @@ Options:
   }
 }
 var mojoAdapter = new MojoAdapter;
+// src/conformance-pins.ts
+var conformancePins = {
+  "static-array-children": [{ code: "BF103", severity: "error" }],
+  "todo-app": [{ code: "BF103", severity: "error" }],
+  "todo-app-ssr": [{ code: "BF103", severity: "error" }],
+  "static-array-from-props": [{ code: "BF101", severity: "error" }],
+  "static-array-from-props-with-component": [
+    { code: "BF103", severity: "error" },
+    { code: "BF101", severity: "error" }
+  ],
+  "filter-nested-find-predicate": [
+    { code: "BF101", severity: "error", issue: "https://github.com/piconic-ai/barefootjs/issues/2038" }
+  ],
+  "array-map-function-reference": [{ code: "BF101", severity: "error" }]
+};
 export {
   mojoAdapter,
+  conformancePins,
   MojoAdapter
 };

package/dist/test-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-render.d.ts","sourceRoot":"","sources":["../src/test-render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxE;AAkCD,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,OAAO,EAAE,OAAO,iBAAiB,EAAE,eAAe,CAAA;IAClD,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAgNjF;AAqWD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAuBT"}
+{"version":3,"file":"test-render.d.ts","sourceRoot":"","sources":["../src/test-render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxE;AAkCD,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,OAAO,EAAE,OAAO,iBAAiB,EAAE,eAAe,CAAA;IAClD,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAwNjF;AAqWD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAuBT"}

package/lib/BarefootJS/Backend/Mojo.pm

@@ -1,5 +1,5 @@
 package BarefootJS::Backend::Mojo;
-our $VERSION = "0.16.0";
+our $VERSION = "0.17.1";
 use Mojo::Base -base, -signatures;
 
 use Mojo::ByteStream qw(b);
@@ -78,13 +78,22 @@ sub materialize ($self, $value) {
 # instance for that render. The Mojo `bf` helper resolves the current
 # instance off `$c->stash->{'bf.instance'}`; swap it for the duration of
 # the nested render and restore it afterwards so sibling renders are
-# unaffected.
+# unaffected. `local` (rather than a manual swap) keeps the restore
+# exception-safe: a die inside the nested render — e.g. a grandchild with
+# no registered renderer — propagates without leaving the child instance
+# bound as the request's active one.
 sub render_named ($self, $template_name, $child_bf, $vars) {
     my $c = $self->c;
-    my $prev = $c->stash->{'bf.instance'};
-    $c->stash->{'bf.instance'} = $child_bf;
+    local $c->stash->{'bf.instance'} = $child_bf;
     my $html = $c->render_to_string(template => $template_name, %$vars);
-    $c->stash->{'bf.instance'} = $prev;
+    # `render_to_string` returns undef — it does NOT die — when the named
+    # template can't be rendered (typically: the template file is missing
+    # from the renderer paths). The calling template's `<%==` would emit
+    # that as an empty string, silently dropping the whole child subtree
+    # from the page (#2132). Fail the render loudly instead.
+    die qq{BarefootJS: child template "$template_name" rendered no output }
+      . qq{(is the template missing from the renderer paths?)\n}
+        unless defined $html;
     return $html;
 }
 

package/lib/Mojolicious/Plugin/BarefootJS/DevReload.pm

@@ -1,5 +1,5 @@
 package Mojolicious::Plugin::BarefootJS::DevReload;
-our $VERSION = "0.16.0";
+our $VERSION = "0.17.1";
 use Mojo::Base 'Mojolicious::Plugin', -signatures;
 
 =head1 NAME

package/lib/Mojolicious/Plugin/BarefootJS.pm

@@ -1,5 +1,5 @@
 package Mojolicious::Plugin::BarefootJS;
-our $VERSION = "0.16.0";
+our $VERSION = "0.17.1";
 use Mojo::Base 'Mojolicious::Plugin', -signatures;
 
 use Mojo::File qw(path);
@@ -31,28 +31,64 @@ sub register ($self, $app, $config = {}) {
         $c->stash->{'bf.instance'} //= BarefootJS->new($c, $config);
     });
 
-    my $manifest = _load_manifest($app, $config);
-    return unless $manifest;
-
-    # Cache the set of UI-registry slot keys so we can answer
-    # "is this template name a child or a top-level page?" with a
-    # single hash lookup at render time. Top-level entries are
-    # everything that isn't `__barefoot__` and doesn't match
-    # `ui/<name>/index` — the same partition `register_components_from_manifest`
-    # applies internally.
-    my %is_child_entry;
-    for my $entry_name (keys %$manifest) {
-        next if $entry_name eq '__barefoot__';
-        next unless $entry_name =~ m{^ui/[^/]+/index$};
-        $is_child_entry{$entry_name} = 1;
-    }
+    return if exists $config->{manifest_path} && !defined $config->{manifest_path};
+    my $manifest_path = path(
+        $config->{manifest_path} // $app->home->child('dist/templates/manifest.json'));
+
+    # Manifest resolution is lazy, re-checked per render (#2126). The
+    # scaffold's dev script starts `bf build --watch` and the web server
+    # concurrently, so the app routinely boots before the first build has
+    # written `manifest.json`. Loading once at register time turned that
+    # startup race into a permanent failure: auto-init stayed disabled for
+    # the server's lifetime and every top-level render died under strict
+    # (`Global symbol "$initial" requires explicit package name`). The
+    # cache is keyed on the file's (mtime, size), so the steady-state cost
+    # is one stat() per render — and `bf build --watch` rebuilds (new
+    # ssrDefaults, `bf add`ed components) are picked up without a restart.
+    my ($cached_sig, $manifest, $is_child_entry);
+    my $load_manifest = sub {
+        my ($size, $mtime) = (stat "$manifest_path")[7, 9];
+        unless (defined $mtime) {
+            # Missing (or unreadable) — drop the cache so the manifest is
+            # re-read as soon as the first build writes it.
+            ($cached_sig, $manifest, $is_child_entry) = (undef, undef, undef);
+            return undef;
+        }
+        my $sig = "$mtime/$size";
+        return $manifest if defined $cached_sig && $cached_sig eq $sig;
+        # Cache parse failures under the same signature so a broken file
+        # warns once, not on every render, and retries when it changes.
+        $cached_sig = $sig;
+        ($manifest, $is_child_entry) = (undef, undef);
+        my $m = eval { decode_json($manifest_path->slurp) };
+        if ($@ || ref($m) ne 'HASH') {
+            $app->log->warn("BarefootJS: cannot parse manifest at $manifest_path: $@") if $@;
+            return undef;
+        }
+        $manifest = $m;
+
+        # Cache the set of UI-registry slot keys so we can answer
+        # "is this template name a child or a top-level page?" with a
+        # single hash lookup at render time. Top-level entries are
+        # everything that isn't `__barefoot__` and doesn't match
+        # `ui/<name>/index` — the same partition `register_components_from_manifest`
+        # applies internally.
+        $is_child_entry = {};
+        for my $entry_name (keys %$manifest) {
+            next if $entry_name eq '__barefoot__';
+            next unless $entry_name =~ m{^ui/[^/]+/index$};
+            $is_child_entry->{$entry_name} = 1;
+        }
+        return $manifest;
+    };
 
     $app->hook(before_render => sub ($c, $args) {
         my $template = $args->{template};
         return unless defined $template && length $template;
-        my $entry = $manifest->{$template};
+        my $m = $load_manifest->() or return;
+        my $entry = $m->{$template};
         return unless $entry;
-        return if $is_child_entry{$template};
+        return if $is_child_entry->{$template};
         # Idempotency guard for nested renders. A controller might
         # call `render_to_string` inside an action and then `render`
         # — without this we'd re-init `bf` on the second pass and
@@ -72,7 +108,7 @@ sub register ($self, $app, $config = {}) {
         $c->stash->{'bf.auto_init_done'} = 1;
 
         $bf->_scope_id($template . '_' . substr(rand() =~ s/^0\.//r, 0, 6));
-        $bf->register_components_from_manifest($manifest);
+        $bf->register_components_from_manifest($m);
 
         # Seed each ssrDefault into the stash unless the caller has
         # already supplied a value for that key — callers always win.
@@ -98,20 +134,6 @@ sub register ($self, $app, $config = {}) {
     });
 }
 
-sub _load_manifest ($app, $config) {
-    return undef if exists $config->{manifest_path} && !defined $config->{manifest_path};
-    my $manifest_path = $config->{manifest_path}
-        // $app->home->child('dist/templates/manifest.json');
-    my $file = path($manifest_path);
-    return undef unless -r $file;
-    my $manifest = eval { decode_json($file->slurp) };
-    if ($@ || ref($manifest) ne 'HASH') {
-        $app->log->warn("BarefootJS: cannot parse manifest at $file: $@") if $@;
-        return undef;
-    }
-    return $manifest;
-}
-
 1;
 __END__
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/mojolicious",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Mojolicious EP template adapter for BarefootJS - generates .html.ep files from IR",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,7 +52,7 @@
     "directory": "packages/adapter-mojolicious"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.17.0"
+    "@barefootjs/shared": "0.18.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0",
@@ -60,6 +60,6 @@
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.17.0"
+    "@barefootjs/jsx": "0.18.0"
   }
 }