extrojs 0.2.0 → 0.3.1

package/dist/plugin/runtimes/clients/dev-bridge.js

@@ -0,0 +1,194 @@
+import "virtual:extro/user/background";
+import { config } from "virtual:extro/dev-bridge/config";
+/**
+ * @file runtimes/clients/dev-bridge.ts
+ * @description The MV3 service-worker bridge run by `extro dev`.
+ *
+ * Responsibilities:
+ *   - Connect to the CLI's signal WS and react to:
+ *       bg-rebuilt  → `chrome.runtime.reload()` (only way to swap BG code).
+ *       cs-rebuilt  → CSUI-aware re-mount via `csui-update`, else tab reload.
+ *       vite-hmr    → fetch transformed module source from the dev server
+ *                     and forward to tabs as `rfr-update` for the CSUI
+ *                     runtime's react-refresh client.
+ *   - Keep the service worker alive past the MV3 idle timeout so the WS
+ *     doesn't die between edits.
+ *   - Restart the extension if the in-memory manifest predates this dev
+ *     session (CSP would block our signal WS otherwise).
+ *
+ * Why the BG SW does the dev-server fetch (not content scripts):
+ *   Chrome's Local Network Access blocks public HTTPS pages from reaching
+ *   localhost without a per-site user grant. Only the chrome-extension://
+ *   origin can reliably fetch http://localhost:<vitePort>.
+ */
+(function extroDevBridge() {
+    // If Chrome's in-memory manifest predates this dev session (e.g. it last
+    // loaded from a prod build), the CSP won't allow our signal WS. Force a
+    // reload so Chrome re-reads the dev manifest from disk. The new SW spawn
+    // sees the updated CSP and skips this branch.
+    const csp = chrome.runtime.getManifest().content_security_policy;
+    const pages = csp?.extension_pages ?? "";
+    if (!pages.includes(`ws://localhost:${config.signalPort}`)) {
+        chrome.runtime.reload();
+        return;
+    }
+    const SIGNAL_URL = `ws://localhost:${config.signalPort}`;
+    const VITE_ORIGIN = `http://localhost:${config.vitePort}`;
+    let signalSocket = null;
+    let wasDisconnected = false;
+    // ---------------------------------------------------------------------
+    // Keep-alive — Chrome MV3 terminates idle SWs after ~30s. Without this,
+    // the signal WS dies between edits and HMR silently stops working.
+    // Periodic chrome.* API calls register as activity and prevent
+    // termination. Dev-only; the prod build doesn't ship this bridge.
+    // ---------------------------------------------------------------------
+    setInterval(() => {
+        chrome.runtime.getPlatformInfo().catch(() => { });
+    }, 20_000);
+    // ---------------------------------------------------------------------
+    // Tab helpers
+    // ---------------------------------------------------------------------
+    const messageMatchingTabs = async (msg) => {
+        let count = 0;
+        try {
+            const manifest = chrome.runtime.getManifest();
+            const matches = manifest.content_scripts?.[0]?.matches ?? [];
+            if (matches.length === 0)
+                return 0;
+            const tabs = await chrome.tabs.query({ url: matches });
+            await Promise.all(tabs.map(async (tab) => {
+                if (tab.id == null)
+                    return;
+                try {
+                    await chrome.tabs.sendMessage(tab.id, msg);
+                    count++;
+                }
+                catch { }
+            }));
+        }
+        catch { }
+        return count;
+    };
+    const reloadMatchingTabs = async () => {
+        try {
+            const manifest = chrome.runtime.getManifest();
+            const matches = manifest.content_scripts?.[0]?.matches ?? [];
+            if (matches.length === 0)
+                return;
+            const tabs = await chrome.tabs.query({ url: matches });
+            for (const tab of tabs) {
+                if (tab.id != null) {
+                    try {
+                        await chrome.tabs.reload(tab.id);
+                    }
+                    catch { }
+                }
+            }
+        }
+        catch (err) {
+            console.warn("[extro] tab reload skipped:", err);
+        }
+    };
+    // ---------------------------------------------------------------------
+    // RFR transport — fetch transformed module source from the Vite dev
+    // server (BG SW is the only origin that reliably reaches localhost on
+    // sites where Local Network Access would block a public-origin fetch).
+    // ---------------------------------------------------------------------
+    const fetchModuleSource = async (modPath) => {
+        try {
+            const res = await fetch(VITE_ORIGIN + modPath);
+            if (!res.ok)
+                return null;
+            return await res.text();
+        }
+        catch (err) {
+            console.warn("[extro] failed to fetch " + modPath, err);
+            return null;
+        }
+    };
+    // ---------------------------------------------------------------------
+    // Signal handlers
+    // ---------------------------------------------------------------------
+    const onBgRebuilt = () => {
+        console.log("[extro] bg-rebuilt signal received");
+        // A service worker can't be hot-swapped; the only way to pick up new
+        // background code is to restart the extension. Deliberately does NOT
+        // message tabs or send csui-update — a BG-only edit leaves content
+        // scripts / CSUI alone.
+        chrome.runtime.reload();
+    };
+    const onCsRebuilt = async () => {
+        console.log("[extro] cs-rebuilt signal received");
+        if (config.hasCSUI) {
+            const count = await messageMatchingTabs({ kind: "csui-update" });
+            console.log(`[extro] csui-update sent to ${count} tab(s)`);
+        }
+        else {
+            await reloadMatchingTabs();
+        }
+        // Deliberately NO chrome.runtime.reload() — a content-only edit is
+        // picked up when the tab reloads (content.js re-injected) or when
+        // CSUI soft-remounts.
+    };
+    const onViteHmr = async (payload) => {
+        // Forward the raw payload for any future consumer that wants the
+        // unmodified Vite envelope.
+        await messageMatchingTabs({ kind: "vite-hmr", payload });
+        if (!config.hasCSUI || !payload || !Array.isArray(payload.updates))
+            return;
+        const fetched = await Promise.all(payload.updates
+            .filter((u) => u && u.type === "js-update" && u.path)
+            .map(async (u) => {
+            const code = await fetchModuleSource(u.path);
+            return code ? { path: u.path, code, timestamp: u.timestamp } : null;
+        }));
+        const modules = fetched.filter((m) => m !== null);
+        if (modules.length === 0)
+            return;
+        const count = await messageMatchingTabs({ kind: "rfr-update", modules });
+        console.log(`[extro] rfr-update ${modules.length} module(s) -> ${count} tab(s)`);
+    };
+    // ---------------------------------------------------------------------
+    // Signal WS
+    // ---------------------------------------------------------------------
+    const connectSignal = () => {
+        signalSocket = new WebSocket(SIGNAL_URL);
+        signalSocket.addEventListener("open", () => {
+            // Wipe the pile of "WebSocket connection failed" entries Chrome
+            // accumulated while dev was down. Only on reconnect, not the very
+            // first connect, so we don't eat the user's pre-bridge BG logs.
+            if (wasDisconnected)
+                console.clear();
+            wasDisconnected = false;
+            console.log("[extro] Connected to dev server.");
+        });
+        signalSocket.addEventListener("message", (event) => {
+            let msg;
+            try {
+                msg = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            if (!msg)
+                return;
+            if (msg.kind === "bg-rebuilt")
+                onBgRebuilt();
+            else if (msg.kind === "cs-rebuilt")
+                onCsRebuilt();
+            else if (msg.kind === "vite-hmr" && msg.payload)
+                onViteHmr(msg.payload);
+        });
+        signalSocket.addEventListener("close", () => {
+            wasDisconnected = true;
+            setTimeout(connectSignal, 1000);
+        });
+        signalSocket.addEventListener("error", () => {
+            try {
+                signalSocket?.close();
+            }
+            catch { }
+        });
+    };
+    connectSignal();
+})();

package/dist/plugin/runtimes/csui-mount.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file runtimes/csui-mount.ts
+ * @description Plugin-side loader for the CSUI Mount Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/csui-mount.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export declare const CSUI_ENTRY_ID = "virtual:extro/csui-content";
+export declare const CSUI_CONFIG_ID = "virtual:extro/csui-mount/config";
+export declare const CSUI_USER_PAGE_ID = "virtual:extro/user/content-page";
+export declare const CSUI_USER_SCRIPT_ID = "virtual:extro/user/content-script";
+export declare const loadCSUIClient: () => string;
+export declare const csuiConfigSource: (dev: boolean) => string;
+export declare const csuiUserPageSource: (pagePath: string) => string;
+export declare const csuiUserScriptSource: (scriptPath: string | undefined) => string;

package/dist/plugin/runtimes/csui-mount.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * @file runtimes/csui-mount.ts
+ * @description Plugin-side loader for the CSUI Mount Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/csui-mount.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export const CSUI_ENTRY_ID = "virtual:extro/csui-content";
+export const CSUI_CONFIG_ID = "virtual:extro/csui-mount/config";
+export const CSUI_USER_PAGE_ID = "virtual:extro/user/content-page";
+export const CSUI_USER_SCRIPT_ID = "virtual:extro/user/content-script";
+const clientJsURL = new URL("./clients/csui-mount.js", import.meta.url);
+export const loadCSUIClient = () => fs.readFileSync(fileURLToPath(clientJsURL), "utf-8");
+export const csuiConfigSource = (dev) => `export const config = ${JSON.stringify({ dev })};\n`;
+export const csuiUserPageSource = (pagePath) => `export { default } from ${JSON.stringify(pagePath)};\n`;
+export const csuiUserScriptSource = (scriptPath) => scriptPath ? `import ${JSON.stringify(scriptPath)};\n` : "\n";

package/dist/plugin/runtimes/dev-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file runtimes/dev-bridge.ts
+ * @description Plugin-side loader for the Dev Bridge Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/dev-bridge.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export declare const DEV_BRIDGE_ENTRY_ID = "virtual:extro/dev-background";
+export declare const DEV_BRIDGE_CONFIG_ID = "virtual:extro/dev-bridge/config";
+export declare const DEV_BRIDGE_USER_BG_ID = "virtual:extro/user/background";
+export declare const loadDevBridgeClient: () => string;
+interface DevBridgeConfig {
+    signalPort: number;
+    vitePort: number;
+    hasCSUI: boolean;
+}
+export declare const devBridgeConfigSource: (cfg: DevBridgeConfig) => string;
+export declare const devBridgeUserBackgroundSource: (backgroundPath: string | undefined) => string;
+export {};

package/dist/plugin/runtimes/dev-bridge.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * @file runtimes/dev-bridge.ts
+ * @description Plugin-side loader for the Dev Bridge Runtime module.
+ *
+ * Owns the virtual IDs this runtime consumes and emits source for each.
+ * The runtime client itself lives at `runtimes/clients/dev-bridge.ts`
+ * (a real TS file compiled separately via `tsconfig.runtime.json`); this
+ * loader only reads the compiled JS and emits the small config / user-
+ * import virtuals it imports.
+ */
+export const DEV_BRIDGE_ENTRY_ID = "virtual:extro/dev-background";
+export const DEV_BRIDGE_CONFIG_ID = "virtual:extro/dev-bridge/config";
+export const DEV_BRIDGE_USER_BG_ID = "virtual:extro/user/background";
+const clientJsURL = new URL("./clients/dev-bridge.js", import.meta.url);
+export const loadDevBridgeClient = () => fs.readFileSync(fileURLToPath(clientJsURL), "utf-8");
+export const devBridgeConfigSource = (cfg) => `export const config = ${JSON.stringify(cfg)};\n`;
+export const devBridgeUserBackgroundSource = (backgroundPath) => backgroundPath ? `import ${JSON.stringify(backgroundPath)};\n` : "\n";

package/dist/plugin/runtimes/routes-module.d.ts

@@ -0,0 +1,20 @@
+import type { RouteManifest } from "../../types/index.js";
+/**
+ * @file runtimes/routes-module.ts
+ * @description The single codegen for the `virtual:extro/routes/<surface>`
+ * Runtime module (ADR 0005). It is the only code that knows the text form of
+ * the routing contract: lazy `import()` thunks, the dynamic-route RegExp, and
+ * the `notFound` / `rootLayout` exports. Input is the typed `RouteManifest`;
+ * output is asserted against the runtime `Route[]` type by the round-trip
+ * test, so this string can no longer drift from what the runtime expects.
+ *
+ * Example output:
+ *
+ *   export const routes = [
+ *     { type: "static",  path: "/",         boundaries: [...], load: () => import("...") },
+ *     { type: "dynamic", path: "/user/:id", paramKeys: ["id"], pattern: new RegExp("^/user/([^/]+)$"), boundaries: [...], load: () => import("...") },
+ *   ];
+ *   export const notFound = () => import("...");
+ *   export const rootLayout = null;
+ */
+export declare function emit(manifest: RouteManifest): string;

package/dist/plugin/runtimes/routes-module.js

@@ -0,0 +1,51 @@
+/**
+ * @file runtimes/routes-module.ts
+ * @description The single codegen for the `virtual:extro/routes/<surface>`
+ * Runtime module (ADR 0005). It is the only code that knows the text form of
+ * the routing contract: lazy `import()` thunks, the dynamic-route RegExp, and
+ * the `notFound` / `rootLayout` exports. Input is the typed `RouteManifest`;
+ * output is asserted against the runtime `Route[]` type by the round-trip
+ * test, so this string can no longer drift from what the runtime expects.
+ *
+ * Example output:
+ *
+ *   export const routes = [
+ *     { type: "static",  path: "/",         boundaries: [...], load: () => import("...") },
+ *     { type: "dynamic", path: "/user/:id", paramKeys: ["id"], pattern: new RegExp("^/user/([^/]+)$"), boundaries: [...], load: () => import("...") },
+ *   ];
+ *   export const notFound = () => import("...");
+ *   export const rootLayout = null;
+ */
+export function emit(manifest) {
+    const entries = manifest.routes.map(serializeRoute).join(",\n");
+    return `export const routes = [
+${entries}
+];
+export const notFound = ${loaderOrNull(manifest.notFound)};
+export const rootLayout = ${loaderOrNull(manifest.rootLayout)};
+`;
+}
+// ---------------------------------------------------------------------------
+// Serialisers
+// ---------------------------------------------------------------------------
+/** A lazy import of an absolute path, or the `null` literal when absent. */
+function loaderOrNull(file) {
+    return file ? `() => import(${JSON.stringify(file)})` : "null";
+}
+// Boundary chain is emitted outermost first as tagged lazy imports, so the
+// runtime composes the route's wrappers without a separate tree fetch.
+function serializeBoundaries(route) {
+    const entries = route.boundaries
+        .map((b) => `{ kind: ${JSON.stringify(b.kind)}, load: () => import(${JSON.stringify(b.file)}) }`)
+        .join(", ");
+    return `[${entries}]`;
+}
+function serializeRoute(route) {
+    if (route.type === "static") {
+        return `  { type: "static", path: ${JSON.stringify(route.path)}, boundaries: ${serializeBoundaries(route)}, load: () => import(${JSON.stringify(route.file)}) }`;
+    }
+    // `patternSource` is materialized into a real RegExp here (the runtime
+    // `Route` type carries `pattern: RegExp`); JSON.stringify keeps escaping
+    // correct without RegExp-literal pitfalls.
+    return `  { type: "dynamic", path: ${JSON.stringify(route.path)}, paramKeys: ${JSON.stringify(route.paramKeys)}, pattern: new RegExp(${JSON.stringify(route.patternSource)}), boundaries: ${serializeBoundaries(route)}, load: () => import(${JSON.stringify(route.file)}) }`;
+}

package/dist/plugin/runtimes/runtime-module.d.ts

@@ -0,0 +1,16 @@
+import type { RoutableSurface } from "../surfaces.js";
+interface GenerateRuntimeModuleOptions {
+    surface: RoutableSurface;
+}
+/**
+ * @file runtimes/runtime-module.ts
+ * @description Generates the per-surface runtime entry.
+ *
+ * The real runtime logic (mounting, route matching, render loop) lives in
+ * `@extrojs/router` as actual TypeScript; this file only emits a tiny
+ * shim that wires the compiled routes array into `createExtroRouter`. The
+ * shim imports from the published `extrojs/runtime` subpath (ADR 0009), the
+ * one path that resolves inside the user's bundle.
+ */
+export declare function generateRuntimeModule({ surface, }: GenerateRuntimeModuleOptions): string;
+export {};

package/dist/plugin/runtimes/runtime-module.js

@@ -0,0 +1,40 @@
+/**
+ * @file runtimes/runtime-module.ts
+ * @description Generates the per-surface runtime entry.
+ *
+ * The real runtime logic (mounting, route matching, render loop) lives in
+ * `@extrojs/router` as actual TypeScript; this file only emits a tiny
+ * shim that wires the compiled routes array into `createExtroRouter`. The
+ * shim imports from the published `extrojs/runtime` subpath (ADR 0009), the
+ * one path that resolves inside the user's bundle.
+ */
+export function generateRuntimeModule({ surface, }) {
+    return `import { createExtroRouter } from "extrojs/runtime";
+import { routes, notFound, rootLayout } from "virtual:extro/routes/${surface}";
+
+// Persist the router handle across HMR updates so we never call createRoot twice.
+// import.meta.hot.data survives module re-execution.
+let handle = import.meta.hot?.data?.handle;
+
+if (!handle) {
+  handle = createExtroRouter(routes, { surface: ${JSON.stringify(surface)}, notFound, rootLayout });
+  if (import.meta.hot) {
+    import.meta.hot.data.handle = handle;
+  }
+} else {
+  handle.update(routes, { notFound, rootLayout });
+}
+
+if (import.meta.hot) {
+  // Only accept updates to the routes dep. Edits to anything else (e.g.
+  // the router internals) bubble to a full page reload. The persisted
+  // handle is wired to the old render closure and can't pick up new module
+  // code in place, so a fresh mount is the correct behavior.
+  import.meta.hot.accept("virtual:extro/routes/${surface}", (mod) => {
+    if (mod?.routes) {
+      handle.update(mod.routes, { notFound: mod.notFound, rootLayout: mod.rootLayout });
+    }
+  });
+}
+`;
+}

package/dist/plugin/surfaces.d.ts

@@ -0,0 +1,37 @@
+import type { ExtroConfig, ManifestV3 } from "../types/index.js";
+import type { AppTree } from "./app-tree.js";
+export type RoutableSurface = "popup" | "options" | "sidepanel";
+export type ScriptSurface = "background" | "content";
+export type SurfaceName = RoutableSurface | ScriptSurface;
+export type SurfaceKind = "routable" | "script";
+export interface SurfaceContext {
+    tree: AppTree;
+    config: ExtroConfig;
+    /** Set during `extro dev` so descriptors can adjust for dev-mode behavior. */
+    dev?: {
+        port: number;
+        signalPort: number;
+    };
+    /**
+     * Shippable Public asset paths (posix, relative to `public/`). Computed once
+     * in `generateManifest` so descriptors stay pure. The Content descriptor
+     * lists them in `web_accessible_resources`.
+     */
+    publicAssets?: string[];
+}
+export interface SurfaceDescriptor {
+    name: SurfaceName;
+    kind: SurfaceKind;
+    /** Whether this surface is materialized for the current build. */
+    isPresent: (ctx: SurfaceContext) => boolean;
+    /** Manifest fragment merged into the final manifest when present. */
+    manifestContribution: (ctx: SurfaceContext) => Partial<ManifestV3>;
+    /** Permissions added when present and the user hasn't supplied their own list. */
+    permissions?: (ctx: SurfaceContext) => readonly string[];
+    /** Host permissions added when present and the user hasn't supplied their own list. */
+    hostPermissions?: (ctx: SurfaceContext) => readonly string[];
+    /** Content surface flag: also accept `page.tsx` as the CSUI Mode. */
+    acceptsCsuiPage?: boolean;
+}
+export declare const SURFACES: readonly SurfaceDescriptor[];
+export declare function findSurface(name: string): SurfaceDescriptor | undefined;

package/dist/plugin/surfaces.js

@@ -0,0 +1,67 @@
+export const SURFACES = [
+    {
+        name: "popup",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.popup,
+        manifestContribution: () => ({ action: { default_popup: "popup.html" } }),
+    },
+    {
+        name: "options",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.options,
+        manifestContribution: () => ({
+            options_ui: { page: "options.html", open_in_tab: true },
+        }),
+    },
+    {
+        name: "sidepanel",
+        kind: "routable",
+        isPresent: ({ tree }) => !!tree.surfaces.sidepanel,
+        manifestContribution: () => ({ side_panel: { default_path: "sidepanel.html" } }),
+    },
+    {
+        name: "background",
+        kind: "script",
+        // In dev the bridge runs as the background SW even when the user has
+        // no BG file, so the surface is forced present.
+        isPresent: ({ tree, dev }) => !!tree.scripts.background || !!dev,
+        manifestContribution: () => ({
+            background: { service_worker: "background.js" },
+        }),
+        // `tabs` is added in dev so the bridge can call chrome.tabs.reload.
+        permissions: ({ dev }) => (dev ? ["storage", "tabs"] : ["storage"]),
+    },
+    {
+        name: "content",
+        kind: "script",
+        acceptsCsuiPage: true,
+        isPresent: ({ tree }) => !!tree.scripts.content,
+        manifestContribution: ({ tree, config, publicAssets }) => {
+            const matches = config.content?.matches ?? ["<all_urls>"];
+            const fragment = {
+                content_scripts: [{ matches, js: ["content.js"] }],
+            };
+            // Anything a content script reaches via chrome.runtime.getURL must be
+            // declared accessible. The CSUI mount runtime dynamic-imports
+            // content.js; Public assets are getURL'd by user code. Both ride one
+            // entry scoped to the content script's matches.
+            const resources = [];
+            if (tree.scripts.content?.csui)
+                resources.push("content.js");
+            if (publicAssets?.length)
+                resources.push(...publicAssets);
+            if (resources.length) {
+                fragment.web_accessible_resources = [{ resources, matches }];
+            }
+            return fragment;
+        },
+        hostPermissions: ({ config }) => config.content?.matches ?? ["<all_urls>"],
+    },
+];
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+const BY_NAME = new Map(SURFACES.map((s) => [s.name, s]));
+export function findSurface(name) {
+    return BY_NAME.get(name);
+}

package/dist/plugin/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { ManifestV3 } from "../../types/index.js";
+export type PluginContextLike = {
+    emitFile(file: {
+        type: "asset";
+        fileName: string;
+        source: string | Uint8Array;
+    }): string;
+    warn(message: string): void;
+};

package/dist/plugin/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/utils/read-json.d.ts

@@ -0,0 +1 @@
+export declare function readJson<T = unknown>(file: string, root: string): T | null;

package/dist/plugin/utils/read-json.js

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+export function readJson(file, root) {
+    const filePath = path.join(root, file);
+    if (!fs.existsSync(filePath))
+        return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}

package/dist/react/env.d.ts

@@ -0,0 +1,13 @@
+export {};
+declare global {
+    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/react/env.js

@@ -0,0 +1 @@
+export {};

package/dist/router/build-tree.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentType, ReactElement } from "react";
+import type { BoundaryKind } from "../types/index.js";
+import type { Router } from "./context.js";
+import type { ErrorProps, LayoutProps, PageProps } from "./types.js";
+/** A boundary already paired with its loaded component (orchestration zips this). */
+export type ResolvedBoundary = {
+    kind: BoundaryKind;
+    component: ComponentType<LayoutProps> | ComponentType<ErrorProps>;
+};
+/**
+ * Every renderable outcome of a navigation. `buildTree` is total over this:
+ * `render()` resolves one of these (with the navToken/load orchestration) and
+ * hands it here; structure lives nowhere else.
+ */
+export type RenderOutcome = {
+    type: "match";
+    page: ComponentType<PageProps>;
+    params: Record<string, string>;
+    boundaries: ResolvedBoundary[];
+} | {
+    type: "not-found";
+    notFound: ComponentType;
+    rootLayout: ComponentType<LayoutProps> | null;
+} | {
+    type: "load-error";
+    error: Error;
+    reset: () => void;
+};
+export type RenderContext = {
+    pathname: string;
+    search: string;
+    router: Router;
+};
+/**
+ * @describe The single, pure home of ADR 0003 §3/§4/§5 structure. Given a
+ * resolved navigation outcome, returns the React element tree to mount:
+ *
+ *   - match:     <Provider><BuiltInEB> L0 <EB user> ... <Page/> ... </Provider>
+ *                (each segment's error nested inside its sibling layout, §3)
+ *   - not-found: <Provider><BuiltInEB> rootLayout? <NotFound/> </Provider> (§4)
+ *   - load-error: bare <DefaultError/> (load failed outside React render, §5)
+ *
+ * Pure and total: same inputs, same tree; no DOM, no effects. The always-on
+ * built-in error boundary (§5) means a match/not-found surface never blanks.
+ */
+export declare function buildTree(outcome: RenderOutcome, ctx: RenderContext): ReactElement;

package/dist/router/build-tree.js

@@ -0,0 +1,56 @@
+import { createElement } from "react";
+import { RouterContext } from "./context.js";
+import { ErrorBoundary } from "./error-boundary.js";
+import { DefaultError } from "./defaults.js";
+/**
+ * @describe The single, pure home of ADR 0003 §3/§4/§5 structure. Given a
+ * resolved navigation outcome, returns the React element tree to mount:
+ *
+ *   - match:     <Provider><BuiltInEB> L0 <EB user> ... <Page/> ... </Provider>
+ *                (each segment's error nested inside its sibling layout, §3)
+ *   - not-found: <Provider><BuiltInEB> rootLayout? <NotFound/> </Provider> (§4)
+ *   - load-error: bare <DefaultError/> (load failed outside React render, §5)
+ *
+ * Pure and total: same inputs, same tree; no DOM, no effects. The always-on
+ * built-in error boundary (§5) means a match/not-found surface never blanks.
+ */
+export function buildTree(outcome, ctx) {
+    if (outcome.type === "load-error") {
+        return createElement(DefaultError, {
+            error: outcome.error,
+            reset: outcome.reset,
+        });
+    }
+    // Router context + the always-on outermost built-in error boundary (§5),
+    // shared by the match and not-found paths so they stay consistent.
+    const provide = (params, inner) => createElement(RouterContext.Provider, {
+        value: {
+            pathname: ctx.pathname,
+            search: ctx.search,
+            params,
+            router: ctx.router,
+        },
+    }, createElement(ErrorBoundary, { fallback: DefaultError, children: inner }));
+    if (outcome.type === "not-found") {
+        let inner = createElement(outcome.notFound);
+        if (outcome.rootLayout) {
+            inner = createElement(outcome.rootLayout, { children: inner });
+        }
+        return provide({}, inner);
+    }
+    // Fold innermost-first so the outermost boundary wraps everything; each
+    // segment's error sits inside its sibling layout (the chain is ordered
+    // layout-before-error per segment). Empty chain = just the page.
+    const composed = outcome.boundaries.reduceRight((child, boundary) => {
+        if (boundary.kind === "error") {
+            return createElement(ErrorBoundary, {
+                fallback: boundary.component,
+                children: child,
+            });
+        }
+        return createElement(boundary.component, {
+            children: child,
+        });
+    }, createElement(outcome.page, { params: outcome.params }));
+    return provide(outcome.params, composed);
+}