extrojs 0.2.0 → 0.3.1

package/dist/plugin/index.js

@@ -0,0 +1,246 @@
+import path from "node:path";
+import { scanAppTree, routeManifest, APP_FILE_BASENAMES, } from "./app-tree.js";
+import { emitAssets } from "./emit-assets.js";
+import { discoverAssets } from "./asset-inventory.js";
+import { decideTreeReaction } from "./dev-reactions.js";
+import { SURFACES } from "./surfaces.js";
+import { emitIcons } from "./generators/icons.js";
+import { emitPublicAssets } from "./generators/public.js";
+import { emit } from "./runtimes/routes-module.js";
+import { generateRuntimeModule } from "./runtimes/runtime-module.js";
+import { DEV_BRIDGE_ENTRY_ID, DEV_BRIDGE_CONFIG_ID, DEV_BRIDGE_USER_BG_ID, loadDevBridgeClient, devBridgeConfigSource, devBridgeUserBackgroundSource, } from "./runtimes/dev-bridge.js";
+import { CSUI_ENTRY_ID, CSUI_CONFIG_ID, CSUI_USER_PAGE_ID, CSUI_USER_SCRIPT_ID, loadCSUIClient, csuiConfigSource, csuiUserPageSource, csuiUserScriptSource, } from "./runtimes/csui-mount.js";
+import { readJson } from "./utils/read-json.js";
+// Virtual IDs follow a slash-namespaced convention so each surface has its
+// own runtime + routes module. Resolved IDs are prefixed with "\0" per
+// Rollup's convention for internal/virtual modules.
+const routesId = (surface) => `virtual:extro/routes/${surface}`;
+const runtimeId = (surface) => `virtual:extro/runtime/${surface}`;
+const resolved = (id) => `\0${id}`;
+export function extro(options) {
+    const root = options.root;
+    const config = options.config ?? {};
+    const scriptsOnly = options.scriptsOnly ?? false;
+    const devBridge = options.devBridge;
+    const broadcastHmr = options.broadcastHmr;
+    let tree = { scripts: {}, surfaces: {} };
+    let pkg = {};
+    return {
+        name: "extro",
+        async config() {
+            tree = await scanAppTree(root);
+            const empty = Object.keys(tree.scripts).length === 0 &&
+                Object.keys(tree.surfaces).length === 0;
+            if (empty && !devBridge) {
+                // In dev with bridge, an entry-less project still gets a synthesized
+                // background SW for HMR signalling. Otherwise, complain.
+                throw new Error("Extro: No extension entrypoints found.\n\nExpected files like:\n  src/app/popup/page.tsx\n  src/app/options/page.tsx\n  src/app/sidepanel/page.tsx\n  src/app/background/index.ts\n  src/app/content/index.ts");
+            }
+            pkg = readJson("package.json", root) ?? {};
+            const input = {};
+            const contentEntry = tree.scripts.content?.csui
+                ? CSUI_ENTRY_ID
+                : tree.scripts.content?.script;
+            if (devBridge) {
+                // Force a background entry in dev — wraps user's BG (if any) with
+                // the WS bridge.
+                input.background = DEV_BRIDGE_ENTRY_ID;
+                if (contentEntry)
+                    input.content = contentEntry;
+            }
+            else if (scriptsOnly) {
+                if (tree.scripts.background)
+                    input.background = tree.scripts.background;
+                if (contentEntry)
+                    input.content = contentEntry;
+            }
+            else {
+                if (tree.scripts.background)
+                    input.background = tree.scripts.background;
+                if (contentEntry)
+                    input.content = contentEntry;
+                for (const surface of Object.keys(tree.surfaces)) {
+                    input[surface] = runtimeId(surface);
+                }
+            }
+            return {
+                // Extro owns `public/` emission through its own pipeline (collision
+                // guard + WAR list + dev-output parity), so Vite's native copy is
+                // off. See ADR 0004.
+                publicDir: false,
+                // Only EXTRO_PUBLIC_* is inlined into surfaces via import.meta.env.
+                // Exactly EXTRO_PUBLIC_, never EXTRO_ (that would leak EXTRO_CRX_KEY
+                // and other build-time vars into bundles). See ADR 0002.
+                envPrefix: "EXTRO_PUBLIC_",
+                build: {
+                    rollupOptions: {
+                        input,
+                        output: {
+                            entryFileNames: "[name].js",
+                        },
+                    },
+                },
+            };
+        },
+        async generateBundle() {
+            if (scriptsOnly)
+                return;
+            // One discovery pass feeds the manifest (pure), the icon emit, and the
+            // public emit. See the Asset inventory.
+            const inventory = discoverAssets(root, tree);
+            await emitAssets({ tree, inventory, pkg, config }, (fileName, source) => {
+                this.emitFile({ type: "asset", fileName, source });
+            });
+            emitIcons({ ctx: this, root, icons: inventory.icons });
+            emitPublicAssets({ ctx: this, root, publicAssets: inventory.public });
+        },
+        configureServer(server) {
+            if (scriptsOnly)
+                return;
+            const basenames = APP_FILE_BASENAMES.join(",");
+            server.watcher.add(path.join(root, `src/app/**/{${basenames}}.{ts,tsx}`));
+            // Warm the CSUI module into the dev server's module graph so its
+            // transitive imports are tracked too. Without this, content files
+            // never appear in handleHotUpdate's ctx.modules (the dev server
+            // only owns the routable surfaces — popup / options / sidepanel —
+            // as Rollup inputs), so edits under src/app/content/ would never
+            // produce an HMR payload for the BG-fetch RFR transport.
+            const csui = tree.scripts.content?.csui;
+            if (csui && broadcastHmr) {
+                const url = "/" + path.relative(root, csui).split(path.sep).join("/");
+                server.warmupRequest(url).catch(() => { });
+            }
+            // Same source as the scanner glob — see APP_FILE_BASENAMES.
+            const isAppEntry = new RegExp(`^src/app/[^/]+/(?:.+/)?(?:${APP_FILE_BASENAMES.join("|")})\\.tsx?$`);
+            const routableSurfaceList = SURFACES
+                .filter((s) => s.kind === "routable")
+                .map((s) => s.name);
+            const handleChange = async (file) => {
+                const rel = path.relative(root, file).split(path.sep).join("/");
+                if (!isAppEntry.test(rel))
+                    return;
+                const prevTree = tree;
+                tree = await scanAppTree(root);
+                // Decide the Dev reaction (pure); the handler owns the effects.
+                const reaction = decideTreeReaction(prevTree, tree, routableSurfaceList);
+                if (reaction.kind === "restart") {
+                    // A Surface born mid-session: its Rollup input was fixed at config()
+                    // time, so a fresh dev session is required to register the new entry.
+                    const what = reaction.surface === "background" || reaction.surface === "content"
+                        ? `${reaction.surface} entrypoint`
+                        : `${reaction.surface} surface`;
+                    console.log(`\n[extro] New ${what} detected. Restart \`extro dev\` to pick it up.\n`);
+                    return;
+                }
+                if (reaction.kind === "invalidate") {
+                    // Reload each changed surface's routes virtual module; the runtime
+                    // module's accept("virtual:extro/routes/<surface>") boundary picks
+                    // up the new array and calls handle.update without a remount.
+                    for (const surface of reaction.surfaces) {
+                        const mod = server.moduleGraph.getModuleById(resolved(routesId(surface)));
+                        if (mod) {
+                            await server.reloadModule(mod);
+                            console.log(`[extro] Routes updated for ${surface}.`);
+                        }
+                    }
+                }
+            };
+            server.watcher.on("add", handleChange);
+            server.watcher.on("unlink", handleChange);
+        },
+        resolveId(id) {
+            // Dev bridge virtuals
+            if (devBridge && id === DEV_BRIDGE_ENTRY_ID)
+                return resolved(DEV_BRIDGE_ENTRY_ID);
+            if (devBridge && id === DEV_BRIDGE_CONFIG_ID)
+                return resolved(DEV_BRIDGE_CONFIG_ID);
+            if (devBridge && id === DEV_BRIDGE_USER_BG_ID)
+                return resolved(DEV_BRIDGE_USER_BG_ID);
+            // CSUI virtuals
+            if (id === CSUI_ENTRY_ID)
+                return resolved(CSUI_ENTRY_ID);
+            if (id === CSUI_CONFIG_ID)
+                return resolved(CSUI_CONFIG_ID);
+            if (id === CSUI_USER_PAGE_ID)
+                return resolved(CSUI_USER_PAGE_ID);
+            if (id === CSUI_USER_SCRIPT_ID)
+                return resolved(CSUI_USER_SCRIPT_ID);
+            if (scriptsOnly)
+                return;
+            for (const desc of SURFACES) {
+                if (desc.kind !== "routable")
+                    continue;
+                const surface = desc.name;
+                if (id === runtimeId(surface))
+                    return resolved(runtimeId(surface));
+                if (id === routesId(surface))
+                    return resolved(routesId(surface));
+            }
+        },
+        load(id) {
+            // Dev bridge: entry + its config + the optional user-background re-export.
+            if (devBridge && id === resolved(DEV_BRIDGE_ENTRY_ID)) {
+                return loadDevBridgeClient();
+            }
+            if (devBridge && id === resolved(DEV_BRIDGE_CONFIG_ID)) {
+                return devBridgeConfigSource({
+                    signalPort: devBridge.signalPort,
+                    vitePort: devBridge.vitePort,
+                    hasCSUI: !!tree.scripts.content?.csui,
+                });
+            }
+            if (devBridge && id === resolved(DEV_BRIDGE_USER_BG_ID)) {
+                return devBridgeUserBackgroundSource(tree.scripts.background);
+            }
+            // CSUI mount: entry + its config + the user page + optional side-effect script.
+            const content = tree.scripts.content;
+            if (id === resolved(CSUI_ENTRY_ID) && content?.csui) {
+                return loadCSUIClient();
+            }
+            if (id === resolved(CSUI_CONFIG_ID)) {
+                return csuiConfigSource(!!devBridge);
+            }
+            if (id === resolved(CSUI_USER_PAGE_ID) && content?.csui) {
+                return csuiUserPageSource(content.csui);
+            }
+            if (id === resolved(CSUI_USER_SCRIPT_ID)) {
+                return csuiUserScriptSource(content?.script);
+            }
+            if (scriptsOnly)
+                return;
+            for (const desc of SURFACES) {
+                if (desc.kind !== "routable")
+                    continue;
+                const surface = desc.name;
+                if (id === resolved(runtimeId(surface))) {
+                    return generateRuntimeModule({ surface });
+                }
+                if (id === resolved(routesId(surface))) {
+                    return emit(routeManifest(tree, surface));
+                }
+            }
+        },
+        handleHotUpdate(ctx) {
+            if (!broadcastHmr)
+                return;
+            // Mirror Vite's own HMR `update` payload shape. Modules without a
+            // resolved url (rare — e.g. virtual-only) are skipped; the CSUI
+            // re-mount signal still covers those via `cs-rebuilt`. Content
+            // files reach this list naturally because configureServer warms the
+            // CSUI module into the graph at startup.
+            const updates = ctx.modules
+                .filter((m) => !!m.url)
+                .map((m) => ({
+                type: m.type === "css" ? "css-update" : "js-update",
+                path: m.url,
+                acceptedPath: m.url,
+                timestamp: ctx.timestamp,
+                explicitImportRequired: false,
+                isWithinCircularImport: false,
+            }));
+            if (updates.length === 0)
+                return;
+            broadcastHmr({ type: "update", updates });
+        },
+    };
+}

