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

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

@@ -0,0 +1,2 @@
+/** Backwards-compatible alias for the shared WorkbookCanvas. */
+export { WorkbookCanvas as WorkbookView } from "./WorkbookCanvas.js";

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

@@ -0,0 +1,18 @@
+/**
+ * Lazy Univer half for dsh-data-table. The heavy Univer engine lives
+ * in a separate chunk (`lib/univer-client.js`, served by the node half at
+ * `/data-sheet/univer-client.js`); this module loads that chunk on the first
+ * sheet render so the ~16MB graph is never in the page's boot bundle.
+ * CSV export is engine-free and stays here.
+ * @module dsh-data-table/client/univer
+ */
+import type { WorkbookLocalChange, WorkbookPresencePayload, WorkbookSelectionRange } from '../../types.ts';
+import type { WorkbookMount, WorkbookMountOptions } from '../../univer/chunk.ts';
+export type { WorkbookDecoration, WorkbookDecorationCell, WorkbookMount, WorkbookMountOptions } from '../../univer/chunk.ts';
+/**
+ * Mount one resident Univer engine into a container with a workbook snapshot.
+ * Resolves after the engine chunk arrived (first call pays the fetch/parse).
+ * `options.readOnly` mounts a preview residency: the snapshot is a past
+ * Version, so no edit is reported and none can be made (PRD v3.2 §7.2).
+ */
+export declare function mountWorkbook(container: HTMLElement, workbookData: object, onDirty?: (change?: WorkbookLocalChange) => void, onPresence?: (presence: WorkbookPresencePayload) => void, options?: WorkbookMountOptions, onSelection?: (ranges: readonly WorkbookSelectionRange[]) => void): Promise<WorkbookMount>;

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

@@ -0,0 +1,81 @@
+/**
+ * Lazy Univer half for dsh-data-table. The heavy Univer engine lives
+ * in a separate chunk (`lib/univer-client.js`, served by the node half at
+ * `/data-sheet/univer-client.js`); this module loads that chunk on the first
+ * sheet render so the ~16MB graph is never in the page's boot bundle.
+ * CSV export is engine-free and stays here.
+ * @module dsh-data-table/client/univer
+ */
+/**
+ * Engine-chunk candidates, tried in order: the node-half route is the durable
+ * source (registered when the dsh server runs the current plugin code); the
+ * dist asset is the stopgap for a server that was started before the route
+ * existed (each failed source is a dead end, not retried).
+ */
+function dataSheetAssetPath(path, keepQuery = false) {
+    const transport = globalThis.__DSH_TRANSPORT__;
+    if (transport?.ownsHost === true) {
+        // The path travels as a query parameter, so a cache-busting query string
+        // would become part of the resolved file path; drop it in this mode.
+        const [withoutQuery] = keepQuery ? path.split('?') : [path];
+        return `/api/data-sheet?path=${encodeURIComponent(withoutQuery ?? path)}`;
+    }
+    return path;
+}
+/**
+ * Build tag appended to the engine chunk URL. The chunk is a plain script the
+ * browser caches by URL, so a rebuilt chunk used to keep running in an already
+ * open page; a unique query makes every build a different URL. The host
+ * transport mode passes the path as a query parameter, so the tag is only
+ * added on the direct route (which matches on `pathname` and ignores queries).
+ */
+const CHUNK_VERSION = typeof __DSH_DATA_SHEET_BUILD__ === 'string' ? __DSH_DATA_SHEET_BUILD__ : 'dev';
+const chunkPath = `/data-sheet/univer-client.js?v=${encodeURIComponent(CHUNK_VERSION)}`;
+const CHUNK_SOURCES = [dataSheetAssetPath(chunkPath, true), '/assets/data-sheet-univer.js'];
+let chunkPromise = null;
+/** Load the engine chunk once (script tag; shared across concurrent callers). */
+function loadChunk() {
+    if (window.__bestExcelUniver !== undefined)
+        return Promise.resolve(window.__bestExcelUniver);
+    if (chunkPromise !== null)
+        return chunkPromise;
+    chunkPromise = (async () => {
+        for (const src of CHUNK_SOURCES) {
+            try {
+                await new Promise((resolve, reject) => {
+                    const el = document.createElement('script');
+                    el.async = true;
+                    el.src = src;
+                    el.addEventListener('load', () => {
+                        if (window.__bestExcelUniver === undefined)
+                            reject(new Error(`univer chunk loaded without its global: ${src}`));
+                        else
+                            resolve();
+                    }, { once: true });
+                    el.addEventListener('error', () => reject(new Error(`univer chunk failed to load: ${src}`)));
+                    document.head.append(el);
+                });
+                const api = window.__bestExcelUniver;
+                if (api === undefined)
+                    throw new Error('univer chunk resolved without its global');
+                return api;
+            }
+            catch (error) {
+                if (src === CHUNK_SOURCES[CHUNK_SOURCES.length - 1])
+                    throw error;
+            }
+        }
+        throw new Error('unreachable');
+    })();
+    return chunkPromise;
+}
+/**
+ * Mount one resident Univer engine into a container with a workbook snapshot.
+ * Resolves after the engine chunk arrived (first call pays the fetch/parse).
+ * `options.readOnly` mounts a preview residency: the snapshot is a past
+ * Version, so no edit is reported and none can be made (PRD v3.2 §7.2).
+ */
+export async function mountWorkbook(container, workbookData, onDirty, onPresence, options, onSelection) {
+    const api = await loadChunk();
+    return api.mountWorkbook(container, workbookData, onDirty, onPresence, options, onSelection);
+}

