extrojs 0.1.0 → 0.2.0

package/README.md

@@ -16,11 +16,11 @@ pnpm add react react-dom
 ## Quick start
 
 ```bash
-extro dev      # dev server with HMR, writes .output/chrome-mv3-dev/
-extro build    # production build to .output/chrome-mv3-prod/
+extro dev      # dev server with HMR, writes output/chrome-mv3-dev/
+extro build    # production build to output/chrome-mv3-prod/
 ```
 
-Load `.output/chrome-mv3-dev/` (or `.output/chrome-mv3-prod/`) in Chrome via **Load Unpacked**.
+Load `output/chrome-mv3-dev/` (or `output/chrome-mv3-prod/`) in Chrome via **Load Unpacked**.
 
 ## Docs and source
 

package/client.d.ts

@@ -0,0 +1,16 @@
+// Ambient types for Extro's env. Opt in from a project by adding:
+//   /// <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
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @describe Parses argv and dispatches. cac itself prints --help/--version
+ * during parse() (scoped to the matched command), so we only handle the
+ * fallback: bare `extro` and unknown commands print top-level help (exit 0
+ * when bare, exit 1 when the command was unknown).
+ */
+export declare const run: () => Promise<void>;

package/dist/cli.js

@@ -0,0 +1,27 @@
+import { cac } from "cac";
+import { pkg } from "./pkg.js";
+import { dev } from "./commands/dev.js";
+import { build } from "./commands/build.js";
+const cli = cac("extro");
+cli.command("dev", "Start the dev server with HMR").action(dev);
+cli.command("build", "Build a production extension bundle").action(build);
+cli.help();
+cli.version(pkg.version);
+/**
+ * @describe Parses argv and dispatches. cac itself prints --help/--version
+ * during parse() (scoped to the matched command), so we only handle the
+ * fallback: bare `extro` and unknown commands print top-level help (exit 0
+ * when bare, exit 1 when the command was unknown).
+ */
+export const run = async () => {
+    const parsed = cli.parse(process.argv, { run: false });
+    // cac has already printed help/version to stdout at this point.
+    if (parsed.options.help || parsed.options.version)
+        return;
+    if (!cli.matchedCommand) {
+        cli.outputHelp();
+        process.exitCode = process.argv.slice(2).length > 0 ? 1 : 0;
+        return;
+    }
+    await cli.runMatchedCommand();
+};

package/dist/commands/build.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @describe Produces a standalone production bundle in
+ * <outDir>/chrome-mv3-prod/: manifest, HTML shells, and script bundles.
+ */
+export declare const build: () => Promise<void>;

package/dist/commands/build.js

@@ -0,0 +1,26 @@
+import { build as viteBuild } from "vite";
+import { extro } from "@extrojs/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { loadConfig } from "../load-config.js";
+import { loadEnvIntoProcess } from "../env.js";
+import { outputDir } from "../paths.js";
+import { createViteLogger, log } from "../logger.js";
+/**
+ * @describe Produces a standalone production bundle in
+ * <outDir>/chrome-mv3-prod/: manifest, HTML shells, and script bundles.
+ */
+export const build = async () => {
+    const root = process.cwd();
+    log.info("Building extension for production...");
+    loadEnvIntoProcess(root, "production");
+    const config = await loadConfig(root);
+    const prodOutDir = outputDir(root, config, "prod");
+    await viteBuild({
+        root,
+        plugins: [react(), extro({ root, config })],
+        build: { outDir: prodOutDir },
+        customLogger: createViteLogger(),
+    });
+    log.success("Build complete");
+    log.info(`Unpacked extension: ${prodOutDir}`);
+};

