Types

AccentNode

Accent - <m:acc> Accent mark over base expression (hat, tilde, dot, etc.)

type AccentNode = {
  type: 'acc';
  /** Accent character (defaults to combining circumflex U+0302) */
  chr?: string;
  /** Base expression */
  e: MathNode[];
}

AccessExplanation

Derivation trace returned by `wb.security.explainAccess(...)`. Matches the Rust `compute_security::engine::AccessExplanation` serde shape.

type AccessExplanation = {
  /** The resolved access level */
  level: AccessLevel;
  /** The policy that determined the level (null = default, no policy matched) */
  matchedPolicy: AccessPolicy | null;
  /** Why this level was chosen */
  reason: string;
  /** All policies that were considered during evaluation */
  candidatePolicies: AccessPolicy[];
  /** Warnings (e.g., "ambiguous: 2 policies at same specificity+priority disagree") */
  warnings: string[];
}

AccessLevel

Single linear access level scale. No per-aspect complexity. - `none` — hidden, scope doesn't exist for this principal - `structure` — formulas, types, formatting visible; values show type placeholders - `read` — full data, no write - `write` — full access - `admin` — full access + can modify policies

type AccessLevel = 'none' | 'structure' | 'read' | 'write' | 'admin'

AccessPolicy

A data access policy. Policies define what access level a principal (matched by tag glob) has to a target (matched by target pattern). `level: 'none'` is the deny — there is no separate `effect` field.

type AccessPolicy = {
  id: PolicyId;
  /** Glob-matched against principal's tags */
  principalTag: TagMatcher;
  /** Target pattern to match */
  target: TargetMatcher;
  /** The granted access level */
  level: AccessLevel;
  /** Higher priority wins within the same specificity tier.

Recommended ranges:
- 0-99: App-defined policies (default: 0)
- 100-199: Template-generated policies
- 200+: Platform/system policies (owner lockout, etc.) */
  priority: number;
  /** Whether this policy is active */
  enabled: boolean;
  /** Policy metadata for auditing and template tracking */
  metadata: AccessPolicyMetadata;
}

AccessPolicyMetadata

Metadata attached to an access policy.

type AccessPolicyMetadata = {
  /** Tag of the principal who created this policy */
  createdBy: string;
  /** Creation timestamp (epoch ms) */
  createdAt: number;
  /** Human-readable description */
  description?: string;
  /** If created by a template, tracks which one */
  templateId?: string;
}

AccessPrincipal

A principal is identified by a set of opaque string tags. Mog provides the matching engine; apps define their own identity taxonomy. Examples: - `{ tags: ['user:[email protected]', 'team:finance'] }` - `{ tags: ['agent:copilot'] }` - `{ tags: ['mog:owner'] }`

type AccessPrincipal = {
  tags: string[];
}

AccessTarget

Identity-based resource target. Phase 1 supports workbook, sheet, and column. Uses a discriminated union for type-safe exhaustive switch checking.

type AccessTarget = | { readonly kind: 'workbook' }
  | { readonly kind: 'sheet'; readonly sheetId: SheetId }
  | { readonly kind: 'column'; readonly colId: ColId; readonly sheetId: SheetId }

ActiveCellEditSource

Kernel-owned read model for the source text used when entering edit mode on the active cell.

type ActiveCellEditSource = {
  sheetId: SheetId;
  row: number;
  col: number;
  source: string;
  version: number;
  fresh: boolean;
}

ActiveScenarioState

Session-scoped state for an applied scenario.

type ActiveScenarioState = {
  /** Scenario whose values are currently applied in this local session. */
  scenarioId: string;
  /** Session baseline token used by restore once Rust-owned apply/restore lands. */
  baselineId: string;
  /** Document handle this session state belongs to. */
  documentId: string;
  /** Whether the stored scenario definition still matches the active baseline. */
  definitionStatus?: 'current' | 'stale' | 'deleted';
  /** Whether active cells have diverged from the baseline. */
  cellMutationStatus?: 'clean' | 'conflicted';
}

AddCheckboxFormControlOptions

type AddCheckboxFormControlOptions = WorksheetCreateCheckboxOptions & {
  type: 'checkbox';
}

AdjustmentValues

Adjustment values for fine-tuning warp parameters. Each warp preset has 0-2 adjustment handles that control its shape. Values are percentages (typically 0-100) or absolute values depending on preset. The specific meaning of each adjustment depends on the preset type. @see ECMA-376 Part 1, Section 20.1.9.9 (CT_GeomGuideList) @example // textArchUp has one adjustment (arc height) { adj1: 50 } // 50% arc height @example // textWave1 has two adjustments (amplitude, frequency) { adj1: 20, adj2: 30 }

type AdjustmentValues = {
  /** Primary adjustment value.
Meaning depends on the warp preset:
- Arc presets: arc height/curvature
- Wave presets: amplitude
- Inflate/deflate: bulge amount
- Fade presets: fade percentage */
  adj1?: number;
  /** Secondary adjustment value.
Meaning depends on the warp preset:
- Wave presets: phase offset
- Pour presets: inner radius
- Some geometric presets: secondary parameter */
  adj2?: number;
}

AdvancedFilterCopyToOptions

type AdvancedFilterCopyToOptions = {
  listRange: string;
  criteriaRange?: string | null;
  mode: 'copyTo';
  copyToRange: string;
  uniqueRecordsOnly?: boolean;
  filterId?: never;
}

AdvancedFilterCopyToResult

type AdvancedFilterCopyToResult = {
  mode: 'copyTo';
  listRange: string;
  criteriaRange?: string;
  filterId?: never;
  rowsMatched: number;
  rowsHidden?: never;
  rowsCopied: number;
  columnsCopied: number;
  destinationRange?: string;
}

AdvancedFilterDetailInfo

type AdvancedFilterDetailInfo = {
  /** Resolved criteria range, if this Advanced Filter has criteria. */
  criteriaRange?: { startRow: number; startCol: number; endRow: number; endCol: number };
  /** Whether duplicate full-row records are hidden/copied after criteria evaluation. */
  uniqueRecordsOnly: boolean;
  /** Whether this Advanced Filter currently has criteria or unique-records semantics. */
  active: boolean;
}

AdvancedFilterInPlaceOptions

type AdvancedFilterInPlaceOptions = {
  listRange: string;
  criteriaRange?: string | null;
  mode: 'inPlace';
  copyToRange?: never;
  uniqueRecordsOnly?: boolean;
  filterId?: string;
}

AdvancedFilterInPlaceResult

type AdvancedFilterInPlaceResult = {
  mode: 'inPlace';
  listRange: string;
  criteriaRange?: string;
  filterId: string;
  rowsMatched: number;
  rowsHidden: number;
  rowsCopied?: never;
  columnsCopied?: never;
  destinationRange?: never;
}

AdvancedFilterOptions

type AdvancedFilterOptions = AdvancedFilterInPlaceOptions | AdvancedFilterCopyToOptions

AdvancedFilterResult

type AdvancedFilterResult = AdvancedFilterInPlaceResult | AdvancedFilterCopyToResult

AggregateFunction

type AggregateFunction = 'sum' | 'count' | 'counta' | 'countunique' | 'average' | 'min' | 'max' | 'product' | 'stdev' | 'stdevp' | 'var' | 'varp'

AggregateResult

Aggregate values for selected cells (status bar display).

type AggregateResult = {
  /** Sum of numeric values */
  sum: number;
  /** Total number of non-empty cells */
  count: number;
  /** Number of numeric cells */
  numericCount: number;
  /** Average of numeric values (null if no numeric cells) */
  average: number | null;
  /** Minimum numeric value (null if no numeric cells) */
  min: number | null;
  /** Maximum numeric value (null if no numeric cells) */
  max: number | null;
}

ApplyScenarioResult

Result returned from applyScenario().

type ApplyScenarioResult = {
  /** Session baseline token to pass to restoreScenario(). */
  baselineId: string;
  /** Document/session handle this baseline belongs to. */
  documentId?: string;
  /** Number of cells that were updated with scenario values. */
  cellsUpdated: number;
  /** CellIds that could not be found (deleted cells). */
  skippedCells: string[];
  /** Original values to pass to restoreScenario() later. */
  originalValues: OriginalCellValue[];
}

AreaSubType

type AreaSubType = 'standard' | 'stacked' | 'percentStacked'

ArrowHead

Arrow head style for connectors.

type ArrowHead = {
  /** Arrow head type */
  type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'open';
  /** Arrow head size */
  size: 'small' | 'medium' | 'large';
}

AuthorizedMaterializedCacheMetadata

type AuthorizedMaterializedCacheMetadata = {
  cachedValuesVersion?: string;
  materializedAt?: string;
  policyVersion?: string;
}

AutoFillChange

A single cell change produced by the fill engine.

type AutoFillChange = {
  row: number;
  col: number;
  type: 'value' | 'formula' | 'format' | 'clear';
}

AutoFillMode

Fill mode for autoFill() — matches Rust FillMode enum. Covers the full spreadsheet fill behavior set.

type AutoFillMode = | 'auto' // Detect pattern automatically (default)
  | 'copy' // Always copy (no series)
  | 'series' // Force series interpretation
  | 'days' // Force date unit: days
  | 'weekdays' // Force date unit: weekdays
  | 'months' // Force date unit: months
  | 'years' // Force date unit: years
  | 'formats' // Copy formats only
  | 'values' // Copy values only (no formats)
  | 'withoutFormats' // Copy values + formulas, skip formats
  | 'linearTrend' // Force linear regression trend
  | 'growthTrend'

AutoFillResult

Result from autoFill() — summary of what the fill engine did.

type AutoFillResult = {
  /** The pattern that was detected (or forced by mode) */
  patternType: FillPatternType;
  /** Number of cells that were filled */
  filledCellCount: number;
  /** Any warnings generated during fill */
  warnings: AutoFillWarning[];
  /** Per-cell changes listing each cell written */
  changes: AutoFillChange[];
}

AutoFillWarning

type AutoFillWarning = {
  row: number;
  col: number;
  kind: AutoFillWarningKind;
}

AutoFillWarningKind

type AutoFillWarningKind = | { type: 'mergedCellsInTarget' }
  | { type: 'formulaRefOutOfBounds'; refIndex: number }
  | { type: 'sourceCellEmpty' }

AutoFilterClearReceipt

Receipt for clearing an auto-filter.

type AutoFilterClearReceipt = {
  kind: 'autoFilterClear';
}

AutoFilterSetReceipt

Receipt for setting an auto-filter.

type AutoFilterSetReceipt = {
  kind: 'autoFilterSet';
  range: string;
}

AxisBound

type AxisBound = AxisBoundLabel | number

AxisBoundLabel

type AxisBoundLabel = "auto" | "same"

AxisConfig

Axis configuration (matches AxisData wire type). Wire field names: categoryAxis, valueAxis, secondaryCategoryAxis, secondaryValueAxis. Legacy aliases: xAxis, yAxis, secondaryYAxis (mapped in chart-bridge).

type AxisConfig = {
  categoryAxis?: SingleAxisConfig;
  valueAxis?: SingleAxisConfig;
  secondaryCategoryAxis?: SingleAxisConfig;
  secondaryValueAxis?: SingleAxisConfig;
  seriesAxis?: SingleAxisConfig;
  /** @deprecated Use categoryAxis instead */
  xAxis?: SingleAxisConfig;
  /** @deprecated Use valueAxis instead */
  yAxis?: SingleAxisConfig;
  /** @deprecated Use secondaryValueAxis instead */
  secondaryYAxis?: SingleAxisConfig;
}

AxisType

Axis type

type AxisType = 'category' | 'value' | 'time' | 'log'

BarNode

Bar - <m:bar> Horizontal bar over or under base

type BarNode = {
  type: 'bar';
  /** Position: 'top' (overline) or 'bot' (underline) */
  pos: 'top' | 'bot';
  /** Base expression */
  e: MathNode[];
}

BarSubType

Chart sub-types for variations

type BarSubType = 'clustered' | 'stacked' | 'percentStacked'

Bevel

Bevel effect for a 3D shape edge. @see ECMA-376 Part 1, Section 20.1.5.3 (bevelT) and 20.1.5.4 (bevelB)

type Bevel = {
  /** Bevel width in EMUs */
  w?: number;
  /** Bevel height in EMUs */
  h?: number;
  /** Bevel preset type */
  prst?: BevelPresetType;
}

BevelEffect

3D bevel effect configuration.

type BevelEffect = {
  /** Bevel preset type */
  type: | 'none'
    | 'relaxed'
    | 'circle'
    | 'slope'
    | 'cross'
    | 'angle'
    | 'soft-round'
    | 'convex'
    | 'cool-slant'
    | 'divot'
    | 'riblet'
    | 'hard-edge'
    | 'art-deco';
  /** Bevel width in pixels */
  width: number;
  /** Bevel height in pixels */
  height: number;
}

BevelPresetType

Bevel preset type. Defines the cross-section profile of a 3D bevel edge effect. 12 presets defining different edge shapes. @see ECMA-376 Part 1, Section 20.1.10.6 (ST_BevelPresetType)

type BevelPresetType = | 'relaxedInset' // Subtle rounded inset
  | 'circle' // Circular cross-section
  | 'slope' // Linear angled edge
  | 'cross' // Cross-shaped profile
  | 'angle' // Sharp angled edge
  | 'softRound' // Soft rounded profile
  | 'convex' // Outward curving edge
  | 'coolSlant' // Stylized slanted edge
  | 'divot' // Indented groove
  | 'riblet' // Ribbed texture
  | 'hardEdge' // Sharp, defined edge
  | 'artDeco'

BlipFill

Picture/texture fill definition.

type BlipFill = {
  src: string;
  stretch?: boolean;
  tile?: TileSettings;
}

BorderBoxNode

BorderBox - <m:borderBox> Box with visible borders

type BorderBoxNode = {
  type: 'borderBox';
  /** Hide individual borders */
  hideTop?: boolean;
  hideBot?: boolean;
  hideLeft?: boolean;
  hideRight?: boolean;
  /** Strikethrough lines */
  strikeH?: boolean;
  strikeV?: boolean;
  strikeBLTR?: boolean;
  strikeTLBR?: boolean;
  /** Content */
  e: MathNode[];
}

BorderStyle

Border style. D3: Spreadsheet border styles. The full XLSX border-style set is supported: - Solid: 'thin', 'medium', 'thick' (varying line widths) - Dashed: 'dashed', 'mediumDashed' (varying dash lengths) - Dotted: 'dotted', 'hair' (dots and very fine lines) - Double: 'double' (two parallel lines) - Dash-dot combinations: 'dashDot', 'dashDotDot', 'mediumDashDot', 'mediumDashDotDot' - Special: 'slantDashDot' (slanted dash-dot pattern) @see cells-layer.ts getBorderDashPattern() for canvas rendering @see format-mapper.ts for XLSX import/export mapping

type BorderStyle = {
  style: | 'none'
    | 'thin'
    | 'medium'
    | 'thick'
    | 'dashed'
    | 'dotted'
    | 'double'
    | 'hair'
    | 'mediumDashed'
    | 'dashDot'
    | 'dashDotDot'
    | 'mediumDashDot'
    | 'mediumDashDotDot'
    | 'slantDashDot';
  color?: string;
  /** Tint modifier for border color (-1.0 to +1.0, ECMA-376). */
  colorTint?: number;
}

BoxNode

Box - <m:box> Invisible container for grouping/alignment

type BoxNode = {
  type: 'box';
  /** Operator emulator (acts as operator for spacing) */
  opEmu?: boolean;
  /** No break (keep together) */
  noBreak?: boolean;
  /** Differential (italic d for dx) */
  diff?: boolean;
  /** Alignment point */
  aln?: boolean;
  /** Content */
  e: MathNode[];
}

BoxplotConfig

Box plot configuration

type BoxplotConfig = {
  showOutliers?: boolean;
  showMean?: boolean;
  whiskerType?: 'tukey' | 'minMax' | 'percentile';
}

BreakWorkbookLinkOptions

type BreakWorkbookLinkOptions = {
  keepValues?: boolean;
}

ButtonControl

Button control - triggers actions on click. Unlike other controls, Button's primary purpose is triggering actions, not storing values. linkedCellId is optional. Use cases: - Increment a counter cell on click - Trigger a macro/script (via actionId) - Navigate to another sheet/location

type ButtonControl = {
  type: 'button';
  /** Button label text */
  label: string;
  /** Optional - Cell to write to on click.
Common patterns:
- Increment counter: read current value, write value + 1
- Toggle: write opposite of current value
- Fixed value: write specific value (e.g., timestamp) */
  linkedCellId?: CellId;
  /** Action ID for future macro/script integration.
Will be used to trigger named actions defined elsewhere. */
  actionId?: string;
  /** Value to write to linked cell on click.
Only used if linkedCellId is set and clickAction is 'setValue'. */
  clickValue?: unknown;
  /** Click behavior when linkedCellId is set.
- 'setValue': Write clickValue to cell
- 'increment': Add 1 to current numeric value
- 'decrement': Subtract 1 from current numeric value
- 'toggle': Toggle boolean value */
  clickAction?: 'setValue' | 'increment' | 'decrement' | 'toggle';
}

CFAboveAverageRule

Above/below average rule.

type CFAboveAverageRule = {
  type: 'aboveAverage';
  aboveAverage: boolean;
  equalAverage?: boolean;
  stdDev?: number;
  style: CFStyle;
}

CFCellValueRule

Cell value comparison rule.

type CFCellValueRule = {
  type: 'cellValue';
  operator: CFOperator;
  value1: number | string;
  value2?: number | string;
  style: CFStyle;
}

CFColorScale

Color scale configuration (2 or 3 colors).

type CFColorScale = {
  minPoint: CFColorPoint;
  midPoint?: CFColorPoint;
  maxPoint: CFColorPoint;
}

CFColorScaleRule

Color scale rule.

type CFColorScaleRule = {
  type: 'colorScale';
  colorScale: CFColorScale;
}

CFContainsBlanksRule

Contains blanks rule.

type CFContainsBlanksRule = {
  type: 'containsBlanks';
  blanks: boolean;
  style: CFStyle;
}

CFContainsErrorsRule

Contains errors rule.

type CFContainsErrorsRule = {
  type: 'containsErrors';
  errors: boolean;
  style: CFStyle;
}

CFContainsTextRule

Contains text rule.

type CFContainsTextRule = {
  type: 'containsText';
  operator: CFTextOperator;
  text: string;
  style: CFStyle;
}

CFDataBar

Data bar configuration.

type CFDataBar = {
  minPoint: CFColorPoint;
  maxPoint: CFColorPoint;
  positiveColor: string;
  negativeColor?: string;
  borderColor?: string;
  negativeBorderColor?: string;
  showBorder?: boolean;
  gradient?: boolean;
  direction?: 'leftToRight' | 'rightToLeft' | 'context';
  axisPosition?: CFDataBarAxisPosition;
  axisColor?: string;
  showValue?: boolean;
  /** When true, negative bars use the positive fill color. */
  matchPositiveFillColor?: boolean;
  /** When true, negative bars use the positive border color. */
  matchPositiveBorderColor?: boolean;
  /** Extension identifier for OOXML ext data bars. */
  extId?: string;
}

CFDataBarRule

Data bar rule.

type CFDataBarRule = {
  type: 'dataBar';
  dataBar: CFDataBar;
}

CFDuplicateValuesRule

Duplicate/unique values rule.

type CFDuplicateValuesRule = {
  type: 'duplicateValues';
  unique?: boolean;
  style: CFStyle;
}

CFFormulaRule

Formula-based rule.

type CFFormulaRule = {
  type: 'formula';
  formula: string;
  style: CFStyle;
}

CFIconSet

Icon set configuration.

type CFIconSet = {
  iconSetName: CFIconSetName;
  thresholds?: CFIconThreshold[];
  reverseOrder?: boolean;
  showIconOnly?: boolean;
  /** Per-threshold custom icon overrides (null entries use default icons). */
  customIcons?: (CFCustomIcon | null)[];
}

CFIconSetRule

Icon set rule.

type CFIconSetRule = {
  type: 'iconSet';
  iconSet: CFIconSet;
}

CFOperator

Comparison operators for cellValue rules.

type CFOperator = | 'greaterThan'
  | 'lessThan'
  | 'greaterThanOrEqual'
  | 'lessThanOrEqual'
  | 'equal'
  | 'notEqual'
  | 'between'
  | 'notBetween'

CFRule

Union of all rule types.

type CFRule = | CFCellValueRule
  | CFFormulaRule
  | CFColorScaleRule
  | CFDataBarRule
  | CFIconSetRule
  | CFTop10Rule
  | CFAboveAverageRule
  | CFDuplicateValuesRule
  | CFContainsTextRule
  | CFContainsBlanksRule
  | CFContainsErrorsRule
  | CFTimePeriodRule

CFRuleInput

Rule input for creating new rules (id and priority assigned by the API). Callers provide the rule configuration; the API generates id and sets priority.

type CFRuleInput = Omit<CFRule, 'id' | 'priority'>

CFStyle

Conditional Formatting Render Types Types needed by canvas-renderer to render conditional formatting results. These are extracted from engine to avoid circular dependencies during the canvas-renderer extraction. ## Two-tier Rust type architecture The CFStyle defined here mirrors `compute-cf/src/types/rule.rs` — the computation / rendering type used by the Rust CF evaluation engine. A separate, intentionally simplified persistence subset lives in `domain-types/src/domain/conditional_format.rs`. That domain type is auto-generated into `compute-types.gen.ts`, which is therefore NOT the rendering source of truth for CFStyle — this file is. @module contracts/conditional-format/render-types

type CFStyle = {
  backgroundColor?: string;
  fontColor?: string;
  bold?: boolean;
  italic?: boolean;
  underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
  strikethrough?: boolean;
  numberFormat?: string;
  borderColor?: string;
  borderStyle?: CFBorderStyle;
  borderTopColor?: string;
  borderTopStyle?: CFBorderStyle;
  borderBottomColor?: string;
  borderBottomStyle?: CFBorderStyle;
  borderLeftColor?: string;
  borderLeftStyle?: CFBorderStyle;
  borderRightColor?: string;
  borderRightStyle?: CFBorderStyle;
}

CFTextOperator

Text operators for containsText rules.

type CFTextOperator = 'contains' | 'notContains' | 'beginsWith' | 'endsWith'

CFTimePeriodRule

Time period (date occurring) rule.

type CFTimePeriodRule = {
  type: 'timePeriod';
  timePeriod: DatePeriod;
  style: CFStyle;
}

CFTop10Rule

Top/bottom N rule.

type CFTop10Rule = {
  type: 'top10';
  rank: number;
  percent?: boolean;
  bottom?: boolean;
  style: CFStyle;
}

CalcMode

Calculation settings for the workbook. G.3: Supports iterative calculation for circular references. Excel allows formulas with circular references to calculate iteratively until they converge or reach the maximum iterations. When disabled (default), circular references result in #CALC! errors. @see plans/active/spreadsheet-compatibility/04-EDITING-BEHAVIORS-PLAN.md - G.3

type CalcMode = 'auto' | 'autoNoTable' | 'manual'

CalculateOptions

Options for wb.calculate() — all optional, backward compatible.

type CalculateOptions = {
  /** Enable iterative calculation for circular references.
- `true` — enable with default settings (100 iterations, 0.001 threshold)
- `{ maxIterations?: number; maxChange?: number }` — enable with custom settings
- `false` — disable (override workbook setting)
- `undefined` — use workbook setting (default) */
  iterative?: boolean | { maxIterations?: number; maxChange?: number };
}

CalculateResult

Result from wb.calculate() — includes convergence metadata.

type CalculateResult = {
  /** Whether circular references were detected. */
  hasCircularRefs: boolean;
  /** Whether iterative calculation converged. Only meaningful when hasCircularRefs is true. */
  converged: boolean;
  /** Number of iterations performed (0 if no circular refs). */
  iterations: number;
  /** Maximum per-cell delta at final iteration. */
  maxDelta: number;
  /** Number of cells involved in circular references. */
  circularCellCount: number;
  /** Number of formula cells recomputed during this calculation. Zero when nothing changed since last full recalc. */
  recomputedCount: number;
}

CalculatedField

Legacy calculated-field shape. New contracts should use `PivotCalculatedField`.

type CalculatedField = {
  fieldId: string;
  calculatedFieldId?: CalculatedFieldId;
  name: string;
  formula: string;
  status?: CalculatedFieldStatus;
  createdAt?: string;
  updatedAt?: string;
}

CalculatedFieldId

type CalculatedFieldId = string & { readonly __brand: 'CalculatedFieldId' }

CalculatedFieldStatus

type CalculatedFieldStatus = {
  state: 'valid' | 'invalid';
  error?: PivotKernelMutationError;
  referencedFieldIds: string[];
}

CalculationSettings

type CalculationSettings = {
  /** Whether to allow iterative calculation for circular references.
When true, formulas with circular references calculate iteratively.
When false (default), circular references show #CALC! error. */
  enableIterativeCalculation: boolean;
  /** Maximum number of iterations for iterative calculation.
Excel default: 100 */
  maxIterations: number;
  /** Maximum change between iterations for convergence.
Calculation stops when all results change by less than this amount.
Excel default: 0.001 */
  maxChange: number;
  /** Calculation mode (auto/manual/autoNoTable).
Default: 'auto' */
  calcMode: CalcMode;
  /** Whether to use full (15-digit) precision for calculations.
Default: true */
  fullPrecision: boolean;
  /** Cell reference style (true = R1C1, false = A1).
Default: false */
  r1c1Mode: boolean;
  /** Whether to perform a full calculation when the file is opened.
Default: false */
  fullCalcOnLoad: boolean;
}

CallableDisposable

A disposable that can also be called as a function (shorthand for dispose). This type alias stays in contracts since it's used in service interface signatures.

type CallableDisposable = (() => void) & IDisposable

CellAnchor

Cell anchor point with pixel offset. Used for precise positioning relative to cell boundaries. Cell Identity Model: Uses CellId for stable references that survive row/col insert/delete. Position is resolved at render time via CellPositionLookup. @example // User places image at B5 const anchor: CellAnchor = { cellId: 'abc-123...', // CellId of B5 xOffset: 10, // 10px from cell left edge yOffset: 5 // 5px from cell top edge }; // After inserting row at row 3, the CellId is unchanged // but resolves to position (row: 5, col: 1) → image moves down

type CellAnchor = {
  /** Stable cell reference that survives row/col insert/delete.
Resolve to current position via CellPositionLookup.getPosition(). */
  cellId: CellId;
  /** Horizontal offset from cell top-left in pixels */
  xOffset: number;
  /** Vertical offset from cell top-left in pixels */
  yOffset: number;
}

CellBorders

Cell borders ECMA-376 CT_Border: Full border specification for cells. Supports standard borders (top/right/bottom/left), diagonal borders, RTL equivalents (start/end), and internal borders for ranges (vertical/horizontal).

type CellBorders = {
  top?: BorderStyle;
  right?: BorderStyle;
  bottom?: BorderStyle;
  left?: BorderStyle;
  diagonal?: BorderStyle & { direction?: 'up' | 'down' | 'both' };
  /** Diagonal up flag (ECMA-376 CT_Border @diagonalUp).
When true, diagonal line runs from bottom-left to top-right.
Note: This is the spec-compliant representation. For convenience,
diagonal.direction can also be used which derives from these flags. */
  diagonalUp?: boolean;
  /** Diagonal down flag (ECMA-376 CT_Border @diagonalDown).
When true, diagonal line runs from top-left to bottom-right.
Note: This is the spec-compliant representation. For convenience,
diagonal.direction can also be used which derives from these flags. */
  diagonalDown?: boolean;
  /** RTL start border (maps to left in LTR, right in RTL).
Used for bidirectional text support. */
  start?: BorderStyle;
  /** RTL end border (maps to right in LTR, left in RTL).
Used for bidirectional text support. */
  end?: BorderStyle;
  /** Internal vertical border (between cells in a range).
Only meaningful when applied to a range of cells. */
  vertical?: BorderStyle;
  /** Internal horizontal border (between cells in a range).
Only meaningful when applied to a range of cells. */
  horizontal?: BorderStyle;
  /** Outline mode flag.
When true, borders are applied as outline around the range.
When false/undefined, borders apply to individual cells. */
  outline?: boolean;
}

CellControl

Cell-embedded interactive control (e.g., checkbox). When a cell contains a control, formulas see its `checked` state as TRUE/FALSE. The `type` field discriminates the control kind for future extensibility (toggle, dropdown, etc.).

type CellControl = {
  /** The kind of control. Currently only 'checkbox' is supported. */
  type: 'checkbox';
  /** Whether the control is in its active state (checkbox: ticked). */
  checked: boolean;
}

CellData

Complete cell data

type CellData = {
  value: CellValue;
  formula?: FormulaA1;
  format?: CellFormat;
  borders?: CellBorders;
  comment?: string;
  hyperlink?: string;
  /** Pre-formatted display string from Rust (e.g., "$1,234.50", "1/1/2024"). */
  formatted?: string;
}

CellFormat

Cell formatting options This interface defines ALL Excel format properties that can be applied to cells. The implementation status of each property is tracked in format-registry.ts. @see FORMAT_PROPERTY_REGISTRY in format-registry.ts for implementation status

type CellFormat = {
  /** Spreadsheet number format code string.

Common format codes:
- Currency:    '$#,##0.00'
- Accounting:  '_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)'
- Percentage:  '0.00%'
- Date:        'M/D/YYYY', 'YYYY-MM-DD', 'MMM D, YYYY'
- Time:        'h:mm AM/PM', 'HH:mm:ss'
- Number:      '#,##0.00', '0.00'
- Scientific:  '0.00E+00'
- Text:        '@'
- Fraction:    '# ?/?'

See the `formatPresets` section in api-spec.json for the full catalog
of 85+ pre-defined format codes with examples.

@example
// Currency
{ numberFormat: '$#,##0.00' }
// Percentage with 1 decimal
{ numberFormat: '0.0%' }
// ISO date
{ numberFormat: 'YYYY-MM-DD' } */
  numberFormat?: string;
  /** Number format category hint. Auto-detected from numberFormat when not set.
Valid values: 'general' | 'number' | 'currency' | 'accounting' | 'date' |
             'time' | 'percentage' | 'fraction' | 'scientific' | 'text' |
             'special' | 'custom' */
  numberFormatType?: NumberFormatType;
  fontFamily?: string;
  fontSize?: number;
  /** Theme font reference for "+Headings" / "+Body" workbook theme fonts.

When set, the cell uses the theme's majorFont (headings) or minorFont (body)
instead of fontFamily. Theme fonts are resolved at render time, allowing cells
to automatically update when the workbook theme changes.

Behavior:
- 'major': Uses theme.fonts.majorFont
- 'minor': Uses theme.fonts.minorFont
- undefined: Uses fontFamily property (or default font if not set)

When fontTheme is set, fontFamily is ignored for rendering but may still be
stored for fallback purposes. This matches Excel's behavior where "+Headings"
cells can have a fontFamily that's used when the theme is unavailable.

@see resolveThemeFonts in theme.ts for resolution
@see ThemeFonts for theme font pair definition */
  fontTheme?: 'major' | 'minor';
  /** Font color. Can be:
- Absolute hex: '#4472c4' or '#ff0000'
- Theme reference: 'theme:accent1' (uses current theme's accent1 color)
- Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker)

Theme references are resolved at render time via resolveThemeColors().
This enables cells to automatically update when the workbook theme changes.

@see resolveThemeColors in theme.ts for resolution
@see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.) */
  fontColor?: string;
  /** Font color tint modifier (-1.0 to +1.0). Applied on top of fontColor. */
  fontColorTint?: number;
  bold?: boolean;
  italic?: boolean;
  /** Underline type. Excel supports 4 underline styles:
- 'none': No underline (default)
- 'single': Standard underline under all characters
- 'double': Two parallel lines under all characters
- 'singleAccounting': Underline under text only (not spaces), for column alignment
- 'doubleAccounting': Double underline under text only (not spaces), for column alignment */
  underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
  strikethrough?: boolean;
  /** Superscript text (vertAlign = 'superscript' in Excel).
Text is rendered smaller and raised above the baseline. */
  superscript?: boolean;
  /** Subscript text (vertAlign = 'subscript' in Excel).
Text is rendered smaller and lowered below the baseline. */
  subscript?: boolean;
  /** Font outline effect.
Draws only the outline of each character (hollow text).
Rare in modern spreadsheets but supported by Excel. */
  fontOutline?: boolean;
  /** Font shadow effect.
Adds a shadow behind the text.
Rare in modern spreadsheets but supported by Excel. */
  fontShadow?: boolean;
  /** Horizontal text alignment.
- 'general': Context-based (left for text, right for numbers) - Excel default
- 'left': Left-align text
- 'center': Center text
- 'right': Right-align text
- 'fill': Repeat content to fill cell width
- 'justify': Justify text (distribute evenly)
- 'centerContinuous': Center across selection without merging
- 'distributed': Distribute text evenly with indent support */
  horizontalAlign?: | 'general'
    | 'left'
    | 'center'
    | 'right'
    | 'fill'
    | 'justify'
    | 'centerContinuous'
    | 'distributed';
  /** Vertical text alignment. The TypeScript/API contract uses `middle`
for centered vertical alignment.
- 'top': Align to top of cell
- 'middle': Center vertically
- 'bottom': Align to bottom of cell - Excel default
- 'justify': Justify vertically (distribute lines evenly)
- 'distributed': Distribute text evenly with vertical spacing */
  verticalAlign?: 'top' | 'middle' | 'bottom' | 'justify' | 'distributed';
  wrapText?: boolean;
  /** Text rotation angle in degrees.
- 0-90: Counter-clockwise rotation
- 91-180: Clockwise rotation (180 - value)
- 255: Vertical text (stacked characters, read top-to-bottom) */
  textRotation?: number;
  /** Indent level (0-15).
Each level adds approximately 8 pixels of indent from the cell edge.
Works with left and right horizontal alignment. */
  indent?: number;
  /** Shrink text to fit cell width.
Reduces font size to fit all text within the cell width.
Mutually exclusive with wrapText in Excel behavior. */
  shrinkToFit?: boolean;
  /** Text reading order for bidirectional text support.
- 'context': Determined by first character with strong directionality
- 'ltr': Left-to-right (forced)
- 'rtl': Right-to-left (forced) */
  readingOrder?: 'context' | 'ltr' | 'rtl';
  /** Auto-indent flag (ECMA-376 CT_CellAlignment/@autoIndent). */
  autoIndent?: boolean;
  /** Background color. Can be:
- Absolute hex: '#ffffff' or '#c6efce'
- Theme reference: 'theme:accent1' (uses current theme's accent1 color)
- Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker)

Theme references are resolved at render time via resolveThemeColors().
This enables cells to automatically update when the workbook theme changes.

For solid fills, this is the only color needed.
For pattern fills, this is the background color behind the pattern.

@see resolveThemeColors in theme.ts for resolution
@see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.) */
  backgroundColor?: string;
  /** Background color tint modifier (-1.0 to +1.0). Applied on top of backgroundColor. */
  backgroundColorTint?: number;
  /** Pattern fill type.
XLSX supports 18 pattern types for cell backgrounds.
When set (and not 'none' or 'solid'), the cell uses a pattern fill. */
  patternType?: PatternType;
  /** Pattern foreground color.
The color of the pattern itself (dots, lines, etc.).
Only used when patternType is set to a non-solid pattern. */
  patternForegroundColor?: string;
  /** Pattern foreground color tint modifier (-1.0 to +1.0). */
  patternForegroundColorTint?: number;
  /** Gradient fill configuration.
When set, overrides backgroundColor and pattern fill.
Excel supports linear and path (radial) gradients. */
  gradientFill?: GradientFill;
  /** Cell borders (top, right, bottom, left, diagonal) */
  borders?: CellBorders;
  /** Cell is locked when sheet protection is enabled.
Default is true in Excel (all cells locked by default).
Only effective when the sheet's isProtected flag is true. */
  locked?: boolean;
  /** Formula is hidden when sheet protection is enabled.
When true, the cell's formula is not shown in the formula bar.
The computed value is still displayed in the cell.
Only effective when the sheet's isProtected flag is true. */
  hidden?: boolean;
  /** Cell value is forced to text mode (apostrophe prefix).
When true:
- Raw value includes the leading apostrophe
- Display value strips the apostrophe
- Formula bar shows the apostrophe
- Value is NOT coerced to date/number/etc.

Set when user types ' as first character.
Follows cell on sort/move (keyed by CellId, Cell Identity Model).

@see plans/active/spreadsheet-compatibility/08-EDITING.md - Item 8.1 */
  forcedTextMode?: boolean;
  /** Arbitrary extension data for future features.
Use namespaced keys: "myfeature.mykey"
Example: { ignoreError: true } to suppress error indicators. */
  extensions?: Record<string, unknown>;
}

