extrojs 0.1.0 → 0.3.0

package/dist/plugin/public.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * @file public.ts
+ * @description Discovers Public assets (static files under the project-root
+ * `public/` directory) and partitions them against the names Extro itself
+ * emits, so a stray `public/manifest.json` can never shadow the real one.
+ * The same partition drives prod emission, dev copy, and the
+ * `web_accessible_resources` list, so all three agree on exactly what ships.
+ */
+export const PUBLIC_DIR = "public";
+/** Recursively list files under `dir` as posix-relative paths from `base`. */
+function walk(dir, base) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...walk(abs, base));
+        }
+        else {
+            out.push(path.relative(base, abs).split(path.sep).join("/"));
+        }
+    }
+    return out;
+}
+/**
+ * Names a Public asset must not overwrite: the generated manifest, the
+ * per-surface HTML shells and script bundles, and the dedicated `icons/`
+ * tree. Generated output always wins.
+ */
+function isReservedName(name, tree) {
+    if (name === "manifest.json")
+        return true;
+    if (name === "icons" || name.startsWith("icons/"))
+        return true;
+    for (const surface of Object.keys(tree.surfaces)) {
+        if (name === `${surface}.html` || name === `${surface}.js`)
+            return true;
+    }
+    if (tree.scripts.background && name === "background.js")
+        return true;
+    if (tree.scripts.content && name === "content.js")
+        return true;
+    return false;
+}
+/**
+ * Partition `public/` into shippable files and conflicts. Returns empty
+ * lists when `public/` is absent.
+ */
+export function collectPublicAssets(root, tree) {
+    const dir = path.join(root, PUBLIC_DIR);
+    if (!fs.existsSync(dir))
+        return { files: [], conflicts: [] };
+    const files = [];
+    const conflicts = [];
+    for (const rel of walk(dir, dir).sort()) {
+        if (isReservedName(rel, tree))
+            conflicts.push(rel);
+        else
+            files.push(rel);
+    }
+    return { files, conflicts };
+}

package/dist/plugin/runtimes/clients/csui-mount.js

@@ -0,0 +1,90 @@
+import "virtual:extro/user/content-script";
+import UserComponent from "virtual:extro/user/content-page";
+import { config } from "virtual:extro/csui-mount/config";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+const STATE_KEY = "__extroCSUI__";
+const getState = () => globalThis[STATE_KEY];
+const setState = (state) => {
+    const slot = globalThis;
+    if (state)
+        slot[STATE_KEY] = state;
+    else
+        delete slot[STATE_KEY];
+};
+const teardownState = (state) => {
+    try {
+        state.root.unmount();
+    }
+    catch { }
+    try {
+        state.host.remove();
+    }
+    catch { }
+    if (state.handler) {
+        try {
+            chrome.runtime.onMessage.removeListener(state.handler);
+        }
+        catch { }
+    }
+};
+const mount = (Component) => {
+    const previous = getState();
+    // Build the new tree on top of the old without removing the old first.
+    // Both hosts use position:fixed at the same coordinates, so they perfectly
+    // overlap; the user sees no gap. The old host is torn down on the next
+    // frame, by which time React has committed + painted the new tree.
+    const host = document.createElement("div");
+    host.id = "extro-csui-root";
+    const shadow = host.attachShadow({ mode: "open" });
+    document.body.appendChild(host);
+    const root = createRoot(shadow);
+    // flushSync so the new tree is committed to the DOM before we return; the
+    // subsequent rAF then reliably runs after the new tree exists. Without it,
+    // React's async commit can race with the rAF callback and the teardown
+    // fires on a blank frame, producing an intermittent flash.
+    flushSync(() => root.render(createElement(Component)));
+    if (previous) {
+        requestAnimationFrame(() => teardownState(previous));
+    }
+    if (!config.dev) {
+        setState({ root, host });
+        return;
+    }
+    // In-flight gate: drop csui-update messages while a re-import is already
+    // running so we don't queue redundant mount/teardown cycles when several
+    // signals arrive in quick succession.
+    let importPending = false;
+    const handler = (raw) => {
+        const msg = raw;
+        if (!msg)
+            return;
+        // RFR transport probe — slice 1 just logs that BG-fetched module
+        // sources are arriving end-to-end. Evaluation + react-refresh wiring
+        // come in later slices.
+        if (msg.kind === "rfr-update" && Array.isArray(msg.modules)) {
+            const modules = msg.modules;
+            console.log("[extro] rfr-update received:", modules.map((m) => ({
+                path: m.path,
+                bytes: m.code ? m.code.length : 0,
+            })));
+            return;
+        }
+        if (msg.kind !== "csui-update")
+            return;
+        if (importPending)
+            return;
+        importPending = true;
+        const url = chrome.runtime.getURL("content.js") + "?v=" + Date.now();
+        import(/* @vite-ignore */ url)
+            .catch((err) => console.error("[extro] csui re-import failed:", err))
+            .finally(() => { importPending = false; });
+    };
+    try {
+        chrome.runtime.onMessage.addListener(handler);
+    }
+    catch { }
+    setState({ root, host, handler });
+};
+mount(UserComponent);

