@coco-vexel/coco-office-editor 0.0.0-stage → 1.0.0

package/dist/spreadsheet.d.cts

@@ -0,0 +1,676 @@
+import { ExcelSheetModel, ExcelStylesModel, ExcelCellKind, ExcelCellValue, ExcelCellModel, ExcelRowModel, ExcelColumnModel, ExcelMergedRangeModel, SpreadsheetFormulaResult, ExcelPaneModel, ExcelBorderModel, ExcelWorkbook, ExcelWorkbookLoadOptions, ExcelWorkbookModel, ExcelHistoryApplyResult, ExcelTransactionGroupOptions, ExcelAgentTransactionGroupOptions, ExcelTransactionGroupSummary, ExcelWorkbookDiff, ExcelColorModel, SpreadsheetFormulaEngine } from '@coco-vexel/coco-office/excel';
+
+interface SpreadsheetPoint {
+    x: number;
+    y: number;
+}
+interface SpreadsheetSize {
+    width: number;
+    height: number;
+}
+interface SpreadsheetRect extends SpreadsheetPoint, SpreadsheetSize {
+}
+interface SpreadsheetRange {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+interface SpreadsheetRenderCell {
+    row: number;
+    column: number;
+    address: string;
+    kind: ExcelCellKind;
+    value: ExcelCellValue;
+    displayText: string;
+    formula?: string;
+    styleId?: number;
+    source: ExcelCellModel;
+}
+interface SpreadsheetMergeInfo {
+    address: string;
+    range: SpreadsheetRange;
+    masterAddress: string;
+    source: ExcelMergedRangeModel;
+}
+interface SpreadsheetSheetRenderModel {
+    sheetId: string;
+    sheetName: string;
+    source: ExcelSheetModel;
+    styles: ExcelStylesModel;
+    cellsByAddress: Map<string, SpreadsheetRenderCell>;
+    cellsByRowColumn: Map<string, SpreadsheetRenderCell>;
+    rowMetaByIndex: Map<number, ExcelRowModel>;
+    columnMetaByIndex: Map<number, ExcelColumnModel>;
+    mergeMasterByAddress: Map<string, SpreadsheetMergeInfo>;
+    mergeFollowerByAddress: Map<string, string>;
+    maxRow: number;
+    maxColumn: number;
+}
+interface SpreadsheetLayoutOptions {
+    defaultRowHeight?: number;
+    defaultColumnWidth?: number;
+    rowHeaderWidth?: number;
+    columnHeaderHeight?: number;
+    rowCount?: number;
+    columnCount?: number;
+}
+interface SpreadsheetHitCell {
+    kind: 'cell';
+    row: number;
+    column: number;
+    address: string;
+}
+interface SpreadsheetHitColumnHeader {
+    kind: 'columnHeader';
+    column: number;
+}
+interface SpreadsheetHitRowHeader {
+    kind: 'rowHeader';
+    row: number;
+}
+interface SpreadsheetHitCorner {
+    kind: 'corner';
+}
+interface SpreadsheetHitNone {
+    kind: 'none';
+}
+type SpreadsheetHitResult = SpreadsheetHitCell | SpreadsheetHitColumnHeader | SpreadsheetHitRowHeader | SpreadsheetHitCorner | SpreadsheetHitNone;
+type SpreadsheetViewportKind = 'main' | 'frozenTop' | 'frozenLeft' | 'frozenTopLeft' | 'columnHeaderScrollable' | 'columnHeaderFrozen' | 'rowHeaderScrollable' | 'rowHeaderFrozen' | 'corner';
+interface SpreadsheetViewport {
+    kind: SpreadsheetViewportKind;
+    screenRect: SpreadsheetRect;
+    originX: number;
+    originY: number;
+    rows: {
+        start: number;
+        end: number;
+    };
+    columns: {
+        start: number;
+        end: number;
+    };
+}
+interface SpreadsheetScrollState {
+    x: number;
+    y: number;
+}
+interface SpreadsheetFreezeState {
+    frozenRows: number;
+    frozenColumns: number;
+}
+interface SpreadsheetViewportState {
+    viewportSize: SpreadsheetSize;
+    scroll: SpreadsheetScrollState;
+    freeze: SpreadsheetFreezeState;
+}
+declare function rowColumnKey(row: number, column: number): string;
+
+interface BuildSpreadsheetRenderModelOptions {
+    minimumRows?: number;
+    minimumColumns?: number;
+    formulaResults?: Map<string, SpreadsheetFormulaResult>;
+}
+declare function buildSpreadsheetSheetRenderModel(sheet: ExcelSheetModel, styles: ExcelStylesModel, options?: BuildSpreadsheetRenderModelOptions): SpreadsheetSheetRenderModel;
+declare function getRenderCell(model: SpreadsheetSheetRenderModel, row: number, column: number): SpreadsheetRenderCell | undefined;
+declare function formatSpreadsheetDisplayValue(value: ExcelCellModel['value'], formatCode: string | undefined): string;
+
+declare class SpreadsheetLayout {
+    readonly model: SpreadsheetSheetRenderModel;
+    readonly defaultRowHeight: number;
+    readonly defaultColumnWidth: number;
+    readonly rowHeaderWidth: number;
+    readonly columnHeaderHeight: number;
+    readonly rowCount: number;
+    readonly columnCount: number;
+    private readonly rowOffsets;
+    private readonly columnOffsets;
+    private readonly rowHeights;
+    private readonly columnWidths;
+    constructor(model: SpreadsheetSheetRenderModel, options?: SpreadsheetLayoutOptions);
+    totalWidth(): number;
+    totalHeight(): number;
+    getColumnWidth(column: number): number;
+    getRowHeight(row: number): number;
+    getColumnX(column: number): number;
+    getRowY(row: number): number;
+    getCellLogicalRect(row: number, column: number): SpreadsheetRect;
+    getRangeLogicalRect(range: SpreadsheetRange): SpreadsheetRect;
+    getVisibleRange(originX: number, originY: number, size: SpreadsheetSize, minimumRow?: number, minimumColumn?: number): SpreadsheetRange;
+    rowAt(logicalY: number): number;
+    columnAt(logicalX: number): number;
+    hitTestLogical(logicalX: number, logicalY: number): SpreadsheetHitResult;
+}
+/** Convert an OOXML column width to the CSS-pixel geometry used by the renderer. */
+declare function excelColumnWidthToCssPixels(width: number): number;
+/** Convert editor CSS pixels back to the OOXML width Core writes to xlsx. */
+declare function cssPixelsToExcelColumnWidth(width: number): number;
+
+interface SpreadsheetViewportManagerOptions {
+    viewportSize: SpreadsheetSize;
+    scroll?: Partial<SpreadsheetScrollState>;
+    freeze?: Partial<SpreadsheetFreezeState>;
+}
+declare class SpreadsheetViewportManager {
+    private readonly layout;
+    readonly scroll: SpreadsheetScrollState;
+    readonly freeze: SpreadsheetFreezeState;
+    readonly viewportSize: SpreadsheetSize;
+    readonly viewports: SpreadsheetViewport[];
+    constructor(layout: SpreadsheetLayout, options: SpreadsheetViewportManagerOptions);
+    hitTest(point: SpreadsheetPoint): SpreadsheetHitResult;
+    findViewport(point: SpreadsheetPoint): SpreadsheetViewport | undefined;
+    cellScreenRect(row: number, column: number, viewport: SpreadsheetViewport): SpreadsheetRect;
+}
+declare function freezeStateFromSheet(sheet: ExcelSheetModel): SpreadsheetFreezeState;
+declare function freezeStateFromPane(pane: ExcelPaneModel | undefined): SpreadsheetFreezeState;
+declare function clampScroll(layout: SpreadsheetLayout, freeze: SpreadsheetFreezeState, viewportSize: SpreadsheetSize, scroll: SpreadsheetScrollState): SpreadsheetScrollState;
+
+interface SpreadsheetResolvedCellStyle {
+    font: string;
+    fontSize: number;
+    underline: boolean;
+    fontColor: string;
+    fillColor: string;
+    wrapText: boolean;
+    border: ExcelBorderModel;
+    horizontalAlign: CanvasTextAlign;
+    verticalAlign: 'top' | 'middle' | 'bottom';
+}
+declare function resolveSpreadsheetCellStyle(styles: ExcelStylesModel, styleId: number | undefined, cell?: SpreadsheetRenderCell): SpreadsheetResolvedCellStyle;
+declare function resolveSpreadsheetRangeBorder(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange): ExcelBorderModel;
+
+interface SpreadsheetCanvasRendererOptions {
+    baseCanvas: HTMLCanvasElement;
+    headerCanvas: HTMLCanvasElement;
+    overlayCanvas: HTMLCanvasElement;
+}
+declare class SpreadsheetCanvasRenderer {
+    private readonly options;
+    private readonly baseCtx;
+    private readonly headerCtx;
+    private readonly overlayCtx;
+    private cssWidth;
+    private cssHeight;
+    private scaleX;
+    private scaleY;
+    private headerFiltersEnabled;
+    private headerFilterColumns;
+    private activeHeaderFilterColumns;
+    constructor(options: SpreadsheetCanvasRendererOptions);
+    resize(width: number, height: number, devicePixelRatio?: number): void;
+    setHeaderFiltersEnabled(enabled: boolean): void;
+    setHeaderFilterColumns(columns: readonly number[] | null): void;
+    setActiveHeaderFilterColumns(columns: readonly number[]): void;
+    render(layout: SpreadsheetLayout, viewportManager: SpreadsheetViewportManager): void;
+    clearOverlay(): void;
+    renderSelection(layout: SpreadsheetLayout, viewportManager: SpreadsheetViewportManager, range: SpreadsheetRange, options?: {
+        showFillHandle?: boolean;
+    }): void;
+    fillHandleRect(layout: SpreadsheetLayout, viewportManager: SpreadsheetViewportManager, range: SpreadsheetRange): SpreadsheetRect | null;
+    renderCopiedRange(layout: SpreadsheetLayout, viewportManager: SpreadsheetViewportManager, range: SpreadsheetRange): void;
+    renderDashedRange(layout: SpreadsheetLayout, viewportManager: SpreadsheetViewportManager, range: SpreadsheetRange, options: {
+        stroke: string;
+        fill?: string;
+    }): void;
+    private clearAll;
+    private drawFillHandle;
+    private drawCells;
+    private drawCell;
+    private drawHeaders;
+}
+
+interface SpreadsheetSelectionState {
+    kind: 'cell' | 'row' | 'column';
+    active: {
+        row: number;
+        column: number;
+    };
+    range: SpreadsheetRange;
+}
+declare function createSelection(row: number, column: number): SpreadsheetSelectionState;
+declare function createRowSelection(row: number, bounds: {
+    columnCount: number;
+}): SpreadsheetSelectionState;
+declare function createRowRangeSelection(startRow: number, endRow: number, bounds: {
+    columnCount: number;
+}): SpreadsheetSelectionState;
+declare function createColumnSelection(column: number, bounds: {
+    rowCount: number;
+}): SpreadsheetSelectionState;
+declare function createColumnRangeSelection(startColumn: number, endColumn: number, bounds: {
+    rowCount: number;
+}): SpreadsheetSelectionState;
+declare function normalizeSelectionRange(range: SpreadsheetRange): SpreadsheetRange;
+declare function extendSelection(selection: SpreadsheetSelectionState, row: number, column: number, bounds?: {
+    rowCount: number;
+    columnCount: number;
+}): SpreadsheetSelectionState;
+declare function moveSelection(selection: SpreadsheetSelectionState, deltaRow: number, deltaColumn: number, bounds: {
+    rowCount: number;
+    columnCount: number;
+}): SpreadsheetSelectionState;
+/**
+ * Spreadsheet selections must include a full merged block once any cell in that block is touched.
+ * Keep this shared because drag selection, paste feedback, and host integrations need the same rule.
+ */
+declare function expandSelectionForMergedRanges(selection: SpreadsheetSelectionState, model: SpreadsheetSheetRenderModel): SpreadsheetSelectionState;
+declare function expandRangeForMergedRanges(range: SpreadsheetRange, model: SpreadsheetSheetRenderModel): SpreadsheetRange;
+declare function selectionAfterRowDeletion(selection: SpreadsheetSelectionState, deletedStartRow: number, deletedCount: number, bounds: {
+    rowCount: number;
+    columnCount: number;
+}, model: SpreadsheetSheetRenderModel): SpreadsheetSelectionState;
+declare function selectionAfterColumnDeletion(selection: SpreadsheetSelectionState, deletedStartColumn: number, deletedCount: number, bounds: {
+    rowCount: number;
+    columnCount: number;
+}, model: SpreadsheetSheetRenderModel): SpreadsheetSelectionState;
+
+interface SpreadsheetClipboardMerge {
+    startRowOffset: number;
+    startColumnOffset: number;
+    rowCount: number;
+    columnCount: number;
+}
+interface SpreadsheetClipboardPayload {
+    text: string;
+    values: ExcelCellValue[][];
+    styleIds: (number | undefined)[][];
+    merges: SpreadsheetClipboardMerge[];
+}
+declare function buildSpreadsheetClipboardPayload(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange): SpreadsheetClipboardPayload;
+declare function serializeRangeToTsv(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange): string;
+declare function parseTsv(text: string): ExcelCellValue[][];
+declare function rangeAddressForMatrix(startRow: number, startColumn: number, values: ExcelCellValue[][]): string;
+
+type SpreadsheetAutoFillDirection = 'down' | 'right';
+interface SpreadsheetAutoFillCell {
+    row: number;
+    column: number;
+    value: ExcelCellValue;
+    formula?: string;
+    styleId?: number;
+}
+interface SpreadsheetAutoFillPlan {
+    direction: SpreadsheetAutoFillDirection;
+    source: SpreadsheetRange;
+    target: SpreadsheetRange;
+    cells: SpreadsheetAutoFillCell[];
+}
+/**
+ * Produces the cells outside the original selection for a down/right fill.
+ * Merged ranges are deliberately excluded for now: their copy semantics need a
+ * separate structural operation rather than cell-by-cell expansion.
+ */
+declare function buildSpreadsheetAutoFillPlan(model: SpreadsheetSheetRenderModel, sourceRange: SpreadsheetRange, targetRange: SpreadsheetRange): SpreadsheetAutoFillPlan;
+declare function supportsSpreadsheetAutoFill(model: SpreadsheetSheetRenderModel, sourceRange: SpreadsheetRange): boolean;
+
+declare function setSpreadsheetCellValue(workbook: ExcelWorkbook, sheetName: string, address: string, value: ExcelCellValue): Promise<void>;
+declare function setSpreadsheetCellFormula(workbook: ExcelWorkbook, sheetName: string, address: string, formula: string | null): Promise<void>;
+declare function setSpreadsheetRangeValues(workbook: ExcelWorkbook, sheetName: string, startRow: number, startColumn: number, values: ExcelCellValue[][]): Promise<void>;
+declare function clearSpreadsheetRange(workbook: ExcelWorkbook, sheetName: string, startRow: number, startColumn: number, rowCount: number, columnCount: number): Promise<void>;
+declare function setSpreadsheetRowHeight(workbook: ExcelWorkbook, sheetName: string, row: number, height: number): Promise<void>;
+declare function setSpreadsheetColumnWidth(workbook: ExcelWorkbook, sheetName: string, column: number, width: number): Promise<void>;
+
+type SpreadsheetSortDirection = 'asc' | 'desc';
+interface SpreadsheetColumnFilter {
+    column: number;
+    values: readonly string[];
+}
+declare function spreadsheetFilterValues(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange, column: number): string[];
+declare function spreadsheetVisibleFilterValues(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange, column: number): string[];
+declare function spreadsheetRowsForFilter(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange, column: number, value: string | readonly string[]): number[];
+declare function spreadsheetRowsForColumnFilters(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange, filters: readonly SpreadsheetColumnFilter[]): number[];
+declare function spreadsheetSortRows(model: SpreadsheetSheetRenderModel, range: SpreadsheetRange, column: number, direction: SpreadsheetSortDirection): number[];
+
+interface SpreadsheetEditorRuntimeState {
+    workbook: ExcelWorkbook;
+    model: ExcelWorkbookModel;
+    activeSheetName: string;
+    activeSheet: SpreadsheetSheetRenderModel;
+    formulaResults: Map<string, SpreadsheetFormulaResult>;
+    formulaEngine: SpreadsheetFormulaEngine;
+}
+interface SpreadsheetCellEditHistoryOptions {
+    mergeUndo?: boolean;
+    mergeWindowMs?: number;
+}
+type SpreadsheetUserTransactionOptions = Omit<ExcelTransactionGroupOptions, 'source'>;
+type SpreadsheetAgentTransactionRunner = (runtime: SpreadsheetEditorRuntime) => Promise<void>;
+interface SpreadsheetAgentTransactionPreview {
+    result: ExcelHistoryApplyResult | null;
+    summary: ExcelTransactionGroupSummary | null;
+    diff: ExcelWorkbookDiff;
+    diffSummary: SpreadsheetPreviewDiffSummary;
+    beforeModel: ExcelWorkbookModel;
+    afterModel: ExcelWorkbookModel;
+    activeSheetName: string;
+}
+interface SpreadsheetPreviewDiffSummary {
+    changed: boolean;
+    changedSheets: number;
+    sheetNames: string[];
+    cellChanges: {
+        total: number;
+        added: number;
+        modified: number;
+        deleted: number;
+    };
+    structuralChanged: boolean;
+    objectChanged: boolean;
+    sampleCells: SpreadsheetPreviewCellChangeSummary[];
+}
+interface SpreadsheetPreviewCellChangeSummary {
+    sheetName: string;
+    address: string;
+    kind: 'added' | 'deleted' | 'modified';
+    before: ExcelCellValue | null;
+    after: ExcelCellValue | null;
+}
+type SpreadsheetPasteMode = 'all' | 'values' | 'formats';
+interface SpreadsheetPasteOptions {
+    mode?: SpreadsheetPasteMode;
+    merges?: SpreadsheetClipboardMerge[];
+    styleIds?: (number | undefined)[][];
+}
+declare class SpreadsheetEditorRuntime {
+    private state;
+    private activeTransaction;
+    private activeTransactionSource;
+    private transactionNeedsRefresh;
+    private constructor();
+    static fromZip(bytes: Uint8Array | ArrayBuffer, options?: ExcelWorkbookLoadOptions): Promise<SpreadsheetEditorRuntime>;
+    static fromWorkbook(workbook: ExcelWorkbook): Promise<SpreadsheetEditorRuntime>;
+    workbook(): ExcelWorkbook;
+    model(): ExcelWorkbookModel;
+    activeSheetName(): string;
+    activeSheet(): SpreadsheetSheetRenderModel;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): Promise<ExcelHistoryApplyResult | null>;
+    redo(): Promise<ExcelHistoryApplyResult | null>;
+    runUserTransaction(options: SpreadsheetUserTransactionOptions, run: () => Promise<void>): Promise<ExcelHistoryApplyResult | null>;
+    runAgentTransaction(options: ExcelAgentTransactionGroupOptions, run: SpreadsheetAgentTransactionRunner): Promise<ExcelHistoryApplyResult | null>;
+    previewAgentTransaction(options: ExcelAgentTransactionGroupOptions, run: SpreadsheetAgentTransactionRunner): Promise<SpreadsheetAgentTransactionPreview>;
+    setActiveSheet(sheetName: string): Promise<void>;
+    addSheet(name: string): Promise<void>;
+    renameSheet(sheetName: string, name: string): Promise<void>;
+    copySheet(sheetName: string, newName: string): Promise<void>;
+    deleteSheet(sheetName: string): Promise<void>;
+    moveSheet(sheetName: string, toIndex: number): Promise<void>;
+    refresh(): Promise<void>;
+    setCellValue(address: string, value: ExcelCellValue, historyOptions?: SpreadsheetCellEditHistoryOptions): Promise<void>;
+    setCellFormula(address: string, formula: string | null, historyOptions?: SpreadsheetCellEditHistoryOptions): Promise<void>;
+    replaceAll(query: string, replacement: string, matchCase?: boolean): Promise<number>;
+    filterRows(startRow: number, endRow: number, column: number, value: string | readonly string[] | null): Promise<void>;
+    filterRowsByColumns(startRow: number, endRow: number, filters: readonly SpreadsheetColumnFilter[]): Promise<void>;
+    sortRows(startRow: number, endRow: number, column: number, direction: SpreadsheetSortDirection): Promise<void>;
+    setRangeValues(startRow: number, startColumn: number, values: ExcelCellValue[][]): Promise<void>;
+    autoFillRange(sourceRange: SpreadsheetRange, targetRange: SpreadsheetRange): Promise<void>;
+    pasteRangeValues(startRow: number, startColumn: number, values: ExcelCellValue[][], merges?: SpreadsheetClipboardMerge[], styleIds?: (number | undefined)[][]): Promise<void>;
+    pasteRange(startRow: number, startColumn: number, values: ExcelCellValue[][], options?: SpreadsheetPasteOptions): Promise<void>;
+    clearRange(startRow: number, startColumn: number, rowCount: number, columnCount: number): Promise<void>;
+    setRowHeight(row: number, height: number): Promise<void>;
+    setColumnWidth(column: number, width: number): Promise<void>;
+    setFreezePanes(frozenRows: number, frozenColumns: number): Promise<void>;
+    insertRows(rowIndex: number, count?: number): Promise<void>;
+    deleteRows(rowIndex: number, count?: number): Promise<void>;
+    insertColumns(columnIndex: number, count?: number): Promise<void>;
+    deleteColumns(columnIndex: number, count?: number): Promise<void>;
+    setRangeBold(startRow: number, startColumn: number, rowCount: number, columnCount: number, value: boolean | undefined): Promise<void>;
+    setRangeItalic(startRow: number, startColumn: number, rowCount: number, columnCount: number, value: boolean | undefined): Promise<void>;
+    setRangeUnderline(startRow: number, startColumn: number, rowCount: number, columnCount: number, value: boolean | undefined): Promise<void>;
+    setRangeFontColor(startRow: number, startColumn: number, rowCount: number, columnCount: number, color: ExcelColorModel | undefined): Promise<void>;
+    setRangeFillColor(startRow: number, startColumn: number, rowCount: number, columnCount: number, color: ExcelColorModel | undefined): Promise<void>;
+    setRangeHorizontalAlign(startRow: number, startColumn: number, rowCount: number, columnCount: number, horizontal: 'left' | 'center' | 'right' | undefined): Promise<void>;
+    setRangeVerticalAlign(startRow: number, startColumn: number, rowCount: number, columnCount: number, vertical: 'top' | 'center' | 'bottom' | undefined): Promise<void>;
+    setRangeNumberFormat(startRow: number, startColumn: number, rowCount: number, columnCount: number, code: string | undefined): Promise<void>;
+    clearRangeFormat(startRow: number, startColumn: number, rowCount: number, columnCount: number): Promise<void>;
+    mergeRange(startRow: number, startColumn: number, rowCount: number, columnCount: number): Promise<void>;
+    unmergeRanges(addresses: string[]): Promise<void>;
+    setRangeBorder(startRow: number, startColumn: number, rowCount: number, columnCount: number, mode: 'all' | 'outer' | 'inner' | 'clear'): Promise<void>;
+    toZip(): Promise<Uint8Array>;
+    moveChart(chartIndex: number, position: {
+        from: {
+            row: number;
+            column: number;
+            rowOffset?: number;
+            columnOffset?: number;
+        };
+        to?: {
+            row: number;
+            column: number;
+            rowOffset?: number;
+            columnOffset?: number;
+        };
+    }): Promise<void>;
+    dispose(): Promise<void>;
+    editableCellAddress(address: string): string;
+    private rebuildActiveSheetRenderModel;
+    private runUserMutation;
+    private runWorksheetStructureMutation;
+    private cellStyleId;
+    private runScopedTransaction;
+    private cellEditHistoryGroup;
+    private range;
+}
+
+interface SpreadsheetAgentActionContext {
+    /** Current selection at the time the action is created. Hosts may pass richer app state later. */
+    selection?: SpreadsheetRange;
+    /** Optional opaque host payload, for example an agent plan id or UI prompt metadata. */
+    metadata?: Record<string, unknown>;
+}
+interface SpreadsheetAgentAction {
+    id: string;
+    label: string;
+    description?: string;
+    actor?: string;
+    agentRunId?: string;
+    agentStepId?: string;
+    agentActionId?: string;
+    metadata?: Record<string, unknown>;
+    run(runtime: SpreadsheetEditorRuntime, context: SpreadsheetAgentActionContext): Promise<void>;
+}
+interface SpreadsheetAgentActionPreview {
+    action: SpreadsheetAgentAction;
+    context: SpreadsheetAgentActionContext;
+    transaction: SpreadsheetAgentTransactionPreview;
+}
+interface SpreadsheetAgentActionApplyResult {
+    action: SpreadsheetAgentAction;
+    context: SpreadsheetAgentActionContext;
+    transaction: ExcelHistoryApplyResult | null;
+}
+declare function previewSpreadsheetAgentAction(runtime: SpreadsheetEditorRuntime, action: SpreadsheetAgentAction, context?: SpreadsheetAgentActionContext): Promise<SpreadsheetAgentActionPreview>;
+declare function applySpreadsheetAgentAction(runtime: SpreadsheetEditorRuntime, action: SpreadsheetAgentAction, context?: SpreadsheetAgentActionContext): Promise<SpreadsheetAgentActionApplyResult>;
+
+interface SpreadsheetCellEditorOptions {
+    textarea: HTMLTextAreaElement;
+    onCommit: (value: string) => void | Promise<void>;
+    onCancel?: () => void;
+}
+declare class SpreadsheetCellEditor {
+    private readonly options;
+    constructor(options: SpreadsheetCellEditorOptions);
+    open(rect: SpreadsheetRect, value: string): void;
+    commit(): Promise<void>;
+    cancel(): void;
+    close(): void;
+}
+
+declare function applyWheelDelta(scroll: SpreadsheetScrollState, deltaX: number, deltaY: number): SpreadsheetScrollState;
+interface SpreadsheetScrollbarGeometry {
+    trackLength: number;
+    thumbStart: number;
+    thumbLength: number;
+    maxScroll: number;
+}
+interface SpreadsheetScrollbarState {
+    horizontal: SpreadsheetScrollbarGeometry;
+    vertical: SpreadsheetScrollbarGeometry;
+}
+declare function computeScrollbarState(layout: SpreadsheetLayout, viewportSize: SpreadsheetSize, freeze: SpreadsheetFreezeState, scroll: SpreadsheetScrollState, scrollbarThickness?: number): SpreadsheetScrollbarState;
+declare function scrollFromThumbPosition(geometry: SpreadsheetScrollbarGeometry, thumbStart: number): number;
+
+declare const SPREADSHEET_COLUMN_RESIZE_MIN = 24;
+declare const SPREADSHEET_ROW_RESIZE_MIN = 12;
+declare const SPREADSHEET_RESIZE_HIT_TOLERANCE = 4;
+interface SpreadsheetResizeHandle {
+    kind: 'column' | 'row';
+    index: number;
+    startSize: number;
+    guidePosition: number;
+    minSize: number;
+}
+interface SpreadsheetResizeDragState extends SpreadsheetResizeHandle {
+    startClientX: number;
+    startClientY: number;
+    currentSize: number;
+    currentGuidePosition: number;
+}
+declare function hitSpreadsheetResizeHandle(layout: SpreadsheetLayout, viewports: readonly SpreadsheetViewport[], point: {
+    x: number;
+    y: number;
+}): SpreadsheetResizeHandle | null;
+declare function startSpreadsheetResizeDrag(handle: SpreadsheetResizeHandle, event: {
+    clientX: number;
+    clientY: number;
+}): SpreadsheetResizeDragState;
+declare function updateSpreadsheetResizeDrag(drag: SpreadsheetResizeDragState, event: {
+    clientX: number;
+    clientY: number;
+}): SpreadsheetResizeDragState;
+
+type SpreadsheetMixedValue<T> = T | 'mixed';
+interface SpreadsheetSelectionFormatState {
+    font: {
+        bold: SpreadsheetMixedValue<boolean>;
+        italic: SpreadsheetMixedValue<boolean>;
+        underline: SpreadsheetMixedValue<boolean>;
+        color: SpreadsheetMixedValue<ExcelColorModel | undefined>;
+    };
+    fill: {
+        foregroundColor: SpreadsheetMixedValue<ExcelColorModel | undefined>;
+    };
+    numberFormatCode: SpreadsheetMixedValue<string | undefined>;
+    alignment: {
+        horizontal: SpreadsheetMixedValue<'left' | 'center' | 'right'>;
+        vertical: SpreadsheetMixedValue<'top' | 'center' | 'bottom'>;
+    };
+    border: SpreadsheetMixedValue<ExcelBorderModel>;
+}
+declare function summarizeSpreadsheetSelectionFormat(model: SpreadsheetSheetRenderModel, selection: SpreadsheetSelectionState): SpreadsheetSelectionFormatState;
+
+interface SpreadsheetFindOptions {
+    query: string;
+    matchCase?: boolean;
+}
+interface SpreadsheetFindMatch {
+    row: number;
+    column: number;
+    address: string;
+    text: string;
+}
+interface SpreadsheetReplaceTarget {
+    address: string;
+    value?: ExcelCellValue;
+    formula?: string;
+}
+declare function buildSpreadsheetReplacePlan(model: SpreadsheetSheetRenderModel, options: SpreadsheetFindOptions & {
+    replacement: string;
+}): SpreadsheetReplaceTarget[];
+declare function findSpreadsheetMatches(model: SpreadsheetSheetRenderModel, options: SpreadsheetFindOptions): SpreadsheetFindMatch[];
+declare function nextSpreadsheetMatch(matches: readonly SpreadsheetFindMatch[], active: {
+    row: number;
+    column: number;
+}, direction?: 'forward' | 'backward'): SpreadsheetFindMatch | null;
+declare function rangeForSpreadsheetMatch(match: SpreadsheetFindMatch): SpreadsheetRange;
+
+interface SpreadsheetEditorChangeEvent {
+    kind: 'workbookChange';
+    bytes: Uint8Array;
+}
+interface SpreadsheetEditorStateEvent {
+    kind: 'stateChange';
+    activeSheetName: string;
+    selection: SpreadsheetSelectionState;
+    editingCell: {
+        row: number;
+        column: number;
+    } | null;
+}
+interface SpreadsheetEditorCellState {
+    address: string;
+    row: number;
+    column: number;
+    value: ExcelCellValue;
+    displayText: string;
+    formula?: string;
+    styleId?: number;
+    format?: {
+        font: unknown;
+        fill: unknown;
+        border: unknown;
+        alignment: unknown;
+        numberFormatCode?: string;
+    };
+}
+interface SpreadsheetEditorOptions {
+    workbookId?: string;
+    onChange?: (event: SpreadsheetEditorChangeEvent) => void | Promise<void>;
+    showSheetTabs?: boolean;
+    /** Isolates editor internals from host-page CSS. Shadow DOM is enabled by default. */
+    styleIsolation?: 'shadow' | 'none';
+    /** Header filter icons are opt-in; hosts can expose filtering from a column menu instead. */
+    enableHeaderFilters?: boolean;
+}
+interface SpreadsheetEditor {
+    runtime(): SpreadsheetEditorRuntime;
+    selection(): SpreadsheetSelectionState;
+    cellState(address: string): SpreadsheetEditorCellState;
+    freezeState(): SpreadsheetFreezeState;
+    filterState(): ReadonlyMap<number, readonly string[]>;
+    activeSheetName(): string;
+    setActiveSheet(name: string): Promise<void>;
+    addSheet(name: string): Promise<void>;
+    renameSheet(sheetName: string, name: string): Promise<void>;
+    copySheet(sheetName: string, newName: string): Promise<void>;
+    deleteSheet(sheetName: string): Promise<void>;
+    moveSheet(sheetName: string, toIndex: number): Promise<void>;
+    setCellValue(address: string, value: ExcelCellValue): Promise<void>;
+    setCellFormula(address: string, formula: string): Promise<void>;
+    formatSelection(kind: 'bold' | 'italic' | 'underline'): Promise<void>;
+    setSelectionFontColor(color: ExcelColorModel | undefined): Promise<void>;
+    setSelectionFillColor(color: ExcelColorModel | undefined): Promise<void>;
+    setSelectionHorizontalAlign(alignment: 'left' | 'center' | 'right'): Promise<void>;
+    setSelectionVerticalAlign(alignment: 'top' | 'center' | 'bottom'): Promise<void>;
+    setSelectionNumberFormat(code: string | undefined): Promise<void>;
+    setSelectionBorder(mode: 'all' | 'outer' | 'inner' | 'clear'): Promise<void>;
+    clearSelection(): Promise<void>;
+    clearSelectionFormat(): Promise<void>;
+    mergeSelection(): Promise<void>;
+    unmergeSelection(): Promise<void>;
+    freezeSelection(): Promise<void>;
+    sortActiveColumn(direction: 'asc' | 'desc'): Promise<void>;
+    filterColumn(column: number, values: readonly string[] | null): Promise<void>;
+    runTransaction(options: SpreadsheetUserTransactionOptions, run: (editor: SpreadsheetEditor) => Promise<void>): Promise<void>;
+    loadWorkbook(bytes: Uint8Array | ArrayBuffer): Promise<void>;
+    toZip(): Promise<Uint8Array>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    subscribe(listener: (event: SpreadsheetEditorChangeEvent) => void): () => void;
+    subscribeState(listener: (event: SpreadsheetEditorStateEvent) => void): () => void;
+    destroy(): void;
+}
+/**
+ * Public browser/Electron surface for the spreadsheet editor.
+ *
+ * The host owns its toolbar and persistence policy. This surface owns the
+ * canvas stack, viewport lifecycle, scrolling, and worksheet switching so web
+ * and desktop hosts do not rebuild those pieces independently.
+ */
+declare function renderSpreadsheetEditor(host: HTMLElement, bytes: Uint8Array | ArrayBuffer, options?: SpreadsheetEditorOptions): Promise<SpreadsheetEditor>;
+
+export { type BuildSpreadsheetRenderModelOptions, SPREADSHEET_COLUMN_RESIZE_MIN, SPREADSHEET_RESIZE_HIT_TOLERANCE, SPREADSHEET_ROW_RESIZE_MIN, type SpreadsheetAgentAction, type SpreadsheetAgentActionApplyResult, type SpreadsheetAgentActionContext, type SpreadsheetAgentActionPreview, type SpreadsheetAgentTransactionPreview, type SpreadsheetAgentTransactionRunner, type SpreadsheetAutoFillCell, type SpreadsheetAutoFillDirection, type SpreadsheetAutoFillPlan, SpreadsheetCanvasRenderer, type SpreadsheetCanvasRendererOptions, type SpreadsheetCellEditHistoryOptions, SpreadsheetCellEditor, type SpreadsheetCellEditorOptions, type SpreadsheetClipboardMerge, type SpreadsheetClipboardPayload, type SpreadsheetColumnFilter, type SpreadsheetEditor, type SpreadsheetEditorCellState, type SpreadsheetEditorChangeEvent, type SpreadsheetEditorOptions, SpreadsheetEditorRuntime, type SpreadsheetEditorRuntimeState, type SpreadsheetEditorStateEvent, type SpreadsheetFindMatch, type SpreadsheetFindOptions, type SpreadsheetFreezeState, type SpreadsheetHitCell, type SpreadsheetHitColumnHeader, type SpreadsheetHitCorner, type SpreadsheetHitNone, type SpreadsheetHitResult, type SpreadsheetHitRowHeader, SpreadsheetLayout, type SpreadsheetLayoutOptions, type SpreadsheetMergeInfo, type SpreadsheetMixedValue, type SpreadsheetPasteMode, type SpreadsheetPasteOptions, type SpreadsheetPoint, type SpreadsheetPreviewCellChangeSummary, type SpreadsheetPreviewDiffSummary, type SpreadsheetRange, type SpreadsheetRect, type SpreadsheetRenderCell, type SpreadsheetReplaceTarget, type SpreadsheetResizeDragState, type SpreadsheetResizeHandle, type SpreadsheetResolvedCellStyle, type SpreadsheetScrollState, type SpreadsheetScrollbarGeometry, type SpreadsheetScrollbarState, type SpreadsheetSelectionFormatState, type SpreadsheetSelectionState, type SpreadsheetSheetRenderModel, type SpreadsheetSize, type SpreadsheetSortDirection, type SpreadsheetUserTransactionOptions, type SpreadsheetViewport, type SpreadsheetViewportKind, SpreadsheetViewportManager, type SpreadsheetViewportManagerOptions, type SpreadsheetViewportState, applySpreadsheetAgentAction, applyWheelDelta, buildSpreadsheetAutoFillPlan, buildSpreadsheetClipboardPayload, buildSpreadsheetReplacePlan, buildSpreadsheetSheetRenderModel, clampScroll, clearSpreadsheetRange, computeScrollbarState, createColumnRangeSelection, createColumnSelection, createRowRangeSelection, createRowSelection, createSelection, cssPixelsToExcelColumnWidth, excelColumnWidthToCssPixels, expandRangeForMergedRanges, expandSelectionForMergedRanges, extendSelection, findSpreadsheetMatches, formatSpreadsheetDisplayValue, freezeStateFromPane, freezeStateFromSheet, getRenderCell, hitSpreadsheetResizeHandle, moveSelection, nextSpreadsheetMatch, normalizeSelectionRange, parseTsv, previewSpreadsheetAgentAction, rangeAddressForMatrix, rangeForSpreadsheetMatch, renderSpreadsheetEditor, resolveSpreadsheetCellStyle, resolveSpreadsheetRangeBorder, rowColumnKey, scrollFromThumbPosition, selectionAfterColumnDeletion, selectionAfterRowDeletion, serializeRangeToTsv, setSpreadsheetCellFormula, setSpreadsheetCellValue, setSpreadsheetColumnWidth, setSpreadsheetRangeValues, setSpreadsheetRowHeight, spreadsheetFilterValues, spreadsheetRowsForColumnFilters, spreadsheetRowsForFilter, spreadsheetSortRows, spreadsheetVisibleFilterValues, startSpreadsheetResizeDrag, summarizeSpreadsheetSelectionFormat, supportsSpreadsheetAutoFill, updateSpreadsheetResizeDrag };