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

package/src/client/univer/WorkbookCanvas.tsx

@@ -0,0 +1,128 @@
+/**
+ * Shared Univer canvas used by the embedded Datasheet panel and the
+ * standalone workbook page. The workspace owns persistence and sync; this
+ * component owns only Univer residency and its imperative editing surface.
+ */
+
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react'
+import { mountWorkbook, type WorkbookDecoration } from './loader.ts'
+import type { WorkbookFocusRange, WorkbookLocalChange, WorkbookOperation, WorkbookPresencePayload, WorkbookSelectionRange } from '../../types.ts'
+import styles from './WorkbookView.module.css'
+
+export interface WorkbookCanvasProps {
+  workbookData: object
+  /**
+   * Preview residency (docs/issue/0002 PRD v3.2 §7.2): the canvas is showing a past
+   * Version rather than live content, so it is mounted with Univer's editable
+   * permission off and its mutations are never reported as changes. The caller
+   * owns the preview state; this component only refuses to fork a Version.
+   */
+  readOnly?: boolean
+  /**
+   * Diff overlay for a preview residency: the cells that differ from the
+   * baseline, painted by the engine at mount (PRD v3.3 §7.2). Part of the
+   * residency, not a live API — a Step jump remounts the canvas, so a stale
+   * highlight cannot survive it.
+   */
+  decoration?: WorkbookDecoration
+  onDirty?: (change?: WorkbookLocalChange) => void
+  onPresence?: (presence: WorkbookPresencePayload) => void
+  onSelectionChange?: (ranges: readonly WorkbookSelectionRange[]) => void
+  onReady?: () => void
+}
+
+export interface WorkbookCanvasHandle {
+  save(): unknown
+  applyOperation(operation: WorkbookOperation): Promise<void>
+  focusRange(range: WorkbookFocusRange): boolean
+  /**
+   * Show a different workbook in the same residency. Returns false when the
+   * engine could not swap, so the caller can fall back to a remount.
+   */
+  swapWorkbook(next: object, decoration?: WorkbookDecoration): boolean
+}
+
+/** Resident workbook canvas shared by embedded and standalone workspaces. */
+export const WorkbookCanvas = forwardRef<WorkbookCanvasHandle, WorkbookCanvasProps>(
+  function WorkbookCanvas({ workbookData, readOnly = false, decoration, onDirty, onPresence, onSelectionChange, onReady }, ref) {
+    const containerRef = useRef<HTMLDivElement>(null)
+    const handleRef = useRef<WorkbookCanvasHandle | null>(null)
+    const [ready, setReady] = useState(false)
+    const [failed, setFailed] = useState(false)
+    // Read through a ref so the mount effect stays keyed on the residency
+    // itself: `workbookData`/`readOnly` are fixed for a residency's lifetime,
+    // and the caller switches residency by changing the React `key`.
+    const readOnlyRef = useRef(readOnly)
+    readOnlyRef.current = readOnly
+    const decorationRef = useRef(decoration)
+    decorationRef.current = decoration
+    const selectionChangeRef = useRef(onSelectionChange)
+    selectionChangeRef.current = onSelectionChange
+    const readyRef = useRef(onReady)
+    readyRef.current = onReady
+
+    useEffect(() => {
+      if (handleRef.current !== null) return
+      const element = containerRef.current
+      if (element === null) return
+      let disposed = false
+      let mounted: Awaited<ReturnType<typeof mountWorkbook>> | null = null
+      const readOnlyMount = readOnlyRef.current
+      void (async () => {
+        await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+        if (disposed) return
+        // Univer emits initialization/layout mutations while createUnit is
+        // still mounting. They describe the initial projection, not a user
+        // edit; forwarding them would mark the workbook dirty immediately and
+        // attempt a large snapshot save before the canvas is ready.
+        const mount = await mountWorkbook(element, workbookData, change => {
+          if (mounted !== null && !readOnlyMount) onDirty?.(change)
+        }, presence => {
+          if (mounted !== null && !readOnlyMount) onPresence?.(presence)
+        }, { readOnly: readOnlyMount, ...(decorationRef.current === undefined ? {} : { decoration: decorationRef.current }) }, ranges => {
+          if (mounted !== null && !readOnlyMount) selectionChangeRef.current?.(ranges)
+        })
+        mounted = mount
+        if (disposed) {
+          mount.dispose()
+          return
+        }
+        handleRef.current = {
+          save: () => mount.save(),
+          applyOperation: operation => mount.applyOperation(operation),
+          focusRange: range => mount.focusRange(range),
+          swapWorkbook: (next, nextDecoration) => mount.swapWorkbook(next, nextDecoration === undefined ? {} : { decoration: nextDecoration }),
+        }
+        setReady(true)
+        readyRef.current?.()
+      })().catch(() => {
+        if (!disposed) setFailed(true)
+      })
+      return () => {
+        disposed = true
+        mounted?.dispose()
+        mounted = null
+        handleRef.current = null
+      }
+      // Workbook data is fixed for the residency's lifetime.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    useImperativeHandle(ref, () => ({
+      save: () => (handleRef.current?.save() ?? null) as unknown,
+      applyOperation: async operation => { await handleRef.current?.applyOperation(operation) },
+      focusRange: range => handleRef.current?.focusRange(range) ?? false,
+      swapWorkbook: (next, nextDecoration) => handleRef.current?.swapWorkbook(next, nextDecoration) ?? false,
+    }))
+
+    return (
+      <div className={styles.view}>
+        <div className={styles.body}>
+          {!ready && !failed && <div className={styles.hint}>表格加载中…</div>}
+          {failed && <div className={styles.hint}>表格渲染失败</div>}
+          <div ref={containerRef} className={styles.univer} />
+        </div>
+      </div>
+    )
+  },
+)

