@world-engines/authoring-ui 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/DesktopAuthoringShell.d.ts

@@ -0,0 +1,178 @@
+import { type ReactNode } from "react";
+import { LadybugExplorer, type LadybugNode } from "./ladybug/LadybugExplorer.js";
+import type { GraphPosition } from "./ladybug/GraphCanvas.js";
+import { type TmwNodeDraft, type TmwSimulationDraft } from "./trigger/tmw/TmwBlueprint.js";
+import { type TmwDiagnostic, type TmwSimulationTraceEntry, type TriggerDocumentV3 } from "@world-engines/tmw";
+import { ViewWorkspace, type ViewFile } from "./view/ViewWorkspace.js";
+import type { SpatialCreateRequest, SpatialRemoveRequest, SpatialUpdateRequest, SpatialWorldSourceV1 } from "@world-engines/spatial-authoring";
+export type { LadybugNode, ViewFile };
+export interface AuthoringUiActionReceipt {
+    readonly project_revision: number;
+    readonly source_digest: string;
+    readonly readback_verified: true;
+}
+export interface CurrentTriggerProjection {
+    readonly source: {
+        readonly source_revision: number;
+        readonly trigger_document: TriggerDocumentV3;
+    };
+    readonly transaction_id: string | null;
+    readonly transaction_status: "idle" | "draft" | "validated" | "simulated" | "committed" | "expired" | "blocked";
+    readonly diagnostics: readonly TmwDiagnostic[];
+    readonly trace: readonly TmwSimulationTraceEntry[];
+    readonly capability_ids: readonly string[];
+    readonly layout_positions?: Readonly<Record<string, GraphPosition>>;
+}
+export interface AuthoringUiSnapshot {
+    readonly project_id: string;
+    readonly projection_revision: number;
+    readonly source_readback: {
+        readonly project_revision: number;
+        readonly source_digest: string;
+    };
+    readonly ladybug: {
+        readonly nodes: readonly LadybugNode[];
+        readonly selected_node_id: string | null;
+        readonly search_query: string;
+        readonly page?: LadybugPageProjection;
+        /** interaction layout read/parse 失败时不能回退到可写默认网格。 */
+        readonly graph?: {
+            readonly capability: "ready" | "unavailable";
+            readonly positions?: Readonly<Record<string, GraphPosition>>;
+            readonly pending_node_ids?: readonly string[];
+            readonly disabled_node_ids?: readonly string[];
+            readonly vector_state_by_node_id?: Readonly<Record<string, "ready" | "pending" | "missing">>;
+        };
+    };
+    /** Desktop 和 Browser 同用经过 authority parser 验证的 TMW SourceV3 projection。 */
+    readonly trigger: CurrentTriggerProjection;
+    readonly view: {
+        readonly files: readonly ViewFile[];
+        readonly selected_path: string | null;
+    };
+    /** 空间 source 由 ProjectHost 注入；UI 不创建副本，也不直接持久化。 */
+    readonly map: {
+        readonly source: SpatialWorldSourceV1;
+        readonly selected_object_id: string | null;
+    };
+    readonly sync: {
+        readonly status: "idle" | "syncing" | "conflict" | "error" | "not_configured";
+        readonly detail: string | null;
+    };
+    /**
+     * 只来自当前 ProjectHost source readback 的本地结构投影。它不是审核结果，
+     * quality_factor/base_score 在本地未获得正式审核回执时必须保持 null。
+     */
+    readonly structural_score?: DesktopStructuralScoreProjection;
+}
+export interface DesktopStructuralScoreProjection {
+    readonly status: "ready" | "unavailable";
+    readonly source_revision: number;
+    readonly source_digest: string;
+    readonly structural_score: number | null;
+    readonly quality_factor: null;
+    readonly base_score: null;
+    readonly primary_type: string | null;
+    readonly dims: Readonly<{
+        entity_count: number;
+        relation_count: number;
+        attr_richness: number;
+        lore_completeness: number;
+        text_volume: number;
+        asset_refs: number;
+    }> | null;
+    readonly evidence: Readonly<{
+        entity_count: number;
+        relation_count: number;
+        total_prop_keys: number;
+    }> | null;
+    readonly reason: string | null;
+    /** 正式远端 draft-preview caller 的最小、已净化 ProjectHost readback 输入。 */
+    readonly draft_context: DesktopScoreDraftContext | null;
+}
+export interface DesktopScoreDraftContext {
+    readonly basis: "project_host_source_readback";
+    readonly client_revision: number;
+    readonly source_digest: string;
+    readonly description: string;
+    readonly entities: ReadonlyArray<Readonly<Record<string, unknown>>>;
+    readonly relations: ReadonlyArray<Readonly<Record<string, unknown>>>;
+}
+export type LadybugPageProjection = Readonly<{
+    capability: "unavailable";
+    reason: string;
+}> | Readonly<{
+    capability: "ready";
+    mode: "browse" | "search";
+    item_ids: readonly string[];
+    cursor: string | null;
+    next_cursor: string | null;
+    previous_cursor: string | null;
+    has_previous: boolean;
+    total_count: number | null;
+    limit: number;
+    order: "id_asc" | "relevance";
+    source_revision: number;
+    source_digest: string;
+}>;
+export interface AuthoringUiAdapter {
+    readSnapshot(): Promise<AuthoringUiSnapshot>;
+    subscribe?(listener: () => void): () => void;
+    selectLadybugNode(node_id: string): Promise<AuthoringUiActionReceipt>;
+    searchLadybug(query: string): Promise<AuthoringUiActionReceipt>;
+    browseLadybugPage?(direction: "first" | "next" | "previous"): Promise<AuthoringUiActionReceipt>;
+    saveLadybugEntity(entity: {
+        readonly node_id: string;
+        readonly kind: string;
+        readonly attributes: Readonly<Record<string, unknown>>;
+    }): Promise<AuthoringUiActionReceipt>;
+    createLadybugRelation?(source_id: string, target_id: string, kind: string): Promise<AuthoringUiActionReceipt>;
+    deleteLadybugRelation?(source_id: string, target_id: string, kind: string): Promise<AuthoringUiActionReceipt>;
+    deleteLadybugEntity?(node_id: string): Promise<AuthoringUiActionReceipt>;
+    unsetLadybugEntityAttribute?(node_id: string, key: string): Promise<AuthoringUiActionReceipt>;
+    commitLadybugPositions?(positions: Readonly<Record<string, GraphPosition>>): Promise<AuthoringUiActionReceipt>;
+    validateTrigger(): Promise<AuthoringUiActionReceipt>;
+    simulateTrigger(draft?: TmwSimulationDraft): Promise<AuthoringUiActionReceipt>;
+    beginTrigger(): Promise<AuthoringUiActionReceipt>;
+    commitTrigger(): Promise<AuthoringUiActionReceipt>;
+    addTriggerNode(draft: TmwNodeDraft): Promise<AuthoringUiActionReceipt>;
+    updateTriggerNode(node: import("@world-engines/tmw").TriggerNodeV3): Promise<AuthoringUiActionReceipt>;
+    deleteTriggerNode(stable_id: string): Promise<AuthoringUiActionReceipt>;
+    connectTriggerNodes(from_stable_id: string, to_stable_id: string): Promise<AuthoringUiActionReceipt>;
+    disconnectTriggerNodes(from_stable_id: string, to_stable_id: string): Promise<AuthoringUiActionReceipt>;
+    commitTriggerPositions(positions: Readonly<Record<string, GraphPosition>>): Promise<AuthoringUiActionReceipt>;
+    selectViewFile(path: string): Promise<AuthoringUiActionReceipt>;
+    saveViewFile(path: string, content: string): Promise<AuthoringUiActionReceipt>;
+    refreshPreview(): Promise<AuthoringUiActionReceipt>;
+    selectSpatialObject(object_id: string): Promise<AuthoringUiActionReceipt>;
+    /** 所有 spatial mutation 都带 source revision，adapter 成功后必须由同一 authority readback。 */
+    createSpatialObject(request: SpatialCreateRequest): Promise<AuthoringUiActionReceipt>;
+    updateSpatialObject(request: SpatialUpdateRequest): Promise<AuthoringUiActionReceipt>;
+    removeSpatialObject(request: SpatialRemoveRequest): Promise<AuthoringUiActionReceipt>;
+    /** Trigger 的空间位置目标只能由 source adapter 进行修复。 */
+    repairTriggerLocationTarget(trigger_id: string, spatial_id: string): Promise<AuthoringUiActionReceipt>;
+    runSync(): Promise<AuthoringUiActionReceipt>;
+}
+export interface DesktopAuthoringUiSlots {
+    readonly graphCanvas?: Parameters<typeof LadybugExplorer>[0]["renderGraphCanvas"];
+    readonly inspector?: Parameters<typeof LadybugExplorer>[0]["renderInspector"];
+    readonly monaco?: Parameters<typeof ViewWorkspace>[0]["renderMonaco"];
+    readonly preview?: () => ReactNode;
+    /** 项目认证与同步只由受信桌面 top window 注入。 */
+    readonly syncSidebar?: () => ReactNode;
+    /**
+     * 远端 tag/radar caller 必须由已认证且已绑定 scenario 的 top window 注入。
+     * Shell 只提供 ProjectHost identity，不会把本地结构分伪装成远端基准。
+     */
+    readonly scoreTagComparison?: (context: Readonly<{
+        project_id: string;
+        project_revision: number;
+        source_digest: string;
+        structural_score: DesktopStructuralScoreProjection;
+    }>) => ReactNode;
+}
+export interface DesktopAuthoringShellProps {
+    readonly adapter: AuthoringUiAdapter;
+    readonly slots?: DesktopAuthoringUiSlots;
+}
+export declare function DesktopAuthoringShell({ adapter, slots }: DesktopAuthoringShellProps): JSX.Element;

