@barefootjs/jsx 0.16.0 → 0.17.1

package/src/query-href-lowering.ts

@@ -0,0 +1,147 @@
+/**
+ * Backend-neutral destructuring of a recognised `queryHref(base, { … })` call
+ * (#2042) into a base expression plus include triples, shared by the SSR
+ * adapters' query lowering.
+ *
+ * `queryHref` is the pure functional URL-query builder (the counterpart to
+ * `searchParams()`); its call + object literal are already structured IR, so an
+ * adapter lowers it to its query helper without any block-body recognition or
+ * re-parse. This module only does the structural match — turning the object
+ * literal's properties into `{ guard, key, value }` triples — leaving each
+ * adapter to format the include condition and the helper call in its own
+ * template language.
+ *
+ * Inclusion is truthy-omit over string values (matching the client `queryHref`'s
+ * `if (value)`): a plain `key: v` is included iff `v` is a non-empty string
+ * (`guard: null`); a conditional `key: cond ? a : <undefined|null|''>` is
+ * included iff `cond` AND `a` is non-empty (`guard: cond`, `value: a`).
+ */
+
+import type { ParsedExpr } from './expression-parser.ts'
+
+export interface QueryHrefTriple {
+  /**
+   * The conditional test of a `key: cond ? a : <omit>` include, or null for a
+   * plain `key: v` (which is included purely on value-truthiness). An adapter
+   * combines this with the value's non-emptiness to form the include condition.
+   */
+  guard: ParsedExpr | null
+  /** The literal search-param key. */
+  key: string
+  /** The value expression (the consequent for a conditional include). */
+  value: ParsedExpr
+}
+
+export interface QueryHrefCall {
+  base: ParsedExpr
+  triples: QueryHrefTriple[]
+}
+
+/**
+ * Match a `queryHref(base, { … })` call from its callee + args, returning the
+ * base and include triples, or null when it isn't a `queryHref` call with a
+ * plain object-literal second argument (→ the adapter falls back to its generic
+ * lowering). `localNames` are the bindings `queryHref` is imported under (from
+ * `queryHrefLocalNames`).
+ */
+export function matchQueryHrefCall(
+  callee: ParsedExpr,
+  args: readonly ParsedExpr[],
+  localNames: ReadonlySet<string>,
+): QueryHrefCall | null {
+  if (callee.kind !== 'identifier' || !localNames.has(callee.name)) return null
+  if (args.length !== 2) return null
+  const [base, obj] = args
+  // A dynamic (non-literal) params object can't be lowered to static include
+  // triples — fall back to the generic lowering.
+  if (obj.kind !== 'object-literal') return null
+
+  const triples: QueryHrefTriple[] = []
+  for (const p of obj.properties) {
+    const v = p.value
+    if (v.kind === 'conditional' && isOmitBranch(v.alternate)) {
+      triples.push({ guard: v.test, key: p.key, value: v.consequent })
+    } else {
+      triples.push({ guard: null, key: p.key, value: v })
+    }
+  }
+  return { base, triples }
+}
+
+/**
+ * Format a {@link QueryHrefCall} as the flat argument list for a guard-list
+ * query helper (`bf->query(base, guard, key, value, …)` in Mojo / `$bf.query(…)`
+ * in Xslate — the two adapters whose helper does the non-empty check itself).
+ * Each triple contributes a guard (`'1'` for a plain include, or the lowered
+ * condition for a conditional one), the key as a string literal, and the value —
+ * all lowered through the adapter's `emit`. The caller wraps the result in its
+ * own `<helper>(…)` call. (The go-template adapter folds the non-empty check
+ * into the include condition itself, so it formats its own form instead.)
+ *
+ * A conditional guard that is NOT already boolean-shaped (a bare value, a member
+ * access, `&&`/`||`) is JS *string* truthiness — `'0'` is a truthy string in JS
+ * but false under Perl's `unless`. To keep SSR byte-identical to the client (and
+ * to the go adapter, whose `lowerUrlGuard` does the same), such a guard is
+ * normalised to a `guard !== ''` test, emitted against a string literal so each
+ * adapter renders string `ne`, not numeric `!=`. Comparisons / `!x` / boolean
+ * literals already yield a real boolean and pass through unchanged.
+ */
+export function queryHrefArgs(q: QueryHrefCall, emit: (e: ParsedExpr) => string): string[] {
+  const out = [emit(q.base)]
+  for (const t of q.triples) {
+    if (t.guard === null) {
+      out.push('1')
+    } else if (isBoolShapeGuard(t.guard)) {
+      out.push(`(${emit(t.guard)})`)
+    } else {
+      const test: ParsedExpr = {
+        kind: 'binary',
+        op: '!==',
+        left: t.guard,
+        right: { kind: 'literal', value: '', literalType: 'string' },
+      }
+      out.push(`(${emit(test)})`)
+    }
+    out.push(emit({ kind: 'literal', value: t.key, literalType: 'string' }))
+    out.push(emit(t.value))
+  }
+  return out
+}
+
+const GUARD_BOOL_OPS: ReadonlySet<string> = new Set([
+  '==',
+  '===',
+  '!=',
+  '!==',
+  '<',
+  '>',
+  '<=',
+  '>=',
+])
+
+/**
+ * Whether a conditional-include guard already evaluates to a real boolean, so it
+ * can be emitted as-is rather than wrapped in a `!== ''` string-truthiness test.
+ * A comparison, a `!negation`, or a boolean literal qualifies; a bare value /
+ * member / `&&` / `||` does not. Mirrors the go adapter's `lowerUrlGuard`
+ * `isBoolShape` so the four backends agree on which guards need normalising.
+ */
+function isBoolShapeGuard(g: ParsedExpr): boolean {
+  return (
+    (g.kind === 'binary' && GUARD_BOOL_OPS.has(g.op)) ||
+    (g.kind === 'unary' && g.op === '!') ||
+    (g.kind === 'literal' && g.literalType === 'boolean')
+  )
+}
+
+/**
+ * The falsy "omit" branch of a conditional include — `undefined` (an identifier),
+ * `null`, or `''` — which makes `cond ? v : <omit>` a conditional include.
+ */
+function isOmitBranch(node: ParsedExpr): boolean {
+  if (node.kind === 'identifier') return node.name === 'undefined'
+  if (node.kind === 'literal') {
+    return node.literalType === 'null' || (node.literalType === 'string' && node.value === '')
+  }
+  return false
+}

