@reactra/babel-plugin 0.1.0-alpha.0

package/dist/behaviours/plugin.js

@@ -0,0 +1,70 @@
+// @reactra/babel-plugin — plugin-class `uses` resolution (Behaviour Plugin spec §3).
+//
+// Owner spec: reactra-behaviour-plugin-spec.md §3 (three-way resolution) + §4
+// (wrap emission). Names that are not compiler-native resolve here: the
+// first-party set auto-imports from @reactra/behaviours/<name>; any other name
+// must be bound by a top-level VALUE import already in the file, else R045
+// (owned by Component DSL §14, raised in Pass 9 — the SVC015 owner/raiser split).
+import { NATIVE_BEHAVIOURS } from "./index.js";
+/** First-party plugin behaviours — DSL vocabulary with a compiler-constant import path (§3 row 2). */
+export const FIRST_PARTY_PLUGINS = new Set([
+    "traceable",
+    "persistent",
+    "observable",
+]);
+/**
+ * Binding names introduced by the file's top-level VALUE imports — named,
+ * default, and namespace forms; `import type` lines are skipped (a type can't
+ * wrap a component). Regex over the preserved user-import lines is sufficient:
+ * Pass 2 stores them verbatim and they are single statements by construction.
+ */
+export const importedBindingNames = (userImports) => {
+    const names = new Set();
+    for (const line of userImports) {
+        if (/^\s*import\s+type\b/.test(line))
+            continue;
+        // Named specifiers: import { a, b as c, type T } from "…"
+        const named = line.match(/\{([^}]*)\}/);
+        if (named?.[1]) {
+            for (const spec of named[1].split(",")) {
+                const s = spec.trim();
+                if (s.length === 0 || s.startsWith("type "))
+                    continue;
+                const renamed = s.match(/\bas\s+(\w+)$/);
+                names.add(renamed?.[1] ?? s.split(/\s+/)[0]);
+            }
+        }
+        // Default import: `import d from` / `import d, { … } from`
+        const def = line.match(/^\s*import\s+(\w+)\s*(?:,|from)/);
+        if (def?.[1])
+            names.add(def[1]);
+        // Namespace import: `import * as ns from`
+        const ns = line.match(/\*\s*as\s+(\w+)/);
+        if (ns?.[1])
+            names.add(ns[1]);
+    }
+    return names;
+};
+/**
+ * Resolve a component's plugin-class `uses` names (everything not in the
+ * native registry), in source order (Behaviour Plugin §3). Throws R045 for a
+ * name that is neither first-party nor bound by a value import in the file.
+ */
+export const resolvePluginBehaviours = (c, graph) => {
+    const pluginNames = (c.uses?.names ?? []).filter((n) => !NATIVE_BEHAVIOURS.has(n));
+    if (pluginNames.length === 0)
+        return [];
+    const bound = importedBindingNames(graph.userImports);
+    return pluginNames.map((name) => {
+        if (FIRST_PARTY_PLUGINS.has(name))
+            return { name, firstParty: true };
+        if (bound.has(name))
+            return { name, firstParty: false };
+        throw new Error(`[reactra:compile] R045: \`uses ${name}\` in component "${c.name}" does not resolve — ` +
+            `"${name}" is not a compiler-native behaviour, not a first-party plugin ` +
+            `(traceable/persistent/observable), and not bound by a value import in this file. ` +
+            `Import it (\`import { ${name} } from "..."\`) or fix the name. ` +
+            `(Component DSL §14 R045; Behaviour Plugin spec §3.)`);
+    });
+};
+//# sourceMappingURL=plugin.js.map

package/dist/behaviours/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/behaviours/plugin.ts"],"names":[],"mappings":"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"}

package/dist/behaviours/replayable.d.ts

@@ -0,0 +1,10 @@
+import type { CompilerNativeBehaviour } from "./types.ts";
+/**
+ * `uses replayable` — inner-body session-recording instrumentation (Replay §4).
+ * Preamble binds the channel + a mount/unmount effect; EVERY action emits an
+ * `action` event (prologue) and a state-writer additionally emits a post-body
+ * `state_snapshot` (epilogue); each `resource` emits a status effect. Deps widen
+ * to all state names (Replay §4.3 rule 4 — "matches the undoable widening rule").
+ */
+export declare const replayableBehaviour: CompilerNativeBehaviour;
+//# sourceMappingURL=replayable.d.ts.map

package/dist/behaviours/replayable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayable.d.ts","sourceRoot":"","sources":["../../src/behaviours/replayable.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAqBzD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,uBA0DjC,CAAA"}

package/dist/behaviours/replayable.js

