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

package/dist/ladybug/GraphEdge.d.ts

@@ -0,0 +1,26 @@
+import { type EdgeProps } from "reactflow";
+import { type GraphEdgeOcclusionIndex } from "./graph-edge-mask.js";
+export interface SharedGraphEdgeData {
+    readonly label: string;
+    readonly markerId?: string;
+    readonly relationIds?: readonly string[];
+    readonly state: "committed" | "pending" | "search" | "disabled";
+    readonly sourceRadius?: number;
+    readonly targetRadius?: number;
+    readonly parallelIndex?: number;
+    readonly parallelCount?: number;
+    readonly emphasized?: boolean;
+    readonly muted?: boolean;
+    readonly maskId?: string;
+    readonly occlusionIndex?: GraphEdgeOcclusionIndex;
+    readonly occlusionZoom?: number;
+    readonly onSelect?: () => void;
+    readonly onContextMenu?: (event: {
+        readonly clientX: number;
+        readonly clientY: number;
+        preventDefault(): void;
+        stopPropagation(): void;
+    }) => void;
+}
+/** 共享边只表达投影状态；关系实际写入仍由宿主 adapter 完成。 */
+export declare function GraphEdge({ sourceX, sourceY, targetX, targetY, data }: EdgeProps<SharedGraphEdgeData>): JSX.Element;

package/dist/ladybug/GraphEdge.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { EdgeLabelRenderer } from "reactflow";
+import { computeGraphEdgeGeometry } from "./graph-edge-geometry.js";
+import { graphEdgeLabelWorldBounds, isGraphEdgeLabelOccluded } from "./graph-edge-mask.js";
+/** 共享边只表达投影状态；关系实际写入仍由宿主 adapter 完成。 */
+export function GraphEdge({ sourceX, sourceY, targetX, targetY, data }) {
+    const state = data?.state ?? "committed";
+    const markerId = data?.markerId;
+    const geometry = computeGraphEdgeGeometry({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        ...(data?.sourceRadius === undefined ? {} : { sourceRadius: data.sourceRadius }),
+        ...(data?.targetRadius === undefined ? {} : { targetRadius: data.targetRadius }),
+        ...(data?.parallelIndex === undefined ? {} : { parallelIndex: data.parallelIndex }),
+        ...(data?.parallelCount === undefined ? {} : { parallelCount: data.parallelCount })
+    });
+    const select = () => data?.onSelect?.();
+    const emphasized = data?.emphasized === true;
+    const labelText = data?.label ?? "0";
+    const labelOccluded = !emphasized
+        && data?.occlusionIndex !== undefined
+        && isGraphEdgeLabelOccluded(data.occlusionIndex, graphEdgeLabelWorldBounds(labelText, geometry.labelX, geometry.labelY, data.occlusionZoom ?? 1));
+    const className = [
+        "shared-graph-edge",
+        `shared-graph-edge--${state}`,
+        data?.emphasized === true ? "is-emphasized" : "",
+        data?.muted === true ? "is-muted" : ""
+    ].filter(Boolean).join(" ");
+    return _jsxs(_Fragment, { children: [_jsx("path", { className: className, d: geometry.path, fill: "none", markerEnd: markerId === undefined ? undefined : `url(#${markerId})`, mask: !emphasized && data?.maskId !== undefined ? `url(#${data.maskId})` : undefined, onClick: select, onContextMenu: (event) => {
+                    event.preventDefault();
+                    data?.onContextMenu?.(event);
+                } }), labelOccluded ? null : _jsx(EdgeLabelRenderer, { children: _jsx("button", { "aria-label": `${labelText} 条关系`, className: `shared-graph-edge__label${emphasized ? " is-emphasized" : ""}`, disabled: state === "disabled" || data?.onSelect === undefined, onClick: (event) => { event.stopPropagation(); select(); }, onContextMenu: (event) => {
+                        event.preventDefault();
+                        data?.onContextMenu?.(event);
+                    }, style: {
+                        position: "absolute",
+                        transform: `translate(-50%, -50%) translate(${geometry.labelX}px, ${geometry.labelY}px)`
+                    }, type: "button", children: labelText }) })] });
+}

