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

package/lib/types/client/persistence/merge.js

@@ -0,0 +1,362 @@
+/**
+ * Three-way merge for Univer workbook snapshots.
+ *
+ * The browser keeps the last server snapshot as the base. When a user save
+ * races an Agent/user write, this module compares base/local/remote at cell
+ * granularity, adopts one-sided changes automatically, and keeps local values
+ * for true conflicts while adding a visible conflict style.
+ */
+import { cellAddress } from '#contracts';
+import { cloneSnapshot, normalizeCellFormula, stableJson, toCellValue } from "../../contract/snapshots.js";
+const MERGEABLE_SHEET_KEYS = [
+    'name',
+    'tabColor',
+    'hidden',
+    'zoomRatio',
+    'defaultColumnWidth',
+    'defaultRowHeight',
+    'freeze',
+    'mergeData',
+    'rowData',
+    'columnData',
+    'showGridlines',
+    'rowHeader',
+    'columnHeader',
+    'rightToLeft',
+    'defaultStyle',
+    'dataSheetMeta',
+];
+/** Merge local and remote snapshots against the last common base snapshot. */
+export function mergeWorkbookSnapshots(baseSnapshot, localSnapshot, remoteSnapshot) {
+    const base = asRecord(baseSnapshot);
+    const local = asRecord(localSnapshot);
+    const remote = asRecord(remoteSnapshot);
+    const merged = cloneSnapshot(local);
+    const conflicts = [];
+    const conflictStyleMap = {};
+    const localStyles = asRecord(merged.styles);
+    const remoteStyles = asRecord(remote.styles);
+    const remoteStyleMap = new Map();
+    const adoptRemoteCell = (cell) => {
+        if (cell === undefined)
+            return undefined;
+        const next = cloneSnapshot(cell);
+        if (typeof next.s === 'string')
+            next.s = remapRemoteStyle(next.s);
+        return next;
+    };
+    const remapRemoteStyle = (styleId) => {
+        const known = remoteStyleMap.get(styleId);
+        if (known !== undefined)
+            return known;
+        const remoteStyle = remoteStyles[styleId];
+        if (remoteStyle === undefined) {
+            remoteStyleMap.set(styleId, styleId);
+            return styleId;
+        }
+        const localStyle = localStyles[styleId];
+        if (localStyle === undefined || deepEqual(localStyle, remoteStyle)) {
+            localStyles[styleId] = cloneSnapshot(remoteStyle);
+            remoteStyleMap.set(styleId, styleId);
+            return styleId;
+        }
+        let candidate = `${styleId}-remote`;
+        let suffix = 1;
+        while (localStyles[candidate] !== undefined)
+            candidate = `${styleId}-remote-${suffix++}`;
+        localStyles[candidate] = cloneSnapshot(remoteStyle);
+        remoteStyleMap.set(styleId, candidate);
+        return candidate;
+    };
+    const baseSheets = asRecord(base.sheets);
+    const localSheets = asRecord(local.sheets);
+    const remoteSheets = asRecord(remote.sheets);
+    const mergedSheets = {};
+    const allSheetIds = new Set([...Object.keys(baseSheets), ...Object.keys(localSheets), ...Object.keys(remoteSheets)]);
+    for (const sheetId of allSheetIds) {
+        const baseSheet = asOptionalRecord(baseSheets[sheetId]);
+        const localSheet = asOptionalRecord(localSheets[sheetId]);
+        const remoteSheet = asOptionalRecord(remoteSheets[sheetId]);
+        if (localSheet === undefined && remoteSheet === undefined)
+            continue;
+        if (localSheet === undefined) {
+            if (baseSheet !== undefined && remoteSheet !== undefined && !deepEqual(remoteSheet, baseSheet)) {
+                conflicts.push(sheetConflict(sheetId, remoteSheet, '本地删除 sheet，但远端同时修改了它'));
+            }
+            // A sheet deleted locally remains deleted. A remote-only sheet is kept.
+            if (baseSheet === undefined && remoteSheet !== undefined)
+                mergedSheets[sheetId] = cloneAndRemapSheet(remoteSheet, adoptRemoteCell);
+            continue;
+        }
+        if (remoteSheet === undefined) {
+            if (baseSheet !== undefined && !deepEqual(localSheet, baseSheet)) {
+                conflicts.push(sheetConflict(sheetId, localSheet, '远端删除 sheet，但本地同时修改了它'));
+            }
+            // A sheet deleted remotely is deleted only when local had not changed it.
+            if (baseSheet !== undefined && deepEqual(localSheet, baseSheet))
+                continue;
+            mergedSheets[sheetId] = cloneSnapshot(localSheet);
+            continue;
+        }
+        const result = mergeSheet(sheetId, baseSheet, localSheet, remoteSheet, adoptRemoteCell, localStyles);
+        mergedSheets[sheetId] = result.sheet;
+        conflicts.push(...result.conflicts);
+        Object.assign(conflictStyleMap, result.conflictStyleMap);
+    }
+    merged.sheets = mergedSheets;
+    merged.styles = localStyles;
+    const baseOrder = asStringArray(base.sheetOrder);
+    const localOrder = asStringArray(local.sheetOrder);
+    const remoteOrder = asStringArray(remote.sheetOrder);
+    if (deepEqual(localOrder, baseOrder) && !deepEqual(remoteOrder, baseOrder))
+        merged.sheetOrder = remoteOrder.filter(id => mergedSheets[id] !== undefined);
+    else if (!deepEqual(localOrder, remoteOrder) && !deepEqual(remoteOrder, baseOrder)) {
+        conflicts.push({ kind: 'structure', description: '本地和远端同时调整了 sheet 顺序，当前保留本地顺序' });
+    }
+    merged.sheetOrder = normalizeSheetOrder(asStringArray(merged.sheetOrder), mergedSheets);
+    return {
+        snapshot: merged,
+        conflicts,
+        autoMergedCells: countAutoMergedCells(base, local, remote, mergedSheets),
+        conflictStyleMap,
+    };
+}
+/** Remove temporary conflict styles before a merged snapshot is persisted. */
+export function stripConflictMarkers(snapshot, conflictStyleMap) {
+    if (Object.keys(conflictStyleMap).length === 0)
+        return snapshot;
+    const next = cloneSnapshot(snapshot);
+    const sheets = asRecord(next.sheets);
+    for (const sheet of Object.values(sheets)) {
+        const cellData = asRecord(sheet).cellData;
+        if (cellData === undefined)
+            continue;
+        for (const [rowKey, row] of Object.entries(cellData)) {
+            for (const [columnKey, cell] of Object.entries(row)) {
+                const marker = typeof cell.s === 'string' ? conflictStyleMap[cell.s] : undefined;
+                if (marker === undefined && !Object.prototype.hasOwnProperty.call(conflictStyleMap, cell.s))
+                    continue;
+                if (marker === null)
+                    delete cell.s;
+                else
+                    cell.s = marker;
+                if (Object.keys(cell).length === 1 && cell.v === null)
+                    delete row[columnKey];
+            }
+            if (Object.keys(row).length === 0)
+                delete cellData[rowKey];
+        }
+    }
+    const styles = asRecord(next.styles);
+    for (const markerId of Object.keys(conflictStyleMap))
+        delete styles[markerId];
+    next.styles = styles;
+    return next;
+}
+/** Apply ordinary cell edits to the merge base without cloning the workbook. */
+export function applyIncrementalChangesToSnapshot(snapshot, changes) {
+    const root = asRecord(snapshot);
+    const sheets = asRecord(root.sheets);
+    for (const change of changes) {
+        const sheet = sheets[change.payload.sheetId] ?? Object.values(sheets).find(candidate => asRecord(candidate).name === change.payload.sheetId);
+        if (sheet === undefined)
+            continue;
+        const cellData = (asRecord(sheet).cellData ??= {});
+        for (const update of change.payload.cells) {
+            const row = (cellData[String(update.row)] ??= {});
+            if (update.value === null && (update.formula === undefined || update.formula.trim().length === 0)) {
+                delete row[String(update.column)];
+                if (Object.keys(row).length === 0)
+                    delete cellData[String(update.row)];
+                continue;
+            }
+            const current = row[String(update.column)] ?? {};
+            row[String(update.column)] = { ...current, v: update.value };
+            const formula = normalizeCellFormula(update.formula);
+            if (formula === undefined)
+                delete row[String(update.column)].f;
+            else
+                row[String(update.column)].f = formula;
+        }
+    }
+}
+/** Patch a merge base from a replayable operation log; false means fallback. */
+export function applyIncrementalOperationsToSnapshot(snapshot, operations) {
+    const changes = [];
+    const collect = (operation) => {
+        if (operation.type === 'update_cells') {
+            const sheetId = operation.payload.sheetId ?? operation.payload.sheetName;
+            if (sheetId === undefined || (operation.payload.cells ?? []).length === 0)
+                return false;
+            changes.push({ type: 'update_cells', payload: { sheetId, cells: operation.payload.cells ?? [] } });
+            return true;
+        }
+        if (operation.type === 'batch') {
+            return (operation.payload.operations ?? []).every((child, index) => collect({
+                ...operation,
+                opId: `${operation.opId}:${index}`,
+                type: child.type,
+                payload: child.payload,
+            }));
+        }
+        return false;
+    };
+    if (!operations.every(collect))
+        return false;
+    applyIncrementalChangesToSnapshot(snapshot, changes);
+    return true;
+}
+function mergeSheet(sheetId, baseSheet, localSheet, remoteSheet, adoptRemoteCell, styles) {
+    const sheet = cloneSnapshot(localSheet);
+    const conflicts = [];
+    const conflictStyleMap = {};
+    let autoMergedCells = 0;
+    const localRowCount = typeof localSheet.rowCount === 'number' ? localSheet.rowCount : 0;
+    const remoteRowCount = typeof remoteSheet.rowCount === 'number' ? remoteSheet.rowCount : 0;
+    const localColumnCount = typeof localSheet.columnCount === 'number' ? localSheet.columnCount : 0;
+    const remoteColumnCount = typeof remoteSheet.columnCount === 'number' ? remoteSheet.columnCount : 0;
+    sheet.rowCount = Math.max(localRowCount, remoteRowCount);
+    sheet.columnCount = Math.max(localColumnCount, remoteColumnCount);
+    for (const key of MERGEABLE_SHEET_KEYS) {
+        const baseValue = baseSheet?.[key];
+        const localValue = localSheet[key];
+        const remoteValue = remoteSheet[key];
+        if (deepEqual(localValue, remoteValue))
+            continue;
+        if (deepEqual(localValue, baseValue)) {
+            if (remoteValue === undefined)
+                delete sheet[key];
+            else
+                sheet[key] = cloneSnapshot(remoteValue);
+        }
+        else if (deepEqual(remoteValue, baseValue)) {
+            continue;
+        }
+        else {
+            conflicts.push({ kind: 'structure', sheetId, sheetName: sheetName(localSheet, sheetId), description: `sheet 属性 ${key} 在本地和远端均有修改，当前保留本地值` });
+        }
+    }
+    const baseCells = asCellData(baseSheet?.cellData);
+    const localCells = asCellData(localSheet.cellData);
+    const remoteCells = asCellData(remoteSheet.cellData);
+    const mergedCells = {};
+    const rowKeys = new Set([...Object.keys(baseCells), ...Object.keys(localCells), ...Object.keys(remoteCells)]);
+    for (const rowKey of rowKeys) {
+        const baseRow = baseCells[rowKey] ?? {};
+        const localRow = localCells[rowKey] ?? {};
+        const remoteRow = remoteCells[rowKey] ?? {};
+        const columnKeys = new Set([...Object.keys(baseRow), ...Object.keys(localRow), ...Object.keys(remoteRow)]);
+        for (const columnKey of columnKeys) {
+            const baseCell = baseRow[columnKey];
+            const localCell = localRow[columnKey];
+            const remoteCell = remoteRow[columnKey];
+            let selected;
+            if (deepEqual(localCell, remoteCell))
+                selected = cloneOptional(localCell);
+            else if (deepEqual(localCell, baseCell)) {
+                selected = adoptRemoteCell(remoteCell);
+                autoMergedCells++;
+            }
+            else if (deepEqual(remoteCell, baseCell)) {
+                selected = cloneOptional(localCell);
+                autoMergedCells++;
+            }
+            else {
+                selected = cloneOptional(localCell) ?? { v: null };
+                const markerId = createConflictStyle(styles, selected, sheetId, Number(rowKey), Number(columnKey));
+                conflictStyleMap[markerId] = typeof localCell?.s === 'string' ? localCell.s : null;
+                selected.s = markerId;
+                conflicts.push({
+                    kind: 'cell',
+                    sheetId,
+                    sheetName: sheetName(localSheet, sheetId),
+                    row: Number(rowKey),
+                    column: Number(columnKey),
+                    address: `${sheetName(localSheet, sheetId)}!${cellAddress(Number(rowKey), Number(columnKey))}`,
+                    baseValue: toCellValue(baseCell),
+                    localValue: toCellValue(localCell),
+                    remoteValue: toCellValue(remoteCell),
+                    description: '本地和远端同时修改了同一单元格，当前保留本地值',
+                });
+            }
+            if (selected !== undefined)
+                (mergedCells[rowKey] ??= {})[columnKey] = selected;
+        }
+    }
+    sheet.cellData = mergedCells;
+    return { sheet, conflicts, autoMergedCells, conflictStyleMap };
+}
+function createConflictStyle(styles, cell, sheetId, row, column) {
+    const original = typeof cell.s === 'string' ? asOptionalRecord(styles[cell.s]) ?? {} : {};
+    const baseId = `data-sheet-conflict-${sheetId}-${row}-${column}`;
+    let id = baseId;
+    let suffix = 1;
+    while (styles[id] !== undefined)
+        id = `${baseId}-${suffix++}`;
+    styles[id] = { ...cloneSnapshot(original), bg: '#FFF2CC', cl: '#9C0006' };
+    return id;
+}
+function sheetConflict(sheetId, sheet, description) {
+    return { kind: 'sheet', sheetId, sheetName: sheetName(sheet, sheetId), description };
+}
+function sheetName(sheet, fallback) {
+    return typeof sheet.name === 'string' && sheet.name.length > 0 ? sheet.name : fallback;
+}
+function countAutoMergedCells(base, local, remote, mergedSheets) {
+    let count = 0;
+    const baseSheets = asRecord(base.sheets);
+    const localSheets = asRecord(local.sheets);
+    const remoteSheets = asRecord(remote.sheets);
+    for (const [sheetId, sheet] of Object.entries(mergedSheets)) {
+        const baseCells = asCellData(baseSheets[sheetId]?.cellData);
+        const localCells = asCellData(localSheets[sheetId]?.cellData);
+        const remoteCells = asCellData(remoteSheets[sheetId]?.cellData);
+        const mergedCells = asCellData(sheet.cellData);
+        for (const [rowKey, row] of Object.entries(mergedCells)) {
+            for (const columnKey of Object.keys(row)) {
+                const localCell = localCells[rowKey]?.[columnKey];
+                const remoteCell = remoteCells[rowKey]?.[columnKey];
+                const baseCell = baseCells[rowKey]?.[columnKey];
+                if (!deepEqual(localCell, remoteCell) && (deepEqual(localCell, baseCell) || deepEqual(remoteCell, baseCell)))
+                    count++;
+            }
+        }
+    }
+    return count;
+}
+function cloneAndRemapSheet(sheet, adoptRemoteCell) {
+    const next = cloneSnapshot(sheet);
+    const cellData = asCellData(next.cellData);
+    for (const [rowKey, row] of Object.entries(cellData)) {
+        for (const [columnKey, cell] of Object.entries(row))
+            row[columnKey] = adoptRemoteCell(cell) ?? cell;
+        cellData[rowKey] = row;
+    }
+    next.cellData = cellData;
+    return next;
+}
+function normalizeSheetOrder(order, sheets) {
+    const result = order.filter(id => sheets[id] !== undefined);
+    for (const id of Object.keys(sheets))
+        if (!result.includes(id))
+            result.push(id);
+    return result;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function asOptionalRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function asCellData(value) {
+    return asRecord(value);
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function cloneOptional(value) {
+    return value === undefined ? undefined : cloneSnapshot(value);
+}
+function deepEqual(left, right) {
+    return stableJson(left) === stableJson(right);
+}

package/lib/types/client/store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal sheet-panel store for dsh-data-table: the right-column
+ * open state. Workbook data lives server-side (node half, snapshot files);
+ * this store only tracks the panel toggle.
+ * @module dsh-data-table/client/store
+ */
+/** The workbook to reopen when the pane mounts without an explicit target. */
+export declare function lastSelectedWorkbookId(): string;
+/** Record the active workbook; call with an empty string when it is removed. */
+export declare function rememberWorkbook(id: string): void;
+/**
+ * The **unretained editing session** the next save joins, per workbook
+ * (PRD v3.3 D22).
+ *
+ * The session is not a saved Version: it keeps accumulating Steps and only
+ * becomes one when the idle window closes it or it reaches the Step cap. It has
+ * to outlive the React panel, because DSH remounts the pane whenever the
+ * conversation tab changes — losing the cursor there was what made "every visit
+ * is its own version", i.e. what users read as "leaving the artifact saved a
+ * version". localStorage is best-effort; the in-memory map covers a browser
+ * that refuses storage.
+ */
+export interface VersionSession {
+    /** The Version id the next save joins; `null` when there is nothing open. */
+    versionId: string;
+    /** Steps already committed into that Version. */
+    stepCount: number;
+}
+/** The open session for a workbook, or `null` when there is none. */
+export declare function readVersionSession(workbookId: string): VersionSession | null;
+/** Record (or with `null`, forget) the open session for a workbook. */
+export declare function rememberVersionSession(workbookId: string, session: VersionSession | null): void;
+/** Whether the right column is open. */
+export declare function isSheetOpen(): boolean;
+/** Open/close the right column. */
+export declare function setSheetOpen(value: boolean): void;
+/** React hook: right-column open state. */
+export declare function useSheetOpen(): boolean;
+/** Record whether the pane is showing the Table tab. */
+export declare function setSheetVisible(value: boolean): void;
+/** Whether the Table tab is on screen. */
+export declare function isSheetVisible(): boolean;
+/** React hook: whether the Table tab is on screen. */
+export declare function useSheetVisible(): boolean;
+/**
+ * Last workbook projection kept outside React. DSH unmounts the right pane when
+ * the conversation tab changes, so caching here lets a remount paint the
+ * previous content immediately instead of showing an empty panel while the
+ * request is in flight. The panel still revalidates against the Host, so edits
+ * made in another browser tab are not lost.
+ */
+export interface WorkbookProjection {
+    id: string;
+    name: string;
+    snapshot: object;
+    revision: number;
+}
+export declare function cachedWorkbookProjection(id: string): WorkbookProjection | null;
+export declare function rememberWorkbookProjection(projection: WorkbookProjection): void;
+/** Drop the cache when the workbook is deleted or fails to load. */
+export declare function forgetWorkbookProjection(id?: string): void;

package/lib/types/client/store.js

@@ -0,0 +1,152 @@
+/**
+ * Minimal sheet-panel store for dsh-data-table: the right-column
+ * open state. Workbook data lives server-side (node half, snapshot files);
+ * this store only tracks the panel toggle.
+ * @module dsh-data-table/client/store
+ */
+import { useSyncExternalStore } from 'react';
+let sheetOpen = false;
+/**
+ * Last workbook the user opened. DSH remounts the pane when the conversation
+ * tab changes, so the selection has to live outside React; localStorage keeps
+ * it across a reload too. Persistence is best-effort: a locked-down browser
+ * simply falls back to an in-memory value for this page life.
+ */
+const LAST_WORKBOOK_KEY = 'dsh.data-sheet.lastWorkbookId';
+let lastWorkbookId = '';
+let lastWorkbookLoaded = false;
+function readLastWorkbook() {
+    if (lastWorkbookLoaded)
+        return lastWorkbookId;
+    lastWorkbookLoaded = true;
+    try {
+        lastWorkbookId = globalThis.localStorage?.getItem(LAST_WORKBOOK_KEY) ?? '';
+    }
+    catch {
+        lastWorkbookId = '';
+    }
+    return lastWorkbookId;
+}
+/** The workbook to reopen when the pane mounts without an explicit target. */
+export function lastSelectedWorkbookId() {
+    return readLastWorkbook();
+}
+/** Record the active workbook; call with an empty string when it is removed. */
+export function rememberWorkbook(id) {
+    readLastWorkbook();
+    if (lastWorkbookId === id)
+        return;
+    lastWorkbookId = id;
+    try {
+        if (id === '')
+            globalThis.localStorage?.removeItem(LAST_WORKBOOK_KEY);
+        else
+            globalThis.localStorage?.setItem(LAST_WORKBOOK_KEY, id);
+    }
+    catch {
+        // Ignore storage failures; the in-memory value still survives remounts.
+    }
+}
+const VERSION_SESSION_PREFIX = 'dsh.data-sheet.versionSession.';
+const versionSessions = new Map();
+function versionSessionKey(workbookId) {
+    return `${VERSION_SESSION_PREFIX}${workbookId}`;
+}
+/** The open session for a workbook, or `null` when there is none. */
+export function readVersionSession(workbookId) {
+    if (workbookId === '')
+        return null;
+    const cached = versionSessions.get(workbookId);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const raw = globalThis.localStorage?.getItem(versionSessionKey(workbookId));
+        if (raw === null || raw === undefined)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.versionId !== 'string' || parsed.versionId === '')
+            return null;
+        const session = { versionId: parsed.versionId, stepCount: typeof parsed.stepCount === 'number' && parsed.stepCount > 0 ? parsed.stepCount : 0 };
+        versionSessions.set(workbookId, session);
+        return session;
+    }
+    catch {
+        return null;
+    }
+}
+/** Record (or with `null`, forget) the open session for a workbook. */
+export function rememberVersionSession(workbookId, session) {
+    if (workbookId === '')
+        return;
+    if (session === null)
+        versionSessions.delete(workbookId);
+    else
+        versionSessions.set(workbookId, session);
+    try {
+        if (session === null)
+            globalThis.localStorage?.removeItem(versionSessionKey(workbookId));
+        else
+            globalThis.localStorage?.setItem(versionSessionKey(workbookId), JSON.stringify(session));
+    }
+    catch {
+        // Ignore storage failures; the in-memory value still survives remounts.
+    }
+}
+const listeners = new Set();
+function emit() {
+    for (const listener of [...listeners])
+        listener();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+/** Whether the right column is open. */
+export function isSheetOpen() {
+    return sheetOpen;
+}
+/** Open/close the right column. */
+export function setSheetOpen(value) {
+    sheetOpen = value;
+    emit();
+}
+/** React hook: right-column open state. */
+export function useSheetOpen() {
+    return useSyncExternalStore(subscribe, () => sheetOpen);
+}
+/**
+ * Whether the Table tab is currently on screen.
+ *
+ * The workspace is a resident tree that outlives the pane, so its own `open`
+ * flag stays true for the life of the page. Anything that must react only to a
+ * *visible* table — the window-level Ctrl/Cmd+S shortcut in particular — reads
+ * this instead.
+ */
+let sheetVisible = false;
+/** Record whether the pane is showing the Table tab. */
+export function setSheetVisible(value) {
+    if (sheetVisible === value)
+        return;
+    sheetVisible = value;
+    emit();
+}
+/** Whether the Table tab is on screen. */
+export function isSheetVisible() {
+    return sheetVisible;
+}
+/** React hook: whether the Table tab is on screen. */
+export function useSheetVisible() {
+    return useSyncExternalStore(subscribe, () => sheetVisible);
+}
+let cachedProjection = null;
+export function cachedWorkbookProjection(id) {
+    return cachedProjection !== null && cachedProjection.id === id ? cachedProjection : null;
+}
+export function rememberWorkbookProjection(projection) {
+    cachedProjection = projection;
+}
+/** Drop the cache when the workbook is deleted or fails to load. */
+export function forgetWorkbookProjection(id) {
+    if (id === undefined || cachedProjection?.id === id)
+        cachedProjection = null;
+}

package/lib/types/client/surface-context.d.ts

@@ -0,0 +1,27 @@
+import type { SurfaceSelection } from '@tita-agent/dsh-surface-bridge';
+export declare const DATA_SHEET_SURFACE_ID = "data-sheet";
+export interface DataSheetFocusTarget {
+    readonly workbookId: string;
+    readonly sheetId: string;
+    readonly startRow: number;
+    readonly startColumn: number;
+    readonly endRow: number;
+    readonly endColumn: number;
+}
+export interface DataSheetRangeContext extends Omit<DataSheetFocusTarget, 'workbookId'> {
+    readonly sheetName: string;
+    readonly values: readonly (readonly unknown[])[];
+}
+export interface DataSheetSelectionContext {
+    readonly workbookId: string;
+    readonly workbookName: string;
+    readonly revision: number;
+    readonly documentRevision: number;
+    readonly ranges: readonly DataSheetRangeContext[];
+}
+/** Keep source-specific focus data opaque to the bridge, but stable in transcript metadata. */
+export declare function dataSheetFocusId(target: DataSheetFocusTarget): string;
+/** Decode a focus id emitted by this source. */
+export declare function dataSheetFocusTargetOf(value: string): DataSheetFocusTarget | undefined;
+/** Project the active Univer ranges into the bridge's shared context vocabulary. */
+export declare function projectDataSheetSelection(input: DataSheetSelectionContext): SurfaceSelection | null;