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

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

@@ -0,0 +1,17 @@
+export type LocalGuiVersionState = "checking" | "up_to_date" | "update_available" | "unpublished" | "error";
+export interface LocalGuiVersionStatus {
+    readonly status: LocalGuiVersionState;
+    readonly current: string;
+    readonly latest?: string;
+}
+export interface LocalGuiVersionChecker {
+    /** 同步读取当前进程内缓存；不会因 HTTP 请求再次访问 registry。 */
+    get(): LocalGuiVersionStatus;
+    /** 每个 checker 最多执行一次异步检查，后续调用复用同一结果。 */
+    check(): Promise<LocalGuiVersionStatus>;
+}
+export interface LocalGuiVersionOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly timeoutMs?: number;
+}
+export declare function createLocalGuiVersionChecker(options?: LocalGuiVersionOptions): LocalGuiVersionChecker;

package/dist/local-gui-version.js

@@ -0,0 +1,147 @@
+import { readFileSync } from "node:fs";
+const PACKAGE_NAME = "@world-engines/project-host";
+const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@world-engines%2fproject-host/latest";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_METADATA_BYTES = 64 * 1024;
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+function parseSemver(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const match = SEMVER_PATTERN.exec(value);
+    if (match === null)
+        return undefined;
+    return {
+        core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+        prerelease: match[4]?.split(".") ?? [],
+    };
+}
+function compareSemver(leftValue, rightValue) {
+    const left = parseSemver(leftValue);
+    const right = parseSemver(rightValue);
+    if (left === undefined || right === undefined)
+        throw new Error("local_gui_version_semver_invalid");
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left.core[index] - right.core[index];
+        if (difference !== 0n)
+            return difference < 0n ? -1 : 1;
+    }
+    if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+        return left.prerelease.length === right.prerelease.length ? 0 : left.prerelease.length === 0 ? 1 : -1;
+    }
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        const a = left.prerelease[index];
+        const b = right.prerelease[index];
+        if (a === undefined || b === undefined)
+            return a === b ? 0 : a === undefined ? -1 : 1;
+        if (a === b)
+            continue;
+        const aNumeric = /^\d+$/u.test(a);
+        const bNumeric = /^\d+$/u.test(b);
+        if (aNumeric && bNumeric)
+            return BigInt(a) < BigInt(b) ? -1 : 1;
+        if (aNumeric !== bNumeric)
+            return aNumeric ? -1 : 1;
+        return a < b ? -1 : 1;
+    }
+    return 0;
+}
+function installedVersion() {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    }
+    catch {
+        throw new Error("local_gui_installed_package_unavailable");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("local_gui_installed_package_invalid");
+    const manifest = value;
+    if (manifest.name !== PACKAGE_NAME || parseSemver(manifest.version) === undefined)
+        throw new Error("local_gui_installed_package_invalid");
+    return manifest.version;
+}
+async function boundedMetadata(response) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_METADATA_BYTES)
+        throw new Error("local_gui_version_metadata_too_large");
+    if (response.body === null)
+        throw new Error("local_gui_version_metadata_invalid");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const item = await reader.read();
+        if (item.done)
+            break;
+        total += item.value.byteLength;
+        if (!Number.isSafeInteger(total) || total > MAX_METADATA_BYTES) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error("local_gui_version_metadata_too_large");
+        }
+        chunks.push(item.value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new Error("local_gui_version_metadata_invalid");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("local_gui_version_metadata_invalid");
+    return value;
+}
+export function createLocalGuiVersionChecker(options = {}) {
+    const request = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (typeof request !== "function" || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000) {
+        throw new Error("local_gui_version_options_invalid");
+    }
+    const current = installedVersion();
+    let cached = Object.freeze({ status: "checking", current });
+    let checkPromise;
+    const check = async () => {
+        if (checkPromise !== undefined)
+            return checkPromise;
+        checkPromise = (async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await request(REGISTRY_LATEST_URL, {
+                    method: "GET",
+                    redirect: "error",
+                    headers: { accept: "application/json" },
+                    signal: controller.signal,
+                });
+                if (response.status === 404)
+                    return Object.freeze({ status: "unpublished", current });
+                if (response.status !== 200)
+                    return Object.freeze({ status: "error", current });
+                const metadata = await boundedMetadata(response);
+                if (metadata.name !== PACKAGE_NAME || typeof metadata.version !== "string" || parseSemver(metadata.version) === undefined) {
+                    return Object.freeze({ status: "error", current });
+                }
+                const latest = metadata.version;
+                return Object.freeze({ status: compareSemver(current, latest) < 0 ? "update_available" : "up_to_date", current, latest });
+            }
+            catch {
+                return Object.freeze({ status: "error", current });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        })().then((result) => {
+            cached = result;
+            return result;
+        });
+        return checkPromise;
+    };
+    return Object.freeze({ get: () => cached, check });
+}

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

