@barefootjs/jsx 0.17.0 → 0.17.1

package/src/adapters/env-signal.ts

@@ -22,28 +22,76 @@ export const ENV_SIGNAL_CLIENT_FACTORY: Record<string, string> = {
 }
 
 /**
- * The getter name(s) of the `searchParams` env signal in this component.
+ * One env signal's SSR-reader surface — the single place a future env signal
+ * registers itself so the adapter seed / memo paths stay open-closed:
+ * registering a new env signal is an analyzer factory entry + one registry
+ * entry here; adapter seed/memo paths consume the registry and need no edits.
+ */
+export interface EnvSignalReader {
+  /** The analyzer's `envReader` key (`'search'`). */
+  key: string
+  /**
+   * Canonical per-request reader binding every adapter's lowering
+   * canonicalises to (`searchParams` → Perl `$searchParams`, Go
+   * `in.SearchParams` via capitalisation).
+   */
+  canonicalName: string
+  /** Reader method names the SSR lowerings recognise (`.get(key)`). */
+  methods: ReadonlySet<string>
+}
+
+/**
+ * Env-signal key → its {@link EnvSignalReader} descriptor. The open-closed
+ * contract: adding a new env signal is an analyzer factory entry
+ * (`ENV_SIGNAL_FACTORIES`, #2057) + one entry here — the adapter seed / memo
+ * paths consume this registry (via {@link envSignalReaderFor} /
+ * {@link envSignalLocalNames}) and need no edits.
+ */
+export const ENV_SIGNAL_READERS: ReadonlyMap<string, EnvSignalReader> = new Map([
+  ['search', { key: 'search', canonicalName: 'searchParams', methods: new Set(['get']) }],
+])
+
+/** Look up an env signal's reader descriptor by its `envReader` key, or `null` when unregistered/absent. */
+export function envSignalReaderFor(key: string | undefined): EnvSignalReader | null {
+  if (key === undefined) return null
+  return ENV_SIGNAL_READERS.get(key) ?? null
+}
+
+/**
+ * The getter name(s) of env signal(s) in this component, optionally filtered
+ * to one `envReader` key.
  *
- * Recognised **structurally** (#2057): the env signal is now declared as a
+ * Recognised **structurally** (#2057): an env signal is declared as a
  * `createSignal`-shaped `const [searchParams, setSearchParams] =
  * createSearchParams()`, so the analyzer collects it into `metadata.signals`
- * with `envReader: 'search'` — exactly like any other signal, but tagged. This
+ * with `envReader: '<key>'` — exactly like any other signal, but tagged. This
  * function returns those getters (whatever the destructured name is —
  * `searchParams`, or an alias), so adapters match the reader `.get()` call
- * against the binding actually used, with **no `searchParams`-name allow-list**
- * (this supersedes the import-name matching, and the closed #2055).
+ * against the binding actually used, with **no name allow-list** (this
+ * supersedes the import-name matching, and the closed #2055).
  *
- * Empty when the component declares no env signal (the component keeps the
- * generic signal lowering).
+ * With `key` omitted, collects every env signal's getters regardless of
+ * which reader they belong to; with `key` given, only that reader's
+ * (`searchParamsLocalNames` is the `'search'`-filtered convenience below).
+ *
+ * Empty when the component declares no matching env signal (the component
+ * keeps the generic signal lowering).
  */
