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

package/dist/module-paths.js

@@ -0,0 +1,32 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+/** A module id without its query (`/a/b.ts?v=1` → `/a/b.ts`). */
+export const fileOf = (id) => id.split('?')[0];
+/** A platform path with `/` separators. */
+export const posixPath = (path) => path.split(sep).join('/');
+/** `file` relative to `dir`, `/`-separated, when it lies strictly inside `dir`; else null. */
+export const relativeInside = (dir, file) => {
+    const rel = relative(dir, file);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel) ? posixPath(rel) : null;
+};
+export const isUnder = (file, dir) => dir !== null && relativeInside(dir, file) !== null;
+const realPaths = new Map();
+/**
+ * The real path of a module id (query dropped; the id itself when it is not a file), cached. The
+ * runtime's `src/` is a real path, and module ids are not always (`resolve.preserveSymlinks`, a
+ * linked workspace): comparing the two as written would silently strip nothing.
+ */
+export const realFileOf = (id) => {
+    const file = fileOf(id);
+    let real = realPaths.get(file);
+    if (real === undefined) {
+        try {
+            real = realpathSync(file);
+        }
+        catch {
+            real = file;
+        }
+        realPaths.set(file, real);
+    }
+    return real;
+};

package/dist/player/index.d.ts

@@ -0,0 +1,31 @@
+import { SceneRunner } from '@pix3/runtime';
+import 'virtual:pix3/spine';
+import 'virtual:pix3/postprocessing';
+/**
+ * `@pix3/vite-plugin/player` (plan §B.5): the game's entry. A project's `src/main.ts` is
+ * `import { startGame } from '@pix3/vite-plugin/player'; startGame('#app');` — in dev the scenes
+ * and assets are fetched from the dev server, in a build they are embedded (html) or sit beside
+ * `index.html` (zip). Port of the 1.x `runtime/src/main.ts` + `register-project-scripts.ts`.
+ *
+ * `window.__PIX3_PLAYER__` is the gate's witness: `status`, `frames` (loop iterations), `errors`.
+ */
+export interface Pix3PlayerState {
+    status: 'booting' | 'running' | 'failed';
+    /** Frames the runner's loop has run. */
+    frames: number;
+    errors: string[];
+    /** The scene the player booted into. */
+    scene: string | null;
+    runner: SceneRunner | null;
+}
+declare global {
+    interface Window {
+        __PIX3_PLAYER__?: Pix3PlayerState;
+    }
+}
+export interface StartGameOptions {
+    /** `res://`-relative scene to boot instead of the manifest's entry scene. */
+    readonly scene?: string;
+}
+/** Boot the game into `target` (a selector or an element; `#app` by default). */
+export declare function startGame(target?: string | HTMLElement, options?: StartGameOptions): Promise<SceneRunner>;

package/dist/player/index.js