CellId

type CellId = string & { readonly [__cellId]: true }

CellIdRange

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

type CellIdRange = {
  /** Cell identifier string (CellId) of the top-left corner cell */
  topLeftCellId: string;
  /** Cell identifier string (CellId) of the bottom-right corner cell */
  bottomRightCellId: string;
}

CellRange

Cell range reference. This is THE canonical range type for ALL range operations in the spreadsheet. Uses flat format for simplicity and JSON compatibility. Used by: XState machines, canvas coordinates, React hooks, API, events, tables, pivots

type CellRange = {
  startRow: number;
  startCol: number;
  endRow: number;
  endCol: number;
  /** True when entire column(s) selected via column header click */
  isFullColumn?: boolean;
  /** True when entire row(s) selected via row header click */
  isFullRow?: boolean;
  sheetId?: string;
}

CellRecord

Typed cell readback record returned by {@link WorksheetCellsAccessor.get}. Shape is intentionally divergent from {@link Worksheet.getCell}'s `{value: null}` empty form: every in-bounds cell carries a `valueType` tag so callers can switch on the discriminant without a separate "is this in-bounds" check. Out-of-bounds reads return `undefined`.

type CellRecord = {
  /** Sheet-relative position (0-indexed). */
  row: number;
  col: number;
  /** A1 address as supplied to `cells.get`, normalized to upper-case. */
  addr: string;
  /** Effective value (formula result for formula cells, raw value otherwise). `null` for empty. */
  value: CellValuePrimitive | null;
  /** Per-cell value type classification — string-keyed enum already used
by {@link Worksheet.getValueTypes} for ranges.
`Empty | String | Double | Boolean | Error` (dates classified as
`Double`, matching the workbook API). */
  valueType: RangeValueType;
  /** Authored formula (A1) when the cell has one; `null` otherwise. */
  formula: string | null;
  /** Unified region-membership shape. `null` for plain cells. */
  region: RegionMeta | null;
  /** Convenience: `region != null && !region.isAnchor`. Derived, not stored. */
  isArrayMember: boolean;
}

CellStyle

Named cell style that can be applied to cells. Styles are a named collection of formatting properties. When applied, the format values are copied to cells (not referenced by ID). This matches Excel behavior where style changes don't affect already-styled cells. Built-in styles are defined in code and never persisted. Custom styles are stored in Yjs for collaboration.

type CellStyle = {
  /** Unique identifier (e.g., 'good', 'heading1', 'custom-abc123') */
  id: string;
  /** Display name shown in UI (e.g., 'Good', 'Heading 1') */
  name: string;
  /** Category for UI grouping */
  category: StyleCategory;
  /** The formatting properties to apply */
  format: CellFormat;
  /** True for built-in styles, false for user-created */
  builtIn: boolean;
}

CellStyleCatalog

type CellStyleCatalog = {
  /** Ordered category metadata for categories with matching styles. */
  categories: readonly CellStyleCategoryInfo[];
  /** Styles matching the catalog query. */
  styles: readonly CellStyle[];
}

CellStyleCategoryInfo

type CellStyleCategoryInfo = {
  /** Stable category identifier used by CellStyle.category. */
  id: StyleCategory;
  /** User-facing category label. */
  label: string;
  /** Display order within the catalog. */
  order: number;
}

CellStyleListOptions

type CellStyleListOptions = {
  /** Which style source to include. Defaults to all styles. */
  source?: CellStyleSource;
  /** Restrict results to a single style category. */
  category?: StyleCategory;
}

CellStyleSource

type CellStyleSource = 'all' | 'builtIn' | 'custom'

CellType

Cell type classification for `getSpecialCells()`. Matches the spreadsheet special-cell type.

enum CellType {
  Blanks = 'Blanks',
  Constants = 'Constants',
  Formulas = 'Formulas',
  Visible = 'Visible',
  ConditionalFormats = 'ConditionalFormats',
  DataValidations = 'DataValidations',
}

CellValue

WorkbookFunctions -- Sub-API for programmatic function invocation. Provides namespaced access to spreadsheet function evaluation without writing to any cell. Usage: `const result = await wb.functions.sum("A1:A10")`

type CellValue = string | number | boolean | null

CellValuePrimitive

Primitive cell value types

type CellValuePrimitive = string | number | boolean | null

CellValueType

Value type filter for `getSpecialCells()` when cellType is `Constants` or `Formulas`. Matches the spreadsheet special-cell value type.

enum CellValueType {
  Numbers = 'Numbers',
  Text = 'Text',
  Logicals = 'Logicals',
  Errors = 'Errors',
}

CellWriteOptions

Options controlling how a cell value is interpreted when written.

type CellWriteOptions = {
  /** If true, value is treated as a formula (prefixed with =) */
  asFormula?: boolean;
  /** If true, string values starting with "=" are stored as literal text, not formulas. */
  literal?: boolean;
}

ChangeOrigin

Origin of a change: direct write, formula recalculation, or remote collaborator.

type ChangeOrigin = 'direct' | 'cascade' | 'remote'

ChangeRecord

WorksheetChanges — Sub-API for opt-in change tracking. Creates lightweight trackers that accumulate cell-level change records across mutations. Trackers are opt-in to avoid bloating return values; they return addresses + metadata only (no cell values) so callers can hydrate via getRange() when needed. Inspired by query-scoped subscriptions and transaction origin tagging.

type ChangeRecord = {
  /** Cell address in A1 notation (e.g. "B1"). */
  address: string;
  /** 0-based row index. */
  row: number;
  /** 0-based column index. */
  col: number;
  /** What caused this change. */
  origin: ChangeOrigin;
  /** Type of change. */
  type: 'modified';
  /** Value before the change (undefined if cell was previously empty). */
  oldValue?: unknown;
  /** Value after the change (undefined if cell was cleared). */
  newValue?: unknown;
}

ChangeTrackOptions

Options for creating a change tracker.

type ChangeTrackOptions = {
  /** Only track changes within this range (A1 notation, e.g. "A1:Z100"). Omit for whole-sheet. */
  scope?: string;
  /** Exclude changes from these origin types. */
  excludeOrigins?: ChangeOrigin[];
}

ChangeTracker

A handle that accumulates change records across mutations.

type ChangeTracker = {
  /** Drain all accumulated changes since creation or last collect() call.
Returns addresses + metadata only (no cell values) — call ws.getRange()
to hydrate if needed. */
  collect(): ChangeRecord[];;
  /** Stop tracking and release internal resources. */
  close(): void;;
  /** Whether this tracker is still active (not closed). */
  active: boolean;
}

Chart

Chart as returned by get/list operations. Extends ChartConfig with identity and metadata fields.

type Chart = {
  id: string;
  sheetId?: string;
  createdAt?: number;
  updatedAt?: number;
}

ChartAreaConfig

Chart area configuration

type ChartAreaConfig = {
  fill?: ChartFill;
  border?: ChartBorder;
  format?: ChartFormat;
}

ChartBorder

Shared chart border configuration (matches ChartBorderData wire type)

type ChartBorder = {
  color?: string;
  width?: number;
  style?: string;
}

ChartColor

Color: hex string for direct colors, object for theme-aware colors.

type ChartColor = string | { theme: string; tintShade?: number }

ChartConfig

Public chart configuration -- the shape used by the unified API surface. This contains all user-facing fields for creating/updating charts. Internal-only fields (CellId anchors, zIndex, table linking cache) are defined in StoredChartConfig in the charts package.

type ChartConfig = {
  type: ChartType;
  /** Chart sub-type. For type-safe usage, prefer TypedChartConfig<T> which constrains subType to match type. */
  subType?: BarSubType | LineSubType | AreaSubType | StockSubType | RadarSubType;
  /** Anchor row (0-based) */
  anchorRow: number;
  /** Anchor column (0-based) */
  anchorCol: number;
  /** Chart width in cells */
  width: number;
  /** Chart height in cells */
  height: number;
  /** Data range in A1 notation (e.g., "A1:D10"). Optional when series[].values are provided. */
  dataRange?: string;
  /** Series labels range in A1 notation */
  seriesRange?: string;
  /** Category labels range in A1 notation */
  categoryRange?: string;
  seriesOrientation?: SeriesOrientation;
  title?: string;
  subtitle?: string;
  legend?: LegendConfig;
  axis?: AxisConfig;
  colors?: string[];
  series?: SeriesConfig[];
  dataLabels?: DataLabelConfig;
  pieSlice?: PieSliceConfig;
  /** @deprecated Use trendlines[] instead — kept for backward compat */
  trendline?: TrendlineConfig;
  /** Wire-compatible trendline array */
  trendlines?: TrendlineConfig[];
  /** Connect scatter points with lines (scatter-lines variant) */
  showLines?: boolean;
  /** Use smooth curves for scatter lines (scatter-smooth-lines variant) */
  smoothLines?: boolean;
  /** Fill area under radar lines */
  radarFilled?: boolean;
  /** Show markers on radar vertices */
  radarMarkers?: boolean;
  /** How blank cells are plotted: 'gap' (leave gap), 'zero' (treat as zero), 'span' (interpolate) */
  displayBlanksAs?: 'gap' | 'zero' | 'span';
  /** Whether to plot only visible cells (respecting row/column hiding) */
  plotVisibleOnly?: boolean;
  /** Gap width between bars/columns as percentage (0-500). Applied to bar/column chart types. */
  gapWidth?: number;
  /** Overlap between bars/columns (-100 to 100). Applied to clustered bar/column types. */
  overlap?: number;
  /** Hole size for doughnut charts as percentage (10-90) */
  doughnutHoleSize?: number;
  /** First slice angle for pie/doughnut charts in degrees (0-360) */
  firstSliceAngle?: number;
  /** Bubble scale for bubble charts as percentage (0-300) */
  bubbleScale?: number;
  /** Split type for of-pie charts (pie-of-pie, bar-of-pie) */
  splitType?: 'auto' | 'value' | 'percent' | 'position' | 'custom';
  /** Split value threshold for of-pie charts */
  splitValue?: number;
  waterfall?: WaterfallConfig;
  histogram?: HistogramConfig;
  boxplot?: BoxplotConfig;
  heatmap?: HeatmapConfig;
  violin?: ViolinConfig;
  treemap?: TreemapConfig;
  sunburst?: SunburstConfig;
  regionMap?: RegionMapConfig;
  name?: string;
  chartTitle?: TitleConfig;
  chartArea?: ChartAreaConfig;
  plotArea?: PlotAreaConfig;
  style?: number;
  roundedCorners?: boolean;
  autoTitleDeleted?: boolean;
  showDataLabelsOverMaximum?: boolean;
  chartFormat?: ChartFormat;
  plotFormat?: ChartFormat;
  titleFormat?: ChartFormat;
  titleRichText?: ChartFormatString[];
  titleFormula?: string;
  dataTable?: DataTableConfig;
  /** Which level of multi-level category labels to show (0-based). */
  categoryLabelLevel?: number;
  /** Which level of multi-level series names to show (0-based). */
  seriesNameLevel?: number;
  /** Show/hide all pivot field buttons on the chart. */
  showAllFieldButtons?: boolean;
  /** Size of the secondary plot for PieOfPie/BarOfPie charts (5-200%). OOXML c:secondPieSize. */
  secondPlotSize?: number;
  /** Use different colors per category. OOXML c:varyColors (chart-group level). */
  varyByCategories?: boolean;
  /** Pivot chart display options. */
  pivotOptions?: PivotChartOptions;
  /** Z-order command for layering charts.
Accepted as a convenience field by ws.charts.update() to adjust z-index:
- 'front': bring to top of stack
- 'back': send to bottom of stack
- 'forward': move one layer up
- 'backward': move one layer down */
  zOrder?: 'front' | 'back' | 'forward' | 'backward';
  /** Mark shape for 3D bar/column charts (default: 'box'). Maps to OOXML c:shape. */
  barShape?: 'box' | 'cylinder' | 'cone' | 'pyramid';
  /** Extensible extra data for enriched chart configurations.
Contains additional chart-specific settings (e.g., chartTitle font, chartArea fill)
that are stored on the chart but not part of the core config schema. */
  extra?: unknown;
  /** Chart height in points */
  heightPt?: number;
  /** Chart width in points */
  widthPt?: number;
  /** Left offset in points */
  leftPt?: number;
  /** Top offset in points */
  topPt?: number;
  /** Enable 3D bubble effect for bubble charts */
  bubble3DEffect?: boolean;
  /** Render surface chart as wireframe */
  wireframe?: boolean;
  /** Use surface chart top-down view (contour) */
  surfaceTopView?: boolean;
  /** Chart color scheme index */
  colorScheme?: number;
}

ChartFill

Fill. Maps to OOXML EG_FillProperties.

type ChartFill = | { type: 'none' }
  | { type: 'solid'; color: ChartColor; transparency?: number }
  | {
      type: 'gradient';
      gradientType: 'linear' | 'radial' | 'rectangular';
      angle?: number;
      stops: { position: number; color: ChartColor; transparency?: number }[];
    }
  | { type: 'pattern'; pattern: string; foreground?: ChartColor; background?: ChartColor }

ChartFont

Font. Maps to OOXML tx_pr → defRPr.

type ChartFont = {
  name?: string;
  size?: number;
  bold?: boolean;
  italic?: boolean;
  color?: ChartColor;
  underline?: | 'none'
    | 'single'
    | 'double'
    | 'singleAccountant'
    | 'doubleAccountant'
    | 'dash'
    | 'dashLong'
    | 'dotDash'
    | 'dotDotDash'
    | 'dotted'
    | 'heavy'
    | 'wavy'
    | 'wavyDouble'
    | 'wavyHeavy'
    | 'words';
  strikethrough?: 'single' | 'double';
}

ChartFormat

Composite format for a chart element.

type ChartFormat = {
  fill?: ChartFill;
  line?: ChartLineFormat;
  font?: ChartFont;
  textRotation?: number;
  shadow?: ChartShadow;
}

ChartFormatString

A styled text run for rich text in chart titles and data labels.

type ChartFormatString = {
  text: string;
  font?: ChartFont;
}

ChartLeaderLinesFormat

Leader line formatting for data labels.

type ChartLeaderLinesFormat = {
  format: ChartLineFormat;
}

ChartLineFormat

Line/border. Maps to OOXML CT_LineProperties.

type ChartLineFormat = {
  color?: ChartColor;
  width?: number;
  dashStyle?: 'solid' | 'dot' | 'dash' | 'dashDot' | 'longDash' | 'longDashDot' | 'longDashDotDot';
  transparency?: number;
}

ChartObject

Chart floating object. Integrates charts with the FloatingObjectManager to provide: - Hit-testing for selection - Drag/resize/z-order operations - Consistent interaction model with other floating objects Architecture Notes: - Uses Cell Identity Model with CellIdRange references (CRDT-safe) - Full chart configuration lives in the Charts domain module - This interface provides the FloatingObject layer for interactions - Position resolution happens at render time via CellPositionLookup @example // Chart data range A1:D10 const chart: ChartObject = { id: 'chart-1', type: 'chart', sheetId: 'sheet-abc', position: { anchorType: 'oneCell', from: { cellId: '...', xOffset: 0, yOffset: 0 }, width: 400, height: 300 }, zIndex: 1, locked: false, printable: true, chartType: 'column', anchorMode: 'oneCell', widthCells: 8, heightCells: 15, chartConfig: { series: [], axes: {} }, dataRangeIdentity: { topLeftCellId: '...', bottomRightCellId: '...' } };

type ChartObject = {
  type: 'chart';
  /** The type of chart (bar, line, pie, etc.) */
  chartType: ChartObjectType;
  /** How chart anchors to cells - affects resize behavior.
- 'oneCell': Chart moves with anchor cell, but doesn't resize with cell changes
- 'twoCell': Chart moves and resizes with both anchor cells */
  anchorMode: 'oneCell' | 'twoCell';
  /** Width in cell units (for oneCell mode sizing).
In twoCell mode, width is determined by the anchor cell positions. */
  widthCells: number;
  /** Height in cell units (for oneCell mode sizing).
In twoCell mode, height is determined by the anchor cell positions. */
  heightCells: number;
  /** Full chart configuration (series, axes, legend, colors, etc.).
Stored directly on the floating object as a sub-object field, following the
same pattern as fill/outline/shadow on shapes. */
  chartConfig: Record<string, unknown>;
  /** Chart data range using CellId corners (CRDT-safe).
Automatically expands when rows/cols inserted between corners.
Optional because some charts may have inline data or external sources. */
  dataRangeIdentity?: CellIdRange;
  /** Series labels range using CellId corners (CRDT-safe).
Used to label each data series in the chart. */
  seriesRangeIdentity?: CellIdRange;
  /** Category labels range using CellId corners (CRDT-safe).
Used for x-axis labels in most chart types. */
  categoryRangeIdentity?: CellIdRange;
}

ChartObjectType

Supported chart types for the ChartObject. Matches the ChartType from charts package but defined here for contracts.

type ChartObjectType = | 'bar'
  | 'column'
  | 'line'
  | 'area'
  | 'pie'
  | 'doughnut'
  | 'scatter'
  | 'bubble'
  | 'combo'
  | 'radar'
  | 'stock'
  | 'funnel'
  | 'waterfall'

ChartSeriesDimension

Dimension identifiers for series data access.

type ChartSeriesDimension = 'categories' | 'values' | 'bubbleSizes'

ChartShadow

Shadow effect for chart elements.

type ChartShadow = {
  visible?: boolean;
  color?: ChartColor;
  blur?: number;
  offsetX?: number;
  offsetY?: number;
  transparency?: number;
}

ChartType

Supported chart types for spreadsheet charts

type ChartType = | 'bar'
  | 'column'
  | 'line'
  | 'area'
  | 'pie'
  | 'doughnut'
  | 'scatter'
  | 'bubble'
  | 'combo'
  | 'radar'
  | 'stock'
  | 'funnel'
  | 'waterfall'
  // OOXML roundtrip types
  | 'surface'
  | 'surface3d'
  | 'ofPie'
  | 'bar3d'
  | 'column3d'
  | 'line3d'
  | 'pie3d'
  | 'area3d'
  // Statistical chart types
  | 'histogram'
  | 'boxplot'
  | 'heatmap'
  | 'violin'
  | 'pareto'
  // Hierarchical chart types
  | 'treemap'
  | 'sunburst'
  // Geographic chart types
  | 'regionMap'
  // Exploded pie variants
  | 'pieExploded'
  | 'pie3dExploded'
  | 'doughnutExploded'
  // Bubble with 3D effect
  | 'bubble3DEffect'
  // Surface variants
  | 'surfaceWireframe'
  | 'surfaceTopView'
  | 'surfaceTopViewWireframe'
  // Line with markers
  | 'lineMarkers'
  | 'lineMarkersStacked'
  | 'lineMarkersStacked100'
  // Decorative 3D shape charts (cylinder)
  | 'cylinderColClustered'
  | 'cylinderColStacked'
  | 'cylinderColStacked100'
  | 'cylinderBarClustered'
  | 'cylinderBarStacked'
  | 'cylinderBarStacked100'
  | 'cylinderCol'
  // Decorative 3D shape charts (cone)
  | 'coneColClustered'
  | 'coneColStacked'
  | 'coneColStacked100'
  | 'coneBarClustered'
  | 'coneBarStacked'
  | 'coneBarStacked100'
  | 'coneCol'
  // Decorative 3D shape charts (pyramid)
  | 'pyramidColClustered'
  | 'pyramidColStacked'
  | 'pyramidColStacked100'
  | 'pyramidBarClustered'
  | 'pyramidBarStacked'
  | 'pyramidBarStacked100'
  | 'pyramidCol'

CheckboxControl

Checkbox control - reads/writes boolean to linked cell. NO local "checked" state - value lives in cell. This is critical for single source of truth. Data flow: 1. Render: Read from cell → `checked = store.getCellValueById(linkedCellId) === true` 2. Click: Write to cell → `store.setCellValueById(linkedCellId, !checked)` 3. EventBus fires → component re-renders with new value @example // Cell A1 contains TRUE/FALSE // Checkbox linked to A1 // Formula =IF(A1, "Yes", "No") works automatically

type CheckboxControl = {
  type: 'checkbox';
  /** REQUIRED - Cell that holds the boolean value.
Uses CellId for stability across row/col insert/delete.

Expected cell values:
- TRUE, true, 1 → checked
- FALSE, false, 0, empty → unchecked */
  linkedCellId: CellId;
  /** Optional label displayed next to checkbox */
  label?: string;
  /** Value to write when checked.
Default: true (boolean TRUE) */
  checkedValue?: unknown;
  /** Value to write when unchecked.
Default: false (boolean FALSE) */
  uncheckedValue?: unknown;
}

CheckpointInfo

Information about a saved checkpoint (version snapshot).

type CheckpointInfo = {
  /** Unique checkpoint ID */
  id: string;
  /** Optional human-readable label */
  label?: string;
  /** Creation timestamp (Unix ms) */
  timestamp: number;
}

Choose

OOXML choose element for conditional layout branching. Contains one or more `if` clauses evaluated in order, and an optional `else` clause. The first `if` clause whose condition evaluates to true has its children included in the layout tree. If no `if` clause matches, the `else` clause children are used (if present). @see ECMA-376 Section 21.4.2.4 choose (Choose)

type Choose = {
  /** Discriminator for LayoutNodeChild union type */
  kind: 'choose';
  /** Optional name for this choose element. */
  name: string;
  /** Ordered list of if-clauses.
Evaluated in document order; first matching clause wins. */
  ifClauses: readonly IfClause[];
  /** Optional else clause.
Used when no if-clause condition evaluates to true.
Null if no else clause is defined. */
  elseClauses: ElseClause | null;
}

ChromeTheme

Data Source Shared Types Types shared between `./data-sources.ts` and `./render-context.ts`. Extracted to break the cycle between those two modules — both now import from this leaf file instead of from each other. @module @mog-sdk/contracts/rendering/data-source-types

type ChromeTheme = {
  canvasBackground: string;
  gridlineColor: string;
  headerBackground: string;
  headerText: string;
  headerBorder: string;
  headerHighlightBackground: string;
  headerHighlightText: string;
  selectionFill: string;
  selectionBorder: string;
  activeCellBorder: string;
  fillHandleColor: string;
  dragSourceColor: string;
  dragTargetColor: string;
  scrollbarTrack: string;
  scrollbarThumb: string;
}

ClearApplyTo

Determines which aspects of a range to clear. Matches the spreadsheet clear-mode enum.

type ClearApplyTo = 'all' | 'contents' | 'formats' | 'hyperlinks'

ClearResult

Confirmation returned by clearData() and clear().

type ClearResult = {
  /** Number of cells in the cleared range. */
  cellCount: number;
}

CodeResult

Result of a code execution.

type CodeResult = {
  /** Whether execution completed successfully */
  success: boolean;
  /** Captured console output */
  output?: string;
  /** Error message (if success is false) */
  error?: string;
  /** Execution duration in milliseconds */
  duration?: number;
}

ColId

type ColId = string & { readonly [__colId]: true }

ColumnFilterCriteria

Column filter criteria - what's applied to a single column. Each column in a filter range can have its own criteria. Rows must match ALL column filters (AND logic across columns).

type ColumnFilterCriteria = {
  /** Type of filter applied to this column.

- value: Checkbox list of specific values to include
- condition: Operator-based rules (equals, contains, etc.)
- color: Filter by cell background or font color
- top10: Top/bottom N items or percent */
  type: 'value' | 'condition' | 'color' | 'top10' | 'dynamic' | 'icon';
  /** For value filters: list of values to INCLUDE (show).
Unchecked values in the dropdown are excluded (hidden).
Include empty string or null to show blank cells. */
  values?: CellValue[];
  /** For value filters: explicitly include blank cells.
When present, takes precedence over inferring from values array. */
  includeBlanks?: boolean;
  /** For condition filters: one or two filter conditions.
When two conditions are present, conditionLogic determines how they combine. */
  conditions?: FilterCondition[];
  /** Logic for combining multiple conditions.
- 'and': Row must match ALL conditions
- 'or': Row must match ANY condition
Default: 'and' */
  conditionLogic?: 'and' | 'or';
  /** For color filters: filter by fill (background) or font color. */
  colorFilter?: {
    /**
     * Which color axis to filter on.
     *
     * Vocabulary matches Excel/ECMA-376: `'fill'` is the cell's background
     * fill color; `'font'` is the text color. (Renamed from `'background'`
     * to `'fill'` so the filter discriminator lines up with the rest of the
     * filter/sort surface and the harness probe.)
     */
    type: 'fill' | 'font';
    /** Hex color to match (e.g., '#ff0000') */
    color: string;
  };
  /** For top/bottom N filters: show only the highest or lowest values. */
  topBottom?: {
    /** Show top values or bottom values */
    type: 'top' | 'bottom';
    /** Number of items or percentage */
    count: number;
    /** Whether count is number of items or percentage */
    by: 'items' | 'percent' | 'sum';
  };
  /** For dynamic filters: a pre-defined rule resolved against live data.
Examples: above average, below average, today, this month, etc. */
  dynamicFilter?: {
    /** The dynamic filter rule to apply */
    rule: DynamicFilterRule;
  };
  /** For icon filters: filter by conditional formatting icon.
Requires an icon set CF rule on the column. Rows are shown only if
the evaluated icon matches the specified set + index. */
  iconFilter?: {
    /** Icon set name (e.g. "3Arrows", "4Rating") */
    iconSet: string;
    /** Icon index within the set (0-based) */
    iconIndex: number;
  };
}

ColumnMapping

Column mapping for a sheet data binding.

type ColumnMapping = {
  /** Column index to write to (0-indexed) */
  columnIndex: number;
  /** JSONPath or field name to extract from data */
  dataPath: string;
  /** Optional transform formula (receives value as input) */
  transform?: string;
  /** Header text (if headerRow >= 0) */
  headerText?: string;
}

ComboBoxControl

ComboBox control - dropdown selection linked to cell. NO local "selectedIndex" state - value lives in cell. Cell stores the selected VALUE (string), not the index. Data flow: 1. Render: Read from cell → find matching item index 2. Select: Write to cell → `store.setCellValueById(linkedCellId, selectedItem)` 3. EventBus fires → component re-renders with new selection Items can be: - Static: `items: ['Option A', 'Option B', 'Option C']` - Dynamic: `itemsSourceRef: { startId: 'abc', endId: 'xyz' }` (range of cells)

type ComboBoxControl = {
  type: 'comboBox';
  /** REQUIRED - Cell that holds the selected value.
Uses CellId for stability across row/col insert/delete.

Stores the selected item VALUE (string), not index.
This makes formulas like =VLOOKUP(A1, ...) work naturally. */
  linkedCellId: CellId;
  /** Static items list.
Use this for fixed options that don't change. */
  items?: string[];
  /** Dynamic items from a cell range.
Uses IdentityRangeRef (CellId-based) for stability.
Range values are read at render time.

If both `items` and `itemsSourceRef` are set, `itemsSourceRef` takes precedence. */
  itemsSourceRef?: IdentityRangeRef;
  /** Placeholder text when no value is selected. */
  placeholder?: string;
  /** Whether to allow typing to filter items.
Default: true */
  filterable?: boolean;
}

Comment

type Comment = {
  id: string;
  cellRef: string;
  author: string;
  authorId?: string;
  authorEmail?: string;
  content: string | null;
  runs: RichTextRun[];
  threadId: string | null;
  parentId: string | null;
  personId?: string;
  resolved?: boolean;
  timestamp?: string;
  createdAt: number | null;
  modifiedAt: number | null;
  xrUid?: string;
  shapeId?: number;
  extLstXml?: string;
  contentType?: CommentContentType;
  mentions?: CommentMention[];
  commentType: CommentType;
  visible?: boolean;
  noteHeight?: number;
  noteWidth?: number;
}

CommentContentType

Distinguishes plain text comments from those containing @mentions.

type CommentContentType = 'plain' | 'mention'

CommentMention

A mention of a user within a comment's rich text content.

type CommentMention = {
  displayText: string;
  userId: string;
  email?: string;
  startIndex: number;
  length: number;
}

CommentType

Whether a comment is a legacy note or a modern threaded comment.

type CommentType = 'note' | 'threadedComment'

CommentUpdate

Options for updating an existing comment via `comments.update()`.

type CommentUpdate = {
  /** New plain-text content for the comment. */
  text?: string;
  /** @mentions to embed in the comment (implies content_type = Mention). */
  mentions?: CommentMention[];
}

CompoundLine

Compound line type for multi-line strokes. Maps to ST_CompoundLine (ECMA-376, dml-main.xsd). Uses camelCase variants; bridge uses PascalCase.

type CompoundLine = 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri'

CompoundLineStyle

Compound line style.

type CompoundLineStyle = 'single' | 'double' | 'thickThin' | 'thinThick' | 'triple'

ComputedConnector

Computed connector between two nodes.

type ComputedConnector = {
  /** Source node ID */
  fromNodeId: NodeId;
  /** Target node ID */
  toNodeId: NodeId;
  /** Connector type */
  connectorType: ConnectorType;
  /** Path data for rendering */
  path: ConnectorPath;
  /** Stroke color (CSS color string) */
  stroke: string;
  /** Stroke width in pixels */
  strokeWidth: number;
  /** Arrow head at start of connector */
  arrowStart?: ArrowHead;
  /** Arrow head at end of connector */
  arrowEnd?: ArrowHead;
}

ComputedLayout

Computed layout result (runtime cache, NOT persisted to Yjs). This is calculated by layout algorithms and cached by the bridge. Invalidated whenever the diagram structure or styling changes. Layout computation is expensive, so this cache avoids recalculating positions on every render.

type ComputedLayout = {
  /** Computed shape positions and styles for each node */
  shapes: ComputedShape[];
  /** Computed connector paths between nodes */
  connectors: ComputedConnector[];
  /** Overall bounds of the rendered diagram */
  bounds: { width: number; height: number };
  /** Version number, incremented on each layout change */
  version: number;
}

ComputedShape

Computed shape position and style for a single node. Contains all information needed to render a node's shape.

type ComputedShape = {
  /** The node this shape represents */
  nodeId: NodeId;
  /** Shape type to render */
  shapeType: SmartArtShapeType;
  /** X position in pixels (relative to diagram origin) */
  x: number;
  /** Y position in pixels (relative to diagram origin) */
  y: number;
  /** Width in pixels */
  width: number;
  /** Height in pixels */
  height: number;
  /** Rotation angle in degrees */
  rotation: number;
  /** Fill color (CSS color string) */
  fill: string;
  /** Stroke/border color (CSS color string) */
  stroke: string;
  /** Stroke width in pixels */
  strokeWidth: number;
  /** Text content to display */
  text: string;
  /** Text styling */
  textStyle: TextStyle;
  /** Visual effects (shadow, glow, etc.) */
  effects: ShapeEffects;
}

ConditionalFormat

A conditional format definition — associates rules with cell ranges. This is the public API type. The kernel stores additional internal fields (CellIdRange for CRDT-safe structure change handling) that are resolved to position-based ranges before being returned through the API.

type ConditionalFormat = {
  /** Unique format identifier. */
  id: string;
  /** Sheet this format belongs to. */
  sheetId?: string;
  /** Whether this CF was created from a pivot table. */
  pivot?: boolean;
  /** Cell ranges this format applies to. */
  ranges: CellRange[];
  /** CellId-based range identities for CRDT-safe tracking. */
  rangeIdentities?: { topLeftCellId: string; bottomRightCellId: string }[];
  /** Rules to evaluate (sorted by priority). */
  rules: CFRule[];
}

ConditionalFormatUpdate

Update payload for a conditional format.

type ConditionalFormatUpdate = {
  /** Replace the rules array. */
  rules?: CFRule[];
  /** Replace the ranges this format applies to. */
  ranges?: CellRange[];
  /** Set stopIfTrue on all rules in this format. */
  stopIfTrue?: boolean;
}

ConnectorHandle

type ConnectorHandle = {
  /** Update connector routing, endpoints, fill, outline. ConnectorConfig pending — uses generic record. */
  update(props: Record<string, unknown>): Promise<void>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<ConnectorHandle>;;
  getData(): Promise<ConnectorObject>;;
}

ConnectorObject

Connector floating object. A line or connector shape that links two objects (or floats freely). Connectors have optional arrowheads and connection site bindings.

type ConnectorObject = {
  type: 'connector';
  /** Connector shape preset (e.g., straightConnector1, bentConnector3) */
  shapeType: ShapeType;
  /** Start connection binding (which shape and site index) */
  startConnection?: { shapeId: string; siteIndex: number };
  /** End connection binding (which shape and site index) */
  endConnection?: { shapeId: string; siteIndex: number };
  /** Fill configuration */
  fill?: ObjectFill;
  /** Outline/stroke configuration (includes arrowheads) */
  outline?: ShapeOutline;
}

ConnectorPath

Path data for rendering a connector.

type ConnectorPath = {
  /** Path type */
  type: 'line' | 'bezier' | 'polyline';
  /** Points along the path */
  points: Array<{ x: number; y: number }>;
  /** Control points for bezier curves */
  controlPoints?: Array<{ x: number; y: number }>;
}

ConnectorType

Type of connector line between nodes.

type ConnectorType = 'straight' | 'elbow' | 'curved' | 'none'

