@pix3/vite-plugin 0.0.0-stage → 2.0.0-alpha.0

package/dist/sync/barrier.js

@@ -0,0 +1,240 @@
+import { parseWirePath } from "../files/paths.js";
+import { HttpError, isRecord } from "../server/http.js";
+import { isGlobbedScript } from "./script-graph.js";
+/**
+ * The sync barrier (plan §B.3), as S1 found it works:
+ *
+ * 0. **flush** — the editor writes its dirty scenes. The page's `pix3_sync` flushes itself before
+ *    calling `POST /sync`; a caller without a tab (the CLI), or a tab that is not the writer (a
+ *    read-only second tab's `pix3_sync`), gets the flush done here, through the writer tab
+ *    (`POST /flush` is the same step on its own);
+ * 1. **rescan** — stat + sha256 of the revision set, changes broadcast as `pix3:fs`;
+ * 2. **hard-invalidate the roots**, so their `load()` runs again with the new revision;
+ * 3. **propagate** every changed file through the client graph (`environment.reloadModule`), and
+ *    the roots themselves when a globbed script was added or removed;
+ * 4. **page confirmation** — the tab re-imports the roots with `?t=<13 digits>` and answers with the
+ *    revision it executed and `globalThis.__pix3Executed`. Sync is ok only when that revision is
+ *    current AND every changed module the editor runs carries a stamp equal to the sha on disk.
+ *    A page behind on either is asked again (roots re-invalidated, bounded: {@link
+ *    MAX_CONFIRM_ATTEMPTS}, within `timeoutMs`); still behind → `{ok:false, reason:'stale_modules',
+ *    paths, ackRev}`.
+ *
+ * A non-ok answer is not a barrier: on `gesture_in_progress` and `stale_modules` the agent
+ * retries; on `expect_mismatch` it re-reads; on `stale` (play is running) it follows `playing`.
+ */
+export const DEFAULT_SYNC_TIMEOUT_MS = 10_000;
+export const VITE_CLIENT_WARNING = "/@vite/client is loaded on the editor page, so the game's full-reload can reload the editor: " +
+    'a script, a bot policy or a module they import uses import.meta.hot, a CSS import or a ' +
+    'non-literal import(). `pix3 check` names the file (W_EDITOR_*).';
+const MAX_SYNC_TIMEOUT_MS = 120_000;
+/**
+ * Step 4 asks the tab again when its answer is behind (`rev` older than the rescan's, or a changed
+ * module's stamp not the disk's): at most this many times, after 50, 100, 200 ms, and never past
+ * the caller's `timeoutMs`. A page that still runs old code after that is reported `stale_modules`
+ * — a module that genuinely failed to re-execute costs ~350 ms more, never a hang.
+ */
+const MAX_CONFIRM_ATTEMPTS = 4;
+const CONFIRM_RETRY_MS = 50;
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+export const parseTimeout = (raw, fallback) => {
+    if (raw === undefined)
+        return fallback;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
+        throw new HttpError(400, 'bad_request', '`timeoutMs` must be a non-negative number.');
+    }
+    return Math.min(raw, MAX_SYNC_TIMEOUT_MS);
+};
+export const parseSyncRequest = (body) => {
+    let expect;
+    if (body.expect !== undefined) {
+        if (!isRecord(body.expect)) {
+            throw new HttpError(400, 'bad_request', '`expect` must be an object {path: sha256}.');
+        }
+        expect = {};
+        for (const [key, value] of Object.entries(body.expect)) {
+            const wirePath = parseWirePath(key, 'expect');
+            if (typeof value !== 'string' || !SHA256_HEX.test(value.toLowerCase())) {
+                throw new HttpError(400, 'bad_request', `expect["${key}"] must be a hex sha256.`);
+            }
+            expect[wirePath] = value.toLowerCase();
+        }
+    }
+    const tabId = typeof body.tabId === 'string' ? body.tabId : null;
+    return { expect, timeoutMs: parseTimeout(body.timeoutMs, DEFAULT_SYNC_TIMEOUT_MS), tabId };
+};
+export class SyncBarrier {
+    deps;
+    /** sha already propagated by a sync, per wire path: the watcher's late echo is suppressed. */
+    propagated = new Map();
+    /** One barrier at a time; a second sync waits for the first. */
+    tail = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The tab that answers for the editor: the asker, else the writer, else the oldest tab. */
+    targetTab(asker) {
+        const { socket, files } = this.deps;
+        if (asker && socket.hasTab(asker))
+            return asker;
+        const writer = files.writerId;
+        if (writer && socket.hasTab(writer))
+            return writer;
+        return socket.tabs()[0]?.tabId ?? null;
+    }
+    /**
+     * Step 0 on its own (`POST /__pix3/api/flush`, and `npm run build` / `pix3 check` before they
+     * read the disk): the writer tab writes its dirty scenes. No writer tab = nothing unsaved here.
+     */
+    async flush(timeoutMs) {
+        const { socket, files } = this.deps;
+        const writer = files.writerId;
+        if (!writer || !socket.hasTab(writer)) {
+            return { ok: true, editor: socket.tabs().length > 0, flushed: false };
+        }
+        const reply = await socket.request(writer, 'flush', { timeoutMs }, timeoutMs + 1_000);
+        return { ...reply, editor: true, flushed: reply.ok };
+    }
+    sync(request) {
+        const run = this.tail.then(() => this.run(request), () => this.run(request));
+        this.tail = run.catch(() => undefined);
+        return run;
+    }
+    async run(request) {
+        const { files, scripts, socket } = this.deps;
+        const started = Date.now();
+        // Step 0: the asking tab flushed itself before calling — but only the writer tab holds
+        // unsaved scenes. A caller without a tab, or a read-only tab asking, flushes the writer here.
+        if (request.tabId === null || request.tabId !== files.writerId) {
+            const flushed = await this.flush(request.timeoutMs);
+            if (!flushed.ok)
+                return { ...flushed, ok: false, step: 'flush' };
+        }
+        // 1. rescan
+        const { events, seq } = await files.rescanAll();
+        const changedFiles = events.filter(event => event.kind === 'file');
+        const changed = {};
+        for (const event of changedFiles) {
+            changed[event.path] = event.op === 'delete' ? null : (event.sha256 ?? null);
+            if (event.op === 'rename' && event.from)
+                changed[event.from] = null;
+        }
+        const expectMismatch = [];
+        for (const [path, expected] of Object.entries(request.expect ?? {})) {
+            const actual = files.hashOf(path);
+            if (actual !== expected)
+                expectMismatch.push({ path, expected, actual });
+        }
+        // 2–3. hard-invalidate the roots, propagate
+        scripts.hardInvalidateRoots();
+        let rootsNeedReload = false;
+        for (const event of changedFiles) {
+            if (event.op !== 'modify' &&
+                (isGlobbedScript(event.path) || isGlobbedScript(event.from ?? '')))
+                rootsNeedReload = true;
+            if (event.op === 'delete' || !event.sha256)
+                continue;
+            this.propagated.set(event.path, event.sha256);
+            await scripts.reload(event.path);
+        }
+        if (rootsNeedReload)
+            await scripts.reloadRoots();
+        const required = this.requiredStamps(changedFiles);
+        const base = {
+            rev: seq,
+            seq,
+            changed,
+            expectMismatch,
+            ...(expectMismatch.length > 0 ? { reason: 'expect_mismatch' } : {}),
+        };
+        // 4. page confirmation
+        const tabId = this.targetTab(request.tabId);
+        if (tabId === null) {
+            return { ok: expectMismatch.length === 0, ...base, editor: false, ms: Date.now() - started };
+        }
+        const deadline = started + request.timeoutMs;
+        // `policyOnly`: modules only bot policies import — applied during play like a policy (S11).
+        const ask = {
+            rev: seq,
+            changed,
+            paths: Object.keys(changed),
+            policyOnly: scripts.policyOnlyModules(),
+        };
+        let attempts = 0;
+        let reply;
+        let verdict;
+        for (;;) {
+            attempts += 1;
+            reply = await socket.request(tabId, 'sync', ask, Math.max(0, deadline - Date.now()));
+            verdict = this.judge(reply, seq, required);
+            // Only a page that answered and is behind is asked again; a refusal is the answer.
+            if (verdict.ok || !reply.ok || attempts >= MAX_CONFIRM_ATTEMPTS)
+                break;
+            const pause = CONFIRM_RETRY_MS * 2 ** (attempts - 1);
+            if (deadline - Date.now() <= pause)
+                break;
+            this.deps.log?.(`sync rev ${seq}: the tab answered rev ${String(verdict.ackRev)}, stale ` +
+                `[${String(verdict.paths)}]; asking again (attempt ${attempts + 1})`);
+            await sleep(pause);
+            scripts.hardInvalidateRoots();
+        }
+        return {
+            ...base,
+            ...verdict,
+            ok: verdict.ok && expectMismatch.length === 0,
+            ...(verdict.ok && expectMismatch.length > 0 ? { reason: 'expect_mismatch' } : {}),
+            editor: true,
+            tabId,
+            ...(attempts > 1 ? { attempts } : {}),
+            // Contract B broken: the page found /@vite/client loaded (plan §B.2).
+            ...(reply.viteClient === true ? { viteClient: true, warning: VITE_CLIENT_WARNING } : {}),
+            ms: Date.now() - started,
+        };
+    }
+    /** Changed files the editor executes, with the sha their stamp must carry. */
+    requiredStamps(events) {
+        const required = new Map();
+        for (const event of events) {
+            if (event.op === 'delete' || !event.sha256)
+                continue;
+            if (this.deps.scripts.isEditorModule(event.path))
+                required.set(event.path, event.sha256);
+        }
+        return required;
+    }
+    judge(reply, rev, required) {
+        if (!reply.ok) {
+            // `executed` is every stamp on the page (hundreds of modules): proof for the judge, noise
+            // in an answer the agent reads.
+            const { ok: _ok, executed: _executed, ...rest } = reply;
+            return {
+                ok: false,
+                reason: typeof reply.reason === 'string' ? reply.reason : 'refused',
+                ...rest,
+            };
+        }
+        const executed = isRecord(reply.executed) ? reply.executed : {};
+        const ackRev = typeof reply.rev === 'number' ? reply.rev : -1;
+        const stale = [];
+        for (const [path, sha] of required)
+            if (executed[path] !== sha)
+                stale.push(path);
+        if (ackRev < rev || stale.length > 0) {
+            return { ok: false, reason: 'stale_modules', paths: stale, ackRev };
+        }
+        return { ok: true };
+    }
+    /**
+     * `handleHotUpdate` for a file a sync already propagated with the same bytes: the watcher's
+     * late echo would otherwise propagate a second time (S1: chokidar repeats `change`).
+     */
+    alreadyPropagated(wirePath, sha) {
+        return sha !== null && this.propagated.get(wirePath) === sha;
+    }
+    notePropagated(wirePath, sha) {
+        if (sha === null)
+            this.propagated.delete(wirePath);
+        else
+            this.propagated.set(wirePath, sha);
+    }
+}