@@ -0,0 +1,102 @@
+import { AssetLoader, AudioService, registerBuiltInScripts, registerProjectScriptExports, ResourceManager, RuntimeRenderer, SceneLoader, SceneManager, SceneRunner, ScriptRegistry, } from '@pix3/runtime';
+import { embeddedAssets } from 'virtual:pix3/embedded-assets';
+import { installNetworkService } from 'virtual:pix3/network';
+import { modules as projectScriptModules } from 'virtual:pix3/project-scripts';
+import { activeScenePath, resourceBase, runtimeAutoloads, runtimeFonts, runtimeLocalization, runtimeQuality, runtimeViewportBaseSize, scenePaths, } from 'virtual:pix3/scene-manifest';
+// Registers the optional Spine runtime (lazily in dev, statically in a build that uses it).
+// Must run before the first scene load.
+import 'virtual:pix3/spine';
+// Same arrangement for `postprocessing`: registered statically when a single-file build places
+// a PostProcess node, the runtime's own code-split import otherwise.
+import 'virtual:pix3/postprocessing';
+const describe = (error) => error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+const installState = () => {
+    const existing = window.__PIX3_PLAYER__;
+    if (existing)
+        return existing;
+    const state = {
+        status: 'booting',
+        frames: 0,
+        errors: [],
+        scene: null,
+        runner: null,
+    };
+    window.__PIX3_PLAYER__ = state;
+    window.addEventListener('error', event => {
+        state.errors.push(event.message || describe(event.error));
+    });
+    window.addEventListener('unhandledrejection', event => {
+        state.errors.push(`unhandledrejection: ${describe(event.reason)}`);
+    });
+    return state;
+};
+/** Boot the game into `target` (a selector or an element; `#app` by default). */
+export async function startGame(target = '#app', options = {}) {
+    const state = installState();
+    try {
+        const app = typeof target === 'string' ? document.querySelector(target) : target;
+        if (!app)
+            throw new Error(`Missing ${typeof target === 'string' ? target : 'mount'} container`);
+        const resourceManager = new ResourceManager(resourceBase, embeddedAssets);
+        const audioService = new AudioService();
+        const scriptRegistry = new ScriptRegistry();
+        registerBuiltInScripts(scriptRegistry);
+        for (const [file, exports] of Object.entries(projectScriptModules)) {
+            registerProjectScriptExports(scriptRegistry, exports, file.replace(/^\/+/, ''));
+        }
+        const assetLoader = new AssetLoader(resourceManager, audioService);
+        const sceneLoader = new SceneLoader(assetLoader, scriptRegistry, resourceManager);
+        // No SceneSaver: a player never writes scenes back out, and one would pin every node class
+        // and `yaml.stringify` into the bundle (CLAUDE.md «Playable export size»).
+        const sceneManager = new SceneManager(sceneLoader);
+        const scenePath = options.scene || activeScenePath || scenePaths[0];
+        if (!scenePath)
+            throw new Error('No scenes found in this project.');
+        state.scene = scenePath;
+        const renderer = new RuntimeRenderer({
+            antialias: runtimeQuality.antialias,
+            shadows: runtimeQuality.shadows,
+            pixelRatio: Math.min(window.devicePixelRatio || 1, runtimeQuality.maxPixelRatio),
+        });
+        renderer.attach(app);
+        const runner = new SceneRunner(sceneManager, renderer, audioService, assetLoader, runtimeViewportBaseSize);
+        state.runner = runner;
+        // Project autoloads: built once when the first scene starts, kept across `changeScene` —
+        // the same runtime code the editor's play mode runs.
+        runner.setAutoloads(runtimeAutoloads, scriptRegistry);
+        // The loop runs on rAF; counting its iterations here is what `__PIX3_PLAYER__.frames` reports.
+        runner.setFrameScheduler({
+            request: callback => requestAnimationFrame(time => {
+                state.frames++;
+                callback(time);
+            }),
+            cancel: handle => cancelAnimationFrame(handle),
+        });
+        // Multiplayer (D5): owned by the runner, inert until a script connects; the generated module
+        // is a no-op when nothing in the project mentions the network.
+        installNetworkService(runner);
+        runner.setBatching2DEnabled(true);
+        runner.setProjectFonts(runtimeFonts.length > 0 ? runtimeFonts : null);
+        if (runtimeLocalization) {
+            runner.setLocalizationConfig({
+                defaultLocale: runtimeLocalization.defaultLocale,
+                fallbackLocale: runtimeLocalization.fallbackLocale,
+                locales: runtimeLocalization.locales,
+            });
+        }
+        // No pre-packed atlas: nothing in 2.x writes `assets/.atlas/atlas-manifest.json` (the editor
+        // packs into IndexedDB for its own play mode), so the player does not probe for one
+        // (.plans/player-build.md P26).
+        // `loadAndStartScene` reads, parses and runs the graph directly; `startScene` would clone it
+        // through the serializer, which a player does not need (and must not bundle).
+        await runner.loadAndStartScene(scenePath);
+        state.status = 'running';
+        return runner;
+    }
+    catch (error) {
+        state.status = 'failed';
+        state.errors.push(describe(error));
+        console.error('[pix3] Failed to start the game:', error);
+        throw error;
+    }
+}

package/dist/server/editor-socket.d.ts