@@ -0,0 +1,14 @@
+export type LocalGuiFileArea = "view" | "docs";
+export interface LocalGuiFileEntry {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface LocalGuiFileReadback extends LocalGuiFileEntry {
+    readonly content: string;
+}
+export declare const LOCAL_GUI_MAX_FILE_BYTES: number;
+export declare function readLocalGuiFile(projectRoot: string, area: LocalGuiFileArea, path: string): Promise<LocalGuiFileReadback>;
+export declare function listLocalGuiFiles(projectRoot: string, area: LocalGuiFileArea): Promise<readonly LocalGuiFileEntry[]>;
+/** 同一进程内所有 GUI 对同一文件串行 CAS；外部编辑器仍由 rename 前二次摘要检查检测。 */
+export declare function writeLocalGuiViewFile(projectRoot: string, path: string, content: string, expectedSha256: string): Promise<LocalGuiFileReadback>;

package/dist/local-gui-workspace.js

@@ -0,0 +1,171 @@
+import { randomBytes } from "node:crypto";
+import { lstat, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { sha256Hex } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, assertSafeProjectParent } from "./safe-project-path.js";
+export const LOCAL_GUI_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_LISTED_FILES = 4_096;
+const EXCLUDED_DIRECTORY_NAMES = new Set([".git", ".vite", ".worldengine", "coverage", "dist", "node_modules"]);
+const TEXT_EXTENSIONS = new Set([
+    ".cjs", ".css", ".graphql", ".html", ".js", ".json", ".jsx", ".md", ".mjs",
+    ".scss", ".svg", ".toml", ".ts", ".tsx", ".txt", ".xml", ".yaml", ".yml",
+]);
+const SENSITIVE_NAMES = new Set([
+    ".dev.vars", ".envrc", ".git-credentials", ".netrc", ".npmrc", ".pypirc", ".yarnrc", ".yarnrc.yml",
+    "auth.json", "credentials", "credentials.json", "private-key.json", "secrets.json", "secrets.yaml", "secrets.yml",
+    "service-account.json",
+]);
+const WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+function isSensitiveName(name) {
+    const lower = name.toLowerCase();
+    return lower === ".env" || lower.startsWith(".env.") || SENSITIVE_NAMES.has(lower)
+        || /(?:^|[._-])(?:credentials?|private[-_]?key|secrets?|service[-_]?account)(?:[._-]|$)/i.test(lower);
+}
+function assertSafeSegment(part) {
+    if (part === "" || part === "." || part === ".." || part.includes(":")) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件路径无效");
+    }
+    if (part.endsWith(".") || part.endsWith(" ") || WINDOWS_DEVICE_NAME.test(part)) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件路径无效");
+    }
+    if (isSensitiveName(part))
+        throw new AuthoringBridgeError("E_REMOTE_FORBIDDEN", "拒绝访问敏感配置文件");
+}
+function normalizeRelativePath(path) {
+    if (typeof path !== "string" || path === "" || isAbsolute(path) || path.includes("\0")) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件路径必须是项目相对路径");
+    }
+    const parts = path.split(/[\\/]+/);
+    for (const part of parts)
+        assertSafeSegment(part);
+    if (parts.slice(0, -1).some((part) => EXCLUDED_DIRECTORY_NAMES.has(part.toLowerCase()))) {
+        throw new AuthoringBridgeError("E_REMOTE_FORBIDDEN", "拒绝访问生成目录或依赖目录");
+    }
+    if (!TEXT_EXTENSIONS.has(extname(parts.at(-1) ?? "").toLowerCase())) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "只允许文本源码与文档文件");
+    }
+    return parts.join("/");
+}
+function areaDirectory(projectRoot, area) {
+    if (area !== "view" && area !== "docs") {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "未知文件区域");
+    }
+    return join(projectRoot, area);
+}
+function within(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+async function readRegularUtf8(projectRoot, root, path) {
+    const normalized = normalizeRelativePath(path);
+    const absolute = await assertSafeExistingProjectPath(projectRoot, join(root, ...normalized.split("/")));
+    if (!within(root, absolute))
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件路径越界");
+    const info = await stat(absolute);
+    if (!info.isFile() || info.size > LOCAL_GUI_MAX_FILE_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "文件不是可编辑的普通文本文件");
+    }
+    const bytes = new Uint8Array(await readFile(absolute));
+    const content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return { path: normalized, size: bytes.byteLength, sha256: await sha256Hex(bytes), content };
+}
+export async function readLocalGuiFile(projectRoot, area, path) {
+    const root = await assertSafeExistingProjectPath(projectRoot, areaDirectory(projectRoot, area));
+    return readRegularUtf8(projectRoot, root, path);
+}
+export async function listLocalGuiFiles(projectRoot, area) {
+    const root = await assertSafeExistingProjectPath(projectRoot, areaDirectory(projectRoot, area));
+    const files = [];
+    async function walk(directory, prefix) {
+        const canonical = await assertSafeExistingProjectPath(projectRoot, directory);
+        if (!within(root, canonical))
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件目录越界");
+        for (const entry of await readdir(canonical, { withFileTypes: true })) {
+            if (files.length >= MAX_LISTED_FILES)
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "文件数量超过本地 GUI 上限");
+            const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const absolute = join(canonical, entry.name);
+            const info = await lstat(absolute);
+            if (info.isSymbolicLink())
+                throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "拒绝链接文件");
+            if (info.isDirectory()) {
+                if (!EXCLUDED_DIRECTORY_NAMES.has(entry.name.toLowerCase()))
+                    await walk(absolute, path);
+            }
+            else if (info.isFile() && info.size <= LOCAL_GUI_MAX_FILE_BYTES && !isSensitiveName(entry.name) && TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+                const bytes = new Uint8Array(await readFile(await assertSafeExistingProjectPath(projectRoot, absolute)));
+                files.push({ path, size: bytes.byteLength, sha256: await sha256Hex(bytes) });
+            }
+        }
+    }
+    await walk(root, "");
+    return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function writeLocalGuiViewFileUnlocked(projectRoot, path, content, expectedSha256) {
+    if (typeof content !== "string" || Buffer.byteLength(content, "utf8") > LOCAL_GUI_MAX_FILE_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "文件内容超过本地 GUI 上限");
+    }
+    if (!/^[a-f0-9]{64}$/.test(expectedSha256)) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "expected_sha256 无效");
+    }
+    const root = await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "view"));
+    const normalized = normalizeRelativePath(path);
+    const target = await assertSafeExistingProjectPath(projectRoot, join(root, ...normalized.split("/")));
+    if (!within(root, target))
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "文件路径越界");
+    const before = await readRegularUtf8(projectRoot, root, normalized);
+    if (before.sha256 !== expectedSha256) {
+        const error = new Error("View 文件已变化");
+        error.code = "E_FILE_CHANGED";
+        throw error;
+    }
+    const bytes = new TextEncoder().encode(content);
+    const temp = join(resolve(target, ".."), `.worldengine-gui-${randomBytes(16).toString("hex")}${extname(target)}.tmp`);
+    await assertSafeProjectParent(projectRoot, temp);
+    try {
+        const handle = await open(temp, "wx");
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        const immediatelyBeforeRename = await readRegularUtf8(projectRoot, root, normalized);
+        if (immediatelyBeforeRename.sha256 !== expectedSha256) {
+            const error = new Error("View 文件已变化");
+            error.code = "E_FILE_CHANGED";
+            throw error;
+        }
+        await assertSafeProjectParent(projectRoot, target);
+        await rename(temp, target);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+    const readback = await readRegularUtf8(projectRoot, root, normalized);
+    const writtenSha256 = await sha256Hex(bytes);
+    if (readback.sha256 !== writtenSha256 || readback.content !== content) {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "View 文件写入回读不一致");
+    }
+    return readback;
+}
+const VIEW_WRITE_TAILS = new Map();
+/** 同一进程内所有 GUI 对同一文件串行 CAS；外部编辑器仍由 rename 前二次摘要检查检测。 */
+export async function writeLocalGuiViewFile(projectRoot, path, content, expectedSha256) {
+    const key = `${resolve(projectRoot).toLowerCase()}\0${path.replaceAll("\\", "/").toLowerCase()}`;
+    const previous = VIEW_WRITE_TAILS.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolvePromise) => { release = resolvePromise; });
+    VIEW_WRITE_TAILS.set(key, current);
+    await previous;
+    try {
+        return await writeLocalGuiViewFileUnlocked(projectRoot, path, content, expectedSha256);
+    }
+    finally {
+        release();
+        if (VIEW_WRITE_TAILS.get(key) === current)
+            VIEW_WRITE_TAILS.delete(key);
+    }
+}

