extrojs 0.2.0 → 0.3.0

package/client.d.ts

@@ -1,16 +1,8 @@
-// Ambient types for Extro's env. Opt in from a project by adding:
+// Ambient types for Extro's env, for code that imports nothing else from the
+// framework (a bare background or content script). Opt in once:
 //   /// <reference types="extrojs/client" />
-// Public env vars (EXTRO_PUBLIC_*) are inlined into every surface via
-// import.meta.env. See ADR 0002.
-
-interface ImportMetaEnv {
-  readonly MODE: string
-  readonly DEV: boolean
-  readonly PROD: boolean
-  readonly BASE_URL: string
-  readonly [key: `EXTRO_PUBLIC_${string}`]: string | undefined
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv
-}
+// The single source of the env shape is src/react/env.ts (ADR 0002); this
+// re-surfaces that one declaration for the explicit-reference path, so the two
+// opt-in routes never declare ImportMetaEnv twice. EXTRO_PUBLIC_* is inlined
+// into every surface via import.meta.env.
+/// <reference path="./dist/react/env.d.ts" />

package/dist/commands/build.js

@@ -1,5 +1,5 @@
 import { build as viteBuild } from "vite";
-import { extro } from "@extrojs/vite-plugin";
+import { extro } from "../plugin/index.js";
 import react from "@vitejs/plugin-react";
 import { loadConfig } from "../load-config.js";
 import { loadEnvIntoProcess } from "../env.js";

package/dist/commands/dev.js

@@ -1,8 +1,8 @@
 import { createServer, build as viteBuild } from "vite";
 import { WebSocketServer } from "ws";
-import { extro } from "@extrojs/vite-plugin";
+import { extro } from "../plugin/index.js";
 import react from "@vitejs/plugin-react";
-import { scanAppTree } from "@extrojs/vite-plugin/internal";
+import { scanAppTree, classifyScriptChange, mergeDirty, resolveFlush, } from "../plugin/internal.js";
 import { loadConfig } from "../load-config.js";
 import { loadEnvIntoProcess } from "../env.js";
 import { outputDir } from "../paths.js";
@@ -103,42 +103,25 @@ export const dev = async () => {
         logLevel: "error",
     });
     // The watcher is a RollupWatcher. We split the rebuild signal by which
