@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/lib/types/client/surface-context.js

@@ -0,0 +1,104 @@
+export const DATA_SHEET_SURFACE_ID = 'data-sheet';
+/** Keep source-specific focus data opaque to the bridge, but stable in transcript metadata. */
+export function dataSheetFocusId(target) {
+    return JSON.stringify(target);
+}
+/** Decode a focus id emitted by this source. */
+export function dataSheetFocusTargetOf(value) {
+    try {
+        const target = JSON.parse(value);
+        if (typeof target.workbookId !== 'string' || typeof target.sheetId !== 'string')
+            return undefined;
+        for (const key of ['startRow', 'startColumn', 'endRow', 'endColumn']) {
+            if (!Number.isSafeInteger(target[key]) || target[key] < 0)
+                return undefined;
+        }
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+function columnName(index) {
+    let value = index + 1;
+    let name = '';
+    while (value > 0) {
+        const remainder = (value - 1) % 26;
+        name = String.fromCharCode(65 + remainder) + name;
+        value = Math.floor((value - 1) / 26);
+    }
+    return name;
+}
+function cellAddress(row, column) {
+    return `${columnName(column)}${row + 1}`;
+}
+function rangeAddress(range) {
+    const start = cellAddress(range.startRow, range.startColumn);
+    const end = cellAddress(range.endRow, range.endColumn);
+    return `${range.sheetName}!${start === end ? start : `${start}:${end}`}`;
+}
+function cellText(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return String(value);
+    }
+}
+function previewText(values) {
+    if (values.length === 0)
+        return undefined;
+    const rendered = values.map(row => row.map(cellText).join('\t')).join('\n').slice(0, 2_000);
+    return rendered.length === 0 ? undefined : rendered;
+}
+/** Project the active Univer ranges into the bridge's shared context vocabulary. */
+export function projectDataSheetSelection(input) {
+    const ranges = input.ranges.filter(range => range.startRow <= range.endRow && range.startColumn <= range.endColumn);
+    if (ranges.length === 0)
+        return null;
+    const count = ranges.reduce((total, range) => total
+        + (range.endRow - range.startRow + 1) * (range.endColumn - range.startColumn + 1), 0);
+    const items = ranges.slice(0, 40).map(range => {
+        const address = rangeAddress(range);
+        return {
+            id: dataSheetFocusId({ workbookId: input.workbookId, ...range }),
+            type: 'range',
+            label: address,
+            ...(previewText(range.values) === undefined ? {} : { text: previewText(range.values) }),
+            attributes: {
+                workbookId: input.workbookId,
+                sheetId: range.sheetId,
+                sheetName: range.sheetName,
+                address,
+                startRow: range.startRow,
+                startColumn: range.startColumn,
+                endRow: range.endRow,
+                endColumn: range.endColumn,
+            },
+        };
+    });
+    const labels = ranges.map(rangeAddress);
+    const summary = ranges.length === 1
+        ? `已选中 ${labels[0]}，共 ${count} 个单元格`
+        : `已选中 ${ranges.length} 个区域，共 ${count} 个单元格`;
+    const note = `工作簿 ID：${input.workbookId}；选区：${labels.join('、')}。条目文本最多预览每个区域前 10 行 × 20 列；完整数据用 workbook_read(workbookId="${input.workbookId}", target={kind:"range", sheetId, range}) 读取。写入前先读取最新 revision，再用 workbook_edit。`;
+    return {
+        source: DATA_SHEET_SURFACE_ID,
+        revision: input.revision,
+        count,
+        countLabel: `${count} 个单元格`,
+        title: 'Table',
+        summary,
+        items,
+        ...(ranges.length > items.length ? { truncated: true } : {}),
+        resource: { name: input.workbookId, display: input.workbookName, version: input.documentRevision },
+        notes: [note],
+        capabilities: [`使用 workbook_read / workbook_edit 操作工作簿 ${input.workbookId}；写入时传该 id 和最新 revision。`],
+    };
+}

package/lib/types/client/surface-control.d.ts

@@ -0,0 +1,2 @@
+export declare function registerDataSheetFocusHandler(handler: (itemId: string) => void): () => void;
+export declare function focusDataSheetItem(itemId: string): void;

package/lib/types/client/surface-control.js

@@ -0,0 +1,12 @@
+/** One live workbook view can honour focus requests from the shared bridge chip. */
+let focusHandler;
+export function registerDataSheetFocusHandler(handler) {
+    focusHandler = handler;
+    return () => {
+        if (focusHandler === handler)
+            focusHandler = undefined;
+    };
+}
+export function focusDataSheetItem(itemId) {
+    focusHandler?.(itemId);
+}

package/lib/types/client/transport/workbookApi.d.ts

@@ -0,0 +1,159 @@
+import type { WorkbookLocalChange, WorkbookOperation, WorkbookSummary, WorkbookChange, WorkbookPresencePayload, WorkbookHistoryVersion } from '../../types.ts';
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: unknown | undefined;
+    constructor(status: number, message: string, code?: string | undefined, details?: unknown | undefined);
+}
+export declare class RevisionConflictError extends HttpStatusError {
+    constructor(message?: string, details?: unknown);
+}
+/** Tell the transport which DSH Session this page belongs to. */
+export declare function setDshSessionId(id: string | undefined): void;
+/** The Session this page is bound to, when it is bound to one. */
+export declare function currentDshSessionId(): string | null;
+/** Route browser requests through the official Electron Connection carrier. */
+export declare function dataSheetClientPath(path: string): string;
+/** Stable per-tab scope used by worktree APIs and Host audit logs. */
+export declare function dataSheetSessionId(): string;
+/**
+ * The live collaboration stream for one workbook.
+ *
+ * `EventSource` cannot set the `x-dsh-session` header every other call carries,
+ * so the Session — which decides *which project's* workbook this is — travels as
+ * a query parameter it can carry. The `session` parameter is a different thing:
+ * this browser tab's own id, used for presence and worktrees.
+ *
+ * @param workbookId - Workbook to watch.
+ * @param after - Revision to resume from.
+ * @returns a same-origin path, ready for `dataSheetClientPath`.
+ */
+export declare function collaborationStreamPath(workbookId: string, after: number): string;
+/**
+ * The standalone page for one workbook.
+ *
+ * A new tab has no sidebar to hand it a Session id, so the project travels in
+ * the URL: without it the page resolves against the sandbox policy root and
+ * could open another project's workbook.
+ *
+ * @param workbookId - Workbook to open in a plain browser document.
+ * @returns a same-origin path.
+ */
+export declare function standaloneWorkbookPath(workbookId: string): string;
+export interface WorkbookEnvelope {
+    ok?: boolean;
+    workbookId?: string;
+    revision?: number;
+    updatedAt?: string;
+    snapshot?: object;
+}
+export interface ChangesEnvelope {
+    revision?: number;
+    operations?: WorkbookOperation[];
+    requiresSnapshot?: boolean;
+    snapshot?: object;
+}
+export interface HistoryEntry {
+    opId: string;
+    revision: number;
+    parentRevision?: number;
+    actor: 'agent' | 'user';
+    type: string;
+    timestamp: string;
+    summary: string;
+    canPreview?: boolean;
+}
+export interface HistoryEnvelope {
+    entries?: HistoryEntry[];
+    versions?: WorkbookHistoryVersion[];
+    checkpoints?: number[];
+    revision?: number;
+}
+export interface HistoryDiffEnvelope {
+    workbookId?: string;
+    from?: number;
+    to?: number;
+    changes?: WorkbookChange[];
+    /** True when the server stopped at its diff limit, so the counts are a floor. */
+    truncated?: boolean;
+}
+export interface WorkbookMutationEnvelope {
+    workbook?: {
+        id: string;
+        name: string;
+        sheets?: WorkbookSummary['sheets'];
+        updatedAt?: string;
+    };
+}
+export declare function fetchWorkbook(id: string): Promise<WorkbookEnvelope>;
+/** One entry of the project file chooser's listing; mirrors the Host's shape. */
+export interface ProjectFileEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    size: number;
+    createdAt: string;
+    modifiedAt: string;
+}
+/** One directory of `<project>/storages`, with sizes and dates. */
+export declare function fetchProjectFiles(directory: string): Promise<{
+    directory: string;
+    entries: ProjectFileEntry[];
+    truncated?: number;
+}>;
+/**
+ * Read one file the chooser listed.
+ *
+ * The browser cannot open a path, so the Host reads it and the bytes arrive here
+ * as a buffer, ready for the import pipeline that already existed.
+ */
+export declare function readProjectFile(path: string): Promise<{
+    name: string;
+    data: ArrayBuffer;
+}>;
+export declare function fetchWorkbooks(): Promise<{
+    workbooks?: WorkbookSummary[];
+}>;
+export declare function createWorkbook(name: string): Promise<WorkbookMutationEnvelope>;
+export declare function renameWorkbook(id: string, name: string): Promise<WorkbookMutationEnvelope>;
+export declare function fetchChanges(id: string, after: number): Promise<ChangesEnvelope>;
+export declare function fetchHistory(id: string): Promise<HistoryEnvelope>;
+export interface HistorySnapshotEnvelope {
+    revision?: number;
+    snapshot?: object;
+    step?: number;
+    stepCount?: number;
+    /** True when the Step's change list stopped at the server's limit. */
+    truncated?: boolean;
+    /**
+     * What the requested Step changed. Present for Step previews, so the canvas
+     * can locate and tint the cells instead of leaving the reader to find them
+     * (PRD v3.3 §7.2).
+     */
+    changes?: WorkbookChange[];
+}
+export declare function fetchHistorySnapshot(id: string, revision: number, step?: number): Promise<HistorySnapshotEnvelope>;
+export declare function fetchHistoryDiff(id: string, from: number, to: number): Promise<HistoryDiffEnvelope>;
+export declare function rollbackWorkbook(id: string, targetRevision: number, baseRevision: number, summary?: string): Promise<{
+    revision?: number;
+}>;
+export declare function deleteWorkbook(id: string): Promise<void>;
+export interface SaveResult {
+    revision: number;
+    operation?: WorkbookOperation;
+    rebasedOperations?: WorkbookOperation[];
+}
+export declare function saveOperationChanges(id: string, changes: WorkbookLocalChange[], baseRevision: number, opId: string, version?: {
+    id: string;
+    status: 'open' | 'final';
+}): Promise<SaveResult | null>;
+export interface SnapshotSaveOptions {
+    /** Named save: the Version gets this summary and closes the session. */
+    summary?: string;
+    /** Session Step: joins the open user Version (PRD v3.1 §4). */
+    versionId?: string;
+    versionStatus?: 'open' | 'final';
+    versionKind?: 'named' | 'auto';
+}
+export declare function saveSnapshot(id: string, snapshotData: unknown, baseRevision: number, opId: string, options?: SnapshotSaveOptions): Promise<SaveResult | null>;
+export declare function publishPresence(workbookId: string, presence: WorkbookPresencePayload): Promise<void>;

