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

package/dist/local-gui-contract.d.ts

@@ -0,0 +1,53 @@
+import type { LocalProjectHostOptions } from "./project-host.js";
+import type { LocalPreviewRuntime } from "./preview-runtime.js";
+import type { LocalGuiAuth, LocalGuiAuthOptions } from "./local-gui-auth.js";
+import type { LocalGuiVersionChecker } from "./local-gui-version.js";
+import type { LocalAccountChatCatalog } from "./local-model-settings.js";
+export declare const LOCAL_GUI_HOST = "127.0.0.1";
+export declare const LOCAL_GUI_PORT = 11451;
+export declare const LOCAL_GUI_ORIGIN = "http://127.0.0.1:11451";
+export declare const LOCAL_GUI_SESSION_COOKIE = "worldengine_gui_session";
+export declare const LOCAL_GUI_MAX_JSON_BODY_BYTES: number;
+export type LocalGuiEnvelope<T> = {
+    readonly ok: true;
+    readonly result: T;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface LocalGuiCommandResult {
+    readonly [key: string]: unknown;
+}
+export type LocalGuiRunCommand = (args: readonly string[], context: Readonly<{
+    auth?: LocalGuiAuth;
+}>) => Promise<LocalGuiCommandResult>;
+export type LocalGuiAccountChatCatalogReader = (input: Readonly<{
+    projectRoot: string;
+    projectId: string;
+}>) => Promise<LocalAccountChatCatalog>;
+export interface StartLocalGuiServerOptions {
+    readonly hostOptions?: LocalProjectHostOptions;
+    readonly assetsDirectory?: string;
+    /** 仅承载构建生成的具名 graph/trigger JS 与 CSS；不会暴露为任意静态目录。 */
+    readonly generatedAssetsDirectory?: string;
+    readonly runCommand?: LocalGuiRunCommand;
+    readonly previewRuntime?: LocalPreviewRuntime;
+    /** 提供时启用 /api/auth/* 与受 PKCE/state 约束的 loopback callback。 */
+    readonly authOptions?: Omit<LocalGuiAuthOptions, "projectId" | "loopbackOrigin">;
+    /** 固定 11450 account-model proxy 的测试 seam；生产默认为该 proxy。 */
+    readonly accountChatCatalogReader?: LocalGuiAccountChatCatalogReader;
+    /** 仅用于注入版本检查 seam；没有事务 updater，不授予安装能力。 */
+    readonly versionChecker?: LocalGuiVersionChecker;
+    /** 仅供真实 HTTP 测试让内核分配端口；生产调用方不能选择端口。 */
+    readonly testOnlyPort?: 0;
+}
+export interface LocalGuiServer {
+    readonly url: string;
+    readonly host: typeof LOCAL_GUI_HOST;
+    readonly port: number;
+    readonly auth?: LocalGuiAuth;
+    close(): Promise<void>;
+}

package/dist/local-gui-contract.js

@@ -0,0 +1,5 @@
+export const LOCAL_GUI_HOST = "127.0.0.1";
+export const LOCAL_GUI_PORT = 11451;
+export const LOCAL_GUI_ORIGIN = `http://${LOCAL_GUI_HOST}:${LOCAL_GUI_PORT}`;
+export const LOCAL_GUI_SESSION_COOKIE = "worldengine_gui_session";
+export const LOCAL_GUI_MAX_JSON_BODY_BYTES = 4 * 1024 * 1024;

package/dist/local-gui-image-assets.d.ts

@@ -0,0 +1,17 @@
+export declare const LOCAL_GUI_MAX_IMAGE_ASSET_BYTES: number;
+export declare const LOCAL_GUI_MAX_IMAGE_ASSETS = 2048;
+export interface LocalGuiImageAsset {
+    readonly asset_path: string;
+    readonly mime: "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "image/avif";
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface LocalGuiImageAssetReadback extends LocalGuiImageAsset {
+    readonly bytes: Uint8Array;
+}
+type ImageMime = LocalGuiImageAsset["mime"];
+export declare function localGuiImageMimeForPath(path: string): ImageMime | undefined;
+export declare function localGuiImageBytesMatchMime(bytes: Uint8Array, mime: ImageMime): boolean;
+export declare function readLocalGuiImageAsset(projectRoot: string, assetPath: string): Promise<LocalGuiImageAssetReadback>;
+export declare function listLocalGuiImageAssets(projectRoot: string): Promise<readonly LocalGuiImageAsset[]>;
+export {};

package/dist/local-gui-image-assets.js

@@ -0,0 +1,96 @@
+import { lstat, readFile, readdir, stat } from "node:fs/promises";
+import { extname, isAbsolute, join } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { sha256Hex } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+export const LOCAL_GUI_MAX_IMAGE_ASSET_BYTES = 24 * 1024 * 1024;
+export const LOCAL_GUI_MAX_IMAGE_ASSETS = 2_048;
+const IMAGE_MIME_BY_EXTENSION = Object.freeze({
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".avif": "image/avif",
+});
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+function pathFailure(message) {
+    throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", message);
+}
+function normalizedAssetPath(value) {
+    if (typeof value !== "string" || !value.startsWith("assets/") || value.includes("\0") || value.includes("\\") || isAbsolute(value)) {
+        pathFailure("图片必须使用 assets/ 下的项目相对路径");
+    }
+    const parts = value.split("/");
+    if (parts.length < 2 || parts.some((part) => part === "" || part === "." || part === ".." || part.includes(":") || part.endsWith(".") || part.endsWith(" ") || WINDOWS_DEVICE_NAME.test(part))) {
+        pathFailure("图片资源路径无效");
+    }
+    return { assetPath: parts.join("/"), relativePath: parts.slice(1).join("/") };
+}
+export function localGuiImageMimeForPath(path) {
+    return IMAGE_MIME_BY_EXTENSION[extname(path).toLowerCase()];
+}
+export function localGuiImageBytesMatchMime(bytes, mime) {
+    if (mime === "image/png")
+        return bytes.length >= 8 && [137, 80, 78, 71, 13, 10, 26, 10].every((byte, index) => bytes[index] === byte);
+    if (mime === "image/jpeg")
+        return bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes.at(-2) === 0xff && bytes.at(-1) === 0xd9;
+    if (mime === "image/gif")
+        return bytes.length >= 6 && (Buffer.from(bytes.subarray(0, 6)).toString("ascii") === "GIF87a" || Buffer.from(bytes.subarray(0, 6)).toString("ascii") === "GIF89a");
+    if (mime === "image/webp")
+        return bytes.length >= 12 && Buffer.from(bytes.subarray(0, 4)).toString("ascii") === "RIFF" && Buffer.from(bytes.subarray(8, 12)).toString("ascii") === "WEBP";
+    return bytes.length >= 12 && Buffer.from(bytes.subarray(4, 8)).toString("ascii") === "ftyp" && ["avif", "avis"].includes(Buffer.from(bytes.subarray(8, 12)).toString("ascii"));
+}
+async function readValidatedImage(projectRoot, assetsRoot, assetPath) {
+    const normalized = normalizedAssetPath(assetPath);
+    const absolute = await assertSafeExistingProjectPath(projectRoot, join(assetsRoot, ...normalized.relativePath.split("/")));
+    const info = await stat(absolute);
+    const mime = localGuiImageMimeForPath(normalized.assetPath);
+    if (!info.isFile() || mime === undefined || info.size <= 0 || info.size > LOCAL_GUI_MAX_IMAGE_ASSET_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "图片资源格式或大小无效");
+    }
+    const bytes = new Uint8Array(await readFile(absolute));
+    if (bytes.byteLength > LOCAL_GUI_MAX_IMAGE_ASSET_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "图片内容超过本地 GUI 上限");
+    }
+    if (!localGuiImageBytesMatchMime(bytes, mime))
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "图片扩展名与内容不一致");
+    return { asset_path: normalized.assetPath, mime, size: bytes.byteLength, sha256: await sha256Hex(bytes), bytes };
+}
+export async function readLocalGuiImageAsset(projectRoot, assetPath) {
+    const assetsRoot = await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "scenario", "assets"));
+    return readValidatedImage(projectRoot, assetsRoot, assetPath);
+}
+export async function listLocalGuiImageAssets(projectRoot) {
+    const assetsRoot = await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "scenario", "assets"));
+    const images = [];
+    async function walk(directory, prefix) {
+        const canonical = await assertSafeExistingProjectPath(projectRoot, directory);
+        for (const entry of await readdir(canonical, { withFileTypes: true })) {
+            const absolute = join(canonical, entry.name);
+            const info = await lstat(absolute);
+            if (info.isSymbolicLink())
+                pathFailure("图片资源目录不能包含链接");
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            if (info.isDirectory()) {
+                await walk(absolute, relativePath);
+            }
+            else if (info.isFile() && localGuiImageMimeForPath(entry.name) !== undefined) {
+                if (images.length >= LOCAL_GUI_MAX_IMAGE_ASSETS)
+                    throw new AuthoringBridgeError("E_VALIDATION_FAILED", "图片资源数量超过本地 GUI 上限");
+                try {
+                    const { bytes: _bytes, ...image } = await readValidatedImage(projectRoot, assetsRoot, `assets/${relativePath}`);
+                    void _bytes;
+                    images.push(image);
+                }
+                catch (error) {
+                    if (error instanceof AuthoringBridgeError && error.code === "E_VALIDATION_FAILED")
+                        continue;
+                    throw error;
+                }
+            }
+        }
+    }
+    await walk(assetsRoot, "");
+    return images.sort((left, right) => left.asset_path.localeCompare(right.asset_path));
+}