@@ -0,0 +1,86 @@
+// @reactra/babel-plugin — `uses replayable` as a compiler-native behaviour entry.
+//
+// Owner spec: reactra-replay-spec.md §4 (seam values) + reactra-compiler-spec.md
+// §4 Pass 9.1 (the registry shape this implements). Emits the inner-body
+// instrumentation that drives the `@reactra/behaviours/replayable` runtime: a
+// channel preamble + mount/unmount effect, a per-action `action` emit, a post-body
+// `state_snapshot` for state-writers, and a per-resource status effect.
+import * as t from "@babel/types";
+/**
+ * The binding name to record in an `action` event's payload array. Identifiers
+ * pass through; an `x = default` param contributes `x`; a rest `...args` spreads.
+ * Non-identifier destructure patterns (rare; not in the spec examples) are
+ * skipped — recording their shape as a value is a later refinement.
+ */
+const paramName = (p) => {
+    if (t.isIdentifier(p))
+        return p.name;
+    if (t.isAssignmentPattern(p) && t.isIdentifier(p.left))
+        return p.left.name;
+    if (t.isRestElement(p) && t.isIdentifier(p.argument))
+        return `...${p.argument.name}`;
+    return null;
+};
+const actionPayload = (a) => a.arrow.params
+    .map((p) => paramName(p))
+    .filter((n) => n !== null)
+    .join(", ");
+/**
+ * `uses replayable` — inner-body session-recording instrumentation (Replay §4).
+ * Preamble binds the channel + a mount/unmount effect; EVERY action emits an
+ * `action` event (prologue) and a state-writer additionally emits a post-body
+ * `state_snapshot` (epilogue); each `resource` emits a status effect. Deps widen
+ * to all state names (Replay §4.3 rule 4 — "matches the undoable widening rule").
+ */
+export const replayableBehaviour = {
+    name: "replayable",
+    runtime: { hook: "useReplayChannel", module: "@reactra/behaviours/replayable" },
+    reactImports: ["useCallback", "useEffect"],
+    exposedBindings: [],
+    widensAugmentedActionDeps: true,
+    emitPreamble(c, ctx) {
+        // v1.4 live re-drive (Replay §4.3 rule 1): the mount bracket registers the
+        // state→setter map. Keys iterate the states in source order; values resolve
+        // via the SAME ctx.setterNameFor the snapshot/restore paths use, so a
+        // renamed `__setX` setter is carried correctly — drift-proof by
+        // construction. A state-less component mounts bare (non-driveable).
+        const setters = [...ctx.stateNames].map((n) => `${n}: ${ctx.setterNameFor(n)}`).join(", ");
+        const mountArg = setters.length > 0 ? `{ ${setters} }` : "";
+        return [
+            ctx.line(`  const __replay = useReplayChannel("${c.name}")`),
+            ctx.line(`  useEffect(() => { __replay.mount(${mountArg}); return () => __replay.unmount() }, [])`),
+        ];
+    },
+    // Every action is a session event (Replay §4.3 rule 2) — not just state-writers.
+    augmentsAction() {
+        return true;
+    },
+    actionPrologue(a, _c, ctx) {
+        // A state-writer carries its straight-line write-set as the 3rd argument —
+        // names only, never values — so the runtime can redact the payload of an
+        // action that writes a `redactKeys` field (Replay §4.3 rule 2 / §5, v1.2).
+        // Pure side-effect actions keep the 2-arg form.
+        const writesArg = ctx.actionWritesState(a)
+            ? `, [${[...ctx.straightLineStateWrites(a).keys()].map((n) => JSON.stringify(n)).join(", ")}]`
+            : "";
+        // Trailing `;` so the prologue separates cleanly from the verbatim body that
+        // follows it (and from a co-applied behaviour's prologue — composition).
+        return `const __t0 = performance.now(); __replay.action("${a.name}", [${actionPayload(a)}]${writesArg});`;
+    },
+    // Only a state-writing action emits a post-body snapshot (Replay §4.3 rule 3).
+    // The object lists every state: a straight-line write contributes `X: <rhs>`,
+    // an unwritten state contributes its current binding (bare `X`).
+    actionEpilogue(a, _c, ctx) {
+        if (!ctx.actionWritesState(a))
+            return null;
+        const writes = ctx.straightLineStateWrites(a);
+        const obj = [...ctx.stateNames]
+            .map((n) => (writes.has(n) ? `${n}: ${writes.get(n)}` : n))
+            .join(", ");
+        return `__replay.snapshot({ ${obj} }, __t0)`;
+    },
+    emitResourceHooks(c, ctx) {
+        return c.resources.map((r) => ctx.line(`  useEffect(() => { __replay.resource("${r.name}", ${r.name}.isPending ? "pending" : "resolved") }, [${r.name}.isPending])`));
+    },
+};
+//# sourceMappingURL=replayable.js.map