package/lib/types/client/transport/workbookApi.js

@@ -0,0 +1,246 @@
+export class HttpStatusError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, message, code, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'HttpStatusError';
+    }
+}
+export class RevisionConflictError extends HttpStatusError {
+    constructor(message = 'workbook revision conflict', details) {
+        super(409, message, 'REVISION_CONFLICT', details);
+        this.name = 'RevisionConflictError';
+    }
+}
+const SESSION_STORAGE_KEY = 'data-sheet.session-id';
+let cachedSessionId = null;
+/**
+ * The DSH Session whose project this page reads and writes.
+ *
+ * Set once when the panel mounts (the sidebar hands its Session id to the body)
+ * or, for the standalone page, read from its URL. Every workbook path is
+ * resolved by the Host inside that Session's project —
+ * `<project>/storages/data-table` — so a request that names the wrong Session
+ * reads and writes another project's workbooks. A request that names **no**
+ * Session keeps the pre-project per-user store instead, which is right for a
+ * script and wrong for a page: the panel always sets this.
+ */
+let dshSessionId = null;
+/** Tell the transport which DSH Session this page belongs to. */
+export function setDshSessionId(id) {
+    dshSessionId = id === undefined || id.length === 0 ? null : id;
+}
+/** The Session this page is bound to, when it is bound to one. */
+export function currentDshSessionId() {
+    return dshSessionId;
+}
+/** Route browser requests through the official Electron Connection carrier. */
+export function dataSheetClientPath(path) {
+    const transport = globalThis.__DSH_TRANSPORT__;
+    return transport?.ownsHost === true
+        ? `/api/data-sheet?path=${encodeURIComponent(path)}`
+        : path;
+}
+/** Stable per-tab scope used by worktree APIs and Host audit logs. */
+export function dataSheetSessionId() {
+    if (cachedSessionId !== null)
+        return cachedSessionId;
+    try {
+        const existing = window.sessionStorage.getItem(SESSION_STORAGE_KEY);
+        if (existing !== null && existing.trim().length > 0) {
+            cachedSessionId = existing;
+            return existing;
+        }
+        const generated = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        window.sessionStorage.setItem(SESSION_STORAGE_KEY, generated);
+        cachedSessionId = generated;
+        return generated;
+    }
+    catch {
+        cachedSessionId = `ephemeral-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        return cachedSessionId;
+    }
+}
+/**
+ * The live collaboration stream for one workbook.
+ *
+ * `EventSource` cannot set the `x-dsh-session` header every other call carries,
+ * so the Session — which decides *which project's* workbook this is — travels as
+ * a query parameter it can carry. The `session` parameter is a different thing:
+ * this browser tab's own id, used for presence and worktrees.
+ *
+ * @param workbookId - Workbook to watch.
+ * @param after - Revision to resume from.
+ * @returns a same-origin path, ready for `dataSheetClientPath`.
+ */
+export function collaborationStreamPath(workbookId, after) {
+    const project = currentDshSessionId();
+    const scope = project === null ? '' : `&sessionId=${encodeURIComponent(project)}`;
+    return `/data-sheet/workbook/${encodeURIComponent(workbookId)}/collaboration?after=${after}`
+        + `&session=${encodeURIComponent(dataSheetSessionId())}${scope}`;
+}
+/**
+ * The standalone page for one workbook.
+ *
+ * A new tab has no sidebar to hand it a Session id, so the project travels in
+ * the URL: without it the page resolves against the sandbox policy root and
+ * could open another project's workbook.
+ *
+ * @param workbookId - Workbook to open in a plain browser document.
+ * @returns a same-origin path.
+ */
+export function standaloneWorkbookPath(workbookId) {
+    const project = currentDshSessionId();
+    return `/data-sheet/workbook/${encodeURIComponent(workbookId)}/view`
+        + (project === null ? '' : `?sessionId=${encodeURIComponent(project)}`);
+}
+async function requestJson(path, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set('accept', 'application/json');
+    headers.set('x-data-sheet-session', dataSheetSessionId());
+    // Which *project* the Host should resolve the path inside. Distinct from the
+    // header above, which is this browser tab's own id for worktrees and presence.
+    if (dshSessionId !== null)
+        headers.set('x-dsh-session', dshSessionId);
+    if (init.body !== undefined && !headers.has('content-type'))
+        headers.set('content-type', 'application/json');
+    let response = null;
+    let networkError = null;
+    // GETs and writes carrying an opId are safe to retry: the Host's idempotency
+    // check makes a lost response indistinguishable from a successful retry.
+    const retryable = init.method === undefined || init.method === 'GET' || init.method === 'HEAD'
+        || typeof init.body === 'string' && init.body.includes('"opId"');
+    for (let attempt = 0; attempt < (retryable ? 3 : 1); attempt += 1) {
+        try {
+            response = await fetch(dataSheetClientPath(path), { ...init, headers });
+            networkError = null;
+            break;
+        }
+        catch (error) {
+            networkError = error;
+            if (attempt + 1 < (retryable ? 3 : 1))
+                await new Promise(resolve => window.setTimeout(resolve, 150 * (attempt + 1)));
+        }
+    }
+    if (response === null) {
+        const detail = networkError instanceof Error ? networkError.message : '';
+        throw new HttpStatusError(0, detail === 'Failed to fetch' ? '网络请求失败，请确认 DSH 服务仍在运行后重试' : (detail || '网络请求失败'), 'NETWORK_ERROR', { detail });
+    }
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch { /* non-json host/proxy failure */ }
+    if (!response.ok) {
+        const record = typeof body === 'object' && body !== null ? body : {};
+        const message = typeof record.error === 'string' ? record.error
+            : typeof record.message === 'string' ? record.message
+                : `${response.status} ${response.statusText || '请求失败'}`;
+        const code = typeof record.code === 'string' ? record.code : undefined;
+        if (response.status === 409 || code === 'REVISION_CONFLICT')
+            throw new RevisionConflictError(message, body);
+        throw new HttpStatusError(response.status, message, code, body);
+    }
+    return body;
+}
+export async function fetchWorkbook(id) {
+    const value = await requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}.json`);
+    if (typeof value === 'object' && value !== null && 'snapshot' in value)
+        return value;
+    return { ok: true, workbookId: id, revision: 0, snapshot: value };
+}
+/** One directory of `<project>/storages`, with sizes and dates. */
+export async function fetchProjectFiles(directory) {
+    return requestJson(`/data-sheet/project-files.json?dir=${encodeURIComponent(directory)}`);
+}
+/**
+ * Read one file the chooser listed.
+ *
+ * The browser cannot open a path, so the Host reads it and the bytes arrive here
+ * as a buffer, ready for the import pipeline that already existed.
+ */
+export async function readProjectFile(path) {
+    const headers = new Headers({ accept: 'application/octet-stream' });
+    if (dshSessionId !== null)
+        headers.set('x-dsh-session', dshSessionId);
+    const response = await fetch(dataSheetClientPath(`/data-sheet/project-file.json?path=${encodeURIComponent(path)}`), { headers });
+    if (!response.ok) {
+        const body = await response.json().catch(() => null);
+        throw new HttpStatusError(response.status, typeof body?.error === 'string' ? body.error : `读取文件失败：${response.status}`);
+    }
+    const encoded = response.headers.get('x-file-name');
+    const name = encoded === null ? (path.split('/').pop() ?? path) : decodeURIComponent(encoded);
+    return { name, data: await response.arrayBuffer() };
+}
+export async function fetchWorkbooks() {
+    return requestJson('/data-sheet/workbooks.json');
+}
+export async function createWorkbook(name) {
+    return requestJson('/data-sheet/workbooks.json', {
+        method: 'POST',
+        body: JSON.stringify({ action: 'create', name }),
+    });
+}
+export async function renameWorkbook(id, name) {
+    return requestJson('/data-sheet/workbooks.json', {
+        method: 'POST',
+        body: JSON.stringify({ action: 'rename', workbookId: id, name }),
+    });
+}
+export async function fetchChanges(id, after) {
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/changes?after=${after}`);
+}
+export async function fetchHistory(id) {
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history`);
+}
+export async function fetchHistorySnapshot(id, revision, step) {
+    const query = step === undefined ? `revision=${revision}` : `revision=${revision}&step=${step}`;
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history?${query}`);
+}
+export async function fetchHistoryDiff(id, from, to) {
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/history/diff?from=${from}&to=${to}`);
+}
+export async function rollbackWorkbook(id, targetRevision, baseRevision, summary) {
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/rollback`, {
+        method: 'POST',
+        body: JSON.stringify({ targetRevision, baseRevision, ...(summary === undefined ? {} : { summary }) }),
+    });
+}
+export async function deleteWorkbook(id) {
+    await requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}.json?action=delete`, { method: 'POST', body: JSON.stringify({ confirm: true }) });
+}
+export async function saveOperationChanges(id, changes, baseRevision, opId, version) {
+    const operation = changes.length === 1 ? changes[0] : { type: 'batch', payload: { operations: changes } };
+    const body = JSON.stringify({ type: operation.type, payload: operation.payload, actor: 'user', baseRevision, opId, ...(version === undefined ? {} : { versionId: version.id, versionStatus: version.status }) });
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}/operations`, {
+        method: 'POST',
+        ...(body.length <= 60 * 1024 ? { keepalive: true } : {}),
+        body,
+    });
+}
+export async function saveSnapshot(id, snapshotData, baseRevision, opId, options = {}) {
+    return requestJson(`/data-sheet/workbook/${encodeURIComponent(id)}.json`, {
+        method: 'POST',
+        body: JSON.stringify({
+            snapshot: snapshotData,
+            baseRevision,
+            opId,
+            ...(options.summary === undefined ? {} : { versionSummary: options.summary }),
+            ...(options.versionId === undefined ? {} : { versionId: options.versionId }),
+            ...(options.versionStatus === undefined ? {} : { versionStatus: options.versionStatus }),
+            ...(options.versionKind === undefined ? {} : { versionKind: options.versionKind }),
+        }),
+    });
+}
+export async function publishPresence(workbookId, presence) {
+    await requestJson(`/data-sheet/workbook/${encodeURIComponent(workbookId)}/presence`, {
+        method: 'POST',
+        body: JSON.stringify(presence),
+    });
+}

package/lib/types/client/univer/StandaloneWorkbookPage.d.ts

@@ -0,0 +1,5 @@
+export interface StandaloneWorkbookPageProps {
+    workbookId: string;
+}
+/** Full-browser workbook workspace. It deliberately reuses the embedded controller. */
+export declare function StandaloneWorkbookPage({ workbookId }: StandaloneWorkbookPageProps): import("react").JSX.Element;

package/lib/types/client/univer/StandaloneWorkbookPage.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { WorkbookWorkspace } from "../SheetPanel.js";
+import styles from './StandaloneWorkbookPage.module.css';
+/** Full-browser workbook workspace. It deliberately reuses the embedded controller. */
+export function StandaloneWorkbookPage({ workbookId }) {
+    return (_jsx("main", { className: styles.root, children: _jsx(WorkbookWorkspace, { open: true, standalone: true, initialWorkbookId: workbookId }) }));
+}

package/lib/types/client/univer/WorkbookCanvas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared Univer canvas used by the embedded Datasheet panel and the
+ * standalone workbook page. The workspace owns persistence and sync; this
+ * component owns only Univer residency and its imperative editing surface.
+ */
+import { type WorkbookDecoration } from './loader.ts';
+import type { WorkbookFocusRange, WorkbookLocalChange, WorkbookOperation, WorkbookPresencePayload, WorkbookSelectionRange } from '../../types.ts';
+export interface WorkbookCanvasProps {
+    workbookData: object;
+    /**
+     * Preview residency (docs/issue/0002 PRD v3.2 §7.2): the canvas is showing a past
+     * Version rather than live content, so it is mounted with Univer's editable
+     * permission off and its mutations are never reported as changes. The caller
+     * owns the preview state; this component only refuses to fork a Version.
+     */
+    readOnly?: boolean;
+    /**
+     * Diff overlay for a preview residency: the cells that differ from the
+     * baseline, painted by the engine at mount (PRD v3.3 §7.2). Part of the
+     * residency, not a live API — a Step jump remounts the canvas, so a stale
+     * highlight cannot survive it.
+     */
+    decoration?: WorkbookDecoration;
+    onDirty?: (change?: WorkbookLocalChange) => void;
+    onPresence?: (presence: WorkbookPresencePayload) => void;
+    onSelectionChange?: (ranges: readonly WorkbookSelectionRange[]) => void;
+    onReady?: () => void;
+}
+export interface WorkbookCanvasHandle {
+    save(): unknown;
+    applyOperation(operation: WorkbookOperation): Promise<void>;
+    focusRange(range: WorkbookFocusRange): boolean;
+    /**
+     * Show a different workbook in the same residency. Returns false when the
+     * engine could not swap, so the caller can fall back to a remount.
+     */
+    swapWorkbook(next: object, decoration?: WorkbookDecoration): boolean;
+}
+/** Resident workbook canvas shared by embedded and standalone workspaces. */
+export declare const WorkbookCanvas: import("react").ForwardRefExoticComponent<WorkbookCanvasProps & import("react").RefAttributes<WorkbookCanvasHandle>>;

package/lib/types/client/univer/WorkbookCanvas.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Shared Univer canvas used by the embedded Datasheet panel and the
+ * standalone workbook page. The workspace owns persistence and sync; this
+ * component owns only Univer residency and its imperative editing surface.
+ */
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { mountWorkbook } from "./loader.js";
+import styles from './WorkbookView.module.css';
+/** Resident workbook canvas shared by embedded and standalone workspaces. */
+export const WorkbookCanvas = forwardRef(function WorkbookCanvas({ workbookData, readOnly = false, decoration, onDirty, onPresence, onSelectionChange, onReady }, ref) {
+    const containerRef = useRef(null);
+    const handleRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    const [failed, setFailed] = useState(false);
+    // Read through a ref so the mount effect stays keyed on the residency
+    // itself: `workbookData`/`readOnly` are fixed for a residency's lifetime,
+    // and the caller switches residency by changing the React `key`.
+    const readOnlyRef = useRef(readOnly);
+    readOnlyRef.current = readOnly;
+    const decorationRef = useRef(decoration);
+    decorationRef.current = decoration;
+    const selectionChangeRef = useRef(onSelectionChange);
+    selectionChangeRef.current = onSelectionChange;
+    const readyRef = useRef(onReady);
+    readyRef.current = onReady;
+    useEffect(() => {
+        if (handleRef.current !== null)
+            return;
+        const element = containerRef.current;
+        if (element === null)
+            return;
+        let disposed = false;
+        let mounted = null;
+        const readOnlyMount = readOnlyRef.current;
+        void (async () => {
+            await new Promise(resolve => requestAnimationFrame(() => resolve()));
+            if (disposed)
+                return;
+            // Univer emits initialization/layout mutations while createUnit is
+            // still mounting. They describe the initial projection, not a user
+            // edit; forwarding them would mark the workbook dirty immediately and
+            // attempt a large snapshot save before the canvas is ready.
+            const mount = await mountWorkbook(element, workbookData, change => {
+                if (mounted !== null && !readOnlyMount)
+                    onDirty?.(change);
+            }, presence => {
+                if (mounted !== null && !readOnlyMount)
+                    onPresence?.(presence);
+            }, { readOnly: readOnlyMount, ...(decorationRef.current === undefined ? {} : { decoration: decorationRef.current }) }, ranges => {
+                if (mounted !== null && !readOnlyMount)
+                    selectionChangeRef.current?.(ranges);
+            });
+            mounted = mount;
+            if (disposed) {
+                mount.dispose();
+                return;
+            }
+            handleRef.current = {
+                save: () => mount.save(),
+                applyOperation: operation => mount.applyOperation(operation),
+                focusRange: range => mount.focusRange(range),
+                swapWorkbook: (next, nextDecoration) => mount.swapWorkbook(next, nextDecoration === undefined ? {} : { decoration: nextDecoration }),
+            };
+            setReady(true);
+            readyRef.current?.();
+        })().catch(() => {
+            if (!disposed)
+                setFailed(true);
+        });
+        return () => {
+            disposed = true;
+            mounted?.dispose();
+            mounted = null;
+            handleRef.current = null;
+        };
+        // Workbook data is fixed for the residency's lifetime.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    useImperativeHandle(ref, () => ({
+        save: () => (handleRef.current?.save() ?? null),
+        applyOperation: async (operation) => { await handleRef.current?.applyOperation(operation); },
+        focusRange: range => handleRef.current?.focusRange(range) ?? false,
+        swapWorkbook: (next, nextDecoration) => handleRef.current?.swapWorkbook(next, nextDecoration) ?? false,
+    }));
+    return (_jsx("div", { className: styles.view, children: _jsxs("div", { className: styles.body, children: [!ready && !failed && _jsx("div", { className: styles.hint, children: "\u8868\u683C\u52A0\u8F7D\u4E2D\u2026" }), failed && _jsx("div", { className: styles.hint, children: "\u8868\u683C\u6E32\u67D3\u5931\u8D25" }), _jsx("div", { ref: containerRef, className: styles.univer })] }) }));
+});

package/lib/types/client/univer/WorkbookView.d.ts

@@ -0,0 +1,3 @@
+/** Backwards-compatible alias for the shared WorkbookCanvas. */
+export { WorkbookCanvas as WorkbookView } from './WorkbookCanvas.tsx';
+export type { WorkbookCanvasHandle as WorkbookViewHandle, WorkbookCanvasProps as WorkbookViewProps } from './WorkbookCanvas.tsx';