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

package/src/client/SheetPanel.tsx

@@ -0,0 +1,1934 @@
+/**
+ * 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 type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SurfaceBridgeService } from '@tita-agent/dsh-surface-bridge'
+import { Button, Input } from '@tita-agent/ui/components'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+  useFullPage,
+} from '@tita-agent/ui/overlays'
+import {
+  ArrowDownToLine,
+  ExternalLink,
+  FileJson,
+  FileSpreadsheet,
+  FileText,
+  History,
+  Save,
+  X,
+} from '@tita-agent/ui/icons'
+import {
+  ObjectPicker,
+  SaveStatus,
+  ToolbarMenu,
+  TopBarDivider,
+  TopBarGroup,
+  WorkspaceTopBar,
+} from '@tita-agent/ui/workspace'
+import { ProjectImportMenu } from './ProjectImportMenu.tsx'
+import {
+  RestoreDialog,
+  SaveVersionDialog,
+  VersionInspectBar,
+  VersionManager,
+  autoVersionName,
+  CURRENT_VERSION_LABEL,
+  restoreVersionSummary,
+  type VersionManagerActions,
+  type VersionManagerEntry,
+  type VersionManagerGroup,
+  type VersionRestoreIntent,
+} from '@tita-agent/ui/versions'
+import '@tita-agent/ui/styles.css'
+import { VERSION_MAX_STEPS, undoTargetOf, versionTimeline } from '#contracts'
+import type { WorkbookFocusRange, WorkbookLocalChange, WorkbookOperation, WorkbookSummary, WorkbookPresence, WorkbookPresencePayload, WorkbookSelectionRange, WorkbookChange } from '../types.ts'
+import { cloneSnapshot } from '../contract/snapshots.ts'
+import {
+  cachedWorkbookProjection,
+  forgetWorkbookProjection,
+  lastSelectedWorkbookId,
+  readVersionSession,
+  rememberVersionSession,
+  rememberWorkbook,
+  rememberWorkbookProjection,
+  useSheetOpen,
+  type VersionSession,
+} from './store.ts'
+import { WorkbookCanvas, type WorkbookCanvasHandle } from './univer/WorkbookCanvas.tsx'
+import { DATA_SHEET_SURFACE_ID, dataSheetFocusTargetOf, projectDataSheetSelection } from './surface-context.ts'
+import { registerDataSheetFocusHandler } from './surface-control.ts'
+import { formatHistoryTime, historyVersionsFromEntries, toVersionManagerEntry } from './versions/records.ts'
+import { VersionChrome } from './versions/VersionChrome.tsx'
+import {
+  baselineRevisionOf,
+  inspectOptionsOf,
+  inspectorSummaryOf,
+  previewDecorationOf,
+  type VersionRestoreRequest,
+  type WorkbookPreviewState,
+} from './versions/inspect.ts'
+import { toDecoration } from './versions/preview-decoration.ts'
+import { canApplyRemoteWhileEditing, coalesceLocalChanges, withWorkbookName } from './persistence/changes.ts'
+import { createOwnOpLog, nextUserVersionId } from './persistence/ids.ts'
+import {
+  collaborationStreamPath,
+  dataSheetSessionId,
+  standaloneWorkbookPath,
+  dataSheetClientPath,
+  createWorkbook,
+  deleteWorkbook as deleteWorkbookRequest,
+  fetchChanges,
+  fetchHistory,
+  fetchHistorySnapshot,
+  fetchHistoryDiff,
+  fetchWorkbook,
+  fetchWorkbooks,
+  HttpStatusError,
+  RevisionConflictError,
+  rollbackWorkbook,
+  saveOperationChanges,
+  saveSnapshot,
+  publishPresence,
+  renameWorkbook as renameWorkbookRequest,
+  type SaveResult,
+} from './transport/workbookApi.ts'
+import {
+  mergeWorkbookSnapshots,
+  applyIncrementalChangesToSnapshot,
+  applyIncrementalOperationsToSnapshot,
+  stripConflictMarkers,
+  type MergeConflict,
+} from './persistence/merge.ts'
+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
+
+type PanelProps = PropsRuntime<'details'>
+
+export interface WorkbookWorkspaceProps {
+  /** Whether the workspace is live. The embedded pane keeps this true even while parked. */
+  open: boolean
+  /**
+   * Whether the workspace is on screen. Defaults to `open`.
+   *
+   * The resident workspace outlives the pane, so `open` cannot answer this; the
+   * few behaviours that must follow real visibility (the window-level save
+   * shortcut) read this instead.
+   */
+  visible?: boolean
+  /** Standalone mode removes the in-panel affordances that only make sense in DSH. */
+  standalone?: boolean
+  /** Optional workbook to load first; embedded mode otherwise requires explicit selection. */
+  initialWorkbookId?: string
+  /** Shared DSH composer context bridge; absent in standalone pages. */
+  bridge?: SurfaceBridgeService
+}
+
+type WorkbookEnvelope = import('./transport/workbookApi.ts').WorkbookEnvelope
+type ChangesEnvelope = import('./transport/workbookApi.ts').ChangesEnvelope
+type CollaborationReadyEnvelope = ChangesEnvelope & { workbookId?: string }
+type HistoryEntry = import('./transport/workbookApi.ts').HistoryEntry
+type HistoryVersion = import('../types.ts').WorkbookHistoryVersion
+
+type SheetSaveState = 'loading' | 'saved' | 'saving' | 'error' | 'conflict'
+
+type WorkbookDialog =
+  | { kind: 'create'; draft: string }
+  | { kind: 'rename'; id: string; draft: string }
+  | { kind: 'delete'; id: string }
+
+/** Shared workbook workspace used by both the DSH details panel and the standalone page. */
+export function WorkbookWorkspace({ open, visible = open, standalone = false, initialWorkbookId, bridge }: WorkbookWorkspaceProps) {
+  /**
+   * 「整页打开」的出口：浏览器里是新标签页，桌面端铺成应用内的一层。桌面壳不允许
+   * 插件开新窗口（`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 = ((): string => initialWorkbookId?.trim() || lastSelectedWorkbookId())()
+  const restored = cachedWorkbookProjection(restoreTarget)
+  const [snapshot, setSnapshot] = useState<object | null>(restored?.snapshot ?? null)
+  const [meta, setMeta] = useState<{ id: string; name: string } | null>(restored === null ? null : { id: restored.id, name: restored.name })
+  const [workbooks, setWorkbooks] = useState<WorkbookSummary[]>([])
+  const [revision, setRevision] = useState(restored?.revision ?? 0)
+  const [viewKey, setViewKey] = useState(0)
+  const [status, setStatus] = useState<SheetSaveState>('loading')
+  const [switching, setSwitching] = useState(false)
+  const [conflicts, setConflicts] = useState<MergeConflict[]>([])
+  const [notice, setNotice] = useState<string | null>(null)
+  const [historyOpen, setHistoryOpen] = useState(false)
+  const [historyLoading, setHistoryLoading] = useState(false)
+  const [historyVersions, setHistoryVersions] = useState<HistoryVersion[]>([])
+  const [expandedHistoryVersions, setExpandedHistoryVersions] = useState<Set<number>>(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<WorkbookPreviewState | null>(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<number | undefined>(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<VersionRestoreRequest | null>(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<WorkbookPresence[]>([])
+  const [toast, setToast] = useState<string | null>(null)
+  const [workbookDialog, setWorkbookDialog] = useState<WorkbookDialog | null>(null)
+  const [workbookActionPending, setWorkbookActionPending] = useState<'create' | 'rename' | 'delete' | null>(null)
+  const [deletingWorkbookId, setDeletingWorkbookId] = useState<string | null>(null)
+  const viewHandle = useRef<WorkbookCanvasHandle | null>(null)
+  const selectionRevisionRef = useRef(0)
+  const selectionSignatureRef = useRef('')
+  const pendingBridgeFocusRef = useRef<(WorkbookFocusRange & { workbookId: string }) | null>(null)
+  const bridgeFocusAttemptRef = useRef<string | null>(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<WorkbookPreviewState | null>(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<VersionManagerEntry[]>(
+    () => versionTimeline(historyEntries),
+    [historyEntries],
+  )
+
+  /** One flat list; `label: ''` renders it without a section header. */
+  const versionGroups = useMemo<VersionManagerGroup[]>(
+    () => (timelineEntries.length === 0 ? [] : [{ id: 'timeline', label: '', entries: timelineEntries }]),
+    [timelineEntries],
+  )
+
+  /** 「撤销这次改动」 on an Agent Version targets the Version before it (D5). */
+  const undoTargetFor = useCallback((entry: VersionManagerEntry) => {
+    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<number | null>(null)
+  const dirtyRef = useRef(false)
+  const revisionRef = useRef(restored?.revision ?? 0)
+  const publishDataSheetSelection = useCallback((ranges: readonly WorkbookSelectionRange[]): void => {
+    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<WorkbookSummary[]>([])
+  // 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<string | null>(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<object | null>(restored?.snapshot ?? null)
+  const metaRef = useRef<{ id: string; name: string } | null>(restored === null ? null : { id: restored.id, name: restored.name })
+  const savingRef = useRef(false)
+  const serverRevisionRef = useRef(restored?.revision ?? 0)
+  const remoteOperationsRef = useRef(new Map<number, WorkbookOperation>())
+  const remoteSnapshotPendingRef = useRef(false)
+  const drainingRemoteRef = useRef(false)
+  const editGenerationRef = useRef(0)
+  const baselineRef = useRef<object | null>(restored === null ? null : cloneSnapshot(restored.snapshot))
+  const conflictsRef = useRef<MergeConflict[]>([])
+  const conflictStyleMapRef = useRef<Record<string, string | null>>({})
+  const pendingLocalChangesRef = useRef<WorkbookLocalChange[]>([])
+  /**
+   * 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<VersionSession | null>(null)
+  const sessionWorkbookIdRef = useRef<string>('')
+  const setSession = (next: VersionSession | null): void => {
+    sessionRef.current = next
+    rememberVersionSession(sessionWorkbookIdRef.current, next)
+  }
+  const seedSession = (workbookId: string): void => {
+    sessionWorkbookIdRef.current = workbookId
+    sessionRef.current = readVersionSession(workbookId)
+  }
+  const sessionVersionId = (): string | null => sessionRef.current?.versionId ?? null
+  const sessionStepCount = (): number => 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: SaveResult | null, fallbackVersionId: string | null, stepCount: number): void => {
+    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<Promise<void> | null>(null)
+  const flushPendingSaveRef = useRef<(() => Promise<void>) | null>(null)
+  const presenceTimerRef = useRef<number | null>(null)
+  const pendingPresenceRef = useRef<WorkbookPresencePayload | null>(null)
+  const toastTimerRef = useRef<number | null>(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: number): void => {
+    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: string): string => ownOpsRef.current.next(id)
+
+  const setMergeConflicts = (next: MergeConflict[], styleMap: Record<string, string | null> = {}): void => {
+    conflictsRef.current = next
+    conflictStyleMapRef.current = styleMap
+    if (mountedRef.current) setConflicts(next)
+  }
+
+  const schedulePresence = (next: WorkbookPresencePayload): void => {
+    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(() => { /* presence is best-effort */ })
+    }, 120)
+  }
+
+  const showToast = (message: string, durationMs = 2200): void => {
+    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 = (): void => { showToast('该状态无法编辑', 2000) }
+
+  const loadHistory = async (id: string): Promise<void> => {
+    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: string, baselineStep?: number): number => {
+    if (baselineId === '') return revisionRef.current
+    return baselineRevisionOf(
+      timelineEntries.find(candidate => candidate.id === baselineId),
+      revisionRef.current,
+      baselineStep,
+    )
+  }, [timelineEntries])
+
+  const previewVersion = useCallback(async (entryId: string, step?: number, baselineOverride?: string, baselineStep?: number): Promise<void> => {
+    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: WorkbookChange[] = value.changes ?? []
+      let changesUnavailable = false
+      let changesTruncated = value.truncated === true
+      let changesSide: 'before' | 'after' = '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((): void => {
+    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: VersionManagerEntry, intent: VersionRestoreIntent): void => {
+    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: VersionManagerActions = {
+    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: { revision: number; label: string; summary: string; mode: 'restore' | 'undo' }): Promise<void> => {
+    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 = (): void => {
+      setHistoryOpen(true)
+      void loadHistory(meta.id)
+    }
+    const onCommandError = (event: Event): void => {
+      const message = (event as CustomEvent<{ message?: string }>).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: string, remount: boolean): Promise<void> => {
+    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: string, snapshotData: object, revision: number): void => {
+    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 (): Promise<void> => {
+      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: string, localSnapshot: object, retry = 0): Promise<SaveResult | null> => {
+    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 (): Promise<void> => {
+    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 as object, 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 as object)
+        } 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: WorkbookLocalChange[], id: string, revision: number): Promise<void> => {
+    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?: string): Promise<void> => {
+    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' as const : 'open' as const
+    const savedGeneration = editGenerationRef.current
+    let snap: object | null = null
+    if (forceSnapshot) {
+      const value = viewHandle.current?.save()
+      snap = value !== undefined && value !== null && typeof value === 'object' ? value as object : 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: 'open' | 'final' = 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' as const : 'open' as const
+        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) as object)
+        } 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(() => { /* status is already shown by savePendingUserChanges */ })
+      }
+    }
+  }
+
+  const scheduleSave = (change?: WorkbookLocalChange): void => {
+    // 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(() => { /* status is already shown by savePendingUserChanges */ })
+    }, 0)
+  }
+
+  const flushPendingSave = async (): Promise<void> => {
+    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: string): Promise<void> => {
+    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 as object, 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 as object, 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: string, snapshotData: object, baseRevision: number, opId: string): Promise<SaveResult | null> => {
+    // 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: KeyboardEvent): void => {
+      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(() => { /* the next visit revalidates and retries */ })
+  }, [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 (): Promise<void> => {
+    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: string): Promise<void> => {
+    if (id.length === 0 || id === meta?.id || switching) return
+    setSwitching(true)
+    try {
+      await flushPendingSave()
+      let envelope: WorkbookEnvelope
+      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((): void => {
+    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: string): void => {
+    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 = (): void => {
+      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(() => { /* teardown cannot show a toast */ })
+      }
+    }
+  }, [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 = (): void => {
+      if (!dirtyRef.current || conflictsRef.current.length > 0 || savingRef.current) return
+      void savePendingUserChanges(meta?.id ?? initialWorkbookId).catch(() => { /* page is closing */ })
+    }
+    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: Event): void => {
+      const detail = (event as CustomEvent<{ snapshot?: object; filename?: string }>).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: Event): void => {
+      const message = (event as CustomEvent<{ message?: string }>).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: EventSource | null = null
+    let reconnectTimer: number | null = null
+
+    const enqueue = (changes: ChangesEnvelope): void => {
+      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 = (): void => {
+      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 as MessageEvent<string>).data) as CollaborationReadyEnvelope
+          enqueue(envelope)
+        } catch { /* the polling fallback repairs malformed events */ }
+      })
+      source.addEventListener('operation', event => {
+        try {
+          const value = JSON.parse((event as MessageEvent<string>).data) as { operation?: WorkbookOperation }
+          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 as MessageEvent<string>).data) as { presence?: WorkbookPresence }
+          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 (): Promise<void> => {
+      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 (): Promise<void> => {
+    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 (): Promise<WorkbookSummary[]> => {
+    const choices = (await fetchWorkbooks()).workbooks ?? []
+    workbooksRef.current = choices
+    if (mountedRef.current) setWorkbooks(choices)
+    return choices
+  }
+
+  const openCreateWorkbookDialog = (): void => {
+    if (workbookActionPending !== null) return
+    setWorkbookDialog({ kind: 'create', draft: `工作簿 ${workbooksRef.current.length + 1}` })
+  }
+
+  const openRenameWorkbookDialog = (id: string): void => {
+    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: string): void => {
+    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 (): Promise<void> => {
+    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 (
+    <div className={`${styles.panel} ${standalone ? styles.standalone : ''}`}>
+      <WorkspaceTopBar>
+        <ObjectPicker
+          label="工作簿"
+          name={meta?.name ?? ''}
+          placeholder="选择工作簿"
+          items={workbooks.map(workbook => ({ id: workbook.id, name: workbook.name, meta: `${workbook.sheets.length} 个 sheet` }))}
+          currentId={meta?.id}
+          disabled={switching && workbooks.length === 0}
+          emptyLabel="暂无工作簿"
+          createLabel="新建工作簿"
+          onCreate={openCreateWorkbookDialog}
+          onSelect={id => { void switchWorkbook(id) }}
+          onRename={openRenameWorkbookDialog}
+          onDelete={openDeleteWorkbookDialog}
+        />
+        <TopBarDivider />
+        <TopBarGroup>
+          {meta !== null && !standalone && (
+            <Button
+              variant="outline"
+              size="sm"
+              title="在浏览器窗口里打开当前工作簿"
+              onClick={() => void fullPage.open({ src: standaloneWorkbookPath(meta.id), title: meta.name || meta.id })}
+            >
+              <ExternalLink size={14} aria-hidden="true" />整页打开
+            </Button>
+          )}
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={meta === null}
+            onClick={() => { setHistoryOpen(true); if (meta !== null) void loadHistory(meta.id) }}
+          >
+            <History size={14} aria-hidden="true" />版本管理
+          </Button>
+        </TopBarGroup>
+        <TopBarDivider />
+        <TopBarGroup>
+          {/* The menu and the project file chooser behind it live together in
+              their own module; the panel only declares where it sits. */}
+          <ProjectImportMenu disabled={meta === null} />
+          <ToolbarMenu
+            label="导出"
+            icon={<ArrowDownToLine size={14} aria-hidden="true" />}
+            disabled={meta === null}
+            groups={[{
+              items: [
+                { id: 'xlsx', label: '导出 Excel', hint: '保留工作簿结构与样式', icon: <FileSpreadsheet size={15} aria-hidden="true" />, onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-xlsx')) } },
+                { id: 'csv', label: '导出 CSV', hint: '导出当前工作表数据', icon: <FileText size={15} aria-hidden="true" />, onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-csv')) } },
+                { id: 'json', label: '导出 JSON', hint: '完整工作簿快照', icon: <FileJson size={15} aria-hidden="true" />, onSelect: () => { window.dispatchEvent(new CustomEvent('data-sheet:request-export-json')) } },
+              ],
+            }]}
+          />
+        </TopBarGroup>
+        {switching && <span className={styles.switchingLabel}>切换中…</span>}
+        <SaveStatus state={status} onRetry={() => { void reloadLatest() }} onReload={() => { void reloadLatest() }} />
+      </WorkspaceTopBar>
+      <Dialog open={workbookDialog !== null} onOpenChange={open => { if (!open && workbookActionPending === null) setWorkbookDialog(null) }}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{workbookDialog?.kind === 'create' ? '新建工作簿' : workbookDialog?.kind === 'rename' ? '重命名工作簿' : '删除工作簿'}</DialogTitle>
+            <DialogDescription>{workbookDialog?.kind === 'delete' ? '此操作会同时删除编辑历史，且无法恢复。' : '名称会显示在顶部工作簿切换器中。'}</DialogDescription>
+          </DialogHeader>
+          {workbookDialog?.kind === 'delete' ? <p className={styles.dialogMessage}>确定删除工作簿「{workbooksRef.current.find(workbook => workbook.id === workbookDialog.id)?.name ?? ''}」吗？</p> : (workbookDialog?.kind === 'create' || workbookDialog?.kind === 'rename') && <label className={styles.dialogField}><span>工作簿名称</span><Input autoFocus 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) }} /></label>}
+          <DialogFooter>
+            <Button variant="outline" size="sm" disabled={workbookActionPending !== null} onClick={() => setWorkbookDialog(null)}>取消</Button>
+            <Button variant={workbookDialog?.kind === 'delete' ? 'destructive' : 'default'} size="sm" disabled={workbookActionPending !== null || (workbookDialog !== null && workbookDialog.kind !== 'delete' && workbookDialog.draft.trim() === '')} onClick={() => { void submitWorkbookDialog() }}>{workbookActionPending !== null ? '处理中…' : workbookDialog?.kind === 'delete' ? '确认删除' : workbookDialog?.kind === 'create' ? '创建工作簿' : '保存名称'}</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <div className={styles.body}>
+        {toast !== null && <div className={styles.toast} role="status">{toast}</div>}
+        {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).
+          <div className={styles.notice} role="status">
+            <span className={styles.noticeMessage}>{notice}</span>
+            <button
+              type="button"
+              className={styles.noticeClose}
+              aria-label="关闭提示"
+              title="关闭"
+              onClick={() => setNotice(null)}
+            >
+              <X size={13} aria-hidden="true" />
+            </button>
+          </div>
+        )}
+        {conflicts.length > 0 && (
+          <div className={styles.conflictPanel}>
+            <div className={styles.conflictText}>
+              <strong>三方合并待处理</strong>
+              <span>冲突单元格当前保留本地值并已高亮，提交前可以继续修改。</span>
+              <small>{conflicts.slice(0, 10).map(conflict => conflict.address ?? conflict.description).join('、')}{conflicts.length > 10 ? ` 等 ${conflicts.length} 项` : ''}</small>
+            </div>
+            <div className={styles.conflictActions}>
+              <button type="button" className={styles.actionButton} onClick={() => { void commitMergedSnapshot() }}>提交合并结果</button>
+              <button type="button" className={styles.actionButton} onClick={() => { void reloadLatest() }}>放弃本地修改</button>
+            </div>
+          </div>
+        )}
+        <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 ? (
+          <div className={styles.hint}>
+            {!open && <p>点击右上角「Table」展开</p>}
+            {open && snapshot === null && <p>{workbooks.length === 0 ? '暂无工作簿，请先创建一个工作簿。' : '请选择要打开的工作簿。'}</p>}
+          </div>
+        ) : (
+          <>
+            {preview !== null && (
+              <div className={styles.previewBar}>
+                <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.
+                  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}
+                />
+              </div>
+            )}
+            <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.
+              key={preview === null ? `${viewKey}:live` : `${viewKey}:inspect-${inspectRemount}`}
+              workbookData={preview === null ? snapshot : preview.snapshot}
+              readOnly={preview !== null}
+              decoration={previewDecoration}
+              onDirty={scheduleSave}
+              onPresence={schedulePresence}
+              onSelectionChange={publishDataSheetSelection}
+              onReady={applyPendingBridgeFocus}
+              ref={handle => { viewHandle.current = handle }}
+            />
+          </>
+        )}
+      </div>
+      {/* 开不了新窗口时那一句。挂在组件树里只是为了有个宿主 —— 它由 Portal 落到 body，
+          z-index 高过抽屉与对话框（2026-10-05 撤掉应用内全屏页之后新增）。 */}
+      {fullPage.notice}
+    </div>
+  )
+}
+
+/** Right-column adapter: the DSH layout owns the open/close state. */
+export function SheetPanel(_: PanelProps) {
+  return <WorkbookWorkspace open={useSheetOpen()} />
+}
+
+function workbookName(id: string, workbooks: WorkbookSummary[]): string {
+  return workbooks.find(workbook => workbook.id === id)?.name ?? id
+}