package/lib/types/client/univer/standalone-entry.d.ts

@@ -0,0 +1 @@
+import './standalone.css';

package/lib/types/client/univer/standalone-entry.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createRoot } from 'react-dom/client';
+import { setDshSessionId } from "../transport/workbookApi.js";
+import { StandaloneWorkbookPage } from "./StandaloneWorkbookPage.js";
+import './standalone.css';
+const root = document.getElementById('data-sheet-workbook-root');
+if (root !== null) {
+    const query = new URLSearchParams(window.location.search);
+    // The project this page reads: the address that opened it carries the Session id
+    // (see `standaloneWorkbookPath`), because a page in its own document — a new tab
+    // or the in-app full page — has no sidebar to ask.
+    setDshSessionId(query.get('sessionId') ?? undefined);
+    const pathMatch = /^\/data-sheet\/workbook\/([^/]+)\/view$/.exec(window.location.pathname);
+    const queryId = query.get('workbook');
+    const workbookId = pathMatch?.[1] === undefined
+        ? (queryId ?? 'main')
+        : decodeURIComponent(pathMatch[1]);
+    createRoot(root).render(_jsx(StandaloneWorkbookPage, { workbookId: workbookId }));
+}

package/lib/types/client/versions/VersionChrome.d.ts

@@ -0,0 +1,33 @@
+import { type VersionManagerActions, type VersionManagerGroup } from '@tita-agent/ui/versions';
+import type { VersionRestoreRequest } from './inspect.ts';
+export interface VersionChromeProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Name of the artifact, for the drawer's header line. */
+    artifactName: string;
+    /** How many Versions the list holds, and when the newest one landed. */
+    versionCount: number;
+    headLabel: string | undefined;
+    /** The Version the canvas would restore, or undo, to. */
+    restorableId: string | undefined;
+    loading: boolean;
+    groups: VersionManagerGroup[];
+    actions: VersionManagerActions;
+    save: {
+        open: boolean;
+        pending: boolean;
+        /** True while no artifact is open: there is nothing to name. */
+        disabled: boolean;
+        onOpenChange: (open: boolean) => void;
+        onConfirm: (name: string) => void;
+    };
+    restore: {
+        /** The pending confirmation, or null when the dialog is closed. */
+        request: VersionRestoreRequest | null;
+        pending: boolean;
+        onOpenChange: (open: boolean) => void;
+        onConfirm: () => void;
+    };
+}
+/** Drawer, 保存版本 dialog and 恢复 confirmation, as one piece of chrome. */
+export declare function VersionChrome({ open, onOpenChange, artifactName, versionCount, headLabel, restorableId, loading, groups, actions, save, restore, }: VersionChromeProps): React.ReactElement;