CopyFromOptions

Options for Range.copyFrom() operation.

type CopyFromOptions = {
  /** What to copy — defaults to 'all'. */
  copyType?: CopyType;
  /** Skip blank source cells (preserve target values where source is empty). */
  skipBlanks?: boolean;
  /** Transpose rows ↔ columns during copy. */
  transpose?: boolean;
}

CopyType

Specifies what data to copy in a range copy operation. Maps to the spreadsheet range-copy mode.

type CopyType = 'all' | 'formulas' | 'values' | 'formats'

CreateBindingConfig

Configuration for creating a sheet data binding.

type CreateBindingConfig = {
  /** Connection providing the data */
  connectionId: string;
  /** Maps data fields to columns */
  columnMappings: ColumnMapping[];
  /** Auto-insert/delete rows to match data length (default: true) */
  autoGenerateRows?: boolean;
  /** Row index for headers (-1 = no header row, default: 0) */
  headerRow?: number;
  /** First row of data (0-indexed, default: 1) */
  dataStartRow?: number;
  /** Preserve header row formatting on refresh (default: true) */
  preserveHeaderFormatting?: boolean;
}

CreateCheckboxOptions

Options for creating a checkbox control.

type CreateCheckboxOptions = {
  /** Sheet to create in */
  sheetId: SheetId;
  /** Anchor position (row, col, offsets) - converted to CellId internally */
  anchor: { row: number; col: number; xOffset?: number; yOffset?: number };
  /** Cell to link (row, col) - converted to CellId internally */
  linkedCell: { row: number; col: number };
  /** Optional label */
  label?: string;
  /** Optional size override */
  width?: number;
  height?: number;
}

CreateComboBoxOptions

Options for creating a comboBox control.

type CreateComboBoxOptions = {
  /** Sheet to create in */
  sheetId: SheetId;
  /** Anchor position */
  anchor: { row: number; col: number; xOffset?: number; yOffset?: number };
  /** Cell to link for selected value */
  linkedCell: { row: number; col: number };
  /** Static items list */
  items?: string[];
  /** Dynamic items source range (row/col based, converted to CellId) */
  itemsSource?: {
    startRow: number;
    startCol: number;
    endRow: number;
    endCol: number;
  };
  /** Placeholder text */
  placeholder?: string;
  /** Optional size override */
  width?: number;
  height?: number;
}

CreateDataTableOptions

Persistent Data Table creation options. `tableRange` is the full anchor-inclusive table selection. The worksheet is implied by the Worksheet API instance.

type CreateDataTableOptions = {
  /** Full A1 range selected for the Data Table, including formula/header cells. */
  tableRange: string;
  /** Excel row input cell. It receives top-row header values. */
  rowInputCell?: string | null;
  /** Excel column input cell. It receives left-column header values. */
  colInputCell?: string | null;
}

CreateDataTableResult

Result of creating a persistent Data Table region.

type CreateDataTableResult = {
  regionId: string;
  tableRange: string;
  bodyRange: string;
  rowInputCell?: string | null;
  colInputCell?: string | null;
  rowsComputed: number;
  colsComputed: number;
  cellCount: number;
}

CreateDrawingOptions

Options for creating a new drawing object.

type CreateDrawingOptions = {
  /** Optional name for the drawing object */
  name?: string;
  /** Alt text for accessibility */
  altText?: string;
  /** Whether the drawing is locked */
  locked?: boolean;
  /** Whether the drawing appears in print */
  printable?: boolean;
  /** Initial background color */
  backgroundColor?: string;
  /** Initial tool settings */
  toolState?: Partial<InkToolState>;
}

CreateNamesFromSelectionOptions

Options for creating named ranges from row/column labels in a selection.

type CreateNamesFromSelectionOptions = {
  /** Create names from labels in the top row of the selection. */
  top?: boolean;
  /** Create names from labels in the left column of the selection. */
  left?: boolean;
  /** Create names from labels in the bottom row of the selection. */
  bottom?: boolean;
  /** Create names from labels in the right column of the selection. */
  right?: boolean;
}

CreateNamesResult

Result of a create-names-from-selection operation.

type CreateNamesResult = {
  /** Number of names successfully created. */
  success: number;
  /** Number of names skipped (already exist or invalid). */
  skipped: number;
}

CreateSparklineGroupOptions

Options for creating a sparkline group.

type CreateSparklineGroupOptions = {
  /** Whether data is in rows (true) or columns (false) */
  dataInRows?: boolean;
  /** Shared visual settings */
  visual?: Partial<SparklineVisualSettings>;
  /** Shared axis settings */
  axis?: Partial<SparklineAxisSettings>;
}

CreateSparklineOptions

Options for creating a new sparkline.

type CreateSparklineOptions = {
  /** Whether data is in rows (true) or columns (false) */
  dataInRows?: boolean;
  /** Visual settings override */
  visual?: Partial<SparklineVisualSettings>;
  /** Axis settings override */
  axis?: Partial<SparklineAxisSettings>;
}

CreateWordArtInput

Configuration for creating new text effects.

type CreateWordArtInput = {
  /** Text content. */
  text: string;
  /** Text warp preset. Missing values are filled by kernel defaults. */
  warpPreset?: TextWarpPreset;
  /** Warp adjustment values. */
  warpAdjustments?: AdjustmentValues;
  /** Text fill configuration. Missing values are filled by kernel defaults. */
  fill?: WordArtFill;
  /** Text outline configuration. Missing values are filled by kernel defaults. */
  outline?: WordArtOutline;
  /** Text effects configuration. Missing values are filled by kernel defaults. */
  effects?: TextEffects;
  /** Visual text-effect configuration overrides. */
  wordArt?: Partial<WordArtObjectConfig>;
  /** X position in pixels. */
  x?: number;
  /** Y position in pixels. */
  y?: number;
  /** Width in pixels. */
  width?: number;
  /** Height in pixels. */
  height?: number;
  /** Display name. */
  name?: string;
}

CreateWorkbookLinkInput

type CreateWorkbookLinkInput = {
  linkId?: LinkId;
  expectedWorkbookId?: WorkbookId | null;
  target: PersistedLinkTarget;
  displayName: string;
  sourceKind: WorkbookLinkSourceKind;
  importedExcelIdentity?: ImportedExternalLinkIdentity;
  materializedCacheMetadata?: AuthorizedMaterializedCacheMetadata;
}

CrossFilterMode

ST_SlicerCacheCrossFilter mode. Canonical source: compute-types.gen.ts

type CrossFilterMode = 'none' | 'showItemsWithDataAtTop' | 'showItemsWithNoData'

CultureInfo

Complete culture information for formatting numbers, dates, and currencies. All properties are required - no partial cultures allowed. Use the culture registry to get complete CultureInfo objects. @example ```typescript const culture = getCulture('de-DE'); // culture.decimalSeparator === ',' // culture.thousandsSeparator === '.' // culture.monthNames[0] === 'Januar' ```

type CultureInfo = {
  /** IETF language tag (e.g., 'en-US', 'de-DE', 'ja-JP').
This is the key used to look up the culture in the registry. */
  name: string;
  /** Human-readable display name (e.g., 'English (United States)').
Used in UI dropdowns. */
  displayName: string;
  /** Native name in the culture's own language (e.g., 'Deutsch (Deutschland)'). */
  nativeName: string;
  /** ISO 639-1 two-letter language code (e.g., 'en', 'de', 'ja'). */
  twoLetterLanguageCode: string;
  /** Decimal separator character (e.g., '.' for en-US, ',' for de-DE). */
  decimalSeparator: string;
  /** Thousands/grouping separator (e.g., ',' for en-US, '.' for de-DE, ' ' for fr-FR). */
  thousandsSeparator: string;
  /** Negative sign (usually '-'). */
  negativeSign: string;
  /** Positive sign (usually '+' or ''). */
  positiveSign: string;
  /** Pattern for negative numbers. */
  negativeNumberPattern: NegativeNumberPattern;
  /** Number of digits per group (usually 3).
Some cultures use variable grouping (e.g., Indian: 3, then 2, 2, 2...).
For simplicity, we use a single value in v1. */
  numberGroupSize: number;
  /** Percent symbol (usually '%'). */
  percentSymbol: string;
  /** Per mille symbol (‰). */
  perMilleSymbol: string;
  /** Pattern for positive percentages. */
  percentPositivePattern: PercentPositivePattern;
  /** Pattern for negative percentages. */
  percentNegativePattern: PercentNegativePattern;
  /** Default currency symbol for this culture (e.g., '$', '€', '¥'). */
  currencySymbol: string;
  /** ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY'). */
  currencyCode: string;
  /** Pattern for positive currency values. */
  currencyPositivePattern: CurrencyPositivePattern;
  /** Pattern for negative currency values. */
  currencyNegativePattern: CurrencyNegativePattern;
  /** Number of decimal digits for currency (e.g., 2 for USD, 0 for JPY). */
  currencyDecimalDigits: number;
  /** Date separator (e.g., '/' for en-US, '.' for de-DE). */
  dateSeparator: string;
  /** Time separator (e.g., ':'). */
  timeSeparator: string;
  /** Short date pattern (e.g., 'M/d/yyyy' for en-US, 'dd.MM.yyyy' for de-DE).
Used for format code interpretation. */
  shortDatePattern: string;
  /** Long date pattern (e.g., 'dddd, MMMM d, yyyy'). */
  longDatePattern: string;
  /** Short time pattern (e.g., 'h:mm tt' for en-US, 'HH:mm' for de-DE). */
  shortTimePattern: string;
  /** Long time pattern (e.g., 'h:mm:ss tt' for en-US, 'HH:mm:ss' for de-DE). */
  longTimePattern: string;
  /** AM designator (e.g., 'AM' for en-US, '' for 24-hour cultures). */
  amDesignator: string;
  /** PM designator (e.g., 'PM' for en-US, '' for 24-hour cultures). */
  pmDesignator: string;
  /** First day of the week (0 = Sunday, 1 = Monday). */
  firstDayOfWeek: DayOfWeek;
  /** Full month names (12 entries, January = index 0). */
  monthNames: readonly [
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
  ];
  /** Abbreviated month names (12 entries, Jan = index 0). */
  abbreviatedMonthNames: readonly [
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
    string,
  ];
  /** Full day names (7 entries, Sunday = index 0). */
  dayNames: readonly [string, string, string, string, string, string, string];
  /** Abbreviated day names (7 entries, Sun = index 0). */
  abbreviatedDayNames: readonly [string, string, string, string, string, string, string];
  /** Shortest day names (7 entries, typically 1-2 letters).
Used in narrow calendar UIs. */
  shortestDayNames: readonly [string, string, string, string, string, string, string];
  /** String for TRUE value (e.g., 'TRUE', 'WAHR', 'VRAI'). */
  trueString: string;
  /** String for FALSE value (e.g., 'FALSE', 'FALSCH', 'FAUX'). */
  falseString: string;
  /** List separator (e.g., ',' for en-US, ';' for de-DE).
This affects function argument separators in formulas. */
  listSeparator: string;
}

CurrencyNegativePattern

Currency negative pattern (matches .NET NumberFormatInfo). Determines how negative currency values are displayed. 0 = ($n) - en-US accounting 1 = -$n - en-US standard 2 = $-n 3 = $n- 4 = (n$) 5 = -n$ 6 = n-$ 7 = n$- 8 = -n $ - de-DE 9 = -$ n 10 = n $- 11 = $ n- 12 = $ -n 13 = n- $ 14 = ($ n) 15 = (n $)

type CurrencyNegativePattern = | 0
  | 1
  | 2
  | 3
  | 4
  | 5
  | 6
  | 7
  | 8
  | 9
  | 10
  | 11
  | 12
  | 13
  | 14
  | 15

CurrencyPositivePattern

Currency positive pattern (matches .NET NumberFormatInfo). Determines where the currency symbol appears relative to the number. 0 = $n (symbol before, no space) - en-US 1 = n$ (symbol after, no space) 2 = $ n (symbol before, space) 3 = n $ (symbol after, space) - de-DE, fr-FR

type CurrencyPositivePattern = 0 | 1 | 2 | 3

CustomList

Custom Lists Types Type definitions for user-defined fill lists. Runtime constant (BUILT_IN_LISTS) has been moved to @mog-sdk/kernel/domain/fill/custom-lists. @see plans/active/excel-parity/10-FILL-AUTOFILL-PLAN.md

type CustomList = {
  /** Unique ID for the list */
  id: string;
  /** Display name for the list */
  name: string;
  /** The list values in order */
  values: string[];
  /** Whether this is a built-in list (cannot be deleted) */
  isBuiltIn?: boolean;
}

DataLabelConfig

Data label configuration (matches DataLabelData wire type)

type DataLabelConfig = {
  show: boolean;
  position?: | 'center'
    | 'insideEnd'
    | 'insideBase'
    | 'outsideEnd'
    | 'left'
    | 'right'
    | 'top'
    | 'bottom'
    | 'bestFit'
    | 'callout'
    | 'outside'
    | 'inside';
  format?: string;
  showValue?: boolean;
  showCategoryName?: boolean;
  /** @deprecated Use showCategoryName instead. Alias kept for legacy consumers. */
  showCategory?: boolean;
  showSeriesName?: boolean;
  showPercentage?: boolean;
  /** @deprecated Use showPercentage instead. Alias kept for legacy consumers. */
  showPercent?: boolean;
  showBubbleSize?: boolean;
  showLegendKey?: boolean;
  separator?: string;
  showLeaderLines?: boolean;
  text?: string;
  visualFormat?: ChartFormat;
  numberFormat?: string;
  /** Text orientation angle in degrees (-90 to 90) */
  textOrientation?: number;
  richText?: ChartFormatString[];
  /** Whether the label auto-generates text from data. */
  autoText?: boolean;
  /** Horizontal text alignment. */
  horizontalAlignment?: 'left' | 'center' | 'right' | 'justify' | 'distributed';
  /** Vertical text alignment. */
  verticalAlignment?: 'top' | 'middle' | 'bottom' | 'justify' | 'distributed';
  /** Whether the number format is linked to the source data cell format. */
  linkNumberFormat?: boolean;
  /** Callout shape type (e.g., 'rectangle', 'roundRectangle', 'wedgeRoundRectCallout'). */
  geometricShapeType?: string;
  /** Formula-based label text. */
  formula?: string;
  /** X position in points (read-only, populated from render engine). */
  left?: number;
  /** Y position in points (read-only, populated from render engine). */
  top?: number;
  /** Height in points (read-only, populated from render engine). */
  height?: number;
  /** Width in points (read-only, populated from render engine). */
  width?: number;
  /** Leader line formatting configuration. */
  leaderLinesFormat?: ChartLeaderLinesFormat;
}

DataSourceType

The type of data source backing a pivot table. Mirrors the workbook data source type.

type DataSourceType = 'range' | 'table' | 'external'

DataTableConfig

Data table configuration (matches ChartDataTableData wire type).

type DataTableConfig = {
  showHorzBorder?: boolean;
  showVertBorder?: boolean;
  showOutline?: boolean;
  showKeys?: boolean;
  format?: ChartFormat;
  /** Whether to show legend keys in the data table */
  showLegendKey?: boolean;
  /** Whether the data table is visible */
  visible?: boolean;
}

DataTableResult

Result of Data Table operation.

type DataTableResult = {
  /** 2D array of computed results.
results[rowIndex][colIndex] is the value when:
- rowInputCell = rowValues[rowIndex]
- colInputCell = colValues[colIndex] */
  results: CellValue[][];
  /** Total number of cells computed. */
  cellCount: number;
  /** Time taken in milliseconds. */
  elapsedMs: number;
  /** Whether the operation was cancelled. */
  cancelled?: boolean;
}

DatePeriod

Date periods for timePeriod rules.

type DatePeriod = | 'yesterday'
  | 'today'
  | 'tomorrow'
  | 'last7Days'
  | 'lastWeek'
  | 'thisWeek'
  | 'nextWeek'
  | 'lastMonth'
  | 'thisMonth'
  | 'nextMonth'
  | 'lastQuarter'
  | 'thisQuarter'
  | 'nextQuarter'
  | 'lastYear'
  | 'thisYear'
  | 'nextYear'

DateUnit

Unit for date-based series fills.

type DateUnit = 'day' | 'weekday' | 'month' | 'year'

DayOfWeek

Culture/Locale types for internationalized number, date, and currency formatting. Stream G: Culture & Localization Design principles: 1. CultureInfo is immutable and complete - no partial definitions 2. Culture is workbook-level state (persisted in WorkbookSettings.culture) 3. Format codes are culture-agnostic; culture applies at render time 4. Uses IETF language tags (en-US, de-DE) not Windows locale IDs

type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6

DeleteCellsReceipt

Receipt for a deleteCellsWithShift mutation.

type DeleteCellsReceipt = {
  kind: 'deleteCells';
  sheetId: string;
  range: { startRow: number; startCol: number; endRow: number; endCol: number };
  direction: 'left' | 'up';
}

DeleteColumnsReceipt

Receipt for a deleteColumns mutation.

type DeleteColumnsReceipt = {
  kind: 'deleteColumns';
  sheetId: string;
  deletedAt: number;
  count: number;
}

DeleteRowsReceipt

Receipt for a deleteRows mutation.

type DeleteRowsReceipt = {
  kind: 'deleteRows';
  sheetId: string;
  deletedAt: number;
  count: number;
}

DelimiterNode

Delimiter - <m:d> Parentheses, brackets, braces, etc.

type DelimiterNode = {
  type: 'd';
  /** Beginning character (default '(') */
  begChr?: string;
  /** Separator character (default '|') */
  sepChr?: string;
  /** Ending character (default ')') */
  endChr?: string;
  /** Grow with content */
  grow?: boolean;
  /** Shape: 'centered' or 'match' */
  shp?: 'centered' | 'match';
  /** Content elements (separated by sepChr) */
  e: MathNode[][];
}

Direction

Cardinal directions for keyboard navigation and commit actions.

type Direction = 'up' | 'down' | 'left' | 'right'

DocumentId

type DocumentId = string

DocumentProperties

type DocumentProperties = {
  title?: string;
  creator?: string;
  description?: string;
  subject?: string;
  created?: string;
  modified?: string;
  lastModifiedBy?: string;
  category?: string;
  keywords?: string;
  company?: string;
  manager?: string;
}

DrawingHandle

type DrawingHandle = {
  addStroke(stroke: InkStroke): Promise<void>;;
  eraseStrokes(strokeIds: StrokeId[]): Promise<void>;;
  clearStrokes(): Promise<void>;;
  moveStrokes(strokeIds: StrokeId[], dx: number, dy: number): Promise<void>;;
  transformStrokes(strokeIds: StrokeId[], transform: StrokeTransformParams): Promise<void>;;
  findStrokesAtPoint(x: number, y: number, tolerance?: number): Promise<StrokeId[]>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<DrawingHandle>;;
  getData(): Promise<DrawingObject>;;
}

DrawingObject

Drawing object floating on the spreadsheet. Extends FloatingObjectBase to integrate with the existing floating object system (selection, drag, resize, z-order, etc.). CRDT-SAFE DESIGN: - Strokes stored as Map<StrokeId, InkStroke> to avoid array ordering conflicts - Uses CellId for anchors (survives row/col insert/delete) - Y.Map under the hood for concurrent editing support

type DrawingObject = {
  type: 'drawing';
  /** Strokes in this drawing, keyed by StrokeId.

Using Map<StrokeId, InkStroke> instead of array for CRDT safety:
- No ordering conflicts when concurrent users add strokes
- O(1) lookup/delete by ID
- Stable references across edits

Render order is determined by stroke createdAt timestamps. */
  strokes: Map<StrokeId, InkStroke>;
  /** Current tool settings for this drawing.
Persisted per-drawing to remember user preferences. */
  toolState: InkToolState;
  /** Recognition results for strokes in this drawing.
Maps from a "recognition ID" to the result.
A recognition can be:
- A shape recognized from one or more strokes
- Text recognized from handwriting strokes */
  recognitions: Map<string, RecognitionResult>;
  /** Background color of the drawing canvas.
- undefined = transparent (shows sheet grid)
- CSS color string = solid background */
  backgroundColor?: string;
}

DynamicFilterRule

Dynamic filter rule — pre-defined filter rules that resolve against live data (e.g. above average, date-relative). Mirrors the Rust DynamicFilterRule enum in compute-core.

type DynamicFilterRule = | 'aboveAverage'
  | 'belowAverage'
  | 'today'
  | 'yesterday'
  | 'tomorrow'
  | 'thisWeek'
  | 'lastWeek'
  | 'nextWeek'
  | 'thisMonth'
  | 'lastMonth'
  | 'nextMonth'
  | 'thisQuarter'
  | 'lastQuarter'
  | 'nextQuarter'
  | 'thisYear'
  | 'lastYear'
  | 'nextYear'

ElseClause

OOXML else-clause within a choose element. Contains layout children that are used when no if-clause condition evaluates to true. Acts as the default/fallback branch. @see ECMA-376 Section 21.4.2.11 else (Else)

type ElseClause = {
  /** Optional name for this else-clause. */
  name: string;
  /** Child layout elements included when no if-clause matches. */
  children: readonly LayoutNodeChild[];
}

EmptyCellDisplay

type EmptyCellDisplay = "gaps" | "zero" | "connect"

EnterKeyDirection

Direction for enter key movement after committing an edit. Issue 8: Settings Panel

type EnterKeyDirection = 'down' | 'right' | 'up' | 'left' | 'none'

EqArrayNode

Equation Array - <m:eqArr> Vertically aligned equations

type EqArrayNode = {
  type: 'eqArr';
  /** Base justification */
  baseJc?: 'top' | 'center' | 'bottom';
  /** Maximum distribution */
  maxDist?: boolean;
  /** Object distribution */
  objDist?: boolean;
  /** Row spacing rule */
  rSpRule?: 0 | 1 | 2 | 3 | 4;
  /** Row spacing value */
  rSp?: number;
  /** Array rows */
  e: MathNode[][];
}

Equation

Main equation data model

type Equation = {
  /** Unique equation identifier */
  id: EquationId;
  /** OMML XML string - the canonical storage format.
This is what gets written to XLSX files.
Example: <m:oMath><m:f><m:num>...</m:num><m:den>...</m:den></m:f></m:oMath> */
  omml: string;
  /** LaTeX source (optional, for display/editing).
Not stored in XLSX - regenerated from OMML on import if needed. */
  latex?: string;
  /** Parsed AST (computed, not persisted).
Used for rendering. Regenerated from OMML when needed. */
  ast?: MathNode;
  /** Cached rendered image as data URL.
Invalidated when equation changes. */
  _cachedImageData?: string;
  /** Style options */
  style: EquationStyle;
}

EquationConfig

Configuration for creating a new equation.

type EquationConfig = {
  /** LaTeX source for the equation. */
  latex: string;
  /** Anchor cell as `{row, col}`. When set, `x`/`y` are offsets from this
cell instead of from cell `(0, 0)`. */
  anchorCell?: { row: number; col: number };
  /** X position in pixels. */
  x?: number;
  /** Y position in pixels. */
  y?: number;
  /** Width in pixels. */
  width?: number;
  /** Height in pixels. */
  height?: number;
  /** Equation style options. */
  style?: EquationStyleConfig;
}

EquationDefaults

Fully normalized equation defaults used by Worksheet equation creation.

type EquationDefaults = {
  /** Fully populated default equation style. */
  style: EquationStyle;
  /** Default equation object width in pixels. */
  width: number;
  /** Default equation object height in pixels. */
  height: number;
}

EquationHandle

type EquationHandle = {
  update(props: EquationUpdates): Promise<void>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<EquationHandle>;;
  getData(): Promise<EquationObject>;;
}

EquationId

Unique identifier for an equation

type EquationId = string & { readonly __brand: 'EquationId' }

EquationJustification

Equation justification within its bounding box

type EquationJustification = 'left' | 'center' | 'right' | 'centerGroup'

EquationObject

Equation floating object. Contains a mathematical equation rendered as a floating object.

type EquationObject = {
  type: 'equation';
  /** The equation data */
  equation: Equation;
}

EquationStyle

Equation rendering style options

type EquationStyle = {
  /** Math font family */
  fontFamily: MathFont;
  /** Base font size in points */
  fontSize: number;
  /** Text color (CSS color string) */
  color: string;
  /** Background color (CSS color string, 'transparent' for none) */
  backgroundColor: string;
  /** Justification */
  justification: EquationJustification;
  /** Display mode (block) vs inline mode */
  displayMode: boolean;
  /** Use small fractions (numerator/denominator same size as surrounding) */
  smallFractions: boolean;
}

EquationStyleConfig

Styling overrides for an equation. Missing fields are filled by kernel defaults.

type EquationStyleConfig = Partial<EquationStyle>

EquationUpdates

Updates for an existing equation.

type EquationUpdates = {
  /** Updated LaTeX source. */
  latex?: string;
  /** Updated OMML XML. */
  omml?: string;
  /** Updated style options. */
  style?: Partial<EquationStyleConfig>;
}

ErrorBarConfig

Error bar configuration for series (matches ErrorBarData wire type)

type ErrorBarConfig = {
  visible?: boolean;
  direction?: string;
  barType?: string;
  valueType?: string;
  value?: number;
  noEndCap?: boolean;
  lineFormat?: ChartLineFormat;
}

ExecuteOptions

Options for code execution via `workbook.executeCode()`.

type ExecuteOptions = {
  /** Maximum execution time in milliseconds */
  timeout?: number;
  /** Whether to run in a sandboxed environment */
  sandbox?: boolean;
}

FieldDef

Schema-Driven Initialization Types These types define how Yjs structures are specified declaratively. All creation, copying, and lazy-init is derived from schemas. ARCHITECTURE: Single Source of Truth - Field definitions are declared ONCE in a schema - createFromSchema() derives structure initialization - copyFromSchema() derives copy behavior - ensureLazyFields() derives migration behavior This eliminates: - Manual field enumeration in multiple places - Divergent copy vs init logic - Missing fields in new code paths @see plans/active/refactor/SCHEMA-DRIVEN-INITIALIZATION.md

type FieldDef = {
  /** The Yjs type or primitive indicator.
- 'Y.Map': Creates new Y.Map()
- 'Y.Array': Creates new Y.Array()
- 'Y.Text': Creates new Y.Text()
- 'primitive': Uses the default value directly */
  type: 'Y.Map' | 'Y.Array' | 'Y.Text' | 'primitive';
  /** Documentation of the value type for Y.Map and Y.Array.
Example: 'SerializedCellData' for cells map, 'number' for heights map.
This is for documentation only - TypeScript cannot enforce Yjs internals. */
  valueType?: string;
  /** Short name for CRDT storage efficiency (optional).
Used by Cell Data schema where 'raw' -> 'r', 'formula' -> 'f', etc.
If not specified, the long name (schema key) is used as-is.

This is for documentation/mapping purposes. The actual Yjs storage
uses the short name, while the API/runtime uses the long name (schema key). */
  shortName?: string;
  /** Whether this field is required during structure creation.
- true: Created by createFromSchema()
- false: Only created on demand or via lazyInit */
  required: boolean;
  /** Copy strategy for this field.
- 'deep': Deep copy (JSON.parse/stringify for plain objects, recursive for Yjs)
- 'shallow': Shallow reference copy (same object)
- 'skip': Don't copy this field (omit from result) */
  copy: 'deep' | 'shallow' | 'skip';
  /** Whether to auto-create this field if missing.
Used for migration: old documents may lack new fields.
ensureLazyFields() creates fields where lazyInit=true and field is missing. */
  lazyInit: boolean;
  /** Default value for primitive fields.
Only used when type='primitive'. */
  default?: unknown;
}

FillDirection

Direction of a fill operation relative to the source range.

type FillDirection = 'down' | 'right' | 'up' | 'left'

FillPatternType

Pattern type detected by the fill engine.

type FillPatternType = | 'copy'
  | 'linear'
  | 'growth'
  | 'date'
  | 'time'
  | 'weekday'
  | 'weekdayShort'
  | 'month'
  | 'monthShort'
  | 'quarter'
  | 'ordinal'
  | 'textWithNumber'
  | 'customList'

FillSeriesOptions

Options for the Fill Series dialog (Edit > Fill > Series).

type FillSeriesOptions = {
  direction: FillDirection;
  seriesType: 'linear' | 'growth' | 'date';
  stepValue: number;
  stopValue?: number;
  dateUnit?: DateUnit;
  trend?: boolean;
}

FillType

Fill type for shapes, text boxes, and connectors. Matches the Rust `FillType` enum in `domain-types`.

type FillType = 'solid' | 'gradient' | 'pattern' | 'pictureAndTexture' | 'none'

FilterByColorOptions

Options for {@link WorksheetFilters.byColor}. Excel/ECMA-376 vocabulary: `'fill'` matches the cell background fill color; `'font'` matches the cell font color. Both compare the resolved per-cell effective format (direct cell formatting; CF-derived colors are not yet supported — see plans/active/ux/filter/round-1/).

type FilterByColorOptions = {
  /** Whether to filter by background fill color or font color. */
  colorType: 'fill' | 'font';
  /** Hex color to match (e.g. '#FFFF00'). Case-insensitive. */
  color: string;
  /** Optional filter ID; defaults to the first auto-filter on the sheet. */
  filterId?: string;
}

FilterCondition

A single filter condition with operator and value(s). Used in condition filters where users specify rules like "greater than 100" or "contains 'error'".

type FilterCondition = {
  /** The comparison operator */
  operator: FilterOperator;
  /** Primary comparison value (not used for isBlank/isNotBlank) */
  value?: CellValue;
  /** Secondary value for 'between' operator (inclusive range) */
  value2?: CellValue;
}

FilterDetailInfo

Detailed filter information including resolved numeric range and column filters.

type FilterDetailInfo = {
  /** Filter ID */
  id: string;
  /** Filter kind. */
  filterKind: FilterKind;
  /** Resolved numeric range of the filter */
  range: { startRow: number; startCol: number; endRow: number; endCol: number };
  /** Per-column filter criteria, keyed by header cell ID */
  columnFilters: Record<string, ColumnFilterCriteria>;
  /** Table ID if this filter is associated with a table. */
  tableId?: string;
  /** Advanced Filter metadata, present for advanced filters. */
  advancedFilter?: AdvancedFilterDetailInfo;
}

FilterInfo

type FilterInfo = {
  /** Filter ID */
  id: string;
  /** Filter kind. */
  filterKind: FilterKind;
  /** The filtered range */
  range?: string;
  /** Per-column filter criteria */
  columns?: Record<string, unknown>;
  /** Table ID if this filter is associated with a table. */
  tableId?: string;
  /** Per-column filter criteria, keyed by column identifier. */
  columnFilters?: Record<string, unknown>;
}

FilterKind

Information about a filter applied to a sheet.

type FilterKind = 'autoFilter' | 'tableFilter' | 'advancedFilter'

FilterOperator

Filter operators for record triggers.

type FilterOperator = | 'equals'
  | 'not_equals'
  | 'contains'
  | 'starts_with'
  | 'ends_with'
  | 'greater_than'
  | 'greater_than_or_equals'
  | 'less_than'
  | 'less_than_or_equals'
  | 'in'
  | 'not_in'
  | 'is_null'
  | 'is_not_null'

FilterSortState

Sort state for a filter.

type FilterSortState = {
  /** Column index or header cell ID to sort by */
  column: string | number;
  /** Sort direction */
  direction: 'asc' | 'desc';
  /** Sort criteria (optional, for advanced sorting) */
  criteria?: any;
}

FilterState

API filter state — derived from Rust FilterState with A1-notation range.

type FilterState = {
  /** The range the auto-filter is applied to (A1 notation) */
  range: string;
  /** Per-column filter criteria, keyed by column identifier (string) */
  columnFilters: Record<string, ColumnFilterCriteria>;
}

FindInRangeOptions

Options for findInRange — range is provided as a separate method parameter.

type FindInRangeOptions = Omit<SearchOptions, 'range'>

FloatingObject

Union of all floating object types. Use type narrowing on the 'type' discriminator to access specific properties.

type FloatingObject = | PictureObject
  | TextBoxObject
  | ShapeObject
  | ConnectorObject
  | ChartObject
  | DrawingObject
  | EquationObject
  | SmartArtObject
  | OleObjectObject

FloatingObjectHandle

type FloatingObjectHandle = {
  /** Stable object ID. */
  id: string;
  /** Discriminator for type narrowing. */
  type: FloatingObjectKind;
  /** Move by delta. dx/dy are pixel offsets (relative).
Rust resolves to new cell anchor. */
  move(dx: number, dy: number): Promise<FloatingObjectMutationReceipt>;;
  /** Set absolute dimensions in pixels. */
  resize(width: number, height: number): Promise<FloatingObjectMutationReceipt>;;
  /** Set absolute rotation angle in degrees. */
  rotate(angle: number): Promise<void>;;
  /** Flip horizontally or vertically. */
  flip(axis: 'horizontal' | 'vertical'): Promise<void>;;
  bringToFront(): Promise<void>;;
  sendToBack(): Promise<void>;;
  bringForward(): Promise<void>;;
  sendBackward(): Promise<void>;;
  delete(): Promise<FloatingObjectRemoveReceipt>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<FloatingObjectHandle>;;
  /** Sync pixel bounds from scene graph. Null if not rendered yet. */
  getBounds(): ObjectBounds | null;;
  /** Full object data (async — reads from store). */
  getData(): Promise<FloatingObject>;;
}

FloatingObjectInfo

Summary information about a floating object (returned by listFloatingObjects).

type FloatingObjectInfo = {
  /** Unique object ID. */
  id: string;
  /** Object type discriminator. */
  type: FloatingObjectType;
  /** Optional display name. */
  name?: string;
  /** X position in pixels. */
  x: number;
  /** Y position in pixels. */
  y: number;
  /** Width in pixels. */
  width: number;
  /** Height in pixels. */
  height: number;
  /** Rotation angle in degrees. */
  rotation?: number;
  /** Flipped horizontally. */
  flipH?: boolean;
  /** Flipped vertically. */
  flipV?: boolean;
  /** Z-order index. */
  zIndex?: number;
  /** Whether the object is visible. */
  visible?: boolean;
  /** ID of the parent group (if this object is grouped). */
  groupId?: string;
  /** Anchor mode (twoCell/oneCell/absolute). */
  anchorType?: ObjectAnchorType;
  /** Alt text for accessibility. */
  altText?: string;
}

FloatingObjectKind

Object type discriminator. Used for type narrowing in union types. Extends CanvasObjectType (which is `string`) with a specific union for spreadsheet object types. This ensures backward compatibility: any code expecting FloatingObjectKind still gets the specific union, while CanvasObjectType-based code accepts it as a string. Storage-layer discriminant for floating objects. Mirrors Rust FloatingObjectKind. See also FloatingObjectType in api/types.ts (API-layer superset that adds 'wordart'). Note: 'slicer' is defined here for the FloatingObjectKind union, but the full SlicerConfig type is in contracts/src/slicers.ts because slicers have significant additional properties.

