@barefootjs/xslate 0.16.0 → 0.17.1

package/lib/BarefootJS/Backend/Xslate.pm

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/xslate",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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.16.0"
+    "@barefootjs/shared": "0.17.1"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"
   },
   "devDependencies": {
     "@barefootjs/adapter-tests": "0.1.0",
-    "@barefootjs/jsx": "0.16.0",
+    "@barefootjs/jsx": "0.17.1",
     "typescript": "^5.0.0"
   }
 }

package/src/__tests__/query-href.test.ts

@@ -0,0 +1,96 @@
+/**
+ * `queryHref(base, { … })` → `$bf.query(...)` lowering for the Xslate adapter
+ * (#2042). Parity with the go-template / Mojo lowering: the call + object literal
+ * are structured IR, so it lowers directly. The shared `query` runtime helper
+ * (BarefootJS.pm) includes a pair iff its guard is truthy AND its value is a
+ * non-empty string, so a plain `key: v` passes guard `1` and a conditional
+ * `key: cond ? v : undefined` passes the lowered condition.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX, type ComponentIR } from '@barefootjs/jsx'
+import { XslateAdapter } from '../adapter/xslate-adapter'
+
+function template(src: string): string {
+  const a = new XslateAdapter()
+  const r = compileJSX(src.trimStart(), 'T.tsx', { adapter: a, outputIR: true })
+  const ir = JSON.parse(r.files.find(f => f.type === 'ir')!.content) as ComponentIR
+  return a.generate(ir).template
+}
+
+describe('queryHref → $bf.query (Xslate, #2042)', () => {
+  test('a plain value passes guard 1', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={queryHref(props.base, { tag: props.tag })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tag)")
+  })
+
+  test('a conditional include passes the lowered condition as the guard', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; sort: string; tag: string }) {
+  return <a href={queryHref(props.base, { sort: props.sort !== 'date' ? props.sort : undefined, tag: props.tag })}>x</a>
+}
+`)
+    // Kolon uses `!=` for string inequality (no `ne` operator).
+    expect(t).toContain("$bf.query($base, ($sort != 'date'), 'sort', $sort, 1, 'tag', $tag)")
+  })
+
+  // A bare-value guard (`flag ? v : undefined`) is JS *string* truthiness — `'0'`
+  // is a truthy string in JS but false under Perl's `unless`. The lowering must
+  // normalise it to a non-empty-string test so SSR matches the client / go (where
+  // `lowerUrlGuard` emits `ne <value> ""`). Kolon renders the `!== ''` test as
+  // `!= ''` (its string inequality), matching the comparison guard above.
+  test('a bare-value guard is normalised to a non-empty-string test', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; flag: string; val: string }) {
+  return <a href={queryHref(props.base, { q: props.flag ? props.val : undefined })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, ($flag != ''), 'q', $val)")
+  })
+
+  // An array value (`{ tag: props.tags }`) lowers to the bare slice expression;
+  // the shared Perl `query` helper detects the arrayref at runtime and appends
+  // one pair per non-empty member (#2048). No adapter-side change beyond passing
+  // the value through.
+  test('an array value passes the slice expression for the helper to append', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; tags: string[] }) {
+  return <a href={queryHref(props.base, { tag: props.tags })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tags)")
+  })
+
+  test('an aliased import is recognised', () => {
+    const t = template(`
+'use client'
+import { queryHref as qh } from '@barefootjs/client'
+export function P(props: { base: string; tag: string }) {
+  return <a href={qh(props.base, { tag: props.tag })}>x</a>
+}
+`)
+    expect(t).toContain("$bf.query($base, 1, 'tag', $tag)")
+  })
+
+  test('a dynamic (non-literal) params object falls back (no $bf.query)', () => {
+    const t = template(`
+'use client'
+import { queryHref } from '@barefootjs/client'
+export function P(props: { base: string; q: Record<string, string> }) {
+  return <a href={queryHref(props.base, props.q)}>x</a>
+}
+`)
+    expect(t).not.toContain('.query')
+  })
+})

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

@@ -101,10 +101,29 @@ runAdapterConformanceTests({
     // Tagged-template-literal call in a className — same family, same
     // refusal (BF101).
     'tagged-template-classname': [{ code: 'BF101', severity: 'error' }],
-    // NB: `.find` / `.findIndex` / `.findLast` / `.findLastIndex` 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.
+    // #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
@@ -113,11 +132,15 @@ runAdapterConformanceTests({
     TemplatePrimitiveCaseId.USER_IMPORT_VIA_CONST,
     TemplatePrimitiveCaseId.NO_DOUBLE_REWRITE_OF_PROPS_OBJECT,
   ]),
-  // Loop boundary markers for `@client` loops aren't emitted by the
-  // Xslate adapter yet (ported from mojo, which skips the same set).
+  // `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
+  // for clientOnly loops (Hono / Go parity), so mapArray() can locate
+  // its insertion anchor at hydration time (#872 / #1087).
   skipMarkerConformance: new Set([
-    'client-only',
-    'client-only-loop-with-sibling-cond',
+    // Same as Hono / Mojo: `/* @client */` markers on TodoApp's keyed
+    // `.map` intentionally elide a slot id from the SSR template that
+    // the IR still declares (s6). See hono-adapter.test for the contract.
     'todo-app',
     // #1467 Phase 2e: same `/* @client */` keyed-map elision (data-table).
     'data-table',
@@ -291,3 +314,172 @@ export function C() {
     expect(deferred.template).not.toContain('data-x')
   })
 })
+
+// #2018 P2: higher-order predicates lower through the runtime evaluator
+// (`$bf.*_eval`), isomorphic with the Go / Mojo `*_eval` helpers. A predicate
+// the evaluator can't model (a method-call predicate) falls back to the Kolon
+// lambda runtime call. Template-text pins guard against silent divergence.
+describe('XslateAdapter - #2075 searchParams()-derived memo seeding', () => {
+  test('seeds an aliased scalar derived memo from the canonical reader', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function SortStatus() {
+  const [sp] = createSearchParams()
+  const sort = createMemo(() => sp().get('sort') ?? 'date')
+  return <p>sort: {sort()}</p>
+}
+`)
+    expect(template).toContain(": my $sort = ($searchParams.get('sort') // 'date');")
+  })
+
+  // The Kolon lambda param and the `$bf` runtime object are
+  // lowering-internal, not out-of-scope template vars (#2075).
+  test('seeds a filter memo chained off the derived memo', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo, createSearchParams } from '@barefootjs/client'
+export function TaggedList(props: { items: { title: string; tags: string[] }[] }) {
+  const [searchParams] = createSearchParams()
+  const tag = createMemo(() => searchParams().get('tag') ?? '')
+  const visible = createMemo(() => props.items.filter((p) => !tag() || p.tags.includes(tag())))
+  return <ul>{visible().map((p) => <li key={p.title}>{p.title}</li>)}</ul>
+}
+`)
+    expect(template).toContain(": my $tag = ($searchParams.get('tag') // '');")
+    expect(template).toContain(': my $visible = $bf.filter($items,')
+  })
+
+  // The seed-scope guard used to scan the LOWERED
+  // Kolon string, allowing every arrow-callback param tree-wide. That let an
+  // outer, unbound `p` (shadowed only inside the callback) slip past the
+  // guard as if it were the callback's own bound `$p` — emitting a bogus
+  // seed line. The guard now walks the parsed SOURCE tree with proper
+  // lexical scoping (`freeIdentifiers`), so this shape seeds nothing and
+  // falls back to the null/ssr-defaults path.
+  test('an outer unbound `p` shadowed only inside the callback does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { items: { ok: boolean }[] }) {
+  const visible = createMemo(() => props.items.filter((p) => p.ok) && p)
+  return <div>{String(visible())}</div>
+}
+`)
+    expect(template).not.toContain('my $visible')
+  })
+
+  // An out-of-scope bare `_` reference must not seed either — the old
+  // unconditional `allowed.add('_')` / `allowed.add('bf')` masked this.
+  test('an out-of-scope bare `_` reference does not seed', () => {
+    const { template } = compileAndGenerate(`
+'use client'
+import { createMemo } from '@barefootjs/client'
+export function C(props: { count: number }) {
+  const doubled = createMemo(() => props.count * 2 + _)
+  return <div>{doubled()}</div>
+}
+`)
+    expect(template).not.toContain('my $doubled')
+  })
+})
+
+describe('XslateAdapter - #2073 value-producing .map(cb)', () => {
+  // The blog-showcase shape (#1938/#1939): a value-returning `.map` (string
+  // projection, not JSX) lowers through the evaluator — `$bf.map_eval`
+  // projects each element (no flatten) and composes through `$bf.join`.
+  test('.map(t => `#${t}`).join(" ") emits $bf.map_eval composed into $bf.join', () => {
+    const { template } = compileAndGenerate(`
+function TagLine({ tags }: { tags: string[] }) {
+  return <p>{tags.map((t) => \`#\${t}\`).join(' ')}</p>
+}
+export { TagLine }
+`)
+    expect(template).toContain("$bf.join($bf.map_eval($tags,")
+    expect(template).toContain('"kind":"template-literal"')
+  })
+
+  test('.map(u => u.name) emits $bf.map_eval with the field projection', () => {
+    const { template } = compileAndGenerate(`
+function NameList({ users }: { users: { name: string }[] }) {
+  return <div>{users.map((u) => u.name).join(', ')}</div>
+}
+export { NameList }
+`)
+    expect(template).toContain('$bf.map_eval($users,')
+    expect(template).toContain('"property":"name"')
+  })
+})
+
+describe('XslateAdapter - higher-order predicate lowering (#2018 P2)', () => {
+  test('a serializable predicate lowers to $bf.filter_eval with the JSON body + env', () => {
+    // A standalone `.filter().length` exercises the higher-order emitter (the
+    // `.filter().map()` form is a loop-hoist with an inline `: if`, handled by
+    // renderLoop, not this emitter).
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.filter(x => x.done).length}</div>
+}
+export { A }
+`)
+    expect(template).toContain('$bf.filter_eval(')
+    expect(template).toContain('"property":"done"')
+    expect(template).toContain("'x'")
+  })
+
+  test('.find / .findLast share $bf.find_eval, distinguished by the forward flag', () => {
+    const find = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.find(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(find).toContain('$bf.find_eval(')
+    expect(find).toContain(', 1, {})')
+
+    const findLast = compileAndGenerate(`
+function A({ items }: { items: { done: boolean }[] }) {
+  return <div>{items.findLast(x => x.done) ? 'y' : 'n'}</div>
+}
+export { A }
+`).template
+    expect(findLast).toContain('$bf.find_eval(')
+    expect(findLast).toContain(', 0, {})')
+  })
+
+  test('.includes() in a predicate now lowers via the evaluator, not the Kolon-lambda fallback', () => {
+    // #2075: `.includes(x)` joined the evaluator's `array-method` surface
+    // (shared with the Perl `Evaluator.pm` runtime), so a predicate built
+    // from it routes through `$bf.every_eval` like any other pure predicate.
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { name: string }[] }) {
+  return <div>{items.every(x => x.name.includes('a')) ? 'y' : 'n'}</div>
+}
+export { A }
+`)
+    expect(template).toContain('$bf.every_eval(')
+    expect(template).toContain('"method":"includes"')
+    expect(template).not.toContain('-> $x {')
+  })
+
+  test('a method-call predicate outside the evaluator surface falls back to the Kolon-lambda runtime call', () => {
+    const { template } = compileAndGenerate(`
+function A({ items }: { items: { name: string }[] }) {
+  return <div>{items.every(x => x.name.toUpperCase() === 'A') ? 'y' : 'n'}</div>
+}
+export { A }
+`)
+    // `.toUpperCase()` is outside the evaluator's `array-method` gate (only
+    // `includes` is recognized there), so the predicate keeps the
+    // `-> $x { … }` lambda form passed to the runtime `$bf.every`.
+    expect(template).not.toContain('every_eval')
+    expect(template).toContain('$bf.every(')
+    expect(template).toContain('-> $x {')
+  })
+})
+
+// #2038 nested-callback-predicate loudness is pinned at the shared
+// conformance layer: `filter-nested-callback-predicate` /
+// `filter-nested-find-predicate` (BF101 via `expectedDiagnostics` above) and
+// `filter-nested-callback-predicate-client` (the `/* @client */` suppression
+// twin, which must render clean).

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