package/dist/ladybug/LadybugExplorer.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from "react";
+import type { SpatialObjectV1 } from "@world-engines/spatial-authoring";
+import type { LadybugPageProjection } from "../DesktopAuthoringShell.js";
+import { type GraphPosition } from "./GraphCanvas.js";
+import { type LadybugHistoryEntry } from "./LadybugSurfaces.js";
+export interface LadybugNode {
+    readonly node_id: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly description: string | null;
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly relations: readonly {
+        readonly source_id: string;
+        readonly target_id: string;
+        readonly kind: string;
+        readonly attributes: Readonly<Record<string, unknown>>;
+    }[];
+    readonly history: readonly Readonly<Record<string, unknown>>[];
+}
+export interface LadybugExplorerProps {
+    readonly nodes: readonly LadybugNode[];
+    readonly selected_node_id: string | null;
+    readonly search_query: string;
+    readonly page?: LadybugPageProjection;
+    readonly disabled: boolean;
+    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">>;
+    };
+    readonly onSelect: (node_id: string) => Promise<void>;
+    readonly onSearch: (query: string) => Promise<void>;
+    readonly onBrowsePage?: (direction: "first" | "next" | "previous") => Promise<void>;
+    readonly onSaveEntity: (entity: {
+        readonly node_id: string;
+        readonly kind: string;
+        readonly attributes: Readonly<Record<string, unknown>>;
+    }) => Promise<void>;
+    readonly onCreateRelation?: (source_id: string, target_id: string, kind: string) => Promise<void>;
+    readonly onDeleteRelation?: (source_id: string, target_id: string, kind: string) => Promise<void>;
+    readonly onDeleteEntity?: (node_id: string) => Promise<void>;
+    readonly onUnsetAttribute?: (node_id: string, key: string) => Promise<void>;
+    readonly onCommitGraphPositions?: (positions: Readonly<Record<string, GraphPosition>>) => Promise<void>;
+    /** source readback 中的对象用于校验 Ladybug spatial_ref，不形成第二份 spatial 索引。 */
+    readonly spatialObjects: readonly SpatialObjectV1[];
+    readonly renderGraphCanvas?: (props: LadybugExplorerProps) => ReactNode;
+    readonly renderInspector?: (node: LadybugNode | null) => ReactNode;
+    readonly history?: {
+        readonly entries: readonly LadybugHistoryEntry[];
+        readonly can_undo: boolean;
+        readonly can_redo: boolean;
+    };
+    readonly onUndo?: () => Promise<void>;
+    readonly onRedo?: () => Promise<void>;
+}
+export declare function LadybugExplorer(props: LadybugExplorerProps): JSX.Element;

