@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/cells/cell-identity.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Cell Identity Model Types
+ *
+ * This module defines the types for the cell identity model, which replaces
+ * A1-style positional references with stable cell identity references.
+ *
+ * Key insight: In the identity model, cell movement is tracked by updating
+ * position data, not by rewriting formula strings. This eliminates O(n)
+ * formula rewrites on structure changes and makes concurrent structure
+ * changes compose correctly under CRDT.
+ *
+ * This is the same approach Google Sheets uses internally.
+ *
+ * @see plans/cell-ids/CELL-IDENTITY-MODEL.md
+ */
+import type { SheetId } from '../core/core';
+/**
+ * Stable cell identifier - never changes even when cell moves.
+ *
+ * We use UUID v7 (time-sortable) for:
+ * - Uniqueness across clients (no coordination needed)
+ * - Time-sortability for debugging
+ * - Compact string representation
+ */
+export type CellId = string;
+/**
+ * Stable row identifier - never changes even when rows are inserted/deleted.
+ *
+ * Follows the same pattern as CellId:
+ * - UUID v7 (time-sortable)
+ * - Position stored in RowData, not as key
+ * - Enables CRDT-safe row format storage
+ *
+ * @see plans/active/refactor/ROW-COLUMN-IDENTITY.md
+ */
+export type RowId = string;
+/**
+ * Row data stored in the rows map.
+ *
+ * Contains the current position of the row. Position is mutable and updated
+ * during structure changes (insert/delete rows). The RowId key is stable.
+ *
+ * Future extensibility: hidden, groupLevel, outlineState, etc.
+ */
+export interface RowData {
+    /** Current zero-based row position (mutable on structure changes) */
+    position: number;
+}
+/**
+ * Stable column identifier - never changes even when columns are inserted/deleted.
+ *
+ * Follows the same pattern as CellId:
+ * - UUID v7 (time-sortable)
+ * - Position stored in ColData, not as key
+ * - Enables CRDT-safe column format storage
+ *
+ * @see plans/active/refactor/ROW-COLUMN-IDENTITY.md
+ */
+export type ColId = string;
+/**
+ * Column data stored in the cols map.
+ *
+ * Contains the current position of the column. Position is mutable and updated
+ * during structure changes (insert/delete columns). The ColId key is stable.
+ *
+ * Future extensibility: hidden, groupLevel, outlineState, etc.
+ */
+export interface ColData {
+    /** Current zero-based column position (mutable on structure changes) */
+    position: number;
+}
+/**
+ * Reference to a cell by identity (for formula storage).
+ *
+ * Note: These types are prefixed with `Identity` to distinguish them from the
+ * existing position-based `CellRef`/`RangeRef` in `range-ref.ts` which are
+ * used for data validation, copy/paste, and other positional operations.
+ *
+ * The absolute flags preserve user intent for A1 display:
+ * - $A$1 = both absolute (display stays fixed even if cell moves)
+ * - $A1 = column absolute (for column references in formulas)
+ * - A$1 = row absolute (for row references in formulas)
+ * - A1 = both relative (display adjusts when viewing formula moves)
+ */
+export interface IdentityCellRef {
+    type: 'cell';
+    /** The stable cell identity */
+    id: CellId;
+    /** True for $1 syntax (row absolute for display) */
+    rowAbsolute: boolean;
+    /** True for $A syntax (column absolute for display) */
+    colAbsolute: boolean;
+}
+/**
+ * Reference to a range by corner cell identities (for formula storage).
+ *
+ * Ranges are defined by their corner cells. When rows/columns are inserted
+ * between the corners, the range automatically expands because the corner
+ * cells' positions change.
+ */
+export interface IdentityRangeRef {
+    type: 'range';
+    /** Start cell (top-left corner) identity */
+    startId: CellId;
+    /** End cell (bottom-right corner) identity */
+    endId: CellId;
+    /** Absolute flags for start cell display */
+    startRowAbsolute: boolean;
+    startColAbsolute: boolean;
+    /** Absolute flags for end cell display */
+    endRowAbsolute: boolean;
+    endColAbsolute: boolean;
+}
+/**
+ * Union of identity-based formula references.
+ */
+export type IdentityFormulaRef = IdentityCellRef | IdentityRangeRef;
+/**
+ * Reference to a range by corner cell identities for schema/validation purposes.
+ *
+ * Unlike IdentityRangeRef (used in formulas), this type:
+ * - Has no absolute flags (not needed for validation ranges)
+ * - Supports cross-sheet references via optional sheetId
+ * - Is designed for RangeSchema.ranges and enumSource constraints
+ *
+ * Why this exists:
+ * RangeSchema previously stored A1 strings ("A1:B10") which have the same CRDT
+ * conflict issue as position-based formula refs. By using CellId corner refs,
+ * concurrent structure changes compose correctly.
+ *
+ * @example
+ * // Schema applies to A1:C10
+ * const ref: IdentityRangeSchemaRef = {
+ *   startId: 'abc-123...',  // CellId of A1
+ *   endId: 'def-456...',    // CellId of C10
+ * };
+ *
+ * @example
+ * // enumSource from another sheet
+ * const ref: IdentityRangeSchemaRef = {
+ *   sheetId: 'sheet-2-uuid',
+ *   startId: 'abc-123...',
+ *   endId: 'def-456...',
+ * };
+ */
+export interface IdentityRangeSchemaRef {
+    /**
+     * Optional target sheet ID for cross-sheet references.
+     * - undefined: same sheet as the schema (common case)
+     * - string: specific sheet ID for cross-sheet enumSource
+     */
+    sheetId?: SheetId;
+    /** CellId of the top-left corner cell */
+    startId: CellId;
+    /** CellId of the bottom-right corner cell */
+    endId: CellId;
+}
+/**
+ * A range defined by corner cell identities.
+ *
+ * This is the universal type for CRDT-safe range references used by:
+ * - Charts (data ranges, anchor positions)
+ * - Tables (table extent)
+ * - Grouping (group extent)
+ *
+ * Unlike position-based ranges, CellIdRange automatically handles:
+ * - Concurrent structure changes (insert/delete rows/cols)
+ * - Range expansion when cells inserted between corners
+ * - Correct CRDT composition under concurrent edits
+ *
+ * Position resolution happens at render/extraction time via GridIndex.
+ *
+ * @example
+ * // Chart data range A1:D10
+ * const range: CellIdRange = {
+ *   topLeftCellId: 'abc-123...',     // CellId of A1
+ *   bottomRightCellId: 'def-456...'  // CellId of D10
+ * };
+ *
+ * // After user inserts column at B:
+ * // - CellIds unchanged
+ * // - But A1 is still at (0,0), D10 is now at (9,4)
+ * // - Range automatically covers A1:E10
+ */
+export interface CellIdRange {
+    /** CellId of the top-left corner cell */
+    topLeftCellId: CellId;
+    /** CellId of the bottom-right corner cell */
+    bottomRightCellId: CellId;
+}
+/**
+ * A merged region defined by corner cell identities.
+ *
+ * This follows the same pattern as IdentityRangeRef - merges are defined by
+ * CellId references to corner cells rather than position coordinates. This
+ * ensures concurrent structure changes (insert/delete rows/cols) compose
+ * correctly under CRDT.
+ *
+ * Position-based merges have the same problem as position-based formula refs:
+ * ```
+ * User A: Creates merge at A1:B2
+ * User B: Inserts column at A (concurrent)
+ *
+ * Position-based: Yjs merges two incompatible coordinate sets → wrong result
+ * CellId-based: Both position shifts apply, CellIds stable → correct result
+ * ```
+ *
+ * @example
+ * // User merges A1:C3
+ * const merge: IdentityMergedRegion = {
+ *   topLeftId: 'abc-123...',    // CellId of A1
+ *   bottomRightId: 'def-456...' // CellId of C3
+ * };
+ * // After inserting column at B, the CellIds are unchanged
+ * // but their positions have shifted, so the merge now covers A1:D3
+ */
+export interface IdentityMergedRegion {
+    /** Origin cell - contains the merged value and is the "owner" of the merge */
+    topLeftId: CellId;
+    /** Extent marker - defines bottom-right boundary of the merge */
+    bottomRightId: CellId;
+}
+/**
+ * Formula stored with identity references.
+ *
+ * The template uses numbered placeholders that are filled in by refs.
+ *
+ * @example
+ * User types: =SUM(A1:B10)+C1*2
+ * Stored as:
+ * {
+ *   template: "SUM({0})+{1}*2",
+ *   refs: [
+ *     { type: 'range', startId: 'abc...', endId: 'def...' },
+ *     { type: 'cell', id: 'ghi...' }
+ *   ]
+ * }
+ *
+ * When displaying, we resolve each ref to its current A1 position.
+ */
+export interface IdentityFormula {
+    /**
+     * Template with numbered placeholders for refs.
+     * Example: "SUM({0}:{1})+{2}*2"
+     *
+     * The template preserves the formula structure (function names, operators,
+     * literals) while placeholders mark where cell/range references go.
+     */
+    template: string;
+    /**
+     * Ordered refs that fill template placeholders.
+     * refs[0] fills {0}, refs[1] fills {1}, etc.
+     */
+    refs: IdentityFormulaRef[];
+}
+/**
+ * Interface for formula conversion between A1 and identity formats.
+ *
+ * This interface enables Import/Export to be developed in parallel
+ * with the Formula Parser by mocking this interface.
+ */
+export interface IFormulaConverter {
+    /**
+     * Convert A1-style formula to identity formula.
+     * Called when user types a formula or imports from XLSX.
+     *
+     * @param a1Formula - Formula string with A1 references (e.g., "=SUM(A1:B10)")
+     * @param sheetId - Current sheet for resolving relative references
+     * @returns Identity formula with cell ID references
+     */
+    toIdentity(a1Formula: string, sheetId: SheetId): IdentityFormula;
+    /**
+     * Convert identity formula back to A1-style string.
+     * Called for display in formula bar and export to XLSX.
+     *
+     * @param formula - Identity formula with cell ID references
+     * @returns A1-style formula string (e.g., "=SUM(A1:B10)")
+     */
+    toA1(formula: IdentityFormula): string;
+}
+//# sourceMappingURL=cell-identity.d.ts.map

