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

package/lib/types/univer/apply-operation.js

@@ -0,0 +1,398 @@
+/**
+ * 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.js";
+import { DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, normalizeCellFormula } from "../contract/snapshots.js";
+export function createOperationApplier(deps) {
+    const { sheetsApi, getSheet } = deps;
+    let applyingRemote = false;
+    const liveSheetMetadata = new Map();
+    const coerceAppendValue = (column, value) => {
+        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, payload) => {
+        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) => {
+        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, range, target, style) => {
+        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) => {
+        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 = {};
+                    const clearCells = [];
+                    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/lib/types/univer/chunk.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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/lib/types/univer/chunk.js

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+export {};

package/lib/types/univer/decoration.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const DECORATION_TINT: {
+    readonly add: "#e6f7ee";
+    readonly modify: "#fff5e0";
+    readonly remove: "#fdeceb";
+};
+export interface DecorationApplier {
+    /** Paint a diff and, for a read-only residency, lock the workbook. */
+    apply(plan: WorkbookDecoration | undefined): void;
+}
+export declare function createDecorationApplier(deps: {
+    sheetsApi: SheetsApi;
+    getSheet: SheetResolver;
+    readOnly: boolean;
+}): DecorationApplier;

package/lib/types/univer/decoration.js

@@ -0,0 +1,88 @@
+/** Tint per change direction; shared with the comparison bar's legend. */
+export const DECORATION_TINT = { add: '#e6f7ee', modify: '#fff5e0', remove: '#fdeceb' };
+/**
+ * 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];
+function lockWorkbook(sheetsApi) {
+    const attempt = (index) => {
+        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) {
+    const { sheetsApi, getSheet, readOnly } = deps;
+    return {
+        apply: (plan) => {
+            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);
+            })();
+        },
+    };
+}

package/lib/types/univer/diagnostics.d.ts

@@ -0,0 +1,31 @@
+import type { WorkbookLocalChange, WorkbookPresencePayload } from '../types.ts';
+/** Why the current mutation could not become an incremental cell change. */
+export declare function noteCellMutation(_commandId: string, mapped: boolean, detail?: {
+    reason?: string;
+    keys?: string[];
+}): void;
+/**
+ * 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 declare function publishMutationAttempt(commandId: string, mapped: boolean): void;
+export declare function cellKeysOf(cellValue: unknown): string[];
+/**
+ * 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 declare function toLocalCellChange(commandInfo: {
+    id: string;
+    params?: unknown;
+}): WorkbookLocalChange | undefined;
+/** 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 declare function toPresence(commandInfo: {
+    id: string;
+    params?: unknown;
+}): WorkbookPresencePayload | undefined;