package/dist/local-model-settings.d.ts

@@ -0,0 +1,28 @@
+import { type LocalGuiFileReadback } from "./local-gui-workspace.js";
+export interface LocalModelSettings {
+    readonly schema_version: 1;
+    readonly model: string;
+}
+export interface LocalModelSettingsReadback extends LocalGuiFileReadback {
+    readonly settings: LocalModelSettings;
+}
+export interface LocalAccountChatCatalog {
+    readonly accountIdentity: string;
+    readonly catalogDigest: string;
+    readonly models: readonly Readonly<{
+        model: string;
+        max_output_tokens: number;
+    }>[];
+}
+export declare function parseLocalModelSettings(value: unknown): LocalModelSettings;
+export declare function readLocalModelSettings(projectRoot: string): Promise<LocalModelSettingsReadback>;
+export declare function writeLocalModelSettings(projectRoot: string, input: Readonly<{
+    model: unknown;
+    expected_sha256: unknown;
+}>): Promise<LocalModelSettingsReadback>;
+/** 仅 Node Host 调用固定 11450 proxy；返回的 account identity 只用于服务端 CAS，绝不交给 GUI/iframe。 */
+export declare function fetchLocalAccountChatCatalog(input: Readonly<{
+    projectRoot: string;
+    projectId: string;
+    fetcher?: typeof globalThis.fetch;
+}>): Promise<LocalAccountChatCatalog>;