package/dist/commands/dev.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @describe Starts the Extro dev server: a Vite server for routable surfaces, a
+ * signal WS the extension's BG SW connects to, and a build-watch sidecar for
+ * background + content scripts. Writes the dev manifest/HTML into the dev
+ * output dir and wires SIGINT/SIGTERM to a clean shutdown.
+ */
+export declare const dev: () => Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,173 @@
+import { createServer, build as viteBuild } from "vite";
+import { WebSocketServer } from "ws";
+import { extro } from "@extrojs/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { scanAppTree } from "@extrojs/vite-plugin/internal";
+import { loadConfig } from "../load-config.js";
+import { loadEnvIntoProcess } from "../env.js";
+import { outputDir } from "../paths.js";
+import { writeDevAssets } from "../dev-assets.js";
+import { pkg } from "../pkg.js";
+import { banner, createViteLogger, log } from "../logger.js";
+const once = (emitter, event) => new Promise((resolve) => emitter.once(event, () => resolve()));
+/**
+ * @describe Throws a helpful error when the user's src/app has no entrypoints,
+ * so `extro dev` fails fast with guidance instead of starting an empty server.
+ */
+const validateTree = (tree) => {
+    const empty = Object.keys(tree.scripts).length === 0 &&
+        Object.keys(tree.surfaces).length === 0;
+    if (!empty)
+        return;
+    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");
+};
+/**
+ * @describe Starts the Extro dev server: a Vite server for routable surfaces, a
+ * signal WS the extension's BG SW connects to, and a build-watch sidecar for
+ * background + content scripts. Writes the dev manifest/HTML into the dev
+ * output dir and wires SIGINT/SIGTERM to a clean shutdown.
+ */
+export const dev = async () => {
+    const root = process.cwd();
+    loadEnvIntoProcess(root, "development");
+    const config = await loadConfig(root);
+    // Separate output dirs let dev artifacts (with the bridge installed) persist
+    // across `extro dev` sessions without needing a prod-restore on shutdown.
+    const devOutDir = outputDir(root, config, "dev");
+    // 1. Scan once up front so we can decide what to start.
+    const tree = await scanAppTree(root);
+    validateTree(tree);
+    // 2. Signal WS — the dev bridge in the extension's BG SW connects here.
+    //    Fixed port (not :0) so the port baked into a previously-loaded BG SW
+    //    keeps working across `extro dev` restarts — otherwise users have to
+    //    refresh the extension every time to pick up a new random port.
+    const signalPort = config.dev?.bridgePort ?? 9012;
+    const wss = new WebSocketServer({ port: signalPort });
+    wss.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            log.error(`Signal port ${signalPort} is in use. Is another \`extro dev\` already running?`);
+            process.exit(1);
+        }
+        throw err;
+    });
+    await once(wss, "listening");
+    const broadcast = (msg) => {
+        const payload = JSON.stringify(msg);
+        for (const client of wss.clients) {
+            if (client.readyState === 1)
+                client.send(payload);
+        }
+    };
+    // 3. Vite dev server for routable surfaces.
+    //    `broadcastHmr` lets the plugin push HMR updates over our signal WS —
+    //    we can't piggy-back on Vite's own HMR WS because its origin check
+    //    rejects chrome-extension:// service workers.
+    const viteLogger = createViteLogger();
+    const server = await createServer({
+        root,
+        plugins: [
+            react(),
+            extro({
+                root,
+                config,
+                broadcastHmr: (payload) => broadcast({ kind: "vite-hmr", payload }),
+            }),
+        ],
+        server: { cors: true, port: config.dev?.port, strictPort: config.dev?.strictPort },
+        // Keep the user's scrollback + our banner; Vite clears the terminal by
+        // default on start and on each HMR.
+        clearScreen: false,
+        customLogger: viteLogger,
+    });
+    await server.listen();
+    const addr = server.httpServer?.address();
+    const port = addr && typeof addr === "object"
+        ? addr.port
+        : server.config.server.port ?? 5173;
+    // 4. Dev manifest + HTML + icons.
+    await writeDevAssets({ tree, root, outDir: devOutDir, port, signalPort, config });
+    // 5. Build-watch sidecar for background + content. Always runs in dev so
+    //    the dev bridge gets bundled into background.js (even if the user has
+    //    no BG of their own).
+    const watcher = await viteBuild({
+        root,
+        // Same mode as the dev server (createServer defaults to development) so
+        // background/content resolve the same .env set as the routables. Without
+        // this the sidecar defaults to production and the scripts would load
+        // .env.production while the popup loads .env.development. See ADR 0002.
+        mode: "development",
+        plugins: [extro({ root, config, scriptsOnly: true, devBridge: { signalPort, vitePort: port } })],
+        // emptyOutDir: false so the watcher doesn't wipe the manifest / HTML /
+        // icons that writeDevAssets just put down.
+        build: { watch: {}, emptyOutDir: false, outDir: devOutDir },
+        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.
+    if (watcher && typeof watcher.on === "function") {
+        const w = watcher;
+        let bgDirty = false;
+        let csDirty = 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;
+            }
+        });
+        w.on("event", (event) => {
+            if (event.code !== "BUNDLE_END")
+                return;
+            if (!bgDirty && !csDirty) {
+                bgDirty = true;
+                csDirty = true;
+            }
+            if (bgDirty)
+                broadcast({ kind: "bg-rebuilt" });
+            if (csDirty)
+                broadcast({ kind: "cs-rebuilt" });
+            bgDirty = false;
+            csDirty = false;
+        });
+    }
+    banner({
+        mode: "dev",
+        version: pkg.version,
+        rows: [
+            { label: "Server", value: `http://localhost:${port}` },
+            { label: "Unpacked", value: devOutDir },
+        ],
+        hint: 'Load the unpacked dir in Chrome via "Load Unpacked".',
+    });
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        process.off("SIGINT", shutdown);
+        process.off("SIGTERM", shutdown);
+        log.info("Shutting down dev server...");
+        if (watcher && typeof watcher.close === "function") {
+            await watcher.close();
+        }
+        wss.close();
+        await server.close();
+        // No prod-restore: dev artifacts live in their own output/chrome-mv3-dev
+        // dir so the loaded extension stays untouched. Run `extro build` for a
+        // standalone prod bundle in output/chrome-mv3-prod.
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+};

