pixifact-cli 0.4.0 → 0.5.0

package/editor/assets/index-CVrKIfXK.css

@@ -0,0 +1 @@
+:root{color:#d9dee7;font-synthesis:none;text-rendering:optimizelegibility;--bg:#111318;--panel:#171a20;--panel-raised:#1d2129;--canvas:#0d0f13;--line:#2a2f39;--line-strong:#39404d;--text:#d9dee7;--muted:#818997;--faint:#596171;--focus:#4c8dff;--focus-soft:#213a63;--success:#51b785;--warning:#d4a64f;--danger:#e36f6f;--control:#11141a;background:#111318;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif}*{box-sizing:border-box}html,body,#app{width:100%;height:100%;margin:0;overflow:hidden}button,input,select{color:inherit;font:inherit;letter-spacing:0}button{border:0}.editor-shell{background:var(--bg);grid-template-rows:42px minmax(0,1fr);width:100%;height:100%;display:grid}.editor-session-standby{background:var(--bg);place-items:center;width:100%;height:100%;display:grid}.editor-session-standby>section{gap:18px;width:min(420px,100vw - 40px);display:grid}.standby-product{color:var(--faint);font-size:10px;font-weight:750}.editor-session-standby h1{color:var(--text);letter-spacing:0;margin:0;font-size:18px}.standby-context{border-top:1px solid var(--line);border-bottom:1px solid var(--line);grid-template-columns:76px minmax(0,1fr);gap:8px 12px;padding:14px 0;display:grid}.standby-context span{color:var(--muted);font-size:12px}.standby-context strong{min-width:0;color:var(--text);text-overflow:ellipsis;white-space:nowrap;font-size:12px;font-weight:500;overflow:hidden}.takeover-button{background:var(--focus);color:#fff;cursor:pointer;border:1px solid #659cff;border-radius:4px;justify-self:start;min-width:104px;height:32px;padding:0 14px;font-size:12px;font-weight:650}.takeover-button:hover:not(:disabled){background:#5a96ff}.standby-note,.standby-error{margin:-6px 0 0;font-size:11px;line-height:1.6}.standby-note{color:var(--muted)}.standby-error{color:var(--danger)}.topbar{border-bottom:1px solid var(--line);background:#14171c;grid-template-columns:232px minmax(0,1fr) auto 112px;align-items:center;min-width:0;display:grid}.brand{border-right:1px solid var(--line);color:#f1f4f8;align-items:center;height:100%;padding:0 14px;font-size:11px;font-weight:750;display:flex}.scene-identity{align-items:baseline;gap:10px;min-width:0;padding:0 14px;display:flex}.scene-identity strong{flex:none;font-size:13px}.scene-identity span{min-width:0;color:var(--muted);text-overflow:ellipsis;white-space:nowrap;font-size:11px;overflow:hidden}.history-tools{align-items:center;gap:2px;padding-right:10px;display:flex}.history-tools button,.reset-button{width:28px;height:28px;color:var(--muted);cursor:pointer;background:0 0;border-radius:4px;place-items:center;padding:0;display:inline-grid}.history-tools button:hover:not(:disabled),.reset-button:hover:not(:disabled){background:var(--panel-raised);color:var(--text)}button:disabled{opacity:.35;cursor:default}.sync-state{border-left:1px solid var(--line);height:100%;color:var(--muted);align-items:center;gap:7px;padding:0 13px;font-size:11px;display:flex}.sync-state span{background:var(--success);border-radius:50%;width:7px;height:7px}.sync-state[data-state=saving] span{background:var(--warning)}.sync-state[data-state=conflict] span,.sync-state[data-state=error] span{background:var(--danger)}.workspace{grid-template-columns:minmax(190px,232px) minmax(360px,1fr) minmax(250px,296px);min-width:0;min-height:0;display:grid}.left-panel,.right-panel,.canvas-panel{min-width:0;min-height:0}.left-panel,.right-panel{background:var(--panel)}.left-panel{border-right:1px solid var(--line)}.right-panel{border-left:1px solid var(--line);overflow:auto}.left-tabs{grid-template-rows:34px minmax(0,1fr);height:100%;display:grid}.tab-list{border-bottom:1px solid var(--line);grid-template-columns:1fr 1fr;display:grid}.tab-trigger{color:var(--muted);cursor:pointer;background:0 0;font-size:11px;position:relative}.tab-trigger[data-state=active]{color:var(--text)}.tab-trigger[data-state=active]:after{background:var(--focus);content:"";height:2px;position:absolute;bottom:-1px;left:12px;right:12px}.tab-content{outline:none;min-height:0;overflow:auto}.panel-title,.inspector-section-title,.asset-group-label{color:var(--muted);font-size:10px;font-weight:700}.panel-title{border-bottom:1px solid var(--line);align-items:center;height:34px;padding:0 12px;display:flex}.tree-list{margin:0;padding:0;list-style:none}.hierarchy-panel{min-height:100%;padding:0 0 6px}.hierarchy-toolbar{z-index:2;border-bottom:1px solid var(--line);background:var(--panel);grid-template-columns:minmax(0,1fr) 27px 27px 27px;align-items:center;gap:2px;height:35px;padding:4px 6px;display:grid;position:sticky;top:0}.hierarchy-toolbar select{border:1px solid var(--line-strong);background:var(--control);width:100%;min-width:0;height:25px;color:var(--text);border-radius:3px;outline:none;padding:0 5px;font-size:10px}.hierarchy-toolbar select:focus{border-color:var(--focus)}.hierarchy-toolbar button{width:27px;height:27px;color:var(--muted);cursor:pointer;background:0 0;border-radius:3px;place-items:center;padding:0;display:grid}.hierarchy-toolbar button:hover:not(:disabled){background:var(--panel-raised);color:var(--text)}.tree-row{width:100%;height:27px;color:var(--text);text-align:left;cursor:default;background:0 0;grid-template-columns:15px 16px minmax(0,1fr) auto;align-items:center;gap:4px;padding-top:0;padding-bottom:0;padding-right:9px;display:grid;position:relative}.hierarchy-panel.is-dragging .tree-row{cursor:grabbing}.hierarchy-panel.is-asset-dragging .tree-row{cursor:copy}.tree-row.drop-inside{box-shadow:inset 0 0 0 1px var(--focus);background:#26364d}.tree-row.drop-before:before,.tree-row.drop-after:after{z-index:1;background:var(--focus);content:"";pointer-events:none;height:2px;position:absolute;left:5px;right:5px}.tree-row.drop-before:before{top:-1px}.tree-row.drop-after:after{bottom:-1px}.tree-row:hover{background:#20242c}.tree-row.selected{background:var(--focus-soft);color:#eef5ff}.tree-disclosure{width:15px;height:20px;color:var(--muted);place-items:center;display:grid}.tree-disclosure.empty{visibility:hidden}.tree-icon{color:#8da4c7}.tree-label{text-overflow:ellipsis;white-space:nowrap;min-width:0;font-size:12px;overflow:hidden}.tree-row small{color:var(--faint);font-size:9px}.scene-root{cursor:default;padding-left:8px;font-weight:650}.scene-mark{color:#a9c8f8;border:1px solid #637a9d;border-radius:3px;place-items:center;width:14px;height:14px;font-size:8px;display:grid}.asset-list{padding:7px 0 14px}.asset-group-label{padding:10px 12px 5px}.asset-row{width:100%;height:29px;color:var(--text);text-align:left;background:0 0;grid-template-columns:18px minmax(0,1fr);align-items:center;gap:5px;padding:0 12px;display:grid}button.asset-row{cursor:pointer}.asset-row[data-asset-draggable=true]{cursor:grab;-webkit-user-select:none;user-select:none}.asset-row:hover,.asset-row.selected{background:#20242c}.asset-row.selected{color:#a9ccff}.asset-row span{text-overflow:ellipsis;white-space:nowrap;font-size:12px;overflow:hidden}.asset-row.asset-draggable{color:var(--muted)}.asset-empty,.panel-empty{color:var(--faint);padding:14px 12px;font-size:12px}.panel-empty.compact{padding-top:18px}.canvas-panel{background:var(--canvas);position:relative}.scene-canvas-host{-webkit-user-select:none;user-select:none;position:absolute;inset:0;overflow:hidden}.scene-canvas-host.is-asset-drop-target:after{z-index:2;border:1px solid var(--focus);content:"";pointer-events:none;position:absolute;inset:3px}.canvas-grid{pointer-events:none;background-image:linear-gradient(#20242b 1px,#0000 1px),linear-gradient(90deg,#20242b 1px,#0000 1px);background-size:24px 24px;position:absolute;inset:0}.scene-canvas{display:block;position:absolute;inset:0}.scene-canvas-host.is-pan-ready .scene-canvas{cursor:grab!important}.scene-canvas-host.is-panning .scene-canvas{cursor:grabbing!important}.canvas-tools{z-index:3;position:absolute;top:10px;right:10px}.canvas-tools button{border:1px solid var(--line);background:var(--panel);width:28px;height:28px;color:var(--muted);cursor:pointer;border-radius:4px;place-items:center;padding:0;display:inline-grid}.canvas-tools button:hover:not(:disabled){border-color:var(--line-strong);background:var(--panel-raised);color:var(--text)}.canvas-status{border:1px solid var(--line);max-width:min(520px,100% - 48px);color:var(--muted);background:#15181e;border-radius:4px;padding:7px 10px;font-size:12px;position:absolute;top:50%;left:50%;transform:translate(-50%,-50%)}.inspector-panel{min-height:0}.inspector-heading{border-bottom:1px solid var(--line);justify-content:space-between;align-items:center;min-height:54px;padding:8px 12px;display:flex}.inspector-heading div{gap:3px;min-width:0;display:grid}.inspector-heading strong{text-overflow:ellipsis;white-space:nowrap;font-size:13px;overflow:hidden}.inspector-heading small,.node-id{color:var(--muted);font-size:10px}.node-id{text-overflow:ellipsis;white-space:nowrap;max-width:90px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;overflow:hidden}.inspector-section-title{border-bottom:1px solid var(--line);height:28px;padding:9px 12px 0}.property-row{border-bottom:1px solid #21252d;grid-template-columns:minmax(70px,.8fr) minmax(120px,1.4fr);align-items:center;min-height:34px;padding:3px 8px 3px 12px;display:grid}.property-row>span{color:var(--text);text-overflow:ellipsis;white-space:nowrap;font-size:11px;overflow:hidden}.property-row>span.inherited{color:var(--muted)}.property-control{grid-template-columns:minmax(0,1fr) 24px;align-items:start;gap:3px;display:grid}.property-value{gap:3px;min-width:0;display:grid}.property-control input[type=text],.property-control input[type=number],.property-control select{border:1px solid var(--line-strong);background:var(--control);width:100%;min-width:0;height:25px;color:var(--text);border-radius:3px;outline:none;padding:0 7px;font-size:11px}.property-control input:focus,.property-control select:focus{border-color:var(--focus)}.property-control input:disabled,.property-control select:disabled{color:#9ca6b5;cursor:default;opacity:1;background:#1b1f26;border-color:#303640}.property-control input[type=checkbox]{width:15px;height:15px;accent-color:var(--focus)}.property-control input[type=color]{border:1px solid var(--line-strong);background:var(--control);border-radius:3px;width:34px;height:24px;padding:2px}.reset-button{width:24px;height:24px}.binding-source{color:#8eb8e8;text-overflow:ellipsis;white-space:nowrap;align-items:center;gap:4px;min-width:0;font-size:10px;display:flex;overflow:hidden}.inline-error,.global-error{color:#ffd1d1;margin:0;font-size:11px}.inline-error{background:#2d1b20;border-bottom:1px solid #4f292f;padding:9px 12px}.global-error{background:#321e23;border:1px solid #66343c;border-radius:4px;max-width:min(520px,100vw - 24px);padding:9px 11px;position:fixed;bottom:12px;right:12px}@media (width<=860px){.workspace{grid-template-columns:190px minmax(320px,1fr) 250px}.topbar{grid-template-columns:190px minmax(0,1fr) auto 100px}}

package/editor/assets/init-C32NAhsC.js

@@ -0,0 +1 @@
+import{n as e,r as t,t as n,u as r}from"./index-CAe9Mkmr.js";r.add(n,t),r.add(e);

package/editor/assets/webworkerAll-BEmxAAYf.js

@@ -0,0 +1 @@
+import"./index-CAe9Mkmr.js";import"./init-C32NAhsC.js";

package/editor/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pixifact Editor</title>
+    <script type="module" crossorigin src="/assets/index-CAe9Mkmr.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CVrKIfXK.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -8,7 +8,8 @@
     "pixifact": "src/pixifact-cli.ts"
   },
   "files": [
-    "src/"
+    "src/",
+    "editor/"
   ],
   "repository": {
     "type": "git",
@@ -32,6 +33,6 @@
   },
   "dependencies": {
     "esbuild": "^0.27.2",
-    "pixifact": "^0.4.0"
+    "pixifact": "^0.5.0"
   }
 }

