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. @deprecated Use the `sheetId` property instead.

setCell(address: string, value: CellValuePrimitive | Date, 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. Use `options.literal` to store strings starting with "=" as literal text. Date values are automatically converted via setDateValue().

setDateValue(row: number, col: number, year: number, month: number, day: number): Promise<void>;

Set a calendar date in a cell, automatically applying a date format. Four input forms (in order of preference for unambiguous semantics): 1. **Calendar parts** — `setDateValue(row, col, year, month, day)` / `setDateValue(addr, year, month, day)`. No `Date`, no timezone — the calendar value is the input. 2. **ISO calendar string** — `setDateValue(row, col, '2026-03-01')` / `setDateValue(addr, '2026-03-01')`. No `Date`, no timezone. 3. **`Date` instant** — `setDateValue(row, col, date)` / `setDateValue(addr, date)`. Resolved against the session's `userTimezone` (set when the workbook was created). 4. **`Date` instant with explicit override** — `setDateValue(row, col, date, { tz })` / `setDateValue(addr, date, { tz })`. Use when a `Date` should be interpreted in a frame other than the session default. @see plans/active/ux/datetime/round-1/session-user-timezone.md

setTimeValue(row: number, col: number, hours: number, minutes: number, seconds: number): Promise<void>;

Set a time-of-day in a cell, automatically applying a time format. Three input forms: 1. **Time parts** — `setTimeValue(row, col, hours, minutes, seconds)` / `setTimeValue(addr, hours, minutes, seconds)`. 2. **`Date` instant** — `setTimeValue(row, col, date)` / `setTimeValue(addr, date)`. Resolved against the session's `userTimezone`. 3. **`Date` instant with explicit override** — `setTimeValue(row, col, date, { tz })`.

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).

getRanges(addresses: string): Promise<CellData[][][]>;

Get cell data for multiple ranges at once (spreadsheet special-cell typeWorksheet.getRanges equivalent). @param addresses - Comma-separated A1-style range addresses (e.g. "A1:B5,D1:E5,G1") @returns Array of 2D cell data arrays, one per address

setRange(range: string, values: (CellValuePrimitive | Date)[][]): Promise<void>;

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

setArrayFormula(range: CellRange, formula: string): Promise<void>;

Enter a CSE (`Ctrl+Shift+Enter`) array formula on the given range. The formula is stored only on the top-left anchor; covered cells are projections of the array result and read-only. Editing any covered cell via `setCell` is rejected by Rust compute-core with `ComputeError::PartialArrayWrite`. Tearing down the array formula is `clear` / `setCell(anchor, null)` on the anchor. Distinct from a regular `setCell` of an array-returning formula: dynamic-array spills allow blocker-literal writes into spill members (raise `#SPILL!`), CSE rejects all partial writes.

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 (spreadsheet special-cell typeRange.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 (spreadsheet special-cell typeclearOrResetContents 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")

getControl(address: string): Promise<CellControl | undefined>;

Get the cell control (e.g., checkbox) for a cell by A1 address. Returns undefined if the cell does not contain a control.

setControl(address: string, control: CellControl | undefined): Promise<void>;

Set or clear a cell control by A1 address. Pass undefined to remove the control and revert to a plain cell.

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

Get the computed value of a cell by A1 address. Returns null for empty cells. Error cells are returned as display strings (e.g. "#DIV/0!").

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

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

getValues(range: string): Promise<CellValue[][]>;

Get cell values for a range as a 2D array. Returns primitive values only (no formatting, formulas, or metadata). Empty cells are null. This is the most common read pattern for SDK/LLM consumers. @param range - A1-style range string (e.g. "A1:C10") @returns 2D array of cell values

evaluate(expression: string): Promise<CellValue>;

Evaluate a formula expression in the context of this sheet without writing it to any cell. The expression should not include the leading `=`. @example const total = await ws.evaluate("SUM(A1:A10)"); @param expression - Formula expression string (e.g. "SUM(A1:A10)") @returns The computed result value

validateFormulaSyntax(formula: string): Promise<FormulaSyntaxValidationError | null>;

Validate a formula expression in the context of this sheet without writing it to any cell. Returns `null` when the formula is syntactically valid. Unlike {@link evaluate}, this is a raw commit-time syntax check: it does not normalize or auto-correct incomplete input before parsing.

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.

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

Get formulas for a range in R1C1 notation. Returns 2D array: R1C1 formula string or null per cell. References are converted relative to each cell's position: - `$A$1` (absolute) becomes `R1C1` - `A1` relative to cell B2 becomes `R[-1]C[-1]` - `$A1` relative to cell B2 becomes `R[-1]C1` (mixed) @param range - A1-style range string (e.g. "A1:C10")

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 | CellRange, options?: {
        includeFormula?: boolean;
    }): Promise<RawCellData[][]>;

Get raw data for a range as a 2D array (A1 notation or CellRange).

getRangeWithIdentity(range: string | CellRange): 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 or the entire used range. With address: returns compact cell string — "Revenue | =SUM(B2:B10) | [bold]" Without address: returns describeRange() over the used range (or empty string if sheet is empty)

describeRange(range: string | CellRange, 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<CellRange | null>;

Get the used range, 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, range?: string): Promise<string[]>;

Find all cells matching a predicate. Returns A1 addresses. Searches entire sheet or optionally within a range.

findByValue(value: CellValue, range?: string): Promise<string[]>;

Find all cells with a specific value. Returns A1 addresses. Searches entire sheet or optionally within a range.

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

Find all cells whose formula matches a regex pattern. Returns A1 addresses. Searches entire sheet or optionally within a range.

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?: FindInRangeOptions): Promise<SearchResult | null>;

