@pixerate/editor 0.24.0 → 0.26.0

package/dist/controller-CxXGOEmy.d.cts

@@ -0,0 +1,2038 @@
+/**
+ * Conditional formatting rule model.
+ *
+ * Portions ported from gridcraft/crates/model/src/features.rs (MIT OR
+ * Apache-2.0, © ArtCraft Team and contributors). See THIRD_PARTY_NOTICES.md.
+ */
+
+/** Comparison of a cell value with one value (or two for `between` / `notBetween`). */
+type ConditionalFormatOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+/**
+ * The look a matching rule adds to a cell. Colours are CSS colours, ideally
+ * `#rrggbb`. Only the parts that are set apply, so several rules can combine
+ * (a fill from one, bold from another).
+ */
+interface ConditionalFormatStyle {
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+}
+/**
+ * An anchor of a colour scale, data bar or icon set: the lowest / highest
+ * number in the range, a fixed number, a percent of the min..max span, a
+ * percentile of the values, or a formula (written for the range's top-left
+ * cell, like formula rules).
+ */
+type ConditionalFormatValue = {
+    type: 'min';
+} | {
+    type: 'max';
+} | {
+    type: 'number';
+    value: number;
+} | {
+    type: 'percent';
+    value: number;
+} | {
+    type: 'percentile';
+    value: number;
+} | {
+    type: 'formula';
+    formula: string;
+};
+/** `dates occurring` periods (weeks start on Sunday, as in Excel's US locale). */
+type ConditionalFormatTimePeriod = 'yesterday' | 'today' | 'tomorrow' | 'last7Days' | 'lastWeek' | 'thisWeek' | 'nextWeek' | 'lastMonth' | 'thisMonth' | 'nextMonth';
+/** Built-in icon sets (the number of icons is the leading digit). */
+type ConditionalFormatIconSet = '3Arrows' | '3ArrowsGray' | '3TrafficLights1' | '3Flags' | '3Symbols' | '3Stars' | '4Arrows' | '4Rating' | '4TrafficLights' | '5Arrows' | '5Rating' | '5Quarters';
+/** The condition of a rule: what it checks and the look it gives. */
+type ConditionalFormatCondition = {
+    /**
+     * Cell value compared with `value` (and `value2` for between). A value
+     * starting with `=` is a formula, relative to the range's top-left
+     * cell; anything else is typed input (`10`, `5%`, `3/4/2026`, `Done`).
+     */
+    type: 'cellIs';
+    operator: ConditionalFormatOperator;
+    value: string;
+    value2?: string;
+    style: ConditionalFormatStyle;
+} | {
+    /** A formula written for the range's top-left cell: `=$B2>100` formats whole rows. */
+    type: 'expression';
+    formula: string;
+    style: ConditionalFormatStyle;
+} | {
+    /** Case-insensitive text tests on the cell's value as text. */
+    type: 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith';
+    text: string;
+    style: ConditionalFormatStyle;
+} | {
+    type: 'blanks' | 'noBlanks' | 'errors' | 'noErrors' | 'duplicate' | 'unique';
+    style: ConditionalFormatStyle;
+} | {
+    /** Top/bottom `rank` values, or `rank` percent of them. */
+    type: 'top10';
+    bottom?: boolean;
+    percent?: boolean;
+    rank: number;
+    style: ConditionalFormatStyle;
+} | {
+    /** Above (or below) the average, optionally by `stdDev` standard deviations. */
+    type: 'aboveAverage';
+    below?: boolean;
+    equal?: boolean;
+    stdDev?: number;
+    style: ConditionalFormatStyle;
+} | {
+    type: 'timePeriod';
+    period: ConditionalFormatTimePeriod;
+    style: ConditionalFormatStyle;
+} | {
+    /** Two or three stops (low, [mid,] high) with colours; the fill blends between them. */
+    type: 'colorScale';
+    stops: Array<{
+        value: ConditionalFormatValue;
+        color: string;
+    }>;
+} | {
+    type: 'dataBar';
+    min?: ConditionalFormatValue;
+    max?: ConditionalFormatValue;
+    color?: string;
+    gradient?: boolean;
+    showValue?: boolean;
+} | {
+    type: 'iconSet';
+    set?: ConditionalFormatIconSet;
+    /**
+     * One threshold per icon, the first being the lower bound (as in
+     * files), or one fewer (the lower bound left out). Default: even
+     * percent steps (0, 33, 67 for three icons).
+     */
+    thresholds?: ConditionalFormatValue[];
+    reverse?: boolean;
+    showValue?: boolean;
+};
+type ConditionalFormatType = ConditionalFormatCondition['type'];
+/**
+ * A conditional format: a condition applied to one or more ranges. Rules
+ * are kept in priority order (the first rule has the highest priority).
+ * Ranges are 0-based and belong to the sheet that stores the rule.
+ */
+type ConditionalFormatRule = ConditionalFormatCondition & {
+    id: string;
+    ranges: CellRange[];
+    /** When this rule matches a cell, lower-priority rules are not applied to it. */
+    stopIfTrue?: boolean;
+};
+/** A rule to add: the id is generated when left out. */
+type NewConditionalFormatRule = ConditionalFormatCondition & {
+    id?: string;
+    ranges: CellRange[];
+    stopIfTrue?: boolean;
+};
+/** The conditional look of one cell, combined from every rule that applies. */
+interface ConditionalCellFormat {
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    /** Data bar: `fraction` (0..1) of the cell width. */
+    dataBar?: {
+        fraction: number;
+        color: string;
+        gradient: boolean;
+    };
+    /** Icon of an icon set: `index` 0 is the lowest icon; `id` is `"<set>:<index>"`. */
+    icon?: {
+        set: ConditionalFormatIconSet;
+        index: number;
+        id: string;
+    };
+    /** A data bar or icon set with `showValue: false`: show the bar / icon only. */
+    hideValue?: boolean;
+}
+/** Per-cell results of evaluating the conditional formats of a sheet. */
+interface ConditionalFormatOverlay {
+    /** The conditional look of (row, col), or undefined when no rule applies. */
+    get(row: number, col: number): ConditionalCellFormat | undefined;
+    /** Number of cells with a conditional look. */
+    readonly size: number;
+    /** Every formatted cell. */
+    entries(): IterableIterator<[{
+        row: number;
+        col: number;
+    }, ConditionalCellFormat]>;
+}
+/** What evaluation needs to know about a sheet. Rows and columns are 0-based. */
+interface ConditionalFormatSheet {
+    rowCount: number;
+    colCount: number;
+    /** The cell's value: number, text (dates are ISO text), boolean, error code or ''. */
+    getValue(row: number, col: number): unknown;
+    /**
+     * Evaluates a formula (with a leading `=`) as if it were in (row, col).
+     * Without it, formula rules never match and formula anchors count as 0.
+     */
+    evaluateFormula?(formula: string, row: number, col: number): unknown;
+    /** The current date, for `timePeriod` rules (default: now). */
+    today?(): Date;
+}
+
+/**
+ * Data validation rule model.
+ *
+ * Portions ported from gridcraft/crates/model/src/features.rs (MIT OR
+ * Apache-2.0, © ArtCraft Team and contributors). See THIRD_PARTY_NOTICES.md.
+ */
+
+/** What a validated cell may hold. `any` only shows the input message. */
+type DataValidationType = 'any' | 'whole' | 'decimal' | 'list' | 'date' | 'time' | 'textLength' | 'custom';
+type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+/**
+ * How invalid input is handled: `stop` rejects it; `warning` asks whether to
+ * keep it (Yes keeps, No returns to editing, Cancel discards); `information`
+ * tells and keeps it unless cancelled.
+ */
+type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
+interface DataValidationRule {
+    id: string;
+    /** Cells the rule applies to (0-based, on the sheet that stores the rule). */
+    ranges: CellRange[];
+    type: DataValidationType;
+    /** For whole, decimal, date, time and text length (default `between`). */
+    operator?: DataValidationOperator;
+    /**
+     * First value: a number, date (`2026-01-31`, `1/31/2026`), time (`9:00`)
+     * or a formula (`=B1`, relative to the range's top-left cell). For `list`,
+     * comma-separated items (`Low,Medium,High`) or a range / formula
+     * (`=$H$1:$H$5`). For `custom`, a formula that must be TRUE; it sees the
+     * value being entered.
+     */
+    formula1?: string;
+    /** Second value, for `between` / `notBetween`. */
+    formula2?: string;
+    /** Blank input is always valid (default true). */
+    ignoreBlank?: boolean;
+    /** Show a dropdown arrow on list cells (default true). */
+    inCellDropdown?: boolean;
+    inputTitle?: string;
+    /** Shown while a cell of the rule is selected. */
+    inputMessage?: string;
+    /** Default true. */
+    showInputMessage?: boolean;
+    errorTitle?: string;
+    errorMessage?: string;
+    /** Default `stop`. */
+    errorStyle?: DataValidationErrorStyle;
+    /** When false, any input is accepted (the rule still drives dropdowns and circles). Default true. */
+    showErrorAlert?: boolean;
+}
+/** A rule to add: the id is generated when left out. */
+type NewDataValidationRule = Omit<DataValidationRule, 'id'> & {
+    id?: string;
+};
+/** The outcome of checking input against a cell's validation. */
+interface DataValidationResult {
+    valid: boolean;
+    /** The rule that applied, if any. */
+    rule?: DataValidationRule;
+    /** For invalid input: how to alert. */
+    errorStyle?: DataValidationErrorStyle;
+    /** Alert title and message (defaults filled in). */
+    title?: string;
+    message?: string;
+}
+/** What validation needs to know about a sheet. Rows and columns are 0-based. */
+interface DataValidationSheet {
+    rowCount: number;
+    colCount: number;
+    getValue(row: number, col: number): unknown;
+    /** Typed input of a cell (`raw`), used by `findInvalidCells`. Formulas are checked through their value. */
+    getInput?(row: number, col: number): string;
+    /**
+     * Evaluates a formula (with a leading `=`) as if it were in (row, col).
+     * `entered`, when given, is the value being typed into that cell: the
+     * formula must see it instead of the cell's current value.
+     */
+    evaluateFormula?(formula: string, row: number, col: number, entered?: {
+        row: number;
+        col: number;
+        value: unknown;
+    }): unknown;
+}
+
+type CellFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'badge' | 'status' | 'assignee';
+type ColumnType = 'bound' | 'freeform' | 'formula';
+interface ColumnBinding {
+    dataSource: string;
+    field: string;
+}
+interface SpreadsheetColumn {
+    id: string;
+    key: string;
+    title: string;
+    width?: number;
+    type: ColumnType;
+    binding?: ColumnBinding;
+    formula?: string;
+    format?: CellFormat;
+    /**
+     * Number format code for the column's cells (e.g. `#,##0.00`,
+     * `"$"#,##0.00;[Red]("$"#,##0.00)`, `m/d/yyyy`). Cells without an explicit
+     * code of their own use it instead of the automatic one chosen for typed
+     * input. See `SpreadsheetController.setColumnNumberFormat`.
+     */
+    numberFormat?: string;
+    readOnly?: boolean;
+    hidden?: boolean;
+}
+type RowType = 'record' | 'freeform';
+interface SpreadsheetRow {
+    id: string;
+    index: number;
+    height?: number;
+    recordId?: string;
+    type: RowType;
+    hidden?: boolean;
+}
+interface CellCoordinate {
+    row: number;
+    col: number;
+    rowId?: string;
+    colId?: string;
+}
+interface CellRange {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}
+interface CellData {
+    raw: string;
+    /**
+     * Evaluated value. Typed (non-formula) input is parsed: `"120"` → 120,
+     * `"TRUE"` → true, `"3/4/2026"` → `"2026-03-04"` (dates are ISO text),
+     * `"10:30"` → 0.4375 (a time alone is a fraction of a day); `'120` forces
+     * the text `"120"`. Formulas store their result.
+     */
+    value: any;
+    error?: string;
+    /** Why the formula failed, e.g. `Argument 2 of SUMIF must be a range.` Set alongside `error`. */
+    errorMessage?: string;
+    format?: CellFormat;
+    /**
+     * Excel number format code used to display the value (see
+     * `formatCellDisplay`). Set explicitly (`explicitNumberFormat`), inherited
+     * from the column's `numberFormat`, or chosen automatically for typed input,
+     * e.g. `"$"#,##0.00` for `$1,200.50`, `0%` for `10%`, `#,##0` for `1,234`,
+     * `m/d/yyyy` for `3/4/2026`, `h:mm` for `10:30`. Absent for General.
+     */
+    numberFormat?: string;
+    /**
+     * True when `numberFormat` was set explicitly (`setCellNumberFormat`):
+     * typing into the cell keeps it instead of choosing an automatic format.
+     */
+    explicitNumberFormat?: boolean;
+    readOnly?: boolean;
+    /**
+     * Set (only) on cells showing a value spilled from a dynamic array: the
+     * anchor cell holding the formula, e.g. `A1`. Spilled cells keep an empty
+     * `raw` and are never stored in the document.
+     */
+    spillAnchor?: string;
+}
+/** A dynamic array spilled from its anchor cell (the cell holding the formula). */
+interface SpreadsheetSpill {
+    /** Anchor cell key, e.g. `A1`. */
+    key: string;
+    anchor: {
+        row: number;
+        col: number;
+    };
+    /** Every cell the array covers, anchor included. */
+    range: CellRange;
+    /** The anchor's formula. */
+    formula: string;
+}
+interface SpreadsheetDocument {
+    id: string;
+    name: string;
+    columns: SpreadsheetColumn[];
+    rows: SpreadsheetRow[];
+    cells: Record<string, Record<string, CellData>>;
+    createdAt?: number;
+    updatedAt?: number;
+    table?: SpreadsheetTableSettings;
+}
+type SortDirection = 'asc' | 'desc';
+interface SortKey {
+    colId: string;
+    direction?: SortDirection;
+}
+type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'between' | 'isBlank' | 'isNotBlank' | 'oneOf';
+interface FilterRule {
+    id: string;
+    colId: string;
+    operator: FilterOperator;
+    value?: string | number;
+    value2?: string | number;
+    values?: string[];
+}
+interface SpreadsheetFilterState {
+    enabled: boolean;
+    rules: FilterRule[];
+}
+type GroupAggregate = 'sum' | 'count' | 'average' | 'min' | 'max';
+interface GroupSummary {
+    colId: string;
+    aggregate: GroupAggregate;
+}
+interface SpreadsheetGrouping {
+    colId: string;
+    summaries: GroupSummary[];
+    collapsed: string[];
+}
+interface SpreadsheetTableSettings {
+    headerRowCount?: number;
+    footerRowCount?: number;
+    headerColumnCount?: number;
+    frozenRowCount?: number;
+    frozenColumnCount?: number;
+    merges?: CellRange[];
+    filter?: SpreadsheetFilterState;
+    grouping?: SpreadsheetGrouping;
+    /**
+     * Conditional formats of this sheet, highest priority first. Kept with the
+     * other per-sheet table state (undoable through document snapshots).
+     */
+    conditionalFormats?: ConditionalFormatRule[];
+    /** Data validation rules of this sheet; a cell uses the first rule containing it. */
+    dataValidations?: DataValidationRule[];
+}
+interface SpreadsheetDataSourceField {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'date' | 'boolean' | 'enum';
+    options?: Array<{
+        key: string;
+        label: string;
+        color?: string;
+    }>;
+}
+interface SpreadsheetDataSource {
+    id: string;
+    name: string;
+    getRecords(): Array<{
+        id: string;
+        [key: string]: any;
+    }>;
+    getFields(): SpreadsheetDataSourceField[];
+    updateRecord(recordId: string, field: string, value: any): Promise<void> | void;
+}
+/**
+ * A defined name (Formulas › Name Manager): a range, constant, formula or
+ * LAMBDA that formulas can use by name, e.g. `=Price*(1+Rate)`,
+ * `=SUM(Sales)`, `=Double(4)`.
+ */
+interface SpreadsheetDefinedName {
+    /** The name, e.g. `Rate`. Unique per scope, compared case-insensitively. */
+    name: string;
+    /**
+     * What the name refers to, as a formula: `=Data!$A$2:$A$20`, `=0.07`,
+     * `=Rate*2` or `=LAMBDA(x, x*2)`. Unqualified references refer to the
+     * name's sheet (sheet scope) or to the sheet of the formula using it.
+     */
+    refersTo: string;
+    /** Id of the sheet for a sheet-scoped name; unset for workbook scope. */
+    sheetId?: string;
+    comment?: string;
+}
+/**
+ * A workbook: several sheets plus defined names. A `SpreadsheetController`
+ * created from a single document is a workbook with one sheet.
+ */
+interface SpreadsheetWorkbook {
+    /** The sheets in tab order. A sheet's `name` is its tab name (unique, case-insensitively). */
+    sheets: SpreadsheetDocument[];
+    /** Id of the sheet shown (default: the first). */
+    activeSheetId?: string;
+    names?: SpreadsheetDefinedName[];
+}
+/** A sheet tab: what sheet-tab bars render. */
+interface SpreadsheetSheetInfo {
+    id: string;
+    name: string;
+    /** Position in tab order (0-based). */
+    index: number;
+    active: boolean;
+}
+
+type FormulaTokenType = 'NUMBER' | 'STRING' | 'BOOLEAN' | 'ERROR' | 'CELL_REF' | 'RANGE' | 'SPILL_REF' | 'PROPERTY_REF' | 'IDENTIFIER' | 'OPERATOR' | 'LPAREN' | 'RPAREN' | 'COMMA' | 'EOF';
+interface FormulaToken {
+    type: FormulaTokenType;
+    value: string;
+    /** Offset of the token in the formula (for a sheet-qualified reference, of its sheet prefix). */
+    position: number;
+    /** Offset just past the token. */
+    end?: number;
+    /**
+     * Sheet of a sheet-qualified reference or name (`Sheet2!A1`, `'My Sheet'!A1:B2`,
+     * `Data!Rate`), unquoted. Unset for references to the formula's own sheet.
+     */
+    sheet?: string;
+    /** Last sheet of a 3-D reference (`Sheet1:Sheet3!A1`). */
+    sheetEnd?: string;
+    /** Offset where the reference itself starts, after the sheet prefix and `!`. */
+    refStart?: number;
+}
+declare function tokenizeFormula(formula: string): FormulaToken[];
+
+/** Row number used for the open end of whole-column ranges such as `A:A`. */
+declare const WHOLE_COLUMN_END_ROW = 1048576;
+type ASTNode = LiteralNode | CellRefNode | RangeNode | SpillRefNode | NameNode | PropertyRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode | InvokeNode | MissingNode;
+/**
+ * Sheet qualification of a reference: `Sheet2!A1` has `sheet: 'Sheet2'`;
+ * a 3-D reference `Sheet1:Sheet3!A1` also has `sheetEnd: 'Sheet3'`. Unset
+ * for references to the formula's own sheet.
+ */
+interface SheetQualifier {
+    sheet?: string;
+    sheetEnd?: string;
+}
+interface LiteralNode {
+    type: 'Literal';
+    value: number | string | boolean;
+}
+interface CellRefNode extends SheetQualifier {
+    type: 'CellRef';
+    ref: string;
+    col: string;
+    row: number;
+}
+interface RangeNode extends SheetQualifier {
+    type: 'Range';
+    raw: string;
+    startCol: string;
+    startRow: number;
+    endCol: string;
+    endRow: number;
+}
+/** `A1#`: the whole spill range of the dynamic array anchored at A1. */
+interface SpillRefNode extends SheetQualifier {
+    type: 'SpillRef';
+    /** Anchor cell, e.g. `A1`. */
+    ref: string;
+    col: string;
+    row: number;
+}
+/**
+ * A bare name: a LET or LAMBDA variable, a defined name (`Rate`,
+ * `Data!Rate` with `sheet`), or `#NAME?` when nothing defines it.
+ */
+interface NameNode {
+    type: 'Name';
+    name: string;
+    /** Sheet of a sheet-qualified name (`Data!Rate`). */
+    sheet?: string;
+}
+interface PropertyRefNode {
+    type: 'PropertyRef';
+    property: string;
+}
+interface BinaryOpNode {
+    type: 'BinaryOp';
+    op: string;
+    left: ASTNode;
+    right: ASTNode;
+}
+interface UnaryOpNode {
+    type: 'UnaryOp';
+    op: string;
+    argument: ASTNode;
+}
+interface FunctionCallNode {
+    type: 'FunctionCall';
+    name: string;
+    args: ASTNode[];
+}
+/**
+ * A call of a computed function: `LAMBDA(x, x+1)(2)` or `(f)(2)`. Calls of a
+ * named function, defined name or variable (`F(2)`) are `FunctionCall`s.
+ */
+interface InvokeNode {
+    type: 'Invoke';
+    callee: ASTNode;
+    args: ASTNode[];
+}
+/** An argument left empty, as in `IF(A1,,1)` or `LAMBDA(x, y, x)(1,)`. */
+interface MissingNode {
+    type: 'Missing';
+}
+declare function parseCellReference(ref: string): {
+    col: string;
+    row: number;
+};
+declare function parseRange(rangeStr: string): RangeNode;
+declare class FormulaParser {
+    private tokens;
+    private current;
+    constructor(tokens: FormulaToken[]);
+    parse(): ASTNode;
+    private expression;
+    private comparison;
+    private concatenation;
+    private addition;
+    private multiplication;
+    private exponentiation;
+    private unary;
+    /** Arguments after `(` up to and including `)`. Empty positions are `Missing`. */
+    private argumentList;
+    private primary;
+    private match;
+    private matchOperator;
+    private check;
+    private advance;
+    private isAtEnd;
+    private peek;
+    private previous;
+    private consume;
+}
+declare function parseFormula(formula: string): ASTNode;
+
+/** Spreadsheet error values. They propagate through operators and functions. */
+declare const FORMULA_ERRORS: Set<string>;
+type FormulaErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#N/A' | '#NUM!' | '#CYCLE!' | '#ERROR!' | '#SPILL!' | '#CALC!';
+declare function isFormulaError(value: unknown): value is string;
+/**
+ * Number to text as Excel converts it in `&` and General display: up to 15
+ * significant digits, scientific for very large or very small magnitudes.
+ */
+declare function numberToText(n: number): string;
+/**
+ * Compares numbers the way Excel does: both are rounded to 15 significant
+ * digits first, so binary noise such as `0.1+0.2` versus `0.3` counts as equal.
+ */
+declare function compareNumbers(a: number, b: number): number;
+/**
+ * Excel's comparison for the `=`, `<>`, `<`… operators: numbers < text <
+ * booleans < errors, numbers compared at 15 significant digits, text
+ * case-insensitively. A blank acts as 0, "" or FALSE depending on the other
+ * side. Dates are ISO text: two ISO dates compare chronologically
+ * ("2026-1-5" is before "2026-01-10"), and an ISO date against a number
+ * compares as its serial number.
+ */
+declare function compareValues(left: unknown, right: unknown): number;
+/**
+ * Sort order (ascending): numbers, text, booleans, errors, then blanks last.
+ * Errors are equal to each other, so sorting keeps their order.
+ */
+declare function sortCompareValues(left: unknown, right: unknown): number;
+declare function colNameToIndex(col: string): number;
+declare function indexToColName(index: number): string;
+/**
+ * A rectangular block of values. `values` is column-major (the order in which
+ * `EvaluationContext.resolveRange` returns cells): `values[col * rows + row]`.
+ */
+interface FormulaRange {
+    rows: number;
+    cols: number;
+    values: any[];
+}
+
+/** What a defined name refers to, as returned by `EvaluationContext.resolveName`. */
+interface FormulaNameDefinition {
+    /** Formula text (`=Sheet1!$A$1:$A$9`, `=0.07`, `=LAMBDA(x, x*2)`) or a parsed formula. */
+    formula: string | ASTNode;
+    /** Sheet that unqualified references in the formula refer to (a sheet-scoped name's sheet). */
+    sheet?: string;
+    /** A key identifying the name (for cycle detection), e.g. `Data!RATE`. Defaults to the name. */
+    key?: string;
+}
+/** Hints for `EvaluationContext.resolveRange`. */
+interface RangeResolveOptions {
+    /** The values are only aggregated by a function that ignores blank cells. */
+    skipBlanks?: boolean;
+}
+interface EvaluationContext {
+    /**
+     * Value of a cell. `sheet` is set for sheet-qualified references
+     * (`Sheet2!A1`); undefined means the formula's own sheet. Return `#REF!`
+     * for a sheet that doesn't exist.
+     */
+    resolveCell?: (col: string, row: number, sheet?: string) => any;
+    /**
+     * Values of a rectangular range, column by column (all rows of the first
+     * column, then the next column). Lookup functions rely on this order.
+     * `sheet` as in `resolveCell`; return an error code for a missing sheet.
+     * `options.skipBlanks` is a hint that the caller ignores blank cells
+     * (SUM, COUNT, AVERAGE, …): a resolver may then leave them out, so sparse
+     * ranges cost no array slots. Returning every value is always correct.
+     */
+    resolveRange?: (startCol: string, startRow: number, endCol: string, endRow: number, sheet?: string, options?: RangeResolveOptions) => any[] | string;
+    resolveProperty?: (property: string) => any;
+    /**
+     * The spilled array anchored at a cell, for `A1#` references: its shape and
+     * values (column-major, like `resolveRange`), or an error code (e.g.
+     * `#REF!` when the cell holds no array).
+     */
+    resolveSpill?: (col: string, row: number, sheet?: string) => FormulaRange | string;
+    /**
+     * The sheets of a 3-D reference (`Sheet1:Sheet3!A1`), from `first` to
+     * `last` in tab order, or an error code when either sheet is missing.
+     */
+    resolveSheetSpan?: (first: string, last: string) => string[] | string;
+    /**
+     * A defined name (`Rate`, `Data!Rate`), or null when none is visible.
+     * `sheet` is the qualifying sheet, or the sheet whose names apply (when a
+     * sheet-scoped name refers to another name); undefined means the formula's
+     * own sheet. Sheet-scoped names come before workbook-scoped ones.
+     */
+    resolveName?: (name: string, sheet?: string) => FormulaNameDefinition | null;
+    /**
+     * The cell holding the formula being evaluated, used by the implicit
+     * intersection operator (`=@A:A` reads the cell in the formula's row).
+     */
+    getFormulaCell?: () => {
+        col: string;
+        row: number;
+    } | null;
+}
+/** A human-readable reason for an error value. */
+interface FormulaDiagnostic {
+    code: FormulaErrorCode;
+    message: string;
+}
+interface FormulaEvaluationResult {
+    /** The computed value; an error code such as `#VALUE!` when the formula fails. */
+    value: any;
+    /** The error code when `value` is an error. */
+    error?: FormulaErrorCode;
+    /** Why the formula failed, e.g. `Argument 2 of SUMIF must be a range.` */
+    message?: string;
+    /**
+     * Set when the formula returned an array of more than one value (a
+     * dynamic array). `value` is then its top-left value; a spreadsheet spills
+     * the whole array into the cells below and to the right.
+     */
+    array?: FormulaRange;
+}
+/** Generic explanation of an error code, used when no specific reason was recorded. */
+declare function describeFormulaError(code: string): string;
+/** Largest array a formula may build (SEQUENCE, RANDARRAY, broadcasting). */
+declare const MAX_FORMULA_ARRAY_SIZE = 1000000;
+declare class FormulaEvaluator {
+    private context;
+    private diagnostics;
+    private env;
+    private defaultSheet;
+    private lambdaDepth;
+    private nameStack;
+    private parsedNames;
+    constructor(context?: EvaluationContext);
+    /**
+     * Evaluates a formula. Errors in the formula are returned as error values
+     * (`#VALUE!` etc.); malformed formulas and missing resolvers throw.
+     */
+    evaluate(astOrFormula: ASTNode | string): any;
+    /**
+     * Evaluates a formula and explains errors. Never throws: malformed formulas
+     * return `#ERROR!` with the parser's message. A result with several values
+     * (a range or a dynamic array) is returned in `array`, with its top-left
+     * value as `value`; a one-value array is just that value.
+     */
+    evaluateWithDiagnostics(astOrFormula: ASTNode | string): FormulaEvaluationResult;
+    /** Records why an error happened and returns the error code. */
+    private fail;
+    private evaluateNode;
+    private unary;
+    /** A binary operator on two single values. */
+    private binary;
+    /**
+     * Dates are ISO text: date +/- days is a date, date - date is a number of
+     * days (fractional when times are involved).
+     */
+    private dateArithmetic;
+    /**
+     * `@` (implicit intersection): a range reference reads the cell in the
+     * formula's row (one column) or column (one row); arrays give their
+     * top-left value.
+     */
+    private implicitIntersection;
+    private evaluateSpillRef;
+    private evaluateRange;
+    private callFunction;
+    private finishCall;
+    /**
+     * Arguments evaluated on first use. With `skipBlanks` (the function ignores
+     * blank cells), range arguments may come back without their blanks.
+     */
+    private lazyArguments;
+    /**
+     * Applies a scalar function element by element when it receives arrays
+     * (`=LEN(A1:A3)`, `=IF(A1:A3>1, "y", "n")`). Arguments typed `range` are
+     * passed whole. Returns undefined when no trigger argument is a
+     * multi-value array.
+     */
+    private liftOverArrays;
+    /** A bare name: a variable, a defined name, or #NAME?. */
+    private evaluateName;
+    private lookupDefinedName;
+    /**
+     * Evaluates a defined name's formula, outside any LET/LAMBDA variables, with
+     * unqualified references pointing at the name's sheet (for sheet-scoped
+     * names).
+     */
+    private evaluateDefinedName;
+    /** A 3-D reference (`Sheet1:Sheet3!A1`, `Sheet1:Sheet3!A1:B2`): every sheet's values, in tab order. */
+    private evaluate3d;
+    /** Calls a lambda with argument expressions, evaluated in the caller's scope. */
+    private invokeLambda;
+    /** Calls a lambda with argument values (`omitted`: positions left out, for ISOMITTED). */
+    private invokeWithValues;
+    private evaluateSpecialForm;
+    /** LET(name1, value1, [name2, value2, ...], calculation). */
+    private evaluateLet;
+    /** LAMBDA([parameter1, ...], calculation): a function value closing over the current variables. */
+    private evaluateLambda;
+    /**
+     * The function argument of a LAMBDA helper: a lambda, or a built-in
+     * function given by name (`BYROW(A1:C3, SUM)`) unless a variable or defined
+     * name has that name. Returns an error string when it is neither.
+     */
+    private lambdaArgument;
+    /** Calls a built-in function with already evaluated arguments. */
+    private callBuiltinWithValues;
+    /** Checks a lambda takes `count` parameters (native functions take any count). */
+    private checkArity;
+    /** MAP(array1, [array2, ...], lambda): calls the lambda with each element. */
+    private evaluateMap;
+    /**
+     * REDUCE([initial_value], array, lambda) / SCAN(...): folds the array row
+     * by row with lambda(accumulator, value). SCAN returns every intermediate
+     * value, in the array's shape.
+     */
+    private evaluateReduce;
+    /** BYROW(array, lambda) / BYCOL(array, lambda): one result per row (a column) or per column (a row). */
+    private evaluateByLine;
+    /** MAKEARRAY(rows, columns, lambda): lambda(row, column) for every 1-based position. */
+    private evaluateMakeArray;
+    private createContext;
+}
+
+interface CellDep {
+    col: string;
+    /** Row number; 0 for a whole-column dependency (`A:A`). */
+    row: number;
+    /** Sheet of a sheet-qualified reference (`Sheet2!A1`); unset for the formula's own sheet. */
+    sheet?: string;
+    /** Last sheet of a 3-D reference (`Sheet1:Sheet3!A1`). */
+    sheetEnd?: string;
+}
+/** A name used by a formula: a defined name, LET/LAMBDA variable or (with `call`) a function. */
+interface NameDep {
+    /** Upper-case name. */
+    name: string;
+    /** Sheet of a sheet-qualified name (`Data!Rate`). */
+    sheet?: string;
+    /** Used as a function (`Double(4)`). */
+    call: boolean;
+}
+/**
+ * Names a formula uses (bare names and calls), for dependencies on defined
+ * names. LET/LAMBDA variables are included; callers ignore names that are
+ * not defined.
+ */
+declare function extractNameDependencies(node: ASTNode): NameDep[];
+/**
+ * Dependency key for "every cell in column `col`", used by whole-column ranges
+ * (`A:A`) instead of expanding a million cell keys.
+ */
+declare const columnDependencyKey: (col: string) => string;
+declare function extractCellDependencies(node: ASTNode): CellDep[];
+/**
+ * A reference a formula reads, without expanding ranges: a single cell or
+ * a rectangle (`A1:B9`; a whole column `A:A` runs to `WHOLE_COLUMN_END_ROW`).
+ * Columns are letters, rows are 1-based; ranges are normalised (start ≤ end).
+ */
+type ReferenceDep = ({
+    kind: 'cell';
+    col: string;
+    row: number;
+} & Pick<CellDep, 'sheet' | 'sheetEnd'>) | ({
+    kind: 'range';
+    startCol: string;
+    startRow: number;
+    endCol: string;
+    endRow: number;
+} & Pick<CellDep, 'sheet' | 'sheetEnd'>);
+/**
+ * The cells and ranges a formula reads, ranges kept whole (unlike
+ * `extractCellDependencies`, which lists every cell of a range). `A1#`
+ * depends on its anchor `A1`.
+ */
+declare function extractReferenceDependencies(node: ASTNode): ReferenceDep[];
+/**
+ * Dependency key of a rectangle (`A1:B9`, or `SHEET!A1:B9` with a sheet
+ * prefix), for `DependencyGraph.setCellDependencies`. The graph stores it as
+ * one range, however many cells it covers.
+ */
+declare function rangeDependencyKey(startCol: string, startRow: number, endCol: string, endRow: number, sheetPrefix?: string): string;
+interface IntervalEntry<T> {
+    r0: number;
+    r1: number;
+    id: string;
+    payload: T;
+}
+/**
+ * Row intervals `[r0, r1]` with payloads, answering "which intervals overlap
+ * rows `a..b`?" in O(log n + k). Entries are sorted by start, with an
+ * implicit segment tree of the largest end below each node, so a query only
+ * descends into subtrees holding a match. Removals mark entries dead;
+ * insertions wait in a small pending set. Both are merged in (on the next
+ * query) once either grows, so mutations cost O(log n) amortised.
+ */
+declare class IntervalIndex<T> {
+    private items;
+    private dead;
+    private deadCount;
+    private maxEnd;
+    private leaves;
+    private position;
+    private pending;
+    /** Live entries. */
+    get size(): number;
+    /** Adds (or revives) the entry `id`. An id always names the same interval. */
+    insert(r0: number, r1: number, id: string, payload: T): void;
+    remove(id: string): void;
+    /** Merges pending insertions and drops dead entries when there are enough of them. */
+    private settle;
+    /** Calls `fn` for every live interval overlapping rows `a..b` (`r0 <= b && r1 >= a`). */
+    query(a: number, b: number, fn: (payload: T, entry: IntervalEntry<T>) => void): void;
+    private walk;
+}
+/** Sizes of the dependency index (see `DependencyGraph.getIndexStats`). */
+interface DependencyIndexStats {
+    /** Cells with registered dependencies (formulas). */
+    formulas: number;
+    /** Single-cell edges (formula → cell it reads). */
+    cellEdges: number;
+    /** Range entries: one per range (per column for ranges up to 64 columns wide), however many cells it covers. */
+    rangeEntries: number;
+    /** Formulas that use a volatile function. */
+    volatile: number;
+}
+declare class DependencyGraph {
+    private nodes;
+    private cellDependents;
+    private rangeIndex;
+    private volatile;
+    private spillDependencies;
+    private spillDependents;
+    private spillEdges;
+    private blockingEdges;
+    private parsed;
+    private parse;
+    private sheetIndex;
+    private removeNode;
+    /**
+     * Sets what `cellKey` depends on directly, replacing its previous
+     * dependencies. Keys are single cells (`B2`), rectangles (`A1:B9`) or
+     * whole columns (`A:`, see `columnDependencyKey`), each optionally
+     * sheet-qualified (`SHEET!A1:A9`). Ranges are stored whole in an interval
+     * index, never expanded cell by cell. `setCellFormula` derives the keys
+     * from a formula.
+     */
+    setCellDependencies(cellKey: string, dependencyKeys: Iterable<string>): void;
+    /**
+     * Marks `cellKey` as volatile (its formula uses NOW, RAND, …): it is
+     * recalculated by every plan made with `includeVolatile`, whatever changed.
+     */
+    setVolatile(cellKey: string, volatile: boolean): void;
+    /** Cells whose formulas are volatile. */
+    getVolatileKeys(): string[];
+    setCellFormula(cellKey: string, formulaStr: string | null): void;
+    /** Removes every registered formula and dependency. */
+    clear(): void;
+    /**
+     * Records the dynamic-array edges of the anchor `anchorKey`, replacing its
+     * previous ones: every key in `spilledKeys` (cells holding its spilled
+     * values) depends on the anchor, and the anchor depends on every key in
+     * `blockingKeys` (cells that stop it spilling). Pass empty lists to remove
+     * the anchor's edges.
+     */
+    setSpillEdges(anchorKey: string, spilledKeys: Iterable<string>, blockingKeys?: Iterable<string>): void;
+    /**
+     * Drops the edge from a spilled cell to the anchor whose values it holds,
+     * for a cell that just got input of its own: its value no longer comes
+     * from the anchor (which recalculates and becomes `#SPILL!`), and the
+     * stale edge could otherwise close a false cycle with the cell's new
+     * formula before the anchor is evaluated again.
+     */
+    detachSpilledCell(cellKey: string): void;
+    /** The spilled cells registered for `anchorKey` by `setSpillEdges`. */
+    getSpilledKeys(anchorKey: string): string[];
+    /**
+     * What a cell depends on directly: single cells, ranges (as registered,
+     * e.g. `A1:A9` or `A:`, not expanded) and dynamic-array (spill) edges.
+     */
+    getDependencies(cellKey: string): string[];
+    /**
+     * Whether the formula in `formulaKey` reads `cellKey` directly: as a cell,
+     * inside one of its ranges, or through a spill edge.
+     */
+    dependsOn(formulaKey: string, cellKey: string): boolean;
+    /**
+     * Formulas (and spilled cells) reading `cellKey` directly, through formulas
+     * or spills. Found in O(log n + k) through the range index.
+     */
+    getDependents(cellKey: string): string[];
+    private collectDependents;
+    /** Sizes of the index: ranges count once (per column), not once per cell. */
+    getIndexStats(): DependencyIndexStats;
+    /**
+     * Detects if there is a cycle containing cellKey.
+     */
+    hasCycle(cellKey: string): boolean;
+    /**
+     * Returns cells affected by updating cellKey in topological order.
+     */
+    getEvaluationOrder(startCellKey: string): {
+        order: string[];
+        hasCycle: boolean;
+    };
+    /**
+     * Plans a recalculation over `cellKeys` (and, with `includeDependents`, every
+     * cell that transitively depends on them; with `includeVolatile`, every
+     * volatile formula and its dependents too). Returns the keys in evaluation
+     * order (dependencies first) and the set of keys that are part of a cycle,
+     * which must be marked `#CYCLE!` instead of evaluated. Every member of a
+     * cycle is reported, not just the cell that closed it.
+     *
+     * Only the planned cells are ordered: a range a formula reads becomes one
+     * node whose edges are the planned cells inside it (found by binary
+     * search), so a range shared by many formulas is resolved once.
+     */
+    getEvaluationPlan(cellKeys: Iterable<string>, options?: {
+        includeDependents?: boolean;
+        includeVolatile?: boolean;
+    }): {
+        order: string[];
+        cyclic: Set<string>;
+    };
+}
+
+/**
+ * A row or column insertion/deletion. `index` is the 0-based position of the
+ * inserted or deleted row/column.
+ */
+interface StructuralChange {
+    axis: 'row' | 'col';
+    index: number;
+    type: 'insert' | 'delete';
+}
+/**
+ * Rewrites the cell and range references in `formula` after a row or column
+ * is inserted or deleted, the way spreadsheet apps do: references after the
+ * change shift, ranges grow or shrink, and references to a deleted row/column
+ * become `#REF!`. Absolute (`$`) markers are kept. String literals, property
+ * references and function names are left untouched.
+ */
+declare function shiftFormulaReferences(formula: string, change: StructuralChange, options?: FormulaReferenceFilter): string;
+/**
+ * Limits a rewrite to some references, e.g. only those pointing at the sheet
+ * that changed: `appliesTo(sheet)` gets the reference's sheet (undefined for
+ * the formula's own sheet) and, for 3-D references, the last sheet.
+ */
+interface FormulaReferenceFilter {
+    appliesTo?: (sheet: string | undefined, sheetEnd: string | undefined) => boolean;
+}
+/** Where a reference passed to a `mapFormulaReferences` callback points. */
+interface FormulaReferenceInfo {
+    /** Sheet of a qualified reference (`Sheet2!A1`), unquoted; undefined for the formula's own sheet. */
+    sheet?: string;
+    /** Last sheet of a 3-D reference. */
+    sheetEnd?: string;
+}
+/**
+ * Calls `rewrite` with the source text of every cell or range reference in
+ * `formula` (e.g. `"$A1"`, `"B2:C10"`, `"A:A"`) and splices in its result.
+ * For a spill reference (`A1#`) it receives the anchor (`"A1"`) and the `#`
+ * is kept, unless the rewrite returns `#REF!`. A sheet prefix (`Sheet2!`,
+ * `'My Sheet'!`) is not part of the text: `info` says which sheet the
+ * reference points at, and the prefix is kept unless the rewrite returns
+ * `#REF!`. String literals, property references and function names (e.g.
+ * `LOG10(`) are skipped. Formulas that fail to tokenize are returned unchanged.
+ */
+declare function mapFormulaReferences(formula: string, rewrite: (reference: string, info: FormulaReferenceInfo) => string): string;
+/**
+ * Moves a formula by (`rowOffset`, `colOffset`), as copy/paste and autofill
+ * do: relative row/column parts shift, `$`-absolute parts stay. A reference
+ * pushed above row 1 or left of column A becomes `#REF!`.
+ */
+declare function offsetFormulaReferences(formula: string, rowOffset: number, colOffset: number): string;
+/** A 0-based cell position. */
+interface CellPosition {
+    row: number;
+    col: number;
+}
+/**
+ * Rewrites references when cells *move* (sort, transpose): references follow
+ * the cell they point at, whether relative or absolute. `moveCell` returns a
+ * cell's new position, or null when it did not move. A range is remapped only
+ * when its cells moved together as a rectangle of the same size (e.g. a
+ * one-row range inside a sorted row, or a range inside a transposed block);
+ * otherwise it is kept, since it still covers the same rows and columns.
+ */
+declare function remapFormulaReferences(formula: string, moveCell: (position: CellPosition) => CellPosition | null, options?: FormulaReferenceFilter): string;
+/**
+ * Whether a sheet name must be quoted in a formula (`'My Sheet'!A1`): names
+ * with spaces or punctuation, starting with a digit, or that look like a
+ * cell reference (`A1`, `R1C1`) or a boolean.
+ */
+declare function sheetNameNeedsQuotes(name: string): boolean;
+/** A sheet name as written in formulas: `Data`, `'My Sheet'`, `'Bob''s'`. */
+declare function quoteSheetName(name: string): string;
+/** The prefix of a reference to `sheet` (or the 3-D span `sheet:sheetEnd`), with `!`. */
+declare function formatSheetPrefix(sheet: string, sheetEnd?: string): string;
+/**
+ * Rewrites references to the sheet `oldName` (cell, range, spill and 3-D
+ * references, and sheet-qualified names such as `Old!Rate`) after it is
+ * renamed to `newName`, quoting the new name when needed.
+ */
+declare function renameSheetInFormula(formula: string, oldName: string, newName: string): string;
+/**
+ * Rewrites a formula after the sheet `name` is deleted: references to it
+ * become `#REF!`. `order` lists the sheet names before the deletion, in tab
+ * order: a 3-D reference losing an end sheet shrinks to the neighbouring
+ * sheet, as in Excel (`Sheet1:Sheet3!A1` without Sheet1 is `Sheet2:Sheet3!A1`).
+ */
+declare function deleteSheetInFormula(formula: string, name: string, order?: readonly string[]): string;
+/**
+ * Renames uses of the defined name `oldName` (`Rate`, `Rate*2`, `Double(4)`,
+ * `Data!Rate`) to `newName`. `appliesTo(sheet)` decides, for a
+ * sheet-qualified use, whether that sheet's name is the renamed one; unset,
+ * every use is renamed. With `qualifiedOnly`, unqualified uses are kept (the
+ * formula is on a sheet where the name means something else).
+ */
+declare function renameNameInFormula(formula: string, oldName: string, newName: string, options?: {
+    appliesTo?: (sheet: string) => boolean;
+    qualifiedOnly?: boolean;
+}): string;
+/** Upper-case names used in a formula (bare names, calls and sheet-qualified names). */
+declare function formulaIdentifiers(formula: string): Array<{
+    name: string;
+    sheet?: string;
+    call: boolean;
+}>;
+
+declare class DataSourceBinder {
+    private dataSources;
+    register(dataSource: SpreadsheetDataSource): void;
+    unregister(dataSourceId: string): void;
+    getDataSource(id: string): SpreadsheetDataSource | undefined;
+    /**
+     * Generates or reconciles spreadsheet rows from a primary data source.
+     */
+    syncRows(currentRows: SpreadsheetRow[], dataSourceId: string): SpreadsheetRow[];
+    /**
+     * Resolves a record's bound field value.
+     */
+    resolveBoundValue(dataSourceId: string, recordId: string, field: string): any;
+    /**
+     * Dispatches an update to the underlying data source.
+     */
+    commitBoundValue(dataSourceId: string, recordId: string, field: string, value: any): Promise<void>;
+}
+
+/**
+ * Spreadsheet clipboard formats. Copying writes three representations:
+ *
+ * - `text/plain`: TSV of the displayed values (pastes into any app)
+ * - `text/html`: an HTML `<table>` (pastes into docs, mail, other sheets)
+ * - `application/x.pixerate.spreadsheet+json`: raw inputs and formulas, so a
+ *   paste into a pixerate spreadsheet is lossless; formulas are re-based to
+ *   the paste position like a spreadsheet copy/paste
+ *
+ * Pasting prefers the custom format, then an HTML table, then TSV. All
+ * functions here are pure and DOM-free.
+ */
+
+declare const SPREADSHEET_CLIPBOARD_MIME = "application/x.pixerate.spreadsheet+json";
+interface SpreadsheetClipboardCell {
+    raw: string;
+    value: unknown;
+    /** Display text for `text/plain` and `text/html` (e.g. `10%` for 0.1); defaults to the value as text. Not stored in the JSON payload. */
+    text?: string;
+}
+interface SpreadsheetClipboardPayload {
+    type: 'pixerate-spreadsheet';
+    version: 1;
+    /** Position of the copied block's top-left cell, used to re-base formulas. */
+    origin: CellPosition;
+    cells: SpreadsheetClipboardCell[][];
+}
+/** MIME type -> data, as written to `DataTransfer.setData`. */
+type SpreadsheetClipboardData = Record<string, string>;
+/** Anything clipboard data can be read from: a `DataTransfer` or a plain record. */
+type SpreadsheetClipboardSource = {
+    getData(format: string): string;
+} | Record<string, string | undefined>;
+interface ParsedSpreadsheetClipboard {
+    format: 'internal' | 'html' | 'text';
+    /** Raw inputs to write, row by row. */
+    rows: string[][];
+    /** For internal pastes: where the block was copied from. */
+    origin?: CellPosition;
+}
+/** Serializes displayed values as an HTML table. Line breaks become `<br>`. */
+declare function serializeHtmlTable(values: ReadonlyArray<ReadonlyArray<unknown>>): string;
+/**
+ * Extracts cell texts from the first `<table>` in `html` (as written by
+ * spreadsheet apps and browsers). `colspan`/`rowspan` cells are expanded with
+ * blank cells so positions line up. Returns null when there is no table.
+ */
+declare function parseHtmlTable(html: string): string[][] | null;
+/** Builds the three clipboard representations of a copied block. */
+declare function createSpreadsheetClipboardData(cells: SpreadsheetClipboardCell[][], origin: CellPosition): SpreadsheetClipboardData;
+/**
+ * Reads clipboard data, preferring the lossless internal format, then an
+ * HTML table, then TSV text. Returns null when there is nothing to paste.
+ */
+declare function readSpreadsheetClipboard(source: SpreadsheetClipboardSource): ParsedSpreadsheetClipboard | null;
+/**
+ * Moves formulas copied from `origin` so they keep their relative references
+ * when pasted at `target`. Non-formula inputs are returned unchanged.
+ */
+declare function rebaseClipboardRows(rows: string[][], origin: CellPosition, target: CellPosition): string[][];
+
+/**
+ * The render model of a spreadsheet: which rows and columns are shown, in
+ * which order, with group header rows, frozen (sticky) offsets and merged
+ * cell spans. Filters, hidden rows/columns and collapsed groups only affect
+ * this view; the document keeps every row.
+ */
+
+declare const DEFAULT_ROW_HEIGHT = 32;
+declare const DEFAULT_COLUMN_WIDTH = 130;
+type SpreadsheetRowSection = 'header' | 'body' | 'footer';
+interface SpreadsheetRowGroup {
+    key: string;
+    label: string;
+    rowIndices: number[];
+    collapsed: boolean;
+    summaries: Record<string, number | null>;
+}
+type SpreadsheetViewRow = {
+    kind: 'row';
+    row: SpreadsheetRow;
+    index: number;
+    section: SpreadsheetRowSection;
+    frozen: boolean;
+    stickyTop: number;
+    groupKey?: string;
+} | {
+    kind: 'group';
+    group: SpreadsheetRowGroup;
+};
+interface SpreadsheetViewColumn {
+    column: SpreadsheetColumn;
+    index: number;
+    header: boolean;
+    frozen: boolean;
+    stickyLeft: number;
+}
+interface SpreadsheetCellSpan {
+    rowSpan: number;
+    colSpan: number;
+    /** The cell whose content is shown (a merge's top-left cell). */
+    source: CellPosition;
+    merge?: CellRange;
+}
+interface SpreadsheetViewModel {
+    rows: SpreadsheetViewRow[];
+    columns: SpreadsheetViewColumn[];
+    groups: SpreadsheetRowGroup[];
+    /** Visible document row indices in display order (for keyboard navigation). */
+    rowOrder: number[];
+    /** Visible document column indices in display order. */
+    columnOrder: number[];
+    filteredOutCount: number;
+    hiddenRowCount: number;
+    hiddenColumnCount: number;
+    /**
+     * Span of the cell rendered at (row, col): `{ rowSpan: 1, colSpan: 1 }` for
+     * an ordinary cell, the visible extent for a merge's first visible cell, and
+     * null for cells covered by a merge (render nothing).
+     */
+    getCellSpan(row: number, col: number): SpreadsheetCellSpan | null;
+}
+type CellValueReader = (rowIndex: number, colIndex: number) => unknown;
+/** Header and footer row counts, clamped so they never overlap. */
+declare function getTableSections(doc: SpreadsheetDocument): {
+    headerRows: number;
+    footerRows: number;
+};
+declare function getRowSection(doc: SpreadsheetDocument, rowIndex: number): SpreadsheetRowSection;
+/** Whether a body row passes the active filters. Header/footer rows always do. */
+declare function rowPassesFilters(doc: SpreadsheetDocument, rowIndex: number, getValue: CellValueReader): boolean;
+/** Category groups of the (unhidden, unfiltered) body rows. */
+declare function computeRowGroups(doc: SpreadsheetDocument, getValue: CellValueReader): SpreadsheetRowGroup[];
+declare function buildSpreadsheetView(doc: SpreadsheetDocument, getValue: CellValueReader): SpreadsheetViewModel;
+
+interface CsvExportOptions {
+    range?: CellRange | null;
+    delimiter?: string;
+    lineEnding?: string;
+    bom?: boolean;
+    /** Export formulas as typed (`=SUM(A1:A3)`) instead of their values. */
+    formulas?: boolean;
+}
+interface CsvImportOptions {
+    startRow?: number;
+    startCol?: number;
+    delimiter?: string;
+    /** Sheet (id or name) to import into; default the active sheet. */
+    sheet?: string;
+}
+type NewFilterRule = Omit<FilterRule, 'id'> & {
+    id?: string;
+};
+/**
+ * Invalid input waiting for the user: a `stop` alert (retry or cancel) or a
+ * `warning` / `information` prompt (accept, retry or cancel). See
+ * `SpreadsheetController.resolveValidationPrompt`.
+ */
+interface SpreadsheetValidationPrompt {
+    rowId: string;
+    colId: string;
+    row: number;
+    col: number;
+    /** The input that failed validation. */
+    raw: string;
+    /** The failed check: rule, alert style, title and message. */
+    result: DataValidationResult;
+    /** True when the input came from the cell editor (which stays open meanwhile). */
+    editing: boolean;
+}
+/**
+ * Outcome of committing input: `committed`; `rejected` (a `stop` rule) or
+ * `confirm` (a `warning` / `information` rule), with `prompt` now waiting
+ * in `validationPrompt`; `pending` when an earlier prompt is still open;
+ * `none` when nothing was being edited.
+ */
+type SpreadsheetCommitResult = {
+    status: 'committed' | 'none';
+} | {
+    status: 'rejected' | 'confirm' | 'pending';
+    prompt: SpreadsheetValidationPrompt;
+};
+/** How the user answered a validation prompt. */
+type SpreadsheetValidationAction = 'accept' | 'retry' | 'cancel';
+interface SpreadsheetControllerOptions {
+    document?: Partial<SpreadsheetDocument>;
+    dataSources?: SpreadsheetDataSource[];
+    primaryDataSourceId?: string;
+    onDocumentChange?: (doc: SpreadsheetDocument) => void;
+    onSelectionChange?: (activeCell: CellCoordinate | null, range: CellRange | null) => void;
+    onCellCommit?: (rowId: string, colId: string, raw: string, value: any) => void;
+    /**
+     * Start from a workbook with several sheets and defined names instead of
+     * `document`. `document` then names nothing; the active sheet is
+     * `workbook.activeSheetId` (default the first sheet).
+     */
+    workbook?: SpreadsheetWorkbook;
+    /**
+     * Called after any change, like `onDocumentChange`, with the whole
+     * workbook. The object holds the live sheet documents: copy it (or use
+     * `getWorkbook()`) before keeping it.
+     */
+    onWorkbookChange?: (workbook: SpreadsheetWorkbook) => void;
+    /** Called when another sheet becomes active. */
+    onActiveSheetChange?: (sheetId: string) => void;
+    /**
+     * Approximate memory budget for undo/redo snapshots, in bytes (UTF-16 size of
+     * the serialized documents). The oldest undo steps beyond it are dropped, but
+     * the most recent one is always kept. Defaults to 64 MiB; 0 = unlimited.
+     */
+    maxHistoryBytes?: number;
+}
+/** Work done by a recalculation (see `SpreadsheetController.getRecalculationStats`). */
+interface SpreadsheetRecalculationStats {
+    /** Formulas evaluated. */
+    evaluated: number;
+    /** Cells in the evaluation plans: formulas, their dependents and spilled cells. */
+    planned: number;
+    /** Evaluation passes (another pass runs when spill ranges change). */
+    passes: number;
+}
+/** A defined name as listed by `getNames()`. */
+interface SpreadsheetNameInfo extends SpreadsheetDefinedName {
+    /** Name of the sheet a sheet-scoped name belongs to; unset for workbook scope. */
+    sheetName?: string;
+    /** Whether the name holds a LAMBDA (it is called like a function). */
+    isLambda: boolean;
+}
+/** Where a defined name lives: `sheet` (id or name) for a sheet-scoped name. */
+interface SpreadsheetNameScope {
+    sheet?: string;
+}
+declare class SpreadsheetController {
+    activeCell: CellCoordinate | null;
+    selectedRange: CellRange | null;
+    editingCell: CellCoordinate | null;
+    draftValue: string;
+    readonly binder: DataSourceBinder;
+    readonly depGraph: DependencyGraph;
+    readonly evaluator: FormulaEvaluator;
+    private primaryDataSourceId?;
+    private onDocumentChange?;
+    private onWorkbookChange?;
+    private onActiveSheetChange?;
+    private runtimes;
+    private active;
+    private ctx;
+    private boundSheetId;
+    private names;
+    private onSelectionChange?;
+    private onCellCommit?;
+    private undoStack;
+    private redoStack;
+    private isApplyingHistory;
+    private readonly maxHistoryBytes;
+    private batching;
+    private pendingCommits;
+    private evaluatingRowIndex;
+    private evaluatingCell;
+    private spillChanges;
+    private recalcStats;
+    private astCache;
+    private rangeCache;
+    /** The active sheet's document (the sheet the editor shows). */
+    get document(): SpreadsheetDocument;
+    set document(doc: SpreadsheetDocument);
+    private get spills();
+    private get spilledBy();
+    private get spillCells();
+    private cfEngine;
+    private cfDirty;
+    private cfIncremental;
+    private valueOverride;
+    private circlesShown;
+    private invalidCircles;
+    /** Invalid input waiting for the user's answer (see `resolveValidationPrompt`). */
+    validationPrompt: SpreadsheetValidationPrompt | null;
+    constructor(options?: SpreadsheetControllerOptions);
+    private get boundRuntime();
+    /** Runs `fn` with `rt` as the sheet `this.document` (and spills) refer to. */
+    private withSheet;
+    /**
+     * Runs `fn` on the sheet named `sheet` (a sheet-qualified reference), or
+     * on the current sheet when undefined. `#REF!` when no sheet has that name.
+     */
+    private onSheet;
+    private findRuntimeByName;
+    private findRuntimeById;
+    /** A sheet by id or name. */
+    private findRuntime;
+    /** Dependency-graph key of a cell (`A1`) on a sheet: sheet-qualified, so keys are unique in the workbook. */
+    private qualify;
+    /** The sheet and A1 key of a qualified key. */
+    private unqualify;
+    private resolveSheetSpan;
+    /** The defined name `name` visible from `rt`: its sheet-scoped name first, then the workbook one. */
+    private findName;
+    private resolveDefinedName;
+    /**
+     * Replaces the active sheet with `document` (its name becomes the sheet's
+     * name, made unique). Clears undo history.
+     */
+    loadDocument(document: SpreadsheetDocument): void;
+    /** A deep copy of the workbook: every sheet, the active sheet and the defined names. */
+    getWorkbook(): SpreadsheetWorkbook;
+    /** Replaces the whole workbook (sheets, names, active sheet). Clears undo history. */
+    loadWorkbook(workbook: SpreadsheetWorkbook): void;
+    private workbookSnapshot;
+    /**
+     * Installs a workbook's sheets and names (taking ownership of the objects).
+     * Duplicate sheet ids and names are made unique.
+     */
+    private setWorkbookState;
+    /**
+     * Re-parses the value of every stored typed (non-formula) cell from its
+     * `raw` input, so documents saved before typed input was parsed (whose
+     * values are text such as `"120"`) compare and sort as numbers. Cells of
+     * bound columns in record rows keep their value: it belongs to the data
+     * source.
+     */
+    private rederiveTypedValues;
+    /**
+     * Value of typed (non-formula) input: a number, boolean, ISO date, error
+     * or text (see `parseCellInput`), its automatic number format, and the
+     * `CellFormat` to use: the automatic one (currency, percentage, date,
+     * number) when `format` is unset or `text` (the default of new columns).
+     */
+    private typedCell;
+    /**
+     * The number format a cell keeps whatever is typed into it: its explicit
+     * one, else its column's. Undefined lets typed input choose one.
+     */
+    private fixedNumberFormat;
+    /** `numberFormat` / `explicitNumberFormat` fields for a formula, bound or spilled cell. */
+    private fixedNumberFormatFields;
+    /**
+     * Typed input for a bound field, coerced by the field's declared type:
+     * number, boolean and date fields get a number, boolean or ISO date when
+     * the input parses as one; string and enum fields (and unknown fields)
+     * keep the text exactly as typed.
+     */
+    private boundInputValue;
+    registerDataSource(ds: SpreadsheetDataSource): void;
+    setPrimaryDataSource(dataSourceId: string | undefined): void;
+    syncWithDataSource(): void;
+    private recomputeRowIndices;
+    getColumn(colIdOrKey: string): SpreadsheetColumn | undefined;
+    getRow(rowIdOrIndex: string | number): SpreadsheetRow | undefined;
+    /** The row with this id on the current sheet (constant time, see `PositionCache`). */
+    private findRow;
+    /** The column with this id on the current sheet. */
+    private findColumn;
+    /** The column whose key is `key` (`A`, `B`, …): keys follow column positions. */
+    private columnByKey;
+    getCell(rowId: string, colId: string): CellData;
+    /** `getCell` for a row and column already looked up. */
+    private cellOf;
+    /** A cell with no value of its own: derived (bound, column formula, blank), keeping an explicit number format. */
+    private finishCell;
+    /** Value of a cell with no stored data: bound record value, column formula, or blank. */
+    private getDerivedCell;
+    setCellValue(rowId: string, colId: string, raw: string): void;
+    private getCellKey;
+    /**
+     * Recalculates a cell and everything that depends on it, in dependency
+     * order. Every cell in a reference cycle is marked `#CYCLE!`.
+     */
+    recalculateCell(rowId: string, colId: string): void;
+    /**
+     * Registers the dependencies of the formula in `cellKey` (A1 key on the
+     * current sheet), or removes them when `formula` is null: its references
+     * (sheet-qualified ones on their sheet, 3-D ones on every sheet of the
+     * span) and, through defined names, the cells those names refer to.
+     */
+    private registerFormula;
+    /**
+     * Spill edges made stale by new input in `cellKey`: the edges of the array
+     * it anchored (its new formula re-spills when evaluated; spill changes
+     * are recalculated in a further pass) and, when it now holds input, its
+     * edge to the anchor whose values it held. Left in place they can close
+     * false cycles with the new formulas before the anchors are evaluated.
+     */
+    private dropStaleSpillEdges;
+    /**
+     * The parsed formula, shared by dependency registration and evaluation (so
+     * a load parses each formula once). ASTs are never mutated.
+     */
+    private parseCached;
+    /**
+     * Adds the qualified keys `ast` depends on, with unqualified references on
+     * `home`: cells, and ranges kept whole (`SHEETID!A1:A50000`), which the
+     * graph indexes as intervals instead of one key per cell. Sets
+     * `volatile.found` when a volatile function (NOW, RAND, …) is used,
+     * directly or through a defined name.
+     */
+    private collectDependencies;
+    /**
+     * Recalculates `keys` (and, with `includeDependents`, their dependents) in
+     * dependency order. Spill ranges are only known after evaluating their
+     * anchors, so when a pass changes which cells hold spilled values (and so
+     * the dependency graph), the dependents of those cells are recalculated in
+     * another pass, until nothing changes.
+     */
+    private recalculateKeys;
+    /**
+     * Recalculates cells of the current sheet whose stored input changed (their
+     * formulas already registered), with their dependents, in one plan.
+     */
+    private recalculateWrittenCells;
+    /**
+     * Work done by the last recalculation (an edit, paste, import, load or
+     * full recalculation): formulas evaluated, cells planned (formulas, their
+     * dependents and spilled cells) and passes (more than one when spill
+     * ranges changed). Deterministic, unlike timings: use it to check that an
+     * edit only recalculates what depends on it.
+     */
+    getRecalculationStats(): SpreadsheetRecalculationStats;
+    /**
+     * Rebuilds the dependency graph from scratch and recalculates every formula
+     * in dependency order.
+     */
+    recalculateAll(): void;
+    private runEvaluationPlan;
+    /**
+     * Drops cached ranges of `sheetId` that cover column `col` (whose cell was
+     * just evaluated), or all of the sheet's when `col` is null (spilled
+     * values moved or changed).
+     */
+    private invalidateRangeCache;
+    private locateCellKey;
+    private markCycle;
+    private evalSingleCellByKey;
+    /**
+     * Spills `array` from the anchor at (row, col) into the cells below and to
+     * the right. Returns why it can't (the anchor then shows `#SPILL!`), or
+     * null once placed. The grid never grows to fit an array, as in Excel.
+     */
+    private placeSpill;
+    /** Removes the array spilled from `anchor`. With `keepEdges`, its dependency edges stay. */
+    private clearSpill;
+    private forgetSpilledCell;
+    private resolveSpillByCoord;
+    private toSpill;
+    /**
+     * The dynamic array covering (row, col), whether it is the anchor (the cell
+     * holding the formula) or a spilled cell; null when there is none.
+     */
+    getSpillAt(row: number, col: number): SpreadsheetSpill | null;
+    /** Every dynamic array currently spilled. */
+    getSpills(): SpreadsheetSpill[];
+    /** Whether `range` overlaps a spilled array (its anchor or spilled cells). */
+    private intersectsSpill;
+    private resolveCellByCoord;
+    /**
+     * Values of a range, column by column. With `skipBlanks` (functions that
+     * ignore blank cells: SUM, COUNT, AVERAGE, …) blank cells are left out, so
+     * a sparse column costs one lookup per row and no array slot.
+     */
+    private resolveRangeByCoords;
+    private resolveCurrentRowProperty;
+    selectCell(row: number, col: number, extendSelection?: boolean): void;
+    selectRange(range: CellRange): void;
+    startEditing(row?: number, col?: number, initialValue?: string): void;
+    /**
+     * Commits the cell editor's draft (or `valueToCommit`). Input that breaks
+     * the cell's data validation is not committed: the editor stays open and
+     * `validationPrompt` holds the alert until `resolveValidationPrompt`.
+     * Unchanged input is not validated.
+     */
+    commitEditing(valueToCommit?: string): SpreadsheetCommitResult;
+    /**
+     * Commits typed input to a cell (e.g. from the formula bar or a list
+     * dropdown) with data validation, like `commitEditing` without an open
+     * editor. `setCellValue` never validates (paste, import and code bypass
+     * validation, as in Excel).
+     */
+    commitCellInput(rowId: string, colId: string, raw: string): SpreadsheetCommitResult;
+    /** Validates input; when it fails, records and returns the prompt. */
+    private checkInput;
+    /**
+     * Answers `validationPrompt`: `accept` keeps the input (warning and
+     * information alerts only; for a stop alert it acts as `retry`), `retry`
+     * returns to editing it, `cancel` discards it.
+     */
+    resolveValidationPrompt(action: SpreadsheetValidationAction): void;
+    cancelEditing(): void;
+    moveCursor(direction: 'up' | 'down' | 'left' | 'right', extendSelection?: boolean): void;
+    insertColumn(index: number, config?: Partial<SpreadsheetColumn>): void;
+    deleteColumn(colId: string): void;
+    insertRow(index: number, config?: Partial<SpreadsheetRow>): void;
+    deleteRow(rowId: string): void;
+    private generateId;
+    /**
+     * Rewrites references in every cell formula (and, for column changes, every
+     * column formula) so they keep pointing at the same cells.
+     */
+    private shiftReferences;
+    /** Filter for references, in formulas on sheet `on`, that point at sheet `target`. */
+    private referencesTo;
+    setColumnWidth(colId: string, width: number): void;
+    autoFitColumnWidth(colId: string, customWidth?: number): void;
+    /**
+     * Exports cell values as TSV: the whole sheet, or only `range` (e.g. the
+     * current selection) when given.
+     */
+    exportToTsv(range?: CellRange | null): string;
+    /**
+     * Pastes tab-separated values starting at (startRow, startCol), adding rows
+     * and columns as needed. The whole paste is a single undo step.
+     */
+    importFromTsv(tsvData: string, startRow?: number, startCol?: number): void;
+    /** Adds rows/columns at the end until (rowIndex, colIndex) exists. */
+    private growGrid;
+    /**
+     * Writes raw inputs starting at (startRow, startCol), growing the grid as
+     * needed, as a single undo step with one recalculation.
+     */
+    private writeMatrix;
+    /**
+     * Runs `fn` as one undo step: cell writes inside it are batched and
+     * recalculated once, then listeners are notified.
+     */
+    private runBatch;
+    /**
+     * Exports the sheet (or `range`) as RFC 4180 CSV. Values are exported as
+     * displayed unless `formulas` is set.
+     */
+    exportToCsv(options?: CsvExportOptions): string;
+    /**
+     * Imports CSV text at (startRow, startCol) (default A1), growing the grid
+     * as needed. The whole import is a single undo step.
+     */
+    importFromCsv(csv: string, options?: CsvImportOptions): void;
+    /** Runs `fn` on the sheet `sheet` (id or name), default the active one. Throws for an unknown sheet. */
+    private onTargetSheet;
+    /**
+     * Writes already-parsed rows of raw inputs (e.g. from an import adapter)
+     * starting at (startRow, startCol), as a single undo step.
+     */
+    importRows(rows: string[][], options?: Omit<CsvImportOptions, 'delimiter'>): void;
+    /** The cells of `range` (or the whole sheet), row by row. */
+    private readMatrix;
+    /**
+     * Builds clipboard data for `range` (default: the selection) as TSV,
+     * an HTML table and the lossless internal JSON format. Write every entry
+     * with `clipboardData.setData(type, data)` in a `copy` event.
+     */
+    copyToClipboardData(range?: CellRange | null): SpreadsheetClipboardData;
+    /**
+     * Pastes clipboard data at `target` (default: the selection's top-left).
+     * Prefers the internal format (formulas re-based to the target), then an
+     * HTML table, then TSV. Returns false when there was nothing to paste.
+     */
+    pasteClipboardData(source: SpreadsheetClipboardSource, target?: CellPosition): boolean;
+    private spillAnchorInRange;
+    private getSelectionTopLeft;
+    /** The table settings object, created on first use. */
+    private get table();
+    /** Records an undo step, applies `fn`, then notifies listeners. */
+    private applyTableChange;
+    /** First and last (inclusive) body row: rows between header and footer rows. */
+    private getBodyRowBounds;
+    private getCellValueAt;
+    /** Rewrites every formula so references follow cells that moved. */
+    private remapAllFormulas;
+    /**
+     * Keeps merges in place when rows/columns are inserted or deleted:
+     * merges after the change shift, merges across it grow or shrink, and
+     * merges reduced to a single cell are dropped.
+     */
+    private adjustTableForStructuralChange;
+    /**
+     * Sorts rows by one or more columns (stable; numbers before text, blanks
+     * last). Without a range (or with a range spanning every column) whole rows
+     * move; with a range only the cells inside it move. Header and footer rows
+     * never move. References follow the moved cells. Returns false when the
+     * sort is rejected (no valid keys, a key outside the range, or merged
+     * cells in the sorted area).
+     */
+    sortRows(keys: SortKey[], options?: {
+        range?: CellRange | null;
+    }): boolean;
+    getFilterState(): SpreadsheetFilterState;
+    /** Replaces all filter rules (and turns filters on when there are any). */
+    setFilterRules(rules: NewFilterRule[]): void;
+    /** Adds a filter rule (AND-combined with the others) and turns filters on. Returns its id. */
+    addFilterRule(rule: NewFilterRule): string;
+    updateFilterRule(ruleId: string, changes: Partial<Omit<FilterRule, 'id'>>): void;
+    removeFilterRule(ruleId: string): void;
+    clearFilters(): void;
+    /** Turns filtering on or off, keeping the rules. */
+    setFiltersEnabled(enabled: boolean): void;
+    toggleFilters(): void;
+    private generateFilterId;
+    setHeaderRowCount(count: number): void;
+    setFooterRowCount(count: number): void;
+    setHeaderColumnCount(count: number): void;
+    /** Keeps the first `count` rows visible while scrolling. 0 unfreezes. */
+    setFrozenRowCount(count: number): void;
+    /** Keeps the first `count` columns visible while scrolling. 0 unfreezes. */
+    setFrozenColumnCount(count: number): void;
+    private setTableCount;
+    /**
+     * Sets an explicit number format code (e.g. `0.00`, `"$"#,##0.00`,
+     * `m/d/yyyy`, `[Red]0;[Blue]-0`) on every cell in `range`, including blank
+     * cells, so values typed later keep it. `null` removes explicit formats: the
+     * cells go back to their column's format or the one chosen for typed input.
+     * Undoable as one step. Returns false when there is no range.
+     */
+    setCellNumberFormat(range: CellRange | null, code: string | null): boolean;
+    /**
+     * Sets the number format code of a column (`null` or `General` clears it).
+     * Its cells without an explicit format of their own use it, including
+     * values typed later; when cleared they go back to the format chosen for
+     * typed input. Undoable.
+     */
+    setColumnNumberFormat(colId: string, code: string | null): void;
+    /** The column's format, or the one typed input chose (typed cells only). */
+    private implicitNumberFormat;
+    /** A copy of `cell` with `numberFormat` set, or removed when undefined. */
+    private withNumberFormat;
+    /** Re-applies the stored cell's (or the column's) format to a spilled value shown there. */
+    private refreshSpilledNumberFormat;
+    hideRows(indices: number[]): void;
+    unhideRows(indices: number[]): void;
+    hideColumns(indices: number[]): void;
+    unhideColumns(indices: number[]): void;
+    /** Unhides every hidden row and column (filters are unaffected). */
+    unhideAll(): void;
+    private setHidden;
+    getMerges(): CellRange[];
+    /** The merge containing (row, col), or null. */
+    getMergeAt(row: number, col: number): CellRange | null;
+    /** Grows `range` until no merge crosses its edge. Keeps the drag direction. */
+    expandRangeToMerges(range: CellRange): CellRange;
+    /**
+     * Merges `range` (default: the selection) into one cell anchored on its
+     * top-left cell; the other cells are cleared. Merges fully inside the range
+     * are absorbed. Returns false for single cells and for ranges that
+     * partially overlap an existing merge.
+     */
+    mergeCells(range?: CellRange | null): boolean;
+    /** Removes every merge intersecting `range` (default: the selection). */
+    unmergeCells(range?: CellRange | null): boolean;
+    /**
+     * Fills `target` from `source` like dragging the fill handle. `target` is
+     * the extended range (source included) and must extend `source` down, up,
+     * right or left. Numbers and dates continue their series, text ending in a
+     * number counts up, other text repeats, and formulas are copied with
+     * their relative references shifted (`$` parts stay). Returns false when
+     * the ranges don't line up.
+     */
+    autofill(source: CellRange, target: CellRange): boolean;
+    /**
+     * Groups body rows by the value in `colId`, with optional per-group
+     * summaries (e.g. `[{ colId, aggregate: 'sum' }]`).
+     */
+    groupRowsBy(colId: string, summaries?: GroupSummary[]): void;
+    ungroupRows(): void;
+    /** Sets (or with `null`, removes) the group summary for a column. */
+    setGroupSummary(colId: string, aggregate: GroupAggregate | null): void;
+    setGroupCollapsed(key: string, collapsed: boolean): void;
+    toggleGroupCollapsed(key: string): void;
+    /** The current row groups with their summaries (empty when not grouped). */
+    getGroups(): SpreadsheetRowGroup[];
+    /**
+     * Transposes `range` (default: the selection) in place around its top-left
+     * cell: rows become columns. Cells left uncovered are cleared, the grid
+     * grows if needed, and references follow the moved cells. Returns false
+     * for single cells or when merged cells are involved.
+     */
+    transposeRange(range?: CellRange | null): boolean;
+    /**
+     * What to render: visible rows (with group headers) and columns in display
+     * order, frozen offsets and merged-cell spans. Filters, hidden rows/columns
+     * and collapsed groups only affect this view, never the document.
+     */
+    getViewModel(): SpreadsheetViewModel;
+    /** The sheets in tab order. */
+    getSheets(): SpreadsheetSheetInfo[];
+    /** Id of the active sheet (the one `document` is). */
+    get activeSheetId(): string;
+    /** A sheet's document by id or name (live: don't mutate it directly). */
+    getSheetDocument(idOrName: string): SpreadsheetDocument | undefined;
+    /** Why `name` can't name a sheet (or null): see `validateSheetName`. `exceptSheet` is the sheet being renamed. */
+    validateSheetName(name: string, exceptSheet?: string): string | null;
+    /**
+     * Shows another sheet (by id or name). The current edit is committed and
+     * each sheet keeps its own selection. Returns false for an unknown sheet.
+     */
+    setActiveSheet(idOrName: string): boolean;
+    private activateRuntime;
+    /**
+     * Adds a sheet (default: `Sheet N`, empty, after the last sheet) and
+     * activates it unless `activate` is false. Returns its id. Throws when
+     * `name` is invalid or taken. Undoable.
+     */
+    addSheet(options?: {
+        name?: string;
+        index?: number;
+        document?: Partial<SpreadsheetDocument>;
+        activate?: boolean;
+    }): string;
+    /**
+     * Renames a sheet. Formulas on every sheet and defined names that refer to
+     * it follow (`=Old!A1` becomes `='New Name'!A1`). Throws when the name is
+     * invalid or taken. Undoable.
+     */
+    renameSheet(idOrName: string, newName: string): void;
+    /** Moves a sheet to position `toIndex` in tab order. Returns false for an unknown sheet. Undoable. */
+    moveSheet(idOrName: string, toIndex: number): boolean;
+    /**
+     * Deletes a sheet and its sheet-scoped names. References to it become
+     * `#REF!` (a 3-D reference losing an end sheet shrinks). The last sheet
+     * can't be deleted (returns false). Undoable.
+     */
+    deleteSheet(idOrName: string): boolean;
+    /**
+     * Copies a sheet (default name `Name (2)`, placed after it) with its
+     * sheet-scoped names, which refer to the copy. Activates the copy unless
+     * `activate` is false. Returns the new sheet's id, or null for an unknown
+     * sheet. Undoable.
+     */
+    duplicateSheet(idOrName: string, options?: {
+        name?: string;
+        index?: number;
+        activate?: boolean;
+    }): string | null;
+    /** Applies `rewrite` to every formula: cells and column formulas on every sheet, and defined names. */
+    private rewriteAllFormulas;
+    private generateSheetId;
+    /** Every defined name, workbook-scoped and sheet-scoped. */
+    getNames(): SpreadsheetNameInfo[];
+    /** The defined name `name` visible from the active sheet (its own sheet-scoped name first), or undefined. */
+    getName(name: string, scope?: SpreadsheetNameScope): SpreadsheetNameInfo | undefined;
+    /** Why `name` can't be a defined name (or null): see `validateDefinedName`. */
+    validateDefinedName(name: string): string | null;
+    private scopeRuntime;
+    /**
+     * Defines (or redefines) a name in the workbook, or on one sheet with
+     * `sheet`. `refersTo` is a formula: a range (`=Data!$A$2:$A$20`), a
+     * constant (`=0.07`), a formula or a LAMBDA (`=LAMBDA(x, x*2)`, called as
+     * `=Double(4)`). Formulas using the name recalculate. Throws when the name
+     * is invalid or the formula can't be read. Undoable.
+     */
+    defineName(name: string, refersTo: string, options?: SpreadsheetNameScope & {
+        comment?: string;
+    }): void;
+    /**
+     * Renames a defined name. Formulas that use it (cells, column formulas and
+     * other names) follow, on the sheets where the old name meant this one.
+     * Throws when the name doesn't exist or the new name is invalid or taken.
+     * Undoable.
+     */
+    renameName(oldName: string, newName: string, options?: SpreadsheetNameScope): void;
+    /**
+     * Deletes a defined name. Formulas still using it show `#NAME?`. Returns
+     * false when there is no such name. Undoable.
+     */
+    deleteName(name: string, options?: SpreadsheetNameScope): boolean;
+    /**
+     * Names formula autocomplete can offer on the active sheet: its
+     * sheet-scoped names and the workbook names they don't hide.
+     */
+    getNameSuggestions(): Array<{
+        name: string;
+        description: string;
+        isLambda: boolean;
+    }>;
+    /**
+     * Evaluates a formula (e.g. `=Rate*2`, `=SUM(Sales)`) as if it were in a
+     * cell of `sheet` (id or name; default the active sheet), without storing
+     * it. Used by the Name Manager to show a name's current value.
+     */
+    evaluateFormula(formula: string, options?: {
+        sheet?: string;
+    }): FormulaEvaluationResult;
+    private recordSnapshot;
+    /** Records the stored state of one cell, for undoing a single-cell edit. */
+    private recordCellSnapshot;
+    private cellHistory;
+    private recordWorkbookSnapshot;
+    private pushUndo;
+    /** Drops the oldest snapshots beyond `maxHistoryBytes`, always keeping the newest. */
+    private trimHistory;
+    /** Approximate bytes held by the undo/redo snapshots (UTF-16 size). */
+    getHistoryByteSize(): number;
+    /** Number of undo / redo snapshots currently held. */
+    getHistoryDepth(): {
+        undo: number;
+        redo: number;
+    };
+    undo(): void;
+    redo(): void;
+    /** Restores the newest entry of `from`, saving the current state of the same scope on `to`. */
+    private applyHistory;
+    private notifyChange;
+    /** The sheet as rule evaluation sees it. */
+    private ruleSheet;
+    /**
+     * Evaluates `formula` as if it were in (row, col), without storing it:
+     * relative references and `[property]` resolve from that cell. With
+     * `entered`, that cell reads as the given value (input being validated).
+     * Returns the value, or an array's values (column-major) for a range.
+     */
+    evaluateFormulaAt(formula: string, row: number, col: number, entered?: {
+        row: number;
+        col: number;
+        value: unknown;
+    }): unknown;
+    /** Records that the value of `cellKey` (and of the array it spills) may have changed. */
+    private markValueChanged;
+    private generateRuleId;
+    /** Moves rule ranges and rule formulas with inserted / deleted rows and columns. */
+    private adjustRulesForStructuralChange;
+    /** Conditional formats of the sheet, highest priority first. */
+    getConditionalFormats(): ConditionalFormatRule[];
+    /**
+     * Adds a conditional format (one undo step). New rules get the highest
+     * priority, as in Excel; pass `priority: 'last'` to add it below the
+     * others. Returns the rule id.
+     */
+    addConditionalFormat(rule: NewConditionalFormatRule, options?: {
+        priority?: 'first' | 'last';
+    }): string;
+    /** Changes a conditional format (its condition, ranges or stop-if-true). Returns false when not found. */
+    updateConditionalFormat(id: string, changes: Partial<NewConditionalFormatRule>): boolean;
+    /** Removes a conditional format. Returns false when not found. */
+    deleteConditionalFormat(id: string): boolean;
+    /**
+     * Moves a conditional format to priority `to` (0 = highest), or by
+     * `{ by: -1 }` (up) / `{ by: 1 }` (down). Returns false when nothing moved.
+     */
+    moveConditionalFormat(id: string, to: number | {
+        by: number;
+    }): boolean;
+    /**
+     * Removes conditional formatting from the cells of `range` (rules keep
+     * their other cells; rules left without cells are deleted), or every rule
+     * when `range` is null.
+     */
+    clearConditionalFormats(range?: CellRange | null): void;
+    /**
+     * The conditional look of every formatted cell. Evaluated on demand and
+     * cached: after a cell edit only the affected cells are re-evaluated.
+     */
+    getConditionalFormatOverlay(): ConditionalFormatOverlay;
+    /** The conditional look of (row, col), if any. */
+    getConditionalFormat(row: number, col: number): ConditionalCellFormat | undefined;
+    /** Data validation rules of the sheet. */
+    getDataValidations(): DataValidationRule[];
+    /** The rule that applies to (row, col), if any. */
+    getDataValidationAt(row: number, col: number): DataValidationRule | undefined;
+    /**
+     * Adds a data validation rule (one undo step). Its cells are first
+     * removed from other rules, so each cell has at most one. Returns the id.
+     */
+    addDataValidation(rule: NewDataValidationRule): string;
+    /** Changes a data validation rule. Returns false when not found. */
+    updateDataValidation(id: string, changes: Partial<NewDataValidationRule>): boolean;
+    /** Removes a data validation rule. Returns false when not found. */
+    deleteDataValidation(id: string): boolean;
+    /** Removes validation from the cells of `range`, or every rule when `range` is null. */
+    clearDataValidation(range?: CellRange | null): void;
+    /** Checks input for (row, col) against its data validation, without committing it. */
+    validateCellInput(row: number, col: number, raw: string): DataValidationResult;
+    /**
+     * Dropdown items of a list-validated cell, or null when the cell has no
+     * list rule (or its in-cell dropdown is off).
+     */
+    getValidationListValues(row: number, col: number): string[] | null;
+    /** Cells whose current value breaks their validation rule. */
+    findInvalidCells(): CellPosition[];
+    /**
+     * Turns "circle invalid data" on or off. View state, not part of the
+     * document (not undoable, not saved); listeners are notified so the grid
+     * redraws.
+     */
+    setInvalidDataCircles(show: boolean): void;
+    /** Whether invalid cells are circled. */
+    getInvalidDataCircles(): boolean;
+    /** Whether (row, col) is circled as invalid (always false while circles are off). */
+    isInvalidDataCircled(row: number, col: number): boolean;
+}
+
+export { type GroupAggregate as $, type ASTNode as A, type BinaryOpNode as B, type CellCoordinate as C, DEFAULT_COLUMN_WIDTH as D, type DataValidationResult as E, type DataValidationRule as F, type DataValidationSheet as G, type DataValidationType as H, DependencyGraph as I, type DependencyIndexStats as J, type EvaluationContext as K, FORMULA_ERRORS as L, type FilterOperator as M, type FilterRule as N, type FormulaDiagnostic as O, type FormulaErrorCode as P, type FormulaEvaluationResult as Q, FormulaEvaluator as R, SpreadsheetController as S, type FormulaNameDefinition as T, FormulaParser as U, type FormulaRange as V, type FormulaReferenceFilter as W, type FormulaReferenceInfo as X, type FormulaToken as Y, type FormulaTokenType as Z, type FunctionCallNode as _, type CellData as a, extractCellDependencies as a$, type GroupSummary as a0, IntervalIndex as a1, type InvokeNode as a2, type LiteralNode as a3, MAX_FORMULA_ARRAY_SIZE as a4, type MissingNode as a5, type NameDep as a6, type NameNode as a7, type NewConditionalFormatRule as a8, type NewDataValidationRule as a9, type SpreadsheetNameInfo as aA, type SpreadsheetNameScope as aB, type SpreadsheetRecalculationStats as aC, type SpreadsheetRow as aD, type SpreadsheetRowGroup as aE, type SpreadsheetRowSection as aF, type SpreadsheetSheetInfo as aG, type SpreadsheetSpill as aH, type SpreadsheetTableSettings as aI, type SpreadsheetValidationAction as aJ, type SpreadsheetValidationPrompt as aK, type SpreadsheetViewColumn as aL, type SpreadsheetViewModel as aM, type SpreadsheetViewRow as aN, type SpreadsheetWorkbook as aO, type StructuralChange as aP, type UnaryOpNode as aQ, WHOLE_COLUMN_END_ROW as aR, buildSpreadsheetView as aS, colNameToIndex as aT, columnDependencyKey as aU, compareNumbers as aV, compareValues as aW, computeRowGroups as aX, createSpreadsheetClipboardData as aY, deleteSheetInFormula as aZ, describeFormulaError as a_, type NewFilterRule as aa, type ParsedSpreadsheetClipboard as ab, type PropertyRefNode as ac, type RangeNode as ad, type RangeResolveOptions as ae, type ReferenceDep as af, type RowType as ag, SPREADSHEET_CLIPBOARD_MIME as ah, type SheetQualifier as ai, type SortDirection as aj, type SortKey as ak, type SpillRefNode as al, type SpreadsheetCellSpan as am, type SpreadsheetClipboardCell as an, type SpreadsheetClipboardData as ao, type SpreadsheetClipboardPayload as ap, type SpreadsheetClipboardSource as aq, type SpreadsheetColumn as ar, type SpreadsheetCommitResult as as, type SpreadsheetControllerOptions as at, type SpreadsheetDataSource as au, type SpreadsheetDataSourceField as av, type SpreadsheetDefinedName as aw, type SpreadsheetDocument as ax, type SpreadsheetFilterState as ay, type SpreadsheetGrouping as az, type CellDep as b, extractNameDependencies as b0, extractReferenceDependencies as b1, formatSheetPrefix as b2, formulaIdentifiers as b3, getRowSection as b4, getTableSections as b5, indexToColName as b6, isFormulaError as b7, mapFormulaReferences as b8, numberToText as b9, offsetFormulaReferences as ba, parseCellReference as bb, parseFormula as bc, parseHtmlTable as bd, parseRange as be, quoteSheetName as bf, rangeDependencyKey as bg, readSpreadsheetClipboard as bh, rebaseClipboardRows as bi, remapFormulaReferences as bj, renameNameInFormula as bk, renameSheetInFormula as bl, rowPassesFilters as bm, serializeHtmlTable as bn, sheetNameNeedsQuotes as bo, shiftFormulaReferences as bp, sortCompareValues as bq, tokenizeFormula as br, type CellFormat as c, type CellPosition as d, type CellRange as e, type CellRefNode as f, type CellValueReader as g, type ColumnBinding as h, type ColumnType as i, type ConditionalCellFormat as j, type ConditionalFormatCondition as k, type ConditionalFormatIconSet as l, type ConditionalFormatOperator as m, type ConditionalFormatOverlay as n, type ConditionalFormatRule as o, type ConditionalFormatSheet as p, type ConditionalFormatStyle as q, type ConditionalFormatTimePeriod as r, type ConditionalFormatType as s, type ConditionalFormatValue as t, type CsvExportOptions as u, type CsvImportOptions as v, DEFAULT_ROW_HEIGHT as w, DataSourceBinder as x, type DataValidationErrorStyle as y, type DataValidationOperator as z };