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

package/dist/server/router.js

@@ -0,0 +1,147 @@
+import { DEFAULT_SYNC_TIMEOUT_MS, parseSyncRequest, parseTimeout, } from "../sync/barrier.js";
+import { editorSessionFor } from "./guard.js";
+import { errorBody, HttpError, readJson, sendJson } from "./http.js";
+export const createRouter = (deps) => {
+    const prefix = `${deps.base}__pix3`;
+    const apiPrefix = `${prefix}/api/`;
+    /** A handler whose answer is `200` + JSON. */
+    const json = (answer) => async (req, res, url) => sendJson(res, 200, await answer(req, url));
+    const { files } = deps;
+    const readFile = (req, res, url, head) => files.readFile(req, res, url, head);
+    const historyVersion = (_req, res, url, head) => files.historyVersion(res, url, head);
+    const jsonMutation = (op) => async (req, res) => files.jsonMutation(req, res, op, await readJson(req));
+    /** `api path → method → handler`; an unknown pair is a 404. */
+    const apiRoutes = {
+        hello: { GET: json(async () => deps.hello()) },
+        file: { GET: readFile, HEAD: readFile, PUT: (req, res, url) => files.writeFile(req, res, url) },
+        manifest: { GET: json(() => files.manifest()) },
+        hash: { POST: json(async (req) => files.hashPaths(await readJson(req))) },
+        mkdir: { POST: jsonMutation('mkdir') },
+        delete: { POST: jsonMutation('delete') },
+        move: { POST: jsonMutation('move') },
+        changeset: { POST: (req, res) => files.writeChangeset(req, res) },
+        history: { GET: json((_req, url) => files.historyList(url)) },
+        'history/version': { GET: historyVersion, HEAD: historyVersion },
+        'history/record': {
+            POST: json(async (req) => ({ ...(await files.historyRecord(await readJson(req))) })),
+        },
+        'history/restore': { POST: (req, res) => files.historyRestore(req, res) },
+        'handover/claim': {
+            POST: json(async (req) => {
+                const claimed = await files.claim((await readJson(req)).writerId);
+                deps.socket.broadcast({ type: 'pix3:writer', writerId: claimed.writerId });
+                return claimed;
+            }),
+        },
+        sync: { POST: json(async (req) => deps.barrier.sync(parseSyncRequest(await readJson(req)))) },
+        flush: {
+            POST: json(async (req) => deps.barrier.flush(parseTimeout((await readJson(req)).timeoutMs, DEFAULT_SYNC_TIMEOUT_MS))),
+        },
+    };
+    const route = async (req, res, url) => {
+        const method = req.method ?? 'GET';
+        const path = url.pathname;
+        deps.guard.checkPeer(req);
+        if (method !== 'GET' && method !== 'HEAD')
+            deps.guard.checkMutation(req);
+        if (path === prefix) {
+            res.writeHead(302, { Location: `${prefix}/${url.search}` });
+            res.end();
+            return;
+        }
+        if (path === `${prefix}/` || path === `${prefix}/index.html`) {
+            if (method !== 'GET' && method !== 'HEAD')
+                throw new HttpError(405, 'method', 'GET only.');
+            const page = deps.editorPage(editorSessionFor(req, deps.sessionToken));
+            res.writeHead(page.status, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-store',
+                // A window the game opens on the editor gets no handle into it (the session token, the
+                // host object): another page's popup with a different policy lands in its own group.
+                // `-allow-popups` keeps the editor's own game pop-out scriptable.
+                'Cross-Origin-Opener-Policy': 'same-origin-allow-popups',
+            });
+            res.end(method === 'HEAD' ? undefined : page.html);
+            return;
+        }
+        if (path === `${prefix}/editor.css` && (method === 'GET' || method === 'HEAD')) {
+            // Served statically, past the project's PostCSS (plan §B.0): no CSS import may reach the
+            // editor chain (contract B).
+            const css = deps.editorCss();
+            if (!css)
+                throw new HttpError(404, 'not_found', '@pix3/editor-core is not installed.');
+            res.writeHead(200, {
+                'Content-Type': 'text/css; charset=utf-8',
+                'Cache-Control': 'no-cache',
+            });
+            res.end(method === 'HEAD' ? undefined : css);
+            return;
+        }
+        if (!path.startsWith(apiPrefix))
+            throw new HttpError(404, 'not_found', 'Not found.');
+        const api = path.slice(apiPrefix.length);
+        if (api === 'keys' || api.startsWith('proxy/')) {
+            deps.guard.checkEditorOnly(req, `${prefix}/`, deps.sessionToken);
+            if (method === 'GET' && api === 'keys') {
+                await deps.imageProxy.keyStatus(res);
+                return;
+            }
+            if (method === 'PUT' && api === 'keys') {
+                await deps.imageProxy.setKey(req, res);
+                return;
+            }
+            if (api.startsWith('proxy/')) {
+                await deps.imageProxy.forward(req, res, api.slice('proxy/'.length));
+                return;
+            }
+            throw new HttpError(405, 'method', 'GET or PUT.');
+        }
+        const handler = Object.hasOwn(apiRoutes, api) ? apiRoutes[api][method] : undefined;
+        if (handler) {
+            await handler(req, res, url, method === 'HEAD');
+            return;
+        }
+        throw new HttpError(404, 'not_found', 'Not found.');
+    };
+    return (req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (isProjectStatePath(url.pathname)) {
+            // `.pix3/` is the plugin's and the CLI's state (dev.json, the journal, local keys), not a
+            // static asset of the game.
+            req.resume();
+            sendJson(res, 404, { error: 'not_found', message: 'Not found.' });
+            return;
+        }
+        if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) {
+            next();
+            return;
+        }
+        route(req, res, url).catch((error) => {
+            if (!(error instanceof HttpError)) {
+                deps.log(`500 ${req.method} ${req.url}: ${error instanceof Error ? error.stack : String(error)}`);
+            }
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            const { status, body } = errorBody(error);
+            // Drain what the client is still sending, so it reads our answer instead of EPIPE.
+            req.resume();
+            sendJson(res, status, body);
+        });
+    };
+};
+/**
+ * Any `.pix3` segment, however the browser spelled it (`%2e`, case): the project's own `.pix3/`
+ * at the root, by `/@fs/<abs>/.pix3/…`, and `~/.pix3` should `fs.allow` ever reach the home.
+ */
+const isProjectStatePath = (pathname) => {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        return false;
+    }
+    return decoded.split('/').some(segment => segment.toLowerCase() === '.pix3');
+};

