Worksheet

getName(): Promise<string>;

Get the sheet name. Async — reads from Rust via IPC (cached after first call).

setName(name: string): Promise<void>;

Set the sheet name.

getIndex(): number;

Get the 0-based sheet index.

getSheetId(): SheetId;

Get the internal sheet ID.

setCell(address: string, value: any, options?: CellWriteOptions): Promise<void>;

Set a cell value by A1 address. String values starting with "=" are treated as formulas (e.g. "=SUM(B1:B10)"). Use `options.asFormula` to force formula interpretation without the "=" prefix.

setDateValue(row: number, col: number, date: Date): Promise<void>;

Set a date value in a cell, automatically applying date format.

setTimeValue(row: number, col: number, date: Date): Promise<void>;

Set a time value in a cell, automatically applying time format.

getCell(address: string): Promise<CellData>;

Get cell data by A1 address.

getRange(range: string): Promise<CellData[][]>;

Get a 2D array of cell data for a range (A1 notation).

setRange(range: string, values: any[][]): Promise<void>;

Set a 2D array of values into a range (A1 notation). String values starting with "=" are treated as formulas.

clearData(range: string): Promise<ClearResult>;

Clear all cell data (values and formulas) in a range (A1 notation, e.g. "A1:C3").

clear(range: string, applyTo?: ClearApplyTo): Promise<ClearResult>;

Unified clear with mode selection (OfficeJS Range.clear equivalent). @param range - A1 range string (e.g. "A1:C3") @param applyTo - What to clear: 'all' (default), 'contents', 'formats', 'hyperlinks'

clearOrResetContents(range: string): Promise<void>;

Clear cell contents with form control awareness (OfficeJS clearOrResetContents equivalent). For cells linked to form controls: resets the control to its default value (checkbox -> unchecked/false, comboBox -> first item/empty). For all other cells: clears contents normally (same as clear(range, 'contents')). @param range - A1 range string (e.g. "A1:C3")

getValue(address: string): Promise<CellValue>;

Get the computed value of a cell by A1 address. Returns null for empty cells.

getData(): Promise<CellValue[][]>;

Get all cell values in the used range as a 2D array. Returns [] if sheet is empty.

getFormula(address: string): Promise<string | null>;

Get the formula of a cell by A1 address (null if not a formula cell).

getFormulas(range: string): Promise<(string | null)[][]>;

Get formulas for a range. Returns 2D array: formula string or null per cell.

getFormulaArray(address: string): Promise<string | null>;

Get the array formula for a cell that is part of a dynamic array spill. If the cell is the source of a dynamic array (e.g., =SEQUENCE(5)), returns the formula. If the cell is a spill member (projected from a source), returns the source cell's formula. Returns null if the cell is not part of an array. @param address - A1-style cell address @returns The array formula string, or null if not an array cell

getRawCellData(address: string, includeFormula?: boolean): Promise<RawCellData>;

Get raw cell data (value, formula, format, borders, etc.) by A1 address.

getRawRangeData(range: string, includeFormula?: boolean): Promise<RawCellData[][]>;

Get raw data for a range as a 2D array.

getRangeWithIdentity(
    startRow: number,
    startCol: number,
    endRow: number,
    endCol: number,
  ): Promise<IdentifiedCellData[]>;

Get all non-empty cells in a range with stable CellId identity. Returns a flat array of cells (not a 2D grid) — only cells with data are included. Each cell includes its CellId, position, computed value, formula text (if formula cell), and pre-formatted display string. Used by operations that need identity-aware cell data (find-replace, clipboard, cell relocation).

describe(address: string): Promise<string>;

Get a human-readable description of a cell: "Revenue | =SUM(B2:B10) | [bold]"

describeRange(range: string, includeStyle?: boolean): Promise<string>;

Get a tabular description of a range with formula abbreviation.

summarize(options?: SummaryOptions): Promise<string>;

Get a sheet overview summary for agent context.

getUsedRange(): Promise<string | null>;

Get the used range as an A1 string, or null if the sheet is empty.

getCurrentRegion(row: number, col: number): Promise<CellRange>;

