extrojs 0.1.0 → 0.3.0

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 "./types/index.js";
+/**
+ * @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/dist/plugin/app-tree.d.ts

@@ -0,0 +1,59 @@
+import type { RouteManifest } from "../types/index.js";
+import { type RoutableSurface } from "./surfaces.js";
+/**
+ * Basenames the scanner recognizes under `src/app/`. The dev watcher in
+ * `index.ts` derives its glob + match regex from this same list so dev
+ * structural-change detection can never drift from what the scanner reads.
+ * (Guard: #9 widened the scanner to include `layout` but not the watcher,
+ * which silently broke layout HMR. This list is the single source so it
+ * cannot recur.)
+ */
+export declare const APP_FILE_BASENAMES: readonly ["page", "index", "layout", "error", "not-found"];
+/**
+ * The Content surface has up to two Modes: a raw script entry
+ * (`src/app/content/index.{ts,tsx}`) and a CSUI page (`src/app/content/page.tsx`).
+ * At least one is set when the slot exists; both may be set together.
+ * Stage 3 turns `csui` into a `Route[]`.
+ */
+export type ContentSlot = {
+    script?: string;
+    csui?: string;
+};
+export type AppTree = {
+    scripts: {
+        background?: string;
+        content?: ContentSlot;
+    };
+    /**
+     * Each present Routable surface's slot _is_ its `RouteManifest` (ADR 0007):
+     * routes + the per-surface not-found / surface-root layout in one record,
+     * so the pieces cannot desync. Present iff the surface has >= 1 page.
+     */
+    surfaces: Partial<Record<RoutableSurface, RouteManifest>>;
+};
+/**
+ * Single pass over `src/app/`. Every convention of the app tree lives here:
+ *
+ *   - Routable surfaces use `page.{ts,tsx}` and may nest. `[id]` segments
+ *     become dynamic params.
+ *       src/app/popup/page.tsx              → { type: "static",  path: "/" }
+ *       src/app/popup/settings/page.tsx     → { type: "static",  path: "/settings" }
+ *       src/app/popup/user/[id]/page.tsx    → { type: "dynamic", path: "/user/:id" }
+ *
+ *   - Script surfaces use `index.{ts,tsx}` at the surface root and do not
+ *     nest.
+ *
+ * Which surfaces fall into which kind is declared in `surfaces.ts`; this
+ * dispatcher consults `findSurface(name).kind` rather than hard-coding names.
+ *
+ * An empty result is returned as-is — the caller decides whether that's an
+ * error.
+ */
+export declare function scanAppTree(root: string): Promise<AppTree>;
+/**
+ * Accessor for one Routable surface's `RouteManifest` — its slot of the
+ * AppTree, or an empty manifest when the surface is absent (ADR 0005/0007).
+ * The single input to `emit` and the invalidation key, and the fixture seam
+ * for the round-trip test (build one by hand, no filesystem scan needed).
+ */
+export declare function routeManifest(tree: AppTree, surface: RoutableSurface): RouteManifest;

package/dist/plugin/app-tree.js

