extrojs 0.2.0 → 0.3.1

package/dist/plugin/dev-reactions.js

@@ -0,0 +1,62 @@
+import { routeManifest } from "./app-tree.js";
+/**
+ * A changed file under `src/app/background/` dirties background; under
+ * `src/app/content/` dirties content; anything else (shared code) dirties both.
+ * This is the only place that knows the `src/app` layout, so the CLI no longer
+ * hardcodes those paths.
+ */
+export function classifyScriptChange(changedPath) {
+    const p = changedPath.replace(/\\/g, "/");
+    const background = p.includes("/src/app/background/");
+    const content = p.includes("/src/app/content/");
+    if (!background && !content)
+        return { background: true, content: true };
+    return { background, content };
+}
+/** Union two dirty states (accumulating `change` events across one build). */
+export function mergeDirty(a, b) {
+    return {
+        background: a.background || b.background,
+        content: a.content || b.content,
+    };
+}
+/**
+ * Resolve the accumulated dirty state at `BUNDLE_END`. No classified change
+ * (the initial build, or an `extro dev` restart) conservatively means both,
+ * matching the broadcast-on-first-build behavior.
+ */
+export function resolveFlush(dirty) {
+    if (!dirty.background && !dirty.content) {
+        return { background: true, content: true };
+    }
+    return { background: dirty.background, content: dirty.content };
+}
+/**
+ * Diff two AppTrees into a {@link DevReaction}. A birth short-circuits the
+ * invalidate scan: the session has to restart regardless of any route delta.
+ */
+export function decideTreeReaction(prev, next, routables) {
+    if (!prev.scripts.background && next.scripts.background) {
+        return { kind: "restart", surface: "background" };
+    }
+    if (!prev.scripts.content && next.scripts.content) {
+        return { kind: "restart", surface: "content" };
+    }
+    for (const surface of routables) {
+        const had = (prev.surfaces[surface]?.routes.length ?? 0) > 0;
+        const has = (next.surfaces[surface]?.routes.length ?? 0) > 0;
+        if (has && !had)
+            return { kind: "restart", surface };
+    }
+    // The Route manifest IS what the routes module emits and is fully
+    // serializable, so its stable stringify is a faithful identity: invalidation
+    // can no longer drift from the contract (ADR 0005). This is what kills the
+    // historical HMR-drift bug class.
+    const changed = [];
+    for (const surface of routables) {
+        const key = (t) => JSON.stringify(routeManifest(t, surface));
+        if (key(prev) !== key(next))
+            changed.push(surface);
+    }
+    return changed.length ? { kind: "invalidate", surfaces: changed } : { kind: "noop" };
+}

package/dist/plugin/emit-assets.d.ts

@@ -0,0 +1,56 @@
+import type { ExtroConfig, ManifestV3 } from "../types/index.js";
+import type { AppTree } from "./app-tree.js";
+import type { AssetInventory } from "./asset-inventory.js";
+import type { RoutableSurface } from "./surfaces.js";
+/**
+ * Receives one finished asset at a time. Sync (Vite's `emitFile`) and async
+ * (`fs.writeFile`) sinks both fit — callers that await the seam will see
+ * any rejection from the async path.
+ */
+export type EmitSink = (fileName: string, source: string) => void | Promise<void>;
+export interface AssetOptions {
+    tree: AppTree;
+    /**
+     * The build's discovered icons + Public assets. Both call paths
+     * (`generateBundle`, `writeDevAssets`) run `discoverAssets` once at their
+     * filesystem edge and pass the result in, so composition stays pure.
+     */
+    inventory: AssetInventory;
+    pkg: {
+        name?: string;
+        description?: string;
+        version?: string;
+    };
+    config: ExtroConfig;
+    dev?: {
+        port: number;
+        signalPort: number;
+    };
+}
+export interface Artifacts {
+    manifest: ManifestV3;
+    html: Partial<Record<RoutableSurface, string>>;
+    /**
+     * The dev probe (`extro-dev.js`) the dev shells load to reveal the
+     * offline screen when the dev server is unreachable. Absent in prod
+     * builds and when there are no HTML surfaces to probe for.
+     */
+    devProbe?: string;
+}
+/**
+ * Pure projection from inputs to artifact strings: no filesystem access (the
+ * Asset inventory is discovered at the caller's edge and passed in). Exposed
+ * alongside `emitAssets` so tests can assert "given this tree + inventory, this
+ * is the manifest" without a sink and without staging files on disk.
+ */
+export declare function composeArtifacts(opts: AssetOptions): Artifacts;
+/**
+ * Canonical emission of Extro's static outputs (manifest + per-surface HTML).
+ * Both the build (`generateBundle`) and dev (`writeDevAssets`) call paths go
+ * through here — the only difference between them is the sink.
+ *
+ * Icons live outside this seam: they are emitted once during build via
+ * Rollup's binary-asset path and are not needed in dev (the initial
+ * `viteBuild` already wrote them to disk).
+ */
+export declare function emitAssets(opts: AssetOptions, emit: EmitSink): Promise<void>;