package/dist/cells/cell-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-identity.d.ts","sourceRoot":"","sources":["../../src/cells/cell-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAM5B;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAMpE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAElB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC5B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC;IAEjE;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC;CACxC"}

package/dist/cells/cell-style.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Cell Text Style - THE CANONICAL SOURCE OF TRUTH
+ *
+ * This module defines how cell text appears. Both canvas rendering and in-cell
+ * editing MUST derive their styling from this module.
+ *
+ * ARCHITECTURAL CONTRACT:
+ * - Canvas renderer uses resolveCellTextStyle() → getCellCanvasFont() adapter
+ * - In-cell editor uses resolveCellTextStyle() → getCellDOMStyle() adapter
+ * - Changes here automatically update both systems
+ *
+ * DO NOT duplicate these values elsewhere. If you need cell styling defaults,
+ * import from this module.
+ *
+ * @see engine/src/canvas/cell-style-adapters.ts for platform-specific adapters
+ */
+/**
+ * Default cell styling values.
+ * These define the contract for how an unformatted cell appears.
+ */
+export declare const DEFAULT_CELL_STYLE: {
+    /** Default font size in pixels */
+    readonly fontSize: 12;
+    /** Default font family stack */
+    readonly fontFamily: "Inter, -apple-system, BlinkMacSystemFont, sans-serif";
+    /** Default font color */
+    readonly fontColor: "#000000";
+    /** Horizontal padding inside cells (pixels) */
+    readonly padding: 4;
+    /** Default horizontal alignment */
+    readonly horizontalAlign: "left";
+    /** Default vertical alignment - matches Excel default ('bottom') */
+    readonly verticalAlign: "bottom";
+    /** Default background (transparent, falls back to surface) */
+    readonly backgroundColor: string | undefined;
+};
+/**
+ * Fully resolved cell text style.
+ *
+ * This is the complete, computed style for rendering cell text.
+ * All optional CellFormat properties are resolved to concrete values.
+ */
+export interface CellTextStyle {
+    /** Horizontal padding in pixels */
+    paddingX: number;
+    /** Font size in pixels */
+    fontSize: number;
+    /** Font family CSS value */
+    fontFamily: string;
+    /** Font weight */
+    fontWeight: 'normal' | 'bold';
+    /** Font style */
+    fontStyle: 'normal' | 'italic';
+    /** Text color */
+    color: string;
+    /** Text decoration (underline, line-through, or both) */
+    textDecoration: string;
+    /** Horizontal text alignment */
+    textAlign: 'left' | 'center' | 'right' | 'justify';
+    /** Vertical text alignment */
+    verticalAlign: 'top' | 'middle' | 'bottom';
+    /** Line height multiplier (1 = tight, matches canvas) */
+    lineHeight: number;
+    /** Background color (undefined = transparent/inherit) */
+    backgroundColor: string | undefined;
+}
+//# sourceMappingURL=cell-style.d.ts.map