@@ -0,0 +1,214 @@
+import fg from "fast-glob";
+import path from "node:path";
+import { findSurface } from "./surfaces.js";
+/**
+ * Basenames the scanner recognizes under `src/app/`. The dev watcher in
+ * `index.ts` derives its glob + match regex from this same list so dev
+ * structural-change detection can never drift from what the scanner reads.
+ * (Guard: #9 widened the scanner to include `layout` but not the watcher,
+ * which silently broke layout HMR. This list is the single source so it
+ * cannot recur.)
+ */
+export const APP_FILE_BASENAMES = [
+    "page",
+    "index",
+    "layout",
+    "error",
+    "not-found",
+];
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Single pass over `src/app/`. Every convention of the app tree lives here:
+ *
+ *   - Routable surfaces use `page.{ts,tsx}` and may nest. `[id]` segments
+ *     become dynamic params.
+ *       src/app/popup/page.tsx              → { type: "static",  path: "/" }
+ *       src/app/popup/settings/page.tsx     → { type: "static",  path: "/settings" }
+ *       src/app/popup/user/[id]/page.tsx    → { type: "dynamic", path: "/user/:id" }
+ *
+ *   - Script surfaces use `index.{ts,tsx}` at the surface root and do not
+ *     nest.
+ *
+ * Which surfaces fall into which kind is declared in `surfaces.ts`; this
+ * dispatcher consults `findSurface(name).kind` rather than hard-coding names.
+ *
+ * An empty result is returned as-is — the caller decides whether that's an
+ * error.
+ */
+export async function scanAppTree(root) {
+    const files = await fg(`src/app/**/{${APP_FILE_BASENAMES.join(",")}}.{ts,tsx}`, { cwd: root });
+    const scripts = {};
+    const pagesBySurface = new Map();
+    // surface → (segment key, e.g. "" or "settings" or "c/[id]") → file path.
+    const layoutsBySurface = new Map();
+    const errorsBySurface = new Map();
+    const notFoundBySurface = new Map();
+    for (const file of files) {
+        const parts = file.split("/").slice(2); // drop "src/app/"
+        const surface = parts[0];
+        if (!surface)
+            continue;
+        const desc = findSurface(surface);
+        if (!desc)
+            continue;
+        const filename = parts[parts.length - 1];
+        const isPage = /^page\.tsx?$/.test(filename);
+        const isIndex = /^index\.tsx?$/.test(filename);
+        const isLayout = /^layout\.tsx?$/.test(filename);
+        const isError = /^error\.tsx?$/.test(filename);
+        const isNotFound = /^not-found\.tsx?$/.test(filename);
+        if (desc.kind === "script") {
+            if (parts.length !== 2)
+                continue;
+            if (!isIndex && !(isPage && desc.acceptsCsuiPage))
+                continue;
+            const abs = path.join(root, file);
+            if (surface === "background") {
+                scripts.background = abs;
+            }
+            else if (surface === "content") {
+                scripts.content = {
+                    ...scripts.content,
+                    [isIndex ? "script" : "csui"]: abs,
+                };
+            }
+            continue;
+        }
+        if (desc.kind !== "routable")
+            continue;
+        const name = surface;
+        const segments = parts.slice(1, -1); // drop surface dir + filename
+        if (isPage) {
+            const list = pagesBySurface.get(name) ?? [];
+            list.push({ file: path.join(root, file), segments });
+            pagesBySurface.set(name, list);
+        }
+        else if (isLayout || isError) {
+            const bySurface = isLayout ? layoutsBySurface : errorsBySurface;
+            const map = bySurface.get(name) ?? new Map();
+            map.set(segments.join("/"), path.join(root, file));
+            bySurface.set(name, map);
+        }
+        else if (isNotFound && segments.length === 0) {
+            // ADR 0003 §4: only the surface-root not-found.tsx is recognized;
+            // deeper ones are intentionally ignored in v0.
+            notFoundBySurface.set(name, path.join(root, file));
+        }
+    }
+    const surfaces = {};
+    for (const [name, pages] of pagesBySurface) {
+        const layoutMap = layoutsBySurface.get(name);
+        const errorMap = errorsBySurface.get(name);
+        const routes = pages.map(({ file, segments }) => buildRoute(file, segments, resolveBoundaryChain(segments, layoutMap, errorMap)));
+        // One RouteManifest per surface: routes + not-found + root layout in a
+        // single record, so the pieces cannot desync (ADR 0007).
+        surfaces[name] = {
+            routes: sortRoutes(routes),
+            notFound: notFoundBySurface.get(name) ?? null,
+            rootLayout: layoutMap?.get("") ?? null,
+        };
+    }
+    return { scripts, surfaces };
+}
+const EMPTY_MANIFEST = {
+    routes: [],
+    notFound: null,
+    rootLayout: null,
+};
+/**
+ * Accessor for one Routable surface's `RouteManifest` — its slot of the
+ * AppTree, or an empty manifest when the surface is absent (ADR 0005/0007).
+ * The single input to `emit` and the invalidation key, and the fixture seam
+ * for the round-trip test (build one by hand, no filesystem scan needed).
+ */
+export function routeManifest(tree, surface) {
+    return tree.surfaces[surface] ?? EMPTY_MANIFEST;
+}
+// ---------------------------------------------------------------------------
+// Route builder
+// ---------------------------------------------------------------------------
+function buildRoute(file, segments, boundaries) {
+    if (segments.some(isDynamic))
+        return buildDynamicRoute(file, segments, boundaries);
+    return buildStaticRoute(file, segments, boundaries);
+}
+function buildStaticRoute(file, segments, boundaries) {
+    const urlPath = segments.length > 0 ? `/${segments.join("/")}` : "/";
+    return { type: "static", path: urlPath, file, boundaries };
+}
+function buildDynamicRoute(file, segments, boundaries) {
+    const paramKeys = [];
+    const patternParts = segments.map((seg) => {
+        if (isDynamic(seg)) {
+            paramKeys.push(seg.slice(1, -1)); // strip [ and ]
+            return "([^/]+)";
+        }
+        return escapeRegex(seg);
+    });
+    // Serializable: the RegExp body, materialized by `emit` at codegen time.
+    const patternSource = `^/${patternParts.join("/")}$`;
+    const urlPath = segments
+        .map((seg) => (isDynamic(seg) ? `:${seg.slice(1, -1)}` : seg))
+        .join("/");
+    return {
+        type: "dynamic",
+        path: `/${urlPath}`,
+        file,
+        paramKeys,
+        patternSource,
+        boundaries,
+    };
+}
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+/**
+ * Static routes first (longest first for specificity), then dynamic routes
+ * (longest first so /user/:id beats /:anything for the same depth).
+ *
+ * Alphabetical tiebreak keeps the output stable across filesystems — otherwise
+ * two routes of equal length would sort by readdir order, which varies.
+ */
+function sortRoutes(routes) {
+    const byLengthThenAlpha = (a, b) => b.path.length - a.path.length || a.path.localeCompare(b.path);
+    const statics = routes
+        .filter((r) => r.type === "static")
+        .sort(byLengthThenAlpha);
+    const dynamics = routes
+        .filter((r) => r.type === "dynamic")
+        .sort(byLengthThenAlpha);
+    return [...statics, ...dynamics];
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Ancestor boundary chain for a page, outermost first: walk from the
+ * surface-root segment (key "") down to the page's own segment. At each
+ * depth the `layout.tsx` is pushed before the `error.tsx`, so composing the
+ * chain inside-out nests the error within its sibling layout (ADR 0003 §3).
+ * Only the files that exist are included.
+ */
+function resolveBoundaryChain(segments, layoutMap, errorMap) {
+    const chain = [];
+    for (let i = 0; i <= segments.length; i++) {
+        const key = segments.slice(0, i).join("/");
+        const layout = layoutMap?.get(key);
+        if (layout)
+            chain.push({ kind: "layout", file: layout });
+        const error = errorMap?.get(key);
+        if (error)
+            chain.push({ kind: "error", file: error });
+    }
+    return chain;
+}
+/** Returns true for dynamic segments like `[id]` or `[userId]`. */
+function isDynamic(segment) {
+    return segment.startsWith("[") && segment.endsWith("]");
+}
+/** Escapes special RegExp characters in a static path segment. */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/plugin/asset-inventory.d.ts

@@ -0,0 +1,24 @@
+import type { AppTree } from "./app-tree.js";
+import { type PublicAssets } from "./public.js";
+/**
+ * @file asset-inventory.ts
+ * @description The Asset inventory: the discovered static-file inputs a build
+ * ships. One `discoverAssets(root, tree)` pass over `icons/` and `public/`
+ * yields a value consumed by both the Manifest generator (kept pure, taking
+ * this as data) and the emit/copy paths, so the filesystem is walked once per
+ * build instead of three times.
+ *
+ * The icon set here is the recognized-sizes set (16/32/48/128) that
+ * `manifest.icons` references, and it is exactly what the emit/copy paths ship.
+ * A stray `icons/64.png` is not in the inventory, so it never ships: there is
+ * one notion of "an icon", and `manifest.icons` and the emitted icon files
+ * cannot diverge.
+ */
+export interface AssetInventory {
+    /** Recognized icons: size -> output path ("icons/16.png"). null when absent. */
+    icons: Record<string, string> | null;
+    /** Public assets, partitioned against the names a build generates. */
+    public: PublicAssets;
+}
+/** Walk `icons/` + `public/` once and return the build's Asset inventory. */
+export declare function discoverAssets(root: string, tree: AppTree): AssetInventory;

package/dist/plugin/asset-inventory.js

@@ -0,0 +1,9 @@
+import { detectIcons } from "./icons.js";
+import { collectPublicAssets } from "./public.js";
+/** Walk `icons/` + `public/` once and return the build's Asset inventory. */
+export function discoverAssets(root, tree) {
+    return {
+        icons: detectIcons(root) ?? null,
+        public: collectPublicAssets(root, tree),
+    };
+}

package/dist/plugin/dev-reactions.d.ts

@@ -0,0 +1,59 @@
+import type { AppTree } from "./app-tree.js";
+import type { RoutableSurface } from "./surfaces.js";
+/**
+ * @file dev-reactions.ts
+ * @description Dev reactions: the framework's decision about what to do when a
+ * watched `src/app` file changes during `extro dev`. Pure functions only. The
+ * watchers that trigger them own every effect (rescan, broadcast, module
+ * invalidation); nothing here touches the filesystem, the module graph, or the
+ * WebSocket. The decisions are the test surface.
+ *
+ * Two complementary halves:
+ *   - the script reaction (`classifyScriptChange` + the dirty reducer), driven
+ *     by the CLI's Rollup build watcher over background/content;
+ *   - the tree reaction (`decideTreeReaction`), driven by the plugin's
+ *     dev-server watcher over the Routable surfaces.
+ */
+/** Which Script surfaces a dev rebuild dirties. */
+export interface ScriptDirty {
+    background: boolean;
+    content: boolean;
+}
+/**
+ * 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 declare function classifyScriptChange(changedPath: string): ScriptDirty;
+/** Union two dirty states (accumulating `change` events across one build). */
+export declare function mergeDirty(a: ScriptDirty, b: ScriptDirty): ScriptDirty;
+/**
+ * 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 declare function resolveFlush(dirty: ScriptDirty): ScriptDirty;
+/**
+ * The reaction to a Routable-side change.
+ *   - `restart`: a Surface was born mid-session. `rollupOptions.input` was
+ *     fixed at `config()` time, so a fresh `extro dev` is required to register
+ *     the new entry.
+ *   - `invalidate`: existing Routable surfaces gained or lost a Route; their
+ *     routes virtual modules must reload so the runtime picks up the new array.
+ *   - `noop`: nothing actionable changed.
+ */
+export type DevReaction = {
+    kind: "restart";
+    surface: "background" | "content" | RoutableSurface;
+} | {
+    kind: "invalidate";
+    surfaces: RoutableSurface[];
+} | {
+    kind: "noop";
+};
+/**
+ * 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 declare function decideTreeReaction(prev: AppTree, next: AppTree, routables: readonly RoutableSurface[]): DevReaction;

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,50 @@
+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>>;
+}
+/**
+ * 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,40 @@
+import { generateManifest } from "./manifest.js";
+import { 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 html = {};
+    for (const surface of Object.keys(opts.tree.surfaces)) {
+        html[surface] = generateHTML({
+            surface,
+            dev: opts.dev ? { port: opts.dev.port } : undefined,
+        });
+    }
+    return { manifest, html };
+}
+/**
+ * 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 } = composeArtifacts(opts);
+    await emit("manifest.json", JSON.stringify(manifest, null, 2));
+    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,39 @@
+interface GenerateHTMLOptions {
+    surface: string;
+    dev?: {
+        port: number;
+    };
+}
+/**
+ * @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 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;
+}
+/**
+ * @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 }: DevScreen) => string;
+/**
+ * @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 declare const devScreenStyles: () => string;
+export {};