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

package/lib/types/client/SheetPanel.js

@@ -0,0 +1,1766 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Right-column workbook canvas. Univer owns the editing experience; this
+ * component owns the browser projection of the DSH workbook service:
+ * snapshot bootstrap, incremental user operations, and Agent-operation sync.
+ * @module dsh-data-table/client/SheetPanel
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Button, Input } from '@tita-agent/ui/components';
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, useFullPage, } from '@tita-agent/ui/overlays';
+import { ArrowDownToLine, ExternalLink, FileJson, FileSpreadsheet, FileText, History, X, } from '@tita-agent/ui/icons';
+import { ObjectPicker, SaveStatus, ToolbarMenu, TopBarDivider, TopBarGroup, WorkspaceTopBar, } from '@tita-agent/ui/workspace';
+import { ProjectImportMenu } from "./ProjectImportMenu.js";
+import { VersionInspectBar, autoVersionName, CURRENT_VERSION_LABEL, restoreVersionSummary, } from '@tita-agent/ui/versions';
+import '@tita-agent/ui/styles.css';
+import { VERSION_MAX_STEPS, undoTargetOf, versionTimeline } from '#contracts';
+import { cloneSnapshot } from "../contract/snapshots.js";
+import { cachedWorkbookProjection, forgetWorkbookProjection, lastSelectedWorkbookId, readVersionSession, rememberVersionSession, rememberWorkbook, rememberWorkbookProjection, useSheetOpen, } from "./store.js";
+import { WorkbookCanvas } from "./univer/WorkbookCanvas.js";
+import { DATA_SHEET_SURFACE_ID, dataSheetFocusTargetOf, projectDataSheetSelection } from "./surface-context.js";
+import { registerDataSheetFocusHandler } from "./surface-control.js";
+import { formatHistoryTime, historyVersionsFromEntries, toVersionManagerEntry } from "./versions/records.js";
+import { VersionChrome } from "./versions/VersionChrome.js";
+import { baselineRevisionOf, inspectOptionsOf, inspectorSummaryOf, previewDecorationOf, } from "./versions/inspect.js";
+import { toDecoration } from "./versions/preview-decoration.js";
+import { canApplyRemoteWhileEditing, coalesceLocalChanges, withWorkbookName } from "./persistence/changes.js";
+import { createOwnOpLog, nextUserVersionId } from "./persistence/ids.js";
+import { collaborationStreamPath, dataSheetSessionId, standaloneWorkbookPath, dataSheetClientPath, createWorkbook, deleteWorkbook as deleteWorkbookRequest, fetchChanges, fetchHistory, fetchHistorySnapshot, fetchHistoryDiff, fetchWorkbook, fetchWorkbooks, HttpStatusError, RevisionConflictError, rollbackWorkbook, saveOperationChanges, saveSnapshot, publishPresence, renameWorkbook as renameWorkbookRequest, } from "./transport/workbookApi.js";
+import { mergeWorkbookSnapshots, applyIncrementalChangesToSnapshot, applyIncrementalOperationsToSnapshot, stripConflictMarkers, } from "./persistence/merge.js";
+import styles from './SheetPanel.module.css';
+// Safety cap only; the merge window and explicit save are the real boundaries (PRD §4.1).
+/**
+ * How many Steps one unretained session may hold before the Host closes it and
+ * a new Version starts. The cap lives in the shared contract (PRD v3.3 D21) so
+ * the client and server gate cannot disagree about it.
+ */
+const HUMAN_VERSION_STEP_LIMIT = VERSION_MAX_STEPS;
+const SYNC_INTERVAL_MS = 1500;
+/** Shared workbook workspace used by both the DSH details panel and the standalone page. */
+export function WorkbookWorkspace({ open, visible = open, standalone = false, initialWorkbookId, bridge }) {
+    /**
+     * 「整页打开」的出口：浏览器里是新标签页，桌面端铺成应用内的一层。桌面壳不允许
+     * 插件开新窗口（`setWindowOpenHandler` 只放行 http/https），判断只在 `useFullPage` 里。
+     */
+    const fullPage = useFullPage();
+    // Resolve the workbook to reopen once, before the first paint, so switching
+    // DSH tabs shows the previous content instead of an empty panel.
+    const restoreTarget = (() => initialWorkbookId?.trim() || lastSelectedWorkbookId())();
+    const restored = cachedWorkbookProjection(restoreTarget);
+    const [snapshot, setSnapshot] = useState(restored?.snapshot ?? null);
+    const [meta, setMeta] = useState(restored === null ? null : { id: restored.id, name: restored.name });
+    const [workbooks, setWorkbooks] = useState([]);
+    const [revision, setRevision] = useState(restored?.revision ?? 0);
+    const [viewKey, setViewKey] = useState(0);
+    const [status, setStatus] = useState('loading');
+    const [switching, setSwitching] = useState(false);
+    const [conflicts, setConflicts] = useState([]);
+    const [notice, setNotice] = useState(null);
+    const [historyOpen, setHistoryOpen] = useState(false);
+    const [historyLoading, setHistoryLoading] = useState(false);
+    const [historyVersions, setHistoryVersions] = useState([]);
+    const [expandedHistoryVersions, setExpandedHistoryVersions] = useState(new Set());
+    /**
+     * The past Version the *canvas* is currently showing (PRD v3.2 §7.2). While
+     * this is set the workspace renders a read-only Univer residency loaded with
+     * `snapshot` from the fetch, the inspect bar is on screen, and nothing can be
+     * persisted — so neither preview nor comparison can fork a Version.
+     */
+    const [preview, setPreview] = useState(null);
+    const [previewLoading, setPreviewLoading] = useState(false);
+    /**
+     * What the inspected Version is measured against (PRD v3.5 §7.2). Preview
+     * *is* a comparison with a fixed other side, so there is no mode: the bar is
+     * always `版本 A → 版本 B`, and `baselineId === ''` — the current content — is
+     * what a preview means.
+     */
+    const [inspectBaselineId, setInspectBaselineId] = useState('');
+    // A baseline can be a Step, and Step is not implied by its Version: a Version
+    // with several Steps has several baselines, and the picker has to come back
+    // showing the one that was chosen.
+    const [inspectBaselineStep, setInspectBaselineStep] = useState(undefined);
+    /**
+     * Incremented only when the inspected residency has to be rebuilt. Switching
+     * the inspected Version does **not** touch it: the canvas keeps its Univer
+     * instance and swaps the unit, so the grid does not flash and the scroll
+     * position survives (PRD v3.5 §7.2).
+     */
+    const [inspectRemount, setInspectRemount] = useState(0);
+    /** Pending restore / undo confirmation, with the copy its dialog needs. */
+    const [restoreRequest, setRestoreRequest] = useState(null);
+    const [restorePending, setRestorePending] = useState(false);
+    const [saveVersionOpen, setSaveVersionOpen] = useState(false);
+    const [saveVersionPending, setSaveVersionPending] = useState(false);
+    /** Comparison baseline; empty means "the current version" (PRD §8). */
+    const [compareAgainst, setCompareAgainst] = useState('');
+    const [presence, setPresence] = useState([]);
+    const [toast, setToast] = useState(null);
+    const [workbookDialog, setWorkbookDialog] = useState(null);
+    const [workbookActionPending, setWorkbookActionPending] = useState(null);
+    const [deletingWorkbookId, setDeletingWorkbookId] = useState(null);
+    const viewHandle = useRef(null);
+    const selectionRevisionRef = useRef(0);
+    const selectionSignatureRef = useRef('');
+    const pendingBridgeFocusRef = useRef(null);
+    const bridgeFocusAttemptRef = useRef(null);
+    /**
+     * Mirror of `preview` for the callbacks that captured an earlier render (the
+     * sync interval and the collaboration stream). Guards on the state value
+     * inside those callbacks would read `null` forever.
+     */
+    const previewRef = useRef(null);
+    useEffect(() => { previewRef.current = preview; }, [preview]);
+    // Remember the active workbook and its projection so a pane remount reopens it
+    // without a blank reload. This is only a cache: the mount effect revalidates.
+    useEffect(() => {
+        if (meta === null)
+            return;
+        rememberWorkbook(meta.id);
+        if (snapshot !== null)
+            rememberWorkbookProjection({ id: meta.id, name: meta.name, snapshot, revision });
+    }, [meta, snapshot, revision]);
+    /**
+     * Every Version row, newest-first, for the shared drawer. `stepsExpanded` has
+     * to be derived here (not inside the mapper) because it depends on local
+     * expansion state — the Steps are already in the history payload, so
+     * expanding needs no fetch. `open` Versions stay in this list because the
+     * drawer's *logic* needs them (an undo target is resolved against the real
+     * order); the rendered timeline filters them out.
+     */
+    const historyEntries = useMemo(() => historyVersions
+        .map((version, index) => {
+        const entry = toVersionManagerEntry(version, index, historyVersions);
+        return {
+            ...entry,
+            stepsExpanded: expandedHistoryVersions.has(version.revision),
+            steps: entry.steps?.map(step => ({
+                ...step,
+                selected: preview?.step === step.index && preview.versionId === version.versionId,
+            })),
+        };
+    })
+        .reverse(), [historyVersions, expandedHistoryVersions, preview]);
+    /**
+     * The one flat timeline the drawer renders (PRD v3.3 §7.3): every named
+     * Version, the newest {@link AUTO_CHECKPOINT_KEEP} Versions, and the last
+     * Version of every calendar day — newest-first, with `今天/昨天/更早`
+     * separators.
+     *
+     * The editing session is included on purpose. It is the newest Version and
+     * the only one that accumulates Steps, so hiding it made every visible row
+     * look like a single-step snapshot and hid the work in progress. It is not a
+     * special card: it is a row like any other, and it simply has no 恢复 button
+     * because restoring the Version that is already current is meaningless.
+     */
+    const timelineEntries = useMemo(() => versionTimeline(historyEntries), [historyEntries]);
+    /** One flat list; `label: ''` renders it without a section header. */
+    const versionGroups = useMemo(() => (timelineEntries.length === 0 ? [] : [{ id: 'timeline', label: '', entries: timelineEntries }]), [timelineEntries]);
+    /** 「撤销这次改动」 on an Agent Version targets the Version before it (D5). */
+    const undoTargetFor = useCallback((entry) => {
+        const target = undoTargetOf(historyEntries, { id: entry.id, number: entry.number, status: entry.status });
+        return target === undefined ? undefined : { id: target.id, label: `V${target.number}`, replayable: target.replayable === true };
+    }, [historyEntries]);
+    /** Newest Version overall — the open editing session included (PRD v3.1 §4). */
+    const headVersion = historyVersions.at(-1);
+    const headLabel = headVersion === undefined ? undefined : formatHistoryTime(headVersion.timestamp);
+    const namedVersionCount = timelineEntries.length;
+    const headRevision = headVersion?.revision;
+    /**
+     * The Version in use is the one still being written to, so its Steps are open
+     * without being asked for (item 6, GUI feedback 2026-09-19): they are the
+     * work currently in progress, and a collapsed list hid them behind a click.
+     * Seeding only ever *adds* the head revision — a Version the user opened by
+     * hand stays open, and one they closed by hand stays closed.
+     */
+    useEffect(() => {
+        if (!historyOpen || headRevision === undefined)
+            return;
+        setExpandedHistoryVersions(current => current.has(headRevision) ? current : new Set(current).add(headRevision));
+    }, [historyOpen, headRevision]);
+    /**
+     * 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.
+     */
+    const previewOptions = useMemo(() => inspectOptionsOf(timelineEntries), [timelineEntries]);
+    const saveTimer = useRef(null);
+    const dirtyRef = useRef(false);
+    const revisionRef = useRef(restored?.revision ?? 0);
+    const publishDataSheetSelection = useCallback((ranges) => {
+        if (bridge === undefined)
+            return;
+        const selection = meta === null || previewRef.current !== null
+            ? null
+            : projectDataSheetSelection({
+                workbookId: meta.id,
+                workbookName: meta.name,
+                revision: 0,
+                documentRevision: revisionRef.current,
+                ranges,
+            });
+        if (selection === null) {
+            selectionSignatureRef.current = '';
+            if (bridge.read(DATA_SHEET_SURFACE_ID) !== null)
+                bridge.publish(DATA_SHEET_SURFACE_ID, null);
+            return;
+        }
+        const signature = JSON.stringify(selection);
+        if (signature === selectionSignatureRef.current)
+            return;
+        selectionSignatureRef.current = signature;
+        selectionRevisionRef.current += 1;
+        bridge.publish(DATA_SHEET_SURFACE_ID, { ...selection, revision: selectionRevisionRef.current });
+    }, [bridge, meta]);
+    useEffect(() => {
+        if (preview !== null)
+            publishDataSheetSelection([]);
+    }, [preview, publishDataSheetSelection]);
+    const workbooksRef = useRef([]);
+    // Seeded from the cached projection so a pane remount is recognised as a
+    // re-entry into the same workbook rather than a cold load.
+    const activeWorkbookIdRef = useRef(restored?.id ?? null);
+    const mountedRef = useRef(true);
+    // Mirrors of the two states the bootstrap effect has to inspect without
+    // depending on them: `snapshot` identity changes on every revalidation, and a
+    // dependency on it re-ran the whole load (and the collaboration session) each
+    // time.
+    const snapshotRef = useRef(restored?.snapshot ?? null);
+    const metaRef = useRef(restored === null ? null : { id: restored.id, name: restored.name });
+    const savingRef = useRef(false);
+    const serverRevisionRef = useRef(restored?.revision ?? 0);
+    const remoteOperationsRef = useRef(new Map());
+    const remoteSnapshotPendingRef = useRef(false);
+    const drainingRemoteRef = useRef(false);
+    const editGenerationRef = useRef(0);
+    const baselineRef = useRef(restored === null ? null : cloneSnapshot(restored.snapshot));
+    const conflictsRef = useRef([]);
+    const conflictStyleMapRef = useRef({});
+    const pendingLocalChangesRef = useRef([]);
+    /**
+     * The unretained editing session: which Version the next save joins, and how
+     * many Steps it already holds (PRD v3.3 D22). Seeded lazily from the store so
+     * a remount continues the same session instead of forking one per visit.
+     */
+    const sessionRef = useRef(null);
+    const sessionWorkbookIdRef = useRef('');
+    const setSession = (next) => {
+        sessionRef.current = next;
+        rememberVersionSession(sessionWorkbookIdRef.current, next);
+    };
+    const seedSession = (workbookId) => {
+        sessionWorkbookIdRef.current = workbookId;
+        sessionRef.current = readVersionSession(workbookId);
+    };
+    const sessionVersionId = () => sessionRef.current?.versionId ?? null;
+    const sessionStepCount = () => sessionRef.current?.stepCount ?? 0;
+    /**
+     * Adopt the Host's answer about the session after a whole-snapshot commit
+     * (import, conflict merge). The cursor must survive the commit — the Host
+     * joins the newest open Version — and only a `final` answer closes it.
+     */
+    const adoptSession = (result, fallbackVersionId, stepCount) => {
+        const versionId = result?.operation?.versionId ?? fallbackVersionId;
+        if (versionId === null || result?.operation?.versionStatus === 'final') {
+            setSession(null);
+            return;
+        }
+        setSession({ versionId, stepCount });
+    };
+    const snapshotSaveRequiredRef = useRef(false);
+    const pendingSavePromiseRef = useRef(null);
+    const flushPendingSaveRef = useRef(null);
+    const presenceTimerRef = useRef(null);
+    const pendingPresenceRef = useRef(null);
+    const toastTimerRef = useRef(null);
+    useEffect(() => { snapshotRef.current = snapshot; }, [snapshot]);
+    useEffect(() => { metaRef.current = meta; }, [meta]);
+    /** Whether a projection is on screen; a stable gate for the sync session. */
+    const hasSnapshot = snapshot !== null;
+    useEffect(() => () => {
+        mountedRef.current = false;
+        if (presenceTimerRef.current !== null)
+            window.clearTimeout(presenceTimerRef.current);
+        if (toastTimerRef.current !== null)
+            window.clearTimeout(toastTimerRef.current);
+    }, []);
+    const setCurrentRevision = (next) => {
+        revisionRef.current = next;
+        serverRevisionRef.current = Math.max(serverRevisionRef.current, next);
+        if (mountedRef.current)
+            setRevision(next);
+    };
+    /**
+     * The op ids this browser sent and has not seen come back, so
+     * `drainRemoteOperations` can tell its own echo from a peer's edit. See
+     * `createOwnOpLog` for why that is what keeps a save from flashing the grid.
+     */
+    const ownOpsRef = useRef(createOwnOpLog());
+    const userOpId = (id) => ownOpsRef.current.next(id);
+    const setMergeConflicts = (next, styleMap = {}) => {
+        conflictsRef.current = next;
+        conflictStyleMapRef.current = styleMap;
+        if (mountedRef.current)
+            setConflicts(next);
+    };
+    const schedulePresence = (next) => {
+        if (meta === null)
+            return;
+        pendingPresenceRef.current = next;
+        if (presenceTimerRef.current !== null)
+            window.clearTimeout(presenceTimerRef.current);
+        presenceTimerRef.current = window.setTimeout(() => {
+            presenceTimerRef.current = null;
+            const pending = pendingPresenceRef.current;
+            pendingPresenceRef.current = null;
+            if (pending === null || meta === null)
+                return;
+            void publishPresence(meta.id, pending).catch(() => { });
+        }, 120);
+    };
+    const showToast = (message, durationMs = 2200) => {
+        setToast(message);
+        if (toastTimerRef.current !== null)
+            window.clearTimeout(toastTimerRef.current);
+        toastTimerRef.current = window.setTimeout(() => {
+            toastTimerRef.current = null;
+            if (mountedRef.current)
+                setToast(null);
+        }, durationMs);
+    };
+    /**
+     * Refuse a *deliberate* write that cannot land: naming a Version, importing,
+     * or merging while a past Version is on screen. A two-second toast, because
+     * this is one refused action rather than a state to keep announcing.
+     *
+     * Editing the read-only grid on purpose is **not** this: that is Univer's
+     * workbook-level protection, the same mechanism a protected sheet uses, and
+     * it says nothing — a spreadsheet does not narrate a lock (GUI feedback
+     * 2026-09-19).
+     */
+    const refuseEdit = () => { showToast('该状态无法编辑', 2000); };
+    const loadHistory = async (id) => {
+        setHistoryLoading(true);
+        try {
+            const value = await fetchHistory(id);
+            if (mountedRef.current && activeWorkbookIdRef.current === id) {
+                setHistoryVersions(value.versions ?? historyVersionsFromEntries(value.entries ?? []));
+            }
+        }
+        catch (error) {
+            if (mountedRef.current)
+                setNotice(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (mountedRef.current)
+                setHistoryLoading(false);
+        }
+    };
+    /**
+     * Put a past Version on the canvas (PRD v3.2 §7.2). Preview is no longer a
+     * read-only screen inside the drawer: the fetched content state is handed to a
+     * read-only Univer residency, and the preview bar above it says what is on
+     * screen and lets the user switch without reopening the list.
+     *
+     * `entryId` is a Version id rather than a row, because the switcher in the bar
+     * addresses Versions the same way the list does.
+     */
+    /** Revision a baseline id measures against; `''` is the live content. */
+    const baselineOf = useCallback((baselineId, baselineStep) => {
+        if (baselineId === '')
+            return revisionRef.current;
+        return baselineRevisionOf(timelineEntries.find(candidate => candidate.id === baselineId), revisionRef.current, baselineStep);
+    }, [timelineEntries]);
+    const previewVersion = useCallback(async (entryId, step, baselineOverride, baselineStep) => {
+        if (meta === null)
+            return;
+        const entry = historyVersions.find(candidate => candidate.versionId === entryId);
+        if (entry === undefined || entry.canPreview !== true)
+            return;
+        setPreviewLoading(true);
+        try {
+            // Entering preview unmounts the live residency, so any edit that has not
+            // reached the server yet has to be committed first — otherwise it would
+            // silently disappear from the canvas when the preview ends. The ref keeps
+            // this out of the callback's dependency list (it closes over refs only).
+            if (dirtyRef.current)
+                await flushPendingSaveRef.current?.();
+            const value = await fetchHistorySnapshot(meta.id, entry.revision, step);
+            if (value.snapshot === undefined)
+                throw new Error('历史快照缺失');
+            // A Step preview already carries what that Step changed, measured against
+            // the state before it. A whole-Version view is measured against the chosen
+            // baseline — the current content by default, because "how is this
+            // different from what I have now" is the question a preview asks.
+            let changes = value.changes ?? [];
+            let changesUnavailable = false;
+            let changesTruncated = value.truncated === true;
+            let changesSide = 'after';
+            if (step === undefined) {
+                const against = baselineOverride === undefined
+                    ? baselineOf(inspectBaselineId, inspectBaselineStep)
+                    : baselineOf(baselineOverride, baselineStep);
+                const from = Math.min(against, entry.revision);
+                const to = Math.max(against, entry.revision);
+                // The canvas always shows `entry`, so that is the side whose changes
+                // are visible: the newer one, or the older one when previewing history
+                // against the current content.
+                changesSide = entry.revision >= against ? 'after' : 'before';
+                try {
+                    if (from === to) {
+                        changes = [];
+                        changesTruncated = false;
+                    }
+                    else {
+                        const diff = await fetchHistoryDiff(meta.id, from, to);
+                        changes = diff.changes ?? [];
+                        changesTruncated = diff.truncated === true;
+                    }
+                }
+                catch {
+                    changes = [];
+                    changesUnavailable = true;
+                    changesTruncated = false;
+                }
+            }
+            const next = {
+                versionId: entry.versionId,
+                revision: value.revision ?? entry.revision,
+                snapshot: value.snapshot,
+                step: step ?? null,
+                changes,
+                changesSide,
+                ...(changesUnavailable ? { changesUnavailable: true } : {}),
+                ...(changesTruncated ? { changesTruncated: true } : {}),
+            };
+            // Switch content inside the residency when possible: changing what is
+            // inspected is "different cells", not "a different application", and
+            // rebuilding Univer for it is what made every switch flash
+            // (PRD v3.5 §7.2). Only a failed swap, or entering inspect from live,
+            // rebuilds the canvas.
+            const swapped = preview !== null && viewHandle.current?.swapWorkbook(next.snapshot, toDecoration(changes, changesSide)) === true;
+            if (!swapped)
+                setInspectRemount(count => count + 1);
+            setPreview(next);
+            // The bar lives above the canvas, so the drawer has to get out of the way
+            // — leaving it open would cover the content being inspected.
+            setHistoryOpen(false);
+        }
+        catch (error) {
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (mountedRef.current)
+                setPreviewLoading(false);
+        }
+    }, [baselineOf, historyVersions, inspectBaselineId, inspectBaselineStep, meta, preview]);
+    /** Leave inspect and hand the canvas back to the live projection. */
+    const exitPreview = useCallback(() => {
+        setPreview(null);
+        // Re-read the live projection: the collaboration stream keeps `snapshot`
+        // current while inspecting, and remounting is the only way Univer swaps
+        // workbooks. A bumped key also covers a residency that never changed it.
+        setViewKey(key => key + 1);
+    }, []);
+    /**
+     * The canvas overlay: identical to what an in-place swap painted, so a
+     * remount and a swap show exactly the same thing.
+     */
+    const previewDecoration = useMemo(() => previewDecorationOf(preview), [preview]);
+    /** Counts + legend for the bar, derived from the same list the canvas tints. */
+    const previewSummary = useMemo(() => inspectorSummaryOf(preview), [preview]);
+    /** The row's single primary action opens the shared confirmation dialog. */
+    const requestRestore = (entry, intent) => {
+        const target = historyVersions.find(candidate => candidate.versionId === intent.targetId);
+        if (target === undefined)
+            return;
+        setRestoreRequest({
+            revision: target.revision,
+            label: intent.targetLabel,
+            // Same copy in both plugins: the Version records where it came from, and
+            // the dialog is what explains an undo (PRD v3 §8). The record gets the
+            // Version *number*, never the dialog's render-time label: a relative day
+            // word written into history is wrong by the next morning.
+            summary: restoreVersionSummary(target.number),
+            mode: intent.mode,
+        });
+    };
+    /** What each row's links do; `restorableId` is filled in by the drawer. */
+    const versionActions = {
+        onPreview: entry => { void previewVersion(entry.id); },
+        onPreviewStep: (entry, step) => { void previewVersion(entry.id, step.index); },
+        onRestore: requestRestore,
+        undoTargetFor,
+        ...(preview === null ? {} : { previewingId: preview.versionId }),
+        onToggleSteps: entry => setExpandedHistoryVersions(current => {
+            const revision = entry.revision ?? -1;
+            const next = new Set(current);
+            if (next.has(revision))
+                next.delete(revision);
+            else
+                next.add(revision);
+            return next;
+        }),
+    };
+    const restoreHistory = async (request) => {
+        if (meta === null || request.revision === revisionRef.current)
+            return;
+        setHistoryLoading(true);
+        try {
+            await rollbackWorkbook(meta.id, request.revision, revisionRef.current, request.summary);
+            // A restore records its own deliberate Version; the open session is over.
+            setSession(null);
+            await reloadSnapshot(meta.id, true);
+            setPreview(null);
+            setStatus('saved');
+            setNotice(request.mode === 'undo'
+                ? '已撤销这次改动，历史版本仍然保留。'
+                : `已恢复到 ${request.label}，历史版本仍然保留。`);
+            await loadHistory(meta.id);
+        }
+        catch (error) {
+            setStatus(error instanceof RevisionConflictError ? 'conflict' : 'error');
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (mountedRef.current)
+                setHistoryLoading(false);
+        }
+    };
+    // Univer's history command is registered by the open-source Datasheet
+    // plugin and asks this host-owned panel to load the durable operation log.
+    useEffect(() => {
+        if (!open || meta === null)
+            return;
+        const onOpenHistory = () => {
+            setHistoryOpen(true);
+            void loadHistory(meta.id);
+        };
+        const onCommandError = (event) => {
+            const message = event.detail?.message;
+            if (message !== undefined) {
+                setStatus('error');
+                setNotice(message);
+            }
+        };
+        window.addEventListener('data-sheet:history', onOpenHistory);
+        window.addEventListener('data-sheet:command-error', onCommandError);
+        return () => {
+            window.removeEventListener('data-sheet:history', onOpenHistory);
+            window.removeEventListener('data-sheet:command-error', onCommandError);
+        };
+    }, [meta, open]);
+    const reloadSnapshot = async (id, remount) => {
+        if (saveTimer.current !== null) {
+            window.clearTimeout(saveTimer.current);
+            saveTimer.current = null;
+        }
+        pendingLocalChangesRef.current = [];
+        snapshotSaveRequiredRef.current = false;
+        remoteOperationsRef.current.clear();
+        remoteSnapshotPendingRef.current = false;
+        const envelope = await fetchWorkbook(id);
+        if (envelope.snapshot === undefined)
+            throw new Error('workbook snapshot 缺失');
+        if (!mountedRef.current)
+            return;
+        const name = workbookName(id, workbooksRef.current);
+        const nextSnapshot = withWorkbookName(envelope.snapshot, name);
+        baselineRef.current = cloneSnapshot(nextSnapshot);
+        setMergeConflicts([]);
+        setSnapshot(nextSnapshot);
+        activeWorkbookIdRef.current = id;
+        serverRevisionRef.current = envelope.revision ?? 0;
+        setMeta({ id, name });
+        setCurrentRevision(envelope.revision ?? 0);
+        dirtyRef.current = false;
+        setNotice(null);
+        if (remount)
+            setViewKey(key => key + 1);
+    };
+    /**
+     * Adopt a snapshot the Host has just stored, instead of re-downloading it.
+     *
+     * The save response carries the new revision and `viewHandle.save()` is what
+     * was stored, so a fetch would only return the snapshot the canvas already
+     * shows — and `reloadSnapshot`'s `remount` argument would then bump `viewKey`
+     * and rebuild the Univer residency for nothing. Queued remote operations at or
+     * below the new revision are dropped the way a cell save drops them, and
+     * `remoteSnapshotPending` is cleared because this *is* what it waited for.
+     */
+    const adoptStoredSnapshot = (id, snapshotData, revision) => {
+        const next = withWorkbookName(snapshotData, workbookName(id, workbooksRef.current));
+        baselineRef.current = cloneSnapshot(next);
+        snapshotRef.current = next;
+        setSnapshot(next);
+        remoteSnapshotPendingRef.current = false;
+        setMergeConflicts([]);
+        for (const pendingRevision of [...remoteOperationsRef.current.keys()]) {
+            if (pendingRevision <= revision)
+                remoteOperationsRef.current.delete(pendingRevision);
+        }
+        serverRevisionRef.current = Math.max(serverRevisionRef.current, revision);
+        setCurrentRevision(revision);
+    };
+    /**
+     * Bootstrap the browser projection.
+     *
+     * This effect deliberately does **not** depend on `snapshot`: `snapshot` gets a
+     * fresh object identity on every load, so depending on it re-ran the request
+     * that produced it, forever — a reload loop that also tore down and rebuilt
+     * the collaboration session on every iteration. `snapshotRef` carries the few
+     * facts the effect needs.
+     *
+     * A re-entry into a workbook that is already painted (the resident workspace
+     * never disappeared, or the cached projection is still valid) only refreshes
+     * the catalog: the collaboration stream reconciles any missed operations
+     * through `/changes`, which is far cheaper than re-downloading the snapshot.
+     */
+    useEffect(() => {
+        mountedRef.current = true;
+        if (!open)
+            return;
+        let cancelled = false;
+        void (async () => {
+            const catalog = await fetchWorkbooks().catch(() => ({ workbooks: [] }));
+            const choices = catalog.workbooks ?? [];
+            workbooksRef.current = choices;
+            if (!cancelled)
+                setWorkbooks(choices);
+            // An explicit target wins; otherwise reopen whatever the user last had,
+            // so switching DSH tabs does not silently deselect the workbook.
+            const requestedWorkbookId = initialWorkbookId?.trim() || lastSelectedWorkbookId();
+            if (requestedWorkbookId.length === 0) {
+                if (!cancelled) {
+                    setStatus('saved');
+                    setNotice(choices.length === 0 ? '暂无工作簿，请先创建工作簿。' : '请选择要打开的工作簿。');
+                }
+                return;
+            }
+            // Already showing this workbook: keep the projection and let the sync
+            // session catch up. Replacing it here is what made every visit flash.
+            if (activeWorkbookIdRef.current === requestedWorkbookId && snapshotRef.current !== null) {
+                if (cancelled)
+                    return;
+                const name = workbookName(requestedWorkbookId, choices);
+                if (metaRef.current !== null && metaRef.current.name !== name)
+                    setMeta({ id: requestedWorkbookId, name });
+                setStatus('saved');
+                return;
+            }
+            try {
+                const envelope = await fetchWorkbook(requestedWorkbookId);
+                if (!cancelled && envelope.snapshot !== undefined) {
+                    const name = workbookName(requestedWorkbookId, choices);
+                    const nextSnapshot = withWorkbookName(envelope.snapshot, name);
+                    baselineRef.current = cloneSnapshot(nextSnapshot);
+                    setMergeConflicts([]);
+                    snapshotRef.current = nextSnapshot;
+                    setSnapshot(nextSnapshot);
+                    activeWorkbookIdRef.current = requestedWorkbookId;
+                    // A cold load continues whatever unretained session this workbook
+                    // left open, so closing and reopening the tab does not fork a Version.
+                    seedSession(requestedWorkbookId);
+                    serverRevisionRef.current = envelope.revision ?? 0;
+                    metaRef.current = { id: requestedWorkbookId, name };
+                    setMeta({ id: requestedWorkbookId, name });
+                    setCurrentRevision(envelope.revision ?? 0);
+                    setStatus('saved');
+                }
+            }
+            catch (error) {
+                // A failed revalidation must not throw away the projection already on
+                // screen; it only reports the failure.
+                if (!cancelled) {
+                    setStatus('error');
+                    if (error instanceof HttpStatusError && error.status === 404) {
+                        rememberWorkbook('');
+                        forgetWorkbookProjection(requestedWorkbookId);
+                        activeWorkbookIdRef.current = null;
+                        snapshotRef.current = null;
+                    }
+                    setNotice(error instanceof HttpStatusError && error.status === 404
+                        ? `工作簿「${requestedWorkbookId}」不存在，请先创建后再打开。`
+                        : error instanceof Error ? error.message : String(error));
+                }
+            }
+        })();
+        return () => { cancelled = true; };
+    }, [initialWorkbookId, open]);
+    // Refresh the explicit workbook catalog without opening a default workbook.
+    useEffect(() => {
+        if (!open)
+            return;
+        const refresh = async () => {
+            try {
+                const choices = (await fetchWorkbooks()).workbooks ?? [];
+                workbooksRef.current = choices;
+                if (mountedRef.current)
+                    setWorkbooks(choices);
+            }
+            catch {
+                // A temporary catalog failure should not interrupt editing.
+            }
+        };
+        const timer = window.setInterval(() => { void refresh(); }, 5000);
+        return () => window.clearInterval(timer);
+    }, [open]);
+    /** Merge a failed local save against the newest server snapshot. */
+    const mergeWithLatestRemote = async (id, localSnapshot, retry = 0) => {
+        pendingLocalChangesRef.current = [];
+        snapshotSaveRequiredRef.current = false;
+        // The merged result is committed as a whole-snapshot Step; the session it
+        // joins is the one already open, so the cursor stays where it is.
+        const envelope = await fetchWorkbook(id);
+        if (envelope.snapshot === undefined)
+            throw new Error('远端 workbook snapshot 缺失');
+        const name = workbookName(id, workbooksRef.current);
+        const remoteSnapshot = withWorkbookName(envelope.snapshot, name);
+        const baseSnapshot = baselineRef.current ?? cloneSnapshot(remoteSnapshot);
+        const normalizedLocal = stripConflictMarkers(localSnapshot, conflictStyleMapRef.current);
+        const merged = mergeWorkbookSnapshots(baseSnapshot, normalizedLocal, remoteSnapshot);
+        const mergedSnapshot = withWorkbookName(merged.snapshot, name);
+        const remoteRevision = envelope.revision ?? 0;
+        baselineRef.current = cloneSnapshot(remoteSnapshot);
+        activeWorkbookIdRef.current = id;
+        setCurrentRevision(remoteRevision);
+        setMergeConflicts(merged.conflicts, merged.conflictStyleMap);
+        setSnapshot(mergedSnapshot);
+        setViewKey(key => key + 1);
+        dirtyRef.current = true;
+        if (merged.conflicts.length > 0) {
+            setStatus('conflict');
+            setNotice(`已自动合并 ${merged.autoMergedCells} 个单元格；发现 ${merged.conflicts.length} 个冲突，冲突单元格已保留本地值并标记。请处理后提交合并结果。`);
+            return null;
+        }
+        savingRef.current = true;
+        setStatus('saving');
+        try {
+            const result = await persistSnapshotForTarget(id, mergedSnapshot, remoteRevision, userOpId(id));
+            const cleanSnapshot = stripConflictMarkers(mergedSnapshot, merged.conflictStyleMap);
+            baselineRef.current = cloneSnapshot(cleanSnapshot);
+            setSnapshot(cleanSnapshot);
+            setMergeConflicts([]);
+            pendingLocalChangesRef.current = [];
+            adoptSession(result, sessionVersionId(), sessionStepCount() + 1);
+            snapshotSaveRequiredRef.current = false;
+            dirtyRef.current = false;
+            if (result !== null)
+                setCurrentRevision(result.revision);
+            setStatus('saved');
+            setNotice(`已自动合并远端修改${merged.autoMergedCells > 0 ? `，合并 ${merged.autoMergedCells} 个单元格` : ''}。`);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof RevisionConflictError && retry < 1)
+                return mergeWithLatestRemote(id, mergedSnapshot, retry + 1);
+            throw error;
+        }
+        finally {
+            savingRef.current = false;
+            void drainRemoteOperations();
+        }
+    };
+    /** Explicitly commit a merged canvas after the user reviews marked cells. */
+    const commitMergedSnapshot = async () => {
+        if (meta === null || conflictsRef.current.length === 0)
+            return;
+        const localSnapshot = viewHandle.current?.save();
+        if (localSnapshot === undefined || localSnapshot === null || typeof localSnapshot !== 'object')
+            return;
+        savingRef.current = true;
+        setStatus('saving');
+        const cleanSnapshot = stripConflictMarkers(localSnapshot, conflictStyleMapRef.current);
+        try {
+            const result = await persistSnapshotForTarget(meta.id, cleanSnapshot, revisionRef.current, userOpId(meta.id));
+            baselineRef.current = cloneSnapshot(cleanSnapshot);
+            setSnapshot(cleanSnapshot);
+            setViewKey(key => key + 1);
+            setMergeConflicts([]);
+            pendingLocalChangesRef.current = [];
+            adoptSession(result, sessionVersionId(), sessionStepCount() + 1);
+            snapshotSaveRequiredRef.current = false;
+            dirtyRef.current = false;
+            if (result !== null)
+                setCurrentRevision(result.revision);
+            setStatus('saved');
+            setNotice('已提交三方合并结果，冲突标记已清除。');
+        }
+        catch (error) {
+            if (error instanceof RevisionConflictError) {
+                try {
+                    await mergeWithLatestRemote(meta.id, localSnapshot);
+                }
+                catch (mergeError) {
+                    setStatus('conflict');
+                    setNotice(mergeError instanceof Error ? mergeError.message : String(mergeError));
+                }
+            }
+            else {
+                setStatus('error');
+                setNotice(error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            savingRef.current = false;
+            void drainRemoteOperations();
+        }
+    };
+    const applyLocalChangesToCanvas = async (changes, id, revision) => {
+        const handle = viewHandle.current;
+        if (handle === null)
+            return;
+        for (const change of changes) {
+            await handle.applyOperation({
+                opId: `local-preview:${id}:${revision}:${Math.random().toString(36).slice(2)}`,
+                workbookId: id,
+                revision,
+                actor: 'user',
+                type: change.type,
+                payload: change.payload,
+                timestamp: new Date().toISOString(),
+            });
+        }
+    };
+    const savePendingUserChanges = async (requestedId) => {
+        const id = requestedId ?? meta?.id;
+        if (id === undefined || id.length === 0)
+            return;
+        // A single in-flight save owns the current revision. New edits remain in
+        // the queue and are drained by the finally block below.
+        if (savingRef.current)
+            return;
+        if (!dirtyRef.current || conflictsRef.current.length > 0)
+            return;
+        const pending = pendingLocalChangesRef.current;
+        const forceSnapshot = snapshotSaveRequiredRef.current;
+        if (!forceSnapshot && pending.length === 0)
+            return;
+        const versionStepCount = sessionStepCount();
+        const versionId = sessionVersionId() ?? nextUserVersionId(id);
+        const remainingVersionSlots = Math.max(1, HUMAN_VERSION_STEP_LIMIT - versionStepCount);
+        const sentChanges = forceSnapshot ? [] : pending.slice(0, remainingVersionSlots);
+        const nextVersionStepCount = versionStepCount + sentChanges.length;
+        const versionStatus = nextVersionStepCount >= HUMAN_VERSION_STEP_LIMIT ? 'final' : 'open';
+        const savedGeneration = editGenerationRef.current;
+        let snap = null;
+        if (forceSnapshot) {
+            const value = viewHandle.current?.save();
+            snap = value !== undefined && value !== null && typeof value === 'object' ? value : null;
+            if (snap === null)
+                return;
+        }
+        pendingLocalChangesRef.current = forceSnapshot ? [] : pending.slice(sentChanges.length);
+        snapshotSaveRequiredRef.current = false;
+        savingRef.current = true;
+        try {
+            const opId = userOpId(id);
+            const result = forceSnapshot
+                ? await saveSnapshot(id, snap, revisionRef.current, opId, { versionId, versionStatus, versionKind: 'auto' })
+                : await saveOperationChanges(id, sentChanges, revisionRef.current, opId, { id: versionId, status: versionStatus });
+            if (result === null || !mountedRef.current || activeWorkbookIdRef.current !== id)
+                return;
+            let effectiveVersionStatus = forceSnapshot ? 'final' : versionStatus;
+            let effectiveVersionStepCount = nextVersionStepCount;
+            if (forceSnapshot && snap !== null) {
+                const cleanSnapshot = stripConflictMarkers(snap, conflictStyleMapRef.current);
+                baselineRef.current = cloneSnapshot(cleanSnapshot);
+                setMergeConflicts([]);
+            }
+            else if (baselineRef.current !== null) {
+                // The server may have accepted this cell edit on top of concurrent
+                // remote cell edits. Project those remote edits first so the live
+                // Univer canvas and the merge base do not lose them.
+                for (const remoteOperation of result.rebasedOperations ?? []) {
+                    remoteOperationsRef.current.delete(remoteOperation.revision);
+                    try {
+                        await viewHandle.current?.applyOperation(remoteOperation);
+                    }
+                    catch { /* the next sync can reload a snapshot */ }
+                    applyIncrementalOperationsToSnapshot(baselineRef.current, [remoteOperation]);
+                }
+                applyIncrementalChangesToSnapshot(baselineRef.current, sentChanges);
+                // The server applies the local request after all rebased operations.
+                // Replay it in the live canvas as well so the visual projection has
+                // exactly the same last-writer-wins result as the durable snapshot.
+                await applyLocalChangesToCanvas(sentChanges, id, result.revision);
+            }
+            if (!forceSnapshot) {
+                const committedVersionId = result.operation?.versionId ?? versionId;
+                const storedVersionStatus = result.operation?.versionStatus ?? versionStatus;
+                // A just-upgraded browser may receive a legacy `temporary` status
+                // from an older Host during rolling upgrades. Treat it as `open`.
+                const committedVersionStatus = storedVersionStatus === 'final' ? 'final' : 'open';
+                effectiveVersionStatus = committedVersionStatus;
+                effectiveVersionStepCount = committedVersionId === versionId ? nextVersionStepCount : sentChanges.length;
+                if (committedVersionStatus === 'final') {
+                    setSession(null);
+                }
+                else {
+                    setSession({ versionId: committedVersionId, stepCount: effectiveVersionStepCount });
+                }
+            }
+            else {
+                // A whole-snapshot save is one Step of the editing session (PRD v3.1
+                // §4): keep joining the same Version so a session stays one Version.
+                const committedVersionId = result.operation?.versionId ?? versionId;
+                const storedVersionStatus = result.operation?.versionStatus;
+                if (storedVersionStatus === 'final') {
+                    setSession(null);
+                }
+                else {
+                    setSession({ versionId: committedVersionId, stepCount: versionStepCount + 1 });
+                }
+            }
+            const hasNewerEdits = editGenerationRef.current !== savedGeneration
+                || pendingLocalChangesRef.current.length > 0 || snapshotSaveRequiredRef.current;
+            dirtyRef.current = hasNewerEdits;
+            setCurrentRevision(result.revision);
+            serverRevisionRef.current = Math.max(serverRevisionRef.current, result.revision);
+            for (const revision of [...remoteOperationsRef.current.keys()]) {
+                if (revision <= result.revision)
+                    remoteOperationsRef.current.delete(revision);
+            }
+            setStatus(hasNewerEdits ? 'saving' : 'saved');
+            if (!hasNewerEdits) {
+                // Clear a stale network/conflict message before showing the compact
+                // success toast; otherwise both notices would stack at the same edge.
+                setNotice(null);
+                // The top menu row already carries a permanent 已保存 indicator at its
+                // right edge, so a plain success toast only duplicated it. Keep the
+                // toast solely for the case it cannot express: the edits are saved but
+                // still sit in the open editing session, which the version list does
+                // not show until it is named (PRD v3.2 §7.3).
+                if (effectiveVersionStatus === 'open') {
+                    showToast(`已保存 · 编辑会话中（${effectiveVersionStepCount}/${HUMAN_VERSION_STEP_LIMIT} 步），命名后进版本清单`);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof RevisionConflictError) {
+                const latestLocal = viewHandle.current?.save();
+                try {
+                    await mergeWithLatestRemote(id, (latestLocal !== undefined && latestLocal !== null ? latestLocal : snap ?? baselineRef.current));
+                }
+                catch (mergeError) {
+                    if (mountedRef.current && activeWorkbookIdRef.current === id) {
+                        setStatus('conflict');
+                        setNotice(mergeError instanceof Error ? mergeError.message : String(mergeError));
+                    }
+                }
+                return;
+            }
+            // Keep a failed incremental edit queued so a later edit/flush can retry
+            // it without forcing the user to reload the workbook.
+            pendingLocalChangesRef.current = [...sentChanges, ...pendingLocalChangesRef.current];
+            if (forceSnapshot)
+                snapshotSaveRequiredRef.current = true;
+            if (mountedRef.current && activeWorkbookIdRef.current === id) {
+                setStatus('error');
+                setNotice(error instanceof Error ? error.message : '保存失败，请稍后重试。');
+            }
+            throw error;
+        }
+        finally {
+            savingRef.current = false;
+            if (mountedRef.current && activeWorkbookIdRef.current === id && dirtyRef.current
+                && conflictsRef.current.length === 0 && saveTimer.current === null && pendingSavePromiseRef.current === null) {
+                const nextPromise = savePendingUserChanges(id);
+                pendingSavePromiseRef.current = nextPromise;
+                void nextPromise.finally(() => {
+                    if (pendingSavePromiseRef.current === nextPromise)
+                        pendingSavePromiseRef.current = null;
+                }).catch(() => { });
+            }
+        }
+    };
+    const scheduleSave = (change) => {
+        // A preview canvas is read-only (`WorkbookCanvas readOnly`) and never calls
+        // this, but the guard is what makes "a preview cannot fork a Version" a
+        // property of the panel rather than of Univer's permission plugin.
+        if (preview !== null)
+            return;
+        if (conflictsRef.current.length > 0) {
+            dirtyRef.current = true;
+            setStatus('conflict');
+            setNotice('当前仍有三方合并冲突，请处理标记单元格后点击「提交合并结果」。');
+            return;
+        }
+        editGenerationRef.current += 1;
+        dirtyRef.current = true;
+        if (change !== undefined && change.payload.cells.length > 0)
+            pendingLocalChangesRef.current.push(change);
+        else
+            snapshotSaveRequiredRef.current = true;
+        setStatus('saving');
+        // A human Version is created only on Ctrl/Cmd+S or after ten mutation
+        // steps. Selection/focus events never reach this callback and therefore
+        // cannot trigger a save.
+        const pendingStepCount = snapshotSaveRequiredRef.current
+            ? HUMAN_VERSION_STEP_LIMIT
+            : sessionStepCount() + pendingLocalChangesRef.current.length;
+        if (pendingStepCount < HUMAN_VERSION_STEP_LIMIT)
+            return;
+        if (saveTimer.current !== null)
+            window.clearTimeout(saveTimer.current);
+        const id = meta?.id;
+        if (id === undefined)
+            return;
+        saveTimer.current = window.setTimeout(() => {
+            saveTimer.current = null;
+            const promise = savePendingUserChanges(id);
+            pendingSavePromiseRef.current = promise;
+            void promise.finally(() => {
+                if (pendingSavePromiseRef.current === promise)
+                    pendingSavePromiseRef.current = null;
+            }).catch(() => { });
+        }, 0);
+    };
+    const flushPendingSave = async () => {
+        if (saveTimer.current !== null) {
+            window.clearTimeout(saveTimer.current);
+            saveTimer.current = null;
+        }
+        if (!dirtyRef.current || meta === null)
+            return;
+        if (conflictsRef.current.length > 0)
+            throw new Error('当前存在三方合并冲突，请先提交合并结果或重新加载最新版本');
+        // A save submits at most ten steps. Keep waiting for any follow-up save
+        // started by the single-flight drain so Ctrl/Cmd+S and workbook switching
+        // never leave a tail of pending edits behind.
+        while (dirtyRef.current && conflictsRef.current.length === 0) {
+            if (!snapshotSaveRequiredRef.current && pendingLocalChangesRef.current.length === 0)
+                break;
+            if (pendingSavePromiseRef.current !== null) {
+                await pendingSavePromiseRef.current;
+            }
+            else if (!savingRef.current) {
+                await savePendingUserChanges(meta.id);
+            }
+            else {
+                return;
+            }
+        }
+        if (conflictsRef.current.length > 0)
+            throw new Error('已完成自动合并，但仍有冲突单元格待处理');
+    };
+    /** Name the current content as an explicit Version even without new edits (PRD §8). */
+    const saveNamedVersion = async (name) => {
+        const id = activeWorkbookIdRef.current;
+        if (id === null)
+            return;
+        // The canvas is showing a past Version: saving it would forge the user's
+        // history. Leaving preview is one click, and the copy says so.
+        if (preview !== null) {
+            setSaveVersionOpen(false);
+            refuseEdit();
+            return;
+        }
+        // D4: an empty name is allowed — "just save this" must not become a naming
+        // chore, so it is auto-named like `6/18 09:41`.
+        const label = name.trim() === '' ? autoVersionName() : name.trim();
+        const snapshotData = viewHandle.current?.save();
+        if (snapshotData === undefined || snapshotData === null || typeof snapshotData !== 'object') {
+            setNotice('无法读取当前工作簿快照，请稍后重试。');
+            return;
+        }
+        // A whole-snapshot save carries the *canvas*, so every queued change is
+        // already inside `snapshotData`. Dropping the queue here rather than when
+        // the answer arrives is what makes an edit arriving during the round-trip
+        // distinguishable: the generation moves and the queue refills.
+        const savedGeneration = editGenerationRef.current;
+        const queuedBeforeSave = pendingLocalChangesRef.current;
+        const queuedSnapshotBeforeSave = snapshotSaveRequiredRef.current;
+        pendingLocalChangesRef.current = [];
+        snapshotSaveRequiredRef.current = false;
+        setSaveVersionPending(true);
+        try {
+            const result = await saveSnapshot(id, snapshotData, revisionRef.current, userOpId(id), {
+                summary: label,
+                versionKind: 'named',
+                versionStatus: 'final',
+            });
+            if (result !== null) {
+                // A named save is a deliberate Version boundary on the Host, so the
+                // unretained session ends here as well.
+                setSession(null);
+                adoptStoredSnapshot(id, snapshotData, result.revision);
+                setSaveVersionOpen(false);
+                setNotice(`已保存版本「${label}」。`);
+                // An edit made while the request was in flight is not in the Version
+                // that was just stored. It opens the next editing session instead of
+                // being discarded along with the queues.
+                const hasNewerEdits = editGenerationRef.current !== savedGeneration
+                    || pendingLocalChangesRef.current.length > 0 || snapshotSaveRequiredRef.current;
+                dirtyRef.current = hasNewerEdits;
+                if (hasNewerEdits)
+                    void savePendingUserChanges(id);
+                else
+                    setStatus('saved');
+                await loadHistory(id);
+            }
+        }
+        catch (error) {
+            // The queued changes are still on the canvas, but only a whole-snapshot
+            // save can carry them now that the queue is empty — the same answer the
+            // incremental path gives for a failed structural change.
+            if (mountedRef.current) {
+                pendingLocalChangesRef.current = [...queuedBeforeSave, ...pendingLocalChangesRef.current];
+                snapshotSaveRequiredRef.current = queuedSnapshotBeforeSave || pendingLocalChangesRef.current.length > 0;
+                dirtyRef.current = snapshotSaveRequiredRef.current || pendingLocalChangesRef.current.length > 0;
+            }
+            setStatus(error instanceof RevisionConflictError ? 'conflict' : 'error');
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (mountedRef.current)
+                setSaveVersionPending(false);
+        }
+    };
+    const persistSnapshotForTarget = (id, snapshotData, baseRevision, opId) => {
+        // Import / merge / structural writes all funnel through here. While a past
+        // Version is on screen the workbook on screen is not the workbook being
+        // edited, so none of them may be recorded.
+        if (previewRef.current !== null) {
+            refuseEdit();
+            return Promise.resolve(null);
+        }
+        // Import / merge / structural flush: one auto Step of the editing session.
+        return saveSnapshot(id, snapshotData, baseRevision, opId, { versionKind: 'auto', versionStatus: 'open' });
+    };
+    // Univer/browser defaults may interpret Ctrl/Cmd+S as a navigation or
+    // refresh action in the host. Datasheet owns persistence, so consume the
+    // shortcut and flush the queue without remounting or reloading the canvas.
+    flushPendingSaveRef.current = flushPendingSave;
+    useEffect(() => {
+        // Window-level: must not stay bound while the Table tab is off screen.
+        if (!visible)
+            return;
+        const onSaveShortcut = (event) => {
+            if (!(event.ctrlKey || event.metaKey) || event.key.toLowerCase() !== 's')
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            event.stopImmediatePropagation();
+            const flush = flushPendingSaveRef.current;
+            if (flush === null)
+                return;
+            // Ctrl/⌘+S is its own confirmation: the top menu row already flips to
+            // 已保存, so it does not need a top-right toast on top of that.
+            void flush().catch(error => {
+                if (mountedRef.current) {
+                    setStatus('error');
+                    setNotice(error instanceof Error ? error.message : String(error));
+                }
+            });
+        };
+        window.addEventListener('keydown', onSaveShortcut, true);
+        return () => window.removeEventListener('keydown', onSaveShortcut, true);
+    }, [visible]);
+    // Leaving the tab commits whatever is still queued, but it is **not** a
+    // Version boundary (PRD v3.3 D21): the request carries the persisted session
+    // id, so it joins the same unretained Version. Only the idle window and the
+    // Step cap close a Version. The flush stays because the resident workspace can
+    // be released after a long idle stay, and an unsaved edit would go with it.
+    useEffect(() => {
+        if (visible || !dirtyRef.current)
+            return;
+        const flush = flushPendingSaveRef.current;
+        if (flush === null)
+            return;
+        void flush().catch(() => { });
+    }, [visible]);
+    /**
+     * Apply committed remote operations in Host revision order. Cell writes are
+     * safe to project even when coordinates overlap: after the remote operation
+     * is painted, the user's pending edits are replayed as a local preview and
+     * will be committed after it. Structural/snapshot changes still use merge.
+     */
+    const drainRemoteOperations = async () => {
+        if (drainingRemoteRef.current || meta === null || !mountedRef.current)
+            return;
+        // A preview residency is rendering a past Version, so a remote operation
+        // must not be painted onto it — the queue is kept intact and drains once the
+        // user leaves preview. Read through a ref because the sync interval and the
+        // collaboration stream captured this callback on an earlier render.
+        if (previewRef.current !== null)
+            return;
+        drainingRemoteRef.current = true;
+        try {
+            while (mountedRef.current && activeWorkbookIdRef.current === meta.id) {
+                for (const revision of [...remoteOperationsRef.current.keys()]) {
+                    if (revision <= revisionRef.current)
+                        remoteOperationsRef.current.delete(revision);
+                }
+                if (remoteSnapshotPendingRef.current) {
+                    if (dirtyRef.current || savingRef.current)
+                        break;
+                    await reloadSnapshot(meta.id, true);
+                    continue;
+                }
+                const next = remoteOperationsRef.current.get(revisionRef.current + 1);
+                if (next === undefined) {
+                    const hasGap = [...remoteOperationsRef.current.keys()].some(revision => revision > revisionRef.current + 1);
+                    if (!hasGap)
+                        break;
+                    try {
+                        const changes = await fetchChanges(meta.id, revisionRef.current);
+                        serverRevisionRef.current = Math.max(serverRevisionRef.current, changes.revision ?? 0);
+                        if (changes.requiresSnapshot) {
+                            remoteSnapshotPendingRef.current = true;
+                            continue;
+                        }
+                        for (const operation of changes.operations ?? [])
+                            remoteOperationsRef.current.set(operation.revision, operation);
+                        continue;
+                    }
+                    catch {
+                        break;
+                    }
+                }
+                if (dirtyRef.current || savingRef.current) {
+                    const localChanges = coalesceLocalChanges(pendingLocalChangesRef.current);
+                    if (!canApplyRemoteWhileEditing(next, snapshotSaveRequiredRef.current)) {
+                        remoteSnapshotPendingRef.current = true;
+                        break;
+                    }
+                }
+                // A write this browser made, echoed back over the collaboration stream.
+                // It is already on the canvas and in the baseline, so the only correct
+                // answer is to retire its revision and move on; the `snapshot_replace`
+                // branch below would otherwise re-download a snapshot the canvas is
+                // already showing. Checked before the dirty/saving branch, because the
+                // echo can arrive while the POST that produced it is still in flight.
+                if (ownOpsRef.current.take(next.opId)) {
+                    remoteOperationsRef.current.delete(next.revision);
+                    setCurrentRevision(next.revision);
+                    continue;
+                }
+                remoteOperationsRef.current.delete(next.revision);
+                if (next.actor === 'agent') {
+                    // Agent writes close a user's open Version on the Host.
+                    // Discard the client-side join cursor so the next human edit starts
+                    // a fresh logical Version after this remote revision.
+                    setSession(null);
+                }
+                if (next.type === 'snapshot_replace') {
+                    if (dirtyRef.current || savingRef.current) {
+                        remoteOperationsRef.current.set(next.revision, next);
+                        remoteSnapshotPendingRef.current = true;
+                        break;
+                    }
+                    await reloadSnapshot(meta.id, true);
+                    continue;
+                }
+                const handle = viewHandle.current;
+                if (handle === null) {
+                    remoteOperationsRef.current.set(next.revision, next);
+                    remoteSnapshotPendingRef.current = true;
+                    break;
+                }
+                try {
+                    await handle.applyOperation(next);
+                }
+                catch {
+                    if (dirtyRef.current || savingRef.current) {
+                        remoteOperationsRef.current.set(next.revision, next);
+                        remoteSnapshotPendingRef.current = true;
+                        break;
+                    }
+                    await reloadSnapshot(meta.id, true);
+                    continue;
+                }
+                if (baselineRef.current !== null && !applyIncrementalOperationsToSnapshot(baselineRef.current, [next])) {
+                    if (dirtyRef.current || savingRef.current) {
+                        remoteOperationsRef.current.set(next.revision, next);
+                        remoteSnapshotPendingRef.current = true;
+                        break;
+                    }
+                    await reloadSnapshot(meta.id, true);
+                    continue;
+                }
+                if (dirtyRef.current) {
+                    try {
+                        await applyLocalChangesToCanvas(coalesceLocalChanges(pendingLocalChangesRef.current), meta.id, revisionRef.current);
+                    }
+                    catch {
+                        remoteSnapshotPendingRef.current = true;
+                        break;
+                    }
+                }
+                setCurrentRevision(next.revision);
+            }
+        }
+        finally {
+            drainingRemoteRef.current = false;
+        }
+    };
+    const switchWorkbook = async (id) => {
+        if (id.length === 0 || id === meta?.id || switching)
+            return;
+        setSwitching(true);
+        try {
+            await flushPendingSave();
+            let envelope;
+            envelope = await fetchWorkbook(id);
+            if (envelope.snapshot === undefined)
+                throw new Error('workbook snapshot 缺失');
+            if (!mountedRef.current)
+                return;
+            publishDataSheetSelection([]);
+            const name = workbookName(id, workbooksRef.current);
+            const nextSnapshot = withWorkbookName(envelope.snapshot, name);
+            // Keep the old workbook mounted until the target has loaded. This makes
+            // switching atomic from the user's perspective and avoids a blank grid
+            // when a target request fails.
+            baselineRef.current = cloneSnapshot(nextSnapshot);
+            setMergeConflicts([]);
+            // Leaving the artifact also leaves its preview: the past Version belonged
+            // to the workbook that is being replaced.
+            setPreview(null);
+            setPresence([]);
+            pendingLocalChangesRef.current = [];
+            // Returning to a workbook continues the unretained session it left open
+            // (PRD v3.3 D22). Only the idle window or the Step cap may close it.
+            seedSession(id);
+            snapshotSaveRequiredRef.current = false;
+            remoteOperationsRef.current.clear();
+            remoteSnapshotPendingRef.current = false;
+            setSnapshot(nextSnapshot);
+            activeWorkbookIdRef.current = id;
+            serverRevisionRef.current = envelope.revision ?? 0;
+            setMeta({ id, name });
+            setCurrentRevision(envelope.revision ?? 0);
+            dirtyRef.current = false;
+            setNotice(null);
+            setViewKey(key => key + 1);
+            setStatus('saved');
+        }
+        catch (error) {
+            if (mountedRef.current) {
+                setStatus(error instanceof RevisionConflictError || conflictsRef.current.length > 0 ? 'conflict' : 'error');
+                setNotice(error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            if (mountedRef.current)
+                setSwitching(false);
+        }
+    };
+    const switchWorkbookRef = useRef(switchWorkbook);
+    switchWorkbookRef.current = switchWorkbook;
+    const applyPendingBridgeFocus = useCallback(() => {
+        const target = pendingBridgeFocusRef.current;
+        if (target === null || switching || target.workbookId !== meta?.id)
+            return;
+        if (viewHandle.current?.focusRange(target)) {
+            pendingBridgeFocusRef.current = null;
+            bridgeFocusAttemptRef.current = null;
+        }
+    }, [meta?.id, switching]);
+    const focusDataSheetSelection = useCallback((itemId) => {
+        const target = dataSheetFocusTargetOf(itemId);
+        if (target === undefined)
+            return;
+        pendingBridgeFocusRef.current = target;
+        bridgeFocusAttemptRef.current = null;
+        if (target.workbookId === meta?.id) {
+            applyPendingBridgeFocus();
+            return;
+        }
+        if (!switching) {
+            bridgeFocusAttemptRef.current = JSON.stringify(target);
+            void switchWorkbookRef.current(target.workbookId);
+        }
+    }, [applyPendingBridgeFocus, meta?.id, switching]);
+    useEffect(() => {
+        const target = pendingBridgeFocusRef.current;
+        if (target === null || switching)
+            return;
+        if (target.workbookId === meta?.id)
+            applyPendingBridgeFocus();
+        else {
+            const key = JSON.stringify(target);
+            if (bridgeFocusAttemptRef.current !== key) {
+                bridgeFocusAttemptRef.current = key;
+                void switchWorkbookRef.current(target.workbookId);
+            }
+        }
+    }, [applyPendingBridgeFocus, meta?.id, switching]);
+    useEffect(() => {
+        if (bridge === undefined)
+            return;
+        const unregister = registerDataSheetFocusHandler(focusDataSheetSelection);
+        const takeFocus = () => {
+            const request = bridge.takeFocus(DATA_SHEET_SURFACE_ID);
+            if (request === null)
+                return;
+            for (const itemId of request.itemIds)
+                focusDataSheetSelection(itemId);
+        };
+        const unsubscribe = bridge.subscribe(takeFocus);
+        takeFocus();
+        return () => {
+            unsubscribe();
+            unregister();
+        };
+    }, [bridge, focusDataSheetSelection]);
+    // Persist a pending user edit before the panel is torn down.
+    useEffect(() => {
+        return () => {
+            if (saveTimer.current !== null)
+                window.clearTimeout(saveTimer.current);
+            if (dirtyRef.current && conflictsRef.current.length === 0) {
+                const id = meta?.id ?? initialWorkbookId;
+                void savePendingUserChanges(id).catch(() => { });
+            }
+        };
+    }, [initialWorkbookId, meta]);
+    // Give the browser a last chance to send queued cell steps when the tab is
+    // hidden or closed. `keepalive` is applied at the request layer too;
+    // normal saves are threshold-based and single-flight.
+    useEffect(() => {
+        const onPageHide = () => {
+            if (!dirtyRef.current || conflictsRef.current.length > 0 || savingRef.current)
+                return;
+            void savePendingUserChanges(meta?.id ?? initialWorkbookId).catch(() => { });
+        };
+        window.addEventListener('pagehide', onPageHide);
+        return () => window.removeEventListener('pagehide', onPageHide);
+    }, [initialWorkbookId, meta]);
+    // Import is initiated by the Univer File menu and committed through the
+    // same optimistic snapshot endpoint as normal user edits.
+    useEffect(() => {
+        const onImport = (event) => {
+            const detail = event.detail;
+            if (detail?.snapshot === undefined || meta === null)
+                return;
+            savingRef.current = true;
+            setStatus('saving');
+            const importedSnapshot = withWorkbookName(detail.snapshot, meta.name);
+            pendingLocalChangesRef.current = [];
+            setSession(null);
+            snapshotSaveRequiredRef.current = false;
+            void persistSnapshotForTarget(meta.id, importedSnapshot, revisionRef.current, userOpId(meta.id))
+                .then(result => {
+                if (result === null || !mountedRef.current)
+                    return;
+                baselineRef.current = cloneSnapshot(importedSnapshot);
+                setMergeConflicts([]);
+                pendingLocalChangesRef.current = [];
+                setSession(null);
+                snapshotSaveRequiredRef.current = false;
+                dirtyRef.current = false;
+                setCurrentRevision(result.revision);
+                setSnapshot(importedSnapshot);
+                setViewKey(key => key + 1);
+                setStatus('saved');
+                setNotice(`已导入 ${detail.filename ?? 'Excel 文件'}`);
+            })
+                .catch(async (error) => {
+                if (mountedRef.current) {
+                    if (error instanceof RevisionConflictError) {
+                        try {
+                            await mergeWithLatestRemote(meta.id, importedSnapshot);
+                        }
+                        catch (mergeError) {
+                            setStatus('conflict');
+                            setNotice(mergeError instanceof Error ? mergeError.message : String(mergeError));
+                        }
+                    }
+                    else {
+                        setStatus('error');
+                        setNotice(error instanceof Error ? error.message : String(error));
+                    }
+                }
+            })
+                .finally(() => { savingRef.current = false; });
+        };
+        const onImportError = (event) => {
+            const message = event.detail?.message ?? 'Excel 导入失败';
+            setStatus('error');
+            setNotice(message);
+        };
+        window.addEventListener('data-sheet:import', onImport);
+        window.addEventListener('data-sheet:import-error', onImportError);
+        return () => {
+            window.removeEventListener('data-sheet:import', onImport);
+            window.removeEventListener('data-sheet:import-error', onImportError);
+        };
+    }, [meta]);
+    // Self-hosted collaboration session. The server uses SSE as a lightweight
+    // transport, while this client keeps the Pro-inspired session states:
+    // connected, pending/awaiting (represented by the save queue), fetch-miss,
+    // offline and conflict. Polling remains as a compatibility fallback.
+    useEffect(() => {
+        if (!open || !hasSnapshot || meta === null)
+            return;
+        let cancelled = false;
+        let source = null;
+        let reconnectTimer = null;
+        const enqueue = (changes) => {
+            if (cancelled)
+                return;
+            serverRevisionRef.current = Math.max(serverRevisionRef.current, changes.revision ?? 0);
+            if (changes.requiresSnapshot)
+                remoteSnapshotPendingRef.current = true;
+            for (const operation of changes.operations ?? [])
+                remoteOperationsRef.current.set(operation.revision, operation);
+            void drainRemoteOperations();
+        };
+        const connect = () => {
+            if (cancelled)
+                return;
+            const after = serverRevisionRef.current;
+            source = new EventSource(dataSheetClientPath(collaborationStreamPath(meta.id, after)));
+            source.addEventListener('ready', event => {
+                try {
+                    const envelope = JSON.parse(event.data);
+                    enqueue(envelope);
+                }
+                catch { /* the polling fallback repairs malformed events */ }
+            });
+            source.addEventListener('operation', event => {
+                try {
+                    const value = JSON.parse(event.data);
+                    if (value.operation !== undefined)
+                        enqueue({ revision: value.operation.revision, operations: [value.operation] });
+                }
+                catch {
+                    // Ignore malformed transient notifications; the next poll repairs the cursor.
+                }
+            });
+            source.addEventListener('presence', event => {
+                try {
+                    const value = JSON.parse(event.data);
+                    const incoming = value.presence;
+                    if (incoming === undefined || incoming.sessionId === dataSheetSessionId())
+                        return;
+                    setPresence(current => [...current.filter(item => item.sessionId !== incoming.sessionId), incoming].slice(-24));
+                }
+                catch { /* presence is best-effort */ }
+            });
+            source.onerror = () => {
+                source?.close();
+                source = null;
+                if (!cancelled && reconnectTimer === null) {
+                    reconnectTimer = window.setTimeout(() => {
+                        reconnectTimer = null;
+                        connect();
+                    }, 2000);
+                }
+            };
+        };
+        const pollFallback = async () => {
+            if (cancelled || source?.readyState === EventSource.OPEN)
+                return;
+            try {
+                enqueue(await fetchChanges(meta.id, revisionRef.current));
+            }
+            catch { /* the next poll/reconnect retries */ }
+        };
+        connect();
+        void pollFallback();
+        const timer = window.setInterval(() => { void pollFallback(); }, SYNC_INTERVAL_MS);
+        const presenceExpiry = window.setInterval(() => {
+            const cutoff = Date.now() - 30_000;
+            setPresence(current => current.filter(item => {
+                const timestamp = Date.parse(item.timestamp);
+                return !Number.isFinite(timestamp) || timestamp >= cutoff;
+            }));
+        }, 10_000);
+        return () => {
+            cancelled = true;
+            window.clearInterval(timer);
+            window.clearInterval(presenceExpiry);
+            if (reconnectTimer !== null)
+                window.clearTimeout(reconnectTimer);
+            source?.close();
+            source = null;
+        };
+        // `hasSnapshot` (not `snapshot`): reconnecting the stream on every
+        // revalidation would drop and rebuild the session on each load.
+    }, [hasSnapshot, meta, open]);
+    const reloadLatest = async () => {
+        if (meta === null)
+            return;
+        try {
+            setNotice(null);
+            await reloadSnapshot(meta.id, true);
+            dirtyRef.current = false;
+            setStatus('saved');
+        }
+        catch (error) {
+            setStatus('error');
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+    };
+    const refreshWorkbookCatalog = async () => {
+        const choices = (await fetchWorkbooks()).workbooks ?? [];
+        workbooksRef.current = choices;
+        if (mountedRef.current)
+            setWorkbooks(choices);
+        return choices;
+    };
+    const openCreateWorkbookDialog = () => {
+        if (workbookActionPending !== null)
+            return;
+        setWorkbookDialog({ kind: 'create', draft: `工作簿 ${workbooksRef.current.length + 1}` });
+    };
+    const openRenameWorkbookDialog = (id) => {
+        const target = workbooksRef.current.find(workbook => workbook.id === id);
+        if (target === undefined || workbookActionPending !== null)
+            return;
+        setWorkbookDialog({ kind: 'rename', id, draft: target.name });
+    };
+    const openDeleteWorkbookDialog = (id) => {
+        const target = workbooksRef.current.find(workbook => workbook.id === id);
+        if (target === undefined || id === meta?.id || workbookActionPending !== null || deletingWorkbookId !== null)
+            return;
+        setWorkbookDialog({ kind: 'delete', id });
+    };
+    const submitWorkbookDialog = async () => {
+        const dialog = workbookDialog;
+        if (dialog === null || workbookActionPending !== null)
+            return;
+        const target = dialog.kind === 'create' ? undefined : workbooksRef.current.find(workbook => workbook.id === dialog.id);
+        if (dialog.kind !== 'create' && target === undefined) {
+            setWorkbookDialog(null);
+            return;
+        }
+        if (dialog.kind !== 'delete' && dialog.draft.trim() === '') {
+            setNotice('工作簿名称不能为空');
+            return;
+        }
+        setWorkbookActionPending(dialog.kind);
+        if (dialog.kind === 'delete')
+            setDeletingWorkbookId(dialog.id);
+        try {
+            if (dialog.kind === 'create') {
+                const name = dialog.draft.trim();
+                const result = await createWorkbook(name);
+                const choices = await refreshWorkbookCatalog();
+                const createdId = result.workbook?.id ?? choices.find(workbook => workbook.name === name)?.id;
+                setWorkbookDialog(null);
+                if (createdId !== undefined)
+                    await switchWorkbook(createdId);
+                setNotice(`已创建工作簿「${name}」`);
+            }
+            else if (dialog.kind === 'rename' && target !== undefined) {
+                const name = dialog.draft.trim();
+                if (name === target.name) {
+                    setWorkbookDialog(null);
+                    return;
+                }
+                const result = await renameWorkbookRequest(dialog.id, name);
+                const nextName = result.workbook?.name ?? name;
+                const choices = workbooksRef.current.map(workbook => workbook.id === dialog.id ? { ...workbook, name: nextName, updatedAt: new Date().toISOString() } : workbook);
+                workbooksRef.current = choices;
+                if (mountedRef.current) {
+                    setWorkbooks(choices);
+                    if (meta?.id === dialog.id) {
+                        setMeta(current => current === null ? current : { ...current, name: nextName });
+                        setSnapshot(current => current === null ? current : withWorkbookName(current, nextName));
+                    }
+                    setNotice(`已重命名为「${nextName}」`);
+                }
+                setWorkbookDialog(null);
+            }
+            else if (dialog.kind === 'delete' && target !== undefined) {
+                await deleteWorkbookRequest(dialog.id);
+                const choices = await refreshWorkbookCatalog();
+                if (mountedRef.current) {
+                    setWorkbooks(choices);
+                    setNotice(`已删除工作簿「${target.name}」`);
+                }
+                setWorkbookDialog(null);
+            }
+        }
+        catch (error) {
+            setStatus('error');
+            setNotice(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (mountedRef.current) {
+                setWorkbookActionPending(null);
+                setDeletingWorkbookId(null);
+            }
+        }
+    };
+    return (_jsxs("div", { className: `${styles.panel} ${standalone ? styles.standalone : ''}`, children: [_jsxs(WorkspaceTopBar, { children: [_jsx(ObjectPicker, { label: "\u5DE5\u4F5C\u7C3F", name: meta?.name ?? '', placeholder: "\u9009\u62E9\u5DE5\u4F5C\u7C3F", items: workbooks.map(workbook => ({ id: workbook.id, name: workbook.name, meta: `${workbook.sheets.length} 个 sheet` })), currentId: meta?.id, disabled: switching && workbooks.length === 0, emptyLabel: "\u6682\u65E0\u5DE5\u4F5C\u7C3F", createLabel: "\u65B0\u5EFA\u5DE5\u4F5C\u7C3F", onCreate: openCreateWorkbookDialog, onSelect: id => { void switchWorkbook(id); }, onRename: openRenameWorkbookDialog, onDelete: openDeleteWorkbookDialog }), _jsx(TopBarDivider, {}), _jsxs(TopBarGroup, { children: [meta !== null && !standalone && (_jsxs(Button, { variant: "outline", size: "sm", title: "\u5728\u6D4F\u89C8\u5668\u7A97\u53E3\u91CC\u6253\u5F00\u5F53\u524D\u5DE5\u4F5C\u7C3F", onClick: () => void fullPage.open({ src: standaloneWorkbookPath(meta.id), title: meta.name || meta.id }), children: [_jsx(ExternalLink, { size: 14, "aria-hidden": "true" }), "\u6574\u9875\u6253\u5F00"] })), _jsxs(Button, { variant: "outline", size: "sm", disabled: meta === null, onClick: () => { setHistoryOpen(true); if (meta !== null)
+                                    void loadHistory(meta.id); }, children: [_jsx(History, { size: 14, "aria-hidden": "true" }), "\u7248\u672C\u7BA1\u7406"] })] }), _jsx(TopBarDivider, {}), _jsxs(TopBarGroup, { children: [_jsx(ProjectImportMenu, { disabled: meta === null }), _jsx(ToolbarMenu, { label: "\u5BFC\u51FA", icon: _jsx(ArrowDownToLine, { size: 14, "aria-hidden": "true" }), disabled: meta === null, groups: [{
+                                        items: [
+                                            { id: 'xlsx', label: '导出 Excel', hint: '保留工作簿结构与样式', icon: _jsx(FileSpreadsheet, { size: 15, "aria-hidden": "true" }), onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-xlsx')); } },
+                                            { id: 'csv', label: '导出 CSV', hint: '导出当前工作表数据', icon: _jsx(FileText, { size: 15, "aria-hidden": "true" }), onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-csv')); } },
+                                            { id: 'json', label: '导出 JSON', hint: '完整工作簿快照', icon: _jsx(FileJson, { size: 15, "aria-hidden": "true" }), onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-json')); } },
+                                        ],
+                                    }] })] }), switching && _jsx("span", { className: styles.switchingLabel, children: "\u5207\u6362\u4E2D\u2026" }), _jsx(SaveStatus, { state: status, onRetry: () => { void reloadLatest(); }, onReload: () => { void reloadLatest(); } })] }), _jsx(Dialog, { open: workbookDialog !== null, onOpenChange: open => { if (!open && workbookActionPending === null)
+                    setWorkbookDialog(null); }, children: _jsxs(DialogContent, { children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: workbookDialog?.kind === 'create' ? '新建工作簿' : workbookDialog?.kind === 'rename' ? '重命名工作簿' : '删除工作簿' }), _jsx(DialogDescription, { children: workbookDialog?.kind === 'delete' ? '此操作会同时删除编辑历史，且无法恢复。' : '名称会显示在顶部工作簿切换器中。' })] }), workbookDialog?.kind === 'delete' ? _jsxs("p", { className: styles.dialogMessage, children: ["\u786E\u5B9A\u5220\u9664\u5DE5\u4F5C\u7C3F\u300C", workbooksRef.current.find(workbook => workbook.id === workbookDialog.id)?.name ?? '', "\u300D\u5417\uFF1F"] }) : (workbookDialog?.kind === 'create' || workbookDialog?.kind === 'rename') && _jsxs("label", { className: styles.dialogField, children: [_jsx("span", { children: "\u5DE5\u4F5C\u7C3F\u540D\u79F0" }), _jsx(Input, { autoFocus: true, value: workbookDialog.draft, onChange: event => setWorkbookDialog(current => current !== null && current.kind !== 'delete' ? { ...current, draft: event.target.value } : current), onKeyDown: event => { if (event.key === 'Enter') {
+                                        event.preventDefault();
+                                        void submitWorkbookDialog();
+                                    } if (event.key === 'Escape' && workbookActionPending === null)
+                                        setWorkbookDialog(null); } })] }), _jsxs(DialogFooter, { children: [_jsx(Button, { variant: "outline", size: "sm", disabled: workbookActionPending !== null, onClick: () => setWorkbookDialog(null), children: "\u53D6\u6D88" }), _jsx(Button, { variant: workbookDialog?.kind === 'delete' ? 'destructive' : 'default', size: "sm", disabled: workbookActionPending !== null || (workbookDialog !== null && workbookDialog.kind !== 'delete' && workbookDialog.draft.trim() === ''), onClick: () => { void submitWorkbookDialog(); }, children: workbookActionPending !== null ? '处理中…' : workbookDialog?.kind === 'delete' ? '确认删除' : workbookDialog?.kind === 'create' ? '创建工作簿' : '保存名称' })] })] }) }), _jsxs("div", { className: styles.body, children: [toast !== null && _jsx("div", { className: styles.toast, role: "status", children: toast }), notice !== null && (
+                    // A banner, not an overlay: it sits in the flex column above the
+                    // canvas and can be dismissed (GUI feedback 2026-09-19 — the old
+                    // absolute notice covered the Univer toolbar and had no close button).
+                    _jsxs("div", { className: styles.notice, role: "status", children: [_jsx("span", { className: styles.noticeMessage, children: notice }), _jsx("button", { type: "button", className: styles.noticeClose, "aria-label": "\u5173\u95ED\u63D0\u793A", title: "\u5173\u95ED", onClick: () => setNotice(null), children: _jsx(X, { size: 13, "aria-hidden": "true" }) })] })), conflicts.length > 0 && (_jsxs("div", { className: styles.conflictPanel, children: [_jsxs("div", { className: styles.conflictText, children: [_jsx("strong", { children: "\u4E09\u65B9\u5408\u5E76\u5F85\u5904\u7406" }), _jsx("span", { children: "\u51B2\u7A81\u5355\u5143\u683C\u5F53\u524D\u4FDD\u7559\u672C\u5730\u503C\u5E76\u5DF2\u9AD8\u4EAE\uFF0C\u63D0\u4EA4\u524D\u53EF\u4EE5\u7EE7\u7EED\u4FEE\u6539\u3002" }), _jsxs("small", { children: [conflicts.slice(0, 10).map(conflict => conflict.address ?? conflict.description).join('、'), conflicts.length > 10 ? ` 等 ${conflicts.length} 项` : ''] })] }), _jsxs("div", { className: styles.conflictActions, children: [_jsx("button", { type: "button", className: styles.actionButton, onClick: () => { void commitMergedSnapshot(); }, children: "\u63D0\u4EA4\u5408\u5E76\u7ED3\u679C" }), _jsx("button", { type: "button", className: styles.actionButton, onClick: () => { void reloadLatest(); }, children: "\u653E\u5F03\u672C\u5730\u4FEE\u6539" })] })] })), _jsx(VersionChrome, { open: historyOpen, onOpenChange: next => {
+                            setHistoryOpen(next);
+                            if (!next) {
+                                // Steps collapse for the next visit — except the current Version's,
+                                // which is the one being produced and reopens expanded (item 6).
+                                setExpandedHistoryVersions(headRevision === undefined ? new Set() : new Set([headRevision]));
+                            }
+                        }, artifactName: meta?.name ?? '工作簿', versionCount: namedVersionCount, headLabel: headLabel, restorableId: headVersion?.versionId, loading: historyLoading, groups: versionGroups, actions: versionActions, save: {
+                            open: saveVersionOpen,
+                            pending: saveVersionPending,
+                            disabled: meta === null,
+                            onOpenChange: setSaveVersionOpen,
+                            onConfirm: name => { void saveNamedVersion(name); },
+                        }, restore: {
+                            request: restoreRequest,
+                            pending: restorePending,
+                            onOpenChange: next => { if (!next)
+                                setRestoreRequest(null); },
+                            onConfirm: () => {
+                                const request = restoreRequest;
+                                if (request === null)
+                                    return;
+                                setRestorePending(true);
+                                void restoreHistory(request).finally(() => { setRestorePending(false); setRestoreRequest(null); });
+                            },
+                        } }), !open || snapshot === null ? (_jsxs("div", { className: styles.hint, children: [!open && _jsx("p", { children: "\u70B9\u51FB\u53F3\u4E0A\u89D2\u300CTable\u300D\u5C55\u5F00" }), open && snapshot === null && _jsx("p", { children: workbooks.length === 0 ? '暂无工作簿，请先创建一个工作簿。' : '请选择要打开的工作簿。' })] })) : (_jsxs(_Fragment, { children: [preview !== null && (_jsx("div", { className: styles.previewBar, children: _jsx(VersionInspectBar
+                                // `shown` is the Version on the canvas — the row that was
+                                // clicked — and `against` is what it is measured with, the
+                                // current content by default. The bar renders them in that
+                                // order, so the left picker is always what you are looking at.
+                                , { 
+                                    // `shown` is the Version on the canvas — the row that was
+                                    // clicked — and `against` is what it is measured with, the
+                                    // current content by default. The bar renders them in that
+                                    // order, so the left picker is always what you are looking at.
+                                    shownId: preview.versionId, ...(preview.step === null ? {} : { shownStep: preview.step }), againstId: inspectBaselineId, ...(inspectBaselineStep === undefined ? {} : { againstStep: inspectBaselineStep }), options: previewOptions, 
+                                    // Both pickers offer the same two levels: a Step carries the
+                                    // revision it produced, so "compare against the state after
+                                    // Step 3" is a measurement the diff can make. `''` is the live
+                                    // content, which has no id.
+                                    againstOptions: [
+                                        { id: '', label: CURRENT_VERSION_LABEL },
+                                        ...previewOptions,
+                                    ], onShownChange: (versionId, step) => { void previewVersion(versionId, step); }, onAgainstChange: (baselineId, baselineStep) => {
+                                        setInspectBaselineId(baselineId);
+                                        setInspectBaselineStep(baselineStep);
+                                        // Re-measure the same Version against the new side; a Step
+                                        // cursor belongs to a Step diff, so it resets.
+                                        void previewVersion(preview.versionId, undefined, baselineId, baselineStep);
+                                    }, summary: previewSummary, loading: previewLoading, onExit: exitPreview }) })), _jsx(WorkbookCanvas
+                            // The residency only rebuilds when inspect starts, ends, or a swap
+                            // failed. Switching the inspected Version keeps the Univer
+                            // instance and swaps the unit, so the grid does not flash.
+                            , { workbookData: preview === null ? snapshot : preview.snapshot, readOnly: preview !== null, decoration: previewDecoration, onDirty: scheduleSave, onPresence: schedulePresence, onSelectionChange: publishDataSheetSelection, onReady: applyPendingBridgeFocus, ref: handle => { viewHandle.current = handle; } }, preview === null ? `${viewKey}:live` : `${viewKey}:inspect-${inspectRemount}`)] }))] }), fullPage.notice] }));
+}
+/** Right-column adapter: the DSH layout owns the open/close state. */
+export function SheetPanel(_) {
+    return _jsx(WorkbookWorkspace, { open: useSheetOpen() });
+}
+function workbookName(id, workbooks) {
+    return workbooks.find(workbook => workbook.id === id)?.name ?? id;
+}