type FloatingObjectKind = | 'shape'
  | 'connector'
  | 'picture'
  | 'textbox'
  | 'chart'
  | 'camera'
  | 'equation'
  | 'smartart'
  | 'drawing'
  | 'oleObject'
  | 'formControl'
  | 'slicer'

FloatingObjectMutationReceipt

Receipt for a floating object creation or update mutation.

type FloatingObjectMutationReceipt = {
  domain: 'floatingObject';
  action: 'create' | 'update';
  id: string;
  object: FloatingObject;
  bounds: ObjectBounds;
}

FloatingObjectRemoveReceipt

Receipt for a floating object removal mutation.

type FloatingObjectRemoveReceipt = {
  domain: 'floatingObject';
  action: 'remove';
  id: string;
}

FloatingObjectType

Type discriminator for floating objects (API layer). Superset of FloatingObjectKind (12 storage-layer variants) + 'wordart' (API-only ergonomic alias). text-effect objects are stored as Textbox with word_art config; this type lets consumers reference them directly.

type FloatingObjectType = | 'shape'
  | 'connector'
  | 'picture'
  | 'textbox'
  | 'chart'
  | 'camera'
  | 'equation'
  | 'smartart'
  | 'drawing'
  | 'oleObject'
  | 'formControl'
  | 'slicer'
  | 'wordart'

FormControl

Union of all implemented form control types. Currently: Checkbox, Button, ComboBox Future: RadioButton, Slider, Spinner

type FormControl = CheckboxControl | ButtonControl | ComboBoxControl

FormControlAnchorUpdate

type FormControlAnchorUpdate = {
  row: number;
  col: number;
  xOffset?: number;
  yOffset?: number;
}

FormControlUpdate

type FormControlUpdate = Partial<Omit<FormControl, 'id' | 'type' | 'sheetId'>>

FormatChangeResult

Result of a format set/setRange operation.

type FormatChangeResult = {
  /** Number of cells whose formatting was changed */
  cellCount: number;
}

FormatEntry

Entry for batch format-values call.

type FormatEntry = {
  /** Cell value descriptor */
  value: { type: string; value?: unknown };
  /** Number format code (e.g., "#,##0.00") */
  formatCode: string;
}

FormulaA1

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.

type FormulaA1 = string & { readonly [formulaA1Brand]: true }

FormulaSyntaxValidationError

Result returned when formula syntax validation rejects an input. `errorPosition` is a zero-based character offset into the authored formula text, when the parser can locate one.

type FormulaSyntaxValidationError = {
  errorMessage: string;
  errorPosition?: number;
}

FractionNode

Fraction - <m:f> Numerator over denominator IMPORTANT: Uses `fractionType` field (NOT `type_`) Maps to OMML <m:fPr><m:type m:val="..."/></m:fPr>

type FractionNode = {
  type: 'f';
  /** Fraction type: bar (stacked), skw (skewed), lin (linear), noBar (no bar) */
  fractionType: 'bar' | 'skw' | 'lin' | 'noBar';
  /** Numerator */
  num: MathNode[];
  /** Denominator */
  den: MathNode[];
}

FunctionArgument

type FunctionArgument = {
  name: string;
  description: string;
  type: FunctionArgumentType;
  optional: boolean;
  repeating?: boolean;
}

FunctionArgumentType

Function Registry -- Lightweight metadata registry for Excel functions. Types remain here in contracts. Migrated from @mog/calculator.

type FunctionArgumentType = | 'number'
  | 'text'
  | 'logical'
  | 'reference'
  | 'array'
  | 'any'
  | 'date'

FunctionInfo

Information about a spreadsheet function (e.g., SUM, VLOOKUP).

type FunctionInfo = {
  /** Function name (uppercase, e.g., "SUM") */
  name: string;
  /** Description of what the function does */
  description: string;
  /** Function category (e.g., "Math & Trig", "Lookup & Reference") */
  category: string;
  /** Syntax example (e.g., "SUM(number1, [number2], ...)") */
  syntax: string;
  /** Usage examples */
  examples?: string[];
  /** Function argument metadata for IntelliSense/argument hints */
  arguments?: FunctionArgument[];
}

FunctionNode

Function - <m:func> Named function like sin, cos, lim

type FunctionNode = {
  type: 'func';
  /** Function name */
  fName: MathNode[];
  /** Argument */
  e: MathNode[];
}

GlowEffect

Glow effect configuration.

type GlowEffect = {
  /** Glow color (CSS color string) */
  color: string;
  /** Glow radius in pixels */
  radius: number;
  /** Opacity (0 = transparent, 1 = opaque) */
  opacity: number;
}

GoalSeekResult

Result of a goal seek operation.

type GoalSeekResult = {
  /** Whether a solution was found */
  found: boolean;
  /** The value found for the changing cell (if found) */
  value?: number;
  /** Number of iterations performed */
  iterations?: number;
}

GradientFill

Gradient fill configuration. Excel supports two gradient types: - linear: Color transitions along a line at a specified angle - path: Color transitions radially from a center point Gradients require at least 2 stops (start and end colors).

type GradientFill = {
  /** Type of gradient.
- 'linear': Straight line gradient at specified degree
- 'path': Radial/rectangular gradient from center point */
  type: 'linear' | 'path';
  /** Angle of linear gradient in degrees (0-359).
0 = left-to-right, 90 = bottom-to-top, etc.
Only used when type is 'linear'. */
  degree?: number;
  /** Center point for path gradients (0.0 to 1.0 for each axis).
{ left: 0.5, top: 0.5 } = center of cell.
Only used when type is 'path'. */
  center?: {
    left: number;
    top: number;
  };
  /** Gradient color stops.
Must have at least 2 stops. Stops should be ordered by position. */
  stops: GradientStop[];
}

GradientStop

GradientStop — Core contracts layer. Maps to CT_GradientStop (dml-main.xsd:1539) with position + color for cell formatting.

type GradientStop = {
  /** Position along the gradient (0.0 to 1.0).
0.0 = start of gradient, 1.0 = end of gradient. */
  position: number;
  /** Color at this position.
Can be absolute hex or theme reference. */
  color: string;
}

GroupCharNode

Group Character - <m:groupChr> Grouping symbol (underbrace, overbrace)

type GroupCharNode = {
  type: 'groupChr';
  /** Character (default is underbrace) */
  chr?: string;
  /** Position: 'top' or 'bot' */
  pos?: 'top' | 'bot';
  /** Vertical justification */
  vertJc?: 'top' | 'bot';
  /** Content */
  e: MathNode[];
}

GroupState

State of all row/column groups on a sheet.

type GroupState = {
  /** All row groups */
  rowGroups: any[];
  /** All column groups */
  columnGroups: any[];
  /** Maximum outline level for rows */
  maxRowLevel: number;
  /** Maximum outline level for columns */
  maxColLevel: number;
}

HeaderFooter

Header/footer configuration (OOXML CT_HeaderFooter).

type HeaderFooter = {
  oddHeader: string | null;
  oddFooter: string | null;
  evenHeader: string | null;
  evenFooter: string | null;
  firstHeader: string | null;
  firstFooter: string | null;
  differentOddEven: boolean;
  differentFirst: boolean;
  scaleWithDoc: boolean;
  alignWithMargins: boolean;
}

HeaderFooterImageInfo

Header/footer image metadata. Stores image references (path or data-URL), not binary blobs.

type HeaderFooterImageInfo = {
  position: HfImagePosition;
  /** Image source — resolved path for imported, or data-URL for API-created */
  src: string;
  /** Descriptive title */
  title: string;
  /** Width in points */
  widthPt: number;
  /** Height in points */
  heightPt: number;
}

HeatmapConfig

Heatmap configuration

type HeatmapConfig = {
  colorScale?: string[];
  showLabels?: boolean;
  minColor?: string;
  maxColor?: string;
}

HfImagePosition

Position of a header/footer image in the page layout.

type HfImagePosition = | 'leftHeader'
  | 'centerHeader'
  | 'rightHeader'
  | 'leftFooter'
  | 'centerFooter'
  | 'rightFooter'

HistogramConfig

Histogram configuration

type HistogramConfig = {
  binCount?: number;
  binWidth?: number;
  cumulative?: boolean;
}

IDisposable

Disposable — Handle-based lifecycle management. Three primitives for consumer-scoped stateful APIs: 1. `IDisposable` — interface for any resource with explicit lifecycle. 2. `DisposableBase` — abstract class with idempotent dispose + Symbol.dispose. 3. `DisposableStore` — tracks child disposables; disposing the store disposes all children. Supports TC39 Explicit Resource Management (TS 5.2+): using region = wb.viewport.createRegion(sheetId, bounds); // auto-disposed at block exit @see plans/archive/kernel/round-5/02-HANDLE-BASED-API-PATTERN.md

type IDisposable = {
  dispose(): void;;
  [Symbol.dispose](): void;;
}

IObjectBoundsReader

type IObjectBoundsReader = {
  /** Pixel bounds in document space. Null if object not in scene graph. */
  getBounds(objectId: string): ObjectBounds | null;;
  /** Union bounds of all objects in a group. */
  getGroupBounds(groupId: string): ObjectBounds | null;;
  /** Bounds for multiple objects. Skips objects not in scene graph. */
  getBoundsMany(objectIds: readonly string[]): Map<string, ObjectBounds>;;
}

IdentifiedCellData

Cell data enriched with stable CellId identity. Used by operations that need to reference cells by identity (not position), such as find-replace, clipboard, and cell relocation. The CellId is a CRDT-safe identifier that survives row/column insert/delete operations. Unlike `CellData` (position-implied), `IdentifiedCellData` includes explicit position and identity for flat iteration over non-empty cells in a range.

type IdentifiedCellData = {
  /** Stable cell identity (CRDT-safe, survives structural changes). */
  cellId: string;
  /** Row index (0-based). */
  row: number;
  /** Column index (0-based). */
  col: number;
  /** The computed cell value (null for empty cells). */
  value: CellValue | null;
  /** Formula text (e.g., "=A1+B1") when the cell contains a formula. */
  formulaText?: string;
  /** Pre-formatted display string (e.g., "$1,234.56" for a currency-formatted number). */
  displayString: string;
}

IdentityRangeRef

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.

type 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;
}

IfClause

OOXML if-clause within a choose element. Evaluates a condition based on the current iteration context: `func(arg)` `op` `val` Where: - `func` determines what value to compute (count, position, variable, etc.) - `arg` provides additional context for the function (used with 'var' function) - `op` is the comparison operator - `val` is the value to compare against The if-clause also supports axis/ptType navigation for context-sensitive evaluation (similar to forEach). @see ECMA-376 Section 21.4.2.14 if (If)

type IfClause = {
  /** Optional name for this if-clause. */
  name: string;
  /** Function to evaluate against the current context.
Determines what property of the context is being tested.

@see ST_FunctionType */
  func: ST_FunctionType;
  /** Argument for the function.
Primarily used with `func='var'` to specify which variable to look up.

@see ST_FunctionArgument */
  arg: ST_FunctionArgument;
  /** Comparison operator for the condition.

@see ST_FunctionOperator */
  op: ST_FunctionOperator;
  /** Value to compare the function result against.
For numeric functions (cnt, pos, depth, etc.), this is a number as string.
For variable functions (var), this is the expected variable value. */
  val: string;
  /** Axis type(s) for navigation context.
Used when the function needs to navigate the data model
(e.g., counting children along a specific axis).

@see ST_AxisType */
  axis: string;
  /** Point type filter(s) for navigation.

@see ST_ElementType */
  ptType: string;
  /** Maximum count of points for axis navigation.
0 means no limit. Defaults to 0. */
  cnt: number;
  /** Starting index (1-based) for axis navigation subsequence.
Defaults to 1. */
  st: number;
  /** Step value for axis navigation.
Defaults to 1. */
  step: number;
  /** Whether to hide the last sibling transition during navigation.
Defaults to true. */
  hideLastTrans: boolean;
  /** Child layout elements included when this condition is true. */
  children: readonly LayoutNodeChild[];
}

ImageColorType

Image color transform type.

type ImageColorType = 'automatic' | 'grayScale' | 'blackAndWhite' | 'watermark'

ImageExportFormat

Image export format options

type ImageExportFormat = 'png' | 'jpeg' | 'svg'

ImageExportOptions

Image export options

type ImageExportOptions = {
  /** Image format (default: 'png') */
  format?: ImageExportFormat;
  /** Pixel ratio for higher resolution (default: 2) */
  pixelRatio?: number;
  /** Background color (default: '#ffffff') */
  backgroundColor?: string;
  /** Target width in pixels (default: 640) */
  width?: number;
  /** Target height in pixels (default: 480) */
  height?: number;
  /** JPEG quality 0-1 (default: 0.92, only used when format is 'jpeg') */
  quality?: number;
  /** Fitting mode (default: 'fill') */
  fittingMode?: ImageFittingMode;
}

ImageFittingMode

Image fitting mode for exports: - 'fill': scale the chart to fill the entire target canvas (may crop) - 'fit': scale the chart to fit within the target dimensions (preserves aspect ratio) - 'fitAndCenter': same as 'fit' but centers the chart within the target canvas

type ImageFittingMode = 'fill' | 'fit' | 'fitAndCenter'

ImportedExternalLinkIdentity

type ImportedExternalLinkIdentity = {
  excelOrdinal: number;
  workbookRelId: string;
  partName: string;
  externalBookRid?: string;
  target?: string;
  targetMode?: 'External' | 'Internal';
}

InkPoint

A single point in a stroke with pressure and tilt support. Coordinates are in local drawing object space (pixels relative to drawing object bounds). Transform to sheet coordinates happens at render time. Pressure and tilt are normalized to [0, 1] ranges for consistent rendering regardless of input device.

type InkPoint = {
  /** X coordinate in drawing object local space (pixels) */
  x: number;
  /** Y coordinate in drawing object local space (pixels) */
  y: number;
  /** Pen pressure normalized to [0, 1].
- 0 = minimum pressure (or mouse with no pressure support)
- 1 = maximum pressure
- undefined = no pressure data (mouse, touch without pressure)

Used for variable stroke width rendering. */
  pressure?: number;
  /** Tilt angle in radians [0, PI/2].
- 0 = perpendicular to surface
- PI/2 = parallel to surface
- undefined = no tilt data

Used for brush shape and texture effects. */
  tilt?: number;
  /** Timestamp when this point was captured (ms since stroke start).
Used for velocity calculations and replay animations.
- undefined = no timing data */
  timestamp?: number;
}

InkStroke

A complete ink stroke with all rendering properties. Strokes are immutable once created - modifications create new strokes with the same ID (for CRDT merge semantics).

type InkStroke = {
  /** Unique identifier for this stroke */
  id: StrokeId;
  /** Ordered array of points composing the stroke */
  points: InkPoint[];
  /** Tool used to create this stroke */
  tool: InkTool;
  /** Stroke color in CSS color format (hex, rgb, hsl) */
  color: string;
  /** Base stroke width in pixels.
Actual rendered width may vary with pressure. */
  width: number;
  /** Stroke opacity [0, 1].
- 0 = fully transparent
- 1 = fully opaque

Different tools have different default opacities
(e.g., highlighter defaults to ~0.4). */
  opacity: number;
  /** User ID who created this stroke.
Used for:
- Collaboration: Show who drew what
- Permissions: Only creator can modify their strokes
- Undo: Per-user undo stacks */
  createdBy: string;
  /** Timestamp when stroke was created (Unix ms).
Used for ordering and undo/redo. */
  createdAt: number;
  /** Whether this stroke is currently selected.
This is a transient UI state, not persisted. */
  selected?: boolean;
}

InkTool

Available ink tools for drawing. Each tool has different rendering characteristics: - pen: Solid line, pressure-sensitive width - pencil: Textured line, slight transparency - highlighter: Wide, semi-transparent, blends with background - marker: Bold, opaque, consistent width - brush: Artistic brush effects, pressure-sensitive - eraser: Removes strokes (not a drawing tool, but handled similarly)

type InkTool = 'pen' | 'pencil' | 'highlighter' | 'marker' | 'brush' | 'eraser'

InkToolSettings

Default settings for a specific ink tool. Each tool can have different defaults for width, opacity, etc. These are used when creating new strokes.

type InkToolSettings = {
  /** Default stroke width in pixels */
  width: number;
  /** Default opacity [0, 1] */
  opacity: number;
  /** Default color (CSS color string) */
  color: string;
  /** Whether this tool supports pressure sensitivity.
Some tools (e.g., highlighter) ignore pressure. */
  supportsPressure: boolean;
}

InkToolState

Current tool state for a drawing session. Tracks the active tool and its settings.

type InkToolState = {
  /** Currently selected tool */
  activeTool: InkTool;
  /** Per-tool settings (user preferences) */
  toolSettings: Record<InkTool, InkToolSettings>;
}

InnerShadowEffect

Inner shadow effect (shadow cast inside the text). Creates a shadow effect along the inside edges of the text, giving the appearance that the text is embossed or inset. Unlike outer shadows, inner shadows are rendered within the text bounds. @example // Subtle inner shadow for depth const innerShadow: InnerShadowEffect = { blurRadius: 25400, // 2pt blur distance: 12700, // 1pt offset direction: 225, // Light from top-left color: '#000000', opacity: 0.3 }; @see ECMA-376 Part 1, Section 20.1.8.40 (innerShdw)

type InnerShadowEffect = {
  /** Blur radius in EMUs.
Controls how soft/diffuse the inner shadow appears. */
  blurRadius: number;
  /** Shadow distance from the text edge in EMUs.
How far the shadow extends inward from the edge. */
  distance: number;
  /** Shadow direction in degrees.
Angle measured clockwise from the positive x-axis.
Determines which edge of the text the shadow appears on. */
  direction: number;
  /** Shadow color (CSS color string). */
  color: string;
  /** Shadow opacity (0-1).
0 = fully transparent, 1 = fully opaque. */
  opacity: number;
}

InsertCellsReceipt

Receipt for an insertCellsWithShift mutation.

type InsertCellsReceipt = {
  kind: 'insertCells';
  sheetId: string;
  range: { startRow: number; startCol: number; endRow: number; endCol: number };
  direction: 'right' | 'down';
}

InsertColumnsReceipt

Receipt for an insertColumns mutation.

type InsertColumnsReceipt = {
  kind: 'insertColumns';
  sheetId: string;
  insertedAt: number;
  count: number;
}

InsertRowsReceipt

Receipt for an insertRows mutation.

type InsertRowsReceipt = {
  kind: 'insertRows';
  sheetId: string;
  insertedAt: number;
  count: number;
}

InsertWorksheetOptions

Options for insertWorksheetsFromBase64 — controls which sheets to import and where to place them in the workbook.

type InsertWorksheetOptions = {
  /** Which sheets to import by name. Default: all sheets. */
  sheetNamesToInsert?: string[];
  /** Where to insert relative to existing sheets. Default: 'end'. */
  positionType?: 'before' | 'after' | 'beginning' | 'end';
  /** Sheet name to position relative to (required for 'before'/'after'). */
  relativeTo?: string;
}

Issue

type Issue = {
  id: string;
  title: string;
  description?: string;
  status: 'open' | 'in_progress' | 'review' | 'done' | 'closed';
  priority: 'low' | 'medium' | 'high' | 'critical';
  type: 'bug' | 'feature' | 'task' | 'improvement';
  assignee?: { id: string; name: string; email: string };
  labels: string[];
  createdAt: string;
  updatedAt: string;
  closedAt?: string;
}

LayoutForm

type LayoutForm = 'compact' | 'outline' | 'tabular'

LayoutNodeChild

Discriminated union type for children of a layout node. A layout node's children can be: - A nested `LayoutNode` (static child) - A `ForEach` element (data-driven iteration) - A `Choose` element (conditional branching) Discriminated via the `kind` field: - `kind: 'layoutNode'` → LayoutNode (defined in ooxml-layout-types.ts) - `kind: 'forEach'` → ForEach - `kind: 'choose'` → Choose Note: The actual LayoutNode type with `kind: 'layoutNode'` is defined in the layout definition types (managed by Agent 1). This union is designed to be extended via intersection when all types are combined.

type LayoutNodeChild = ForEach | Choose | LayoutNodeChildRef

LegendConfig

Legend configuration (matches LegendData wire type)

type LegendConfig = {
  show: boolean;
  position: string;
  visible: boolean;
  overlay?: boolean;
  font?: ChartFont;
  format?: ChartFormat;
  entries?: LegendEntryConfig[];
  /** Custom legend X position (0-1, fraction of chart area) when position is 'custom' */
  customX?: number;
  /** Custom legend Y position (0-1, fraction of chart area) when position is 'custom' */
  customY?: number;
  shadow?: ChartShadow;
  /** Show drop shadow on legend box. */
  showShadow?: boolean;
  /** Legend height in points (read-only, populated from render engine). */
  height?: number;
  /** Legend width in points (read-only, populated from render engine). */
  width?: number;
  /** Legend left position in points (read-only, populated from render engine). */
  left?: number;
  /** Legend top position in points (read-only, populated from render engine). */
  top?: number;
}

LegendEntryConfig

Legend entry override (show/hide individual entries).

type LegendEntryConfig = {
  idx: number;
  delete?: boolean;
  format?: ChartFormat;
  /** Whether this legend entry is visible */
  visible?: boolean;
}

LimLowNode

Lower Limit - <m:limLow> Base with limit below

type LimLowNode = {
  type: 'limLow';
  /** Base expression */
  e: MathNode[];
  /** Limit expression */
  lim: MathNode[];
}

LimUppNode

Upper Limit - <m:limUpp> Base with limit above

type LimUppNode = {
  type: 'limUpp';
  /** Base expression */
  e: MathNode[];
  /** Limit expression */
  lim: MathNode[];
}

LineCap

Line cap style. Maps to ST_LineCap (ECMA-376, dml-main.xsd). Uses lowercase variants; bridge uses PascalCase.

type LineCap = | 'flat' // Flat end (ends exactly at the endpoint)
  | 'round' // Rounded end (semicircle at the endpoint)
  | 'square'

LineDash

Detailed line dash pattern. Matches OOXML line dash styles and Rust `LineDash` enum. Uses the same 11 variants as OOXML ST_PresetLineDashVal.

type LineDash = | 'solid'
  | 'dot'
  | 'dash'
  | 'dashDot'
  | 'lgDash'
  | 'lgDashDot'
  | 'lgDashDotDot'
  | 'sysDash'
  | 'sysDot'
  | 'sysDashDot'
  | 'sysDashDotDot'

LineEndSize

