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

package/dist/local-preview-projections.js

@@ -0,0 +1,117 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { LOCAL_PREVIEW_CUSTOM_STATE_MAX_BYTES } from "./local-preview-view-state.js";
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+function fail(code, message) { throw new AuthoringBridgeError(code, message); }
+function record(value) { if (typeof value !== "object" || value === null || Array.isArray(value))
+    fail("EINVAL", "参数无效"); return value; }
+function exact(value, allowed) { const result = record(value); if (Object.keys(result).some((key) => !allowed.includes(key)))
+    fail("EINVAL", "参数包含未知字段"); return result; }
+function empty(value) { exact(value, []); }
+function id(value, field) { if (typeof value !== "string" || !ID.test(value))
+    fail("EINVAL", `${field} 无效`); return value; }
+function clone(value) { return value === undefined ? undefined : JSON.parse(JSON.stringify(value)); }
+function capabilityMissing(name) { return fail("E_CAPABILITY_UNAVAILABLE", `本地 Preview 尚无 ${name} 的真实只读来源`); }
+/** 从 LocalPreviewRuntime.readProjectionSnapshot 的窄 Host snapshot 读取已有真值。 */
+export function localPreviewCoreFromRuntimeSnapshot(value) {
+    const root = record(value);
+    const identity = record(root.capture_identity);
+    const gameplay = record(root.gameplay);
+    const source = record(root.source_projection);
+    if (root.kind !== "worldengine.local-preview-projection/v1" || root.development_preview !== true)
+        fail("E_OPERATION_UNCERTAIN", "local Preview runtime projection identity 无效");
+    const scriptId = id(identity.project_id, "capture_identity.project_id");
+    const scenarioId = id(identity.local_scenario_id, "capture_identity.local_scenario_id");
+    const metadataRoot = record(source.metadata);
+    const metadata = metadataRoot.metadata === null || metadataRoot.metadata === undefined ? undefined : record(metadataRoot.metadata);
+    if (metadata !== undefined && metadata.title !== undefined && typeof metadata.title !== "string")
+        fail("E_OPERATION_UNCERTAIN", "local Preview metadata title 无效");
+    const title = metadata === undefined || metadata.title === undefined ? "" : metadata.title;
+    if (!Array.isArray(gameplay.save_variables) || !record(gameplay.unlocks))
+        fail("E_OPERATION_UNCERTAIN", "local Preview gameplay projection 无效");
+    const saveVariables = gameplay.save_variables.map((candidate) => { const item = record(candidate); const name = id(item.name, "save variable name"); if (item.scope !== "save" || typeof item.valueType !== "string")
+        fail("E_OPERATION_UNCERTAIN", "local Preview save variable 无效"); return Object.freeze({ name, scope: "save", valueType: item.valueType, value: clone(item.value) }); });
+    const unlocks = Object.fromEntries(Object.entries(record(gameplay.unlocks)).map(([key, unlocked]) => { if (!/^(node|edge):.+$/u.test(key) || typeof unlocked !== "boolean")
+        fail("E_OPERATION_UNCERTAIN", "local Preview unlock projection 无效"); return [key, unlocked]; }));
+    return Object.freeze({ scriptId, scenarioId, title, saveVariables: Object.freeze(saveVariables), unlocks: Object.freeze(unlocks) });
+}
+/** SDK 只读 dispatcher。扩展读取面各自接入，缺真值不会阻断已可用的 SAV 读取。 */
+export class LocalPreviewReadOnlyProjection {
+    #core;
+    #readers;
+    constructor(core, readers = {}) {
+        if (!ID.test(core.scriptId) || !ID.test(core.scenarioId))
+            fail("E_OPERATION_UNCERTAIN", "local Preview core identity 无效");
+        if (new Set(core.saveVariables.map((item) => item.name)).size !== core.saveVariables.length || Object.values(core.unlocks).some((entry) => typeof entry !== "boolean"))
+            fail("E_OPERATION_UNCERTAIN", "local Preview core gameplay 无效");
+        this.#core = core;
+        this.#readers = readers;
+    }
+    capabilities() { return Object.freeze({ customStateMaxBytes: this.#readers.customState === undefined ? 0 : LOCAL_PREVIEW_CUSTOM_STATE_MAX_BYTES, assetMaxBytes: 0, supportsAssets: this.#readers.assets !== undefined, supportsEdit: false, supportsDelete: false }); }
+    async handle(method, params) {
+        if (method === "scenario.getMeta") {
+            empty(params);
+            return Object.freeze({ scriptId: this.#core.scriptId, title: this.#core.title, schemaVersion: 3 });
+        }
+        if (method === "scenario.getVariable") {
+            const p = exact(params, ["name", "scope"]);
+            const name = id(p.name, "name");
+            if (p.scope !== "save")
+                fail("EINVAL", "scope 必须是 save");
+            const variable = this.#core.saveVariables.find((item) => item.name === name);
+            if (variable === undefined)
+                fail("ENOTFOUND", "变量不存在");
+            return Object.freeze({ ...variable, value: clone(variable.value) });
+        }
+        if (method === "scenario.getUnlock") {
+            const p = exact(params, ["target", "id"]);
+            if (p.target !== "node" && p.target !== "edge")
+                fail("EINVAL", "target 无效");
+            const targetId = id(p.id, "id");
+            return Object.freeze({ unlocked: this.#core.unlocks[`${p.target}:${targetId}`] ?? true });
+        }
+        if (method === "scenario.getProgress") {
+            empty(params);
+            if (this.#readers.progress === undefined)
+                capabilityMissing("SAV progress");
+            const progress = await this.#readers.progress();
+            if (!Number.isFinite(progress) || progress < 0 || progress > 1)
+                fail("E_OPERATION_UNCERTAIN", "local Preview SAV progress 无效");
+            return progress;
+        }
+        if (method === "scenario.getOwnedResources") {
+            empty(params);
+            if (this.#readers.ownedResources === undefined)
+                capabilityMissing("owned resources");
+            return (await this.#readers.ownedResources()).map((group) => Object.freeze({ ...group, resources: group.resources.map((resource) => Object.freeze({ ...resource })) }));
+        }
+        if (method === "state.get" || method === "state.getEntry" || method === "state.keys") {
+            const entries = await this.#state();
+            if (method === "state.keys") {
+                empty(params);
+                return entries.map((entry) => entry.key).sort();
+            }
+            const key = id(exact(params, ["key"]).key, "key");
+            const entry = entries.find((candidate) => candidate.key === key);
+            return method === "state.get" ? clone(entry?.value) : entry === undefined ? undefined : Object.freeze({ ...entry, value: clone(entry.value), authorizedUserIds: [...entry.authorizedUserIds] });
+        }
+        if (method === "asset.list" || method === "asset.getUrl") {
+            if (this.#readers.assets === undefined)
+                capabilityMissing("capture assets");
+            if (method === "asset.list") {
+                empty(params);
+                return await Promise.all((await this.#readers.assets.list()).map(async (asset) => this.#assetRecord(asset)));
+            }
+            const assetId = id(exact(params, ["id"]).id, "id");
+            const asset = (await this.#readers.assets.list()).find((candidate) => candidate.id === assetId);
+            if (asset === undefined)
+                fail("ENOTFOUND", "capture asset 不存在");
+            return await this.#readers.assets.getUrl(asset);
+        }
+        fail("EPERM", "本地 Preview 未授予该 ChatPlay SDK 能力");
+    }
+    async #state() { if (this.#readers.customState === undefined)
+        capabilityMissing("view custom state"); const entries = await this.#readers.customState(); if (new Set(entries.map((entry) => entry.key)).size !== entries.length)
+        fail("E_OPERATION_UNCERTAIN", "custom state key 重复"); return entries; }
+    async #assetRecord(asset) { if (!ID.test(asset.id) || asset.source !== "capture" || !Number.isSafeInteger(asset.size) || asset.size < 0 || !Number.isSafeInteger(asset.createdTs) || asset.createdTs < 0 || !/^[a-f0-9]{64}$/u.test(asset.sha256))
+        fail("E_OPERATION_UNCERTAIN", "capture asset 无效"); return Object.freeze({ id: asset.id, scriptId: this.#core.scriptId, filename: asset.filename, mime: asset.mime, size: asset.size, createdTs: asset.createdTs, url: await this.#readers.assets.getUrl(asset), sha256: asset.sha256 }); }
+}

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

@@ -0,0 +1,105 @@
+import { type TmwSceneStateV1, type TmwPendingSceneClockCrossingV1 } from "@world-engines/tmw";
+import { type LocalPreviewSourceCapture } from "./local-preview-source.js";
+import type { LocalPreviewWorldlineRuntime } from "./local-preview-worldlines.js";
+import { LocalPreviewViewStateSqlitePort } from "./local-preview-view-state-sqlite.js";
+import { LocalPreviewPlayerReadModels } from "./local-preview-player-read-models.js";
+export interface LocalPreviewRuntimeInspection {
+    readonly development_preview: true;
+    readonly capture_sha256: string;
+    readonly project_id: string;
+    readonly scenario_id: string;
+    readonly compiler_receipt_sha256: string;
+    readonly compiled_plan_sha256: string;
+    readonly save_path: string;
+    readonly event_execution: "local_deterministic";
+}
+export interface LocalPreviewEventInput {
+    readonly event_type: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly operation_id: string;
+    readonly turn_id: string;
+    readonly world_time?: number | null;
+}
+export interface LocalPreviewEventReceipt {
+    readonly status: "committed" | "already_committed";
+    readonly operation_id: string;
+    /** 仅 committed 首次返回；幂等重放为空，避免 View 重复广播。 */
+    readonly author_view_events: ReadonlyArray<Readonly<{
+        eventId: string;
+        eventType: string;
+        viewVisiblePayload: Readonly<Record<string, null | boolean | number | string>>;
+    }>>;
+}
+export interface LocalPreviewWriterPreparation {
+    readonly identity: string;
+    readonly operation_id: string;
+    readonly turn_id: string;
+    readonly capture_sha256: string;
+    readonly timeline_revision: string;
+    readonly ledger_head: string;
+    readonly worldline_id: string;
+    readonly world_time: number | null;
+    readonly scene: TmwSceneStateV1 | null;
+}
+/**
+ * 本地开发预览的单实例 Runtime seam。
+ * 它只消费 immutable capture，SAV 也只写入 capture-hash 隔离目录；不是正式 Player 保存、head、lease 或发布 authority。
+ */
+export declare class LocalPreviewRuntime {
+    #private;
+    private constructor();
+    static open(input: Readonly<{
+        project_root: string;
+        capture?: LocalPreviewSourceCapture;
+    }>): Promise<LocalPreviewRuntime>;
+    inspect(): LocalPreviewRuntimeInspection;
+    readScene(): TmwSceneStateV1 | null;
+    readVariable(name: string, scope: "save" | "execution"): import("@world-engines/tmw").TmwVariableV1;
+    readUnlock(kind: "node" | "edge", id: string): boolean;
+    readViewInteractionBinding(): Readonly<Record<string, unknown>>;
+    openViewState(viewId: string): Promise<LocalPreviewViewStateSqlitePort>;
+    appendAcceptedUserMessage(input: Readonly<{
+        operation_id: string;
+        turn_id: string;
+        message_id: string;
+        text: string;
+    }>): Promise<Readonly<{
+        message: import("./local-preview-message-store.js").LocalPreviewCommittedMessage;
+        replayed: boolean;
+    }>>;
+    readCommittedMessages(): Promise<readonly import("./local-preview-message-store.js").LocalPreviewCommittedMessage[]>;
+    /** 仅恢复指定 operation 仍在当前 SAV 中、且可由 source ledger 精确验证的 View 事件；不扫描历史。 */
+    readAuthorViewEventsByOperation(operationIdInput: string): LocalPreviewEventReceipt["author_view_events"];
+    playerReadModels(): LocalPreviewPlayerReadModels;
+    /** Host-only facade; it reuses activation.sqlite and never exposes DatabaseSync to iframe code. */
+    worldlineRuntime(): LocalPreviewWorldlineRuntime;
+    prepareWriterTurn(input: Readonly<{
+        operation_id: string;
+        turn_id: string;
+    }>): Promise<LocalPreviewWriterPreparation>;
+    commitSuccessfulWriterResult(input: Readonly<{
+        prepare_identity: string;
+        text: string;
+        message_id: string;
+        ordered_message_ids: readonly string[];
+        writer_receipt_digest: string;
+        pending_clock_crossings?: readonly TmwPendingSceneClockCrossingV1[];
+    }>): Promise<Readonly<{
+        status: "committed" | "already_committed";
+        message_id: string;
+    }>>;
+    readCommittedWriterMessage(messageId: string): Readonly<{
+        message_id: string;
+        text: string;
+    }> | null;
+    /** Host-only typed input for a separate allowlisted View projector; never expose this object directly through iframe RPC. */
+    readProjectionSnapshot(): Readonly<Record<string, unknown>>;
+    dispose(): void;
+    /** 本地开发 Runtime：无远端 lease/head；同一 operation_id 读取已持久 receipt，不重复执行。 */
+    executeEvent(input: LocalPreviewEventInput): Promise<LocalPreviewEventReceipt>;
+    /** Host-only：仅消费当前 SAV 已到期的 pending crossing；不创建或推进新的时钟事件。 */
+    drainPendingSceneCrossings(input: Readonly<{
+        turn_id: string;
+        max_events?: number;
+    }>): Promise<readonly LocalPreviewEventReceipt[]>;
+}