package/dist/sync/hot-update.d.ts

@@ -0,0 +1,16 @@
+import type { DevEnvironment, EnvironmentModuleNode, HotUpdateOptions } from 'vite';
+import type { EditorServer } from '../dev-server.ts';
+import { type ScriptGraph } from './script-graph.ts';
+/**
+ * The plugin's `hotUpdate` — not the legacy `handleHotUpdate`: Vite (6+, the environment API)
+ * calls the legacy hook for `update` only, so a script file created or deleted outside a sync
+ * never reached the editor — its roots kept the old glob until the next sync, and a play restart
+ * ran without the new class (`.plans/scripts-vite.md` S13). This hook sees every kind.
+ *
+ * `undefined` leaves Vite's default propagation alone; `[]` means this hook did it.
+ */
+export declare const scriptHotUpdate: (update: Pick<HotUpdateOptions, "type" | "file" | "modules">, environment: Pick<DevEnvironment, "name" | "moduleGraph">, context: {
+    readonly root: string;
+    readonly scripts: ScriptGraph;
+    readonly editor: EditorServer;
+}) => Promise<EnvironmentModuleNode[] | undefined>;

package/dist/sync/hot-update.js

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCENE_MANIFEST_ID } from "../build/player-modules.js";
+import { isGlobbedScript, resolvedId, sha256Hex } from "./script-graph.js";
+/**
+ * The plugin's `hotUpdate` — not the legacy `handleHotUpdate`: Vite (6+, the environment API)
+ * calls the legacy hook for `update` only, so a script file created or deleted outside a sync
+ * never reached the editor — its roots kept the old glob until the next sync, and a play restart
+ * ran without the new class (`.plans/scripts-vite.md` S13). This hook sees every kind.
+ *
+ * `undefined` leaves Vite's default propagation alone; `[]` means this hook did it.
+ */
+export const scriptHotUpdate = async (update, environment, context) => {
+    const { type, file, modules } = update;
+    const { scripts, editor } = context;
+    // The player's scene manifest follows `pix3project.yaml` (entry scene, viewport, quality).
+    if (file === join(context.root, 'pix3project.yaml')) {
+        const manifest = environment.moduleGraph.getModuleById(resolvedId(SCENE_MANIFEST_ID));
+        if (!manifest)
+            return undefined;
+        environment.moduleGraph.invalidateModule(manifest);
+        return [...modules, manifest];
+    }
+    const wirePath = scripts.wirePathOf(file);
+    if (wirePath === null)
+        return undefined;
+    const globbed = isGlobbedScript(wirePath);
+    // A deleted helper has nothing to propagate (its importers fail on their next import, and
+    // a sync reports that); a created one is not in the graph yet and Vite's default retries
+    // the importers that failed to resolve it.
+    if (!globbed && (type !== 'update' || !scripts.isEditorModule(wirePath)))
+        return undefined;
+    // The work is done once, on the client graph (the editor's and the game tab's environment);
+    // every environment returns [] so Vite does not propagate a second time.
+    if (environment.name !== 'client')
+        return [];
+    let sha;
+    try {
+        sha = sha256Hex(readFileSync(file));
+    }
+    catch {
+        sha = null;
+    }
+    // A sync already propagated these bytes; the watcher's late echo must not do it twice.
+    if (editor.barrier.alreadyPropagated(wirePath, sha))
+        return [];
+    editor.barrier.notePropagated(wirePath, sha);
+    // Propagate through the client environment's own nodes (never Vite 8's backward-compatible
+    // mixed nodes — S1, finding 5): a changed file through its importers, an added or deleted
+    // globbed script by re-running the roots' globs. Then tell the editor to re-import its roots.
+    scripts.hardInvalidateRoots();
+    if (type === 'update')
+        await scripts.reload(wirePath);
+    if (globbed && type !== 'update')
+        await scripts.reloadRoots();
+    editor.socket.broadcast({ type: 'pix3:scripts', path: wirePath, op: type });
+    return [];
+};