package/dist/cells/cell-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-style.d.ts","sourceRoot":"","sources":["../../src/cells/cell-style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC7B,kCAAkC;;IAElC,gCAAgC;;IAEhC,yBAAyB;;IAEzB,+CAA+C;;IAE/C,mCAAmC;;IAEnC,oEAAoE;;IAEpE,8DAA8D;8BAChC,MAAM,GAAG,SAAS;CACxC,CAAC;AAMX;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAE5B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAGjB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC9B,iBAAiB;IACjB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAGnD,8BAA8B;IAC9B,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC3C,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IAGnB,yDAAyD;IACzD,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC"}

package/dist/cells/formula-string.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Branded types for formula strings.
+ *
+ * The spreadsheet engine uses two distinct formula string formats:
+ *
+ * - **FormulaA1**: Has the `=` prefix (`"=SUM(A1:B10)"`).
+ *   Produced by Rust's `to_a1_string()`, returned in `ActiveCellData.formula`.
+ *   Used for: formula bar display, search, sending to Rust's `process_input`.
+ *
+ * - **FormulaTemplate**: No `=` prefix (`"SUM(A1:B10)"`).
+ *   Produced by `IdentityFormula.template`, `CellEdit.formula`.
+ *   Used for: wire format for incremental updates, internal storage.
+ *
+ * These branded types make it a **compile-time error** to pass one where
+ * the other is expected, eliminating the "double-equals" class of bugs.
+ */
+declare const formulaA1Brand: unique symbol;
+declare const formulaTemplateBrand: unique symbol;
+/**
+ * A formula string WITH the `=` prefix: `"=SUM(A1:B10)"`, `"=A1+A2"`.
+ *
+ * This is the display/input format used at the Rust-TS boundary and in the UI.
+ */
+export type FormulaA1 = string & {
+    readonly [formulaA1Brand]: true;
+};
+/**
+ * A formula template WITHOUT the `=` prefix: `"SUM(A1:B10)"`, `"A1+A2"`.
+ *
+ * This is the internal storage format used by `IdentityFormula.template`
+ * and `CellEdit.formula` in the wire protocol.
+ */
+export type FormulaTemplate = string & {
+    readonly [formulaTemplateBrand]: true;
+};
+export {};
+//# sourceMappingURL=formula-string.d.ts.map

