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

package/src/univer/apply-operation.ts

@@ -0,0 +1,369 @@
+/**
+ * Applying a workbook operation to the live canvas (docs/issue/0022 P4).
+ *
+ * This is the *canvas* half of an operation: the Host has already decided the
+ * operation is durable and recorded it, and this turns it into Univer commands
+ * so the browser sees the same result without reloading a snapshot. The two
+ * halves share one vocabulary (`contract/mutations.ts` applies an operation to a
+ * snapshot) and must agree: a command this file cannot express is a bug the user
+ * sees as "my edit did not appear".
+ *
+ * Built as a factory because it needs the mount's facade and its sheet resolver,
+ * and because `applyingRemote` has to be visible to the engine's mutation guard:
+ * a remote operation we apply ourselves is not a user edit.
+ */
+import { APPEND_HEADER_MISMATCH } from '../contract/operations.ts'
+import { DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, normalizeCellFormula } from '../contract/snapshots.ts'
+
+import type { SheetColumn, WorkbookCellStyle, WorkbookCellUpdate, WorkbookOperation, WorkbookOperationPayload } from '../types.ts'
+import type { SheetsApi, SheetResolver, UniverRange, UniverSheet } from './facade.ts'
+
+
+/** Default sheet extent (Univer's own default), so data lands on a full-size grid. */
+
+export interface OperationApplier {
+  apply(operation: WorkbookOperation): Promise<void>
+  /** True while an operation from elsewhere is being written to the canvas. */
+  isApplyingRemote(): boolean
+  /** Sheet metadata that only exists in the live canvas (not in the snapshot). */
+  liveSheetMetadata: Map<string, unknown>
+}
+
+export function createOperationApplier(deps: { sheetsApi: SheetsApi; getSheet: SheetResolver }): OperationApplier {
+  const { sheetsApi, getSheet } = deps
+  let applyingRemote = false
+
+  const liveSheetMetadata = new Map<string, unknown>()
+
+  const coerceAppendValue = (column: SheetColumn, value: unknown): string | number | boolean | null => {
+    if (value === undefined || value === null) return null
+    if (column.type === 'number' || column.type === 'currency') {
+      const numeric = typeof value === 'number' ? value : Number(value)
+      return Number.isFinite(numeric) ? numeric : String(value)
+    }
+    if (column.type === 'boolean') return typeof value === 'boolean' ? value : String(value) === 'true'
+    if (column.type === 'date') return value instanceof Date ? value.toISOString().slice(0, 10) : String(value)
+    return String(value)
+  }
+
+  /** Append tabular data with Univer's range mutation APIs. */
+  const applyAppendRows = (operation: WorkbookOperation, payload: WorkbookOperationPayload): void => {
+    const sheetRef = payload.sheetId ?? payload.sheetName
+    const columns = payload.columns ?? []
+    const rows = payload.rows ?? []
+    if (columns.length === 0) throw new Error('至少需要一列')
+    const headerRowIndex = payload.headerRowIndex ?? 0
+    // Mirrors the Host snapshot check, so a batch can never pass here and fail
+    // there. A report sheet whose real header is not row 0 is addressed
+    // explicitly instead of being rejected.
+    const verifyHeader = payload.verifyHeader !== false
+
+    let sheet = getSheet(sheetRef)
+    if (sheet === null) {
+      if (sheetRef === undefined) throw new Error('Univer sheet 不存在')
+      // Keep an implicitly created sheet addressable by the same stable
+      // reference that the Host snapshot uses. This matters when an append is
+      // followed by another command in the same Agent batch.
+      const generatedSheetId = sheetRef ?? `sheet-${operation.opId.slice(0, 12)}`
+      const activeWorkbook = sheetsApi.getActiveWorkbook()
+      if (activeWorkbook === null) throw new Error('Univer workbook 未挂载')
+      activeWorkbook.create(payload.name ?? sheetRef ?? 'Sheet', DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, { sheet: { id: generatedSheetId } })
+      sheet = getSheet(generatedSheetId) ?? getSheet(sheetRef)
+    }
+    if (sheet === null || sheet.getRange === undefined) throw new Error('Univer sheet 创建失败')
+
+    const headerRange = sheet.getRange(headerRowIndex, 0, 1, columns.length)
+    const existingHeader = columns.map((_column, index) => sheet?.getRange?.(headerRowIndex, index).getValue?.())
+    const hasExistingHeader = existingHeader.some(value => value !== undefined && value !== null && String(value).length > 0)
+    if (verifyHeader && hasExistingHeader && columns.some((column, index) => String(existingHeader[index] ?? '') !== column.label)) {
+      throw new Error(APPEND_HEADER_MISMATCH)
+    }
+    if (!hasExistingHeader) headerRange.setValues([columns.map(column => column.label)])
+
+    const nextRow = Math.max(headerRowIndex + 1, (sheet.getLastRow?.() ?? 0) + 1)
+    if (rows.length > 0) {
+      const values = rows.map(row => columns.map(column => coerceAppendValue(column, row[column.key])))
+      sheet.getRange(nextRow, 0, values.length, columns.length).setValues(values)
+    }
+    if (sheet.getMaxColumns?.() !== undefined && sheet.setColumnCount !== undefined) {
+      sheet.setColumnCount(Math.max(sheet.getMaxColumns?.() ?? DEFAULT_SHEET_COLUMNS, columns.length))
+    }
+    if (sheet.getMaxRows?.() !== undefined && sheet.setRowCount !== undefined) {
+      sheet.setRowCount(Math.max(sheet.getMaxRows?.() ?? DEFAULT_SHEET_ROWS, nextRow + rows.length))
+    }
+    const sheetId = sheet.getSheetId?.()
+    if (payload.meta !== undefined && sheetId !== undefined) liveSheetMetadata.set(sheetId, payload.meta)
+  }
+
+  /** Sort through the open-source sort preset's Facade mixin. */
+  const applySortRange = (payload: WorkbookOperationPayload): void => {
+    const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+    const range = payload.range
+    const sort = payload.sort
+    if (sheet === null || range === undefined || sort === undefined) throw new Error('sort_range 参数无效')
+    const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+    if (target.sort === undefined) throw new Error('当前 Univer Sort Facade 不可用')
+    target.sort({ column: sort.column - range.startColumn, ascending: sort.direction !== 'desc' })
+  }
+
+  /** Apply the JSON-safe Datasheet style subset through Univer's Facade. */
+  const applyCellStyle = async (sheet: UniverSheet, range: UniverRange, target: { startRow: number; startColumn: number; endRow: number; endColumn: number }, style: WorkbookCellStyle): Promise<void> => {
+    if (style.bg !== undefined) {
+      if (range.setBackgroundColor === undefined) throw new Error('当前 Univer Facade 不支持背景色')
+      range.setBackgroundColor(style.bg)
+    }
+    if (style.cl !== undefined) {
+      if (range.setFontColor === undefined) throw new Error('当前 Univer Facade 不支持字体颜色')
+      range.setFontColor(style.cl)
+    }
+    if (style.ff !== undefined) {
+      if (range.setFontFamily === undefined) throw new Error('当前 Univer Facade 不支持字体')
+      range.setFontFamily(style.ff)
+    }
+    if (style.fs !== undefined) {
+      if (range.setFontSize === undefined) throw new Error('当前 Univer Facade 不支持字号')
+      range.setFontSize(style.fs)
+    }
+    if (style.bl !== undefined) {
+      if (range.setFontWeight === undefined) throw new Error('当前 Univer Facade 不支持粗体')
+      range.setFontWeight(style.bl ? 'bold' : 'normal')
+    }
+    if (style.it !== undefined) {
+      if (range.setFontStyle === undefined) throw new Error('当前 Univer Facade 不支持斜体')
+      range.setFontStyle(style.it ? 'italic' : 'normal')
+    }
+    if (style.ul !== undefined) {
+      if (range.setFontLine === undefined) throw new Error('当前 Univer Facade 不支持下划线')
+      range.setFontLine(style.ul ? 'underline' : 'none')
+    }
+    if (style.st !== undefined) {
+      if (range.setFontLine === undefined) throw new Error('当前 Univer Facade 不支持删除线')
+      range.setFontLine(style.st ? 'line-through' : 'none')
+    }
+    if (style.ht !== undefined) {
+      if (range.setHorizontalAlignment === undefined) throw new Error('当前 Univer Facade 不支持水平对齐')
+      const alignment = style.ht === 1 ? 'left' : style.ht === 2 ? 'center' : 'normal'
+      range.setHorizontalAlignment(alignment)
+    }
+    if (style.vt !== undefined) {
+      if (range.setVerticalAlignment === undefined) throw new Error('当前 Univer Facade 不支持垂直对齐')
+      const alignment = style.vt === 1 ? 'top' : style.vt === 2 ? 'middle' : 'bottom'
+      range.setVerticalAlignment(alignment)
+    }
+    if (style.tr !== undefined) {
+      if (range.setTextRotation === undefined) throw new Error('当前 Univer Facade 不支持文字旋转')
+      range.setTextRotation(style.tr)
+    }
+    // Univer 0.25 exposes number format through the native SetStyleCommand;
+    // use the command bridge for this one style that the Facade does not wrap.
+    if (style.n !== undefined) {
+      await sheetsApi.executeCommand('sheet.command.set-style', {
+        unitId: sheetsApi.getActiveWorkbook()?.getId(),
+        subUnitId: sheet.getSheetId?.(),
+        range: target,
+        style: { type: 'n', value: style.n },
+      }, { fromCollab: true })
+    }
+  }
+  const applyOperation = async (operation: WorkbookOperation): Promise<void> => {
+    const workbook = sheetsApi.getActiveWorkbook()
+    if (workbook === null) throw new Error('Univer workbook 未挂载')
+    const payload = operation.payload
+    applyingRemote = true
+    try {
+      switch (operation.type) {
+      case 'update_cells': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet === null) throw new Error(`Univer sheet 不存在：${payload.sheetId ?? payload.sheetName ?? ''}`)
+        const cells = payload.cells ?? []
+        if (cells.length === 0) return
+        const unitId = workbook.getId()
+        const sheetId = sheet.getSheetId?.()
+        if (sheetId === undefined) throw new Error('Univer sheet id 缺失')
+        const value: Record<string, Record<string, { v: WorkbookCellUpdate['value']; f?: string }>> = {}
+        const clearCells: WorkbookCellUpdate[] = []
+        for (const cell of cells) {
+          // The same normalization the snapshot applies: the canvas and the
+          // stored snapshot are two views of one workbook.
+          const formula = normalizeCellFormula(cell.formula)
+          if (cell.value === null && formula === undefined) {
+            clearCells.push(cell)
+            continue
+          }
+          value[String(cell.row)] ??= {}
+          value[String(cell.row)][String(cell.column)] = { v: cell.value, ...(formula === undefined ? {} : { f: formula }) }
+        }
+        if (Object.keys(value).length > 0) {
+          await sheetsApi.executeCommand('sheet.command.set-range-values', { unitId, subUnitId: sheetId, value }, { fromCollab: true })
+        }
+        // A null value is a content clear rather than a value assignment in
+        // Univer. Keep clears grouped after the fast sparse value command.
+        for (const cell of clearCells) sheet.getRange(cell.row, cell.column).clearContent()
+        return
+      }
+      case 'clear_range': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range
+        if (sheet === null || range === undefined) throw new Error('clear_range 参数无效')
+        sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1).clearContent()
+        return
+      }
+      case 'set_hyperlink': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range
+        if (sheet === null || range === undefined || payload.url === undefined) throw new Error('set_hyperlink 参数无效')
+        const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+        if (target.setHyperLink === undefined) throw new Error('当前 Univer HyperLink Facade 不可用')
+        const current = target.getValue?.()
+        const label = payload.label ?? (current === undefined || current === null || String(current).length === 0 ? undefined : String(current))
+        await target.setHyperLink(payload.url, label)
+        return
+      }
+      case 'remove_hyperlink': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range
+        if (sheet === null || range === undefined) throw new Error('remove_hyperlink 参数无效')
+        // DSH's operation contract mirrors set_hyperlink and targets only the
+        // top-left cell. A multi-cell range must not remove unrelated links.
+        const target = sheet.getRange(range.startRow, range.startColumn)
+        if (target.cancelHyperLink === undefined) throw new Error('当前 Univer HyperLink Facade 不可用')
+        target.cancelHyperLink()
+        return
+      }
+      case 'delete_cells': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range
+        const shift = payload.shift ?? 'clear'
+        if (sheet === null || range === undefined) throw new Error('delete_cells 参数无效')
+        const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+        if (shift === 'clear') {
+          target.clearContent()
+          return
+        }
+        if (target.deleteCells === undefined) throw new Error('当前 Univer Facade 不支持结构性删除单元格')
+        target.deleteCells(shift === 'left' ? 0 : 1)
+        return
+      }
+      case 'insert_rows': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet?.insertRows === undefined || payload.range === undefined) throw new Error('insert_rows 参数无效')
+        sheet.insertRows(payload.range.startRow, payload.count ?? 1)
+        return
+      }
+      case 'delete_rows': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet?.deleteRows === undefined || payload.range === undefined) throw new Error('delete_rows 参数无效')
+        sheet.deleteRows(payload.range.startRow, payload.count ?? 1)
+        return
+      }
+      case 'insert_columns': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet?.insertColumns === undefined || payload.range === undefined) throw new Error('insert_columns 参数无效')
+        sheet.insertColumns(payload.range.startColumn, payload.count ?? 1)
+        return
+      }
+      case 'delete_columns': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet?.deleteColumns === undefined || payload.range === undefined) throw new Error('delete_columns 参数无效')
+        sheet.deleteColumns(payload.range.startColumn, payload.count ?? 1)
+        return
+      }
+      case 'create_sheet':
+        workbook.create(payload.name ?? payload.sheetId ?? 'Sheet', DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, {
+          sheet: { id: payload.sheetId ?? `sheet-${operation.opId.slice(0, 12)}` },
+        })
+        return
+      case 'rename_sheet': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet?.setName === undefined || payload.name === undefined) throw new Error('rename_sheet 参数无效')
+        sheet.setName(payload.name)
+        return
+      }
+      case 'delete_sheet': {
+        if (workbook.deleteSheet === undefined) throw new Error('当前 Univer Facade 不支持删除 sheet')
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        if (sheet === null) throw new Error(`Univer sheet 不存在：${payload.sheetId ?? payload.sheetName ?? ''}`)
+        // Pass the Facade sheet object so a name-based Agent operation is
+        // resolved to the actual sheet id before Univer executes the command.
+        workbook.deleteSheet(sheet)
+        return
+      }
+      case 'format_cells': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range
+        if (sheet === null || range === undefined || payload.style === undefined) throw new Error('format_cells 参数无效')
+        const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+        await applyCellStyle(sheet, target, range, payload.style)
+        return
+      }
+      case 'merge_cells': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range ?? payload.merge
+        if (sheet === null || range === undefined) throw new Error('merge_cells 参数无效')
+        const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+        if (target.merge === undefined) throw new Error('当前 Univer Facade 不支持合并单元格')
+        target.merge({ defaultMerge: true, isForceMerge: true })
+        return
+      }
+      case 'unmerge_cells': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const range = payload.range ?? payload.merge
+        if (sheet === null || range === undefined) throw new Error('unmerge_cells 参数无效')
+        const target = sheet.getRange(range.startRow, range.startColumn, range.endRow - range.startRow + 1, range.endColumn - range.startColumn + 1)
+        if (target.breakApart === undefined) throw new Error('当前 Univer Facade 不支持取消合并')
+        target.breakApart()
+        return
+      }
+      case 'freeze_panes': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const freeze = payload.freeze
+        if (sheet === null || freeze === undefined || sheet.setFreeze === undefined || sheet.cancelFreeze === undefined) throw new Error('freeze_panes 参数无效')
+        const rows = Math.max(0, freeze.rows ?? 0)
+        const columns = Math.max(0, freeze.columns ?? 0)
+        if (rows === 0 && columns === 0) sheet.cancelFreeze()
+        else sheet.setFreeze({ startRow: rows, startColumn: columns, xSplit: columns, ySplit: rows })
+        return
+      }
+      case 'set_column_width': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const index = payload.range?.startColumn
+        if (sheet === null || index === undefined || payload.size === undefined || sheet.setColumnWidth === undefined) throw new Error('set_column_width 参数无效')
+        sheet.setColumnWidth(index, payload.size)
+        return
+      }
+      case 'set_row_height': {
+        const sheet = getSheet(payload.sheetId ?? payload.sheetName)
+        const index = payload.range?.startRow
+        if (sheet === null || index === undefined || payload.size === undefined || sheet.setRowHeight === undefined) throw new Error('set_row_height 参数无效')
+        sheet.setRowHeight(index, payload.size)
+        return
+      }
+      case 'append_rows':
+        applyAppendRows(operation, payload)
+        return
+      case 'sort_range':
+        applySortRange(payload)
+        return
+      case 'batch': {
+        for (const child of payload.operations ?? []) {
+          if (child.type === 'batch' || child.type === 'snapshot_replace') throw new Error('batch 不支持嵌套 batch 或 snapshot_replace')
+          // Re-enable the guard after each recursive call. The child call
+          // owns the same operation adapter but resets the guard in finally.
+          applyingRemote = true
+          await applyOperation({ ...operation, type: child.type, payload: child.payload })
+        }
+        return
+      }
+      case 'snapshot_replace':
+        // An arbitrary snapshot has no equivalent single Univer command.
+        throw new Error(`operation ${operation.type} 需要重新加载 snapshot`)
+        default:
+          throw new Error(`未知 workbook operation：${String(operation.type)}`)
+      }
+    } finally {
+      applyingRemote = false
+    }
+  }
+
+  return { apply: applyOperation, isApplyingRemote: () => applyingRemote, liveSheetMetadata }
+}