package/dist/sync/script-graph.d.ts

@@ -0,0 +1,79 @@
+import { type EnvironmentModuleNode, type ViteDevServer } from 'vite';
+/**
+ * The scripts the editor executes, and the proof that it executed the bytes on disk (plan §B.2).
+ *
+ * - `virtual:pix3/editor-scripts` — eager `import.meta.glob` over `scripts/` and `src/scripts/`
+ *   (no specs, tests or declarations), exporting `__pix3Revision`;
+ * - `virtual:pix3/bot-policies` — the same over `design/tests/bots/`;
+ * - every project source module the client environment transforms gets an **executed-content
+ *   stamp**, `(globalThis.__pix3Executed ??= {})[path] = sha`, which runs only when that module
+ *   body runs. S1 showed the root's own hashes prove nothing about nested modules; the stamp does.
+ */
+export declare const EDITOR_SCRIPTS_ID = "virtual:pix3/editor-scripts";
+export declare const BOT_POLICIES_ID = "virtual:pix3/bot-policies";
+export declare const ROOT_IDS: readonly ["virtual:pix3/editor-scripts", "virtual:pix3/bot-policies"];
+export declare const resolvedId: (id: string) => string;
+/**
+ * The project-script rule, mirrored from the runtime's `project-script-registration.ts`
+ * (`PROJECT_SCRIPT_DIRECTORIES`, `projectScriptGlobPatterns`, `isProjectScriptEntry`): the
+ * plugin runs in Node and cannot import the runtime's TypeScript sources, so `script-rule.spec.ts`
+ * pins these to the runtime's. A `.ts` under `scripts/` or `src/scripts/` (no specs, tests or
+ * declarations) is an entry — no `.js`, no textual gate.
+ */
+export declare const SCRIPT_DIRS: readonly ["scripts", "src/scripts"];
+export declare const BOT_POLICY_DIRS: readonly ["design/tests/bots"];
+/** The glob patterns of a root over `dirs` (= the runtime's `projectScriptGlobPatterns`). */
+export declare const globPatterns: (dirs: readonly string[]) => string[];
+/** Source of a glob root; `revision` is the file table's `seq` when Vite loads it. */
+export declare const rootModuleSource: (id: string, revision: number) => string;
+/** True for a wire path the editor-scripts or bot-policies glob picks up. */
+export declare const isGlobbedScript: (wirePath: string) => boolean;
+export declare const sha256Hex: (bytes: Uint8Array | string) => string;
+export declare class ScriptGraph {
+    private readonly root;
+    private readonly server;
+    /** Absolute directories inside the root that hold no project sources (Vite's `cacheDir`). */
+    private readonly ignored;
+    constructor(root: string, server: () => ViteDevServer | null, ignored?: readonly string[]);
+    /** Module id (absolute path, maybe with a query) → wire path, when it is a project source. */
+    wirePathOf(id: string): string | null;
+    absoluteOf(wirePath: string): string;
+    /**
+     * `transform` hook body: append the executed-content stamp to a project source module. The sha
+     * is of the file on disk (what the barrier compares with), not of `code`.
+     */
+    stamp(code: string, id: string): string | null;
+    private graph;
+    rootModules(): EnvironmentModuleNode[];
+    /**
+     * Vite ≥ 5.1 SOFT-invalidates static importers of a changed module: the cached transform is
+     * reused with re-stamped `?t=` and `load()` does not run again, so `__pix3Revision` would stay
+     * stale (S1, finding 1). The roots are hard-invalidated explicitly.
+     *
+     * Twice: as an HMR invalidation (`lastHMRTimestamp`, what the propagation stamps) and as a plain
+     * one, because only `lastInvalidationTimestamp` is what Vite checks a transform against. With
+     * the HMR call alone, a root request already in flight — the tab re-importing after a watcher
+     * `pix3:scripts`, its `load()` done at the old `seq` — is handed to the next request for the same
+     * URL (`transformRequest` dedupes on the URL without `?t=`), and its result is even cached after
+     * the invalidation. The sync's own re-import then executed the previous `__pix3Revision`
+     * (`.plans/scripts-vite.md` S15). Vite's own clock is used, so the invalidation is strictly later
+     * than every request that started before it.
+     */
+    hardInvalidateRoots(): void;
+    /** Client-environment nodes of a file (never Vite 8's mixed nodes — S1, finding 5). */
+    modulesOf(wirePath: string): EnvironmentModuleNode[];
+    /** True when the editor executes `wirePath`: globbed, or imported (transitively) by a root. */
+    isEditorModule(wirePath: string): boolean;
+    /**
+     * Project modules only the bot policies reach (`.plans/scripts-vite.md` S4/S11): reachable from
+     * `virtual:pix3/bot-policies` and not from `virtual:pix3/editor-scripts`, so the game the editor
+     * plays never runs them and a change to one need not wait for play to stop. Read from the client
+     * graph as it is now (after the barrier's propagation); a module the graph has not seen is not
+     * listed, which errs on the side of holding play.
+     */
+    policyOnlyModules(): string[];
+    /** HMR-propagate one file through the client graph (stamps `lastHMRTimestamp` up the chain). */
+    reload(wirePath: string): Promise<number>;
+    /** Re-run the roots' globs (a script was added or removed). */
+    reloadRoots(): Promise<void>;
+}