package/dist/local-gui-preview-client.d.ts

@@ -0,0 +1,3 @@
+import type { PreviewSession } from "./preview-runtime.js";
+/** Node 作者工具对既有 GUI 的窄 adapter；本地 HttpOnly cookie 仅留在本调用内存。 */
+export declare function attachLocalGuiPreview(projectRoot: string, projectId: string, request?: typeof fetch): Promise<PreviewSession | null>;

package/dist/local-gui-preview-client.js

@@ -0,0 +1,111 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { request as httpRequest } from "node:http";
+import { LOCAL_GUI_ORIGIN, LOCAL_GUI_SESSION_COOKIE } from "./local-gui-contract.js";
+// Node fetch 会强制 sec-fetch-mode=cors；此受限本地 adapter 必须保留导航握手头。
+const requestLocalGui = ((input, init) => new Promise((resolve, reject) => {
+    const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    if (url.origin !== LOCAL_GUI_ORIGIN) {
+        reject(new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "GUI origin 无效"));
+        return;
+    }
+    const requestHeaders = {};
+    new Headers(init?.headers).forEach((value, key) => { requestHeaders[key] = value; });
+    const request = httpRequest(url, {
+        method: init?.method ?? "GET", headers: requestHeaders,
+        ...(init?.signal == null ? {} : { signal: init.signal }),
+    }, (incoming) => {
+        const chunks = [];
+        let size = 0;
+        incoming.on("data", (value) => {
+            size += value.length;
+            if (size > 256 * 1024) {
+                request.destroy(new AuthoringBridgeError("E_VALIDATION_FAILED", "GUI 响应过大"));
+            }
+            else
+                chunks.push(value);
+        });
+        incoming.on("error", reject);
+        incoming.on("end", () => {
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(incoming.headers)) {
+                if (Array.isArray(value))
+                    value.forEach((item) => headers.append(key, item));
+                else if (value !== undefined)
+                    headers.set(key, value);
+            }
+            const status = incoming.statusCode ?? 502;
+            resolve(new Response([204, 205, 304].includes(status) ? null : Buffer.concat(chunks), { status, headers }));
+        });
+    });
+    request.once("error", (error) => reject(new TypeError("GUI request failed", { cause: error })));
+    request.end(init?.body);
+}));
+/** Node 作者工具对既有 GUI 的窄 adapter；本地 HttpOnly cookie 仅留在本调用内存。 */
+export async function attachLocalGuiPreview(projectRoot, projectId, request = requestLocalGui) {
+    const signal = AbortSignal.timeout(25_000);
+    let response;
+    try {
+        response = await request(`${LOCAL_GUI_ORIGIN}/`, {
+            redirect: "manual", signal,
+            headers: { "sec-fetch-site": "none", "sec-fetch-mode": "navigate", "sec-fetch-dest": "document" },
+        });
+    }
+    catch (error) {
+        const cause = error instanceof Error && "cause" in error ? error.cause : undefined;
+        if (cause?.code === "ECONNREFUSED")
+            return null;
+        throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "既有 GUI 无法安全连接");
+    }
+    const setCookie = response.headers.get("set-cookie");
+    await response.body?.cancel();
+    const pair = setCookie?.split(";", 1)[0];
+    if (!response.ok || !pair?.startsWith(`${LOCAL_GUI_SESSION_COOKIE}=`) || !/;\s*HttpOnly(?:;|$)/iu.test(setCookie)) {
+        throw new AuthoringBridgeError("E_PROJECT_BUSY", "11451 不提供当前项目 GUI 会话，拒绝接管");
+    }
+    const call = async (path, action) => {
+        const reply = await request(`${LOCAL_GUI_ORIGIN}${path}`, {
+            method: action === undefined ? "GET" : "POST", redirect: "manual", signal,
+            headers: { cookie: pair, origin: LOCAL_GUI_ORIGIN, "content-type": "application/json" },
+            ...(action === undefined ? {} : { body: JSON.stringify({ action }) }),
+        });
+        const raw = await reply.text();
+        if (!reply.ok || raw.length > 256 * 1024)
+            throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "既有 GUI 预览请求失败");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "GUI 响应无效");
+        }
+        if (parsed.ok !== true)
+            throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "GUI 预览能力不可用");
+        return parsed.result;
+    };
+    const status = await call("/api/status");
+    if (status?.project_id !== projectId)
+        throw new AuthoringBridgeError("E_PROJECT_BUSY", "11451 属于另一项目，拒绝接管");
+    let preview = await call("/api/preview", "status");
+    if (preview === null || preview.state === "stopped" || preview.state === "failed") {
+        preview = await call("/api/preview", "start");
+    }
+    while (preview?.state === "starting") {
+        if (signal.aborted)
+            throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "GUI 预览就绪超时");
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        preview = await call("/api/preview", "status");
+    }
+    let url;
+    try {
+        url = new URL(preview?.url ?? "");
+    }
+    catch {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "GUI 预览地址无效");
+    }
+    if (preview?.state !== "running" || preview.project_root !== projectRoot || !preview.session_id
+        || url.protocol !== "http:" || url.hostname !== "localhost" || Number(url.port) !== preview.port
+        || !/^\/_worldengine_preview\/[a-f0-9]{32}\/$/u.test(url.pathname) || url.search || url.hash) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "GUI 预览未绑定当前项目");
+    }
+    return preview;
+}

