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

package/dist/server/http.js

@@ -0,0 +1,70 @@
+/**
+ * HTTP primitives of `/__pix3/api/*` (port of `packages/cli/src/server/http.ts`). Errors are always
+ * `{ error: <code>, message, ...extra }` JSON, the shape the editor's `WorkspaceClient` parses.
+ */
+export class HttpError extends Error {
+    status;
+    code;
+    extra;
+    constructor(status, code, message, extra = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.extra = extra;
+    }
+}
+export const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export const DEFAULT_MAX_JSON_BYTES = 1024 * 1024;
+/** The request body as bytes, refused past `maxBytes`. */
+export const readBytes = (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+            reject(new HttpError(413, 'too_large', 'Request body too large.'));
+            req.destroy();
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+});
+export const readBody = async (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => (await readBytes(req, maxBytes)).toString('utf8');
+export const readJson = async (req, maxBytes = DEFAULT_MAX_JSON_BYTES) => {
+    const raw = await readBody(req, maxBytes);
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (isRecord(parsed))
+            return parsed;
+    }
+    catch {
+        // fall through
+    }
+    throw new HttpError(400, 'bad_json', 'Body must be a JSON object.');
+};
+export const headerValue = (req, name) => {
+    const value = req.headers[name];
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.join(', ');
+    return null;
+};
+export const sendJson = (res, status, body, extraHeaders = {}) => {
+    if (res.writableEnded || res.destroyed)
+        return;
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+        ...extraHeaders,
+    });
+    res.end(JSON.stringify(body));
+};
+export const errnoCode = (error) => error && typeof error === 'object' && 'code' in error ? String(error.code) : undefined;
+export const errorBody = (error) => error instanceof HttpError
+    ? { status: error.status, body: { error: error.code, message: error.message, ...error.extra } }
+    : { status: 500, body: { error: 'internal', message: 'Internal error.' } };

package/dist/server/image-keys.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Image-generation API keys (plan §B.1 «Ключи генерации картинок»). They live on this machine,
+ * never in the browser: the origin is the dev server's port, which every project and the game's
+ * own code share, so localStorage / IndexedDB is no place for a secret. The plugin's proxy
+ * (`image-proxy.ts`) reads the key per request and adds it to the upstream call.
+ *
+ * Where: `~/.pix3/keys.json` (`PIX3_HOME` overrides `~/.pix3`, as for the CLI), mode 0600 in a
+ * 0700 directory. When `~` cannot be written (a sandbox), `.pix3/local/keys.json` in the project —
+ * `.pix3/` is gitignored by the starter, and the file API refuses `.pix3/local` (`paths.ts`).
+ * The file is read on every request, so an edit by hand applies at once; unknown entries survive
+ * a write.
+ */
+export declare const IMAGE_PROVIDERS: readonly ["gemini", "openai"];
+export type ImageProvider = (typeof IMAGE_PROVIDERS)[number];
+export declare const isImageProvider: (value: unknown) => value is ImageProvider;
+/** What the editor may learn about a key: whether it is there, and its last four characters. */
+export interface KeyStatus {
+    readonly set: boolean;
+    readonly last4?: string;
+}
+export interface KeyStoreOptions {
+    /** `~/.pix3` (or `PIX3_HOME`). */
+    readonly home: string;
+    readonly projectRoot: string;
+}
+export declare const defaultPix3Home: (env?: NodeJS.ProcessEnv) => string;
+export declare const KEYS_FILE = "keys.json";
+export declare const LOCAL_KEYS_PATH = ".pix3/local/keys.json";
+export declare class ImageKeyStore {
+    private readonly homeFile;
+    private readonly localFile;
+    constructor(options: KeyStoreOptions);
+    /** The key for `provider`, or null. The home file wins over the project fallback. */
+    key(provider: ImageProvider): Promise<string | null>;
+    status(): Promise<Record<ImageProvider, KeyStatus>>;
+    /**
+     * Set (or with `null` remove) one provider's key. Written to `~/.pix3/keys.json`, or to the
+     * project's `.pix3/local/keys.json` when the home directory refuses the write. A removal clears
+     * the key from both files, so the fallback cannot bring it back.
+     */
+    set(provider: ImageProvider, key: string | null): Promise<{
+        readonly status: KeyStatus;
+        readonly where: 'home' | 'project';
+    }>;
+    private update;
+}