Get the contiguous data region around a cell (Excel's Ctrl+Shift+* / CurrentRegion).

findDataEdge(
    row: number,
    col: number,
    direction: 'up' | 'down' | 'left' | 'right',
  ): Promise<{ row: number; col: number }>;

Find the data edge in a direction (Excel's Ctrl+Arrow). Single bridge call to Rust.

findLastRow(col: number): Promise<{ lastDataRow: number | null; lastFormatRow: number | null }>;

Find the last populated row in a column. Returns data and formatting edges.

findLastColumn(
    row: number,
  ): Promise<{ lastDataCol: number | null; lastFormatCol: number | null }>;

Find the last populated column in a row. Returns data and formatting edges.

findCells(predicate: (cell: CellData) => boolean): Promise<string[]>;

Find all cells matching a predicate. Returns A1 addresses.

findByValue(value: any): Promise<string[]>;

Find all cells with a specific value. Returns A1 addresses.

findByFormula(pattern: RegExp): Promise<string[]>;

Find all cells whose formula matches a regex pattern. Returns A1 addresses.

regexSearch(patterns: string[], options?: SearchOptions): Promise<SearchResult[]>;

Search cells using regex patterns.

signCheck(range?: string, options?: SignCheckOptions): Promise<SignCheckResult>;

Detect cells whose numeric sign disagrees with their neighbors. Returns anomalies sorted by severity — the agent decides which are real errors.

findInRange(range: string, text: string, options?: SearchOptions): Promise<SearchResult | null>;

Find the first cell matching text within a range (OfficeJS Range.find equivalent). @param range - A1 range string to search within @param text - Text or regex pattern to search for @param options - Search options (matchCase, entireCell) @returns The first matching SearchResult, or null if no match found

replaceAll(
    range: string,
    text: string,
    replacement: string,
    options?: SearchOptions,
  ): Promise<number>;

Find and replace all occurrences within a range (OfficeJS Range.replaceAll equivalent). @param range - A1 range string to search within @param text - Text to find @param replacement - Replacement text @param options - Search options (matchCase, entireCell) @returns Number of replacements made

getExtendedRange(
    range: string,
    direction: 'up' | 'down' | 'left' | 'right',
    activeCell?: { row: number; col: number },
  ): Promise<CellRange>;

Get the extended range in a direction (OfficeJS Range.getExtendedRange / Ctrl+Shift+Arrow). From the active cell (default: top-left of range), finds the data edge in the given direction and returns a range extending from the original range to that edge. @param range - A1 range string (current selection) @param direction - Direction to extend @param activeCell - Optional active cell override (default: top-left of range) @returns Extended range as CellRange

isEntireColumn(range: string | CellRange): boolean;

Check if a range represents entire column(s) (e.g., "A:C"). @param range - A1 range string or CellRange object @returns True if the range represents entire column(s)

isEntireRow(range: string | CellRange): boolean;

Check if a range represents entire row(s) (e.g., "1:5"). @param range - A1 range string or CellRange object @returns True if the range represents entire row(s)

getVisibleView(range: string): Promise<VisibleRangeView>;

Get only the visible (non-hidden) rows from a range (OfficeJS RangeView equivalent). Filters out rows hidden by AutoFilter or manual hide operations. Returns cell values for visible rows only, along with the absolute row indices. @param range - A1 range string (e.g., "A1:Z100") @returns Visible rows' values and their indices

getSpecialCells(cellType: CellType, valueType?: CellValueType): Promise<CellAddress[]>;

Find cells matching a special cell type (OfficeJS Range.getSpecialCells equivalent). Returns addresses of cells matching the specified type within the used range. Optionally filter by value type when cellType is `Constants` or `Formulas`. @param cellType - The type of cells to find @param valueType - Optional value type filter (only for Constants/Formulas) @returns Array of matching cell addresses

getDisplayValue(address: string): Promise<string>;

Get the display value (formatted string) for a cell by A1 address.

getDisplayText(range: string): Promise<string[][]>;

Get formatted display text for an entire range as a 2D array (OfficeJS Range.text equivalent). @param range - A1 range string @returns 2D array of formatted display strings

getValueTypes(range: string): Promise<RangeValueType[][]>;

Get per-cell value type classification for a range (OfficeJS Range.valueTypes equivalent). @param range - A1 range string @returns 2D array of RangeValueType enums

getNumberFormatCategories(range: string): Promise<NumberFormatCategory[][]>;

Get per-cell number format category for a range (OfficeJS Range.numberFormatCategories equivalent). @param range - A1 range string @returns 2D array of NumberFormatCategory enums

sortRange(range: string, options: SortOptions): Promise<void>;

Sort a range by the specified options.

autoFill(
    sourceRange: string,
    targetRange: string,
    fillMode?: AutoFillMode,
  ): Promise<AutoFillResult>;

Autofill from source range into target range. @param sourceRange - Source range in A1 notation (e.g., "A1:A3") @param targetRange - Target range to fill into (e.g., "A4:A10") @param fillMode - Fill behavior. Default: 'auto' (detect pattern).

fillSeries(range: string, options: FillSeriesOptions): Promise<void>;

Fill a range with a series (Edit > Fill > Series dialog equivalent). More explicit than autoFill — caller specifies exact series parameters. The range contains BOTH source cells (first row/col) and target cells (rest). The kernel splits them based on direction. @param range - Range in A1 notation containing source + target cells @param options - Series parameters (type, step, stop, direction, etc.)

moveTo(sourceRange: string, targetRow: number, targetCol: number): Promise<void>;

Move (relocate) cells from a source range to a target position. Moves cell values, formulas, and formatting. Formula references within the moved range are adjusted to the new position. The source range is cleared after the move. @param sourceRange - Source range in A1 notation (e.g., "A1:B10") @param targetRow - Destination top-left row (0-based) @param targetCol - Destination top-left column (0-based)

copyFrom(sourceRange: string, targetRange: string, options?: CopyFromOptions): Promise<void>;

Copy cells from a source range to a target range with optional paste-special behavior. Supports selective copy (values only, formulas only, formats only, or all), skip-blanks, and transpose. Maps to OfficeJS Range.copyFrom(). @param sourceRange - Source range in A1 notation (e.g., "A1:B10") @param targetRange - Target range in A1 notation (e.g., "D1:E10") @param options - Optional paste-special behavior (copyType, skipBlanks, transpose)

setCells(cells: Array<{ addr: string; value: any }>): Promise<SetCellsResult>;

Bulk-write scattered cell values and/or formulas in a single IPC call. Values starting with "=" are treated as formulas. Supports both A1 addressing and numeric (row, col) addressing.

createTable(name: string, options: CreateTableOptions): Promise<void>;

Create a table from headers and data in a single call. Writes `[headers, ...data]` starting at `startCell` (default "A1"), then creates an Excel table over the written range. @param name - Table name (must be unique in the workbook) @param options - Headers, data rows, and optional start cell

toCSV(options?: { separator?: string }): Promise<string>;

Export the used range as a CSV string (RFC 4180 compliant). Fields containing commas, quotes, or newlines are quoted. Double-quotes inside fields are escaped as "". Formula injection is prevented by prefixing `=`, `+`, `-`, `@` with a tab character. @param options - Optional separator (default ",")

toJSON(options?: { headerRow?: number | 'none' }): Promise<Record<string, CellValue>[]>;

Export the used range as an array of row objects. By default, the first row is used as header keys. Pass `headerRow: 'none'` to use column letters (A, B, C, ...) as keys. Pass `headerRow: N` to use a specific 0-based row as headers. @param options - Optional header row configuration

getDependents(address: string): Promise<string[]>;

Get cells that depend on this cell by A1 address.

getPrecedents(address: string): Promise<string[]>;

Get cells that this cell depends on by A1 address.

getSelectionAggregates(ranges: CellRange[]): Promise<AggregateResult>;

Get aggregates (SUM, COUNT, AVG, MIN, MAX) for selected ranges.

formatValues(entries: FormatEntry[]): Promise<string[]>;

Batch-format values using number format codes. Returns formatted strings.

isVisible(): boolean;

Check if the sheet is visible (sync -- local metadata).

setVisible(visible: boolean): Promise<void>;

Show or hide the sheet.

getVisibility(): Promise<'visible' | 'hidden' | 'veryHidden'>;

Get the visibility state of the sheet ('visible', 'hidden', or 'veryHidden').

setVisibility(state: 'visible' | 'hidden' | 'veryHidden'): Promise<void>;

Set the visibility state of the sheet.

on(event: SheetEvent | string, handler: (event: any) => void): () => void;

setBoundsReader(reader: IObjectBoundsReader): void;

Inject the bounds reader (from the renderer's SceneGraphBoundsReader) so that floating-object handles can resolve pixel bounds via `handle.getBounds()`. Calling this invalidates cached typed collections so they pick up the new reader on their next access.