package/dist/local-gui-score.d.ts

@@ -0,0 +1,72 @@
+import { type LocalStructuralProjection } from "@world-engines/authoring-ui/score";
+import type { LocalGuiAuth } from "./local-gui-auth.js";
+import type { LocalProjectHost } from "./project-host.js";
+export type LocalGuiScoreHost = Pick<LocalProjectHost, "inspect" | "readGraphProjectionReadback">;
+export interface LocalGuiScoreIdentity {
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly snapshot_digest: string;
+    readonly source_revision: number;
+    readonly source_digest: string;
+}
+export interface LocalGuiScoreResult {
+    readonly identity: LocalGuiScoreIdentity;
+    readonly local: LocalStructuralProjection;
+    readonly official: {
+        readonly status: "available" | "unavailable" | "error";
+        readonly structural_score: number | null;
+        readonly quality: null;
+        readonly base: null;
+        readonly radars: LocalGuiOfficialRadars | null;
+        readonly reason?: "authentication_required" | "remote_scenario_binding_required" | "remote_score_invalid" | "remote_score_unavailable";
+    };
+}
+export interface LocalGuiTagBenchmarkResult {
+    readonly identity: LocalGuiScoreIdentity;
+    readonly tag: string;
+    readonly status: "available" | "unavailable" | "error";
+    readonly benchmark: Readonly<{
+        tag: string;
+        model: string;
+        epoch: number;
+    }> | null;
+    readonly radars: LocalGuiBenchmarkRadars | null;
+    /** 与 benchmark 同一次响应读取的正式 self 快照，前端不得混用另一请求的正式画像。 */
+    readonly official: LocalGuiScoreResult["official"];
+    readonly comparison_available: boolean;
+    readonly reason?: "authentication_required" | "remote_scenario_binding_required" | "remote_score_invalid" | "remote_score_unavailable" | "benchmark_updating" | "score_benchmark_identity_unproven";
+}
+interface LocalGuiOfficialAxis {
+    readonly key: string;
+    readonly self: number | null;
+    readonly eligible: boolean;
+}
+interface LocalGuiOfficialProfile {
+    readonly model_version: string;
+    readonly source_revision: string;
+    readonly ranking_epoch: number | null;
+    readonly axes: readonly LocalGuiOfficialAxis[];
+}
+export interface LocalGuiOfficialRadars {
+    readonly story: LocalGuiOfficialProfile | null;
+    readonly presentation: LocalGuiOfficialProfile | null;
+}
+interface LocalGuiBenchmarkAxis {
+    readonly key: string;
+    readonly mean: number | null;
+    readonly median: number | null;
+    readonly sample_state: "available" | "insufficient";
+}
+interface LocalGuiBenchmarkProfile {
+    readonly model: string;
+    readonly epoch: number;
+    readonly axes: readonly LocalGuiBenchmarkAxis[];
+}
+export interface LocalGuiBenchmarkRadars {
+    readonly story: LocalGuiBenchmarkProfile;
+    readonly presentation: LocalGuiBenchmarkProfile;
+}
+export declare function readLocalGuiScore(host: LocalGuiScoreHost): Promise<LocalGuiScoreResult>;
+export declare function readLocalGuiOfficialScore(auth: LocalGuiAuth | undefined): Promise<LocalGuiScoreResult["official"]>;
+export declare function readLocalGuiTagBenchmark(host: LocalGuiScoreHost, tag: string, auth?: LocalGuiAuth): Promise<LocalGuiTagBenchmarkResult>;
+export {};

