@reactra/vite-plugin 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akhil Shastri and the Reactra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @reactra/vite-plugin
+
+> Reactra Vite plugin — wires the Reactra compiler and file-based route manifest into Vite.
+
+**Alpha** — published under the npm dist-tag `alpha`. APIs may change before 1.0.
+
+```bash
+npm install @reactra/vite-plugin@alpha
+```
+
+Part of [Reactra](https://github.com/akhilshastri/reactra) — a compiler-first,
+React-19-compatible framework. See the [documentation](https://reactra-docs.vercel.app) to get
+started.
+
+## License
+
+MIT

package/dist/esbuild-prescan.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal structural type for esbuild's `Plugin` interface — we don't
+ * import esbuild at type-position to keep this file resolvable under
+ * Bun without esbuild's full type tree.
+ */
+export interface EsbuildPluginBuild {
+    onLoad(opts: {
+        filter: RegExp;
+        namespace?: string;
+    }, cb: (args: {
+        path: string;
+    }) => {
+        contents: string;
+        loader: string;
+    } | null): void;
+}
+export interface EsbuildPlugin {
+    readonly name: string;
+    setup(build: EsbuildPluginBuild): void;
+}
+/**
+ * esbuild plugin factory — registers an `onLoad` callback that
+ * preprocesses Reactra DSL files before esbuild's parser sees them.
+ *
+ * The Vite plugin's `config()` hook injects this into
+ * `config.optimizeDeps.esbuildOptions.plugins` so the dep-scan phase
+ * runs through it. Once Vite's dev server is up, the regular
+ * `transform()` hook takes over for per-request compiles.
+ */
+export declare const reactraEsbuildPlugin: EsbuildPlugin;
+//# sourceMappingURL=esbuild-prescan.d.ts.map

package/dist/esbuild-prescan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-prescan.d.ts","sourceRoot":"","sources":["../src/esbuild-prescan.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CACJ,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5C,EAAE,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAC1E,IAAI,CAAA;CACR;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAA;CACvC;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAmClC,CAAA"}

package/dist/esbuild-prescan.js

@@ -0,0 +1,75 @@
+// esbuild plugin for Vite's dep-scan pre-bundling phase (Day 24 / `#15`).
+//
+// Vite's `optimizeDeps` runs esbuild over the entry's import graph
+// BEFORE the dev server starts serving requests — so the Vite
+// `transform()` hook hasn't fired yet. esbuild's scanner sees raw
+// DSL keywords (`export component Foo {`, `route store X {`, etc.)
+// and bails with "Unexpected component" / "Expected ';' but found
+// 'store'" parse errors. Result: the dreaded "Failed to run
+// dependency scan" warning at first dev-server boot. On-demand
+// serving still works because the transform pipeline does fire on
+// each request, but pre-bundling is skipped and the user sees a
+// scary-looking stack trace they have to learn to ignore.
+//
+// Fix: register an esbuild `onLoad` callback for `.tsx/.ts/.jsx/.js`
+// files. When the file's source contains a Reactra container keyword,
+// run `compile()` to produce React-19 TSX before esbuild's parser
+// sees it. Otherwise return `null` so esbuild's default loaders take
+// over. Cheap regex gate — same `containsReactraDsl` predicate the
+// Vite `transform` hook uses, so the per-file cost is the same.
+//
+// This module exports a plain esbuild Plugin (not a Vite plugin);
+// the Vite plugin's `config()` hook wires it into
+// `config.optimizeDeps.esbuildOptions.plugins`.
+import { readFileSync } from "node:fs";
+import { compile, containsReactraDsl } from "@reactra/babel-plugin";
+const SUPPORTED_RE = /\.(?:tsx|jsx|ts|js)$/;
+/**
+ * esbuild plugin factory — registers an `onLoad` callback that
+ * preprocesses Reactra DSL files before esbuild's parser sees them.
+ *
+ * The Vite plugin's `config()` hook injects this into
+ * `config.optimizeDeps.esbuildOptions.plugins` so the dep-scan phase
+ * runs through it. Once Vite's dev server is up, the regular
+ * `transform()` hook takes over for per-request compiles.
+ */
+export const reactraEsbuildPlugin = {
+    name: "@reactra/esbuild-prescan",
+    setup(build) {
+        build.onLoad({ filter: SUPPORTED_RE }, (args) => {
+            let source;
+            try {
+                source = readFileSync(args.path, "utf8");
+            }
+            catch {
+                // File unreadable — let esbuild's default loader try (and
+                // emit its own clearer error).
+                return null;
+            }
+            if (!containsReactraDsl(source))
+                return null;
+            // The pre-scan phase only needs source good enough for esbuild
+            // to discover IMPORTS — it doesn't actually execute the code.
+            // We still run the full compile() because:
+            //   (1) it's already cheap on Reactra files (no IR, no Babel
+            //       round-trip — single-pass preprocess + template emit);
+            //   (2) the resulting React-19 TSX has the same import-set as
+            //       the original source, so esbuild scans the right deps;
+            //   (3) handing esbuild anything less risks subtle scan-vs-
+            //       transform divergence at runtime (different deps pre-
+            //       bundled than the page actually uses).
+            try {
+                const { code } = compile(source, { sourceFile: args.path });
+                return { contents: code, loader: "tsx" };
+            }
+            catch {
+                // If our compile fails here, fall through to esbuild's
+                // default loader — it'll produce a similar error but at the
+                // correct phase (the regular transform also runs compile,
+                // so a real syntax error surfaces there with our diagnostics).
+                return null;
+            }
+        });
+    },
+};
+//# sourceMappingURL=esbuild-prescan.js.map

package/dist/esbuild-prescan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild-prescan.js","sourceRoot":"","sources":["../src/esbuild-prescan.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,mEAAmE;AACnE,8DAA8D;AAC9D,kEAAkE;AAClE,mEAAmE;AACnE,kEAAkE;AAClE,4DAA4D;AAC5D,+DAA+D;AAC/D,kEAAkE;AAClE,gEAAgE;AAChE,0DAA0D;AAC1D,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,kEAAkE;AAClE,qEAAqE;AACrE,mEAAmE;AACnE,gEAAgE;AAChE,EAAE;AACF,kEAAkE;AAClE,kDAAkD;AAClD,gDAAgD;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAmBnE,MAAM,YAAY,GAAG,sBAAsB,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkB;IACjD,IAAI,EAAE,0BAA0B;IAChC,KAAK,CAAC,KAAK;QACT,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;YAC9C,IAAI,MAAc,CAAA;YAClB,IAAI,CAAC;gBACH,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;gBAC1D,+BAA+B;gBAC/B,OAAO,IAAI,CAAA;YACb,CAAC;YACD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC5C,+DAA+D;YAC/D,8DAA8D;YAC9D,2CAA2C;YAC3C,6DAA6D;YAC7D,8DAA8D;YAC9D,8DAA8D;YAC9D,8DAA8D;YAC9D,4DAA4D;YAC5D,6DAA6D;YAC7D,8CAA8C;YAC9C,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;gBAC3D,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,uDAAuD;gBACvD,4DAA4D;gBAC5D,0DAA0D;gBAC1D,+DAA+D;gBAC/D,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;CACF,CAAA"}

package/dist/extract.d.ts

@@ -0,0 +1,128 @@
+import type { ContainerNode } from "@reactra/babel-plugin";
+/**
+ * One discovered container (component / store / service) extracted from a
+ * single source file via {@link extractContainers}.
+ */
+export interface ContainerInfo {
+    /** `"component" | "store" | "service"` — derived from the marker name. */
+    readonly kind: "component" | "store" | "service";
+    readonly name: string;
+    /** True when the declaration carries `export` (v2 independent export token). */
+    readonly exported: boolean;
+    /**
+     * Service modifier (`"scoped" | "server"`) when present; undefined for
+     * plain `service X {}` and for stores/components.
+     */
+    readonly serviceModifier?: string;
+    /**
+     * Names of every `inject service X` site inside this container's body —
+     * used by {@link collectServiceInjectionDiagnostics} to find injection
+     * sites that reference undeclared services.
+     */
+    readonly injectedServiceNames: string[];
+}
+/**
+ * Project the already-compiled container graph into the three-way
+ * {@link ContainerInfo}. The pure half of {@link extractContainers}, split out
+ * so the A3 graph cache can derive from a single per-file compile (the scanner
+ * passes a cached `ContainerNode[]` instead of re-reading + re-compiling).
+ */
+export declare const containersToInfo: (containers: readonly ContainerNode[]) => ContainerInfo[];
+/**
+ * Extract all containers (components, stores, services) from a raw DSL source
+ * file via the compiled graph. `injectedServiceNames` is read from each
+ * container's `injects` list (no body-boundary guessing — a mis-attribution-
+ * proof replacement for the old "next top-level const" slice heuristic).
+ *
+ * Returns `[]` on malformed source — callers must treat an empty result as
+ * "no containers" rather than an error.
+ */
+export declare const extractContainers: (source: string) => ContainerInfo[];
+/**
+ * Extract the first `export component <Name>` declaration name from `source`.
+ * Returns `null` when no exported component is found (plain React TSX, no
+ * DSL container, or a malformed file).
+ *
+ * Replaces `extractPageComponentName` in walker.ts — fixes the R2 regression
+ * where the old regex missed `export component Foo uses traceable {` (the
+ * header-`uses` form). The graph normalises all header forms before we read.
+ */
+export declare const extractComponentName: (source: string) => string | null;
+/** Container-graph half of {@link extractComponentName} (A3 cache path). */
+export declare const componentNameFromContainers: (containers: readonly ContainerNode[]) => string | null;
+/**
+ * Extract the FIRST component's `prefetch` trigger from `source` via the
+ * compiled graph (`container.prefetch.trigger`). Returns the trigger word, or
+ * `undefined` when the file has no component, no `prefetch` declaration, or is
+ * malformed.
+ *
+ * First-component-wins matches the existing manifest semantics (one prefetch
+ * policy per page). Reads the graph rather than line-regexing the raw DSL, so
+ * the header-`uses` form (`export component X uses traceable { prefetch … }`)
+ * is recognised — the same regression class that produced the header-`uses`
+ * walker bug (B5).
+ */
+export declare const extractPrefetch: (source: string) => "hover" | "visible" | "mount" | "none" | undefined;
+/** Container-graph half of {@link extractPrefetch} (A3 cache path). */
+export declare const prefetchFromContainers: (containers: readonly ContainerNode[]) => "hover" | "visible" | "mount" | "none" | undefined;
+/**
+ * One `query` declaration extracted from a page component. Shape is unchanged
+ * from the existing `RouteQueryDecl` in walker.ts — only the extraction
+ * mechanism changes.
+ */
+export interface QueryDecl {
+    readonly name: string;
+    readonly tsType: string;
+}
+/**
+ * Extract `query` declarations from `source` via the compiled graph
+ * (`container.queries`, source-ordered). Returns `[]` for files with no
+ * queries, malformed files, or non-component files.
+ *
+ * C5 (B5): folded off `QUERY_MARKER_RE` onto the graph — `QueryNode.tsType` is
+ * the already-decoded StringLiteral value from Pass 2, so the v2 semicolon leak
+ * and the manual `\"`-unescaping the old regex carried are both gone for free.
+ * `tsType` defaults to `"string"` in Pass 2, matching the prior fallback. Inline
+ * `inject store s(query foo)` args never produce a `QueryNode`, so they're
+ * excluded as before.
+ */
+export declare const extractQueries: (source: string) => QueryDecl[];
+/** Container-graph half of {@link extractQueries} (A3 cache path). */
+export declare const queriesFromContainers: (containers: readonly ContainerNode[]) => QueryDecl[];
+/**
+ * Extract every store declaration from `source`. Returns `{ name, exported }`
+ * pairs. Non-exported stores are included so callers can filter by `exported`.
+ *
+ * Replaces `STORE_DECL_RE` / `extractStoreNames` in walker.ts with a
+ * graph-based approach that correctly handles:
+ *   - v2 `export app store X` / `export subtree store X "/p"` forms
+ *   - header-`uses` `export store X uses undoable`
+ *   - non-exported `app store X` / `route store X`
+ *   - keyed `route store X(key: string)`
+ */
+export declare const extractStoreNames: (source: string) => {
+    name: string;
+    exported: boolean;
+}[];
+/** Container-graph half of {@link extractStoreNames} (A3 cache path). */
+export declare const storeNamesFromContainers: (containers: readonly ContainerNode[]) => {
+    name: string;
+    exported: boolean;
+}[];
+/**
+ * Extract every service declaration from `source`. Returns
+ * `{ name, exported, serviceModifier? }` triples. Non-exported services are
+ * included so callers can filter by `exported`.
+ */
+export declare const extractServiceNames: (source: string) => {
+    name: string;
+    exported: boolean;
+    serviceModifier?: string;
+}[];
+/** Container-graph half of {@link extractServiceNames} (A3 cache path). */
+export declare const serviceNamesFromContainers: (containers: readonly ContainerNode[]) => {
+    name: string;
+    exported: boolean;
+    serviceModifier?: string;
+}[];
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAIzE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,EAAE,CAAA;CACxC;AAoDD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,YAAY,SAAS,aAAa,EAAE,KACnC,aAAa,EAOX,CAAA;AAEL;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG,aAAa,EACtB,CAAA;AAI1C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,IACV,CAAA;AAErD,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,GACtC,YAAY,SAAS,aAAa,EAAE,KACnC,MAAM,GAAG,IAIX,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,KACb,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SACI,CAAA;AAEhD,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,GACjC,YAAY,SAAS,aAAa,EAAE,KACnC,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SACuB,CAAA;AAEnE;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,SAAS,EACV,CAAA;AAE/C,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAChC,YAAY,SAAS,aAAa,EAAE,KACnC,SAAS,EAGT,CAAA;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EACpC,CAAA;AAElD,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,GACnC,YAAY,SAAS,aAAa,EAAE,KACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAGgB,CAAA;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,KACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EACZ,CAAA;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,GACrC,YAAY,SAAS,aAAa,EAAE,KACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EAGwB,CAAA"}

package/dist/extract.js

@@ -0,0 +1,155 @@
+// @reactra/vite-plugin — parse-based container extraction
+//
+// Owner: reactra-compiler-spec.md §4 Pass 1.1 (preprocess markers) +
+//        reactra-router-spec.md §5.1 (manifest format) +
+//        Phase 3 ADR-1 (reuse the compiler — single grammar source of truth).
+//
+// Each exported function calls `compileToGraph()` once per file and reads the
+// intermediate FileGraph (Pass 2 extract). This replaces the hand-rolled regex
+// passes in walker.ts AND the marker-regex / body-slice heuristics this file
+// used to carry — the R2/B5 regression mitigation: the walker now shares the
+// compiler's exact grammar for header-`uses` forms, v2 store/service lifetimes,
+// and `inject` site classification (no body-boundary guessing).
+import { compileToGraph } from "@reactra/babel-plugin";
+// ─── graph helper ─────────────────────────────────────────────────────────────
+/**
+ * Run `compileToGraph()` on `source` and return its `containers`, or `[]` on
+ * any failure (malformed / mid-edit file). The try/catch is intentional: a
+ * broken source file must not crash the manifest regen loop — every public
+ * function below degrades to its documented empty / null fallback.
+ *
+ * READ-ONLY (C1): consumers read existing graph fields; codegen is never run.
+ */
+const containerNodes = (source) => {
+    try {
+        return compileToGraph(source).graph.containers;
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Collapse the compiler's five-way {@link ContainerKind} into the three-way
+ * `ContainerInfo.kind` the walker consumes. The three store lifetimes
+ * (`route-store` / `session-store` / `export-store`) all surface as `"store"`.
+ *
+ * Exhaustive by construction: a 4th store kind added to {@link ContainerKind}
+ * makes the `default` branch a `never`-assignment compile error (C2) — so a
+ * future store lifetime can never be silently dropped from the manifest.
+ */
+const toInfoKind = (kind) => {
+    switch (kind) {
+        case "component":
+            return "component";
+        case "service":
+            return "service";
+        case "route-store":
+        case "session-store":
+        case "export-store":
+            return "store";
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+};
+/** Service-injection-site names for a container, read straight from the graph. */
+const injectedServiceNamesOf = (c) => c.injects.filter((i) => i.serviceKind === "service").map((i) => i.name);
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Project the already-compiled container graph into the three-way
+ * {@link ContainerInfo}. The pure half of {@link extractContainers}, split out
+ * so the A3 graph cache can derive from a single per-file compile (the scanner
+ * passes a cached `ContainerNode[]` instead of re-reading + re-compiling).
+ */
+export const containersToInfo = (containers) => containers.map((c) => ({
+    kind: toInfoKind(c.kind),
+    name: c.name,
+    exported: c.exported,
+    serviceModifier: c.serviceModifier,
+    injectedServiceNames: injectedServiceNamesOf(c),
+}));
+/**
+ * Extract all containers (components, stores, services) from a raw DSL source
+ * file via the compiled graph. `injectedServiceNames` is read from each
+ * container's `injects` list (no body-boundary guessing — a mis-attribution-
+ * proof replacement for the old "next top-level const" slice heuristic).
+ *
+ * Returns `[]` on malformed source — callers must treat an empty result as
+ * "no containers" rather than an error.
+ */
+export const extractContainers = (source) => containersToInfo(containerNodes(source));
+// ─── Focused extract fns (used by walker.ts) ──────────────────────────────────
+/**
+ * Extract the first `export component <Name>` declaration name from `source`.
+ * Returns `null` when no exported component is found (plain React TSX, no
+ * DSL container, or a malformed file).
+ *
+ * Replaces `extractPageComponentName` in walker.ts — fixes the R2 regression
+ * where the old regex missed `export component Foo uses traceable {` (the
+ * header-`uses` form). The graph normalises all header forms before we read.
+ */
+export const extractComponentName = (source) => componentNameFromContainers(containerNodes(source));
+/** Container-graph half of {@link extractComponentName} (A3 cache path). */
+export const componentNameFromContainers = (containers) => {
+    // Route pages are `export component` — only EXPORTED components qualify.
+    const component = containers.find((c) => c.kind === "component" && c.exported);
+    return component?.name ?? null;
+};
+/**
+ * Extract the FIRST component's `prefetch` trigger from `source` via the
+ * compiled graph (`container.prefetch.trigger`). Returns the trigger word, or
+ * `undefined` when the file has no component, no `prefetch` declaration, or is
+ * malformed.
+ *
+ * First-component-wins matches the existing manifest semantics (one prefetch
+ * policy per page). Reads the graph rather than line-regexing the raw DSL, so
+ * the header-`uses` form (`export component X uses traceable { prefetch … }`)
+ * is recognised — the same regression class that produced the header-`uses`
+ * walker bug (B5).
+ */
+export const extractPrefetch = (source) => prefetchFromContainers(containerNodes(source));
+/** Container-graph half of {@link extractPrefetch} (A3 cache path). */
+export const prefetchFromContainers = (containers) => containers.find((c) => c.kind === "component")?.prefetch?.trigger;
+/**
+ * Extract `query` declarations from `source` via the compiled graph
+ * (`container.queries`, source-ordered). Returns `[]` for files with no
+ * queries, malformed files, or non-component files.
+ *
+ * C5 (B5): folded off `QUERY_MARKER_RE` onto the graph — `QueryNode.tsType` is
+ * the already-decoded StringLiteral value from Pass 2, so the v2 semicolon leak
+ * and the manual `\"`-unescaping the old regex carried are both gone for free.
+ * `tsType` defaults to `"string"` in Pass 2, matching the prior fallback. Inline
+ * `inject store s(query foo)` args never produce a `QueryNode`, so they're
+ * excluded as before.
+ */
+export const extractQueries = (source) => queriesFromContainers(containerNodes(source));
+/** Container-graph half of {@link extractQueries} (A3 cache path). */
+export const queriesFromContainers = (containers) => containers.flatMap((c) => c.queries.map((q) => ({ name: q.name, tsType: q.tsType.trim() || "string" })));
+/**
+ * Extract every store declaration from `source`. Returns `{ name, exported }`
+ * pairs. Non-exported stores are included so callers can filter by `exported`.
+ *
+ * Replaces `STORE_DECL_RE` / `extractStoreNames` in walker.ts with a
+ * graph-based approach that correctly handles:
+ *   - v2 `export app store X` / `export subtree store X "/p"` forms
+ *   - header-`uses` `export store X uses undoable`
+ *   - non-exported `app store X` / `route store X`
+ *   - keyed `route store X(key: string)`
+ */
+export const extractStoreNames = (source) => storeNamesFromContainers(containerNodes(source));
+/** Container-graph half of {@link extractStoreNames} (A3 cache path). */
+export const storeNamesFromContainers = (containers) => containersToInfo(containers)
+    .filter((c) => c.kind === "store")
+    .map(({ name, exported }) => ({ name, exported }));
+/**
+ * Extract every service declaration from `source`. Returns
+ * `{ name, exported, serviceModifier? }` triples. Non-exported services are
+ * included so callers can filter by `exported`.
+ */
+export const extractServiceNames = (source) => serviceNamesFromContainers(containerNodes(source));
+/** Container-graph half of {@link extractServiceNames} (A3 cache path). */
+export const serviceNamesFromContainers = (containers) => containersToInfo(containers)
+    .filter((c) => c.kind === "service")
+    .map(({ name, exported, serviceModifier }) => ({ name, exported, serviceModifier }));
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

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

package/dist/fingerprint.d.ts

@@ -0,0 +1,28 @@
+import type { ContainerNode } from "@reactra/babel-plugin";
+/**
+ * The declaration set of one source file that the manifest + resource-names
+ * output depends on. All arrays are sorted for order-insensitive comparison
+ * (declaration order in the file doesn't affect the generated output —
+ * scanStores/scanServices/collectResourceNames all sort their results).
+ */
+export interface DeclFingerprint {
+    /** Sorted store binding names declared in the file. */
+    readonly stores: string[];
+    /** Sorted service binding names declared in the file. */
+    readonly services: string[];
+    /** Sorted `name:modifier` pairs (modifier = "" when none) — flips a regen. */
+    readonly serviceModifiers: string[];
+    /** Sorted resource names declared across the file's containers. */
+    readonly resources: string[];
+}
+/**
+ * Derive a {@link DeclFingerprint} from a file's compiled containers. Pure:
+ * same containers → identical fingerprint. Caller supplies the cached
+ * `containersFor(path)` result so no extra compile is paid.
+ */
+export declare const fingerprintOf: (containers: readonly ContainerNode[]) => DeclFingerprint;
+/** True when two fingerprints declare the same set of stores/services/resources. */
+export declare const fingerprintsEqual: (a: DeclFingerprint, b: DeclFingerprint) => boolean;
+/** True when `path` is a page file (under `src/pages/`) — routes/queries/prefetch live here. */
+export declare const isPagesFile: (projectRoot: string, eventPath: string) => boolean;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IACzB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IACnC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAC7B;AAQD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,YAAY,SAAS,aAAa,EAAE,KACnC,eAoBF,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,GAAI,GAAG,eAAe,EAAE,GAAG,eAAe,KAAG,OAS1E,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,WAAW,GAAI,aAAa,MAAM,EAAE,WAAW,MAAM,KAAG,OAKpE,CAAA"}

package/dist/fingerprint.js

@@ -0,0 +1,68 @@
+// @reactra/vite-plugin — per-file declaration fingerprint (A3 increment 2)
+//
+// Owner: backlogs/framework-review-2026-06-12.md §A3 +
+//        reactra-compiler-spec.md §7.1 (vite plugin file-watcher hook).
+//
+// A3 increment 2: on a `change` event we want to skip the src/-wide store/
+// service/resource rescan when the edit only touched a body — the declared SET
+// (store names, service names + modifiers, resource names) is what the manifest
+// + resource-names files are derived from, so if that set is unchanged the wide
+// rescan can't change the generated output.
+//
+// We deliberately do NOT implement the backlog's literal "skip store/service
+// rescan on every change" — a `change` CAN rename a store, add/remove one, or
+// flip a service modifier (and a `[id]`→`[customerId]` param rename arrives as
+// `change` too). The fingerprint differ catches all of those: any decl-set
+// change forces a full regen.
+//
+// The fingerprint is cheap strings derived from the already-cached compile —
+// no extra read, no extra compile.
+const STORE_KINDS = new Set([
+    "route-store",
+    "session-store",
+    "export-store",
+]);
+/**
+ * Derive a {@link DeclFingerprint} from a file's compiled containers. Pure:
+ * same containers → identical fingerprint. Caller supplies the cached
+ * `containersFor(path)` result so no extra compile is paid.
+ */
+export const fingerprintOf = (containers) => {
+    const stores = [];
+    const services = [];
+    const serviceModifiers = [];
+    const resources = [];
+    for (const c of containers) {
+        if (STORE_KINDS.has(c.kind))
+            stores.push(c.name);
+        if (c.kind === "service") {
+            services.push(c.name);
+            serviceModifiers.push(`${c.name}:${c.serviceModifier ?? ""}`);
+        }
+        for (const r of c.resources)
+            resources.push(r.name);
+    }
+    const sort = (xs) => xs.sort((a, b) => a.localeCompare(b));
+    return {
+        stores: sort(stores),
+        services: sort(services),
+        serviceModifiers: sort(serviceModifiers),
+        resources: sort(resources),
+    };
+};
+/** True when two fingerprints declare the same set of stores/services/resources. */
+export const fingerprintsEqual = (a, b) => {
+    const sameList = (xs, ys) => xs.length === ys.length && xs.every((x, i) => x === ys[i]);
+    return (sameList(a.stores, b.stores) &&
+        sameList(a.services, b.services) &&
+        sameList(a.serviceModifiers, b.serviceModifiers) &&
+        sameList(a.resources, b.resources));
+};
+/** True when `path` is a page file (under `src/pages/`) — routes/queries/prefetch live here. */
+export const isPagesFile = (projectRoot, eventPath) => {
+    const root = projectRoot.replace(/\\/g, "/");
+    const target = eventPath.replace(/\\/g, "/");
+    const prefix = (root.endsWith("/") ? root + "src/pages/" : root + "/src/pages/");
+    return target.startsWith(prefix);
+};
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

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

package/dist/graph-cache.d.ts

@@ -0,0 +1,23 @@
+import type { ContainerNode } from "@reactra/babel-plugin";
+/**
+ * A per-regen cache of compiled container graphs, keyed by absolute file path.
+ * One instance lives for the duration of a single manifest regeneration.
+ */
+export interface GraphCache {
+    /**
+     * Read + parse `path` once per regen; returns `graph.containers`.
+     * Returns `[]` on any read OR compile failure (malformed / mid-edit file),
+     * so callers degrade to their documented empty result rather than throwing.
+     *
+     * @param path absolute file path (the cache key — NO content-hash / mtime).
+     */
+    containersFor: (path: string) => readonly ContainerNode[];
+}
+/**
+ * Build a fresh {@link GraphCache}. Memoizes by absolute path: the first
+ * `containersFor(path)` reads + compiles; subsequent calls for the same path
+ * return the stashed result. Discard the instance when the regen completes —
+ * it never sees stale content because a new cache is built per regen.
+ */
+export declare const createGraphCache: () => GraphCache;
+//# sourceMappingURL=graph-cache.d.ts.map

package/dist/graph-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-cache.d.ts","sourceRoot":"","sources":["../src/graph-cache.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,aAAa,EAAE,CAAA;CAC1D;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,UAqBnC,CAAA"}

package/dist/graph-cache.js

@@ -0,0 +1,52 @@
+// @reactra/vite-plugin — per-regen graph cache
+//
+// Owner: reactra-compiler-spec.md §7.1 (vite plugin file-watcher hook) +
+//        backlogs/framework-review-2026-06-12.md §A3 (one walk, one preprocess).
+//
+// A3 increment 1: every container-reading scanner (scanPages, scanStores,
+// scanServices, collectServiceInjectionDiagnostics, collectResourceNames) used
+// to read + `compileToGraph` each file independently — after B5 landed, a 200-
+// file regen compiled each file 4–5×. This cache folds the read + compile +
+// try/catch fallback into ONE place, memoized by absolute path, so each file
+// compiles AT MOST once per regen.
+//
+// Lifetime: ONE instance per regen (created at the top of regenerateRouteManifest
+// and the watcher event handler, then thrown away). NO module-level instance,
+// NO content-hash / mtime key, NO eviction (C1) — a regen is short-lived and a
+// fresh cache each time is correct by construction. The fingerprint differ
+// (increment 2) is the only module-level state.
+//
+// READ-ONLY (C3): reads `graph.containers` only; codegen is never run. Returns
+// `[]` on read OR compile failure, preserving every scanner's documented empty
+// degradation. Node-portable (C7): `node:fs` + plain `Map` only.
+import { readFileSync } from "node:fs";
+import { compileToGraph } from "@reactra/babel-plugin";
+/**
+ * Build a fresh {@link GraphCache}. Memoizes by absolute path: the first
+ * `containersFor(path)` reads + compiles; subsequent calls for the same path
+ * return the stashed result. Discard the instance when the regen completes —
+ * it never sees stale content because a new cache is built per regen.
+ */
+export const createGraphCache = () => {
+    const byPath = new Map();
+    const containersFor = (path) => {
+        const cached = byPath.get(path);
+        if (cached)
+            return cached;
+        let containers;
+        try {
+            const source = readFileSync(path, "utf8");
+            // READ-ONLY: consume only `.graph.containers`; codegen is never run.
+            containers = compileToGraph(source).graph.containers;
+        }
+        catch {
+            // Read OR compile failure → degrade to empty (C3). The next regen
+            // (a fresh cache) recovers once the file is well-formed / readable.
+            containers = [];
+        }
+        byPath.set(path, containers);
+        return containers;
+    };
+    return { containersFor };
+};
+//# sourceMappingURL=graph-cache.js.map