package/dist/local-model-settings.js

@@ -0,0 +1,124 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { readLocalGuiFile, writeLocalGuiViewFile } from "./local-gui-workspace.js";
+import { LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN, resolveLocalAccountProjectBinding } from "./account-model-proxy.js";
+const PREVIEW_CONFIG_PATH = "preview.config.json";
+const MAX_CATALOG_BYTES = 64 * 1024;
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+async function boundedJson(response, limit) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit)
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录响应过大");
+    if (response.body === null)
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录响应无效");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const next = await reader.read();
+        if (next.done)
+            break;
+        size += next.value.byteLength;
+        if (size > limit) {
+            await reader.cancel();
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录响应过大");
+        }
+        chunks.push(next.value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        const value = object(JSON.parse(new TextDecoder().decode(bytes)));
+        if (value !== undefined)
+            return value;
+    }
+    catch { /* fail closed below */ }
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录响应无效");
+}
+export function parseLocalModelSettings(value) {
+    const config = object(value);
+    if (config === undefined || Object.keys(config).sort().join("\0") !== "model\0schema_version"
+        || config.schema_version !== 1 || typeof config.model !== "string" || !MODEL.test(config.model)) {
+        fail("E_PREVIEW_MODEL_CONFIG_REQUIRED", "view/preview.config.json 无效");
+    }
+    return Object.freeze({ schema_version: 1, model: config.model });
+}
+export async function readLocalModelSettings(projectRoot) {
+    const file = await readLocalGuiFile(projectRoot, "view", PREVIEW_CONFIG_PATH);
+    let value;
+    try {
+        value = JSON.parse(file.content);
+    }
+    catch {
+        fail("E_PREVIEW_MODEL_CONFIG_REQUIRED", "view/preview.config.json 缺失或无效");
+    }
+    return Object.freeze({ ...file, settings: parseLocalModelSettings(value) });
+}
+export async function writeLocalModelSettings(projectRoot, input) {
+    if (typeof input.model !== "string" || !MODEL.test(input.model) || typeof input.expected_sha256 !== "string") {
+        fail("E_SCHEMA_INVALID", "模型设置字段无效");
+    }
+    const settings = Object.freeze({ schema_version: 1, model: input.model });
+    const file = await writeLocalGuiViewFile(projectRoot, PREVIEW_CONFIG_PATH, `${JSON.stringify(settings)}\n`, input.expected_sha256);
+    return Object.freeze({ ...file, settings });
+}
+/** 仅 Node Host 调用固定 11450 proxy；返回的 account identity 只用于服务端 CAS，绝不交给 GUI/iframe。 */
+export async function fetchLocalAccountChatCatalog(input) {
+    const binding = await resolveLocalAccountProjectBinding(input.projectRoot, input.projectId);
+    const proxy = new URL(LOCAL_ACCOUNT_MODEL_PROXY_ORIGIN);
+    const fetcher = input.fetcher ?? globalThis.fetch;
+    const headers = { Host: proxy.host, "x-worldengine-project-id": input.projectId, "x-worldengine-project-root-sha256": binding.rootIdentity };
+    let sessionResponse;
+    try {
+        sessionResponse = await fetcher(`${proxy.origin}/v1/session`, { headers, signal: AbortSignal.timeout(10_000) });
+    }
+    catch {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "账户模型代理暂时不可用");
+    }
+    if (sessionResponse.status === 401)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "请先登录账户");
+    if (!sessionResponse.ok)
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "账户模型代理暂时不可用");
+    const session = await boundedJson(sessionResponse, MAX_CATALOG_BYTES);
+    const identity = session.account_identity;
+    if (session.project_id !== input.projectId || typeof identity !== "string" || !/^[a-f0-9]{64}$/u.test(identity))
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型 session 无效");
+    let catalogResponse;
+    try {
+        catalogResponse = await fetcher(`${proxy.origin}/v1/chat/catalog`, { headers: { ...headers, "x-worldengine-account-identity": identity }, signal: AbortSignal.timeout(10_000) });
+    }
+    catch {
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "账户模型目录暂时不可用");
+    }
+    if (catalogResponse.status === 401)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "请先登录账户");
+    if (catalogResponse.status === 409)
+        throw new AuthoringBridgeError("E_ACCOUNT_CHANGED", "账户已变化，请重新读取模型目录");
+    if (!catalogResponse.ok)
+        throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "账户模型目录暂时不可用");
+    const catalog = await boundedJson(catalogResponse, MAX_CATALOG_BYTES);
+    if (catalog.project_id !== input.projectId || typeof catalog.principal_id !== "string" || catalog.principal_id.length === 0 || typeof catalog.catalog_digest !== "string" || !/^[a-f0-9]{64}$/u.test(catalog.catalog_digest) || !Array.isArray(catalog.models))
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录响应无效");
+    const seen = new Set();
+    const models = catalog.models.flatMap((entry) => {
+        const item = object(entry);
+        const model = item?.model;
+        const max = item?.max_output_tokens;
+        if (typeof model !== "string" || !MODEL.test(model) || seen.has(model) || typeof max !== "number" || !Number.isSafeInteger(max) || max < 1 || max > 1_000_000)
+            return [];
+        seen.add(model);
+        return [Object.freeze({ model, max_output_tokens: max })];
+    });
+    if (models.length !== catalog.models.length)
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "账户模型目录包含无效条目");
+    return Object.freeze({ accountIdentity: identity, catalogDigest: catalog.catalog_digest, models: Object.freeze(models) });
+}