package/dist/plugin/emit-assets.js

@@ -0,0 +1,47 @@
+import { generateManifest } from "./manifest.js";
+import { DEV_PROBE_FILE, generateDevProbe, generateHTML, } from "./generators/html.js";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Pure projection from inputs to artifact strings: no filesystem access (the
+ * Asset inventory is discovered at the caller's edge and passed in). Exposed
+ * alongside `emitAssets` so tests can assert "given this tree + inventory, this
+ * is the manifest" without a sink and without staging files on disk.
+ */
+export function composeArtifacts(opts) {
+    const manifest = generateManifest(opts);
+    const surfaces = Object.keys(opts.tree.surfaces);
+    const html = {};
+    for (const surface of surfaces) {
+        html[surface] = generateHTML({
+            surface,
+            dev: opts.dev ? { port: opts.dev.port } : undefined,
+        });
+    }
+    const devProbe = opts.dev && surfaces.length > 0
+        ? generateDevProbe({ port: opts.dev.port })
+        : undefined;
+    return { manifest, html, devProbe };
+}
+/**
+ * Canonical emission of Extro's static outputs (manifest + per-surface HTML).
+ * Both the build (`generateBundle`) and dev (`writeDevAssets`) call paths go
+ * through here — the only difference between them is the sink.
+ *
+ * Icons live outside this seam: they are emitted once during build via
+ * Rollup's binary-asset path and are not needed in dev (the initial
+ * `viteBuild` already wrote them to disk).
+ */
+export async function emitAssets(opts, emit) {
+    const { manifest, html, devProbe } = composeArtifacts(opts);
+    await emit("manifest.json", JSON.stringify(manifest, null, 2));
+    if (devProbe) {
+        await emit(DEV_PROBE_FILE, devProbe);
+    }
+    for (const [surface, body] of Object.entries(html)) {
+        if (!body)
+            continue;
+        await emit(`${surface}.html`, body);
+    }
+}

package/dist/plugin/generators/html.d.ts

@@ -0,0 +1,64 @@
+interface GenerateHTMLOptions {
+    surface: string;
+    dev?: {
+        port: number;
+    };
+}
+/**
+ * The dev probe script emitted next to the HTML shells in the dev output
+ * dir. Referenced by the shells and reserved against Public assets, so the
+ * name lives here once.
+ */
+export declare const DEV_PROBE_FILE = "extro-dev.js";
+/**
+ * @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 carries a hidden brand-styled "dev server offline"
+ * screen inside #root. The probe script (generateDevProbe) reveals it only
+ * when the dev server is unreachable; on a normal start it never paints,
+ * and React's createRoot replaces #root's children on mount.
+ */
+export declare function generateHTML({ surface, dev }: GenerateHTMLOptions): string;
+export interface DevScreen {
+    title: string;
+    /** HTML body content (paragraphs, code, etc.). Inserted as-is. */
+    body: string;
+    /**
+     * When true, the screen fills the viewport and centers its card. Use for
+     * surfaces with a real viewport (options tab, sidepanel). When false
+     * (popup), the screen sizes to content with a fixed minimum.
+     */
+    fill?: boolean;
+    /**
+     * When true, the screen ships with the `hidden` attribute and stays out
+     * of the first paint until something removes it (the dev probe, for the
+     * offline screen).
+     */
+    hidden?: boolean;
+}
+/**
+ * @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 declare const renderDevScreen: ({ title, body, fill, hidden, }: DevScreen) => string;
+/**
+ * @describe Global styles for any `.extro-dev-screen` rendered in dev. Body
+ * is painted dark only while a visible screen is in the DOM (via `:has()`),
+ * so the user's app keeps default styling both before React mounts (screen
+ * still hidden) and after (screen wiped from #root).
+ */
+export declare const devScreenStyles: () => string;
+/**
+ * @describe Generates the dev probe (`extro-dev.js`), emitted into the dev
+ * output dir next to the HTML shells. MV3 CSP bans inline scripts but allows
+ * 'self', so the probe loads from the extension origin and runs even when
+ * the Vite dev server is down. It reveals the hidden offline screen only
+ * when the @vite/client script fails to fetch, the one unambiguous signal
+ * that the server is unreachable; a failing user module while the server is
+ * up stays Vite's error overlay's problem.
+ */
+export declare const generateDevProbe: ({ port }: {
+    port: number;
+}) => string;
+export {};

package/dist/plugin/generators/html.js

@@ -0,0 +1,167 @@
+/**
+ * The dev probe script emitted next to the HTML shells in the dev output
+ * dir. Referenced by the shells and reserved against Public assets, so the
+ * name lives here once.
+ */
+export const DEV_PROBE_FILE = "extro-dev.js";
+/**
+ * @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 carries a hidden brand-styled "dev server offline"
+ * screen inside #root. The probe script (generateDevProbe) reveals it only
+ * when the dev server is unreachable; on a normal start it never paints,
+ * and React's createRoot replaces #root's children on mount.
+ */
+export function generateHTML({ surface, dev }) {
+    const title = surface.charAt(0).toUpperCase() + surface.slice(1);
+    const scripts = dev
+        ? `
+      <script src="./${DEV_PROBE_FILE}"></script>
+      <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",
+            // Hidden until the probe proves the dev server is down, so a normal
+            // start never paints it (the screen used to flash for the moment
+            // between document load and React mount).
+            hidden: true,
+        })
+        : "";
+    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, hidden = false, }) => {
+    const cls = `extro-dev-screen${fill ? " extro-dev-screen--fill" : ""}`;
+    return `
+<div class="${cls}"${hidden ? " hidden" : ""}>
+  <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 visible screen is in the DOM (via `:has()`),
+ * so the user's app keeps default styling both before React mounts (screen
+ * still hidden) and after (screen wiped from #root).
+ */
+export const devScreenStyles = () => `
+<style>
+  body { margin: 0; }
+  body:has(.extro-dev-screen:not([hidden])) { 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 forwards;
+  }
+  .extro-dev-screen[hidden] {
+    display: none;
+  }
+  .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();
+/**
+ * @describe Generates the dev probe (`extro-dev.js`), emitted into the dev
+ * output dir next to the HTML shells. MV3 CSP bans inline scripts but allows
+ * 'self', so the probe loads from the extension origin and runs even when
+ * the Vite dev server is down. It reveals the hidden offline screen only
+ * when the @vite/client script fails to fetch, the one unambiguous signal
+ * that the server is unreachable; a failing user module while the server is
+ * up stays Vite's error overlay's problem.
+ */
+export const generateDevProbe = ({ port }) => `
+// Generated by Extro. Reveals the "dev server isn't running" screen when
+// the Vite dev server can't be reached. Script fetch errors don't bubble,
+// hence the capture-phase listener; this classic script runs before the
+// module scripts below it can fail.
+window.addEventListener(
+  "error",
+  (event) => {
+    const el = event.target;
+    if (!(el instanceof HTMLScriptElement)) return;
+    if (el.src !== "http://localhost:${port}/@vite/client") return;
+    document.querySelector(".extro-dev-screen")?.removeAttribute("hidden");
+  },
+  true,
+);
+`.trimStart();

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

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

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

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

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

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

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

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