package/src/client/univer/WorkbookView.module.css

@@ -0,0 +1,30 @@
+.view {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 320px;
+  border: 0;
+  border-radius: 0;
+  overflow: hidden;
+  background: var(--tita-surface);
+}
+
+.body {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+}
+
+.hint {
+  padding: 32px 20px;
+  font-size: 13px;
+  color: var(--tita-ink-muted);
+  text-align: center;
+}
+
+.univer {
+  position: absolute;
+  inset: 0;
+  height: 100%;
+  width: 100%;
+}

package/src/client/univer/WorkbookView.tsx

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

package/src/client/univer/loader.ts

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

package/src/client/univer/react-dom-client.d.ts

@@ -0,0 +1,10 @@
+declare module 'react-dom/client' {
+  import type { ReactNode } from 'react'
+
+  interface Root {
+    render(children: ReactNode): void
+    unmount(): void
+  }
+
+  export function createRoot(container: Element | DocumentFragment): Root
+}

package/src/client/univer/standalone-entry.tsx

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

package/src/client/univer/standalone.css

@@ -0,0 +1,12 @@
+html,
+body,
+#data-sheet-workbook-root {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  overflow: hidden;
+}
+
+body {
+  background: var(--tita-canvas);
+}

package/src/client/univer/univer-locales.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Ambient declarations for the sheets preset family's `lib/es` runtime
+ * modules (index + locale packs): the published packages ship no sibling
+ * declarations next to the runtime files. Mirrors the typed counterparts —
+ * the preset factory signature (index modules) and the default locale object.
+ * @module dsh-data-table/client/univer-locales
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- ambient shim for the runtime-only subpath (IPreset is not exported).
+type PresetFactory = (config?: unknown) => any
+
+declare module '@univerjs/presets/lib/es/preset-sheets-core/index.js' {
+  export const UniverSheetsCorePreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-filter/index.js' {
+  export const UniverSheetsFilterPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-sort/index.js' {
+  export const UniverSheetsSortPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-find-replace/index.js' {
+  export const UniverSheetsFindReplacePreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-conditional-formatting/index.js' {
+  export const UniverSheetsConditionalFormattingPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-data-validation/index.js' {
+  export const UniverSheetsDataValidationPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-drawing/index.js' {
+  export const UniverSheetsDrawingPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-hyper-link/index.js' {
+  export const UniverSheetsHyperLinkPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-note/index.js' {
+  export const UniverSheetsNotePreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-thread-comment/index.js' {
+  export const UniverSheetsThreadCommentPreset: PresetFactory
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-table/index.js' {
+  export const UniverSheetsTablePreset: PresetFactory
+}
+
+declare module '@univerjs/presets/lib/es/preset-sheets-core/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-filter/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-sort/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-find-replace/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-conditional-formatting/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-data-validation/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-drawing/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-hyper-link/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-note/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-thread-comment/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}
+declare module '@univerjs/presets/lib/es/preset-sheets-table/locales/*.js' {
+  const locale: Record<string, unknown>
+  export default locale
+}