package/dist/server/image-keys.js

@@ -0,0 +1,118 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { errnoCode } from "./http.js";
+/**
+ * Image-generation API keys (plan §B.1 «Ключи генерации картинок»). They live on this machine,
+ * never in the browser: the origin is the dev server's port, which every project and the game's
+ * own code share, so localStorage / IndexedDB is no place for a secret. The plugin's proxy
+ * (`image-proxy.ts`) reads the key per request and adds it to the upstream call.
+ *
+ * Where: `~/.pix3/keys.json` (`PIX3_HOME` overrides `~/.pix3`, as for the CLI), mode 0600 in a
+ * 0700 directory. When `~` cannot be written (a sandbox), `.pix3/local/keys.json` in the project —
+ * `.pix3/` is gitignored by the starter, and the file API refuses `.pix3/local` (`paths.ts`).
+ * The file is read on every request, so an edit by hand applies at once; unknown entries survive
+ * a write.
+ */
+export const IMAGE_PROVIDERS = ['gemini', 'openai'];
+export const isImageProvider = (value) => typeof value === 'string' && IMAGE_PROVIDERS.includes(value);
+export const defaultPix3Home = (env = process.env) => env.PIX3_HOME || join(homedir(), '.pix3');
+export const KEYS_FILE = 'keys.json';
+export const LOCAL_KEYS_PATH = '.pix3/local/keys.json';
+/** Errors that mean "this directory is not ours to write" — the cue for the project fallback. */
+const UNWRITABLE = new Set(['EACCES', 'EPERM', 'EROFS', 'ENOTDIR']);
+const statusOf = (key) => key ? { set: true, last4: key.length >= 12 ? key.slice(-4) : undefined } : { set: false };
+export class ImageKeyStore {
+    homeFile;
+    localFile;
+    constructor(options) {
+        this.homeFile = join(options.home, KEYS_FILE);
+        this.localFile = join(options.projectRoot, ...LOCAL_KEYS_PATH.split('/'));
+    }
+    /** The key for `provider`, or null. The home file wins over the project fallback. */
+    async key(provider) {
+        const home = await readKeys(this.homeFile);
+        const value = home?.[provider] ?? (await readKeys(this.localFile))?.[provider];
+        return typeof value === 'string' && value.trim() ? value.trim() : null;
+    }
+    async status() {
+        const out = {};
+        for (const provider of IMAGE_PROVIDERS) {
+            out[provider] = statusOf((await this.key(provider)) ?? undefined);
+        }
+        return out;
+    }
+    /**
+     * Set (or with `null` remove) one provider's key. Written to `~/.pix3/keys.json`, or to the
+     * project's `.pix3/local/keys.json` when the home directory refuses the write. A removal clears
+     * the key from both files, so the fallback cannot bring it back.
+     */
+    async set(provider, key) {
+        const value = key?.trim() || null;
+        if (value === null) {
+            await this.update(this.homeFile, provider, null).catch(ignoreUnwritable);
+            await this.update(this.localFile, provider, null).catch(ignoreUnwritable);
+            return { status: { set: false }, where: 'home' };
+        }
+        try {
+            await this.update(this.homeFile, provider, value);
+            // A key moved home must not leave a stale copy behind in the project.
+            await this.update(this.localFile, provider, null).catch(ignoreUnwritable);
+            return { status: statusOf(value), where: 'home' };
+        }
+        catch (error) {
+            if (!UNWRITABLE.has(errnoCode(error) ?? ''))
+                throw error;
+            await this.update(this.localFile, provider, value);
+            return { status: statusOf(value), where: 'project' };
+        }
+    }
+    async update(file, provider, value) {
+        const current = await readKeys(file);
+        if (value === null && !current?.[provider])
+            return;
+        const next = { ...(current ?? {}) };
+        if (value === null)
+            delete next[provider];
+        else
+            next[provider] = value;
+        await writeSecretFile(file, `${JSON.stringify(next, null, 2)}\n`);
+    }
+}
+const ignoreUnwritable = (error) => {
+    const code = errnoCode(error) ?? '';
+    if (!UNWRITABLE.has(code) && code !== 'ENOENT')
+        throw error;
+};
+const readKeys = async (file) => {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        // An inaccessible home store must not hide the project fallback. In particular, macOS
+        // reports ENOTDIR for a file in a parent path, where other systems may report ENOENT.
+        const code = errnoCode(error) ?? '';
+        if (code === 'ENOENT' || UNWRITABLE.has(code))
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        // A hand edit that broke the JSON: no key rather than a crash (the message never quotes it).
+        return null;
+    }
+};
+/** 0600 file in a 0700 directory, replaced atomically (never a moment with looser bits). */
+const writeSecretFile = async (file, text) => {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, text, { mode: 0o600 });
+    await chmod(tmp, 0o600);
+    await rename(tmp, file);
+};

