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

package/src/client/persistence/merge.ts

@@ -0,0 +1,392 @@
+/**
+ * Three-way merge for Univer workbook snapshots.
+ *
+ * The browser keeps the last server snapshot as the base. When a user save
+ * races an Agent/user write, this module compares base/local/remote at cell
+ * granularity, adopts one-sided changes automatically, and keeps local values
+ * for true conflicts while adding a visible conflict style.
+ */
+
+import { cellAddress } from '#contracts'
+import { cloneSnapshot, normalizeCellFormula, stableJson, toCellValue } from '../../contract/snapshots.ts'
+import type { WorkbookLocalChange, WorkbookOperation } from '../../types.ts'
+
+type JsonRecord = Record<string, any>
+type CellData = Record<string, Record<string, JsonRecord>>
+
+export interface MergeConflict {
+  kind: 'cell' | 'structure' | 'sheet'
+  sheetId?: string
+  sheetName?: string
+  row?: number
+  column?: number
+  address?: string
+  baseValue?: unknown
+  localValue?: unknown
+  remoteValue?: unknown
+  description: string
+}
+
+export interface WorkbookMergeResult {
+  snapshot: object
+  conflicts: MergeConflict[]
+  autoMergedCells: number
+  conflictStyleMap: Record<string, string | null>
+}
+
+interface MergeSheetResult {
+  sheet: JsonRecord
+  conflicts: MergeConflict[]
+  autoMergedCells: number
+  conflictStyleMap: Record<string, string | null>
+}
+
+const MERGEABLE_SHEET_KEYS = [
+  'name',
+  'tabColor',
+  'hidden',
+  'zoomRatio',
+  'defaultColumnWidth',
+  'defaultRowHeight',
+  'freeze',
+  'mergeData',
+  'rowData',
+  'columnData',
+  'showGridlines',
+  'rowHeader',
+  'columnHeader',
+  'rightToLeft',
+  'defaultStyle',
+  'dataSheetMeta',
+] as const
+
+/** Merge local and remote snapshots against the last common base snapshot. */
+export function mergeWorkbookSnapshots(baseSnapshot: object, localSnapshot: object, remoteSnapshot: object): WorkbookMergeResult {
+  const base = asRecord(baseSnapshot)
+  const local = asRecord(localSnapshot)
+  const remote = asRecord(remoteSnapshot)
+  const merged = cloneSnapshot(local)
+  const conflicts: MergeConflict[] = []
+  const conflictStyleMap: Record<string, string | null> = {}
+  const localStyles = asRecord(merged.styles)
+  const remoteStyles = asRecord(remote.styles)
+  const remoteStyleMap = new Map<string, string>()
+
+  const adoptRemoteCell = (cell: JsonRecord | undefined): JsonRecord | undefined => {
+    if (cell === undefined) return undefined
+    const next = cloneSnapshot(cell)
+    if (typeof next.s === 'string') next.s = remapRemoteStyle(next.s)
+    return next
+  }
+
+  const remapRemoteStyle = (styleId: string): string => {
+    const known = remoteStyleMap.get(styleId)
+    if (known !== undefined) return known
+    const remoteStyle = remoteStyles[styleId]
+    if (remoteStyle === undefined) {
+      remoteStyleMap.set(styleId, styleId)
+      return styleId
+    }
+    const localStyle = localStyles[styleId]
+    if (localStyle === undefined || deepEqual(localStyle, remoteStyle)) {
+      localStyles[styleId] = cloneSnapshot(remoteStyle)
+      remoteStyleMap.set(styleId, styleId)
+      return styleId
+    }
+    let candidate = `${styleId}-remote`
+    let suffix = 1
+    while (localStyles[candidate] !== undefined) candidate = `${styleId}-remote-${suffix++}`
+    localStyles[candidate] = cloneSnapshot(remoteStyle)
+    remoteStyleMap.set(styleId, candidate)
+    return candidate
+  }
+
+  const baseSheets = asRecord(base.sheets)
+  const localSheets = asRecord(local.sheets)
+  const remoteSheets = asRecord(remote.sheets)
+  const mergedSheets: JsonRecord = {}
+  const allSheetIds = new Set([...Object.keys(baseSheets), ...Object.keys(localSheets), ...Object.keys(remoteSheets)])
+
+  for (const sheetId of allSheetIds) {
+    const baseSheet = asOptionalRecord(baseSheets[sheetId])
+    const localSheet = asOptionalRecord(localSheets[sheetId])
+    const remoteSheet = asOptionalRecord(remoteSheets[sheetId])
+    if (localSheet === undefined && remoteSheet === undefined) continue
+    if (localSheet === undefined) {
+      if (baseSheet !== undefined && remoteSheet !== undefined && !deepEqual(remoteSheet, baseSheet)) {
+        conflicts.push(sheetConflict(sheetId, remoteSheet, '本地删除 sheet，但远端同时修改了它'))
+      }
+      // A sheet deleted locally remains deleted. A remote-only sheet is kept.
+      if (baseSheet === undefined && remoteSheet !== undefined) mergedSheets[sheetId] = cloneAndRemapSheet(remoteSheet, adoptRemoteCell)
+      continue
+    }
+    if (remoteSheet === undefined) {
+      if (baseSheet !== undefined && !deepEqual(localSheet, baseSheet)) {
+        conflicts.push(sheetConflict(sheetId, localSheet, '远端删除 sheet，但本地同时修改了它'))
+      }
+      // A sheet deleted remotely is deleted only when local had not changed it.
+      if (baseSheet !== undefined && deepEqual(localSheet, baseSheet)) continue
+      mergedSheets[sheetId] = cloneSnapshot(localSheet)
+      continue
+    }
+    const result = mergeSheet(sheetId, baseSheet, localSheet, remoteSheet, adoptRemoteCell, localStyles)
+    mergedSheets[sheetId] = result.sheet
+    conflicts.push(...result.conflicts)
+    Object.assign(conflictStyleMap, result.conflictStyleMap)
+  }
+
+  merged.sheets = mergedSheets
+  merged.styles = localStyles
+  const baseOrder = asStringArray(base.sheetOrder)
+  const localOrder = asStringArray(local.sheetOrder)
+  const remoteOrder = asStringArray(remote.sheetOrder)
+  if (deepEqual(localOrder, baseOrder) && !deepEqual(remoteOrder, baseOrder)) merged.sheetOrder = remoteOrder.filter(id => mergedSheets[id] !== undefined)
+  else if (!deepEqual(localOrder, remoteOrder) && !deepEqual(remoteOrder, baseOrder)) {
+    conflicts.push({ kind: 'structure', description: '本地和远端同时调整了 sheet 顺序，当前保留本地顺序' })
+  }
+  merged.sheetOrder = normalizeSheetOrder(asStringArray(merged.sheetOrder), mergedSheets)
+
+  return {
+    snapshot: merged,
+    conflicts,
+    autoMergedCells: countAutoMergedCells(base, local, remote, mergedSheets),
+    conflictStyleMap,
+  }
+}
+
+/** Remove temporary conflict styles before a merged snapshot is persisted. */
+export function stripConflictMarkers(snapshot: object, conflictStyleMap: Record<string, string | null>): object {
+  if (Object.keys(conflictStyleMap).length === 0) return snapshot
+  const next = cloneSnapshot(snapshot) as JsonRecord
+  const sheets = asRecord(next.sheets)
+  for (const sheet of Object.values(sheets)) {
+    const cellData = asRecord(sheet).cellData as CellData | undefined
+    if (cellData === undefined) continue
+    for (const [rowKey, row] of Object.entries(cellData)) {
+      for (const [columnKey, cell] of Object.entries(row)) {
+        const marker = typeof cell.s === 'string' ? conflictStyleMap[cell.s] : undefined
+        if (marker === undefined && !Object.prototype.hasOwnProperty.call(conflictStyleMap, cell.s)) continue
+        if (marker === null) delete cell.s
+        else cell.s = marker
+        if (Object.keys(cell).length === 1 && cell.v === null) delete row[columnKey]
+      }
+      if (Object.keys(row).length === 0) delete cellData[rowKey]
+    }
+  }
+  const styles = asRecord(next.styles)
+  for (const markerId of Object.keys(conflictStyleMap)) delete styles[markerId]
+  next.styles = styles
+  return next
+}
+
+/** Apply ordinary cell edits to the merge base without cloning the workbook. */
+export function applyIncrementalChangesToSnapshot(snapshot: object, changes: WorkbookLocalChange[]): void {
+  const root = asRecord(snapshot)
+  const sheets = asRecord(root.sheets)
+  for (const change of changes) {
+    const sheet = sheets[change.payload.sheetId] ?? Object.values(sheets).find(candidate => asRecord(candidate).name === change.payload.sheetId)
+    if (sheet === undefined) continue
+    const cellData = (asRecord(sheet).cellData ??= {}) as CellData
+    for (const update of change.payload.cells) {
+      const row = (cellData[String(update.row)] ??= {})
+      if (update.value === null && (update.formula === undefined || update.formula.trim().length === 0)) {
+        delete row[String(update.column)]
+        if (Object.keys(row).length === 0) delete cellData[String(update.row)]
+        continue
+      }
+      const current = row[String(update.column)] ?? {}
+      row[String(update.column)] = { ...current, v: update.value }
+      const formula = normalizeCellFormula(update.formula)
+      if (formula === undefined) delete row[String(update.column)].f
+      else row[String(update.column)].f = formula
+    }
+  }
+}
+
+/** Patch a merge base from a replayable operation log; false means fallback. */
+export function applyIncrementalOperationsToSnapshot(snapshot: object, operations: WorkbookOperation[]): boolean {
+  const changes: WorkbookLocalChange[] = []
+  const collect = (operation: WorkbookOperation): boolean => {
+    if (operation.type === 'update_cells') {
+      const sheetId = operation.payload.sheetId ?? operation.payload.sheetName
+      if (sheetId === undefined || (operation.payload.cells ?? []).length === 0) return false
+      changes.push({ type: 'update_cells', payload: { sheetId, cells: operation.payload.cells ?? [] } })
+      return true
+    }
+    if (operation.type === 'batch') {
+      return (operation.payload.operations ?? []).every((child, index) => collect({
+        ...operation,
+        opId: `${operation.opId}:${index}`,
+        type: child.type,
+        payload: child.payload,
+      }))
+    }
+    return false
+  }
+  if (!operations.every(collect)) return false
+  applyIncrementalChangesToSnapshot(snapshot, changes)
+  return true
+}
+
+function mergeSheet(
+  sheetId: string,
+  baseSheet: JsonRecord | undefined,
+  localSheet: JsonRecord,
+  remoteSheet: JsonRecord,
+  adoptRemoteCell: (cell: JsonRecord | undefined) => JsonRecord | undefined,
+  styles: JsonRecord,
+): MergeSheetResult {
+  const sheet = cloneSnapshot(localSheet)
+  const conflicts: MergeConflict[] = []
+  const conflictStyleMap: Record<string, string | null> = {}
+  let autoMergedCells = 0
+  const localRowCount = typeof localSheet.rowCount === 'number' ? localSheet.rowCount : 0
+  const remoteRowCount = typeof remoteSheet.rowCount === 'number' ? remoteSheet.rowCount : 0
+  const localColumnCount = typeof localSheet.columnCount === 'number' ? localSheet.columnCount : 0
+  const remoteColumnCount = typeof remoteSheet.columnCount === 'number' ? remoteSheet.columnCount : 0
+  sheet.rowCount = Math.max(localRowCount, remoteRowCount)
+  sheet.columnCount = Math.max(localColumnCount, remoteColumnCount)
+
+  for (const key of MERGEABLE_SHEET_KEYS) {
+    const baseValue = baseSheet?.[key]
+    const localValue = localSheet[key]
+    const remoteValue = remoteSheet[key]
+    if (deepEqual(localValue, remoteValue)) continue
+    if (deepEqual(localValue, baseValue)) {
+      if (remoteValue === undefined) delete sheet[key]
+      else sheet[key] = cloneSnapshot(remoteValue)
+    } else if (deepEqual(remoteValue, baseValue)) {
+      continue
+    } else {
+      conflicts.push({ kind: 'structure', sheetId, sheetName: sheetName(localSheet, sheetId), description: `sheet 属性 ${key} 在本地和远端均有修改，当前保留本地值` })
+    }
+  }
+
+  const baseCells = asCellData(baseSheet?.cellData)
+  const localCells = asCellData(localSheet.cellData)
+  const remoteCells = asCellData(remoteSheet.cellData)
+  const mergedCells: CellData = {}
+  const rowKeys = new Set([...Object.keys(baseCells), ...Object.keys(localCells), ...Object.keys(remoteCells)])
+  for (const rowKey of rowKeys) {
+    const baseRow = baseCells[rowKey] ?? {}
+    const localRow = localCells[rowKey] ?? {}
+    const remoteRow = remoteCells[rowKey] ?? {}
+    const columnKeys = new Set([...Object.keys(baseRow), ...Object.keys(localRow), ...Object.keys(remoteRow)])
+    for (const columnKey of columnKeys) {
+      const baseCell = baseRow[columnKey]
+      const localCell = localRow[columnKey]
+      const remoteCell = remoteRow[columnKey]
+      let selected: JsonRecord | undefined
+      if (deepEqual(localCell, remoteCell)) selected = cloneOptional(localCell)
+      else if (deepEqual(localCell, baseCell)) {
+        selected = adoptRemoteCell(remoteCell)
+        autoMergedCells++
+      } else if (deepEqual(remoteCell, baseCell)) {
+        selected = cloneOptional(localCell)
+        autoMergedCells++
+      } else {
+        selected = cloneOptional(localCell) ?? { v: null }
+        const markerId = createConflictStyle(styles, selected, sheetId, Number(rowKey), Number(columnKey))
+        conflictStyleMap[markerId] = typeof localCell?.s === 'string' ? localCell.s : null
+        selected.s = markerId
+        conflicts.push({
+          kind: 'cell',
+          sheetId,
+          sheetName: sheetName(localSheet, sheetId),
+          row: Number(rowKey),
+          column: Number(columnKey),
+          address: `${sheetName(localSheet, sheetId)}!${cellAddress(Number(rowKey), Number(columnKey))}`,
+          baseValue: toCellValue(baseCell),
+          localValue: toCellValue(localCell),
+          remoteValue: toCellValue(remoteCell),
+          description: '本地和远端同时修改了同一单元格，当前保留本地值',
+        })
+      }
+      if (selected !== undefined) (mergedCells[rowKey] ??= {})[columnKey] = selected
+    }
+  }
+  sheet.cellData = mergedCells
+  return { sheet, conflicts, autoMergedCells, conflictStyleMap }
+}
+
+function createConflictStyle(styles: JsonRecord, cell: JsonRecord, sheetId: string, row: number, column: number): string {
+  const original = typeof cell.s === 'string' ? asOptionalRecord(styles[cell.s]) ?? {} : {}
+  const baseId = `data-sheet-conflict-${sheetId}-${row}-${column}`
+  let id = baseId
+  let suffix = 1
+  while (styles[id] !== undefined) id = `${baseId}-${suffix++}`
+  styles[id] = { ...cloneSnapshot(original), bg: '#FFF2CC', cl: '#9C0006' }
+  return id
+}
+
+function sheetConflict(sheetId: string, sheet: JsonRecord, description: string): MergeConflict {
+  return { kind: 'sheet', sheetId, sheetName: sheetName(sheet, sheetId), description }
+}
+
+function sheetName(sheet: JsonRecord, fallback: string): string {
+  return typeof sheet.name === 'string' && sheet.name.length > 0 ? sheet.name : fallback
+}
+
+function countAutoMergedCells(base: JsonRecord, local: JsonRecord, remote: JsonRecord, mergedSheets: JsonRecord): number {
+  let count = 0
+  const baseSheets = asRecord(base.sheets)
+  const localSheets = asRecord(local.sheets)
+  const remoteSheets = asRecord(remote.sheets)
+  for (const [sheetId, sheet] of Object.entries(mergedSheets)) {
+    const baseCells = asCellData(baseSheets[sheetId]?.cellData)
+    const localCells = asCellData(localSheets[sheetId]?.cellData)
+    const remoteCells = asCellData(remoteSheets[sheetId]?.cellData)
+    const mergedCells = asCellData(sheet.cellData)
+    for (const [rowKey, row] of Object.entries(mergedCells)) {
+      for (const columnKey of Object.keys(row)) {
+        const localCell = localCells[rowKey]?.[columnKey]
+        const remoteCell = remoteCells[rowKey]?.[columnKey]
+        const baseCell = baseCells[rowKey]?.[columnKey]
+        if (!deepEqual(localCell, remoteCell) && (deepEqual(localCell, baseCell) || deepEqual(remoteCell, baseCell))) count++
+      }
+    }
+  }
+  return count
+}
+
+function cloneAndRemapSheet(sheet: JsonRecord, adoptRemoteCell: (cell: JsonRecord | undefined) => JsonRecord | undefined): JsonRecord {
+  const next = cloneSnapshot(sheet)
+  const cellData = asCellData(next.cellData)
+  for (const [rowKey, row] of Object.entries(cellData)) {
+    for (const [columnKey, cell] of Object.entries(row)) row[columnKey] = adoptRemoteCell(cell) ?? cell
+    cellData[rowKey] = row
+  }
+  next.cellData = cellData
+  return next
+}
+
+function normalizeSheetOrder(order: string[], sheets: JsonRecord): string[] {
+  const result = order.filter(id => sheets[id] !== undefined)
+  for (const id of Object.keys(sheets)) if (!result.includes(id)) result.push(id)
+  return result
+}
+
+function asRecord(value: unknown): JsonRecord {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : {}
+}
+
+function asOptionalRecord(value: unknown): JsonRecord | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : undefined
+}
+
+function asCellData(value: unknown): CellData {
+  return asRecord(value) as CellData
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+}
+
+function cloneOptional<T>(value: T | undefined): T | undefined {
+  return value === undefined ? undefined : cloneSnapshot(value)
+}
+
+function deepEqual(left: unknown, right: unknown): boolean {
+  return stableJson(left) === stableJson(right)
+}
+