package/src/client/univer/univer-modules.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Ambient types for the deep Univer preset entry. The preset factory is only
+ * exported from the es build subpath (the npm exports map types live at a
+ * different subpath), so this standalone declaration types the runtime import
+ * in `client/univer/loader.ts`. Must stay free of top-level imports to remain an ambient
+ * module declaration rather than an augmentation.
+ * @module dsh-data-table/client/univer-modules
+ */
+
+declare module '@univerjs/presets/lib/es/preset-sheets-core/index.js' {
+  import type { Plugin, PluginCtor } from '@univerjs/core'
+
+  export interface UniverSheetsCorePresetOptions {
+    container?: HTMLElement
+    header?: boolean
+    toolbar?: boolean
+    formulaBar?: boolean
+    statusBarStatistic?: boolean
+    footer?: boolean
+    contextMenu?: boolean
+    disableAutoFocus?: boolean
+  }
+  export function UniverSheetsCorePreset(
+    config?: Partial<UniverSheetsCorePresetOptions>,
+  ): { plugins: Array<PluginCtor<Plugin> | [PluginCtor<Plugin>, unknown]> }
+}

package/src/client/versions/VersionChrome.tsx

@@ -0,0 +1,114 @@
+/**
+ * The version drawer and the two dialogs that answer from it (docs/issue/0022 P5).
+ *
+ * This is the chrome half of the history surface: `records.ts` turns a stored
+ * Version into the row the list draws, `inspect.ts` produces what the comparison
+ * bar needs, and this assembles the Drawer, the 保存版本 dialog and the
+ * 恢复/撤销 confirmation out of them. It was inline in `SheetPanel.tsx`, which is
+ * pinned at its size for a reason — the panel's job is the canvas and the wire,
+ * and the copy and structure of the history UI are not part of that.
+ */
+import { Button } from '@tita-agent/ui/components'
+import {
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+} from '@tita-agent/ui/overlays'
+import { Save } from '@tita-agent/ui/icons'
+import {
+  RestoreDialog,
+  SaveVersionDialog,
+  VersionManager,
+  type VersionManagerActions,
+  type VersionManagerGroup,
+} from '@tita-agent/ui/versions'
+import type { VersionRestoreRequest } from './inspect.ts'
+
+export interface VersionChromeProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Name of the artifact, for the drawer's header line. */
+  artifactName: string
+  /** How many Versions the list holds, and when the newest one landed. */
+  versionCount: number
+  headLabel: string | undefined
+  /** The Version the canvas would restore, or undo, to. */
+  restorableId: string | undefined
+  loading: boolean
+  groups: VersionManagerGroup[]
+  actions: VersionManagerActions
+  save: {
+    open: boolean
+    pending: boolean
+    /** True while no artifact is open: there is nothing to name. */
+    disabled: boolean
+    onOpenChange: (open: boolean) => void
+    onConfirm: (name: string) => void
+  }
+  restore: {
+    /** The pending confirmation, or null when the dialog is closed. */
+    request: VersionRestoreRequest | null
+    pending: boolean
+    onOpenChange: (open: boolean) => void
+    onConfirm: () => void
+  }
+}
+
+/** Drawer, 保存版本 dialog and 恢复 confirmation, as one piece of chrome. */
+export function VersionChrome({
+  open,
+  onOpenChange,
+  artifactName,
+  versionCount,
+  headLabel,
+  restorableId,
+  loading,
+  groups,
+  actions,
+  save,
+  restore,
+}: VersionChromeProps): React.ReactElement {
+  return (
+    <>
+      <Drawer open={open} onOpenChange={onOpenChange}>
+        <DrawerContent aria-label="版本管理">
+          <DrawerHeader>
+            <div>
+              <DrawerTitle>版本管理</DrawerTitle>
+              <DrawerDescription>
+                {versionCount === 0
+                  ? `${artifactName} · 还没有版本`
+                  : `${artifactName} · ${versionCount} 个版本 · 最近保存 ${headLabel ?? ''}`}
+              </DrawerDescription>
+            </div>
+            <Button variant="outline" size="sm" disabled={save.disabled} onClick={() => save.onOpenChange(true)}>
+              <Save size={14} aria-hidden="true" />保存版本
+            </Button>
+          </DrawerHeader>
+          <DrawerBody>
+            <VersionManager loading={loading} groups={groups} actions={{ ...actions, restorableId }} />
+          </DrawerBody>
+        </DrawerContent>
+      </Drawer>
+      <SaveVersionDialog
+        open={save.open}
+        onOpenChange={save.onOpenChange}
+        pending={save.pending}
+        onConfirm={save.onConfirm}
+      />
+      <RestoreDialog
+        open={restore.request !== null}
+        onOpenChange={restore.onOpenChange}
+        targetLabel={restore.request?.label ?? ''}
+        {...(restore.request?.summary === undefined ? {} : { targetSummary: restore.request.summary })}
+        {...(restore.request === null ? {} : { mode: restore.request.mode })}
+        artifactLabel="工作簿内容"
+        pending={restore.pending}
+        onConfirm={restore.onConfirm}
+      />
+    </>
+  )
+}