package/dist/cells/formula-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formula-string.d.ts","sourceRoot":"","sources":["../../src/cells/formula-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAC5C,OAAO,CAAC,MAAM,oBAAoB,EAAE,OAAO,MAAM,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC"}

package/dist/cells/index.d.ts

@@ -0,0 +1,7 @@
+export * from './cell-identity';
+export * from './cell-style';
+export * from './formula-string';
+export * from './range-ref';
+export * from './rich-text';
+export * from './spill';
+//# sourceMappingURL=index.d.ts.map

package/dist/cells/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cells/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/cells/range-ref.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Range Reference Types
+ *
+ * Structured representations of cell and range references.
+ * Used for parsing, manipulating, and adjusting ranges for:
+ * - RangeSchema.ranges (cells the schema applies to)
+ * - enumSource (dynamic dropdown source)
+ * - Row/column insert/delete operations
+ * - Copy/paste operations
+ */
+/**
+ * Structured representation of a cell reference (e.g., $A$1, B2)
+ */
+export interface CellRef {
+    /** Row index (0-based) */
+    row: number;
+    /** Column index (0-based) */
+    col: number;
+    /** True for absolute row reference ($1) - doesn't shift on insert/delete */
+    rowAbsolute: boolean;
+    /** True for absolute column reference ($A) - doesn't shift on insert/delete */
+    colAbsolute: boolean;
+}
+/**
+ * Structured representation of a range reference (e.g., $A$1:$B$10)
+ */
+export interface RangeRef {
+    /** Start cell (top-left) */
+    start: CellRef;
+    /** End cell (bottom-right) */
+    end: CellRef;
+    /** Sheet name for cross-sheet refs like Sheet2!A1:B10 */
+    sheetName?: string;
+}
+/**
+ * Result of checking if a cell is contained in a range
+ */
+export interface RangeContainsResult {
+    /** Whether the cell is within the range */
+    contains: boolean;
+    /** Position within range, relative to start (for relative refs) */
+    relativeRow?: number;
+    /** Position within range, relative to start (for relative refs) */
+    relativeCol?: number;
+}
+/**
+ * Bounds for viewport queries
+ */
+export interface ViewportBounds {
+    /** Minimum row index (inclusive) */
+    minRow: number;
+    /** Maximum row index (inclusive) */
+    maxRow: number;
+    /** Minimum column index (inclusive) */
+    minCol: number;
+    /** Maximum column index (inclusive) */
+    maxCol: number;
+}
+/**
+ * Spatial index for efficient range lookups.
+ * Avoids O(n) scan of all schemas for every cell query.
+ */
+export interface IRangeSpatialIndex<T> {
+    /**
+     * Get all items whose ranges contain the given cell
+     */
+    getItemsForCell(row: number, col: number): Promise<T[]>;
+    /**
+     * Get all items whose ranges intersect the given viewport
+     */
+    getItemsInViewport(bounds: ViewportBounds): Promise<Map<string, T>>;
+    /**
+     * Rebuild the index (call when ranges change)
+     */
+    rebuild(items: T[]): void;
+}
+//# sourceMappingURL=range-ref.d.ts.map

