@reactra/language-tools 0.1.0-alpha.0

package/dist/shadow/emitter.js

@@ -0,0 +1,871 @@
+// Shadow emitter — reactra2tsx lowering for the Reactra DSL v2.
+// Per plan/phase-4-language-tools-spec.md §3 (reactra2tsx emitter contract).
+//
+// Produces a TypeScript string that tsc can type-check, with every DSL binding
+// reachable under its real type. Consumes FileGraph from compile() — same object
+// Pass 9 receives (anti-drift decision §2).
+// framework-review §B1: the compiler's behaviour registry + the shared emission
+// conventions (setter naming, await arg order). The shadow imports these via the
+// package surface (no cross-package relative paths; babel-plugin owns both).
+// `classifyStateSetters`/`setterNameFor` are the GATED reconciliation that
+// replaced the shadow's old looser `resolveSetterName` (§B1 C1).
+import { NATIVE_BEHAVIOURS } from "@reactra/babel-plugin";
+import { AWAIT_ARG_ORDER, classifyStateSetters, setterNameFor } from "@reactra/babel-plugin/conventions";
+import { preprocessedToDslOffset, ppSpanToDslRuns } from "./mapper.js";
+// ---------------------------------------------------------------------------
+// Surface-type naming convention (§3.2 / store consumer resolution)
+// ---------------------------------------------------------------------------
+/** PascalCase: `fooBar` → `FooBar`. */
+const toPascalCase = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+/** The exported surface type alias for a given store/service name. */
+const surfaceTypeName = (name) => `${toPascalCase(name)}Surface`;
+// ---------------------------------------------------------------------------
+// Import-path extraction from userImports entries
+// ---------------------------------------------------------------------------
+/**
+ * True when the import statement imports `name` (value or type import).
+ * Handles: `{ name }`, `{ name as alias }`, `{ type name }`, `import type { name }`.
+ */
+const importsName = (imp, name) => {
+    const match = imp.match(/\{([^}]+)\}/);
+    if (!match)
+        return false;
+    return match[1].split(",").some((part) => {
+        const stripped = part.trim().replace(/^type\s+/, "");
+        const [imported] = stripped.split(/\s+as\s+/);
+        return imported?.trim() === name;
+    });
+};
+/**
+ * Extract the module specifier from an import statement.
+ * `import type { X } from "./stores"` → `"./stores"`.
+ */
+const extractImportPath = (imp) => {
+    const m = imp.match(/from\s+["']([^"']+)["']/);
+    return m ? (m[1] ?? null) : null;
+};
+// ---------------------------------------------------------------------------
+// Store-surface resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the TypeScript type to use as the generic for useReactraStore<T>.
+ * Three cases (per §3, open question 5):
+ *   1. Same-file store container → <Name>Surface (emitted by emitStore in this file)
+ *   2. Imported store (import type { name } from "path") → <Name>Surface
+ *      (caller must emit import type { <Name>Surface } from "path")
+ *   3. No binding → "unknown"
+ */
+const resolveStoreSurface = (storeName, graph) => {
+    // Case 1: same-file store container.
+    const isLocal = graph.containers.some((c) => (c.kind === "route-store" || c.kind === "session-store" || c.kind === "export-store") &&
+        c.name === storeName);
+    if (isLocal)
+        return { surface: surfaceTypeName(storeName), importPath: null };
+    // Case 2: imported (value or type import).
+    for (const imp of graph.userImports) {
+        if (importsName(imp, storeName)) {
+            const path = extractImportPath(imp);
+            return { surface: surfaceTypeName(storeName), importPath: path };
+        }
+    }
+    // Case 3: fallback.
+    return { surface: "unknown", importPath: null };
+};
+// ---------------------------------------------------------------------------
+// Service-surface resolution (symmetric partner to resolveStoreSurface)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the TypeScript type for useService<T>.
+ * Same three-case logic as resolveStoreSurface:
+ *   1. Same-file service container → <Name>Surface
+ *   2. Imported service → <Name>Surface + importPath
+ *   3. No binding → "unknown"
+ */
+const resolveServiceSurface = (serviceName, graph) => {
+    // Case 1: same-file service container.
+    if (graph.containers.some((c) => c.kind === "service" && c.name === serviceName)) {
+        return { surface: surfaceTypeName(serviceName), importPath: null };
+    }
+    // Case 2: imported (value or type import).
+    for (const imp of graph.userImports) {
+        if (importsName(imp, serviceName)) {
+            const path = extractImportPath(imp);
+            return { surface: surfaceTypeName(serviceName), importPath: path };
+        }
+    }
+    // Case 3: fallback.
+    return { surface: "unknown", importPath: null };
+};
+// ---------------------------------------------------------------------------
+// Pre-pass: collect Surface imports needed for the preamble
+// ---------------------------------------------------------------------------
+/**
+ * Scan all storeUses and service injects across all containers and collect any
+ * Surface type imports that are not same-file.
+ * Returns entries: `import type { XSurface } from "path"`.
+ */
+const collectSurfaceImports = (graph) => {
+    const seen = new Set();
+    const result = [];
+    const record = (surface, importPath) => {
+        if (!importPath || surface === "unknown")
+            return;
+        const key = `${importPath}::${surface}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        result.push(`import type { ${surface} } from "${importPath}"`);
+    };
+    for (const c of graph.containers) {
+        for (const su of c.storeUses) {
+            if (su.typeOverride)
+                continue;
+            const { surface, importPath } = resolveStoreSurface(su.storeName, graph);
+            record(surface, importPath);
+        }
+        for (const inj of c.injects) {
+            if (inj.serviceKind !== "service")
+                continue;
+            const { surface, importPath } = resolveServiceSurface(inj.name, graph);
+            record(surface, importPath);
+        }
+    }
+    return result;
+};
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+/**
+ * Emit a TypeScript shadow file for the given FileGraph.
+ *
+ * @param graph - result of compile(source).graph
+ * @param source - the original DSL source string (for slice offsets)
+ * @param rewrites - compile(source).rewrites — used to compose preprocessed→DSL offsets.
+ *                   Pass an empty array when source-map fidelity is not required.
+ * @returns shadow text + position mappings
+ */
+export const emitShadow = (graph, source, rewrites = []) => {
+    const lines = [];
+    const mappings = [];
+    // Track current output offset for mapping generation.
+    let offset = 0;
+    // emit: pushes a line, advances offset by (text.length + 1) for the \n join.
+    // Returns the generated offset at which this line STARTS.
+    const emit = (text) => {
+        const startOffset = offset;
+        lines.push(text);
+        offset += text.length + 1; // +1 for the \n join
+        return startOffset;
+    };
+    /**
+     * Record source mappings from a verbatim-sliced span in graph.preprocessed
+     * back to the DSL source. `genStart` is the byte offset in the shadow text
+     * where the span begins; `ppStart`/`ppEnd` are the preprocessed offsets
+     * (from Babel AST .start/.end).
+     *
+     * Emits one mapping per exact preprocessed↔DSL run (ppSpanToDslRuns):
+     * Volar interpolates positions linearly inside a mapping, so a
+     * completion-grade mapping must cover text that is IDENTICAL in source and
+     * shadow. The emitter writes `preprocessed.slice(ppStart, ppEnd)` verbatim
+     * at genStart, so generated≡preprocessed by construction; the runs restrict
+     * that to where preprocessed≡DSL too. When no exact run exists (fully
+     * synthesized text), falls back to a single anchor mapping at the span
+     * start — hover/diagnostic-grade, like the pre-fix behavior.
+     */
+    const record = (genStart, ppStart, ppEnd) => {
+        if (ppStart == null || ppEnd == null || ppEnd <= ppStart)
+            return;
+        let exact = false;
+        for (const run of ppSpanToDslRuns(ppStart, ppEnd, rewrites, source)) {
+            // Guard the suffix-alignment heuristic: only verbatim runs ship.
+            const dslText = source.slice(run.dslOffset, run.dslOffset + run.length);
+            const ppText = graph.preprocessed.slice(run.ppOffset, run.ppOffset + run.length);
+            if (dslText !== ppText)
+                continue;
+            mappings.push({
+                generatedOffset: genStart + (run.ppOffset - ppStart),
+                sourceOffset: run.dslOffset,
+                length: run.length,
+            });
+            exact = true;
+        }
+        if (!exact) {
+            const dslOffset = preprocessedToDslOffset(ppStart, rewrites);
+            if (dslOffset === null)
+                return;
+            mappings.push({ generatedOffset: genStart, sourceOffset: dslOffset, length: ppEnd - ppStart });
+        }
+    };
+    const hasPageComponent = graph.containers.some((c) => c.kind === "component" && (c.params.length > 0 || c.queries.length > 0));
+    // Preamble — per spec §3 "Preamble rules".
+    for (const imp of graph.userImports)
+        emit(imp);
+    for (const t of graph.userTypes)
+        emit(t);
+    emit(`import type { Dispatch, SetStateAction } from "react"`);
+    // Real package boundaries (Runtime spec §symbol map): useReactraStore lives in
+    // @reactra/store, useService in @reactra/service, ResourceHandle in
+    // @reactra/resource. The shadow must import what actually resolves in a
+    // consumer app — a phantom import makes every binding silently `any`
+    // (hover "any", dead completions) while stub-backed tests stay green.
+    emit(`import { useReactraStore } from "@reactra/store"`);
+    emit(`import { useService } from "@reactra/service"`);
+    if (graph.containers.some((c) => c.resources.length > 0)) {
+        emit(`import { type ResourceHandle } from "@reactra/resource"`);
+    }
+    if (hasPageComponent) {
+        emit(`import { useRoute, coerceQuery } from "@reactra/router"`);
+    }
+    // Emit any Surface type imports needed for cross-file inject store consumers.
+    for (const surfaceImp of collectSurfaceImports(graph))
+        emit(surfaceImp);
+    for (const container of graph.containers) {
+        if (container.kind === "component") {
+            emitComponent(container, graph, emit, record);
+        }
+        else if (container.kind === "route-store" ||
+            container.kind === "session-store" ||
+            container.kind === "export-store") {
+            emitStore(container, graph, emit, record);
+        }
+        else if (container.kind === "service") {
+            emitService(container, graph, emit);
+        }
+    }
+    // Mirror the compiler's auto-default-export rule (Pass 9 Day-21 #18): when
+    // exactly one component is exported, the compiled output emits `export default X`.
+    // The route manifest types `import("./pages/…")` as `Promise<{ default: ComponentType }>`,
+    // so the shadow must match or the generated-file check fires a TS2322.
+    const exportedComponents = graph.containers.filter((c) => c.kind === "component" && c.exported);
+    if (exportedComponents.length === 1) {
+        emit(`\nexport default ${exportedComponents[0].name}`);
+    }
+    return { text: lines.join("\n"), mappings };
+};
+// ---------------------------------------------------------------------------
+// Component lowering (§3.1)
+// ---------------------------------------------------------------------------
+const emitComponent = (c, graph, emit, record) => {
+    const isPage = c.params.length > 0 || c.queries.length > 0;
+    const decl = c.exported ? "export const" : "const";
+    if (isPage) {
+        emit(`${decl} ${c.name} = () => {`);
+        emit(`  const __route = useRoute()`);
+        for (const p of c.params)
+            emitParam(p, graph, emit);
+        for (const q of c.queries)
+            emitQuery(q, graph, emit);
+    }
+    else {
+        emit(`${decl} ${c.name} = (${c.propsParam ?? ""}) => {`);
+    }
+    // §B1 C1: classify setters ONCE per component (gated: only renames for a
+    // non-trivial `action set<Cap(X)>` targeting an existing `state X`).
+    const { renamedStates } = classifyStateSetters(c);
+    for (const su of c.storeUses)
+        emitStoreUse(su, graph, emit);
+    for (const inj of c.injects)
+        emitInject(inj, graph, emit);
+    for (const s of c.states)
+        emitState(s, graph, emit, record, renamedStates);
+    // `uses` bindings declared before derived/action/view so they're in scope for all of them.
+    if (c.uses)
+        emitUses(c.uses, c.name, emit);
+    for (const d of c.deriveds)
+        emitDerived(d, graph, emit, record);
+    for (const a of c.actions)
+        emitAction(a, graph, emit, record);
+    for (const r of c.resources)
+        emitResource(r, graph, emit, record);
+    for (const cmd of c.commands)
+        emitCommand(cmd, graph, emit, record);
+    for (const m of c.mounts)
+        emitFlatBody(m.body, graph, emit);
+    for (const e of c.effects)
+        emitFlatBody(e.body, graph, emit);
+    if (c.meta)
+        emitMeta(c.meta, graph, emit);
+    if (c.errorBoundary)
+        emitErrorBoundary(c.errorBoundary, graph, emit);
+    // Suspense: emit body JSX as a void expression so it type-checks independently.
+    if (c.suspense) {
+        const sb = c.suspense.body.body;
+        if (sb.start != null && sb.end != null) {
+            const bodyText = graph.preprocessed.slice(sb.start, sb.end);
+            emit(`  void (<>{(${bodyText})}</>)`);
+        }
+    }
+    if (c.view) {
+        emitView(c.view, graph, emit, record);
+    }
+    else {
+        emit(`  return null as never`);
+    }
+    emit(`}`);
+};
+// ---------------------------------------------------------------------------
+// Store lowering (§3.2)
+// ---------------------------------------------------------------------------
+const emitStore = (c, graph, emit, record) => {
+    // Anti-drift: the compiler FORCE-exports every store regardless of the source
+    // `export` keyword (pass-9-codegen.ts — "Force-exported regardless of c.exported").
+    // The shadow must match, or a non-`export`ed store reads as module-private here while
+    // the build ships it exported (the D4 divergence the F-PARITY gate now guards).
+    const decl = "export";
+    const inputsTypeName = `${toPascalCase(c.name)}Inputs`;
+    const surfType = surfaceTypeName(c.name);
+    // Inputs type — each InputNode contributes a field typed from its declared
+    // annotation (Run 2 / D3 — `tsType` is now threaded through the preprocessor and
+    // AST). per §3.2: "input X: T -> const X = __inputs.X follows as the first body
+    // statement". Falls back to `unknown` only when the source omits the annotation.
+    if (c.inputs.length > 0) {
+        const fields = c.inputs
+            .map((inp) => {
+            const opt = inp.requirement === "optional" ? "?" : "";
+            return `${inp.name}${opt}: ${inp.tsType ?? "unknown"}`;
+        })
+            .join("; ");
+        emit(`${decl ? decl + " " : ""}type ${inputsTypeName} = { ${fields} }`);
+        emit(`${decl ? decl + " " : ""}function ${c.name}(__inputs: ${inputsTypeName}) {`);
+        // Bind each input as a const in the function body.
+        for (const inp of c.inputs)
+            emitInput(inp, emit);
+    }
+    else {
+        emit(`${decl ? decl + " " : ""}function ${c.name}() {`);
+    }
+    // §B1 C1: stores never rename setters — `classifyStateSetters` returns an
+    // empty `renamedStates` for non-component containers, so a store `state X`
+    // always emits `setX` (matches Pass 9, which renames in components only).
+    const { renamedStates } = classifyStateSetters(c);
+    for (const s of c.states)
+        emitState(s, graph, emit, record, renamedStates);
+    for (const d of c.deriveds)
+        emitDerived(d, graph, emit, record);
+    for (const a of c.actions)
+        emitAction(a, graph, emit, record);
+    for (const r of c.resources)
+        emitResource(r, graph, emit, record);
+    for (const e of c.effects)
+        emitFlatBody(e.body, graph, emit);
+    // Return all state/derived/action/resource names.
+    const returnNames = [
+        ...c.states.map((s) => s.name),
+        ...c.deriveds.map((d) => d.name),
+        ...c.actions.map((a) => a.name),
+        ...c.resources.map((r) => r.name),
+    ];
+    emit(`  return { ${returnNames.join(", ")} }`);
+    emit(`}`);
+    // Surface type alias — ReturnType<typeof storeFn> is the consumable surface.
+    emit(`${decl ? decl + " " : ""}type ${surfType} = ReturnType<typeof ${c.name}>`);
+};
+// ---------------------------------------------------------------------------
+// Service lowering (§3.3)
+// ---------------------------------------------------------------------------
+const emitService = (c, graph, emit) => {
+    // Anti-drift: the compiler force-exports every service regardless of the source
+    // `export` keyword (pass-9-codegen.ts). Match it (see the store note above — D4).
+    const decl = "export";
+    const surfType = surfaceTypeName(c.name);
+    const noop = () => { };
+    emit(`${decl ? decl + " " : ""}function ${c.name}() {`);
+    for (const a of c.actions)
+        emitAction(a, graph, emit, noop);
+    const returnNames = c.actions.map((a) => a.name);
+    emit(`  return { ${returnNames.join(", ")} }`);
+    emit(`}`);
+    emit(`${decl ? decl + " " : ""}type ${surfType} = ReturnType<typeof ${c.name}>`);
+};
+// ---------------------------------------------------------------------------
+// Per-construct lowering helpers
+// ---------------------------------------------------------------------------
+const emitParam = (p, _graph, emit) => {
+    // Route params are always `string` at runtime (`__route.params` is
+    // `Record<string, string>`; Pass 9 emits no coercion). The shadow projects
+    // `string` unconditionally — typing a `param count: number` as `number` would be
+    // a runtime-contradicting lie (the value is the URL string `"42"`). A non-string
+    // annotation therefore surfaces honestly as a type error on number/array ops.
+    emit(`  const ${p.name} = __route.params.${p.name}`);
+};
+const emitQuery = (q, _graph, emit) => {
+    const tsType = q.tsType ?? "string";
+    // coerceQuery returns unknown at runtime; cast to the declared type (D2: array/union
+    // types would otherwise land as unknown). A query with no default can be absent from
+    // the URL, so it widens to `| undefined` (matching the router); a defaulted query never is.
+    const cast = q.defaultText !== undefined ? tsType : `${tsType} | undefined`;
+    emit(`  const ${q.name} = coerceQuery(__route.query.${q.name}, ${JSON.stringify(tsType)}) as ${cast}`);
+};
+const emitInput = (inp, emit) => {
+    emit(`  const ${inp.name} = __inputs.${inp.name}`);
+};
+const emitStoreUse = (su, graph, emit) => {
+    // typeOverride takes precedence over resolved surface (per spec §3.1 inject-store table).
+    const surface = su.typeOverride ?? resolveStoreSurface(su.storeName, graph).surface;
+    if (su.fields && su.fields.length > 0) {
+        const destructure = su.fields
+            .map((f) => (typeof f === "string" ? f : `${f.source}: ${f.local}`))
+            .join(", ");
+        emit(`  const { ${destructure} } = useReactraStore<${surface}>("${su.storeName}")`);
+    }
+    else {
+        emit(`  const ${su.alias ?? su.storeName} = useReactraStore<${surface}>("${su.storeName}")`);
+    }
+};
+const emitInject = (inj, graph, emit) => {
+    if (inj.serviceKind !== "service")
+        return;
+    const binding = inj.alias ?? inj.name;
+    const { surface } = resolveServiceSurface(inj.name, graph);
+    emit(`  const ${binding} = useService<${surface}>("${inj.name}")`);
+};
+const emitState = (s, graph, emit, record, renamedStates) => {
+    const init = s.initializer;
+    const ppStart = init.start;
+    const ppEnd = init.end;
+    const initText = s.initializerText;
+    // Emit the let binding; record a mapping from the initializer span.
+    const lineText = `  let ${s.name} = ${initText}`;
+    // The initializer text appears after "  let <name> = " in the emitted line.
+    const prefixLen = `  let ${s.name} = `.length;
+    const lineStart = emit(lineText);
+    if (ppStart != null && ppEnd != null) {
+        record(lineStart + prefixLen, ppStart, ppEnd);
+    }
+    // §B1 C1: shared GATED setter naming — `renamedStates` is computed once per
+    // container by the caller via `classifyStateSetters` (the SAME derivation
+    // Pass 9 uses). The old shadow-local `resolveSetterName` matched on a bare
+    // action name across all containers and could rename when Pass 9 wouldn't.
+    const setterName = setterNameFor(s.name, renamedStates);
+    emit(`  const ${setterName}: Dispatch<SetStateAction<typeof ${s.name}>> = null as never`);
+};
+const emitDerived = (d, graph, emit, record) => {
+    const thunk = d.thunk;
+    const body = thunk.body;
+    const preprocessed = graph.preprocessed;
+    const start = body.start;
+    const end = body.end;
+    if (start == null || end == null) {
+        emit(`  // [reactra2tsx] unhandled: derived ${d.name} — missing offsets`);
+        return;
+    }
+    const bodyText = preprocessed.slice(start, end);
+    const inner = stripOuterParens(bodyText.trim());
+    // Both bare and IIFE forms emit as-is (IIFE already is the IIFE; bare is the expression).
+    const prefixLen = `  const ${d.name} = `.length;
+    const lineStart = emit(`  const ${d.name} = ${inner}`);
+    // Map the derived body back to the preprocessed span (trimmed inner may differ — map raw body).
+    record(lineStart + prefixLen, start, end);
+};
+/**
+ * True when `node` is a pure entity name — an Identifier or a dotted member chain
+ * with no call or computed access anywhere. Only such a name is valid inside `typeof`.
+ */
+const isEntityName = (node) => {
+    if (node.type === "Identifier")
+        return true;
+    if (node.type === "MemberExpression" && node.computed !== true && node.object != null) {
+        return isEntityName(node.object);
+    }
+    return false;
+};
+const emitResource = (r, graph, emit, record) => {
+    // The raw fetched type: `Awaited<ReturnType<typeof <callee>>>` for an entity
+    // fetcher, else `unknown`. `rawCallee` carries the mappable callee text/range.
+    let rawType = "unknown";
+    let calleeRange = null;
+    const body = r.fetcher.body;
+    if (body.type === "CallExpression") {
+        const callee = body.callee;
+        if (isEntityName(callee) && callee.start != null && callee.end != null) {
+            const calleeText = graph.preprocessed.slice(callee.start, callee.end);
+            rawType = `Awaited<ReturnType<typeof ${calleeText}>>`;
+            calleeRange = { start: callee.start, end: callee.end };
+        }
+        else {
+            emit(`  // resource type unknown — complex fetcher`);
+        }
+    }
+    else {
+        emit(`  // resource type unknown — complex fetcher`);
+    }
+    if (r.select === undefined) {
+        emitResourceDecl(r.name, rawType, "", calleeRange, emit, record);
+        return;
+    }
+    // `select(u => u.name)` projects `.data` to the selector's return (the type
+    // parameter `S`). A `typeof` type query can't read an inline arrow expression,
+    // so we bind the SAME selector source Pass 9 emits to a named helper (no drift —
+    // B1) and `ReturnType<typeof helper>` it. The helper's param is the raw fetched
+    // type, so an UNannotated selector (`u => u.name`) still infers `S` correctly;
+    // for a complex fetcher the raw type is `any` so the selector body doesn't error.
+    const selParam = rawType === "unknown" ? "any" : rawType;
+    emit(`  const __sel_${r.name} = (__d: ${selParam}) => (${r.select})(__d)`);
+    emitResourceDecl(r.name, rawType, `, ReturnType<typeof __sel_${r.name}>`, calleeRange, emit, record);
+};
+/** Emit the `const <name>: ResourceHandle<<raw><selectArg>> = null as never` line + map the callee. */
+const emitResourceDecl = (name, rawType, selectArg, calleeRange, emit, record) => {
+    const prefix = `  const ${name}: ResourceHandle<`;
+    const lineStart = emit(`${prefix}${rawType}${selectArg}> = null as never`);
+    // The callee sits inside `Awaited<ReturnType<typeof <callee>>>` — offset past that wrapper.
+    if (calleeRange)
+        record(lineStart + prefix.length + "Awaited<ReturnType<typeof ".length, calleeRange.start, calleeRange.end);
+};
+const emitAction = (a, graph, emit, record) => {
+    const preprocessed = graph.preprocessed;
+    const arrow = a.arrow;
+    const paramsText = arrow.params
+        .map((p) => {
+        if (p.start == null || p.end == null)
+            return "";
+        return preprocessed.slice(p.start, p.end);
+    })
+        .join(", ");
+    const bodyText = arrow.body.start != null && arrow.body.end != null
+        ? preprocessed.slice(arrow.body.start, arrow.body.end)
+        : "{ }";
+    const asyncPrefix = a.isAsync ? "async " : "";
+    // No return annotation — TS infers from the sliced body, matching Pass-9 (which annotates nothing).
+    // Component `action async` is transition-wrapped by Pass-9 so its runtime return is void; the shadow
+    // models the raw body — a deliberate simplification.
+    const prefix = `  const ${a.name} = ${asyncPrefix}(${paramsText}) => `;
+    const lineStart = emit(`${prefix}${bodyText}`);
+    // Map the action body (the part the user wrote) back to its preprocessed origin.
+    if (arrow.body.start != null && arrow.body.end != null) {
+        record(lineStart + prefix.length, arrow.body.start, arrow.body.end);
+    }
+};
+/**
+ * Emit the shadow for a `command` (the write primitive). The handle surface must
+ * type-check in the view:
+ *  - block form  → `f.pending` / `f.result` / `f.error` (mirrors useActionState).
+ *    The body is emitted as a typed reducer so `f.result` infers its return type
+ *    AND the body itself type-checks (states/imports in scope).
+ *  - arrow form  → `f.pending` only (mirrors useTransition). The fetcher is
+ *    type-checked via a `void` expression.
+ * The optimistic / rollback clause bodies are emitted as `void` arrows so their
+ * state writes / error param type-check too. The optimistic-tracked states need
+ * no special shadow: they're ordinary `let` bindings (the view reads them as the
+ * mirror's element type, which equals the base type).
+ */
+const emitCommand = (cmd, graph, emit, record) => {
+    const pp = graph.preprocessed;
+    const arrow = cmd.arrow;
+    const paramsText = arrow.params
+        .map((p) => (p.start != null && p.end != null ? pp.slice(p.start, p.end) : ""))
+        .join(", ");
+    if (cmd.form === "block") {
+        const bodyText = arrow.body.start != null && arrow.body.end != null ? pp.slice(arrow.body.start, arrow.body.end) : "{ }";
+        const prefix = `  const __cmd_${cmd.name} = async (${paramsText}) => `;
+        const lineStart = emit(`${prefix}${bodyText}`);
+        if (arrow.body.start != null && arrow.body.end != null) {
+            record(lineStart + prefix.length, arrow.body.start, arrow.body.end);
+        }
+        emit(`  const ${cmd.name}: ((arg?: unknown) => void) & ` +
+            `{ pending: boolean; result: Awaited<ReturnType<typeof __cmd_${cmd.name}>> | undefined; error: string | undefined } = null as never`);
+    }
+    else {
+        // Arrow form — type-check the fetcher; expose only `.pending`.
+        const fetcherText = arrow.body.start != null && arrow.body.end != null ? pp.slice(arrow.body.start, arrow.body.end) : "undefined";
+        const prefix = `  void (async (${paramsText}) => (`;
+        const lineStart = emit(`${prefix}${fetcherText}))`);
+        if (arrow.body.start != null && arrow.body.end != null) {
+            record(lineStart + prefix.length, arrow.body.start, arrow.body.end);
+        }
+        emit(`  const ${cmd.name}: ((arg?: unknown) => void) & { pending: boolean } = null as never`);
+    }
+    // Type-check the optional clause bodies (state writes / error param).
+    if (cmd.optimistic?.start != null && cmd.optimistic.end != null) {
+        const prefix = `  void (`;
+        const lineStart = emit(`${prefix}${pp.slice(cmd.optimistic.start, cmd.optimistic.end)})`);
+        record(lineStart + prefix.length, cmd.optimistic.start, cmd.optimistic.end);
+    }
+    // The rollback error param is `unknown` at runtime (it comes from a `catch`), so the
+    // shadow forces `: unknown` rather than slicing the bare `(e)` verbatim — otherwise
+    // a `rollback(e)` would be a false TS7006 (implicit any) under strict. Mirrors
+    // emitErrorBoundary, which annotates its error param the same way.
+    const rb = cmd.rollback;
+    if (rb?.body?.start != null && rb.body.end != null) {
+        const p0 = rb.params[0];
+        const paramDecl = p0?.name ? `${p0.name}: unknown` : "";
+        const prefix = `  void ((${paramDecl}) => `;
+        const lineStart = emit(`${prefix}${pp.slice(rb.body.start, rb.body.end)})`);
+        record(lineStart + prefix.length, rb.body.start, rb.body.end);
+    }
+};
+/**
+ * Emit the statements of an arrow body as flat top-level statements.
+ * Used for mount/effect — teardown `return () => ...` is dropped per §3.1.
+ */
+const emitFlatBody = (arrow, graph, emit) => {
+    const preprocessed = graph.preprocessed;
+    const arrowBody = arrow.body;
+    if (arrowBody.type !== "BlockStatement" || !Array.isArray(arrowBody.body))
+        return;
+    for (const stmt of arrowBody.body) {
+        // Drop `return () => ...` teardown statement.
+        if (stmt.type === "ReturnStatement" &&
+            stmt.argument != null &&
+            stmt.argument.type === "ArrowFunctionExpression") {
+            continue;
+        }
+        if (stmt.start != null && stmt.end != null) {
+            emit(`  ${preprocessed.slice(stmt.start, stmt.end)}`);
+        }
+    }
+};
+/**
+ * meta { title: expr } → document.title = expr (per §3.1).
+ * document.title is string — a non-string title expr raises TS2322.
+ */
+const emitMeta = (meta, graph, emit) => {
+    const preprocessed = graph.preprocessed;
+    const obj = meta.object;
+    if (obj.type !== "ObjectExpression" || !obj.properties)
+        return;
+    for (const prop of obj.properties) {
+        if (prop.type === "ObjectProperty" && prop.key.type === "Identifier" && prop.key.name === "title") {
+            const v = prop.value;
+            if (v.start != null && v.end != null) {
+                const titleExpr = preprocessed.slice(v.start, v.end);
+                emit(`  document.title = (${titleExpr}) as string`);
+            }
+            break;
+        }
+    }
+};
+/**
+ * errorBoundary(e) { JSX } → IIFE call that type-checks the JSX body (per §3.1).
+ * The error param is typed unknown (React ErrorBoundary contract).
+ * A prop type mismatch raises TS2345.
+ */
+const emitErrorBoundary = (eb, graph, emit) => {
+    const preprocessed = graph.preprocessed;
+    const body = eb.body;
+    const bodyStart = body.body.start;
+    const bodyEnd = body.body.end;
+    if (bodyStart == null || bodyEnd == null)
+        return;
+    const bodyText = preprocessed.slice(bodyStart, bodyEnd);
+    emit(`  ;((${eb.errorParam}: unknown) => ${bodyText})(undefined)`);
+};
+/** Collect all __reactra_await__ CallExpression nodes via a recursive walk. */
+const collectAwaitCalls = (node) => {
+    if (!node || typeof node !== "object")
+        return [];
+    const results = [];
+    if (node.type === "CallExpression" &&
+        node.callee?.type === "Identifier" &&
+        node.callee?.name === "__reactra_await__") {
+        results.push(node);
+        // Don't recurse inside — arguments are the arrows we'll slice separately.
+        return results;
+    }
+    // Recurse into known child fields that may contain JSX nodes.
+    const childFields = [
+        "body", "expression", "children", "openingElement", "closingElement",
+        "attributes", "argument", "left", "right", "test", "consequent", "alternate",
+        "callee", "arguments", "elements", "properties", "value",
+    ];
+    for (const field of childFields) {
+        const child = node[field];
+        if (Array.isArray(child)) {
+            for (const item of child) {
+                if (item && typeof item === "object") {
+                    results.push(...collectAwaitCalls(item));
+                }
+            }
+        }
+        else if (child && typeof child === "object") {
+            results.push(...collectAwaitCalls(child));
+        }
+    }
+    return results;
+};
+/**
+ * Emit the component view as a return statement.
+ * Each `__reactra_await__(rArrow, successArrow, pendingArrow, errorArrow)`
+ * call embedded in the JSX is replaced with:
+ *   {(r).status === "success" ? (successBody) : (r).status === "pending" ? (pendingBody) : (errorBody)}
+ * so tsc sees the resource field access under the correct union type.
+ * The error param is typed `as unknown` to match the runtime contract.
+ */
+const emitView = (view, graph, emit, record) => {
+    const preprocessed = graph.preprocessed;
+    const viewBodyExpr = view.body.body;
+    if (viewBodyExpr.start == null || viewBodyExpr.end == null) {
+        emit(`  return null as never`);
+        return;
+    }
+    const awaitCalls = collectAwaitCalls(viewBodyExpr);
+    if (awaitCalls.length === 0) {
+        // No await blocks — emit the view body verbatim and record the span.
+        const bodyText = preprocessed.slice(viewBodyExpr.start, viewBodyExpr.end);
+        const prefix = `  return `;
+        const lineStart = emit(`${prefix}${bodyText}`);
+        record(lineStart + prefix.length, viewBodyExpr.start, viewBodyExpr.end);
+        return;
+    }
+    // Build text with await calls replaced by ternaries.
+    // Each call occupies [callStart, callEnd] in `preprocessed`. We need to
+    // also replace the surrounding JSXExpressionContainer `{...}` if present,
+    // since the ternary already includes `{}` delimiters.
+    // Strategy: walk left-to-right, replacing each call span with the ternary.
+    // We target the CallExpression span directly (not the container) since we
+    // need the `{}` in the output.
+    let result = "";
+    let cursor = viewBodyExpr.start;
+    // Every span of `result` that is a verbatim preprocessed slice, recorded at
+    // its REAL position in `result` — the substitution changes lengths, so a
+    // single whole-body mapping would drift for everything after the first
+    // ternary. Each piece becomes its own record() call (→ exact runs), which is
+    // what makes hover/completion work INSIDE await blocks.
+    const pieces = [];
+    const appendSlice = (ppStart, ppEnd) => {
+        if (ppEnd > ppStart)
+            pieces.push({ resultPos: result.length, ppStart, ppEnd });
+        result += preprocessed.slice(ppStart, ppEnd);
+    };
+    for (const call of awaitCalls) {
+        if (call.start == null || call.end == null)
+            continue;
+        const callStart = call.start;
+        const callEnd = call.end;
+        if (callStart < cursor)
+            continue;
+        // Verbatim text before this call.
+        appendSlice(cursor, callStart);
+        // Extract argument arrows.
+        const args = call.arguments ?? [];
+        // §B1: index via the shared AWAIT_ARG_ORDER (same constants Pass 9 uses).
+        const resourceArrow = args[AWAIT_ARG_ORDER.resource];
+        const successArrow = args[AWAIT_ARG_ORDER.success];
+        const pendingArrow = args[AWAIT_ARG_ORDER.pending];
+        const errorArrow = args[AWAIT_ARG_ORDER.error];
+        const rBody = resourceArrow?.body;
+        const rRaw = rBody?.start != null && rBody?.end != null
+            ? preprocessed.slice(rBody.start, rBody.end)
+            : null;
+        const rText = rRaw !== null ? rRaw.trim() : "undefined";
+        // The trim consumed leading whitespace — anchor the mapped span at the
+        // first kept char so the slice equals rText exactly.
+        const rPpStart = rRaw !== null ? rBody.start + (rRaw.length - rRaw.trimStart().length) : null;
+        const appendR = () => {
+            if (rPpStart !== null)
+                appendSlice(rPpStart, rPpStart + rText.length);
+            else
+                result += rText;
+        };
+        const successBody = successArrow?.body;
+        const hasPending = pendingArrow != null && pendingArrow.type === "ArrowFunctionExpression";
+        const hasError = errorArrow != null && errorArrow.type === "ArrowFunctionExpression";
+        const pendingBody = hasPending ? pendingArrow.body : null;
+        // Error param from the error arrow's first param (e.g. `e`).
+        const errorParam = (() => {
+            if (!hasError)
+                return "e";
+            const params = errorArrow.params;
+            const p = params?.[0];
+            return p?.type === "Identifier" ? p.name : "e";
+        })();
+        const errorBody = hasError ? errorArrow.body : null;
+        const appendBody = (node, fallback) => {
+            if (node?.start != null && node?.end != null) {
+                appendSlice(node.start, node.end);
+            }
+            else {
+                result += fallback;
+            }
+        };
+        // Ternary on the REAL ResourceHandle discriminators (it has no `status`
+        // field): r.isPending ? pending : r.error ? error : success.
+        // The error branch wraps the body in an IIFE with `(param: unknown)` so tsc
+        // checks any member access against `unknown` (e.g. `e.message` raises TS18046).
+        // Passing `undefined` as the IIFE argument is fine — we only need type-checking,
+        // not runtime execution. Pattern mirrors emitErrorBoundary (per §3.1).
+        // Built via appendSlice so each user-written block lands in `pieces`.
+        result += "(";
+        appendR();
+        result += ").isPending ? ";
+        if (hasPending) {
+            appendBody(pendingBody, "<></>");
+        }
+        else {
+            result += "null";
+        }
+        if (hasError) {
+            result += " : (";
+            appendR();
+            result += `).error ? ((${errorParam}: unknown) => `;
+            appendBody(errorBody, "null");
+            result += ")(undefined)";
+        }
+        result += " : ";
+        appendBody(successBody, "null");
+        cursor = callEnd;
+    }
+    // Remaining verbatim text after last await call.
+    appendSlice(cursor, viewBodyExpr.end);
+    // One record per verbatim piece — the substitution changes lengths, so each
+    // piece needs its own generated offset for exact (completion-grade) runs.
+    const viewPrefix = `  return `;
+    const lineStart = emit(`${viewPrefix}${result}`);
+    for (const p of pieces) {
+        record(lineStart + viewPrefix.length + p.resultPos, p.ppStart, p.ppEnd);
+    }
+};
+// ---------------------------------------------------------------------------
+// Behaviour uses lowering (§3.1)
+// ---------------------------------------------------------------------------
+/**
+ * Emit a comment for each `uses <behaviour>` declaration.
+ * No mixin type contracts are published by @reactra/behaviours in Phase 1,
+ * so the shadow degrades gracefully — the comment is a signal to LSP consumers
+ * that the keyword was seen.
+ */
+const emitUses = (uses, _componentName, emit) => {
+    // D1: a `uses <behaviour>` injects bare names into the body (e.g. `undo`/`redo` from
+    // `uses undoable`). Declare each so references type-check instead of TS2304 — using the
+    // compiler behaviour registry's exposedBindings/exposedTypes (the single source of truth,
+    // shared with codegen). `null as never` is the same value-less binding the kept `setX`
+    // escape hatch uses; the type comes from exposedTypes (falls back to `unknown`).
+    for (const name of uses.names) {
+        const behaviour = NATIVE_BEHAVIOURS.get(name);
+        if (!behaviour || behaviour.exposedBindings.length === 0) {
+            emit(`  // uses ${name} — no injected bindings`);
+            continue;
+        }
+        for (const binding of behaviour.exposedBindings) {
+            const t = behaviour.exposedTypes?.[binding] ?? "unknown";
+            // `null as unknown as (T)` — a value-less binding that keeps `typeof binding === T`.
+            // (`null as never` collapses `typeof` to `never` for primitive/union types like boolean.)
+            emit(`  const ${binding} = null as unknown as (${t})`);
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// Small utilities
+// ---------------------------------------------------------------------------
+// §B1 C1: `resolveSetterName` deleted. The shadow now shares the GATED setter
+// derivation from `@reactra/babel-plugin/conventions` (`classifyStateSetters` +
+// `setterNameFor`) — the old bare-name-match impl lived here and had drifted
+// from Pass 9 (it renamed on any action named `setX`, ignoring triviality and
+// state-membership; Pass 9 only renames for a NON-TRIVIAL action targeting an
+// existing state). They agreed on the examples by luck.
+/** Strip outer parentheses if the string starts with `(` and ends with `)`. */
+const stripOuterParens = (s) => {
+    if (!s.startsWith("(") || !s.endsWith(")"))
+        return s;
+    let depth = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === "(")
+            depth++;
+        else if (s[i] === ")") {
+            depth--;
+            if (depth === 0 && i < s.length - 1)
+                return s;
+        }
+    }
+    return s.slice(1, -1);
+};
+//# sourceMappingURL=emitter.js.map