@barefootjs/xslate 0.17.1 → 0.18.0

package/dist/index.js

@@ -187302,12 +187302,13 @@ import {
   emitAttrValue,
   augmentInheritedPropAccesses,
   collectModuleStringConsts,
-  isLowerableObjectRestDestructure,
   lookupStaticRecordLiteral,
   searchParamsLocalNames,
   prepareLoweringMatchers,
   queryHrefArgs,
-  sortComparatorFromArrow as sortComparatorFromArrow2
+  isValidHelperId,
+  sortComparatorFromArrow as sortComparatorFromArrow2,
+  isLowerableLoopDestructure
 } from "@barefootjs/jsx";
 
 // src/adapter/boolean-result.ts
@@ -187600,7 +187601,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})`;
 }
@@ -187711,7 +187715,7 @@ class XslateFilterEmitter {
     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";
@@ -187911,7 +187915,7 @@ class XslateTopLevelEmitter {
     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)})`;
@@ -187942,8 +187946,8 @@ class XslateTopLevelEmitter {
   unsupported(_raw, _reason) {
     return "''";
   }
-  objectLiteral(_properties, _raw, _emit) {
-    return "''";
+  objectLiteral(properties, _raw, _emit) {
+    return properties.length === 0 ? "{}" : "''";
   }
 }
 
@@ -188174,6 +188178,17 @@ function collectStringValueNames(ir) {
 }
 
 // src/adapter/xslate-adapter.ts
+function kolonSegmentAccessor(base, segments) {
+  let expr = base;
+  for (const seg of segments) {
+    expr += seg.kind === "field" ? seg.isIdent ? `.${seg.key}` : `[${kolonHashKey(seg.key)}]` : `[${seg.index}]`;
+  }
+  return expr;
+}
+function kolonStringLiteral(s) {
+  return `'${escapeKolonSingleQuoted(s)}'`;
+}
+
 class XslateAdapter extends BaseAdapter {
   name = "xslate";
   extension = ".tx";
@@ -188442,21 +188457,37 @@ ${whenTrue}
       return `<: $bf.comment("loop:${loop.markerId}") | mark_raw :><: $bf.comment("/loop:${loop.markerId}") | mark_raw :>`;
     }
     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 Xslate adapter cannot lower — Kolon \`for LIST -> $item\` binds a single scalar and can't unpack a tuple.`,
+        message: `Loop callback uses a destructure pattern (\`${loop.param}\`) that the Xslate 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 Xslate 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.convertExpressionToKolon(loop.array);
     let array = rawArray;
     if (loop.sortComparator) {
@@ -188478,7 +188509,15 @@ ${whenTrue}
     }
     if (supportableDestructure) {
       for (const b of loop.paramBindings ?? []) {
-        indexLocalLines.push(b.rest ? `: my $${b.name} = $${loopVar};` : `: my $${b.name} = $${loopVar}${b.path};`);
+        const parent = kolonSegmentAccessor(`$${loopVar}`, b.segments ?? []);
+        if (b.rest?.kind === "object") {
+          const exclude = b.rest.exclude.map((k) => kolonStringLiteral(k.key)).join(", ");
+          indexLocalLines.push(`: my $${b.name} = $bf.omit(${parent}, [${exclude}]);`);
+        } else if (b.rest?.kind === "array") {
+          indexLocalLines.push(`: my $${b.name} = $bf.slice(${parent}, ${b.rest.from}, nil);`);
+        } else {
+          indexLocalLines.push(`: my $${b.name} = ${kolonSegmentAccessor(`$${loopVar}`, b.segments ?? [])};`);
+        }
       }
     }
     const prevInLoop = this.inLoop;
@@ -188534,8 +188573,32 @@ ${childrenUnderLoop}` : childrenUnderLoop;
     emitBooleanShorthand: (_value, name) => `${kolonHashKey(name)} => 1`,
     emitJsxChildren: () => ""
   };
+  componentPropSegmentEntries(segments) {
+    const last = segments[segments.length - 1];
+    if (last && last.kind === "entries")
+      return last.parts;
+    const seg = { kind: "entries", parts: [] };
+    segments.push(seg);
+    return seg.parts;
+  }
+  combineComponentPropSegments(segments) {
+    let acc = null;
+    for (const seg of segments) {
+      if (seg.kind === "entries") {
+        if (seg.parts.length === 0)
+          continue;
+        const text = `{ ${seg.parts.join(", ")} }`;
+        acc = acc === null ? text : `${acc}.merge(${text})`;
+      } else {
+        const text = `(${seg.expr} // {})`;
+        acc = acc === null ? text : `${acc}.merge(${text})`;
+      }
+    }
+    return acc ?? "{}";
+  }
   renderComponent(comp) {
-    const propParts = [];
+    const segments = [{ kind: "entries", parts: [] }];
+    const currentEntries = () => this.componentPropSegmentEntries(segments);
     for (const p of comp.props) {
       if ((p.name.match(/^on[A-Z]/) || p.name === "ref") && p.value.kind === "expression")
         continue;
@@ -188543,27 +188606,19 @@ ${childrenUnderLoop}` : childrenUnderLoop;
         const trimmed = p.value.expr.trim();
         if (this.propsObjectName && this.propsObjectName === trimmed) {
           for (const pp of this.propsParams) {
-            propParts.push(`${pp.name} => $${pp.name}`);
+            currentEntries().push(`${pp.name} => $${pp.name}`);
           }
           continue;
         }
-        this.errors.push({
-          code: "BF101",
-          severity: "error",
-          message: `Spread props (\`{...${trimmed}}\`) on a child component cannot be lowered to Kolon — Kolon hashref method args can't splat a runtime hash into named entries.`,
-          loc: comp.loc ?? { file: this.componentName + ".tsx", start: { line: 1, column: 0 }, end: { line: 1, column: 0 } },
-          suggestion: {
-            message: "Pass the child component its props explicitly rather than spreading a runtime object."
-          }
-        });
+        segments.push({ kind: "spread", expr: this.convertExpressionToKolon(p.value.expr) });
         continue;
       }
       const lowered = emitAttrValue(p.value, this.componentPropEmitter, p.name);
       if (lowered)
-        propParts.push(lowered);
+        currentEntries().push(lowered);
     }
     if (comp.slotId && !this.inLoop) {
-      propParts.push(`_bf_slot => '${comp.slotId}'`);
+      currentEntries().push(`_bf_slot => '${comp.slotId}'`);
     }
     const tplName = this.toTemplateName(comp.name);
     const effectiveChildren = comp.children.length > 0 ? comp.children : resolveJsxChildrenProp(comp.props);
@@ -188573,11 +188628,12 @@ ${childrenUnderLoop}` : childrenUnderLoop;
       const childrenBody = this.renderChildren(effectiveChildren);
       this.inLoop = prevInLoop;
       const macroName = `bf_children_${comp.slotId ?? "c" + this.childrenCaptureCounter++}`;
-      const childrenEntry = `children => ${macroName}()`;
-      const allParts = [...propParts, childrenEntry];
-      return `<: macro ${macroName} -> () { :>${childrenBody}<: } :><: $bf.render_child('${tplName}', { ${allParts.join(", ")} }) | mark_raw :>`;
+      currentEntries().push(`children => ${macroName}()`);
+      const dict = this.combineComponentPropSegments(segments);
+      return `<: macro ${macroName} -> () { :>${childrenBody}<: } :><: $bf.render_child('${tplName}', ${dict}) | mark_raw :>`;
     }
-    const hashEntries = propParts.length > 0 ? `, { ${propParts.join(", ")} }` : "";
+    const isEmpty = segments.every((s) => s.kind === "entries" && s.parts.length === 0);
+    const hashEntries = isEmpty ? "" : `, ${this.combineComponentPropSegments(segments)}`;
     return `<: $bf.render_child('${tplName}'${hashEntries}) | mark_raw :>`;
   }
   childrenCaptureCounter = 0;
@@ -188852,6 +188908,10 @@ ${reason}` : "";
           const qArgs = queryHrefArgs(node, (n) => this.renderParsedExprToKolon(n));
           return `$bf.query(${qArgs.join(", ")})`;
         }
+        if (node?.kind === "helper-call" && isValidHelperId(node.helper)) {
+          const argsX = node.args.map((a) => this.renderParsedExprToKolon(a));
+          return `$bf.${node.helper}(${argsX.join(", ")})`;
+        }
       }
     }
     const support = isSupported(parsed);
@@ -188951,7 +189011,26 @@ Options:
   }
 }
 var xslateAdapter = new XslateAdapter;