package/dist/cells/range-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range-ref.d.ts","sourceRoot":"","sources":["../../src/cells/range-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,WAAW,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,4BAA4B;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,GAAG,EAAE,OAAO,CAAC;IACb,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;OAEG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAExD;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpE;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;CAC3B"}

package/dist/cells/rich-text.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Rich Text Types
+ *
+ * Defines the rich text segment model for Excel-compatible rich text support.
+ * Rich text is stored as an array of segments, where each segment has text
+ * and optional formatting.
+ *
+ * Key design decisions:
+ * - Segment array (not formatted string) for clean storage and rendering
+ * - TextFormat matches Excel's inline rich text capabilities
+ * - Runtime utility functions live in utils/rich-text.ts and are re-exported here
+ *
+ * @see STREAM-C3-COMMENTS-RICHTEXT.md
+ */
+/**
+ * Formatting options for a text segment.
+ * Matches Excel's inline rich text capabilities.
+ */
+export interface TextFormat {
+    /** Bold text */
+    bold?: boolean;
+    /** Italic text */
+    italic?: boolean;
+    /** Underline type (single, double, accounting styles) */
+    underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+    /** Strikethrough text */
+    strikethrough?: boolean;
+    /** Font family name (e.g., "Arial", "Calibri") */
+    fontFamily?: string;
+    /** Font size in points */
+    fontSize?: number;
+    /** Font color in hex format (e.g., "#FF0000") */
+    fontColor?: string;
+    /** Superscript text (e.g., for exponents) */
+    superscript?: boolean;
+    /** Subscript text (e.g., for chemical formulas) */
+    subscript?: boolean;
+}
+/**
+ * A segment of rich text with optional formatting.
+ * Rich text is stored as an array of segments.
+ *
+ * @example
+ * // "Hello World" with "World" in bold
+ * [
+ *   { text: "Hello " },
+ *   { text: "World", format: { bold: true } }
+ * ]
+ */
+export interface RichTextSegment {
+    /** The text content of this segment */
+    text: string;
+    /** Optional formatting for this segment */
+    format?: Partial<TextFormat>;
+}
+/**
+ * Type alias for rich text content.
+ * Empty array = no content, single segment with no format = plain text.
+ */
+export type RichText = RichTextSegment[];
+/**
+ * Utility type for cells that can have rich text.
+ * A cell's text content can be either a plain string or rich text.
+ */
+export type CellTextContent = string | RichText;
+//# sourceMappingURL=rich-text.d.ts.map

package/dist/cells/rich-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text.d.ts","sourceRoot":"","sources":["../../src/cells/rich-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;GAGG;AACH,MAAM,WAAW,UAAU;IAEzB,gBAAgB;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kBAAkB;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;IACvF,yBAAyB;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;IAGxB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,CAAC"}