Arrowhead/line-end size for connector endpoints. Maps to ST_LineEndLength/ST_LineEndWidth (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types.

type LineEndSize = 'sm' | 'med' | 'lg'

LineEndType

Arrowhead/line-end type for connector endpoints. Maps to ST_LineEndType (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types.

type LineEndType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow'

LineJoin

Line join style. Maps to EG_LineJoinProperties (ECMA-376, dml-main.xsd). Uses lowercase variants; bridge uses tagged union.

type LineJoin = | 'bevel' // Beveled corner (flat cut at the join)
  | 'miter' // Mitered corner (sharp pointed join)
  | 'round'

LineSubType

type LineSubType = | 'straight'
  | 'smooth'
  | 'stepped'
  | 'stacked'
  | 'percentStacked'
  | 'markers'
  | 'markersStacked'
  | 'markersPercentStacked'

LinkId

type LinkId = string

LinkStatus

type LinkStatus = | 'unresolved'
  | 'loading'
  | 'ready'
  | 'stale'
  | 'denied'
  | 'broken'
  | 'ambiguous'

LinkStatusReason

type LinkStatusReason = | 'wrongWorkbookId'
  | 'missingTarget'
  | 'unsupportedLinkKind'
  | 'permissionDenied'
  | 'sourceUnavailable'

LinkStatusView

type LinkStatusView = {
  linkId: LinkId;
  status: LinkStatus;
  statusReason?: LinkStatusReason;
  lastResolvedAt?: string;
  cachedValuesVersion?: string;
}

MarkerStyle

Marker style for scatter/line chart markers.

type MarkerStyle = | 'circle'
  | 'dash'
  | 'diamond'
  | 'dot'
  | 'none'
  | 'picture'
  | 'plus'
  | 'square'
  | 'star'
  | 'triangle'
  | 'x'
  | 'auto'

MathFont

Math font for equation rendering Excel uses Cambria Math by default

type MathFont = | 'Cambria Math' // Default Excel math font
  | 'Latin Modern' // TeX-style
  | 'STIX Two Math' // Scientific publishing
  | 'XITS Math' // Based on STIX
  | string

MathNode

Any math AST node

type MathNode = | OMath
  | OMathPara
  | AccentNode
  | BarNode
  | BoxNode
  | BorderBoxNode
  | DelimiterNode
  | EqArrayNode
  | FractionNode
  | FunctionNode
  | GroupCharNode
  | LimLowNode
  | LimUppNode
  | MatrixNode
  | NaryNode
  | PhantomNode
  | RadicalNode
  | PreScriptNode
  | SubscriptNode
  | SubSupNode
  | SuperscriptNode
  | MathRun

MathRun

Text Run - <m:r> Actual text/symbol content

type MathRun = {
  type: 'r';
  /** Text content */
  text: string;
  /** Run properties */
  rPr?: MathRunProperties;
}

MatrixNode

Matrix - <m:m> Mathematical matrix

type MatrixNode = {
  type: 'm';
  /** Base justification */
  baseJc?: 'top' | 'center' | 'bottom';
  /** Hide placeholder */
  plcHide?: boolean;
  /** Row spacing rule */
  rSpRule?: 0 | 1 | 2 | 3 | 4;
  /** Column gap rule */
  cGpRule?: 0 | 1 | 2 | 3 | 4;
  /** Row spacing */
  rSp?: number;
  /** Column spacing */
  cSp?: number;
  /** Column gap */
  cGp?: number;
  /** Column properties */
  mcs?: Array<{ count?: number; mcJc?: 'left' | 'center' | 'right' }>;
  /** Matrix rows - each row is an array of cells, each cell is an array of nodes */
  mr: MathNode[][][];
}

MergeReceipt

Receipt for a merge mutation.

type MergeReceipt = {
  kind: 'merge';
  range: string;
}

MergedRegion

Information about a merged cell region.

type MergedRegion = {
  /** The merged range in A1 notation (e.g., "A1:B2") */
  range: string;
  /** Start row (0-based) */
  startRow: number;
  /** Start column (0-based) */
  startCol: number;
  /** End row (0-based, inclusive) */
  endRow: number;
  /** End column (0-based, inclusive) */
  endCol: number;
  /** Row span (endRow - startRow + 1) */
  rowSpan: number;
  /** Column span (endCol - startCol + 1) */
  colSpan: number;
}

NameAddReceipt

Receipt for a named range add mutation.

type NameAddReceipt = {
  kind: 'nameAdd';
  name: string;
  reference: string;
}

NameRemoveReceipt

Receipt for a named range remove mutation.

type NameRemoveReceipt = {
  kind: 'nameRemove';
  name: string;
}

NamedItemType

API type classification for a named item's value. @see https://learn.microsoft.com/en-us/javascript/api/excel/excel.nameditemtype

type NamedItemType = | 'String'
  | 'Integer'
  | 'Double'
  | 'Boolean'
  | 'Range'
  | 'Error'
  | 'Array'

NamedRangeInfo

Information about a defined name / named range.

type NamedRangeInfo = {
  /** The defined name */
  name: string;
  /** The reference formula (e.g., "Sheet1!$A$1:$B$10") */
  reference: string;
  /** Scope: undefined or sheet name (undefined = workbook scope) */
  scope?: string;
  /** Optional descriptive comment */
  comment?: string;
  /** Whether the name is visible in Name Manager. Hidden names are typically system-generated. */
  visible?: boolean;
}

NamedRangeReference

Parsed reference for a named range that refers to a simple sheet!range.

type NamedRangeReference = {
  /** The sheet name (e.g., "Sheet1") */
  sheetName: string;
  /** The range portion (e.g., "$A$1:$B$10") */
  range: string;
}

NamedRangeUpdateOptions

Options for updating a named range.

type NamedRangeUpdateOptions = {
  /** New name (for renaming) */
  name?: string;
  /** New reference (A1-style) */
  reference?: string;
  /** New comment */
  comment?: string;
  /** Whether the name is visible in Name Manager */
  visible?: boolean;
}

NamedSlicerStyle

A named slicer style stored in the workbook (custom or built-in).

type NamedSlicerStyle = {
  name: string;
  readOnly: boolean;
  style: SlicerCustomStyle;
}

NamedTimelineStyle

A named timeline style stored in the workbook (custom or built-in).

type NamedTimelineStyle = {
  name: string;
  readOnly: boolean;
  style: SlicerCustomStyle;
}

NaryNode

N-ary Operator - <m:nary> Summation, integral, product, etc.

type NaryNode = {
  type: 'nary';
  /** Operator character (sum, integral, product, etc.) */
  chr?: string;
  /** Limit location: 'undOvr' (above/below) or 'subSup' (sub/superscript) */
  limLoc?: 'undOvr' | 'subSup';
  /** Grow with content */
  grow?: boolean;
  /** Hide subscript */
  subHide?: boolean;
  /** Hide superscript */
  supHide?: boolean;
  /** Subscript (lower limit) */
  sub: MathNode[];
  /** Superscript (upper limit) */
  sup: MathNode[];
  /** Content (integrand, summand) */
  e: MathNode[];
}

NegativeNumberPattern

Negative number pattern. Determines how negative numbers are displayed (outside of currency context). 0 = (n) - parentheses 1 = -n - leading minus (most common) 2 = - n - leading minus with space 3 = n- - trailing minus 4 = n - - trailing minus with space

type NegativeNumberPattern = 0 | 1 | 2 | 3 | 4

NoFill

No fill (transparent). Text will be rendered without any fill color. @see ECMA-376 Part 1, Section 20.1.8.45 (CT_NoFillProperties)

type NoFill = {
  type: 'none';
}

NodeId

Unique identifier for a diagram node. This is a branded type for type safety - prevents accidental use of arbitrary strings as NodeIds. Uses UUID v4 format.

type NodeId = string & { readonly __brand: 'SmartArtNodeId' }

NodeMoveDirection

Hierarchical movement direction for a diagram node. Used by bridges, api/worksheet/smartart, and editor actions.

type NodeMoveDirection = 'promote' | 'demote' | 'move-up' | 'move-down'

NodePosition

Node insertion position relative to a target diagram node. Used by bridges, api/worksheet/smartart, and editor actions.

type NodePosition = 'before' | 'after' | 'above' | 'below' | 'child'

Note

A cell note (simple, single string per cell). API-only type (no Rust equivalent).

type Note = {
  content: string;
  author: string;
  cellAddress: string;
  /** Visible state of the note shape. */
  visible?: boolean;
  /** Note callout box height in points. */
  height?: number;
  /** Note callout box width in points. */
  width?: number;
}

Notification

A single notification

type Notification = {
  /** Unique ID for the notification */
  id: NotificationId;
  /** Notification type/severity */
  type: NotificationType;
  /** Short title (optional) */
  title?: string;
  /** Main message content */
  message: string;
  /** Timestamp when created */
  timestamp: number;
  /** Auto-dismiss after this many ms (null = manual dismiss only) */
  duration: number | null;
  /** Whether the notification can be dismissed */
  dismissible: boolean;
  /** Optional action button */
  action?: {
    label: string;
    onClick: () => void;
  };
}

NotificationId

Branded type for notification IDs — prevents accidental use of arbitrary strings.

type NotificationId = string & { readonly __brand: 'NotificationId' }

NotificationOptions

Options for creating a notification

type NotificationOptions = {
  /** Notification type/severity (default: 'info') */
  type?: NotificationType;
  /** Short title */
  title?: string;
  /** Auto-dismiss duration in ms (default: 5000, null for no auto-dismiss) */
  duration?: number | null;
  /** Whether dismissible (default: true) */
  dismissible?: boolean;
  /** Optional action button */
  action?: {
    label: string;
    onClick: () => void;
  };
}

NotificationType

Notification severity levels

type NotificationType = 'info' | 'success' | 'warning' | 'error'

NumberFormatCategory

Number format category classification. Matches the FormatType enum from Rust compute-formats.

enum NumberFormatCategory {
  General = 'General',
  Number = 'Number',
  Currency = 'Currency',
  Accounting = 'Accounting',
  Date = 'Date',
  Time = 'Time',
  Percentage = 'Percentage',
  Fraction = 'Fraction',
  Scientific = 'Scientific',
  Text = 'Text',
  Special = 'Special',
  Custom = 'Custom',
}

NumberFormatType

type NumberFormatType = | 'general'
  | 'number'
  | 'currency'
  | 'accounting'
  | 'date'
  | 'time'
  | 'percentage'
  | 'fraction'
  | 'scientific'
  | 'text'
  | 'special'
  | 'custom'

OMath

Root math container - <m:oMath>

type OMath = {
  type: 'oMath';
  children: MathNode[];
}

OMathPara

Math paragraph - <m:oMathPara>

type OMathPara = {
  type: 'oMathPara';
  justification?: 'left' | 'right' | 'center' | 'centerGroup';
  equations: OMath[];
}

ObjectAnchorType

How the object anchors to the sheet. Determines behavior when rows/columns are resized.

type ObjectAnchorType = | 'twoCell' // Anchored to two cells (moves and resizes with cells)
  | 'oneCell' // Anchored to one cell (moves but doesn't resize)
  | 'absolute'

ObjectBorder

Border style for floating objects.

type ObjectBorder = {
  /** Border line style */
  style: 'none' | 'solid' | 'dashed' | 'dotted';
  /** Border color (CSS color string) */
  color: string;
  /** Border width in pixels */
  width: number;
}

ObjectBounds

Pure-primitive rendering bounds types Leaf types (zero intra-contracts deps) that describe geometric/visual records. Promoted to Tier 1 during Phase C: they are consumed by both Tier 2 machines/actors and Tier 2 rendering, so hosting them here breaks what would otherwise be a types-machines ↔ types-rendering cycle. @module @mog/types-viewport/rendering/bounds

type ObjectBounds = {
  x: number;
  y: number;
  width: number;
  height: number;
  rotation: number;
}

ObjectFill

Fill configuration for shapes and text boxes. Matches the Rust `ObjectFill` struct in `domain-types`.

type ObjectFill = {
  /** Fill type */
  type: FillType;
  /** Solid fill color (CSS color string) */
  color?: string;
  /** Gradient configuration */
  gradient?: GradientFill;
  /** Fill transparency (0 = opaque, 1 = fully transparent). */
  transparency?: number;
  /** Pattern fill configuration (for type='pattern') */
  pattern?: PatternFill;
  /** Picture/texture fill configuration (for type='pictureAndTexture') */
  blip?: BlipFill;
}

ObjectPosition

Object position configuration. Supports cell-anchored and absolute positioning modes.

type ObjectPosition = {
  /** Anchor type determines how object moves/resizes with cells */
  anchorType: ObjectAnchorType;
  /** Start anchor (top-left corner) - required for all anchor types */
  from: CellAnchor;
  /** End anchor (bottom-right corner) - only for twoCell anchor */
  to?: CellAnchor;
  /** Absolute X position in pixels (only for absolute anchor) */
  x?: number;
  /** Absolute Y position in pixels (only for absolute anchor) */
  y?: number;
  /** Width in pixels (for oneCell and absolute anchors) */
  width?: number;
  /** Height in pixels (for oneCell and absolute anchors) */
  height?: number;
  /** Rotation angle in degrees (0-360) */
  rotation?: number;
  /** Flip horizontally (mirror along vertical axis) */
  flipH?: boolean;
  /** Flip vertically (mirror along horizontal axis) */
  flipV?: boolean;
}

OleObjectObject

OLE (Object Linking and Embedding) floating object. Represents embedded or linked objects from other applications (e.g., Word documents, PDF files, Visio drawings). The object may have a preview image (PNG/JPEG) or display as an icon. EMF/WMF previews are not supported and will have a null previewImageSrc. Architecture Notes: - Preview image is extracted during OOXML parsing and stored as a blob URL - Linked objects reference external files (isLinked); embedded objects are self-contained - dvAspect determines whether the object renders as content or as an icon - progId identifies the source application (e.g., "Word.Document.12", "AcroExch.Document")

type OleObjectObject = {
  type: 'oleObject';
  /** OLE ProgID identifying the source application (e.g., "Word.Document.12") */
  progId: string;
  /** Display aspect: 'content' renders the object preview, 'icon' shows an application icon */
  dvAspect: 'content' | 'icon';
  /** Whether the object links to an external file */
  isLinked: boolean;
  /** Whether the object data is embedded in the workbook */
  isEmbedded: boolean;
  /** Blob URL for the preview image (PNG/JPEG), null for EMF/WMF or missing previews */
  previewImageSrc: string | null;
  /** Descriptive text for accessibility */
  altText: string;
}

OperationWarning

Non-fatal warning attached to an operation result.

type OperationWarning = {
  /** Machine-readable warning code */
  code: string;
  /** Human-readable description */
  message: string;
  /** Optional structured context for programmatic handling */
  context?: Record<string, unknown>;
}

OriginalCellValue

A saved original cell value from before scenario application.

type OriginalCellValue = {
  sheetId: SheetId;
  cellId: string;
  value: string | number | boolean | null;
  /** Original formula, if the cell had one. */
  formula?: string;
}

OuterShadowEffect

Outer shadow effect (shadow cast outside the text). Creates a shadow behind the text that appears to be cast by a light source. The shadow can be positioned, blurred, scaled, and skewed for various effects including simple drop shadows and perspective shadows. @example // Simple drop shadow (bottom-right) const shadow: OuterShadowEffect = { blurRadius: 50800, // 4pt blur distance: 38100, // 3pt offset direction: 45, // 45 degrees (down-right) color: '#000000', opacity: 0.4 }; @see ECMA-376 Part 1, Section 20.1.8.52 (outerShdw)

type OuterShadowEffect = {
  /** Blur radius in EMUs (English Metric Units).
Higher values create a softer, more diffuse shadow.
1 point = 12700 EMUs.

@example 50800 // 4pt blur */
  blurRadius: number;
  /** Shadow distance from text in EMUs.
How far the shadow is offset from the text.

@example 38100 // 3pt offset */
  distance: number;
  /** Shadow direction in degrees.
Angle measured clockwise from the positive x-axis.
- 0 = right
- 90 = down
- 180 = left
- 270 = up */
  direction: number;
  /** Shadow color (CSS color string).
Typically black or dark gray for standard shadows.

@example '#000000' */
  color: string;
  /** Shadow opacity (0-1).
0 = fully transparent, 1 = fully opaque.
Typical values range from 0.3 to 0.6 for natural-looking shadows. */
  opacity: number;
  /** Horizontal scale factor for perspective shadows.
Values less than 1.0 compress the shadow horizontally.
Values greater than 1.0 stretch the shadow horizontally.

@default 1.0 (no scaling) */
  scaleX?: number;
  /** Vertical scale factor for perspective shadows.
Values less than 1.0 compress the shadow vertically.
Values greater than 1.0 stretch the shadow vertically.

@default 1.0 (no scaling) */
  scaleY?: number;
  /** Skew angle X in degrees (for perspective shadows).
Shears the shadow horizontally.

@default 0 (no skew) */
  skewX?: number;
  /** Skew angle Y in degrees (for perspective shadows).
Shears the shadow vertically.

@default 0 (no skew) */
  skewY?: number;
  /** Shadow alignment relative to the text bounding box.
Determines the anchor point for shadow positioning.

@default 'b' (bottom) */
  alignment?: ShadowAlignment;
  /** Whether shadow rotates with text when text is rotated.
If true, the shadow direction is relative to the text.
If false, the shadow direction is absolute (relative to the page).

@default true */
  rotateWithShape?: boolean;
}

OutlineSettings

Outline display settings for grouping.

type OutlineSettings = {
  /** Whether outline symbols (+/-) are visible */
  showOutlineSymbols: boolean;
  /** Whether outline level buttons (1,2,3...) are visible */
  showOutlineLevelButtons: boolean;
  /** Whether summary rows appear below detail rows */
  summaryRowsBelow: boolean;
  /** Whether summary columns appear to the right of detail */
  summaryColumnsRight: boolean;
}

PageMargins

Page margins in inches. Full OOXML representation including header/footer margins.

type PageMargins = {
  top: number;
  bottom: number;
  left: number;
  right: number;
  header: number;
  footer: number;
}

Path

A geometric path composed of segments.

type Path = {
  segments: PathSegment[];
  closed: boolean;
  subPaths?: SubPath[];
}

PathSegment

A single segment in a path.

type PathSegment = MoveTo | LineTo | CurveTo | QuadraticTo | ClosePath

PatternFill

Pattern fill definition.

type PatternFill = {
  preset: string;
  foregroundColor?: string;
  backgroundColor?: string;
}

PatternType

Spreadsheet pattern fill types. XLSX supports 18 pattern types for cell backgrounds. These patterns combine a foreground color (the pattern) with a background color. Pattern visualization (8x8 pixels): - none: No fill (transparent) - solid: Solid fill (fgColor only) - darkGray/mediumGray/lightGray/gray125/gray0625: Dot density patterns - darkHorizontal/lightHorizontal: Horizontal stripe patterns - darkVertical/lightVertical: Vertical stripe patterns - darkDown/lightDown: Diagonal stripes (top-left to bottom-right) - darkUp/lightUp: Diagonal stripes (bottom-left to top-right) - darkGrid/lightGrid: Grid patterns (horizontal + vertical) - darkTrellis/lightTrellis: Cross-hatch patterns (both diagonals)

type PatternType = | 'none'
  | 'solid'
  | 'darkGray'
  | 'mediumGray'
  | 'lightGray'
  | 'gray125'
  | 'gray0625'
  | 'darkHorizontal'
  | 'darkVertical'
  | 'darkDown'
  | 'darkUp'
  | 'darkGrid'
  | 'darkTrellis'
  | 'lightHorizontal'
  | 'lightVertical'
  | 'lightDown'
  | 'lightUp'
  | 'lightGrid'
  | 'lightTrellis'

PercentNegativePattern

Percent negative pattern. 0 = -n % 1 = -n% 2 = -%n 3 = %-n 4 = %n- 5 = n-% 6 = n%- 7 = -% n 8 = n %- 9 = % n- 10 = % -n 11 = n- %

type PercentNegativePattern = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11

PercentPositivePattern

Percent positive pattern. 0 = n % - number, space, percent 1 = n% - number, percent (most common) 2 = %n - percent, number 3 = % n - percent, space, number

type PercentPositivePattern = 0 | 1 | 2 | 3

PersistedLinkTarget

type PersistedLinkTarget = | { readonly kind: 'document-ref'; readonly documentId: DocumentId }
  | { readonly kind: 'open-session'; readonly sessionId: WorkbookSessionId }
  | { readonly kind: 'path'; readonly path: string }
  | { readonly kind: 'url'; readonly url: string }
  | { readonly kind: 'excel-external-path'; readonly target: string }
  | { readonly kind: 'opaque-host-ref'; readonly provider: string; readonly ref: string }

PersistedWorkbookLinkRecord

type PersistedWorkbookLinkRecord = {
  linkId: LinkId;
  expectedWorkbookId: WorkbookId | null;
  target: PersistedLinkTarget;
  displayName: string;
  sourceKind: WorkbookLinkSourceKind;
  importedExcelIdentity?: ImportedExternalLinkIdentity;
  materializedCacheMetadata?: AuthorizedMaterializedCacheMetadata;
}

PhantomNode

Phantom - <m:phant> Invisible element for spacing

type PhantomNode = {
  type: 'phant';
  /** Show content (false = invisible) */
  show?: boolean;
  /** Zero width */
  zeroWid?: boolean;
  /** Zero ascent */
  zeroAsc?: boolean;
  /** Zero descent */
  zeroDesc?: boolean;
  /** Transparent (show but don't contribute to size) */
  transp?: boolean;
  /** Content */
  e: MathNode[];
}

PictureAdjustments

Image adjustment settings. Values mirror Excel's picture format options.

type PictureAdjustments = {
  /** Brightness adjustment (-100 to 100, 0 = normal) */
  brightness?: number;
  /** Contrast adjustment (-100 to 100, 0 = normal) */
  contrast?: number;
  /** Transparency (0 = opaque, 100 = fully transparent) */
  transparency?: number;
}

PictureConfig

Configuration for creating a new picture.

type PictureConfig = {
  /** Image source: data URL, blob URL, or file path. */
  src: string;
  /** X position in pixels. */
  x?: number;
  /** Y position in pixels. */
  y?: number;
  /** Width in pixels (defaults to original image width). */
  width?: number;
  /** Height in pixels (defaults to original image height). */
  height?: number;
  /** Accessibility alt text. */
  altText?: string;
  /** Display name. */
  name?: string;
  /** Image crop settings (percentage from each edge). */
  crop?: PictureCrop;
  /** Image adjustments (brightness, contrast, transparency). */
  adjustments?: PictureAdjustments;
  /** Border around the picture. */
  border?: ObjectBorder;
  /** Full floating-object position update. Used by Format Picture dialogs. */
  position?: Partial<ObjectPosition>;
  /** Whether the picture is locked when sheet protection is active. */
  locked?: boolean;
  /** Whether the picture prints with the worksheet. */
  printable?: boolean;
  /** Anchor cell as `{row, col}`. When set, `x`/`y` become offsets from this
cell instead of from cell `(0, 0)`. Used by paste-image to anchor at the
active cell. */
  anchorCell?: { row: number; col: number };
}

PictureCrop

Image crop settings. Values are percentages (0-100) of original dimension to crop from each side.

type PictureCrop = {
  /** Percentage to crop from top (0-100) */
  top: number;
  /** Percentage to crop from right (0-100) */
  right: number;
  /** Percentage to crop from bottom (0-100) */
  bottom: number;
  /** Percentage to crop from left (0-100) */
  left: number;
}

PictureHandle

type PictureHandle = {
  update(props: Partial<PictureConfig>): Promise<void>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<PictureHandle>;;
  getData(): Promise<PictureObject>;;
}

PictureObject

Picture/image floating object. Supports images from various sources with cropping and adjustments.

type PictureObject = {
  type: 'picture';
  /** Image source (data URL, blob URL, or external URL) */
  src: string;
  /** Original image width in pixels (before scaling) */
  originalWidth: number;
  /** Original image height in pixels (before scaling) */
  originalHeight: number;
  /** Crop settings (percentage-based) */
  crop?: PictureCrop;
  /** Image adjustments (brightness, contrast, transparency) */
  adjustments?: PictureAdjustments;
  /** Border around the image */
  border?: ObjectBorder;
  /** Image color transform type */
  colorType?: ImageColorType;
}

PieSliceConfig

Pie/doughnut slice configuration (matches PieSliceData wire type)

type PieSliceConfig = {
  explosion?: number;
  explodedIndices?: number[];
  explodeOffset?: number;
  /** Explode all slices simultaneously */
  explodeAll?: boolean;
}

PivotCalculatedFieldSpec

type PivotCalculatedFieldSpec = {
  calculatedFieldId?: CalculatedFieldId;
  name: string;
  formula: string;
}

PivotChartOptions

Pivot chart display options (field button visibility).

type PivotChartOptions = {
  /** Show axis field buttons on the chart. */
  showAxisFieldButtons?: boolean;
  /** Show legend field buttons on the chart. */
  showLegendFieldButtons?: boolean;
  /** Show report filter field buttons on the chart. */
  showReportFilterFieldButtons?: boolean;
  /** Show value field buttons on the chart. */
  showValueFieldButtons?: boolean;
}

PivotColumnHeader

type PivotColumnHeader = {
  headers: PivotHeader[];
  fieldId: string;
}

PivotCommandReceipt

type PivotCommandReceipt = {
  receiptId: string;
  kernelReceiptId: string;
  action: string;
  pivotId: string;
  effects: PivotMutationEffect[];
  updateReason: string;
  refreshPolicy: 'dirtyOnly' | 'refreshAndMaterialize';
  materialized: boolean;
  configRevision: number;
  resultRevision: number;
  projectionRevision: number;
  materializedRevision?: number;
  renderFrame: number;
  status: 'complete' | 'failed' | 'cancelled' | 'timeout';
  error?: PivotKernelMutationError | { code: 'UI_TIMEOUT' | 'UI_CANCELLED'; message: string };
}

PivotCreateConfig

Input config for pivot creation — accepts either the simple ergonomic format (dataSource string + field name arrays) or the full wire format (sourceSheetName, sourceRange, fields[], placements[]). Simple format example: ```ts { name: "Sales", dataSource: "Sheet1!A1:D100", rowFields: ["Region"], columnFields: ["Year"], valueFields: [{ field: "Amount", aggregation: "sum" }] } ``` Full format example: ```ts { name: "Sales", sourceSheetName: "Sheet1", sourceRange: { startRow: 0, startCol: 0, endRow: 99, endCol: 3 }, outputSheetName: "Sheet1", outputLocation: { row: 0, col: 5 }, fields: [...], placements: [...], filters: [] } ```

type PivotCreateConfig = | SimplePivotTableConfig
  | Omit<PivotTableConfig, 'id' | 'createdAt' | 'updatedAt' | 'schemaVersion'>

PivotDataHierarchyInfo

Identifies which data hierarchy (value field) a pivot cell belongs to.

type PivotDataHierarchyInfo = {
  /** The field ID of the value field. */
  fieldId: string;
  /** Stable placement ID of the value field. */
  measurePlacementId?: PlacementId;
  /** The display name of the value field (e.g., "Sum of Sales"). */
  displayName: string;
  /** The aggregate function applied. */
  aggregateFunction: AggregateFunction;
  /** The 0-based index of this value field in the value placements. */
  index: number;
}

PivotExpansionKey

type PivotExpansionKey = {
  axis: 'row' | 'column';
  axisPlacementId: PlacementId;
  memberPath: PivotMemberKey[];
}

PivotExpansionState

Tracks which headers are expanded/collapsed. Uses Record<string, boolean> for TS ergonomics; Rust side uses HashSet<String> with custom serde that accepts both array and map formats.

type PivotExpansionState = {
  keys?: PivotExpansionKey[];
  /** @deprecated Legacy expansion map keyed by rendered header strings. */
  expandedRows: Record<string, boolean>;
  /** @deprecated Legacy expansion map keyed by rendered header strings. */
  expandedColumns: Record<string, boolean>;
}

PivotFieldArea

type PivotFieldArea = 'row' | 'column' | 'value' | 'filter'

PivotFieldItems

Collection of pivot items for a single field. Mirrors the Rust PivotFieldItems type.

type PivotFieldItems = {
  fieldId: string;
  fieldName: string;
  area: PivotFieldArea;
  items: PivotItemInfo[];
}

PivotFilter

type PivotFilter = {
  fieldId: string;
  includeValues?: CellValue[];
  excludeValues?: CellValue[];
  condition?: PivotFilterConditionFlat;
  topBottom?: PivotTopBottomFilter;
  showItemsWithNoData?: boolean;
}

PivotFilterConditionFlat

type PivotFilterConditionFlat = {
  operator: FilterOperator;
  value?: CellValue;
  value2?: CellValue;
}

PivotGrandTotals

type PivotGrandTotals = {
  row?: CellValue[];
  column?: CellValue[][];
  grand?: CellValue[];
  rowLabel?: string;
}

PivotHeader

type PivotHeader = {
  key: PivotMemberKey;
  value: CellValue;
  fieldId: string;
  axisPlacementId?: PlacementId;
  depth: number;
  span: number;
  isExpandable: boolean;
  isExpanded: boolean;
  isSubtotal: boolean;
  isGrandTotal: boolean;
  parentKey?: PivotMemberKey;
  childKeys?: PivotMemberKey[];
}

PivotItemInfo

A PivotItem represents a unique value within a pivot field. Mirrors the Rust PivotItemInfo type.

type PivotItemInfo = {
  key: PivotMemberKey;
  value: CellValue;
  fieldId: string;
  axisPlacementId?: PlacementId;
  area: PivotFieldArea;
  depth: number;
  isExpandable: boolean;
  isExpanded: boolean;
  isVisible: boolean;
  isSubtotal: boolean;
  isGrandTotal: boolean;
  childKeys?: PivotMemberKey[];
  parentKey?: PivotMemberKey;
}

PivotItemLocation

Identifies which pivot items (row/column group values) intersect at a given cell.

type PivotItemLocation = {
  /** The field ID. */
  fieldId: string;
  /** Stable placement ID of the axis field, when available. */
  axisPlacementId?: PlacementId;
  /** The display value of the item. */
  value: CellValue;
  /** The compound key identifying this item in the pivot result tree. */
  key: PivotMemberKey;
}

PivotKernelMutationError

type PivotKernelMutationError = {
  code: | 'PIVOT_NOT_FOUND'
    | 'PLACEMENT_NOT_FOUND'
    | 'DUPLICATE_PLACEMENT_ID'
    | 'AMBIGUOUS_SELECTOR'
    | 'INVALID_PLACEMENT_SOURCE'
    | 'CALCULATED_FIELD_NOT_FOUND'
    | 'DUPLICATE_CALCULATED_FIELD_ID'
    | 'DUPLICATE_CALCULATED_FIELD_NAME'
    | 'INVALID_CALCULATED_FIELD_FORMULA'
    | 'INVALID_CALCULATED_FIELD_REFERENCE'
    | 'CALCULATED_FIELD_DEPENDENCY_CYCLE'
    | 'INVALID_CALCULATED_FIELD_STATE'
    | 'INVALID_EXPANSION_KEY'
    | 'UNRESOLVABLE_EXPANSION_KEY'
    | 'STALE_EXPANSION_TARGET'
    | 'REFRESH_FAILED'
    | 'MATERIALIZATION_FAILED';
  stage: PivotMutationStage;
  message: string;
}

PivotKernelMutationReceipt

type PivotKernelMutationReceipt = {
  kernelReceiptId: string;
  pivotId: string;
  effects: PivotMutationEffect[];
  mutationResult: unknown;
  updateReason: string;
  refreshPolicy: 'dirtyOnly' | 'refreshAndMaterialize';
  materialized: boolean;
  configRevision: number;
  resultRevision?: number;
  materializedRevision?: number;
  status: PivotMutationStatus;
  error?: PivotKernelMutationError;
}

PivotMeasureDescriptor

type PivotMeasureDescriptor = {
  placementId: PlacementId;
  source: | { type: 'field'; fieldId: string }
    | { type: 'calculatedField'; calculatedFieldId: CalculatedFieldId };
  aggregateFunction: AggregateFunction;
  name: string;
  numberFormat?: string;
}

PivotMemberKey

type PivotMemberKey = string & { readonly __brand: 'PivotMemberKey' }

PivotMemberRef

type PivotMemberRef = {
  key: PivotMemberKey;
  value: CellValue;
  displayText: string;
  fieldId?: string;
  groupingBucketId?: string;
}

PivotMutationEffect

type PivotMutationEffect = {
  type: | 'placementAdded'
    | 'placementUpdated'
    | 'placementRemoved'
    | 'calculatedFieldAdded'
    | 'calculatedFieldUpdated'
    | 'calculatedFieldRemoved'
    | 'calculatedFieldInvalidated'
    | 'expansionChanged'
    | 'expansionKeyDropped';
  placementId?: PlacementId;
  calculatedFieldId?: CalculatedFieldId;
  expansionKey?: PivotExpansionKey;
}

PivotMutationStage

type PivotMutationStage = | 'validate'
  | 'configWrite'
  | 'refresh'
  | 'materialize'

PivotMutationStatus

type PivotMutationStatus = 'applied' | 'noOp' | 'failed'

PivotPlacementMutationReceipt

type PivotPlacementMutationReceipt = | (PivotKernelMutationReceipt & { status: 'applied'; placementId: PlacementId })
  | (PivotKernelMutationReceipt & { status: 'noOp' | 'failed'; placementId?: never })

PivotPlacementPatch

type PivotPlacementPatch = Partial<Omit<PivotPlacementSpec, 'placementId' | 'area' | 'source'>>

PivotPlacementSpec

type PivotPlacementSpec = {
  placementId?: PlacementId;
  fieldId?: string;
  area: PivotFieldArea;
  position?: number;
  source?: { type: 'field'; fieldId: string } | { type: 'calculatedField'; calculatedFieldId: CalculatedFieldId };
  aggregateFunction?: AggregateFunction;
  sortOrder?: SortOrder;
  displayName?: string;
  showValuesAs?: ShowValuesAsConfig;
  numberFormat?: string;
}

PivotQueryRecord

A single flat record from a pivot query result.

type PivotQueryRecord = {
  /** Dimension values keyed by field name (e.g., { Region: "North", Year: 2021 }) */
  dimensions: Record<string, CellValue>;
  /** Aggregated values keyed by value field label (e.g., { "Sum of Amount": 110 }) */
  values: Record<string, CellValue>;
  /** Measure-aware values with stable placement provenance. */
  valueRecords?: PivotValueRecord[];
  rowMemberPath?: PivotMemberRef[];
  columnMemberPath?: PivotMemberRef[];
}

PivotQueryResult

Result of queryPivot() — flat, agent-friendly records instead of hierarchy trees.

type PivotQueryResult = {
  /** Pivot table name */
  pivotName: string;
  /** Row dimension field names */
  rowFields: string[];
  /** Column dimension field names */
  columnFields: string[];
  /** Value field labels */
  valueFields: string[];
  /** Flat records — one per data intersection, excluding subtotals and grand totals */
  records: PivotQueryRecord[];
  /** Total source row count */
  sourceRowCount: number;
}

PivotRefreshReceipt

Receipt for a pivot table refresh mutation.

type PivotRefreshReceipt = {
  kind: 'pivotRefresh';
  pivotId: string;
}

PivotRenderedBounds

type PivotRenderedBounds = {
  totalRows: number;
  totalCols: number;
  firstDataRow: number;
  firstDataCol: number;
  /** Number of data columns reserved for the pivot body — `column_leaves * max(v, 1)`.
Distinct from `totalCols`, which adds row-header columns and grand-total columns.
Computed from the column-axis structure (sum of depth-0 column-header spans),
not from per-row value vectors, so it stays correct when measures or rows are empty. */
  numDataCols: number;
}

PivotRow

type PivotRow = {
  key: PivotTupleKey;
  headers: PivotHeader[];
  values: CellValue[];
  valueRecords?: PivotValueRecord[];
  depth: number;
  isSubtotal: boolean;
  isGrandTotal: boolean;
  /** Source row indices from the original data that contribute to this row's values.
Indices are 0-based into the source data rows (excluding the header row). */
  sourceRowIndices?: number[];
}

PivotTableConfig

Configuration for creating or describing a pivot table.

type PivotTableConfig = {
  /** Pivot table name */
  name: string;
  /** Source data range in A1 notation (e.g., "Sheet1!A1:E100") */
  dataSource: string;
  /** Target sheet name (defaults to a new sheet) */
  targetSheet?: string;
  /** Target cell address (defaults to A1) */
  targetAddress?: string;
  /** Field names for the row area */
  rowFields?: string[];
  /** Field names for the column area */
  columnFields?: string[];
  /** Value field configurations */
  valueFields?: PivotValueField[];
  /** Field names for the filter area */
  filterFields?: string[];
  /** When true, allows multiple filter criteria on a single field. */
  allowMultipleFiltersPerField?: boolean;
  /** Controls whether the pivot table auto-formats when refreshed. */
  autoFormat?: boolean;
  /** Controls whether custom formatting is preserved on refresh. */
  preserveFormatting?: boolean;
}

PivotTableHandle

Handle for interacting with an existing pivot table. Returned by `worksheet.getPivotTable()`. Provides methods to query and modify the pivot table's field configuration.

type PivotTableHandle = {
  /** Unique pivot table identifier (readonly) */
  id: string;
  /** Get the pivot table name */
  getName(): string;;
  /** Get the current configuration including all fields */
  getConfig(): PivotTableConfig;;
  /** Add a field to the row, column, or filter area */
  addField(field: string, area: 'row' | 'column' | 'filter', position?: number): void;;
  /** Add a value field with aggregation */
  addValueField(field: string, aggregation: PivotValueField['aggregation'], label?: string): void;;
  /** Remove a field by name */
  removeField(fieldName: string): void;;
  /** Change the aggregation function of a value field */
  changeAggregation(valueFieldLabel: string, newAggregation: PivotValueField['aggregation']): void;;
  /** Rename a value field's display label */
  renameValueField(currentLabel: string, newLabel: string): void;;
  /** Refresh the pivot table from its data source */
  refresh(): Promise<void>;;
  /** Get all items for all non-value fields */
  getAllItems(): Promise<PivotFieldItems[]>;;
  /** Set the "Show Values As" calculation for a value field. Pass null to clear. */
  setShowValuesAs(valueFieldLabel: string, showValuesAs: ShowValuesAsConfig | null): void;;
  /** Set item visibility by value string -> boolean map */
  setItemVisibility(fieldId: string, visibleItems: Record<string, boolean>): void;;
  /** Get the data source type (range, table, or external). */
  getDataSourceType(): DataSourceType;;
  /** Change the source data range without refreshing/materializing. */
  setDataSource(dataSource: string): Promise<void>;;
}

PivotTableInfo

Summary information about an existing pivot table.

type PivotTableInfo = {
  /** Pivot table name */
  name: string;
  /** Source data range (e.g., "Sheet1!A1:D100") */
  dataSource: string;
  /** Range occupied by the pivot table content */
  contentArea: string;
  /** Range occupied by filter dropdowns (if any) */
  filterArea?: string;
  /** Output anchor location as A1 reference (e.g., "G1") */
  location?: string;
  /** Row dimension field names */
  rowFields?: string[];
  /** Column dimension field names */
  columnFields?: string[];
  /** Value fields with aggregation info */
  valueFields?: PivotValueField[];
  /** Filter field names */
  filterFields?: string[];
}

PivotTableLayout

type PivotTableLayout = {
  showRowGrandTotals?: boolean;
  showColumnGrandTotals?: boolean;
  layoutForm?: LayoutForm;
  subtotalLocation?: SubtotalLocation;
  repeatRowLabels?: boolean;
  insertBlankRowAfterItem?: boolean;
  showRowHeaders?: boolean;
  showColumnHeaders?: boolean;
  classicLayout?: boolean;
  grandTotalCaption?: string;
  rowHeaderCaption?: string;
  colHeaderCaption?: string;
  dataCaption?: string;
  gridDropZones?: boolean;
  errorCaption?: string;
  showError?: boolean;
  missingCaption?: string;
  showMissing?: boolean;
}

PivotTableResult

type PivotTableResult = {
  columnHeaders: PivotColumnHeader[];
  rows: PivotRow[];
  records?: PivotQueryRecord[];
  grandTotals: PivotGrandTotals;
  sourceRowCount: number;
  renderedBounds: PivotRenderedBounds;
  measureDescriptors?: PivotMeasureDescriptor[];
  valueRecords?: PivotValueRecord[];
  errors?: string[];
}

PivotTableStyle

type PivotTableStyle = {
  styleName?: string;
  showRowStripes?: boolean;
  showColumnStripes?: boolean;
}

PivotTableStyleInfo

WorkbookPivotTableStyles -- Pivot table style presets and default style management. Provides access to the workbook-level default pivot table style preset. Equivalent API shape: `workbook.pivotTableStyles`.

type PivotTableStyleInfo = {
  name: string;
  isDefault: boolean;
}

PivotTopBottomFilter

type PivotTopBottomFilter = {
  type: TopBottomType;
  n: number;
  by: TopBottomBy;
  valueFieldId?: string;
}

PivotTupleKey

type PivotTupleKey = string & { readonly __brand: 'PivotTupleKey' }

PivotValueField

A value field in a pivot table.

type PivotValueField = {
  /** Stable value placement ID once the field is placed. */
  placementId?: PlacementId;
  /** Source field name */
  field: string;
  /** Aggregation function */
  aggregation: 'sum' | 'count' | 'average' | 'max' | 'min';
  /** Custom label for the value field */
  label?: string;
}

PivotValueRecord

type PivotValueRecord = {
  rowKey: PivotTupleKey;
  columnKey: PivotTupleKey;
  measureIndex: number;
  value: CellValue;
  sourceRowIndices?: number[];
}

PlacementId

type PlacementId = string & { readonly __brand: 'PlacementId' }

Platform

Supported operating system platforms. Canonical type for OS identity — used by PlatformIdentity, keyboard shortcut resolution, and any code that branches on the host OS.

type Platform = 'macos' | 'windows' | 'linux'

PlotAreaConfig

Plot area configuration

type PlotAreaConfig = {
  fill?: ChartFill;
  border?: ChartBorder;
  format?: ChartFormat;
}

PointFormat

Per-point formatting for individual data points (matches PointFormatData wire type)

type PointFormat = {
  idx: number;
  fill?: string;
  border?: ChartBorder;
  dataLabel?: DataLabelConfig;
  visualFormat?: ChartFormat;
  /** Readonly: computed value at this point (populated by get, ignored on set). */
  value?: number | string;
  /** Per-point marker fill color. */
  markerBackgroundColor?: ChartColor;
  /** Per-point marker border color. */
  markerForegroundColor?: ChartColor;
  /** Per-point marker size (2-72 points). */
  markerSize?: number;
  /** Per-point marker style. */
  markerStyle?: MarkerStyle;
}

PolicyId

Branded policy identifier.

type PolicyId = string & { readonly __brand?: 'PolicyId' }

PreScriptNode

Pre-scripts - <m:sPre> Subscript and superscript before base

type PreScriptNode = {
  type: 'sPre';
  /** Subscript */
  sub: MathNode[];
  /** Superscript */
  sup: MathNode[];
  /** Base */
  e: MathNode[];
}

PresetShadowType

Preset shadow types (20 predefined shadows). These map to DrawingML's preset shadow definitions (shdw1-shdw20). Each preset defines a complete shadow configuration including distance, direction, blur, color, and opacity. Use these for consistent, quick shadow application rather than configuring OuterShadowEffect manually. Preset categories: - shdw1-shdw4: Outer shadows (basic drop shadows) - shdw5-shdw8: Perspective shadows (cast at an angle) - shdw9-shdw12: Offset shadows (shifted significantly from text) - shdw13-shdw16: Inner shadows (shadow inside text edges) - shdw17-shdw20: Special effects (reflection-like, soft shadows) @see ECMA-376 Part 1, Section 20.1.10.56 (ST_PresetShadowVal)

type PresetShadowType = | 'shdw1' // Outer offset diagonal bottom right
  | 'shdw2' // Outer offset bottom
  | 'shdw3' // Outer offset diagonal bottom left
  | 'shdw4' // Outer offset right
  | 'shdw5' // Outer offset center
  | 'shdw6' // Outer offset left
  | 'shdw7' // Outer offset diagonal top right
  | 'shdw8' // Outer offset top
  | 'shdw9' // Outer offset diagonal top left
  | 'shdw10' // Perspective diagonal upper left
  | 'shdw11' // Perspective diagonal upper right
  | 'shdw12' // Perspective diagonal lower left
  | 'shdw13' // Perspective diagonal lower right
  | 'shdw14' // Perspective below
  | 'shdw15' // Perspective above
  | 'shdw16' // Perspective left
  | 'shdw17' // Perspective right
  | 'shdw18' // Perspective upper left
  | 'shdw19' // Perspective upper right
  | 'shdw20'

PrintSettings

Full print settings for a sheet, matching the Rust domain-types canonical type. Replaces the old lossy SheetPrintSettings. All fields are nullable where the underlying OOXML attribute is optional, using `null` to mean "not set / use default". Distinct from PrintOptions (runtime-only configuration in print-export).

type PrintSettings = {
  /** OOXML paper size code (1=Letter, 9=A4, etc.), null = not set */
  paperSize: number | null;
  /** Page orientation, null = not set (defaults to portrait) */
  orientation: string | null;
  /** Scale percentage (10-400), null = not set */
  scale: number | null;
  /** Fit to N pages wide, null = not set */
  fitToWidth: number | null;
  /** Fit to N pages tall, null = not set */
  fitToHeight: number | null;
  /** Print cell gridlines */
  gridlines: boolean;
  /** Print row/column headings */
  headings: boolean;
  /** Center content horizontally on page */
  hCentered: boolean;
  /** Center content vertically on page */
  vCentered: boolean;
  /** Page margins in inches (with header/footer margins) */
  margins: PageMargins | null;
  /** Header/footer configuration */
  headerFooter: HeaderFooter | null;
  /** Print in black and white */
  blackAndWhite: boolean;
  /** Draft quality */
  draft: boolean;
  /** First page number override, null = auto */
  firstPageNumber: number | null;
  /** Page order: "downThenOver" or "overThenDown", null = default */
  pageOrder: string | null;
  /** Use printer defaults */
  usePrinterDefaults: boolean | null;
  /** Horizontal DPI, null = not set */
  horizontalDpi: number | null;
  /** Vertical DPI, null = not set */
  verticalDpi: number | null;
  /** Relationship ID for printer settings binary, null = not set */
  rId: string | null;
  /** Whether the sheet had printOptions element in OOXML */
  hasPrintOptions: boolean;
  /** Whether the sheet had pageSetup element in OOXML */
  hasPageSetup: boolean;
  /** Whether to use firstPageNumber (vs auto) */
  useFirstPageNumber: boolean;
  /** How to print cell comments: "none" | "atEnd" | "asDisplayed", null = not set (defaults to none) */
  printComments: string | null;
  /** How to print cell errors: "displayed" | "blank" | "dash" | "NA", null = not set (defaults to displayed) */
  printErrors: string | null;
}

ProtectionConfig

Full protection configuration for a sheet.

type ProtectionConfig = {
  /** Whether the sheet is protected */
  isProtected: boolean;
  /** Whether a password is set for protection (does not expose the hash) */
  hasPasswordSet?: boolean;
  /** Allow selecting locked cells */
  allowSelectLockedCells?: boolean;
  /** Allow selecting unlocked cells */
  allowSelectUnlockedCells?: boolean;
  /** Allow formatting cells */
  allowFormatCells?: boolean;
  /** Allow formatting columns */
  allowFormatColumns?: boolean;
  /** Allow formatting rows */
  allowFormatRows?: boolean;
  /** Allow inserting columns */
  allowInsertColumns?: boolean;
  /** Allow inserting rows */
  allowInsertRows?: boolean;
  /** Allow inserting hyperlinks */
  allowInsertHyperlinks?: boolean;
  /** Allow deleting columns */
  allowDeleteColumns?: boolean;
  /** Allow deleting rows */
  allowDeleteRows?: boolean;
  /** Allow sorting */
  allowSort?: boolean;
  /** Allow using auto-filter */
  allowAutoFilter?: boolean;
  /** Allow using pivot tables */
  allowPivotTables?: boolean;
  /** Allow editing objects such as charts, shapes, and images */
  allowEditObjects?: boolean;
  /** Allow editing scenarios */
  allowEditScenarios?: boolean;
}

ProtectionOperation

Valid operations for structural protection checks.

type ProtectionOperation = | 'insertRows'
  | 'insertColumns'
  | 'deleteRows'
  | 'deleteColumns'
  | 'formatCells'
  | 'formatRows'
  | 'formatColumns'
  | 'sort'
  | 'filter'
  | 'editObject'

ProtectionOptions

Granular options for sheet protection.

type ProtectionOptions = {
  /** Allow selecting locked cells */
  allowSelectLockedCells?: boolean;
  /** Allow selecting unlocked cells */
  allowSelectUnlockedCells?: boolean;
  /** Allow formatting cells */
  allowFormatCells?: boolean;
  /** Allow formatting columns */
  allowFormatColumns?: boolean;
  /** Allow formatting rows */
  allowFormatRows?: boolean;
  /** Allow inserting columns */
  allowInsertColumns?: boolean;
  /** Allow inserting rows */
  allowInsertRows?: boolean;
  /** Allow inserting hyperlinks */
  allowInsertHyperlinks?: boolean;
  /** Allow deleting columns */
  allowDeleteColumns?: boolean;
  /** Allow deleting rows */
  allowDeleteRows?: boolean;
  /** Allow sorting */
  allowSort?: boolean;
  /** Allow using auto-filter */
  allowAutoFilter?: boolean;
  /** Allow using pivot tables */
  allowPivotTables?: boolean;
  /** Allow editing objects such as charts, shapes, and images */
  allowEditObjects?: boolean;
  /** Allow editing scenarios */
  allowEditScenarios?: boolean;
}

RadarSubType

Radar chart sub-types

type RadarSubType = 'basic' | 'filled'

RadicalNode

Radical - <m:rad> Square root or n-th root

type RadicalNode = {
  type: 'rad';
  /** Hide degree (for square root) */
  degHide?: boolean;
  /** Degree (n in n-th root) */
  deg: MathNode[];
  /** Radicand (content under root) */
  e: MathNode[];
}

RangePixelPosition

Pixel bounds of a range (top/left offset from worksheet origin, height, width).

type RangePixelPosition = {
  /** Pixel offset of the range's top edge from the worksheet origin */
  top: number;
  /** Pixel offset of the range's left edge from the worksheet origin */
  left: number;
  /** Height of the range in pixels */
  height: number;
  /** Width of the range in pixels */
  width: number;
}

RangeValueType

Per-cell value type classification. Matches the workbook range value-type enum values.

enum RangeValueType {
  Empty = 'Empty',
  String = 'String',
  Double = 'Double',
  Boolean = 'Boolean',
  Error = 'Error',
}

RawCellData

Complete raw cell data including formula, formatting, and metadata. Unlike `CellData` from core (which is the minimal read type), `RawCellData` includes all optional cell metadata useful for bulk reads and LLM presentation.

type RawCellData = {
  /** The computed cell value */
  value: CellValue;
  /** The formula string with "=" prefix, if the cell contains a formula */
  formula?: FormulaA1;
  /** Cell formatting */
  format?: CellFormat;
  /** Cell borders */
  borders?: CellBorders;
  /** Cell comment/note text */
  comment?: string;
  /** Hyperlink URL */
  hyperlink?: string;
  /** Whether the cell is part of a merged region */
  isMerged?: boolean;
  /** The merged region this cell belongs to (A1 notation, e.g., "A1:B2") */
  mergedRegion?: string;
}

RecognitionResult

Union type for all recognition results.

type RecognitionResult = RecognizedShape | RecognizedText

RecognizedShape

A shape recognized from one or more ink strokes. Recognition converts freehand strokes into clean geometric shapes while preserving the original strokes for undo/redo.

type RecognizedShape = {
  /** Type discriminator */
  type: 'shape';
  /** Recognized shape type */
  shapeType: RecognizedShapeType;
  /** Shape parameters (position, dimensions, etc.) */
  params: ShapeParams;
  /** IDs of the source strokes that were recognized as this shape.
Used for:
- Undo: Can restore original strokes
- Styling: Shape inherits color/width from source strokes */
  sourceStrokeIds: StrokeId[];
  /** Confidence score [0, 1] for the recognition */
  confidence: number;
  /** Timestamp when recognition occurred */
  recognizedAt: number;
}

RecognizedText

Text recognized from handwritten ink strokes. Handwriting recognition converts ink to text with multiple alternative interpretations ranked by confidence.

type RecognizedText = {
  /** Type discriminator */
  type: 'text';
  /** Primary recognized text (highest confidence) */
  text: string;
  /** Alternative interpretations ranked by confidence.
First element is same as `text` field. */
  alternatives: TextAlternative[];
  /** IDs of the source strokes that were recognized as this text.
Used for undo and re-recognition. */
  sourceStrokeIds: StrokeId[];
  /** Bounding box for the recognized text */
  bounds: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
  /** Timestamp when recognition occurred */
  recognizedAt: number;
}

RedoReceipt

Receipt for a redo operation.

type RedoReceipt = {
  kind: 'redo';
  success: boolean;
}

ReflectionEffect

Reflection effect configuration.

type ReflectionEffect = {
  /** Blur amount for the reflection */
  blur: number;
  /** Distance from the shape to the reflection */
  distance: number;
  /** Opacity of the reflection (0 = transparent, 1 = opaque) */
  opacity: number;
  /** Size of the reflection relative to the shape (0-1) */
  size: number;
}

RegionBounds

Region rectangle dimensions in cells. Together with `anchorRow` / `anchorCol` describes the full region rectangle.

type RegionBounds = {
  rows: number;
  cols: number;
}

RegionKind

Region kind discriminant — string union matching Rust's `serde(rename_all = "camelCase")` serialization of `enum RegionKind`. - `arraySpill` — modern dynamic-array spill (e.g. `=SEQUENCE(5)`). The formula bar does NOT brace-wrap members. - `cseArray` — legacy Ctrl+Shift+Enter array formula. Formula bar brace-wraps (`{=…}`). - `dataTable` — XLSX `<f t="dataTable">`. Formula bar brace-wraps (`{=TABLE(…)}`). Mirrors `kernel/src/bridges/compute/types.ts::RegionKind` and Rust's `snapshot_types::properties::RegionKind`. Re-exported from the bridge to keep the wire types in one place.

type RegionKind = 'arraySpill' | 'cseArray' | 'dataTable'

RegionMapConfig

Region map chart configuration

type RegionMapConfig = {
  /** Geographic region scope */
  region?: 'world' | 'us' | 'europe' | 'asia' | 'africa' | 'oceania' | 'southAmerica';
  /** Color scale for region fills */
  colorScale?: string[];
  /** Show region labels */
  showLabels?: boolean;
  /** Projection type */
  projection?: 'mercator' | 'equalEarth' | 'naturalEarth';
}

RegionMeta

Region membership shape carried on `StoreCellData.region`. `isAnchor` distinguishes the formula-owning cell (CSE anchor / Data Table master) from members. **No `source` field** — formula text lives on `StoreCellData.formula`; brace policy is a per-`kind` switch.

type RegionMeta = {
  kind: RegionKind;
  isAnchor: boolean;
  anchorRow: number;
  anchorCol: number;
  bounds: RegionBounds;
}

RemoveDuplicatesResult

Result of a remove-duplicates operation.

type RemoveDuplicatesResult = {
  /** Number of duplicate rows removed */
  removedCount: number;
  /** Number of unique rows remaining */
  remainingCount: number;
}

RenderScheduler

Scheduler that bridges buffer writes to canvas layer invalidation. Implements the "Write = Invalidate" contract: when viewport buffers receive patches, they call these methods to mark the appropriate canvas layers dirty and wake the render loop. This is a contracts-level mirror of the canvas-engine RenderScheduler so that contracts does not depend on @mog/canvas-engine at runtime.

type RenderScheduler = {
  /** Cell value or format changed — mark cells layer dirty. */
  markCellsDirty(cells?: { row: number; col: number }[]): void;;
  /** Row/col dimensions changed — mark cells + headers + selection dirty. */
  markGeometryDirty(): void;;
  /** Full buffer swap or theme change — mark all layers dirty. */
  markAllDirty(): void;;
}

ResolvedCellFormat

Dense cell format where every property is explicitly present (null when unset). Returned by formats.get().

type ResolvedCellFormat = {
  [K in keyof CellFormat]-?: CellFormat[K] | null;
}

RetargetWorkbookLinkInput

type RetargetWorkbookLinkInput = {
  target: PersistedLinkTarget;
  expectedWorkbookId?: WorkbookId | null;
  displayName?: string;
  sourceKind?: WorkbookLinkSourceKind;
  materializedCacheMetadata?: AuthorizedMaterializedCacheMetadata;
}

RichTextRun

type RichTextRun = {
  text: string;
  fontName: string | null;
  fontSize: number | null;
  bold: boolean;
  italic: boolean;
  underline: boolean;
  strikethrough: boolean;
  color: string | null;
  colorIndexed?: number;
  colorTheme?: number;
  colorTint?: number;
  charset: number | null;
  family: number | null;
  scheme: string | null;
  vertAlign?: string;
  preserveSpace?: boolean;
}

Scenario

A saved scenario with metadata.

type Scenario = {
  /** Unique scenario ID */
  id: string;
  /** Creation timestamp (Unix ms) */
  createdAt: number;
}

ScenarioConfig

Configuration for creating a what-if scenario.

type ScenarioConfig = {
  /** Scenario name */
  name: string;
  /** Cell addresses that change (A1 notation) */
  changingCells: string[];
  /** Values for the changing cells, in the same order */
  values: (string | number | boolean | null)[];
  /** Optional description */
  comment?: string;
}

Schema

A schema is a record of field names to their definitions. This is the single source of truth for a Yjs structure's shape. Example: ```typescript const SHEET_MAPS_SCHEMA = { meta: { type: 'Y.Map', required: true, copy: 'deep', lazyInit: false }, cells: { type: 'Y.Map', valueType: 'SerializedCellData', required: true, copy: 'deep', lazyInit: false }, // ... etc } as const satisfies Schema; ```

type Schema = Record<string, FieldDef>

ScreenshotOptions

Options for capturing a sheet screenshot as a PNG image.

type ScreenshotOptions = {
  /** Device pixel ratio (1 = standard, 2 = Retina). Default: 1. */
  dpr?: number;
  /** Whether to render row/column headers. Default: true. */
  showHeaders?: boolean;
  /** Whether to render gridlines. Default: true. */
  showGridlines?: boolean;
  /** Maximum pixel width — scales down if exceeded. */
  maxWidth?: number;
  /** Maximum pixel height — scales down if exceeded. */
  maxHeight?: number;
}

ScrollPosition

Scroll position (cell-level, not pixel-level).

type ScrollPosition = {
  /** Top visible row index (0-based). */
  topRow: number;
  /** Left visible column index (0-based). */
  leftCol: number;
}

SearchOptions

Options for cell search operations.

type SearchOptions = {
  /** Whether the search is case-sensitive */
  matchCase?: boolean;
  /** Whether to match the entire cell value */
  entireCell?: boolean;
  /** Whether to search formula text instead of computed values */
  searchFormulas?: boolean;
  /** Limit search to this range (A1 notation). Used by regexSearch; ignored by findInRange (use its range parameter instead). */
  range?: string;
}

SearchResult

A single search result.

type SearchResult = {
  /** Cell address in A1 notation */
  address: string;
  /** The cell's display value */
  value: string;
  /** The cell's formula (if any) */
  formula?: string;
}

SerializedCellData

Serialized cell data for Yjs storage. Uses short keys for compact CRDT storage. NOTE: The DiffCellData type (previously in contracts/src/versioning.ts) was removed when the versioning package was deleted.

type SerializedCellData = {
  /** Stable cell identity */
  id: CellId;
  /** Row position */
  row: number;
  /** Column position */
  col: number;
  /** Raw value (CellRawValue).
Can be a primitive (string, number, boolean, null) or RichText array.
Rich text is only valid for literal values, not formula results.
Use isRichText() from @mog-sdk/contracts to discriminate.
Use rawToCellValue() to convert to CellValue when needed. */
  r: CellRawValue;
  /** A1-style formula string without '=' prefix (backward compatible) */
  f?: string;
  /** Parsed identity formula */
  idf?: IdentityFormula;
  /** Computed value (omit if same as raw) */
  c?: CellValue;
  /** Note (omit if empty) */
  n?: string;
  /** Hyperlink URL (omit if none) */
  h?: string;
  /** For spill anchor cells: the dimensions of the spill range.
{ rows, cols } where rows >= 1 and cols >= 1.
Only present on the cell containing the array formula. */
  spillRange?: { rows: number; cols: number };
  /** For spill member cells: CellId of the anchor cell containing the formula.
Points back to the cell that owns this spill range.
Used for:
- Determining if editing this cell should be blocked
- Finding the formula when clicking a spill cell
- Clearing old spill when anchor formula result changes size */
  spillAnchor?: CellId;
  /** True if this is a legacy CSE (Ctrl+Shift+Enter) array formula.
CSE formulas have fixed size and show {=formula} in the formula bar.
Only present on anchor cells when isCSE is true. */
  isCSE?: boolean;
}

SeriesConfig

Individual series configuration (matches ChartSeriesData wire type)

type SeriesConfig = {
  name?: string;
  type?: string;
  color?: string;
  values?: string;
  categories?: string;
  bubbleSize?: string;
  smooth?: boolean;
  explosion?: number;
  invertIfNegative?: boolean;
  yAxisIndex?: number;
  showMarkers?: boolean;
  markerSize?: number;
  markerStyle?: string;
  lineWidth?: number;
  points?: PointFormat[];
  dataLabels?: DataLabelConfig;
  trendlines?: TrendlineConfig[];
  errorBars?: ErrorBarConfig;
  xErrorBars?: ErrorBarConfig;
  yErrorBars?: ErrorBarConfig;
  idx?: number;
  order?: number;
  format?: ChartFormat;
  barShape?: string;
  /** Color to use when a data point is inverted (negative) */
  invertColor?: ChartColor;
  /** Marker fill color. */
  markerBackgroundColor?: ChartColor;
  /** Marker border color. */
  markerForegroundColor?: ChartColor;
  /** Whether this series is hidden/filtered from the chart. */
  filtered?: boolean;
  /** Show drop shadow on series. */
  showShadow?: boolean;
  /** Show connector lines between pie slices (bar-of-pie, pie-of-pie). */
  showConnectorLines?: boolean;
  /** Gap width between bars/columns as percentage (per-series override) */
  gapWidth?: number;
  /** Overlap between bars/columns (-100 to 100, per-series override) */
  overlap?: number;
  /** Hole size for doughnut charts as percentage (per-series override) */
  doughnutHoleSize?: number;
  /** First slice angle for pie/doughnut charts in degrees (per-series override) */
  firstSliceAngle?: number;
  /** Split type for of-pie charts (per-series override) */
  splitType?: string;
  /** Split value threshold for of-pie charts (per-series override) */
  splitValue?: number;
  /** Bubble scale as percentage (per-series override) */
  bubbleScale?: number;
  leaderLineFormat?: ChartFormat;
  showLeaderLines?: boolean;
  /** Per-series histogram bin options (overrides chart-level histogram config) */
  binOptions?: HistogramConfig;
  /** Per-series box/whisker options (overrides chart-level boxplot config) */
  boxwhiskerOptions?: BoxplotConfig;
  /** @deprecated Use trendlines[] instead */
  trendline?: TrendlineConfig;
}

SeriesOrientation

Data series orientation

type SeriesOrientation = 'rows' | 'columns'

SetCellsResult

Result of a bulk setCells() operation.

type SetCellsResult = {
  /** Number of cells successfully written */
  cellsWritten: number;
  /** Per-cell errors, if any (omitted when all succeed) */
  errors?: Array<{ addr: string; error: string }> | null;
  /** Non-fatal warnings (e.g., deduplication, coercion) */
  warnings?: OperationWarning[];
}

ShadowAlignment

Shadow alignment options. Specifies the alignment of the shadow relative to the text. The shadow is positioned based on this anchor point. @see ECMA-376 Part 1, Section 20.1.10.3 (ST_RectAlignment)

type ShadowAlignment = | 'tl' // Top-left
  | 't' // Top-center
  | 'tr' // Top-right
  | 'l' // Middle-left
  | 'ctr' // Center
  | 'r' // Middle-right
  | 'bl' // Bottom-left
  | 'b' // Bottom-center
  | 'br'

ShadowEffect

Drop shadow effect configuration.

type ShadowEffect = {
  /** Shadow color (CSS color string) */
  color: string;
  /** Blur radius in pixels */
  blur: number;
  /** Horizontal offset in pixels */
  offsetX: number;
  /** Vertical offset in pixels */
  offsetY: number;
  /** Opacity (0 = transparent, 1 = opaque) */
  opacity: number;
}

Shape

Shape as returned by get/list operations. Extends ShapeConfig with identity and metadata fields. Same pattern as Chart extends ChartConfig.

type Shape = {
  /** Unique shape ID */
  id: string;
  /** Sheet ID the shape belongs to */
  sheetId: string;
  /** Z-order within the sheet */
  zIndex: number;
  /** Creation timestamp (Unix ms) */
  createdAt?: number;
  /** Last update timestamp (Unix ms) */
  updatedAt?: number;
}

ShapeConfig

Shape configuration for creating/updating shapes. Uses simple integer positions (anchorRow/anchorCol) for the public API. Internal storage uses CellId-based ObjectPosition. Preserves full fidelity: gradient fills, arrowhead outlines, rich text.

type ShapeConfig = {
  /** Shape type (rect, ellipse, triangle, etc.) */
  type: ShapeType;
  /** Anchor row (0-based) */
  anchorRow: number;
  /** Anchor column (0-based) */
  anchorCol: number;
  /** X offset from anchor cell in pixels */
  xOffset?: number;
  /** Y offset from anchor cell in pixels */
  yOffset?: number;
  /** Width in pixels */
  width: number;
  /** Height in pixels */
  height: number;
  /** Absolute pixel X on the sheet. When set, Rust resolves to anchorCol + xOffset. */
  pixelX?: number;
  /** Absolute pixel Y on the sheet. When set, Rust resolves to anchorRow + yOffset. */
  pixelY?: number;
  /** Optional name for the shape */
  name?: string;
  /** Fill configuration (solid, gradient with stops/angle, or none) */
  fill?: ObjectFill;
  /** Outline/stroke configuration (with optional arrowheads) */
  outline?: ShapeOutline;
  /** Rich text content inside the shape (with CellFormat) */
  text?: ShapeText;
  /** Shadow effect */
  shadow?: OuterShadowEffect;
  /** Rotation angle in degrees (0-360) */
  rotation?: number;
  /** Whether the shape is locked */
  locked?: boolean;
  /** Shape-specific adjustments (e.g., cornerRadius for roundRect) */
  adjustments?: Record<string, number>;
  /** Whether the shape is visible (default: true). */
  visible?: boolean;
  /** Anchor mode: how the shape anchors to cells (twoCell/oneCell/absolute). */
  anchorMode?: ObjectAnchorType;
  /** Whether to preserve aspect ratio when resizing */
  lockAspectRatio?: boolean;
  /** Accessibility title for the shape (distinct from alt text description) */
  altTextTitle?: string;
  /** User-visible display name (may differ from internal name) */
  displayName?: string;
}

ShapeEffects

Visual effects that can be applied to shapes.

type ShapeEffects = {
  /** Drop shadow effect */
  shadow?: ShadowEffect;
  /** Glow effect around the shape */
  glow?: GlowEffect;
  /** Reflection effect below the shape */
  reflection?: ReflectionEffect;
  /** 3D bevel effect */
  bevel?: BevelEffect;
  /** 3D transformation effect */
  transform3D?: Transform3DEffect;
}

ShapeHandle

type ShapeHandle = {
  shapeType: ShapeType;
  update(props: Partial<ShapeConfig>): Promise<FloatingObjectMutationReceipt>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<ShapeHandle>;;
  getData(): Promise<ShapeObject>;;
}

ShapeObject

Shape floating object. A geometric shape with optional fill, outline, and text.

type ShapeObject = {
  type: 'shape';
  /** Type of shape to render */
  shapeType: ShapeType;
  /** Fill configuration */
  fill?: ObjectFill;
  /** Outline/stroke configuration */
  outline?: ShapeOutline;
  /** Text content inside the shape */
  text?: ShapeText;
  /** Shadow effect (outer shadow / drop shadow) */
  shadow?: OuterShadowEffect;
  /** Shape-specific adjustments.
Keys depend on shape type (e.g., 'cornerRadius' for roundRect,
'arrowHeadSize' for arrows, 'starPoints' for stars). */
  adjustments?: Record<string, number>;
}

ShapeOutline

Shape outline/stroke configuration.

type ShapeOutline = {
  /** Outline style */
  style: 'none' | 'solid' | 'dashed' | 'dotted';
  /** Outline color (CSS color string) */
  color: string;
  /** Outline width in pixels */
  width: number;
  /** Head (start) arrowhead configuration */
  headEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize };
  /** Tail (end) arrowhead configuration */
  tailEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize };
  /** Detailed dash pattern (overrides coarse `style` when set). Matches OOXML dash styles. */
  dash?: LineDash;
  /** Outline transparency (0 = opaque, 1 = fully transparent). */
  transparency?: number;
  /** Compound line style (e.g., double, thickThin). */
  compound?: CompoundLineStyle;
  /** Whether the outline is visible. */
  visible?: boolean;
}