package/dist/local-gui-score.js

@@ -0,0 +1,184 @@
+import { computeLocalStructuralProjection, } from "@world-engines/authoring-ui/score";
+import { PRESENTATION_SCORE_AXES, STORY_SCORE_AXES } from "@world-engines/authoring-ui/score-presentation";
+import { isKnownScenarioTag } from "@world-engines/authoring-ui/score-tags";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+function description(metadata) {
+    if (typeof metadata.description === "string")
+        return metadata.description;
+    const nested = metadata.metadata;
+    return typeof nested === "object" && nested !== null && !Array.isArray(nested)
+        && typeof nested.description === "string"
+        ? nested.description
+        : "";
+}
+function identity(status, graph) {
+    if (status.project_revision !== graph.project_revision)
+        throw Object.assign(new Error("评分读取期间项目 revision 已变化"), { code: "E_STALE_PROJECT_REVISION" });
+    return {
+        project_id: status.project_id,
+        project_revision: status.project_revision,
+        snapshot_digest: status.snapshot_digest,
+        source_revision: graph.project_revision,
+        source_digest: graph.source_sha256,
+    };
+}
+export async function readLocalGuiScore(host) {
+    const graph = await host.readGraphProjectionReadback();
+    const status = await host.inspect();
+    const freshIdentity = identity(status, graph);
+    return {
+        identity: freshIdentity,
+        local: computeLocalStructuralProjection({
+            entities: graph.authoring.entities,
+            relations: graph.authoring.relations,
+            description: description(graph.authoring.metadata),
+            source_revision: graph.project_revision,
+            source_digest: graph.source_sha256,
+        }),
+        official: { status: "unavailable", structural_score: null, quality: null, base: null, radars: null, reason: "authentication_required" },
+    };
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function finiteScore(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100 ? value : null;
+}
+async function boundedRemoteScore(auth, request) {
+    let timer;
+    try {
+        return await Promise.race([
+            auth.requestScore(request),
+            new Promise((_resolve, reject) => { timer = setTimeout(() => reject(Object.assign(new Error("remote score timeout"), { code: "E_OPERATION_UNCERTAIN" })), 5_000); }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function scoreValue(value) {
+    return value === null ? null : typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100 ? value : undefined;
+}
+function officialRadars(value) {
+    const root = record(value);
+    if (root === undefined)
+        return null;
+    const profile = (candidate, expected) => {
+        if (candidate === null)
+            return null;
+        const item = record(candidate);
+        if (item === undefined || !Array.isArray(item.axes) || item.axes.length !== expected.length)
+            return undefined;
+        if (typeof item.model_version !== "string" || item.model_version.length === 0 || typeof item.source_revision !== "string" || item.source_revision.length === 0)
+            return undefined;
+        const rankingEpoch = item.ranking_epoch === undefined || item.ranking_epoch === null ? null
+            : Number.isSafeInteger(item.ranking_epoch) && item.ranking_epoch >= 0 ? item.ranking_epoch : undefined;
+        if (rankingEpoch === undefined)
+            return undefined;
+        const expectedKeys = new Set(expected.map(({ key }) => key));
+        const seen = new Set();
+        const axes = [];
+        for (const candidateAxis of item.axes) {
+            const axis = record(candidateAxis);
+            if (axis === undefined || typeof axis.key !== "string" || !expectedKeys.has(axis.key) || seen.has(axis.key))
+                return undefined;
+            seen.add(axis.key);
+            if (typeof axis.eligible !== "boolean")
+                return undefined;
+            const score = scoreValue(axis.score);
+            if (score === undefined || score === null)
+                return undefined;
+            axes.push({ key: axis.key, self: axis.eligible ? score : null, eligible: axis.eligible });
+        }
+        return { model_version: item.model_version, source_revision: item.source_revision, ranking_epoch: rankingEpoch, axes };
+    };
+    const story = profile(root.story, STORY_SCORE_AXES);
+    const presentation = profile(root.presentation, PRESENTATION_SCORE_AXES);
+    if (story === undefined || presentation === undefined)
+        return null;
+    return { story, presentation };
+}
+function benchmarkRadars(value) {
+    const root = record(value);
+    if (root === undefined)
+        return null;
+    const profile = (candidate, expected) => {
+        const item = record(candidate);
+        if (item === undefined || typeof item.model !== "string" || item.model.length === 0 || !Number.isSafeInteger(item.epoch) || item.epoch < 0 || !Array.isArray(item.axes) || item.axes.length !== expected.length)
+            return undefined;
+        const expectedKeys = new Set(expected.map(({ key }) => key));
+        const seen = new Set();
+        const axes = [];
+        for (const candidateAxis of item.axes) {
+            const axis = record(candidateAxis);
+            if (axis === undefined || typeof axis.key !== "string" || !expectedKeys.has(axis.key) || seen.has(axis.key))
+                return undefined;
+            seen.add(axis.key);
+            if (axis.sample_state !== "available" && axis.sample_state !== "insufficient")
+                return undefined;
+            const mean = scoreValue(axis.mean);
+            const median = axis.median === undefined ? null : scoreValue(axis.median);
+            if (mean === undefined || median === undefined || (axis.sample_state === "available" && mean === null) || (axis.sample_state === "insufficient" && (mean !== null || median !== null)))
+                return undefined;
+            axes.push({ key: axis.key, mean, median, sample_state: axis.sample_state });
+        }
+        return { model: item.model, epoch: item.epoch, axes };
+    };
+    const story = profile(root.story, STORY_SCORE_AXES);
+    const presentation = profile(root.presentation, PRESENTATION_SCORE_AXES);
+    if (story === undefined || presentation === undefined || story.model !== presentation.model || story.epoch !== presentation.epoch)
+        return null;
+    return { story, presentation };
+}
+function unavailableReason(error) {
+    return error instanceof AuthoringBridgeError && error.code === "E_AUTH_REQUIRED" ? "authentication_required"
+        : error instanceof AuthoringBridgeError && error.code === "E_REFERENCE_MISSING" ? "remote_scenario_binding_required"
+            : "remote_score_unavailable";
+}
+export async function readLocalGuiOfficialScore(auth) {
+    if (auth === undefined)
+        return { status: "unavailable", structural_score: null, quality: null, base: null, radars: null, reason: "authentication_required" };
+    try {
+        const response = await boundedRemoteScore(auth, { kind: "score" });
+        const body = record(response.body);
+        if (body === undefined)
+            return { status: "error", structural_score: null, quality: null, base: null, radars: null, reason: "remote_score_invalid" };
+        const structuralScore = finiteScore(body.structural_score);
+        if (structuralScore === null)
+            return { status: "error", structural_score: null, quality: null, base: null, radars: null, reason: "remote_score_invalid" };
+        return { status: "available", structural_score: structuralScore, quality: null, base: null, radars: officialRadars(body.radars) };
+    }
+    catch (error) {
+        return { status: "unavailable", structural_score: null, quality: null, base: null, radars: null, reason: unavailableReason(error) };
+    }
+}
+export async function readLocalGuiTagBenchmark(host, tag, auth) {
+    if (!isKnownScenarioTag(tag)) {
+        throw Object.assign(new Error("tag 无效"), { code: "E_SCHEMA_INVALID" });
+    }
+    const score = await readLocalGuiScore(host);
+    if (auth === undefined)
+        return { identity: score.identity, tag, status: "unavailable", benchmark: null, radars: null, official: score.official, comparison_available: false, reason: "authentication_required" };
+    try {
+        const [official, response] = await Promise.all([
+            readLocalGuiOfficialScore(auth),
+            boundedRemoteScore(auth, { kind: "tag-benchmark", tag }),
+        ]);
+        const body = record(response.body);
+        const radars = body === undefined || body.tag !== tag ? null : benchmarkRadars(body);
+        const comparable = radars !== null && official.radars?.story !== null && official.radars?.presentation !== null
+            && official.radars?.story !== undefined && official.radars?.presentation !== undefined
+            && official.radars.story.model_version === radars.story.model
+            && official.radars.presentation.model_version === radars.presentation.model
+            && official.radars.story.ranking_epoch === radars.story.epoch
+            && official.radars.presentation.ranking_epoch === radars.presentation.epoch;
+        return radars === null
+            ? { identity: score.identity, tag, status: "error", benchmark: null, radars: null, official, comparison_available: false, reason: "remote_score_invalid" }
+            : { identity: score.identity, tag, status: "available", benchmark: { tag, model: radars.story.model, epoch: radars.story.epoch }, radars, official, comparison_available: comparable, ...(comparable ? {} : { reason: "score_benchmark_identity_unproven" }) };
+    }
+    catch (error) {
+        const reason = error instanceof AuthoringBridgeError && error.code === "E_OPERATION_UNCERTAIN" && error.message.includes("基准正在更新") ? "benchmark_updating" : unavailableReason(error);
+        return { identity: score.identity, tag, status: "unavailable", benchmark: null, radars: null, official: score.official, comparison_available: false, reason };
+    }
+}

package/dist/local-gui-server.d.ts

@@ -0,0 +1,10 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type LocalGuiServer, type StartLocalGuiServerOptions } from "./local-gui-contract.js";
+/** @internal 供真实 HTTP Range 回归复用；调用方仍负责 session/capability authorization。 */
+export declare function sendPreviewAsset(request: IncomingMessage, response: ServerResponse, asset: Readonly<{
+    mime: string;
+    sha256: string;
+    bytes: Uint8Array;
+}>): void;
+/** 启动绑定一个 canonical project root 的 npm 包内本地 GUI；浏览器不能改选 root。 */
+export declare function startLocalGuiServer(root: string, options?: StartLocalGuiServerOptions): Promise<LocalGuiServer>;