package/dist/plugin/runtimes/clients/dev-bridge.js

@@ -0,0 +1,194 @@
+import "virtual:extro/user/background";
+import { config } from "virtual:extro/dev-bridge/config";
+/**
+ * @file runtimes/clients/dev-bridge.ts
+ * @description The MV3 service-worker bridge run by `extro dev`.
+ *
+ * Responsibilities:
+ *   - Connect to the CLI's signal WS and react to:
+ *       bg-rebuilt  → `chrome.runtime.reload()` (only way to swap BG code).
+ *       cs-rebuilt  → CSUI-aware re-mount via `csui-update`, else tab reload.
+ *       vite-hmr    → fetch transformed module source from the dev server
+ *                     and forward to tabs as `rfr-update` for the CSUI
+ *                     runtime's react-refresh client.
+ *   - Keep the service worker alive past the MV3 idle timeout so the WS
+ *     doesn't die between edits.
+ *   - Restart the extension if the in-memory manifest predates this dev
+ *     session (CSP would block our signal WS otherwise).
+ *
+ * Why the BG SW does the dev-server fetch (not content scripts):
+ *   Chrome's Local Network Access blocks public HTTPS pages from reaching
+ *   localhost without a per-site user grant. Only the chrome-extension://
+ *   origin can reliably fetch http://localhost:<vitePort>.
+ */
+(function extroDevBridge() {
+    // If Chrome's in-memory manifest predates this dev session (e.g. it last
+    // loaded from a prod build), the CSP won't allow our signal WS. Force a
+    // reload so Chrome re-reads the dev manifest from disk. The new SW spawn
+    // sees the updated CSP and skips this branch.
+    const csp = chrome.runtime.getManifest().content_security_policy;
+    const pages = csp?.extension_pages ?? "";
+    if (!pages.includes(`ws://localhost:${config.signalPort}`)) {
+        chrome.runtime.reload();
+        return;
+    }
+    const SIGNAL_URL = `ws://localhost:${config.signalPort}`;
+    const VITE_ORIGIN = `http://localhost:${config.vitePort}`;
+    let signalSocket = null;
+    let wasDisconnected = false;
+    // ---------------------------------------------------------------------
+    // Keep-alive — Chrome MV3 terminates idle SWs after ~30s. Without this,
+    // the signal WS dies between edits and HMR silently stops working.
+    // Periodic chrome.* API calls register as activity and prevent
+    // termination. Dev-only; the prod build doesn't ship this bridge.
+    // ---------------------------------------------------------------------
+    setInterval(() => {
+        chrome.runtime.getPlatformInfo().catch(() => { });
+    }, 20_000);
+    // ---------------------------------------------------------------------
+    // Tab helpers
+    // ---------------------------------------------------------------------
+    const messageMatchingTabs = async (msg) => {
+        let count = 0;
+        try {
+            const manifest = chrome.runtime.getManifest();
+            const matches = manifest.content_scripts?.[0]?.matches ?? [];
+            if (matches.length === 0)
+                return 0;
+            const tabs = await chrome.tabs.query({ url: matches });
+            await Promise.all(tabs.map(async (tab) => {
+                if (tab.id == null)
+                    return;
+                try {
+                    await chrome.tabs.sendMessage(tab.id, msg);
+                    count++;
+                }
+                catch { }
+            }));
+        }
+        catch { }
+        return count;
+    };
+    const reloadMatchingTabs = async () => {
+        try {
+            const manifest = chrome.runtime.getManifest();
+            const matches = manifest.content_scripts?.[0]?.matches ?? [];
+            if (matches.length === 0)
+                return;
+            const tabs = await chrome.tabs.query({ url: matches });
+            for (const tab of tabs) {
+                if (tab.id != null) {
+                    try {
+                        await chrome.tabs.reload(tab.id);
+                    }
+                    catch { }
+                }
+            }
+        }
+        catch (err) {
+            console.warn("[extro] tab reload skipped:", err);
+        }
+    };
+    // ---------------------------------------------------------------------
+    // RFR transport — fetch transformed module source from the Vite dev
+    // server (BG SW is the only origin that reliably reaches localhost on
+    // sites where Local Network Access would block a public-origin fetch).
+    // ---------------------------------------------------------------------
+    const fetchModuleSource = async (modPath) => {
+        try {
+            const res = await fetch(VITE_ORIGIN + modPath);
+            if (!res.ok)
+                return null;
+            return await res.text();
+        }
+        catch (err) {
+            console.warn("[extro] failed to fetch " + modPath, err);
+            return null;
+        }
+    };
+    // ---------------------------------------------------------------------
+    // Signal handlers
+    // ---------------------------------------------------------------------
+    const onBgRebuilt = () => {
+        console.log("[extro] bg-rebuilt signal received");
+        // A service worker can't be hot-swapped; the only way to pick up new
+        // background code is to restart the extension. Deliberately does NOT
+        // message tabs or send csui-update — a BG-only edit leaves content
+        // scripts / CSUI alone.
+        chrome.runtime.reload();
+    };
+    const onCsRebuilt = async () => {
+        console.log("[extro] cs-rebuilt signal received");
+        if (config.hasCSUI) {
+            const count = await messageMatchingTabs({ kind: "csui-update" });
+            console.log(`[extro] csui-update sent to ${count} tab(s)`);
+        }
+        else {
+            await reloadMatchingTabs();
+        }
+        // Deliberately NO chrome.runtime.reload() — a content-only edit is
+        // picked up when the tab reloads (content.js re-injected) or when
+        // CSUI soft-remounts.
+    };
+    const onViteHmr = async (payload) => {
+        // Forward the raw payload for any future consumer that wants the
+        // unmodified Vite envelope.
+        await messageMatchingTabs({ kind: "vite-hmr", payload });
+        if (!config.hasCSUI || !payload || !Array.isArray(payload.updates))
+            return;
+        const fetched = await Promise.all(payload.updates
+            .filter((u) => u && u.type === "js-update" && u.path)
+            .map(async (u) => {
+            const code = await fetchModuleSource(u.path);
+            return code ? { path: u.path, code, timestamp: u.timestamp } : null;
+        }));
+        const modules = fetched.filter((m) => m !== null);
+        if (modules.length === 0)
+            return;
+        const count = await messageMatchingTabs({ kind: "rfr-update", modules });
+        console.log(`[extro] rfr-update ${modules.length} module(s) -> ${count} tab(s)`);
+    };
+    // ---------------------------------------------------------------------
+    // Signal WS
+    // ---------------------------------------------------------------------
+    const connectSignal = () => {
+        signalSocket = new WebSocket(SIGNAL_URL);
+        signalSocket.addEventListener("open", () => {
+            // Wipe the pile of "WebSocket connection failed" entries Chrome
+            // accumulated while dev was down. Only on reconnect, not the very
+            // first connect, so we don't eat the user's pre-bridge BG logs.
+            if (wasDisconnected)
+                console.clear();
+            wasDisconnected = false;
+            console.log("[extro] Connected to dev server.");
+        });
+        signalSocket.addEventListener("message", (event) => {
+            let msg;
+            try {
+                msg = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            if (!msg)
+                return;
+            if (msg.kind === "bg-rebuilt")
+                onBgRebuilt();
+            else if (msg.kind === "cs-rebuilt")
+                onCsRebuilt();
+            else if (msg.kind === "vite-hmr" && msg.payload)
+                onViteHmr(msg.payload);
+        });
+        signalSocket.addEventListener("close", () => {
+            wasDisconnected = true;
+            setTimeout(connectSignal, 1000);
+        });
+        signalSocket.addEventListener("error", () => {
+            try {
+                signalSocket?.close();
+            }
+            catch { }
+        });
+    };
+    connectSignal();
+})();

package/dist/plugin/runtimes/csui-mount.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file runtimes/csui-mount.ts
+ * @description Plugin-side loader for the CSUI Mount Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/csui-mount.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export declare const CSUI_ENTRY_ID = "virtual:extro/csui-content";
+export declare const CSUI_CONFIG_ID = "virtual:extro/csui-mount/config";
+export declare const CSUI_USER_PAGE_ID = "virtual:extro/user/content-page";
+export declare const CSUI_USER_SCRIPT_ID = "virtual:extro/user/content-script";
+export declare const loadCSUIClient: () => string;
+export declare const csuiConfigSource: (dev: boolean) => string;
+export declare const csuiUserPageSource: (pagePath: string) => string;
+export declare const csuiUserScriptSource: (scriptPath: string | undefined) => string;

package/dist/plugin/runtimes/csui-mount.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * @file runtimes/csui-mount.ts
+ * @description Plugin-side loader for the CSUI Mount Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/csui-mount.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export const CSUI_ENTRY_ID = "virtual:extro/csui-content";
+export const CSUI_CONFIG_ID = "virtual:extro/csui-mount/config";
+export const CSUI_USER_PAGE_ID = "virtual:extro/user/content-page";
+export const CSUI_USER_SCRIPT_ID = "virtual:extro/user/content-script";
+const clientJsURL = new URL("./clients/csui-mount.js", import.meta.url);
+export const loadCSUIClient = () => fs.readFileSync(fileURLToPath(clientJsURL), "utf-8");
+export const csuiConfigSource = (dev) => `export const config = ${JSON.stringify({ dev })};\n`;
+export const csuiUserPageSource = (pagePath) => `export { default } from ${JSON.stringify(pagePath)};\n`;
+export const csuiUserScriptSource = (scriptPath) => scriptPath ? `import ${JSON.stringify(scriptPath)};\n` : "\n";

package/dist/plugin/runtimes/dev-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file runtimes/dev-bridge.ts
+ * @description Plugin-side loader for the Dev Bridge Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/dev-bridge.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export declare const DEV_BRIDGE_ENTRY_ID = "virtual:extro/dev-background";
+export declare const DEV_BRIDGE_CONFIG_ID = "virtual:extro/dev-bridge/config";
+export declare const DEV_BRIDGE_USER_BG_ID = "virtual:extro/user/background";
+export declare const loadDevBridgeClient: () => string;
+interface DevBridgeConfig {
+    signalPort: number;
+    vitePort: number;
+    hasCSUI: boolean;
+}
+export declare const devBridgeConfigSource: (cfg: DevBridgeConfig) => string;
+export declare const devBridgeUserBackgroundSource: (backgroundPath: string | undefined) => string;
+export {};

package/dist/plugin/runtimes/dev-bridge.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * @file runtimes/dev-bridge.ts
+ * @description Plugin-side loader for the Dev Bridge Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/dev-bridge.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export const DEV_BRIDGE_ENTRY_ID = "virtual:extro/dev-background";
+export const DEV_BRIDGE_CONFIG_ID = "virtual:extro/dev-bridge/config";
+export const DEV_BRIDGE_USER_BG_ID = "virtual:extro/user/background";
+const clientJsURL = new URL("./clients/dev-bridge.js", import.meta.url);
+export const loadDevBridgeClient = () => fs.readFileSync(fileURLToPath(clientJsURL), "utf-8");
+export const devBridgeConfigSource = (cfg) => `export const config = ${JSON.stringify(cfg)};\n`;
+export const devBridgeUserBackgroundSource = (backgroundPath) => backgroundPath ? `import ${JSON.stringify(backgroundPath)};\n` : "\n";

package/dist/plugin/runtimes/routes-module.d.ts

@@ -0,0 +1,20 @@
+import type { RouteManifest } from "../../types/index.js";
+/**
+ * @file runtimes/routes-module.ts
+ * @description The single codegen for the `virtual:extro/routes/<surface>`
+ * Runtime module (ADR 0005). It is the only code that knows the text form of
+ * the routing contract: lazy `import()` thunks, the dynamic-route RegExp, and
+ * the `notFound` / `rootLayout` exports. Input is the typed `RouteManifest`;
+ * output is asserted against the runtime `Route[]` type by the round-trip
+ * test, so this string can no longer drift from what the runtime expects.
+ *
+ * Example output:
+ *
+ *   export const routes = [
+ *     { type: "static",  path: "/",         boundaries: [...], load: () => import("...") },
+ *     { type: "dynamic", path: "/user/:id", paramKeys: ["id"], pattern: new RegExp("^/user/([^/]+)$"), boundaries: [...], load: () => import("...") },
+ *   ];
+ *   export const notFound = () => import("...");
+ *   export const rootLayout = null;
+ */
+export declare function emit(manifest: RouteManifest): string;

package/dist/plugin/runtimes/routes-module.js

@@ -0,0 +1,51 @@
+/**
+ * @file runtimes/routes-module.ts
+ * @description The single codegen for the `virtual:extro/routes/<surface>`
+ * Runtime module (ADR 0005). It is the only code that knows the text form of
+ * the routing contract: lazy `import()` thunks, the dynamic-route RegExp, and
+ * the `notFound` / `rootLayout` exports. Input is the typed `RouteManifest`;
+ * output is asserted against the runtime `Route[]` type by the round-trip
+ * test, so this string can no longer drift from what the runtime expects.
+ *
+ * Example output:
+ *
+ *   export const routes = [
+ *     { type: "static",  path: "/",         boundaries: [...], load: () => import("...") },
+ *     { type: "dynamic", path: "/user/:id", paramKeys: ["id"], pattern: new RegExp("^/user/([^/]+)$"), boundaries: [...], load: () => import("...") },
+ *   ];
+ *   export const notFound = () => import("...");
+ *   export const rootLayout = null;
+ */
+export function emit(manifest) {
+    const entries = manifest.routes.map(serializeRoute).join(",\n");
+    return `export const routes = [
+${entries}
+];
+export const notFound = ${loaderOrNull(manifest.notFound)};
+export const rootLayout = ${loaderOrNull(manifest.rootLayout)};
+`;
+}
+// ---------------------------------------------------------------------------
+// Serialisers
+// ---------------------------------------------------------------------------
+/** A lazy import of an absolute path, or the `null` literal when absent. */
+function loaderOrNull(file) {
+    return file ? `() => import(${JSON.stringify(file)})` : "null";
+}
+// Boundary chain is emitted outermost first as tagged lazy imports, so the
+// runtime composes the route's wrappers without a separate tree fetch.
+function serializeBoundaries(route) {
+    const entries = route.boundaries
+        .map((b) => `{ kind: ${JSON.stringify(b.kind)}, load: () => import(${JSON.stringify(b.file)}) }`)
+        .join(", ");
+    return `[${entries}]`;
+}
+function serializeRoute(route) {
+    if (route.type === "static") {
+        return `  { type: "static", path: ${JSON.stringify(route.path)}, boundaries: ${serializeBoundaries(route)}, load: () => import(${JSON.stringify(route.file)}) }`;
+    }
+    // `patternSource` is materialized into a real RegExp here (the runtime
+    // `Route` type carries `pattern: RegExp`); JSON.stringify keeps escaping
+    // correct without RegExp-literal pitfalls.
+    return `  { type: "dynamic", path: ${JSON.stringify(route.path)}, paramKeys: ${JSON.stringify(route.paramKeys)}, pattern: new RegExp(${JSON.stringify(route.patternSource)}), boundaries: ${serializeBoundaries(route)}, load: () => import(${JSON.stringify(route.file)}) }`;
+}

package/dist/plugin/runtimes/runtime-module.d.ts

@@ -0,0 +1,16 @@
+import type { RoutableSurface } from "../surfaces.js";
+interface GenerateRuntimeModuleOptions {
+    surface: RoutableSurface;
+}
+/**
+ * @file runtimes/runtime-module.ts
+ * @description Generates the per-surface runtime entry.
+ *
+ * The real runtime logic (mounting, route matching, render loop) lives in
+ * `@extrojs/router` as actual TypeScript; this file only emits a tiny
+ * shim that wires the compiled routes array into `createExtroRouter`. The
+ * shim imports from the published `extrojs/runtime` subpath (ADR 0009), the
+ * one path that resolves inside the user's bundle.
+ */
+export declare function generateRuntimeModule({ surface, }: GenerateRuntimeModuleOptions): string;
+export {};

package/dist/plugin/runtimes/runtime-module.js

@@ -0,0 +1,40 @@
+/**
+ * @file runtimes/runtime-module.ts
+ * @description Generates the per-surface runtime entry.
+ *
+ * The real runtime logic (mounting, route matching, render loop) lives in
+ * `@extrojs/router` as actual TypeScript; this file only emits a tiny
+ * shim that wires the compiled routes array into `createExtroRouter`. The
+ * shim imports from the published `extrojs/runtime` subpath (ADR 0009), the
+ * one path that resolves inside the user's bundle.
+ */
+export function generateRuntimeModule({ surface, }) {
+    return `import { createExtroRouter } from "extrojs/runtime";
+import { routes, notFound, rootLayout } from "virtual:extro/routes/${surface}";
+
+// Persist the router handle across HMR updates so we never call createRoot twice.
+// import.meta.hot.data survives module re-execution.
+let handle = import.meta.hot?.data?.handle;
+
+if (!handle) {
+  handle = createExtroRouter(routes, { surface: ${JSON.stringify(surface)}, notFound, rootLayout });
+  if (import.meta.hot) {
+    import.meta.hot.data.handle = handle;
+  }
+} else {
+  handle.update(routes, { notFound, rootLayout });
+}
+
+if (import.meta.hot) {
+  // Only accept updates to the routes dep. Edits to anything else (e.g.
+  // the router internals) bubble to a full page reload. The persisted
+  // handle is wired to the old render closure and can't pick up new module
+  // code in place, so a fresh mount is the correct behavior.
+  import.meta.hot.accept("virtual:extro/routes/${surface}", (mod) => {
+    if (mod?.routes) {
+      handle.update(mod.routes, { notFound: mod.notFound, rootLayout: mod.rootLayout });
+    }
+  });
+}
+`;
+}

package/dist/plugin/surfaces.d.ts

@@ -0,0 +1,37 @@
+import type { ExtroConfig, ManifestV3 } from "../types/index.js";
+import type { AppTree } from "./app-tree.js";
+export type RoutableSurface = "popup" | "options" | "sidepanel";
+export type ScriptSurface = "background" | "content";
+export type SurfaceName = RoutableSurface | ScriptSurface;
+export type SurfaceKind = "routable" | "script";
+export interface SurfaceContext {
+    tree: AppTree;
+    config: ExtroConfig;
+    /** Set during `extro dev` so descriptors can adjust for dev-mode behavior. */
+    dev?: {
+        port: number;
+        signalPort: number;
+    };
+    /**
+     * Shippable Public asset paths (posix, relative to `public/`). Computed once
+     * in `generateManifest` so descriptors stay pure. The Content descriptor
+     * lists them in `web_accessible_resources`.
+     */
+    publicAssets?: string[];
+}
+export interface SurfaceDescriptor {
+    name: SurfaceName;
+    kind: SurfaceKind;
+    /** Whether this surface is materialized for the current build. */
+    isPresent: (ctx: SurfaceContext) => boolean;
+    /** Manifest fragment merged into the final manifest when present. */
+    manifestContribution: (ctx: SurfaceContext) => Partial<ManifestV3>;
+    /** Permissions added when present and the user hasn't supplied their own list. */
+    permissions?: (ctx: SurfaceContext) => readonly string[];
+    /** Host permissions added when present and the user hasn't supplied their own list. */
+    hostPermissions?: (ctx: SurfaceContext) => readonly string[];
+    /** Content surface flag: also accept `page.tsx` as the CSUI Mode. */
+    acceptsCsuiPage?: boolean;
+}
+export declare const SURFACES: readonly SurfaceDescriptor[];
+export declare function findSurface(name: string): SurfaceDescriptor | undefined;

package/dist/plugin/surfaces.js

@@ -0,0 +1,67 @@
+export const SURFACES = [
+    {
+        name: "popup",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.popup,
+        manifestContribution: () => ({ action: { default_popup: "popup.html" } }),
+    },
+    {
+        name: "options",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.options,
+        manifestContribution: () => ({
+            options_ui: { page: "options.html", open_in_tab: true },
+        }),
+    },
+    {
+        name: "sidepanel",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.sidepanel,
+        manifestContribution: () => ({ side_panel: { default_path: "sidepanel.html" } }),
+    },
+    {
+        name: "background",
+        kind: "script",
+        // In dev the bridge runs as the background SW even when the user has
+        // no BG file, so the surface is forced present.
+        isPresent: ({ tree, dev }) => !!tree.scripts.background || !!dev,
+        manifestContribution: () => ({
+            background: { service_worker: "background.js" },
+        }),
+        // `tabs` is added in dev so the bridge can call chrome.tabs.reload.
+        permissions: ({ dev }) => (dev ? ["storage", "tabs"] : ["storage"]),
+    },
+    {
+        name: "content",
+        kind: "script",
+        acceptsCsuiPage: true,
+        isPresent: ({ tree }) => !!tree.scripts.content,
+        manifestContribution: ({ tree, config, publicAssets }) => {
+            const matches = config.content?.matches ?? ["<all_urls>"];
+            const fragment = {
+                content_scripts: [{ matches, js: ["content.js"] }],
+            };
+            // Anything a content script reaches via chrome.runtime.getURL must be
+            // declared accessible. The CSUI mount runtime dynamic-imports
+            // content.js; Public assets are getURL'd by user code. Both ride one
+            // entry scoped to the content script's matches.
+            const resources = [];
+            if (tree.scripts.content?.csui)
+                resources.push("content.js");
+            if (publicAssets?.length)
+                resources.push(...publicAssets);
+            if (resources.length) {
+                fragment.web_accessible_resources = [{ resources, matches }];
+            }
+            return fragment;
+        },
+        hostPermissions: ({ config }) => config.content?.matches ?? ["<all_urls>"],
+    },
+];
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+const BY_NAME = new Map(SURFACES.map((s) => [s.name, s]));
+export function findSurface(name) {
+    return BY_NAME.get(name);
+}