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

package/lib/types/univer/diagnostics.js

@@ -0,0 +1,141 @@
+/**
+ * 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.js";
+/**
+ * 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;
+/** Why the current mutation could not become an incremental cell change. */
+export function noteCellMutation(_commandId, mapped, detail = {}) {
+    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, mapped) {
+    if (typeof window === 'undefined')
+        return;
+    window.__dshLastCellMutation = {
+        at: new Date().toISOString(),
+        commandId,
+        mapped,
+        ...(mapped ? {} : (lastCellMutationNote ?? { reason: 'command-not-mapped' })),
+    };
+}
+export function cellKeysOf(cellValue) {
+    if (typeof cellValue !== 'object' || cellValue === null)
+        return [];
+    const firstRow = Object.values(cellValue)[0];
+    if (typeof firstRow !== 'object' || firstRow === null)
+        return [];
+    const firstCell = Object.values(firstRow)[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) {
+    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;
+    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 = [];
+    const rows = params.cellValue;
+    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)) {
+            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;
+            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) {
+    const commandId = commandInfo.id.toLowerCase();
+    let kind;
+    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
+        : {};
+    const payload = { 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;
+        const safeRange = {};
+        for (const key of ['startRow', 'startColumn', 'endRow', 'endColumn']) {
+            if (typeof candidate[key] === 'number' && Number.isFinite(candidate[key]))
+                safeRange[key] = candidate[key];
+        }
+        if (Object.keys(safeRange).length > 0)
+            payload.range = safeRange;
+    }
+    return { kind, payload };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * 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 type { WorkbookMount, WorkbookMountOptions } from './chunk.ts';
+export type { WorkbookDecoration, WorkbookDecorationCell, WorkbookDecorationTone, WorkbookMount, WorkbookMountOptions } from './chunk.ts';
+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 { WorkbookLocalChange, WorkbookPresencePayload, WorkbookSelectionRange } from '../types.ts';
+/**
+ * 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 declare function mountWorkbook(container: HTMLElement, workbookData: object, onDirty?: (change?: WorkbookLocalChange) => void, onPresence?: (presence: WorkbookPresencePayload) => void, options?: WorkbookMountOptions, onSelection?: (ranges: readonly WorkbookSelectionRange[]) => void): WorkbookMount;

package/lib/types/univer/engine.js

@@ -0,0 +1,338 @@
+/**
+ * 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 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 { DataSheetExportPlugin } from "./plugins/export.js";
+import { DataSheetCollaborationPlugin } from "./plugins/collaboration.js";
+import { DataSheetHistoryPlugin } from "./plugins/history.js";
+import { getInstalledFontConfigs, withDefaultSheetFont } from "./fonts.js";
+import { shouldPersistUniverMutation } from "../contract/operations.js";
+import { publishMutationAttempt, toLocalCellChange, toPresence } from "./diagnostics.js";
+import { createDecorationApplier } from "./decoration.js";
+import { createOperationApplier } from "./apply-operation.js";
+/** 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;
+    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, workbookData, onDirty, onPresence, options = {}, onSelection) {
+    const readOnly = options.readOnly === true;
+    const decoration = options.decoration;
+    const installedFontConfigs = getInstalledFontConfigs();
+    let openHistory;
+    let refreshSelection = () => { };
+    const onUniverMutation = (commandInfo, options) => {
+        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({
+        // 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;
+        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;
+    const getSheet = (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;
+    let currentSelectionRanges = [];
+    const projectSelections = (ranges) => {
+        const workbook = sheetsApi.getActiveWorkbook();
+        if (workbook === null)
+            return [];
+        const activeSheetId = workbook.getActiveSheet?.()?.getSheetId?.();
+        const projected = [];
+        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) => {
+        currentSelectionRanges = [...ranges];
+        onSelection?.(projectSelections(currentSelectionRanges));
+    };
+    refreshSelection = () => {
+        if (currentSelectionRanges.length > 0)
+            onSelection?.(projectSelections(currentSelectionRanges));
+    };
+    const bindSelectionWatcher = () => {
+        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, options = {}) => {
+        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.sheets === 'object') {
+                const sheets = snapshot.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) => {
+            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;
+            if (win.__bestExcelDebugMounts !== undefined) {
+                win.__bestExcelDebugMounts = win.__bestExcelDebugMounts.filter(entry => entry.container !== container);
+            }
+        },
+    };
+}

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

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

package/lib/types/univer/entry.js

@@ -0,0 +1,11 @@
+/**
+ * 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 { mountWorkbook } from "./engine.js";
+// 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 };

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

@@ -0,0 +1,107 @@
+/**
+ * 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;

package/lib/types/univer/facade.js

@@ -0,0 +1 @@
+export {};