package/lib/types/client/versions/VersionChrome.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The version drawer and the two dialogs that answer from it (docs/issue/0022 P5).
+ *
+ * This is the chrome half of the history surface: `records.ts` turns a stored
+ * Version into the row the list draws, `inspect.ts` produces what the comparison
+ * bar needs, and this assembles the Drawer, the 保存版本 dialog and the
+ * 恢复/撤销 confirmation out of them. It was inline in `SheetPanel.tsx`, which is
+ * pinned at its size for a reason — the panel's job is the canvas and the wire,
+ * and the copy and structure of the history UI are not part of that.
+ */
+import { Button } from '@tita-agent/ui/components';
+import { Drawer, DrawerBody, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, } from '@tita-agent/ui/overlays';
+import { Save } from '@tita-agent/ui/icons';
+import { RestoreDialog, SaveVersionDialog, VersionManager, } from '@tita-agent/ui/versions';
+/** Drawer, 保存版本 dialog and 恢复 confirmation, as one piece of chrome. */
+export function VersionChrome({ open, onOpenChange, artifactName, versionCount, headLabel, restorableId, loading, groups, actions, save, restore, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Drawer, { open: open, onOpenChange: onOpenChange, children: _jsxs(DrawerContent, { "aria-label": "\u7248\u672C\u7BA1\u7406", children: [_jsxs(DrawerHeader, { children: [_jsxs("div", { children: [_jsx(DrawerTitle, { children: "\u7248\u672C\u7BA1\u7406" }), _jsx(DrawerDescription, { children: versionCount === 0
+                                                ? `${artifactName} · 还没有版本`
+                                                : `${artifactName} · ${versionCount} 个版本 · 最近保存 ${headLabel ?? ''}` })] }), _jsxs(Button, { variant: "outline", size: "sm", disabled: save.disabled, onClick: () => save.onOpenChange(true), children: [_jsx(Save, { size: 14, "aria-hidden": "true" }), "\u4FDD\u5B58\u7248\u672C"] })] }), _jsx(DrawerBody, { children: _jsx(VersionManager, { loading: loading, groups: groups, actions: { ...actions, restorableId } }) })] }) }), _jsx(SaveVersionDialog, { open: save.open, onOpenChange: save.onOpenChange, pending: save.pending, onConfirm: save.onConfirm }), _jsx(RestoreDialog, { open: restore.request !== null, onOpenChange: restore.onOpenChange, targetLabel: restore.request?.label ?? '', ...(restore.request?.summary === undefined ? {} : { targetSummary: restore.request.summary }), ...(restore.request === null ? {} : { mode: restore.request.mode }), artifactLabel: "\u5DE5\u4F5C\u7C3F\u5185\u5BB9", pending: restore.pending, onConfirm: restore.onConfirm })] }));
+}

package/lib/types/client/versions/inspect.d.ts

