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

package/dist/dev-info.js

@@ -0,0 +1,116 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const LOCAL_NAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * The public base URL for `dev.json`: `PIX3_PUBLIC_URL` (an origin or an origin with the base
+ * path) wins; otherwise a tab's `Origin` that is not this server's own loopback address. Null
+ * when neither says anything new. The result always ends with `base`.
+ */
+export const publicUrlOf = (options) => {
+    const withBase = (origin) => `${origin}${options.base}`;
+    if (options.env) {
+        try {
+            const url = new URL(options.env);
+            if (url.protocol !== 'http:' && url.protocol !== 'https:')
+                return null;
+            const path = url.pathname.replace(/\/+$/, '');
+            // `http://localhost:5174` or `http://localhost:5174/game/` (the base spelled out).
+            return path && path !== options.base.replace(/\/+$/, '')
+                ? `${url.origin}${path}/`
+                : withBase(url.origin);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!options.tabOrigin)
+        return null;
+    let origin;
+    try {
+        origin = new URL(options.tabOrigin);
+    }
+    catch {
+        return null;
+    }
+    const port = Number(origin.port || (origin.protocol === 'https:' ? 443 : 80));
+    if (LOCAL_NAMES.has(origin.hostname) && port === options.port)
+        return null;
+    return withBase(origin.origin);
+};
+export const devJsonPath = (root) => join(root, '.pix3', 'dev.json');
+export const writeDevInfo = (root, info) => {
+    const path = devJsonPath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(info, null, 2)}\n`);
+};
+export const clearDevInfo = (root, pid = process.pid) => {
+    const path = devJsonPath(root);
+    try {
+        const current = JSON.parse(readFileSync(path, 'utf8'));
+        if (current.pid !== pid)
+            return;
+    }
+    catch {
+        return;
+    }
+    rmSync(path, { force: true });
+};
+const readVersion = (packageJson) => {
+    try {
+        const parsed = JSON.parse(readFileSync(packageJson, 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The plugin's own version (its `package.json`, one level above `src/` and `dist/`). */
+export const pluginVersion = () => readVersion(fileURLToPath(new URL('../package.json', import.meta.url))) ?? '0.0.0';
+/**
+ * Directory of an installed package as the project sees it: `node_modules/<name>` in the root or
+ * any ancestor (hoisting). Not `require.resolve` — `@pix3/runtime` does not export its
+ * `package.json`.
+ */
+export const findPackageDir = (root, name) => {
+    for (let dir = root;; dir = dirname(dir)) {
+        const candidate = join(dir, 'node_modules', ...name.split('/'));
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+        if (dirname(dir) === dir)
+            return null;
+    }
+};
+export const installedVersion = (root, name) => {
+    const dir = findPackageDir(root, name);
+    return dir ? readVersion(join(dir, 'package.json')) : null;
+};
+const parse = (version) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+.*)?$/.exec(version);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]), prerelease: match[4] !== undefined };
+};
+/**
+ * Plan §A.3 gate: the project's `@pix3/runtime` must equal `@pix3/editor-core` exactly for
+ * prereleases and share major.minor for releases. Returns the problem, or null.
+ */
+export const versionMismatch = (runtime, editorCore) => {
+    if (runtime === null)
+        return 'The project has no @pix3/runtime installed. Run: npm i @pix3/runtime';
+    if (editorCore === null)
+        return null;
+    const a = parse(runtime);
+    const b = parse(editorCore);
+    const exact = runtime === editorCore;
+    const compatible = a !== null &&
+        b !== null &&
+        !a.prerelease &&
+        !b.prerelease &&
+        a.major === b.major &&
+        a.minor === b.minor;
+    if (exact || compatible)
+        return null;
+    return (`This editor (@pix3/editor-core ${editorCore}) needs @pix3/runtime ${editorCore}; the project ` +
+        `has ${runtime}. Run: npm i @pix3/runtime@${editorCore}`);
+};

package/dist/dev-server.d.ts

@@ -0,0 +1,28 @@
+import type { ViteDevServer } from 'vite';
+import { type Versions } from './dev-info.ts';
+import { ProjectFiles } from './files/project-files.ts';
+import { EditorSocket } from './server/editor-socket.ts';
+import { SyncBarrier } from './sync/barrier.ts';
+import type { ScriptGraph } from './sync/script-graph.ts';
+import type { Pix3Options } from './index.ts';
+export interface EditorServer {
+    readonly files: ProjectFiles;
+    readonly socket: EditorSocket;
+    readonly barrier: SyncBarrier;
+}
+/**
+ * `configureServer` with the editor on: the file API, the editor's socket, the sync barrier, the
+ * image-gen proxy and `/__pix3/*`, and `.pix3/dev.json` for as long as the server listens.
+ */
+export declare const startEditorServer: (devServer: ViteDevServer, options: {
+    readonly root: string;
+    /** Vite's `base`, ending in `/`. */
+    readonly base: string;
+    readonly resRoot: string;
+    readonly build: Pix3Options["build"];
+    readonly allowRemote: boolean;
+    readonly imageGen: Pix3Options["imageGen"];
+    readonly versions: Versions;
+    readonly scripts: ScriptGraph;
+    readonly log: (line: string) => void;
+}) => Promise<EditorServer>;

package/dist/dev-server.js

@@ -0,0 +1,139 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { clearDevInfo, findPackageDir, publicUrlOf, versionMismatch, writeDevInfo, } from "./dev-info.js";
+import { editorPageHtml, versionGatePageHtml } from "./editor-page.js";
+import { ProjectFiles } from "./files/project-files.js";
+import { EditorSocket } from "./server/editor-socket.js";
+import { RequestGuard } from "./server/guard.js";
+import { defaultPix3Home, IMAGE_PROVIDERS, ImageKeyStore } from "./server/image-keys.js";
+import { DEFAULT_UPSTREAMS, ImageProxy, UPSTREAM_ENV } from "./server/image-proxy.js";
+import { createRouter } from "./server/router.js";
+import { SyncBarrier } from "./sync/barrier.js";
+/**
+ * `configureServer` with the editor on: the file API, the editor's socket, the sync barrier, the
+ * image-gen proxy and `/__pix3/*`, and `.pix3/dev.json` for as long as the server listens.
+ */
+export const startEditorServer = async (devServer, options) => {
+    const { root, base, resRoot, versions, log } = options;
+    const logger = devServer.config.logger;
+    const guard = new RequestGuard({
+        allowRemote: options.allowRemote,
+        allowedHosts: () => devServer.config.server.allowedHosts ?? [],
+    });
+    const imageProxy = new ImageProxy({
+        keys: new ImageKeyStore({
+            home: options.imageGen?.home ?? defaultPix3Home(),
+            projectRoot: root,
+        }),
+        upstreams: Object.fromEntries(IMAGE_PROVIDERS.map(provider => [
+            provider,
+            options.imageGen?.upstreams?.[provider] ||
+                process.env[UPSTREAM_ENV[provider]] ||
+                DEFAULT_UPSTREAMS[provider],
+        ])),
+        log,
+    });
+    const files = new ProjectFiles({
+        root,
+        log,
+        onChange: frame => socket.broadcast({ ...frame }),
+    });
+    // What both a tab's `welcome` and `GET /__pix3/api/hello` start with.
+    const projectState = () => ({
+        seq: files.currentSeq,
+        revision: files.revision(),
+        writerId: files.writerId,
+        root,
+        resRoot,
+        versions,
+    });
+    const socket = new EditorSocket({
+        path: `${base}__pix3/ws`,
+        accept: req => guard.checkSocket(req),
+        onTabsChanged: () => notePublicUrl(),
+        welcome: tab => ({ tabId: tab.tabId, ...projectState(), projectName: basename(root) }),
+        log,
+    });
+    // `dev.json`'s `publicUrl` (Remote SSH, plan §E.3): `PIX3_PUBLIC_URL`, else the newest tab's
+    // `Origin` when the browser reached this server through another address (a VS Code port
+    // forward that is not 1:1). The agent finds its tab by that prefix.
+    let devInfo = null;
+    const notePublicUrl = () => {
+        if (!devInfo)
+            return;
+        const publicUrl = publicUrlOf({
+            env: process.env.PIX3_PUBLIC_URL,
+            tabOrigin: socket.tabs().at(-1)?.origin ?? null,
+            port: devInfo.port,
+            base,
+        });
+        if (!publicUrl || publicUrl === devInfo.publicUrl)
+            return;
+        devInfo = { ...devInfo, publicUrl, publicEditorUrl: `${publicUrl}__pix3/` };
+        writeDevInfo(root, devInfo);
+        log(`the browser reaches this server at ${publicUrl} (dev.json publicUrl)`);
+    };
+    const barrier = new SyncBarrier({ files, scripts: options.scripts, socket, log });
+    await files.start();
+    devServer.httpServer?.on('upgrade', (req, sock, head) => {
+        socket.handleUpgrade(req, sock, head);
+    });
+    devServer.watcher.on('all', (_event, path) => files.noteFsEvent(path));
+    const gate = versionMismatch(versions.runtime, versions.editorCore);
+    const editorCoreDir = findPackageDir(root, '@pix3/editor-core');
+    const editorCss = editorCoreDir ? join(editorCoreDir, 'dist', 'editor.css') : null;
+    devServer.middlewares.use(createRouter({
+        base,
+        guard,
+        files,
+        socket,
+        barrier,
+        log,
+        hello: () => ({
+            ...projectState(),
+            tabs: socket.tabs().map(tab => tab.tabId),
+            build: options.build,
+        }),
+        editorPage: session => gate
+            ? { status: 409, html: versionGatePageHtml(gate) }
+            : {
+                status: 200,
+                html: editorPageHtml(base, {
+                    css: editorCss !== null && existsSync(editorCss),
+                    session,
+                }),
+            },
+        // Handed to the editor page on a top-level navigation only (`editorSessionFor`).
+        sessionToken: randomBytes(32).toString('base64url'),
+        imageProxy,
+        editorCss: () => (editorCss && existsSync(editorCss) ? readFileSync(editorCss) : null),
+    }));
+    const httpServer = devServer.httpServer;
+    httpServer?.on('listening', () => {
+        const address = httpServer.address();
+        const port = typeof address === 'object' && address ? address.port : 0;
+        const protocol = devServer.config.server.https ? 'https' : 'http';
+        const url = `${protocol}://localhost:${port}${base}`;
+        const editorUrl = `${url}__pix3/`;
+        devInfo = {
+            url,
+            editorUrl,
+            port,
+            pid: process.pid,
+            versions,
+            startedAt: new Date().toISOString(),
+        };
+        writeDevInfo(root, devInfo);
+        notePublicUrl();
+        logger.info(`\n  Pix3 editor: ${editorUrl}\n`);
+        if (gate)
+            logger.warn(`[pix3] ${gate}`);
+    });
+    httpServer?.on('close', () => {
+        clearDevInfo(root);
+        socket.close();
+        void files.close();
+    });
+    return { files, socket, barrier };
+};

package/dist/editor-page.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The editor page and `virtual:pix3/editor-host` (plan §B.1, §B.2 variant B).
+ *
+ * The page is raw HTML: `transformIndexHtml` would inject `/@vite/client`, and with it Vite's
+ * `full-reload` and reload-after-reconnect. Its one module is the host, requested from Vite
+ * directly by its `/@id/` URL (S1: no inline module and no html-proxy needed).
+ */
+export declare const EDITOR_HOST_ID = "virtual:pix3/editor-host";
+export declare const SPINE_LOADER_ID = "virtual:pix3/spine-loader";
+/** The `<meta>` the page client reads (and removes) the editor session token from. */
+export declare const SESSION_META = "pix3-session";
+export declare const editorPageHtml: (base: string, options?: {
+    css?: boolean;
+    session?: string | null;
+}) => string;
+/** What `/__pix3/` shows instead of the editor when the version gate fails (plan §A.3). */
+export declare const versionGatePageHtml: (message: string) => string;
+export interface EditorHostSource {
+    readonly base: string;
+    /** `/@fs/…` URL of the plugin's page client (`src/client/index`). */
+    readonly clientUrl: string;
+    /** Whether `@pix3/editor-core` resolves from the project. */
+    readonly editorCore: boolean;
+}
+/**
+ * Source of `virtual:pix3/editor-host`. The script roots are imported statically, so they are in
+ * the module graph from the first load and every sync only re-imports them with a fresh `?t=`.
+ * Without `@pix3/editor-core` (P1, until the port lands) the page shows the host's state instead
+ * of the editor — enough to run the barrier against a real browser.
+ */
+export declare const editorHostSource: ({ base, clientUrl, editorCore }: EditorHostSource) => string;

package/dist/editor-page.js

@@ -0,0 +1,74 @@
+/**
+ * The editor page and `virtual:pix3/editor-host` (plan §B.1, §B.2 variant B).
+ *
+ * The page is raw HTML: `transformIndexHtml` would inject `/@vite/client`, and with it Vite's
+ * `full-reload` and reload-after-reconnect. Its one module is the host, requested from Vite
+ * directly by its `/@id/` URL (S1: no inline module and no html-proxy needed).
+ */
+export const EDITOR_HOST_ID = 'virtual:pix3/editor-host';
+export const SPINE_LOADER_ID = 'virtual:pix3/spine-loader';
+/**
+ * Contract B's page check (plan §B.2), installed before any module loads: a resource observer sets
+ * `window.__PIX3_VITE_CLIENT__` when Vite's client is fetched, at load or later (a script added
+ * with a CSS import reaches the page on a sync). The resource-timing buffer is raised first — the
+ * default 250 entries fill up with the editor's own modules and later entries would be dropped.
+ * The regex keeps the literal client path out of the page text.
+ */
+const VITE_CLIENT_PROBE = 'window.__PIX3_VITE_CLIENT__=false;try{performance.setResourceTimingBufferSize(1e5);' +
+    'new PerformanceObserver(function(list){list.getEntries().forEach(function(e){' +
+    'if(/\\/@vite\\/client$/.test(new URL(e.name,location.href).pathname))window.__PIX3_VITE_CLIENT__=true;' +
+    "})}).observe({type:'resource',buffered:true})}catch(e){}";
+const escapeHtml = (text) => text.replace(/[&<>"']/g, ch => `&#${ch.charCodeAt(0)};`);
+/** The `<meta>` the page client reads (and removes) the editor session token from. */
+export const SESSION_META = 'pix3-session';
+export const editorPageHtml = (base, options = {}) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />${options.session
+    ? `\n    <meta name="${SESSION_META}" content="${escapeHtml(options.session)}" />`
+    : ''}
+    <title>Pix3</title>
+    <style>html,body,#pix3-editor{margin:0;height:100%}</style>
+    <script>${VITE_CLIENT_PROBE}</script>${options.css ? `\n    <link rel="stylesheet" href="${base}__pix3/editor.css" />` : ''}
+  </head>
+  <body>
+    <div id="pix3-editor"></div>
+    <script type="module" src="${base}@id/__x00__${EDITOR_HOST_ID}"></script>
+  </body>
+</html>
+`;
+/** What `/__pix3/` shows instead of the editor when the version gate fails (plan §A.3). */
+export const versionGatePageHtml = (message) => `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><title>Pix3 — version mismatch</title></head>
+  <body style="font:15px/1.5 system-ui,sans-serif;margin:3rem;max-width:44rem">
+    <h1 style="font-size:1.4rem">Pix3 cannot open this project yet</h1>
+    <p>${escapeHtml(message)}</p>
+    <p>Then restart the dev server.</p>
+  </body>
+</html>
+`;
+/**
+ * Source of `virtual:pix3/editor-host`. The script roots are imported statically, so they are in
+ * the module graph from the first load and every sync only re-imports them with a fresh `?t=`.
+ * Without `@pix3/editor-core` (P1, until the port lands) the page shows the host's state instead
+ * of the editor — enough to run the barrier against a real browser.
+ */
+export const editorHostSource = ({ base, clientUrl, editorCore }) => {
+    const lines = [
+        `import * as editorScripts from 'virtual:pix3/editor-scripts';`,
+        `import * as botPolicies from 'virtual:pix3/bot-policies';`,
+        `import { EditorHostConnection, viteClientLoaded } from ${JSON.stringify(clientUrl)};`,
+    ];
+    if (editorCore)
+        lines.push(`import { mountEditor } from '@pix3/editor-core';`);
+    lines.push(`const host = new EditorHostConnection({ base: ${JSON.stringify(base)}, roots: { editorScripts, botPolicies } });`, `window.__PIX3_HOST__ = host;`, `host.connect();`, `if (viteClientLoaded()) console.error('[pix3] /@vite/client is loaded on the editor page: a non-literal import(), import.meta.hot or a CSS import reached the editor chain (plan §B.2, contract B; \`pix3 check\` names the file).');`, `const root = document.getElementById('pix3-editor');`);
+    if (editorCore) {
+        lines.push(`void host.ready().then(() => mountEditor(root, host));`);
+    }
+    else {
+        lines.push(`root.textContent = 'Pix3 editor host is running; @pix3/editor-core is not installed.';`, `void host.ready().then(hello => { root.dataset.tabId = hello.tabId; root.dataset.seq = String(hello.seq); });`);
+    }
+    return `${lines.join('\n')}\n`;
+};

package/dist/files/changeset.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Multi-file transactions of the write path (plan §C.4 "Changeset: staging и восстановление").
+ * `temp+rename` is atomic for one file only; a flush that touches a scene and a prefab must land
+ * both or neither, including across a crash of the dev server between the two renames.
+ *
+ * On-disk layout of one transaction `<id>`:
+ *
+ *     .pix3/tx/<id>/new/<n>       the new bytes of entry n (fsynced before the intent)
+ *     .pix3/tx/<id>/old/<n>       a copy of what was at entry n's path (absent when nothing was)
+ *     .pix3/tx/<id>/intent.json   {id, files: [{path, sha256, old: 'absent' | 'old/<n>'}],
+ *                                  state: 'prepared' | 'committed'} — replaced atomically
+ *
+ * Renames start only once `intent.json` is durable, so a transaction without a readable intent
+ * never touched a project file. A rename moves `new/<n>` away, so "staged file still present"
+ * means "not renamed yet"; a missing staged file whose target has the intended sha was renamed.
+ */
+export interface ChangesetEntry {
+    readonly path: string;
+    readonly data: Buffer;
+    readonly sha256: string;
+    /** Entity tags the file must match (`*` = must exist), or null for unconditional. */
+    readonly ifMatch: readonly string[] | null;
+    readonly createOnly: boolean;
+}
+export interface TxIntentFile {
+    readonly path: string;
+    readonly sha256: string;
+    readonly old: 'absent' | `old/${number}`;
+}
+export interface TxIntent {
+    readonly id: string;
+    readonly files: readonly TxIntentFile[];
+    readonly state: 'prepared' | 'committed';
+}
+/** What recovery did to one path; the caller journals it. */
+export interface RecoveredFile {
+    readonly path: string;
+    readonly author: 'editor' | 'restore';
+}
+export declare const MAX_CHANGESET_BYTES: number;
+export declare const txRootOf: (root: string) => string;
+/** Validate `POST /__pix3/api/changeset` `{files: [{path, text? | base64?, ifMatch?, createOnly?}]}`. */
+export declare const parseChangeset: (body: Record<string, unknown>) => ChangesetEntry[];
+/** A request fingerprint for `X-Mutation-Id` replay: same paths, conditions and bytes. */
+export declare const changesetFingerprint: (entries: readonly ChangesetEntry[]) => string;
+/** fsync a directory, so a rename or a create inside it is durable. A no-op where unsupported. */
+export declare const fsyncDir: (dir: string) => Promise<void>;
+/** Replace `intent.json` atomically and durably (temp + fsync + rename + fsync of the dir). */
+export declare const writeIntent: (txDir: string, intent: TxIntent) => Promise<void>;
+/**
+ * Rename `temp` over `target`. When `.pix3/` is on another device than the target, the bytes are
+ * copied to a sibling first and renamed from there, so the replace itself stays atomic.
+ */
+export declare const renameIntoPlace: (temp: string, target: string) => Promise<void>;
+export interface StagedFile {
+    readonly entry: ChangesetEntry;
+    readonly absolute: string;
+    /** The file's mode bits to keep, or null when nothing is there yet. */
+    readonly mode: number | null;
+}
+/**
+ * Steps 3 of plan §C.4: stage the new bytes and copies of the old ones, then write the intent
+ * (`prepared`). Returns the transaction directory and its intent; nothing in the project changed.
+ */
+export declare const stageTransaction: (root: string, files: readonly StagedFile[]) => Promise<{
+    txDir: string;
+    intent: TxIntent;
+}>;
+/** Put entry `n`'s old bytes back (or remove the file it created). */
+export declare const rollBackFile: (root: string, txDir: string, file: TxIntentFile) => Promise<void>;
+/**
+ * Recovery at plugin start (plan §C.4), before the first scan. For every `.pix3/tx/<id>/`:
+ *
+ * - no readable intent → nothing was renamed yet (renames start after the intent is durable):
+ *   the directory is removed;
+ * - `committed` → every file is in place: clean up (the versions are journaled as `editor`);
+ * - `prepared` and consistent — every entry is either still staged with the intended bytes, or
+ *   gone from `new/` with the target at the intended sha → roll forward;
+ * - `prepared` and anything else (a staged file lost, a renamed target with other bytes) → roll
+ *   back every renamed entry from `old/` (a target whose old was `absent` is deleted).
+ *
+ * Either way both files of a two-file changeset end up all old or all new (gate row N6).
+ */
+export declare const recoverTransactions: (root: string, log: (line: string) => void) => Promise<RecoveredFile[]>;