package/src/client/versions/inspect.ts

@@ -0,0 +1,138 @@
+/**
+ * The read-only comparison surface, as view models (docs/issue/0022 P5).
+ *
+ * `records.ts` translates a stored Version into the row the drawer draws; this
+ * takes that row — or a fetched diff — and produces the things the *inspect*
+ * half needs: the two pickers' options, the canvas overlay, the counts in the
+ * bar, and the revision a baseline id addresses. All of it is pure, which is the
+ * point: the panel is 1800 lines of ref-mutating effects, and each of these was
+ * a `useMemo` body buried in the middle of it.
+ */
+import { versionChangeDirection } from '#contracts'
+import {
+  versionOptionLabel,
+  versionStepOptionLabel,
+  type VersionInspectOption,
+  type VersionInspectorSummary,
+  type VersionManagerEntry,
+} from '@tita-agent/ui/versions'
+import type { WorkbookChange } from '../../types.ts'
+import type { WorkbookDecoration } from '../univer/loader.ts'
+import { toDecoration } from './preview-decoration.ts'
+
+/**
+ * One preview residency (docs/issue/0002 PRD v3.2 §7.2). `step` is part of the
+ * canvas's React `key` so replaying a Step of the same Version remounts it;
+ * `snapshot` is the content the canvas renders read-only.
+ */
+export interface WorkbookPreviewState {
+  versionId: string
+  revision: number
+  /** Rebuilt content state; the canvas renders exactly this. */
+  snapshot: object
+  /** Step index when the preview is a Step replay rather than the Version end. */
+  step: number | null
+  /**
+   * What is on screen vs what it is compared against: a Step against the state
+   * before it, a Version against the newer one it followed. Drives the canvas
+   * overlay so the reader does not have to find the changed cells (v3.3 §7.2).
+   */
+  changes: WorkbookChange[]
+  /**
+   * Which end of the measured range the canvas is showing, so only changes the
+   * reader can actually see get tinted.
+   */
+  changesSide: 'before' | 'after'
+  /** True when the changes could not be rebuilt (compressed history). */
+  changesUnavailable?: boolean
+  /** True when the diff stopped at the server's limit, so the counts are a floor. */
+  changesTruncated?: boolean
+}
+
+/**
+ * The overlay for a residency: identical to what an in-place swap painted, so a
+ * remount and a swap show exactly the same thing.
+ */
+export function previewDecorationOf(preview: WorkbookPreviewState | null): WorkbookDecoration | undefined {
+  return preview === null ? undefined : toDecoration(preview.changes, preview.changesSide)
+}
+
+/**
+ * Counts + legend for the bar, derived from the same list the canvas tints.
+ *
+ * The counts carry the same bucket names the engine paints with, so the legend
+ * and the grid are read as one thing; `truncated` is carried through because a
+ * capped list would otherwise read as the whole comparison.
+ */
+export function inspectorSummaryOf(preview: WorkbookPreviewState | null): VersionInspectorSummary {
+  const summary: VersionInspectorSummary = { total: 0, add: 0, remove: 0, modify: 0, structure: 0, style: 0 }
+  if (preview === null) return summary
+  summary.total = preview.changes.length
+  if (preview.changesUnavailable === true) summary.unavailable = true
+  if (preview.changesTruncated === true) summary.truncated = true
+  for (const change of preview.changes) {
+    summary[versionChangeDirection({
+      kind: change.kind,
+      target: '',
+      description: '',
+      ...(change.row === undefined ? {} : { row: change.row }),
+      ...(change.column === undefined ? {} : { column: change.column }),
+      ...(change.before === undefined ? {} : { before: change.before }),
+      ...(change.after === undefined ? {} : { after: change.after }),
+      ...(change.styleOnly === true ? { styleOnly: true } : {}),
+    })] += 1
+  }
+  return summary
+}
+
+/**
+ * Preview switcher options: every Version the artifact could be swapped onto,
+ * newest-first, labelled the way its row was. Built from the timeline so the
+ * selector can never offer a Version the list does not show.
+ *
+ * The Steps give the picker its second level; the shared helper budgets a Step's
+ * summary to one menu line.
+ */
+export function inspectOptionsOf(entries: readonly VersionManagerEntry[]): VersionInspectOption[] {
+  return entries
+    .filter(entry => entry.replayable)
+    .map(entry => ({
+      id: entry.id,
+      label: versionOptionLabel({ summary: entry.summary, ...(entry.timestamp === undefined ? { time: entry.time } : { timestamp: entry.timestamp }) }),
+      steps: (entry.steps ?? []).map(step => ({
+        index: step.index,
+        label: versionStepOptionLabel(step),
+        ...(step.revision === undefined ? {} : { revision: step.revision }),
+      })),
+    }))
+}
+
+/**
+ * Revision a baseline id measures against.
+ *
+ * A Step is measured at the revision it produced. Falling back to the Version
+ * rather than refusing keeps a record written before the field existed usable —
+ * it just compares the whole Version.
+ */
+export function baselineRevisionOf(
+  entry: VersionManagerEntry | undefined,
+  fallbackRevision: number,
+  step?: number,
+): number {
+  if (entry === undefined) return fallbackRevision
+  if (step !== undefined) {
+    const found = entry.steps?.find(candidate => candidate.index === step)
+    if (found?.revision !== undefined) return found.revision
+  }
+  return entry.revision ?? fallbackRevision
+}
+
+/** What 「恢复」/「撤销这次改动」 posts, once the confirmation dialog is answered. */
+export interface VersionRestoreRequest {
+  revision: number
+  /** Render-time label, for the dialog and the notice. */
+  label: string
+  /** Durable summary written into the new Version's record. */
+  summary: string
+  mode: 'restore' | 'undo'
+}