package/dist/ladybug/LadybugExplorer.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { SharedGraphCanvas } from "./GraphCanvas.js";
+import { LadybugHistory, LadybugInspector } from "./LadybugSurfaces.js";
+import { LadybugTable } from "./LadybugTable.js";
+function parseEntityAttributes(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function compareCodepoint(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+export function LadybugExplorer(props) {
+    const selected = props.nodes.find((node) => node.node_id === props.selected_node_id) ?? null;
+    // 老的 projection 只能安全降级为未搜索状态；不能让可选展示字段阻断整个桌面壳。
+    const normalizedSearchQuery = typeof props.search_query === "string" ? props.search_query : "";
+    const [query, setQuery] = useState(normalizedSearchQuery);
+    const [entityId, setEntityId] = useState(selected?.node_id ?? "");
+    const [entityKind, setEntityKind] = useState(selected?.kind ?? "");
+    const [attributes, setAttributes] = useState(JSON.stringify(selected?.attributes ?? {}, null, 2));
+    const [spatialRef, setSpatialRef] = useState("");
+    const [spatialRefError, setSpatialRefError] = useState(null);
+    const [relationIntent, setRelationIntent] = useState(null);
+    const [relationKind, setRelationKind] = useState("");
+    useEffect(() => setQuery(normalizedSearchQuery), [normalizedSearchQuery]);
+    // 同一实体的 source revision 改变时保留用户尚未提交的草稿；切换实体才换成
+    // 新选择的 canonical readback。Inspector 仍始终展示最新节点投影。
+    useEffect(() => {
+        setEntityId(selected?.node_id ?? "");
+        setEntityKind(selected?.kind ?? "");
+        setAttributes(JSON.stringify(selected?.attributes ?? {}, null, 2));
+        setSpatialRef(typeof selected?.attributes.spatial_ref === "string" ? selected.attributes.spatial_ref : "");
+        setSpatialRefError(null);
+    }, [selected?.node_id]);
+    const parsedAttributes = parseEntityAttributes(attributes);
+    const relations = [...new Map(props.nodes.flatMap((node) => node.relations.map((relation) => {
+            const id = JSON.stringify([relation.source_id, relation.kind, relation.target_id]);
+            return [id, {
+                    id,
+                    source: relation.source_id,
+                    target: relation.target_id,
+                    label: relation.kind,
+                    pending: Boolean(props.graph?.pending_node_ids?.includes(relation.source_id) || props.graph?.pending_node_ids?.includes(relation.target_id)),
+                    disabled: Boolean(props.graph?.disabled_node_ids?.includes(relation.source_id) || props.graph?.disabled_node_ids?.includes(relation.target_id)),
+                    searchMatch: normalizedSearchQuery.length > 0 && relation.kind.toLowerCase().includes(normalizedSearchQuery.toLowerCase()),
+                }];
+        }))).values()];
+    const attributesError = parsedAttributes === null ? "实体属性必须是 JSON 对象。" : null;
+    const graphDisabled = props.disabled || props.graph?.capability === "unavailable";
+    const saveEntity = () => {
+        if (entityId.trim().length === 0 || entityKind.trim().length === 0)
+            return;
+        if (parsedAttributes === null)
+            return;
+        const next = { ...parsedAttributes };
+        if (spatialRef.length > 0) {
+            if (!props.spatialObjects.some((object) => object.id === spatialRef)) {
+                setSpatialRefError("spatial_ref 必须指向当前 source readback 中的空间对象。");
+                return;
+            }
+            next.spatial_ref = spatialRef;
+        }
+        else {
+            delete next.spatial_ref;
+        }
+        setSpatialRefError(null);
+        void props.onSaveEntity({ node_id: entityId.trim(), kind: entityKind.trim(), attributes: next });
+    };
+    const renderInspectorBody = props.renderInspector ?? ((node) => (_jsxs(_Fragment, { children: [_jsxs("dl", { children: [_jsx("dt", { children: "\u8282\u70B9" }), _jsx("dd", { children: node.label }), _jsx("dt", { children: "\u7C7B\u578B" }), _jsx("dd", { children: node.kind }), _jsx("dt", { children: "\u8BF4\u660E" }), _jsx("dd", { children: node.description ?? "无" }), _jsx("dt", { children: "\u5173\u7CFB" }), _jsx("dd", { children: node.relations.length }), _jsx("dt", { children: "\u5C5E\u6027\u5386\u53F2" }), _jsx("dd", { children: node.history.length })] }), _jsx("ul", { "aria-label": "\u5B9E\u4F53\u5173\u7CFB", children: [...node.relations].sort((left, right) => compareCodepoint(left.source_id, right.source_id) || compareCodepoint(left.kind, right.kind) || compareCodepoint(left.target_id, right.target_id)).map((relation) => {
+                    const direction = relation.source_id === relation.target_id ? "自环" : relation.source_id === node.node_id ? "出" : "入";
+                    return _jsxs("li", { children: [_jsx("span", { "aria-label": `关系方向 ${direction}`, children: direction }), " \u00B7 ", relation.source_id, " \u2014", relation.kind, "\u2192 ", relation.target_id, props.onDeleteRelation === undefined ? null : _jsx("button", { disabled: graphDisabled, onClick: () => void props.onDeleteRelation?.(relation.source_id, relation.target_id, relation.kind), type: "button", children: "\u5220\u9664\u5173\u7CFB" })] }, `${relation.source_id}:${relation.kind}:${relation.target_id}`);
+                }) }), _jsx("ul", { "aria-label": "\u5B9E\u4F53\u5C5E\u6027", children: Object.keys(node.attributes).sort().map((key) => _jsxs("li", { children: [key, props.onUnsetAttribute === undefined ? null : _jsx("button", { disabled: props.disabled, onClick: () => void props.onUnsetAttribute?.(node.node_id, key), type: "button", children: "\u79FB\u9664\u5C5E\u6027" })] }, key)) }), props.onDeleteEntity === undefined ? null : _jsx("button", { disabled: props.disabled, onClick: () => void props.onDeleteEntity?.(node.node_id), type: "button", children: "\u5220\u9664\u5B9E\u4F53" })] })));
+    return (_jsxs("section", { "aria-label": "Ladybug \u56FE\u8C31", "data-testid": "ladybug-explorer", children: [_jsxs("form", { "aria-label": "Ladybug \u641C\u7D22", onSubmit: (event) => { event.preventDefault(); if (query.trim().length > 0)
+                    void props.onSearch(query.trim()); }, children: [_jsx("input", { "aria-label": "\u641C\u7D22\u5B9E\u4F53", disabled: props.disabled, onChange: (event) => setQuery(event.target.value), value: query }), _jsx("button", { disabled: props.disabled || query.trim().length === 0, type: "submit", children: "\u641C\u7D22" }), props.page?.capability === "ready" && props.page.mode === "search" && props.onBrowsePage !== undefined ? _jsx("button", { disabled: props.disabled, onClick: () => void props.onBrowsePage?.("first"), type: "button", children: "\u8FD4\u56DE\u5168\u91CF\u5B9E\u4F53" }) : null] }), _jsxs("div", { "aria-label": "Ladybug GraphCanvas", children: [props.graph?.capability === "unavailable" ? _jsx("p", { role: "alert", children: "GraphCanvas layout \u6295\u5F71\u4E0D\u53EF\u7528\uFF0C\u5DF2\u7981\u7528\u7F16\u8F91\u4EE5\u4FDD\u62A4 source readback\u3002" }) : null, props.renderGraphCanvas?.(props) ?? _jsx(SharedGraphCanvas, { disabled: graphDisabled, nodes: props.nodes.map((node) => ({ id: node.node_id, label: node.label, kind: node.kind, disabled: Boolean(props.graph?.disabled_node_ids?.includes(node.node_id)), pending: Boolean(props.graph?.pending_node_ids?.includes(node.node_id)), ...(props.graph?.vector_state_by_node_id?.[node.node_id] === undefined ? {} : { vector: props.graph.vector_state_by_node_id[node.node_id] }) })), onCommitPositions: (positions) => void props.onCommitGraphPositions?.(positions), ...(props.onCreateRelation === undefined ? {} : { onRelationDragIntent: (source, target) => setRelationIntent({ source, target }) }), onSelectNode: (id) => void props.onSelect(id), relations: relations, searchQuery: normalizedSearchQuery, selectedNodeId: props.selected_node_id, ...(props.graph?.positions === undefined ? {} : { positions: props.graph.positions }) })] }), _jsx(LadybugTable, { disabled: props.disabled, nodes: props.nodes, onSelect: props.onSelect, selected_node_id: props.selected_node_id, ...(props.page === undefined ? {} : { page: props.page }), ...(props.onBrowsePage === undefined ? {} : { onBrowsePage: props.onBrowsePage }) }), relationIntent === null ? null : _jsxs("form", { "aria-label": "\u65B0\u5EFA\u5173\u7CFB", onSubmit: (event) => { event.preventDefault(); if (relationKind.trim().length === 0 || props.onCreateRelation === undefined)
+                    return; void props.onCreateRelation(relationIntent.source, relationIntent.target, relationKind.trim()); setRelationIntent(null); setRelationKind(""); }, children: [_jsxs("p", { children: [relationIntent.source, " \u2192 ", relationIntent.target] }), _jsx("input", { "aria-label": "\u65B0\u5173\u7CFB\u7C7B\u578B", onChange: (event) => setRelationKind(event.target.value), value: relationKind }), _jsx("button", { disabled: graphDisabled || relationKind.trim().length === 0 || props.onCreateRelation === undefined, type: "submit", children: "\u521B\u5EFA\u5173\u7CFB" }), _jsx("button", { onClick: () => setRelationIntent(null), type: "button", children: "\u53D6\u6D88" })] }), _jsx(LadybugInspector, { node: selected, renderBody: renderInspectorBody, ...(props.renderInspector === undefined ? {} : { renderEmpty: () => props.renderInspector(null) }) }), _jsx(LadybugHistory, { canRedo: props.history?.can_redo ?? false, canUndo: props.history?.can_undo ?? false, entries: props.history?.entries ?? selected?.history.map((entry, index) => ({ id: `${selected.node_id}:${index}`, label: typeof entry.label === "string" ? entry.label : `历史 ${index + 1}` })) ?? [], ...(props.onRedo === undefined ? {} : { onRedo: () => void props.onRedo?.() }), ...(props.onUndo === undefined ? {} : { onUndo: () => void props.onUndo?.() }) }), _jsxs("form", { "aria-label": "\u5B9E\u4F53\u7F16\u8F91", onSubmit: (event) => { event.preventDefault(); saveEntity(); }, children: [_jsx("input", { "aria-label": "\u5B9E\u4F53 ID", disabled: props.disabled, onChange: (event) => setEntityId(event.target.value), value: entityId }), _jsx("input", { "aria-label": "\u5B9E\u4F53\u7C7B\u578B", disabled: props.disabled, onChange: (event) => setEntityKind(event.target.value), value: entityKind }), _jsx("textarea", { "aria-label": "\u5B9E\u4F53\u5C5E\u6027 JSON", disabled: props.disabled, onChange: (event) => setAttributes(event.target.value), value: attributes }), _jsxs("label", { children: ["spatial_ref", _jsxs("select", { "aria-label": "Ladybug spatial_ref", disabled: props.disabled, onChange: (event) => setSpatialRef(event.target.value), value: spatialRef, children: [_jsx("option", { value: "", children: "\u65E0\u7A7A\u95F4\u5F15\u7528" }), props.spatialObjects.map((object) => _jsxs("option", { value: object.id, children: [object.label, " \u00B7 ", object.id] }, object.id))] })] }), attributesError === null ? null : _jsx("p", { role: "alert", children: attributesError }), spatialRefError === null ? null : _jsx("p", { role: "alert", children: spatialRefError }), _jsx("button", { disabled: props.disabled || attributesError !== null || entityId.trim().length === 0 || entityKind.trim().length === 0, type: "submit", children: "\u4FDD\u5B58\u5B9E\u4F53" })] })] }));
+}

package/dist/ladybug/LadybugSurfaces.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type { LadybugNode } from "./LadybugExplorer.js";
+export interface LadybugInspectorProps {
+    readonly node: LadybugNode | null;
+    readonly disabled?: boolean;
+    /** Browser 注入现有成熟编辑 body；共享外壳不读取 Browser store。 */
+    readonly renderBody?: (node: LadybugNode) => ReactNode;
+    readonly renderEmpty?: () => ReactNode;
+}
+/** Browser 与 Desktop 共用的 Inspector 外壳；宿主差异只存在于注入的数据和 mutation adapter。 */
+export declare function LadybugInspector({ node, renderBody, renderEmpty }: LadybugInspectorProps): JSX.Element;
+export interface LadybugHistoryEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly timestamp?: number;
+}
+export interface LadybugHistoryProps {
+    readonly entries: readonly LadybugHistoryEntry[];
+    readonly canUndo?: boolean;
+    readonly canRedo?: boolean;
+    readonly onUndo?: () => void;
+    readonly onRedo?: () => void;
+}
+/** 仅渲染 history 投影并发出 intent；OPFS/IndexedDB/ProjectHost 持久化由各宿主 adapter 负责。 */
+export declare function LadybugHistory({ entries, canUndo, canRedo, onUndo, onRedo }: LadybugHistoryProps): JSX.Element;

package/dist/ladybug/LadybugSurfaces.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** Browser 与 Desktop 共用的 Inspector 外壳；宿主差异只存在于注入的数据和 mutation adapter。 */
+export function LadybugInspector({ node, renderBody, renderEmpty }) {
+    return (_jsx("aside", { "aria-label": "Ladybug Inspector", "data-testid": "ladybug-inspector", style: { display: "contents" }, children: node === null ? renderEmpty?.() ?? _jsx("p", { children: "\u9009\u62E9\u4E00\u4E2A\u8282\u70B9\u4EE5\u67E5\u770B Inspector\u3002" }) : renderBody?.(node) ?? (_jsxs("dl", { children: [_jsx("dt", { children: "\u8282\u70B9" }), _jsx("dd", { children: node.label }), _jsx("dt", { children: "\u7C7B\u578B" }), _jsx("dd", { children: node.kind }), _jsx("dt", { children: "\u8BF4\u660E" }), _jsx("dd", { children: node.description ?? "无" }), _jsx("dt", { children: "\u5173\u7CFB" }), _jsx("dd", { children: node.relations.length }), _jsx("dt", { children: "\u5C5E\u6027\u5386\u53F2" }), _jsx("dd", { children: node.history.length })] })) }));
+}
+/** 仅渲染 history 投影并发出 intent；OPFS/IndexedDB/ProjectHost 持久化由各宿主 adapter 负责。 */
+export function LadybugHistory({ entries, canUndo = false, canRedo = false, onUndo, onRedo }) {
+    return (_jsxs("section", { "aria-label": "Ladybug History", "data-testid": "ladybug-history", children: [_jsxs("div", { role: "toolbar", "aria-label": "Ladybug \u5386\u53F2\u64CD\u4F5C", children: [_jsx("button", { disabled: !canUndo || onUndo === undefined, onClick: onUndo, type: "button", children: "\u64A4\u9500" }), _jsx("button", { disabled: !canRedo || onRedo === undefined, onClick: onRedo, type: "button", children: "\u91CD\u505A" })] }), entries.length === 0 ? _jsx("p", { children: "\u6682\u65E0\u5386\u53F2\u8BB0\u5F55\u3002" }) : _jsx("ol", { children: entries.map((entry) => _jsx("li", { children: entry.label }, entry.id)) })] }));
+}

package/dist/ladybug/LadybugTable.d.ts

@@ -0,0 +1,15 @@
+import type { LadybugPageProjection } from "../DesktopAuthoringShell.js";
+import type { LadybugNode } from "./LadybugExplorer.js";
+export interface LadybugTableProps {
+    readonly disabled: boolean;
+    readonly nodes: readonly LadybugNode[];
+    readonly selected_node_id: string | null;
+    readonly onSelect: (node_id: string) => Promise<void>;
+    readonly page?: LadybugPageProjection;
+    readonly onBrowsePage?: (direction: "first" | "next" | "previous") => Promise<void>;
+}
+/**
+ * ready page 完全消费 Host cursor；旧调用方没有 page projection 时才保留组件内分页，
+ * 不能把该兼容路径当作完整数据库浏览能力。
+ */
+export declare function LadybugTable(props: LadybugTableProps): JSX.Element;

package/dist/ladybug/LadybugTable.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+const PAGE_SIZE = 20;
+function compareCodepoint(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * ready page 完全消费 Host cursor；旧调用方没有 page projection 时才保留组件内分页，
+ * 不能把该兼容路径当作完整数据库浏览能力。
+ */
+export function LadybugTable(props) {
+    const [page, setPage] = useState(0);
+    const sorted = useMemo(() => [...props.nodes].sort((left, right) => compareCodepoint(left.node_id, right.node_id)
+        || compareCodepoint(left.kind, right.kind)
+        || compareCodepoint(left.label, right.label)), [props.nodes]);
+    const hostPage = props.page?.capability === "ready" ? props.page : null;
+    const hostVisible = hostPage === null ? sorted : hostPage.item_ids.flatMap((id) => {
+        const node = sorted.find((candidate) => candidate.node_id === id);
+        return node === undefined ? [] : [node];
+    });
+    const pageCount = Math.max(1, Math.ceil(sorted.length / PAGE_SIZE));
+    const safePage = Math.min(page, pageCount - 1);
+    const visible = hostPage === null ? sorted.slice(safePage * PAGE_SIZE, (safePage + 1) * PAGE_SIZE) : hostVisible;
+    useEffect(() => setPage(0), [props.nodes]);
+    return (_jsxs("section", { "aria-label": "Ladybug \u5B9E\u4F53\u8868", children: [props.page?.capability === "unavailable" ? _jsx("p", { role: "alert", children: props.page.reason }) : null, _jsx("p", { role: "status", children: hostPage === null ? `当前结果 ${sorted.length} 个实体；第 ${safePage + 1}/${pageCount} 页` : hostPage.mode === "browse" ? `全量实体：本页 ${visible.length} 个，共 ${hostPage.total_count ?? "未知"} 个` : `搜索结果 ${visible.length} 个` }), _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "\u64CD\u4F5C" }), _jsx("th", { children: "ID" }), _jsx("th", { children: "\u7C7B\u578B" }), _jsx("th", { children: "\u6807\u7B7E" }), _jsx("th", { children: "\u5C5E\u6027" }), _jsx("th", { children: "\u5173\u7CFB" })] }) }), _jsx("tbody", { children: visible.map((node) => _jsxs("tr", { "aria-selected": node.node_id === props.selected_node_id, children: [_jsx("td", { children: _jsx("button", { disabled: props.disabled, onClick: () => void props.onSelect(node.node_id), type: "button", children: "\u9009\u62E9" }) }), _jsx("td", { children: node.node_id }), _jsx("td", { children: node.kind }), _jsx("td", { children: node.label }), _jsx("td", { children: Object.keys(node.attributes).length }), _jsx("td", { children: node.relations.length })] }, node.node_id)) })] }), sorted.length === 0 ? _jsx("p", { children: props.page?.capability === "ready" && props.page.mode === "browse" ? "数据库当前没有实体。" : "没有匹配的实体。" }) : null, hostPage?.mode === "browse" ? _jsx("p", { children: "\u5168\u91CF\u9875\u53EA\u8BFB\u53D6\u5B9E\u4F53\uFF1B\u5173\u7CFB\u5728\u9009\u62E9\u5B9E\u4F53\u540E\u70B9\u67E5\u3002\u5F53\u524D Host \u7684\u70B9\u67E5\u5173\u7CFB\u5C1A\u672A\u63D0\u4F9B\u72EC\u7ACB\u5206\u9875\u3002" }) : null, _jsxs("nav", { "aria-label": "Ladybug \u5B9E\u4F53\u5206\u9875", children: [_jsx("button", { disabled: props.disabled || (hostPage === null ? safePage === 0 : hostPage.mode !== "browse" || !hostPage.has_previous || props.onBrowsePage === undefined), onClick: () => hostPage === null ? setPage((current) => Math.max(0, current - 1)) : void props.onBrowsePage?.("previous"), type: "button", children: "\u4E0A\u4E00\u9875" }), _jsx("button", { disabled: props.disabled || (hostPage === null ? safePage + 1 >= pageCount : hostPage.mode !== "browse" || hostPage.next_cursor === null || props.onBrowsePage === undefined), onClick: () => hostPage === null ? setPage((current) => Math.min(pageCount - 1, current + 1)) : void props.onBrowsePage?.("next"), type: "button", children: "\u4E0B\u4E00\u9875" })] })] }));
+}