package/dist/local-preview-assets.d.ts

@@ -0,0 +1,28 @@
+export interface LocalPreviewFrozenAsset {
+    readonly id: string;
+    readonly filename: string;
+    readonly mime: string;
+    readonly size: number;
+    /** 同次双读绑定的 manifest snapshot 时间，不是作者原始媒体创建时间。 */
+    readonly createdTs: number;
+    readonly source: "capture";
+    /** Host 用于拒绝旧 catalog entry；不应转发给不可信 iframe。 */
+    readonly sha256: string;
+}
+export interface LocalPreviewResolvedAssetBytes {
+    readonly id: string;
+    readonly mime: string;
+    readonly sha256: string;
+    readonly bytes: Uint8Array;
+}
+export interface LocalPreviewFrozenAssetResolver {
+    /** 仅返回媒体元数据，不返回作者路径或源 base64。 */
+    list(): readonly LocalPreviewFrozenAsset[];
+    /** 仅供 Host/父页面消费，调用方必须传回同次 list 得到的 hash fence。 */
+    resolveBytes(asset: Readonly<Pick<LocalPreviewFrozenAsset, "id" | "sha256">>): LocalPreviewResolvedAssetBytes;
+}
+/**
+ * 从 LocalPreviewRuntime.readProjectionSnapshot 的冻结 resource_refs 建立 Host-only catalog。
+ * 不读取作者文件系统路径，也不接受 URI；所有媒体字节都来自同一 immutable capture。
+ */
+export declare function localPreviewAssetsFromRuntimeSnapshot(snapshot: unknown): LocalPreviewFrozenAssetResolver;