ShapeText

type ShapeText = {
  /** Text content */
  content: string;
  /** Text formatting */
  format?: CellFormat;
  /** Rich text runs for per-run formatting. When present, authoritative over content+format. */
  runs?: TextRun[];
  /** Vertical alignment of text within shape */
  verticalAlign?: 'top' | 'middle' | 'bottom' | 'justified' | 'distributed';
  /** Horizontal alignment of text within shape */
  horizontalAlign?: 'left' | 'center' | 'right' | 'justify' | 'distributed';
  /** Text margins within the container */
  margins?: TextMargins;
  /** Auto-size behavior */
  autoSize?: TextAutoSize;
  /** Text orientation */
  orientation?: TextOrientation;
  /** Reading order / directionality */
  readingOrder?: TextReadingOrder;
  /** Horizontal overflow behavior */
  horizontalOverflow?: TextOverflow;
  /** Vertical overflow behavior */
  verticalOverflow?: TextOverflow;
}

ShapeType

Available shape types. Matches common common spreadsheet shape categories. Extracted here (rather than in `floating-objects.ts`) so that diagram and other subtype modules can reference a subset without creating a cycle back into `floating-objects.ts`.

type ShapeType = | 'rect'
  | 'roundRect'
  | 'ellipse'
  | 'triangle'
  | 'rtTriangle'
  | 'diamond'
  | 'pentagon'
  | 'hexagon'
  | 'octagon'
  | 'parallelogram'
  | 'trapezoid'
  | 'nonIsoscelesTrapezoid'
  | 'heptagon'
  | 'decagon'
  | 'dodecagon'
  | 'teardrop'
  | 'pie'
  | 'pieWedge'
  | 'blockArc'
  | 'donut'
  | 'noSmoking'
  | 'plaque'
  // Rectangle variants (rounded/snipped)
  | 'round1Rect'
  | 'round2SameRect'
  | 'round2DiagRect'
  | 'snip1Rect'
  | 'snip2SameRect'
  | 'snip2DiagRect'
  | 'snipRoundRect'
  // Arrows
  | 'rightArrow'
  | 'leftArrow'
  | 'upArrow'
  | 'downArrow'
  | 'leftRightArrow'
  | 'upDownArrow'
  | 'quadArrow'
  | 'chevron'
  // Arrow Callouts
  | 'leftArrowCallout'
  | 'rightArrowCallout'
  | 'upArrowCallout'
  | 'downArrowCallout'
  | 'leftRightArrowCallout'
  | 'upDownArrowCallout'
  | 'quadArrowCallout'
  // Curved/Special Arrows
  | 'bentArrow'
  | 'uturnArrow'
  | 'circularArrow'
  | 'leftCircularArrow'
  | 'leftRightCircularArrow'
  | 'curvedRightArrow'
  | 'curvedLeftArrow'
  | 'curvedUpArrow'
  | 'curvedDownArrow'
  | 'swooshArrow'
  // Stars and banners
  | 'star4'
  | 'star5'
  | 'star6'
  | 'star7'
  | 'star8'
  | 'star10'
  | 'star12'
  | 'star16'
  | 'star24'
  | 'star32'
  | 'ribbon'
  | 'ribbon2'
  | 'ellipseRibbon'
  | 'ellipseRibbon2'
  | 'leftRightRibbon'
  | 'banner'
  // Callouts
  | 'wedgeRectCallout'
  | 'wedgeRoundRectCallout'
  | 'wedgeEllipseCallout'
  | 'cloud'
  | 'callout1'
  | 'callout2'
  | 'callout3'
  | 'borderCallout1'
  | 'borderCallout2'
  | 'borderCallout3'
  | 'accentCallout1'
  | 'accentCallout2'
  | 'accentCallout3'
  | 'accentBorderCallout1'
  | 'accentBorderCallout2'
  | 'accentBorderCallout3'
  // Lines and connectors
  | 'line'
  | 'lineArrow'
  | 'lineDoubleArrow'
  | 'curve'
  | 'arc'
  | 'connector'
  | 'bentConnector2'
  | 'bentConnector3'
  | 'bentConnector4'
  | 'bentConnector5'
  | 'curvedConnector2'
  | 'curvedConnector3'
  | 'curvedConnector4'
  | 'curvedConnector5'
  // Flowchart shapes
  | 'flowChartProcess'
  | 'flowChartDecision'
  | 'flowChartInputOutput'
  | 'flowChartPredefinedProcess'
  | 'flowChartInternalStorage'
  | 'flowChartDocument'
  | 'flowChartMultidocument'
  | 'flowChartTerminator'
  | 'flowChartPreparation'
  | 'flowChartManualInput'
  | 'flowChartManualOperation'
  | 'flowChartConnector'
  | 'flowChartPunchedCard'
  | 'flowChartPunchedTape'
  | 'flowChartSummingJunction'
  | 'flowChartOr'
  | 'flowChartCollate'
  | 'flowChartSort'
  | 'flowChartExtract'
  | 'flowChartMerge'
  | 'flowChartOfflineStorage'
  | 'flowChartOnlineStorage'
  | 'flowChartMagneticTape'
  | 'flowChartMagneticDisk'
  | 'flowChartMagneticDrum'
  | 'flowChartDisplay'
  | 'flowChartDelay'
  | 'flowChartAlternateProcess'
  | 'flowChartOffpageConnector'
  // Decorative symbols
  | 'heart'
  | 'lightningBolt'
  | 'sun'
  | 'moon'
  | 'smileyFace'
  | 'foldedCorner'
  | 'bevel'
  | 'frame'
  | 'halfFrame'
  | 'corner'
  | 'diagStripe'
  | 'chord'
  | 'can'
  | 'cube'
  | 'plus'
  | 'cross'
  | 'irregularSeal1'
  | 'irregularSeal2'
  | 'homePlate'
  | 'funnel'
  | 'verticalScroll'
  | 'horizontalScroll'
  // Action Buttons
  | 'actionButtonBlank'
  | 'actionButtonHome'
  | 'actionButtonHelp'
  | 'actionButtonInformation'
  | 'actionButtonForwardNext'
  | 'actionButtonBackPrevious'
  | 'actionButtonEnd'
  | 'actionButtonBeginning'
  | 'actionButtonReturn'
  | 'actionButtonDocument'
  | 'actionButtonSound'
  | 'actionButtonMovie'
  // Brackets and Braces
  | 'leftBracket'
  | 'rightBracket'
  | 'leftBrace'
  | 'rightBrace'
  | 'bracketPair'
  | 'bracePair'
  // Math shapes
  | 'mathPlus'
  | 'mathMinus'
  | 'mathMultiply'
  | 'mathDivide'
  | 'mathEqual'
  | 'mathNotEqual'
  // Miscellaneous
  | 'gear6'
  | 'gear9'
  | 'cornerTabs'
  | 'squareTabs'
  | 'plaqueTabs'
  | 'chartX'
  | 'chartStar'
  | 'chartPlus'

Sheet

Minimal Sheet interface for selector functions. This represents the deserialized view of sheet data used by selectors. The floatingObjects array is the deserialized form of the Y.Map storage.

type Sheet = {
  /** Array of floating objects on the sheet (deserialized from Y.Map) */
  floatingObjects?: FloatingObject[];
}

SheetDataBindingInfo

Information about an existing sheet data binding.

type SheetDataBindingInfo = {
  /** Unique binding identifier */
  id: string;
  /** Connection providing the data */
  connectionId: string;
  /** Maps data fields to columns */
  columnMappings: ColumnMapping[];
  /** Auto-insert/delete rows to match data length */
  autoGenerateRows: boolean;
  /** Row index for headers (-1 = no header row) */
  headerRow: number;
  /** First row of data (0-indexed) */
  dataStartRow: number;
  /** Preserve header row formatting on refresh */
  preserveHeaderFormatting: boolean;
  /** Last refresh timestamp */
  lastRefresh?: number;
}

SheetHideReceipt

Receipt for a sheet hide mutation.

type SheetHideReceipt = {
  kind: 'sheetHide';
  name: string;
}

SheetId

type SheetId = string & { readonly [__sheetId]: true }

SheetMoveReceipt

Receipt for a sheet move mutation.

type SheetMoveReceipt = {
  kind: 'sheetMove';
  name: string;
  newIndex: number;
}

SheetRange

type SheetRange = {
  startRow: number;
  startCol: number;
  endRow: number;
  endCol: number;
}

SheetRangeDescribeResult

Result entry for one sheet range in a batch read.

type SheetRangeDescribeResult = {
  /** Sheet name (as resolved). */
  sheet: string;
  /** The range that was actually read. */
  range: string;
  /** The LLM-formatted description (same format as ws.describeRange). Empty string if error. */
  description: string;
  /** Set if this entry failed (bad sheet name, empty sheet, etc.). */
  error?: string;
}

SheetRangeRequest

A request for a range read on a specific sheet (used by wb.describeRanges).

type SheetRangeRequest = {
  /** Sheet name (case-insensitive lookup). */
  sheet: string;
  /** A1-style range, e.g. "A1:M50". If omitted, reads used range. */
  range?: string;
}

SheetRemoveReceipt

Receipt for a sheet remove mutation.

type SheetRemoveReceipt = {
  kind: 'sheetRemove';
  removedName: string;
  remainingCount: number;
}

SheetRenameReceipt

Receipt for a sheet rename mutation.

type SheetRenameReceipt = {
  kind: 'sheetRename';
  oldName: string;
  newName: string;
}

SheetSettingsInfo

Full sheet settings (mirrors SheetSettings from core contracts).

type SheetSettingsInfo = {
  /** Default row height in pixels */
  defaultRowHeight: number;
  /** Default column width in pixels */
  defaultColWidth: number;
  /** Whether gridlines are shown */
  showGridlines: boolean;
  /** Whether row headers are shown */
  showRowHeaders: boolean;
  /** Whether column headers are shown */
  showColumnHeaders: boolean;
  /** Whether zero values are displayed (false = blank) */
  showZeroValues: boolean;
  /** Gridline color (hex string) */
  gridlineColor: string;
  /** Whether the sheet is protected */
  isProtected: boolean;
  /** Whether the sheet uses right-to-left layout */
  rightToLeft: boolean;
}

SheetShowReceipt

Receipt for a sheet show mutation.

type SheetShowReceipt = {
  kind: 'sheetShow';
  name: string;
}

SheetSnapshot

A summary snapshot of a single sheet.

type SheetSnapshot = {
  /** Sheet ID */
  id: string;
  /** Sheet name */
  name: string;
  /** Sheet index (0-based) */
  index: number;
  /** Range containing all non-empty cells, or null if sheet is empty */
  usedRange: CellRange | null;
  /** Number of cells with data */
  cellCount: number;
  /** Number of cells with formulas */
  formulaCount: number;
  /** Number of charts in this sheet */
  chartCount: number;
  /** Sheet dimensions */
  dimensions: { rows: number; cols: number };
}

ShowValuesAs

type ShowValuesAs = 'noCalculation' | 'percentOfGrandTotal' | 'percentOfColumnTotal' | 'percentOfRowTotal' | 'percentOfParentRowTotal' | 'percentOfParentColumnTotal' | 'difference' | 'percentDifference' | 'runningTotal' | 'percentRunningTotal' | 'rankAscending' | 'rankDescending' | 'index'

ShowValuesAsConfig

type ShowValuesAsConfig = {
  type: ShowValuesAs;
  baseField?: string;
  baseItem?: { type: 'relative'; position: 'previous' | 'next' } | { type: 'specific'; value: CellValue };
}

SignAnomaly

A single cell whose sign disagrees with its neighbors.

type SignAnomaly = {
  /** A1 address of the anomalous cell. */
  cell: string;
  /** The cell's computed numeric value. */
  value: number;
  /** Fraction of neighbors with the opposite sign (0.0–1.0).
1.0 = every neighbor disagrees. Sorted descending. */
  disagreement: number;
  /** The neighboring cells that were considered. */
  neighbors: { cell: string; value: number }[];
}

SignCheckOptions

Options for sign anomaly detection.

type SignCheckOptions = {
  /** Which axis to check sign consistency along.
- `'column'`: compare cells vertically within each column (default).
- `'row'`: compare cells horizontally within each row.
- `'both'`: run both checks, merge results. */
  axis?: 'column' | 'row' | 'both';
  /** How many non-empty numeric neighbors to consider in each direction.
Default: 3 (up to 6 neighbors total per axis). */
  window?: number;
}

SignCheckResult

Result of a signCheck call.

type SignCheckResult = {
  /** Total non-zero numeric cells examined. */
  cellsChecked: number;
  /** Cells whose sign disagrees with the majority of their neighbors. */
  anomalies: SignAnomaly[];
}

SingleAxisConfig

Single axis configuration (matches SingleAxisData wire type).

