@mog-sdk/node 0.1.10 → 0.1.12

package/dist/index.d.cts

@@ -16,11 +16,13 @@ export type IKernelContext = any;
 export type IEventBus = any;
 
 
-
+import { Workbook, WorkbookInternal, Worksheet } from '@mog-sdk/spreadsheet-contracts/api';
+export { Workbook, Worksheet } from '@mog-sdk/spreadsheet-contracts/api';
 import * as _mog_kernel_bridges from '@mog/kernel/bridges';
 
 
 
+import { CodeExecutionOptions, CodeExecutionResult } from '@mog-sdk/spreadsheet-contracts/core';
 
 /**
  * Save a workbook to a file path. Node.js only.
@@ -112,6 +114,7 @@ var subApis = {
 	},
 	ws: {
 		smartArt: "WorksheetSmartArt",
+		changes: "WorksheetChanges",
 		formats: "WorksheetFormats",
 		layout: "WorksheetLayout",
 		view: "WorksheetView",
@@ -234,6 +237,30 @@ var interfaces = {
 				usedTypes: [
 				]
 			},
+			getIterativeCalculation: {
+				signature: "getIterativeCalculation(): Promise<boolean>;",
+				docstring: "Get whether iterative calculation is enabled for circular references.\nConvenience accessor — equivalent to `(await getSettings()).calculationSettings.enableIterativeCalculation`.",
+				usedTypes: [
+				]
+			},
+			setIterativeCalculation: {
+				signature: "setIterativeCalculation(enabled: boolean): Promise<void>;",
+				docstring: "Set whether iterative calculation is enabled for circular references.\nConvenience mutator — patches `calculationSettings.enableIterativeCalculation`.",
+				usedTypes: [
+				]
+			},
+			setMaxIterations: {
+				signature: "setMaxIterations(n: number): Promise<void>;",
+				docstring: "Set the maximum number of iterations for iterative calculation.\nConvenience mutator — patches `calculationSettings.maxIterations`.",
+				usedTypes: [
+				]
+			},
+			setConvergenceThreshold: {
+				signature: "setConvergenceThreshold(threshold: number): Promise<void>;",
+				docstring: "Set the convergence threshold (maximum change) for iterative calculation.\nConvenience mutator — patches `calculationSettings.maxChange`.",
+				usedTypes: [
+				]
+			},
 			getUsePrecisionAsDisplayed: {
 				signature: "getUsePrecisionAsDisplayed(): Promise<boolean>;",
 				docstring: "Whether to use displayed precision instead of full (15-digit) precision.\nConvenience accessor — inverted from `calculationSettings.fullPrecision`.",
@@ -462,16 +489,18 @@ var interfaces = {
 				]
 			},
 			clearData: {
-				signature: "clearData(range: string): Promise<void>;",
+				signature: "clearData(range: string): Promise<ClearResult>;",
 				docstring: "Clear all cell data (values and formulas) in a range (A1 notation, e.g. \"A1:C3\").",
 				usedTypes: [
+					"ClearResult"
 				]
 			},
 			clear: {
-				signature: "clear(range: string, applyTo?: ClearApplyTo): Promise<void>;",
+				signature: "clear(range: string, applyTo?: ClearApplyTo): Promise<ClearResult>;",
 				docstring: "Unified clear with mode selection (OfficeJS Range.clear equivalent).\n\n@param range - A1 range string (e.g. \"A1:C3\")\n@param applyTo - What to clear: 'all' (default), 'contents', 'formats', 'hyperlinks'",
 				usedTypes: [
-					"ClearApplyTo"
+					"ClearApplyTo",
+					"ClearResult"
 				]
 			},
 			getValue: {
@@ -1398,21 +1427,36 @@ var interfaces = {
 			}
 		}
 	},
+	WorksheetChanges: {
+		docstring: "Sub-API for opt-in change tracking on a worksheet.",
+		functions: {
+			track: {
+				signature: "track(options?: ChangeTrackOptions): ChangeTracker;",
+				docstring: "Create a change tracker that accumulates cell-level change records\nfrom this point forward.\n\n@param options - Optional scope and origin filters\n@returns A ChangeTracker handle — call collect() to drain, close() when done",
+				usedTypes: [
+					"ChangeTrackOptions",
+					"ChangeTracker"
+				]
+			}
+		}
+	},
 	WorksheetFormats: {
 		docstring: "Sub-API for cell formatting operations on a worksheet.",
 		functions: {
 			set: {
-				signature: "set(address: string, format: CellFormat): Promise<void>;",
+				signature: "set(address: string, format: CellFormat): Promise<FormatChangeResult>;",
 				docstring: "Set format for a single cell.\n\n@param address - A1-style cell address (e.g. \"A1\", \"B3\")\n@param format - Format properties to apply",
 				usedTypes: [
-					"CellFormat"
+					"CellFormat",
+					"FormatChangeResult"
 				]
 			},
 			setRange: {
-				signature: "setRange(range: string, format: CellFormat): Promise<void>;",
+				signature: "setRange(range: string, format: CellFormat): Promise<FormatChangeResult>;",
 				docstring: "Set format for a contiguous range.\n\n@param range - A1-style range string (e.g. \"A1:B2\")\n@param format - Format properties to apply",
 				usedTypes: [
-					"CellFormat"
+					"CellFormat",
+					"FormatChangeResult"
 				]
 			},
 			setRanges: {
@@ -1430,10 +1474,10 @@ var interfaces = {
 				]
 			},
 			get: {
-				signature: "get(address: string): Promise<CellFormat | null>;",
-				docstring: "Get the format of a single cell.\n\n@param address - A1-style cell address\n@returns The cell format, or null if no format is set",
+				signature: "get(address: string): Promise<ResolvedCellFormat>;",
+				docstring: "Get the fully-resolved format of a single cell.\n\nReturns a dense CellFormat with all fields present (null for unset properties,\nnever undefined). Includes the full cascade (default → col → row → table → cell → CF)\nwith theme colors resolved to hex.\n\n@param address - A1-style cell address\n@returns The resolved cell format (always an object, never null)",
 				usedTypes: [
-					"CellFormat"
+					"ResolvedCellFormat"
 				]
 			},
 			adjustIndent: {
@@ -2317,7 +2361,7 @@ var interfaces = {
 				]
 			},
 			setCriteria: {
-				signature: "setCriteria(\n    filterId: string,\n    col: number,\n    criteria: ColumnFilterCriteria,\n  ): Promise<void>;",
+				signature: "setCriteria(filterId: string, col: number, criteria: ColumnFilterCriteria): Promise<void>;",
 				docstring: "Set filter criteria for a column using filter ID.\n\n@param filterId - Filter ID\n@param col - Column index (0-based)\n@param criteria - Filter criteria to apply",
 				usedTypes: [
 					"ColumnFilterCriteria"
@@ -3745,6 +3789,11 @@ var types = {
 		definition: "'standard' | 'stacked' | 'percentStacked'",
 		docstring: ""
 	},
+	AutoFillChange: {
+		name: "AutoFillChange",
+		definition: "{\n  row: number;\n  col: number;\n  type: 'value' | 'formula' | 'format' | 'clear';\n}",
+		docstring: "A single cell change produced by the fill engine."
+	},
 	AutoFillMode: {
 		name: "AutoFillMode",
 		definition: "| 'auto' // Detect pattern automatically (default)\n  | 'copy' // Always copy (no series)\n  | 'series' // Force series interpretation\n  | 'days' // Force date unit: days\n  | 'weekdays' // Force date unit: weekdays\n  | 'months' // Force date unit: months\n  | 'years' // Force date unit: years\n  | 'formats' // Copy formats only\n  | 'values' // Copy values only (no formats)\n  | 'withoutFormats' // Copy values + formulas, skip formats\n  | 'linearTrend' // Force linear regression trend\n  | 'growthTrend'",
@@ -3752,7 +3801,7 @@ var types = {
 	},
 	AutoFillResult: {
 		name: "AutoFillResult",
-		definition: "{\n  /** The pattern that was detected (or forced by mode) */\n  patternType: FillPatternType;\n  /** Number of cells that were filled */\n  filledCellCount: number;\n  /** Any warnings generated during fill */\n  warnings: AutoFillWarning[];\n}",
+		definition: "{\n  /** The pattern that was detected (or forced by mode) */\n  patternType: FillPatternType;\n  /** Number of cells that were filled */\n  filledCellCount: number;\n  /** Any warnings generated during fill */\n  warnings: AutoFillWarning[];\n  /** Per-cell changes listing each cell written */\n  changes: AutoFillChange[];\n}",
 		docstring: "Result from autoFill() — summary of what the fill engine did."
 	},
 	AutoFillWarning: {
@@ -3945,6 +3994,26 @@ var types = {
 		definition: "{\n  /** If true, value is treated as a formula (prefixed with =) */\n  asFormula?: boolean;\n}",
 		docstring: "Options controlling how a cell value is interpreted when written."
 	},
+	ChangeOrigin: {
+		name: "ChangeOrigin",
+		definition: "'direct' | 'cascade' | 'remote'",
+		docstring: "Origin of a change: direct write, formula recalculation, or remote collaborator."
+	},
+	ChangeRecord: {
+		name: "ChangeRecord",
+		definition: "{\n  /** Cell address in A1 notation (e.g. \"B1\"). */\n  address: string;\n  /** 0-based row index. */\n  row: number;\n  /** 0-based column index. */\n  col: number;\n  /** What caused this change. */\n  origin: ChangeOrigin;\n  /** Type of change. */\n  type: 'modified';\n}",
+		docstring: "WorksheetChanges — Sub-API for opt-in change tracking.\n\nCreates lightweight trackers that accumulate cell-level change records\nacross mutations. Trackers are opt-in to avoid bloating return values;\nthey return addresses + metadata only (no cell values) so callers can\nhydrate via getRange() when needed.\n\nInspired by:\n- Excel OfficeJS onChanged (lightweight payload + lazy hydration)\n- Firestore onSnapshot (query-scoped subscriptions)\n- Yjs transaction.origin (source/origin tagging for collab)"
+	},
+	ChangeTrackOptions: {
+		name: "ChangeTrackOptions",
+		definition: "{\n  /** Only track changes within this range (A1 notation, e.g. \"A1:Z100\"). Omit for whole-sheet. */\n  scope?: string;\n  /** Exclude changes from these origin types. */\n  excludeOrigins?: ChangeOrigin[];\n}",
+		docstring: "Options for creating a change tracker."
+	},
+	ChangeTracker: {
+		name: "ChangeTracker",
+		definition: "{\n  /** Drain all accumulated changes since creation or last collect() call.\nReturns addresses + metadata only (no cell values) — call ws.getRange()\nto hydrate if needed. */\n  collect(): ChangeRecord[];;\n  /** Stop tracking and release internal resources. */\n  close(): void;;\n  /** Whether this tracker is still active (not closed). */\n  active: boolean;\n}",
+		docstring: "A handle that accumulates change records across mutations."
+	},
 	Chart: {
 		name: "Chart",
 		definition: "{\n  id: string;\n  sheetId?: string;\n  createdAt?: number;\n  updatedAt?: number;\n}",
@@ -4005,6 +4074,11 @@ var types = {
 		definition: "'all' | 'contents' | 'formats' | 'hyperlinks'",
 		docstring: "Determines which aspects of a range to clear.\nMatches OfficeJS Excel.ClearApplyTo enum."
 	},
+	ClearResult: {
+		name: "ClearResult",
+		definition: "{\n  /** Number of cells in the cleared range. */\n  cellCount: number;\n}",
+		docstring: "Confirmation returned by clearData() and clear()."
+	},
 	CodeResult: {
 		name: "CodeResult",
 		definition: "{\n  /** Whether execution completed successfully */\n  success: boolean;\n  /** Captured console output */\n  output?: string;\n  /** Error message (if success is false) */\n  error?: string;\n  /** Execution duration in milliseconds */\n  duration?: number;\n}",
@@ -4215,6 +4289,11 @@ var types = {
 		definition: "| 'shape'\n  | 'connector'\n  | 'picture'\n  | 'textbox'\n  | 'chart'\n  | 'camera'\n  | 'equation'\n  | 'smartart'\n  | 'drawing'\n  | 'oleObject'\n  | 'formControl'\n  | 'slicer'\n  | 'wordart'",
 		docstring: "Type discriminator for floating objects. Superset of Rust FloatingObjectKind (12 variants) + legacy TS-only 'wordart'."
 	},
+	FormatChangeResult: {
+		name: "FormatChangeResult",
+		definition: "{\n  /** Number of cells whose formatting was changed */\n  cellCount: number;\n}",
+		docstring: "Result of a format set/setRange operation."
+	},
 	FormatEntry: {
 		name: "FormatEntry",
 		definition: "{\n  /** Cell value descriptor */\n  value: { type: string; value?: unknown };\n  /** Number format code (e.g., \"#,##0.00\") */\n  formatCode: string;\n}",
@@ -4556,6 +4635,11 @@ var types = {
 		definition: "{\n  /** Number of duplicate rows removed */\n  removedCount: number;\n  /** Number of unique rows remaining */\n  remainingCount: number;\n}",
 		docstring: "Result of a remove-duplicates operation."
 	},
+	ResolvedCellFormat: {
+		name: "ResolvedCellFormat",
+		definition: "{\n  [K in keyof CellFormat]-?: CellFormat[K] | null;\n}",
+		docstring: "Dense cell format where every property is explicitly present (null when unset). Returned by formats.get()."
+	},
 	RichTextSegment: {
 		name: "RichTextSegment",
 		definition: "{\n  text: string;\n  bold?: boolean;\n  italic?: boolean;\n  underline?: boolean;\n  strikethrough?: boolean;\n  color?: string;\n  fontName?: string;\n  fontSize?: number;\n}",
@@ -4598,7 +4682,7 @@ var types = {
 	},
 	SetCellsResult: {
 		name: "SetCellsResult",
-		definition: "{\n  /** Number of cells successfully written */\n  cellsWritten: number;\n  /** Per-cell errors, if any (omitted when all succeed) */\n  errors?: Array<{ addr: string; error: string }>;\n  /** Non-fatal warnings (e.g., deduplication, coercion) */\n  warnings?: OperationWarning[];\n}",
+		definition: "{\n  /** Number of cells successfully written */\n  cellsWritten: number;\n  /** Per-cell errors, if any (omitted when all succeed) */\n  errors?: Array<{ addr: string; error: string }> | null;\n  /** Non-fatal warnings (e.g., deduplication, coercion) */\n  warnings?: OperationWarning[];\n}",
 		docstring: "Result of a bulk setCells() operation."
 	},
 	ShadowAlignment: {
@@ -4952,180 +5036,12 @@ var types = {
 		docstring: "A summary snapshot of the entire workbook state."
 	}
 };
-var generated = "2026-04-02T22:03:24.772Z";
 var apiSpec = {
 	subApis: subApis,
 	interfaces: interfaces,
-	types: types,
-	generated: generated
+	types: types
 };
 
-
-/**
- * A spreadsheet workbook — the primary API for all spreadsheet operations.
- *
- * Create with `createWorkbook()`. Access sheets via `getActiveSheet()`,
- * `getSheet(index)`, or `getSheetByName(name)`.
- *
- * Sub-APIs: history, sheets, names, scenarios, styles, notifications,
- * theme, viewport, protection, floatingObjects.
- */
-export interface Workbook {
-  /** Get the currently active worksheet */
-  getActiveSheet(): Worksheet;
-  /** Get the active sheet ID */
-  getActiveSheetId(): string;
-  /** Set the active sheet by ID */
-  setActiveSheetId(sheetId: string): void;
-  /** Get sheet by 0-based index */
-  getSheet(index: number): Worksheet;
-  /** Get sheet by name */
-  getSheetByName(name: string): Worksheet | undefined;
-
-  /** Undo/redo, batch operations, checkpoints */
-  readonly history: WorkbookHistory;
-  /** Sheet CRUD: add, remove, rename, move, duplicate */
-  readonly sheets: WorkbookSheets;
-
-  /** Execute code in a sandboxed VM */
-  executeCode(code: string, options?: { timeout?: number }): Promise<unknown>;
-  /** Export workbook to XLSX buffer */
-  toBuffer(): Promise<Uint8Array>;
-  /** Dispose all resources — MUST call when done */
-  dispose(): void;
-
-  [key: string]: any;
-}
-
-export interface WorkbookHistory {
-  undo(): Promise<void>;
-  redo(): Promise<void>;
-  batch(fn: () => Promise<void>): Promise<void>;
-  [key: string]: any;
-}
-
-export interface WorkbookSheets {
-  add(name?: string): Promise<string>;
-  remove(sheetId: string): Promise<void>;
-  rename(sheetId: string, name: string): Promise<void>;
-  getAll(): Array<{ id: string; name: string; index: number }>;
-  [key: string]: any;
-}
-
-/**
- * A single worksheet — read/write cells, formatting, charts, and more.
- *
- * Supports both A1 notation (`"A1"`) and numeric addressing (`(row, col)`).
- *
- * Sub-APIs: formats, layout, view, structure, charts, shapes, pictures,
- * filters, validation, tables, pivots, slicers, comments, hyperlinks,
- * outline, protection, print, settings, bindings.
- */
-export interface Worksheet {
-  /** Sheet name */
-  readonly name: string;
-  /** Sheet ID */
-  readonly id: string;
-  /** 0-based sheet index */
-  getIndex(): number;
-
-  /** Set a cell value (A1 notation) */
-  setCell(address: string, value: unknown): Promise<void>;
-  /** Set a cell value (numeric) */
-  setCell(row: number, col: number, value: unknown): Promise<void>;
-
-  /** Get a cell's computed value */
-  getValue(address: string): Promise<unknown>;
-  getValue(row: number, col: number): Promise<unknown>;
-
-  /** Get a cell's formula (or undefined if none) */
-  getFormula(address: string): Promise<string | undefined>;
-  getFormula(row: number, col: number): Promise<string | undefined>;
-
-  /** Get full cell data */
-  getCell(address: string): Promise<CellData | undefined>;
-  getCell(row: number, col: number): Promise<CellData | undefined>;
-
-  /** Formatting sub-API */
-  readonly formats: WorksheetFormats;
-  /** Layout sub-API (row heights, column widths, merges) */
-  readonly layout: WorksheetLayout;
-  /** Chart operations */
-  readonly charts: WorksheetCharts;
-  /** Table operations */
-  readonly tables: WorksheetTables;
-
-  /** Describe the sheet for LLM consumption */
-  describe(): Promise<string>;
-  /** Describe a range for LLM consumption */
-  describeRange(range: string): Promise<string>;
-
-  [key: string]: any;
-}
-
-export interface CellData {
-  value: unknown;
-  formula?: string;
-  formattedValue?: string;
-  [key: string]: any;
-}
-
-export interface WorksheetFormats {
-  set(address: string, format: Record<string, unknown>): Promise<void>;
-  get(address: string): Promise<Record<string, unknown>>;
-  [key: string]: any;
-}
-
-export interface WorksheetLayout {
-  setRowHeight(row: number, height: number): Promise<void>;
-  setColumnWidth(col: number, width: number): Promise<void>;
-  merge(range: string): Promise<void>;
-  unmerge(range: string): Promise<void>;
-  [key: string]: any;
-}
-
-export interface WorksheetCharts {
-  add(type: string, dataRange: string, options?: Record<string, unknown>): Promise<string>;
-  remove(chartId: string): Promise<void>;
-  [key: string]: any;
-}
-
-export interface WorksheetTables {
-  add(range: string, options?: Record<string, unknown>): Promise<string>;
-  remove(tableId: string): Promise<void>;
-  [key: string]: any;
-}
-
-export interface CreateWorkbookOptions {
-  /** Document ID (auto-generated if omitted) */
-  documentId?: string;
-  /** XLSX source to import */
-  source?: { type: 'bytes'; data: Uint8Array } | { type: 'path'; path: string };
-  /** Import options */
-  importOptions?: Record<string, unknown>;
-}
-
-export interface WorkbookConfig {
-  ctx: any;
-  getActiveSheetId?: () => string;
-  setActiveSheetId?: (sheetId: string) => void;
-  eventBus: any;
-  [key: string]: any;
-}
-
-/**
- * Create a new headless workbook.
- *
- * @example
- * ```typescript
- * import { createWorkbook } from '@mog/sdk';
- * const wb = await createWorkbook();
- * const ws = wb.getActiveSheet();
- * await ws.setCell('A1', 42);
- * ```
- */
-export declare function createWorkbook(options?: CreateWorkbookOptions): Promise<Workbook>;
-
 /**
  * HeadlessLifecycleSystem - Headless Boot Wrapper for the Spreadsheet Engine
  *