package/src/univer/chunk.ts

@@ -0,0 +1,77 @@
+/**
+ * The engine-chunk contract, declared once (docs/issue/0002 PRD v3.2 §7.2).
+ *
+ * Two bundles have to agree on this shape without importing each other:
+ * `src/univer/entry.ts` builds the ~16MB Univer IIFE, and
+ * `src/client/univer/loader.ts` loads it lazily on first sheet render. Keeping the interface *and* the
+ * `window` global here means a signature change cannot be made on one side only
+ * — which is exactly how the preview's `readOnly` option would otherwise have
+ * been silently dropped by the loader.
+ *
+ * Type-only: this module emits no runtime code, so it is erased from both
+ * bundles and cannot pull Univer into the boot bundle.
+ *
+ * @module dsh-data-table/univer/chunk
+ */
+
+import type { WorkbookFocusRange, WorkbookLocalChange, WorkbookOperation, WorkbookPresencePayload, WorkbookSelectionRange } from '../types.ts'
+
+/** Mounted Univer residency: dispose releases the engine. */
+export interface WorkbookMount {
+  save(): unknown
+  applyOperation(operation: WorkbookOperation): Promise<void>
+  /** Focus one cell range in the active workbook. */
+  focusRange(range: WorkbookFocusRange): boolean
+  /**
+   * Show a different workbook in the same residency (same Univer instance, new
+   * unit). Returns false when the swap was impossible, so the caller can fall
+   * back to a full remount. PRD v3.5 §7.2.
+   */
+  swapWorkbook(next: object, options?: { decoration?: WorkbookDecoration }): boolean
+  dispose(): void
+}
+
+/** Which cells a preview paints, and why (docs/issue/0002 PRD v3.3 §7.2). */
+export type WorkbookDecorationTone = 'add' | 'remove' | 'modify'
+
+export interface WorkbookDecorationCell {
+  sheetRef?: string
+  row: number
+  column: number
+  tone: WorkbookDecorationTone
+}
+
+export interface WorkbookDecoration {
+  cells: WorkbookDecorationCell[]
+  /** Cell to select so the viewport lands on what changed. */
+  focus?: { sheetRef?: string; row: number; column: number }
+}
+
+/**
+ * Mount options forwarded to the engine. `readOnly` mounts a preview residency:
+ * the snapshot is a past Version, so the canvas reports no edits, drops the
+ * editing chrome and turns Univer's workbook-level edit permission off
+ * (PRD v3.2 §7.2). `decoration` is the diff overlay (PRD v3.3 §7.2).
+ */
+export interface WorkbookMountOptions {
+  readOnly?: boolean
+  decoration?: WorkbookDecoration
+}
+
+/** The engine surface the chunk exposes. */
+export interface UniverChunkApi {
+  mountWorkbook(
+    container: HTMLElement,
+    workbookData: object,
+    onDirty?: (change?: WorkbookLocalChange) => void,
+    onPresence?: (presence: WorkbookPresencePayload) => void,
+    options?: WorkbookMountOptions,
+    onSelection?: (ranges: readonly WorkbookSelectionRange[]) => void,
+  ): WorkbookMount
+}
+
+declare global {
+  interface Window {
+    __bestExcelUniver?: UniverChunkApi
+  }
+}