@@ -0,0 +1,70 @@
+import { type VersionInspectOption, type VersionInspectorSummary, type VersionManagerEntry } from '@tita-agent/ui/versions';
+import type { WorkbookChange } from '../../types.ts';
+import type { WorkbookDecoration } from '../univer/loader.ts';
+/**
+ * One preview residency (docs/issue/0002 PRD v3.2 §7.2). `step` is part of the
+ * canvas's React `key` so replaying a Step of the same Version remounts it;
+ * `snapshot` is the content the canvas renders read-only.
+ */
+export interface WorkbookPreviewState {
+    versionId: string;
+    revision: number;
+    /** Rebuilt content state; the canvas renders exactly this. */
+    snapshot: object;
+    /** Step index when the preview is a Step replay rather than the Version end. */
+    step: number | null;
+    /**
+     * What is on screen vs what it is compared against: a Step against the state
+     * before it, a Version against the newer one it followed. Drives the canvas
+     * overlay so the reader does not have to find the changed cells (v3.3 §7.2).
+     */
+    changes: WorkbookChange[];
+    /**
+     * Which end of the measured range the canvas is showing, so only changes the
+     * reader can actually see get tinted.
+     */
+    changesSide: 'before' | 'after';
+    /** True when the changes could not be rebuilt (compressed history). */
+    changesUnavailable?: boolean;
+    /** True when the diff stopped at the server's limit, so the counts are a floor. */
+    changesTruncated?: boolean;
+}
+/**
+ * The overlay for a residency: identical to what an in-place swap painted, so a
+ * remount and a swap show exactly the same thing.
+ */
+export declare function previewDecorationOf(preview: WorkbookPreviewState | null): WorkbookDecoration | undefined;
+/**
+ * Counts + legend for the bar, derived from the same list the canvas tints.
+ *
+ * The counts carry the same bucket names the engine paints with, so the legend
+ * and the grid are read as one thing; `truncated` is carried through because a
+ * capped list would otherwise read as the whole comparison.
+ */
+export declare function inspectorSummaryOf(preview: WorkbookPreviewState | null): VersionInspectorSummary;
+/**
+ * Preview switcher options: every Version the artifact could be swapped onto,
+ * newest-first, labelled the way its row was. Built from the timeline so the
+ * selector can never offer a Version the list does not show.
+ *
+ * The Steps give the picker its second level; the shared helper budgets a Step's
+ * summary to one menu line.
+ */
+export declare function inspectOptionsOf(entries: readonly VersionManagerEntry[]): VersionInspectOption[];
+/**
+ * Revision a baseline id measures against.
+ *
+ * A Step is measured at the revision it produced. Falling back to the Version
+ * rather than refusing keeps a record written before the field existed usable —
+ * it just compares the whole Version.
+ */
+export declare function baselineRevisionOf(entry: VersionManagerEntry | undefined, fallbackRevision: number, step?: number): number;
+/** What 「恢复」/「撤销这次改动」 posts, once the confirmation dialog is answered. */
+export interface VersionRestoreRequest {
+    revision: number;
+    /** Render-time label, for the dialog and the notice. */
+    label: string;
+    /** Durable summary written into the new Version's record. */
+    summary: string;
+    mode: 'restore' | 'undo';
+}

package/lib/types/client/versions/inspect.js

@@ -0,0 +1,88 @@
+/**
+ * The read-only comparison surface, as view models (docs/issue/0022 P5).
+ *
+ * `records.ts` translates a stored Version into the row the drawer draws; this
+ * takes that row — or a fetched diff — and produces the things the *inspect*
+ * half needs: the two pickers' options, the canvas overlay, the counts in the
+ * bar, and the revision a baseline id addresses. All of it is pure, which is the
+ * point: the panel is 1800 lines of ref-mutating effects, and each of these was
+ * a `useMemo` body buried in the middle of it.
+ */
+import { versionChangeDirection } from '#contracts';
+import { versionOptionLabel, versionStepOptionLabel, } from '@tita-agent/ui/versions';
+import { toDecoration } from "./preview-decoration.js";
+/**
+ * The overlay for a residency: identical to what an in-place swap painted, so a
+ * remount and a swap show exactly the same thing.
+ */
+export function previewDecorationOf(preview) {
+    return preview === null ? undefined : toDecoration(preview.changes, preview.changesSide);
+}
+/**
+ * Counts + legend for the bar, derived from the same list the canvas tints.
+ *
+ * The counts carry the same bucket names the engine paints with, so the legend
+ * and the grid are read as one thing; `truncated` is carried through because a
+ * capped list would otherwise read as the whole comparison.
+ */
+export function inspectorSummaryOf(preview) {
+    const summary = { total: 0, add: 0, remove: 0, modify: 0, structure: 0, style: 0 };
+    if (preview === null)
+        return summary;
+    summary.total = preview.changes.length;
+    if (preview.changesUnavailable === true)
+        summary.unavailable = true;
+    if (preview.changesTruncated === true)
+        summary.truncated = true;
+    for (const change of preview.changes) {
+        summary[versionChangeDirection({
+            kind: change.kind,
+            target: '',
+            description: '',
+            ...(change.row === undefined ? {} : { row: change.row }),
+            ...(change.column === undefined ? {} : { column: change.column }),
+            ...(change.before === undefined ? {} : { before: change.before }),
+            ...(change.after === undefined ? {} : { after: change.after }),
+            ...(change.styleOnly === true ? { styleOnly: true } : {}),
+        })] += 1;
+    }
+    return summary;
+}
+/**
+ * Preview switcher options: every Version the artifact could be swapped onto,
+ * newest-first, labelled the way its row was. Built from the timeline so the
+ * selector can never offer a Version the list does not show.
+ *
+ * The Steps give the picker its second level; the shared helper budgets a Step's
+ * summary to one menu line.
+ */
+export function inspectOptionsOf(entries) {
+    return entries
+        .filter(entry => entry.replayable)
+        .map(entry => ({
+        id: entry.id,
+        label: versionOptionLabel({ summary: entry.summary, ...(entry.timestamp === undefined ? { time: entry.time } : { timestamp: entry.timestamp }) }),
+        steps: (entry.steps ?? []).map(step => ({
+            index: step.index,
+            label: versionStepOptionLabel(step),
+            ...(step.revision === undefined ? {} : { revision: step.revision }),
+        })),
+    }));
+}
+/**
+ * Revision a baseline id measures against.
+ *
+ * A Step is measured at the revision it produced. Falling back to the Version
+ * rather than refusing keeps a record written before the field existed usable —
+ * it just compares the whole Version.
+ */
+export function baselineRevisionOf(entry, fallbackRevision, step) {
+    if (entry === undefined)
+        return fallbackRevision;
+    if (step !== undefined) {
+        const found = entry.steps?.find(candidate => candidate.index === step);
+        if (found?.revision !== undefined)
+            return found.revision;
+    }
+    return entry.revision ?? fallbackRevision;
+}