package/dist/behaviours/replayable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayable.js","sourceRoot":"","sources":["../../src/behaviours/replayable.ts"],"names":[],"mappings":"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"}

package/dist/behaviours/types.d.ts

@@ -0,0 +1,77 @@
+import type { ActionNode, ContainerNode } from "../ast/nodes.ts";
+import type { Emitted } from "../passes/pass-9-codegen.ts";
+/**
+ * The Pass-9 helpers a behaviour's seams receive, rather than closing over
+ * module-private state — this keeps the registry the single dispatch point
+ * (Compiler §4 Pass 9.1).
+ */
+export interface BehaviourEmitCtx {
+    /** Every component `state` name. */
+    readonly stateNames: ReadonlySet<string>;
+    /** State names whose `useState` setter was renamed `__set<X>` (`classifyStateSetters`). */
+    readonly renamedStates: ReadonlySet<string>;
+    /** The identifier a `state X` write lowers to — public `setX` or the renamed `__setX`. */
+    setterNameFor(state: string): string;
+    /** Does this action body write ≥ 1 `state`? (`undoable` augments only writers.) */
+    actionWritesState(a: ActionNode): boolean;
+    /**
+     * Top-level (straight-line) `state = rhs` writes in an action body, as a
+     * `Map<stateName, rhsSourceText>` — what `replayable`'s snapshot object is built
+     * from (Replay §4.3 rule 3). Writes inside a branch/loop/callback are NOT
+     * included (RLIM-08): that field reflects its pre-update binding instead.
+     */
+    straightLineStateWrites(a: ActionNode): Map<string, string>;
+    /** Wrap a boilerplate line as an unmapped `Emitted` (Compiler §8: injected text, no DSL origin). */
+    line(text: string): Emitted;
+}
+/**
+ * One inner-body behaviour the compiler knows how to instrument, keyed by its
+ * `uses` name. `undoable` + `replayable` are the Phase-1 entries. The seam
+ * *values* are owned by the cited specs (Undo §4.2 / Replay §4.3); this
+ * interface is only the *shape* (Compiler §4 Pass 9.1).
+ *
+ * Scope: compiler-native (inner-body) behaviours only — NOT the plugin/HOF
+ * class (`traceable`/`persistent`/`observable`/third-party), which is the
+ * separate, deferred Behaviour Plugin spec.
+ */
+export interface CompilerNativeBehaviour {
+    /** The `uses` name this entry handles (`"undoable"` | `"replayable"`). */
+    readonly name: string;
+    /** Runtime hook the preamble calls + the package it is imported from. */
+    readonly runtime: {
+        readonly hook: string;
+        readonly module: string;
+    };
+    /** React hooks this emission needs, beyond what `state`/`derived`/`action` pull. */
+    readonly reactImports: readonly string[];
+    /** Bare identifiers the preamble introduces into `view`/`action` scope; may be empty. */
+    readonly exposedBindings: readonly string[];
+    /**
+     * The TS type of each exposed binding, keyed by `exposedBindings` name — the
+     * machine-readable type contract the reactra2tsx shadow consumes (D1) so that
+     * `uses undoable` references (`undo`, `redo`, …) type-check instead of `TS2304`.
+     * A binding absent here lowers to `unknown` in the shadow. The compiler does NOT
+     * read this field — emission is unaffected.
+     */
+    readonly exposedTypes?: Readonly<Record<string, string>>;
+    /** Widen an augmented action's `useCallback` deps to all state names? */
+    readonly widensAugmentedActionDeps: boolean;
+    /** Lines emitted after `state`/`derived`/`ref` and before the actions (preamble + any mount/unmount effect). */
+    emitPreamble(c: ContainerNode, ctx: BehaviourEmitCtx): Emitted[];
+    /** Does this behaviour instrument action `a` at all? */
+    augmentsAction(a: ActionNode, c: ContainerNode, ctx: BehaviourEmitCtx): boolean;
+    /** Statement(s) prepended inside an augmented action body, before the user code. `null` = none. */
+    actionPrologue(a: ActionNode, c: ContainerNode, ctx: BehaviourEmitCtx): string | null;
+    /**
+     * Statement(s) appended inside an augmented action body, after the user code.
+     * `null` = none. (`undoable` returns `null`; the epilogue emission site lands
+     * with `replayable` — Piece A step 2 — since it is the first user.)
+     */
+    actionEpilogue(a: ActionNode, c: ContainerNode, ctx: BehaviourEmitCtx): string | null;
+    /**
+     * Lines emitted after the actions, e.g. one per-resource status `useEffect`.
+     * (`undoable` returns `[]`; the emission site lands with `replayable` — step 2.)
+     */
+    emitResourceHooks(c: ContainerNode, ctx: BehaviourEmitCtx): Emitted[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/behaviours/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/behaviours/types.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAA;AAE1D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3C,0FAA0F;IAC1F,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACpC,mFAAmF;IACnF,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAA;IACzC;;;;;OAKG;IACH,uBAAuB,CAAC,CAAC,EAAE,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3D,oGAAoG;IACpG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC5B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACpE,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACxD,yEAAyE;IACzE,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAA;IAE3C,gHAAgH;IAChH,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,EAAE,CAAA;IAChE,wDAAwD;IACxD,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAA;IAC/E,mGAAmG;IACnG,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAA;IACrF;;;;OAIG;IACH,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAA;IACrF;;;OAGG;IACH,iBAAiB,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,EAAE,CAAA;CACtE"}

package/dist/behaviours/types.js

@@ -0,0 +1,10 @@
+// @reactra/babel-plugin — compiler-native behaviour registry types.
+//
+// Owner spec: reactra-compiler-spec.md §4 Pass 9.1. A `CompilerNativeBehaviour`
+// generalises the inner-body instrumentation that `uses undoable` / `uses
+// replayable` inject (Component DSL §9 "compiler-native behaviours"), so Pass 9
+// dispatches through a table keyed by `uses` name instead of per-name branches.
+// This file is the registry SHAPE; each behaviour's seam VALUES are owned by its
+// spec (Undo spec §4.2 / Replay spec §4.3) and live in the per-behaviour module.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/behaviours/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/behaviours/types.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF"}

package/dist/behaviours/undoable.d.ts

@@ -0,0 +1,10 @@
+import type { CompilerNativeBehaviour } from "./types.ts";
+/**
+ * `uses undoable` — inner-body undo/redo instrumentation (Undo spec §4).
+ * Seams: a preamble (`__undo` ring buffer + `__snapshot`/`__restore` closures +
+ * the exposed `undo`/`redo`/… bindings) and a per-state-writing-action prologue
+ * (`__undo.push(__snapshot())`) whose deps widen to all state names. No epilogue,
+ * no resource hooks.
+ */
+export declare const undoableBehaviour: CompilerNativeBehaviour;
+//# sourceMappingURL=undoable.d.ts.map

package/dist/behaviours/undoable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undoable.d.ts","sourceRoot":"","sources":["../../src/behaviours/undoable.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,uBAoD/B,CAAA"}

package/dist/behaviours/undoable.js

@@ -0,0 +1,62 @@
+// @reactra/babel-plugin — `uses undoable` as a compiler-native behaviour entry.
+//
+// Owner spec: reactra-undo-spec.md §4 (seam values) + reactra-compiler-spec.md
+// §4 Pass 9.1 (the registry shape this implements). Lifted verbatim from the
+// former inline `emitUndoablePreamble` + `isUndoable` action path in Pass 9 —
+// emitted output is byte-identical (golden-suite guarded).
+/**
+ * `uses undoable` — inner-body undo/redo instrumentation (Undo spec §4).
+ * Seams: a preamble (`__undo` ring buffer + `__snapshot`/`__restore` closures +
+ * the exposed `undo`/`redo`/… bindings) and a per-state-writing-action prologue
+ * (`__undo.push(__snapshot())`) whose deps widen to all state names. No epilogue,
+ * no resource hooks.
+ */
+export const undoableBehaviour = {
+    name: "undoable",
+    runtime: { hook: "useUndoHistory", module: "@reactra/behaviours/undoable" },
+    // The preamble's undo/redo/clearHistory are `useCallback` even when the
+    // component declares no actions (Undo spec §4.1).
+    reactImports: ["useCallback"],
+    exposedBindings: ["undo", "redo", "canUndo", "canRedo", "historySize", "clearHistory"],
+    // Shadow type contract (D1) — matches what `useUndoHistory` exposes via the preamble.
+    exposedTypes: {
+        undo: "() => void",
+        redo: "() => void",
+        canUndo: "boolean",
+        canRedo: "boolean",
+        historySize: "number",
+        clearHistory: "() => void",
+    },
+    widensAugmentedActionDeps: true,
+    emitPreamble(c, ctx) {
+        const names = c.states.map((s) => s.name);
+        const snapshot = `{ ${names.join(", ")} }`;
+        const restore = names.map((n) => `${ctx.setterNameFor(n)}(s.${n})`).join("; ");
+        const deps = names.join(", ");
+        return [
+            ctx.line(`  const __undo = useUndoHistory({ maxHistory: 50 })`),
+            ctx.line(`  const __snapshot = () => (${snapshot})`),
+            ctx.line(`  const __restore = (s) => { ${restore} }`),
+            ctx.line(`  const undo = useCallback(() => { const s = __undo.undo(__snapshot()); if (s) __restore(s) }, [${deps}])`),
+            ctx.line(`  const redo = useCallback(() => { const s = __undo.redo(__snapshot()); if (s) __restore(s) }, [${deps}])`),
+            ctx.line(`  const canUndo = __undo.canUndo`),
+            ctx.line(`  const canRedo = __undo.canRedo`),
+            ctx.line(`  const historySize = __undo.size`),
+            ctx.line(`  const clearHistory = useCallback(() => __undo.clear(), [])`),
+        ];
+    },
+    // Only state-writing actions get a snapshot (Undo spec §4.2 rule 2).
+    augmentsAction(a, _c, ctx) {
+        return ctx.actionWritesState(a);
+    },
+    actionPrologue() {
+        return "__undo.push(__snapshot());";
+    },
+    actionEpilogue() {
+        return null;
+    },
+    emitResourceHooks() {
+        return [];
+    },
+};
+//# sourceMappingURL=undoable.js.map

package/dist/behaviours/undoable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undoable.js","sourceRoot":"","sources":["../../src/behaviours/undoable.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,8EAA8E;AAC9E,2DAA2D;AAI3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA4B;IACxD,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,8BAA8B,EAAE;IAC3E,wEAAwE;IACxE,kDAAkD;IAClD,YAAY,EAAE,CAAC,aAAa,CAAC;IAC7B,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,CAAC;IACtF,sFAAsF;IACtF,YAAY,EAAE;QACZ,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,SAAS;QAClB,WAAW,EAAE,QAAQ;QACrB,YAAY,EAAE,YAAY;KAC3B;IACD,yBAAyB,EAAE,IAAI;IAE/B,YAAY,CAAC,CAAC,EAAE,GAAG;QACjB,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACzC,MAAM,QAAQ,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;QAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7B,OAAO;YACL,GAAG,CAAC,IAAI,CAAC,qDAAqD,CAAC;YAC/D,GAAG,CAAC,IAAI,CAAC,+BAA+B,QAAQ,GAAG,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,gCAAgC,OAAO,IAAI,CAAC;YACrD,GAAG,CAAC,IAAI,CAAC,mGAAmG,IAAI,IAAI,CAAC;YACrH,GAAG,CAAC,IAAI,CAAC,mGAAmG,IAAI,IAAI,CAAC;YACrH,GAAG,CAAC,IAAI,CAAC,kCAAkC,CAAC;YAC5C,GAAG,CAAC,IAAI,CAAC,kCAAkC,CAAC;YAC5C,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC;YAC7C,GAAG,CAAC,IAAI,CAAC,8DAA8D,CAAC;SACzE,CAAA;IACH,CAAC;IAED,qEAAqE;IACrE,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG;QACvB,OAAO,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAA;IACjC,CAAC;IAED,cAAc;QACZ,OAAO,4BAA4B,CAAA;IACrC,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAA;IACb,CAAC;IAED,iBAAiB;QACf,OAAO,EAAE,CAAA;IACX,CAAC;CACF,CAAA"}

package/dist/compile.d.ts

@@ -0,0 +1,69 @@
+import type { RawSourceMap } from "./preprocess/index.ts";
+import type { Rewrite } from "./preprocess/types.ts";
+import type { FileGraph } from "./ast/nodes.ts";
+export interface CompileResult {
+    /** Final React 19 TSX source */
+    code: string;
+    /** The intermediate graph (useful for tests, devtools, sidecars) */
+    graph: FileGraph;
+    /**
+     * v3 **composed** source→compiled map (`#10-followup`, Compiler §8). Pass 9
+     * records one segment per user-code slice (`state`/`derived`/`action`/
+     * `resource`/`view`/`effect`/`mount` in components); `compile()` composes
+     * those through the preprocess map to DSL `(line, col)`. Compiler-injected
+     * boilerplate is unmapped by design. `sourcesContent` carries the DSL.
+     * `sourceFile` defaults to `"input.tsx"`; the Vite plugin passes the real `id`.
+     */
+    map: RawSourceMap;
+    /**
+     * The ordered list of rewrite operations produced by the preprocessor.
+     * Consumed by the language-tools shadow emitter to compose
+     * shadow→preprocessed positions all the way back to DSL offsets.
+     * Additive field — callers that ignore it are unaffected.
+     */
+    rewrites: Rewrite[];
+}
+/**
+ * The graph-only result: everything a consumer needs WITHOUT running codegen.
+ * Returned by {@link compileToGraph} for callers (the LSP) that read only the
+ * intermediate graph + rewrites and never need the emitted `code`/`map`.
+ */
+export interface GraphResult {
+    /** The intermediate graph (Pass 2 extract + Pass 3 read-sets). */
+    graph: FileGraph;
+    /** Preprocessor rewrite operations (shadow→DSL position composition). */
+    rewrites: Rewrite[];
+}
+/**
+ * Compile Reactra DSL to the intermediate {@link GraphResult} WITHOUT codegen.
+ *
+ * The LSP/language-tools path consumes only `.graph` + `.rewrites`; running the
+ * full {@link compile} (including Pass 9 codegen) on every keystroke is wasted
+ * work (framework-review A5). This is the same prefix `compile` runs — they
+ * share {@link runToGraph}, so there is no second pipeline to drift.
+ *
+ * @param source raw Reactra source (.tsx with DSL keywords)
+ * @returns the intermediate graph + preprocessor rewrites (no emitted code)
+ */
+export declare const compileToGraph: (source: string) => GraphResult;
+/**
+ * Options accepted by {@link compile}. All are optional; omitting them
+ * yields the same behaviour as the original single-argument call.
+ */
+export interface CompileOptions {
+    /**
+     * Source file path to embed in the returned source map's `sources[0]`
+     * + `file` fields. Vite's plugin layer threads its module `id` here.
+     * Defaults to `"input.tsx"` for self-contained smoke tests.
+     */
+    readonly sourceFile?: string;
+}
+/**
+ * Compile Reactra DSL source to React 19 TSX.
+ *
+ * @param source raw Reactra source (.tsx with DSL keywords)
+ * @param opts   build-time options; see {@link CompileOptions}
+ * @returns object with `code` (compiled TSX) and `graph` (intermediate)
+ */
+export declare const compile: (source: string, opts?: CompileOptions) => CompileResult;
+//# sourceMappingURL=compile.d.ts.map

package/dist/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAKpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,GAAG,EAAE,YAAY,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,KAAK,EAAE,SAAS,CAAA;IAChB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB;AAqBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,WAG/C,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAI7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,OAAM,cAAmB,KAAG,aAqBnE,CAAA"}

package/dist/compile.js

@@ -0,0 +1,75 @@
+// Top-level Reactra compile entry point.
+//
+// Combines the pipeline:
+//   preprocess -> @babel/parser -> Pass 2 extract -> Pass 3 read-set -> Pass 9 codegen
+//
+// Phase-1 MVP: components compile to runnable React 19; stores and
+// services emit placeholder factories (real wiring is Wave 3.3).
+import { composeSourceMap, preprocess } from "./preprocess/index.js";
+import { parsePreprocessed } from "./passes/pass-1-parse.js";
+import { extractGraph } from "./passes/pass-2-extract.js";
+import { analyzeReadSets } from "./passes/pass-3-readset.js";
+import { codegen } from "./passes/pass-9-codegen.js";
+/**
+ * The shared pipeline prefix: preprocess → parse → extract → read-sets, stopping
+ * before codegen. BOTH {@link compileToGraph} and {@link compile} consume this —
+ * the prefix exists exactly once, so a graph consumed via `compileToGraph` can
+ * never structurally drift from the graph `compile` emits (framework-review B1).
+ * `preprocessed` is returned for `compile`'s source-map composition; it is not
+ * part of the public {@link GraphResult}.
+ */
+const runToGraph = (source) => {
+    const { code: preprocessed, rewrites } = preprocess(source);
+    const ast = parsePreprocessed(preprocessed);
+    const graph = extractGraph(source, preprocessed, ast);
+    // Pass 3 — read-set analysis: populate `deps` on component derived/action
+    // nodes so Pass 9 emits real `useMemo`/`useCallback` dependency arrays
+    // instead of the stale-closure `[]`.
+    analyzeReadSets(ast, graph);
+    return { graph, rewrites, preprocessed };
+};
+/**
+ * Compile Reactra DSL to the intermediate {@link GraphResult} WITHOUT codegen.
+ *
+ * The LSP/language-tools path consumes only `.graph` + `.rewrites`; running the
+ * full {@link compile} (including Pass 9 codegen) on every keystroke is wasted
+ * work (framework-review A5). This is the same prefix `compile` runs — they
+ * share {@link runToGraph}, so there is no second pipeline to drift.
+ *
+ * @param source raw Reactra source (.tsx with DSL keywords)
+ * @returns the intermediate graph + preprocessor rewrites (no emitted code)
+ */
+export const compileToGraph = (source) => {
+    const { graph, rewrites } = runToGraph(source);
+    return { graph, rewrites };
+};
+/**
+ * Compile Reactra DSL source to React 19 TSX.
+ *
+ * @param source raw Reactra source (.tsx with DSL keywords)
+ * @param opts   build-time options; see {@link CompileOptions}
+ * @returns object with `code` (compiled TSX) and `graph` (intermediate)
+ */
+export const compile = (source, opts = {}) => {
+    // Shares the pipeline prefix with compileToGraph (single source of truth).
+    // Backlog 1a: `inject store X` resolves its name via `import type { X }`
+    // (cross-file) or a same-file declaration, so codegen no longer reads the
+    // `.reactra.json` sidecar index (the reader was deleted in Session 4).
+    const { graph, rewrites, preprocessed } = runToGraph(source);
+    const { code: compiledCode, marks } = codegen(graph);
+    // #10-followup (Compiler §8): compose the codegen hop (compiled → preprocessed,
+    // via the per-slice `marks`) with the preprocess hop (preprocessed → source)
+    // into a source→compiled map. Compiler boilerplate stays unmapped by design;
+    // `sourcesContent` carries the DSL so devtools always shows the original.
+    const sourceFile = opts.sourceFile ?? "input.tsx";
+    const map = composeSourceMap({
+        source,
+        preprocessed,
+        rewrites,
+        compiled: compiledCode,
+        marks,
+        sourceFile,
+    });
+    return { code: compiledCode, graph, map, rewrites };
+};
+//# sourceMappingURL=compile.js.map

package/dist/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,yBAAyB;AACzB,uFAAuF;AACvF,EAAE;AACF,mEAAmE;AACnE,iEAAiE;AAEjE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AAsCpD;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,MAAc,EAA0C,EAAE;IAC5E,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC3D,MAAM,GAAG,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAA;IAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAA;IACrD,0EAA0E;IAC1E,uEAAuE;IACvE,qCAAqC;IACrC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC3B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;AAC1C,CAAC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAe,EAAE;IAC5D,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC9C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;AAC5B,CAAC,CAAA;AAkBD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,OAAuB,EAAE,EAAiB,EAAE;IAClF,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC5D,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IACpD,gFAAgF;IAChF,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,WAAW,CAAA;IACjD,MAAM,GAAG,GAAG,gBAAgB,CAAC;QAC3B,MAAM;QACN,YAAY;QACZ,QAAQ;QACR,QAAQ,EAAE,YAAY;QACtB,KAAK;QACL,UAAU;KACX,CAAC,CAAA;IACF,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAA;AACrD,CAAC,CAAA"}

package/dist/conventions/index.d.ts

@@ -0,0 +1,110 @@
+import type { ContainerNode, ContainerKind } from "../ast/nodes.ts";
+import { CONTAINER_MARKERS } from "../ast/nodes.ts";
+/** Capitalise the first letter — used for setter names (`foo` → `Foo`). */
+export declare const cap: (s: string) => string;
+/**
+ * Positional order of the four arrows in a `__reactra_await__(resource,
+ * success, pending, error)` marker call. Both emitters index the call's
+ * `arguments` array via these constants so the resource/success/pending/error
+ * branches can never be wired up inconsistently across the two code paths.
+ *
+ * Pass 9: `pass-9-codegen.ts` await rewrite + the error-branch detector.
+ * Shadow: `shadow/emitter.ts` await lowering.
+ */
+export declare const AWAIT_ARG_ORDER: {
+    readonly resource: 0;
+    readonly success: 1;
+    readonly pending: 2;
+    readonly error: 3;
+};
+/**
+ * The identifier `state X` writes lower to (Component DSL §2.1/§2.3). Normally
+ * the auto-emitted public setter `set<Cap(X)>`; but when a non-trivial
+ * `action set<Cap(X)>` owns that public name, the `useState` setter is renamed
+ * `__set<Cap(X)>` so the action and the real setter don't collide (improvements
+ * #4). `renamedStates` holds the state names in the renamed case — compute it
+ * with {@link classifyStateSetters}.
+ */
+export declare const setterNameFor: (stateName: string, renamedStates: ReadonlySet<string>) => string;
+/**
+ * The state name an `action set<Cap(X)>` targets, or `null` if the action name
+ * isn't of that shape. `setFilter` → `filter` (Pascal → camel: lowercase the
+ * first char after `set`); `set`/`setup-with-no-tail` → `null`.
+ *
+ * Exported because the R016 warning (Pass 9) reports the targeted state name.
+ */
+export declare const setterActionTarget: (actionName: string) => string | null;
+/**
+ * Classify `action set<Cap(X)>` declarations that name an existing `state X`
+ * (improvements #4, replacing the Day-21 hard R046 collision):
+ *   - **trivial identity passthrough** → action **suppressed** (the auto-emitted
+ *     `setX` already provides it); the caller emits R016 (warning);
+ *   - **non-trivial** → the action **owns** the public `setX`; its state's
+ *     `useState` setter is **renamed** `__setX` so they don't collide, and
+ *     every `X = expr` write (here and elsewhere) lowers to `__setX`.
+ *
+ * Pure — returns the set of state names to rename and the set of action names
+ * to drop; the R016 warning is emitted by the caller (the single per-component
+ * emit point). Components only — store/service `state`/`action` emit through
+ * other paths, so a non-component container yields empty sets.
+ */
+export declare const classifyStateSetters: (c: ContainerNode) => {
+    renamedStates: Set<string>;
+    suppressedActions: Set<string>;
+};
+/**
+ * Top-level container-wrapper markers, keyed to the `ContainerKind` they map to.
+ * Re-exported from `ast/nodes.ts` so there is exactly one home for the marker
+ * vocabulary (the conventions module). Pass 2 recognises these at the
+ * outer-decl level; the shadow emitter and parity test read them from here.
+ */
+export { CONTAINER_MARKERS };
+export type { ContainerKind };
+/**
+ * Body-level markers emitted by the preprocessor inside a container body and
+ * consumed by Pass 2's body-marker switch (`pass-2-extract.ts`). This is the
+ * authoritative list — the convention-parity test (language-tools) asserts that
+ * every key here is handled by BOTH emitters (or explicitly punted), so a NEW
+ * marker can't be added without a human wiring it on both sides (framework
+ * review §B1: stop the two emitters drifting silently).
+ *
+ * Values are the literal marker strings — kept byte-identical to the strings
+ * the preprocessor emits and Pass 2 switches on. The set is `as const` so the
+ * key type is the exact string-literal union.
+ *
+ * `__reactra_await__` is included: it is a body-level marker, but Pass 2
+ * handles it in a dedicated view-walk (not the flat body switch). The parity
+ * manifest classifies it as VIEW-HANDLED rather than switch-handled.
+ */
+export declare const BODY_MARKERS: {
+    readonly __reactra_state__: "state";
+    readonly __reactra_derived__: "derived";
+    readonly __reactra_action__: "action";
+    readonly __reactra_action_async__: "action";
+    readonly __reactra_resource__: "resource";
+    readonly __reactra_ref__: "ref";
+    readonly __reactra_mount__: "mount";
+    readonly __reactra_cleanup__: "cleanup";
+    readonly __reactra_effect__: "effect";
+    readonly __reactra_effect_on__: "effect";
+    readonly __reactra_view__: "view";
+    readonly __reactra_uses__: "uses";
+    readonly __reactra_inject__: "inject";
+    readonly __reactra_provide__: "provide";
+    readonly __reactra_param__: "param";
+    readonly __reactra_query__: "query";
+    readonly __reactra_meta__: "meta";
+    readonly __reactra_prefetch__: "prefetch";
+    readonly __reactra_transition__: "transition";
+    readonly __reactra_inject_store__: "inject-store";
+    readonly __reactra_inject_store_args__: "inject-store";
+    readonly __reactra_inject_store_keyed__: "inject-store";
+    readonly __reactra_error_boundary__: "errorBoundary";
+    readonly __reactra_suspense__: "suspense";
+    readonly __reactra_input__: "input";
+    readonly __reactra_preserved__: "preserved";
+    readonly __reactra_await__: "await";
+};
+/** A body-marker function name (the keys of {@link BODY_MARKERS}). */
+export type BodyMarker = keyof typeof BODY_MARKERS;
+//# sourceMappingURL=index.d.ts.map

package/dist/conventions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conventions/index.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAc,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAMnD,2EAA2E;AAC3E,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAgD,CAAA;AAMhF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAMV;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,EAAE,eAAe,WAAW,CAAC,MAAM,CAAC,KAAG,MACJ,CAAA;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,YAAY,MAAM,KAAG,MAAM,GAAG,IAKhE,CAAA;AA+BD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAC/B,GAAG,aAAa,KACf;IAAE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAY9D,CAAA;AAMD;;;;;GAKG;AACH,OAAO,EAAE,iBAAiB,EAAE,CAAA;AAC5B,YAAY,EAAE,aAAa,EAAE,CAAA;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4Bf,CAAA;AAEV,sEAAsE;AACtE,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,YAAY,CAAA"}