@@ -0,0 +1,53 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+/**
+ * The editor's own WebSocket, `/__pix3/ws` (plan §B.2, variant B): the editor page carries no
+ * `/@vite/client`, so neither Vite's `full-reload` nor its reload-after-reconnect ever reaches
+ * it. Everything the plugin tells the page — file changes, "re-import your scripts", "flush" —
+ * goes over this socket.
+ *
+ * Client → plugin: `{type:'hello', tabId}` once, then `{type:'reply', id, ...}` answers.
+ * Plugin → client: `{type:'welcome', ...}`, broadcast frames (`pix3:fs`, `pix3:writer`,
+ * `pix3:scripts`), and requests `{type:'request', id, kind, ...}` that the tab answers by `id`.
+ */
+export interface EditorTab {
+    readonly tabId: string;
+    readonly connectedAt: number;
+    /** The page's `Origin` (the address the browser reached the server at), when it sent one. */
+    readonly origin?: string;
+}
+export type RequestReply = Record<string, unknown> & {
+    readonly ok: boolean;
+};
+export interface EditorSocketOptions {
+    /** URL path of the socket (`<base>__pix3/ws`). */
+    readonly path: string;
+    /** Throws to refuse the upgrade (host, peer address, origin — `RequestGuard`). */
+    readonly accept: (req: IncomingMessage) => void;
+    /** First frame a tab gets after its `hello`. */
+    readonly welcome: (tab: EditorTab) => Record<string, unknown>;
+    readonly log?: (line: string) => void;
+    readonly onTabsChanged?: () => void;
+}
+export declare class EditorSocket {
+    private readonly options;
+    private readonly wss;
+    private readonly connections;
+    private readonly pending;
+    constructor(options: EditorSocketOptions);
+    /** `httpServer.on('upgrade')` handler; returns false for upgrades that are not ours. */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): boolean;
+    /** Connected editor tabs, oldest first. */
+    tabs(): EditorTab[];
+    hasTab(tabId: string): boolean;
+    broadcast(frame: Record<string, unknown>): void;
+    /**
+     * Ask one tab to do something and wait for its answer. Never rejects: a missing tab, a closed
+     * socket or silence become `{ok:false, reason:'no_tab'|'tab_closed'|'timeout'}`.
+     */
+    request(tabId: string, kind: string, payload: Record<string, unknown>, timeoutMs: number): Promise<RequestReply>;
+    close(): void;
+    private adopt;
+    private drop;
+    private onMessage;
+}

package/dist/server/editor-socket.js

@@ -0,0 +1,134 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { isRecord } from "./http.js";
+const TAB_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/;
+export class EditorSocket {
+    options;
+    wss = new WebSocketServer({ noServer: true });
+    connections = new Set();
+    pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** `httpServer.on('upgrade')` handler; returns false for upgrades that are not ours. */
+    handleUpgrade(req, socket, head) {
+        const path = (req.url ?? '').split('?')[0];
+        if (path !== this.options.path)
+            return false;
+        try {
+            this.options.accept(req);
+        }
+        catch {
+            socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            socket.destroy();
+            return true;
+        }
+        const origin = typeof req.headers.origin === 'string' ? req.headers.origin : null;
+        this.wss.handleUpgrade(req, socket, head, ws => this.adopt(ws, origin));
+        return true;
+    }
+    /** Connected editor tabs, oldest first. */
+    tabs() {
+        const out = [];
+        for (const connection of this.connections)
+            if (connection.tab)
+                out.push(connection.tab);
+        return out.sort((a, b) => a.connectedAt - b.connectedAt);
+    }
+    hasTab(tabId) {
+        return this.tabs().some(tab => tab.tabId === tabId);
+    }
+    broadcast(frame) {
+        const text = JSON.stringify(frame);
+        for (const connection of this.connections) {
+            if (connection.tab)
+                connection.socket.send(text);
+        }
+    }
+    /**
+     * Ask one tab to do something and wait for its answer. Never rejects: a missing tab, a closed
+     * socket or silence become `{ok:false, reason:'no_tab'|'tab_closed'|'timeout'}`.
+     */
+    request(tabId, kind, payload, timeoutMs) {
+        const connection = [...this.connections].find(c => c.tab?.tabId === tabId);
+        if (!connection)
+            return Promise.resolve({ ok: false, reason: 'no_tab', tabId });
+        const id = randomUUID();
+        return new Promise(resolve => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                resolve({ ok: false, reason: 'timeout', tabId });
+            }, timeoutMs);
+            this.pending.set(id, { tabId, resolve, timer });
+            connection.socket.send(JSON.stringify({ type: 'request', id, kind, ...payload }));
+        });
+    }
+    close() {
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, reason: 'tab_closed', tabId: pending.tabId });
+            this.pending.delete(id);
+        }
+        for (const connection of this.connections)
+            connection.socket.terminate();
+        this.connections.clear();
+        this.wss.close();
+    }
+    adopt(socket, origin) {
+        const connection = { socket, origin, tab: null };
+        this.connections.add(connection);
+        socket.on('message', (raw) => this.onMessage(connection, raw));
+        socket.on('close', () => this.drop(connection));
+        socket.on('error', () => this.drop(connection));
+    }
+    drop(connection) {
+        if (!this.connections.delete(connection))
+            return;
+        const tabId = connection.tab?.tabId;
+        if (!tabId)
+            return;
+        for (const [id, pending] of this.pending) {
+            if (pending.tabId !== tabId)
+                continue;
+            clearTimeout(pending.timer);
+            this.pending.delete(id);
+            pending.resolve({ ok: false, reason: 'tab_closed', tabId });
+        }
+        this.options.log?.(`editor tab ${tabId} disconnected`);
+        this.options.onTabsChanged?.();
+    }
+    onMessage(connection, raw) {
+        let message;
+        try {
+            message = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(message))
+            return;
+        if (message.type === 'hello') {
+            const tabId = message.tabId;
+            if (connection.tab || typeof tabId !== 'string' || !TAB_ID_PATTERN.test(tabId))
+                return;
+            connection.tab = {
+                tabId,
+                connectedAt: Date.now(),
+                ...(connection.origin ? { origin: connection.origin } : {}),
+            };
+            connection.socket.send(JSON.stringify({ type: 'welcome', ...this.options.welcome(connection.tab) }));
+            this.options.log?.(`editor tab ${tabId} connected`);
+            this.options.onTabsChanged?.();
+            return;
+        }
+        if (message.type === 'reply' && typeof message.id === 'string') {
+            const pending = this.pending.get(message.id);
+            if (!pending || pending.tabId !== connection.tab?.tabId)
+                return;
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            const { type: _type, id: _id, ...rest } = message;
+            pending.resolve({ ...rest, ok: rest.ok === true });
+        }
+    }
+}