package/dist/plugin/internal.d.ts

@@ -0,0 +1,14 @@
+export { scanAppTree, routeManifest } from "./app-tree.js";
+export type { AppTree, ContentSlot } from "./app-tree.js";
+export type { ManifestRoute, RouteManifest } from "../types/index.js";
+export { emitAssets, composeArtifacts } from "./emit-assets.js";
+export type { EmitSink, AssetOptions, Artifacts } from "./emit-assets.js";
+export { discoverAssets } from "./asset-inventory.js";
+export type { AssetInventory } from "./asset-inventory.js";
+export type { PublicAssets } from "./public.js";
+export { classifyScriptChange, mergeDirty, resolveFlush } from "./dev-reactions.js";
+export type { ScriptDirty } from "./dev-reactions.js";
+export { renderDevScreen, devScreenStyles } from "./generators/html.js";
+export type { DevScreen } from "./generators/html.js";
+export { SURFACES } from "./surfaces.js";
+export type { RoutableSurface, ScriptSurface, SurfaceName, SurfaceKind, SurfaceContext, SurfaceDescriptor, } from "./surfaces.js";

package/dist/plugin/internal.js

@@ -0,0 +1,6 @@
+export { scanAppTree, routeManifest } from "./app-tree.js";
+export { emitAssets, composeArtifacts } from "./emit-assets.js";
+export { discoverAssets } from "./asset-inventory.js";
+export { classifyScriptChange, mergeDirty, resolveFlush } from "./dev-reactions.js";
+export { renderDevScreen, devScreenStyles } from "./generators/html.js";
+export { SURFACES } from "./surfaces.js";