@@ -0,0 +1,123 @@
+/**
+ * Component-tree analysis for the Text::Xslate (Kolon) template adapter.
+ *
+ * Extracted from `xslate-adapter.ts` (domain-module refactor, issue #2018
+ * track D). Pure functions over the IR — they read no adapter instance
+ * state. `collectImportedLoopChildComponentErrors` returns its diagnostics
+ * instead of pushing onto the adapter's error list, so the adapter stays the
+ * sole owner of `errors`.
+ *
+ * SHARED CANDIDATE: `hasClientInteractivity` is byte-identical to the Mojo
+ * adapter's copy and adapter-agnostic; the BF103 loop-child check is the same
+ * structural walk in both, differing only in the Perl/Kolon diagnostic text —
+ * both are groundwork for a shared Perl-family codegen module (issue #2018
+ * track D).
+ */
+
+import type {
+  ComponentIR,
+  IRNode,
+  IRComponent,
+  IRElement,
+  IRFragment,
+  IRConditional,
+  IRLoop,
+  IRIfStatement,
+  IRProvider,
+  IRAsync,
+  CompilerError,
+} from '@barefootjs/jsx'
+
+/**
+ * Whether the component needs the client runtime — it owns reactive state
+ * (signals / effects / onMount) or the analyzer flagged it as needing init.
+ */
+export function hasClientInteractivity(ir: ComponentIR): boolean {
+  return (
+    ir.metadata.signals.length > 0 ||
+    ir.metadata.effects.length > 0 ||
+    ir.metadata.onMounts.length > 0 ||
+    (ir.metadata.clientAnalysis?.needsInit ?? false)
+  )
+}
+
+/**
+ * Build a `BF103` diagnostic for every component reference inside a loop body
+ * whose name is imported from a relative-path module. Mirror of the Go
+ * adapter's check — the Xslate adapter has the same cross-template-registration
+ * constraint at request time. Returns the diagnostics so the caller pushes
+ * them onto its own error list.
+ */
+export function collectImportedLoopChildComponentErrors(
+  ir: ComponentIR,
+  componentName: string,
+): CompilerError[] {
+  const errors: CompilerError[] = []
+  const relativeImports = new Set<string>()
+  for (const imp of ir.metadata.templateImports ?? ir.metadata.imports ?? []) {
+    if (!imp.source.startsWith('./') && !imp.source.startsWith('../')) continue
+    if (imp.isTypeOnly) continue
+    for (const spec of imp.specifiers) {
+      relativeImports.add(spec.alias ?? spec.name)
+    }
+  }
+  if (relativeImports.size === 0) return errors
+
+  const loc = { file: componentName + '.tsx', start: { line: 1, column: 0 }, end: { line: 1, column: 0 } }
+  const visit = (node: IRNode, inLoop: boolean): void => {
+    switch (node.type) {
+      case 'component': {
+        const comp = node as IRComponent
+        if (inLoop && relativeImports.has(comp.name)) {
+          errors.push({
+            code: 'BF103',
+            severity: 'error',
+            message: `Component <${comp.name}> is imported from a sibling module and used inside a loop. The Xslate adapter emits a cross-template call; the child template must be registered alongside the parent at render time.`,
+            loc: comp.loc ?? loc,
+            suggestion: {
+              message:
+                `Options:\n` +
+                `  1. Compile '${comp.name}' (its source file) with the same adapter and register the resulting Xslate template alongside the parent at render time.\n` +
+                `  2. Inline <${comp.name}> directly inside the loop body so no cross-file template lookup is needed.\n` +
+                `  3. Mark the loop position as @client-only so the template is materialised on the client instead of at SSR time.`,
+            },
+          })
+        }
+        for (const child of comp.children) visit(child, inLoop)
+        break
+      }
+      case 'element':
+        for (const child of (node as IRElement).children) visit(child, inLoop)
+        break
+      case 'fragment':
+        for (const child of (node as IRFragment).children) visit(child, inLoop)
+        break
+      case 'conditional': {
+        const cond = node as IRConditional
+        visit(cond.whenTrue, inLoop)
+        if (cond.whenFalse) visit(cond.whenFalse, inLoop)
+        break
+      }
+      case 'loop':
+        for (const child of (node as IRLoop).children) visit(child, true)
+        break
+      case 'if-statement': {
+        const stmt = node as IRIfStatement
+        visit(stmt.consequent, inLoop)
+        if (stmt.alternate) visit(stmt.alternate, inLoop)
+        break
+      }
+      case 'provider':
+        for (const child of (node as IRProvider).children) visit(child, inLoop)
+        break
+      case 'async': {
+        const a = node as IRAsync
+        visit(a.fallback, inLoop)
+        for (const child of a.children) visit(child, inLoop)
+        break
+      }
+    }
+  }
+  visit(ir.root, false)
+  return errors
+}