package/lib/types/client/versions/preview-decoration.d.ts

@@ -0,0 +1,11 @@
+import type { WorkbookChange } from '../../types.ts';
+import type { WorkbookDecoration } from '../univer/loader.ts';
+/**
+ * Turn a change list into the canvas overlay (PRD v3.3 §7.2): every changed
+ * cell, toned by direction, plus the first changed cell as the focus so
+ * switching what is inspected moves the viewport onto what actually changed.
+ *
+ * A removed cell exists only in the baseline, so it cannot be tinted in this
+ * snapshot; it is counted in the bar instead of being painted nowhere.
+ */
+export declare function toDecoration(changes: WorkbookChange[], side: 'before' | 'after'): WorkbookDecoration | undefined;

package/lib/types/client/versions/preview-decoration.js

@@ -0,0 +1,54 @@
+/**
+ * Turning a diff into a canvas overlay (docs/issue/0022 P5).
+ *
+ * The *order* of a diff is not the same as its direction, and which tones may be
+ * painted depends on which side of the comparison the canvas is showing: a
+ * removed cell does not exist in the snapshot that is on screen, so painting it
+ * would tint an empty cell. That rule is the whole reason this is a module.
+ */
+import { versionChangeDirection } from '#contracts';
+/**
+ * Turn a change list into the canvas overlay (PRD v3.3 §7.2): every changed
+ * cell, toned by direction, plus the first changed cell as the focus so
+ * switching what is inspected moves the viewport onto what actually changed.
+ *
+ * A removed cell exists only in the baseline, so it cannot be tinted in this
+ * snapshot; it is counted in the bar instead of being painted nowhere.
+ */
+export function toDecoration(changes, side) {
+    const cells = [];
+    let focus;
+    for (const change of changes) {
+        if (change.kind !== 'cell' || change.row === undefined || change.column === undefined)
+            continue;
+        const sheetRef = change.sheetId ?? change.sheetName;
+        const direction = versionChangeDirection({
+            kind: 'cell',
+            target: '',
+            description: '',
+            row: change.row,
+            column: change.column,
+            ...(change.before === undefined ? {} : { before: change.before }),
+            ...(change.after === undefined ? {} : { after: change.after }),
+        });
+        // A diff is directional, and the canvas shows exactly one of its two sides:
+        //  - showing the newer side, an addition/replacement is paint-able (green /
+        //    amber) and a deletion has no cell here at all;
+        //  - showing the older side — the default when previewing an old Version
+        //    against the current content — it is the other way round, and the cell
+        //    that no longer exists is the red one.
+        // Painting the wrong side's cells would tint empty cells and claim a change
+        // the reader cannot see.
+        const tone = direction === 'add' ? 'add' : direction === 'remove' ? 'remove' : 'modify';
+        const paintable = side === 'after' ? tone !== 'remove' : tone !== 'add';
+        if (!paintable)
+            continue;
+        cells.push({ ...(sheetRef === undefined ? {} : { sheetRef }), row: change.row, column: change.column, tone });
+        if (focus === undefined) {
+            focus = { ...(sheetRef === undefined ? {} : { sheetRef }), row: change.row, column: change.column };
+        }
+    }
+    if (cells.length === 0 && focus === undefined)
+        return undefined;
+    return { cells, ...(focus === undefined ? {} : { focus }) };
+}