package/dist/ladybug/entity-props.d.ts

@@ -0,0 +1,98 @@
+import type { TriggerDef } from "@world-engines/blocks-editor";
+import type { ViewAccessMode } from "@world-engines/ladybug-bridge";
+import { SERIALIZED_PROP_ENVELOPE_MARKER } from "@world-engines/protocol-ts/entity-prop-envelope";
+export type { ViewAccessMode } from "@world-engines/ladybug-bridge";
+export interface GraphSourceReference {
+    readonly document_entity_id: string;
+    readonly chunk_entity_id: string;
+    readonly chunk_sha256: string;
+    readonly source_start: number;
+    readonly source_end: number;
+}
+export type GraphTriggerDef = TriggerDef & {
+    readonly source_refs?: ReadonlyArray<GraphSourceReference>;
+};
+export type EntityReferenceKind = "node" | "edge" | "attr";
+export interface EntityReferenceTarget {
+    readonly kind: EntityReferenceKind;
+    readonly id: string;
+    readonly attr_key?: string;
+}
+export interface EntityReferenceValue {
+    readonly $ref: EntityReferenceTarget;
+}
+export interface ScenarioAssetReferenceValue {
+    readonly $asset: string;
+}
+export type EntityRichTextSegment = {
+    readonly text: string;
+} | EntityReferenceValue;
+export interface EntityRichTextValue {
+    readonly $rich: ReadonlyArray<EntityRichTextSegment>;
+}
+export type EntityPropObject = {
+    readonly [subKey: string]: EntityProp;
+};
+export type EntityPropArray = ReadonlyArray<EntityProp>;
+export type EntityPropValue = string | ScenarioAssetReferenceValue | EntityReferenceValue | EntityRichTextValue | EntityPropArray | EntityPropObject;
+export type EntityStateKind = "available" | "disabled" | "frozen";
+export interface FrozenEntry {
+    readonly source_id: string;
+    readonly prev_state?: EntityStateKind;
+    readonly additional_state?: EntityStateKind;
+    readonly cancel_condition?: TriggerDef;
+    readonly expires_at?: number;
+}
+export interface AttrState {
+    readonly id: string;
+    readonly value: EntityPropValue;
+    readonly enter_when_trigger_id?: string;
+    readonly locked_until_trigger_id?: string;
+    readonly kind?: EntityStateKind;
+    readonly frozen_stack?: ReadonlyArray<FrozenEntry>;
+    readonly dead?: boolean;
+    readonly disabled?: boolean;
+}
+export interface EntityProp {
+    readonly value: EntityPropValue;
+    readonly view_access?: ViewAccessMode;
+    readonly trigger?: GraphTriggerDef;
+    readonly source_refs?: ReadonlyArray<GraphSourceReference>;
+    readonly states?: ReadonlyArray<AttrState>;
+    readonly title?: string;
+    readonly initial_available?: boolean;
+}
+export declare const isPropScalar: (v: EntityPropValue) => v is string;
+export declare const isEntityReferenceValue: (value: unknown) => value is EntityReferenceValue;
+export declare const isScenarioAssetReferenceValue: (value: unknown) => value is ScenarioAssetReferenceValue;
+export declare const isPropArray: (v: EntityPropValue) => v is EntityPropArray;
+export declare const isPropReference: (v: EntityPropValue) => v is EntityReferenceValue;
+export declare const isPropRichText: (v: EntityPropValue) => v is EntityRichTextValue;
+export declare const isPropTree: (v: EntityPropValue) => v is EntityPropObject;
+export declare const propValueToText: (v: EntityPropValue) => string;
+export type PropShape = "scalar" | "tree" | "array" | "reference" | "richtext";
+export declare const propShape: (v: EntityPropValue) => PropShape;
+export declare const normalizeEntityProps: (raw: unknown) => Record<string, EntityProp>;
+export declare const convertPropShape: (v: EntityPropValue, target: PropShape, defaultKey: string) => EntityPropValue;
+export declare const emptyPropValue: (shape: PropShape) => EntityPropValue;
+export type SerializedPropValue = string | ScenarioAssetReferenceValue | EntityReferenceValue | EntityRichTextValue | ReadonlyArray<SerializedProp> | {
+    readonly [subKey: string]: SerializedProp;
+};
+export type SerializedProp = SerializedPropValue | {
+    readonly [SERIALIZED_PROP_ENVELOPE_MARKER]: true;
+    readonly value: SerializedPropValue;
+    readonly trigger?: TriggerDef;
+    readonly states?: ReadonlyArray<Record<string, unknown>>;
+    readonly title?: string;
+    readonly initial_available?: boolean;
+    readonly source_refs?: ReadonlyArray<GraphSourceReference>;
+    readonly view_access?: ViewAccessMode;
+};
+export declare const serializeEntityProps: (props: Record<string, EntityProp>) => Record<string, SerializedProp>;
+export declare const toStringPropsLegacy: (props: Record<string, EntityProp>) => Record<string, string>;
+export declare const propValue: (props: Record<string, EntityProp>, key: string) => string;
+export declare const activeAttrState: (prop: EntityProp) => AttrState | undefined;
+export declare const isPropDead: (prop: EntityProp) => boolean;
+export declare const effectivePropValue: (prop: EntityProp) => EntityPropValue | undefined;
+export declare const effectivePropValueText: (prop: EntityProp) => string;
+export declare const isEntityFullyDead: (props: Record<string, EntityProp>) => boolean;