npm - extrojs - Versions diffs - 0.1.0 → 0.3.0 - Mend

extrojs 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/README.md +3 -3
package/client.d.ts +8 -0
package/dist/cli.d.ts +7 -0
package/dist/cli.js +27 -0
package/dist/commands/build.d.ts +5 -0
package/dist/commands/build.js +26 -0
package/dist/commands/dev.d.ts +7 -0
package/dist/commands/dev.js +156 -0
package/dist/config.d.ts +2 -2
package/dist/core/asset.d.ts +10 -0
package/dist/core/asset.js +10 -0
package/dist/dev-assets.d.ts +3 -3
package/dist/dev-assets.js +33 -12
package/dist/env.d.ts +10 -0
package/dist/env.js +18 -0
package/dist/exports/asset.d.ts +1 -0
package/dist/exports/asset.js +1 -0
package/dist/exports/link.d.ts +1 -0
package/dist/exports/link.js +1 -0
package/dist/exports/navigation.d.ts +2 -0
package/dist/exports/navigation.js +1 -0
package/dist/exports/runtime.d.ts +2 -0
package/dist/exports/runtime.js +3 -0
package/dist/index.js +5 -136
package/dist/load-config.d.ts +1 -1
package/dist/logger.d.ts +34 -0
package/dist/logger.js +65 -0
package/dist/paths.d.ts +8 -0
package/dist/paths.js +8 -0
package/dist/pkg.d.ts +6 -0
package/dist/pkg.js +5 -0
package/dist/plugin/app-tree.d.ts +59 -0
package/dist/plugin/app-tree.js +214 -0
package/dist/plugin/asset-inventory.d.ts +24 -0
package/dist/plugin/asset-inventory.js +9 -0
package/dist/plugin/dev-reactions.d.ts +59 -0
package/dist/plugin/dev-reactions.js +62 -0
package/dist/plugin/emit-assets.d.ts +50 -0
package/dist/plugin/emit-assets.js +40 -0
package/dist/plugin/generators/html.d.ts +39 -0
package/dist/plugin/generators/html.js +127 -0
package/dist/plugin/generators/icons.d.ts +15 -0
package/dist/plugin/generators/icons.js +16 -0
package/dist/plugin/generators/public.d.ts +17 -0
package/dist/plugin/generators/public.js +20 -0
package/dist/plugin/icons.d.ts +5 -0
package/dist/plugin/icons.js +20 -0
package/dist/plugin/index.d.ts +31 -0
package/dist/plugin/index.js +246 -0
package/dist/plugin/internal.d.ts +14 -0
package/dist/plugin/internal.js +6 -0
package/dist/plugin/manifest.d.ts +29 -0
package/dist/plugin/manifest.js +68 -0
package/dist/plugin/public.d.ts +21 -0
package/dist/plugin/public.js +63 -0
package/dist/plugin/runtimes/clients/csui-mount.js +90 -0
package/dist/plugin/runtimes/clients/dev-bridge.js +194 -0
package/dist/plugin/runtimes/csui-mount.d.ts +18 -0
package/dist/plugin/runtimes/csui-mount.js +21 -0
package/dist/plugin/runtimes/dev-bridge.d.ts +22 -0
package/dist/plugin/runtimes/dev-bridge.js +19 -0
package/dist/plugin/runtimes/routes-module.d.ts +20 -0
package/dist/plugin/runtimes/routes-module.js +51 -0
package/dist/plugin/runtimes/runtime-module.d.ts +16 -0
package/dist/plugin/runtimes/runtime-module.js +40 -0
package/dist/plugin/surfaces.d.ts +37 -0
package/dist/plugin/surfaces.js +67 -0
package/dist/plugin/types/index.d.ts +9 -0
package/dist/plugin/types/index.js +1 -0
package/dist/plugin/utils/read-json.d.ts +1 -0
package/dist/plugin/utils/read-json.js +8 -0
package/dist/react/env.d.ts +13 -0
package/dist/react/env.js +1 -0
package/dist/router/build-tree.d.ts +46 -0
package/dist/router/build-tree.js +56 -0
package/dist/router/context.d.ts +13 -0
package/dist/router/context.js +2 -0
package/dist/router/create-router.d.ts +10 -0
package/dist/router/create-router.js +126 -0
package/dist/router/defaults.d.ts +24 -0
package/dist/router/defaults.js +25 -0
package/dist/router/error-boundary.d.ts +23 -0
package/dist/router/error-boundary.js +21 -0
package/dist/router/hooks.d.ts +18 -0
package/dist/router/hooks.js +34 -0
package/dist/router/index.d.ts +8 -0
package/dist/router/index.js +7 -0
package/dist/router/link.d.ts +305 -0
package/dist/router/link.js +30 -0
package/dist/router/match.d.ts +14 -0
package/dist/router/match.js +27 -0
package/dist/router/types.d.ts +55 -0
package/dist/router/types.js +1 -0
package/dist/types/index.d.ts +152 -0
package/dist/types/index.js +1 -0
package/package.json +47 -9