-    // entry changed: a background-only edit must not reload tabs / remount
-    // CSUI, and a content-only edit must not reload the extension. `change`
-    // events (one per changed file) accumulate until the next `BUNDLE_END`;
-    // a file outside both surface dirs (shared code) conservatively dirties
-    // both. No classified change (initial build, or an `extro dev` restart)
-    // also means both, matching the old broadcast-on-first-build behavior.
+    // entry changed: a background-only edit must not reload tabs / remount CSUI,
+    // and a content-only edit must not reload the extension. `change` events
+    // accumulate the Dev reaction until the next `BUNDLE_END`; the classify and
+    // flush rules (incl. shared-code-dirties-both) live in `dev-reactions.ts`.
     if (watcher && typeof watcher.on === "function") {
         const w = watcher;
-        let bgDirty = false;
-        let csDirty = false;
+        let dirty = { background: false, content: false };
         w.on("change", (id) => {
-            const p = String(id).replace(/\\/g, "/");
-            const isBg = p.includes("/src/app/background/");
-            const isCs = p.includes("/src/app/content/");
-            if (isBg)
-                bgDirty = true;
-            if (isCs)
-                csDirty = true;
-            if (!isBg && !isCs) {
-                bgDirty = true;
-                csDirty = true;
-            }
+            dirty = mergeDirty(dirty, classifyScriptChange(String(id)));
         });
         w.on("event", (event) => {
             if (event.code !== "BUNDLE_END")
                 return;
-            if (!bgDirty && !csDirty) {
-                bgDirty = true;
-                csDirty = true;
-            }
-            if (bgDirty)
+            const { background, content } = resolveFlush(dirty);
+            dirty = { background: false, content: false };
+            if (background)
                 broadcast({ kind: "bg-rebuilt" });
-            if (csDirty)
+            if (content)
                 broadcast({ kind: "cs-rebuilt" });
-            bgDirty = false;
-            csDirty = false;
         });
     }
     banner({

package/dist/config.d.ts

@@ -1,3 +1,3 @@
-import type { ExtroConfig } from "@extrojs/types";
-export type { ExtroConfig } from "@extrojs/types";
+import type { ExtroConfig } from "./types/index.js";
+export type { ExtroConfig } from "./types/index.js";
 export declare const defineConfig: (config: ExtroConfig) => ExtroConfig;

package/dist/core/asset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve a public asset to its extension URL. Works in every surface (popup,
+ * options, sidepanel, background, content), unlike a root-relative `/logo.svg`
+ * which resolves against a content script's host-page origin.
+ *
+ * @example
+ * import { asset } from "extrojs/asset"
+ * <img src={asset("logo.svg")} />
+ */
+export declare const asset: (path: string) => string;

package/dist/core/asset.js

@@ -0,0 +1,10 @@
+/**
+ * Resolve a public asset to its extension URL. Works in every surface (popup,
+ * options, sidepanel, background, content), unlike a root-relative `/logo.svg`
+ * which resolves against a content script's host-page origin.
+ *
+ * @example
+ * import { asset } from "extrojs/asset"
+ * <img src={asset("logo.svg")} />
+ */
+export const asset = (path) => chrome.runtime.getURL(path);

package/dist/dev-assets.d.ts

@@ -1,5 +1,5 @@
-import type { ExtroConfig } from "@extrojs/types";
-import { type AppTree } from "@extrojs/vite-plugin/internal";
+import type { ExtroConfig } from "./types/index.js";
+import { type AppTree } from "./plugin/internal.js";
 interface WriteDevAssetsOptions {
     tree: AppTree;
     root: string;
@@ -12,7 +12,7 @@ interface WriteDevAssetsOptions {
  * @describe Writes the dev manifest + HTML shells + icons to disk so Chrome
  * can load the unpacked extension while the Vite dev server serves modules
  * over HTTP. Background/content scripts are written by the build-watch
- * sidecar (a Vite watch-mode build) — not here.
+ * sidecar (a Vite watch-mode build), not here.
  */
 export declare const writeDevAssets: ({ tree, root, outDir, port, signalPort, config, }: WriteDevAssetsOptions) => Promise<void>;
 export {};

package/dist/dev-assets.js

@@ -1,39 +1,41 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { emitAssets, collectPublicAssets, } from "@extrojs/vite-plugin/internal";
+import { emitAssets, discoverAssets, } from "./plugin/internal.js";
 /**
  * @describe Writes the dev manifest + HTML shells + icons to disk so Chrome
  * can load the unpacked extension while the Vite dev server serves modules
  * over HTTP. Background/content scripts are written by the build-watch
- * sidecar (a Vite watch-mode build) — not here.
+ * sidecar (a Vite watch-mode build), not here.
  */
 export const writeDevAssets = async ({ tree, root, outDir, port, signalPort, config, }) => {
     await fs.mkdir(outDir, { recursive: true });
     const pkgRaw = await fs.readFile(path.join(root, "package.json"), "utf8").catch(() => "{}");
     const pkg = JSON.parse(pkgRaw);
-    await emitAssets({ tree, root, pkg, config, dev: { port, signalPort } }, (fileName, source) => fs.writeFile(path.join(outDir, fileName), source));
-    await copyIcons(root, outDir);
-    await copyPublic(root, outDir, tree);
+    // One discovery pass for the dev manifest, the icon copy, and the public
+    // copy, mirroring the prod path. See the Asset inventory.
+    const inventory = discoverAssets(root, tree);
+    await emitAssets({ tree, inventory, pkg, config, dev: { port, signalPort } }, (fileName, source) => fs.writeFile(path.join(outDir, fileName), source));
+    await copyIcons(root, outDir, inventory.icons);
+    await copyPublic(root, outDir, inventory.public);
 };
-const copyIcons = async (root, outDir) => {
-    const srcDir = path.join(root, "icons");
-    const exists = await fs.stat(srcDir).then((s) => s.isDirectory()).catch(() => false);
-    if (!exists)
+const copyIcons = async (root, outDir, icons) => {
+    if (!icons)
         return;
-    const dstDir = path.join(outDir, "icons");
-    await fs.mkdir(dstDir, { recursive: true });
-    const files = await fs.readdir(srcDir);
-    await Promise.all(files.map((f) => fs.copyFile(path.join(srcDir, f), path.join(dstDir, f))));
+    const entries = Object.values(icons);
+    if (entries.length === 0)
+        return;
+    await fs.mkdir(path.join(outDir, "icons"), { recursive: true });
+    await Promise.all(entries.map((rel) => fs.copyFile(path.join(root, rel), path.join(outDir, rel))));
 };
 /**
  * @describe Copies Public assets into the dev output dir so they resolve at
  * the extension origin in dev exactly as in prod (chrome.runtime.getURL, or a
  * root-relative ref on a routable surface). Mirrors copyIcons; the collision
- * guard from collectPublicAssets keeps a stray file from shadowing a
+ * guard from the Asset inventory keeps a stray file from shadowing a
  * generated output.
  */
-const copyPublic = async (root, outDir, tree) => {
-    const { files, conflicts } = collectPublicAssets(root, tree);
+const copyPublic = async (root, outDir, publicAssets) => {
+    const { files, conflicts } = publicAssets;
     for (const conflict of conflicts) {
         console.warn(`[extro] public/${conflict} collides with a generated output; skipping. Rename it to ship it.`);
     }

package/dist/exports/asset.d.ts

@@ -0,0 +1 @@
+export { asset } from "../core/asset.js";

package/dist/exports/asset.js

@@ -0,0 +1 @@
+export { asset } from "../core/asset.js";

package/dist/exports/link.d.ts

@@ -0,0 +1 @@
+export { Link } from "../router/index.js";

package/dist/exports/link.js

@@ -0,0 +1 @@
+export { Link } from "../router/index.js";

package/dist/exports/navigation.d.ts

@@ -0,0 +1,2 @@
+export { useLocation, useParams, useRouter, useSearchParams, } from "../router/index.js";
+export type { ErrorProps, LayoutProps, PageProps, Router } from "../router/index.js";

package/dist/exports/navigation.js

@@ -0,0 +1 @@
+export { useLocation, useParams, useRouter, useSearchParams, } from "../router/index.js";

package/dist/exports/runtime.d.ts

@@ -0,0 +1,2 @@
+export { createExtroRouter, matchRoutes } from "../router/index.js";
+export type { CreateRouterOptions, DynamicRoute, ExtroRouterHandle, Route, RouteMatch, StaticRoute, } from "../router/index.js";

package/dist/exports/runtime.js

@@ -0,0 +1,3 @@
+// Internal subpath. Emitted by the generated Runtime module
+// (`virtual:extro/runtime/<surface>`), not for direct user import.
+export { createExtroRouter, matchRoutes } from "../router/index.js";

package/dist/load-config.d.ts

@@ -1,2 +1,2 @@
-import type { ExtroConfig } from "@extrojs/types";
+import type { ExtroConfig } from "./types/index.js";
 export declare const loadConfig: (root: string) => Promise<ExtroConfig>;

package/dist/paths.d.ts

@@ -1,4 +1,4 @@
-import type { ExtroConfig } from "@extrojs/types";
+import type { ExtroConfig } from "./types/index.js";
 /**
  * @describe Resolved unpacked-extension output dir for a build mode. The base
  * comes from `config.outDir` (default `output`, resolved against the project

package/dist/plugin/app-tree.d.ts

@@ -0,0 +1,59 @@
+import type { RouteManifest } from "../types/index.js";
+import { type RoutableSurface } from "./surfaces.js";
+/**
+ * Basenames the scanner recognizes under `src/app/`. The dev watcher in
+ * `index.ts` derives its glob + match regex from this same list so dev
+ * structural-change detection can never drift from what the scanner reads.
+ * (Guard: #9 widened the scanner to include `layout` but not the watcher,
+ * which silently broke layout HMR. This list is the single source so it
+ * cannot recur.)
+ */
+export declare const APP_FILE_BASENAMES: readonly ["page", "index", "layout", "error", "not-found"];
+/**
+ * The Content surface has up to two Modes: a raw script entry
+ * (`src/app/content/index.{ts,tsx}`) and a CSUI page (`src/app/content/page.tsx`).
+ * At least one is set when the slot exists; both may be set together.
+ * Stage 3 turns `csui` into a `Route[]`.
+ */
+export type ContentSlot = {
+    script?: string;
+    csui?: string;
+};
+export type AppTree = {
+    scripts: {
+        background?: string;
+        content?: ContentSlot;
+    };
+    /**
+     * Each present Routable surface's slot _is_ its `RouteManifest` (ADR 0007):
+     * routes + the per-surface not-found / surface-root layout in one record,
+     * so the pieces cannot desync. Present iff the surface has >= 1 page.
+     */
+    surfaces: Partial<Record<RoutableSurface, RouteManifest>>;
+};
+/**
+ * Single pass over `src/app/`. Every convention of the app tree lives here:
+ *
+ *   - Routable surfaces use `page.{ts,tsx}` and may nest. `[id]` segments
+ *     become dynamic params.
+ *       src/app/popup/page.tsx              → { type: "static",  path: "/" }
+ *       src/app/popup/settings/page.tsx     → { type: "static",  path: "/settings" }
+ *       src/app/popup/user/[id]/page.tsx    → { type: "dynamic", path: "/user/:id" }
+ *
+ *   - Script surfaces use `index.{ts,tsx}` at the surface root and do not
+ *     nest.
+ *
+ * Which surfaces fall into which kind is declared in `surfaces.ts`; this
+ * dispatcher consults `findSurface(name).kind` rather than hard-coding names.
+ *
+ * An empty result is returned as-is — the caller decides whether that's an
+ * error.
+ */
+export declare function scanAppTree(root: string): Promise<AppTree>;
+/**
+ * Accessor for one Routable surface's `RouteManifest` — its slot of the
+ * AppTree, or an empty manifest when the surface is absent (ADR 0005/0007).
+ * The single input to `emit` and the invalidation key, and the fixture seam
+ * for the round-trip test (build one by hand, no filesystem scan needed).
+ */
+export declare function routeManifest(tree: AppTree, surface: RoutableSurface): RouteManifest;

package/dist/plugin/app-tree.js

@@ -0,0 +1,214 @@
+import fg from "fast-glob";
+import path from "node:path";
+import { findSurface } from "./surfaces.js";
+/**
+ * Basenames the scanner recognizes under `src/app/`. The dev watcher in
+ * `index.ts` derives its glob + match regex from this same list so dev
+ * structural-change detection can never drift from what the scanner reads.
+ * (Guard: #9 widened the scanner to include `layout` but not the watcher,
+ * which silently broke layout HMR. This list is the single source so it
+ * cannot recur.)
+ */
+export const APP_FILE_BASENAMES = [
+    "page",
+    "index",
+    "layout",
+    "error",
+    "not-found",
+];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Single pass over `src/app/`. Every convention of the app tree lives here:
+ *
+ *   - Routable surfaces use `page.{ts,tsx}` and may nest. `[id]` segments
+ *     become dynamic params.
+ *       src/app/popup/page.tsx              → { type: "static",  path: "/" }
+ *       src/app/popup/settings/page.tsx     → { type: "static",  path: "/settings" }
+ *       src/app/popup/user/[id]/page.tsx    → { type: "dynamic", path: "/user/:id" }
+ *
+ *   - Script surfaces use `index.{ts,tsx}` at the surface root and do not
+ *     nest.
+ *
+ * Which surfaces fall into which kind is declared in `surfaces.ts`; this
+ * dispatcher consults `findSurface(name).kind` rather than hard-coding names.
+ *
+ * An empty result is returned as-is — the caller decides whether that's an
+ * error.
+ */
+export async function scanAppTree(root) {
+    const files = await fg(`src/app/**/{${APP_FILE_BASENAMES.join(",")}}.{ts,tsx}`, { cwd: root });
+    const scripts = {};
+    const pagesBySurface = new Map();
+    // surface → (segment key, e.g. "" or "settings" or "c/[id]") → file path.
+    const layoutsBySurface = new Map();
+    const errorsBySurface = new Map();
+    const notFoundBySurface = new Map();
+    for (const file of files) {
+        const parts = file.split("/").slice(2); // drop "src/app/"
+        const surface = parts[0];
+        if (!surface)
+            continue;
+        const desc = findSurface(surface);
+        if (!desc)
+            continue;
+        const filename = parts[parts.length - 1];
+        const isPage = /^page\.tsx?$/.test(filename);
+        const isIndex = /^index\.tsx?$/.test(filename);
+        const isLayout = /^layout\.tsx?$/.test(filename);
+        const isError = /^error\.tsx?$/.test(filename);
+        const isNotFound = /^not-found\.tsx?$/.test(filename);
+        if (desc.kind === "script") {
+            if (parts.length !== 2)
+                continue;
+            if (!isIndex && !(isPage && desc.acceptsCsuiPage))
+                continue;
+            const abs = path.join(root, file);
+            if (surface === "background") {
+                scripts.background = abs;
+            }
+            else if (surface === "content") {
+                scripts.content = {
+                    ...scripts.content,
+                    [isIndex ? "script" : "csui"]: abs,
+                };
+            }
+            continue;
+        }
+        if (desc.kind !== "routable")
+            continue;
+        const name = surface;
+        const segments = parts.slice(1, -1); // drop surface dir + filename
+        if (isPage) {
+            const list = pagesBySurface.get(name) ?? [];
+            list.push({ file: path.join(root, file), segments });
+            pagesBySurface.set(name, list);
+        }
+        else if (isLayout || isError) {
+            const bySurface = isLayout ? layoutsBySurface : errorsBySurface;
+            const map = bySurface.get(name) ?? new Map();
+            map.set(segments.join("/"), path.join(root, file));
+            bySurface.set(name, map);
+        }
+        else if (isNotFound && segments.length === 0) {
+            // ADR 0003 §4: only the surface-root not-found.tsx is recognized;
+            // deeper ones are intentionally ignored in v0.
+            notFoundBySurface.set(name, path.join(root, file));
+        }
+    }
+    const surfaces = {};
+    for (const [name, pages] of pagesBySurface) {
+        const layoutMap = layoutsBySurface.get(name);
+        const errorMap = errorsBySurface.get(name);
+        const routes = pages.map(({ file, segments }) => buildRoute(file, segments, resolveBoundaryChain(segments, layoutMap, errorMap)));
+        // One RouteManifest per surface: routes + not-found + root layout in a
+        // single record, so the pieces cannot desync (ADR 0007).
+        surfaces[name] = {
+            routes: sortRoutes(routes),
+            notFound: notFoundBySurface.get(name) ?? null,
+            rootLayout: layoutMap?.get("") ?? null,
+        };
+    }
+    return { scripts, surfaces };
+}
+const EMPTY_MANIFEST = {
+    routes: [],
+    notFound: null,
+    rootLayout: null,
+};
+/**
+ * Accessor for one Routable surface's `RouteManifest` — its slot of the
+ * AppTree, or an empty manifest when the surface is absent (ADR 0005/0007).
+ * The single input to `emit` and the invalidation key, and the fixture seam
+ * for the round-trip test (build one by hand, no filesystem scan needed).
+ */
+export function routeManifest(tree, surface) {
+    return tree.surfaces[surface] ?? EMPTY_MANIFEST;
+}
+// ---------------------------------------------------------------------------
+// Route builder
+// ---------------------------------------------------------------------------
+function buildRoute(file, segments, boundaries) {
+    if (segments.some(isDynamic))
+        return buildDynamicRoute(file, segments, boundaries);
+    return buildStaticRoute(file, segments, boundaries);
+}
+function buildStaticRoute(file, segments, boundaries) {
+    const urlPath = segments.length > 0 ? `/${segments.join("/")}` : "/";
+    return { type: "static", path: urlPath, file, boundaries };
+}
+function buildDynamicRoute(file, segments, boundaries) {
+    const paramKeys = [];
+    const patternParts = segments.map((seg) => {
+        if (isDynamic(seg)) {
+            paramKeys.push(seg.slice(1, -1)); // strip [ and ]
+            return "([^/]+)";
+        }
+        return escapeRegex(seg);
+    });
+    // Serializable: the RegExp body, materialized by `emit` at codegen time.
+    const patternSource = `^/${patternParts.join("/")}$`;
+    const urlPath = segments
+        .map((seg) => (isDynamic(seg) ? `:${seg.slice(1, -1)}` : seg))
+        .join("/");
+    return {
+        type: "dynamic",
+        path: `/${urlPath}`,
+        file,
+        paramKeys,
+        patternSource,
+        boundaries,
+    };
+}
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+/**
+ * Static routes first (longest first for specificity), then dynamic routes
+ * (longest first so /user/:id beats /:anything for the same depth).
+ *
+ * Alphabetical tiebreak keeps the output stable across filesystems — otherwise
+ * two routes of equal length would sort by readdir order, which varies.
+ */
+function sortRoutes(routes) {
+    const byLengthThenAlpha = (a, b) => b.path.length - a.path.length || a.path.localeCompare(b.path);
+    const statics = routes
+        .filter((r) => r.type === "static")
+        .sort(byLengthThenAlpha);
+    const dynamics = routes
+        .filter((r) => r.type === "dynamic")
+        .sort(byLengthThenAlpha);
+    return [...statics, ...dynamics];
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Ancestor boundary chain for a page, outermost first: walk from the
+ * surface-root segment (key "") down to the page's own segment. At each
+ * depth the `layout.tsx` is pushed before the `error.tsx`, so composing the
+ * chain inside-out nests the error within its sibling layout (ADR 0003 §3).
+ * Only the files that exist are included.
+ */
+function resolveBoundaryChain(segments, layoutMap, errorMap) {
+    const chain = [];
+    for (let i = 0; i <= segments.length; i++) {
+        const key = segments.slice(0, i).join("/");
+        const layout = layoutMap?.get(key);
+        if (layout)
+            chain.push({ kind: "layout", file: layout });
+        const error = errorMap?.get(key);
+        if (error)
+            chain.push({ kind: "error", file: error });
+    }
+    return chain;
+}
+/** Returns true for dynamic segments like `[id]` or `[userId]`. */
+function isDynamic(segment) {
+    return segment.startsWith("[") && segment.endsWith("]");
+}
+/** Escapes special RegExp characters in a static path segment. */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/plugin/asset-inventory.d.ts

@@ -0,0 +1,24 @@
+import type { AppTree } from "./app-tree.js";
+import { type PublicAssets } from "./public.js";
+/**
+ * @file asset-inventory.ts
+ * @description The Asset inventory: the discovered static-file inputs a build
+ * ships. One `discoverAssets(root, tree)` pass over `icons/` and `public/`
+ * yields a value consumed by both the Manifest generator (kept pure, taking
+ * this as data) and the emit/copy paths, so the filesystem is walked once per
+ * build instead of three times.
+ *
+ * The icon set here is the recognized-sizes set (16/32/48/128) that
+ * `manifest.icons` references, and it is exactly what the emit/copy paths ship.
+ * A stray `icons/64.png` is not in the inventory, so it never ships: there is
+ * one notion of "an icon", and `manifest.icons` and the emitted icon files
+ * cannot diverge.
+ */
+export interface AssetInventory {
+    /** Recognized icons: size -> output path ("icons/16.png"). null when absent. */
+    icons: Record<string, string> | null;
+    /** Public assets, partitioned against the names a build generates. */
+    public: PublicAssets;
+}
+/** Walk `icons/` + `public/` once and return the build's Asset inventory. */
+export declare function discoverAssets(root: string, tree: AppTree): AssetInventory;

package/dist/plugin/asset-inventory.js

@@ -0,0 +1,9 @@
+import { detectIcons } from "./icons.js";
+import { collectPublicAssets } from "./public.js";
+/** Walk `icons/` + `public/` once and return the build's Asset inventory. */
+export function discoverAssets(root, tree) {
+    return {
+        icons: detectIcons(root) ?? null,
+        public: collectPublicAssets(root, tree),
+    };
+}

package/dist/plugin/dev-reactions.d.ts

@@ -0,0 +1,59 @@
+import type { AppTree } from "./app-tree.js";
+import type { RoutableSurface } from "./surfaces.js";
+/**
+ * @file dev-reactions.ts
+ * @description Dev reactions: the framework's decision about what to do when a
+ * watched `src/app` file changes during `extro dev`. Pure functions only. The
+ * watchers that trigger them own every effect (rescan, broadcast, module
+ * invalidation); nothing here touches the filesystem, the module graph, or the
+ * WebSocket. The decisions are the test surface.
+ *
+ * Two complementary halves:
+ *   - the script reaction (`classifyScriptChange` + the dirty reducer), driven
+ *     by the CLI's Rollup build watcher over background/content;
+ *   - the tree reaction (`decideTreeReaction`), driven by the plugin's
+ *     dev-server watcher over the Routable surfaces.
+ */
+/** Which Script surfaces a dev rebuild dirties. */
+export interface ScriptDirty {
+    background: boolean;
+    content: boolean;
+}
+/**
+ * A changed file under `src/app/background/` dirties background; under
+ * `src/app/content/` dirties content; anything else (shared code) dirties both.
+ * This is the only place that knows the `src/app` layout, so the CLI no longer
+ * hardcodes those paths.
+ */
+export declare function classifyScriptChange(changedPath: string): ScriptDirty;
+/** Union two dirty states (accumulating `change` events across one build). */
+export declare function mergeDirty(a: ScriptDirty, b: ScriptDirty): ScriptDirty;
+/**
+ * Resolve the accumulated dirty state at `BUNDLE_END`. No classified change
+ * (the initial build, or an `extro dev` restart) conservatively means both,
+ * matching the broadcast-on-first-build behavior.
+ */
+export declare function resolveFlush(dirty: ScriptDirty): ScriptDirty;
+/**
+ * The reaction to a Routable-side change.
+ *   - `restart`: a Surface was born mid-session. `rollupOptions.input` was
+ *     fixed at `config()` time, so a fresh `extro dev` is required to register
+ *     the new entry.
+ *   - `invalidate`: existing Routable surfaces gained or lost a Route; their
+ *     routes virtual modules must reload so the runtime picks up the new array.
+ *   - `noop`: nothing actionable changed.
+ */
+export type DevReaction = {
+    kind: "restart";
+    surface: "background" | "content" | RoutableSurface;
+} | {
+    kind: "invalidate";
+    surfaces: RoutableSurface[];
+} | {
+    kind: "noop";
+};
+/**
+ * Diff two AppTrees into a {@link DevReaction}. A birth short-circuits the
+ * invalidate scan: the session has to restart regardless of any route delta.
+ */
+export declare function decideTreeReaction(prev: AppTree, next: AppTree, routables: readonly RoutableSurface[]): DevReaction;