@beyondwork/xlsx-substrate-bindings 0.0.0-stage → 0.2.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.
Files changed (47) hide show
  1. package/LICENSE.md +31 -0
  2. package/README.md +135 -2
  3. package/dist/ai/agent-metadata.d.ts +363 -0
  4. package/dist/ai/agent-metadata.js +227 -0
  5. package/dist/ai/index.d.ts +6 -0
  6. package/dist/ai/index.js +7 -0
  7. package/dist/ai/mutation-bridge.d.ts +82 -0
  8. package/dist/ai/mutation-bridge.js +179 -0
  9. package/dist/ai/types.d.ts +765 -0
  10. package/dist/ai/types.js +23 -0
  11. package/dist/index.d.ts +50 -0
  12. package/dist/index.js +90 -0
  13. package/dist/runtime/index.d.ts +2 -0
  14. package/dist/runtime/index.js +1 -0
  15. package/dist/runtime/types.d.ts +1435 -0
  16. package/dist/runtime/types.js +15 -0
  17. package/dist/shared.d.ts +69 -0
  18. package/dist/shared.js +1 -0
  19. package/dist/ui/index.d.ts +2 -0
  20. package/dist/ui/index.js +1 -0
  21. package/dist/ui/types.d.ts +765 -0
  22. package/dist/ui/types.js +12 -0
  23. package/dist/wasm/ai-session-bridge.d.ts +97 -0
  24. package/dist/wasm/ai-session-bridge.js +154 -0
  25. package/dist/wasm/bridge-contract.d.ts +643 -0
  26. package/dist/wasm/bridge-contract.js +1001 -0
  27. package/dist/wasm/index.d.ts +50 -0
  28. package/dist/wasm/index.js +297 -0
  29. package/dist/wasm/memory-budget.d.ts +77 -0
  30. package/dist/wasm/memory-budget.js +532 -0
  31. package/dist/wasm/runtime-guard.d.ts +141 -0
  32. package/dist/wasm/runtime-guard.js +373 -0
  33. package/dist/wasm/session-router.d.ts +98 -0
  34. package/dist/wasm/session-router.js +184 -0
  35. package/dist/wasm/sheet-window-binary-reference.d.ts +9 -0
  36. package/dist/wasm/sheet-window-binary-reference.js +308 -0
  37. package/dist/wasm/sheet-window-binary.d.ts +279 -0
  38. package/dist/wasm/sheet-window-binary.js +636 -0
  39. package/dist/wasm/web.d.ts +72 -0
  40. package/dist/wasm/web.js +142 -0
  41. package/generated/wasm-web/package.json +3 -0
  42. package/generated/wasm-web/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +42 -0
  43. package/generated/wasm-web/xlsx_substrate_wasm.d.ts +532 -0
  44. package/generated/wasm-web/xlsx_substrate_wasm.js +2493 -0
  45. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
  46. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +120 -0
  47. package/package.json +55 -3
@@ -0,0 +1,765 @@
1
+ import type { XlsxBlocker, XlsxCellAddress, XlsxCellRange, XlsxReadbackEnvelope, XlsxScopeHandle } from "../shared.ts";
2
+ import type { XlsxWorkflowContextInput } from "../runtime/types.ts";
3
+ export type XlsxUiStateClass = "canonical-document" | "session-shared" | "local-preference";
4
+ export type XlsxUiStateNamespace = "runtime.workbook" | "runtime.viewport" | "runtime.collab.session" | "ui.local.preference" | "ui.scope.projection";
5
+ export declare function classifyXlsxUiState(namespace: XlsxUiStateNamespace): XlsxUiStateClass;
6
+ export type XlsxUiBlockerCode = "missing-active-sheet" | "layout-projection-refused" | "selection-not-inspectable" | "capability-blocked" | "workflow-blocked";
7
+ export interface XlsxUiBlocker extends XlsxBlocker {
8
+ readonly code: XlsxUiBlockerCode;
9
+ }
10
+ export interface XlsxUiSessionBinding {
11
+ readonly envelope: XlsxReadbackEnvelope;
12
+ readonly status: "bound" | "missing-active-sheet";
13
+ readonly workbookId: string;
14
+ /**
15
+ * Session identity at emission — an opaque value that advances on every
16
+ * applied mutation; equality/advancement only, never a recomputable state
17
+ * hash. FD-3 stale-card demotion compares this against a held mutation's
18
+ * `audit.afterCanonicalHash` (see
19
+ * `XlsxRuntimeSessionMutationReceipt.canonicalHash`).
20
+ */
21
+ readonly canonicalHash: string;
22
+ readonly activeSheetId?: string;
23
+ readonly sheets: readonly XlsxUiSessionSheet[];
24
+ readonly blockers: readonly XlsxUiBlocker[];
25
+ }
26
+ export interface XlsxUiSessionSheet {
27
+ readonly sheetId: string;
28
+ readonly name: string;
29
+ readonly visibility: "visible" | "hidden" | "very-hidden";
30
+ readonly populatedCellCount: number;
31
+ }
32
+ export interface XlsxUiViewportHint {
33
+ readonly sheetId: string;
34
+ readonly visibleRange: XlsxCellRange;
35
+ readonly overscanRows: number;
36
+ readonly overscanColumns: number;
37
+ readonly originXPx: number;
38
+ readonly originYPx: number;
39
+ readonly zoomMilli: number;
40
+ /**
41
+ * Prefetch-density metadata only (E1 contract). Geometry is CSS-pixel
42
+ * semantic space and never scales with this field; device scaling is
43
+ * owned exclusively by L11 from `window.devicePixelRatio`. Retained so
44
+ * the bridge hint shape is unchanged. Shipped producers send 1000.
45
+ */
46
+ readonly devicePixelRatioMilli: number;
47
+ }
48
+ export interface XlsxUiViewportReadback {
49
+ readonly status: "accepted" | "refused";
50
+ readonly hint: XlsxUiViewportHint;
51
+ readonly projectedRange?: XlsxCellRange;
52
+ readonly layoutCacheKey?: string;
53
+ readonly geometryCacheKey?: string;
54
+ readonly blockers: readonly XlsxUiBlocker[];
55
+ }
56
+ /**
57
+ * BR-1/D1 verdict vocabulary for per-operation capability records. Matches
58
+ * `ConductorToolCapabilityVerdict` wire strings.
59
+ */
60
+ export type XlsxUiOperationCapabilityVerdict = "supported" | "warn-and-proceed" | "hard-refusal";
61
+ /**
62
+ * BR-1/D1 per-operation capability record (bridge v18). `operationId` is the
63
+ * runtime-owned tool-registry operation vocabulary (e.g. `data.filter`,
64
+ * `range.value-edit`); `blockers` are typed kebab-case codes, never prose —
65
+ * user-facing copy maps from codes in one service-side place.
66
+ */
67
+ export interface XlsxUiOperationCapabilityRecord {
68
+ readonly operationId: string;
69
+ readonly verdict: XlsxUiOperationCapabilityVerdict;
70
+ readonly blockers: readonly string[];
71
+ }
72
+ export interface XlsxUiSelectionReadback {
73
+ readonly envelope: XlsxReadbackEnvelope;
74
+ readonly handle: XlsxScopeHandle;
75
+ readonly label: string;
76
+ readonly scopeKind: XlsxScopeHandle["kind"];
77
+ readonly sheetId?: string;
78
+ readonly cellId?: string;
79
+ readonly address?: XlsxCellAddress;
80
+ readonly range?: XlsxCellRange;
81
+ /**
82
+ * X5-U-028 (bridge v24): the selection's orientation. `anchor` is the
83
+ * cell the user started from (Excel's active cell); `head` is the corner
84
+ * keyboard extension moves. Both lie inside `range`. The runtime derives
85
+ * them from the target (top-left / bottom-right, or the cell itself)
86
+ * unless the read carried an `XlsxUiSelectionCursor`, which it validates
87
+ * and echoes — so a C3 -> A1 drag keeps anchor C3 across every refresh.
88
+ * Absent only when the selection has neither an address nor a range.
89
+ */
90
+ readonly anchor?: XlsxCellAddress;
91
+ readonly head?: XlsxCellAddress;
92
+ readonly valueKind?: string;
93
+ readonly formulaText?: string;
94
+ /**
95
+ * X5-U-009 (bridge v31): the link on a cell-target selection, so the
96
+ * formula bar / status can show where it goes. Absent on unlinked cells
97
+ * and on every non-cell scope.
98
+ */
99
+ readonly hyperlink?: XlsxUiCellHyperlink;
100
+ /** Runtime-computed status-bar aggregates over the full selected range. */
101
+ readonly aggregates?: XlsxUiSelectionAggregates;
102
+ readonly geometry: XlsxUiSelectionGeometryReadback;
103
+ readonly editability: "editable" | "warn-and-proceed" | "blocked";
104
+ readonly blockers: readonly XlsxUiBlocker[];
105
+ /**
106
+ * BR-1/D1 (bridge v18): full-list per-operation capability records for
107
+ * this selection. The v18 wire always emits the full runtime-owned
108
+ * operation list; empty only on refused readbacks. Required since BR-4 —
109
+ * consumers drive enablement from these records (fail-closed: a
110
+ * runtime-owned operation missing from the list is a hard refusal).
111
+ */
112
+ readonly capabilities: readonly XlsxUiOperationCapabilityRecord[];
113
+ }
114
+ /**
115
+ * X5-U-028 (bridge v24): host-owned selection orientation sent with a
116
+ * selection read. A scope handle is normalized (`A1:C3` whichever corner
117
+ * the drag started from), so the orientation cannot be recovered from the
118
+ * handle; the host sends the corners it built the handle from and the
119
+ * runtime echoes them on `XlsxUiSelectionReadback.anchor`/`head` after
120
+ * checking both lie inside the selected range. A cursor outside the range
121
+ * is a request error (the cursor was paired with the wrong handle), never a
122
+ * silent reset to the derived corners.
123
+ */
124
+ export interface XlsxUiSelectionCursor {
125
+ readonly anchor: XlsxCellAddress;
126
+ readonly head: XlsxCellAddress;
127
+ }
128
+ export interface XlsxUiSelectionAggregates {
129
+ readonly sum?: number;
130
+ readonly average?: number;
131
+ readonly count: number;
132
+ readonly numericCount: number;
133
+ /**
134
+ * X3-R-031 (bridge v38): stored cells of the WHOLE selection that carry a
135
+ * formula (a shared-formula child counts once, like its master).
136
+ */
137
+ readonly formulaCount: number;
138
+ /**
139
+ * X3-R-031 (bridge v38): addresses of the WHOLE selection the editability
140
+ * verdict blocks — sheet protection over locked addresses (blank addresses
141
+ * included, the way the sheet-window readback blocks a blank slot),
142
+ * covered merge cells, kernel output regions.
143
+ */
144
+ readonly blockedCount: number;
145
+ }
146
+ export interface XlsxUiSelectionSetReadback {
147
+ readonly envelope: XlsxReadbackEnvelope;
148
+ readonly status: "single-area" | "multi-area" | "empty";
149
+ readonly areas: readonly XlsxUiSelectionSetArea[];
150
+ readonly activeAreaId?: string;
151
+ readonly anchorAreaId?: string;
152
+ readonly summary: XlsxUiSelectionSetSummary;
153
+ /**
154
+ * X5-U-025 (bridge v27): set-level typed blockers — one `capability-blocked`
155
+ * entry per operation the SET refuses that its areas alone would not, with
156
+ * the operation id as `target`. Empty for a one-area set.
157
+ */
158
+ readonly blockers: readonly XlsxUiBlocker[];
159
+ /**
160
+ * X5-U-025 (bridge v27): the ONE full-list capability record set for the
161
+ * whole selection set — worst-wins over the areas plus the set-only facts
162
+ * (the aggregate write ceiling; `multi-area-selection` on every verb whose
163
+ * commit takes one range). The host index reads THIS when the set has two
164
+ * or more areas; each area's own `selection.capabilities` describes that
165
+ * area alone. Fail-closed like the single-area list: a runtime-owned
166
+ * operation missing here is a hard refusal.
167
+ */
168
+ readonly capabilities: readonly XlsxUiOperationCapabilityRecord[];
169
+ }
170
+ export interface XlsxUiSelectionSetArea {
171
+ readonly areaId: string;
172
+ readonly selection: XlsxUiSelectionReadback;
173
+ readonly role: "active" | "anchor" | "additional";
174
+ }
175
+ export interface XlsxUiSelectionSetSummary {
176
+ readonly areaCount: number;
177
+ readonly projectedAreaCount: number;
178
+ readonly formulaAreaCount: number;
179
+ readonly blockedAreaCount: number;
180
+ readonly blockerCount: number;
181
+ readonly label: string;
182
+ }
183
+ export interface XlsxUiSelectionGeometryReadback {
184
+ readonly status: "unavailable" | "not-projected" | "projected";
185
+ readonly projection?: "complete" | "clipped" | "outside-window";
186
+ readonly rectCount: number;
187
+ readonly reason?: string;
188
+ }
189
+ export interface XlsxUiAccessibilitySummary {
190
+ readonly envelope: XlsxReadbackEnvelope;
191
+ readonly label: string;
192
+ readonly scopeKind: XlsxScopeHandle["kind"];
193
+ readonly sheetId?: string;
194
+ readonly address?: XlsxCellAddress;
195
+ readonly range?: XlsxCellRange;
196
+ readonly valueKind?: string;
197
+ readonly hasFormula: boolean;
198
+ readonly geometryStatus: XlsxUiSelectionGeometryReadback["status"];
199
+ readonly editability: XlsxUiSelectionReadback["editability"];
200
+ readonly blockerCount: number;
201
+ }
202
+ /**
203
+ * UX-P-104 (bridge v22): the sheet's true used-range bounds and the exact
204
+ * CSS-pixel size of the grid from A1 to those bounds, at this readback's
205
+ * zoom.
206
+ *
207
+ * The readback itself describes a LOADED WINDOW. Without this the mounted
208
+ * scroll surface had to ESTIMATE how much sheet lay beyond that window
209
+ * (loaded window + a two-window tail at default 20px/64px metrics, grown
210
+ * monotonically so the scrollbar never shrank), which made the scrollbar
211
+ * thumb a guess on every sheet and a wrong one on any sheet with authored
212
+ * row heights or column widths. Consumers size the scroll surface from
213
+ * `widthPx`/`heightPx` and clamp requested windows to `lastRow`/`lastColumn`.
214
+ *
215
+ * Absent when the sheet has no used range (an empty sheet) and on refused
216
+ * windows.
217
+ */
218
+ export interface XlsxUiSheetExtent {
219
+ /** First used row (1-based). */
220
+ readonly firstRow: number;
221
+ /** First used column (1-based). */
222
+ readonly firstColumn: number;
223
+ /** Last used row (1-based) — the bottom of the scrollable sheet. */
224
+ readonly lastRow: number;
225
+ /** Last used column (1-based) — the right edge of the scrollable sheet. */
226
+ readonly lastColumn: number;
227
+ /**
228
+ * Exact CSS-pixel width of columns 1..=`lastColumn` at this readback's
229
+ * zoom. Hidden columns contribute zero, exactly as the paint geometry
230
+ * projects them.
231
+ */
232
+ readonly widthPx: number;
233
+ /** Exact CSS-pixel height of rows 1..=`lastRow`; hidden rows contribute zero. */
234
+ readonly heightPx: number;
235
+ /**
236
+ * UX-P-104 rework: bucket width, in ROW INDICES, of `rowOffsets`.
237
+ */
238
+ readonly rowOffsetStride: number;
239
+ /**
240
+ * UX-P-104 rework: sampled cumulative row offsets. `rowOffsets[k]` is the
241
+ * exact CSS-pixel height of rows `1..=min(k * rowOffsetStride, lastRow)` —
242
+ * the sheet offset of the TOP of row `k * stride + 1`. `rowOffsets[0]` is
243
+ * always 0 and the last entry is always exactly `heightPx`.
244
+ *
245
+ * `heightPx / lastRow` is NOT the sheet's mean row height: it is total
246
+ * VISIBLE height over total INDEX count, and it only maps the sheet when
247
+ * the hidden and tall rows are spread evenly. Where they are CLUSTERED —
248
+ * an autofilter over a sorted column, a collapsed group at the end of a
249
+ * report, a tall title band — that mean puts a stretch of the scrollbar
250
+ * over rows that occupy no pixels, and the grid at the bottom of the bar
251
+ * paints nothing. These samples are the sheet's real shape at bucket
252
+ * resolution.
253
+ */
254
+ readonly rowOffsets: readonly number[];
255
+ /** Bucket width, in COLUMN INDICES, of `columnOffsets`. */
256
+ readonly columnOffsetStride: number;
257
+ /** Sampled cumulative column offsets; same contract, last entry `widthPx`. */
258
+ readonly columnOffsets: readonly number[];
259
+ }
260
+ /**
261
+ * UX-P-104 rework: the exact sheet offset of the LOADED window's first row and
262
+ * column, in CSS pixels at this readback's zoom, measured from row 1 / column
263
+ * 1 on the same metric walk as `XlsxUiSheetExtent`.
264
+ *
265
+ * The client cannot derive this from the sampled index: the projection grows
266
+ * the requested range by the overscan, so a loaded window rarely starts on a
267
+ * bucket edge. Interpolating it instead would put the window's paint somewhere
268
+ * other than where the surface says the window is — which is the exact class
269
+ * of disagreement between the surface and the offset -> row map that UX-P-104
270
+ * exists to remove.
271
+ */
272
+ export interface XlsxUiSheetWindowOrigin {
273
+ readonly xPx: number;
274
+ readonly yPx: number;
275
+ }
276
+ export interface XlsxUiSheetWindowReadback {
277
+ readonly envelope: XlsxReadbackEnvelope;
278
+ readonly status: "accepted" | "refused";
279
+ readonly workbookId: string;
280
+ /**
281
+ * Session identity at emission — opaque; equality/advancement only (see
282
+ * `XlsxRuntimeSessionMutationReceipt.canonicalHash`).
283
+ */
284
+ readonly canonicalHash: string;
285
+ readonly activeSheetId?: string;
286
+ readonly sheetName?: string;
287
+ readonly viewport: XlsxUiViewportReadback;
288
+ readonly coordinatePosture: XlsxUiSheetWindowCoordinatePosture;
289
+ /**
290
+ * X5-U-018: right-to-left sheet (`<sheetView rightToLeft="1">`). The paint
291
+ * geometry column offsets are already mirrored (column A on the right); the
292
+ * mounted grid reads this to set `dir="rtl"` for text and scroll direction.
293
+ * Absent/false for the common left-to-right sheet.
294
+ */
295
+ readonly rightToLeft?: boolean;
296
+ /**
297
+ * UX-P-104: the sheet's true used-range bounds and exact pixel extent —
298
+ * the whole sheet, not this window. The mounted scroll surface sizes
299
+ * itself from this instead of estimating the tail beyond the window.
300
+ * Absent on an empty sheet and on refused windows.
301
+ */
302
+ readonly sheetExtent?: XlsxUiSheetExtent;
303
+ /**
304
+ * UX-P-104 rework: where the loaded window sits on `sheetExtent`. Present
305
+ * exactly when `sheetExtent` is.
306
+ */
307
+ readonly sheetWindowOrigin?: XlsxUiSheetWindowOrigin;
308
+ readonly rows: readonly XlsxUiSheetWindowRow[];
309
+ readonly columns: readonly XlsxUiSheetWindowColumn[];
310
+ readonly cells: readonly XlsxUiSheetWindowCell[];
311
+ readonly mergedRanges: readonly XlsxUiSheetWindowMergedRange[];
312
+ readonly panePartitions: readonly XlsxUiSheetWindowPanePartition[];
313
+ /**
314
+ * X5-U-011 (bridge v31): the active sheet's typed data-validation rules —
315
+ * resolved list values for the in-cell picker, alert text for the commit
316
+ * banner, and the cells inside this window whose current value violates
317
+ * their rule (Excel's "circle invalid data"). v32 adds the `none` and
318
+ * `time` rule types and the comparison `operator`. Optional on the type
319
+ * so a v30 readback still types; the mounted grid treats absent as empty.
320
+ */
321
+ readonly dataValidations?: readonly XlsxUiSheetWindowDataValidation[];
322
+ readonly paintGeometry?: XlsxUiSheetWindowPaintGeometry;
323
+ readonly activeSelection?: XlsxUiSelectionReadback;
324
+ readonly accessibility?: XlsxUiAccessibilitySummary;
325
+ /**
326
+ * BR-1/D1 (bridge v18): full-list per-operation capability records for
327
+ * this window — the active selection's records when a selection is
328
+ * present, otherwise the window-scoped projection. Empty ONLY on refused
329
+ * windows. Required since BR-4 — consumers drive enablement from these
330
+ * records (fail-closed: a missing runtime-owned operation is a hard
331
+ * refusal).
332
+ */
333
+ readonly capabilities: readonly XlsxUiOperationCapabilityRecord[];
334
+ readonly blockers: readonly XlsxUiBlocker[];
335
+ readonly cache?: XlsxUiSheetWindowCacheReadback;
336
+ }
337
+ export interface XlsxUiSheetWindowCacheReadback {
338
+ readonly status: "hit" | "miss";
339
+ readonly cacheKey: string;
340
+ readonly missReason?: string;
341
+ }
342
+ export interface XlsxUiSheetWindowCoordinatePosture {
343
+ readonly nativeAddressAuthority: "worksheet-a1";
344
+ readonly projectionPosture: "visual-only";
345
+ readonly hiddenMetricsPosture: "included-with-hidden-flag";
346
+ readonly filteredSortedPosture: "native-order" | "not-modeled-preserve-native" | "sorted-or-filtered-preserve-native" | "mapping-blocked";
347
+ }
348
+ /**
349
+ * Why a hidden row/column is hidden.
350
+ *
351
+ * - `manual` — the user's own hide; the visibility commands toggle it.
352
+ * - `preserve-native-governed` — a preserved autoFilter/sortState owns the
353
+ * visible-row state and refuses the toggle.
354
+ * - `cleared-filter-band` (X1-D-030) — the row sat inside a filter the user
355
+ * has since cleared and stayed hidden, because clearing a filter does not
356
+ * own the stored hidden bit. It toggles like a manual hide; the distinct
357
+ * value exists so the grid can explain why the gap is still there.
358
+ */
359
+ export type XlsxUiHiddenMetricPosture = "manual" | "preserve-native-governed" | "cleared-filter-band";
360
+ export interface XlsxUiSheetWindowRow {
361
+ readonly row: number;
362
+ readonly heightPoints: string;
363
+ readonly hidden: boolean;
364
+ readonly customHeight: boolean;
365
+ readonly precision: XlsxUiLayoutPrecision;
366
+ readonly outlineLevel?: number | null;
367
+ readonly collapsed?: boolean;
368
+ readonly hiddenPosture?: XlsxUiHiddenMetricPosture | null;
369
+ }
370
+ export interface XlsxUiSheetWindowColumn {
371
+ readonly column: number;
372
+ readonly width: string;
373
+ readonly hidden: boolean;
374
+ readonly customWidth: boolean;
375
+ readonly precision: XlsxUiLayoutPrecision;
376
+ readonly outlineLevel?: number | null;
377
+ readonly collapsed?: boolean;
378
+ readonly hiddenPosture?: XlsxUiHiddenMetricPosture | null;
379
+ }
380
+ export interface XlsxUiSheetWindowCell {
381
+ readonly address: XlsxCellAddress;
382
+ readonly cellId?: string;
383
+ readonly selectionHandle?: XlsxScopeHandle;
384
+ readonly displayText?: string;
385
+ readonly valueKind?: string;
386
+ readonly formulaText?: string;
387
+ readonly displayFingerprint?: string;
388
+ readonly styleRef?: string;
389
+ readonly displayFormatPosture?: "general" | "builtin-supported" | "custom-supported" | "date-time-supported-subset" | "date-time-unsupported" | "currency-supported-subset" | "currency-unsupported" | "locale-unsupported" | "complex-unsupported" | "unsupported" | "missing";
390
+ readonly numFmtId?: number;
391
+ readonly formatCode?: string;
392
+ readonly bold?: boolean;
393
+ readonly italic?: boolean;
394
+ readonly underline?: boolean;
395
+ /** D1a display style: resolved solid fill color (#RRGGBB). */
396
+ readonly fillColor?: string;
397
+ /** D1a display style: resolved font color (#RRGGBB). */
398
+ readonly fontColor?: string;
399
+ /** X1-D-011a: sanitized authored font family name (readback + paint stack). */
400
+ readonly fontName?: string;
401
+ /**
402
+ * X1-D-011a: authored font size in points (validated numeric source string).
403
+ * Readback-only — the canvas painter stays on the engine's 12px metric so
404
+ * underline offsets and MDW width math do not desync (typed follow-up).
405
+ */
406
+ readonly fontSizePoints?: string;
407
+ /**
408
+ * D1b-2: value-conditional text color from a matched `[Red]` number-format
409
+ * section (#FF0000). Wins over `fontColor` in paint precedence.
410
+ */
411
+ readonly displayTextColor?: string;
412
+ /**
413
+ * D1a display style: explicit horizontal alignment override. X5-U-008 (iii)
414
+ * adds `justify` / `distributed` (bridge v29): both imply multi-line layout
415
+ * whether or not `wrapText` is set; `justify` spreads every line but the
416
+ * last to the cell width, `distributed` spreads every line.
417
+ */
418
+ readonly horizontalAlignment?: "left" | "center" | "right" | "justify" | "distributed";
419
+ /**
420
+ * X5-U-008 (ii) display style: explicit vertical alignment override. Absent
421
+ * means Excel's default anchor (bottom).
422
+ */
423
+ readonly verticalAlignment?: "top" | "middle" | "bottom";
424
+ readonly wrapText?: boolean;
425
+ readonly borderTop?: boolean;
426
+ readonly borderRight?: boolean;
427
+ readonly borderBottom?: boolean;
428
+ readonly borderLeft?: boolean;
429
+ readonly mergeRole: "unmerged" | "owner" | "covered";
430
+ readonly mergeOwner?: XlsxCellAddress;
431
+ readonly mergeRange?: XlsxCellRange;
432
+ readonly editability: XlsxUiSelectionReadback["editability"];
433
+ readonly blockers: readonly XlsxUiBlocker[];
434
+ readonly postureMarkers: readonly string[];
435
+ /**
436
+ * X5-U-009 (bridge v31): the link this cell carries — an authored worksheet
437
+ * `<hyperlink>` or a `HYPERLINK()` formula — with its follow posture
438
+ * settled by the runtime. The grid paints the link affordance from this
439
+ * field alone (never from a DOM or text heuristic). Rides the binary
440
+ * envelope's `rest.rareCells` side table; absent on every unlinked cell.
441
+ */
442
+ readonly hyperlink?: XlsxUiCellHyperlink;
443
+ }
444
+ /**
445
+ * X5-U-009 (bridge v31): a cell link as the mounted surface reads it.
446
+ *
447
+ * - `kind` — `external` (http/https/mailto URI) or `internal` (a place in
448
+ * this workbook: `Sheet1!B2`, `'My Sheet'!A1:C9`, or a defined name).
449
+ * - `source` — `authored` (worksheet `<hyperlink>`) or `formula`
450
+ * (`HYPERLINK()`; the target is read from the formula's first argument).
451
+ * - `follow` — whether L11 may follow it. `refused` carries a typed
452
+ * `refusal`: the six authoring-policy reasons (`scheme-not-allowed` for
453
+ * `javascript:` / `data:` / `file:`, ...) plus `location-not-found` (the
454
+ * sheet or name is not in this workbook) and `target-unresolved` (a
455
+ * HYPERLINK() whose target is an expression, not a literal or one cell).
456
+ * - `sheetId` + `range` — present exactly for an allowed internal link: the
457
+ * runtime-resolved destination. The client never resolves a sheet name or
458
+ * a defined name itself.
459
+ */
460
+ export interface XlsxUiCellHyperlink {
461
+ readonly kind: "internal" | "external";
462
+ /** The URI, or the location text (`#` already stripped for a formula). */
463
+ readonly target: string;
464
+ readonly tooltip?: string;
465
+ readonly source: "authored" | "formula";
466
+ readonly follow: "allowed" | "refused";
467
+ readonly refusal?: "empty" | "scheme-missing" | "scheme-not-allowed" | "invalid-url" | "invalid-location" | "too-long" | "location-not-found" | "target-unresolved";
468
+ readonly sheetId?: string;
469
+ readonly range?: XlsxCellRange;
470
+ }
471
+ /** X5-U-011: one typed data-validation rule as the grid reads it. */
472
+ export interface XlsxUiSheetWindowDataValidation {
473
+ readonly range: XlsxCellRange;
474
+ /** The OOXML `type`; `none` is Excel's "Any value" (prompt-only) rule. */
475
+ readonly ruleType: "none" | "list" | "whole" | "decimal" | "date" | "time" | "textLength" | "custom";
476
+ /** The OOXML `operator` of a comparison-shaped rule; absent for list, custom and any-value. */
477
+ readonly operator?: "between" | "notBetween" | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual";
478
+ /** Picker values for a list rule; absent for other kinds or an unresolved source. */
479
+ readonly listValues?: readonly string[];
480
+ /** A list rule whose author left "In-cell dropdown" on. */
481
+ readonly showsDropdown: boolean;
482
+ /** `showErrorMessage`: whether a commit is checked at all. */
483
+ readonly enforced: boolean;
484
+ readonly errorStyle: "stop" | "warning" | "information";
485
+ readonly errorTitle?: string;
486
+ /** The author's message, or Excel's default wording. */
487
+ readonly errorMessage: string;
488
+ readonly promptTitle?: string;
489
+ readonly prompt?: string;
490
+ /** Cells of the projected window whose current value violates the rule. */
491
+ readonly invalidCells: readonly XlsxCellAddress[];
492
+ }
493
+ export interface XlsxUiSheetWindowMergedRange {
494
+ readonly sourceRange: XlsxCellRange;
495
+ readonly clippedRange: XlsxCellRange;
496
+ readonly owner: XlsxCellAddress;
497
+ readonly coveredCellCount: number;
498
+ readonly precision: XlsxUiLayoutPrecision;
499
+ }
500
+ export interface XlsxUiSheetWindowPanePartition {
501
+ readonly region: "top-left" | "top" | "left" | "body";
502
+ readonly range: XlsxCellRange;
503
+ readonly precision: XlsxUiLayoutPrecision;
504
+ }
505
+ export interface XlsxUiSheetWindowPaintGeometry {
506
+ readonly rows: readonly XlsxUiPaintRowGeometry[];
507
+ readonly columns: readonly XlsxUiPaintColumnGeometry[];
508
+ readonly cells: readonly XlsxUiPaintCellGeometry[];
509
+ readonly activeSelection?: XlsxUiPaintSelectionGeometry;
510
+ readonly objects?: readonly XlsxUiPaintObjectGeometry[];
511
+ /**
512
+ * X5-U-017: resolved sparkline glyphs whose host cell falls in this window.
513
+ * Separate from `objects` because a sparkline is not a drawing anchor — it
514
+ * has no drawing part, no anchor range and no EMU offsets; it is a
515
+ * cell-sized picture of a value series, so it carries the series itself.
516
+ * Absent or empty on every workbook without an x14 sparkline family.
517
+ */
518
+ readonly sparklines?: readonly XlsxUiPaintSparklineGeometry[];
519
+ }
520
+ /**
521
+ * X5-U-017: one resolved sparkline, ready to paint. `rect` is the HOST CELL's
522
+ * rect in this window (no separate geometry projection). `series` is the
523
+ * `<xm:f>` source values in row-major order, with `null` for every
524
+ * non-numeric point (blank, text, boolean, error) — the gap Excel leaves in
525
+ * the glyph, which a consumer must not paint as a zero. `truncated` says the
526
+ * source range held more points than the runtime series bound.
527
+ */
528
+ export interface XlsxUiPaintSparklineGeometry {
529
+ readonly kind: "line" | "column" | "winloss";
530
+ readonly hostRange: XlsxCellRange;
531
+ readonly rect: XlsxUiPaintRect;
532
+ readonly series: readonly (number | null)[];
533
+ readonly truncated: boolean;
534
+ readonly precision: XlsxUiPaintGeometryPrecision;
535
+ }
536
+ export interface XlsxUiPaintObjectGeometry {
537
+ readonly sourcePart: string;
538
+ readonly objectKind: "chart" | "ole-object" | "image" | "shape" | "unknown";
539
+ readonly range?: XlsxCellRange;
540
+ readonly rects: readonly XlsxUiPaintRect[];
541
+ readonly exactRect?: XlsxUiPaintRect;
542
+ readonly precision: XlsxUiPaintGeometryPrecision;
543
+ /**
544
+ * BR-2/D4-R1 (bridge v18): verified media handle, present only on `image`
545
+ * anchors whose media part passed the import allowlist (declared content
546
+ * type AND magic-byte sniff) and SHA-256 verification.
547
+ */
548
+ readonly media?: XlsxUiMediaHandle;
549
+ /**
550
+ * D4-R2b (bridge v20): verified chart handle, present only on `chart`
551
+ * anchors whose chart part passed the `xl/charts/*.xml` path-confinement
552
+ * and XML-sanity gates. Chart XML resolves through the chart-bytes call
553
+ * for host-side preview synthesis; anchors without a handle keep the
554
+ * placeholder-chip presentation.
555
+ */
556
+ readonly chart?: XlsxUiChartHandle;
557
+ /**
558
+ * D4-R1b-3 (bridge v21; fill + frame insets v25): the picture's
559
+ * source-rect crop, fill inset, grouped frame and rotation/flip, present
560
+ * only on `image` anchors whose drawing XML carried a non-identity
561
+ * `a:srcRect`, `a:stretch/a:fillRect`, `a:xfrm` or enclosing `xdr:grpSp`
562
+ * geometry. Absent means "paint the whole source stretched to the anchor
563
+ * extent", the pre-D4-R1b-3 behaviour.
564
+ */
565
+ readonly transform?: XlsxUiDrawingTransform;
566
+ }
567
+ /**
568
+ * D4-R1b-3 picture transform (bridge v21; fill + frame insets v25), in
569
+ * painter-ready units — the OOXML thousandths-of-a-percent and
570
+ * 60000ths-of-a-degree forms are normalized on the Rust side of the bridge.
571
+ *
572
+ * Three boxes nest, each named by four edge insets as fractions of the box
573
+ * outside it (positive shrinks that edge inward, negative pushes it out):
574
+ *
575
+ * 1. The picture FRAME inside the anchor extent (`frame*Fraction`). Zero or
576
+ * absent for an ungrouped picture — its frame is the anchor. A picture
577
+ * inside `xdr:grpSp` gets its child frame here, with every enclosing
578
+ * group's rotation and flips already folded into `rotationDegrees` and
579
+ * the flips, and into where the frame sits.
580
+ * 2. The FILL rectangle inside the frame (`fill*Fraction`,
581
+ * `a:stretch/a:fillRect`): where the cropped source is stretched to.
582
+ * Positive insets leave a transparent margin; negative insets overflow
583
+ * the frame and are clipped to it (ECMA-376 20.1.8.30).
584
+ * 3. The CROP of the source image (`crop*Fraction`, `a:srcRect`): which
585
+ * source region is stretched into the fill rectangle. Positive edges hide
586
+ * source pixels; a NEGATIVE edge is an outward crop — the region reaches
587
+ * past the image, so the image lands inset inside the fill rectangle with
588
+ * transparent margin (ECMA-376 20.1.8.55). Opposite edges never sum to 1
589
+ * or more on any of the three boxes.
590
+ *
591
+ * `rotationDegrees` is clockwise about the FRAME's centre, and the flips
592
+ * mirror about the same centre BEFORE the rotation, as DrawingML specifies:
593
+ * the picture is mirrored in its own unrotated frame and the mirrored result
594
+ * is then turned. With `rotationDegrees: 90` and `flipHorizontal` the two
595
+ * orders differ by a full mirror, so an integrator reproducing this paint
596
+ * must compose flip-then-rotate. The fill and frame insets are omitted from
597
+ * the wire when zero.
598
+ */
599
+ export interface XlsxUiDrawingTransform {
600
+ readonly cropLeftFraction: number;
601
+ readonly cropTopFraction: number;
602
+ readonly cropRightFraction: number;
603
+ readonly cropBottomFraction: number;
604
+ readonly rotationDegrees: number;
605
+ readonly flipHorizontal: boolean;
606
+ readonly flipVertical: boolean;
607
+ readonly fillLeftFraction?: number;
608
+ readonly fillTopFraction?: number;
609
+ readonly fillRightFraction?: number;
610
+ readonly fillBottomFraction?: number;
611
+ readonly frameLeftFraction?: number;
612
+ readonly frameTopFraction?: number;
613
+ readonly frameRightFraction?: number;
614
+ readonly frameBottomFraction?: number;
615
+ }
616
+ /**
617
+ * BR-2/D4-R1 verified drawing-media handle (bridge v18). `mediaId` is the
618
+ * digest-addressed key (`media:sha256:<64-hex>`) the media-bytes call and
619
+ * the session media route resolve; bytes are digest-verified at serve time.
620
+ */
621
+ export interface XlsxUiMediaHandle {
622
+ readonly mediaId: string;
623
+ readonly contentType: string;
624
+ readonly sha256: string;
625
+ readonly byteLength: number;
626
+ readonly naturalWidthPx?: number;
627
+ readonly naturalHeightPx?: number;
628
+ }
629
+ /**
630
+ * D4-R2b verified drawing-chart handle (bridge v20). `chartId` is the
631
+ * digest-addressed key (`chart:sha256:<64-hex>`) the chart-bytes call and
632
+ * the session chart route resolve; the XML digest is recomputed at serve
633
+ * time. Readback-only and never canonical-hash input.
634
+ */
635
+ export interface XlsxUiChartHandle {
636
+ readonly chartId: string;
637
+ readonly sha256: string;
638
+ readonly byteLength: number;
639
+ }
640
+ export interface XlsxUiPaintRowGeometry {
641
+ readonly row: number;
642
+ readonly offsetPx: number;
643
+ readonly sizePx: number;
644
+ readonly hidden: boolean;
645
+ readonly precision: XlsxUiPaintGeometryPrecision;
646
+ }
647
+ export interface XlsxUiPaintColumnGeometry {
648
+ readonly column: number;
649
+ readonly offsetPx: number;
650
+ readonly sizePx: number;
651
+ readonly hidden: boolean;
652
+ readonly precision: XlsxUiPaintGeometryPrecision;
653
+ }
654
+ export interface XlsxUiPaintCellGeometry {
655
+ readonly address: XlsxCellAddress;
656
+ readonly rects: readonly XlsxUiPaintRect[];
657
+ readonly hidden: boolean;
658
+ readonly precision: XlsxUiPaintGeometryPrecision;
659
+ readonly mergeOwner?: XlsxCellAddress;
660
+ }
661
+ export interface XlsxUiPaintSelectionGeometry {
662
+ readonly hulls: readonly XlsxUiPaintSelectionHull[];
663
+ readonly fillHandleRect?: XlsxUiPaintRect;
664
+ readonly projection: "complete" | "clipped";
665
+ readonly precision: XlsxUiPaintGeometryPrecision;
666
+ }
667
+ export interface XlsxUiPaintSelectionHull {
668
+ readonly range: XlsxCellRange;
669
+ readonly rect: XlsxUiPaintRect;
670
+ }
671
+ export interface XlsxUiPaintRect {
672
+ readonly xPx: number;
673
+ readonly yPx: number;
674
+ readonly widthPx: number;
675
+ readonly heightPx: number;
676
+ readonly coordinateSpace: XlsxUiPaintCoordinateSpace;
677
+ readonly precision: XlsxUiPaintGeometryPrecision;
678
+ }
679
+ export type XlsxUiPaintCoordinateSpace = {
680
+ readonly kind: "sheet-units";
681
+ } | {
682
+ readonly kind: "pane-px";
683
+ readonly region: "top-left" | "top" | "left" | "body";
684
+ } | {
685
+ readonly kind: "viewport-px";
686
+ } | {
687
+ readonly kind: "canvas-layer-px";
688
+ } | {
689
+ readonly kind: "screen-px-diagnostic";
690
+ };
691
+ export type XlsxUiLayoutPrecision = "exact" | "within-tolerance" | "estimated" | "preserved" | "not-projected";
692
+ export type XlsxUiPaintGeometryPrecision = "exact" | "within-tolerance" | "estimated" | "unavailable";
693
+ export type XlsxUiOverlayLaneKind = "comments" | "issues" | "suggestions" | "validations" | "protected-ranges" | "charts-objects";
694
+ export type XlsxUiOverlaySourceLaneKind = XlsxUiOverlayLaneKind | "formula-precedents" | "formula-dependents" | "output-regions" | "tables" | "charts-objects" | "presence";
695
+ export interface XlsxUiOverlayLanesRequest {
696
+ readonly laneKinds?: readonly XlsxUiOverlayLaneKind[];
697
+ readonly workflowContext?: XlsxWorkflowContextInput;
698
+ readonly maxEntriesPerLane?: number;
699
+ readonly visibleByDefault?: boolean;
700
+ }
701
+ export interface XlsxUiOverlayLanesReadback {
702
+ readonly envelope: XlsxReadbackEnvelope;
703
+ readonly lanes: readonly XlsxUiOverlayLaneSnapshot[];
704
+ }
705
+ export interface XlsxUiOverlayLaneSnapshot {
706
+ readonly laneKind: XlsxUiOverlayLaneKind;
707
+ readonly snapshotId: string;
708
+ readonly status: "empty" | "complete" | "partial";
709
+ readonly revision: number;
710
+ readonly visible: boolean;
711
+ readonly visibilitySource: "workflow-policy" | "local-preference" | "authored-default";
712
+ readonly visibilityReason: string;
713
+ readonly entries: readonly XlsxUiOverlayLaneEntry[];
714
+ readonly sheetBuckets: readonly XlsxUiOverlaySheetBucket[];
715
+ readonly omittedEntryCount: number;
716
+ }
717
+ export interface XlsxUiOverlayLaneEntry {
718
+ readonly entryId: string;
719
+ readonly sourceLane: XlsxUiOverlaySourceLaneKind;
720
+ readonly status: "open" | "pending" | "resolved" | "informational";
721
+ readonly severity: "info" | "warning" | "blocking";
722
+ readonly anchor: {
723
+ readonly type: "workbook" | "sheet" | "cell" | "range" | "table" | "output-region" | "defined-name" | "preserve-only";
724
+ readonly id: string;
725
+ readonly sheetId?: string;
726
+ readonly range?: XlsxCellRange;
727
+ };
728
+ readonly visualizationClass: string;
729
+ readonly scopeId?: string;
730
+ readonly label: string;
731
+ /**
732
+ * X5-U-010a: the comment body. Present only on `comments`-lane entries
733
+ * (`visualizationClass: "comment-balloon"`); absent everywhere else.
734
+ *
735
+ * `commentText` and `commentAuthor` are USER CONTENT and travel the same
736
+ * lane as cell display text through the credential-redaction seam
737
+ * (`ui/react/src/redaction.ts`): never key-matched, never narrative-scrubbed.
738
+ *
739
+ * A legacy `xl/comments*.xml` note (`commentIsLegacyNote: true`) has no
740
+ * threading: it reports `commentReplyCount: 0` and `commentResolved: false`
741
+ * — the unresolved default, not an authored resolution.
742
+ */
743
+ readonly commentAuthor?: string;
744
+ readonly commentText?: string;
745
+ readonly commentResolved?: boolean;
746
+ readonly commentReplyCount?: number;
747
+ readonly commentIsLegacyNote?: boolean;
748
+ /**
749
+ * X5-U-010b (bridge v33): the replies in thread order and the root's
750
+ * Excel-shaped `dT`. A note has an empty list and no timestamp. Reply
751
+ * `author` / `text` are USER CONTENT like the root's.
752
+ */
753
+ readonly commentReplies?: readonly XlsxUiOverlayCommentReply[];
754
+ readonly commentTimestamp?: string;
755
+ }
756
+ /** X5-U-010b: one reply of a threaded comment on the overlay wire. */
757
+ export interface XlsxUiOverlayCommentReply {
758
+ readonly author: string;
759
+ readonly text: string;
760
+ readonly timestamp?: string;
761
+ }
762
+ export interface XlsxUiOverlaySheetBucket {
763
+ readonly sheetId: string;
764
+ readonly entryIds: readonly string[];
765
+ }