@world-engines/project-host 0.1.0-alpha.0

package/dist/local-gui-server.js

@@ -0,0 +1,987 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, realpath, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AUTHORING_BRIDGE_TOOLS, authoringToolDescriptor, } from "@world-engines/authoring-bridge";
+import { LOCAL_GUI_HOST, LOCAL_GUI_MAX_JSON_BODY_BYTES, LOCAL_GUI_PORT, LOCAL_GUI_SESSION_COOKIE, } from "./local-gui-contract.js";
+import { listLocalGuiFiles, readLocalGuiFile, writeLocalGuiViewFile, } from "./local-gui-workspace.js";
+import { importLocalGalleryImage, listLocalGalleryImages, readLocalGalleryImage } from "./local-gallery.js";
+import { readLocalGuiOfficialScore, readLocalGuiScore, readLocalGuiTagBenchmark } from "./local-gui-score.js";
+import { LocalPreviewRuntime } from "./preview-runtime.js";
+import { LocalPreviewRuntime as LocalPreviewStateRuntime } from "./local-preview-runtime.js";
+import { LocalPreviewReadOnlyProjection, localPreviewCoreFromRuntimeSnapshot } from "./local-preview-projections.js";
+import { localPreviewAssetsFromRuntimeSnapshot } from "./local-preview-assets.js";
+import { LOCAL_PREVIEW_VIEW_STATE_NAMESPACE, LocalPreviewViewStateStore } from "./local-preview-view-state.js";
+import { LocalPreviewSession } from "./local-preview-session.js";
+import { createLocalPreviewViewEventIngress, projectLocalPreviewAuthorViewEvents, readLocalPreviewViewInteractionConfig, } from "./local-preview-view-events.js";
+import { LocalProjectHost } from "./project-host.js";
+import { toPublicError } from "./public-error.js";
+import { LOCAL_GUI_AUTHORIZATION_ORIGINS, createLocalGuiAuth, } from "./local-gui-auth.js";
+import { createLocalGuiVersionChecker } from "./local-gui-version.js";
+import { fetchLocalAccountChatCatalog, readLocalModelSettings, writeLocalModelSettings } from "./local-model-settings.js";
+const SECURITY_HEADERS = Object.freeze({
+    "Content-Security-Policy": `default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self'; img-src 'self' data:; connect-src 'self'; worker-src 'self'; frame-src http://localhost:*; object-src 'none'; base-uri 'none'; form-action 'self' ${LOCAL_GUI_AUTHORIZATION_ORIGINS.join(" ")}; frame-ancestors 'none'`,
+    "X-Frame-Options": "DENY",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    "Cache-Control": "no-store",
+});
+const LOCAL_GUI_MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
+const LOCAL_PREVIEW_ASSET_CAPABILITY_TOKEN = /^[A-Za-z0-9_-]{43}$/u;
+const CONTENT_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".wasm": "application/wasm",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+};
+class LocalGuiHttpError extends Error {
+    code;
+    status;
+    constructor(code, status, message) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "LocalGuiHttpError";
+    }
+}
+function success(result) {
+    return { ok: true, result };
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message } };
+}
+function sendHeaders(response, headers = {}) {
+    for (const [name, value] of Object.entries(SECURITY_HEADERS))
+        response.setHeader(name, value);
+    for (const [name, value] of Object.entries(headers))
+        response.setHeader(name, value);
+}
+function sendJson(response, status, body) {
+    sendHeaders(response, { "Content-Type": "application/json; charset=utf-8" });
+    let serialized = JSON.stringify(body);
+    if (Buffer.byteLength(serialized, "utf8") > LOCAL_GUI_MAX_JSON_RESPONSE_BYTES) {
+        response.statusCode = 413;
+        serialized = JSON.stringify(failure("E_BODY_TOO_LARGE", "响应体过大"));
+    }
+    else {
+        response.statusCode = status;
+    }
+    response.end(`${serialized}\n`);
+}
+function acceptsJson(request) {
+    return String(request.headers.accept ?? "").split(",").some((item) => item.trim().split(";", 1)[0]?.toLowerCase() === "application/json");
+}
+function sendGalleryImage(response, image) {
+    sendHeaders(response, {
+        "Content-Type": image.mime,
+        "Content-Length": String(image.bytes.byteLength),
+        "Cache-Control": "private, max-age=0, must-revalidate",
+        ETag: `"${image.sha256}"`,
+    });
+    response.statusCode = 200;
+    response.end(image.bytes);
+}
+/** @internal 供真实 HTTP Range 回归复用；调用方仍负责 session/capability authorization。 */
+export function sendPreviewAsset(request, response, asset) {
+    const baseHeaders = {
+        "Content-Type": asset.mime,
+        "Cache-Control": "private, max-age=0, must-revalidate",
+        ETag: `"${asset.sha256}"`,
+        "X-Local-Preview-Asset-Sha256": asset.sha256,
+        "Cross-Origin-Resource-Policy": "cross-origin",
+        "Accept-Ranges": "bytes",
+    };
+    const range = request.headers.range;
+    let body = asset.bytes;
+    if (range !== undefined) {
+        const match = typeof range === "string" && !range.includes(",") ? /^bytes=(\d*)-(\d*)$/u.exec(range) : null;
+        const startText = match?.[1] ?? "";
+        const endText = match?.[2] ?? "";
+        let start = Number.NaN;
+        let end = Number.NaN;
+        if (match !== null && (startText !== "" || endText !== "")) {
+            if (startText === "") {
+                const suffix = Number(endText);
+                if (Number.isSafeInteger(suffix) && suffix > 0 && suffix <= asset.bytes.byteLength) {
+                    start = asset.bytes.byteLength - suffix;
+                    end = asset.bytes.byteLength - 1;
+                }
+            }
+            else {
+                start = Number(startText);
+                end = endText === "" ? asset.bytes.byteLength - 1 : Number(endText);
+            }
+        }
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end >= asset.bytes.byteLength) {
+            sendHeaders(response, { ...baseHeaders, "Content-Range": `bytes */${asset.bytes.byteLength}`, "Content-Length": "0" });
+            response.statusCode = 416;
+            response.end();
+            return;
+        }
+        body = asset.bytes.subarray(start, end + 1);
+        baseHeaders["Content-Range"] = `bytes ${start}-${end}/${asset.bytes.byteLength}`;
+        response.statusCode = 206;
+    }
+    else {
+        response.statusCode = 200;
+    }
+    sendHeaders(response, { ...baseHeaders, "Content-Length": String(body.byteLength) });
+    if (request.method === "HEAD")
+        response.end();
+    else
+        response.end(body);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, `${name} 无效`);
+    return value;
+}
+function requiredText(value, name) {
+    if (typeof value !== "string")
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, `${name} 无效`);
+    return value;
+}
+function requiredRevision(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "expected_project_revision 无效");
+    return value;
+}
+function exactKeys(body, keys) {
+    if (Object.keys(body).sort().join("\0") !== [...keys].sort().join("\0")) {
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "请求字段无效");
+    }
+}
+async function readJsonBody(request) {
+    if ((request.headers["content-type"] ?? "").split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 415, "请求必须使用 application/json");
+    }
+    const declared = Number(request.headers["content-length"] ?? 0);
+    if (Number.isFinite(declared) && declared > LOCAL_GUI_MAX_JSON_BODY_BYTES) {
+        throw new LocalGuiHttpError("E_BODY_TOO_LARGE", 413, "请求体过大");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > LOCAL_GUI_MAX_JSON_BODY_BYTES)
+            throw new LocalGuiHttpError("E_BODY_TOO_LARGE", 413, "请求体过大");
+        chunks.push(bytes);
+    }
+    let value;
+    try {
+        value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "JSON 无效");
+    }
+    if (!isRecord(value))
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "JSON body 必须是 object");
+    return value;
+}
+function requestCookie(request, name) {
+    const cookie = request.headers.cookie;
+    if (cookie === undefined)
+        return undefined;
+    for (const part of cookie.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator < 0 || part.slice(0, separator).trim() !== name)
+            continue;
+        return part.slice(separator + 1).trim();
+    }
+    return undefined;
+}
+function tokensEqual(left, right) {
+    if (left === undefined)
+        return false;
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.byteLength === b.byteLength && timingSafeEqual(a, b);
+}
+function isAllowedTopLevelNavigation(request, origin) {
+    if (request.method !== "GET")
+        return false;
+    const fetchSite = request.headers["sec-fetch-site"];
+    const fetchMode = request.headers["sec-fetch-mode"];
+    const fetchDest = request.headers["sec-fetch-dest"];
+    const requestOrigin = request.headers.origin;
+    return (fetchSite === "none" || fetchSite === "same-origin")
+        && fetchMode === "navigate"
+        && fetchDest === "document"
+        && (requestOrigin === undefined || requestOrigin === origin);
+}
+function isNavigationDocument(request) {
+    return request.method === "GET"
+        && request.headers["sec-fetch-mode"] === "navigate"
+        && request.headers["sec-fetch-dest"] === "document"
+        && request.headers.origin === undefined;
+}
+function assertApiRequest(request, origin, sessionToken) {
+    if (!tokensEqual(requestCookie(request, LOCAL_GUI_SESSION_COOKIE), sessionToken)) {
+        throw new LocalGuiHttpError("E_GUI_SESSION_REQUIRED", 401, "需要本地 GUI session");
+    }
+    const fetchSite = request.headers["sec-fetch-site"];
+    const requestOrigin = request.headers.origin;
+    if (fetchSite === "cross-site" || fetchSite === "same-site" || requestOrigin === "null") {
+        throw new LocalGuiHttpError("E_GUI_ORIGIN_FORBIDDEN", 403, "请求来源无效");
+    }
+    if (requestOrigin !== undefined && requestOrigin !== origin) {
+        throw new LocalGuiHttpError("E_GUI_ORIGIN_FORBIDDEN", 403, "请求来源无效");
+    }
+    if (request.method !== "GET" && requestOrigin !== origin) {
+        throw new LocalGuiHttpError("E_GUI_ORIGIN_FORBIDDEN", 403, "mutation 必须来自精确同源");
+    }
+}
+function area(value) {
+    if (value === "view" || value === "docs")
+        return value;
+    throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "area 必须是 view 或 docs");
+}
+function validateJobArgs(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 32 || value.some((item) => typeof item !== "string" || item.length === 0 || item.length > 8_192)) {
+        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "args 无效");
+    }
+    const args = value;
+    const [command] = args;
+    const allowed = (command === "doctor" && args.length === 1)
+        || (command === "ingest" && args.length === 5)
+        || (command === "recall" && (args.length === 2 || args.length === 3));
+    if (!allowed) {
+        throw new LocalGuiHttpError("E_COMMAND_NOT_ALLOWED", 400, "命令不在本地 GUI allowlist");
+    }
+    return Object.freeze([...args]);
+}
+function publicFailure(error) {
+    if (error instanceof LocalGuiHttpError)
+        return { status: error.status, body: failure(error.code, error.message) };
+    const candidate = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+    if (candidate === "E_FILE_CHANGED")
+        return { status: 409, body: failure(candidate, "文件已被其他写入者修改") };
+    if (candidate === "E_PROJECT_MIGRATION_REQUIRED")
+        return { status: 409, body: failure(candidate, "项目需要先迁移到 gallery manifest v2") };
+    const publicError = toPublicError(error);
+    const status = publicError.code === "E_STALE_PROJECT_REVISION" || publicError.code === "E_PROJECT_BUSY" ? 409 : 400;
+    return { status, body: failure(publicError.code, "请求失败") };
+}
+function safeStaticRelativePath(pathname) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源路径无效");
+    }
+    if (!decoded.startsWith("/") || decoded.startsWith("//") || decoded.includes("\0") || decoded.includes("\\")) {
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源路径无效");
+    }
+    const parts = decoded.slice(1).split("/").filter(Boolean);
+    const device = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+    if (parts.some((part) => part === "." || part === ".." || part.includes(":") || part.endsWith(".") || part.endsWith(" ") || device.test(part))) {
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源路径无效");
+    }
+    const selected = parts.length === 0 || extname(parts.at(-1) ?? "") === "" ? "index.html" : parts.join("/");
+    if (!new Set([".css", ".html", ".ico", ".js", ".json", ".map", ".png", ".svg", ".wasm", ".woff", ".woff2"]).has(extname(selected).toLowerCase())) {
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源类型无效");
+    }
+    return selected;
+}
+async function staticFile(assetsRoot, pathname) {
+    const relativePath = safeStaticRelativePath(pathname);
+    const candidate = resolve(assetsRoot, ...relativePath.split("/"));
+    const rel = relative(assetsRoot, candidate);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源路径无效");
+    let current = assetsRoot;
+    for (const segment of relativePath.split("/")) {
+        current = join(current, segment);
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "拒绝链接静态资源");
+    }
+    const canonical = await realpath(candidate);
+    const canonicalRel = relative(assetsRoot, canonical);
+    if (canonicalRel === ".." || canonicalRel.startsWith(`..${sep}`) || isAbsolute(canonicalRel))
+        throw new LocalGuiHttpError("E_PATH_OUTSIDE_PROJECT", 400, "静态资源路径无效");
+    if (!(await stat(canonical)).isFile())
+        throw new LocalGuiHttpError("E_NOT_FOUND", 404, "静态资源不存在");
+    return canonical;
+}
+async function serveStatic(response, assetsRoot, pathname) {
+    const path = await staticFile(assetsRoot, pathname);
+    sendHeaders(response, { "Content-Type": CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream" });
+    response.statusCode = 200;
+    await new Promise((resolvePromise, rejectPromise) => {
+        const stream = createReadStream(path);
+        stream.once("error", rejectPromise);
+        response.once("finish", resolvePromise);
+        stream.pipe(response);
+    });
+}
+function jobView(job) {
+    return {
+        job_id: job.job_id,
+        args: job.args,
+        created_at_ms: job.created_at_ms,
+        state: job.state,
+        ...(job.result === undefined ? {} : { result: job.result }),
+        ...(job.error === undefined ? {} : { error: job.error }),
+    };
+}
+function startJob(jobs, runCommand, args, auth) {
+    const job = { job_id: `job_${randomBytes(16).toString("hex")}`, args, created_at_ms: Date.now(), state: "running" };
+    jobs.set(job.job_id, job);
+    void runCommand(args, auth === undefined ? {} : { auth }).then((result) => {
+        job.result = result;
+        job.state = "completed";
+    }, (error) => {
+        job.error = { code: toPublicError(error).code, message: "命令执行失败" };
+        job.state = "failed";
+    });
+    return job;
+}
+/** 启动绑定一个 canonical project root 的 npm 包内本地 GUI；浏览器不能改选 root。 */
+export async function startLocalGuiServer(root, options = {}) {
+    const host = await LocalProjectHost.open(root, options.hostOptions ?? {});
+    const previewAssetCapabilities = new Map();
+    let projectionRuntime;
+    let projectionRuntimeOpening;
+    const currentProjectionRuntime = async () => {
+        const status = await host.inspect();
+        if (projectionRuntime !== undefined && projectionRuntime.projectRevision === status.project_revision)
+            return projectionRuntime.runtime;
+        if (projectionRuntimeOpening?.projectRevision === status.project_revision)
+            return await projectionRuntimeOpening.promise;
+        const revision = status.project_revision;
+        const promise = LocalPreviewStateRuntime.open({ project_root: host.root }).then((runtime) => {
+            const previous = projectionRuntime;
+            projectionRuntime = Object.freeze({ projectRevision: revision, runtime });
+            if (previous !== undefined && previous.runtime !== runtime) {
+                previous.runtime.dispose();
+                previewAssetCapabilities.clear();
+            }
+            return runtime;
+        });
+        projectionRuntimeOpening = Object.freeze({ projectRevision: revision, promise });
+        try {
+            return await promise;
+        }
+        finally {
+            if (projectionRuntimeOpening?.promise === promise)
+                projectionRuntimeOpening = undefined;
+        }
+    };
+    const currentPreviewAssets = async () => localPreviewAssetsFromRuntimeSnapshot((await currentProjectionRuntime()).readProjectionSnapshot());
+    const pendingWriterViewDeliveries = [];
+    const drainWriterViewEvents = async (turnId, enqueue = true) => {
+        const current = await currentViewRuntime();
+        const inspection = current.runtime.inspect();
+        const drained = [];
+        for (const receipt of await current.runtime.drainPendingSceneCrossings({ turn_id: turnId, max_events: 64 })) {
+            let events;
+            try {
+                events = current.runtime.readAuthorViewEventsByOperation(receipt.operation_id);
+            }
+            catch (error) {
+                if (error.code === "E_REFERENCE_MISSING")
+                    continue;
+                throw error;
+            }
+            const deliveries = await projectLocalPreviewAuthorViewEvents({ capture_sha256: inspection.capture_sha256, binding: current.runtime.readViewInteractionBinding(), surface: "pc", author_view_events: events });
+            if (deliveries.length > 0) {
+                const entry = Object.freeze({ operation_id: receipt.operation_id, deliveries });
+                drained.push(entry);
+                if (enqueue)
+                    pendingWriterViewDeliveries.push(entry);
+            }
+        }
+        return Object.freeze(drained);
+    };
+    const currentAuthenticatedPrincipal = async () => {
+        if (auth?.status().state !== "signed_in")
+            return null;
+        const session = await auth.requestModel({ kind: "session" });
+        const principalId = session.body.principal_id;
+        if (session.status !== 200 || typeof principalId !== "string" || principalId.length === 0) {
+            throw new LocalGuiHttpError("E_AUTH_REQUIRED", 401, "本地 GUI 账户主体不可用");
+        }
+        return principalId;
+    };
+    let viewEventIngress;
+    const currentViewRuntime = async () => {
+        const before = await host.inspect();
+        const runtime = await currentProjectionRuntime();
+        const after = await host.inspect();
+        if (before.project_revision !== after.project_revision) {
+            throw new LocalGuiHttpError("E_FILE_CHANGED", 409, "Preview source 在读取期间变化，请刷新后重试");
+        }
+        return Object.freeze({ projectRevision: after.project_revision, runtime });
+    };
+    const currentViewEventIngress = async () => {
+        const current = await currentViewRuntime();
+        if (viewEventIngress?.projectRevision === current.projectRevision && viewEventIngress.runtime === current.runtime)
+            return viewEventIngress.ingress;
+        const inspection = current.runtime.inspect();
+        const ingress = await createLocalPreviewViewEventIngress({
+            capture_sha256: inspection.capture_sha256,
+            binding: current.runtime.readViewInteractionBinding(),
+            surface: "pc",
+            readCurrentFrame: () => null,
+            deriveExecutionContext: (event) => {
+                const id = createHash("sha256").update(`${inspection.capture_sha256}\u0000${event.interaction_id}`, "utf8").digest("hex").slice(0, 48);
+                return Object.freeze({ operation_id: `local.view.${id}`, turn_id: `local.view.turn.${id}` });
+            },
+            executeEvent: (input) => current.runtime.executeEvent(input),
+        });
+        viewEventIngress = Object.freeze({ projectRevision: current.projectRevision, runtime: current.runtime, ingress });
+        return ingress;
+    };
+    let previewSessionPromise;
+    const previewSession = async () => {
+        previewSessionPromise ??= LocalPreviewSession.open({
+            root: host.root,
+            projectId: (await host.inspect()).project_id,
+            readOnlyProjection: async () => {
+                const runtime = await currentProjectionRuntime();
+                const runtimeSnapshot = runtime.readProjectionSnapshot();
+                const identity = runtimeSnapshot.capture_identity;
+                if (typeof identity !== "object" || identity === null || Array.isArray(identity))
+                    throw new LocalGuiHttpError("E_OPERATION_UNCERTAIN", 500, "Preview capture identity 无效");
+                const viewId = requiredString(identity.local_view_id, "local_view_id");
+                const captureId = requiredString(identity.capture_sha256, "capture_sha256");
+                const saveId = `local.preview.${captureId.slice(0, 24)}`;
+                const assets = await currentPreviewAssets();
+                const player = runtime.playerReadModels();
+                return new LocalPreviewReadOnlyProjection(localPreviewCoreFromRuntimeSnapshot(runtimeSnapshot), {
+                    progress: () => player.progress(),
+                    ownedResources: () => player.ownedResources(),
+                    customState: async () => {
+                        const principalId = await currentAuthenticatedPrincipal();
+                        const store = await LocalPreviewViewStateStore.open({ captureId, namespace: LOCAL_PREVIEW_VIEW_STATE_NAMESPACE, saveId, viewId, principalId }, await runtime.openViewState(viewId));
+                        return await store.entries();
+                    },
+                    assets: {
+                        list: async () => assets.list(),
+                        getUrl: async (asset) => `/api/preview/asset?id=${encodeURIComponent(asset.id)}`,
+                    },
+                });
+            },
+            writerCommitted: async ({ turn_id }) => { await drainWriterViewEvents(turn_id); },
+            hostNotificationSnapshot: async () => {
+                const runtime = await currentProjectionRuntime();
+                const snapshot = runtime.readProjectionSnapshot();
+                const identity = snapshot.capture_identity;
+                const captureId = requiredString(identity.capture_sha256, "capture_sha256");
+                const viewId = requiredString(identity.local_view_id, "local_view_id");
+                const saveId = `local.preview.${captureId.slice(0, 24)}`;
+                const principalId = await currentAuthenticatedPrincipal();
+                const store = await LocalPreviewViewStateStore.open({ captureId, namespace: LOCAL_PREVIEW_VIEW_STATE_NAMESPACE, saveId, viewId, principalId }, await runtime.openViewState(viewId));
+                const entries = await store.entries();
+                const owned = await runtime.playerReadModels().ownedResources();
+                return Object.freeze({ state: Object.freeze({ generation: (await (await runtime.openViewState(viewId)).read({ captureId, namespace: LOCAL_PREVIEW_VIEW_STATE_NAMESPACE, saveId, viewId })).generation, entries: Object.freeze(entries.map((entry) => Object.freeze({ key: entry.key, revision: entry.revision }))) }), owned_resources: owned });
+            },
+            runtime: currentProjectionRuntime,
+        });
+        return previewSessionPromise;
+    };
+    const preview = options.previewRuntime ?? new LocalPreviewRuntime();
+    const issuePreviewAssetCapability = async (id) => {
+        const resolver = await currentPreviewAssets();
+        const asset = resolver.list().find((entry) => entry.id === id);
+        if (asset === undefined)
+            throw new LocalGuiHttpError("E_NOT_FOUND", 404, "Preview asset 不存在");
+        const resolved = resolver.resolveBytes(asset);
+        const token = randomBytes(32).toString("base64url");
+        previewAssetCapabilities.set(token, Object.freeze({ asset: Object.freeze({ mime: resolved.mime, sha256: resolved.sha256, bytes: resolved.bytes }) }));
+        return Object.freeze({ url: `${origin}/preview-media/${token}`, mime: resolved.mime, size: resolved.bytes.byteLength, sha256: resolved.sha256 });
+    };
+    const jobs = new Map();
+    const modelCatalogTokens = new Map();
+    const readAccountChatCatalog = options.accountChatCatalogReader ?? ((input) => fetchLocalAccountChatCatalog(input));
+    const version = options.versionChecker ?? createLocalGuiVersionChecker();
+    void version.check();
+    const sessionToken = randomBytes(32).toString("base64url");
+    const previewWorldlineRequestEpoch = randomBytes(16).toString("base64url");
+    const previewWorldlineRequests = new Map();
+    const worldlineRequest = (method, params, requestId) => {
+        if (typeof requestId !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/u.test(requestId))
+            throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "worldline request_id 无效");
+        const paramsDigest = createHash("sha256").update(JSON.stringify(params)).digest("hex");
+        const existing = previewWorldlineRequests.get(requestId);
+        if (existing !== undefined) {
+            if (existing.method !== method || existing.paramsDigest !== paramsDigest)
+                throw new LocalGuiHttpError("E_OPERATION_ID_CONFLICT", 409, "worldline request_id 已绑定不同意图");
+            return existing;
+        }
+        const context = Object.freeze({
+            requestId: createHash("sha256").update(sessionToken).update("\u0000").update(previewWorldlineRequestEpoch).update("\u0000").update(requestId).digest("hex"),
+            createdAtMs: Date.now(),
+        });
+        const entry = { method, paramsDigest, context };
+        previewWorldlineRequests.set(requestId, entry);
+        return entry;
+    };
+    const executeWorldlineRequest = async (entry, operation) => {
+        if (Object.prototype.hasOwnProperty.call(entry, "result"))
+            return entry.result;
+        entry.pending ??= operation().then((result) => { entry.result = result; return result; }, (error) => { delete entry.pending; throw error; });
+        return await entry.pending;
+    };
+    const defaultAssets = fileURLToPath(new URL("../assets/gui", import.meta.url));
+    const defaultGeneratedAssets = fileURLToPath(new URL("./gui", import.meta.url));
+    let assetsRoot;
+    let generatedAssetsRoot;
+    try {
+        assetsRoot = await realpath(resolve(options.assetsDirectory ?? defaultAssets));
+        if (!(await stat(assetsRoot)).isDirectory())
+            throw new Error("not a directory");
+        generatedAssetsRoot = await realpath(resolve(options.generatedAssetsDirectory ?? defaultGeneratedAssets));
+        if (!(await stat(generatedAssetsRoot)).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        await host.close();
+        throw new LocalGuiHttpError("E_GUI_UNAVAILABLE", 500, "本地 GUI 静态资源不可用");
+    }
+    let origin = "";
+    let auth;
+    const server = createServer(async (request, response) => {
+        try {
+            if (request.headers.host !== origin.slice("http://".length)) {
+                throw new LocalGuiHttpError("E_GUI_HOST_FORBIDDEN", 403, "Host 无效");
+            }
+            const url = new URL(request.url ?? "/", origin);
+            if (request.method === "GET" && url.pathname === "/desktop-login/callback") {
+                if (auth === undefined)
+                    throw new LocalGuiHttpError("E_CAPABILITY_UNAVAILABLE", 404, "认证能力不可用");
+                await auth.handleCallback(url);
+                sendHeaders(response, { Location: "/" });
+                response.setHeader("Set-Cookie", `${LOCAL_GUI_SESSION_COOKIE}=${sessionToken}; HttpOnly; SameSite=Strict; Path=/`);
+                response.statusCode = 303;
+                response.end();
+                return;
+            }
+            if (url.pathname.startsWith("/api/")) {
+                assertApiRequest(request, origin, sessionToken);
+                if (request.method === "GET" && url.pathname === "/api/status") {
+                    sendJson(response, 200, success(await host.inspect()));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/tools") {
+                    sendJson(response, 200, success({ tools: AUTHORING_BRIDGE_TOOLS.map((descriptor) => ({ ...descriptor, available: host.isToolAvailable(descriptor.name) })) }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/graph") {
+                    sendJson(response, 200, success(await host.readGraphProjectionReadback()));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/score") {
+                    if (url.searchParams.size !== 0)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "score 不接受查询参数");
+                    const local = await readLocalGuiScore(host);
+                    sendJson(response, 200, success({ ...local, official: await readLocalGuiOfficialScore(auth) }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/score/tag-benchmark") {
+                    if (url.searchParams.size !== 1)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "tag benchmark 查询参数无效");
+                    sendJson(response, 200, success(await readLocalGuiTagBenchmark(host, requiredString(url.searchParams.get("tag"), "tag"), auth)));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/gallery") {
+                    const areaValue = url.searchParams.get("area");
+                    if (areaValue !== "scenario" && areaValue !== "view")
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Gallery area 无效");
+                    const ownerKind = url.searchParams.get("owner_kind");
+                    const ownerId = url.searchParams.get("owner_id");
+                    if (areaValue === "scenario" && ownerKind !== "entity" && ownerKind !== "relation")
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Scenario Gallery owner_kind 无效");
+                    if (areaValue === "scenario" && (ownerId === null || ownerId.length === 0))
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Scenario Gallery owner_id 无效");
+                    if (areaValue === "view" && (ownerKind !== null || ownerId !== null))
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "View Gallery 不接受 owner");
+                    sendJson(response, 200, success({ images: await listLocalGalleryImages(host.root, areaValue, ownerKind, ownerId ?? undefined) }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/gallery/file") {
+                    if (url.searchParams.size !== 1)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Gallery file 查询参数无效");
+                    sendGalleryImage(response, await readLocalGalleryImage(host.root, requiredString(url.searchParams.get("path"), "path")));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/auth/status") {
+                    sendJson(response, 200, success(auth === undefined ? { state: "signed_out", available: false } : { ...auth.status(), available: true }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/auth/account") {
+                    sendJson(response, 200, success(auth === undefined ? { state: "signed_out", available: false } : { ...await auth.account(), available: true }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/model-settings") {
+                    if (url.searchParams.size !== 0)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "模型设置不接受查询参数");
+                    const projectId = (await host.inspect()).project_id;
+                    const accountCatalog = auth?.status().state !== "signed_in" ? undefined : await readAccountChatCatalog({ projectRoot: host.root, projectId });
+                    const catalogToken = accountCatalog === undefined ? undefined : randomBytes(24).toString("base64url");
+                    if (catalogToken !== undefined && accountCatalog !== undefined)
+                        modelCatalogTokens.set(catalogToken, Object.freeze({ accountIdentity: accountCatalog.accountIdentity, catalogDigest: accountCatalog.catalogDigest, models: accountCatalog.models.map((entry) => entry.model) }));
+                    sendJson(response, 200, success({
+                        config: await readLocalModelSettings(host.root),
+                        account_catalog: accountCatalog === undefined ? { state: "sign_in_required", models: [] } : { state: "ready", catalog_digest: accountCatalog.catalogDigest, catalog_token: catalogToken, models: accountCatalog.models },
+                    }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/version") {
+                    sendJson(response, 200, success({ ...version.get(), can_update: false, availability: "unavailable" }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/preview/session") {
+                    const after = url.searchParams.get("after_revision");
+                    const timeout = url.searchParams.get("timeout_ms");
+                    if ((after === null) !== (timeout === null))
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Preview session wait 参数无效");
+                    const session = await previewSession();
+                    if (after === null)
+                        sendJson(response, 200, success({ ...await session.inspectForHost(), view_event_deliveries: pendingWriterViewDeliveries.splice(0) }));
+                    else {
+                        const revision = Number(after);
+                        const timeoutMs = Number(timeout);
+                        sendJson(response, 200, success({ ...await session.waitForRevision(revision, timeoutMs), view_event_deliveries: pendingWriterViewDeliveries.splice(0) }));
+                    }
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/preview/view-config") {
+                    if (url.searchParams.size !== 0)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Preview View 配置不接受查询参数");
+                    try {
+                        const current = await currentViewRuntime();
+                        const inspection = current.runtime.inspect();
+                        sendJson(response, 200, success(await readLocalPreviewViewInteractionConfig({
+                            capture_sha256: inspection.capture_sha256,
+                            binding: current.runtime.readViewInteractionBinding(),
+                            surface: "pc",
+                        })));
+                    }
+                    catch {
+                        sendJson(response, 200, success(null));
+                    }
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/preview/view-delivery-recovery") {
+                    if (url.searchParams.size !== 0)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "View delivery recovery 不接受查询参数");
+                    const session = await previewSession();
+                    const current = await currentViewRuntime();
+                    const inspection = current.runtime.inspect();
+                    const recovered = [];
+                    for (const item of session.pendingViewDeliveryFailures()) {
+                        if (item.capture_sha256 !== inspection.capture_sha256)
+                            continue;
+                        const events = current.runtime.readAuthorViewEventsByOperation(item.operation_id);
+                        const deliveries = await projectLocalPreviewAuthorViewEvents({ capture_sha256: inspection.capture_sha256, binding: current.runtime.readViewInteractionBinding(), surface: "pc", author_view_events: events });
+                        recovered.push(Object.freeze({ operation_id: item.operation_id, deliveries }));
+                    }
+                    sendJson(response, 200, success(recovered));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/preview/asset") {
+                    if (url.searchParams.size !== 1)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Preview asset 查询参数无效");
+                    const id = requiredString(url.searchParams.get("id"), "id");
+                    const resolver = await currentPreviewAssets();
+                    const asset = resolver.list().find((entry) => entry.id === id);
+                    if (asset === undefined)
+                        throw new LocalGuiHttpError("E_NOT_FOUND", 404, "Preview asset 不存在");
+                    sendPreviewAsset(request, response, resolver.resolveBytes(asset));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/preview/asset-capability") {
+                    if (url.searchParams.size !== 1)
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Preview asset capability 查询参数无效");
+                    sendJson(response, 200, success(await issuePreviewAssetCapability(requiredString(url.searchParams.get("id"), "id"))));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/files") {
+                    sendJson(response, 200, success({ area: area(url.searchParams.get("area")), files: await listLocalGuiFiles(host.root, area(url.searchParams.get("area"))) }));
+                    return;
+                }
+                if (request.method === "GET" && url.pathname === "/api/file") {
+                    sendJson(response, 200, success(await readLocalGuiFile(host.root, area(url.searchParams.get("area")), requiredString(url.searchParams.get("path"), "path"))));
+                    return;
+                }
+                const jobMatch = request.method === "GET" ? /^\/api\/jobs\/(job_[a-f0-9]{32})$/.exec(url.pathname) : null;
+                if (jobMatch !== null) {
+                    const job = jobs.get(jobMatch[1]);
+                    if (job === undefined)
+                        throw new LocalGuiHttpError("E_NOT_FOUND", 404, "job 不存在");
+                    sendJson(response, 200, success(jobView(job)));
+                    return;
+                }
+                if (request.method !== "POST")
+                    throw new LocalGuiHttpError("E_NOT_FOUND", 404, "API 不存在");
+                if (url.pathname === "/api/auth/start") {
+                    if (auth === undefined)
+                        throw new LocalGuiHttpError("E_CAPABILITY_UNAVAILABLE", 400, "认证能力不可用");
+                    const started = await auth.start();
+                    if (acceptsJson(request)) {
+                        sendJson(response, 200, success({ authorization_url: started.authorization_url }));
+                        return;
+                    }
+                    sendHeaders(response, { Location: started.authorization_url });
+                    response.statusCode = 303;
+                    response.end();
+                    return;
+                }
+                const body = await readJsonBody(request);
+                if (url.pathname === "/api/preview/asset-capabilities/revoke") {
+                    exactKeys(body, ["tokens"]);
+                    if (!Array.isArray(body.tokens) || body.tokens.length > 128 || body.tokens.some((token) => typeof token !== "string" || !LOCAL_PREVIEW_ASSET_CAPABILITY_TOKEN.test(token))) {
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "Preview asset capability token 无效");
+                    }
+                    for (const token of body.tokens)
+                        previewAssetCapabilities.delete(token);
+                    sendJson(response, 200, success({ ok: true }));
+                    return;
+                }
+                if (url.pathname === "/api/tool") {
+                    const name = requiredString(body.name, "name");
+                    const descriptor = authoringToolDescriptor(name);
+                    if (!isRecord(body.input))
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "input 必须是 object");
+                    let call;
+                    if (descriptor.project_effect) {
+                        if (!isRecord(body.effect_identity))
+                            throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "effect_identity 必须是 object");
+                        call = { name, input: body.input, effect_identity: {
+                                operation_id: requiredString(body.effect_identity.operation_id, "operation_id"),
+                                expected_project_revision: requiredRevision(body.effect_identity.expected_project_revision),
+                            } };
+                    }
+                    else {
+                        call = { name, input: body.input };
+                    }
+                    sendJson(response, 200, success(await host.dispatchTool(call)));
+                    return;
+                }
+                if (url.pathname === "/api/snapshot") {
+                    sendJson(response, 200, success(await host.snapshot({ operation_id: requiredString(body.operation_id, "operation_id"), expected_project_revision: requiredRevision(body.expected_project_revision) })));
+                    return;
+                }
+                if (url.pathname === "/api/file") {
+                    if (body.area !== undefined && body.area !== "view")
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "GUI 只能写 view 区域");
+                    sendJson(response, 200, success(await writeLocalGuiViewFile(host.root, requiredString(body.path, "path"), requiredText(body.content, "content"), requiredString(body.expected_sha256, "expected_sha256"))));
+                    return;
+                }
+                if (url.pathname === "/api/model-settings") {
+                    exactKeys(body, ["model", "expected_sha256", "catalog_token"]);
+                    if (auth?.status().state !== "signed_in")
+                        throw new LocalGuiHttpError("E_AUTH_REQUIRED", 401, "请先登录账户");
+                    const catalogToken = requiredString(body.catalog_token, "catalog_token");
+                    const expected = modelCatalogTokens.get(catalogToken);
+                    if (expected === undefined)
+                        throw new LocalGuiHttpError("E_FILE_CHANGED", 409, "模型目录已变化，请重新读取");
+                    const current = await readAccountChatCatalog({ projectRoot: host.root, projectId: (await host.inspect()).project_id });
+                    modelCatalogTokens.delete(catalogToken);
+                    if (current.accountIdentity !== expected.accountIdentity || current.catalogDigest !== expected.catalogDigest || !current.models.some((entry) => entry.model === body.model) || !expected.models.includes(String(body.model)))
+                        throw new LocalGuiHttpError("E_FILE_CHANGED", 409, "账户或模型目录已变化，请重新读取");
+                    sendJson(response, 200, success(await writeLocalModelSettings(host.root, { model: body.model, expected_sha256: body.expected_sha256 })));
+                    return;
+                }
+                if (url.pathname === "/api/gallery/import") {
+                    sendJson(response, 200, success(await importLocalGalleryImage(host, {
+                        operation_id: requiredString(body.operation_id, "operation_id"),
+                        expected_project_revision: requiredRevision(body.expected_project_revision),
+                        area: requiredString(body.area, "area"),
+                        ...(body.owner_kind === undefined ? {} : { owner_kind: requiredString(body.owner_kind, "owner_kind") }),
+                        ...(body.owner_id === undefined ? {} : { owner_id: requiredString(body.owner_id, "owner_id") }),
+                        filename: requiredString(body.filename, "filename"),
+                        content_base64: requiredString(body.content_base64, "content_base64"),
+                    })));
+                    return;
+                }
+                if (url.pathname === "/api/preview") {
+                    const action = requiredString(body.action, "action");
+                    if (action === "start")
+                        sendJson(response, 200, success(await preview.start(host.root, origin)));
+                    else if (action === "stop")
+                        sendJson(response, 200, success(await preview.stop()));
+                    else if (action === "status")
+                        sendJson(response, 200, success(preview.inspect()));
+                    else
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "preview action 无效");
+                    return;
+                }
+                if (url.pathname === "/api/preview/session/command") {
+                    const method = requiredString(body.method, "method");
+                    if (!isRecord(body.params))
+                        throw new LocalGuiHttpError("E_SCHEMA_INVALID", 400, "params 必须是 object");
+                    if (method === "worldline.list" || method === "worldline.fork" || method === "worldline.activate") {
+                        exactKeys(body, ["method", "params", "request_id"]);
+                        const entry = worldlineRequest(method, body.params, body.request_id);
+                        sendJson(response, 202, success(await executeWorldlineRequest(entry, async () => await (await previewSession()).handle(method, body.params, entry.context))));
+                        return;
+                    }
+                    sendJson(response, 202, success(await (await previewSession()).handle(method, body.params)));
+                    return;
+                }
+                if (url.pathname === "/api/preview/view-event") {
+                    exactKeys(body, ["event"]);
+                    let committed;
+                    try {
+                        const result = await (await currentViewEventIngress()).handleTrustedOpaqueFrameData(body.event);
+                        if (result.ok !== true) {
+                            sendJson(response, 200, success(result));
+                            return;
+                        }
+                        committed = result;
+                        const event = body.event;
+                        const interactionId = requiredString(event.interaction_id, "interaction_id");
+                        const current = await currentViewRuntime();
+                        const captureSha256 = current.runtime.inspect().capture_sha256;
+                        const id = createHash("sha256").update(`${captureSha256}\u0000${interactionId}`, "utf8").digest("hex").slice(0, 48);
+                        const viewEventDeliveries = await drainWriterViewEvents(`local.view.turn.${id}`, false);
+                        sendJson(response, 200, success(Object.freeze({ ...result, view_event_deliveries: viewEventDeliveries })));
+                    }
+                    catch (error) {
+                        const publicError = toPublicError(error);
+                        if (committed !== undefined) {
+                            sendJson(response, 200, success({ ok: false, code: publicError.code, player_message: "操作已提交，但界面更新失败，请刷新查看结果", committed: true, delivered_count: 0 }));
+                        }
+                        else {
+                            sendJson(response, 200, success({ ok: false, code: publicError.code, player_message: "当前预览未提供可用的 View 互动配置", committed: false, delivered_count: 0 }));
+                        }
+                    }
+                    return;
+                }
+                if (url.pathname === "/api/preview/view-delivery-failed") {
+                    exactKeys(body, ["operation_id"]);
+                    const current = await currentViewRuntime();
+                    const operationId = requiredString(body.operation_id, "operation_id");
+                    current.runtime.readAuthorViewEventsByOperation(operationId);
+                    await (await previewSession()).recordViewDeliveryFailure({ operation_id: operationId, capture_sha256: current.runtime.inspect().capture_sha256 });
+                    sendJson(response, 200, success({ ok: true }));
+                    return;
+                }
+                if (url.pathname === "/api/preview/view-delivery-resolved") {
+                    exactKeys(body, ["operation_id"]);
+                    await (await previewSession()).resolveViewDeliveryFailure(requiredString(body.operation_id, "operation_id"));
+                    sendJson(response, 200, success({ ok: true }));
+                    return;
+                }
+                if (url.pathname === "/api/jobs") {
+                    if (options.runCommand === undefined)
+                        throw new LocalGuiHttpError("E_CAPABILITY_UNAVAILABLE", 400, "异步命令能力不可用");
+                    sendJson(response, 202, success(jobView(startJob(jobs, options.runCommand, validateJobArgs(body.args), auth))));
+                    return;
+                }
+                if (url.pathname === "/api/auth/logout") {
+                    if (auth === undefined)
+                        throw new LocalGuiHttpError("E_CAPABILITY_UNAVAILABLE", 400, "认证能力不可用");
+                    sendJson(response, 200, success(await auth.logout()));
+                    return;
+                }
+                if (url.pathname === "/api/update") {
+                    sendJson(response, 409, failure("E_UPDATE_UNAVAILABLE", "官方发布基线与事务 updater 尚不可用"));
+                    return;
+                }
+                throw new LocalGuiHttpError("E_NOT_FOUND", 404, "API 不存在");
+            }
+            const mediaMatch = (request.method === "GET" || request.method === "HEAD") && url.search === "" ? /^\/preview-media\/([A-Za-z0-9_-]{43})$/u.exec(url.pathname) : null;
+            if (mediaMatch !== null) {
+                const capability = previewAssetCapabilities.get(mediaMatch[1]);
+                if (capability === undefined) {
+                    previewAssetCapabilities.delete(mediaMatch[1]);
+                    throw new LocalGuiHttpError("E_NOT_FOUND", 404, "Preview asset capability 不存在");
+                }
+                sendPreviewAsset(request, response, capability.asset);
+                return;
+            }
+            const hasSession = tokensEqual(requestCookie(request, LOCAL_GUI_SESSION_COOKIE), sessionToken);
+            if (!hasSession) {
+                if (!isAllowedTopLevelNavigation(request, origin))
+                    throw new LocalGuiHttpError("E_GUI_ORIGIN_FORBIDDEN", 403, "只允许本地同源顶层导航");
+                response.setHeader("Set-Cookie", `${LOCAL_GUI_SESSION_COOKIE}=${sessionToken}; HttpOnly; SameSite=Strict; Path=/`);
+            }
+            else if ((request.headers["sec-fetch-site"] === "cross-site" && !isNavigationDocument(request)) || request.headers.origin === "null" || (request.headers.origin !== undefined && request.headers.origin !== origin)) {
+                throw new LocalGuiHttpError("E_GUI_ORIGIN_FORBIDDEN", 403, "请求来源无效");
+            }
+            if (request.method !== "GET")
+                throw new LocalGuiHttpError("E_NOT_FOUND", 404, "资源不存在");
+            if (["/graph.js", "/graph.css", "/score.js", "/score.css", "/trigger.js", "/trigger.css", "/graph-layout-worker.js", "/graph-layout.wasm", "/plane-generator.js", "/plane-generator_bg.wasm", "/plane-generation.js", "/procedural-city.js", "/road-generation.js", "/road-parcels.js", "/spatial-templates.js"].includes(url.pathname)) {
+                await serveStatic(response, generatedAssetsRoot, url.pathname);
+            }
+            else {
+                await serveStatic(response, assetsRoot, url.pathname);
+            }
+        }
+        catch (error) {
+            if (response.headersSent) {
+                response.destroy();
+                return;
+            }
+            const rendered = publicFailure(error);
+            sendJson(response, rendered.status, rendered.body);
+        }
+    });
+    const requestedPort = options.testOnlyPort ?? LOCAL_GUI_PORT;
+    try {
+        await new Promise((resolvePromise, rejectPromise) => {
+            const onError = (error) => { server.off("listening", onListening); rejectPromise(error); };
+            const onListening = () => { server.off("error", onError); resolvePromise(); };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen({ host: LOCAL_GUI_HOST, port: requestedPort });
+        });
+    }
+    catch (error) {
+        await host.close();
+        if (error.code === "EADDRINUSE") {
+            throw new LocalGuiHttpError("E_GUI_PORT_IN_USE", 409, "本地 GUI 固定端口已被占用");
+        }
+        throw error;
+    }
+    const address = server.address();
+    if (address === null || typeof address === "string" || address.address !== LOCAL_GUI_HOST) {
+        await host.close();
+        server.close();
+        throw new LocalGuiHttpError("E_GUI_UNAVAILABLE", 500, "本地 GUI 未绑定 loopback");
+    }
+    origin = `http://${LOCAL_GUI_HOST}:${address.port}`;
+    if (options.authOptions !== undefined) {
+        const projectId = (await host.inspect()).project_id;
+        auth = createLocalGuiAuth({ ...options.authOptions, projectId, projectRoot: host.root, loopbackOrigin: origin });
+    }
+    let closed = false;
+    return {
+        url: `${origin}/`,
+        host: LOCAL_GUI_HOST,
+        port: address.port,
+        ...(auth === undefined ? {} : { auth }),
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            previewAssetCapabilities.clear();
+            await new Promise((resolvePromise) => {
+                server.close(() => resolvePromise());
+                server.closeAllConnections();
+            });
+            await preview.stop();
+            projectionRuntime?.runtime.dispose();
+            await host.close();
+            jobs.clear();
+        },
+    };
+}