package/dist/DesktopAuthoringShell.js

@@ -0,0 +1,235 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { LadybugExplorer } from "./ladybug/LadybugExplorer.js";
+import { MapWorkspace } from "./map/MapWorkspace.js";
+import { TmwBlueprint } from "./trigger/tmw/TmwBlueprint.js";
+import { parseTriggerDocumentV3 } from "@world-engines/tmw";
+import { ViewWorkspace } from "./view/ViewWorkspace.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringOrNull(value) {
+    return typeof value === "string" || value === null;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+function isGraphProjection(value) {
+    // v0 snapshot 没有 interaction layout；调用方必须把它归一为不可写，而不是默认可写网格。
+    if (value === undefined)
+        return true;
+    if (!isRecord(value) || (value.capability !== "ready" && value.capability !== "unavailable"))
+        return false;
+    if (value.capability === "ready") {
+        if (!isRecord(value.positions))
+            return false;
+        for (const [id, position] of Object.entries(value.positions)) {
+            if (id.trim().length === 0 || !isRecord(position) || !Number.isFinite(position.x) || !Number.isFinite(position.y))
+                return false;
+        }
+    }
+    if (value.pending_node_ids !== undefined && !isStringArray(value.pending_node_ids))
+        return false;
+    if (value.disabled_node_ids !== undefined && !isStringArray(value.disabled_node_ids))
+        return false;
+    if (value.vector_state_by_node_id !== undefined) {
+        if (!isRecord(value.vector_state_by_node_id))
+            return false;
+        for (const [id, state] of Object.entries(value.vector_state_by_node_id)) {
+            if (id.trim().length === 0 || (state !== "ready" && state !== "pending" && state !== "missing"))
+                return false;
+        }
+    }
+    return true;
+}
+function isLadybugPageProjection(value, projectionRevision, sourceDigest) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value))
+        return false;
+    if (value.capability === "unavailable")
+        return typeof value.reason === "string";
+    return value.capability === "ready"
+        && (value.mode === "browse" || value.mode === "search")
+        && isStringArray(value.item_ids)
+        && isStringOrNull(value.cursor)
+        && isStringOrNull(value.next_cursor)
+        && isStringOrNull(value.previous_cursor)
+        && typeof value.has_previous === "boolean"
+        && (value.total_count === null || (Number.isSafeInteger(value.total_count) && value.total_count >= 0))
+        && Number.isSafeInteger(value.limit)
+        && value.limit > 0
+        && (value.order === "id_asc" || value.order === "relevance")
+        && value.source_revision === projectionRevision
+        && value.source_digest === sourceDigest;
+}
+function isCurrentTriggerProjection(value, projectionRevision) {
+    if (!isRecord(value)
+        || !isRecord(value.source)
+        || value.source.source_revision !== projectionRevision
+        || !Number.isSafeInteger(value.source.source_revision)
+        || value.source.source_revision < 0
+        || !isStringOrNull(value.transaction_id)
+        || !["idle", "draft", "validated", "simulated", "committed", "expired", "blocked"].includes(value.transaction_status)
+        || !Array.isArray(value.diagnostics)
+        || !Array.isArray(value.trace)
+        || !isStringArray(value.capability_ids))
+        return false;
+    return parseTriggerDocumentV3(value.source.trigger_document).ok;
+}
+function isStructuralScoreProjection(value, projectionRevision, sourceDigest) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value)
+        || (value.status !== "ready" && value.status !== "unavailable")
+        || value.source_revision !== projectionRevision
+        || value.source_digest !== sourceDigest
+        || value.quality_factor !== null
+        || value.base_score !== null
+        || (value.reason !== null && typeof value.reason !== "string"))
+        return false;
+    if (value.status === "unavailable") {
+        return value.structural_score === null
+            && value.primary_type === null
+            && value.dims === null
+            && value.evidence === null
+            && value.draft_context === null;
+    }
+    return typeof value.structural_score === "number"
+        && Number.isFinite(value.structural_score)
+        && value.structural_score >= 0
+        && value.structural_score <= 100
+        && typeof value.primary_type === "string"
+        && isRecord(value.dims)
+        && Object.values(value.dims).every((entry) => typeof entry === "number" && Number.isFinite(entry) && entry >= 0)
+        && isRecord(value.evidence)
+        && [value.evidence.entity_count, value.evidence.relation_count, value.evidence.total_prop_keys]
+            .every((entry) => Number.isSafeInteger(entry) && entry >= 0)
+        && isRecord(value.draft_context)
+        && value.draft_context.basis === "project_host_source_readback"
+        && value.draft_context.client_revision === projectionRevision
+        && value.draft_context.source_digest === sourceDigest
+        && typeof value.draft_context.description === "string"
+        && Array.isArray(value.draft_context.entities)
+        && Array.isArray(value.draft_context.relations);
+}
+/** adapter 的 TS 声明不是来自桌面 IPC 的运行时证明；坏投影必须先拒绝再渲染。 */
+function snapshotError(snapshot) {
+    if (!isRecord(snapshot)
+        || typeof snapshot.project_id !== "string"
+        || typeof snapshot.projection_revision !== "number"
+        || !isRecord(snapshot.source_readback)
+        || typeof snapshot.source_readback.project_revision !== "number"
+        || typeof snapshot.source_readback.source_digest !== "string"
+        || !isRecord(snapshot.ladybug)
+        || !Array.isArray(snapshot.ladybug.nodes)
+        || !isStringOrNull(snapshot.ladybug.selected_node_id)
+        // 兼容旧投影的可选 search_query；其余结构字段不能静默降级。
+        || (snapshot.ladybug.search_query !== undefined && typeof snapshot.ladybug.search_query !== "string")
+        || !isLadybugPageProjection(snapshot.ladybug.page, snapshot.projection_revision, snapshot.source_readback.source_digest)
+        || !isGraphProjection(snapshot.ladybug.graph)
+        || !isCurrentTriggerProjection(snapshot.trigger, snapshot.projection_revision)
+        || !isRecord(snapshot.view)
+        || !Array.isArray(snapshot.view.files)
+        || !isStringOrNull(snapshot.view.selected_path)
+        || !isRecord(snapshot.map)
+        || !isRecord(snapshot.map.source)
+        || typeof snapshot.map.source.revision !== "number"
+        || !Array.isArray(snapshot.map.source.objects)
+        || !isStringOrNull(snapshot.map.selected_object_id)
+        || !isRecord(snapshot.sync)
+        || !["idle", "syncing", "conflict", "error", "not_configured"].includes(snapshot.sync.status)
+        || !isStringOrNull(snapshot.sync.detail)) {
+        return "本地作者项目快照格式无效；已 fail-closed，手动编辑不可用。";
+    }
+    if (snapshot.projection_revision !== snapshot.source_readback.project_revision
+        || snapshot.projection_revision !== snapshot.map.source.revision) {
+        return "投影 revision 与 source readback 不一致；为避免覆盖真实作者源，手动编辑已暂停。";
+    }
+    return null;
+}
+export function DesktopAuthoringShell({ adapter, slots }) {
+    const [snapshot, setSnapshot] = useState(null);
+    const [failure, setFailure] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const [pane, setPane] = useState("ladybug");
+    const reloadVersion = useRef(0);
+    const reload = useCallback(async () => {
+        const ownVersion = reloadVersion.current + 1;
+        reloadVersion.current = ownVersion;
+        setBusy(true);
+        try {
+            const next = await adapter.readSnapshot();
+            if (reloadVersion.current !== ownVersion)
+                return null;
+            const validationError = snapshotError(next);
+            if (validationError !== null) {
+                setFailure(validationError);
+                return null;
+            }
+            setSnapshot(next);
+            setFailure(null);
+            return next;
+        }
+        catch (cause) {
+            if (reloadVersion.current !== ownVersion)
+                return null;
+            const message = cause instanceof Error ? cause.message : "无法读取本地作者项目快照。";
+            setFailure(message);
+            return null;
+        }
+        finally {
+            if (reloadVersion.current === ownVersion)
+                setBusy(false);
+        }
+    }, [adapter]);
+    useEffect(() => { void reload(); }, [reload]);
+    useEffect(() => adapter.subscribe?.(() => { void reload(); }), [adapter, reload]);
+    const perform = useCallback(async (action) => {
+        if (failure !== null)
+            return;
+        setBusy(true);
+        try {
+            const receipt = await action();
+            if (!receipt.readback_verified)
+                throw new Error("adapter 返回了未经 source readback 验证的操作结果。");
+            const readback = await reload();
+            if (readback === null)
+                return;
+            if (readback.source_readback.project_revision !== receipt.project_revision
+                || readback.source_readback.source_digest !== receipt.source_digest) {
+                throw new Error("操作 receipt 与重新读取的 source readback 不一致；当前快照已保持只读，未将操作视为成功。");
+            }
+        }
+        catch (cause) {
+            setFailure(cause instanceof Error ? cause.message : "桌面作者操作失败。");
+            setBusy(false);
+        }
+    }, [failure, reload]);
+    if (snapshot === null) {
+        return failure === null
+            ? _jsx("p", { role: "status", children: "\u6B63\u5728\u8BFB\u53D6\u672C\u5730\u4F5C\u8005\u9879\u76EE\u2026" })
+            : _jsxs("main", { "aria-label": "Desktop Authoring Shell", "data-testid": "desktop-authoring-shell", children: [_jsx("p", { role: "alert", children: failure }), _jsx("button", { disabled: busy, onClick: () => void reload(), type: "button", children: "\u91CD\u65B0\u8BFB\u53D6" })] });
+    }
+    const disabled = busy || failure !== null;
+    const structuralScore = isStructuralScoreProjection(snapshot.structural_score, snapshot.projection_revision, snapshot.source_readback.source_digest) ? snapshot.structural_score : undefined;
+    const scoreForSlot = structuralScore ?? {
+        status: "unavailable",
+        source_revision: snapshot.projection_revision,
+        source_digest: snapshot.source_readback.source_digest,
+        structural_score: null,
+        quality_factor: null,
+        base_score: null,
+        primary_type: null,
+        dims: null,
+        evidence: null,
+        reason: "当前 ProjectHost 未提供匹配 source identity 的可信结构投影",
+        draft_context: null,
+    };
+    return (_jsxs("main", { "aria-label": "Desktop Authoring Shell", "data-testid": "desktop-authoring-shell", children: [_jsxs("header", { children: [_jsx("strong", { children: snapshot.project_id }), _jsxs("span", { children: ["revision ", snapshot.projection_revision] }), _jsxs("span", { children: ["sync: ", snapshot.sync.status] }), _jsx("button", { disabled: busy, onClick: () => void reload(), type: "button", children: "\u91CD\u65B0\u8BFB\u53D6" }), _jsx("button", { disabled: disabled || snapshot.sync.status === "not_configured", onClick: () => void perform(() => adapter.runSync()), type: "button", children: "\u540C\u6B65" })] }), snapshot.sync.detail === null ? null : _jsx("p", { role: "status", children: snapshot.sync.detail }), failure === null ? null : _jsx("p", { role: "alert", children: failure }), slots?.syncSidebar?.(), _jsxs("section", { "aria-label": "\u672C\u5730\u7ED3\u6784\u8BC4\u5206", "data-testid": "desktop-structural-score", children: [_jsx("h2", { children: "\u672C\u5730\u7ED3\u6784\u9884\u4F30" }), structuralScore?.status === "ready" ? (_jsxs(_Fragment, { children: [_jsxs("p", { children: [_jsx("strong", { children: structuralScore.structural_score?.toFixed(1) }), " / 100"] }), _jsxs("p", { children: ["\u7ED3\u6784\u7C7B\u578B\uFF08\u4E0D\u4EE3\u8868\u8D28\u91CF\u7B49\u7EA7\uFF09\uFF1A", structuralScore.primary_type] }), _jsxs("p", { children: ["\u6709\u6548\u8BC1\u636E\uFF1A", structuralScore.evidence?.entity_count, " \u5B9E\u4F53 \u00B7 ", structuralScore.evidence?.relation_count, " \u5173\u7CFB \u00B7 ", structuralScore.evidence?.total_prop_keys, " \u5C5E\u6027"] }), _jsx("p", { children: "\u672A\u5BA1\u6838\uFF1A\u672C\u5730\u6CA1\u6709 quality factor\uFF0C\u4E0D\u751F\u6210\u57FA\u7840\u5206\u6216\u7CFB\u7EDF\u5206\u3002" }), _jsx("dl", { children: Object.entries(structuralScore.dims ?? {}).map(([key, value]) => (_jsxs("div", { children: [_jsx("dt", { children: key }), _jsx("dd", { children: value.toFixed(1) })] }, key))) })] })) : (_jsxs("p", { role: "status", children: ["\u672C\u5730\u7ED3\u6784\u9884\u4F30\u4E0D\u53EF\u7528\uFF1A", scoreForSlot.reason] })), slots?.scoreTagComparison?.({
+                        project_id: snapshot.project_id,
+                        project_revision: snapshot.projection_revision,
+                        source_digest: snapshot.source_readback.source_digest,
+                        structural_score: scoreForSlot,
+                    })] }), _jsx("nav", { "aria-label": "\u4F5C\u8005\u5DE5\u4F5C\u533A", children: ["ladybug", "trigger", "view", "map"].map((item) => (_jsx("button", { "aria-pressed": pane === item, onClick: () => setPane(item), type: "button", children: item }, item))) }), pane === "ladybug" ? _jsx(LadybugExplorer, { disabled: disabled, graph: snapshot.ladybug.graph ?? { capability: "unavailable" }, nodes: snapshot.ladybug.nodes, ...(adapter.browseLadybugPage === undefined ? {} : { onBrowsePage: (direction) => perform(() => adapter.browseLadybugPage(direction)) }), ...(snapshot.ladybug.page === undefined ? {} : { page: snapshot.ladybug.page }), ...(adapter.commitLadybugPositions === undefined ? {} : { onCommitGraphPositions: (positions) => perform(() => adapter.commitLadybugPositions(positions)) }), ...(adapter.createLadybugRelation === undefined ? {} : { onCreateRelation: (source, target, kind) => perform(() => adapter.createLadybugRelation(source, target, kind)) }), ...(adapter.deleteLadybugRelation === undefined ? {} : { onDeleteRelation: (source, target, kind) => perform(() => adapter.deleteLadybugRelation(source, target, kind)) }), ...(adapter.deleteLadybugEntity === undefined ? {} : { onDeleteEntity: (id) => perform(() => adapter.deleteLadybugEntity(id)) }), ...(adapter.unsetLadybugEntityAttribute === undefined ? {} : { onUnsetAttribute: (id, key) => perform(() => adapter.unsetLadybugEntityAttribute(id, key)) }), onSearch: (query) => perform(() => adapter.searchLadybug(query)), onSaveEntity: (entity) => perform(() => adapter.saveLadybugEntity(entity)), onSelect: (id) => perform(() => adapter.selectLadybugNode(id)), search_query: snapshot.ladybug.search_query, selected_node_id: snapshot.ladybug.selected_node_id, spatialObjects: snapshot.map.source.objects, ...(slots?.graphCanvas === undefined ? {} : { renderGraphCanvas: slots.graphCanvas }), ...(slots?.inspector === undefined ? {} : { renderInspector: slots.inspector }) }) : null, pane === "trigger" ? _jsx(TmwBlueprint, { busy: disabled, capabilityIds: snapshot.trigger.capability_ids, diagnostics: snapshot.trigger.diagnostics, layoutPositions: snapshot.trigger.layout_positions ?? {}, onAddNode: (draft) => perform(() => adapter.addTriggerNode(draft)), onBegin: () => void perform(() => adapter.beginTrigger()), onCommit: () => void perform(() => adapter.commitTrigger()), onConnect: (from, to) => perform(() => adapter.connectTriggerNodes(from, to)), onDeleteNode: (id) => perform(() => adapter.deleteTriggerNode(id)), onDisconnect: (from, to) => perform(() => adapter.disconnectTriggerNodes(from, to)), onLayout: (positions) => perform(() => adapter.commitTriggerPositions(positions)), onSimulate: (draft) => void perform(() => adapter.simulateTrigger(draft)), onUpdateNode: (node) => perform(() => adapter.updateTriggerNode(node)), onValidate: () => void perform(() => adapter.validateTrigger()), source: snapshot.trigger.source, trace: snapshot.trigger.trace, transactionId: snapshot.trigger.transaction_id, transactionStatus: snapshot.trigger.transaction_status }) : null, pane === "view" ? _jsx(ViewWorkspace, { disabled: disabled, files: snapshot.view.files, onPreview: () => perform(() => adapter.refreshPreview()), onSaveFile: (path, content) => perform(() => adapter.saveViewFile(path, content)), onSelectFile: (path) => perform(() => adapter.selectViewFile(path)), selected_path: snapshot.view.selected_path, ...(slots?.monaco === undefined ? {} : { renderMonaco: slots.monaco }), ...(slots?.preview === undefined ? {} : { renderPreview: slots.preview }) }) : null, pane === "map" ? _jsx(MapWorkspace, { disabled: disabled, onCreateObject: (request) => perform(() => adapter.createSpatialObject(request)), onRemoveObject: (request) => perform(() => adapter.removeSpatialObject(request)), onSelectObject: (objectId) => perform(() => adapter.selectSpatialObject(objectId)), onUpdateObject: (request) => perform(() => adapter.updateSpatialObject(request)), selected_object_id: snapshot.map.selected_object_id, source: snapshot.map.source }) : null] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { DesktopAuthoringShell } from "./DesktopAuthoringShell.js";
+export type { AuthoringUiActionReceipt, AuthoringUiAdapter, AuthoringUiSnapshot, DesktopAuthoringShellProps, DesktopAuthoringUiSlots, DesktopStructuralScoreProjection, DesktopScoreDraftContext, LadybugPageProjection, LadybugNode, ViewFile, } from "./DesktopAuthoringShell.js";
+export { LadybugExplorer } from "./ladybug/LadybugExplorer.js";
+export { LadybugTable } from "./ladybug/LadybugTable.js";
+export type { LadybugTableProps } from "./ladybug/LadybugTable.js";
+export { SharedGraphCanvas, forceLayout, graphGlyphKind, groupGraphRelations } from "./ladybug/GraphCanvas.js";
+export type { GraphFocusRequest, GraphGlyphKind, GraphPosition, GraphVectorState, GraphViewport, SharedGraphCanvasProps, SharedGraphNode, SharedGraphRelation, SharedGraphRelationGroupSelection } from "./ladybug/GraphCanvas.js";
+export { BrowserGraphCanvasAdapter } from "./ladybug/BrowserGraphCanvasAdapter.js";
+export type { BrowserGraphCanvasAdapterProps } from "./ladybug/BrowserGraphCanvasAdapter.js";
+export { LadybugHistory, LadybugInspector } from "./ladybug/LadybugSurfaces.js";
+export type { LadybugHistoryEntry, LadybugHistoryProps, LadybugInspectorProps } from "./ladybug/LadybugSurfaces.js";
+export { TmwBlueprint } from "./trigger/tmw/TmwBlueprint.js";
+export { TmwFlowLane } from "./trigger/tmw/TmwFlowLane.js";
+export type { TmwBlueprintProps, TmwNodeDraft, TmwSimulationDraft } from "./trigger/tmw/TmwBlueprint.js";
+export type { TmwFlowLaneProps } from "./trigger/tmw/TmwFlowLane.js";
+export type { TmwTranslate } from "./trigger/tmw/translate.js";
+export { ViewWorkspace } from "./view/ViewWorkspace.js";
+export { MapWorkspace } from "./map/MapWorkspace.js";
+export type { MapWorkspaceProps } from "./map/MapWorkspace.js";
+export { SyncSidebar } from "./sync/SyncSidebar.js";
+export type { SyncSidebarAdapter, SyncSidebarSnapshot } from "./sync/SyncSidebar.js";
+export { DownloadPanel } from "./sync/DownloadPanel.js";
+export type { DownloadReplaceUiPlan, DownloadReplaceUiPort } from "./sync/DownloadPanel.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { DesktopAuthoringShell } from "./DesktopAuthoringShell.js";
+export { LadybugExplorer } from "./ladybug/LadybugExplorer.js";
+export { LadybugTable } from "./ladybug/LadybugTable.js";
+export { SharedGraphCanvas, forceLayout, graphGlyphKind, groupGraphRelations } from "./ladybug/GraphCanvas.js";
+export { BrowserGraphCanvasAdapter } from "./ladybug/BrowserGraphCanvasAdapter.js";
+export { LadybugHistory, LadybugInspector } from "./ladybug/LadybugSurfaces.js";
+export { TmwBlueprint } from "./trigger/tmw/TmwBlueprint.js";
+export { TmwFlowLane } from "./trigger/tmw/TmwFlowLane.js";
+export { ViewWorkspace } from "./view/ViewWorkspace.js";
+export { MapWorkspace } from "./map/MapWorkspace.js";
+export { SyncSidebar } from "./sync/SyncSidebar.js";
+export { DownloadPanel } from "./sync/DownloadPanel.js";

package/dist/ladybug/BrowserGraphCanvasAdapter.d.ts

@@ -0,0 +1,12 @@
+import type { JSX, ReactNode } from "react";
+import { type SharedGraphCanvasProps } from "./GraphCanvas.js";
+/** Browser 端用此薄 adapter 接回既有 Inspector、import 与 embedding；core 不依赖 browser store。 */
+export interface BrowserGraphCanvasAdapterProps extends SharedGraphCanvasProps {
+    /** 既有浏览器 Import 流程的受限入口；未提供时明确禁用，而不是伪造导入。 */
+    readonly onOpenImport?: () => void;
+    /** 既有浏览器 embedding 批处理的受限入口；GraphCanvas 不直接读取 store。 */
+    readonly onRunEmbedding?: () => void;
+    /** 生产 Browser 可复用成熟 embedding 控件，而非让 core 直接接触 store。 */
+    readonly renderEmbeddingControl?: () => ReactNode;
+}
+export declare function BrowserGraphCanvasAdapter({ onOpenImport, onRunEmbedding, renderEmbeddingControl, ...canvas }: BrowserGraphCanvasAdapterProps): JSX.Element;

package/dist/ladybug/BrowserGraphCanvasAdapter.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SharedGraphCanvas } from "./GraphCanvas.js";
+export function BrowserGraphCanvasAdapter({ onOpenImport, onRunEmbedding, renderEmbeddingControl, ...canvas }) {
+    const importEnabled = !canvas.disabled && onOpenImport !== undefined;
+    const embeddingEnabled = !canvas.disabled && onRunEmbedding !== undefined;
+    const hasBrowserActions = onOpenImport !== undefined || onRunEmbedding !== undefined || renderEmbeddingControl !== undefined;
+    return _jsxs("section", { "aria-label": "GraphCanvas Browser adapter", children: [hasBrowserActions ? _jsxs("div", { "aria-label": "GraphCanvas Browser \u64CD\u4F5C", children: [_jsx("button", { disabled: !importEnabled, onClick: () => onOpenImport?.(), type: "button", children: "\u5BFC\u5165\u5B9E\u4F53" }), renderEmbeddingControl?.() ?? _jsx("button", { disabled: !embeddingEnabled, onClick: () => onRunEmbedding?.(), type: "button", children: "\u751F\u6210 embedding" })] }) : null, _jsx(SharedGraphCanvas, { ...canvas, showToolbar: canvas.showToolbar ?? false })] });
+}

package/dist/ladybug/GraphCanvas.d.ts

@@ -0,0 +1,121 @@
+import { type MouseEvent } from "react";
+import { type SharedGraphGroup } from "./graph-groups.js";
+import { type GraphContentEntity, type GraphNameAttrPredicate, type GraphNodeMetrics } from "./graph-node-metrics.js";
+import type { GraphLayoutSolverHandle } from "./graph-layout-contract.js";
+export interface GraphPosition {
+    readonly x: number;
+    readonly y: number;
+}
+export interface GraphViewport {
+    readonly x: number;
+    readonly y: number;
+    readonly zoom: number;
+}
+export interface GraphFocusRequest {
+    /** 同一 requestId 只处理一次；重复聚焦同节点时由宿主换新 id。 */
+    readonly requestId: string | number;
+    readonly nodeId: string;
+    readonly zoom?: number;
+    readonly durationMs?: number;
+}
+export type GraphVectorState = "ready" | "pending" | "missing";
+export interface SharedGraphNode {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly disabled?: boolean;
+    /** 缺省回退 disabled；显式 false 可让灰态节点仍可选择/右键以重新启用。 */
+    readonly interactionDisabled?: boolean;
+    readonly pending?: boolean;
+    readonly searchMatch?: boolean;
+    readonly highlighted?: boolean;
+    /** 缺省表示宿主未提供向量事实，不得解释为 ready。 */
+    readonly vector?: GraphVectorState;
+    /** 作者可见文本 envelope；共享 metrics 不需要完整 editor EntityNode。 */
+    readonly content?: GraphContentEntity;
+    /** 高成本投影可由宿主预计算；提供时优先于 content。 */
+    readonly metrics?: GraphNodeMetrics;
+}
+export interface SharedGraphRelation {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly label: string;
+    readonly pending?: boolean;
+    readonly disabled?: boolean;
+    readonly searchMatch?: boolean;
+}
+export interface SharedGraphRelationGroupSelection {
+    readonly pairId: string;
+    /** ReactFlow 聚合线使用稳定的无向 canonical 端点。 */
+    readonly source: string;
+    readonly target: string;
+    readonly relationIds: readonly string[];
+    /** 原始顺序、source/target 与 label 全部保留，供宿主详情面板消费。 */
+    readonly relations: readonly SharedGraphRelation[];
+}
+export interface SharedGraphCanvasProps {
+    readonly nodes: readonly SharedGraphNode[];
+    readonly relations: readonly SharedGraphRelation[];
+    readonly selectedNodeId: string | null;
+    readonly selectedRelationId?: string | null;
+    /** 关联 FAB hover/focus 的瞬时远端提示；不改变 selection 或 layout。 */
+    readonly highlightNodeId?: string | null;
+    readonly searchQuery: string;
+    readonly disabled: boolean;
+    /** Browser 已有成熟 toolbar 时关闭；Desktop 默认展示共享布局操作。 */
+    readonly showToolbar?: boolean;
+    /** 大图可开启 ReactFlow viewport culling；缺省 false 保持 npm 现有行为。 */
+    readonly onlyRenderVisibleElements?: boolean;
+    /** canonical 48px node 左上角；圆心固定为 position + 24，不随内容尺寸漂移。 */
+    readonly positions?: Readonly<Record<string, GraphPosition>>;
+    readonly viewport?: GraphViewport;
+    readonly focusRequest?: GraphFocusRequest | null;
+    /** 场景/世界稳定 identity；变化时立即废弃旧 Worker 与所有在途布局结果。 */
+    readonly graphIdentity?: string | number;
+    readonly groups?: readonly SharedGraphGroup[];
+    readonly isNameAttrKey?: GraphNameAttrPredicate;
+    readonly onSelectNode: (id: string) => void;
+    readonly onCreateNodeAt?: (position: GraphPosition) => void;
+    readonly onEditNode?: (id: string) => void;
+    /** 只请求宿主确认删除；共享 core 不直接删除实体。 */
+    readonly onRequestDeleteNode?: (id: string) => void;
+    readonly onCreateRelationFromNode?: (id: string) => void;
+    readonly onSelectRelation?: (id: string) => void;
+    /** 聚合线选择入口；未提供时向后兼容地回退 onSelectRelation(firstId)。 */
+    readonly onSelectRelationGroup?: (selection: SharedGraphRelationGroupSelection) => void;
+    readonly onEditRelationGroup?: (selection: SharedGraphRelationGroupSelection) => void;
+    /** 只请求宿主确认删除；selection 保留全部底层有向关系。 */
+    readonly onRequestDeleteRelationGroup?: (selection: SharedGraphRelationGroupSelection) => void;
+    /** 解除纯视觉分组但不删除成员；确认与写入由宿主完成。 */
+    readonly onRequestUngroup?: (group: SharedGraphGroup) => void;
+    readonly onClearSelection?: () => void;
+    /** 双击居中由 core 完成，callback 只回传宿主业务意图。 */
+    readonly onNodeDoubleClick?: (id: string) => void;
+    /** 在一次 pan/zoom 手势结束时回传 viewport，避免逐帧持久化。 */
+    readonly onViewportChange?: (viewport: GraphViewport) => void;
+    readonly onLayoutError?: (error: Error) => void;
+    /** 测试/受限 runtime 可替换 factory；浏览器缺省始终使用共享 WASM Worker。 */
+    readonly createLayoutSolver?: () => GraphLayoutSolverHandle;
+    /** Browser adapter 可将既有右键菜单接入；core 不拥有任何 store 或删除 authority。 */
+    readonly onNodeContextMenu?: (id: string, event: MouseEvent<HTMLDivElement>) => void;
+    /** 仅传递关系拖拽意图；宿主决定是否创建关系。 */
+    readonly onRelationDragIntent?: (sourceId: string, targetId: string) => void;
+    /** 拖拽或 force-layout 完成后一次性提交全部 position。 */
+    readonly onCommitPositions?: (positions: Readonly<Record<string, GraphPosition>>) => void;
+    /** group rectangles 与成员 positions 的唯一原子持久化 seam；成员关系由中心点投影，不重复存储。 */
+    readonly onCommitLayout?: (layout: {
+        readonly positions: Readonly<Record<string, GraphPosition>>;
+        readonly groups: readonly SharedGraphGroup[];
+    }) => void;
+}
+export declare const graphNodeContentTitle: (label: string, metrics: GraphNodeMetrics) => string;
+export type GraphGlyphKind = "person" | "place" | "faction" | "item" | "event" | "neutral";
+export declare const graphGlyphKind: (kind: string) => GraphGlyphKind;
+export declare function groupGraphRelations(relations: readonly SharedGraphRelation[]): SharedGraphRelationGroupSelection[];
+/**
+ * 同步执行 editor 成熟 physics tick；坐标输入输出均为 canonical 48px node 左上角。
+ * 只返回最终投影，调用方可在一次交互结束后单次持久化。
+ */
+export declare function forceLayout(nodes: readonly SharedGraphNode[], current: Readonly<Record<string, GraphPosition>>, relations?: readonly SharedGraphRelation[], isNameAttrKey?: GraphNameAttrPredicate): Record<string, GraphPosition>;
+export declare function SharedGraphCanvas(props: SharedGraphCanvasProps): JSX.Element;