package/dist/server/image-proxy.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ImageKeyStore, type ImageProvider } from './image-keys.ts';
+/**
+ * `/__pix3/api/keys` and `/__pix3/api/proxy/{gemini,openai}/…` (plan §B.1 «Ключи генерации
+ * картинок»). The editor's Generate panel calls the providers through here; the plugin adds the
+ * key from {@link ImageKeyStore}, so the page never holds it. Only the two generation endpoints
+ * the panel uses are forwarded — the key is not a general-purpose credential for the page.
+ * Who may call is the router's business (`RequestGuard.checkEditorOnly`).
+ *
+ * The key never leaves this module: responses and logs carry the provider, the path, the status
+ * and the size; an upstream answer that happens to contain the key gets it replaced by `[key]`.
+ */
+export declare const DEFAULT_UPSTREAMS: Readonly<Record<ImageProvider, string>>;
+/** Env overrides of the upstream origins (a local mock in an e2e run). */
+export declare const UPSTREAM_ENV: Readonly<Record<ImageProvider, string>>;
+export interface ImageProxyDeps {
+    readonly keys: ImageKeyStore;
+    readonly upstreams: Readonly<Record<ImageProvider, string>>;
+    readonly log: (line: string) => void;
+    /** For specs; the global `fetch` otherwise. */
+    readonly fetchImpl?: typeof fetch;
+}
+export declare class ImageProxy {
+    private readonly deps;
+    constructor(deps: ImageProxyDeps);
+    /** `GET /__pix3/api/keys` → `{keys: {gemini: {set, last4?}, openai: …}}`. */
+    keyStatus(res: ServerResponse): Promise<void>;
+    /** `PUT /__pix3/api/keys` `{provider, key}` (`key: null` or `''` removes) → the new status only. */
+    setKey(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** `POST /__pix3/api/proxy/<provider>/<path>` → the upstream's answer, the key added. */
+    forward(req: IncomingMessage, res: ServerResponse, rest: string): Promise<void>;
+}

package/dist/server/image-proxy.js

@@ -0,0 +1,124 @@
+import { HttpError, readBytes, readJson, sendJson } from "./http.js";
+import { isImageProvider } from "./image-keys.js";
+/**
+ * `/__pix3/api/keys` and `/__pix3/api/proxy/{gemini,openai}/…` (plan §B.1 «Ключи генерации
+ * картинок»). The editor's Generate panel calls the providers through here; the plugin adds the
+ * key from {@link ImageKeyStore}, so the page never holds it. Only the two generation endpoints
+ * the panel uses are forwarded — the key is not a general-purpose credential for the page.
+ * Who may call is the router's business (`RequestGuard.checkEditorOnly`).
+ *
+ * The key never leaves this module: responses and logs carry the provider, the path, the status
+ * and the size; an upstream answer that happens to contain the key gets it replaced by `[key]`.
+ */
+export const DEFAULT_UPSTREAMS = {
+    gemini: 'https://generativelanguage.googleapis.com',
+    openai: 'https://api.openai.com',
+};
+/** Env overrides of the upstream origins (a local mock in an e2e run). */
+export const UPSTREAM_ENV = {
+    gemini: 'PIX3_PROXY_GEMINI_URL',
+    openai: 'PIX3_PROXY_OPENAI_URL',
+};
+/** The upstream paths a provider may be called on (relative to its origin, no leading `/`). */
+const ALLOWED_PATHS = {
+    gemini: /^v1(beta)?\/models\/[A-Za-z0-9._-]+:generateContent$/,
+    openai: /^v1\/images\/(generations|edits)$/,
+};
+/** Reference images ride in the body as base64 / multipart. */
+const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+const UPSTREAM_TIMEOUT_MS = 5 * 60_000;
+const authHeaders = (provider, key) => provider === 'gemini' ? { 'x-goog-api-key': key } : { Authorization: `Bearer ${key}` };
+const KEY_HINT = 'Set it in the Generate panel (the key icon) or in Editor Settings → AI Images.';
+export class ImageProxy {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** `GET /__pix3/api/keys` → `{keys: {gemini: {set, last4?}, openai: …}}`. */
+    async keyStatus(res) {
+        sendJson(res, 200, { keys: await this.deps.keys.status() });
+    }
+    /** `PUT /__pix3/api/keys` `{provider, key}` (`key: null` or `''` removes) → the new status only. */
+    async setKey(req, res) {
+        const body = await readJson(req, 16 * 1024);
+        if (!isImageProvider(body.provider)) {
+            throw new HttpError(400, 'bad_provider', '`provider` must be "gemini" or "openai".');
+        }
+        if (body.key !== null && typeof body.key !== 'string') {
+            throw new HttpError(400, 'bad_key', '`key` must be a string, or null to remove it.');
+        }
+        if (typeof body.key === 'string' && /[\s\0]/.test(body.key.trim())) {
+            throw new HttpError(400, 'bad_key', 'An API key has no spaces or control characters.');
+        }
+        const { status, where } = await this.deps.keys.set(body.provider, body.key);
+        this.deps.log(`image-gen: ${body.provider} key ${status.set ? 'set' : 'removed'} (${where})`);
+        sendJson(res, 200, { provider: body.provider, ...status, where });
+    }
+    /** `POST /__pix3/api/proxy/<provider>/<path>` → the upstream's answer, the key added. */
+    async forward(req, res, rest) {
+        const slash = rest.indexOf('/');
+        const provider = slash < 0 ? rest : rest.slice(0, slash);
+        const path = slash < 0 ? '' : rest.slice(slash + 1);
+        if (!isImageProvider(provider)) {
+            throw new HttpError(404, 'not_found', 'Unknown image provider.');
+        }
+        if (req.method !== 'POST')
+            throw new HttpError(405, 'method', 'POST only.');
+        if (!ALLOWED_PATHS[provider].test(path)) {
+            throw new HttpError(403, 'path_not_allowed', `The ${provider} proxy forwards image generation only.`);
+        }
+        const key = await this.deps.keys.key(provider);
+        if (!key) {
+            req.resume();
+            throw new HttpError(409, 'no_key', `No ${provider} API key on this machine. ${KEY_HINT}`);
+        }
+        const body = await readBytes(req, MAX_REQUEST_BYTES);
+        const headers = authHeaders(provider, key);
+        const contentType = req.headers['content-type'];
+        if (typeof contentType === 'string')
+            headers['Content-Type'] = contentType;
+        const target = `${this.deps.upstreams[provider].replace(/\/+$/, '')}/${path}`;
+        const started = Date.now();
+        const abort = new AbortController();
+        const timer = setTimeout(() => abort.abort(), UPSTREAM_TIMEOUT_MS);
+        // The editor's Cancel (or a closed tab) aborts the upstream call too.
+        res.on('close', () => {
+            if (!res.writableFinished)
+                abort.abort();
+        });
+        let upstream;
+        let bytes;
+        try {
+            upstream = await (this.deps.fetchImpl ?? fetch)(target, {
+                method: 'POST',
+                headers,
+                body,
+                signal: abort.signal,
+            });
+            bytes = Buffer.from(await upstream.arrayBuffer());
+        }
+        catch (error) {
+            const reason = abort.signal.aborted ? 'aborted' : 'unreachable';
+            this.deps.log(`image-gen: ${provider} ${path} → ${reason} (${Date.now() - started} ms)`);
+            throw new HttpError(502, 'upstream_unreachable', `The ${provider} API did not answer (${reason}): ${scrub(describe(error), key)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const scrubbed = scrubBuffer(bytes, key);
+        this.deps.log(`image-gen: ${provider} ${path} → ${upstream.status} (${scrubbed.length} bytes, ` +
+            `${Date.now() - started} ms)`);
+        if (res.writableEnded || res.destroyed)
+            return;
+        res.writeHead(upstream.status, {
+            'Content-Type': upstream.headers.get('content-type') ?? 'application/octet-stream',
+            'Cache-Control': 'no-store',
+        });
+        res.end(scrubbed);
+    }
+}
+const describe = (error) => error instanceof Error
+    ? `${error.message}${error.cause instanceof Error ? ` (${error.cause.message})` : ''}`
+    : String(error);
+const scrub = (text, key) => text.split(key).join('[key]');
+const scrubBuffer = (bytes, key) => bytes.includes(key) ? Buffer.from(scrub(bytes.toString('utf8'), key), 'utf8') : bytes;

package/dist/server/router.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ProjectFiles } from '../files/project-files.ts';
+import { type SyncBarrier } from '../sync/barrier.ts';
+import type { EditorSocket } from './editor-socket.ts';
+import { type RequestGuard } from './guard.ts';
+import type { ImageProxy } from './image-proxy.ts';
+/**
+ * `/__pix3/*` (plan §B.1): the editor page and the file API. Mounted as a pre-middleware, so it
+ * sees `req.url` with Vite's `base` still on it.
+ *
+ * | Route | |
+ * |---|---|
+ * | `GET /__pix3/` | the editor page (raw HTML: no `transformIndexHtml`, no `/@vite/client`) |
+ * | `GET /__pix3/editor.css` | the prebuilt editor's stylesheet |
+ * | `GET /__pix3/api/hello` | project, versions, `seq`, `revision`, current writer |
+ * | `GET\|HEAD\|PUT /__pix3/api/file?path=` | bytes with sha256 ETag; conditional atomic write |
+ * | `GET /__pix3/api/manifest` | full rescan + every file with its hash |
+ * | `POST /__pix3/api/hash` | `{paths}` → `{hashes}` |
+ * | `POST /__pix3/api/{mkdir,delete,move}` | |
+ * | `POST /__pix3/api/changeset` | `{files: [{path, text\|base64, ifMatch?, createOnly?}]}` as one transaction (§C.4) |
+ * | `GET /__pix3/api/history?path=` | `{entries}` of the version journal, newest first |
+ * | `GET\|HEAD /__pix3/api/history/version?path=&id=` | one journaled version's raw bytes |
+ * | `POST /__pix3/api/history/record` | `{path, text, author: 'rejected-draft', note?}` → the entry (any tab) |
+ * | `POST /__pix3/api/history/restore` | `{path, id}` (+ `If-Match`) → written back, seen as `external` |
+ * | `POST /__pix3/api/handover/claim` | `{writerId}` → the disk the new writer starts from |
+ * | `POST /__pix3/api/sync` | the barrier (§B.3) |
+ * | `POST /__pix3/api/flush` | step 0 of the barrier on its own (`vite build`, `pix3 check`/`smoke` before they read the disk) |
+ * | `GET\|PUT /__pix3/api/keys` | image-gen key status `{set, last4?}` per provider / set or remove one (never echoed) |
+ * | `POST /__pix3/api/proxy/{gemini,openai}/…` | the provider's generation endpoint, the key added server-side |
+ *
+ * `keys` and `proxy` answer the editor page only (`RequestGuard.checkEditorOnly`: the page's
+ * session token, its `Referer`, `Sec-Fetch-Site`). No URL with a `.pix3` segment is served at all —
+ * the project's `.pix3/` holds `local/keys.json` when `~` is not writable.
+ */
+export interface RouterDeps {
+    readonly base: string;
+    readonly guard: RequestGuard;
+    readonly files: ProjectFiles;
+    readonly socket: EditorSocket;
+    readonly barrier: SyncBarrier;
+    readonly hello: () => Record<string, unknown>;
+    /** `session`: the token for this request's page, or null (`editorSessionFor`). */
+    readonly editorPage: (session: string | null) => {
+        status: number;
+        html: string;
+    };
+    /** Handed to the editor page on a top-level navigation; required by `keys` and `proxy`. */
+    readonly sessionToken: string;
+    readonly imageProxy: ImageProxy;
+    /** The prebuilt editor's stylesheet (`@pix3/editor-core/dist/editor.css`), or null. */
+    readonly editorCss: () => Buffer | null;
+    readonly log: (line: string) => void;
+}
+export declare const createRouter: (deps: RouterDeps) => (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;

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