@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/serve/vite-plugin.js

@@ -1,92 +1,13 @@
-/**
- * `@pyric/cli/vite` — the firebase→pyric-sandbox swap as a Vite plugin.
- *
- * The serve analog for SOURCE-driven apps: instead of `vite build && pyric dev
- * dist`, a team keeps `vite dev` (HMR, source maps) with the in-process sandbox
- * standing in for Firebase. The app's `firebase/*` imports are UNCHANGED — the
- * plugin swaps them at the module-resolution layer (`resolveId`), the same way
- * `pyric dev` swaps via a runtime import map. (Design: `plans/pyric-vite-plugin.md`.)
- *
- * Two flavors, one `apply` function. Under `vite dev` the swap is ALWAYS on.
- * For `vite build` the swap is MODE-gated: a plain `vite build` (mode
- * `production`) ships the real `firebase` package — the swap never reaches the
- * prod artifact — while `vite build --mode development` (any NON-production
- * mode) produces a SANDBOX build that bundles pyric's in-page adapters instead
- * of the real SDK: self-contained, meant to be previewed under `pyric dev`, and
- * stamped with the sandbox-build marker so it can never be deployed (`pyric
- * deploy hosting` refuses it). `pyric({ swapInBuild })` forces the build
- * behavior on/off regardless of mode. See `sandbox-marker.ts`.
- *
- * This is a thin adapter over serve's proven machinery. It REUSES, not reimplements:
- *   - the node-builtin shims — `NODE_BUILTIN_SHIMS`;
- *   - the swap targets — `defaultSdkEntries()` (the `serve/entries/*` wrappers,
- *     compiled-dist preferred, src fallback);
- *   - the `/__pyric/*` namespace — `createPyricNamespace` mounted verbatim behind
- *     a connect-middleware adapter;
- *   - rules load + prepare — `loadProjectRules` / `prepareRulesSource`;
- *   - the SharedWorker host — `bundleWorker` served at `/__pyric/sdk/worker.js`;
- *   - durable stores — `createStateStore` (persist) / `createCaptureStore`.
- *
- * Scope = M1 (swap + rules) + M2 (SharedWorker multi-tab + persist/capture/seed)
- * + M3 (the MCP bridge fold — `{ bridge }`). M3 reuses `createBridgeMount` (the
- * proven serve-flavored bridge behind `pyric dev --bridge`), composing it into
- * the same `/__pyric` middleware; on the worker path the bridge peer routes
- * agent tool-calls THROUGH the SharedWorker (`connectBridgePeer`), so the agent
- * and the app share one backend without forcing the page in-page.
- *
- * Serving `worker.js` flips `runtime.ts` to the worker path (one backend across
- * tabs, IndexedDB-durable); on that path the WORKER owns persist/capture/seed via
- * the same `/__pyric/*` routes. If the worker bundle fails, the plugin falls back
- * to the in-page sandbox (single-tab, ephemeral).
- */
-import { readFile } from 'node:fs/promises';
-import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
-import path from 'node:path';
-import { SDK_MODULES, defaultSdkEntries, resolveStudioUiDir, pyricPackageRoot, NODE_BUILTIN_RE, NODE_BUILTIN_SHIMS, } from './bundler.js';
 import { createViteWorkerRuntime } from './vite-worker-runtime.js';