package/dist/sync/script-graph.js

@@ -0,0 +1,214 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, sep } from 'node:path';
+import { normalizePath } from 'vite';
+import { isExcludedPath } from "../files/scan.js";
+import { relativeInside } from "../module-paths.js";
+/**
+ * The scripts the editor executes, and the proof that it executed the bytes on disk (plan §B.2).
+ *
+ * - `virtual:pix3/editor-scripts` — eager `import.meta.glob` over `scripts/` and `src/scripts/`
+ *   (no specs, tests or declarations), exporting `__pix3Revision`;
+ * - `virtual:pix3/bot-policies` — the same over `design/tests/bots/`;
+ * - every project source module the client environment transforms gets an **executed-content
+ *   stamp**, `(globalThis.__pix3Executed ??= {})[path] = sha`, which runs only when that module
+ *   body runs. S1 showed the root's own hashes prove nothing about nested modules; the stamp does.
+ */
+export const EDITOR_SCRIPTS_ID = 'virtual:pix3/editor-scripts';
+export const BOT_POLICIES_ID = 'virtual:pix3/bot-policies';
+export const ROOT_IDS = [EDITOR_SCRIPTS_ID, BOT_POLICIES_ID];
+export const resolvedId = (id) => `\0${id}`;
+/**
+ * The project-script rule, mirrored from the runtime's `project-script-registration.ts`
+ * (`PROJECT_SCRIPT_DIRECTORIES`, `projectScriptGlobPatterns`, `isProjectScriptEntry`): the
+ * plugin runs in Node and cannot import the runtime's TypeScript sources, so `script-rule.spec.ts`
+ * pins these to the runtime's. A `.ts` under `scripts/` or `src/scripts/` (no specs, tests or
+ * declarations) is an entry — no `.js`, no textual gate.
+ */
+export const SCRIPT_DIRS = ['scripts', 'src/scripts'];
+export const BOT_POLICY_DIRS = ['design/tests/bots'];
+const SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?)$/;
+const NOT_A_SCRIPT = /\.(?:spec|test)\.ts$|\.d\.ts$/;
+/** The glob patterns of a root over `dirs` (= the runtime's `projectScriptGlobPatterns`). */
+export const globPatterns = (dirs) => dirs.flatMap(dir => [
+    `/${dir}/**/*.ts`,
+    `!/${dir}/**/*.spec.ts`,
+    `!/${dir}/**/*.test.ts`,
+    `!/${dir}/**/*.d.ts`,
+]);
+/** Source of a glob root; `revision` is the file table's `seq` when Vite loads it. */
+export const rootModuleSource = (id, revision) => {
+    const dirs = id === BOT_POLICIES_ID ? BOT_POLICY_DIRS : SCRIPT_DIRS;
+    return [
+        `export const __pix3Revision = ${revision};`,
+        `export const modules = import.meta.glob(${JSON.stringify(globPatterns(dirs))}, { eager: true });`,
+        '',
+    ].join('\n');
+};
+/** True for a wire path the editor-scripts or bot-policies glob picks up. */
+export const isGlobbedScript = (wirePath) => wirePath.endsWith('.ts') &&
+    !NOT_A_SCRIPT.test(wirePath) &&
+    [...SCRIPT_DIRS, ...BOT_POLICY_DIRS].some(dir => wirePath.startsWith(`${dir}/`));
+export const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export class ScriptGraph {
+    root;
+    server;
+    /** Absolute directories inside the root that hold no project sources (Vite's `cacheDir`). */
+    ignored;
+    constructor(root, server, ignored = []) {
+        this.root = root;
+        this.server = server;
+        this.ignored = ignored.map(dir => normalizePath(dir).replace(/\/+$/, ''));
+    }
+    /** Module id (absolute path, maybe with a query) → wire path, when it is a project source. */
+    wirePathOf(id) {
+        const file = id.split('?')[0];
+        if (!isAbsolute(file) || !SOURCE_EXTENSION.test(file))
+            return null;
+        // A pre-bundled dependency in an in-project `cacheDir` is not the project's code.
+        if (this.ignored.some(dir => normalizePath(file).startsWith(`${dir}/`)))
+            return null;
+        const wirePath = relativeInside(this.root, file);
+        return wirePath === null || isExcludedPath(wirePath) ? null : wirePath;
+    }
+    absoluteOf(wirePath) {
+        return `${this.root}${sep}${wirePath.split('/').join(sep)}`;
+    }
+    /**
+     * `transform` hook body: append the executed-content stamp to a project source module. The sha
+     * is of the file on disk (what the barrier compares with), not of `code`.
+     */
+    stamp(code, id) {
+        const wirePath = this.wirePathOf(id);
+        if (wirePath === null)
+            return null;
+        let sha;
+        try {
+            sha = sha256Hex(readFileSync(id.split('?')[0]));
+        }
+        catch {
+            return null;
+        }
+        return (`${code}\n;(globalThis.__pix3Executed ??= {})[${JSON.stringify(wirePath)}] = ` +
+            `${JSON.stringify(sha)};\n`);
+    }
+    graph() {
+        return this.server()?.environments.client ?? null;
+    }
+    rootModules() {
+        const env = this.graph();
+        if (!env)
+            return [];
+        const out = [];
+        for (const id of ROOT_IDS) {
+            const mod = env.moduleGraph.getModuleById(resolvedId(id));
+            if (mod)
+                out.push(mod);
+        }
+        return out;
+    }
+    /**
+     * Vite ≥ 5.1 SOFT-invalidates static importers of a changed module: the cached transform is
+     * reused with re-stamped `?t=` and `load()` does not run again, so `__pix3Revision` would stay
+     * stale (S1, finding 1). The roots are hard-invalidated explicitly.
+     *
+     * Twice: as an HMR invalidation (`lastHMRTimestamp`, what the propagation stamps) and as a plain
+     * one, because only `lastInvalidationTimestamp` is what Vite checks a transform against. With
+     * the HMR call alone, a root request already in flight — the tab re-importing after a watcher
+     * `pix3:scripts`, its `load()` done at the old `seq` — is handed to the next request for the same
+     * URL (`transformRequest` dedupes on the URL without `?t=`), and its result is even cached after
+     * the invalidation. The sync's own re-import then executed the previous `__pix3Revision`
+     * (`.plans/scripts-vite.md` S15). Vite's own clock is used, so the invalidation is strictly later
+     * than every request that started before it.
+     */
+    hardInvalidateRoots() {
+        const env = this.graph();
+        if (!env)
+            return;
+        for (const mod of this.rootModules()) {
+            env.moduleGraph.invalidateModule(mod, new Set(), Date.now(), true, false);
+            env.moduleGraph.invalidateModule(mod, new Set(), undefined, false, false);
+        }
+    }
+    /** Client-environment nodes of a file (never Vite 8's mixed nodes — S1, finding 5). */
+    modulesOf(wirePath) {
+        const env = this.graph();
+        if (!env)
+            return [];
+        return [...(env.moduleGraph.getModulesByFile(normalizePath(this.absoluteOf(wirePath))) ?? [])];
+    }
+    /** True when the editor executes `wirePath`: globbed, or imported (transitively) by a root. */
+    isEditorModule(wirePath) {
+        if (isGlobbedScript(wirePath))
+            return true;
+        const roots = new Set(ROOT_IDS.map(resolvedId));
+        const seen = new Set();
+        const queue = this.modulesOf(wirePath);
+        while (queue.length > 0) {
+            const mod = queue.shift();
+            if (seen.has(mod))
+                continue;
+            seen.add(mod);
+            if (mod.id && roots.has(mod.id))
+                return true;
+            for (const importer of mod.importers)
+                queue.push(importer);
+        }
+        return false;
+    }
+    /**
+     * Project modules only the bot policies reach (`.plans/scripts-vite.md` S4/S11): reachable from
+     * `virtual:pix3/bot-policies` and not from `virtual:pix3/editor-scripts`, so the game the editor
+     * plays never runs them and a change to one need not wait for play to stop. Read from the client
+     * graph as it is now (after the barrier's propagation); a module the graph has not seen is not
+     * listed, which errs on the side of holding play.
+     */
+    policyOnlyModules() {
+        const env = this.graph();
+        if (!env)
+            return [];
+        const reach = (rootId) => {
+            const out = new Set();
+            const root = env.moduleGraph.getModuleById(resolvedId(rootId));
+            if (!root)
+                return out;
+            const seen = new Set([root]);
+            const queue = [...root.importedModules];
+            while (queue.length > 0) {
+                const mod = queue.shift();
+                if (seen.has(mod))
+                    continue;
+                seen.add(mod);
+                const wirePath = mod.file ? this.wirePathOf(mod.file) : null;
+                if (wirePath !== null)
+                    out.add(wirePath);
+                for (const imported of mod.importedModules)
+                    queue.push(imported);
+            }
+            return out;
+        };
+        // No editor root in the graph yet: nothing can be proven policy-only.
+        if (!env.moduleGraph.getModuleById(resolvedId(EDITOR_SCRIPTS_ID)))
+            return [];
+        const game = reach(EDITOR_SCRIPTS_ID);
+        return [...reach(BOT_POLICIES_ID)].filter(path => !game.has(path)).sort();
+    }
+    /** HMR-propagate one file through the client graph (stamps `lastHMRTimestamp` up the chain). */
+    async reload(wirePath) {
+        const env = this.graph();
+        if (!env)
+            return 0;
+        const mods = this.modulesOf(wirePath);
+        for (const mod of mods)
+            await env.reloadModule(mod);
+        return mods.length;
+    }
+    /** Re-run the roots' globs (a script was added or removed). */
+    async reloadRoots() {
+        const env = this.graph();
+        if (!env)
+            return;
+        for (const mod of this.rootModules())
+            await env.reloadModule(mod);
+    }
+}

package/dist/vite-config.d.ts

@@ -0,0 +1,12 @@
+import { type UserConfig } from 'vite';
+/** The plugin's `config` hook: what it adds to the user's Vite config. */
+export declare const pix3ViteConfig: (options: {
+    readonly user: UserConfig;
+    /** This package's directory (the page client and the player are served from it). */
+    readonly packageDir: string;
+    /** The playable build this command makes, or false (dev, `build: false`). */
+    readonly format: "html" | "zip" | false;
+    readonly compress: boolean;
+    /** Vite 8 bundles with rolldown (`this.meta.rolldownVersion`), Vite 7 with rollup. */
+    readonly rolldown: boolean;
+}) => UserConfig;