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

package/lib/types/univer/plugins/export.js

@@ -0,0 +1,246 @@
+/**
+ * Univer-side export plugin for dsh-data-table.
+ *
+ * This follows Univer's normal plugin shape: commands are registered with
+ * ICommandService. The browser-facing exporter stays a small adapter over
+ * the live Workbook model, so menu actions always export the current
+ * in-memory edits.
+ * @module dsh-data-table/univer-export-plugin
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { CommandType, Inject, ICommandService, IUniverInstanceService, Injector, Plugin, UniverInstanceType, } from '@univerjs/presets';
+import { downloadBlob, downloadWorkbookCsv, downloadWorkbookXlsx, readWorkbookXlsx } from "../../xlsx-export.js";
+import { UNIVER_PLUGIN_VERSION } from "./version.js";
+function dataSheetAssetPath(path) {
+    const transport = globalThis.__DSH_TRANSPORT__;
+    return transport?.ownsHost === true
+        ? `/api/data-sheet?path=${encodeURIComponent(path)}`
+        : path;
+}
+export const EXPORT_CSV_COMMAND_ID = 'dsh.data-sheet.export-csv';
+export const EXPORT_XLSX_COMMAND_ID = 'dsh.data-sheet.export-xlsx';
+export const IMPORT_XLSX_COMMAND_ID = 'dsh.data-sheet.import-xlsx';
+/** Univer plugin that owns the datasheet export commands and DSH menu bridge. */
+let DataSheetExportPlugin = class DataSheetExportPlugin extends Plugin {
+    _injector;
+    _commandService;
+    _univerInstanceService;
+    static pluginName = 'dsh.data-sheet.export';
+    static packageName = 'dsh-data-table';
+    static version = UNIVER_PLUGIN_VERSION;
+    static type = UniverInstanceType.UNIVER_SHEET;
+    constructor(_config, _injector, _commandService, _univerInstanceService) {
+        super();
+        this._injector = _injector;
+        this._commandService = _commandService;
+        this._univerInstanceService = _univerInstanceService;
+    }
+    onStarting() {
+        this.disposeWithMe(this._commandService.registerCommand({
+            id: EXPORT_CSV_COMMAND_ID,
+            type: CommandType.COMMAND,
+            handler: () => this.export('csv'),
+        }));
+        this.disposeWithMe(this._commandService.registerCommand({
+            id: EXPORT_XLSX_COMMAND_ID,
+            type: CommandType.COMMAND,
+            handler: () => this.export('xlsx'),
+        }));
+        this.disposeWithMe(this._commandService.registerCommand({
+            id: IMPORT_XLSX_COMMAND_ID,
+            type: CommandType.COMMAND,
+            handler: () => {
+                this.importFile('xlsx');
+                return true;
+            },
+        }));
+        // The compact DSH header owns import/export. Keep the bridge event-based
+        // so the React shell does not depend on Univer's private Injector or
+        // command service implementation.
+        const onExportCsv = () => { void this.export('csv'); };
+        const onExportXlsx = () => { void this.export('xlsx'); };
+        const onExportJson = () => { void this.export('json'); };
+        const onImportXlsx = () => { this.importFile('xlsx'); };
+        // The project chooser read the file's bytes on the Host side; parsing is the
+        // same pipeline, so it enters here rather than in a second implementation.
+        const onImportBytes = (event) => {
+            const detail = event.detail;
+            if (detail?.data === undefined)
+                return;
+            void this.importBuffer(detail.data, detail.name ?? '导入文件');
+        };
+        document.addEventListener('data-sheet:import-bytes', onImportBytes);
+        const onImportCsv = () => { this.importFile('csv'); };
+        window.addEventListener('data-sheet:request-export-csv', onExportCsv);
+        window.addEventListener('data-sheet:request-export-xlsx', onExportXlsx);
+        window.addEventListener('data-sheet:request-export-json', onExportJson);
+        window.addEventListener('data-sheet:request-import-xlsx', onImportXlsx);
+        window.addEventListener('data-sheet:request-import-csv', onImportCsv);
+        window.addEventListener('data-sheet:import-bytes', onImportBytes);
+        this.disposeWithMe({
+            dispose: () => {
+                window.removeEventListener('data-sheet:request-export-csv', onExportCsv);
+                window.removeEventListener('data-sheet:request-export-xlsx', onExportXlsx);
+                window.removeEventListener('data-sheet:request-export-json', onExportJson);
+                window.removeEventListener('data-sheet:request-import-xlsx', onImportXlsx);
+                window.removeEventListener('data-sheet:request-import-csv', onImportCsv);
+                window.removeEventListener('data-sheet:import-bytes', onImportBytes);
+            },
+        });
+    }
+    async export(format) {
+        const workbook = this._univerInstanceService.getCurrentUnitOfType(UniverInstanceType.UNIVER_SHEET);
+        if (workbook == null)
+            return false;
+        const snapshot = workbook.getSnapshot();
+        const filename = snapshotWorkbookName(snapshot) || workbook.name || 'workbook';
+        if (format === 'json') {
+            // The workbook snapshot is already the plugin's own persistence format,
+            // so a JSON export is a lossless, round-trippable dump.
+            downloadBlob(new Blob([JSON.stringify(snapshot, null, 2)], { type: 'application/json;charset=utf-8' }), `${safeFilename(filename)}.json`);
+            return true;
+        }
+        try {
+            const result = await exportInWorker(format, snapshot);
+            if (result === null)
+                return false;
+            if (format === 'csv') {
+                downloadBlob(new Blob([result], { type: 'text/csv;charset=utf-8' }), `${safeFilename(filename)}.csv`);
+            }
+            else {
+                downloadBlob(new Blob([result], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }), `${safeFilename(filename)}.xlsx`);
+            }
+        }
+        catch {
+            // A server started before the worker route existed, or a restricted
+            // browser, still gets a functional export through the synchronous path.
+            if (format === 'csv')
+                downloadWorkbookCsv(snapshot, filename);
+            else
+                downloadWorkbookXlsx(snapshot, filename);
+        }
+        return true;
+    }
+    importFile(format) {
+        const input = document.createElement('input');
+        input.type = 'file';
+        input.accept = format === 'csv'
+            ? '.csv,text/csv'
+            : '.xlsx,.xls,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-excel';
+        input.addEventListener('change', () => {
+            const file = input.files?.[0];
+            if (file === undefined)
+                return;
+            if (file.size > 25 * 1024 * 1024) {
+                window.dispatchEvent(new CustomEvent('data-sheet:import-error', { detail: { message: `${format === 'csv' ? 'CSV' : 'Excel'} 文件过大（最大 25 MB）` } }));
+                return;
+            }
+            void file.arrayBuffer().then(data => this.importBuffer(data, file.name));
+        });
+        input.click();
+    }
+    /**
+     * Parse one buffer and hand the workbook to the panel.
+     *
+     * Shared by both ways in — the OS file dialog and the project chooser, which
+     * reads the bytes over HTTP because a browser cannot open a path. Everything
+     * after the bytes arrive is one pipeline, so the two entry points cannot drift
+     * into two imports.
+     *
+     * @param data - The file's bytes.
+     * @param name - The name the panel reports and the worker partly decides from.
+     */
+    async importBuffer(data, name) {
+        try {
+            const compatibilityCopy = data.slice(0);
+            const snapshot = await importInWorker(data, name).catch(error => {
+                // Older servers may not expose the worker route. Keep import
+                // functional with a synchronous compatibility fallback in that case.
+                if (error instanceof Error && /Worker/.test(error.message))
+                    return readWorkbookXlsx(compatibilityCopy, name);
+                throw error;
+            });
+            window.dispatchEvent(new CustomEvent('data-sheet:import', { detail: { snapshot, filename: name } }));
+        }
+        catch (error) {
+            window.dispatchEvent(new CustomEvent('data-sheet:import-error', { detail: { message: error instanceof Error ? error.message : String(error) } }));
+        }
+    }
+};
+DataSheetExportPlugin = __decorate([
+    __param(1, Inject(Injector)),
+    __param(2, ICommandService),
+    __param(3, IUniverInstanceService)
+], DataSheetExportPlugin);
+export { DataSheetExportPlugin };
+function importInWorker(data, filename) {
+    if (typeof Worker === 'undefined')
+        return Promise.reject(new Error('当前浏览器不支持 Worker'));
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(dataSheetAssetPath('/data-sheet/xlsx-import-worker.js'));
+        const timeout = window.setTimeout(() => {
+            worker.terminate();
+            reject(new Error('导入超时'));
+        }, 60_000);
+        worker.onmessage = event => {
+            window.clearTimeout(timeout);
+            worker.terminate();
+            const result = event.data;
+            if (result.ok !== true || typeof result.snapshot !== 'object' || result.snapshot === null) {
+                reject(new Error(result.error ?? '导入失败'));
+            }
+            else {
+                resolve(result.snapshot);
+            }
+        };
+        worker.onerror = event => {
+            window.clearTimeout(timeout);
+            worker.terminate();
+            reject(new Error(event.message || '导入 Worker 加载失败'));
+        };
+        worker.postMessage({ data, filename }, [data]);
+    });
+}
+function snapshotWorkbookName(snapshot) {
+    if (typeof snapshot !== 'object' || snapshot === null)
+        return null;
+    const name = snapshot.name;
+    return typeof name === 'string' && name.trim().length > 0 ? name.trim() : null;
+}
+function exportInWorker(format, snapshot) {
+    if (typeof Worker === 'undefined')
+        return Promise.reject(new Error('当前浏览器不支持 Worker'));
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(dataSheetAssetPath('/data-sheet/xlsx-export-worker.js'));
+        const timeout = window.setTimeout(() => {
+            worker.terminate();
+            reject(new Error('导出超时'));
+        }, 60_000);
+        worker.onmessage = event => {
+            window.clearTimeout(timeout);
+            worker.terminate();
+            const data = event.data;
+            if (data.ok !== true)
+                reject(new Error(data.error ?? '导出失败'));
+            else
+                resolve((data.value ?? null));
+        };
+        worker.onerror = event => {
+            window.clearTimeout(timeout);
+            worker.terminate();
+            reject(new Error(event.message || '导出 Worker 加载失败'));
+        };
+        worker.postMessage({ format, snapshot });
+    });
+}
+function safeFilename(value) {
+    return value.replace(/[\\/:*?"<>|]/g, '-').trim() || 'workbook';
+}

package/lib/types/univer/plugins/history.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Datasheet edit-history entry point for the open-source Univer canvas.
+ *
+ * Univer Pro's history viewer is intentionally not used. The DSH host owns
+ * durable operation logs/checkpoints and opens its own history panel when the
+ * command is executed.
+ */
+import { ICommandService, Injector, Plugin, UniverInstanceType } from '@univerjs/presets';
+export declare const SHOW_HISTORY_COMMAND_ID = "dsh.data-sheet.show-history";
+export interface DataSheetHistoryPluginConfig {
+    onOpenHistory?: () => void;
+}
+/** Registers the DSH history panel command on the Univer ribbon. */
+export declare class DataSheetHistoryPlugin extends Plugin {
+    private readonly _config;
+    protected readonly _injector: Injector;
+    private readonly _commandService;
+    static pluginName: string;
+    static packageName: string;
+    static version: string;
+    static type: UniverInstanceType;
+    constructor(_config: DataSheetHistoryPluginConfig | undefined, _injector: Injector, _commandService: ICommandService);
+    onStarting(): void;
+}

package/lib/types/univer/plugins/history.js

@@ -0,0 +1,50 @@
+/**
+ * Datasheet edit-history entry point for the open-source Univer canvas.
+ *
+ * Univer Pro's history viewer is intentionally not used. The DSH host owns
+ * durable operation logs/checkpoints and opens its own history panel when the
+ * command is executed.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { CommandType, Inject, ICommandService, Injector, Plugin, UniverInstanceType, } from '@univerjs/presets';
+import { UNIVER_PLUGIN_VERSION } from "./version.js";
+export const SHOW_HISTORY_COMMAND_ID = 'dsh.data-sheet.show-history';
+/** Registers the DSH history panel command on the Univer ribbon. */
+let DataSheetHistoryPlugin = class DataSheetHistoryPlugin extends Plugin {
+    _config;
+    _injector;
+    _commandService;
+    static pluginName = 'dsh.data-sheet.history';
+    static packageName = 'dsh-data-table';
+    static version = UNIVER_PLUGIN_VERSION;
+    static type = UniverInstanceType.UNIVER_SHEET;
+    constructor(_config, _injector, _commandService) {
+        super();
+        this._config = _config;
+        this._injector = _injector;
+        this._commandService = _commandService;
+    }
+    onStarting() {
+        this.disposeWithMe(this._commandService.registerCommand({
+            id: SHOW_HISTORY_COMMAND_ID,
+            type: CommandType.COMMAND,
+            handler: () => {
+                this._config?.onOpenHistory?.();
+                return true;
+            },
+        }));
+    }
+};
+DataSheetHistoryPlugin = __decorate([
+    __param(1, Inject(Injector)),
+    __param(2, ICommandService)
+], DataSheetHistoryPlugin);
+export { DataSheetHistoryPlugin };

package/lib/types/univer/plugins/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The version every Data Sheet Univer plugin declares.
+ *
+ * Univer's `PluginService` compares a plugin's declared `version` against its
+ * core version and logs `Plugin version mismatch` when they differ. Our three
+ * adapters are not `@univerjs/*` packages, but declaring the pinned core
+ * version is what keeps that warning out of the console.
+ *
+ * `tests/univer-plugin-version.test.mjs` pins this constant to the installed
+ * `@univerjs/presets` version, so upgrading Univer cannot silently bring the
+ * warning back.
+ */
+export declare const UNIVER_PLUGIN_VERSION = "0.25.1";

package/lib/types/univer/plugins/version.js

@@ -0,0 +1,13 @@
+/**
+ * The version every Data Sheet Univer plugin declares.
+ *
+ * Univer's `PluginService` compares a plugin's declared `version` against its
+ * core version and logs `Plugin version mismatch` when they differ. Our three
+ * adapters are not `@univerjs/*` packages, but declaring the pinned core
+ * version is what keeps that warning out of the console.
+ *
+ * `tests/univer-plugin-version.test.mjs` pins this constant to the installed
+ * `@univerjs/presets` version, so upgrading Univer cannot silently bring the
+ * warning back.
+ */
+export const UNIVER_PLUGIN_VERSION = '0.25.1';

package/lib/types/version/diff.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What changed between two snapshots (docs/issue/0022 P2).
+ *
+ * Pure, and the only place that decides what counts as a change: a cell's
+ * value, a sheet's identity, or the structure around it (merges, freeze,
+ * row/column sizes). The Version list and the comparison bar both read this
+ * shape, so the answer to "what changed" is defined once.
+ *
+ * `scopes` narrows the walk to the sheets and ranges an operation actually
+ * touched; without it the whole workbook is compared.
+ */
+import type { WorkbookChange, WorkbookOperationPayload, WorkbookOperationType, WorkbookRange } from '../types.ts';
+/**
+ * How many differences one diff reports.
+ *
+ * A bound is necessary — the list travels in an HTTP response and an Agent
+ * result — but an *unsignalled* bound is not: a caller receiving exactly this
+ * many cannot tell a comparison that found this many from one that stopped
+ * looking, so `describeSnapshotReplace` stated `修改 500 个单元格` for a save that
+ * touched thousands, and the comparison bar showed the same number as though it
+ * were the whole answer. Callers ask {@link diffReachedLimit}.
+ */
+export declare const DIFF_CHANGE_LIMIT = 500;
+/** Whether a diff stopped at the limit, so its count is a lower bound. */
+export declare function diffReachedLimit(changes: readonly WorkbookChange[]): boolean;
+export interface WorkbookDiffScope {
+    ref: string;
+    wholeSheet: boolean;
+    ranges: WorkbookRange[];
+}
+/** Collect the smallest safe regions touched by a proposal. */
+export declare function collectDiffScopes(operations: Array<{
+    type: WorkbookOperationType;
+    payload: WorkbookOperationPayload;
+}>): Map<string, WorkbookDiffScope>;
+export declare function diffWorkbookSnapshots(before: unknown, after: unknown, scopes?: Map<string, WorkbookDiffScope>): WorkbookChange[];

package/lib/types/version/diff.js

@@ -0,0 +1,156 @@
+/**
+ * How many differences one diff reports.
+ *
+ * A bound is necessary — the list travels in an HTTP response and an Agent
+ * result — but an *unsignalled* bound is not: a caller receiving exactly this
+ * many cannot tell a comparison that found this many from one that stopped
+ * looking, so `describeSnapshotReplace` stated `修改 500 个单元格` for a save that
+ * touched thousands, and the comparison bar showed the same number as though it
+ * were the whole answer. Callers ask {@link diffReachedLimit}.
+ */
+export const DIFF_CHANGE_LIMIT = 500;
+/** Whether a diff stopped at the limit, so its count is a lower bound. */
+export function diffReachedLimit(changes) {
+    return changes.length >= DIFF_CHANGE_LIMIT;
+}
+import { asWorkbookSnapshot, toCellValue } from "../contract/snapshots.js";
+/** Collect the smallest safe regions touched by a proposal. */
+export function collectDiffScopes(operations) {
+    const scopes = new Map();
+    const add = (ref, range, wholeSheet = false) => {
+        if (ref === undefined || ref.trim().length === 0)
+            return;
+        const key = ref.trim();
+        const scope = scopes.get(key) ?? { ref: key, wholeSheet: false, ranges: [] };
+        scope.wholeSheet ||= wholeSheet;
+        if (range !== undefined)
+            scope.ranges.push(range);
+        scopes.set(key, scope);
+    };
+    for (const operation of operations) {
+        const payload = operation.payload;
+        const ref = payload.sheetId ?? payload.sheetName ?? (operation.type === 'create_sheet' ? payload.name : undefined);
+        if (operation.type === 'batch') {
+            for (const child of payload.operations ?? []) {
+                const nested = collectDiffScopes([child]);
+                for (const scope of nested.values()) {
+                    const target = scopes.get(scope.ref) ?? { ref: scope.ref, wholeSheet: false, ranges: [] };
+                    target.wholeSheet ||= scope.wholeSheet;
+                    target.ranges.push(...scope.ranges);
+                    scopes.set(scope.ref, target);
+                }
+            }
+            continue;
+        }
+        if (operation.type === 'update_cells') {
+            const cells = payload.cells ?? [];
+            if (cells.length > 0) {
+                add(ref, {
+                    startRow: Math.min(...cells.map(cell => cell.row)),
+                    startColumn: Math.min(...cells.map(cell => cell.column)),
+                    endRow: Math.max(...cells.map(cell => cell.row)),
+                    endColumn: Math.max(...cells.map(cell => cell.column)),
+                });
+            }
+            continue;
+        }
+        if (operation.type === 'clear_range' || operation.type === 'delete_cells' || operation.type === 'format_cells'
+            || operation.type === 'merge_cells' || operation.type === 'unmerge_cells' || operation.type === 'sort_range'
+            || operation.type === 'set_hyperlink' || operation.type === 'remove_hyperlink' || operation.type === 'remove_duplicates') {
+            add(ref, payload.range ?? payload.merge);
+            continue;
+        }
+        if (operation.type === 'set_column_width' || operation.type === 'set_row_height' || operation.type === 'freeze_panes'
+            || operation.type === 'append_rows' || operation.type === 'insert_rows' || operation.type === 'delete_rows'
+            || operation.type === 'insert_columns' || operation.type === 'delete_columns') {
+            add(ref, undefined, true);
+            continue;
+        }
+        if (operation.type === 'create_sheet' || operation.type === 'delete_sheet' || operation.type === 'rename_sheet')
+            add(ref, undefined, true);
+    }
+    return scopes;
+}
+/** No value at either end: `toCellValue` answers `null` for a valueless cell. */
+function isBlankValue(value) {
+    return value === null || value === undefined || String(value) === '';
+}
+export function diffWorkbookSnapshots(before, after, scopes) {
+    const left = asWorkbookSnapshot(before);
+    const right = asWorkbookSnapshot(after);
+    const changes = [];
+    const sheetIds = new Set([...left.sheetOrder, ...right.sheetOrder]);
+    for (const sheetId of sheetIds) {
+        const beforeSheet = left.sheets[sheetId];
+        const afterSheet = right.sheets[sheetId];
+        if (beforeSheet === undefined || afterSheet === undefined) {
+            changes.push({ kind: 'sheet', sheetId, sheetName: afterSheet?.name ?? beforeSheet?.name, description: afterSheet === undefined ? '删除 sheet' : '新增 sheet' });
+            continue;
+        }
+        const scope = scopes === undefined || scopes.size === 0
+            ? undefined
+            : [...scopes.values()].find(candidate => candidate.ref === sheetId || candidate.ref === beforeSheet.name || candidate.ref === afterSheet.name);
+        if (scopes !== undefined && scopes.size > 0 && scope === undefined)
+            continue;
+        if (beforeSheet.name !== afterSheet.name)
+            changes.push({ kind: 'sheet', sheetId, sheetName: afterSheet.name, before: beforeSheet.name, after: afterSheet.name, description: '重命名 sheet' });
+        for (const key of ['mergeData', 'freeze', 'columnData', 'rowData']) {
+            if (JSON.stringify(beforeSheet[key]) !== JSON.stringify(afterSheet[key])) {
+                changes.push({ kind: 'structure', sheetId, sheetName: afterSheet.name, before: beforeSheet[key], after: afterSheet[key], description: key === 'mergeData' ? '调整合并单元格' : key === 'freeze' ? '调整冻结窗格' : '调整行列尺寸' });
+            }
+        }
+        const rows = scope?.wholeSheet || scope === undefined
+            ? new Set([...Object.keys(beforeSheet.cellData ?? {}), ...Object.keys(afterSheet.cellData ?? {})])
+            : new Set(scope.ranges.flatMap(range => {
+                const result = [];
+                for (let row = range.startRow; row <= range.endRow; row += 1)
+                    result.push(String(row));
+                return result;
+            }));
+        for (const row of rows) {
+            const columns = scope?.wholeSheet || scope === undefined
+                ? new Set([...Object.keys(beforeSheet.cellData?.[row] ?? {}), ...Object.keys(afterSheet.cellData?.[row] ?? {})])
+                : new Set(scope.ranges.flatMap(range => {
+                    const result = [];
+                    for (let column = range.startColumn; column <= range.endColumn; column += 1)
+                        result.push(String(column));
+                    return result;
+                }));
+            for (const column of columns) {
+                const beforeCell = beforeSheet.cellData?.[row]?.[column];
+                const afterCell = afterSheet.cellData?.[row]?.[column];
+                if (JSON.stringify(beforeCell) === JSON.stringify(afterCell))
+                    continue;
+                const beforeValue = toCellValue(beforeCell);
+                const afterValue = toCellValue(afterCell);
+                // A cell with no value on either side that only gained a style is not a
+                // difference worth reporting. Formatting a range writes a style id into
+                // every cell it covers, empty ones included, and those entries used to
+                // dominate the count: 473 of them against 11 real edits, which made the
+                // comparison bar unreadable (GUI feedback 2026-09-19).
+                //
+                // `toCellValue` answers `null` for a valueless cell, so "blank" here has
+                // to mean null/empty and not just `undefined` — testing for `undefined`
+                // compiles, passes the unit tests, and silently changes nothing.
+                if (isBlankValue(beforeValue) && isBlankValue(afterValue))
+                    continue;
+                // Same value, different cell object: the formatting moved, the content
+                // did not. Reported as 样式 rather than as a modification.
+                const styleOnly = beforeValue === afterValue;
+                changes.push({
+                    kind: 'cell',
+                    sheetId,
+                    sheetName: afterSheet.name,
+                    row: Number(row),
+                    column: Number(column),
+                    before: beforeValue,
+                    after: afterValue,
+                    ...(styleOnly ? { styleOnly: true } : {}),
+                });
+                if (changes.length >= DIFF_CHANGE_LIMIT)
+                    return changes;
+            }
+        }
+    }
+    return changes;
+}

package/lib/types/version/grouping.d.ts

@@ -0,0 +1,7 @@
+import type { WorkbookHistoryVersion, WorkbookOperation } from '../types.ts';
+export declare function operationVersionId(operation: WorkbookOperation): string;
+export declare function historyVersionStatus(status: WorkbookOperation['versionStatus']): WorkbookHistoryVersion['status'];
+/** Group physical revisions into the logical Version shown to users. A user
+ * save can fill one open Version over several requests; an Agent semantic
+ * batch is one Version with N replayable Steps. */
+export declare function historyVersionsFromOperations(source: WorkbookOperation[], canReplay: (revision: number) => boolean, activeRevisions: Set<number>): WorkbookHistoryVersion[];

package/lib/types/version/grouping.js

@@ -0,0 +1,94 @@
+/**
+ * Physical revisions → the logical Versions a person sees (docs/issue/0022 P2).
+ *
+ * One user save can fill a single open Version across several requests, and one
+ * Agent semantic batch is a Version with N replayable Steps. This is the only
+ * place that decides where one Version ends and the next begins, so the list,
+ * the comparison bar and the Agent's history tool cannot disagree about it.
+ */
+import { operationSummary, versionKindOfOperations, workbookOperationSteps } from "../contract/operations.js";
+import { describeSessionSteps } from "./summary.js";
+export function operationVersionId(operation) {
+    return operation.versionId ?? `revision:${operation.revision}`;
+}
+export function historyVersionStatus(status) {
+    return status === 'temporary' || status === undefined ? (status === 'temporary' ? 'open' : 'final') : status;
+}
+/** Group physical revisions into the logical Version shown to users. A user
+ * save can fill one open Version over several requests; an Agent semantic
+ * batch is one Version with N replayable Steps. */
+export function historyVersionsFromOperations(source, canReplay, activeRevisions) {
+    const groups = new Map();
+    for (const operation of source.slice().sort((left, right) => left.revision - right.revision)) {
+        const id = operationVersionId(operation);
+        const group = groups.get(id);
+        if (group === undefined)
+            groups.set(id, [operation]);
+        else
+            group.push(operation);
+    }
+    const entries = [...groups.entries()];
+    const numberByVersionId = new Map(entries.map(([versionId], index) => [versionId, index + 1]));
+    /** Display number of the Version whose revision range covers `revision`. */
+    const numberAtRevision = (revision) => {
+        if (revision === undefined)
+            return undefined;
+        for (const [versionId, operations] of entries) {
+            const first = operations[0];
+            const last = operations.at(-1);
+            if (first === undefined || last === undefined)
+                continue;
+            if (revision >= first.revision && revision <= last.revision)
+                return numberByVersionId.get(versionId);
+        }
+        return undefined;
+    };
+    return entries.map(([versionId, operations], index) => {
+        const first = operations[0];
+        const last = operations.at(-1);
+        if (first === undefined || last === undefined)
+            throw new Error('历史版本缺少操作');
+        const steps = operations.flatMap(operation => workbookOperationSteps(operation));
+        const storedSummary = last.versionSummary ?? first.versionSummary ?? (operations.length === 1
+            ? operationSummary(first)
+            : describeSessionSteps(steps));
+        const branch = operations.every(operation => activeRevisions.has(operation.revision)) ? 'main' : 'superseded';
+        const storedStatus = historyVersionStatus(last.versionStatus);
+        const intent = last.versionIntent ?? first.versionIntent;
+        const agentRunId = last.agentRunId ?? first.agentRunId;
+        const lineage = last.lineage ?? first.lineage;
+        const restoredFromRevision = last.restoredFromRevision ?? first.restoredFromRevision;
+        const restoredFromNumber = numberAtRevision(restoredFromRevision);
+        // A stored `恢复到 revision 48` predates the v3 wording rule; show the
+        // Version number instead of the internal revision (PRD v3 §7.3).
+        const summary = restoredFromNumber !== undefined && /^恢复到 revision \d+$/.test(storedSummary)
+            ? `恢复到 V${restoredFromNumber}`
+            : storedSummary;
+        // v3 tier. Explicit when written; pre-v3 logs are derived from the facts
+        // that already separated a deliberate Version from editing-session churn.
+        const kind = versionKindOfOperations(operations);
+        return {
+            versionId,
+            // Creation order: a restore lands after every existing Version, so its
+            // number is always fresh and old numbers are never reused (PRD §3.2).
+            number: index + 1,
+            startRevision: first.revision,
+            revision: last.revision,
+            parentRevision: first.parentRevision ?? Math.max(0, first.revision - 1),
+            actor: first.actor,
+            timestamp: first.timestamp,
+            summary,
+            kind,
+            ...(intent === undefined ? {} : { intent }),
+            ...(agentRunId === undefined ? {} : { agentRunId }),
+            ...(lineage === undefined ? {} : { lineage }),
+            ...(restoredFromRevision === undefined ? {} : { restoredFromRevision }),
+            ...(restoredFromNumber === undefined ? {} : { restoredFromNumber }),
+            stepCount: steps.length,
+            steps: steps.map((step, index) => ({ index, opId: step.opId, type: step.type, summary: operationSummary(step), ...(step.revision === undefined ? {} : { revision: step.revision }) })),
+            canPreview: canReplay(last.revision),
+            status: branch === 'superseded' ? 'superseded' : storedStatus,
+            branch,
+        };
+    });
+}

package/lib/types/version/records.d.ts

@@ -0,0 +1,17 @@
+import type { VersionRecord } from '#contracts';
+import type { WorkbookCheckpoint, WorkbookHistoryVersion, WorkbookOperation } from '../types.ts';
+/** Follow logical parents from the current head. Versions skipped by a
+ * rollback remain in history but are no longer part of the active main line. */
+export declare function activeHistoryRevisions(currentRevision: number, operations: Map<number, WorkbookOperation>): Set<number>;
+export declare function canReplayHistoryRevision(targetRevision: number, currentRevision: number, checkpoints: number[], operations: Map<number, WorkbookOperation>): boolean;
+/**
+ * Stable content hash for a Version (PRD §3.2): the checkpoint the Version
+ * starts from, plus the ordered opIds applied on top of it. It is a pure
+ * function of the Version's inputs, so the history list never has to
+ * materialise or copy a workbook snapshot into the browser (PRD §11).
+ */
+export declare function versionContentHash(version: WorkbookHistoryVersion, checkpointHash: (revision: number) => string): string;
+/** Map the Data Sheet history shape onto the shared Version record (PRD §7.1). */
+export declare function toVersionRecords(versions: WorkbookHistoryVersion[], workbookId: string, checkpointHash: (revision: number) => string): VersionRecord[];
+/** Memoized checkpoint hash lookup: hashes each snapshot at most once. */
+export declare function checkpointHasher(checkpoints: WorkbookCheckpoint[]): (revision: number) => string;