package/dist/plugin/generators/html.js ADDED Viewed

@@ -0,0 +1,127 @@
+/**
+ * @describe Generates the HTML shell for a surface. In dev mode, the shell
+ * points at the Vite dev server (with @vite/client for HMR) instead of the
+ * built bundle, and pre-renders a brand-styled "dev server offline" screen
+ * inside #root. React's createRoot replaces #root's children on mount, so
+ * the screen vanishes on a normal start; if the dev server never comes up,
+ * the screen stays visible.
+ */
+export function generateHTML({ surface, dev }) {
+    const title = surface.charAt(0).toUpperCase() + surface.slice(1);
+    const scripts = dev
+        ? `
+      <script type="module" src="http://localhost:${dev.port}/@vite/client"></script>
+      <script type="module" src="http://localhost:${dev.port}/@id/@vitejs/plugin-react/preamble"></script>
+      <script type="module" src="http://localhost:${dev.port}/@id/virtual:extro/runtime/${surface}"></script>
+    `
+        : `<script type="module" src="./${surface}.js"></script>`;
+    const rootContent = dev
+        ? renderDevScreen({
+            title: "Dev server isn't running",
+            body: `
+          <p>Start it with <code>extro dev</code>, then reopen this surface.</p>
+          <p>Expected at <code>http://localhost:${dev.port}</code>.</p>
+        `,
+            // Popups size to content (no viewport to fill); everything else
+            // (options/sidepanel/tab) gets a full-viewport centered layout.
+            fill: surface !== "popup",
+        })
+        : "";
+    return `
+  <!doctype html>
+  <html>
+    <head>
+      <title>${title}</title>
+      ${dev ? devScreenStyles() : ""}
+    </head>
+    <body>
+      <div id="root">${rootContent}</div>
+      ${scripts.trim()}
+    </body>
+  </html>
+  `.trim();
+}
+/**
+ * @describe Renders a brand-styled "developer screen" card. Used as the
+ * pre-render inside #root for offline-dev-server fallback today, intended
+ * for reuse in other build-time / runtime dev panels.
+ */
+export const renderDevScreen = ({ title, body, fill = false }) => {
+    const cls = `extro-dev-screen${fill ? " extro-dev-screen--fill" : ""}`;
+    return `
+<div class="${cls}">
+  <div class="extro-dev-screen__card">
+    <span class="extro-dev-screen__tag">EXTRO</span>
+    <h1>${title}</h1>
+    ${body.trim()}
+  </div>
+</div>
+`.trim();
+};
+/**
+ * @describe Global styles for any `.extro-dev-screen` rendered in dev. Body
+ * is painted dark only while a screen is in the DOM (via `:has()`), so the
+ * user's app reverts to default styling once React mounts.
+ */
+export const devScreenStyles = () => `
+<style>
+  body { margin: 0; }
+  body:has(.extro-dev-screen) { background: #0a0a0a; }
+  .extro-dev-screen {
+    box-sizing: border-box;
+    min-width: 360px;
+    min-height: 240px;
+    padding: 24px 28px;
+    background: #0a0a0a;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+    animation: extro-dev-screen-in 0.18s 0.05s forwards;
+  }
+  .extro-dev-screen--fill {
+    min-height: 100vh;
+  }
+  .extro-dev-screen__card {
+    box-sizing: border-box;
+    width: 100%;
+    max-width: 480px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+    color: #e5e5e5;
+  }
+  .extro-dev-screen__tag {
+    align-self: flex-start;
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    padding: 3px 8px;
+    color: #0a0a0a;
+    background: #CC785C;
+    border-radius: 3px;
+  }
+  .extro-dev-screen h1 {
+    margin: 4px 0 0;
+    font-size: 15px;
+    font-weight: 600;
+    color: #fafafa;
+  }
+  .extro-dev-screen p {
+    margin: 0;
+    font-size: 13px;
+    line-height: 1.5;
+    color: #a3a3a3;
+  }
+  .extro-dev-screen code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 12px;
+    padding: 1px 6px;
+    color: #CC785C;
+    background: #1a1a1a;
+    border-radius: 3px;
+  }
+  @keyframes extro-dev-screen-in { to { opacity: 1; } }
+</style>
+`.trim();

