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

package/src/univer/diagnostics.ts

@@ -0,0 +1,136 @@
+/**
+ * Live-canvas diagnostics and command mapping (docs/issue/0022 P4).
+ *
+ * Two jobs that both start from a Univer command: turning it into the small DSH
+ * change contract the Host persists, and leaving a probe behind so a live
+ * workbook can be inspected from the console (`__dshLastCellMutation`). They sit
+ * together because both are "what did Univer just do", and neither decides what
+ * to persist — `contract/operations.ts` decides that.
+ */
+import { normalizeCellFormula } from '../contract/snapshots.ts'
+import type { WorkbookCellUpdate, WorkbookLocalChange, WorkbookPresencePayload } from '../types.ts'
+
+/**
+ * Diagnostic seam for the incremental-save mapping (PRD v3.1 follow-up).
+ *
+ * Cell edits that cannot be expressed as a plain value fall back to a whole
+ * snapshot save, which is correct but ~230 KB per edit. This records why the
+ * last such mutation was not mapped, so the reason can be read from the
+ * browser console instead of guessed:
+ *
+ *     __dshLastCellMutation    // { commandId, mapped, reason?, keys? }
+ */
+let lastCellMutationNote: { reason?: string; keys?: string[] } | undefined
+
+/** Why the current mutation could not become an incremental cell change. */
+export function noteCellMutation(_commandId: string, mapped: boolean, detail: { reason?: string; keys?: string[] } = {}): void {
+  lastCellMutationNote = mapped ? undefined : detail
+}
+
+/**
+ * Publish the outcome of one persisted mutation. This runs for *every*
+ * mutation the workbook persists, so a command id we do not map is still
+ * visible instead of leaving the probe undefined:
+ *
+ *     __dshLastCellMutation    // { commandId, mapped, reason?, keys? }
+ */
+export function publishMutationAttempt(commandId: string, mapped: boolean): void {
+  if (typeof window === 'undefined') return
+  ;(window as unknown as { __dshLastCellMutation?: unknown }).__dshLastCellMutation = {
+    at: new Date().toISOString(),
+    commandId,
+    mapped,
+    ...(mapped ? {} : (lastCellMutationNote ?? { reason: 'command-not-mapped' })),
+  }
+}
+
+export function cellKeysOf(cellValue: unknown): string[] {
+  if (typeof cellValue !== 'object' || cellValue === null) return []
+  const firstRow = Object.values(cellValue as Record<string, unknown>)[0]
+  if (typeof firstRow !== 'object' || firstRow === null) return []
+  const firstCell = Object.values(firstRow as Record<string, unknown>)[0]
+  return typeof firstCell === 'object' && firstCell !== null ? Object.keys(firstCell) : []
+}
+
+/**
+ * Convert Univer's sparse set-range-values mutation into the small DSH edit
+ * contract. Formatting, pasted rich objects, and structural commands return
+ * undefined so the browser deliberately falls back to a full snapshot save.
+ */
+export function toLocalCellChange(commandInfo: { id: string; params?: unknown }): WorkbookLocalChange | undefined {
+  if (commandInfo.id !== 'sheet.mutation.set-range-values') return undefined
+  if (typeof commandInfo.params !== 'object' || commandInfo.params === null) {
+    noteCellMutation(commandInfo.id, false, { reason: 'params-missing' })
+    return undefined
+  }
+  const params = commandInfo.params as Record<string, unknown>
+  if (typeof params.subUnitId !== 'string' || typeof params.cellValue !== 'object' || params.cellValue === null) {
+    noteCellMutation(commandInfo.id, false, { reason: 'cellValue-missing', keys: cellKeysOf(params.cellValue) })
+    return undefined
+  }
+  const cells: WorkbookCellUpdate[] = []
+  const rows = params.cellValue as Record<string, unknown>
+  for (const [rowKey, rowValue] of Object.entries(rows)) {
+    const row = Number(rowKey)
+    if (!Number.isInteger(row) || typeof rowValue !== 'object' || rowValue === null) return undefined
+    for (const [columnKey, cellValue] of Object.entries(rowValue as Record<string, unknown>)) {
+      const column = Number(columnKey)
+      if (!Number.isInteger(column)) {
+        noteCellMutation(commandInfo.id, false, { reason: 'bad-column-key', keys: cellKeysOf(params.cellValue) })
+        return undefined
+      }
+      if (cellValue === null) {
+        cells.push({ row, column, value: null })
+        continue
+      }
+      if (typeof cellValue !== 'object' || Array.isArray(cellValue)) {
+        noteCellMutation(commandInfo.id, false, { reason: 'cell-not-object', keys: cellKeysOf(params.cellValue) })
+        return undefined
+      }
+      const cell = cellValue as Record<string, unknown>
+      const unsupportedKeys = Object.keys(cell).filter(key => !['v', 'f', 't'].includes(key))
+      if (unsupportedKeys.length > 0) {
+        noteCellMutation(commandInfo.id, false, { reason: 'unsupported-cell-keys', keys: Object.keys(cell) })
+        return undefined
+      }
+      const value = cell.v
+      if (value !== undefined && value !== null && typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') return undefined
+      const formula = normalizeCellFormula(cell.f)
+      cells.push({ row, column, value: value === undefined ? null : value, ...(formula === undefined ? {} : { formula }) })
+    }
+  }
+  if (cells.length === 0) {
+    noteCellMutation(commandInfo.id, false, { reason: 'no-cells', keys: cellKeysOf(params.cellValue) })
+    return undefined
+  }
+  noteCellMutation(commandInfo.id, true)
+  return { type: 'update_cells', payload: { sheetId: params.subUnitId, cells } }
+}
+
+/** Convert selection/focus commands into a compact ephemeral presence event.
+ * Unknown commands are intentionally ignored so UI internals never become
+ * durable edits or high-volume network traffic. */
+export function toPresence(commandInfo: { id: string; params?: unknown }): WorkbookPresencePayload | undefined {
+  const commandId = commandInfo.id.toLowerCase()
+  let kind: WorkbookPresencePayload['kind'] | undefined
+  if (commandId.includes('selection') || commandId.includes('set-selections')) kind = 'selection'
+  else if (commandId.includes('activate') || commandId.includes('active') || commandId.includes('focus') || commandId.includes('current-sheet')) kind = 'active-sheet'
+  else return undefined
+  const params = typeof commandInfo.params === 'object' && commandInfo.params !== null
+    ? commandInfo.params as Record<string, unknown>
+    : {}
+  const payload: Record<string, unknown> = { commandId }
+  for (const key of ['subUnitId', 'unitId', 'sheetId']) {
+    if (typeof params[key] === 'string') payload[key] = params[key]
+  }
+  const range = params.range
+  if (typeof range === 'object' && range !== null && !Array.isArray(range)) {
+    const candidate = range as Record<string, unknown>
+    const safeRange: Record<string, number> = {}
+    for (const key of ['startRow', 'startColumn', 'endRow', 'endColumn']) {
+      if (typeof candidate[key] === 'number' && Number.isFinite(candidate[key])) safeRange[key] = candidate[key] as number
+    }
+    if (Object.keys(safeRange).length > 0) payload.range = safeRange
+  }
+  return { kind, payload }
+}

package/src/univer/engine.ts

@@ -0,0 +1,370 @@
+/**
+ * Heavy Univer engine for dsh-data-table: the sheets-core preset
+ * mount plus the free feature presets (filter/sort/find-replace/conditional
+ * formatting/data validation/drawing/hyper-link/note/thread-comment/table)
+ * and the Univer-native CSV/Excel export plugin. Bundled as a self-contained IIFE chunk
+ * (`lib/univer-client.js`) served on demand by the node half — the ~16MB
+ * Univer graph never enters the boot bundle.
+ * @module dsh-data-table/univer-engine
+ */
+
+import {
+  createUniver,
+  defaultTheme,
+  LocaleType,
+  merge,
+  UniverInstanceType,
+} from '@univerjs/presets'
+// The es-path values carry runtime code; the honest types live in the types tree.
+import { UniverSheetsCorePreset } from '@univerjs/presets/lib/es/preset-sheets-core/index.js'
+import { UniverSheetsFilterPreset } from '@univerjs/presets/lib/es/preset-sheets-filter/index.js'
+import { UniverSheetsSortPreset } from '@univerjs/presets/lib/es/preset-sheets-sort/index.js'
+import { UniverSheetsFindReplacePreset } from '@univerjs/presets/lib/es/preset-sheets-find-replace/index.js'
+import { UniverSheetsConditionalFormattingPreset } from '@univerjs/presets/lib/es/preset-sheets-conditional-formatting/index.js'
+import { UniverSheetsDataValidationPreset } from '@univerjs/presets/lib/es/preset-sheets-data-validation/index.js'
+import { UniverSheetsDrawingPreset } from '@univerjs/presets/lib/es/preset-sheets-drawing/index.js'
+import { UniverSheetsHyperLinkPreset } from '@univerjs/presets/lib/es/preset-sheets-hyper-link/index.js'
+import { UniverSheetsNotePreset } from '@univerjs/presets/lib/es/preset-sheets-note/index.js'
+import { UniverSheetsThreadCommentPreset } from '@univerjs/presets/lib/es/preset-sheets-thread-comment/index.js'
+import { UniverSheetsTablePreset } from '@univerjs/presets/lib/es/preset-sheets-table/index.js'
+import { UniverSheetsCrosshairHighlightPlugin } from '@univerjs/sheets-crosshair-highlight'
+import type {
+  WorkbookDecoration,
+  WorkbookMount,
+  WorkbookMountOptions,
+} from './chunk.ts'
+
+// Re-exported so `univer/entry.ts` and the loader keep one name for the mount
+// contract, which lives in `univer/chunk.ts` beside the loader side.
+export type { WorkbookDecoration, WorkbookDecorationCell, WorkbookDecorationTone, WorkbookMount, WorkbookMountOptions } from './chunk.ts'
+import coreZhCN from '@univerjs/presets/lib/es/preset-sheets-core/locales/zh-CN.js'
+import coreEnUS from '@univerjs/presets/lib/es/preset-sheets-core/locales/en-US.js'
+import filterZhCN from '@univerjs/presets/lib/es/preset-sheets-filter/locales/zh-CN.js'
+import filterEnUS from '@univerjs/presets/lib/es/preset-sheets-filter/locales/en-US.js'
+import sortZhCN from '@univerjs/presets/lib/es/preset-sheets-sort/locales/zh-CN.js'
+import sortEnUS from '@univerjs/presets/lib/es/preset-sheets-sort/locales/en-US.js'
+import findReplaceZhCN from '@univerjs/presets/lib/es/preset-sheets-find-replace/locales/zh-CN.js'
+import findReplaceEnUS from '@univerjs/presets/lib/es/preset-sheets-find-replace/locales/en-US.js'
+import condFmtZhCN from '@univerjs/presets/lib/es/preset-sheets-conditional-formatting/locales/zh-CN.js'
+import condFmtEnUS from '@univerjs/presets/lib/es/preset-sheets-conditional-formatting/locales/en-US.js'
+import dataValZhCN from '@univerjs/presets/lib/es/preset-sheets-data-validation/locales/zh-CN.js'
+import dataValEnUS from '@univerjs/presets/lib/es/preset-sheets-data-validation/locales/en-US.js'
+import drawingZhCN from '@univerjs/presets/lib/es/preset-sheets-drawing/locales/zh-CN.js'
+import drawingEnUS from '@univerjs/presets/lib/es/preset-sheets-drawing/locales/en-US.js'
+import hyperLinkZhCN from '@univerjs/presets/lib/es/preset-sheets-hyper-link/locales/zh-CN.js'
+import hyperLinkEnUS from '@univerjs/presets/lib/es/preset-sheets-hyper-link/locales/en-US.js'
+import noteZhCN from '@univerjs/presets/lib/es/preset-sheets-note/locales/zh-CN.js'
+import noteEnUS from '@univerjs/presets/lib/es/preset-sheets-note/locales/en-US.js'
+import threadZhCN from '@univerjs/presets/lib/es/preset-sheets-thread-comment/locales/zh-CN.js'
+import threadEnUS from '@univerjs/presets/lib/es/preset-sheets-thread-comment/locales/en-US.js'
+import tableZhCN from '@univerjs/presets/lib/es/preset-sheets-table/locales/zh-CN.js'
+import tableEnUS from '@univerjs/presets/lib/es/preset-sheets-table/locales/en-US.js'
+import crosshairZhCN from '@univerjs/sheets-crosshair-highlight/locale/zh-CN'
+import crosshairEnUS from '@univerjs/sheets-crosshair-highlight/locale/en-US'
+// Univer ships its styles as separate artifacts; without them the workbench
+// renders unstyled (toolbar stacked vertically). The client build turns these
+// imports into inlined style injections.
+import '@univerjs/presets/lib/styles/preset-sheets-core.css'
+import '@univerjs/presets/lib/styles/preset-sheets-filter.css'
+import '@univerjs/presets/lib/styles/preset-sheets-sort.css'
+import '@univerjs/presets/lib/styles/preset-sheets-find-replace.css'
+import '@univerjs/presets/lib/styles/preset-sheets-conditional-formatting.css'
+import '@univerjs/presets/lib/styles/preset-sheets-data-validation.css'
+import '@univerjs/presets/lib/styles/preset-sheets-drawing.css'
+import '@univerjs/presets/lib/styles/preset-sheets-hyper-link.css'
+import '@univerjs/presets/lib/styles/preset-sheets-note.css'
+import '@univerjs/presets/lib/styles/preset-sheets-thread-comment.css'
+import '@univerjs/presets/lib/styles/preset-sheets-table.css'
+import '@univerjs/sheets-crosshair-highlight/lib/index.css'
+import './overrides.css'
+import type {
+  SheetColumn,
+  WorkbookCellStyle,
+  WorkbookCellUpdate,
+  WorkbookLocalChange,
+  WorkbookOperation,
+  WorkbookOperationPayload,
+  WorkbookFocusRange,
+  WorkbookRange,
+  WorkbookPresencePayload,
+  WorkbookSelectionRange,
+} from '../types.ts'
+import { DataSheetExportPlugin } from './plugins/export.ts'
+import { DataSheetCollaborationPlugin } from './plugins/collaboration.ts'
+import { DataSheetHistoryPlugin } from './plugins/history.ts'
+import { getInstalledFontConfigs, withDefaultSheetFont } from './fonts.ts'
+import { shouldPersistUniverMutation } from '../contract/operations.ts'
+import { publishMutationAttempt, toLocalCellChange, toPresence } from './diagnostics.ts'
+import { DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS } from '../contract/snapshots.ts'
+import { createDecorationApplier } from './decoration.ts'
+import { createOperationApplier } from './apply-operation.ts'
+import type { SheetsApi, SheetResolver } from './facade.ts'
+
+/** Default sheet extent (Univer's own default), so data lands on a full-size grid. */
+
+/**
+ * Load marker + default probe value.
+ *
+ * The engine chunk is a classic script the browser may still serve from cache,
+ * so "is my bundle current?" was impossible to answer from the console. These
+ * two globals are set as soon as the chunk evaluates:
+ *
+ *     __dshDataSheetEngine     // { version, loadedAt } — undefined means a stale chunk
+ *     __dshLastCellMutation    // { reason: 'no-persisted-mutation-yet' } until you edit
+ */
+if (typeof window !== 'undefined') {
+  const win = window as unknown as { __dshDataSheetEngine?: unknown; __dshLastCellMutation?: unknown }
+  win.__dshDataSheetEngine = { version: 'v3.2', loadedAt: new Date().toISOString() }
+  // One line, so "which engine build is this page running?" is answered by the
+  // console itself instead of a hand-typed global.
+  console.info('[data-sheet] Univer engine chunk v3.2 loaded · probe: __dshLastCellMutation')
+  win.__dshLastCellMutation = { reason: 'no-persisted-mutation-yet' }
+}
+
+
+/**
+ * Mount one resident Univer engine into a container; the container must be in
+ * the DOM and the chunk must already be loaded. The workbook data is an
+ * Univer snapshot (IWorkbookData-shaped) that the residency renders; `save()`
+ * returns the current snapshot for the client half to persist. The client
+ * batches ten durable user steps (or flushes on Ctrl/Cmd+S) into one Version.
+ */
+export function mountWorkbook(container: HTMLElement, workbookData: object, onDirty?: (change?: WorkbookLocalChange) => void, onPresence?: (presence: WorkbookPresencePayload) => void, options: WorkbookMountOptions = {}, onSelection?: (ranges: readonly WorkbookSelectionRange[]) => void): WorkbookMount {
+  const readOnly = options.readOnly === true
+  const decoration = options.decoration
+  const installedFontConfigs = getInstalledFontConfigs()
+  let openHistory: (() => void) | undefined
+  let refreshSelection = (): void => {}
+  const onUniverMutation = (commandInfo: { id: string; params?: unknown }, options?: { onlyLocal?: boolean; fromChangeset?: boolean; fromCollab?: boolean }): void => {
+    if (applier.isApplyingRemote() || options?.onlyLocal || options?.fromChangeset || options?.fromCollab) return
+    if (!shouldPersistUniverMutation(commandInfo.id)) {
+      const presence = toPresence(commandInfo)
+      // A preview is not somebody editing: it publishes no editing presence,
+      // so peers do not see a phantom collaborator.
+      if (presence !== undefined && !readOnly) onPresence?.(presence)
+      return
+    }
+    // Belt and braces with `setEditable(false)` below: even a command that
+    // slipped past the permission interceptor is never reported as a change,
+    // so a preview can never fork a Version.
+    if (readOnly) return
+    onPresence?.({ kind: 'editing', payload: { commandId: commandInfo.id } })
+    const change = toLocalCellChange(commandInfo)
+    publishMutationAttempt(commandInfo.id, change !== undefined)
+    onDirty?.(change)
+    refreshSelection()
+  }
+  const { univer, univerAPI } = createUniver({    // The sheets-core preset renders nothing (silently) without the locale
+    // packs and theme; keep both in sync with the official 0.25 usage.
+    locale: LocaleType.ZH_CN,
+    locales: {
+      zhCN: merge({}, coreZhCN, filterZhCN, sortZhCN, findReplaceZhCN, condFmtZhCN, dataValZhCN, drawingZhCN, hyperLinkZhCN, noteZhCN, threadZhCN, tableZhCN, crosshairZhCN),
+      enUS: merge({}, coreEnUS, filterEnUS, sortEnUS, findReplaceEnUS, condFmtEnUS, dataValEnUS, drawingEnUS, hyperLinkEnUS, noteEnUS, threadEnUS, tableEnUS, crosshairEnUS),
+    },
+    theme: defaultTheme,
+    plugins: [
+      DataSheetExportPlugin,
+      [DataSheetHistoryPlugin, { onOpenHistory: () => openHistory?.() }],
+      [DataSheetCollaborationPlugin, { onMutation: onUniverMutation }],
+      UniverSheetsCrosshairHighlightPlugin,
+    ],
+    presets: [
+      UniverSheetsCorePreset({
+        container,
+        header: true,
+        // A preview shows history: the editing chrome would only invite edits
+        // that cannot be saved (PRD v3.3 §7.2). Read-only mode keeps the grid,
+        // the headers and the sheet tabs, and drops the rest.
+        toolbar: !readOnly,
+        formulaBar: !readOnly,
+        // (`disableEdit` is deliberately *not* passed here: this preset
+        // destructures a fixed key set and would drop it silently. It is not
+        // needed either — with the workbook permission off, the cell editor
+        // refuses to open, measured.)
+        statusBarStatistic: true,
+        // The footer carries the sheet tabs. A past Version still has several
+        // sheets, so switching between them is navigation and must stay
+        // available in a read-only view (GUI feedback 2026-09-19).
+        footer: true,
+        contextMenu: !readOnly,
+        // Register custom families during UI initialization so they are
+        // present in the font dropdown (addFonts alone is too late for the
+        // initial font-family component in this Univer version).
+        customFontFamily: {
+          list: installedFontConfigs,
+          override: true,
+        },
+      }),
+      // Free feature presets (mirrors the best_excel plugin set). Datasheet
+      // collaboration is provided by its own dependency-free adapter above;
+      // the commercial Univer collaboration preset is intentionally unused.
+      UniverSheetsFilterPreset(),
+      UniverSheetsSortPreset(),
+      UniverSheetsFindReplacePreset(),
+      UniverSheetsConditionalFormattingPreset(),
+      UniverSheetsDataValidationPreset(),
+      UniverSheetsDrawingPreset(),
+      UniverSheetsHyperLinkPreset(),
+      UniverSheetsNotePreset(),
+      UniverSheetsThreadCommentPreset(),
+      UniverSheetsTablePreset(),
+    ],
+  })
+  // Univer does not download these fonts; the browser uses them when the
+  // corresponding family is installed on the user's machine.
+  univer.createUnit(UniverInstanceType.UNIVER_SHEET, withDefaultSheetFont(workbookData))
+  // Debug seam: mounted engines by container, for live workbook inspection.
+  {
+    const win = window as unknown as { __bestExcelDebugMounts?: Array<{ container: HTMLElement; api: unknown }> }
+    win.__bestExcelDebugMounts = win.__bestExcelDebugMounts ?? []
+    win.__bestExcelDebugMounts.push({ container, api: univerAPI })
+  }
+  // The sheets facade augments FUniver with the workbook API; the core type
+  // lacks it, so the engine views the facade structurally (see `facade.ts`).
+  const sheetsApi = univerAPI as unknown as SheetsApi
+  const getSheet: SheetResolver = (sheetRef) => {
+    const workbook = sheetsApi.getActiveWorkbook()
+    if (workbook === null) return null
+    if (sheetRef !== undefined) return workbook.getSheetBySheetId(sheetRef) ?? workbook.getSheetByName(sheetRef)
+    return workbook.getSheetBySheetId('sheet1') ?? null
+  }
+
+  let selectionSubscription: { dispose(): void } | undefined
+  let currentSelectionRanges: Array<WorkbookRange & { sheetId?: string }> = []
+  const projectSelections = (ranges: readonly (WorkbookRange & { sheetId?: string })[]): WorkbookSelectionRange[] => {
+    const workbook = sheetsApi.getActiveWorkbook()
+    if (workbook === null) return []
+    const activeSheetId = workbook.getActiveSheet?.()?.getSheetId?.()
+    const projected: WorkbookSelectionRange[] = []
+    for (const range of ranges.slice(0, 40)) {
+      const sheetId = range.sheetId ?? activeSheetId
+      if (sheetId === undefined) continue
+      const sheet = workbook.getSheetBySheetId(sheetId)
+      if (sheet === null) continue
+      const startRow = Math.max(0, Math.floor(range.startRow))
+      const startColumn = Math.max(0, Math.floor(range.startColumn))
+      const endRow = Math.max(startRow, Math.floor(range.endRow))
+      const endColumn = Math.max(startColumn, Math.floor(range.endColumn))
+      const values = sheet.getRange(
+        startRow,
+        startColumn,
+        Math.min(endRow - startRow + 1, 10),
+        Math.min(endColumn - startColumn + 1, 20),
+      ).getValues?.() ?? []
+      projected.push({
+        sheetId,
+        sheetName: sheet.getSheetName?.() ?? sheetId,
+        startRow,
+        startColumn,
+        endRow,
+        endColumn,
+        values,
+      })
+    }
+    return projected
+  }
+  const publishSelections = (ranges: readonly (WorkbookRange & { sheetId?: string })[]): void => {
+    currentSelectionRanges = [...ranges]
+    onSelection?.(projectSelections(currentSelectionRanges))
+  }
+  refreshSelection = (): void => {
+    if (currentSelectionRanges.length > 0) onSelection?.(projectSelections(currentSelectionRanges))
+  }
+  const bindSelectionWatcher = (): void => {
+    selectionSubscription?.dispose()
+    selectionSubscription = undefined
+    currentSelectionRanges = []
+    onSelection?.([])
+    const workbook = sheetsApi.getActiveWorkbook()
+    if (workbook?.onSelectionChange === undefined) return
+    selectionSubscription = workbook.onSelectionChange(ranges => {
+      if (sheetsApi.getActiveWorkbook()?.getId() !== workbook.getId()) return
+      publishSelections(ranges)
+    })
+  }
+  bindSelectionWatcher()
+
+
+  /**
+   * Show a different workbook **without rebuilding Univer** (PRD v3.5 §7.2).
+   *
+   * Switching the inspected Version used to change the canvas key, which
+   * unmounted the residency and called `createUniver` again — re-registering
+   * every plugin and rebuilding the whole DI graph for a change that is only
+   * "different cells". Swapping the *unit* on the same engine keeps the grid,
+   * the sheet tabs and the scroll position, and removes the re-init cost.
+   *
+   * A fresh unit also means the previous Version's diff tint disappears with
+   * it, so there is nothing to un-paint.
+   */
+  const decoration_ = createDecorationApplier({ sheetsApi, getSheet, readOnly })
+  // Paint on the **mount** path too, not only in `swapWorkbook`. Entering inspect
+  // remounts the canvas (`preview === null` means there is no residency to swap),
+  // so the mount is the *first* preview a reader ever sees. Applying the plan
+  // only when swapping dropped both the diff tint and the read-only lock on that
+  // first look — the cells were counted in the bar but nothing was painted, and
+  // the unit stayed editable. Restores the pre-split behaviour, where the mount
+  // called the same thing (`if (readOnly || decoration !== undefined) apply…`).
+  if (readOnly || decoration !== undefined) decoration_.apply(decoration)
+  const applier = createOperationApplier({ sheetsApi, getSheet })
+
+  const swapWorkbook = (next: object, options: { decoration?: WorkbookDecoration } = {}): boolean => {
+    const previousId = sheetsApi.getActiveWorkbook()?.getId()
+    try {
+      univer.createUnit(UniverInstanceType.UNIVER_SHEET, withDefaultSheetFont(next))
+    } catch {
+      return false
+    }
+    bindSelectionWatcher()
+    decoration_.apply(options.decoration)
+    if (previousId !== undefined) {
+      try {
+        sheetsApi.disposeUnit?.(previousId)
+      } catch {
+        // A unit that refuses to dispose is a leak, not a broken canvas.
+      }
+    }
+    return true
+  }
+
+  return {
+    swapWorkbook,
+    save: () => {
+      const wb = sheetsApi.getActiveWorkbook()
+      if (wb === null) return workbookData
+      const snapshot = wb.getSnapshot()
+      if (typeof snapshot === 'object' && snapshot !== null && typeof (snapshot as { sheets?: unknown }).sheets === 'object') {
+        const sheets = (snapshot as { sheets: Record<string, Record<string, unknown>> }).sheets
+        for (const [sheetId, meta] of applier.liveSheetMetadata.entries()) {
+          const sheet = sheets[sheetId]
+          if (sheet !== undefined) sheet.dataSheetMeta = meta
+        }
+      }
+      return snapshot
+    },
+    applyOperation: applier.apply,
+    focusRange: (target: WorkbookFocusRange): boolean => {
+      const workbook = sheetsApi.getActiveWorkbook()
+      const sheet = workbook?.getSheetBySheetId(target.sheetId)
+      if (workbook === null || workbook === undefined || sheet === null || sheet === undefined || workbook.setActiveRange === undefined) return false
+      workbook.setActiveSheet?.(sheet)
+      const range = sheet.getRange(
+        target.startRow,
+        target.startColumn,
+        target.endRow - target.startRow + 1,
+        target.endColumn - target.startColumn + 1,
+      )
+      workbook.setActiveRange(range)
+      return true
+    },
+    dispose: () => {
+      selectionSubscription?.dispose()
+      selectionSubscription = undefined
+      univer.dispose()
+      const win = window as unknown as { __bestExcelDebugMounts?: Array<{ container: HTMLElement; api: unknown }> }
+      if (win.__bestExcelDebugMounts !== undefined) {
+        win.__bestExcelDebugMounts = win.__bestExcelDebugMounts.filter(entry => entry.container !== container)
+      }
+    },
+  }
+}

package/src/univer/entry.ts

@@ -0,0 +1,14 @@
+/**
+ * Chunk entry for dsh-data-table. Built as a self-contained IIFE
+ * (`lib/univer-client.js`, Univer fully inlined) and loaded as a classic
+ * script on first sheet render; it hands the engine surface to the client
+ * half through a global so the ~16MB graph never enters the boot bundle.
+ * @module dsh-data-table/univer/entry
+ */
+
+import type { UniverChunkApi } from './chunk.ts'
+import { mountWorkbook } from './engine.ts'
+
+// The interface and the `window` global live in ./chunk.ts so the loader
+// in the client bundle cannot drift from the chunk it loads.
+window.__bestExcelUniver = { mountWorkbook } satisfies UniverChunkApi

package/src/univer/facade.ts

@@ -0,0 +1,91 @@
+/**
+ * The Univer facade surface this adapter actually uses (docs/issue/0022 P4).
+ *
+ * The sheets facade augments `FUniver` with `getActiveWorkbook`/`getSnapshot`,
+ * which the core type does not declare, so the engine views it structurally. It
+ * is declared once here because three modules need the same view of it —
+ * decoration, the operation applier and the engine — and three copies would
+ * drift the moment one of them used a facade method the others did not declare.
+ */
+import type { WorkbookRange } from '../types.ts'
+
+export interface UniverRange {
+  getValue?(): unknown
+  getValues?(): unknown[][]
+  setValue(value: unknown): unknown
+  clearContent(): unknown
+  setValues(value: unknown): unknown
+  getRange?(): WorkbookRange
+  /** Tint one cell; the diff overlay's only painting primitive. */
+  setBackgroundColor?(color: string): unknown | Promise<unknown>
+  setFontColor?(color: string): unknown
+  setFontFamily?(family: string): unknown
+  setFontSize?(size: number): unknown
+  setFontWeight?(weight: 'bold' | 'normal' | null): unknown
+  setFontStyle?(style: 'italic' | 'normal' | null): unknown
+  setFontLine?(line: 'underline' | 'line-through' | 'none' | null): unknown
+  setHorizontalAlignment?(alignment: 'left' | 'center' | 'normal'): unknown
+  setVerticalAlignment?(alignment: 'top' | 'middle' | 'bottom'): unknown
+  setTextRotation?(rotation: number): unknown
+  sort?(column: number | { column: number; ascending: boolean }): unknown
+  merge?(options?: { defaultMerge?: boolean; isForceMerge?: boolean }): unknown
+  breakApart?(): unknown
+  /** 0 = shift cells left, 1 = shift cells up (Univer facade enum). */
+  deleteCells?: (direction: 0 | 1) => unknown
+  setHyperLink?(url: string, label?: string): Promise<boolean>
+  cancelHyperLink?(): boolean
+}
+
+export interface UniverSheet {
+  getSheetId?: () => string
+  getSheetName?: () => string
+  getRange(row: number, column: number, numRows?: number, numColumns?: number): UniverRange
+  deleteRows?: (rowPosition: number, howMany?: number) => unknown
+  insertRows?: (rowIndex: number, numRows?: number) => unknown
+  deleteColumns?: (columnPosition: number, howMany?: number) => unknown
+  insertColumns?: (columnIndex: number, numColumns?: number) => unknown
+  setName?: (name: string) => unknown
+  setColumnWidth?: (columnPosition: number, width: number) => unknown
+  setRowHeight?: (rowPosition: number, height: number) => unknown
+  setFreeze?: (freeze: { startRow: number; startColumn: number; xSplit: number; ySplit: number }) => unknown
+  cancelFreeze?: () => unknown
+  getLastRow?: () => number
+  getMaxColumns?: () => number
+  getMaxRows?: () => number
+  setColumnCount?: (count: number) => unknown
+  setRowCount?: (count: number) => unknown
+}
+
+export interface UniverWorkbook {
+  getId(): string
+  getSnapshot(): unknown
+  getSheetBySheetId(sheetId: string): UniverSheet | null
+  getSheetByName(name: string): UniverSheet | null
+  getActiveSheet?(): UniverSheet | null
+  onSelectionChange?(listener: (ranges: readonly (WorkbookRange & { sheetId?: string })[]) => void): { dispose(): void }
+  create(name: string, rows: number, columns: number, options?: { sheet?: { id?: string } }): unknown
+  deleteSheet?(sheet: string | UniverSheet): unknown
+  /** Workbook-level edit permission (docs/issue/0002 PRD v3.2 §7.2). */
+  setEditable?(value: boolean): unknown
+  /**
+   * The permission facade behind that call, for *reading back* what was set.
+   * `canEdit()` is the only way to tell whether the lock actually landed — see
+   * `lockWorkbook` in `decoration.ts` for why that question is not rhetorical.
+   */
+  getWorkbookPermission?(): { canEdit?(): boolean } | null
+  /** Select a range; the facade scrolls the active range into view. */
+  setActiveRange?(range: unknown): unknown
+  /** Activate a sheet before selecting a range on it. */
+  setActiveSheet?(sheet: unknown): unknown
+}
+
+/** The facade's workbook-scoped API, as this adapter uses it. */
+export interface SheetsApi {
+  /** Dispose a unit without tearing the engine down (used by `swapWorkbook`). */
+  disposeUnit?(unitId: string): boolean
+  getActiveWorkbook(): UniverWorkbook | null
+  executeCommand(id: string, params: unknown, options?: unknown): Promise<unknown>
+}
+
+/** Resolve a sheet by id, by name, or the default first sheet. */
+export type SheetResolver = (sheetRef: string | undefined) => UniverSheet | null