package/lib/types/client/versions/records.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A stored Version as the panel renders it (docs/issue/0022 P5).
+ *
+ * The history payload and the shared `VersionManager` speak different shapes:
+ * the payload is what the store knows (revisions, steps, lineage), and the row
+ * model is what a person sees. This is that translation, and nothing else — it
+ * is the module PRD 0002 keeps touching, so it is a module rather than twelve
+ * helpers at the bottom of the panel.
+ */
+import { formatVersionTime, type VersionManagerEntry } from '@tita-agent/ui/versions';
+import type { WorkbookHistoryVersion } from '../../types.ts';
+import type { HistoryEntry } from '../transport/workbookApi.ts';
+/** The history payload's Version, under the name the panel's rows use. */
+export type HistoryVersion = WorkbookHistoryVersion;
+/** The shared component formats Version times; re-exported so callers did not have to move. */
+export declare const formatHistoryTime: typeof formatVersionTime;
+export declare function historyVersionsFromEntries(entries: HistoryEntry[]): HistoryVersion[];
+/** Shared drawer entry shape (docs/issue/0002 Phase 3 / PRD v3 §7). */
+export declare function toVersionManagerEntry(version: HistoryVersion, index: number, all: HistoryVersion[]): VersionManagerEntry;

package/lib/types/client/versions/records.js

@@ -0,0 +1,70 @@
+/**
+ * A stored Version as the panel renders it (docs/issue/0022 P5).
+ *
+ * The history payload and the shared `VersionManager` speak different shapes:
+ * the payload is what the store knows (revisions, steps, lineage), and the row
+ * model is what a person sees. This is that translation, and nothing else — it
+ * is the module PRD 0002 keeps touching, so it is a module rather than twelve
+ * helpers at the bottom of the panel.
+ */
+import { formatVersionTime } from '@tita-agent/ui/versions';
+/** The shared component formats Version times; re-exported so callers did not have to move. */
+export const formatHistoryTime = formatVersionTime;
+export function historyVersionsFromEntries(entries) {
+    return entries.map((entry, index) => ({
+        versionId: `revision:${entry.revision}`,
+        number: index + 1,
+        startRevision: entry.revision,
+        revision: entry.revision,
+        parentRevision: entry.parentRevision ?? Math.max(0, entry.revision - 1),
+        actor: entry.actor,
+        timestamp: entry.timestamp,
+        summary: entry.summary,
+        stepCount: 1,
+        steps: [{ index: 0, opId: entry.opId, type: entry.type, summary: entry.summary }],
+        canPreview: entry.canPreview === true,
+        status: 'final',
+        // A legacy operation-log row is a deliberate step, not session churn.
+        kind: 'named',
+        branch: 'main',
+    }));
+}
+/** Shared drawer entry shape (docs/issue/0002 Phase 3 / PRD v3 §7). */
+export function toVersionManagerEntry(version, index, all) {
+    const status = version.branch === 'superseded'
+        ? 'superseded'
+        : version.status === 'final'
+            ? 'committed'
+            : 'open';
+    const restoredFromNumber = version.restoredFromNumber
+        ?? (version.restoredFromRevision === undefined
+            ? undefined
+            : all.find(candidate => candidate.revision === version.restoredFromRevision)?.number);
+    const restoredFrom = restoredFromNumber === undefined
+        ? undefined
+        : all.find(candidate => candidate.number === restoredFromNumber);
+    return {
+        id: version.versionId,
+        number: version.number ?? all.length - index,
+        revision: version.revision,
+        summary: version.summary,
+        actor: version.actor === 'agent' ? 'agent' : 'user',
+        time: formatHistoryTime(version.timestamp),
+        timestamp: version.timestamp,
+        status,
+        kind: version.kind,
+        ...(restoredFrom === undefined
+            ? (restoredFromNumber === undefined ? {} : { restoredFromNumber })
+            : { restoredFromTime: formatHistoryTime(restoredFrom.timestamp) }),
+        stepCount: version.stepCount,
+        replayable: version.canPreview,
+        steps: version.steps.map(step => ({
+            id: step.opId,
+            index: step.index,
+            label: `Step ${step.index + 1}`,
+            summary: step.summary,
+            ...(step.revision === undefined ? {} : { revision: step.revision }),
+        })),
+        ...(version.intent === undefined ? {} : { intent: version.intent }),
+    };
+}