package/dist/plugin/generators/icons.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import type { PluginContextLike } from "../types/index.js";
+interface EmitIconsOptions {
+    ctx: PluginContextLike;
+    root: string;
+    /** The recognized icon set from the Asset inventory (size -> "icons/16.png"). */
+    icons: Record<string, string> | null;
+}
+/**
+ * @file generators/icons.ts
+ * @description Emits the recognized extension icons named by the Asset
+ * inventory. Discovery already decided which sizes exist, so this only reads
+ * bytes: what ships is exactly what `manifest.icons` references.
+ */
+export declare function emitIcons({ ctx, root, icons }: EmitIconsOptions): void;
+export {};

package/dist/plugin/generators/icons.js ADDED Viewed

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * @file generators/icons.ts
+ * @description Emits the recognized extension icons named by the Asset
+ * inventory. Discovery already decided which sizes exist, so this only reads
+ * bytes: what ships is exactly what `manifest.icons` references.
+ */
+export function emitIcons({ ctx, root, icons }) {
+    if (!icons)
+        return;
+    for (const rel of Object.values(icons)) {
+        const source = fs.readFileSync(path.join(root, rel));
+        ctx.emitFile({ type: "asset", fileName: rel, source });
+    }
+}

package/dist/plugin/generators/public.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+import type { PluginContextLike } from "../types/index.js";
+import { type PublicAssets } from "../public.js";
+interface EmitPublicAssetsOptions {
+    ctx: PluginContextLike;
+    root: string;
+    /** The partitioned Public assets from the Asset inventory. */
+    publicAssets: PublicAssets;
+}
+/**
+ * @file generators/public.ts
+ * @description Emits Public assets into the build output with their original
+ * names, from the partition the Asset inventory already computed. Mirrors
+ * `emitIcons`; the collision guard skips any file that would overwrite a
+ * generated output and warns instead.
+ */
+export declare function emitPublicAssets({ ctx, root, publicAssets }: EmitPublicAssetsOptions): void;
+export {};

package/dist/plugin/generators/public.js ADDED Viewed

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PUBLIC_DIR } from "../public.js";
+/**
+ * @file generators/public.ts
+ * @description Emits Public assets into the build output with their original
+ * names, from the partition the Asset inventory already computed. Mirrors
+ * `emitIcons`; the collision guard skips any file that would overwrite a
+ * generated output and warns instead.
+ */
+export function emitPublicAssets({ ctx, root, publicAssets }) {
+    const { files, conflicts } = publicAssets;
+    for (const conflict of conflicts) {
+        ctx.warn(`public/${conflict} collides with a generated output; skipping. Rename it to ship it.`);
+    }
+    for (const file of files) {
+        const source = fs.readFileSync(path.join(root, PUBLIC_DIR, file));
+        ctx.emitFile({ type: "asset", fileName: file, source });
+    }
+}

package/dist/plugin/icons.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+/**
+ * @file icons.ts
+ * @description Detects the icons for the extension.
+ */
+export declare function detectIcons(root: string): Record<string, string> | undefined;

package/dist/plugin/icons.js ADDED Viewed

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * @file icons.ts
+ * @description Detects the icons for the extension.
+ */
+export function detectIcons(root) {
+    const iconsDir = path.join(root, "icons");
+    if (!fs.existsSync(iconsDir))
+        return undefined;
+    const sizes = ["16", "32", "48", "128"];
+    const icons = {};
+    for (const size of sizes) {
+        const file = path.join(iconsDir, `${size}.png`);
+        if (fs.existsSync(file)) {
+            icons[size] = `icons/${size}.png`;
+        }
+    }
+    return Object.keys(icons).length ? icons : undefined;
+}

package/dist/plugin/index.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import type { Plugin } from "vite";
+import type { ExtroConfig } from "../types/index.js";
+interface ExtroPluginOptions {
+    root: string;
+    config?: ExtroConfig;
+    /**
+     * When true, only background/content are bundled. Manifest + HTML emission
+     * is skipped (writeDevAssets handles those separately during `extro dev`).
+     * Used by the dev build-watch sidecar.
+     */
+    scriptsOnly?: boolean;
+    /**
+     * When set, wrap the background entry in the dev bridge so a service
+     * worker exists in dev mode (even if the user didn't write one) to
+     * receive rebuild signals from the CLI's WS server and forward Vite HMR
+     * events to content scripts.
+     */
+    devBridge?: {
+        signalPort: number;
+        vitePort: number;
+    };
+    /**
+     * Called from the dev-server plugin's `handleHotUpdate` with a payload
+     * shaped like Vite's own HMR `update` event. The CLI uses this to
+     * broadcast HMR over the signal WS (avoiding Vite's HMR WS, whose
+     * origin check rejects chrome-extension:// service workers).
+     */
+    broadcastHmr?: (payload: object) => void;
+}
+export declare function extro(options: ExtroPluginOptions): Plugin;
+export {};

package/dist/plugin/index.js ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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;