package/src/automation.ts

@@ -5,7 +5,6 @@ import {
     builtinSceneAssetIds,
     builtinSceneNameFromAssetId,
     defaultSceneSourceRoots,
-    extractSceneScriptInterfaces,
     findMissingScenePartReferences,
     inspectSceneTemplate,
     isIgnoredSceneSourceDirectory,
@@ -17,7 +16,7 @@ import {
     toPosixPath,
     validateSceneContent,
 } from 'pixifact/compiler';
-import { readBuiltinSceneScriptSourcesSync } from 'pixifact/compiler-node';
+import { extractSceneScriptInterfaces, readBuiltinSceneScriptSourcesSync } from 'pixifact/compiler-node';
 import {
     parsePixifactProjectConfig,
     pixifactProjectConfigFileName,
@@ -398,20 +397,30 @@ function validateCompilerSceneFile(root: string, scenePath: string) {
     if (sourceRootFailure) {
         return sourceRootFailure;
     }
+    let template: SceneTemplate;
+    try {
+        template = parseSceneTemplate(content);
+    } catch {
+        return validateSceneContent({
+            scene: scenePath,
+            content,
+        });
+    }
+    const pair = readCompilerScenePairContract(root, scenePath, template);
+    if (pair.diagnostics.length > 0 || !pair.sceneInterface) {
+        return compilerSceneValidationFailure(scenePath, content, pair.diagnostics);
+    }
     const result = validateSceneContent({
         scene: scenePath,
         content,
         existingAssets: collectProjectAssets(root),
         sceneInterfaces: collectCompilerSceneInterfaces(root, scenePath),
+        sceneInterface: pair.sceneInterface,
         normalizeSceneReference: normalizeCompilerSceneReference(scenePath),
     });
     if (!result.ok) {
         return result;
     }
-    const pair = readCompilerScenePairContract(root, scenePath, parseSceneTemplate(content));
-    if (pair.diagnostics.length > 0) {
-        return compilerSceneValidationFailure(scenePath, content, pair.diagnostics);
-    }
     return {
         ...result,
         scenePath,

package/src/editorServer.ts

@@ -0,0 +1,375 @@
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import {
+    normalizeSceneAssetId,
+    pairedSceneScriptPath,
+} from 'pixifact/compiler';
+import { extractSceneScriptInterfaces } from 'pixifact/compiler-node';
+import {
+    claimEditorSession,
+    createEditorHostSession,
+    editorSessionProtocolVersion,
+    findActiveEditorSession,
+    removeEditorSessionDescriptor,
+    type EditorSessionDescriptor,
+} from './editorSession';
+
+export interface EditorProjectServiceOptions {
+    projectRoot: string;
+    staticRoot: string;
+}
+
+export interface StartEditorOptions {
+    projectRoot: string;
+    staticRoot?: string;
+}
+
+export interface EditorServerSession {
+    url: string;
+    stop: () => void;
+}
+
+interface EditorProjectFile {
+    kind: 'image' | 'scene' | 'script' | 'file';
+    path: string;
+}
+
+interface BunServer {
+    hostname: string;
+    port: number;
+    stop(closeActiveConnections?: boolean): void;
+    upgrade(request: Request): boolean;
+}
+
+interface BunWebSocket {
+    send(data: string): void;
+}
+
+declare const Bun: {
+    serve(options: {
+        fetch(request: Request, server: BunServer): Promise<Response> | Response | undefined;
+        hostname: string;
+        port: number;
+        websocket: {
+            close(socket: BunWebSocket): void;
+            message(socket: BunWebSocket, message: string | ArrayBuffer | Uint8Array): void;
+            open(socket: BunWebSocket): void;
+        };
+    }): BunServer;
+};
+
+const ignoredDirectories = new Set(['.git', '.pixifact', 'dist', 'node_modules', 'target']);
+const imageExtensions = new Set(['.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp']);
+const scriptExtensions = new Set(['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx']);
+const contentTypes: Record<string, string> = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+};
+
+class EditorRequestError extends Error {
+    constructor(readonly status: number, message: string) {
+        super(message);
+    }
+}
+
+function jsonResponse(value: unknown, status = 200) {
+    return Response.json(value, { status });
+}
+
+function sceneVersion(source: string) {
+    return `sha256:${createHash('sha256').update(source).digest('hex')}`;
+}
+
+function fileKind(filePath: string): EditorProjectFile['kind'] {
+    const extension = path.extname(filePath).toLowerCase();
+    if (extension === '.scene') {
+        return 'scene';
+    }
+    if (imageExtensions.has(extension)) {
+        return 'image';
+    }
+    if (scriptExtensions.has(extension)) {
+        return 'script';
+    }
+    return 'file';
+}
+
+function listProjectFiles(projectRoot: string) {
+    const files: EditorProjectFile[] = [];
+
+    function visit(directory: string) {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignoredDirectories.has(entry.name)) {
+                    visit(absolutePath);
+                }
+                continue;
+            }
+            if (entry.isFile()) {
+                const relativePath = path.relative(projectRoot, absolutePath).split(path.sep).join('/');
+                files.push({ path: relativePath, kind: fileKind(relativePath) });
+            }
+        }
+    }
+
+    visit(projectRoot);
+    return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function readProjectSceneBindings(projectRoot: string) {
+    const scenePaths = listProjectFiles(projectRoot)
+        .filter((file) => file.kind === 'scene')
+        .map((file) => normalizeSceneAssetId(file.path));
+    return extractSceneScriptInterfaces(scenePaths.map((scene) => {
+        const scriptPath = pairedSceneScriptPath(scene);
+        return {
+            scene,
+            fileName: path.resolve(projectRoot, scriptPath),
+            source: fs.readFileSync(resolveInsideRoot(projectRoot, scriptPath), 'utf8'),
+        };
+    }));
+}
+
+function resolveInsideRoot(root: string, requestedPath: string) {
+    if (!requestedPath || path.isAbsolute(requestedPath)) {
+        throw new EditorRequestError(400, 'Project path must stay inside the project root.');
+    }
+    const absolutePath = path.resolve(root, requestedPath);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`)) {
+        throw new EditorRequestError(400, 'Project path must stay inside the project root.');
+    }
+    const realPath = fs.realpathSync(absolutePath);
+    if (realPath !== root && !realPath.startsWith(`${root}${path.sep}`)) {
+        throw new EditorRequestError(400, 'Project path must stay inside the project root.');
+    }
+    return realPath;
+}
+
+function requestPath(url: URL) {
+    return url.searchParams.get('path') ?? '';
+}
+
+async function readJsonBody(request: Request) {
+    const value = await request.json();
+    if (!value || typeof value !== 'object') {
+        throw new EditorRequestError(400, 'Request body must be a JSON object.');
+    }
+    return value as Record<string, unknown>;
+}
+
+function serveStaticFile(staticRoot: string, pathname: string) {
+    const relativePath = pathname === '/' ? 'index.html' : decodeURIComponent(pathname.slice(1));
+    const requestedPath = path.resolve(staticRoot, relativePath);
+    if (requestedPath !== staticRoot && !requestedPath.startsWith(`${staticRoot}${path.sep}`)) {
+        throw new EditorRequestError(400, 'Static path must stay inside the Editor root.');
+    }
+    const filePath = fs.existsSync(requestedPath) && fs.statSync(requestedPath).isFile()
+        ? requestedPath
+        : path.join(staticRoot, 'index.html');
+    const extension = path.extname(filePath).toLowerCase();
+    return new Response(fs.readFileSync(filePath), {
+        headers: {
+            'content-type': contentTypes[extension] ?? 'application/octet-stream',
+        },
+    });
+}
+
+export function createEditorProjectService(options: EditorProjectServiceOptions) {
+    const projectRoot = fs.realpathSync(options.projectRoot);
+    const staticRoot = fs.realpathSync(options.staticRoot);
+
+    async function fetch(request: Request): Promise<Response> {
+        try {
+            const url = new URL(request.url);
+            if (url.pathname === '/api/project' && request.method === 'GET') {
+                const files = listProjectFiles(projectRoot);
+                return jsonResponse({
+                    name: path.basename(projectRoot),
+                    root: projectRoot,
+                    files,
+                    scenes: files.filter((file) => file.kind === 'scene').map((file) => file.path),
+                    images: files.filter((file) => file.kind === 'image').map((file) => file.path),
+                });
+            }
+            if (url.pathname === '/api/scene' && request.method === 'GET') {
+                const scenePath = requestPath(url);
+                if (path.extname(scenePath).toLowerCase() !== '.scene') {
+                    throw new EditorRequestError(400, 'Scene path must end with .scene.');
+                }
+                const source = fs.readFileSync(resolveInsideRoot(projectRoot, scenePath), 'utf8');
+                return jsonResponse({ path: scenePath, source, version: sceneVersion(source) });
+            }
+            if (url.pathname === '/api/scene-bindings' && request.method === 'GET') {
+                return jsonResponse(readProjectSceneBindings(projectRoot));
+            }
+            if (url.pathname === '/api/scene' && request.method === 'PUT') {
+                const scenePath = requestPath(url);
+                if (path.extname(scenePath).toLowerCase() !== '.scene') {
+                    throw new EditorRequestError(400, 'Scene path must end with .scene.');
+                }
+                const filePath = resolveInsideRoot(projectRoot, scenePath);
+                const body = await readJsonBody(request);
+                if (typeof body.source !== 'string' || typeof body.expectedVersion !== 'string') {
+                    throw new EditorRequestError(400, 'Scene write requires source and expectedVersion.');
+                }
+                const currentSource = fs.readFileSync(filePath, 'utf8');
+                if (sceneVersion(currentSource) !== body.expectedVersion) {
+                    throw new EditorRequestError(409, 'Scene file version changed.');
+                }
+                fs.writeFileSync(filePath, body.source, 'utf8');
+                return jsonResponse({ path: scenePath, version: sceneVersion(body.source) });
+            }
+            if (url.pathname === '/api/file' && request.method === 'GET') {
+                const filePath = resolveInsideRoot(projectRoot, requestPath(url));
+                const extension = path.extname(filePath).toLowerCase();
+                return new Response(fs.readFileSync(filePath), {
+                    headers: {
+                        'content-type': contentTypes[extension] ?? 'application/octet-stream',
+                    },
+                });
+            }
+            if (url.pathname.startsWith('/api/')) {
+                return jsonResponse({ ok: false, error: 'Editor API route was not found.' }, 404);
+            }
+            return serveStaticFile(staticRoot, url.pathname);
+        } catch (error) {
+            if (error instanceof EditorRequestError) {
+                return jsonResponse({ ok: false, error: error.message }, error.status);
+            }
+            throw error;
+        }
+    }
+
+    return { fetch };
+}
+
+function defaultEditorStaticRoot() {
+    return path.resolve(import.meta.dir, '..', 'editor');
+}
+
+function openBrowser(url: string) {
+    const command = process.platform === 'darwin'
+        ? ['open', url]
+        : process.platform === 'win32'
+            ? ['cmd', '/c', 'start', '', url]
+            : ['xdg-open', url];
+    spawn(command[0], command.slice(1), { detached: true, stdio: 'ignore' }).unref();
+}
+
+export function watchEditorProject(projectRoot: string, onProjectFileChanged: (path: string) => void) {
+    const changedPathTimers = new Map<string, ReturnType<typeof setTimeout>>();
+    const watcher = fs.watch(projectRoot, { recursive: true }, (_event, fileName) => {
+        if (!fileName) return;
+        const changedPath = String(fileName).split(path.sep).join('/');
+        const pending = changedPathTimers.get(changedPath);
+        if (pending) clearTimeout(pending);
+        changedPathTimers.set(changedPath, setTimeout(() => {
+            changedPathTimers.delete(changedPath);
+            onProjectFileChanged(changedPath);
+        }, 30));
+    });
+    return () => {
+        for (const timer of changedPathTimers.values()) clearTimeout(timer);
+        watcher.close();
+    };
+}
+
+export async function startEditorServer(options: StartEditorOptions): Promise<EditorServerSession> {
+    const staticRoot = options.staticRoot ?? defaultEditorStaticRoot();
+    if (!fs.existsSync(path.join(staticRoot, 'index.html'))) {
+        throw new Error('Editor frontend is not built. Run "bun run editor:frontend:build" first.');
+    }
+    const projectRoot = fs.realpathSync(options.projectRoot);
+    const activeSession = await findActiveEditorSession({ projectRoot });
+    if (activeSession) {
+        openBrowser(activeSession.origin);
+        return {
+            url: activeSession.origin,
+            stop() {},
+        };
+    }
+
+    const service = createEditorProjectService({ projectRoot, staticRoot });
+    const token = randomBytes(32).toString('hex');
+    const hostSession = createEditorHostSession({ projectRoot, token });
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: 0,
+        fetch(request, bunServer) {
+            const sessionResponse = hostSession.fetch(request);
+            if (sessionResponse) {
+                return sessionResponse;
+            }
+            const requestUrl = new URL(request.url);
+            if (requestUrl.pathname === '/api/events') {
+                if (request.headers.get('origin') !== requestUrl.origin) {
+                    return Response.json({ ok: false, error: 'Editor WebSocket origin is invalid.' }, { status: 403 });
+                }
+                if (bunServer.upgrade(request)) {
+                    return undefined;
+                }
+            }
+            return service.fetch(request);
+        },
+        websocket: {
+            open(socket) {
+                hostSession.open(socket);
+            },
+            close(socket) {
+                hostSession.close(socket);
+            },
+            message(socket, message) {
+                hostSession.message(socket, message);
+            },
+        },
+    });
+    const stopWatcher = watchEditorProject(projectRoot, hostSession.notifyProjectFileChanged);
+    const url = `http://${server.hostname}:${server.port}`;
+    const descriptor: EditorSessionDescriptor = {
+        protocolVersion: editorSessionProtocolVersion,
+        projectRoot,
+        pid: process.pid,
+        origin: url,
+        token,
+    };
+    const claim = await claimEditorSession({ projectRoot, descriptor });
+    if (!claim.owned) {
+        stopWatcher();
+        server.stop(true);
+        openBrowser(claim.descriptor.origin);
+        return {
+            url: claim.descriptor.origin,
+            stop() {},
+        };
+    }
+
+    let stopped = false;
+    const removeDescriptor = () => removeEditorSessionDescriptor(descriptor);
+    process.once('exit', removeDescriptor);
+    openBrowser(url);
+    return {
+        url,
+        stop() {
+            if (stopped) return;
+            stopped = true;
+            process.off('exit', removeDescriptor);
+            removeDescriptor();
+            stopWatcher();
+            server.stop(true);
+        },
+    };
+}