package/src/client/store.ts

@@ -0,0 +1,188 @@
+/**
+ * Minimal sheet-panel store for dsh-data-table: the right-column
+ * open state. Workbook data lives server-side (node half, snapshot files);
+ * this store only tracks the panel toggle.
+ * @module dsh-data-table/client/store
+ */
+
+import { useSyncExternalStore } from 'react'
+
+let sheetOpen = false
+
+/**
+ * Last workbook the user opened. DSH remounts the pane when the conversation
+ * tab changes, so the selection has to live outside React; localStorage keeps
+ * it across a reload too. Persistence is best-effort: a locked-down browser
+ * simply falls back to an in-memory value for this page life.
+ */
+const LAST_WORKBOOK_KEY = 'dsh.data-sheet.lastWorkbookId'
+let lastWorkbookId = ''
+let lastWorkbookLoaded = false
+
+function readLastWorkbook(): string {
+  if (lastWorkbookLoaded) return lastWorkbookId
+  lastWorkbookLoaded = true
+  try {
+    lastWorkbookId = globalThis.localStorage?.getItem(LAST_WORKBOOK_KEY) ?? ''
+  } catch {
+    lastWorkbookId = ''
+  }
+  return lastWorkbookId
+}
+
+/** The workbook to reopen when the pane mounts without an explicit target. */
+export function lastSelectedWorkbookId(): string {
+  return readLastWorkbook()
+}
+
+/** Record the active workbook; call with an empty string when it is removed. */
+export function rememberWorkbook(id: string): void {
+  readLastWorkbook()
+  if (lastWorkbookId === id) return
+  lastWorkbookId = id
+  try {
+    if (id === '') globalThis.localStorage?.removeItem(LAST_WORKBOOK_KEY)
+    else globalThis.localStorage?.setItem(LAST_WORKBOOK_KEY, id)
+  } catch {
+    // Ignore storage failures; the in-memory value still survives remounts.
+  }
+}
+/**
+ * The **unretained editing session** the next save joins, per workbook
+ * (PRD v3.3 D22).
+ *
+ * The session is not a saved Version: it keeps accumulating Steps and only
+ * becomes one when the idle window closes it or it reaches the Step cap. It has
+ * to outlive the React panel, because DSH remounts the pane whenever the
+ * conversation tab changes — losing the cursor there was what made "every visit
+ * is its own version", i.e. what users read as "leaving the artifact saved a
+ * version". localStorage is best-effort; the in-memory map covers a browser
+ * that refuses storage.
+ */
+export interface VersionSession {
+  /** The Version id the next save joins; `null` when there is nothing open. */
+  versionId: string
+  /** Steps already committed into that Version. */
+  stepCount: number
+}
+
+const VERSION_SESSION_PREFIX = 'dsh.data-sheet.versionSession.'
+const versionSessions = new Map<string, VersionSession>()
+
+function versionSessionKey(workbookId: string): string {
+  return `${VERSION_SESSION_PREFIX}${workbookId}`
+}
+
+/** The open session for a workbook, or `null` when there is none. */
+export function readVersionSession(workbookId: string): VersionSession | null {
+  if (workbookId === '') return null
+  const cached = versionSessions.get(workbookId)
+  if (cached !== undefined) return cached
+  try {
+    const raw = globalThis.localStorage?.getItem(versionSessionKey(workbookId))
+    if (raw === null || raw === undefined) return null
+    const parsed = JSON.parse(raw) as Partial<VersionSession>
+    if (typeof parsed.versionId !== 'string' || parsed.versionId === '') return null
+    const session: VersionSession = { versionId: parsed.versionId, stepCount: typeof parsed.stepCount === 'number' && parsed.stepCount > 0 ? parsed.stepCount : 0 }
+    versionSessions.set(workbookId, session)
+    return session
+  } catch {
+    return null
+  }
+}
+
+/** Record (or with `null`, forget) the open session for a workbook. */
+export function rememberVersionSession(workbookId: string, session: VersionSession | null): void {
+  if (workbookId === '') return
+  if (session === null) versionSessions.delete(workbookId)
+  else versionSessions.set(workbookId, session)
+  try {
+    if (session === null) globalThis.localStorage?.removeItem(versionSessionKey(workbookId))
+    else globalThis.localStorage?.setItem(versionSessionKey(workbookId), JSON.stringify(session))
+  } catch {
+    // Ignore storage failures; the in-memory value still survives remounts.
+  }
+}
+
+const listeners = new Set<() => void>()
+
+function emit(): void {
+  for (const listener of [...listeners]) listener()
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => { listeners.delete(listener) }
+}
+
+/** Whether the right column is open. */
+export function isSheetOpen(): boolean {
+  return sheetOpen
+}
+
+/** Open/close the right column. */
+export function setSheetOpen(value: boolean): void {
+  sheetOpen = value
+  emit()
+}
+
+/** React hook: right-column open state. */
+export function useSheetOpen(): boolean {
+  return useSyncExternalStore(subscribe, () => sheetOpen)
+}
+
+/**
+ * Whether the Table tab is currently on screen.
+ *
+ * The workspace is a resident tree that outlives the pane, so its own `open`
+ * flag stays true for the life of the page. Anything that must react only to a
+ * *visible* table — the window-level Ctrl/Cmd+S shortcut in particular — reads
+ * this instead.
+ */
+let sheetVisible = false
+
+/** Record whether the pane is showing the Table tab. */
+export function setSheetVisible(value: boolean): void {
+  if (sheetVisible === value) return
+  sheetVisible = value
+  emit()
+}
+
+/** Whether the Table tab is on screen. */
+export function isSheetVisible(): boolean {
+  return sheetVisible
+}
+
+/** React hook: whether the Table tab is on screen. */
+export function useSheetVisible(): boolean {
+  return useSyncExternalStore(subscribe, () => sheetVisible)
+}
+
+/**
+ * Last workbook projection kept outside React. DSH unmounts the right pane when
+ * the conversation tab changes, so caching here lets a remount paint the
+ * previous content immediately instead of showing an empty panel while the
+ * request is in flight. The panel still revalidates against the Host, so edits
+ * made in another browser tab are not lost.
+ */
+export interface WorkbookProjection {
+  id: string
+  name: string
+  snapshot: object
+  revision: number
+}
+
+let cachedProjection: WorkbookProjection | null = null
+
+export function cachedWorkbookProjection(id: string): WorkbookProjection | null {
+  return cachedProjection !== null && cachedProjection.id === id ? cachedProjection : null
+}
+
+export function rememberWorkbookProjection(projection: WorkbookProjection): void {
+  cachedProjection = projection
+}
+
+/** Drop the cache when the workbook is deleted or fails to load. */
+export function forgetWorkbookProjection(id?: string): void {
+  if (id === undefined || cachedProjection?.id === id) cachedProjection = null
+}