package/dist/plugin/manifest.d.ts

@@ -0,0 +1,29 @@
+import type { ExtroConfig, ManifestV3 } from "../types/index.js";
+import type { AppTree } from "./app-tree.js";
+import type { AssetInventory } from "./asset-inventory.js";
+interface GenerateManifestOptions {
+    tree: AppTree;
+    /**
+     * The build's discovered icons + Public assets. Passed in as data so this
+     * generator never touches the filesystem: its inputs are the test surface.
+     */
+    inventory: AssetInventory;
+    pkg: {
+        name?: string;
+        description?: string;
+        version?: string;
+    };
+    config: ExtroConfig;
+    /**
+     * When set, the manifest is generated for a dev session:
+     *   - CSP relaxed for the Vite dev server + signal WS
+     *   - Background descriptor reports present (bridge runs there)
+     *   - Background descriptor adds `tabs` to permissions
+     */
+    dev?: {
+        port: number;
+        signalPort: number;
+    };
+}
+export declare function generateManifest({ tree, inventory, pkg, config, dev, }: GenerateManifestOptions): ManifestV3;
+export {};

package/dist/plugin/manifest.js

@@ -0,0 +1,68 @@
+import { SURFACES } from "./surfaces.js";
+export function generateManifest({ tree, inventory, pkg, config, dev, }) {
+    const manifest = {
+        manifest_version: 3,
+        name: config.name ?? pkg.name ?? "Extro Extension",
+        version: config.version ?? pkg.version ?? "0.0.1",
+    };
+    const description = config.description ?? pkg.description;
+    if (description) {
+        manifest.description = description;
+    }
+    const publicAssets = inventory.public.files;
+    const ctx = { tree, config, dev, publicAssets };
+    const permissions = new Set(config.permissions ?? []);
+    const hostPermissions = new Set(config.hostPermissions ?? []);
+    for (const desc of SURFACES) {
+        if (!desc.isPresent(ctx))
+            continue;
+        Object.assign(manifest, desc.manifestContribution(ctx));
+        if (!config.permissions && desc.permissions) {
+            for (const p of desc.permissions(ctx))
+                permissions.add(p);
+        }
+        if (!config.hostPermissions && desc.hostPermissions) {
+            for (const p of desc.hostPermissions(ctx))
+                hostPermissions.add(p);
+        }
+    }
+    if (permissions.size > 0) {
+        manifest.permissions = [...permissions];
+    }
+    if (hostPermissions.size > 0) {
+        manifest.host_permissions = [...hostPermissions];
+    }
+    const icons = config.icons ?? inventory.icons ?? undefined;
+    if (icons) {
+        manifest.icons = icons;
+    }
+    if (dev) {
+        // CSP relaxed for dev: Vite dev server (HTTP + HMR WS) + the CLI's
+        // signal WS that the dev bridge connects to.
+        const origin = `http://localhost:${dev.port}`;
+        const viteWs = `ws://localhost:${dev.port}`;
+        const signalWs = `ws://localhost:${dev.signalPort}`;
+        manifest.content_security_policy = {
+            extension_pages: [
+                `script-src 'self' ${origin} 'wasm-unsafe-eval'`,
+                `object-src 'self'`,
+                `connect-src 'self' ${origin} ${viteWs} ${signalWs}`,
+            ].join("; "),
+        };
+    }
+    // EXTRO_CRX_KEY pins the extension ID (ADR 0002). Set before the
+    // config.manifest merge so an explicit manifest.key still wins.
+    const crxKey = process.env.EXTRO_CRX_KEY;
+    if (crxKey) {
+        manifest.key = crxKey;
+    }
+    if (config.manifest) {
+        Object.assign(manifest, config.manifest);
+    }
+    // Final imperative hook: sees the fully generated manifest and may mutate it
+    // or return a replacement. Runs last so it can change anything (ADR 0008).
+    if (config.transformManifest) {
+        return config.transformManifest(manifest) ?? manifest;
+    }
+    return manifest;
+}

package/dist/plugin/public.d.ts

@@ -0,0 +1,21 @@
+import type { AppTree } from "./app-tree.js";
+/**
+ * @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 declare const PUBLIC_DIR = "public";
+export interface PublicAssets {
+    /** Posix-relative paths that will ship, sorted for stable output. */
+    files: string[];
+    /** Files skipped because their name collides with a generated output. */
+    conflicts: string[];
+}
+/**
+ * Partition `public/` into shippable files and conflicts. Returns empty
+ * lists when `public/` is absent.
+ */
+export declare function collectPublicAssets(root: string, tree: AppTree): PublicAssets;

package/dist/plugin/public.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEV_PROBE_FILE } from "./generators/html.js";
+/**
+ * @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;
+    // Dev-only output, but reserved in all modes so the partition (and the
+    // web_accessible_resources list derived from it) doesn't depend on the
+    // build mode.
+    if (name === DEV_PROBE_FILE)
+        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);