package/src/ssr-defaults.ts

@@ -143,6 +143,10 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
   }
   for (const sig of metadata.signals) {
     if (!sig.getter || sig.isModule) continue
+    // Env signals (#2057) have no static SSR default — their value is the
+    // request-scoped reader, seeded by the adapter's env-signal binding, not a
+    // baked initial value.
+    if (sig.envReader) continue
     const value = tryStaticEval(sig.initialValue, { bindings, propsLike })
     out[sig.getter] = { value: resultToJsonable(value) }
     bindings[sig.getter] = value
@@ -169,7 +173,7 @@ export function extractSsrDefaults(metadata: IRMetadata): Record<string, SsrDefa
   if (metadata.propsObjectName !== null) {
     const referenced = new Set<string>()
     for (const sig of metadata.signals) {
-      if (!sig.getter || sig.isModule) continue
+      if (!sig.getter || sig.isModule || sig.envReader) continue
       collectPropRefs(sig.initialValue, metadata.propsObjectName, referenced)
     }
     for (const memo of metadata.memos) {

package/src/ssr-seed-plan.ts

@@ -0,0 +1,146 @@
+/**
+ * Backend-neutral SSR seed plan — which signals/memos an adapter may seed
+ * in-template at SSR time, and from what scope.
+ *
+ * Design principle: the IR/analyzer side ANALYZES and attaches structured
+ * information; adapters only EMIT. The "is this binding derivable from names
+ * already in template scope" decision used to live (triplicated) in the
+ * template adapters' seed paths; this module computes it once, on the IR, so
+ * every adapter consumes the same plan and only supplies its own syntax.
+ *
+ * Ordering / acyclicity guarantee: `steps` lists the component's signals
+ * first, then its memos, each group in declaration order (matching
+ * `IRMetadata.signals` / `IRMetadata.memos`). A binding's name only enters
+ * the scope set AFTER its own step is decided, so a `derived` step's `frees`
+ * can only name `baseScope` entries or EARLIER steps — self- and
+ * forward-references are rejected by construction, and a consumer emitting
+ * the steps top-to-bottom never reads an undeclared local.
+ *
+ * Module-scope pure-string consts count as in-scope (they are part of
+ * `baseScope`) because every adapter compile-time-inlines them to their
+ * literal value — `collectModuleStringConsts` is the shared source of that
+ * set — so a reference to one is never a template-variable read.
+ *
+ * A `derived` step with EMPTY `frees` is a constant expression (e.g.
+ * `createSignal('b')`): the plan still classifies it as derived because the
+ * expression is fully analyzable; emit-side constant-skipping (adapters keep
+ * their existing ssr-defaults seeding for such inits) is an adapter concern,
+ * not a plan concern. Likewise the plan makes no backend-specific choices —
+ * no target-variable checks, no self-shadowing rules, no per-backend shape
+ * catalogs — those stay in the adapters.
+ */
+
+import { collectModuleStringConsts } from './augment-inherited-props.ts'
+import { envSignalReaderFor, type EnvSignalReader } from './adapters/env-signal.ts'
+import {
+  extractArrowBodyExpression,
+  freeIdentifiers,
+  isSupported,
+  parseExpression,
+  type ParsedExpr,
+} from './expression-parser.ts'
+import type { IRMetadata } from './types.ts'
+
+/**
+ * One binding in component declaration order (signals first, then memos —
+ * matching `IRMetadata` order and the adapters' iteration).
+ *
+ * - `env-reader`: an env signal whose `envReader` key resolves in the shared
+ *   registry (`envSignalReaderFor`). The runtime provides the per-request
+ *   reader, so there is nothing to seed; the name still enters scope so a
+ *   later derived step may reference it. An `envReader` key UNKNOWN to the
+ *   registry falls through to the normal derived/opaque rules instead.
+ * - `derived`: the binding's value expression is a supported shape whose free
+ *   identifiers are all in scope at this point (baseScope + earlier steps) —
+ *   an adapter may seed it in-template by lowering `parsed`/`expr`.
+ * - `opaque`: not seedable this way (empty init, unsupported shape,
+ *   unanalyzable free set, out-of-scope reference, or a block-bodied memo).
+ *   The name still enters scope for later steps; adapters keep their static
+ *   ssr-defaults seeding for it.
+ */
+export type SsrSeedStep =
+  | { kind: 'env-reader'; name: string; reader: EnvSignalReader }
+  | { kind: 'derived'; name: string; origin: 'signal' | 'memo'; expr: string; parsed: ParsedExpr; frees: string[] }
+  | { kind: 'opaque'; name: string; origin: 'signal' | 'memo' }
+
+export interface SsrSeedPlan {
+  /**
+   * Names in scope before any step: props params, the props-object name
+   * (when the component takes an undestructured props object), and module
+   * pure-string consts (compile-time inlined by every adapter).
+   */
+  baseScope: string[]
+  steps: SsrSeedStep[]
+}
+
+/**
+ * Classify one value expression against the current scope: `derived` when it
+ * parses to a supported shape whose free identifiers are all `available`
+ * (an unanalyzable free set — `freeIdentifiers` → null — fails safe to
+ * opaque). The scope check runs over the parsed SOURCE tree, so a shadowed
+ * name (`items.filter((p) => p.ok) && p`, where the trailing `p` is a
+ * different, unbound reference from the callback's own param) is rejected.
+ */
+function classify(
+  name: string,
+  origin: 'signal' | 'memo',
+  expr: string,
+  parsed: ParsedExpr,
+  available: ReadonlySet<string>,
+): SsrSeedStep {
+  if (!isSupported(parsed).supported) return { kind: 'opaque', name, origin }
+  const frees = freeIdentifiers(parsed)
+  if (frees === null) return { kind: 'opaque', name, origin }
+  for (const free of frees) {
+    if (!available.has(free)) return { kind: 'opaque', name, origin }
+  }
+  return { kind: 'derived', name, origin, expr, parsed, frees: [...frees] }
+}
+
+/**
+ * Compute the component's SSR seed plan from its metadata. See the module
+ * doc for the contract. Memo steps are gated to EXPRESSION-BODIED memos
+ * (`extractArrowBodyExpression` returns the body): a block-bodied memo is
+ * `opaque` even when the analyzer folded it to a `parsed` expression.
+ */
+export function computeSsrSeedPlan(metadata: IRMetadata): SsrSeedPlan {
+  const baseScope: string[] = metadata.propsParams.map(p => p.name)
+  if (metadata.propsObjectName) baseScope.push(metadata.propsObjectName)
+  for (const name of collectModuleStringConsts(metadata.localConstants).keys()) {
+    baseScope.push(name)
+  }
+
+  const available = new Set<string>(baseScope)
+  const steps: SsrSeedStep[] = []
+
+  for (const signal of metadata.signals) {
+    if (signal.envReader) {
+      const reader = envSignalReaderFor(signal.envReader)
+      if (reader) {
+        steps.push({ kind: 'env-reader', name: signal.getter, reader })
+        available.add(signal.getter)
+        continue
+      }
+    }
+    const expr = signal.initialValue.trim()
+    steps.push(
+      expr === ''
+        ? { kind: 'opaque', name: signal.getter, origin: 'signal' }
+        : classify(signal.getter, 'signal', expr, parseExpression(expr), available),
+    )
+    available.add(signal.getter)
+  }
+
+  for (const memo of metadata.memos) {
+    const body = extractArrowBodyExpression(memo.computation)
+    const expr = body?.trim() ?? ''
+    steps.push(
+      expr === ''
+        ? { kind: 'opaque', name: memo.name, origin: 'memo' }
+        : classify(memo.name, 'memo', expr, memo.parsed ?? parseExpression(expr), available),
+    )
+    available.add(memo.name)
+  }
+
+  return { baseScope, steps }
+}

package/src/types.ts

@@ -4,7 +4,26 @@
  * JSX-independent intermediate representation for multi-backend support.
  */
 
-import type { ParsedExpr, ParsedStatement, SortComparator } from './expression-parser.ts'
+import type { ParsedExpr, ParsedStatement } from './expression-parser.ts'
+import type { SsrSeedPlan } from './ssr-seed-plan.ts'
+
+/**
+ * Loop-hoisted sort comparator for the `.sort().map()` / `.toSorted().map()`
+ * pattern (#2018 P5). Carries the generic comparator `arrow` (params + body)
+ * that the SSR adapter serializes to the runtime evaluator (eval-first) or, for
+ * a `localeCompare` comparator the evaluator can't model, recovers a structured
+ * comparator from via `sortComparatorFromArrow`. The `paramA` / `paramB` / `raw`
+ * fields round-trip the comparator to native JS for the client / CSR path
+ * (`(paramA, paramB) => raw`), so the client is untouched.
+ */
+export type IRLoopSort = {
+  // Always the comparator arrow itself — narrowed so consumers read
+  // `.params` / `.body` without a defensive `kind` check or non-null assertion.
+  arrow: Extract<ParsedExpr, { kind: 'arrow' }>
+  paramA: string
+  paramB: string
+  raw: string
+}
 
 // =============================================================================
 // Source Location (for Error Reporting)
@@ -323,6 +342,20 @@ export interface IRExpression {
   expr: string
   /** Pre-transformed expr with destructured prop refs rewritten to _p.xxx (for client JS templates). */
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached once
+   * during IR construction so SSR adapters emit from the tree instead of each
+   * re-parsing the string at emit time (and so a multi-adapter build parses it
+   * once, not per adapter). Plain serializable data.
+   *
+   * OPTIONAL by design — consumers MUST fall back to parsing `expr` when it is
+   * missing. It is absent for an empty/whitespace `expr`, and may also be
+   * absent for a node the IR-build walk doesn't reach (the walk is best-effort;
+   * under-coverage is a missed optimization, never a behavioural change). When
+   * present, an unparsable expression is a `{ kind: 'unsupported' }` node (the
+   * adapter's own support gate handles it).
+   */
+  parsed?: ParsedExpr
   typeInfo: TypeInfo | null
   reactive: boolean
   slotId: string | null
@@ -347,6 +380,13 @@ export interface IRConditional {
   condition: string
   /** Pre-transformed condition with destructured prop refs rewritten to _p.xxx. */
   templateCondition?: string
+  /**
+   * Structured parse of `condition` (`parseExpression(condition.trim())`),
+   * attached during IR construction so adapters lower the condition from the
+   * tree instead of re-parsing the string. Optional/best-effort — see
+   * `IRExpression.parsed`; consumers fall back to parsing `condition`.
+   */
+  parsedCondition?: ParsedExpr
   conditionType: TypeInfo | null
   reactive: boolean
   whenTrue: IRNode
@@ -404,6 +444,14 @@ export interface IRLoop {
    */
   method?: 'flatMap'
   array: string
+  /**
+   * Structured parse of `array` (`parseExpression(array.trim())`), attached
+   * during IR construction so adapters lower the loop's array from the tree
+   * instead of re-parsing the string (e.g. the Go adapter's scalar-literal
+   * loop typing). Optional/best-effort — mirrors `IRExpression.parsed`;
+   * consumers fall back to parsing `array`.
+   */
+  arrayParsed?: ParsedExpr
   /** Pre-transformed array expr with destructured prop refs rewritten to _p.xxx. */
   templateArray?: string
   arrayType: TypeInfo | null
@@ -471,14 +519,16 @@ export interface IRLoop {
    * When present, the loop renders with an if-condition wrapping each iteration.
    * Example: todos.filter(t => !t.done).map(...) stores { param: 't', predicate: ParsedExpr, raw: '!t.done' }
    *
-   * For block-body filters like:
+   * Block-body filters like
    *   filter(t => { const f = filter(); if (f === 'active') return !t.done; return true })
-   * The blockBody field contains the parsed statements.
+   * are normalized to a single boolean `predicate` expression at IR-build time
+   * (#2040, `foldBlockToExpr` + `predicateTernaryToLogical` in `jsx-to-ir`), so
+   * adapters only ever see the unified expression form — there is no separate
+   * block-statement shape to lower.
    */
   filterPredicate?: {
     param: string
-    predicate?: ParsedExpr        // Expression body
-    blockBody?: ParsedStatement[] // Block body (mutually exclusive with predicate)
+    predicate?: ParsedExpr        // Boolean predicate expression (folded from any block body)
     raw: string  // Original string for error messages
   }
 
@@ -487,14 +537,14 @@ export interface IRLoop {
    * When present, the loop array is sorted before iteration.
    * Example: todos.sort((a, b) => a.priority - b.priority).map(...)
    *
-   * The structured shape carries enough info for both adapters to
-   * emit the same `bf_sort` / `bf->sort` call (`SortComparator` is
-   * defined in `expression-parser.ts` because the standalone
-   * `array-method` IR variant uses the same type). The loop-hoist
-   * path lifts a comparator off a sibling `array-method` node
-   * during `jsx-to-ir.ts` chain detection — see `extractSortComparator`.
+   * The {@link IRLoopSort} struct carries the generic comparator `arrow`
+   * (params + body) the SSR adapter serializes to the runtime evaluator
+   * (eval-first; `sortComparatorFromArrow` fallback for `localeCompare`), plus
+   * the param names + raw body for the client JS round-trip. Lifted off the
+   * `.sort()` callback during `jsx-to-ir.ts` chain detection — see
+   * `extractSortComparator`. (#2018 P5)
    */
-  sortComparator?: SortComparator
+  sortComparator?: IRLoopSort
 
   /**
    * When both filter and sort are chained, indicates the order of operations.
@@ -746,6 +796,13 @@ export interface IRIfStatement {
   condition: string
   /** Pre-transformed condition with destructured prop refs rewritten to _p.xxx. */
   templateCondition?: string
+  /**
+   * Structured parse of `condition` (`parseExpression(condition.trim())`),
+   * attached during IR construction so adapters lower the condition from the
+   * tree instead of re-parsing the string. Optional/best-effort — see
+   * `IRExpression.parsed`; consumers fall back to parsing `condition`.
+   */
+  parsedCondition?: ParsedExpr
   /** The JSX return in the then branch */
   consequent: IRNode
   /** The else branch: either another IRIfStatement (else if) or IRNode (final else) */
@@ -839,6 +896,14 @@ export interface ExpressionAttr {
   /** `expr` with destructured prop refs rewritten to `_p.xxx`, for SSR
    *  template inlining. Absent when no rewrite was needed. */
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached
+   * during IR construction so adapters lower the attribute value from the tree
+   * instead of re-parsing the string (often several times per attribute).
+   * Optional/best-effort — see `IRExpression.parsed`; consumers fall back to
+   * parsing `expr`.
+   */
+  parsed?: ParsedExpr
   /** Set when the producer peeled an `expr || undefined` boolean-presence
    *  pattern; adapters fold this back into `(expr) || undefined` at emit. */
   presenceOrUndefined?: boolean
@@ -873,6 +938,16 @@ export interface SpreadAttr {
   kind: 'spread'
   expr: string
   templateExpr?: string
+  /**
+   * Structured parse of `expr` (`parseExpression(expr.trim())`), attached
+   * during IR construction so adapters lower the spread bag from the tree
+   * instead of re-parsing the string with `ts.createSourceFile`. Optional /
+   * best-effort — mirrors `ExpressionAttr.parsed`: it may be absent (a node the
+   * attach walk misses, or an empty `expr`), and parsing may yield
+   * `{ kind: 'unsupported' }`, which adapters treat as unlowerable and handle
+   * via their existing non-conditional spread paths (or BF101).
+   */
+  parsed?: ParsedExpr
   /**
    * Component-scoped, stable slot ID assigned at IR-build time for
    * adapters that need to plumb the spread bag through a structured
@@ -1039,6 +1114,14 @@ export interface SignalInfo {
   getter: string
   setter: string | null
   initialValue: string
+  /**
+   * `initialValue` parsed into a structured tree (Roadmap A). Attached
+   * best-effort by the analyzer so adapters can lower a literal initial value
+   * (e.g. `useState(['a', 'b'])`) from structure instead of re-parsing the
+   * string with `ts.createSourceFile`. Absent when the shape isn't supported;
+   * consumers fall back to parsing `initialValue`.
+   */
+  parsed?: ParsedExpr
   /** Initial value with TypeScript type annotations preserved, for .tsx output */
   typedInitialValue?: string
   type: TypeInfo
@@ -1075,6 +1158,26 @@ export interface SignalInfo {
   isModule?: boolean
   /** When true, the declaration carries an `export` keyword. */
   isExported?: boolean
+  /**
+   * Request-scoped environment-signal key when this signal was produced by an
+   * env-signal factory (`createSearchParams()` → `'search'`), rather than by
+   * `createSignal`. Set structurally by the analyzer (#2057) — the getter is a
+   * normal reactive getter (so it lands in the fold purity oracle for free, no
+   * name allow-list), but its *value* is a request-scoped reader with methods
+   * (`.get(key)`), which adapters lower to their per-request reader object
+   * instead of a plain template field. This flag is how adapters recognise an
+   * env signal from structure instead of matching the import name.
+   */
+  envReader?: string
+  /**
+   * For an env signal (`envReader` set), the exact callee text of its factory
+   * call as written — `'createSearchParams'`, an alias (`'csp'` for
+   * `import { createSearchParams as csp }`), or a namespace access
+   * (`'bf.createSearchParams'`). Backends that re-emit the declaration (client
+   * JS, JSX/Hono SSR) emit `<envFactory>()` so the call resolves to the binding
+   * actually in scope, not a hardcoded canonical name (#2057).
+   */
+  envFactory?: string
 }
 
 export interface MemoInfo {
@@ -1082,6 +1185,52 @@ export interface MemoInfo {
   computation: string
   /** Computation with TypeScript type annotations preserved, for .tsx output */
   typedComputation?: string
+  /**
+   * Structured parse of the memo's BODY as a single value expression, computed
+   * once at analysis time. Lets adapters pattern-match the memo's shape on the
+   * structured tree instead of re-parsing `computation` with their own AST walks
+   * / regexes.
+   *
+   * Set for an expression-bodied arrow (`() => <body>`) whose body
+   * `parseExpression` supports, AND — since #2040 — for a block-bodied memo
+   * (`() => { … }`) whose statements `foldBlockToExpr` can normalize to one
+   * expression (`let`-inline + value `if` / early `return` → ternary). A block
+   * the fold refuses (imperative residue) or a shape `parseExpression` can't
+   * represent leaves `parsed` undefined, so consumers must still fall back to
+   * `parsedBlock` / `computation` when it's missing. NOTE: a present `parsed`
+   * therefore no longer implies an expression-bodied arrow.
+   */
+  parsed?: ParsedExpr
+  /**
+   * Whether the memo's effective body is a template literal (`() => `…`` or a
+   * block body whose first `return` is one), classified once at analysis time
+   * from the real arrow AST. Lets the Go adapter pick the `string` field type
+   * without re-parsing `computation` with `ts.createSourceFile`. A template
+   * literal — including a no-substitution `` `plain` `` — folds to a plain
+   * string `ParsedExpr` literal, losing the backtick distinction, so this is a
+   * dedicated flag rather than a `parsed.kind` check.
+   */
+  bodyIsTemplateLiteral?: boolean
+  /**
+   * A block-bodied memo's statements, parsed best-effort (tolerant: a statement
+   * the parser can't represent is omitted). Lets the Go adapter pattern-match
+   * block-body memo shapes — e.g. the `const k = getter(); if (!k) return CONST`
+   * guard — on the structured statements instead of re-parsing `computation`
+   * with `ts.createSourceFile`. Absent for expression-bodied memos (those carry
+   * `parsed` instead) and when the arrow has no block body.
+   */
+  parsedBlock?: ParsedStatement[]
+  /**
+   * Whether {@link parsedBlock} represents EVERY statement of the block (true)
+   * or the tolerant parser omitted at least one it couldn't represent (false).
+   * A consumer that must reason about the whole block — e.g. one that bails on
+   * any statement it doesn't recognise (the template-literal memo lowering) —
+   * reads this and falls back when it's `false`, since omitted statements are
+   * otherwise invisible. Consumers that scan for a recognised prefix and ignore
+   * the rest (the guard-and-return-const lowering) can disregard it. Only set
+   * when `parsedBlock` is.
+   */
+  parsedBlockComplete?: boolean
   type: TypeInfo
   deps: string[]
   loc: SourceLocation
@@ -1282,6 +1431,17 @@ export interface FunctionInfo {
 export interface ConstantInfo {
   name: string
   value?: string
+  /**
+   * `value` parsed into a structured tree (Roadmap A). Attached best-effort by
+   * the analyzer (parsed from the parenthesised value so a bare object literal
+   * — which TS reads as a block at statement position — resolves to an
+   * `object-literal` rather than failing). Lets adapters lower a constant value
+   * (e.g. a module-scope record's `{ … }`) from structure instead of
+   * re-parsing the string with `ts.createSourceFile`. Absent when the constant
+   * has no `value` string (e.g. an inlined-JSX const) or when the analyzer
+   * couldn't structure it (best-effort — consumers fall back to the string).
+   */
+  parsed?: ParsedExpr
   /** Value with TypeScript type annotations preserved, for .tsx output */
   typedValue?: string
   valueBranches?: string[]
@@ -1367,6 +1527,16 @@ export interface IRMetadata {
    * resolves the compiled module rather than the source `.tsx`.
    */
   clientSignalImportSources?: Set<string>
+  /**
+   * Backend-neutral SSR seed plan: per-binding derived/opaque/env-reader
+   * classification in declaration order, plus the base scope, computed by
+   * `computeSsrSeedPlan` from this metadata. Attached by `buildMetadata` and
+   * serialized into IR JSON like the rest of the metadata; template adapters
+   * consume it instead of re-deriving scope/derivability themselves (their
+   * target-syntax choices — lowering, self-shadow rules, constant-emit
+   * guards — stay adapter-side).
+   */
+  ssrSeedPlan?: SsrSeedPlan
 }
 
 // =============================================================================