package/dist/sync/barrier.d.ts

@@ -0,0 +1,69 @@
+import type { ProjectFiles } from '../files/project-files.ts';
+import type { EditorSocket } from '../server/editor-socket.ts';
+import { type ScriptGraph } from './script-graph.ts';
+/**
+ * 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 declare const DEFAULT_SYNC_TIMEOUT_MS = 10000;
+export declare const VITE_CLIENT_WARNING: string;
+export interface SyncRequest {
+    readonly expect?: Record<string, string>;
+    readonly timeoutMs: number;
+    /** The tab that asked (the page's `pix3_sync`); it has flushed already. */
+    readonly tabId: string | null;
+}
+export type SyncResult = Record<string, unknown> & {
+    readonly ok: boolean;
+};
+export declare const parseTimeout: (raw: unknown, fallback: number) => number;
+export declare const parseSyncRequest: (body: Record<string, unknown>) => SyncRequest;
+export interface BarrierDeps {
+    readonly files: ProjectFiles;
+    readonly scripts: ScriptGraph;
+    readonly socket: EditorSocket;
+    readonly log?: (line: string) => void;
+}
+export declare class SyncBarrier {
+    private readonly deps;
+    /** sha already propagated by a sync, per wire path: the watcher's late echo is suppressed. */
+    private readonly propagated;
+    /** One barrier at a time; a second sync waits for the first. */
+    private tail;
+    constructor(deps: BarrierDeps);
+    /** The tab that answers for the editor: the asker, else the writer, else the oldest tab. */
+    private targetTab;
+    /**
+     * 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.
+     */
+    flush(timeoutMs: number): Promise<SyncResult>;
+    sync(request: SyncRequest): Promise<SyncResult>;
+    private run;
+    /** Changed files the editor executes, with the sha their stamp must carry. */
+    private requiredStamps;
+    private judge;
+    /**
+     * `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: string, sha: string | null): boolean;
+    notePropagated(wirePath: string, sha: string | null): void;
+}

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>;
+}