Find the first cell matching text within a range (spreadsheet special-cell typeRange.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?: FindInRangeOptions): Promise<number>;

Find and replace all occurrences within a range (spreadsheet special-cell typeRange.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 (spreadsheet special-cell typeRange.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 (visible range-view 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<string[]>;

Find cells matching a special cell type (spreadsheet special-cell typeRange.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

getValueForEditing(row: number, col: number, editText?: string): Promise<string>;

Get the edit-mode string representation of a cell value. Used by formula bar and in-cell editing. For formula cells, returns the formula string (e.g. "=SUM(A1:A10)"). For date/time cells, returns pre-computed edit text if available. For value cells, returns the raw value as a string. @param row - Row index (0-based) @param col - Column index (0-based) @param editText - Optional pre-computed edit text (for date/time cells) @returns The string to display in edit mode

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

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

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

Get the formatted display values for a range as a 2D array. Returns the same formatted strings shown in each cell (number formats applied, dates formatted, etc.). This is the range counterpart to `getDisplayValue()`. @param range - A1-style range string (e.g. "A1:C10") @returns 2D array of formatted display strings

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

Get per-cell value type classification for a range (spreadsheet special-cell typeRange.valueTypes equivalent). @param range - A1 range string or CellRange object @returns 2D array of RangeValueType enums

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

Get per-cell number format category for a range (spreadsheet special-cell typeRange.numberFormatCategories equivalent). @param range - A1 range string or CellRange object @returns 2D array of NumberFormatCategory enums

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

Sort a range by the specified options (A1 notation).

sortByColor(range: string | CellRange, opts: SortByColorOptions): Promise<void>;

Sort a range by cell or font color, putting matched-color rows on top or bottom. Convenience wrapper over {@link sortRange} with a single color-keyed criterion. Excel/ECMA-376 vocabulary: `'fill'` is the cell background fill, `'font'` is the cell font color. Compares the resolved per-cell effective format. @param range - A1-style range string or CellRange object @param opts - Color sort options (column, color type, target color, top/bottom position)

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 spreadsheet special-cell typeRange.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: CellValuePrimitive | Date;
    }>): 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.

toCSV(options?: {
        separator?: string;
        range?: 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';
        range?: string;
    }): 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 and range

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.

enableCalculation: boolean;

Per-sheet toggle that controls whether formulas on this sheet are recalculated. When `false`, formulas retain their last computed value but do not recalculate when dependencies change. Defaults to `true`.

calculate(markAllDirty?: boolean): Promise<void>;

Force recalculation of this sheet. @param markAllDirty - If `true`, marks all formula cells on this sheet as dirty before recalculating (equivalent to a full sheet recalc). Defaults to `false`, which recalculates only cells already marked dirty.

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.

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.

getNext(visibleOnly?: boolean): Promise<Worksheet>;

Returns the next worksheet. If `visibleOnly` is true, skips hidden sheets. Throws if no next sheet exists.

getNextOrNull(visibleOnly?: boolean): Promise<Worksheet | null>;

Returns the next worksheet, or null if none exists. If `visibleOnly` is true, skips hidden sheets.

getPrevious(visibleOnly?: boolean): Promise<Worksheet>;

Returns the previous worksheet. If `visibleOnly` is true, skips hidden sheets. Throws if no previous sheet exists.

getPreviousOrNull(visibleOnly?: boolean): Promise<Worksheet | null>;

Returns the previous worksheet, or null if none exists. If `visibleOnly` is true, skips hidden sheets.

on(event: string, handler: (event: unknown) => void): CallableDisposable;

refreshActiveCellData(row: number, col: number): Promise<void>;

Refresh the active-cell metadata cache (Stream C fix). Call this when the active cell changes (selection move) so the viewport reader's `getActiveCellData()` returns up-to-date metadata — including `isCseAnchor` — and the formula bar can immediately display `{=…}` braces for CSE array formula cells. Looks up the cellId at the given position and calls the compute bridge's `refreshActiveCell`. Safe to call speculatively; no-ops if the cell has no id (empty cell).

refreshActiveCellEditSource(row: number, col: number): Promise<void>;

Refresh the active-cell edit-source read model for the given cell. This is infrastructure for edit-entry hot paths. It is intentionally scoped to the active cell rather than exposing arbitrary synchronous cell reads.

getActiveCellEditSource(row: number, col: number): ActiveCellEditSource | null;

Synchronously read the active-cell edit-source cache when it matches the requested cell and is fresh. Returns null for stale/missing/different-cell data so callers can fall back to one Rust-owned edit-source query.

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.