-import { createEventHub, createPyricNamespace, } from './namespace.js';
-import { formatActivityWarning } from './activity-warning.js';
-import { diskWorkspace, diskProjectStore } from './studio/index.js';
-import { createBridgeMount } from './bridge-mount.js';
-import { loadProjectDatabaseRules, loadProjectRules, loadProjectStorageRules, prepareRulesSource, rulesHashOf, } from './rules.js';
-import { createStateStore, STATE_FILE_VERSION } from './state-store.js';
-import { createCaptureStore } from './capture-store.js';
-import { isAllowedHost } from './server.js';
-import { SANDBOX_BUILD_META } from './sandbox-marker.js';
-import { readFirebaseJson, readFirebaseRc } from '../cli/firebase-json.js';
-import { discoverFunctionsRtdbProject, } from '../functions-rtdb/project.js';
-import { spawnFunctionsRtdbChild, } from '../functions-rtdb/child.js';
-import { buildChildEnv, createLinePrefixer, registerModuleUrl, } from '../cli/dev-runner.js';
-import { loadViteAiEnv, resolveViteAiConfig, viteWorkerEpochSalt, } from './vite-ai-config.js';
-import { resolveViteRulesConfig } from './vite-rules-source.js';
-import { PYRIC_RUNTIME_CHIP_META, runtimeChipMetaValue, } from './runtime/chip-config.js';
-/**
- * Whether a `vite build` should run the firebase→pyric swap (produce a SANDBOX
- * build). MODE-based with a plugin-config override:
- *   - `options.swapInBuild` wins outright when set (force on/off);
- *   - otherwise swap for any NON-production mode. A plain `vite build` (mode
- *     `production`) ships real firebase; `vite build --mode development` (or any
- *     custom non-prod mode) is a sandbox build.
- * `vite dev` is handled separately in `apply` (always on).
- */
-function swapsInBuild(env, swapInBuild) {
-    if (swapInBuild !== undefined)
-        return swapInBuild;
-    return env.mode !== 'production';
-}
-/** Any `firebase/<sub>` specifier. */
-const FB_ANY = /^firebase\/([a-z-]+(?:\/[a-z-]+)*)$/;
-/** The firebase subpaths with swap entries. */
-const SERVED = new Set(SDK_MODULES.map((specifier) => specifier.slice('firebase/'.length)));
-const entryKey = (subpath) => subpath.replaceAll('/', '-');
-const NODE_SHIM_PREFIX = '\0pyric:node-shim:';
-/** Walk up from a file to the nearest directory containing a package.json. */
-function packageRootOf(file) {
-    let dir = path.dirname(file);
-    while (dir !== path.dirname(dir) && !existsSync(path.join(dir, 'package.json'))) {
-        dir = path.dirname(dir);
-    }
-    return dir;
+import { createViteSandboxGeneration, } from './vite-sandbox-generation.js';
+import { createViteModuleContext, createViteModuleSwap } from './vite-module-swap.js';
+import { createVitePageRuntime } from './vite-page-runtime.js';
+function resolveFunctionsOptions(options) {
+    if (options === false)
+        return false;
+    if (typeof options === 'object')
+        return options;
+    return {};
 }
 /**
  * The dev-only Vite plugin. Add to `vite.config`:
@@ -95,102 +16,22 @@ function packageRootOf(file) {
  *   export default defineConfig({ plugins: [pyric()] });
  */
 export function pyric(options = {}) {
-    let resolvedAi = resolveViteAiConfig(options.ai, {});
-    // Resolved once. `defaultSdkEntries()` prefers compiled dist `.js` and falls
-    // back to source `.ts` in the workspace.
-    const entries = defaultSdkEntries(); // { app, auth, firestore, init } → abs paths
-    const pyricRoot = pyricPackageRoot();
-    // The @pyric/cli package root — covers the served entries AND their siblings
-    // (`worker/client.js`, the bridge client) that the entries statically import.
-    const cliRoot = packageRootOf(entries.init);
-    // section 8 refinement: a firebase import is "pyric-internal" iff its importer lives
-    // under the resolved pyric package root — keyed on the root, not a `/pyric/`
-    // substring (which a user project path could false-positive).
-    const isPyricImporter = (importer) => {
-        if (!importer)
-            return false;
-        const f = importer.split('?')[0];
-        return f === pyricRoot || f.startsWith(pyricRoot + path.sep);
-    };
-    // Node builtins are reached only from OUR code (pyric internals + the served
-    // entries) — shim those, but NEVER hijack a user app or third-party library's
-    // own `fs`/`path`/`url` (which Vite, or the user's polyfill plugin, should
-    // resolve). The firebase branch stays scoped to pyric; this is the wider "ours".
-    const isOurCode = (importer) => {
-        if (!importer)
-            return false;
-        if (isPyricImporter(importer))
-            return true;
-        const f = importer.split('?')[0];
-        return f === cliRoot || f.startsWith(cliRoot + path.sep);
-    };
-    const shimFor = (spec) => NODE_BUILTIN_SHIMS[spec.replace(/^node:/, '')];
-    // The esbuild mirror for Vite's dep optimizer — REQUIRED so a node_modules
-    // library's `firebase/*` swaps too (the optimizer's esbuild pass bypasses the
-    // Rollup-pipeline resolveId below and would otherwise pre-bake real firebase).
-    const esbuildMirror = {
-        name: 'pyric-sandbox-optimizer',
-        setup(build) {
-            build.onResolve({ filter: FB_ANY }, (args) => {
-                const sub = FB_ANY.exec(args.path)[1];
-                if (SERVED.has(sub))
-                    return { path: entries[entryKey(sub)] };
-                return null; // non-served firebase from a lib → real firebase
-            });
-            build.onResolve({ filter: NODE_BUILTIN_RE }, (args) => {
-                if (!isOurCode(args.importer))
-                    return null; // user/lib node builtins → Vite/their polyfill
-                return { path: args.path.replace(/^node:/, ''), namespace: 'pyric-node-shim' };
-            });
-            build.onLoad({ filter: /.*/, namespace: 'pyric-node-shim' }, (args) => ({
-                contents: NODE_BUILTIN_SHIMS[args.path],
-                loader: 'js',
-            }));
-        },
-    };
-    // Live rules box — the watcher swaps it; the init payload always serves the
-    // current version.
-    const live = {
-        rules: null,
-        rulesHash: null,
-        databaseRules: null,
-        databaseRulesHash: null,
-        databaseUrl: null,
-        storageRules: null,
-        storageRulesHash: null,
-    };
-    // M2: the SharedWorker bundle's content hash (sync) — stamped into the page so
-    // a still-running OLD worker is detected as stale. The collaborator becomes
-    // ready once its bundle succeeds; until then (or on bundle failure) the page
-    // is forced onto the in-page sandbox path. transformIndexHtml reads its tag.
+    const moduleContext = createViteModuleContext();
+    const moduleSwap = createViteModuleSwap(moduleContext);
+    const { entries, cliRoot } = moduleContext;
     const workerRuntime = createViteWorkerRuntime();
-    // Set by the `config` hook. When the plugin runs under `vite build` at all it
-    // is a SANDBOX build (the `apply` gate below only lets build through under the
-    // sandbox trigger), so `command === 'build'` is sufficient to know we are
-    // producing marker-stamped, non-production output.
-    let sandboxBuild = false;
-    // Sandbox build: the serve init entry (runtime bootstrap + the ServeAuthHelper
-    // popup picker) is emitted as its OWN chunk and script-tagged into index.html.
-    // Rollup dedupes the shared runtime module between this chunk and the app
-    // chunk (both import the same absolute file), so the page runs exactly ONE
-    // sandbox runtime — unlike serve-time injection of /__pyric/sdk/init.js,
-    // which is a separately-bundled second runtime copy (the double-init bug:
-    // two banners, two bridge registrations). `pyric dev` sees the marker and
-    // skips its injection for these pages (see injectServeTags).
-    let initChunkRef;
-    let initChunkFile;
-    // M3 bridge fold: normalize `bridge` once (true ⇒ `{}`, falsy ⇒ null). When
-    // on, the MCP mount is composed into the /__pyric middleware (createBridgeMount,
-    // shared with `pyric dev --bridge`) AND the page is forced onto the in-page
-    // sandbox path — the bridge peer is the in-page sandbox, never the SharedWorker,
-    // so multi-tab is disabled under bridge to keep agent + app on one backend.
+    const studioEnabled = options.ui !== false;
+    const pageRuntimeInput = {
+        options,
+        studioEnabled,
+        initEntry: entries.init,
+        workerRuntime,
+    };
+    const pageRuntime = createVitePageRuntime(pageRuntimeInput);
+    // Normalize the public bridge shorthand once. The active generation owns the
+    // bridge/session attachment and routes the peer through the SharedWorker.
     const bridgeOpts = options.bridge === true ? {} : options.bridge || null;
-    // Plugin-level AI engine, normalized to the JSON-safe wire shape. Travels
-    // to the worker host via the init payload (→ ctx.aiEngine) AND to the in-page
-    // fallback via an injected synchronous global (see transformIndexHtml).
-    // An explicit engine is available immediately (some hook tests call the HTML
-    // transform directly); Vite's config hook may otherwise select the simple
-    // PYRIC_AI_MODEL environment path for the active mode/root.
+    let activeGeneration = null;
     return {
         name: 'pyric:sandbox',
         // Active for `vite dev` ALWAYS, and for `vite build` only when it is a
@@ -201,643 +42,57 @@ export function pyric(options = {}) {
         // `pyric dev`, never deploy it).
         apply(config, env) {
             void config;
-            if (env.command === 'serve')
-                return true;
-            return swapsInBuild(env, options.swapInBuild);
+            return pageRuntime.applies(env);
         },
         enforce: 'pre',
         config(config, env) {
-            sandboxBuild = env.command === 'build';
-            const loadedEnv = loadViteAiEnv(env.mode, config.root, config.envDir);
-            resolvedAi = resolveViteAiConfig(options.ai, loadedEnv);
-            // Cast: the `esbuild` package's `Plugin` type skews slightly from Vite's
-            // bundled esbuild types (benign — the Plugin shape is stable across the
-            // versions in range).
             return {
-                optimizeDeps: {
-                    // Keep firebase out of the optimizer's pre-bake; the resolver swaps it
-                    // per-importer at request time.
-                    exclude: [...SDK_MODULES],
-                    // The excluded SDK is served as ESM straight from dist, so Vite never
-                    // scans it for dependencies. js-md5 / js-sha256 are CJS-only (no ESM
-                    // named exports); without a forced pre-bundle the browser gets the raw
-                    // UMD source and `import { md5 }` throws a SyntaxError. Force-including
-                    // them gives the dist imports the interop-wrapped optimized copies.
-                    include: ['js-md5', 'js-sha256'],
-                    esbuildOptions: { plugins: [esbuildMirror] },
-                },
-                // Sandbox build only: the swapped-in runtime chunk uses TOP-LEVEL AWAIT
-                // (it deploys rules before app code runs — load-bearing, see
-                // entries/runtime.ts). Vite's default build target predates TLA and the
-                // esbuild transpile would fail. A sandbox build is a throwaway preview
-                // served under `pyric dev` (modern browser), so pin an ESNext target
-                // that keeps TLA. A plain production `vite build` never runs this plugin,
-                // so the user's own target is untouched there.
-                ...(sandboxBuild ? { build: { target: 'esnext' } } : {}),
+                ...moduleSwap.config(),
+                ...pageRuntime.config(config, env),
             };
         },
         configResolved(resolved) {
-            // AUGMENT (don't replace) the fs allow-list: pyric dist + the @pyric/cli
-            // tree live outside the app root, but setting `server.fs.allow` in config()
-            // would clobber Vite's auto-added root/workspace entries and 403 the app's
-            // own source. Push the two PACKAGE ROOTS — @pyric/cli' root (not just the
-            // entries dir) is needed because the served init entry statically imports
-            // siblings (`worker/client.js`, the bridge client) outside entries/.
-            const allow = resolved.server?.fs?.allow;
-            if (allow) {
-                for (const dir of [pyricRoot, cliRoot]) {
-                    if (!allow.includes(dir))
-                        allow.push(dir);
-                }
-            }
+            moduleSwap.configResolved(resolved);
         },
         resolveId(source, importer) {
-            const fb = FB_ANY.exec(source);
-            if (fb) {
-                const sub = fb[1];
-                if (SERVED.has(sub))
-                    return entries[entryKey(sub)]; // swap served set for user/lib
-                return null; // non-served firebase from user → real firebase
-            }
-            const node = NODE_BUILTIN_RE.exec(source);
-            // Shim node builtins ONLY when reached from our own code — never hijack a
-            // user app or library's own fs/path/url (Vite/their polyfill handles those).
-            if (node && isOurCode(importer))
-                return NODE_SHIM_PREFIX + node[2];
-            return null;
+            return moduleSwap.resolveId(source, importer);
         },
         load(id) {
-            if (id.startsWith(NODE_SHIM_PREFIX))
-                return shimFor(id.slice(NODE_SHIM_PREFIX.length));
-            return null;
+            return moduleSwap.load(id);
         },
         async configureServer(server) {
-            const cwd = options.root ?? server.config.root;
-            // Reproduce serve's rules prelude: firebase.json (optional) → loadProjectRules.
-            let fbJson = null;
-            try {
-                fbJson = await readFirebaseJson(cwd);
-            }
-            catch {
-                /* optional — serve without a firebase.json */
-            }
-            // Convention-first development source: an explicit option wins; otherwise
-            // an authored 2+modules file wins over firebase.json's generated deployment
-            // target. Projects without that convention retain the normal Firebase
-            // discovery path.
-            const config = resolveViteRulesConfig(cwd, options.rules, fbJson);
-            const loaded = await loadProjectRules(cwd, config);
-            const loadedDatabase = await loadProjectDatabaseRules(cwd, config);
-            const loadedStorage = await loadProjectStorageRules(cwd, config);
-            live.rules = loaded.rules;
-            live.rulesHash = loaded.rulesHash;
-            live.databaseRules = loadedDatabase.rules;
-            live.databaseRulesHash = loadedDatabase.rulesHash;
-            live.databaseUrl = loadedDatabase.databaseUrl;
-            live.storageRules = loadedStorage.rules;
-            live.storageRulesHash = loadedStorage.rulesHash;
-            // ── M2 durable stores (mirrors serve's startServe orchestration) ──────
-            // Capture (default-on): the worker/page pushes its session fixture to
-            // /__pyric/capture; the store writes .pyric/last-session.json for `pyric verify`.
-            const capture = (options.capture ?? true) ? createCaptureStore(cwd) : undefined;
-            // Persist: createStateStore IS the durable sandbox. Load eagerly so a
-            // corrupt/mismatched file fails the start (not silently ephemeral).
-            const state = options.persist ? createStateStore(cwd) : undefined;
-            if (state && options.fresh) {
-                for (const p of [state.path, state.backupPath])
-                    if (existsSync(p))
-                        rmSync(p);
-                server.config.logger.info('  ⓘ [pyric] fresh: discarded the existing state file; re-seeding');
-            }
-            // Eager load (mirrors serve.ts:158) — parse the file NOW so a corrupt or
-            // version-mismatched state file throws StateFileError and FAILS THE START
-            // with the actionable inspect-or-delete message. Without this the first
-            // parse is deferred into initPayload() at request time, where it throws
-            // synchronously AFTER namespace.ts has committed `writeHead(200)`: the
-            // client gets a 200 with an empty body, the page/worker swallow the JSON
-            // error, and the sandbox silently runs WITHOUT the persisted data + rules.
-            // (No-op on first run: load() returns null for a missing file.)
-            // configureServer is async, so an uncaught throw aborts the dev start.
-            if (state)
-                state.load();
-            // Seed: a "collection/doc" → fields map, OR a `pyric snapshot` state-file
-            // envelope (detected by its `version` key). Ported from serve.ts.
-            let seed = null;
-            let seedState = null;
-            let seedUsers = null;
-            if (options.seed) {
-                const seedPath = path.resolve(cwd, options.seed);
-                let parsed;
-                try {
-                    parsed = JSON.parse(readFileSync(seedPath, 'utf8'));
-                }
-                catch (e) {
-                    throw new Error(`@pyric/cli/vite: failed to read seed ${seedPath}: ${e instanceof Error ? e.message : String(e)}`);
-                }
-                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-                    throw new Error('@pyric/cli/vite: seed must be a JSON object of "collection/doc" → fields');
-                }
-                const obj = parsed;
-                if (obj.version === STATE_FILE_VERSION && ('firestore' in obj || 'auth' in obj)) {
-                    const fixture = obj;
-                    if (state && !state.exists()) {
-                        // persist first run from a fixture: prime the store, then the normal
-                        // persist path restores it like any lived state.
-                        if (fixture.firestore != null)
-                            state.writeSection('firestore', fixture.firestore);
-                        if (fixture.auth != null)
-                            state.writeSection('auth', fixture.auth);
-                    }
-                    else if (!state) {
-                        seedState = fixture.firestore ?? null;
-                        seedUsers = fixture.auth?.users ?? null;
-                    }
-                    // persist + existing state: lived state wins; the fixture is inert.
-                }
-                else {
-                    seed = parsed;
-                }
-            }
-            // ── M2 SharedWorker host: bundle it (cached per version) and serve it at
-            // /__pyric/sdk/worker.js. This is what flips runtime.ts to the worker path.
-            // On bundle failure, the collaborator stays unready and its HTML tag
-            // forces the in-page sandbox.
-            try {
-                await workerRuntime.prepare(viteWorkerEpochSalt(cwd, resolvedAi.engineWire));
-            }
-            catch (e) {
-                server.config.logger.warn(`  ⚠ [pyric] SharedWorker bundle failed — using the in-page sandbox (single-tab, ephemeral): ${e instanceof Error ? e.message : String(e)}`);
-            }
-            // ── Functions (RTDB triggers) — the `pyric dev` parity fold ───────────
-            // Discover the one supported Functions codebase from the same resolved
-            // firebase.json the rules used (project.ts reads it itself). Reuses the
-            // exact serve module, so absent `functions` → null (silently off) and a
-            // malformed config throws serve's own error text — which, thrown from an
-            // async configureServer, fails the dev start the same way serve's
-            // `return 2` aborts. The Functions child connects to the sandbox over the
-            // bridge WS, so a discovered codebase forces the bridge mount on (mirrors
-            // serve's `bridgeEnabledFor(..., functionsProject)`). `functions: false`
-            // is the off switch: discovery never runs, so neither does the mount.
-            const functionsOpts = typeof options.functions === 'object' ? options.functions : {};
-            let functionsProject = null;
-            if (options.functions !== false) {
-                try {
-                    functionsProject = discoverFunctionsRtdbProject(cwd);
-                }
-                catch (error) {
-                    // Malformed functions config: fail the start with serve's exact message.
-                    throw error instanceof Error ? error : new Error(String(error));
-                }
-            }
-            const functionsProjectId = functionsProject
-                ? (process.env.PYRIC_PROJECT ?? (await readFirebaseRc(cwd))?.projects?.default ?? 'demo-project')
-                : null;
-            // ── M3 MCP bridge (mirrors serve.ts:221–274) ─────────────────────────
-            // The mount is long-lived (one bridge per dev session); its MCP transport
-            // is rebuilt per request (stateless). Composed into the /__pyric middleware
-            // below (handler tier) + the server's WS upgrade. middlewareMode has no
-            // httpServer → HTTP routes still work, no WS peer.
-            // Guard the WS upgrade with the SAME allow rule Vite's own host check
-            // uses (host + allowedHosts, where `true` = opted into all hosts). Vite's
-            // upgrade path bypasses connect middleware, so this is the only guard on it.
-            const mount = bridgeOpts || functionsProject
-                ? createBridgeMount({
-                    ...(bridgeOpts ?? {}),
-                    // A functions-only session still needs a labeled bridge; prefer an
-                    // explicit bridge project, else the resolved functions project id.
-                    project: bridgeOpts?.project ?? functionsProjectId ?? undefined,
-                    upgradeGuard: {
-                        boundHost: typeof server.config.server.host === 'string' ? server.config.server.host : 'localhost',
-                        allowedHosts: server.config.server.allowedHosts === true
-                            ? true
-                            : Array.isArray(server.config.server.allowedHosts)
-                                ? server.config.server.allowedHosts
-                                : [],
-                    },
-                })
-                : null;
-            // The /__pyric/* namespace, reused VERBATIM (now with the sdk dir + state +
-            // capture routes live).
-            const events = createEventHub();
-            const initPayload = () => ({
-                rules: live.rules,
-                rulesHash: live.rulesHash,
-                databaseRules: live.databaseRules,
-                databaseRulesHash: live.databaseRulesHash,
-                databaseUrl: live.databaseUrl,
-                storageRules: live.storageRules,
-                storageRulesHash: live.storageRulesHash,
-                // Project identity: scopes the storage IDB name per served project
-                // (issue #359). Local-only — a dev path never leaves the machine.
-                projectKey: cwd,
-                // The bound port is known only after `listen`; initPayload runs per
-                // request (after listen), so resolve it lazily here. Absolute ws://host:port
-                // mirrors serve (the browser reads this as the bridge peer URL).
-                bridgeUrl: (() => {
-                    if (!mount)
-                        return null;
-                    const addr = server.httpServer?.address();
-                    const port = addr && typeof addr === 'object' ? addr.port : 0;
-                    const host = (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
-                    return port > 0 ? mount.wsUrl({ host, port }) : null;
-                })(),
-                // Precedence: once a state file exists, lived state is the truth — seed
-                // applies only on the first (state-less) run.
-                seed: state?.exists() ? null : seed,
-                seedState,
-                persist: Boolean(state),
-                capture: Boolean(capture),
-                authUsers: state
-                    ? (state.readSection('auth')?.users ?? null)
-                    : seedUsers,
-                // Messaging is part of the canonical firebase/* sandbox swap.
-                messaging: true,
-                // Plugin-level engine → the worker host's ctx.aiEngine (host-ai.ts),
-                // which wins over any op-carried engine. Null when unset.
-                ai: resolvedAi.engineWire ? { engine: resolvedAi.engineWire } : null,
-            });
-            // Pyric Studio: mount the disk-backed workspace/project routes that
-            // Studio's `local` mode talks to + serve the built Studio app at
-            // /__pyric/ui/. Mirrors `pyric dev --ui`; the studio-ui assets are
-            // vendored in this package's dist (resolveStudioUiDir).
-            //
-            // ON BY DEFAULT, including under `bridge`: the bridge now routes agent
-            // tool-calls THROUGH the SharedWorker (see `connectBridgePeer`), so the
-            // app, Studio, and agent all observe the ONE sandbox. Explicit `ui: false`
-            // still wins.
+            const priorGeneration = activeGeneration;
+            activeGeneration = null;
+            await priorGeneration?.close();
+            const projectDir = options.root ?? server.config.root;
             const uiEnabled = options.ui ?? true;
-            const studio = uiEnabled
-                ? {
-                    workspace: diskWorkspace(cwd),
-                    projects: diskProjectStore(path.join(cwd, '.pyric', 'projects')),
-                }
-                : undefined;
-            let studioUiDir;
-            if (uiEnabled) {
-                studioUiDir = resolveStudioUiDir() ?? undefined;
-                if (!studioUiDir) {
-                    server.config.logger.warn('[pyric] ui: built Studio app not found; /__pyric/ui/ will 404 ' +
-                        '(run the full build, or reinstall @pyric/cli).');
-                }
-            }
-            const { sdkDir } = workerRuntime.status();
-            const namespace = createPyricNamespace({
-                sdkDir,
-                initPayload,
-                events,
-                activity: (incident) => server.config.logger.warn(formatActivityWarning(incident)),
-                state,
-                capture,
-                studio,
-                studioUiDir,
-                // `ai.proxyUpstream`: what `/__pyric/ai-proxy` forwards to (beats the
-                // PYRIC_AI_PROXY_UPSTREAM env var; falls back to the default when unset).
-                aiProxyUpstream: resolvedAi.proxyUpstream,
-                // Adapt Vite's logger to the plain info/note shape the namespace's
-                // diagnostics (denial relay, future hot-reload lines) expect —
-                // matches the `↻`/`⚠ [pyric]` lines already logged elsewhere in this
-                // plugin via `server.config.logger` directly.
-                logger: {
-                    info: (m) => server.config.logger.info(m),
-                    note: (m) => server.config.logger.warn(m),
-                },
-            });
-            // DNS-rebinding guard for the /__pyric/* surface. Vite has its own host
-            // check, but a `configureServer` hook that doesn't return a function mounts
-            // BEFORE it (and the ordering differs across Vite 5/6/7), so guard here too
-            // — independent of Vite's internals. Reuses serve's `isAllowedHost`.
-            const srvOpts = server.config.server;
-            const hostAllowed = (req) => {
-                if (srvOpts.allowedHosts === true)
-                    return true; // user opted into all hosts
-                const boundHost = typeof srvOpts.host === 'string' ? srvOpts.host : 'localhost';
-                const extra = Array.isArray(srvOpts.allowedHosts) ? srvOpts.allowedHosts : [];
-                return isAllowedHost(req.headers.host, boundHost, extra);
+            const functionsOptions = resolveFunctionsOptions(options.functions);
+            const ai = pageRuntime.ai();
+            const generationOptions = {
+                rules: options.rules,
+                seed: options.seed,
+                persist: options.persist,
+                fresh: options.fresh,
+                capture: options.capture,
+                bridge: bridgeOpts,
+                ui: uiEnabled,
+                functions: functionsOptions,
             };
-            // Connect-middleware adapter (build `url` from originalUrl; next() when the
-            // namespace closure returns false; never rewrite route bodies).
-            server.middlewares.use('/__pyric', (req, res, next) => {
-                if (!hostAllowed(req)) {
-                    res.statusCode = 403;
-                    res.end(`pyric: refused request for Host '${req.headers.host ?? ''}' (DNS-rebinding guard).`);
-                    return;
-                }
-                const url = new URL(req.originalUrl ?? req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
-                // Bridge first (mirrors serve.ts): /__pyric/mcp + /__pyric/health must be
-                // handled by the mount, not 404 through the namespace. Falls through to the
-                // namespace when the mount returns false (every non-bridge route).
-                Promise.resolve(mount ? mount.handler(req, res, url) : false)
-                    .then((bridged) => (bridged ? true : Promise.resolve(namespace(req, res, url))))
-                    .then((handled) => {
-                    if (!handled)
-                        next();
-                })
-                    .catch((err) => {
-                    if (!res.headersSent)
-                        res.statusCode = 500;
-                    res.end(err instanceof Error ? err.message : String(err));
-                });
-            });
-            // WS upgrade for the in-page sandbox peer (ws://…/__pyric/sandbox). The
-            // listener only fires once upgrades arrive (after listen), so adding it in
-            // configureServer is safe. middlewareMode has no httpServer → HTTP bridge
-            // routes still work, just no WS peer.
-            // Cast: Vite types `httpServer` as http.Server | http2.Http2SecureServer;
-            // attachUpgrade only needs `.on('upgrade')`, present on both. (serve passes
-            // a plain http.Server, so this widening is plugin-specific.)
-            if (mount && server.httpServer)
-                mount.attachUpgrade(server.httpServer);
-            // A2 discovery pointer: the stdio `mcp-proxy` (the sanctioned Claude Code
-            // entrypoint) reads `.pyric/serve.json` to find the bridge without a fixed
-            // URL -- it takes the PORT and probes BOTH loopback families, defeating the
-            // IPv6/IPv4 trap that broke the hand-written `.mcp.json`. serve writes this
-            // pointer; the Vite plugin must too. Written after listen (port known),
-            // removed on close.
-            if (mount && server.httpServer) {
-                const httpServer = server.httpServer;
-                const pointer = path.join(cwd, '.pyric', 'serve.json');
-                const host = (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
-                const writePointer = () => {
-                    const addr = httpServer.address();
-                    const port = addr && typeof addr === 'object' ? addr.port : 0;
-                    if (!port)
-                        return;
-                    try {
-                        mkdirSync(path.dirname(pointer), { recursive: true });
-                        writeFileSync(pointer, JSON.stringify({
-                            url: `http://${host}:${port}`,
-                            mcpUrl: mount.mcpUrl({ host, port }),
-                            port,
-                            pid: process.pid,
-                            instanceId: mount.instanceId,
-                            project: bridgeOpts?.project ?? 'sandbox',
-                        }, null, 2) + '\n');
-                    }
-                    catch {
-                        /* best-effort: the proxy falls back to a port scan */
-                    }
-                };
-                // Cross-family collision guard: once listening, probe BOTH loopback
-                // families on our port. If a DIFFERENT sandbox answers on the other
-                // family, two dev servers are colliding (IPv4 `*:P` + IPv6 `[::1]:P`)
-                // and the agent/browser can split across them (writes seem to vanish).
-                // #697's dual-bind can't apply here — Vite owns the single listen — so
-                // we can only warn, loudly. (Our own family answers with our instanceId
-                // and is skipped; a dual-stack bind owns both and never trips this.)
-                const warnOnCollision = async () => {
-                    const a = httpServer.address();
-                    const p = a && typeof a === 'object' ? a.port : 0;
-                    if (!p)
-                        return;
-                    for (const probe of [`http://127.0.0.1:${p}`, `http://[::1]:${p}`]) {
-                        try {
-                            const res = await fetch(`${probe}/__pyric/health`, { signal: AbortSignal.timeout(1000) });
-                            if (res.status !== 200)
-                                continue;
-                            const body = (await res.json());
-                            if (body.mode === 'sandbox' && body.instanceId && body.instanceId !== mount.instanceId) {
-                                server.config.logger.warn(`\n⚠  pyric: another sandbox already serves port ${p} on a different loopback ` +
-                                    `family (${probe}). Two dev servers are colliding across IPv4/IPv6 — your MCP ` +
-                                    `agent and browser can land on DIFFERENT sandboxes (writes seem to vanish). ` +
-                                    `Stop the other server, or give this app a unique \`server.port\` so the two ` +
-                                    `don't share one (pinning server.host to a family the squatter holds would ` +
-                                    `just EADDRINUSE).\n`, { timestamp: true });
-                                return; // one warning is enough
-                            }
-                        }
-                        catch {
-                            /* other family silent — no collision */
-                        }
-                    }
-                };
-                const announce = () => {
-                    writePointer();
-                    void warnOnCollision();
-                };
-                if (httpServer.listening)
-                    announce();
-                else
-                    httpServer.once('listening', announce);
-                httpServer.once('close', () => {
-                    try {
-                        rmSync(pointer);
-                    }
-                    catch {
-                        /* gone already */
-                    }
-                });
-            }
-            // ── Functions child lifecycle (mirrors serve's runServe) ─────────────
-            // The Functions runtime executes in an isolated node child (child.ts),
-            // exactly as `pyric dev` runs it: the child loads the user's unchanged
-            // functions module, and `--import @pyric/cli/register` + `PYRIC_SANDBOX=
-            // remote:<serveUrl>` route its `firebase-admin/app` to a RemoteSandbox that
-            // dials the bridge WS (`/__pyric/sandbox`). onValueCreated triggers observe
-            // RTDB writes and write their effects back through that one shared sandbox.
-            // Started once a sandbox peer (a browser tab / SharedWorker relay) has
-            // connected — the trigger's baseline needs a live backend — and stopped on
-            // server close. Vite restarts re-run configureServer, so the child respawns
-            // with the new server. Unlike `pyric dev` (which does not watch functions
-            // source), the plugin hot-reloads it via Vite's own watcher — see the
-            // watch block below; `functions: { watch: false }` restores dev's
-            // restart-to-reload behavior.
-            if (functionsProject && functionsProjectId && mount && server.httpServer) {
-                const httpServer = server.httpServer;
-                const project = functionsProject;
-                const projectId = functionsProjectId;
-                const bridgeMount = mount;
-                const host = (typeof server.config.server.host === 'string' && server.config.server.host) || 'localhost';
-                // Prefer the compiled child (node cannot execute the .ts source when the
-                // plugin runs from source in tests); fall back to spawnFunctionsRtdbChild's
-                // own default (correct when the plugin runs from dist in production).
-                const builtChild = path.join(cliRoot, 'dist/functions-rtdb/child.js');
-                const childModuleUrl = existsSync(builtChild) ? builtChild : undefined;
-                let functionsChild = null;
-                let disposed = false;
-                const start = async (mode = 'initial') => {
-                    const addr = httpServer.address();
-                    const port = addr && typeof addr === 'object' ? addr.port : 0;
-                    if (!port || disposed)
-                        return;
-                    const serveUrl = `http://${host}:${port}`;
-                    // Wait (bounded) for a sandbox peer — the SharedWorker relay / browser
-                    // tab that holds the backend. Poll the mount directly (no self-fetch).
-                    // On a hot reload the peer is usually still connected (the loop exits
-                    // immediately); when it dropped mid-session, wait briefly rather than
-                    // the full initial 30s.
-                    const deadline = Date.now() + (mode === 'reload' ? 5_000 : 30_000);
-                    while (!disposed && !bridgeMount.sandboxConnected()) {
-                        if (Date.now() >= deadline)
-                            break;
-                        await new Promise((r) => setTimeout(r, 250));
-                    }
-                    if (disposed)
-                        return;
-                    if (!bridgeMount.sandboxConnected()) {
-                        server.config.logger.warn(mode === 'reload'
-                            ? `  ✖ [pyric] functions not restarted — no sandbox peer connected. ` +
-                                `Functions stay down until the next save with ${serveUrl} open.`
-                            : `  ⚠ [pyric] functions not started — no browser tab connected after 30s. ` +
-                                `Open ${serveUrl} and restart the dev server.`);
-                        return;
-                    }
-                    functionsChild = spawnFunctionsRtdbChild({
-                        cwd: project.sourceDir,
-                        entry: project.entry,
-                        env: buildChildEnv(process.env, { serveUrl, registerUrl: registerModuleUrl() }),
-                        // Precedence (per field): plugin option > env var > firebase files
-                        // > default. projectId already folds PYRIC_PROJECT > .firebaserc >
-                        // demo-project.
-                        instance: functionsOpts.instance ?? `${projectId}-default-rtdb`,
-                        location: functionsOpts.region ?? process.env.PYRIC_FUNCTIONS_RTDB_REGION ?? 'us-central1',
-                        ...(childModuleUrl ? { childModuleUrl } : {}),
-                        onEvent(event) {
-                            if (event.type === 'execution') {
-                                const params = Object.entries(event.params)
-                                    .map(([name, value]) => `${name}=${value}`)
-                                    .join(', ');
-                                const suffix = params ? ` (${params})` : '';
-                                if (event.status === 'fulfilled') {
-                                    server.config.logger.info(`  ✔ [pyric] function ${event.exportName} ← /${event.ref}${suffix}`);
-                                }
-                                else {
-                                    server.config.logger.error(`  ✖ [pyric] function ${event.exportName} ← /${event.ref}${suffix}: ${event.error.message}`);
-                                }
-                            }
-                            else {
-                                server.config.logger.error(`  ✖ [pyric] functions delivery for ${event.exportName}: ${event.error.message}`);
-                            }
-                        },
-                    });
-                    const out = createLinePrefixer('[functions] ', (line) => server.config.logger.info(line.replace(/\n$/, '')));
-                    const err = createLinePrefixer('[functions] ', (line) => server.config.logger.warn(line.replace(/\n$/, '')));
-                    functionsChild.child.stdout?.setEncoding('utf8');
-                    functionsChild.child.stderr?.setEncoding('utf8');
-                    functionsChild.child.stdout?.on('data', (chunk) => out.push(chunk));
-                    functionsChild.child.stderr?.on('data', (chunk) => err.push(chunk));
-                    functionsChild.child.stdout?.once('end', () => out.flush());
-                    functionsChild.child.stderr?.once('end', () => err.flush());
-                    try {
-                        const ready = await functionsChild.ready;
-                        server.config.logger.info(mode === 'reload'
-                            ? `  ↻ [pyric] functions reloaded (${ready.triggerCount} trigger${ready.triggerCount === 1 ? '' : 's'})`
-                            : `  ✔ [pyric] functions ${ready.triggerCount} onValueCreated ` +
-                                `trigger${ready.triggerCount === 1 ? '' : 's'} from ${path.relative(cwd, project.entry)}`);
-                        for (const unsupported of ready.unsupportedTriggers) {
-                            server.config.logger.warn(`  ⚠ [pyric] functions export ${unsupported.exportName} uses unsupported trigger ` +
-                                `${unsupported.eventType}; it will not run.`);
-                        }
-                    }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        server.config.logger.error(mode === 'reload'
-                            ? // Unlike rules, last-good cannot stay live — the old child is
-                                // already stopped — so a broken save takes functions down.
-                                `  ✖ [pyric] functions failed to reload: ${message}\n` +
-                                    `  ✖ [pyric] functions are down until the next good save.`
-                            : `  ✖ [pyric] functions failed to start: ${message}`);
-                        await functionsChild.stop().catch(() => undefined);
-                        functionsChild = null;
-                    }
-                };
-                let reloadDebounce = null;
-                httpServer.once('close', () => {
-                    disposed = true;
-                    if (reloadDebounce)
-                        clearTimeout(reloadDebounce);
-                    void functionsChild?.stop().catch(() => undefined);
-                });
-                if (httpServer.listening)
-                    void start();
-                else
-                    httpServer.once('listening', () => void start());
-                // Functions hot-reload from Vite's OWN watcher (mirrors the rules block
-                // below). Restart = redeploy: stop the old child, respawn via the same
-                // start path — there is no in-place swap, so in-flight executions in the
-                // old child may drop and writes landing in the swap gap become the new
-                // child's baseline (execution.ts consumes each trigger's first observed
-                // value as baseline; they do not fire). Debounced 300ms — a save fans
-                // out several fs events and a child respawn is far heavier than a rules
-                // re-parse. Restarts are serialized: a save landing mid-restart queues
-                // exactly one follow-up run.
-                if (functionsOpts.watch !== false) {
-                    const sourceDir = project.sourceDir;
-                    // Usually redundant (Vite watches its root, which contains the
-                    // functions dir in the common layout) but load-bearing when the
-                    // functions source lives outside Vite's root. node_modules stays
-                    // ignored: Vite's watcher ignores `**/node_modules/**` globally, and
-                    // the handler below filters it again for explicitly-added trees.
-                    server.watcher.add(sourceDir);
-                    let restarting = false;
-                    let queued = false;
-                    const restart = async () => {
-                        if (restarting) {
-                            queued = true;
-                            return;
-                        }
-                        restarting = true;
-                        try {
-                            do {
-                                queued = false;
-                                if (disposed)
-                                    return;
-                                const old = functionsChild;
-                                functionsChild = null;
-                                if (old)
-                                    await old.stop().catch(() => undefined);
-                                await start('reload');
-                            } while (queued && !disposed);
-                        }
-                        finally {
-                            restarting = false;
-                        }
-                    };
-                    const onFunctionsFsEvent = (file) => {
-                        const resolved = path.resolve(file);
-                        const rel = path.relative(sourceDir, resolved);
-                        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
-                            return;
-                        if (rel.split(path.sep).includes('node_modules'))
-                            return;
-                        if (reloadDebounce)
-                            clearTimeout(reloadDebounce);
-                        reloadDebounce = setTimeout(() => void restart(), 300);
-                    };
-                    server.watcher.on('change', onFunctionsFsEvent);
-                    server.watcher.on('add', onFunctionsFsEvent);
-                    server.watcher.on('unlink', onFunctionsFsEvent);
-                }
-            }
-            // Rules hot-reload from Vite's OWN watcher (no second fs watcher). Reuse
-            // prepareRulesSource (resolve + lint); last-good stays live on a broken save.
-            // Debounced (editors emit several change events per save) — matches
-            // watchProjectRules' 150ms cadence, which we can't reuse here (it opens its
-            // own fs watcher).
-            if (loaded.sourcePath) {
-                const rulesFile = loaded.sourcePath;
-                let debounce = null;
-                server.watcher.add(rulesFile);
-                server.watcher.on('change', (file) => {
-                    if (path.resolve(file) !== path.resolve(rulesFile))
-                        return;
-                    if (debounce)
-                        clearTimeout(debounce);
-                    debounce = setTimeout(() => {
-                        void readFile(rulesFile, 'utf8').then((raw) => {
-                            try {
-                                const rules = prepareRulesSource(raw, rulesFile);
-                                live.rules = rules;
-                                live.rulesHash = rulesHashOf(rules);
-                                events.broadcast('rules-changed', { rules, rulesHash: live.rulesHash });
-                                server.config.logger.info(`  ↻ [pyric] rules reloaded (${live.rulesHash})`);
-                            }
-                            catch (e) {
-                                server.config.logger.warn(`  ⚠ [pyric] rules NOT reloaded (last-good stays live): ${e instanceof Error ? e.message : String(e)}`);
-                            }
-                        }, () => { });
-                    }, 150);
-                });
-            }
+            const generationInput = {
+                server,
+                projectDir,
+                cliRoot,
+                workerRuntime,
+                options: generationOptions,
+                ai,
+            };
+            const generation = await createViteSandboxGeneration(generationInput);
+            activeGeneration = generation;
+        },
+        async closeBundle() {
+            const generation = activeGeneration;
+            activeGeneration = null;
+            await generation?.close();
         },
         // Sandbox build only: emit the serve init entry as its own chunk. Emitted in
         // buildStart (module graph time); its final filename is resolved in
@@ -845,70 +100,13 @@ export function pyric(options = {}) {
         // BEFORE Vite's build-html plugin applies transformIndexHtml — the filename
         // is always available when the script tag is injected below.
         buildStart() {
-            if (sandboxBuild) {
-                initChunkRef = this.emitFile({
-                    type: 'chunk',
-                    id: entries.init,
-                    name: 'pyric-sandbox-init',
-                });
-            }
+            pageRuntime.buildStart((chunk) => this.emitFile(chunk));
         },
         generateBundle() {
-            if (initChunkRef)
-                initChunkFile = this.getFileName(initChunkRef);
+            pageRuntime.generateBundle((referenceId) => this.getFileName(referenceId));
         },
         transformIndexHtml(html) {
-            const runtimeChipTag = `<meta name="${PYRIC_RUNTIME_CHIP_META}" content="${runtimeChipMetaValue(options.runtimeChip)}" data-studio="${options.ui === false ? 'off' : 'on'}" data-pyric-sandbox>`;
-            // Sandbox BUILD: the app's own `firebase/*` imports were already swapped
-            // (resolveId, above) to pyric's in-page adapters and BUNDLED into the app
-            // chunk, and the emitted init chunk (script-tagged here) carries the
-            // runtime bootstrap + the ServeAuthHelper popup picker — rollup shares
-            // ONE runtime module between the two, so the output is fully
-            // self-contained. `pyric dev` sees the marker below and skips its own
-            // serve-time injection for this page (a second injected runtime would
-            // double-init: two banners, two bridge peers). The marker is also the
-            // signal that makes `pyric dev` trust this dist (skip the inlined-SDK
-            // scan). transformIndexHtml runs BEFORE Vite writes index.html, so both
-            // land in the emitted asset.
-            if (sandboxBuild) {
-                if (html.includes(SANDBOX_BUILD_META))
-                    return html;
-                const initTag = initChunkFile
-                    ? `<script type="module" crossorigin src="/${initChunkFile}" data-pyric-sandbox-init></script>`
-                    : '';
-                const tags = SANDBOX_BUILD_META + runtimeChipTag + initTag;
-                return html.includes('</head>')
-                    ? html.replace('</head>', `${tags}</head>`)
-                    : tags + html;
-            }
-            const MARKER = 'data-pyric-sandbox';
-            if (html.includes(MARKER))
-                return html;
-            // Worker path (default): stamp the served worker's content hash so the page
-            // can WARN when a still-running OLD worker is stale (a SharedWorker can't
-            // hot-update). In-page path: force it via the explicit flag before the init
-            // module evaluates — a classic inline script runs before the deferred module.
-            // The flag (not nulling `window.SharedWorker`) leaves the user's own
-            // SharedWorker usage intact. We force in-page ONLY when the worker bundle
-            // failed (worker runtime unready) — the ephemeral fallback. `bridge` no longer
-            // forces in-page: the bridge peer routes agent tool-calls THROUGH the
-            // worker (see `connectBridgePeer`), so the agent shares the one sandbox the
-            // app + Studio use.
-            const head = workerRuntime.headTag(MARKER);
-            // Plugin-level engine for the IN-PAGE path: a classic inline script runs
-            // before the deferred init module AND before app code's `getAI`, so the
-            // served `getAI` (entries/ai.ts) reads it synchronously — init.json can't
-            // be awaited there. Harmless on the worker path (that branch ignores the
-            // global; the worker reads ctx.aiEngine from init.json). `<` is escaped so
-            // an engine value can never break out of the script tag.
-            const aiEngineTag = resolvedAi.engineWire
-                ? `<script ${MARKER}>globalThis.__PYRIC_AI_ENGINE__=${JSON.stringify(resolvedAi.engineWire).replace(/</g, '\\u003c')};</script>`
-                : '';
-            // Boot the sandbox by loading the real init entry as a module (Vite
-            // serves + transforms it). The init module's top-level await deploys rules
-            // before app code runs. Mirrors serve's injectServeTags.
-            const tag = head + aiEngineTag + runtimeChipTag + `<script type="module" src="/@fs/${entries.init}" ${MARKER}></script>`;
-            return html.includes('</head>') ? html.replace('</head>', `${tag}</head>`) : tag + html;
+            return pageRuntime.transformIndexHtml(html);
         },
     };
 }