package/dist/dev-assets.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { emitAssets, } from "@extrojs/vite-plugin/internal";
+import { emitAssets, collectPublicAssets, } from "@extrojs/vite-plugin/internal";
 /**
  * @describe Writes the dev manifest + HTML shells + icons to disk so Chrome
  * can load the unpacked extension while the Vite dev server serves modules
@@ -13,6 +13,7 @@ export const writeDevAssets = async ({ tree, root, outDir, port, signalPort, con
     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);
 };
 const copyIcons = async (root, outDir) => {
     const srcDir = path.join(root, "icons");
@@ -24,3 +25,21 @@ const copyIcons = async (root, outDir) => {
     const files = await fs.readdir(srcDir);
     await Promise.all(files.map((f) => fs.copyFile(path.join(srcDir, f), path.join(dstDir, f))));
 };
+/**
+ * @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
+ * generated output.
+ */
+const copyPublic = async (root, outDir, tree) => {
+    const { files, conflicts } = collectPublicAssets(root, tree);
+    for (const conflict of conflicts) {
+        console.warn(`[extro] public/${conflict} collides with a generated output; skipping. Rename it to ship it.`);
+    }
+    await Promise.all(files.map(async (rel) => {
+        const dst = path.join(outDir, rel);
+        await fs.mkdir(path.dirname(dst), { recursive: true });
+        await fs.copyFile(path.join(root, "public", rel), dst);
+    }));
+};

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @describe Loads `.env` files into `process.env` before config is read, so
+ * `extro.config.ts` and manifest generation (the build-time env tier) can see
+ * them. Uses Vite's own `loadEnv` with an empty prefix (all vars, same
+ * stacking as `import.meta.env`), and does NOT override existing keys, so real
+ * process env (CI) wins over `.env` files. The public tier (`EXTRO_PUBLIC_*`
+ * via `import.meta.env`) is handled separately by Vite's `envPrefix`. See ADR
+ * 0002.
+ */
+export declare const loadEnvIntoProcess: (root: string, mode: "development" | "production") => void;

package/dist/env.js