+// 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-callback-predicate": [
+    { code: "BF101", severity: "error", issue: "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" }
+  ],
+  "array-map-function-reference": [{ code: "BF101", severity: "error" }]
+};
 export {
   xslateAdapter,
+  conformancePins,
   XslateAdapter
 };

package/lib/BarefootJS/Backend/Xslate.pm

@@ -1,5 +1,5 @@
 package BarefootJS::Backend::Xslate;
-our $VERSION = "0.17.0";
+our $VERSION = "0.17.1";
 use strict;
 use warnings;
 use utf8;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/xslate",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Text::Xslate (Kolon) adapter for BarefootJS — compiles IR to .tx templates and ships the Xslate rendering backend; runs under any PSGI/Plack app",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,14 +55,14 @@
     "directory": "packages/adapter-xslate"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.17.1"
+    "@barefootjs/shared": "0.18.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.17.1",
+    "@barefootjs/jsx": "0.18.0",
     "typescript": "^5.0.0"
   }
 }

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

@@ -13,13 +13,11 @@
  */
 
 import { describe, test, expect } from 'bun:test'
-import {
-  runAdapterConformanceTests,
-  TemplatePrimitiveCaseId,
-} from '@barefootjs/adapter-tests'
+import { runAdapterConformanceTests } from '@barefootjs/adapter-tests'
 import { XslateAdapter } from '../adapter'
 import { renderXslateComponent, XslateNotAvailableError } from '../test-render'
 import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { conformancePins } from '../conformance-pins'
 
 runAdapterConformanceTests({
   name: 'xslate',
@@ -33,105 +31,17 @@ runAdapterConformanceTests({
   // body children (TableCell) now receive `_bf_slot` for deterministic
   // parent-scope-derived IDs matching Hono.
   // Per-fixture build-time contracts for shapes the Xslate adapter
-  // intentionally refuses to lower. Mirrors mojo's set — the lowering
-  // gates are shared code paths in the ported adapter.
-  expectedDiagnostics: {
-    // Sibling-imported child component in a loop body: emits a
-    // cross-template call needing separate registration. BF103 makes
-    // the requirement loud (same as mojo).
-    'static-array-children': [{ code: 'BF103', severity: 'error' }],
-    // TodoApp / TodoAppSSR import `TodoItem` from a sibling file and
-    // call it inside a keyed `.map`. With the standalone-filter fix in
-    // place these reach the SAME BF103 (imported child in `.map`) as
-    // mojo — NOT BF101 — confirming the `.filter(...)` chain itself now
-    // lowers and the only remaining gate is the imported-child one.
-    'todo-app': [{ code: 'BF103', severity: 'error' }],
-    'todo-app-ssr': [{ code: 'BF103', severity: 'error' }],
-    // Array-destructure loop param (`([k, v]) => …`) can't lower to a
-    // single Kolon loop variable (same BF104 as mojo).
-    'static-array-from-props': [{ code: 'BF104', severity: 'error' }],
-    // Both BF103 (imported child) and BF104 (destructure) fire.
-    'static-array-from-props-with-component': [
-      { code: 'BF103', severity: 'error' },
-      { code: 'BF104', severity: 'error' },
-    ],
-    // Rest-destructure `.map()` callbacks — the object-rest shape read via
-    // member access (`rest-destructure-object-in-map`) now lowers via Kolon
-    // `: my` binding locals (`$rest` aliases the item). The other three stay
-    // refused: rest SPREAD needs a residual object, array-index / nested paths
-    // can't unpack a tuple (same surface as mojo).
-    'rest-destructure-object-spread-in-map': [{ code: 'BF104', severity: 'error' }],
-    'rest-destructure-array-in-map': [{ code: 'BF104', severity: 'error' }],
-    'rest-destructure-nested-in-map': [{ code: 'BF104', severity: 'error' }],
-    // XSLATE-SPECIFIC (mojo passes this): the site/ui Button auto-infers a
-    // `<Slot>` sibling that spreads `{...props}` / `{...children.props}`
-    // onto its root element. Kolon hashref method args can't splat a
-    // runtime hash into named entries (no `%$h`-into-call-args form), so
-    // the adapter refuses the spread with BF101 rather than emit a broken
-    // render_child call. Mojo's EP `%= include` accepts a flat stash, so it
-    // lowers the same shape; this is a genuine engine divergence, pinned
-    // declaratively here.
-    'button': [{ code: 'BF101', severity: 'error' }],
-    // `kbd` auto-infers the same `<Slot>` `{...props}` spread as `button`
-    // above — refused with BF101 for the identical Kolon engine reason, not a
-    // render-mismatch (so it's pinned here, not in `skipJsx`).
-    'kbd': [{ code: 'BF101', severity: 'error' }],
-    // #1467 demo-corpus context providers (`radio-group`, `select`,
-    // `dropdown-menu`, `combobox`, `command`) are no longer pinned — an
-    // object-literal provider value (`{ value: currentValue,
-    // onValueChange: (v) => {…} }`) lowers to a Kolon hashref via
-    // `parseProviderObjectLiteral` (#1897): getter members snapshot
-    // their body's SSR value, handler / function-shaped members lower
-    // to `nil`. 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 — it
-    // compiles clean now (`selected()[index]` → `index-access`,
-    // `.toFixed(2)` → `$bf.to_fixed`, `/* @client */` memo SSR-folded)
-    // and renders to Hono parity on real Text::Xslate. 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.
-    // `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-literal call in a className — same family, same
-    // refusal (BF101).
-    'tagged-template-classname': [{ code: 'BF101', severity: 'error' }],
-    // #2038: a filter predicate whose body contains a NESTED callback call
-    // (`t => !picked().some(p => …)` / `t => picked().find(p => …)`). Kolon
-    // has no inline `grep` form, so `XslateFilterEmitter.callbackMethod` used
-    // to degrade the inner call to its receiver, silently changing predicate
-    // semantics — the compiler is loud instead of lossy. (Mojo is pinned only
-    // for the `.find` variant: it lowers a nested `.some` to a real inline
-    // Perl `grep`.) The `/* @client */` twin
-    // (`filter-nested-callback-predicate-client`) has no pin here: it must
-    // render clean on every adapter, which asserts the suppression contract.
-    // https://github.com/piconic-ai/barefootjs/issues/2038
-    'filter-nested-callback-predicate': [{ code: 'BF101', severity: 'error' }],
-    'filter-nested-find-predicate': [{ code: 'BF101', severity: 'error' }],
-    // NB: TOP-LEVEL `.find` / `.findIndex` / `.findLast` / `.findLastIndex`
-    // (text position) are NOT pinned here — unlike mojo (which refuses them),
-    // Xslate lowers them to `$bf.find` / `find_index` / `find_last` /
-    // `find_last_index` via the same Kolon-lambda mechanism as `.filter` /
-    // `.every` / `.some`, so they render. Only the NESTED-in-a-predicate form
-    // above is refused (#2038).
-    // #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' }],
-  },
-  // Template-primitive registry parity: same V1 surface as mojo, so the
-  // same two cases stay skipped (bespoke user import + customSerialize
-  // can't render server-side without user-supplied helper mappings).
-  skipTemplatePrimitives: new Set([
-    TemplatePrimitiveCaseId.USER_IMPORT_VIA_CONST,
-    TemplatePrimitiveCaseId.NO_DOUBLE_REWRITE_OF_PROPS_OBJECT,
-  ]),
+  // intentionally refuses to lower. Lives in `../conformance-pins` —
+  // mirrors mojo's set (the lowering gates are shared code paths in
+  // the ported adapter).
+  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.
   // `client-only` / `client-only-loop-with-sibling-cond` /
   // `filter-nested-callback-predicate-client` are no longer skipped —
   // `renderLoop` now emits the `$bf.comment("loop:<id>")` boundary pair

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

@@ -326,7 +326,28 @@ export function renderSortMethod(recv: string, c: SortComparator): string {
 }
 
 // `.flat(depth?)` → `$bf.flat($recv, $depth)`.
-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

@@ -183,8 +183,12 @@ export class XslateFilterEmitter 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 {
@@ -486,8 +490,12 @@ export class XslateTopLevelEmitter 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(
@@ -537,12 +545,16 @@ export class XslateTopLevelEmitter 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 empty-string literal, exactly as before the
-    // `object-literal` kind existed (byte-identical; Roadmap A-1). Object
-    // values that round-trip to a Kolon hashref go through the dedicated
-    // `objectLiteralToKolonHashref` 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 Kolon's real empty hashref
+    // literal, matching the `'{}'` convention `objectLiteralToKolonHashref`
+    // 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 ? '{}' : "''"
   }
 }