package/src/univer/decoration.ts

@@ -0,0 +1,111 @@
+/**
+ * The diff overlay and the read-only lock (docs/issue/0022 P4, PRD v3.3 §7.2).
+ *
+ * Order matters twice over: the tint is written through `SetStyleCommand`, which
+ * the workbook's editable permission gates, so it has to land **before**
+ * `setEditable(false)`; and the selection has to be made before the lock too, so
+ * stepping a Version moves the viewport onto the cell that changed instead of
+ * leaving the reader to hunt for it.
+ *
+ * Fire-and-forget: `mountWorkbook` returns synchronously and the canvas is usable
+ * immediately — the lock is a frame or two behind (see {@link lockWorkbook}),
+ * and the mutation guard in the engine covers that window.
+ *
+ * The three tints are the contract with `VersionInspectBar`'s legend: the swatch
+ * a reader sees beside `新增 2` is painted with the same hex the engine writes
+ * into the cell.
+ */
+import type { WorkbookDecoration } from './chunk.ts'
+import type { SheetsApi, SheetResolver } from './facade.ts'
+
+/** Tint per change direction; shared with the comparison bar's legend. */
+export const DECORATION_TINT = { add: '#e6f7ee', modify: '#fff5e0', remove: '#fdeceb' } as const
+
+export interface DecorationApplier {
+  /** Paint a diff and, for a read-only residency, lock the workbook. */
+  apply(plan: WorkbookDecoration | undefined): void
+}
+
+/**
+ * Univer's permission service re-creates the workbook's permission points
+ * **after** the mount, with their defaults — so a lock applied at mount is
+ * silently undone, and a preview stayed editable (GUI feedback 2026-09-23:
+ * "why can I still type into a comparison?").
+ *
+ * Measured against the real engine, mounted with `readOnly: true`:
+ *
+ *     t=0     setEditable(false) → canEdit() false   (the lock lands)
+ *     t=100ms canEdit() true                          ← the service re-added it
+ *     t=200ms setEditable(false) → canEdit() false    (and it stays off)
+ *
+ * `WorkbookPermissionService._init` iterates the existing sheet units and calls
+ * `addPermissionPoint` for each point, and `addPermissionPoint` takes the
+ * point's *default* value — `true` for `WorkbookEdit`. That write is what undid
+ * the mount-time lock. It happens once, in the first ~100ms; the lock is
+ * therefore re-asserted a few times over the first second rather than once.
+ *
+ * The lock is Univer's own workbook permission — the mechanism a protected
+ * sheet uses — and with it off the cell editor refuses to open too
+ * (`sheet.operation.set-cell-edit-visible` returns false), so a preview cannot
+ * be typed into at all, not merely have its edits refused on commit.
+ *
+ * Delays rather than animation frames: a frame loop stops while the page is
+ * hidden, and the point of these attempts is to land *after* a write that
+ * happens on Univer's own schedule.
+ */
+const LOCK_RETRY_DELAYS_MS = [0, 150, 400, 900] as const
+
+function lockWorkbook(sheetsApi: SheetsApi): void {
+  const attempt = (index: number): void => {
+    try {
+      sheetsApi.getActiveWorkbook()?.setEditable?.(false)
+    } catch {
+      // Permission point unavailable: the mutation guard in the engine still
+      // refuses to report an edit from a read-only residency.
+      return
+    }
+    const next = index + 1
+    if (next < LOCK_RETRY_DELAYS_MS.length) {
+      setTimeout(() => attempt(next), LOCK_RETRY_DELAYS_MS[next])
+    }
+  }
+  attempt(0)
+}
+
+export function createDecorationApplier(deps: { sheetsApi: SheetsApi; getSheet: SheetResolver; readOnly: boolean }): DecorationApplier {
+  const { sheetsApi, getSheet, readOnly } = deps
+  return {
+    apply: (plan: WorkbookDecoration | undefined): void => {
+      void (async () => {
+        const workbook = sheetsApi.getActiveWorkbook()
+        if (plan !== undefined) {
+          for (const cell of plan.cells) {
+            // Paint every cell the caller sent: which tones exist in the shown
+            // snapshot is the caller's decision, because the same diff has a
+            // different paintable side depending on which Version is on screen.
+            try {
+              await getSheet(cell.sheetRef)?.getRange(cell.row, cell.column)?.setBackgroundColor?.(DECORATION_TINT[cell.tone])
+            } catch {
+              // A cell outside the sheet's bounds: skip it, keep the rest.
+            }
+          }
+        }
+        const focus = plan?.focus
+        if (focus !== undefined && workbook !== null) {
+          try {
+            const sheet = getSheet(focus.sheetRef)
+            const range = sheet?.getRange(focus.row, focus.column)
+            if (sheet !== null && range !== undefined) {
+              const sheetId = sheet.getSheetId?.()
+              if (sheetId !== undefined) workbook.setActiveSheet?.(sheetId)
+              workbook.setActiveRange?.(range)
+            }
+          } catch {
+            // Selection is an affordance, not a correctness requirement.
+          }
+        }
+        if (readOnly) lockWorkbook(sheetsApi)
+      })()
+    },
+  }
+}