package/src/adapter/emit-context.ts

@@ -0,0 +1,104 @@
+/**
+ * The contract the extracted expression-emitter modules depend on instead of
+ * the concrete `XslateAdapter`.
+ *
+ * The Xslate adapter's top-level expression lowering is mutually recursive
+ * with the adapter's own const/record resolution and its filter-predicate
+ * emitter, so the extracted `XslateTopLevelEmitter` still needs to call back
+ * into shared per-compile state and recursive entry points. `XslateEmitContext`
+ * is that seam: the emitter takes a `XslateEmitContext` built by the adapter's
+ * private `emitCtx` getter (the adapter does NOT `implements` this interface,
+ * so the wrapped members stay private and off its exported public type —
+ * matching the Go adapter's `emitCtx`). The emitter depends on this narrow
+ * interface rather than the full ~2.5k-line class, so the coupling is explicit
+ * and it's unit-testable against a stub.
+ *
+ * Keep this surface minimal: add a member only when an extracted module
+ * genuinely needs it, so the seam documents the real cross-module coupling
+ * rather than re-exposing the whole adapter.
+ */
+
+import type { ParsedExpr, CompilerError, IRMetadata } from '@barefootjs/jsx'
+
+export interface XslateEmitContext {
+  /**
+   * (#1922) Local binding names the request-scoped `searchParams()` env signal
+   * is imported under. Non-empty enables the env-signal method-call lowering.
+   */
+  readonly _searchParamsLocals: Set<string>
+
+  /**
+   * Inline a module-scope pure string-literal const by name as the resolved
+   * literal value, or null when the name is not such a const.
+   */
+  _resolveModuleStringConst(name: string): string | null
+
+  /** Resolve a literal const (`const totalPages = 5`) to its Kolon value, or null. */
+  _resolveLiteralConst(name: string): string | null
+
+  /**
+   * Resolve a static property access on a module object-literal const
+   * (`variantClasses.ghost`) to its Kolon value at compile time, or null.
+   */
+  _resolveStaticRecordLiteral(objectName: string, key: string): string | null
+
+  /** Record a BF101 unsupported-expression diagnostic. */
+  _recordExprBF101(message: string, reason?: string): void
+
+  /** Lower a filter/predicate body to its Kolon form, bound to `param`. */
+  _renderKolonFilterExprPublic(expr: ParsedExpr, param: string): string
+}
+
+/**
+ * The contract the extracted object-literal / conditional-spread lowering
+ * (`spread/spread-codegen.ts`) depends on. The spread lowering recurses into
+ * the core expression lowering and records its own BF101 diagnostics, so it
+ * needs the recursive entry point plus the per-compile bookkeeping the
+ * adapter owns. Declared separately from `XslateEmitContext` so each
+ * extracted module's real coupling is documented precisely.
+ */
+export interface XslateSpreadContext {
+  /** Component name, for diagnostic source locations. */
+  readonly componentName: string
+
+  /** Per-compile diagnostic list the spread lowering appends to. */
+  readonly errors: CompilerError[]
+
+  /** Local-constant metadata, for resolving `Record[key]` spread values. */
+  readonly localConstants: IRMetadata['localConstants']
+
+  /** Prop params, for classifying a bare-identifier index as a prop. */
+  readonly propsParams: { name: string }[]
+
+  /**
+   * Lower a JS expression to its Kolon form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr` — mirrors go-template's
+   * `convertExpressionToGo(jsExpr, out?, preParsed?)`. With `preParsed` set,
+   * `expr` is unused for parsing (the converter derives any diagnostic text
+   * from the tree), so callers may pass `''`.
+   */
+  convertExpressionToKolon(expr: string, preParsed?: ParsedExpr): string
+}
+
+/**
+ * The contract the extracted in-template memo / context seeding
+ * (`memo/seed.ts`) depends on. The seed lowering recurses into the core
+ * expression lowering to compute a derived signal/memo value or a context
+ * default; that recursive entry is its only adapter coupling.
+ */
+export interface XslateMemoContext {
+  /**
+   * Lower a JS expression to its Kolon form (the core recursive entry).
+   *
+   * When the IR already carries a structured `ParsedExpr` tree, pass it as
+   * `preParsed` so the converter threads it straight through instead of
+   * re-parsing `expr` — mirrors go-template's
+   * `convertExpressionToGo(jsExpr, out?, preParsed?)`. With `preParsed` set,
+   * `expr` is unused for parsing (the converter derives any diagnostic text
+   * from the tree), so callers may pass `''`.
+   */
+  convertExpressionToKolon(expr: string, preParsed?: ParsedExpr): string
+}