@@ -0,0 +1,18 @@
+import { loadEnv } from "vite";
+/**
+ * @describe Loads `.env` files into `process.env` before config is read, so
+ * `extro.config.ts` and manifest generation (the build-time env tier) can see
+ * them. Uses Vite's own `loadEnv` with an empty prefix (all vars, same
+ * stacking as `import.meta.env`), and does NOT override existing keys, so real
+ * process env (CI) wins over `.env` files. The public tier (`EXTRO_PUBLIC_*`
+ * via `import.meta.env`) is handled separately by Vite's `envPrefix`. See ADR
+ * 0002.
+ */
+export const loadEnvIntoProcess = (root, mode) => {
+    const env = loadEnv(mode, root, "");
+    for (const [key, value] of Object.entries(env)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+};

package/dist/index.js

@@ -1,137 +1,6 @@
 #!/usr/bin/env node
-import path from "node:path";
-import { createServer, build as viteBuild } from "vite";
-import { WebSocketServer } from "ws";
-import { extro } from "@extrojs/vite-plugin";
-import react from "@vitejs/plugin-react";
-import { scanAppTree } from "@extrojs/vite-plugin/internal";
-import { loadConfig } from "./load-config.js";
-import { writeDevAssets } from "./dev-assets.js";
-const command = process.argv[2];
-const root = process.cwd();
-// Separate output dirs let dev artifacts (with the bridge installed) persist
-// across `extro dev` sessions without needing a prod-restore on shutdown.
-const devOutDir = path.join(root, ".output", "chrome-mv3-dev");
-const prodOutDir = path.join(root, ".output", "chrome-mv3-prod");
-const dev = async () => {
-    const config = await loadConfig(root);
-    // 1. Scan once up front so we can decide what to start.
-    const tree = await scanAppTree(root);
-    validateTree(tree);
-    // 2. Signal WS — the dev bridge in the extension's BG SW connects here.
-    //    Fixed port (not :0) so the port baked into a previously-loaded BG SW
-    //    keeps working across `extro dev` restarts — otherwise users have to
-    //    refresh the extension every time to pick up a new random port.
-    const signalPort = 9012;
-    const wss = new WebSocketServer({ port: signalPort });
-    wss.on("error", (err) => {
-        if (err.code === "EADDRINUSE") {
-            console.error(`\n[extro] Signal port ${signalPort} is in use — is another \`extro dev\` already running?\n`);
-            process.exit(1);
-        }
-        throw err;
-    });
-    await once(wss, "listening");
-    const broadcast = (msg) => {
-        const payload = JSON.stringify(msg);
-        for (const client of wss.clients) {
-            if (client.readyState === 1)
-                client.send(payload);
-        }
-    };
-    // 3. Vite dev server for routable surfaces.
-    //    `broadcastHmr` lets the plugin push HMR updates over our signal WS —
-    //    we can't piggy-back on Vite's own HMR WS because its origin check
-    //    rejects chrome-extension:// service workers.
-    const server = await createServer({
-        root,
-        plugins: [
-            react(),
-            extro({
-                root,
-                config,
-                broadcastHmr: (payload) => broadcast({ kind: "vite-hmr", payload }),
-            }),
-        ],
-        server: { cors: true },
-    });
-    await server.listen();
-    const addr = server.httpServer?.address();
-    const port = addr && typeof addr === "object" ? addr.port : server.config.server.port ?? 5173;
-    // 4. Dev manifest + HTML + icons.
-    await writeDevAssets({ tree, root, outDir: devOutDir, port, signalPort, config });
-    // 5. Build-watch sidecar for background + content. Always runs in dev so
-    //    the dev bridge gets bundled into background.js (even if the user has
-    //    no BG of their own).
-    const watcher = await viteBuild({
-        root,
-        plugins: [extro({ root, config, scriptsOnly: true, devBridge: { signalPort } })],
-        // emptyOutDir: false so the watcher doesn't wipe the manifest / HTML /
-        // icons that writeDevAssets just put down.
-        build: { watch: {}, emptyOutDir: false, outDir: devOutDir },
-        logLevel: "error",
-    });
-    // The watcher is a RollupWatcher; bundle events fire on every rebuild
-    // (including the first one). Broadcast on each so the bridge reloads.
-    if (watcher && typeof watcher.on === "function") {
-        ;
-        watcher.on("event", (event) => {
-            if (event.code === "BUNDLE_END") {
-                broadcast({ kind: "scripts-rebuilt" });
-            }
-        });
-    }
-    console.log(`\nExtro dev server: http://localhost:${port}`);
-    console.log(`Load unpacked extension from: ${devOutDir}\n`);
-    let shuttingDown = false;
-    const shutdown = async () => {
-        if (shuttingDown) {
-            console.log("\nAlready shutting down, please wait...");
-            return;
-        }
-        shuttingDown = true;
-        console.log("\nShutting down dev server...");
-        if (watcher && typeof watcher.close === "function") {
-            await watcher.close();
-        }
-        wss.close();
-        await server.close();
-        // No prod-restore: dev artifacts live in their own .output/chrome-mv3-dev
-        // dir so the loaded extension stays untouched. Run `extro build` for a
-        // standalone prod bundle in .output/chrome-mv3-prod.
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-};
-const validateTree = (tree) => {
-    const empty = Object.keys(tree.scripts).length === 0 &&
-        Object.keys(tree.surfaces).length === 0;
-    if (!empty)
-        return;
-    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");
-};
-const once = (emitter, event) => new Promise((resolve) => emitter.once(event, () => resolve()));
-const build = async () => {
-    console.log("Building extension...");
-    const config = await loadConfig(root);
-    await viteBuild({
-        root,
-        plugins: [react(), extro({ root, config })],
-        build: { outDir: prodOutDir },
-    });
-    console.log(`Build complete. Load unpacked extension from: ${prodOutDir}`);
-};
-switch (command) {
-    case "dev":
-        await dev();
-        break;
-    case "build":
-        await build();
-        break;
-    case "init":
-        console.log("Initializing Extro project...");
-        break;
-    default:
-        console.log("Extro CLI");
-}
+import { run } from "./cli.js";
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/logger.d.ts

@@ -0,0 +1,34 @@
+import { type Logger } from "vite";
+interface BannerRow {
+    label: string;
+    value: string;
+}
+interface BannerOptions {
+    mode: string;
+    version: string;
+    rows: BannerRow[];
+    hint?: string;
+}
+export declare const log: {
+    success: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    /** Low-key line for frequent, low-importance output (e.g. HMR updates).
+     *  Multi-line input is prefixed per line so the `›` rail stays continuous. */
+    muted: (msg: string) => void;
+};
+/**
+ * @describe A Vite `customLogger` that rebadges Vite's own info chatter
+ * (HMR updates, page reloads, dep optimization, "building for production",
+ * bundle sizes, etc.) as Extro `›` muted lines. Warnings + errors still
+ * pass through Vite's logger untouched so they keep their semantics.
+ */
+export declare const createViteLogger: () => Logger;
+/**
+ * @describe Prints the grouped startup banner: a brand tag with version/mode,
+ * then aligned label/value rows and an optional dimmed hint. Mirrors Vite's
+ * own startup idiom so the two read as a coherent stack.
+ */
+export declare const banner: ({ mode, version, rows, hint }: BannerOptions) => void;
+export {};

package/dist/logger.js

@@ -0,0 +1,65 @@
+import pc from "picocolors";
+import { createLogger } from "vite";
+// Extro brand terracotta (#CC785C) on the logo's near-black (#0a0a0a).
+// picocolors only does the 16 ANSI names, so emit 24-bit truecolor directly,
+// gated on the same color-support check picocolors uses (auto-plain in pipes).
+const brand = (s) => pc.isColorSupported ? `\x1b[38;2;204;120;92m${s}\x1b[39m` : s;
+const brandTag = (s) => pc.isColorSupported
+    ? `\x1b[1m\x1b[48;2;204;120;92m\x1b[38;2;10;10;10m${s}\x1b[0m`
+    : s;
+const tag = brandTag(" EXTRO ");
+// Status prefixes stay conventional (green/yellow/red are universal terminal
+// semantics); the Extro "voice" (tag, `›`, accents) carries the brand color.
+export const log = {
+    success: (msg) => console.log(`${pc.green("✓")} ${msg}`),
+    info: (msg) => console.log(`${brand("›")} ${msg}`),
+    warn: (msg) => console.warn(`${pc.yellow("⚠")} ${msg}`),
+    error: (msg) => console.error(`${pc.red("✗")} ${msg}`),
+    /** Low-key line for frequent, low-importance output (e.g. HMR updates).
+     *  Multi-line input is prefixed per line so the `›` rail stays continuous. */
+    muted: (msg) => {
+        for (const line of msg.split("\n"))
+            console.log(pc.dim(`›  ${line}`));
+    },
+};
+/**
+ * @describe A Vite `customLogger` that rebadges Vite's own info chatter
+ * (HMR updates, page reloads, dep optimization, "building for production",
+ * bundle sizes, etc.) as Extro `›` muted lines. Warnings + errors still
+ * pass through Vite's logger untouched so they keep their semantics.
+ */
+export const createViteLogger = () => {
+    const vite = createLogger();
+    vite.info = (msg) => {
+        const clean = msg
+            .replace(/\x1b\[[0-9;]*m/g, "")
+            .replace(/^[\d:apm.\s]*\[vite\]\s*/i, "")
+            .trim();
+        if (!clean)
+            return;
+        // Drop Vite's own startup banner — we already print "Building extension
+        // for production..." / the dev banner ourselves.
+        if (/^vite v[\d.]+ (building|dev server running)/i.test(clean))
+            return;
+        log.muted(clean);
+    };
+    return vite;
+};
+/**
+ * @describe Prints the grouped startup banner: a brand tag with version/mode,
+ * then aligned label/value rows and an optional dimmed hint. Mirrors Vite's
+ * own startup idiom so the two read as a coherent stack.
+ */
+export const banner = ({ mode, version, rows, hint }) => {
+    const width = Math.max(...rows.map((row) => row.label.length));
+    const lines = [
+        "",
+        `  ${tag} ${pc.dim(`v${version}`)} ${brand(mode)}`,
+        "",
+        ...rows.map((row) => `  ${brand("➜")}  ${row.label.padEnd(width)}  ${brand(row.value)}`),
+    ];
+    if (hint)
+        lines.push("", `  ${pc.dim(hint)}`);
+    lines.push("");
+    console.log(lines.join("\n"));
+};

package/dist/paths.d.ts

@@ -0,0 +1,8 @@
+import type { ExtroConfig } from "@extrojs/types";
+/**
+ * @describe Resolved unpacked-extension output dir for a build mode. The base
+ * comes from `config.outDir` (default `output`, resolved against the project
+ * root); the `chrome-mv3-<mode>` subdir keeps dev and prod artifacts separate
+ * and leaves room for other targets later.
+ */
+export declare const outputDir: (root: string, config: ExtroConfig, mode: "dev" | "prod") => string;

package/dist/paths.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+/**
+ * @describe Resolved unpacked-extension output dir for a build mode. The base
+ * comes from `config.outDir` (default `output`, resolved against the project
+ * root); the `chrome-mv3-<mode>` subdir keeps dev and prod artifacts separate
+ * and leaves room for other targets later.
+ */
+export const outputDir = (root, config, mode) => path.join(path.resolve(root, config.outDir ?? "output"), `chrome-mv3-${mode}`);

package/dist/pkg.d.ts

@@ -0,0 +1,6 @@
+interface Pkg {
+    name: string;
+    version: string;
+}
+export declare const pkg: Pkg;
+export {};

package/dist/pkg.js

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+// Read at runtime rather than `import`ing package.json: it lives outside
+// `rootDir: src`, so tsc would reject a static import. The URL resolves the
+// same in the workspace (dist/pkg.js -> ../package.json) and once published.
+export const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extrojs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Next.js for Chrome extensions. File-based entrypoints, automatic Manifest V3 generation, and React routing in a single Vite-powered CLI.",
   "keywords": [
     "extro",
@@ -29,13 +29,17 @@
     ".": {
       "types": "./dist/config.d.ts",
       "import": "./dist/config.js"
+    },
+    "./client": {
+      "types": "./client.d.ts"
     }
   },
   "bin": {
     "extro": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "client.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -45,12 +49,13 @@
   },
   "dependencies": {
     "@vitejs/plugin-react": "^6.0.1",
+    "cac": "^7.0.0",
     "jiti": "^2.4.2",
+    "picocolors": "^1.1.1",
     "vite": "^8.0.0",
     "ws": "^8.20.0",
-    "@extrojs/react": "0.1.0",
-    "@extrojs/vite-plugin": "0.1.0",
-    "@extrojs/types": "0.1.0"
+    "@extrojs/types": "0.2.0",
+    "@extrojs/vite-plugin": "0.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"
@@ -58,6 +63,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc -w",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }