@libraz/formulon 0.9.6 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,3 @@
1
- // Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
2
1
  //
3
2
  // Hand-written TypeScript declarations for the Formulon WASM bindings.
4
3
  //
@@ -34,6 +33,29 @@ export interface Status {
34
33
  context: string;
35
34
  }
36
35
 
36
+ /** Per-call telemetry returned by `Workbook.recalcParallel`. The five
37
+ * scheduler counters are `uint64_t` in the C ABI but are exposed as
38
+ * JavaScript `number` values by the WASM binding. They are exact through
39
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1). */
40
+ export interface ParallelRecalcStats {
41
+ cellsEvaluated: number;
42
+ sccsProcessed: number;
43
+ parallelSteps: number;
44
+ serialFallbackSteps: number;
45
+ cycleRecoveries: number;
46
+ workerThreadsStarted: number;
47
+ workerThreadsUsed: number;
48
+ }
49
+
50
+ /** `{ status, stats }` returned by `Workbook.recalcParallel`. */
51
+ export interface ParallelRecalcResult {
52
+ status: Status;
53
+ stats: ParallelRecalcStats;
54
+ }
55
+
56
+ /** A JS array with the status of the list enumeration that produced it. */
57
+ export type ListResult<T> = ReadonlyArray<T> & { readonly status: Status };
58
+
37
59
  /** Flattened mirror of `fm_value_t`. Only the field selected by `kind`
38
60
  * is meaningful; the others carry default-zero values. */
39
61
  export interface Value {
@@ -73,14 +95,65 @@ export interface EvalArrayResult {
73
95
  cells: Value[][];
74
96
  }
75
97
 
76
- /** Return type of `Workbook.save()` / `Workbook.saveEx(format)`. */
98
+ /** Return type of `Workbook.save()` / `Workbook.saveAs(format)`. */
77
99
  export interface SaveResult {
78
100
  status: Status;
79
101
  /** Freshly-allocated `Uint8Array` on success; `null` on failure. */
80
102
  bytes: Uint8Array | null;
81
103
  }
82
104
 
83
- /** `fm_workbook_format_t` ordinals: container format for `saveEx`. */
105
+ /**
106
+ * Return type of `Workbook.saveWithDiagnostics(format)`.
107
+ *
108
+ * A field means the same thing whichever container was written; where the
109
+ * underlying event exists in only one container, the other simply never
110
+ * raises it. Coverage is partial by design — an all-zero result means
111
+ * none of the losses below occurred, not that nothing was logged.
112
+ *
113
+ * Summing these does NOT give "how many things did I lose":
114
+ * `droppedPartCount` and `droppedRelationshipCount` both rise for one
115
+ * dropped part.
116
+ */
117
+ export interface SaveDiagnosticsResult extends SaveResult {
118
+ /** Formula cells emitted as cached literals. Always zero for XLSX. */
119
+ downgradedFormulaCount: number;
120
+ /** Sheet features not lowered to records. Always zero for XLSX. */
121
+ deferredFeatureCount: number;
122
+ /** Passthrough parts dropped for colliding with a generated path, or
123
+ * for two entries claiming one path. Both containers. */
124
+ droppedPartCount: number;
125
+ /** Relationships dropped because their target part is gone. Both
126
+ * containers, at package / workbook / (XLSB) sheet scope. Rises with
127
+ * `droppedPartCount` for one dropped part — do not add them. */
128
+ droppedRelationshipCount: number;
129
+ /** Tables emitted under a writer-assigned id. Always zero for XLSB. */
130
+ renumberedPartCount: number;
131
+ }
132
+
133
+ /**
134
+ * Return type of `Workbook.readDiagnostics()`. Same contract as
135
+ * `SaveDiagnosticsResult`: one meaning per field across both containers,
136
+ * partial coverage by design.
137
+ */
138
+ export interface ReadDiagnosticsResult {
139
+ status: Status;
140
+ /** Formula cells whose stored formula could not be decoded. XLSB only. */
141
+ undecodedFormulaCount: number;
142
+ /** Defined names skipped for the same reason. XLSB only. */
143
+ undecodedDefinedNameCount: number;
144
+ /** Package parts whose content type could not be resolved, so they were
145
+ * not decoded. XLSB only — the XLSX reader keeps unmodelled parts as
146
+ * passthrough instead of dropping them. */
147
+ undecodedPartCount: number;
148
+ /** Presentation-overlay entries dropped for an unusable reference: one
149
+ * per merge / hyperlink / data validation, one per conditional-format
150
+ * block (a block can carry several rules). XLSX only. */
151
+ skippedFeatureCount: number;
152
+ /** Workbook parts whose content type was unrecognised. Max 1. XLSX only. */
153
+ unknownContentTypeCount: number;
154
+ }
155
+
156
+ /** `fm_workbook_format_t` ordinals: container format for `saveAs`. */
84
157
  export enum WorkbookFormat {
85
158
  Unknown = 0,
86
159
  Xlsx = 1,
@@ -96,35 +169,61 @@ export interface StringResult {
96
169
  /** Return type of `Workbook.cellAt(sheet, idx)`. */
97
170
  export interface CellEntry {
98
171
  status: Status;
99
- row: number;
100
- col: number;
172
+ row?: number;
173
+ col?: number;
101
174
  /** Raw formula text, or `null` for pure literals. */
102
- formula: string | null;
103
- value: Value;
175
+ formula?: string | null;
176
+ value?: Value;
104
177
  }
105
178
 
106
179
  /** Return type of `Workbook.definedNameAt(idx)`. */
107
180
  export interface DefinedNameEntry {
108
181
  status: Status;
109
- name: string;
110
- formula: string;
182
+ name?: string;
183
+ formula?: string;
111
184
  /** -1 for workbook scope; otherwise a 0-based sheet index. */
112
- localSheetId: number;
185
+ localSheetId?: number;
113
186
  }
114
187
 
115
188
  /** Return type of `Workbook.tableAt(idx)`. */
116
189
  export interface TableEntry {
117
190
  status: Status;
118
- name: string;
119
- displayName: string;
120
- ref: string;
191
+ name?: string;
192
+ displayName?: string;
193
+ ref?: string;
194
+ sheetIndex?: number;
195
+ }
196
+
197
+ /** Authoring input for a worksheet table. `columns` must have exactly one
198
+ * name per column in `ref`; `styleName` follows Excel's built-in TableStyle
199
+ * names. With `headerRow` (the default), the caller still writes the header
200
+ * cells: Excel expects the first row of `ref` to hold the column names. */
201
+ export interface TableInput {
121
202
  sheetIndex: number;
203
+ ref: string;
204
+ name: string;
205
+ displayName?: string;
206
+ columns: string[];
207
+ styleName?: string;
208
+ headerRow?: boolean;
209
+ totalsRow?: boolean;
210
+ }
211
+
212
+ /** Partial table metadata update. Omitted fields preserve their existing
213
+ * values; an empty `styleName` explicitly removes the table style. When
214
+ * omitted, `ref` also preserves the current range. `headerRow` and
215
+ * `totalsRow` update their flags only when supplied. */
216
+ export interface TableUpdateInput {
217
+ ref?: string;
218
+ styleName?: string;
219
+ headerRow?: boolean;
220
+ totalsRow?: boolean;
122
221
  }
123
222
 
124
223
  /** Return type of `Workbook.passthroughAt(idx)`. */
125
224
  export interface PassthroughEntry {
126
225
  status: Status;
127
- path: string;
226
+ path?: string;
128
227
  }
129
228
 
130
229
  /** PivotTable layout cell kind. Mirrors `fm_pivot_cell_kind_t`. */
@@ -318,6 +417,8 @@ export interface PivotFilterSpec {
318
417
  axis: PivotAxis;
319
418
  fieldName: string;
320
419
  type: PivotFilterType;
420
+ /** Data-field aggregate scored by value filters. Defaults to 0. */
421
+ dataFieldIndex?: number;
321
422
  valueKind?: PivotFilterValueKind;
322
423
  valueInt?: number;
323
424
  valueDouble?: number;
@@ -327,6 +428,30 @@ export interface PivotFilterSpec {
327
428
  valueHighDouble?: number;
328
429
  }
329
430
 
431
+ /** Return type of `Workbook.pivotFilterAt(...)`: the stored filter plus a
432
+ * status envelope. Field names and semantics match `PivotFilterSpec`.
433
+ *
434
+ * The active-filter list is **session state**. An entry added through
435
+ * `pivotFilterAdd` affects evaluation only while the workbook handle
436
+ * lives and is not written by `save`. Conversely a `<filters>` block
437
+ * Excel wrote is preserved verbatim on save but does not appear here, so
438
+ * `pivotFilterCount` reports only what this session added. The filter
439
+ * surface that does persist is pivot field item visibility. */
440
+ export interface PivotFilterResult {
441
+ status: Status;
442
+ axis: number;
443
+ fieldName: string;
444
+ type: number;
445
+ dataFieldIndex: number;
446
+ valueKind: number;
447
+ valueInt: number;
448
+ valueDouble: number;
449
+ valueText: string;
450
+ valueHighKind: number;
451
+ valueHighInt: number;
452
+ valueHighDouble: number;
453
+ }
454
+
330
455
  /** Conditional-format match kind. Mirrors `formulon::cf::CFMatchKind`. */
331
456
  export enum CfMatchKind {
332
457
  DifferentialFormat = 0,
@@ -335,6 +460,28 @@ export enum CfMatchKind {
335
460
  IconSet = 3,
336
461
  }
337
462
 
463
+ /** Excel cell-error ordinals. Mirrors `formulon::ErrorCode`; these are the
464
+ * values carried by `Value.errorCode` and accepted by `setError`. */
465
+ export enum ErrorCode {
466
+ Null = 0,
467
+ Div0 = 1,
468
+ Value = 2,
469
+ Ref = 3,
470
+ Name = 4,
471
+ Num = 5,
472
+ NA = 6,
473
+ GettingData = 7,
474
+ Spill = 8,
475
+ Calc = 9,
476
+ Field = 10,
477
+ Blocked = 11,
478
+ Connect = 12,
479
+ External = 13,
480
+ Busy = 14,
481
+ Python = 15,
482
+ Unknown = 16,
483
+ }
484
+
338
485
  /**
339
486
  * Workbook-level calc mode (`<calcPr calcMode>`).
340
487
  *
@@ -353,6 +500,20 @@ export enum CalcMode {
353
500
 
354
501
  export type ExcelProfileId = 'mac-365-ja_JP' | 'win-365-ja_JP';
355
502
 
503
+ /**
504
+ * A wall-clock reading in local civil fields, as read back from
505
+ * {@link Workbook.pinnedNow}. `month` is 1-12 and `day` is 1-31; the other
506
+ * fields follow the usual 24-hour ranges.
507
+ */
508
+ export interface CivilTime {
509
+ year: number;
510
+ month: number;
511
+ day: number;
512
+ hour: number;
513
+ minute: number;
514
+ second: number;
515
+ }
516
+
356
517
  /** RGBA colour. Channels are 0-255 (sRGB). */
357
518
  export interface CfColor {
358
519
  r: number;
@@ -393,33 +554,31 @@ export interface CfMatch {
393
554
  iconIndex: number;
394
555
  }
395
556
 
396
- /** Iterable handle backing a `std::vector<CfMatch>` on the C++ side.
397
- * Mirrors how embind surfaces `register_vector<T>`. */
398
- export interface CfMatchVector {
399
- size(): number;
400
- get(index: number): CfMatch;
401
- delete(): void;
402
- }
403
-
404
557
  /** One cell's CF result inside a viewport-range evaluation. */
405
558
  export interface CfCellResult {
406
559
  row: number;
407
560
  col: number;
408
- matches: CfMatchVector;
409
- }
410
-
411
- /** Iterable handle backing a `std::vector<CfCellResult>`. */
412
- export interface CfCellVector {
413
- size(): number;
414
- get(index: number): CfCellResult;
415
- delete(): void;
561
+ matches: ReadonlyArray<CfMatch>;
416
562
  }
417
563
 
418
564
  /** Return type of `Workbook.evaluateCfRange(...)`. `cells` is sparse:
419
565
  * only cells that produced at least one match appear. */
420
566
  export interface CfRangeResult {
421
567
  status: Status;
422
- cells: CfCellVector;
568
+ cells: ReadonlyArray<CfCellResult>;
569
+ }
570
+
571
+ /** Resolved print geometry for one worksheet. All coordinates are 0-based. */
572
+ export interface PaginationResult {
573
+ status: Status;
574
+ /** The sheet's declared `_xlnm.Print_Area`. Empty when the sheet declares
575
+ * none -- it is not backfilled with the used range. Pagination itself
576
+ * still falls back to the used range in that case, so `pageCount` can be
577
+ * non-zero while this is empty. */
578
+ printArea: Array<{ firstRow: number; firstCol: number; lastRow: number; lastCol: number }>;
579
+ horizontalBreaks: number[];
580
+ verticalBreaks: number[];
581
+ pageCount: number;
423
582
  }
424
583
 
425
584
  /** Per-sheet view: zoom (10..400, default 100), frozen-pane row/col
@@ -505,19 +664,17 @@ export interface ColumnLayout {
505
664
  /** Boolean stored as 0/1. */
506
665
  hidden: number;
507
666
  outlineLevel: number;
508
- }
509
-
510
- /** Iterable handle backing a `std::vector<ColumnLayout>`. */
511
- export interface ColumnLayoutVector {
512
- size(): number;
513
- get(index: number): ColumnLayout;
514
- delete(): void;
667
+ /** Whether the width is logically explicit (raw presence or non-zero legacy width). */
668
+ hasWidth: number;
669
+ /** Whether the source / model carries an explicit style attribute. */
670
+ hasStyle: number;
671
+ styleXf: number;
515
672
  }
516
673
 
517
674
  /** Return type of `Workbook.getSheetColumns(sheet)`. */
518
675
  export interface ColumnsResult {
519
676
  status: Status;
520
- columns: ColumnLayoutVector;
677
+ columns: ReadonlyArray<ColumnLayout>;
521
678
  }
522
679
 
523
680
  /** Per-row layout override. */
@@ -527,19 +684,15 @@ export interface RowLayout {
527
684
  /** Boolean stored as 0/1. */
528
685
  hidden: number;
529
686
  outlineLevel: number;
530
- }
531
-
532
- /** Iterable handle backing a `std::vector<RowLayout>`. */
533
- export interface RowLayoutVector {
534
- size(): number;
535
- get(index: number): RowLayout;
536
- delete(): void;
687
+ /** Whether OOXML customFormat=1 makes the row style effective. */
688
+ hasStyle: number;
689
+ styleXf: number;
537
690
  }
538
691
 
539
692
  /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
540
693
  export interface RowsResult {
541
694
  status: Status;
542
- rows: RowLayoutVector;
695
+ rows: ReadonlyArray<RowLayout>;
543
696
  }
544
697
 
545
698
  /** Inclusive cell rectangle used by `addMerge` / `getMerges`. */
@@ -554,8 +707,13 @@ export interface MergeRange {
554
707
  export interface HyperlinkEntry {
555
708
  row: number;
556
709
  col: number;
710
+ /** Inclusive bottom-right endpoint of the hyperlink rectangle. */
711
+ lastRow: number;
712
+ lastCol: number;
557
713
  /** Absolute or relative target (URL, email, internal ref, …). */
558
714
  target: string;
715
+ /** In-workbook destination (empty for an external target). */
716
+ location: string;
559
717
  /** Display text override (empty when default). */
560
718
  display: string;
561
719
  /** Tooltip text (empty when none). */
@@ -568,6 +726,12 @@ export interface CommentEntry {
568
726
  text: string;
569
727
  }
570
728
 
729
+ /** Status-bearing comment lookup returned by `getCommentResult`. */
730
+ export interface CommentResult {
731
+ status: Status;
732
+ comment: CommentEntry | null;
733
+ }
734
+
571
735
  /** Sheet-wide comment entry returned by `getComments(sheet)`. Extends
572
736
  * `CommentEntry` with the anchor cell so comments on otherwise-empty
573
737
  * cells can be discovered without already knowing their `(row, col)`. */
@@ -656,8 +820,9 @@ export interface CellNode {
656
820
  * `ok` is `false` when no function matches `name`; the remaining
657
821
  * fields are absent. When `ok` is `true`, `name` / `minArity` /
658
822
  * `maxArity` are always populated; `signatureTemplate` and
659
- * `description` are populated only when the locale metadata table
660
- * has an entry for this function and locale. */
823
+ * `description` are always `undefined` — the engine ships no
824
+ * human-readable function text and a host merges its own provider
825
+ * document over this result (`docs/function-metadata-schema.md`). */
661
826
  export interface FunctionMetadataResult {
662
827
  readonly ok: boolean;
663
828
  readonly name?: string;
@@ -799,6 +964,19 @@ export interface ConditionalFormatEntry {
799
964
  readonly showValue: boolean;
800
965
  readonly minLengthPct: number;
801
966
  readonly maxLengthPct: number;
967
+ /**
968
+ * `x14` extension payload. Present whenever the rule states the
969
+ * setting; a rule read back from a workbook always carries all six, so
970
+ * the object can be handed straight to `addConditionalFormat`.
971
+ *
972
+ * `axisPosition` is 0 = automatic, 1 = middle, 2 = none.
973
+ */
974
+ readonly gradient?: boolean;
975
+ readonly axisPosition?: number;
976
+ readonly negativeFill?: CfColor;
977
+ readonly border?: CfColor;
978
+ readonly negativeBorder?: CfColor;
979
+ readonly axisColor?: CfColor;
802
980
  };
803
981
  /** Engaged for `iconSet` rules. */
804
982
  readonly iconSet?: {
@@ -806,6 +984,9 @@ export interface ConditionalFormatEntry {
806
984
  readonly thresholds: ReadonlyArray<CfValueObjectInput>;
807
985
  readonly reverse: boolean;
808
986
  readonly showValue: boolean;
987
+ /** Round-trip only: the `percent` attribute is preserved across load
988
+ * and save but never consulted during evaluation. Each threshold
989
+ * carries its own `type`, and that type is what interprets it. */
809
990
  readonly percent: boolean;
810
991
  };
811
992
  }
@@ -846,6 +1027,18 @@ export interface ConditionalFormatInput {
846
1027
  showValue?: boolean;
847
1028
  minLengthPct?: number;
848
1029
  maxLengthPct?: number;
1030
+ /**
1031
+ * `x14` extension payload. Omit a key to keep the model default:
1032
+ * gradient fill on, automatic axis, negative fill equal to `fill`, no
1033
+ * border, and a black axis. `axisPosition` is 0 = automatic,
1034
+ * 1 = middle, 2 = none.
1035
+ */
1036
+ gradient?: boolean;
1037
+ axisPosition?: number;
1038
+ negativeFill?: CfColor;
1039
+ border?: CfColor;
1040
+ negativeBorder?: CfColor;
1041
+ axisColor?: CfColor;
849
1042
  };
850
1043
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
851
1044
  iconSet?: {
@@ -853,6 +1046,9 @@ export interface ConditionalFormatInput {
853
1046
  thresholds: ReadonlyArray<CfValueObjectInput>;
854
1047
  reverse?: boolean;
855
1048
  showValue?: boolean;
1049
+ /** Round-trip only: preserved across load and save but never
1050
+ * consulted during evaluation (each threshold's own `type` is
1051
+ * authoritative). */
856
1052
  percent?: boolean;
857
1053
  };
858
1054
  }
@@ -873,6 +1069,53 @@ export interface CellXfResult {
873
1069
  horizontalAlign: number;
874
1070
  verticalAlign: number;
875
1071
  wrapText: boolean;
1072
+ /** OOXML `justifyLastLine`; effective with distributed horizontal alignment. */
1073
+ justifyLastLine: boolean;
1074
+ /** Whether the source `<xf>` carried an `<alignment>` child. */
1075
+ hasAlignment: boolean;
1076
+ /** Whether `horizontal="..."` was explicitly present. */
1077
+ hasHorizontalAlign: boolean;
1078
+ /** Whether `vertical="..."` was explicitly present. */
1079
+ hasVerticalAlign: boolean;
1080
+ /** Whether `wrapText="..."` was explicitly present. */
1081
+ hasWrapText: boolean;
1082
+ /** Whether `justifyLastLine="..."` was explicitly present. */
1083
+ hasJustifyLastLine: boolean;
1084
+ /** OOXML `textRotation`; present only when the source attribute existed. */
1085
+ textRotation?: number;
1086
+ /** OOXML `indent`; present only when the source attribute existed. */
1087
+ indent?: number;
1088
+ /** OOXML signed `relativeIndent`; present only when the source attribute existed. */
1089
+ relativeIndent?: number;
1090
+ /** OOXML `shrinkToFit`; present only when the source attribute existed. */
1091
+ shrinkToFit?: boolean;
1092
+ /** OOXML `readingOrder`; present only when the source attribute existed. */
1093
+ readingOrder?: number;
1094
+ /** Index into `<cellStyleXfs>` of the named style this format inherits
1095
+ * from. Always 0 for a record read back from `getCellStyleXf`. */
1096
+ xfId?: number;
1097
+ }
1098
+
1099
+ /** How an OOXML `<color>` element expressed its value.
1100
+ * Mirrors `formulon::io::ColorSpec`.
1101
+ *
1102
+ * A record read from a workbook carries the original specification here.
1103
+ * When `kind` is non-zero, this selector is authoritative; the sibling
1104
+ * `*Argb` field is not an Excel-rendered value for theme/indexed/auto
1105
+ * selectors. It is literal RGB for `kind === 1`, or a compatibility
1106
+ * fallback otherwise. Leave `kind` at 0 on a record built from scratch and
1107
+ * the writer emits the sibling `*Argb` as `rgb`. */
1108
+ export interface ColorSpec {
1109
+ /** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
1110
+ kind: number;
1111
+ /** AARRGGBB; meaningful when `kind` is 1. */
1112
+ rgb: number;
1113
+ /** Theme index; meaningful when `kind` is 2. */
1114
+ theme: number;
1115
+ /** Theme tint in -1..1; meaningful when `kind` is 2. */
1116
+ tint: number;
1117
+ /** Legacy palette index; meaningful when `kind` is 3. */
1118
+ indexed: number;
876
1119
  }
877
1120
 
878
1121
  /** Plain-data shape of a font record. Mirrors `formulon::io::FontRecord`. */
@@ -882,28 +1125,56 @@ export interface FontRecord {
882
1125
  bold: boolean;
883
1126
  italic: boolean;
884
1127
  strike: boolean;
1128
+ /** Whether the source carried a `<b>` element at all. An absent element
1129
+ * on a differential font means "leave bold unchanged"; `hasBold` with
1130
+ * `bold: false` means "switch bold off". */
1131
+ hasBold: boolean;
1132
+ /** Whether the source carried an `<i>` element at all. */
1133
+ hasItalic: boolean;
1134
+ /** Whether the source carried a `<strike>` element at all. */
1135
+ hasStrike: boolean;
885
1136
  /** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
886
1137
  underline: number;
887
- /** AARRGGBB packed colour. */
1138
+ /** 0=baseline, 1=superscript, 2=subscript. */
1139
+ vertAlign: number;
1140
+ /** Whether the source carried a `<family>` element. */
1141
+ hasFamily: boolean;
1142
+ /** OOXML font-family class (0..5). */
1143
+ family: number;
1144
+ /** Whether the source carried a `<charset>` element. */
1145
+ hasCharset: boolean;
1146
+ /** OOXML charset codepage id (e.g. 128 = Shift_JIS). */
1147
+ charset: number;
1148
+ /** AARRGGBB literal RGB or compatibility fallback; not a resolved
1149
+ * theme/indexed/auto render colour. */
888
1150
  colorArgb: number;
1151
+ /** Original `<color>` specification, preserved for round-tripping. */
1152
+ color: ColorSpec;
889
1153
  }
890
1154
 
891
1155
  /** Plain-data shape of a fill record. Mirrors `formulon::io::FillRecord`. */
892
1156
  export interface FillRecord {
893
1157
  /** OOXML pattern ordinal: 0=none, 1=solid, 2..18=standard pattern set. */
894
1158
  pattern: number;
895
- /** Foreground AARRGGBB colour. */
1159
+ /** Foreground literal RGB or compatibility fallback. */
896
1160
  fgArgb: number;
897
- /** Background AARRGGBB colour. */
1161
+ /** Background literal RGB or compatibility fallback. */
898
1162
  bgArgb: number;
1163
+ /** Original `<fgColor>` specification, preserved for round-tripping. */
1164
+ fg: ColorSpec;
1165
+ /** Original `<bgColor>` specification, preserved for round-tripping. */
1166
+ bg: ColorSpec;
899
1167
  }
900
1168
 
901
1169
  /** One side of a `BorderRecord`. */
902
1170
  export interface BorderSide {
903
1171
  /** OOXML border-style ordinal: 0=none, 1=thin, ..., 13=slantDashDot. */
904
1172
  style: number;
905
- /** AARRGGBB packed colour. */
1173
+ /** AARRGGBB literal RGB or compatibility fallback; not a resolved
1174
+ * theme/indexed/auto render colour. */
906
1175
  colorArgb: number;
1176
+ /** Original `<color>` specification, preserved for round-tripping. */
1177
+ color: ColorSpec;
907
1178
  }
908
1179
 
909
1180
  /** Plain-data shape of a border record. Mirrors `formulon::io::BorderRecord`. */
@@ -928,6 +1199,32 @@ export interface CellXf {
928
1199
  /** 0=top, 1=center, 2=bottom, 3=justify, 4=distributed. */
929
1200
  verticalAlign: number;
930
1201
  wrapText: boolean;
1202
+ /** OOXML `justifyLastLine`; effective with distributed alignment. Defaults to false. */
1203
+ justifyLastLine?: boolean;
1204
+ /** Whether to preserve an explicit alignment child. Omit to infer from supplied alignment fields. */
1205
+ hasAlignment?: boolean;
1206
+ /** Whether `horizontalAlign` was explicitly supplied; defaults to inference. */
1207
+ hasHorizontalAlign?: boolean;
1208
+ /** Whether `verticalAlign` was explicitly supplied; defaults to inference. */
1209
+ hasVerticalAlign?: boolean;
1210
+ /** Whether `wrapText` was explicitly supplied; defaults to inference. */
1211
+ hasWrapText?: boolean;
1212
+ /** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
1213
+ hasJustifyLastLine?: boolean;
1214
+ /** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
1215
+ textRotation?: number;
1216
+ /** OOXML `indent` (0..255). Omitted when absent. */
1217
+ indent?: number;
1218
+ /** OOXML signed `relativeIndent`. Omitted when absent. */
1219
+ relativeIndent?: number;
1220
+ /** OOXML `shrinkToFit`; omitted when absent so explicit false is retained. */
1221
+ shrinkToFit?: boolean;
1222
+ /** OOXML `readingOrder` (0=context, 1=LTR, 2=RTL). Omitted when absent. */
1223
+ readingOrder?: number;
1224
+ /** Index of the named style in `<cellStyleXfs>` this format inherits from.
1225
+ * Only meaningful for `addXf`; must name an entry created by
1226
+ * `addCellStyleXf`. Defaults to 0. */
1227
+ xfId?: number;
931
1228
  }
932
1229
 
933
1230
  /** Return type of `Workbook.getFont(fontIndex)`. */
@@ -962,6 +1259,10 @@ export interface DxfRecord {
962
1259
  numFmtId: number;
963
1260
  formatCode: string;
964
1261
  };
1262
+ /** Serialized OOXML `<alignment .../>` child; lexical formatting may normalize on load. */
1263
+ alignmentXml?: string;
1264
+ /** Serialized OOXML `<protection .../>` child; lexical formatting may normalize on load. */
1265
+ protectionXml?: string;
965
1266
  }
966
1267
 
967
1268
  export interface DxfResult extends DxfRecord {
@@ -979,9 +1280,20 @@ export interface LambdaTextResult {
979
1280
  text: string;
980
1281
  }
981
1282
 
1283
+ /** Minimum severity for the engine's structured log stream. Mirrors
1284
+ * `fm_log_level_t`. `Off` discards every record and is the default: an
1285
+ * embedded library must not write to the host's stderr unless asked. */
1286
+ export enum LogLevel {
1287
+ Debug = 0,
1288
+ Info = 1,
1289
+ Warn = 2,
1290
+ Error = 3,
1291
+ Off = 4,
1292
+ }
1293
+
982
1294
  /** External-link kinds. Mirrors
983
1295
  * `formulon::io::ExternalLinkRecord::Kind`. */
984
- export const enum ExternalLinkKind {
1296
+ export enum ExternalLinkKind {
985
1297
  Unknown = 0,
986
1298
  ExternalBook = 1,
987
1299
  Ole = 2,
@@ -1040,8 +1352,9 @@ export interface AddStyleResult {
1040
1352
  index: number;
1041
1353
  }
1042
1354
 
1043
- /** Return type of `Workbook.addNumFmt(formatCode)`. The id is either a
1044
- * matched built-in (`0..163`) or a freshly-assigned custom id (`>= 164`). */
1355
+ /** Return type of `Workbook.addNumFmt(formatCode)`. The id may reuse any
1356
+ * existing effective mapping (built-in or custom, including a custom record
1357
+ * overriding a built-in slot), or be a freshly-assigned custom id (`>= 164`). */
1045
1358
  export interface AddNumFmtResult {
1046
1359
  status: Status;
1047
1360
  numFmtId: number;
@@ -1063,6 +1376,13 @@ export interface PartialRecalcResult {
1063
1376
  recomputed: number;
1064
1377
  }
1065
1378
 
1379
+ /** Result of `Workbook.getSheetAutoFilterXml`. The empty `xml` string means
1380
+ * that the sheet has no AutoFilter definition. */
1381
+ export interface SheetAutoFilterXmlResult {
1382
+ status: Status;
1383
+ xml: string;
1384
+ }
1385
+
1066
1386
  /** Iterative-solver progress callback. Receives the current
1067
1387
  * iteration number, the maximum residual seen, and the configured
1068
1388
  * iteration cap. Returning `false` (or any falsy value) aborts the
@@ -1082,7 +1402,11 @@ export interface Workbook {
1082
1402
 
1083
1403
  save(): SaveResult;
1084
1404
  /** Serialises using an explicit container `format` (see `WorkbookFormat`). */
1085
- saveEx(format: WorkbookFormat | number): SaveResult;
1405
+ saveAs(format: WorkbookFormat | number): SaveResult;
1406
+ /** Serialises using an explicit format and reports loss/defer counters. */
1407
+ saveWithDiagnostics(format: WorkbookFormat | number): SaveDiagnosticsResult;
1408
+ /** Returns the loss counters captured when this handle was loaded. */
1409
+ readDiagnostics(): ReadDiagnosticsResult;
1086
1410
  addSheet(name: string): Status;
1087
1411
  /** Removes the sheet at `index`. */
1088
1412
  removeSheet(index: number): Status;
@@ -1098,6 +1422,8 @@ export interface Workbook {
1098
1422
  /** Stores a static Excel error literal; `errorCode` is an ErrorCode ordinal. */
1099
1423
  setError(sheet: number, row: number, col: number, errorCode: number): Status;
1100
1424
  setText(sheet: number, row: number, col: number, text: string): Status;
1425
+ /** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
1426
+ setCellPhonetic(sheet: number, row: number, col: number, phonetic: string): Status;
1101
1427
  setBlank(sheet: number, row: number, col: number): Status;
1102
1428
  setFormula(sheet: number, row: number, col: number, formula: string): Status;
1103
1429
 
@@ -1140,8 +1466,23 @@ export interface Workbook {
1140
1466
  * formula text. Returns `kInvalidArgument` when the cell is absent
1141
1467
  * or its cached value is not a lambda. */
1142
1468
  getLambdaText(sheet: number, row: number, col: number): LambdaTextResult;
1469
+ /** Returns the cell's OOXML phonetic guide (`<rPh>`), or an empty string. */
1470
+ getCellPhonetic(sheet: number, row: number, col: number): StringResult;
1143
1471
 
1472
+ /** Recalculates all dirty cells serially on the caller thread. */
1144
1473
  recalc(): Status;
1474
+ /**
1475
+ * Recalculates all dirty cells using the parallel SCC scheduler and returns
1476
+ * per-call telemetry. This call is synchronous: it returns after all
1477
+ * workers have joined. `threadCount` must be a finite integer: 0 selects
1478
+ * automatic detection (capped at 8), 1 keeps evaluation on the caller and
1479
+ * starts no workers, and 2..8 set the worker upper bound. Missing,
1480
+ * fractional, non-finite, negative, or above-8 values fail with
1481
+ * `kInvalidArgument`.
1482
+ * The `uint64_t` counters in `stats` are JavaScript numbers and are exact
1483
+ * through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
1484
+ */
1485
+ recalcParallel(threadCount: number): ParallelRecalcResult;
1145
1486
  /** Recalculates only cells touched by the supplied viewport. */
1146
1487
  partialRecalc(viewport: RecalcViewport): PartialRecalcResult;
1147
1488
 
@@ -1162,6 +1503,34 @@ export interface Workbook {
1162
1503
  calcMode(): CalcMode;
1163
1504
  setCalcMode(mode: CalcMode): Status;
1164
1505
 
1506
+ /**
1507
+ * The workbook's pinned wall-clock reading, or `null` when it follows the
1508
+ * host clock (the default).
1509
+ *
1510
+ * Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
1511
+ * ("this month", "year to date", ...) one instant to agree on. Without a
1512
+ * pin each reads the clock independently, which makes a recalc internally
1513
+ * inconsistent across a midnight boundary and makes any such result
1514
+ * untestable.
1515
+ *
1516
+ * Local civil fields are carried rather than a timestamp so the reading has
1517
+ * no residual timezone interpretation: the same values reproduce the same
1518
+ * results in any zone. This is model state, not file state — `save()` does
1519
+ * not record it and a reloaded workbook comes back unpinned.
1520
+ *
1521
+ * Cached formula values are not recomputed by `setPinnedNow`; drive
1522
+ * `recalc()` to see the pin take effect on existing cells.
1523
+ *
1524
+ * `setPinnedNow` returns `kInvalidArgument` unless `year` is in
1525
+ * `[1900, 9999]`, `month` in `[1, 12]`, `day` within that month's real
1526
+ * length, `hour` in `[0, 23]`, and `minute` / `second` in `[0, 59]`. The
1527
+ * pin is a calendar instant, not a normalising constructor: a month of 13
1528
+ * is rejected rather than rolled into the next year.
1529
+ */
1530
+ pinnedNow(): CivilTime | null;
1531
+ setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1532
+ clearPinnedNow(): Status;
1533
+
1165
1534
  /**
1166
1535
  * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
1167
1536
  */
@@ -1193,6 +1562,17 @@ export interface Workbook {
1193
1562
 
1194
1563
  tableCount(): number;
1195
1564
  tableAt(idx: number): TableEntry;
1565
+ createTable(input: TableInput): AddStyleResult;
1566
+ /** Partially updates a table. Omitted fields preserve their current
1567
+ * values. A supplied `ref` must keep the table's existing column count;
1568
+ * an empty `styleName` clears the style. */
1569
+ updateTable(idx: number, input: TableUpdateInput): Status;
1570
+ removeTable(idx: number): Status;
1571
+
1572
+ /** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
1573
+ getSheetAutoFilterXml(sheet: number): SheetAutoFilterXmlResult;
1574
+ /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1575
+ setSheetAutoFilterXml(sheet: number, xml: string): Status;
1196
1576
 
1197
1577
  passthroughCount(): number;
1198
1578
  passthroughAt(idx: number): PassthroughEntry;
@@ -1349,18 +1729,25 @@ export interface Workbook {
1349
1729
  /** Replaces the data-field entry at `dataFieldIdx` in place. */
1350
1730
  pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
1351
1731
 
1352
- /** Number of active (slicer-applied) filters on the pivot. */
1732
+ /** Number of active (slicer-applied) filters on the pivot. Counts only
1733
+ * the entries this session added -- see {@link PivotFilterResult}. */
1353
1734
  pivotFilterCount(sheet: number, pivotIdx: number): number;
1354
- /** Appends an active filter. */
1735
+ /** Appends an active filter. The entry is session state and is not
1736
+ * written by `save`; see {@link PivotFilterResult}. */
1355
1737
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
1738
+ /** Reads the active filter at `filterIdx`. The list is session state:
1739
+ * see {@link PivotFilterResult}. */
1740
+ pivotFilterAt(sheet: number, pivotIdx: number, filterIdx: number): PivotFilterResult;
1356
1741
  /** Drops every active filter from the pivot. */
1357
1742
  pivotFilterClear(sheet: number, pivotIdx: number): Status;
1358
1743
  /** Removes the active filter at `filterIdx`. */
1359
1744
  pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
1360
1745
 
1361
1746
  /** Evaluates every CF block on `sheet` against the inclusive range
1362
- * `[(firstRow, firstCol), (lastRow, lastCol)]`. Pass `NaN` for
1363
- * `todaySerial` to disable `TimePeriod` rules. */
1747
+ * `[(firstRow, firstCol), (lastRow, lastCol)]`. `todaySerial` pins the
1748
+ * date basis for `TimePeriod` rules; pass `NaN` to disable them (no
1749
+ * `TimePeriod` rule then matches). `0` does *not* disable them -- it is
1750
+ * the valid serial for 1899-12-30. */
1364
1751
  evaluateCfRange(
1365
1752
  sheet: number,
1366
1753
  firstRow: number,
@@ -1370,6 +1757,9 @@ export interface Workbook {
1370
1757
  todaySerial: number,
1371
1758
  ): CfRangeResult;
1372
1759
 
1760
+ /** Computes print-area page breaks and physical page count for `sheet`. */
1761
+ paginate(sheet: number): PaginationResult;
1762
+
1373
1763
  /** Reads the full per-sheet view (zoom, freeze, tab-hidden, and the
1374
1764
  * display / orientation flags). */
1375
1765
  getSheetView(sheet: number): SheetViewResult;
@@ -1429,11 +1819,11 @@ export interface Workbook {
1429
1819
  setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
1430
1820
  /** Returns the resolved XF record at `xfIndex`. */
1431
1821
  getCellXf(xfIndex: number): CellXfResult;
1432
- /** Returns the resolved font record at `fontIndex`. */
1822
+ /** Returns the font record at `fontIndex`, including its ColorSpec selector. */
1433
1823
  getFont(fontIndex: number): FontResult;
1434
- /** Returns the resolved fill record at `fillIndex`. */
1824
+ /** Returns the fill record at `fillIndex`, including its ColorSpec selectors. */
1435
1825
  getFill(fillIndex: number): FillResult;
1436
- /** Returns the resolved border record at `borderIndex`. */
1826
+ /** Returns the border record at `borderIndex`, including its ColorSpec selectors. */
1437
1827
  getBorder(borderIndex: number): BorderResult;
1438
1828
  /** Returns the format string registered for `numFmtId`. */
1439
1829
  getNumFmt(numFmtId: number): NumFmtResult;
@@ -1447,9 +1837,13 @@ export interface Workbook {
1447
1837
  addFill(record: FillRecord): AddStyleResult;
1448
1838
  /** Adds a border (deduplicating against existing entries). */
1449
1839
  addBorder(record: BorderRecord): AddStyleResult;
1450
- /** Adds a number-format code. Built-in matches return the built-in id
1451
- * without modifying the table; custom codes are appended at
1452
- * `max(existing_custom_id, 163) + 1`. */
1840
+ /** Adds a number-format code. An existing effective mapping is reused,
1841
+ * including an existing custom record; a built-in id is reused without
1842
+ * modifying the table only when its current effective mapping matches the
1843
+ * code. Otherwise custom codes are appended at
1844
+ * `max(existing_custom_id, 163) + 1`. Effective mappings use the first
1845
+ * valid custom record for an id in document order, then a non-empty
1846
+ * built-in code. */
1453
1847
  addNumFmt(formatCode: string): AddNumFmtResult;
1454
1848
  /** Adds an `<xf>` record (deduplicating against existing entries).
1455
1849
  * Out-of-range font/fill/border indices or unregistered `numFmtId`
@@ -1484,12 +1878,20 @@ export interface Workbook {
1484
1878
  /** Returns the named-style xf record at `index`. Output shape mirrors
1485
1879
  * `getCellXf`. */
1486
1880
  getCellStyleXf(index: number): CellXfResult;
1881
+ /** Appends (deduplicating) a named-style xf and returns its
1882
+ * `<cellStyleXfs>` index, which is what `setCellStyle` and
1883
+ * `CellXf.xfId` reference. */
1884
+ addCellStyleXf(record: CellXf): AddStyleResult;
1885
+ /** Adds or replaces the `<cellStyle>` entry named `name`. `builtinId` is
1886
+ * an OOXML ordinal `0..47`, or `0xFFFFFFFF` for a custom style; it is
1887
+ * required because the binding takes a fixed argument count. */
1888
+ setCellStyle(name: string, xfId: number, builtinId: number): Status;
1487
1889
 
1488
1890
  /** Returns every external-link record carried by the workbook in
1489
1891
  * `<externalReferences>` document order. Empty for fresh workbooks
1490
1892
  * and any package whose source archive had no `<externalReferences>`
1491
1893
  * block. */
1492
- getExternalLinks(): ReadonlyArray<ExternalLinkRecord>;
1894
+ getExternalLinks(): ListResult<ExternalLinkRecord>;
1493
1895
 
1494
1896
  /** Adds a merge range to `sheet`. */
1495
1897
  addMerge(sheet: number, range: MergeRange): Status;
@@ -1500,21 +1902,42 @@ export interface Workbook {
1500
1902
  /** Drops every merge on `sheet`. */
1501
1903
  clearMerges(sheet: number): Status;
1502
1904
  /** Returns every merge range on `sheet` as a JS array. */
1503
- getMerges(sheet: number): ReadonlyArray<MergeRange>;
1905
+ getMerges(sheet: number): ListResult<MergeRange>;
1504
1906
 
1505
1907
  /** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
1506
1908
  getComment(sheet: number, row: number, col: number): CommentEntry | null;
1909
+ /** Returns a comment lookup result that distinguishes absence from an invalid sheet or handle. */
1910
+ getCommentResult(sheet: number, row: number, col: number): CommentResult;
1507
1911
  /** Returns every comment on `sheet`, including comments anchored on
1508
1912
  * cells that carry no value. */
1509
- getComments(sheet: number): ReadonlyArray<SheetCommentEntry>;
1913
+ getComments(sheet: number): ListResult<SheetCommentEntry>;
1510
1914
  /** Sets / replaces the cell comment. Pass an empty `text` to remove. */
1511
1915
  setComment(sheet: number, row: number, col: number, author: string, text: string): Status;
1512
1916
 
1513
- /** Appends a hyperlink to `sheet`. Pass empty strings for `display`
1514
- * or `tooltip` to mean "use the default" or "no tooltip". The
1515
- * `location` field is filled implicitly (empty) and the writer mints
1516
- * a fresh `rId` on save. */
1517
- addHyperlink(sheet: number, row: number, col: number, target: string, display: string, tooltip: string): Status;
1917
+ /** Appends a hyperlink to `sheet`. For an in-workbook link, pass an empty
1918
+ * `target` and its A1 destination as `location`. */
1919
+ addHyperlink(
1920
+ sheet: number,
1921
+ row: number,
1922
+ col: number,
1923
+ target: string,
1924
+ display: string,
1925
+ tooltip: string,
1926
+ location: string,
1927
+ ): Status;
1928
+ /** Appends a hyperlink covering the inclusive rectangle from `(row, col)`
1929
+ * through `(lastRow, lastCol)`. */
1930
+ addHyperlinkRange(
1931
+ sheet: number,
1932
+ row: number,
1933
+ col: number,
1934
+ lastRow: number,
1935
+ lastCol: number,
1936
+ target: string,
1937
+ display: string,
1938
+ tooltip: string,
1939
+ location: string,
1940
+ ): Status;
1518
1941
  /** Removes every hyperlink anchored at `(row, col)`. No-op when none match. */
1519
1942
  removeHyperlink(sheet: number, row: number, col: number): Status;
1520
1943
  /** Removes the hyperlink at `index`. Returns kInvalidArgument if `index` is out of range. */
@@ -1522,13 +1945,13 @@ export interface Workbook {
1522
1945
  /** Drops every hyperlink on `sheet`. */
1523
1946
  clearHyperlinks(sheet: number): Status;
1524
1947
  /** Returns every hyperlink on `sheet` as a JS array. */
1525
- getHyperlinks(sheet: number): ReadonlyArray<HyperlinkEntry>;
1948
+ getHyperlinks(sheet: number): ListResult<HyperlinkEntry>;
1526
1949
 
1527
1950
  /** Returns every data-validation rule on `sheet` in storage order.
1528
1951
  * Each rule's `ranges` mirrors the OOXML `<dataValidation sqref=...>`
1529
1952
  * cell-range list; the rule itself surfaces its raw OOXML payload
1530
1953
  * (the engine does not yet evaluate validation rules). */
1531
- getValidations(sheet: number): ReadonlyArray<DataValidationEntry>;
1954
+ getValidations(sheet: number): ListResult<DataValidationEntry>;
1532
1955
  /** Appends a data-validation rule to `sheet`. */
1533
1956
  addValidation(sheet: number, validation: DataValidationInput): Status;
1534
1957
  /** Removes the validation rule at `index`. Returns `kInvalidArgument`
@@ -1540,7 +1963,7 @@ export interface Workbook {
1540
1963
  /** Returns every CF rule on `sheet` in flattened priority order. The
1541
1964
  * returned entries borrow rule ids from the engine's storage; treat
1542
1965
  * them as immutable view objects. */
1543
- getConditionalFormats(sheet: number): ReadonlyArray<ConditionalFormatEntry>;
1966
+ getConditionalFormats(sheet: number): ListResult<ConditionalFormatEntry>;
1544
1967
  /** Appends a new single-rule `<conditionalFormatting>` block to
1545
1968
  * `sheet`, including visual rules when their payload object is supplied.
1546
1969
  * `index` is the new rule's position in the sheet's flattened CF rule
@@ -1565,24 +1988,25 @@ export interface Workbook {
1565
1988
 
1566
1989
  /** Returns metadata for the function `name` (case-insensitive). When
1567
1990
  * the function is unknown, returns `{ok: false}`. `locale` selects
1568
- * the catalog locale (`0` = `en-US`, `1` = `ja-JP`); description /
1569
- * signature fields are populated only when the locale metadata table
1570
- * has an entry. */
1991
+ * the catalog locale (`0` = `en-US`, `1` = `ja-JP`) and is validated,
1992
+ * but does not change the result: the description / signature fields
1993
+ * are always `undefined` (see {@link FunctionMetadataResult}). */
1571
1994
  functionMetadata(name: string, locale: number): FunctionMetadataResult;
1572
1995
  /** Returns every registered function's canonical name in ascending
1573
1996
  * sort order. */
1574
1997
  functionNames(): ReadonlyArray<string>;
1575
1998
 
1576
1999
  /** Returns the localized display name for the canonical function
1577
- * `canonicalName` in `locale`. Returns the canonical name unchanged
1578
- * when the locale's alias table is empty (currently always for
1579
- * non-`en-US` locales). Returns the empty string when the canonical
1580
- * name does not match a registered function. */
2000
+ * `canonicalName` in `locale`. No alias table exists in any locale,
2001
+ * so this always returns the canonical name unchanged; localized
2002
+ * display names belong to the host's provider document. Returns the
2003
+ * empty string when the canonical name does not match a registered
2004
+ * function. */
1581
2005
  localizeFunctionName(canonicalName: string, locale: number): string;
1582
2006
  /** Inverse of `localizeFunctionName`: returns the canonical English
1583
- * name for the localized function `localizedName`. Falls through to
1584
- * case-insensitive canonical-name matching when no alias is
1585
- * registered. Returns the empty string when no function matches. */
2007
+ * name for the localized function `localizedName`. With no alias
2008
+ * table this is a case-insensitive canonical-name match, in every
2009
+ * locale. Returns the empty string when no function matches. */
1586
2010
  canonicalizeFunctionName(localizedName: string, locale: number): string;
1587
2011
 
1588
2012
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
@@ -1610,8 +2034,12 @@ export interface WorkbookCtor {
1610
2034
  export interface FormulonModule {
1611
2035
  Workbook: WorkbookCtor;
1612
2036
 
1613
- /** Convenience: evaluates a single formula in a fresh workbook
1614
- * (place at `Sheet1!A1`, recalc, return the cached value). */
2037
+ /** Convenience: evaluates `formula` read-only against a fresh
2038
+ * single-sheet workbook, anchored at `Sheet1!A1`. Nothing is written
2039
+ * and no recalc runs, so an anchor-referencing formula such as `=A1`
2040
+ * or `=COUNTA(A1)` reads the blank anchor rather than becoming a
2041
+ * self-reference. An array result is reduced to its top-left element;
2042
+ * use `Workbook.evaluateFormulaArray` for the whole grid. */
1615
2043
  evalFormula(formula: string): EvalResult;
1616
2044
 
1617
2045
  /** Library version string (UTF-8). */
@@ -1623,11 +2051,31 @@ export interface FormulonModule {
1623
2051
  /** Static description of `status` (e.g. `"kOk"`). */
1624
2052
  statusString(status: number): string;
1625
2053
 
2054
+ /** Excel display literal for a cell error code (e.g. `"#DIV/0!"`). */
2055
+ errorDisplayName(errorCode: number): string;
2056
+
1626
2057
  /** Most-recent thread-local error message. */
1627
2058
  lastErrorMessage(): string;
1628
2059
 
1629
2060
  /** Most-recent thread-local error context. */
1630
2061
  lastErrorContext(): string;
2062
+
2063
+ /** Sets the engine's minimum structured-log severity (a `LogLevel`
2064
+ * ordinal). This is **process-wide** state, not per `Workbook`. The
2065
+ * default is `LogLevel.Off`, under which the engine writes nothing to
2066
+ * stderr and invokes no sink. */
2067
+ setLogMinLevel(level: number): Status;
2068
+
2069
+ /** Routes structured-log records to `sink`, or restores the (silent at
2070
+ * the default threshold) stderr fallback when `sink` is `null`.
2071
+ * **Process-wide** state, not per `Workbook`.
2072
+ *
2073
+ * `sink` receives one complete JSON record as raw bytes -- the C ABI
2074
+ * hands the binding a length-delimited range, never a NUL-terminated
2075
+ * string. The view is only valid for the duration of the call; copy it
2076
+ * (`new Uint8Array(record)`) or decode it (`new TextDecoder().decode(
2077
+ * record)`) before returning. */
2078
+ setLogSink(sink: ((record: Uint8Array) => void) | null): Status;
1631
2079
  }
1632
2080
 
1633
2081
  /** Optional Emscripten module-init overrides. Pass to the factory to