package/dist/local-preview-assets.js

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const SHA256 = /^[a-f0-9]{64}$/u;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+const SAFE_MEDIA_TYPES = new Set([
+    "image/avif",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "audio/aac",
+    "audio/flac",
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/ogg",
+    "audio/wav",
+    "audio/webm",
+    "video/mp4",
+    "video/ogg",
+    "video/webm",
+]);
+function fail(message) {
+    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+}
+function record(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(message);
+    return value;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function resourcePath(value, seen) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 1024 || value.startsWith("/")
+        || value.includes("\\") || value.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+        || seen.has(value)) {
+        fail("本地 Preview capture resource path 无效或重复");
+    }
+    seen.add(value);
+    return value;
+}
+function mediaType(value) {
+    if (typeof value !== "string" || !SAFE_MEDIA_TYPES.has(value)) {
+        fail("本地 Preview capture resource media_type 不受支持");
+    }
+    return value;
+}
+function canonicalBase64(value) {
+    if (typeof value !== "string" || !BASE64.test(value))
+        fail("本地 Preview capture resource base64 无效");
+    const bytes = new Uint8Array(Buffer.from(value, "base64"));
+    if (Buffer.from(bytes).toString("base64") !== value)
+        fail("本地 Preview capture resource base64 非 canonical");
+    return bytes;
+}
+function assetId(captureSha256, path) {
+    return `local-preview-asset:v1:${captureSha256}:${sha256(path).slice(0, 32)}`;
+}
+/**
+ * 从 LocalPreviewRuntime.readProjectionSnapshot 的冻结 resource_refs 建立 Host-only catalog。
+ * 不读取作者文件系统路径，也不接受 URI；所有媒体字节都来自同一 immutable capture。
+ */
+export function localPreviewAssetsFromRuntimeSnapshot(snapshot) {
+    const root = record(snapshot, "本地 Preview asset snapshot 无效");
+    if (root.kind !== "worldengine.local-preview-projection/v1" || root.development_preview !== true) {
+        fail("本地 Preview asset snapshot identity 无效");
+    }
+    const identity = record(root.capture_identity, "本地 Preview asset capture identity 缺失");
+    const captureSha256 = identity.capture_sha256;
+    if (typeof captureSha256 !== "string" || !SHA256.test(captureSha256))
+        fail("本地 Preview asset capture hash 无效");
+    const snapshotUpdatedAtMs = identity.snapshot_updated_at_ms;
+    if (typeof snapshotUpdatedAtMs !== "number" || !Number.isSafeInteger(snapshotUpdatedAtMs) || snapshotUpdatedAtMs < 0) {
+        fail("本地 Preview asset snapshot timestamp 无效");
+    }
+    const projection = record(root.source_projection, "本地 Preview asset source projection 缺失");
+    const refs = projection.resource_refs;
+    if (!Array.isArray(refs))
+        fail("本地 Preview asset resource_refs 必须为数组");
+    const paths = new Set();
+    const ids = new Set();
+    const captured = refs.map((candidate) => {
+        const ref = record(candidate, "本地 Preview capture resource 无效");
+        if (Object.keys(ref).some((key) => key !== "path" && key !== "media_type" && key !== "bytes_base64")) {
+            fail("本地 Preview capture resource 包含未知字段");
+        }
+        const path = resourcePath(ref.path, paths);
+        const mime = mediaType(ref.media_type);
+        const bytes = canonicalBase64(ref.bytes_base64);
+        const id = assetId(captureSha256, path);
+        if (ids.has(id))
+            fail("本地 Preview capture asset id 冲突");
+        ids.add(id);
+        const metadata = Object.freeze({
+            id,
+            filename: path.slice(path.lastIndexOf("/") + 1),
+            mime,
+            size: bytes.byteLength,
+            createdTs: snapshotUpdatedAtMs,
+            source: "capture",
+            sha256: sha256(bytes),
+        });
+        return Object.freeze({ metadata, bytes });
+    });
+    const byId = new Map(captured.map((entry) => [entry.metadata.id, entry]));
+    const metadata = Object.freeze(captured.map((entry) => entry.metadata));
+    return Object.freeze({
+        list: () => metadata,
+        resolveBytes(asset) {
+            const entry = byId.get(asset.id);
+            if (entry === undefined)
+                fail("本地 Preview capture asset 不存在或不属于当前 capture");
+            if (!SHA256.test(asset.sha256) || asset.sha256 !== entry.metadata.sha256 || sha256(entry.bytes) !== entry.metadata.sha256) {
+                fail("本地 Preview capture asset hash 已过期或不一致");
+            }
+            return Object.freeze({
+                id: entry.metadata.id,
+                mime: entry.metadata.mime,
+                sha256: entry.metadata.sha256,
+                bytes: entry.bytes.slice(),
+            });
+        },
+    });
+}