package/lib/types/client/workspace-host.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Resident host for the embedded Table workspace.
+ *
+ * The dock renders only the active tab's body (`DockSurface` → `renderTab`), so
+ * switching DSH tabs — or switching conversation sessions — unmounts the pane's
+ * React tree. When the workspace lived in that tree, every re-entry disposed the
+ * Univer engine, re-fetched the whole snapshot and rebuilt the sheet, which is
+ * exactly the "reloads on every visit" the panel used to show.
+ *
+ * The workspace therefore lives in one long-lived container that is created
+ * once and merely *moves* between the pane and an off-screen parking lot. Re-
+ * entering the tab re-parents the existing DOM and React tree, so the editor,
+ * its scroll position, its unsaved drafts and its collaboration stream all
+ * survive. A long stay in the parking lot releases it again, so the engine is
+ * not held for the life of the page either.
+ *
+ * The DOM access and the timer are injected so the adoption/parking bookkeeping
+ * can be tested without a browser (this repository has no DOM test
+ * environment).
+ *
+ * @module dsh-data-table/client/workspace-host
+ */
+/** How long a parked workspace is kept warm before it is released. */
+export declare const PARKED_RELEASE_MS: number;
+/** Minimal DOM surface this module needs; injectable for tests. */
+export interface WorkspaceHostEnvironment {
+    /** Create the element that owns the workspace. */
+    createContainer(): HTMLElement;
+    /** Create the off-screen element a parked workspace is moved into. */
+    createParkingLot(): HTMLElement;
+    /** The document body the parking lot is attached to. */
+    body(): HTMLElement;
+    /** Schedule the idle release (injectable so tests stay deterministic). */
+    schedule(callback: () => void, delayMs: number): unknown;
+    /** Cancel a scheduled idle release. */
+    cancel(handle: unknown): void;
+}
+/** Replace the DOM environment (tests only). Resets any resident workspace. */
+export declare function setWorkspaceHostEnvironment(next: WorkspaceHostEnvironment): void;
+/** The resident container, or null when nothing is resident. */
+export declare function workspaceHostElement(): HTMLElement | null;
+/** Whether the resident workspace is currently parked off-screen. */
+export declare function isWorkspaceHostParked(): boolean;
+/**
+ * Put the resident workspace inside `target`, creating it on first use.
+ * @param target - the pane element that should display the workspace.
+ * @param mount - called once per workspace lifetime; may return a disposer.
+ * @returns the resident container.
+ */
+export declare function adoptWorkspaceHost(target: HTMLElement, mount: (container: HTMLElement) => void | (() => void)): HTMLElement;
+/**
+ * Move the resident workspace off-screen without destroying it.
+ *
+ * Its measured size is kept so the engine sees no resize while parked; that is
+ * what makes re-adoption invisible instead of a relayout. The workspace is
+ * released after {@link PARKED_RELEASE_MS} so a tab the user has moved on from
+ * does not pin a whole engine for the life of the page.
+ */
+export declare function parkWorkspaceHost(): void;
+/** Release the resident workspace, unmounting its React tree. Safe when empty. */
+export declare function disposeWorkspaceHost(): void;