package/dist/cells/spill.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Spill Contracts (Stream AF: Array Formulas)
+ *
+ * Types for dynamic array spill behavior in Excel-compatible spreadsheets.
+ *
+ * ARCHITECTURE:
+ * - Spill occurs when a formula returns a 2D array larger than 1x1
+ * - The anchor cell contains the formula; spill cells show computed values
+ * - Spill cells store `spillAnchor: CellId` pointing to the formula cell
+ * - This enables efficient lookup, proper deletion, and CRDT-safe collaboration
+ *
+ * Excel Compatibility:
+ * - Dynamic arrays spill automatically (Excel 365+)
+ * - Legacy CSE (Ctrl+Shift+Enter) creates fixed-size array formulas
+ * - #SPILL! error when spill range is blocked
+ * - Spill cannot cross sheet boundaries
+ *
+ * @see plans/active/detailed-parity-implementation/STREAM-AF-ARRAY-FORMULAS.md
+ */
+import type { CellRange, CellValue, SheetId } from '../core/core';
+import type { CellId } from './cell-identity';
+/**
+ * Result of evaluating an array-returning formula.
+ *
+ * Produced by the recalculation module when a formula returns CellValue[][].
+ * Used by the spill orchestration layer to determine what to write.
+ */
+export interface SpillResult {
+    /** The cell containing the array formula (anchor) */
+    anchorCellId: CellId;
+    /** Sheet containing the spill */
+    sheetId: SheetId;
+    /** The array values to spill (row-major order) */
+    values: CellValue[][];
+    /** Calculated spill range (anchor cell + extent) */
+    spillRange: CellRange;
+    /** Whether the spill is blocked by existing data */
+    blocked: boolean;
+    /** CellId of the cell blocking the spill, if any */
+    blockingCellId?: CellId;
+}
+/**
+ * Spill range info for a single anchor cell.
+ *
+ * Stored on anchor cells to track their spill extent.
+ * Used for:
+ * - Clearing old spill when formula result changes size
+ * - Detecting when a cell is being entered in a spill range
+ * - Selection highlighting of entire spill range
+ */
+export interface SpillRangeInfo {
+    /** Number of rows the spill occupies (including anchor) */
+    rows: number;
+    /** Number of columns the spill occupies (including anchor) */
+    cols: number;
+}
+/**
+ * Array formula state for legacy CSE formulas.
+ *
+ * CSE (Ctrl+Shift+Enter) creates fixed-size array formulas where:
+ * - User pre-selects the output range
+ * - Formula is stored once on the anchor cell
+ * - All cells in the range are marked as array members
+ * - Size is fixed (does not auto-resize like dynamic arrays)
+ * - Formula bar shows {=formula} with curly braces
+ *
+ * Stored on the anchor cell only. Member cells reference back via spillAnchor.
+ */
+export interface ArrayFormulaState {
+    /** The range this array formula occupies */
+    range: CellRange;
+    /**
+     * Whether this is a legacy CSE formula.
+     * - true: Fixed-size CSE formula (user-selected range)
+     * - false: Dynamic spill formula (auto-sized)
+     */
+    isCSE: boolean;
+}
+/**
+ * Spill error reasons for diagnostics.
+ */
+export type SpillErrorReason = 'blocked' | 'merged' | 'cross_sheet' | 'bounds_overflow' | 'table_overlap' | 'array_overlap';
+/**
+ * Detailed spill error information.
+ *
+ * Provides context for #SPILL! errors to help users understand
+ * why their formula cannot spill.
+ */
+export interface SpillError {
+    /** The type of obstruction */
+    reason: SpillErrorReason;
+    /** CellId of the blocking cell (if reason is 'blocked') */
+    blockingCellId?: CellId;
+    /** Human-readable description */
+    message: string;
+}
+/**
+ * Projection information for a cell position.
+ *
+ * Describes how a cell's displayed value is derived from a dynamic array
+ * formula's projection. This replaces the old "spill phantom" concept:
+ * instead of creating phantom CellIds for each spilled position, the
+ * ProjectionRegistry maps (sheet, row, col) -> source cell + offset.
+ *
+ * @see compute-core/src/eval/projection_registry.rs
+ */
+export interface ProjectionInfo {
+    /** Row of the source cell (the cell containing the array formula). */
+    sourceRow: number;
+    /** Column of the source cell. */
+    sourceCol: number;
+    /** Top-left row of the projection region (usually same as sourceRow). */
+    originRow: number;
+    /** Top-left column of the projection region (usually same as sourceCol). */
+    originCol: number;
+    /** Number of rows in the projected array. */
+    rows: number;
+    /** Number of columns in the projected array. */
+    cols: number;
+}
+//# sourceMappingURL=spill.d.ts.map