package/dist/server/guard.d.ts

@@ -0,0 +1,61 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * Who may talk to `/__pix3/*` (plan §B.1 «Защита записи»).
+ *
+ * The plugin's middleware runs before Vite's own host validation (it is a pre-middleware), so it
+ * checks the `Host` itself:
+ * - **Host** — `localhost`, a literal loopback address (127.0.0.0/8, ::1) or one of
+ *   `server.allowedHosts` (DNS rebinding: a page on an attacker's domain that resolves to
+ *   127.0.0.1 still sends its own name — and `127.evil.com` is a name, not an address); under
+ *   `allowRemote` any IP literal too, as Vite allows (a rebinding page never has one);
+ * - **peer address** — loopback unless `allowRemote` (a dev server started with `--host` must not
+ *   hand the project's files to the LAN);
+ * - **mutations and the WebSocket** — `X-Pix3: 1` (mutations) and, when the request carries an
+ *   `Origin`, the page's own origin. A cross-site page cannot add the header without a CORS
+ *   preflight, which this server never answers; a WebSocket has no preflight at all, so its
+ *   `Origin` is the only thing that keeps another site's tab from opening the event stream.
+ *   Local processes (the CLI) send no `Origin`.
+ */
+export type AllowedHosts = readonly string[] | true;
+export interface GuardOptions {
+    readonly allowRemote: boolean;
+    /** Vite's `server.allowedHosts` (`true` = any). */
+    readonly allowedHosts: () => AllowedHosts;
+}
+/** `Host` header → lower-cased name (`[::1]` keeps its brackets), or null when malformed. */
+export declare const hostNameOf: (hostHeader: string | undefined) => string | null;
+export declare const isAllowedHost: (hostHeader: string | undefined, allowed: AllowedHosts, options?: {
+    readonly allowRemote?: boolean;
+}) => boolean;
+export declare const isLoopbackAddress: (address: string | undefined) => boolean;
+export declare class RequestGuard {
+    private readonly options;
+    constructor(options: GuardOptions);
+    /** Every `/__pix3/*` request, reads included. */
+    checkPeer(req: IncomingMessage): void;
+    /** The editor's WebSocket upgrade: no preflight exists, so its `Origin` is the only fence. */
+    checkSocket(req: IncomingMessage): void;
+    private checkSameOrigin;
+    /** Anything that is not GET/HEAD. */
+    checkMutation(req: IncomingMessage): void;
+    /**
+     * Routes only the editor page may use, reads included: the image-generation keys and proxy
+     * (plan §B.1). On top of {@link checkMutation}:
+     * - `Sec-Fetch-Site`, when the browser sends it, is `same-origin`;
+     * - `Referer`, when sent, is a page under `editorPrefix` (`<base>__pix3/`) — the game at `/` is
+     *   the same origin, so the origin alone cannot tell the two apart;
+     * - `X-Pix3-Session` is the token the plugin hands only to a top-level navigation of the editor
+     *   page ({@link editorSessionFor}). A `Referer` is the page's to choose within its origin
+     *   (`fetch(url, {referrer})`), the token is not.
+     * Same-origin isolation has limits a header cannot fix (a service worker the game registers on
+     * `/` sees the editor's traffic); the key itself never reaches any page.
+     */
+    checkEditorOnly(req: IncomingMessage, editorPrefix: string, sessionToken: string): void;
+}
+/**
+ * The session token for an editor-page request, or null when this request must not get it: the
+ * page fetched by script (`Sec-Fetch-Dest: empty`) or framed (`iframe`) — the game at `/` can do
+ * both. Browsers send `Sec-Fetch-*` only to secure origins (https, localhost); without them (a
+ * plain-http LAN address under `allowRemote`, a non-browser client) the token is handed out.
+ */
+export declare const editorSessionFor: (req: IncomingMessage, token: string) => string | null;

package/dist/server/guard.js

@@ -0,0 +1,165 @@
+import { timingSafeEqual } from 'node:crypto';
+import { BlockList, isIP } from 'node:net';
+import { headerValue, HttpError } from "./http.js";
+const LOOPBACK = new BlockList();
+LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4');
+LOOPBACK.addAddress('::1', 'ipv6');
+/** A literal IP address (`[…]` brackets dropped), or null for a name. */
+const ipLiteral = (name) => {
+    const bare = name.startsWith('[') && name.endsWith(']') ? name.slice(1, -1) : name;
+    const family = isIP(bare);
+    return family === 4
+        ? { address: bare, family: 'ipv4' }
+        : family === 6
+            ? { address: bare, family: 'ipv6' }
+            : null;
+};
+/** In 127.0.0.0/8 or ::1 (IPv4-mapped included) — by address, never by how a name begins. */
+const isLoopbackIp = (address) => {
+    const ip = ipLiteral(address);
+    return ip !== null && LOOPBACK.check(ip.address, ip.family);
+};
+/** `Host` header → lower-cased name (`[::1]` keeps its brackets), or null when malformed. */
+export const hostNameOf = (hostHeader) => {
+    const host = (hostHeader ?? '').trim().toLowerCase();
+    if (!host)
+        return null;
+    let name;
+    let port;
+    if (host.startsWith('[')) {
+        const close = host.indexOf(']');
+        if (close < 0)
+            return null;
+        name = host.slice(0, close + 1);
+        const rest = host.slice(close + 1);
+        if (rest && !rest.startsWith(':'))
+            return null;
+        port = rest.slice(1);
+    }
+    else {
+        const colon = host.indexOf(':');
+        name = colon < 0 ? host : host.slice(0, colon);
+        port = colon < 0 ? '' : host.slice(colon + 1);
+        if (colon >= 0 && !port)
+            return null;
+    }
+    if (port && !/^\d{1,5}$/.test(port))
+        return null;
+    return name || null;
+};
+/** Vite's rule for one `allowedHosts` entry: exact name, or `.example.com` for it and subdomains. */
+const matchesAllowed = (name, entry) => {
+    const allowed = entry.toLowerCase();
+    if (allowed.startsWith('.'))
+        return name === allowed.slice(1) || name.endsWith(allowed);
+    return name === allowed;
+};
+export const isAllowedHost = (hostHeader, allowed, options = {}) => {
+    const name = hostNameOf(hostHeader);
+    if (name === null)
+        return false;
+    if (name === 'localhost' || isLoopbackIp(name))
+        return true;
+    // An IP literal cannot be a rebinding page's name; the peer check still applies.
+    if (options.allowRemote && ipLiteral(name) !== null)
+        return true;
+    if (allowed === true)
+        return true;
+    return allowed.some(entry => matchesAllowed(name, entry));
+};
+export const isLoopbackAddress = (address) => Boolean(address) && isLoopbackIp(address ?? '');
+/** `Origin` header, or null when absent (a non-browser client). */
+const originOf = (req) => headerValue(req, 'origin');
+/** The origin a page served by this request's `Host` has. */
+const ownOrigins = (req) => {
+    const host = headerValue(req, 'host') ?? '';
+    return [`http://${host}`, `https://${host}`].map(origin => origin.toLowerCase());
+};
+export class RequestGuard {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Every `/__pix3/*` request, reads included. */
+    checkPeer(req) {
+        if (!isAllowedHost(req.headers.host, this.options.allowedHosts(), {
+            allowRemote: this.options.allowRemote,
+        })) {
+            throw new HttpError(403, 'forbidden_host', 'Forbidden host.');
+        }
+        if (!this.options.allowRemote && !isLoopbackAddress(req.socket.remoteAddress)) {
+            throw new HttpError(403, 'forbidden_remote', 'The Pix3 editor only answers this machine. Pass pix3({ allowRemote: true }) to serve it ' +
+                'to other hosts.');
+        }
+    }
+    /** The editor's WebSocket upgrade: no preflight exists, so its `Origin` is the only fence. */
+    checkSocket(req) {
+        this.checkPeer(req);
+        this.checkSameOrigin(req);
+    }
+    checkSameOrigin(req) {
+        const origin = originOf(req);
+        if (origin !== null && !ownOrigins(req).includes(origin.toLowerCase())) {
+            throw new HttpError(403, 'forbidden_origin', 'Origin not allowed.');
+        }
+    }
+    /** Anything that is not GET/HEAD. */
+    checkMutation(req) {
+        if (headerValue(req, 'x-pix3') !== '1') {
+            throw new HttpError(403, 'missing_x_pix3', 'Mutations need the header `X-Pix3: 1`.');
+        }
+        this.checkSameOrigin(req);
+    }
+    /**
+     * Routes only the editor page may use, reads included: the image-generation keys and proxy
+     * (plan §B.1). On top of {@link checkMutation}:
+     * - `Sec-Fetch-Site`, when the browser sends it, is `same-origin`;
+     * - `Referer`, when sent, is a page under `editorPrefix` (`<base>__pix3/`) — the game at `/` is
+     *   the same origin, so the origin alone cannot tell the two apart;
+     * - `X-Pix3-Session` is the token the plugin hands only to a top-level navigation of the editor
+     *   page ({@link editorSessionFor}). A `Referer` is the page's to choose within its origin
+     *   (`fetch(url, {referrer})`), the token is not.
+     * Same-origin isolation has limits a header cannot fix (a service worker the game registers on
+     * `/` sees the editor's traffic); the key itself never reaches any page.
+     */
+    checkEditorOnly(req, editorPrefix, sessionToken) {
+        this.checkMutation(req);
+        const site = headerValue(req, 'sec-fetch-site');
+        if (site !== null && site !== 'same-origin') {
+            throw new HttpError(403, 'forbidden_site', 'Only the editor page may call this route.');
+        }
+        const referer = headerValue(req, 'referer');
+        if (referer !== null) {
+            let path;
+            try {
+                path = new URL(referer).pathname;
+            }
+            catch {
+                path = '';
+            }
+            if (!path.startsWith(editorPrefix)) {
+                throw new HttpError(403, 'forbidden_page', 'Only the editor page may call this route.');
+            }
+        }
+        if (!sameSecret(headerValue(req, 'x-pix3-session') ?? '', sessionToken)) {
+            throw new HttpError(403, 'bad_session', 'Missing or stale editor session: reload the editor tab.');
+        }
+    }
+}
+const sameSecret = (given, expected) => {
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+};
+/**
+ * The session token for an editor-page request, or null when this request must not get it: the
+ * page fetched by script (`Sec-Fetch-Dest: empty`) or framed (`iframe`) — the game at `/` can do
+ * both. Browsers send `Sec-Fetch-*` only to secure origins (https, localhost); without them (a
+ * plain-http LAN address under `allowRemote`, a non-browser client) the token is handed out.
+ */
+export const editorSessionFor = (req, token) => {
+    const dest = headerValue(req, 'sec-fetch-dest');
+    if (dest === null)
+        return token;
+    return dest === 'document' ? token : null;
+};

package/dist/server/http.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * 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 declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly extra: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
+}
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const DEFAULT_MAX_JSON_BYTES: number;
+/** The request body as bytes, refused past `maxBytes`. */
+export declare const readBytes: (req: IncomingMessage, maxBytes?: number) => Promise<Buffer>;
+export declare const readBody: (req: IncomingMessage, maxBytes?: number) => Promise<string>;
+export declare const readJson: (req: IncomingMessage, maxBytes?: number) => Promise<Record<string, unknown>>;
+export declare const headerValue: (req: IncomingMessage, name: string) => string | null;
+export declare const sendJson: (res: ServerResponse, status: number, body: Record<string, unknown>, extraHeaders?: Record<string, string>) => void;
+export declare const errnoCode: (error: unknown) => string | undefined;
+export declare const errorBody: (error: unknown) => {
+    status: number;
+    body: Record<string, unknown>;
+};