type SingleAxisConfig = {
  title?: string;
  visible: boolean;
  min?: number;
  max?: number;
  axisType?: string;
  gridLines?: boolean;
  minorGridLines?: boolean;
  majorUnit?: number;
  minorUnit?: number;
  tickMarks?: string;
  minorTickMarks?: string;
  numberFormat?: string;
  reverse?: boolean;
  position?: string;
  logBase?: number;
  displayUnit?: string;
  format?: ChartFormat;
  titleFormat?: ChartFormat;
  gridlineFormat?: ChartLineFormat;
  minorGridlineFormat?: ChartLineFormat;
  crossBetween?: string;
  tickLabelPosition?: string;
  baseTimeUnit?: string;
  majorTimeUnit?: string;
  minorTimeUnit?: string;
  customDisplayUnit?: number;
  displayUnitLabel?: string;
  labelAlignment?: string;
  labelOffset?: number;
  noMultiLevelLabels?: boolean;
  /** Scale type: linear or logarithmic */
  scaleType?: 'linear' | 'logarithmic';
  /** Category axis type */
  categoryType?: 'automatic' | 'textAxis' | 'dateAxis';
  /** Where the axis crosses */
  crossesAt?: 'automatic' | 'max' | 'min' | 'custom';
  /** Custom crossing value when crossesAt is 'custom' */
  crossesAtValue?: number;
  /** Whether the axis title is visible (separate from title text content). */
  titleVisible?: boolean;
  /** Interval between tick labels (e.g., 1 = every label, 2 = every other). */
  tickLabelSpacing?: number;
  /** Interval between tick marks. */
  tickMarkSpacing?: number;
  /** Whether the number format is linked to the source data cell format. */
  linkNumberFormat?: boolean;
  /** Whether tick marks are between categories (true) or on categories (false) */
  isBetweenCategories?: boolean;
  /** Text orientation angle in degrees (-90 to 90) */
  textOrientation?: number;
  /** Label alignment (alias for labelAlignment) */
  alignment?: string;
  /** @deprecated Alias for axisType — kept for backward compat with charts package */
  type?: AxisType;
  /** @deprecated Alias for visible — kept for backward compat with charts package */
  show?: boolean;
}

Size

A 2D size (width and height).

type Size = {
  width: number;
  height: number;
}

Slicer

Full slicer state including selection and position.

type Slicer = {
  /** Currently selected filter items */
  selectedItems: CellValue[];
  /** Position and dimensions in pixels */
  position: { x: number; y: number; width: number; height: number };
}

SlicerConfig

Configuration for creating a new slicer.

type SlicerConfig = {
  /** Slicer ID (generated if omitted) */
  id?: string;
  /** Sheet ID the slicer belongs to */
  sheetId?: string;
  /** Name of the table to connect the slicer to */
  tableName?: string;
  /** Column name within the table to filter on */
  columnName?: string;
  /** Display name for the slicer (auto-generated if omitted) */
  name?: string;
  /** Position and dimensions in pixels */
  position?: { x: number; y: number; width: number; height: number };
  /** Data source connection (rich alternative to tableName/columnName) */
  source?: SlicerSource;
  /** Slicer caption (header text) */
  caption?: string;
  /** Style configuration */
  style?: SlicerStyle;
  /** Show slicer header */
  showHeader?: boolean;
  /** Z-order within the sheet */
  zIndex?: number;
  /** Whether slicer position is locked */
  locked?: boolean;
  /** Whether multi-select is enabled */
  multiSelect?: boolean;
  /** Initial selected values */
  selectedValues?: CellValue[];
  /** Currently selected date range start (timeline slicers) */
  selectedStartDate?: number;
  /** Currently selected date range end (timeline slicers) */
  selectedEndDate?: number;
  /** Current aggregation level (timeline slicers) */
  timelineLevel?: TimelineLevel;
}

SlicerCustomStyle

Custom slicer style definition. Canonical source: compute-types.gen.ts (Rust domain-types)

type SlicerCustomStyle = {
  /** Header background color */
  headerBackgroundColor?: string;
  /** Header text color */
  headerTextColor?: string;
  /** Header font size */
  headerFontSize?: number;
  /** Selected item background color */
  selectedBackgroundColor?: string;
  /** Selected item text color */
  selectedTextColor?: string;
  /** Available item background color */
  availableBackgroundColor?: string;
  /** Available item text color */
  availableTextColor?: string;
  /** Unavailable item background color */
  unavailableBackgroundColor?: string;
  /** Unavailable item text color */
  unavailableTextColor?: string;
  /** Border color */
  borderColor?: string;
  /** Border width in pixels */
  borderWidth?: number;
  /** Corner radius for items */
  itemBorderRadius?: number;
}

SlicerInfo

Summary information about a slicer.

type SlicerInfo = {
  /** Unique slicer ID */
  id: string;
  /** Programmatic name (unique within workbook). Falls back to caption if not set. */
  name: string;
  /** Display caption (header text). */
  caption: string;
  /** Connected table name */
  tableName: string;
  /** Connected column name */
  columnName: string;
  /** Source type — 'table' for table slicers, 'pivot' for pivot table slicers */
  source?: { type: 'table' | 'pivot' };
  /** Discriminator for timeline slicers (matches TimelineSlicerConfig.sourceType) */
  sourceType?: 'timeline';
}

SlicerItem

A single item in a slicer's value list.

type SlicerItem = {
  /** The display value */
  value: CellValue;
  /** Whether this item is currently selected */
  selected: boolean;
  /** Number of matching records (if available) */
  count?: number;
}

SlicerPivotSource

Reference to a pivot field for slicer binding.

type SlicerPivotSource = {
  type: 'pivot';
  /** Pivot table ID to connect to */
  pivotId: string;
  /** Field name in the pivot (row/column/filter field) */
  fieldName: string;
  /** Which area the field is in */
  fieldArea: 'row' | 'column' | 'filter';
}

SlicerSortOrder

Slicer sort order. Canonical source: compute-types.gen.ts

type SlicerSortOrder = 'ascending' | 'descending' | 'dataSourceOrder'

SlicerSource

Union type for slicer data sources. Canonical source: compute-types.gen.ts (Rust domain-types) Generated version uses intersection with helper interfaces: `{ type: "table" } & SlicerSource_table | { type: "pivot" } & SlicerSource_pivot` Contracts uses named interface variants. Both are structurally identical (same internally-tagged discriminated union shape). No bridge conversion needed.

type SlicerSource = SlicerTableSource | SlicerPivotSource

SlicerState

Enriched runtime state for a slicer (includes computed items, connection status).

type SlicerState = {
  /** Computed items with selection state */
  items: SlicerItem[];
  /** Whether the slicer is connected to its data source */
  isConnected: boolean;
  /** Selected values */
  selectedValues: CellValue[];
  /** Timeline periods (for timeline slicers) */
  periods?: TimelinePeriod[];
}

SlicerStyle

Complete slicer style configuration. Canonical source: compute-types.gen.ts (Rust domain-types)

type SlicerStyle = {
  /** Style preset (mutually exclusive with custom) */
  preset?: SlicerStylePreset;
  /** Custom style (mutually exclusive with preset) */
  custom?: SlicerCustomStyle;
  /** Number of columns for item layout (default: 1) */
  columnCount: number;
  /** Button height in pixels */
  buttonHeight: number;
  /** Show item selection indicators */
  showSelectionIndicator: boolean;
  /** ST_SlicerCacheCrossFilter — controls cross-filtering visual indication.
Replaces the previous showItemsWithNoData boolean.
Default: 'showItemsWithDataAtTop' */
  crossFilter: CrossFilterMode;
  /** Whether to use custom sort list. Default: true */
  customListSort: boolean;
  /** Whether to show items with no matching data (x14 pivot-backed slicers). Default: true */
  showItemsWithNoData: boolean;
  /** 'dataSourceOrder' is internal-only; never read from or written to OOXML. Import defaults to 'ascending'. */
  sortOrder: SlicerSortOrder;
}

SlicerStyleInfo

type SlicerStyleInfo = {
  name: string;
  isDefault: boolean;
}

SlicerStylePreset

Slicer style presets matching Excel's slicer style gallery. Canonical source: compute-types.gen.ts (Rust domain-types)

type SlicerStylePreset = | 'light1'
  | 'light2'
  | 'light3'
  | 'light4'
  | 'light5'
  | 'light6'
  | 'dark1'
  | 'dark2'
  | 'dark3'
  | 'dark4'
  | 'dark5'
  | 'dark6'
  | 'other1'
  | 'other2'

SlicerTableSource

Reference to a table field for slicer binding. Uses column header CellId for Cell Identity Model compliance. **Graceful Degradation:** If the column header cell is deleted, the slicer becomes "disconnected" and shows a placeholder state. This matches Excel behavior where slicers become invalid when their source column is deleted.

type SlicerTableSource = {
  type: 'table';
  /** Table ID to connect to */
  tableId: string;
  /** Column header CellId - stable across column moves.
If this CellId becomes orphaned (column deleted), slicer shows disconnected state. */
  columnCellId: CellId;
}

SmartArtCategory

diagram categories matching Excel. Each category represents a different type of visual representation: - list: Sequential or grouped items - process: Steps or stages in a workflow - cycle: Continuous or circular processes - hierarchy: Organization charts, tree structures - relationship: Connections between concepts - matrix: Grid-based relationships - pyramid: Proportional or hierarchical layers - picture: Image-centric layouts

type SmartArtCategory = | 'list'
  | 'process'
  | 'cycle'
  | 'hierarchy'
  | 'relationship'
  | 'matrix'
  | 'pyramid'
  | 'picture'

SmartArtConfig

Configuration for creating a new diagram.

type SmartArtConfig = {
  /** Layout ID (e.g., 'hierarchy/org-chart', 'process/basic-process'). */
  layoutId: string;
  /** X position in pixels. */
  x?: number;
  /** Y position in pixels. */
  y?: number;
  /** Width in pixels. */
  width?: number;
  /** Height in pixels. */
  height?: number;
  /** Initial nodes to create. */
  nodes?: SmartArtNodeConfig[];
  /** Display name. */
  name?: string;
}

SmartArtDiagram

diagram model (deserialized TypeScript view). IMPORTANT: This interface represents the runtime/API view of the data. Actual Yjs storage uses Y.Map and Y.Array types as defined in SMARTART_DIAGRAM_SCHEMA. The bridge handles conversion between formats. NOTE: computedLayout is NOT part of this interface because it's a runtime cache managed by the bridge, not persisted data. COPY SEMANTICS: When copying a diagramDiagram, the bridge must: 1. Generate new NodeIds for all nodes (using createNodeId()) 2. Build oldId -> newId mapping 3. Deep-copy node data (text, styling, level, siblingOrder) 4. Remap parentId and childIds references using mapping 5. Update rootNodeIds array with new IDs 6. Preserve tree structure with new identity

type SmartArtDiagram = {
  /** Layout ID (e.g., 'hierarchy/org-chart', 'process/basic-process') */
  layoutId: string;
  /** Category of the diagram */
  category: SmartArtCategory;
  /** Map of all nodes by their ID */
  nodes: Map<NodeId, SmartArtNode>;
  /** Top-level (root) node IDs in display order */
  rootNodeIds: NodeId[];
  /** Quick style ID (e.g., 'subtle-effect', 'moderate-effect') */
  quickStyleId: string;
  /** Color theme ID (e.g., 'colorful-1', 'accent-1') */
  colorThemeId: string;
  /** Layout-specific options (varies by layout type) */
  layoutOptions: Record<string, unknown>;
}

SmartArtNode

Single node in a diagram. Nodes form a tree structure with parent-child relationships. Each node can have optional per-node styling that overrides diagram defaults.

type SmartArtNode = {
  /** Unique node identifier */
  id: NodeId;
  /** Text content displayed in the node */
  text: string;
  /** Hierarchy level (0 = root, 1 = child, 2 = grandchild, etc.) */
  level: number;
  /** Parent node ID (null for root nodes) */
  parentId: NodeId | null;
  /** Ordered child node IDs */
  childIds: NodeId[];
  /** Order among siblings (used for layout ordering) */
  siblingOrder: number;
  /** Fill/background color (CSS color string) */
  fillColor?: string;
  /** Border/stroke color (CSS color string) */
  borderColor?: string;
  /** Text color (CSS color string) */
  textColor?: string;
  /** Font family for node text */
  fontFamily?: string;
  /** Font size in points */
  fontSize?: number;
  /** Font weight */
  fontWeight?: 'normal' | 'bold';
  /** Font style */
  fontStyle?: 'normal' | 'italic';
  /** Image URL for picture layouts */
  imageUrl?: string;
  /** How the image fits within the node bounds */
  imageFit?: 'cover' | 'contain' | 'fill';
}

SmartArtNodeConfig

Configuration for a diagram node.

type SmartArtNodeConfig = {
  /** Node text content. */
  text: string;
  /** Hierarchy level (0 = root). */
  level?: number;
  /** Insertion position relative to a reference node. */
  position?: 'before' | 'after' | 'child';
  /** Reference node ID for positioning. */
  referenceNodeId?: string;
}

SmartArtNodeId

Diagram node ID type.

type SmartArtNodeId = string

SmartArtObject

Diagram floating object. Diagrams provide visual representations of information like organization charts, process flows, relationship diagrams, and hierarchies. The diagram data contains the nodes and their relationships, while layout/styling is computed at render time. Architecture Notes: - Diagram data (nodes, relationships) is persisted in Yjs via the bridge layer - Selection state (selectedNodeIds, editingNodeId) lives in XState context, NOT here - Computed layout is a runtime cache, managed by the bridge - Uses existing object-interaction-machine for selection/drag/resize

type SmartArtObject = {
  type: 'smartart';
  /** The diagram data including nodes, relationships, and styling.
This is the persisted data - layout is computed at runtime. */
  diagram: SmartArtDiagram;
}

SmartArtShapeType

diagram-specific shape types. This is a subset of the full ShapeType union from floating-objects.ts that diagram layouts commonly use. The names match exactly with the ShapeType definitions to ensure compatibility.

type SmartArtShapeType = | 'rect'
  | 'roundRect'
  | 'ellipse'
  | 'diamond'
  | 'hexagon'
  | 'chevron'
  | 'rightArrow'
  | 'pentagon'
  | 'trapezoid'
  | 'parallelogram'
  | 'plus'
  | 'star5'
  | 'cloud'
  | 'wedgeRectCallout'

SoftEdgeEffect

Soft edge effect (feathered edges). Creates a gradual fade-out at the edges of the text, making the text appear to blend into the background. The effect creates a smooth transition from fully opaque text to fully transparent at the edges. @example // Soft fade at edges const softEdge: SoftEdgeEffect = { radius: 25400 // 2pt feather radius }; @see ECMA-376 Part 1, Section 20.1.8.57 (softEdge)

type SoftEdgeEffect = {
  /** Soft edge radius in EMUs.
How far inward from the text edge the fade begins.
Larger values create a more gradual fade.

@example 25400 // 2pt radius */
  radius: number;
}

SolidFill

Solid fill — post-theme-resolution using CSS color strings. The OOXML raw version (with DrawingColor) is in the generated ooxml-types.ts bridge. @see ECMA-376 Part 1, Section 20.1.8.51 (CT_SolidColorFillProperties)

type SolidFill = {
  type: 'solid';
  /** Fill color (CSS color string: hex, rgb, rgba, hsl, named) */
  color: string;
  /** Opacity (0-1, where 0 is fully transparent, 1 is fully opaque) */
  opacity?: number;
}

SortByColorOptions

Options for {@link Worksheet.sortByColor}. Sorts the rows of a range by a color predicate on a single column. Matched-color rows are placed on top (`position: 'top'`) or bottom (`position: 'bottom'`) of the range; ties fall through to natural row order (stable sort).

type SortByColorOptions = {
  /** Column index (0-based, absolute) whose color drives the sort. */
  column: number;
  /** Whether to compare against fill (cell background) or font color. */
  colorType: 'fill' | 'font';
  /** Hex color to match (e.g. '#FFFF00'). Case-insensitive. */
  color: string;
  /** Place matched-color rows on top of the range or at the bottom. */
  position: 'top' | 'bottom';
  /** Whether the first row of the range is a header row (default: false). */
  hasHeaders?: boolean;
  /** Sort only currently visible row slots, preserving hidden row positions. */
  visibleRowsOnly?: boolean;
}

SortColumn

A single column sort specification. Discriminated on `sortBy`. The default ('value') accepts an optional Workbook `customList`. Color sorts (`cellColor` / `fontColor`) require a `targetColor` and `colorPosition` so invalid combinations cannot be expressed.

type SortColumn = {
  /** Column index (0-based, relative to the sort range) */
  column: number;
  /** Sort direction: 'asc' (default) or 'desc'. */
  direction?: 'asc' | 'desc';
  /** Case sensitive comparison (default: false) */
  caseSensitive?: boolean;
} & (
  | {
      /** What to sort by (default: 'value' if omitted) */
      sortBy?: 'value';
      /**
       * Optional Excel custom-list sort: values present in the list
       * sort by their list position; values not in the list sort
       * *after* list members (spreadsheet compatibility).
       */
      customList?: CellValue[];
    }
  | {
      sortBy: 'cellColor' | 'fontColor';
      /** Hex color to match (e.g. '#FFFF00'). */
      targetColor: string;
      /** Whether matched rows go to top or bottom of the sorted range. */
      colorPosition: 'top' | 'bottom';
    }
)

SortOptions

Options for sorting a range of cells.

type SortOptions = {
  /** Columns to sort by, in priority order */
  columns: SortColumn[];
  /** Whether the first row of the range contains headers (default: false) */
  hasHeaders?: boolean;
  /** Sort only currently visible row slots, preserving hidden row positions. */
  visibleRowsOnly?: boolean;
}

SortOrder

Sort order for pivot fields. "none" means no explicit sort — uses natural order. Maps to Option<SortDirection> on the Rust side (None = "none").

type SortOrder = 'asc' | 'desc' | 'none'

Sparkline

type Sparkline = {
  id: string;
  sheetId: SheetId;
  cell: SparklineCellAddress;
  dataRange: SparklineDataRange;
  type: SparklineType;
  dataInRows: boolean;
  groupId?: string;
  visual: SparklineVisualSettings;
  axis: SparklineAxisSettings;
  createdAt?: number;
  updatedAt?: number;
}

SparklineAxisSettings

type SparklineAxisSettings = {
  minValue: AxisBound;
  maxValue: AxisBound;
  showAxis?: boolean;
  axisColor?: string;
  displayEmptyCells: EmptyCellDisplay;
  rightToLeft?: boolean;
}

SparklineCellAddress

type SparklineCellAddress = {
  sheetId: string;
  row: number;
  col: number;
}

SparklineDataRange

type SparklineDataRange = {
  startRow: number;
  startCol: number;
  endRow: number;
  endCol: number;
}

SparklineGroup

type SparklineGroup = {
  id: string;
  sheetId: string;
  sparklineIds: string[];
  type: SparklineType;
  visual: SparklineVisualSettings;
  axis: SparklineAxisSettings;
  createdAt?: number;
  updatedAt?: number;
}

SparklineType

type SparklineType = "line" | "column" | "winLoss"

SparklineVisualSettings

type SparklineVisualSettings = {
  color: string;
  negativeColor?: string;
  showMarkers?: boolean;
  markerColor?: string;
  highPointColor?: string;
  lowPointColor?: string;
  firstPointColor?: string;
  lastPointColor?: string;
  lineWeight?: number;
  columnGap?: number;
  barGap?: number;
}

SplitViewportConfig

Split view: 2-4 independently scrolling viewports. Split view creates independent panes that can each scroll separately, allowing users to compare distant regions of the spreadsheet. Viewport IDs by direction: - 'horizontal': 'top', 'bottom' (split along a row) - 'vertical': 'left', 'right' (split along a column) - 'both': 'topLeft', 'topRight', 'bottomLeft', 'bottomRight' (4 quadrants) @see plans/active/excel-parity/01-split-view-not-implemented.md

type SplitViewportConfig = {
  type: 'split';
  /** Direction of the split */
  direction: 'horizontal' | 'vertical' | 'both';
  /** Row index for horizontal split line.
Used when direction is 'horizontal' or 'both'.
Defaults to 0 (ignored) when direction is 'vertical'. */
  horizontalPosition: number;
  /** Column index for vertical split line.
Used when direction is 'vertical' or 'both'.
Defaults to 0 (ignored) when direction is 'horizontal'. */
  verticalPosition: number;
}

StockSubType

Stock chart sub-types (OHLC = Open-High-Low-Close)

type StockSubType = 'hlc' | 'ohlc' | 'volume-hlc' | 'volume-ohlc'

StripePattern

type StripePattern = {
  stripeSize: number;
  stripe1Fill?: string;
  stripe2Fill?: string;
}

StrokeId

Unique identifier for a stroke within a drawing. Branded type provides type safety - prevents accidentally using string IDs where StrokeId is expected (and vice versa). Uses UUID v7 (time-sortable) for: - Uniqueness across clients (no coordination needed) - Time-sortability for undo/redo ordering - Compact string representation

type StrokeId = string & { readonly __brand: 'StrokeId' }

StrokeTransformParams

Transform parameters for stroke transformations.

type StrokeTransformParams = {
  /** Transform type */
  type: StrokeTransformType;
  /** Center point X for rotation/scale */
  centerX?: number;
  /** Center point Y for rotation/scale */
  centerY?: number;
  /** Rotation angle in radians (for 'rotate') */
  angle?: number;
  /** Scale factor X (for 'scale') */
  scaleX?: number;
  /** Scale factor Y (for 'scale') */
  scaleY?: number;
}

StrokeTransformType

Transform type for stroke transformations.

type StrokeTransformType = 'rotate' | 'scale' | 'flip-horizontal' | 'flip-vertical'

StyleCategory

Style category for grouping styles in the UI gallery.

type StyleCategory = | 'good-bad-neutral' // Good, Bad, Neutral
  | 'data-model' // Calculation, Check Cell, etc.
  | 'titles-headings' // Title, Heading 1-4
  | 'themed' // Accent1-6 variations
  | 'number-format' // Currency, Percent, Comma
  | 'custom'

SubPath

A single subpath within a compound path.

type SubPath = {
  segments: PathSegment[];
  closed: boolean;
}

SubSupNode

Sub-Superscript - <m:sSubSup>

type SubSupNode = {
  type: 'sSubSup';
  /** Align scripts */
  alnScr?: boolean;
  /** Base */
  e: MathNode[];
  /** Subscript */
  sub: MathNode[];
  /** Superscript */
  sup: MathNode[];
}

SubscriptNode

Subscript - <m:sSub>

type SubscriptNode = {
  type: 'sSub';
  /** Base */
  e: MathNode[];
  /** Subscript */
  sub: MathNode[];
}

SubtotalConfig

Configuration for the subtotal operation.

type SubtotalConfig = {
  /** Target range to subtotal */
  range: CellRange;
  /** Whether the target range includes a header row */
  hasHeaders: boolean;
  /** Column index to group by (0-based) */
  groupByColumn: number;
  /** Columns to subtotal (0-based indices) */
  subtotalColumns: number[];
  /** Aggregation function to use */
  aggregation: 'sum' | 'count' | 'average' | 'max' | 'min';
  /** Whether to replace existing subtotals */
  replace?: boolean;
  /** Whether summary rows appear below their detail rows */
  summaryBelowData?: boolean;
}

SubtotalLocation

type SubtotalLocation = 'top' | 'bottom'

SubtotalResult

Result of creating subtotals.

type SubtotalResult = {
  /** Number of row groups created */
  groupsCreated: number;
  /** Number of subtotal rows inserted */
  subtotalRowsInserted: number;
  /** Range affected by the subtotal operation */
  affectedRange: CellRange;
}

SummaryOptions

Options for the `worksheet.summarize()` method.

type SummaryOptions = {
  /** Whether to include sample data in the summary */
  includeData?: boolean;
  /** Maximum number of rows to include in sample data */
  maxRows?: number;
  /** Maximum number of columns to include in sample data */
  maxCols?: number;
}

SunburstConfig

Sunburst chart configuration

type SunburstConfig = {
  /** Number of hierarchy levels to display */
  levels?: number;
  /** Show category labels on each arc */
  showLabels?: boolean;
  /** Color scale for sunburst arcs */
  colorScale?: string[];
  /** Inner radius as fraction of outer radius (0-1) */
  innerRadius?: number;
}

SuperscriptNode

Superscript - <m:sSup>

type SuperscriptNode = {
  type: 'sSup';
  /** Base */
  e: MathNode[];
  /** Superscript */
  sup: MathNode[];
}

TableAddColumnReceipt

Receipt for a table addColumn mutation.

type TableAddColumnReceipt = {
  kind: 'tableAddColumn';
  tableName: string;
  columnName: string;
  position: number;
}

TableAddRowReceipt

Receipt for a table addRow mutation.

type TableAddRowReceipt = {
  kind: 'tableAddRow';
  tableName: string;
  index: number;
}

TableColumn

A single column in a table. Field names match the Rust-generated `TableColumn` type (compute-types.gen.ts).

type TableColumn = {
  /** Unique column ID */
  id: string;
  /** Column header name */
  name: string;
  /** Column index within the table (0-based) */
  index: number;
  /** Total row function type */
  totalsFunction: TotalsFunction | null;
  /** Total row label */
  totalsLabel: string | null;
  /** Calculated column formula */
  calculatedFormula?: string;
}

TableDeleteRowReceipt

Receipt for a table deleteRow mutation.

type TableDeleteRowReceipt = {
  kind: 'tableDeleteRow';
  tableName: string;
  index: number;
}

TableElementStyle

type TableElementStyle = {
  fill?: string;
  fontColor?: string;
  fontBold?: boolean;
  borderTop?: string;
  borderBottom?: string;
  borderLeft?: string;
  borderRight?: string;
}

TableInfo

Information about an existing table. Field names match the Rust-generated `Table` type (compute-types.gen.ts) except `range` which is converted from `SheetRange` to A1 notation string.

type TableInfo = {
  /** Internal table identifier */
  id: string;
  /** Table name */
  name: string;
  /** Display name */
  displayName: string;
  /** Sheet the table belongs to */
  sheetId: string;
  /** Table range in A1 notation (converted from Rust SheetRange) */
  range: string;
  /** Column definitions */
  columns: TableColumn[];
  /** Whether the table has a header row */
  hasHeaderRow: boolean;
  /** Whether the totals row is visible */
  hasTotalsRow: boolean;
  /** Table style name */
  style: string;
  /** Whether banded rows are shown */
  bandedRows: boolean;
  /** Whether banded columns are shown */
  bandedColumns: boolean;
  /** Whether first column is emphasized */
  emphasizeFirstColumn: boolean;
  /** Whether last column is emphasized */
  emphasizeLastColumn: boolean;
  /** Whether filter buttons are shown */
  showFilterButtons: boolean;
  /** Whether the table automatically expands when adjacent user input is entered */
  autoExpand: boolean;
  /** Whether formulas entered in table data columns automatically create/fill calculated columns */
  autoCalculatedColumns: boolean;
}

TableOptions

Options for creating a new table.

type TableOptions = {
  /** Table name (auto-generated if omitted) */
  name?: string;
  /** Whether the first row of the range contains headers (default: true) */
  hasHeaders?: boolean;
  /** Table style preset name */
  style?: string;
  /** Whether the table automatically expands when adjacent user input is entered (default: true) */
  autoExpand?: boolean;
  /** Whether formulas entered in table data columns automatically create/fill calculated columns (default: true) */
  autoCalculatedColumns?: boolean;
}

TableRemoveColumnReceipt

Receipt for a table removeColumn mutation.

type TableRemoveColumnReceipt = {
  kind: 'tableRemoveColumn';
  tableName: string;
  columnIndex: number;
}

TableResizeReceipt

Receipt for a table resize mutation.

type TableResizeReceipt = {
  kind: 'tableResize';
  tableName: string;
  newRange: string;
}

TableRowCollection

A collection-like wrapper around a table's data rows. Returned by `WorksheetTables.getRows()`. The `count` property is a snapshot taken at construction time and does NOT live-update.

type TableRowCollection = {
  /** Number of data rows (snapshot, not live). */
  count: number;
  /** Get the cell values of a data row by index. */
  getAt(index: number): Promise<CellValue[]>;;
  /** Add a data row. If index is omitted, appends to the end. */
  add(index?: number, values?: CellValue[]): Promise<TableAddRowReceipt>;;
  /** Delete a data row by index. */
  deleteAt(index: number): Promise<TableDeleteRowReceipt>;;
  /** Get the cell values of a data row by index. */
  getValues(index: number): Promise<CellValue[]>;;
  /** Set the cell values of a data row by index. */
  setValues(index: number, values: CellValue[]): Promise<void>;;
  /** Get the A1-notation range for a data row by index. */
  getRange(index: number): Promise<string>;;
}

TableStyleConfig

Configuration for creating/updating a custom table style.

type TableStyleConfig = {
  /** Optional legacy style name. `WorkbookTableStyles.add(name, style)` owns the
canonical name through its first argument. */
  name?: string;
  headerRow?: TableElementStyle;
  totalRow?: TableElementStyle;
  firstColumn?: TableElementStyle;
  lastColumn?: TableElementStyle;
  rowStripes?: StripePattern;
  columnStripes?: StripePattern;
  wholeTable?: TableElementStyle;
}

TableStyleInfo

type TableStyleInfo = {
  id: string;
  name: string;
  createdAt: number;
  updatedAt: number;
  headerRow: TableElementStyle;
  totalRow: TableElementStyle;
  firstColumn: TableElementStyle;
  lastColumn: TableElementStyle;
  rowStripes: StripePattern;
  columnStripes: StripePattern;
  wholeTable: TableElementStyle;
}

TableStyleInfoWithReadOnly

A table style with a computed `readOnly` flag (built-in styles are read-only).

type TableStyleInfoWithReadOnly = TableStyleInfo & { readOnly: boolean }

TableUpdateOptions

Options for updating a table's properties via `WorksheetTables.update()`.

type TableUpdateOptions = {
  /** Table style preset name (e.g. "TableStyleLight1"). */
  style?: string;
  /** New table name (renames the table). */
  name?: string;
  /** Whether the first column is emphasized. */
  emphasizeFirstColumn?: boolean;
  /** Whether the last column is emphasized. */
  emphasizeLastColumn?: boolean;
  /** Whether banded columns are shown. */
  bandedColumns?: boolean;
  /** Whether banded rows are shown. */
  bandedRows?: boolean;
  /** Whether filter buttons are shown on the header row. */
  showFilterButtons?: boolean;
  /** Whether the header row is visible. */
  hasHeaderRow?: boolean;
  /** Whether the totals row is visible. */
  hasTotalsRow?: boolean;
  /** Whether the table automatically expands when adjacent user input is entered. */
  autoExpand?: boolean;
  /** Whether formulas entered in table data columns automatically create/fill calculated columns. */
  autoCalculatedColumns?: boolean;
}

TagMatcher

Glob-matchable tag pattern for matching against principal tags. Examples: - `"agent:copilot"` — exact match - `"agent:*"` — all agents - `"sf:role:*"` — all Salesforce roles - `"*"` — everyone

type TagMatcher = string

TargetMatcher

Target matcher — same structure as AccessTarget but allows `'*'` wildcards for IDs to match any resource of that kind.

type TargetMatcher = | { readonly kind: 'workbook' }
  | { readonly kind: 'sheet'; readonly sheetId: SheetId | '*' }
  | { readonly kind: 'column'; readonly colId: ColId | '*'; readonly sheetId: SheetId | '*' }

TextAutoSize

How text auto-sizes within its container.

type TextAutoSize = | { type: 'none' }
  | { type: 'textToFitShape'; fontScale?: number; lineSpacingReduction?: number }
  | { type: 'shapeToFitText' }

TextBoxBorder

Text box border with optional corner radius.

type TextBoxBorder = {
  /** Corner radius in pixels (for rounded corners) */
  radius?: number;
}

TextBoxConfig

Configuration for creating a new text box.

type TextBoxConfig = {
  /** Text content and formatting — shared model with ShapeData. */
  text?: ShapeText;
  /** Anchor cell as `{row, col}`. When set, `x`/`y` are offsets from this
cell instead of from cell `(0, 0)`. */
  anchorCell?: { row: number; col: number };
  /** X position in pixels. */
  x?: number;
  /** Y position in pixels. */
  y?: number;
  /** Width in pixels (default: 200). */
  width?: number;
  /** Height in pixels (default: 100). */
  height?: number;
  /** Display name. */
  name?: string;
}

TextBoxHandle

type TextBoxHandle = {
  update(props: Partial<TextBoxConfig>): Promise<void>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<TextBoxHandle>;;
  getData(): Promise<TextBoxObject>;;
}

TextBoxObject

Text box floating object. A rectangular container for rich text content.

type TextBoxObject = {
  type: 'textbox';
  /** Text content and formatting — shared model with ShapeData. */
  text?: ShapeText;
  /** Fill color/gradient for the text box background */
  fill?: ObjectFill;
  /** Border around the text box */
  border?: TextBoxBorder;
  /** Optional text-effect configuration for styled text effects */
  wordArt?: WordArtConfig;
}

TextEffects

Container for all text effects. Groups all visual effects that can be applied to text-effect text. Effects are applied in a specific order to ensure correct visual stacking: **Effect Application Order:** 1. Text fill and outline (base rendering) 2. Outer shadow (rendered behind text) 3. Glow (rendered around text edges) 4. Inner shadow (rendered inside text) 5. Soft edges (feathers text edges) 6. Reflection (rendered below text) 7. 3D bevel (adds depth to edges) 8. 3D rotation and perspective (transforms entire result) Note: You can use either `presetShadow` for quick shadow application, or `outerShadow`/`innerShadow` for custom shadow configuration. Using both may produce unexpected results. @example // Dramatic text effects const effects: TextEffects = { outerShadow: { blurRadius: 50800, distance: 38100, direction: 45, color: '#000000', opacity: 0.4 }, glow: { radius: 63500, color: '#FFD700', opacity: 0.6 }, bevel: { topPreset: 'circle', topWidth: 38100, topHeight: 38100 } }; @see ECMA-376 Part 1, Section 20.1.8 (DrawingML - Effect)

type TextEffects = {
  /** Outer shadow effect.
Creates a shadow behind and offset from the text.
For quick shadow setup, consider using `presetShadow` instead. */
  outerShadow?: OuterShadowEffect;
  /** Inner shadow effect.
Creates a shadow inside the text edges for an embossed look. */
  innerShadow?: InnerShadowEffect;
  /** Preset shadow (alternative to custom shadow).
Use this for quick application of standard shadow styles.
Choose from 20 predefined shadow configurations (shdw1-shdw20).
If both `presetShadow` and `outerShadow`/`innerShadow` are specified,
the custom shadow settings take precedence. */
  presetShadow?: PresetShadowType;
  /** Glow effect.
Creates a soft colored glow around the text. */
  glow?: GlowEffect;
  /** Soft edge effect.
Creates feathered/faded edges on the text. */
  softEdge?: SoftEdgeEffect;
  /** Reflection effect.
Creates a mirror reflection below the text. */
  reflection?: ReflectionEffect;
  /** Bevel effect.
Creates 3D beveled edges on the text.
Can apply different bevels to top and bottom edges. */
  bevel?: BevelEffect;
  /** 3D rotation effect.
Rotates text in 3D space and applies perspective.
Includes lighting and material settings for realistic 3D rendering. */
  transform3D?: Transform3DEffect;
}