-export function searchParamsLocalNames(metadata: IRMetadata): Set<string> {
+export function envSignalLocalNames(metadata: IRMetadata, key?: string): Set<string> {
   const names = new Set<string>()
   for (const s of metadata.signals) {
-    if (s.envReader === 'search') names.add(s.getter)
+    if (s.envReader !== undefined && (key === undefined || s.envReader === key)) {
+      names.add(s.getter)
+    }
   }
   return names
 }
 
+/** The getter name(s) of the `searchParams` env signal in this component. See {@link envSignalLocalNames}. */
+export function searchParamsLocalNames(metadata: IRMetadata): Set<string> {
+  return envSignalLocalNames(metadata, 'search')
+}
+
 /**
  * True when the component declares the `searchParams` env signal. Convenience
  * for adapters/harnesses that only need to gate on presence (the lowering

package/src/compiler.ts

@@ -23,6 +23,7 @@ import { generateModuleExports, collectInlineExportedNames } from './module-expo
 import { applyCssLayerPrefix } from './css-layer-prefixer.ts'
 import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.ts'
 import { extractSsrDefaults } from './ssr-defaults.ts'
+import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
 
 /**
  * Extended compile options with required adapter
@@ -482,7 +483,7 @@ function compileMultipleComponents(
 export function buildMetadata(
   ctx: ReturnType<typeof analyzeComponent>,
 ): IRMetadata {
-  return {
+  const metadata: IRMetadata = {
     componentName: ctx.componentName || 'Unknown',
     hasDefaultExport: ctx.hasDefaultExport,
     isExported: ctx.isExported,
@@ -512,6 +513,10 @@ export function buildMetadata(
     localFunctions: ctx.localFunctions,
     localConstants: ctx.localConstants,
   }
+  // Computed from the assembled metadata (not `ctx`): the plan reads the
+  // exact fields adapters see, so the two can never disagree.
+  metadata.ssrSeedPlan = computeSsrSeedPlan(metadata)
+  return metadata
 }
 
 // =============================================================================

package/src/expression-parser.ts

@@ -247,8 +247,12 @@ export interface SupportResult {
 const UNSUPPORTED_METHODS = new Set([
   // Higher-order array methods. Seven of these (`filter`, `every`,
   // `some`, `find`, `findIndex`, `findLast`, `findLastIndex`) are
-  // intercepted as `higher-order` IR before reaching this gate;
-  // `map` is intercepted as an IRLoop. `reduce` / `reduceRight` stay
+  // intercepted as `higher-order` IR before reaching this gate.
+  // `map` is intercepted as an IRLoop when its callback returns JSX,
+  // and as a `CALLBACK_METHODS` evaluator lowering (`map_eval`, #2073)
+  // when it returns a value — it stays listed here so the fall-throughs
+  // (a bare `arr.map` reference, a function-reference callback) still
+  // refuse loudly. `reduce` / `reduceRight` stay
   // listed here so the shapes the Tier C catalogue can't lower still
   // refuse loudly: the `convertNode` call branch intercepts a matching
   // `.reduce(fn, init)` / `.reduceRight(fn, init)` into the structured
@@ -603,11 +607,12 @@ export function tsNodeToParsedExpr(node: ts.Node): ParsedExpr {
  * Higher-order array methods whose callback body the runtime evaluator drives
  * (#2018). Recognised generically as a `call` whose callee is `<recv>.<method>`
  * and whose first argument is an `arrow`; the adapter serializes the arrow body
- * to the evaluator. `map` is excluded — a JSX-returning `.map` is an IRLoop
- * upstream, and a value-returning `.map` has no template lowering.
+ * to the evaluator. A JSX-returning `.map` / `.flatMap` is an IRLoop upstream
+ * and never reaches this recognition; the value-returning `.map(cb)` form
+ * (e.g. `tags.map(t => \`#${t}\`).join(' ')`) lowers via `map_eval` (#2073).
  */
 export const CALLBACK_METHODS: ReadonlySet<string> = new Set([
-  'filter', 'every', 'some', 'find', 'findIndex', 'findLast', 'findLastIndex',
+  'filter', 'map', 'every', 'some', 'find', 'findIndex', 'findLast', 'findLastIndex',
   'sort', 'toSorted', 'reduce', 'reduceRight', 'flatMap',
 ])
 
@@ -2207,8 +2212,12 @@ function checkSupport(expr: ParsedExpr): SupportResult {
       // the receiver and the callback BODY are supported. Recognised before the
       // `UNSUPPORTED_METHODS` gate so the eval-lowered shapes aren't refused
       // (a BARE method reference — `arr.filter` uncalled, no arrow arg — still
-      // falls through to the gate). A nested callback inside the body refuses
-      // at the adapter's `serializeParsedExpr` purity gate, not here.
+      // falls through to the gate). A nested callback inside the body is NOT
+      // refused here: the evaluator refuses it (`serializeParsedExpr` → null)
+      // and each adapter then either lowers it faithfully (Mojo's inline
+      // `grep`, Go's `len (bf_filter_eval …)`) or surfaces BF101 at its
+      // predicate fallback's exact degrade points (#2038) — a blanket refusal
+      // here would break the faithful shapes (#1443 PR4).
       const cb = asCallbackMethodCall(expr)
       if (cb) {
         const objSupport = checkSupport(cb.object)
@@ -3121,6 +3130,82 @@ export function stringifyParsedExpr(expr: ParsedExpr): string {
   }
 }
 
+/**
+ * Rewrite every zero-arg `call` node whose callee is a bare identifier in
+ * `names` into that identifier — `tag()` → `tag` — leaving everything else
+ * untouched. Returns a new tree; the input is never mutated.
+ *
+ * Rationale: in an SSR seed/constructor context a signal/memo getter call
+ * reads the already-computed SEEDED value, so `tag()` reduces to "the value
+ * bound to `tag`". Materialising the call lets the runtime evaluator (which
+ * refuses any non-builtin call, {@link toEvalNode}'s `evalBuiltinCalleeName`
+ * gate) evaluate a predicate that reads sibling memos — e.g. a `.filter`
+ * predicate `(p) => !tag() || p.tags.includes(tag())` — with the getter's
+ * value supplied through the evaluator's `base_env` instead of an
+ * unsupported call node. `names` is caller-supplied (typically the sibling
+ * signals/memos seeded alongside the derived memo being lowered), so a call
+ * to an unrelated function is left as a `call` node and still refused by the
+ * evaluator's builtin gate if it reaches `serializeParsedExpr`.
+ */
+export function materializeGetterCalls(expr: ParsedExpr, names: ReadonlySet<string>): ParsedExpr {
+  const rw = (e: ParsedExpr): ParsedExpr => materializeGetterCalls(e, names)
+  switch (expr.kind) {
+    case 'call':
+      if (
+        expr.args.length === 0 &&
+        expr.callee.kind === 'identifier' &&
+        names.has(expr.callee.name)
+      ) {
+        return { kind: 'identifier', name: expr.callee.name }
+      }
+      return { kind: 'call', callee: rw(expr.callee), args: expr.args.map(rw) }
+    case 'binary':
+      return { kind: 'binary', op: expr.op, left: rw(expr.left), right: rw(expr.right) }
+    case 'logical':
+      return { kind: 'logical', op: expr.op, left: rw(expr.left), right: rw(expr.right) }
+    case 'unary':
+      return { kind: 'unary', op: expr.op, argument: rw(expr.argument) }
+    case 'conditional':
+      return {
+        kind: 'conditional',
+        test: rw(expr.test),
+        consequent: rw(expr.consequent),
+        alternate: rw(expr.alternate),
+      }
+    case 'member':
+      return { kind: 'member', object: rw(expr.object), property: expr.property, computed: expr.computed }
+    case 'index-access':
+      return { kind: 'index-access', object: rw(expr.object), index: rw(expr.index) }
+    case 'template-literal':
+      return {
+        kind: 'template-literal',
+        parts: expr.parts.map(p => (p.type === 'string' ? p : { type: 'expression', expr: rw(p.expr) })),
+      }
+    case 'array-literal':
+      return { kind: 'array-literal', elements: expr.elements.map(rw) }
+    case 'array-method':
+      // `flat`'s `args` is always `[]` (the depth is carried structurally in
+      // `flatDepth`, not `args`) — still rewrite `object`, just skip the
+      // `args.map` that every other method needs.
+      if (expr.method === 'flat') return { ...expr, object: rw(expr.object) }
+      return { ...expr, object: rw(expr.object), args: expr.args.map(rw) }
+    case 'object-literal':
+      return {
+        kind: 'object-literal',
+        raw: expr.raw,
+        properties: expr.properties.map(p => ({ ...p, value: rw(p.value) })),
+      }
+    case 'arrow':
+      return { kind: 'arrow', params: expr.params, body: rw(expr.body) }
+    // Leaves / opaque shapes — nothing to rewrite.
+    case 'identifier':
+    case 'literal':
+    case 'regex':
+    case 'unsupported':
+      return expr
+  }
+}
+
 /**
  * Serialize a pure-expression `ParsedExpr` (a higher-order callback body) into
  * the minimal JSON the runtime evaluator consumes — the format pinned by the
@@ -3201,10 +3286,20 @@ export function freeVarsInBody(body: ParsedExpr, params: ReadonlySet<string>): s
         // carries the ref on its `value` identifier, which is visited here.)
         for (const p of e.properties) visit(p.value)
         return
+      case 'array-method':
+        // Only `.includes(x)` is serializable ({@link toEvalNode}); its
+        // `object` (the receiver) and `args` (the needle) are the value
+        // positions serialized, so visit both when the tree reaches here
+        // with that method. Every other `array-method` is non-serializable
+        // and doesn't occur in a serializable body.
+        if (e.method === 'includes') {
+          visit(e.object)
+          e.args.forEach(visit)
+        }
+        return
       // Non-serializable kinds don't occur in a serializable body
       // (serializeParsedExpr returns null for them); nothing to collect.
       case 'literal':
-      case 'array-method':
       case 'arrow':
       case 'regex':
       case 'unsupported':
@@ -3215,6 +3310,87 @@ export function freeVarsInBody(body: ParsedExpr, params: ReadonlySet<string>): s
   return [...found].sort()
 }
 
+/**
+ * Every value-position identifier in `expr` NOT bound by an enclosing arrow's
+ * own parameters — with proper lexical scoping: an arrow's params bind only
+ * within that arrow's body, and nested arrows accumulate onto the enclosing
+ * bound set. Unlike {@link freeVarsInBody} (which assumes a single flat param
+ * set and never recurses into nested `arrow` nodes, since a serializable
+ * evaluator body never contains one), this walks the full source-level tree —
+ * including arrows — so a caller can ask "is this name free ANYWHERE in the
+ * expression, honoring each arrow's own scope" rather than only within one
+ * callback body.
+ *
+ * Walks the same value positions as {@link serializeParsedExpr} /
+ * {@link freeVarsInBody}: call callee (skipped when it resolves to an
+ * evaluator builtin — see {@link evalBuiltinCalleeName} — so `Math.floor(x)`
+ * doesn't report `Math` as free) + args, binary/logical/unary operands,
+ * conditional branches, a member's OBJECT only (the property name is not a
+ * reference), an index-access's object + index, template-literal expression
+ * parts, array-literal elements, array-method object + args, and an
+ * object-literal's property VALUES (not keys). An `arrow` recurses into its
+ * body with its own params added to the bound set.
+ *
+ * Returns `null` when the tree contains an `unsupported` node (or any other
+ * shape this walk can't analyze) — the caller must fail safe rather than
+ * assume nothing is free.
+ */
+export function freeIdentifiers(expr: ParsedExpr): Set<string> | null {
+  const free = new Set<string>()
+
+  function visit(e: ParsedExpr, bound: ReadonlySet<string>): boolean {
+    switch (e.kind) {
+      case 'literal':
+      case 'regex':
+        return true
+      case 'identifier':
+        if (!bound.has(e.name)) free.add(e.name)
+        return true
+      case 'call': {
+        const isBuiltinCallee = evalBuiltinCalleeName(e.callee) !== null
+        if (!isBuiltinCallee && !visit(e.callee, bound)) return false
+        for (const a of e.args) if (!visit(a, bound)) return false
+        return true
+      }
+      case 'member':
+        return visit(e.object, bound)
+      case 'index-access':
+        return visit(e.object, bound) && visit(e.index, bound)
+      case 'binary':
+      case 'logical':
+        return visit(e.left, bound) && visit(e.right, bound)
+      case 'unary':
+        return visit(e.argument, bound)
+      case 'conditional':
+        return visit(e.test, bound) && visit(e.consequent, bound) && visit(e.alternate, bound)
+      case 'template-literal':
+        for (const p of e.parts) {
+          if (p.type === 'expression' && !visit(p.expr, bound)) return false
+        }
+        return true
+      case 'array-literal':
+        for (const el of e.elements) if (!visit(el, bound)) return false
+        return true
+      case 'array-method':
+        if (!visit(e.object, bound)) return false
+        for (const a of e.args) if (!visit(a, bound)) return false
+        return true
+      case 'object-literal':
+        for (const p of e.properties) if (!visit(p.value, bound)) return false
+        return true
+      case 'arrow': {
+        const inner = new Set(bound)
+        for (const p of e.params) inner.add(p)
+        return visit(e.body, inner)
+      }
+      case 'unsupported':
+        return false
+    }
+  }
+
+  return visit(expr, new Set()) ? free : null
+}
+
 // Operators the evaluator implements (Go `eval.go` evalBinary / evalUnary, Perl
 // `Evaluator.pm` _binary / _unary). An op outside these sets — loose `==`,
 // `instanceof`, `**`, bitwise/shift, or the parser's `'unknown'` sentinel — is
@@ -3346,10 +3522,24 @@ function toEvalNode(e: ParsedExpr): Record<string, unknown> | null {
       }
       return { kind: 'object-literal', properties }
     }
+    case 'array-method': {
+      // `.includes(x)` is the one `array-method` the evaluator executes
+      // (Go `eval.go` / Perl `Evaluator.pm`, includes support): the
+      // receiver-type dispatch (array SameValueZero membership vs string
+      // substring) happens at evaluator runtime, same as the SSR template
+      // lowering's `bf_includes` / `$bf->includes`. Every other
+      // `array-method` (`join`, `slice`, `flat`, …) is outside the
+      // evaluator's surface and refuses below.
+      if (e.method === 'includes' && e.args.length === 1) {
+        const object = toEvalNode(e.object)
+        const arg = toEvalNode(e.args[0])
+        return object && arg ? { kind: 'array-method', method: 'includes', object, args: [arg] } : null
+      }
+      return null
+    }
     // Outside the evaluator's pure-expression surface — refuse so the caller
     // falls back to BF101 / `@client`. A nested `arrow` (a callback inside the
     // body) is refused here, keeping the evaluator non-recursive.
-    case 'array-method':
     case 'arrow':
     case 'regex':
     case 'unsupported':

package/src/index.ts

@@ -12,6 +12,10 @@ export type { CompileResult, CompileOptions, CompileOptionsWithAdapter, FileOutp
 export { extractSsrDefaults } from './ssr-defaults.ts'
 export type { SsrDefault } from './ssr-defaults.ts'
 
+// Backend-neutral SSR seed plan (in-template derived signal/memo seeding)
+export { computeSsrSeedPlan } from './ssr-seed-plan.ts'
+export type { SsrSeedPlan, SsrSeedStep } from './ssr-seed-plan.ts'
+
 // Pure IR types
 export type {
   ComponentIR,
@@ -77,7 +81,8 @@ export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate } from './adapters/template-imports.ts'
 export { emitParsedExpr } from './adapters/parsed-expr-emitter.ts'
 export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
-export { importsSearchParams, searchParamsLocalNames, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export { importsSearchParams, searchParamsLocalNames, envSignalLocalNames, envSignalReaderFor, ENV_SIGNAL_READERS, queryHrefLocalNames, matchSearchParamsMethodCall } from './adapters/env-signal.ts'
+export type { EnvSignalReader } from './adapters/env-signal.ts'
 export { matchQueryHrefCall, queryHrefArgs, type QueryHrefCall, type QueryHrefTriple } from './query-href-lowering.ts'
 export {
   registerLoweringPlugin,
@@ -276,7 +281,7 @@ export {
 export { ErrorCodes, createError, formatError, generateCodeFrame } from './errors.ts'
 
 // Expression Parser
-export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
+export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, freeIdentifiers, materializeGetterCalls, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'
 export type { ParsedExpr, ObjectLiteralProperty, ParsedStatement, SortComparator, SortKey, FlatDepth, SupportLevel, SupportResult, TemplatePart } from './expression-parser.ts'
 export { buildLoopChainExpr } from './loop-chain.ts'

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

@@ -5,6 +5,7 @@
  */
 
 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()`
@@ -1526,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
 }
 
 // =============================================================================