@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/api/types.d.ts

@@ -0,0 +1,1542 @@
+/**
+ * Unified Spreadsheet API -- Shared Types
+ *
+ * Additional types needed by the unified API that don't already exist in core.
+ * Core types (CellValue, CellFormat, CellRange, etc.) are imported and
+ * re-exported so consumers can import everything from '@mog/spreadsheet-contracts/api'.
+ */
+import type { FormulaA1 } from '../cells/formula-string';
+import type { CellBorders, CellFormat, CellRange, CellValue, FormattedText } from '../core/core';
+import type { CFResult } from '../data/conditional-format';
+import type { ColumnFilterCriteria } from '../data/filter';
+import type { SlicerSource, SlicerStyle, TimelineLevel } from '../data/slicers';
+import type { TableStylePreset, TotalFunction } from '../data/tables';
+import type { SpreadsheetEvent as InternalSpreadsheetEvent } from '../events';
+export type { CellAddress, CellBorders, CellData, CellFormat, CellRange, CellValue, ResolvedCellFormat, SheetId, SheetInfo, } from '../core/core';
+export type { SheetMeta } from '../store/store-types';
+export type { PrintSettings } from '../core/core';
+import type { ObjectAnchorType, ObjectFill, PictureAdjustments, PictureCrop, ShapeOutline, ShapeText, ShapeType, TextMargins } from '../objects/floating-objects';
+import type { OuterShadowEffect } from '../wordart/effects';
+export type { LineDash, ObjectAnchorType, ObjectFill, PictureAdjustments, PictureCrop, ShapeOutline, ShapeText, ShapeType, TextMargins, } from '../objects/floating-objects';
+/**
+ * Shape configuration for creating/updating shapes.
+ *
+ * Uses simple integer positions (anchorRow/anchorCol) for the public API.
+ * Internal storage uses CellId-based ObjectPosition.
+ * Preserves full fidelity: gradient fills, arrowhead outlines, rich text.
+ */
+export interface ShapeConfig {
+    /** Shape type (rect, ellipse, triangle, etc.) */
+    type: ShapeType;
+    /** Anchor row (0-based) */
+    anchorRow: number;
+    /** Anchor column (0-based) */
+    anchorCol: number;
+    /** X offset from anchor cell in pixels */
+    xOffset?: number;
+    /** Y offset from anchor cell in pixels */
+    yOffset?: number;
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+    /** Absolute pixel X on the sheet. When set, Rust resolves to anchorCol + xOffset. */
+    pixelX?: number;
+    /** Absolute pixel Y on the sheet. When set, Rust resolves to anchorRow + yOffset. */
+    pixelY?: number;
+    /** Optional name for the shape */
+    name?: string;
+    /** Fill configuration (solid, gradient with stops/angle, or none) */
+    fill?: ObjectFill;
+    /** Outline/stroke configuration (with optional arrowheads) */
+    outline?: ShapeOutline;
+    /** Rich text content inside the shape (with CellFormat) */
+    text?: ShapeText;
+    /** Shadow effect */
+    shadow?: OuterShadowEffect;
+    /** Rotation angle in degrees (0-360) */
+    rotation?: number;
+    /** Whether the shape is locked */
+    locked?: boolean;
+    /** Shape-specific adjustments (e.g., cornerRadius for roundRect) */
+    adjustments?: Record<string, number>;
+    /** Whether the shape is visible (default: true). */
+    visible?: boolean;
+    /** Anchor mode: how the shape anchors to cells (twoCell/oneCell/absolute). */
+    anchorMode?: ObjectAnchorType;
+}
+/**
+ * Shape as returned by get/list operations.
+ *
+ * Extends ShapeConfig with identity and metadata fields.
+ * Same pattern as Chart extends ChartConfig.
+ */
+export interface Shape extends ShapeConfig {
+    /** Unique shape ID */
+    id: string;
+    /** Sheet ID the shape belongs to */
+    sheetId: string;
+    /** Z-order within the sheet */
+    zIndex: number;
+    /** Creation timestamp (Unix ms) */
+    createdAt?: number;
+    /** Last update timestamp (Unix ms) */
+    updatedAt?: number;
+}
+export type { Chart, ChartBorder, ChartConfig, ChartType, DataLabelConfig, ImageExportOptions, SeriesConfig, } from '../data/charts';
+/** A single segment of rich text content. */
+export interface RichTextSegment {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    color?: string;
+    fontName?: string;
+    fontSize?: number;
+}
+/** A cell comment (thread-aware). */
+export interface Comment {
+    id: string;
+    cellId: string;
+    cellAddress: string;
+    text: string;
+    author: string;
+    threadId?: string;
+    resolved?: boolean;
+    createdAt?: number;
+    parentId?: string;
+    authorId?: string;
+    modifiedAt?: number;
+    content?: RichTextSegment[];
+}
+/** A cell note (simple, single string per cell). */
+export interface Note {
+    content: string;
+    author: string;
+    cellAddress: string;
+}
+/** Options controlling how a cell value is interpreted when written. */
+export interface CellWriteOptions {
+    /** If true, value is treated as a formula (prefixed with =) */
+    asFormula?: boolean;
+}
+/**
+ * Complete raw cell data including formula, formatting, and metadata.
+ *
+ * Unlike `CellData` from core (which is the minimal read type), `RawCellData`
+ * includes all optional cell metadata useful for bulk reads and LLM presentation.
+ */
+export interface RawCellData {
+    /** The computed cell value */
+    value: CellValue;
+    /** The formula string with "=" prefix, if the cell contains a formula */
+    formula?: FormulaA1;
+    /** Cell formatting */
+    format?: CellFormat;
+    /** Cell borders */
+    borders?: CellBorders;
+    /** Cell comment/note text */
+    comment?: string;
+    /** Hyperlink URL */
+    hyperlink?: string;
+    /** Whether the cell is part of a merged region */
+    isMerged?: boolean;
+    /** The merged region this cell belongs to (A1 notation, e.g., "A1:B2") */
+    mergedRegion?: string;
+}
+/**
+ * Cell data enriched with stable CellId identity.
+ *
+ * Used by operations that need to reference cells by identity (not position),
+ * such as find-replace, clipboard, and cell relocation. The CellId is a CRDT-safe
+ * identifier that survives row/column insert/delete operations.
+ *
+ * Unlike `CellData` (position-implied), `IdentifiedCellData` includes explicit
+ * position and identity for flat iteration over non-empty cells in a range.
+ */
+export interface IdentifiedCellData {
+    /** Stable cell identity (CRDT-safe, survives structural changes). */
+    cellId: string;
+    /** Row index (0-based). */
+    row: number;
+    /** Column index (0-based). */
+    col: number;
+    /** The computed cell value (null for empty cells). */
+    value: CellValue | null;
+    /** Formula text (e.g., "=A1+B1") when the cell contains a formula. */
+    formulaText?: string;
+    /** Pre-formatted display string (e.g., "$1,234.56" for a currency-formatted number). */
+    displayString: string;
+}
+/** Options for sorting a range of cells. */
+export interface SortOptions {
+    /** Columns to sort by, in priority order */
+    columns: SortColumn[];
+    /** Whether the first row of the range contains headers (default: false) */
+    hasHeaders?: boolean;
+}
+/** A single column sort specification. */
+export interface SortColumn {
+    /** Column index (0-based, relative to the sort range) */
+    column: number;
+    /** Sort direction as boolean (default: true = ascending). Use `direction` for string form. */
+    ascending?: boolean;
+    /** Sort direction as 'asc' | 'desc'. Takes precedence over `ascending` if both are set. */
+    direction?: 'asc' | 'desc';
+    /** What to sort by (default: 'value') */
+    sortBy?: 'value' | 'cellColor' | 'fontColor';
+    /** Case sensitive comparison (default: false) */
+    caseSensitive?: boolean;
+}
+/** Current auto-filter state for a sheet. */
+export interface FilterState {
+    /** The range the auto-filter is applied to (A1 notation) */
+    range: string;
+    /** Per-column filter criteria, keyed by column index */
+    columns: Map<number, ColumnFilterCriteria>;
+}
+export type { CFAboveAverageRule, CFCellValueRule, CFColorPoint, CFColorScale, CFColorScaleRule, CFContainsBlanksRule, CFContainsErrorsRule, CFContainsTextRule, CFDataBar, CFDataBarAxisPosition, CFDataBarRule, CFDuplicateValuesRule, CFFormulaRule, CFIconSet, CFIconSetName, CFIconSetRule, CFIconThreshold, CFOperator, CFResult, CFRule, CFRuleBase, CFRuleInput, CFRuleType, CFStyle, CFTextOperator, CFTimePeriodRule, CFTop10Rule, CFValueType, ConditionalFormat, DatePeriod, } from '../data/conditional-format';
+/** A data validation rule for cells. */
+export interface ValidationRule {
+    /** Schema ID — populated when reading, optional when creating (auto-generated if omitted) */
+    id?: string;
+    /** The cell range this rule applies to in A1 notation (e.g., "A1:B5") — populated when reading */
+    range?: string;
+    /** The validation type. 'none' indicates no validation rule is set. */
+    type: 'none' | 'list' | 'wholeNumber' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+    /** Comparison operator */
+    operator?: 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'between' | 'notBetween';
+    /** Primary constraint value or formula */
+    formula1?: string | number;
+    /** Secondary constraint value or formula (for 'between' / 'notBetween') */
+    formula2?: string | number;
+    /** Explicit list of allowed values (for 'list' type) */
+    values?: string[];
+    /** Source reference for list validation: A1 range (e.g., "=Sheet1!A1:A10") or formula (e.g., "=INDIRECT(A1)"). Prefixed with "=" for formulas. */
+    listSource?: string;
+    /** Whether blank cells pass validation (default: true) */
+    allowBlank?: boolean;
+    /** Whether to show a dropdown arrow for list validations */
+    showDropdown?: boolean;
+    /** Whether to show an input message when the cell is selected */
+    showInputMessage?: boolean;
+    /** Title for the input message */
+    inputTitle?: string;
+    /** Body text for the input message */
+    inputMessage?: string;
+    /** Whether to show an error alert on invalid input */
+    showErrorAlert?: boolean;
+    /** Error alert style */
+    errorStyle?: 'stop' | 'warning' | 'information';
+    /** Title for the error alert */
+    errorTitle?: string;
+    /** Body text for the error alert */
+    errorMessage?: string;
+}
+/** Information about a merged cell region. */
+export interface MergedRegion {
+    /** The merged range in A1 notation (e.g., "A1:B2") */
+    range: string;
+    /** Start row (0-based) */
+    startRow: number;
+    /** Start column (0-based) */
+    startCol: number;
+    /** End row (0-based, inclusive) */
+    endRow: number;
+    /** End column (0-based, inclusive) */
+    endCol: number;
+}
+/** Result of a goal seek operation. */
+export interface GoalSeekResult {
+    /** Whether a solution was found */
+    found: boolean;
+    /** The value found for the changing cell (if found) */
+    value?: number;
+    /** Number of iterations performed */
+    iterations?: number;
+}
+/** Non-fatal warning attached to an operation result. */
+export interface OperationWarning {
+    /** Machine-readable warning code */
+    code: string;
+    /** Human-readable description */
+    message: string;
+    /** Optional structured context for programmatic handling */
+    context?: Record<string, unknown>;
+}
+/** Result of a bulk setCells() operation. */
+export interface SetCellsResult {
+    /** Number of cells successfully written */
+    cellsWritten: number;
+    /** Per-cell errors, if any (omitted when all succeed) */
+    errors?: Array<{
+        addr: string;
+        error: string;
+    }> | null;
+    /** Non-fatal warnings (e.g., deduplication, coercion) */
+    warnings?: OperationWarning[];
+}
+/** Result of a format set/setRange operation. */
+export interface FormatChangeResult {
+    /** Number of cells whose formatting was changed */
+    cellCount: number;
+}
+/** Confirmation returned by clearData() and clear(). */
+export interface ClearResult {
+    /** Number of cells in the cleared range. */
+    cellCount: number;
+}
+/** Options for creating a new table. */
+export interface TableOptions {
+    /** Table name (auto-generated if omitted) */
+    name?: string;
+    /** Whether the first row of the range contains headers (default: true) */
+    hasHeaders?: boolean;
+    /** Table style preset name */
+    style?: string;
+}
+/** Options for the one-liner createTable() convenience method. */
+export interface CreateTableOptions {
+    /** Column header names. */
+    headers: string[];
+    /** Data rows (each row must match headers length). */
+    data: CellValue[][];
+    /** Top-left cell address to start writing (default: "A1"). */
+    startCell?: string;
+}
+/** Information about an existing table. */
+export interface TableInfo {
+    /** Internal table identifier (opaque string) */
+    id?: string;
+    /** Table name */
+    name: string;
+    /** Table range in A1 notation */
+    range: string;
+    /** Whether the table has a header row */
+    hasHeaders: boolean;
+    /** Table style preset name */
+    style?: TableStylePreset;
+    /** Column definitions */
+    columns: TableColumn[];
+    /** Whether the total row is visible */
+    showTotals?: boolean;
+    /** Whether first column is highlighted */
+    highlightFirstColumn?: boolean;
+    /** Whether last column is highlighted */
+    highlightLastColumn?: boolean;
+    /** Whether banded columns are shown */
+    showBandedColumns?: boolean;
+    /** Whether banded rows are shown */
+    showBandedRows?: boolean;
+    /** Whether filter buttons are shown */
+    showFilterButton?: boolean;
+    /** Whether the header row is shown (mirrors hasHeaders) */
+    showHeaders?: boolean;
+}
+/** A single column in a table. */
+export interface TableColumn {
+    /** Column header name */
+    name: string;
+    /** Column index within the table (0-based) */
+    index: number;
+    /** Total row function type */
+    totalFunction?: TotalFunction;
+    /** Calculated column formula */
+    calculatedFormula?: string;
+}
+/** Configuration for creating or describing a pivot table. */
+export interface PivotTableConfig {
+    /** Pivot table name */
+    name: string;
+    /** Source data range in A1 notation (e.g., "Sheet1!A1:E100") */
+    dataSource: string;
+    /** Target sheet name (defaults to a new sheet) */
+    targetSheet?: string;
+    /** Target cell address (defaults to A1) */
+    targetAddress?: string;
+    /** Field names for the row area */
+    rowFields?: string[];
+    /** Field names for the column area */
+    columnFields?: string[];
+    /** Value field configurations */
+    valueFields?: PivotValueField[];
+    /** Field names for the filter area */
+    filterFields?: string[];
+}
+/** A value field in a pivot table. */
+export interface PivotValueField {
+    /** Source field name */
+    field: string;
+    /** Aggregation function */
+    aggregation: 'sum' | 'count' | 'average' | 'max' | 'min';
+    /** Custom label for the value field */
+    label?: string;
+}
+/**
+ * Handle for interacting with an existing pivot table.
+ *
+ * Returned by `worksheet.getPivotTable()`. Provides methods to query
+ * and modify the pivot table's field configuration.
+ */
+export interface PivotTableHandle {
+    /** Unique pivot table identifier (readonly) */
+    readonly id: string;
+    /** Get the pivot table name */
+    getName(): string;
+    /** Get the current configuration including all fields */
+    getConfig(): PivotTableConfig;
+    /** Add a field to the row, column, or filter area */
+    addField(field: string, area: 'row' | 'column' | 'filter', position?: number): void;
+    /** Add a value field with aggregation */
+    addValueField(field: string, aggregation: PivotValueField['aggregation'], label?: string): void;
+    /** Remove a field by name */
+    removeField(fieldName: string): void;
+    /** Change the aggregation function of a value field */
+    changeAggregation(valueFieldLabel: string, newAggregation: PivotValueField['aggregation']): void;
+    /** Rename a value field's display label */
+    renameValueField(currentLabel: string, newLabel: string): void;
+    /** Refresh the pivot table from its data source */
+    refresh(): Promise<void>;
+}
+/** Summary information about an existing pivot table. */
+export interface PivotTableInfo {
+    /** Pivot table name */
+    name: string;
+    /** Source data range (e.g., "Sheet1!A1:D100") */
+    dataSource: string;
+    /** Range occupied by the pivot table content */
+    contentArea: string;
+    /** Range occupied by filter dropdowns (if any) */
+    filterArea?: string;
+    /** Output anchor location as A1 reference (e.g., "G1") */
+    location?: string;
+    /** Row dimension field names */
+    rowFields?: string[];
+    /** Column dimension field names */
+    columnFields?: string[];
+    /** Value fields with aggregation info */
+    valueFields?: PivotValueField[];
+    /** Filter field names */
+    filterFields?: string[];
+}
+/** A single flat record from a pivot query result. */
+export interface PivotQueryRecord {
+    /** Dimension values keyed by field name (e.g., { Region: "North", Year: 2021 }) */
+    dimensions: Record<string, CellValue>;
+    /** Aggregated values keyed by value field label (e.g., { "Sum of Amount": 110 }) */
+    values: Record<string, CellValue>;
+}
+/** Result of queryPivot() — flat, agent-friendly records instead of hierarchy trees. */
+export interface PivotQueryResult {
+    /** Pivot table name */
+    pivotName: string;
+    /** Row dimension field names */
+    rowFields: string[];
+    /** Column dimension field names */
+    columnFields: string[];
+    /** Value field labels */
+    valueFields: string[];
+    /** Flat records — one per data intersection, excluding subtotals and grand totals */
+    records: PivotQueryRecord[];
+    /** Total source row count */
+    sourceRowCount: number;
+}
+/** Configuration for creating a new slicer. */
+export interface SlicerConfig {
+    /** Name of the table to connect the slicer to */
+    tableName?: string;
+    /** Column name within the table to filter on */
+    columnName?: string;
+    /** Display name for the slicer (auto-generated if omitted) */
+    name?: string;
+    /** Position and dimensions in pixels */
+    position?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Data source connection (rich alternative to tableName/columnName) */
+    source?: SlicerSource;
+    /** Slicer caption (header text) */
+    caption?: string;
+    /** Style configuration (partial for incremental updates) */
+    style?: Partial<SlicerStyle>;
+    /** Show slicer header */
+    showHeader?: boolean;
+    /** Currently selected date range start (timeline slicers) */
+    selectedStartDate?: number;
+    /** Currently selected date range end (timeline slicers) */
+    selectedEndDate?: number;
+    /** Current aggregation level (timeline slicers) */
+    timelineLevel?: TimelineLevel;
+}
+/** Summary information about a slicer. */
+export interface SlicerInfo {
+    /** Unique slicer ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Connected table name */
+    tableName: string;
+    /** Connected column name */
+    columnName: string;
+    /** Source type — 'table' for table slicers, 'pivot' for pivot table slicers */
+    source?: {
+        type: 'table' | 'pivot';
+    };
+    /** Discriminator for timeline slicers (matches TimelineSlicerConfig.sourceType) */
+    sourceType?: 'timeline';
+}
+/** Full slicer state including selection and position. */
+export interface Slicer extends SlicerInfo {
+    /** Currently selected filter items */
+    selectedItems: CellValue[];
+    /** Position and dimensions in pixels */
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** A single item in a slicer's value list. */
+export interface SlicerItem {
+    /** The display value */
+    value: CellValue;
+    /** Whether this item is currently selected */
+    selected: boolean;
+    /** Number of matching records (if available) */
+    count?: number;
+}
+/** Granular options for sheet protection. */
+export interface ProtectionOptions {
+    /** Allow selecting locked cells */
+    allowSelectLockedCells?: boolean;
+    /** Allow selecting unlocked cells */
+    allowSelectUnlockedCells?: boolean;
+    /** Allow formatting cells */
+    allowFormatCells?: boolean;
+    /** Allow formatting columns */
+    allowFormatColumns?: boolean;
+    /** Allow formatting rows */
+    allowFormatRows?: boolean;
+    /** Allow inserting columns */
+    allowInsertColumns?: boolean;
+    /** Allow inserting rows */
+    allowInsertRows?: boolean;
+    /** Allow inserting hyperlinks */
+    allowInsertHyperlinks?: boolean;
+    /** Allow deleting columns */
+    allowDeleteColumns?: boolean;
+    /** Allow deleting rows */
+    allowDeleteRows?: boolean;
+    /** Allow sorting */
+    allowSort?: boolean;
+    /** Allow using auto-filter */
+    allowAutoFilter?: boolean;
+    /** Allow using pivot tables */
+    allowPivotTables?: boolean;
+}
+/** Configuration for creating a what-if scenario. */
+export interface ScenarioConfig {
+    /** Scenario name */
+    name: string;
+    /** Cell addresses that change (A1 notation) */
+    changingCells: string[];
+    /** Values for the changing cells, in the same order */
+    values: (string | number | boolean | null)[];
+    /** Optional description */
+    comment?: string;
+}
+/** A saved scenario with metadata. */
+export interface Scenario extends ScenarioConfig {
+    /** Unique scenario ID */
+    id: string;
+    /** Creation timestamp (Unix ms) */
+    createdAt: number;
+}
+/** A saved original cell value from before scenario application. */
+export interface OriginalCellValue {
+    sheetId: string;
+    cellId: string;
+    value: string | number | boolean | null;
+    /** Original formula, if the cell had one. */
+    formula?: string;
+}
+/** Result returned from applyScenario(). */
+export interface ApplyScenarioResult {
+    /** Number of cells that were updated with scenario values. */
+    cellsUpdated: number;
+    /** CellIds that could not be found (deleted cells). */
+    skippedCells: string[];
+    /** Original values to pass to restoreScenario() later. */
+    originalValues: OriginalCellValue[];
+}
+/** Information about a defined name / named range. */
+export interface NamedRangeInfo {
+    /** The defined name */
+    name: string;
+    /** The reference formula (e.g., "Sheet1!$A$1:$B$10") */
+    reference: string;
+    /** Scope: undefined or sheet name (undefined = workbook scope) */
+    scope?: string;
+    /** Optional descriptive comment */
+    comment?: string;
+    /** Whether the name is visible in Name Manager. Hidden names are typically system-generated. */
+    visible?: boolean;
+}
+/** Parsed reference for a named range that refers to a simple sheet!range. */
+export interface NamedRangeReference {
+    /** The sheet name (e.g., "Sheet1") */
+    sheetName: string;
+    /** The range portion (e.g., "$A$1:$B$10") */
+    range: string;
+}
+/**
+ * OfficeJS-compatible type classification for a named item's value.
+ *
+ * @see https://learn.microsoft.com/en-us/javascript/api/excel/excel.nameditemtype
+ */
+export type NamedItemType = 'String' | 'Integer' | 'Double' | 'Boolean' | 'Range' | 'Error' | 'Array';
+/** Information about a saved checkpoint (version snapshot). */
+export interface CheckpointInfo {
+    /** Unique checkpoint ID */
+    id: string;
+    /** Optional human-readable label */
+    label?: string;
+    /** Creation timestamp (Unix ms) */
+    timestamp: number;
+}
+/** Options for code execution via `workbook.executeCode()`. */
+export interface ExecuteOptions {
+    /** Maximum execution time in milliseconds */
+    timeout?: number;
+    /** Whether to run in a sandboxed environment */
+    sandbox?: boolean;
+}
+/** Result of a code execution. */
+export interface CodeResult {
+    /** Whether execution completed successfully */
+    success: boolean;
+    /** Captured console output */
+    output?: string;
+    /** Error message (if success is false) */
+    error?: string;
+    /** Execution duration in milliseconds */
+    duration?: number;
+}
+/** Options for the `worksheet.summarize()` method. */
+export interface SummaryOptions {
+    /** Whether to include sample data in the summary */
+    includeData?: boolean;
+    /** Maximum number of rows to include in sample data */
+    maxRows?: number;
+    /** Maximum number of columns to include in sample data */
+    maxCols?: number;
+}
+/** Options for cell search operations. */
+export interface SearchOptions {
+    /** Whether the search is case-sensitive */
+    matchCase?: boolean;
+    /** Whether to match the entire cell value */
+    entireCell?: boolean;
+    /** Whether to search formula text instead of computed values */
+    searchFormulas?: boolean;
+    /** Limit search to this range (A1 notation) */
+    range?: string;
+}
+/** A single search result. */
+export interface SearchResult {
+    /** Cell address in A1 notation */
+    address: string;
+    /** The cell's display value */
+    value: string;
+    /** The cell's formula (if any) */
+    formula?: string;
+}
+/**
+ * Per-cell value type classification.
+ * Matches OfficeJS Excel.RangeValueType enum values.
+ */
+export declare enum RangeValueType {
+    /** Cell is empty */
+    Empty = "Empty",
+    /** Cell contains a string */
+    String = "String",
+    /** Cell contains a number (including dates) */
+    Double = "Double",
+    /** Cell contains a boolean */
+    Boolean = "Boolean",
+    /** Cell contains an error */
+    Error = "Error"
+}
+/**
+ * Determines which aspects of a range to clear.
+ * Matches OfficeJS Excel.ClearApplyTo enum.
+ */
+export type ClearApplyTo = 'all' | 'contents' | 'formats' | 'hyperlinks';
+/**
+ * Number format category classification.
+ * Matches the FormatType enum from Rust compute-formats.
+ */
+export declare enum NumberFormatCategory {
+    General = "General",
+    Number = "Number",
+    Currency = "Currency",
+    Accounting = "Accounting",
+    Date = "Date",
+    Time = "Time",
+    Percentage = "Percentage",
+    Fraction = "Fraction",
+    Scientific = "Scientific",
+    Text = "Text",
+    Special = "Special",
+    Custom = "Custom"
+}
+/** Information about a spreadsheet function (e.g., SUM, VLOOKUP). */
+export interface FunctionInfo {
+    /** Function name (uppercase, e.g., "SUM") */
+    name: string;
+    /** Description of what the function does */
+    description: string;
+    /** Function category (e.g., "Math & Trig", "Lookup & Reference") */
+    category: string;
+    /** Syntax example (e.g., "SUM(number1, [number2], ...)") */
+    syntax: string;
+    /** Usage examples */
+    examples?: string[];
+    /** Function argument metadata for IntelliSense/argument hints */
+    arguments?: import('../utils/function-registry').FunctionArgument[];
+}
+/** A summary snapshot of the entire workbook state. */
+export interface WorkbookSnapshot {
+    /** All sheets in the workbook */
+    sheets: SheetSnapshot[];
+    /** ID of the currently active sheet */
+    activeSheetId: string;
+    /** Total number of sheets */
+    sheetCount: number;
+}
+/** A summary snapshot of a single sheet. */
+export interface SheetSnapshot {
+    /** Sheet ID */
+    id: string;
+    /** Sheet name */
+    name: string;
+    /** Sheet index (0-based) */
+    index: number;
+    /** Range containing all non-empty cells (A1 notation), or null if empty */
+    usedRange: string | null;
+    /** Number of cells with data */
+    cellCount: number;
+    /** Number of cells with formulas */
+    formulaCount: number;
+    /** Number of charts in this sheet */
+    chartCount: number;
+    /** Sheet dimensions */
+    dimensions: {
+        rows: number;
+        cols: number;
+    };
+}
+/** All spreadsheet event types that can be subscribed to via `workbook.on()`. */
+export type SpreadsheetEventType = 'cellChanged' | 'rangeChanged' | 'sheetAdded' | 'sheetRemoved' | 'sheetRenamed' | 'sheetMoved' | 'activeSheetChanged' | 'selectionChanged' | 'formatChanged' | 'structureChanged' | 'tableChanged' | 'chartChanged' | 'filterChanged' | 'sortApplied' | 'undoRedoStateChanged' | 'calculationComplete' | 'protectionChanged';
+/** Generic event handler. For typed subscriptions, T is the specific event type. */
+export type EventHandler<T = InternalSpreadsheetEvent> = (event: T) => void;
+export type { EventByType, SpreadsheetEventType as InternalEventType, SpreadsheetEvent as InternalSpreadsheetEvent, } from '../events';
+/** Full protection configuration for a sheet. */
+export interface ProtectionConfig {
+    /** Whether the sheet is protected */
+    isProtected: boolean;
+    /** Whether a password is set for protection (does not expose the hash) */
+    hasPasswordSet?: boolean;
+    /** Allow selecting locked cells */
+    allowSelectLockedCells?: boolean;
+    /** Allow selecting unlocked cells */
+    allowSelectUnlockedCells?: boolean;
+    /** Allow formatting cells */
+    allowFormatCells?: boolean;
+    /** Allow formatting columns */
+    allowFormatColumns?: boolean;
+    /** Allow formatting rows */
+    allowFormatRows?: boolean;
+    /** Allow inserting columns */
+    allowInsertColumns?: boolean;
+    /** Allow inserting rows */
+    allowInsertRows?: boolean;
+    /** Allow inserting hyperlinks */
+    allowInsertHyperlinks?: boolean;
+    /** Allow deleting columns */
+    allowDeleteColumns?: boolean;
+    /** Allow deleting rows */
+    allowDeleteRows?: boolean;
+    /** Allow sorting */
+    allowSort?: boolean;
+    /** Allow using auto-filter */
+    allowAutoFilter?: boolean;
+    /** Allow using pivot tables */
+    allowPivotTables?: boolean;
+}
+/** Sheet view options (gridlines, headings). */
+export interface ViewOptions {
+    /** Whether gridlines are shown */
+    showGridlines: boolean;
+    /** Whether row headers are shown */
+    showRowHeaders: boolean;
+    /** Whether column headers are shown */
+    showColumnHeaders: boolean;
+}
+/** Scroll position (cell-level, not pixel-level). */
+export interface ScrollPosition {
+    /** Top visible row index (0-based). */
+    topRow: number;
+    /** Left visible column index (0-based). */
+    leftCol: number;
+}
+/** Information about a custom table style. */
+export interface TableStyleInfo {
+    /** Style name/ID */
+    name: string;
+    /** Display name */
+    displayName?: string;
+    /** Whether this is a built-in style */
+    isBuiltIn?: boolean;
+}
+/** Configuration for creating/updating a custom table style. */
+export interface TableStyleConfig {
+    /** Style name */
+    name: string;
+    /** Style JSON definition */
+    [key: string]: unknown;
+}
+export type { WorkbookSettings } from '../core/core';
+/** Information about a filter applied to a sheet. */
+export interface FilterInfo {
+    /** Filter ID */
+    id: string;
+    /** The filtered range */
+    range?: string;
+    /** Per-column filter criteria */
+    columns?: Record<string, unknown>;
+    /** Table ID if this filter is associated with a table. */
+    tableId?: string;
+    /** Per-column filter criteria, keyed by column identifier. */
+    columnFilters?: Record<string, unknown>;
+}
+/** Detailed filter information including resolved numeric range and column filters. */
+export interface FilterDetailInfo {
+    /** Filter ID */
+    id: string;
+    /** Resolved numeric range of the filter */
+    range: {
+        startRow: number;
+        startCol: number;
+        endRow: number;
+        endCol: number;
+    };
+    /** Per-column filter criteria, keyed by header cell ID */
+    columnFilters: Record<string, ColumnFilterCriteria>;
+}
+/** Enriched runtime state for a slicer (includes computed items, connection status). */
+export interface SlicerState {
+    /** Computed items with selection state */
+    items: SlicerItem[];
+    /** Whether the slicer is connected to its data source */
+    isConnected: boolean;
+    /** Selected values */
+    selectedValues: CellValue[];
+    /** Timeline periods (for timeline slicers) */
+    periods?: TimelinePeriod[];
+}
+/** A period in a timeline slicer. */
+export interface TimelinePeriod {
+    /** Period label */
+    label: string;
+    /** Period start date (ISO string) */
+    start: string;
+    /** Period end date (ISO string) */
+    end: string;
+    /** Whether this period is selected */
+    selected: boolean;
+}
+/** Aggregate values for selected cells (status bar display). */
+export interface AggregateResult {
+    /** Sum of numeric values */
+    sum: number;
+    /** Total number of non-empty cells */
+    count: number;
+    /** Number of numeric cells */
+    numericCount: number;
+    /** Average of numeric values (null if no numeric cells) */
+    average: number | null;
+    /** Minimum numeric value (null if no numeric cells) */
+    min: number | null;
+    /** Maximum numeric value (null if no numeric cells) */
+    max: number | null;
+}
+/** Entry for batch format-values call. */
+export interface FormatEntry {
+    /** Cell value descriptor */
+    value: {
+        type: string;
+        value?: unknown;
+    };
+    /** Number format code (e.g., "#,##0.00") */
+    formatCode: string;
+}
+/** Options for text-to-columns splitting. */
+export interface TextToColumnsOptions {
+    /** Delimiter type */
+    delimiter: 'comma' | 'tab' | 'semicolon' | 'space' | 'custom';
+    /** Custom delimiter character (when delimiter is 'custom') */
+    customDelimiter?: string;
+    /** Whether to treat consecutive delimiters as one */
+    treatConsecutiveAsOne?: boolean;
+    /** Text qualifier character */
+    textQualifier?: '"' | "'" | 'none';
+}
+/** Result of a remove-duplicates operation. */
+export interface RemoveDuplicatesResult {
+    /** Number of duplicate rows removed */
+    removedCount: number;
+    /** Number of unique rows remaining */
+    remainingCount: number;
+}
+/** Type discriminator for floating objects. Superset of Rust FloatingObjectKind (12 variants) + legacy TS-only 'wordart'. */
+export type FloatingObjectType = 'shape' | 'connector' | 'picture' | 'textbox' | 'chart' | 'camera' | 'equation' | 'smartart' | 'drawing' | 'oleObject' | 'formControl' | 'slicer' | 'wordart';
+/** Summary information about a floating object (returned by listFloatingObjects). */
+export interface FloatingObjectInfo {
+    /** Unique object ID. */
+    id: string;
+    /** Object type discriminator. */
+    type: FloatingObjectType;
+    /** Optional display name. */
+    name?: string;
+    /** X position in pixels. */
+    x: number;
+    /** Y position in pixels. */
+    y: number;
+    /** Width in pixels. */
+    width: number;
+    /** Height in pixels. */
+    height: number;
+    /** Rotation angle in degrees. */
+    rotation?: number;
+    /** Flipped horizontally. */
+    flipH?: boolean;
+    /** Flipped vertically. */
+    flipV?: boolean;
+    /** Z-order index. */
+    zIndex?: number;
+    /** Whether the object is visible. */
+    visible?: boolean;
+    /** ID of the parent group (if this object is grouped). */
+    groupId?: string;
+    /** Anchor mode (twoCell/oneCell/absolute). */
+    anchorType?: ObjectAnchorType;
+    /** Alt text for accessibility. */
+    altText?: string;
+}
+/** Configuration for creating a new picture. */
+export interface PictureConfig {
+    /** Image source: data URL, blob URL, or file path. */
+    src: string;
+    /** X position in pixels. */
+    x?: number;
+    /** Y position in pixels. */
+    y?: number;
+    /** Width in pixels (defaults to original image width). */
+    width?: number;
+    /** Height in pixels (defaults to original image height). */
+    height?: number;
+    /** Accessibility alt text. */
+    altText?: string;
+    /** Display name. */
+    name?: string;
+    /** Image crop settings (percentage from each edge). */
+    crop?: PictureCrop;
+    /** Image adjustments (brightness, contrast, transparency). */
+    adjustments?: PictureAdjustments;
+}
+/** Configuration for creating a new text box. */
+export interface TextBoxConfig {
+    /** Initial text content. */
+    content: string;
+    /** X position in pixels. */
+    x?: number;
+    /** Y position in pixels. */
+    y?: number;
+    /** Width in pixels (default: 200). */
+    width?: number;
+    /** Height in pixels (default: 100). */
+    height?: number;
+    /** Display name. */
+    name?: string;
+    /** Text margins within the box. */
+    margins?: TextMargins;
+}
+/** Configuration for creating a new equation. */
+export interface EquationConfig {
+    /** LaTeX source for the equation. */
+    latex: string;
+    /** X position in pixels. */
+    x?: number;
+    /** Y position in pixels. */
+    y?: number;
+    /** Width in pixels. */
+    width?: number;
+    /** Height in pixels. */
+    height?: number;
+    /** Equation style options. */
+    style?: EquationStyleConfig;
+}
+/** Styling options for an equation. */
+export interface EquationStyleConfig {
+    /** Font family (default: 'Cambria Math'). */
+    fontFamily?: string;
+    /** Base font size in points. */
+    fontSize?: number;
+    /** Text color (CSS). */
+    color?: string;
+    /** Background color (CSS or 'transparent'). */
+    backgroundColor?: string;
+    /** Display mode: block (true) vs inline (false). */
+    displayMode?: boolean;
+}
+/** Updates for an existing equation. */
+export interface EquationUpdates {
+    /** Updated LaTeX source. */
+    latex?: string;
+    /** Updated OMML XML. */
+    omml?: string;
+    /** Updated style options. */
+    style?: Partial<EquationStyleConfig>;
+}
+/** Configuration for creating new WordArt. */
+export interface WordArtConfig {
+    /** Text content. */
+    text: string;
+    /** Preset style ID (e.g., 'fill-1', 'gradient-2'). */
+    presetId?: string;
+    /** X position in pixels. */
+    x?: number;
+    /** Y position in pixels. */
+    y?: number;
+    /** Width in pixels. */
+    width?: number;
+    /** Height in pixels. */
+    height?: number;
+    /** Display name. */
+    name?: string;
+}
+/** Updates for existing WordArt. */
+export interface WordArtUpdates {
+    /** Updated text content. */
+    text?: string;
+    /** Warp preset name (text geometric transformation). */
+    warp?: string;
+    /** Warp adjustment values. */
+    warpAdjustments?: Record<string, number>;
+    /** Fill configuration. */
+    fill?: Record<string, unknown>;
+    /** Outline configuration. */
+    outline?: Record<string, unknown>;
+    /** Text effects (shadow, glow, reflection, etc.). */
+    effects?: Record<string, unknown>;
+    /** Full WordArt configuration batch update. */
+    config?: Record<string, unknown>;
+    /** Text formatting update. */
+    textFormat?: Record<string, unknown>;
+}
+/** Configuration for creating a new SmartArt diagram. */
+export interface SmartArtConfig {
+    /** Layout ID (e.g., 'hierarchy/org-chart', 'process/basic-process'). */
+    layoutId: string;
+    /** X position in pixels. */
+    x?: number;
+    /** Y position in pixels. */
+    y?: number;
+    /** Width in pixels. */
+    width?: number;
+    /** Height in pixels. */
+    height?: number;
+    /** Initial nodes to create. */
+    nodes?: SmartArtNodeConfig[];
+    /** Display name. */
+    name?: string;
+}
+/** Configuration for a SmartArt diagram node. */
+export interface SmartArtNodeConfig {
+    /** Node text content. */
+    text: string;
+    /** Hierarchy level (0 = root). */
+    level?: number;
+    /** Insertion position relative to a reference node. */
+    position?: 'before' | 'after' | 'child';
+    /** Reference node ID for positioning. */
+    referenceNodeId?: string;
+}
+/** Transform type for stroke transformations. */
+export type StrokeTransformType = 'rotate' | 'scale' | 'flip-horizontal' | 'flip-vertical';
+/** Transform parameters for stroke transformations. */
+export interface StrokeTransformParams {
+    /** Transform type */
+    type: StrokeTransformType;
+    /** Center point X for rotation/scale */
+    centerX?: number;
+    /** Center point Y for rotation/scale */
+    centerY?: number;
+    /** Rotation angle in radians (for 'rotate') */
+    angle?: number;
+    /** Scale factor X (for 'scale') */
+    scaleX?: number;
+    /** Scale factor Y (for 'scale') */
+    scaleY?: number;
+}
+/** State of all row/column groups on a sheet. */
+export interface GroupState {
+    /** All row groups */
+    rowGroups: any[];
+    /** All column groups */
+    columnGroups: any[];
+    /** Maximum outline level for rows */
+    maxRowLevel: number;
+    /** Maximum outline level for columns */
+    maxColLevel: number;
+}
+/** Configuration for the subtotal operation. */
+export interface SubtotalConfig {
+    /** Column index to group by (0-based) */
+    groupByColumn: number;
+    /** Columns to subtotal (0-based indices) */
+    subtotalColumns: number[];
+    /** Aggregation function to use */
+    aggregation: 'sum' | 'count' | 'average' | 'max' | 'min';
+    /** Whether to replace existing subtotals */
+    replace?: boolean;
+}
+/** Sort state for a filter. */
+export interface FilterSortState {
+    /** Column index or header cell ID to sort by */
+    column: string | number;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+    /** Sort criteria (optional, for advanced sorting) */
+    criteria?: any;
+}
+/** Full sheet settings (mirrors SheetSettings from core contracts). */
+export interface SheetSettingsInfo {
+    /** Default row height in pixels */
+    defaultRowHeight: number;
+    /** Default column width in pixels */
+    defaultColWidth: number;
+    /** Whether gridlines are shown */
+    showGridlines: boolean;
+    /** Whether row headers are shown */
+    showRowHeaders: boolean;
+    /** Whether column headers are shown */
+    showColumnHeaders: boolean;
+    /** Whether zero values are displayed (false = blank) */
+    showZeroValues: boolean;
+    /** Gridline color (hex string) */
+    gridlineColor: string;
+    /** Whether the sheet is protected */
+    isProtected: boolean;
+    /** Whether the sheet uses right-to-left layout */
+    rightToLeft: boolean;
+}
+/** Outline display settings for grouping. */
+export interface OutlineSettings {
+    /** Whether outline symbols (+/-) are visible */
+    showOutlineSymbols: boolean;
+    /** Whether outline level buttons (1,2,3...) are visible */
+    showOutlineLevelButtons: boolean;
+    /** Whether summary rows appear below detail rows */
+    summaryRowsBelow: boolean;
+    /** Whether summary columns appear to the right of detail */
+    summaryColumnsRight: boolean;
+}
+/** Options for updating a named range. */
+export interface NamedRangeUpdateOptions {
+    /** New name (for renaming) */
+    name?: string;
+    /** New reference (A1-style) */
+    reference?: string;
+    /** New comment */
+    comment?: string;
+    /** Whether the name is visible in Name Manager */
+    visible?: boolean;
+}
+/** Options for creating named ranges from row/column labels in a selection. */
+export interface CreateNamesFromSelectionOptions {
+    /** Create names from labels in the top row of the selection. */
+    top?: boolean;
+    /** Create names from labels in the left column of the selection. */
+    left?: boolean;
+    /** Create names from labels in the bottom row of the selection. */
+    bottom?: boolean;
+    /** Create names from labels in the right column of the selection. */
+    right?: boolean;
+}
+/** Result of a create-names-from-selection operation. */
+export interface CreateNamesResult {
+    /** Number of names successfully created. */
+    success: number;
+    /** Number of names skipped (already exist or invalid). */
+    skipped: number;
+}
+/** An entry in the undo history. */
+export interface UndoHistoryEntry {
+    /** Unique identifier for this entry. */
+    id: string;
+    /** Description of the operation. */
+    description: string;
+    /** Timestamp of the operation (Unix ms). */
+    timestamp: number;
+}
+/** Full undo/redo state from the compute engine. */
+export interface UndoState {
+    /** Whether undo is available. */
+    canUndo: boolean;
+    /** Whether redo is available. */
+    canRedo: boolean;
+    /** Number of operations that can be undone. */
+    undoDepth: number;
+    /** Number of operations that can be redone. */
+    redoDepth: number;
+}
+/** Column mapping for a sheet data binding. */
+export interface ColumnMapping {
+    /** Column index to write to (0-indexed) */
+    columnIndex: number;
+    /** JSONPath or field name to extract from data */
+    dataPath: string;
+    /** Optional transform formula (receives value as input) */
+    transform?: string;
+    /** Header text (if headerRow >= 0) */
+    headerText?: string;
+}
+/** Configuration for creating a sheet data binding. */
+export interface CreateBindingConfig {
+    /** Connection providing the data */
+    connectionId: string;
+    /** Maps data fields to columns */
+    columnMappings: ColumnMapping[];
+    /** Auto-insert/delete rows to match data length (default: true) */
+    autoGenerateRows?: boolean;
+    /** Row index for headers (-1 = no header row, default: 0) */
+    headerRow?: number;
+    /** First row of data (0-indexed, default: 1) */
+    dataStartRow?: number;
+    /** Preserve header row formatting on refresh (default: true) */
+    preserveHeaderFormatting?: boolean;
+}
+/** Information about an existing sheet data binding. */
+export interface SheetDataBindingInfo {
+    /** Unique binding identifier */
+    id: string;
+    /** Connection providing the data */
+    connectionId: string;
+    /** Maps data fields to columns */
+    columnMappings: ColumnMapping[];
+    /** Auto-insert/delete rows to match data length */
+    autoGenerateRows: boolean;
+    /** Row index for headers (-1 = no header row) */
+    headerRow: number;
+    /** First row of data (0-indexed) */
+    dataStartRow: number;
+    /** Preserve header row formatting on refresh */
+    preserveHeaderFormatting: boolean;
+    /** Last refresh timestamp */
+    lastRefresh?: number;
+}
+/**
+ * Cell data from the viewport buffer (sync, pre-fetched for 60fps rendering).
+ *
+ * Produced by BinaryViewportBuffer's CellAccessor. Fields match the binary
+ * cell record layout. Fields not in the binary record (cellId, editText,
+ * hyperlinkUrl) are optional — use async Worksheet APIs for those.
+ */
+export interface ViewportCellData {
+    row: number;
+    col: number;
+    /**
+     * Typed cell value: number for numbers, string for text, boolean for booleans,
+     * CellError for errors, null for empty cells.
+     */
+    value: CellValue;
+    /** Cell ID (CRDT identifier). Not in binary record — only populated by legacy path. */
+    cellId?: string;
+    /** Display text (formatted value as string). */
+    displayText: FormattedText | null;
+    /** Whether the cell contains a formula. */
+    hasFormula: boolean;
+    /** Whether the cell has a comment indicator. */
+    hasComment: boolean;
+    /** Whether the cell has a sparkline. */
+    hasSparkline: boolean;
+    /** Whether the cell has a hyperlink. */
+    hasHyperlink: boolean;
+    /** Error text if the cell is in error state. */
+    error?: string;
+    /** Edit text (raw input string for editor). Not in binary record. */
+    editText?: string;
+    /** Hyperlink URL. Not in binary record — use hasHyperlink flag + async API. */
+    hyperlinkUrl?: string;
+    /** Cell format from the binary format palette. */
+    format?: unknown;
+    /** Schema type for this cell (e.g., 'boolean' for checkbox cells). Not always populated. */
+    schema_type?: string;
+}
+/**
+ * Active cell data for formula bar, editors, and status bar.
+ *
+ * Produced by ComputeBridge.getActiveCellData(). Field names match the
+ * generated ActiveCellData type from compute-types.gen.ts.
+ */
+export interface ActiveCellInfo {
+    cellId: string;
+    value: CellValue;
+    formula?: string;
+    format?: unknown;
+    metadata?: unknown;
+    editText?: string;
+    isFormulaHidden: boolean;
+    hyperlinkUrl?: string;
+    numberFormat?: string;
+}
+/** Merge region within the viewport. Wire type from Rust. */
+export interface ViewportMergeRegion {
+    start_row: number;
+    start_col: number;
+    end_row: number;
+    end_col: number;
+}
+/** Row dimension data from viewport. Wire type from Rust. */
+export interface ViewportRowDimension {
+    row: number;
+    height: number;
+    hidden: boolean;
+}
+/** Column dimension data from viewport. Wire type from Rust. */
+export interface ViewportColDimension {
+    col: number;
+    width: number;
+    hidden: boolean;
+}
+/** The visible cell range bounds for the viewport. */
+export interface ViewportBounds {
+    sheetId: string;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+/** Binary cell data for zero-copy canvas rendering. */
+export interface BinaryCellData {
+    row: number;
+    col: number;
+    /** Raw binary payload for direct rendering. */
+    data?: ArrayBuffer;
+}
+/**
+ * Binary viewport reader for ultra-fast canvas rendering.
+ * Reads from an ArrayBuffer-based representation (zero-copy on WASM path).
+ */
+export interface BinaryViewportReader {
+    /** Read cell data from binary buffer. */
+    getCellData(row: number, col: number): BinaryCellData | null;
+    /** Get the underlying binary buffer for direct canvas rendering. */
+    getBuffer(): ArrayBuffer | null;
+    /** Check if binary data is available for this viewport. */
+    isReady(): boolean;
+}
+/**
+ * Duck-typed binary cell reader for the canvas cells layer hot path.
+ * Matches the flyweight CellAccessor shape from the kernel's BinaryViewportBuffer.
+ * Duck-typed to avoid hard dependency from contracts to kernel.
+ */
+export interface BinaryCellReader {
+    moveTo(row: number, col: number): boolean;
+    readonly valueType: number;
+    readonly numberValue: number;
+    readonly displayText: FormattedText | null;
+    readonly errorText: string | null;
+    readonly format: CellFormat;
+    readonly hasFormula: boolean;
+    readonly hasComment: boolean;
+    readonly hasSparkline: boolean;
+    readonly hasHyperlink: boolean;
+    readonly isCheckbox: boolean;
+    readonly isProjectedPosition: boolean;
+    readonly hasValidationError: boolean;
+}
+/**
+ * Sync viewport reader for 60fps render paths.
+ *
+ * Read-only interface over the pre-populated viewport buffer.
+ * All methods are synchronous — the buffer is populated from Rust via async
+ * IPC, but reads are O(1) lookups into the local cache.
+ *
+ * Replaces direct `ctx.viewportBuffer` access in the app layer (48 files).
+ */
+export interface ViewportReader {
+    /** Get cell data for a visible cell (sync, O(1)). Returns null if outside viewport. */
+    getCellData(row: number, col: number): ViewportCellData | null;
+    /** Get data for the active cell (formula bar, editors). */
+    getActiveCellData(): ActiveCellInfo | null;
+    /** Get all merge regions visible in the viewport. */
+    getMerges(): ViewportMergeRegion[];
+    /** Check if a cell has a comment indicator. */
+    hasComment(row: number, col: number): boolean;
+    /** Get row dimension (height, hidden state) for a visible row. */
+    getRowDimension(row: number): ViewportRowDimension | null;
+    /** Get column dimension (width, hidden state) for a visible column. */
+    getColDimension(col: number): ViewportColDimension | null;
+    /** Get the current viewport bounds, or null if not yet populated. */
+    getBounds(): ViewportBounds | null;
+    /** Binary transfer path for ultra-fast rendering. */
+    readonly binary: BinaryViewportReader;
+    /**
+     * Binary cell reader (flyweight accessor for renderer).
+     * Duck-typed to avoid leaking kernel class references.
+     */
+    readonly binaryCellReader: BinaryCellReader | null;
+    /**
+     * Per-viewport binary cell reader resolver (Phase 6).
+     * Returns a flyweight accessor for the given viewport's binary buffer.
+     * Duck-typed to avoid leaking kernel class references.
+     */
+    readonly binaryCellReaderForViewport?: (viewportId: string) => BinaryCellReader | undefined;
+}
+/**
+ * A RecordValues is a map of field (column) IDs to their values.
+ * This is the computed/display value, not raw formula text.
+ */
+export type RecordValues = {
+    [key: string]: CellValue;
+};
+/**
+ * A TableRecord represents a row in a table with its values.
+ */
+export interface TableRecord {
+    /** The record's row ID (row index as string, e.g., "5") */
+    rowId: string;
+    /** The record's field values (keyed by column ID or column name) */
+    values: RecordValues;
+}
+/**
+ * Filter expression for querying records.
+ * Currently supports simple equality filters.
+ */
+export interface FilterExpression {
+    /** Field to filter on (column ID or column name) */
+    field: string;
+    /** Value to match (exact equality) */
+    equals: CellValue;
+}
+/**
+ * Records API — table-aware CRUD operations.
+ *
+ * Provides record (row) operations for table-based views like Kanban, Gallery, etc.
+ * A "Record" is a row in a table, with each column representing a field.
+ *
+ * Available on `workbook.records`. Wraps the kernel Records module,
+ * hiding the DocumentContext from app-layer consumers.
+ */
+export interface IRecordsAPI {
+    /** Get a single record by row ID. */
+    get(tableId: string, rowId: string): Promise<TableRecord | null>;
+    /** Query records in a table with optional filtering. */
+    query(tableId: string, filter?: FilterExpression): Promise<TableRecord[]>;
+    /** Get a single field value from a record. */
+    getFieldValue(tableId: string, rowId: string, fieldId: string): Promise<CellValue>;
+    /** Create a new record in the table. Returns the new record's row ID. */
+    create(tableId: string, values: RecordValues): Promise<string>;
+    /** Update a record's field values. */
+    update(tableId: string, rowId: string, changes: Partial<RecordValues>): Promise<void>;
+    /** Delete a record from the table (clears the row's cells). */
+    del(tableId: string, rowId: string): Promise<void>;
+}
+/**
+ * Coarse sheet-level event types for `ws.on()`.
+ *
+ * Each coarse type maps to one or more fine-grained internal events.
+ * Callers that need fine-grained control can use SpreadsheetEventType
+ * as an escape hatch: `ws.on('filter:applied', handler)`.
+ */
+export type SheetEvent = 'cellChanged' | 'filterChanged' | 'visibilityChanged' | 'structureChanged' | 'mergeChanged' | 'tableChanged' | 'chartChanged' | 'slicerChanged' | 'sparklineChanged' | 'groupingChanged' | 'cfChanged' | 'viewportRefreshed' | 'recalcComplete' | 'nameChanged' | 'selectionChanged' | 'activated' | 'deactivated';
+/**
+ * Coarse workbook-level event types for `wb.on()`.
+ *
+ * These events are not sheet-scoped — they fire once for the whole workbook.
+ */
+export type WorkbookEvent = 'sheetAdded' | 'sheetRemoved' | 'sheetRenamed' | 'activeSheetChanged' | 'undoStackChanged' | 'checkpointCreated' | 'namedRangeChanged' | 'scenarioChanged' | 'settingsChanged';
+/**
+ * Calculation type for `calculate()`.
+ * - 'recalculate' — recalculate dirty cells only (default)
+ * - 'full' — recalculate all cells
+ * - 'fullRebuild' — rebuild dependency graph and recalculate all
+ */
+export type CalculationType = 'recalculate' | 'full' | 'fullRebuild';
+/**
+ * Reactive conditional format cache.
+ *
+ * Provides sync reads for the render path and auto-invalidates when CF rules
+ * or cell values change. Created lazily by `ws.conditionalFormats`.
+ *
+ * Lifecycle: implements `destroy()` for subscription teardown.
+ * `WorksheetImpl.dispose()` calls `destroy()` to prevent memory leaks.
+ */
+export interface ConditionalFormatCache {
+    /** Get the CF result for a cell (sync, O(1)). Returns undefined if no CF applies. */
+    getResult(sheetId: string, row: number, col: number): CFResult | undefined;
+    /** Check if a cell has conditional formatting. */
+    hasCF(sheetId: string, row: number, col: number): boolean;
+    /** Force re-evaluation of all CF rules for a sheet. */
+    evaluateAll(sheetId: string): Promise<void>;
+    /** Invalidate cached results for specific cells. */
+    invalidateCells(sheetId: string, changedCells?: Array<{
+        row: number;
+        col: number;
+    }>): Promise<void>;
+    /** Invalidate all cached results. */
+    invalidateAll(): void;
+    /** Subscribe to rule changes. Returns unsubscribe function. */
+    onRulesChanged(callback: () => void): () => void;
+    /** Tear down subscriptions and release resources. */
+    destroy(): void;
+}
+/**
+ * Reactive cell metadata cache.
+ *
+ * Provides sync reads for projection (dynamic array spill) data and
+ * validation error indicators. Auto-invalidates on recalc. Created lazily
+ * by `ws.cellMetadata`.
+ *
+ * Lifecycle: implements `destroy()` for subscription teardown.
+ */
+export interface CellMetadataCache {
+    /** Check if a cell position is a projected (spill target) position. */
+    isProjectedPosition(row: number, col: number): boolean;
+    /** Get the source cell of a projection. */
+    getProjectionSourcePosition(row: number, col: number): {
+        row: number;
+        col: number;
+    } | undefined;
+    /** Get the full range of a projection (dynamic array spill range). */
+    getProjectionRange(row: number, col: number): CellRange | undefined;
+    /** Check if a cell has validation errors. */
+    hasValidationErrors(row: number, col: number): boolean;
+    /** Evaluate metadata for the visible viewport range. */
+    evaluateViewport(sheetId: string, startRow: number, startCol: number, endRow: number, endCol: number): Promise<void>;
+    /** Subscribe to metadata changes. Returns unsubscribe function. */
+    onChange(callback: () => void): () => void;
+    /** Clear all cached data. */
+    clear(): void;
+    /** Tear down subscriptions and release resources. */
+    destroy(): void;
+}
+//# sourceMappingURL=types.d.ts.map