TextMargins

Text margins within a text box or shape.

type TextMargins = {
  /** Top margin in pixels */
  top: number;
  /** Right margin in pixels */
  right: number;
  /** Bottom margin in pixels */
  bottom: number;
  /** Left margin in pixels */
  left: number;
}

TextOrientation

Text orientation within a shape.

type TextOrientation = | 'horizontal'
  | 'vertical'
  | 'vertical270'
  | 'wordArtVertical'
  | 'eastAsianVertical'
  | 'mongolianVertical'

TextOverflow

Text overflow behavior.

type TextOverflow = 'overflow' | 'clip' | 'ellipsis'

TextReadingOrder

Text reading order / directionality.

type TextReadingOrder = 'leftToRight' | 'rightToLeft'

TextRun

A single text run within a paragraph. Corresponds to the `a:r` element. Contains text content and run-level formatting properties. @see ECMA-376 Part 1, Section 21.1.2.3.8 (a:r)

type TextRun = {
  /** The actual text content of this run. */
  text: string;
  /** Run-level formatting properties. */
  properties?: TextRunProperties;
}

TextRunProperties

Text run properties (a:rPr). Controls character-level formatting such as font, size, color, bold, italic, underline, etc. @see ECMA-376 Part 1, Section 21.1.2.3.9 (a:rPr)

type TextRunProperties = {
  /** Bold text. */
  bold?: boolean;
  /** Italic text. */
  italic?: boolean;
  /** Underline style. */
  underline?: TextUnderlineType;
  /** Strikethrough style. */
  strikethrough?: 'noStrike' | 'sngStrike' | 'dblStrike';
  /** Font family name (Latin script). */
  fontFamily?: string;
  /** East Asian font family name. */
  fontFamilyEastAsian?: string;
  /** Complex script font family name. */
  fontFamilyComplexScript?: string;
  /** Font size in hundredths of a point.
For example, 1200 = 12pt. */
  fontSize?: number;
  /** Text color. */
  color?: DmlColorValue;
  /** Character spacing (tracking) in hundredths of a point. */
  spacing?: number;
  /** Baseline shift as a percentage (positive = superscript, negative = subscript). */
  baseline?: number;
  /** Whether text is capitalized. */
  cap?: 'none' | 'small' | 'all';
  /** Text language (BCP 47 language tag, e.g., "en-US"). */
  lang?: string;
  /** Whether the run is a hyperlink. */
  hyperlink?: HyperlinkInfo;
}

TextStyle

Text styling properties for node labels.

type TextStyle = {
  /** Font family name */
  fontFamily: string;
  /** Font size in points */
  fontSize: number;
  /** Font weight */
  fontWeight: 'normal' | 'bold';
  /** Font style */
  fontStyle: 'normal' | 'italic';
  /** Text color (CSS color string) */
  color: string;
  /** Horizontal text alignment */
  align: 'left' | 'center' | 'right';
  /** Vertical text alignment */
  verticalAlign: 'top' | 'middle' | 'bottom';
}

TextToColumnsDelimiters

Delimiter set for text-to-columns splitting. Multiple delimiters may be enabled.

type TextToColumnsDelimiters = {
  /** Split on tab characters. */
  tab?: boolean;
  /** Split on semicolons. */
  semicolon?: boolean;
  /** Split on commas. */
  comma?: boolean;
  /** Split on spaces. */
  space?: boolean;
  /** Split on this custom delimiter character/string. */
  other?: string;
}

TextToColumnsDestination

Destination cell for text-to-columns output.

type TextToColumnsDestination = {
  /** Zero-based row index. */
  row: number;
  /** Zero-based column index. */
  col: number;
}

TextToColumnsOptions

Options for text-to-columns splitting.

type TextToColumnsOptions = {
  /** Split mode. Defaults to 'delimited' when omitted. */
  type?: 'delimited' | 'fixedWidth';
  /** Legacy single delimiter selector. Defaults to 'comma' when `delimiters`
is omitted. Use `delimiters` when more than one delimiter is selected. */
  delimiter?: 'comma' | 'tab' | 'semicolon' | 'space' | 'custom';
  /** Custom delimiter character (when delimiter is 'custom') */
  customDelimiter?: string;
  /** Full delimiter set. Takes precedence over `delimiter` when provided. */
  delimiters?: TextToColumnsDelimiters;
  /** Destination cell. Defaults to the top-left source cell. */
  destination?: string | TextToColumnsDestination;
  /** Whether to treat consecutive delimiters as one */
  treatConsecutiveAsOne?: boolean;
  /** Text qualifier character */
  textQualifier?: '"' | "'" | 'none';
  /** Zero-based character offsets at which to split (fixedWidth mode). */
  fixedWidthBreaks?: number[];
}

TextToColumnsResult

Result of a text-to-columns operation.

type TextToColumnsResult = {
  /** Number of source rows processed. */
  rowsProcessed: number;
  /** Maximum number of destination columns produced by any processed row. */
  columnsCreated: number;
}

TextWarpPreset

Text-Effect Types Implements DrawingML text warp and effects from ECMA-376 Part 1. Decorative text is NOT a separate floating object type - it's a configuration that can be applied to TextBoxObject to add warping and effects. @see ECMA-376 Part 1, Section 20.1.10 (Text Body Properties) @see ECMA-376 Part 1, Section 20.1.10.78 (ST_TextShapeType)

type TextWarpPreset = | 'textNoShape' // OOXML compatibility - no shape transformation
  | 'textPlain' // Plain text with no transformation

  // Arc paths (text follows curved arc)
  | 'textArchUp'
  | 'textArchDown'
  | 'textCircle'
  | 'textButton'

  // Arc paths with fill (poured effect)
  | 'textArchUpPour'
  | 'textArchDownPour'
  | 'textCirclePour'
  | 'textButtonPour'

  // Curve effects (upward/downward Bezier curves)
  | 'textCurveUp'
  | 'textCurveDown'

  // Wave effects (sinusoidal distortion)
  | 'textWave1'
  | 'textWave2'
  | 'textDoubleWave1'
  | 'textWave4'

  // Inflate/deflate effects (bulge/pinch)
  | 'textInflate'
  | 'textDeflate'
  | 'textInflateBottom'
  | 'textDeflateBottom'
  | 'textInflateTop'
  | 'textDeflateTop'
  | 'textDeflateInflate'
  | 'textDeflateInflateDeflate'

  // Fade effects (perspective scaling)
  | 'textFadeRight'
  | 'textFadeLeft'
  | 'textFadeUp'
  | 'textFadeDown'

  // Slant effects (shear transformation)
  | 'textSlantUp'
  | 'textSlantDown'

  // Cascade effects (stair-step)
  | 'textCascadeUp'
  | 'textCascadeDown'

  // Additional geometric warps
  | 'textTriangle'
  | 'textTriangleInverted'
  | 'textChevron'
  | 'textChevronInverted'
  | 'textRingInside'
  | 'textRingOutside'
  | 'textStop'
  | 'textCanUp'
  | 'textCanDown'

ThemeColorSlot

All valid theme color slot names

type ThemeColorSlot = keyof ThemeColors

ThemeColors

Theme Contracts Type definitions and utilities for workbook themes. Themes define color palettes and font pairs that cells can reference. Issue 4: Page Layout - Themes

type ThemeColors = {
  /** Primary dark color - typically black/near-black for text */
  dark1: string;
  /** Primary light color - typically white for backgrounds */
  light1: string;
  /** Secondary dark color */
  dark2: string;
  /** Secondary light color */
  light2: string;
  /** Accent color 1 - primary accent (blue in Office default) */
  accent1: string;
  /** Accent color 2 - typically orange */
  accent2: string;
  /** Accent color 3 - typically gray */
  accent3: string;
  /** Accent color 4 - typically yellow/gold */
  accent4: string;
  /** Accent color 5 - typically blue-gray */
  accent5: string;
  /** Accent color 6 - typically green */
  accent6: string;
  /** Hyperlink color */
  hyperlink: string;
  /** Followed hyperlink color */
  followedHyperlink: string;
}

ThemeDefinition

Complete theme definition including colors and fonts.

type ThemeDefinition = {
  /** Unique theme identifier (e.g., 'office', 'slice', 'custom-abc123') */
  id: string;
  /** Display name shown in UI (e.g., 'Office', 'Slice') */
  name: string;
  /** Theme color palette */
  colors: ThemeColors;
  /** Theme font pair */
  fonts: ThemeFonts;
  /** True for built-in themes, false for user-created */
  builtIn: boolean;
}

ThemeFonts

Theme font pair - major (headings) and minor (body) fonts.

type ThemeFonts = {
  /** Font for headings (e.g., 'Calibri Light') */
  majorFont: string;
  /** Font for body text (e.g., 'Calibri') */
  minorFont: string;
}

TileSettings

Tile settings for picture/texture fills.

type TileSettings = {
  tx?: number;
  ty?: number;
  sx?: number;
  sy?: number;
  flip?: string;
  algn?: string;
}

TimelineLevel

Timeline aggregation level. Determines how dates are grouped in the timeline display.

type TimelineLevel = 'years' | 'quarters' | 'months' | 'days'

TimelinePeriod

A period in a timeline slicer.

type TimelinePeriod = {
  /** Period label */
  label: string;
  /** Period start date (ISO string) */
  start: string;
  /** Period end date (ISO string) */
  end: string;
  /** Whether this period is selected */
  selected: boolean;
}

TimelineSlicerConfig

Timeline slicer specific configuration. Extends base slicer for date-range filtering.

type TimelineSlicerConfig = {
  /** Source must be table or pivot with date column */
  sourceType: 'timeline';
  /** Current aggregation level */
  timelineLevel: TimelineLevel;
  /** Start date of the data range */
  dataStartDate?: number;
  /** End date of the data range */
  dataEndDate?: number;
  /** Currently selected date range start */
  selectedStartDate?: number;
  /** Currently selected date range end */
  selectedEndDate?: number;
  /** Show the level selector in the header */
  showLevelSelector: boolean;
  /** Show the date range label */
  showDateRangeLabel: boolean;
}

TimelineStyleInfo

type TimelineStyleInfo = {
  name: string;
  isDefault: boolean;
}

TitleConfig

Rich title configuration

type TitleConfig = {
  text?: string;
  visible?: boolean;
  position?: 'top' | 'bottom' | 'left' | 'right' | 'overlay';
  font?: ChartFont;
  format?: ChartFormat;
  overlay?: boolean;
  /** Text orientation angle in degrees (-90 to 90) */
  textOrientation?: number;
  richText?: ChartFormatString[];
  formula?: string;
  /** Horizontal text alignment. */
  horizontalAlignment?: 'left' | 'center' | 'right';
  /** Vertical text alignment. */
  verticalAlignment?: 'top' | 'middle' | 'bottom';
  /** Show drop shadow on title. */
  showShadow?: boolean;
  /** Height in points (read-only, populated from render engine). */
  height?: number;
  /** Width in points (read-only, populated from render engine). */
  width?: number;
  /** Left position in points (read-only, populated from render engine). */
  left?: number;
  /** Top position in points (read-only, populated from render engine). */
  top?: number;
}

TopBottomBy

type TopBottomBy = 'items' | 'percent' | 'sum'

TopBottomType

type TopBottomType = 'top' | 'bottom'

TotalsFunction

Totals function type (matches Rust TotalsFunction).

type TotalsFunction = | 'average'
  | 'count'
  | 'countNums'
  | 'max'
  | 'min'
  | 'stdDev'
  | 'sum'
  | 'var'
  | 'custom'
  | 'none'

Transform3DEffect

3D transformation effect configuration.

type Transform3DEffect = {
  /** Rotation around X axis in degrees */
  rotationX: number;
  /** Rotation around Y axis in degrees */
  rotationY: number;
  /** Rotation around Z axis in degrees */
  rotationZ: number;
  /** Perspective distance for 3D effect */
  perspective: number;
}

TreemapConfig

Treemap chart configuration

type TreemapConfig = {
  /** Number of hierarchy levels to display */
  levels?: number;
  /** Show category labels on each rectangle */
  showLabels?: boolean;
  /** Color scale for treemap rectangles */
  colorScale?: string[];
  /** Layout algorithm */
  layoutAlgorithm?: 'squarified' | 'slice' | 'dice' | 'sliceDice';
}

TrendlineConfig

Trendline configuration (matches TrendlineData wire type)

type TrendlineConfig = {
  show?: boolean;
  type?: string;
  color?: string;
  lineWidth?: number;
  order?: number;
  period?: number;
  forward?: number;
  backward?: number;
  intercept?: number;
  displayEquation?: boolean;
  displayRSquared?: boolean;
  name?: string;
  lineFormat?: ChartLineFormat;
  label?: TrendlineLabelConfig;
  /** @deprecated Use displayEquation instead */
  showEquation?: boolean;
  /** @deprecated Use displayRSquared instead */
  showR2?: boolean;
  /** @deprecated Use forward instead */
  forwardPeriod?: number;
  /** @deprecated Use backward instead */
  backwardPeriod?: number;
}

TrendlineLabelConfig

Trendline label configuration.

type TrendlineLabelConfig = {
  text?: string;
  format?: ChartFormat;
  numberFormat?: string;
}

UndoHistoryEntry

An entry in the undo history.

type UndoHistoryEntry = {
  /** Unique identifier for this entry. */
  id: string;
  /** Description of the operation. */
  description: string;
  /** Timestamp of the operation (Unix ms). */
  timestamp: number;
}

UndoReceipt

Receipt for an undo operation.

type UndoReceipt = {
  kind: 'undo';
  success: boolean;
}

UndoServiceState

Undo service state

type UndoServiceState = {
  /** Whether undo is available */
  canUndo: boolean;
  /** Whether redo is available */
  canRedo: boolean;
  /** Number of items in undo stack */
  undoStackSize: number;
  /** Number of items in redo stack */
  redoStackSize: number;
  /** Description of next undo operation */
  nextUndoDescription: string | null;
  /** Description of next redo operation */
  nextRedoDescription: string | null;
}

UndoState

Full undo/redo state from the compute engine.

type UndoState = {
  /** Whether undo is available. */
  canUndo: boolean;
  /** Whether redo is available. */
  canRedo: boolean;
  /** Number of operations that can be undone. */
  undoDepth: number;
  /** Number of operations that can be redone. */
  redoDepth: number;
  /** Description of the next undo operation, if set. */
  nextUndoDescription: string | null;
  /** Description of the next redo operation, if set. */
  nextRedoDescription: string | null;
}

UndoStateChangeEvent

Undo state change event

type UndoStateChangeEvent = {
  /** Current state */
  state: UndoServiceState;
  /** What triggered this change */
  trigger: 'undo' | 'redo' | 'push' | 'clear' | 'external';
}

UnmergeReceipt

Receipt for an unmerge mutation.

type UnmergeReceipt = {
  kind: 'unmerge';
  range: string;
}

UpdateWorkbookLinkInput

type UpdateWorkbookLinkInput = {
  expectedWorkbookId?: WorkbookId | null;
  target?: PersistedLinkTarget;
  displayName?: string;
  sourceKind?: WorkbookLinkSourceKind;
  importedExcelIdentity?: ImportedExternalLinkIdentity;
  materializedCacheMetadata?: AuthorizedMaterializedCacheMetadata;
}

ValidationCheckResult

Result of validating a single cell value against the rules covering it. Uses the public `errorStyle` vocabulary ("stop" | "warning" | "information") rather than the internal `enforcement` vocabulary. "none" indicates that no validation rule covers the cell (the value is trivially valid).

type ValidationCheckResult = {
  /** Whether the value satisfies the covering rule. */
  valid: boolean;
  /** Error message (only meaningful when `valid` is false). */
  errorMessage?: string;
  /** Error title for dialog display (only meaningful when `valid` is false). */
  errorTitle?: string;
  /** Error style from the covering rule. "none" means no rule covers the cell,
in which case the result is trivially valid. */
  errorStyle: 'stop' | 'warning' | 'information' | 'none';
}

ValidationRule

A data validation rule for cells.

type ValidationRule = {
  /** Schema ID — populated when reading, optional when creating (auto-generated if omitted) */
  id?: string;
  /** The cell range this rule applies to in A1 notation (e.g., "A1:B5") — populated when reading */
  range?: string;
  /** The validation type. 'none' indicates no validation rule is set. */
  type: 'none' | 'list' | 'wholeNumber' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
  /** Comparison operator */
  operator?: | 'equal'
    | 'notEqual'
    | 'greaterThan'
    | 'lessThan'
    | 'greaterThanOrEqual'
    | 'lessThanOrEqual'
    | 'between'
    | 'notBetween';
  /** Primary constraint value or formula */
  formula1?: string | number;
  /** Secondary constraint value or formula (for 'between' / 'notBetween') */
  formula2?: string | number;
  /** Explicit list of allowed values (for 'list' type) */
  values?: string[];
  /** Source reference for list validation: A1 range (e.g., "=Sheet1!A1:A10") or formula (e.g., "=INDIRECT(A1)"). Prefixed with "=" for formulas. */
  listSource?: string;
  /** Whether blank cells pass validation (default: true) */
  allowBlank?: boolean;
  /** Whether to show a dropdown arrow for list validations */
  showDropdown?: boolean;
  /** Whether to show an input message when the cell is selected */
  showInputMessage?: boolean;
  /** Title for the input message */
  inputTitle?: string;
  /** Body text for the input message */
  inputMessage?: string;
  /** Whether to show an error alert on invalid input */
  showErrorAlert?: boolean;
  /** Error alert style */
  errorStyle?: 'stop' | 'warning' | 'information';
  /** Title for the error alert */
  errorTitle?: string;
  /** Body text for the error alert */
  errorMessage?: string;
}

ValidationSetReceipt

Receipt for setting a validation rule.

type ValidationSetReceipt = {
  kind: 'validationSet';
  address: string;
}

ViewOptions

Sheet view options (gridlines, headings).

type ViewOptions = {
  /** Whether gridlines are shown */
  showGridlines: boolean;
  /** Whether row headers are shown */
  showRowHeaders: boolean;
  /** Whether column headers are shown */
  showColumnHeaders: boolean;
}

ViewportBounds

type ViewportBounds = {
  startRow: number;
  startCol: number;
  endRow: number;
  endCol: number;
}

ViewportChangeEvent

Events emitted by the viewport coordinator when viewport state changes. Consumers subscribe to these events to react to data changes without polling.

type ViewportChangeEvent = | { type: 'fetch-committed' }
  | { type: 'cells-patched'; cells: { row: number; col: number }[] }
  | { type: 'dimensions-patched'; axis: 'row' | 'col' }

ViewportRegion

Handle for a registered viewport region. Created by `wb.viewport.createRegion()`. The kernel tracks cell data for this region and delivers incremental updates. Dispose when the region is no longer needed (e.g., component unmount, sheet switch). Supports TC39 Explicit Resource Management: using region = wb.viewport.createRegion(sheetId, bounds);

type ViewportRegion = {
  /** Unique ID for this region (auto-generated). */
  id: string;
  /** Sheet this region is tracking. */
  sheetId: string;
  /** Update the locally-tracked visible bounds (e.g., on scroll or resize).

**Important:** This updates local state only. It does NOT push bounds to
the Rust compute engine. Rust-side viewport bounds (the prefetch range)
are exclusively managed by the fetch manager via {@link refresh}. Pushing
visible bounds here would overwrite the wider prefetch range on every
scroll, causing off-screen mutations to be silently dropped.

@see plans/completed/plans/fix-offscreen-mutation-display.md — Phase 5 */
  updateBounds(bounds: ViewportBounds): void;;
  /** Request a data refresh for this region. */
  refresh(scrollBehavior?: unknown): Promise<void>;;
}

ViolinConfig

Violin plot configuration

type ViolinConfig = {
  showBox?: boolean;
  bandwidth?: number;
  side?: 'both' | 'left' | 'right';
}

VisibleRangeView

The result of `getVisibleView()` — only visible (non-hidden) rows from a range. Matches the visible range-view concept: a filtered view of a range that excludes hidden rows (e.g., rows hidden by AutoFilter).

type VisibleRangeView = {
  /** Cell values for visible rows only (2D array, same column count as input range). */
  values: CellValue[][];
  /** The 0-based row indices (absolute, within the sheet) of the visible rows. */
  visibleRowIndices: number[];
}

WaterfallConfig

Waterfall chart configuration for special bars

type WaterfallConfig = {
  /** Indices that are "total" bars (drawn from zero) */
  totalIndices?: number[];
  /** Color for positive values */
  increaseColor?: string;
  /** Color for negative values */
  decreaseColor?: string;
  /** Color for total bars */
  totalColor?: string;
}

WordArtConfig

text-effect configuration for a TextBoxObject. When applied to a TextBoxObject, this config transforms regular text into stylized text effects with warping, fills, and effects. This is the main configuration type for text effects - it contains all the settings needed to render text with decorative styling. @see ECMA-376 Part 1, Section 21.1.2.2.33 (txBody - Text Body) @example // Basic text effects with arch warp const config: WordArtConfig = { warpPreset: 'textArchUp', warpAdjustments: { adj1: 50 }, fill: { type: 'gradient', gradientType: 'linear', angle: 90, stops: [...] }, outline: { width: 1.5, color: '#000000' } }; @example // text effects with effects const config: WordArtConfig = { warpPreset: 'textWave1', fill: { type: 'solid', color: '#FF6600' }, effects: { outerShadow: { blurRadius: 40000, distance: 25000, direction: 45, color: '#000000', opacity: 0.35 } } };

type WordArtConfig = {
  /** Text warp preset type.
Determines the geometric transformation applied to the text. */
  warpPreset: TextWarpPreset;
  /** Fine-tune warp parameters.
Values depend on the preset type. */
  warpAdjustments?: AdjustmentValues;
  /** Text fill (solid, gradient, pattern, or none).
Defines how the interior of text characters is colored. */
  fill: WordArtFill;
  /** Text outline/stroke.
Defines the border around text characters. */
  outline?: WordArtOutline;
  /** Text effects (shadow, glow, reflection, bevel, 3D).
Adds visual effects to the text. */
  effects?: TextEffects;
  /** Whether text follows the warp path exactly (true) or flows naturally (false).

- `true` (default): Each glyph is positioned and rotated to follow the warp path
  tangent. Used for arc, circle, and path-following effects where text should
  curve with the path. The rotation of each character matches the path direction.

- `false`: Text maintains its baseline orientation while the overall shape is
  warped. Used for inflate/deflate effects where text distorts but doesn't rotate.
  Characters remain upright even as they are scaled/positioned along the path. */
  followPath?: boolean;
  /** Text anchoring within the warp bounds.
Controls where text is positioned within the warped area. */
  anchor?: 'top' | 'middle' | 'bottom';
  /** Text direction.
Affects how text flows within the warp. */
  textDirection?: 'ltr' | 'rtl';
  /** Normalize letter heights across different characters.
When true, all characters are scaled to have the same height. */
  normalizeHeights?: boolean;
}

WordArtConfigUpdate

Typed patch for updating an existing text-effect configuration.

type WordArtConfigUpdate = Partial<
  Omit<WordArtConfig, 'warpAdjustments' | 'outline' | 'effects'>
> & {
  /** Warp adjustment values. Explicit undefined removes stored adjustments. */
  warpAdjustments?: AdjustmentValues | undefined;
  /** Text outline configuration. Explicit undefined removes the outline. */
  outline?: WordArtOutline | undefined;
  /** Text effects. Explicit undefined removes stored effects. */
  effects?: TextEffects | undefined;
}

WordArtDefaults

Fully normalized text effects defaults used by Worksheet text effects creation.

type WordArtDefaults = {
  /** Fully populated default visual text-effect configuration. */
  config: WordArtObjectConfig;
  /** Default text-effect object width in pixels. */
  width: number;
  /** Default text-effect object height in pixels. */
  height: number;
}

WordArtFill

Union type for all fill types. Used for text-effect text fill configuration.

type WordArtFill = SolidFill | GradientFill | PatternFill | NoFill

WordArtHandle

Decorative text-effect objects are text boxes with text-effect configuration.

type WordArtHandle = {
  update(props: WordArtUpdates): Promise<void>;;
  duplicate(offsetX?: number, offsetY?: number): Promise<WordArtHandle>;;
  getData(): Promise<TextBoxObject>;;
}

WordArtObjectConfig

Persisted visual text-effect configuration stored on a TextBoxObject.

type WordArtObjectConfig = DomainWordArtConfig

WordArtOutline

text-effect text outline configuration. Defines the stroke/border around text characters. @see ECMA-376 Part 1, Section 20.1.8.38 (CT_LineProperties)

type WordArtOutline = {
  /** Outline width in points (1pt = 1/72 inch).
Typical values range from 0.5 to 6 points. */
  width: number;
  /** Outline color (CSS color string: hex, rgb, rgba, hsl, named) */
  color: string;
  /** Opacity (0-1, where 0 is fully transparent, 1 is fully opaque) */
  opacity?: number;
  /** Dash style (default: 'solid') */
  dash?: LineDash;
  /** Line cap style (default: 'flat') */
  cap?: LineCap;
  /** Line join style (default: 'round') */
  join?: LineJoin;
  /** Miter limit for miter joins.
When the miter length exceeds this ratio of the line width,
the join is rendered as a bevel instead. */
  miterLimit?: number;
  /** Compound line type for multi-stroke outlines */
  compound?: CompoundLine;
}

WordArtTextFormatUpdate

Text-format fields accepted by text-effect text formatting updates.

type WordArtTextFormatUpdate = Partial<NonNullable<ShapeText['format']>>

WordArtUpdates

Updates for existing text effects.

type WordArtUpdates = {
  /** Updated text content. */
  text?: string;
  /** Warp preset name (text geometric transformation). */
  warp?: TextWarpPreset;
  /** Warp adjustment values. */
  warpAdjustments?: AdjustmentValues;
  /** Fill configuration. */
  fill?: WordArtFill;
  /** Outline configuration. Explicit undefined removes the outline. */
  outline?: WordArtOutline | undefined;
  /** Text effects (shadow, glow, reflection, etc.). */
  effects?: TextEffects;
  /** Full text-effect configuration batch update. */
  config?: WordArtConfigUpdate;
  /** Text formatting update. */
  textFormat?: WordArtTextFormatUpdate;
}

WorkbookChangeRecord

A single cell-level change observed by a workbook tracker. Includes sheet name.

type WorkbookChangeRecord = {
  /** Sheet name where the change occurred. */
  sheet: string;
  /** Cell address in A1 notation (e.g., "B1"). */
  address: string;
  /** 0-based row index. */
  row: number;
  /** 0-based column index. */
  col: number;
  /** What caused this change. */
  origin: ChangeOrigin;
  /** Type of change. */
  type: 'modified';
  /** Value before the change (undefined if cell was previously empty). */
  oldValue?: unknown;
  /** Value after the change (undefined if cell was cleared). */
  newValue?: unknown;
}

WorkbookChangeTracker

A handle that accumulates change records across all sheets.

type WorkbookChangeTracker = {
  /** Drain accumulated changes since creation or last collect() call. */
  collect(): WorkbookCollectResult;;
  /** Async version of collect() that resolves sheet names across the Rust bridge.
Preferred over collect() when called from async context.
Falls back to raw sheet IDs if name resolution fails. */
  collectAsync(): Promise<WorkbookCollectResult>;;
  /** Stop tracking and release internal resources. */
  close(): void;;
  /** Whether this tracker is still active (not closed). */
  active: boolean;
}

WorkbookCollectResult

Result from collecting workbook-level changes.

type WorkbookCollectResult = {
  /** Accumulated change records. */
  records: WorkbookChangeRecord[];
  /** True if the tracker hit its limit and stopped accumulating. */
  truncated: boolean;
  /** Total changes observed (may exceed records.length when truncated). */
  totalObserved: number;
}

WorkbookCustomListInput

type WorkbookCustomListInput = {
  /** Display name for the user-defined list. */
  name: string;
  /** Ordered values used by fill and custom sort operations. */
  values: readonly string[];
}

WorkbookCustomListUpdate

type WorkbookCustomListUpdate = {
  /** Updated display name. Omit to keep the current name. */
  name?: string;
  /** Updated ordered values. Omit to keep the current values. */
  values?: readonly string[];
}

WorkbookId

type WorkbookId = string

WorkbookLinkSourceKind

type WorkbookLinkSourceKind = 'mog-workbook' | 'excel-workbook' | 'dde-link' | 'ole-link'

WorkbookProtectionOptions

Workbook protection options - matches Excel behavior. Workbook protection prevents structural changes to sheets. When a workbook is protected: - Users cannot add, delete, rename, hide, unhide, or move sheets - Sheet content can still be edited (unless sheet is also protected) Plan 08: Dialogs - Task 4 (Protect Workbook Dialog)

type WorkbookProtectionOptions = {
  /** Protect workbook structure (prevents sheet add/delete/move/rename/hide/unhide).
Default: true when protection is enabled. */
  structure: boolean;
}

WorkbookSessionId

type WorkbookSessionId = string

WorkbookSettings

Workbook-level settings (persisted in Yjs workbook metadata). These apply globally to the entire workbook, not per-sheet. Stream L: Settings & Toggles

type WorkbookSettings = {
  /** Whether horizontal scrollbar is visible (default: true) */
  showHorizontalScrollbar: boolean;
  /** Whether vertical scrollbar is visible (default: true) */
  showVerticalScrollbar: boolean;
  /** Whether scrollbars auto-hide when not scrolling (default: false).
When true, scrollbars fade out after scroll ends and reappear on hover or scroll.
Plan 09 Group 7.2: Auto-Hide Scroll Bars */
  autoHideScrollBars: boolean;
  /** Whether the tab strip is visible (default: true) */
  showTabStrip: boolean;
  /** Whether sheets can be reordered by dragging (default: true) */
  allowSheetReorder: boolean;
  /** Whether the formula bar is visible (default: true) */
  showFormulaBar: boolean;
  /** Whether to auto-fit column width on header double-click (default: true) */
  autoFitOnDoubleClick: boolean;
  /** ID of active theme.
Built-in theme IDs: 'office', 'slice', 'vapor-trail', etc.
Use 'custom' to indicate a custom theme is stored in customTheme.
Issue 4: Page Layout - Themes */
  themeId: string;
  /** Override for theme fonts. When set, uses this font theme instead
of the fonts from the selected theme.
Built-in font theme IDs: 'office', 'arial', 'times', 'calibri', etc.
undefined means use fonts from themeId.

Plan 12: Fonts/Typography - Theme Font UI */
  themeFontsId?: string;
  /** Locale/culture for number, date, and currency formatting.
Uses IETF language tags: 'en-US', 'de-DE', 'ja-JP', etc.
Default: 'en-US'

This affects:
- Decimal and thousands separators (1,234.56 vs 1.234,56)
- Currency symbol position ($100 vs 100 €)
- Date format patterns (MM/DD/YYYY vs DD.MM.YYYY)
- Month and day name translations
- AM/PM designators

Stream G: Culture & Localization */
  culture: string;
  /** Whether to show cut/copy indicator (marching ants). Default: true */
  showCutCopyIndicator: boolean;
  /** Whether fill handle dragging is enabled. Default: true */
  allowDragFill: boolean;
  /** Direction to move after pressing Enter. Default: 'down' */
  enterKeyDirection: EnterKeyDirection;
  /** Whether cell drag-and-drop to move cells is enabled. Default: false (not yet implemented) */
  allowCellDragDrop: boolean;
  /** Currently selected sheet IDs for multi-sheet operations.
Default: undefined (falls back to [activeSheetId])

This is collaborative state - other users can see which sheets you have selected.
Used for operations that broadcast to multiple sheets (formatting, structure changes).

When multiple sheets are selected:
- Formatting operations apply to all selected sheets
- Structure operations (insert/delete rows/cols) apply to all selected sheets
- The active sheet is always included in the selection */
  selectedSheetIds?: SheetId[];
  /** Whether the workbook structure is protected.
When true, prevents adding, deleting, renaming, hiding, unhiding, or moving sheets.
Default: false

Plan 08: Dialogs - Task 4 (Protect Workbook Dialog) */
  isWorkbookProtected?: boolean;
  /** Hashed protection password for workbook (optional).
Uses XLSX-compatible XOR hash algorithm for round-trip compatibility.
Empty string or undefined means no password protection. */
  workbookProtectionPasswordHash?: string;
  /** Workbook protection options (what operations are prevented).
Only relevant when isWorkbookProtected is true.
If not set, defaults to DEFAULT_WORKBOOK_PROTECTION_OPTIONS.
@see WorkbookProtectionOptions in protection.ts */
  workbookProtectionOptions?: import('./document/protection').WorkbookProtectionOptions;
  /** Calculation settings including iterative calculation for circular references.
If not set, defaults to DEFAULT_CALCULATION_SETTINGS.

@see plans/active/spreadsheet-compatibility/04-EDITING-BEHAVIORS-PLAN.md - G.3 */
  calculationSettings?: CalculationSettings;
  /** Whether the workbook uses the 1904 date system (affects all date calculations).
Default: false (1900 date system). */
  date1904?: boolean;
  /** Default table style ID for new tables created in this workbook.
Can be a built-in style preset name (e.g., 'medium2', 'dark1')
or a custom style ID (e.g., 'custom-abc123').

When undefined, new tables use the 'medium2' preset by default.

Plan 15: Tables spreadsheet compatibility - P1-8 (Set as default style) */
  defaultTableStyleId?: string;
  /** Whether chart data points track cell movement when cells are inserted/deleted.
When true, chart data series follow their original data points even if
the underlying cells shift due to row/column insertion or deletion.
Default: true (matches the spreadsheet default).

Mirrors the workbook chart data point tracking behavior. */
  chartDataPointTrack?: boolean;
}

WorkbookSnapshot

A summary snapshot of the entire workbook state.

type WorkbookSnapshot = {
  /** All sheets in the workbook */
  sheets: SheetSnapshot[];
  /** ID of the currently active sheet */
  activeSheetId: string;
  /** Total number of sheets */
  sheetCount: number;
}

WorkbookTrackOptions

Options for creating a workbook-level change tracker.

type WorkbookTrackOptions = {
  /** Filter by origin type. Omit to track all origins. */
  origins?: ChangeOrigin[];
  /** Max records before auto-truncation (default: 10000). */
  limit?: number;
}

WorksheetCreateCheckboxOptions

type WorksheetCreateCheckboxOptions = Omit<CreateCheckboxOptions, 'sheetId'>

WorksheetCreateComboBoxOptions

type WorksheetCreateComboBoxOptions = Omit<CreateComboBoxOptions, 'sheetId'>