@beyondwork/xlsx-substrate-bindings 0.0.0-stage → 0.1.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 (50) hide show
  1. package/LICENSE.md +31 -0
  2. package/dist/ai/index.d.ts +2 -0
  3. package/dist/ai/index.js +1 -0
  4. package/dist/ai/types.d.ts +320 -0
  5. package/dist/ai/types.js +23 -0
  6. package/dist/index.d.ts +46 -0
  7. package/dist/index.js +72 -0
  8. package/dist/runtime/index.d.ts +2 -0
  9. package/dist/runtime/index.js +1 -0
  10. package/dist/runtime/types.d.ts +1379 -0
  11. package/dist/runtime/types.js +15 -0
  12. package/dist/shared.d.ts +69 -0
  13. package/dist/shared.js +1 -0
  14. package/dist/ui/index.d.ts +2 -0
  15. package/dist/ui/index.js +1 -0
  16. package/dist/ui/types.d.ts +765 -0
  17. package/dist/ui/types.js +12 -0
  18. package/dist/wasm/bridge-contract.d.ts +541 -0
  19. package/dist/wasm/bridge-contract.js +862 -0
  20. package/dist/wasm/chart-test-fixture.d.ts +19 -0
  21. package/dist/wasm/chart-test-fixture.js +42 -0
  22. package/dist/wasm/index.d.ts +9 -0
  23. package/dist/wasm/index.js +67 -0
  24. package/dist/wasm/media-test-fixture.d.ts +44 -0
  25. package/dist/wasm/media-test-fixture.js +160 -0
  26. package/dist/wasm/session-router.d.ts +98 -0
  27. package/dist/wasm/session-router.js +184 -0
  28. package/dist/wasm/sheet-window-binary-reference.d.ts +9 -0
  29. package/dist/wasm/sheet-window-binary-reference.js +308 -0
  30. package/dist/wasm/sheet-window-binary.d.ts +279 -0
  31. package/dist/wasm/sheet-window-binary.js +636 -0
  32. package/dist/wasm/volatile-test-fixture.d.ts +7 -0
  33. package/dist/wasm/volatile-test-fixture.js +35 -0
  34. package/dist/wasm/web.d.ts +59 -0
  35. package/dist/wasm/web.js +60 -0
  36. package/generated/wasm/package.json +3 -0
  37. package/generated/wasm/sheet-window-binary.mjs +482 -0
  38. package/generated/wasm/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +45 -0
  39. package/generated/wasm/xlsx_substrate_wasm.d.ts +336 -0
  40. package/generated/wasm/xlsx_substrate_wasm.js +2108 -0
  41. package/generated/wasm/xlsx_substrate_wasm_bg.wasm +0 -0
  42. package/generated/wasm/xlsx_substrate_wasm_bg.wasm.d.ts +105 -0
  43. package/generated/wasm-web/package.json +3 -0
  44. package/generated/wasm-web/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +42 -0
  45. package/generated/wasm-web/xlsx_substrate_wasm.d.ts +466 -0
  46. package/generated/wasm-web/xlsx_substrate_wasm.js +2109 -0
  47. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
  48. package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +105 -0
  49. package/package.json +41 -3
  50. package/README.md +0 -3
@@ -0,0 +1,279 @@
1
+ import type { XlsxReadbackEnvelope, XlsxScopeHandle } from "../shared.ts";
2
+ import type { XlsxUiAccessibilitySummary, XlsxUiBlocker, XlsxUiOperationCapabilityRecord, XlsxUiPaintObjectGeometry, XlsxUiPaintSelectionGeometry, XlsxUiPaintSparklineGeometry, XlsxUiSelectionReadback, XlsxUiSheetExtent, XlsxUiSheetWindowOrigin, XlsxUiSheetWindowCacheReadback, XlsxUiCellHyperlink, XlsxUiSheetWindowCoordinatePosture, XlsxUiSheetWindowDataValidation, XlsxUiSheetWindowMergedRange, XlsxUiSheetWindowPanePartition, XlsxUiSheetWindowReadback, XlsxUiViewportReadback } from "../ui/index.ts";
3
+ /**
4
+ * T5 — Binary Sheet-Window Snapshot v1 (`xlsx-sheet-window-binary/1`) decoder.
5
+ *
6
+ * The wasm export `readRuntimeSessionSheetWindowBinary` returns a hybrid
7
+ * envelope `{ schemaId, bytes, rest }`: `bytes` carries the four bulk arrays
8
+ * (`rows`, `columns`, `cells`, `paintGeometry.rows/columns/cells+rects`) in a
9
+ * flat little-endian layout; `rest` is a small JSON DTO with everything O(1)-
10
+ * sized, rare, or deeply nested. This replaces the per-call
11
+ * `serde_wasm_bindgen::to_value` of the full window DTO (~3.5ms of the
12
+ * scroll-step readback; bench BR-6, test/perf/xlsx-interaction-latency.bench.ts).
13
+ *
14
+ * ## Copy-out-once posture (wasm memory-growth footgun)
15
+ *
16
+ * Views into `WebAssembly.Memory` are invalidated by memory growth — any
17
+ * allocation-capable call (including the decode itself, via JS-heap pressure
18
+ * triggering wasm-side reentry in future designs) can leave a `Uint8Array`
19
+ * view over detached garbage. The decoder therefore REQUIRES that
20
+ * `envelope.bytes` is already detached from live wasm memory:
21
+ *
22
+ * - wasm-bindgen `Vec<u8>` returns perform exactly one memcpy out of linear
23
+ * memory into a fresh JS-heap `Uint8Array` in generated glue — that IS the
24
+ * copy-out-once, with no window in which growth can invalidate a view;
25
+ * - through the T2 worker pool the envelope arrives structured-cloned — the
26
+ * `ArrayBuffer` is a fresh copy on the receiving side.
27
+ *
28
+ * A single memcpy of a ~100-400KB snapshot is tens of microseconds —
29
+ * predictable and orders cheaper than the per-field serde it replaces. If a
30
+ * future ptr+len fast path lands, callers must
31
+ * `Uint8Array.prototype.slice()` BEFORE handing bytes to this decoder. As a
32
+ * defensive backstop the decoder copies the region out itself before
33
+ * touching it when `bytes` could alias growable memory: a view over a larger
34
+ * buffer (the signature of a raw view into linear memory), a full-length
35
+ * view over a resizable `ArrayBuffer`, or any view whose backing store is
36
+ * not a plain fixed `ArrayBuffer` (growable or concurrently mutable shared
37
+ * memory).
38
+ *
39
+ * ## Laziness and output shape
40
+ *
41
+ * The decoded object exposes `rows`, `columns`, `cells`, and `paintGeometry`
42
+ * as memoized section-level getters: nothing decodes until first access, and
43
+ * each section decodes wholesale into plain objects **field-identical to the
44
+ * JSON `XlsxUiSheetWindowReadback`** — including serde's key-presence
45
+ * semantics (ground truth probed against the live wasm build):
46
+ *
47
+ * - `Option` fields WITHOUT `skip_serializing_if` are present with value
48
+ * `undefined` (e.g. `formulaText`, `mergeOwner`);
49
+ * - fields WITH `skip_serializing_if` are ABSENT when skipped (`fillColor`,
50
+ * `wrapText`, `borderTop`, ... only exist when set/true);
51
+ * - required arrays (`blockers`, `postureMarkers`, `paintGeometry.objects`)
52
+ * are always present.
53
+ *
54
+ * All `rest` fields pass through unchanged (minus the transport-internal
55
+ * fields enumerated in `decodeSheetWindowBinary`), so readback.ts,
56
+ * tile-scheduler.ts, and the workbook painter consume the decoded object
57
+ * with zero changes. v2 follow-up (named, not in scope): zero-copy-into-paint
58
+ * — teach the canvas painter to read PAINT_CELLS/RECTS typed arrays directly
59
+ * per tile range, skipping object materialization.
60
+ *
61
+ * ## Layout deviations vs the T5 contract draft (frozen here, golden-guarded)
62
+ *
63
+ * The contract's §1 table has three internal inconsistencies this
64
+ * implementation resolves; any further change requires re-agreeing the layout
65
+ * with the Rust encoder and bumping the header version:
66
+ *
67
+ * 1. PAINT_ROWS/PAINT_COLS are 32 B/record, not the stated 24 B (the listed
68
+ * fields sum to 28 and the stated layout misaligns the f64 pair; 32 keeps
69
+ * 8-byte alignment). 32 is the ONLY accepted stride: no encoder emits the
70
+ * contract-draft 28 B packed layout, and tolerating one with a guessed
71
+ * field order would silently decode garbage f64 geometry instead of
72
+ * failing the stride assert.
73
+ * 2. RECTS are 48 B/record, not 32: `UiPaintRectDto` carries per-rect
74
+ * `coordinateSpace` (tagged kind + optional pane region) and `precision`,
75
+ * which the contract's bare x/y/w/h pool cannot represent. Encoded as
76
+ * three interned string ids + pad after the four f64s.
77
+ * 3. `postureMarkers` moved OUT of `rest.rareCells` into an interned
78
+ * string-table id on the cell record (US-joined list, `\x1f` separator):
79
+ * measured prevalence is ~99% of cells (`["empty"]`, `["formula"]`,
80
+ * `["merge-owner"]`, ...) from a tiny vocabulary — the contract's
81
+ * "almost always empty" premise holds for `selectionHandle`/`blockers`
82
+ * (which stay in `rest.rareCells`) but not for markers, and routing ~475
83
+ * marker arrays through JSON `rest` would rebuild the serde cost the
84
+ * binary path removes. Cell records are therefore 96 B, not 88.
85
+ */
86
+ export declare const SHEET_WINDOW_BINARY_SCHEMA_ID = "xlsx-sheet-window-binary/1";
87
+ /** "XSW1" read as a little-endian u32. */
88
+ export declare const SHEET_WINDOW_BINARY_MAGIC = 827806552;
89
+ export declare const SHEET_WINDOW_BINARY_VERSION = 1;
90
+ export declare const SHEET_WINDOW_BINARY_HEADER_BYTES = 32;
91
+ export declare const SHEET_WINDOW_BINARY_SECTION_ENTRY_BYTES = 16;
92
+ export declare const SHEET_WINDOW_SECTION_ROWS = 1;
93
+ export declare const SHEET_WINDOW_SECTION_COLS = 2;
94
+ export declare const SHEET_WINDOW_SECTION_CELLS = 3;
95
+ export declare const SHEET_WINDOW_SECTION_PAINT_ROWS = 4;
96
+ export declare const SHEET_WINDOW_SECTION_PAINT_COLS = 5;
97
+ export declare const SHEET_WINDOW_SECTION_RECTS = 6;
98
+ export declare const SHEET_WINDOW_SECTION_PAINT_CELLS = 7;
99
+ export declare const SHEET_WINDOW_SECTION_STRTAB = 8;
100
+ export declare const SHEET_WINDOW_SECTION_STRBLOB = 9;
101
+ export declare const SHEET_WINDOW_LINE_RECORD_BYTES = 24;
102
+ export declare const SHEET_WINDOW_CELL_RECORD_BYTES = 96;
103
+ export declare const SHEET_WINDOW_PAINT_LINE_RECORD_BYTES = 32;
104
+ export declare const SHEET_WINDOW_RECT_RECORD_BYTES = 48;
105
+ export declare const SHEET_WINDOW_PAINT_CELL_RECORD_BYTES = 32;
106
+ export declare const SHEET_WINDOW_STRTAB_ENTRY_BYTES = 8;
107
+ /** Sentinel for absent u32 indices (`mergedRangeIdx`, `rareIdx`, `numFmtId`, merge-owner coords). */
108
+ export declare const SHEET_WINDOW_U32_NONE = 4294967295;
109
+ /** Sentinel for absent `outlineLevel`. */
110
+ export declare const SHEET_WINDOW_OUTLINE_NONE = 255;
111
+ /** Separator for the interned `postureMarkers` list (`\u001f` unit separator, cannot appear in marker tokens). */
112
+ export declare const SHEET_WINDOW_MARKER_SEPARATOR = "\u001F";
113
+ /** Header flag bit0: binary paint-geometry sections are present. */
114
+ export declare const SHEET_WINDOW_FLAG_PAINT_GEOMETRY = 1;
115
+ /** Per-cell rare payloads referenced by `rareIdx` from cell records. */
116
+ export interface XlsxSheetWindowRareCell {
117
+ readonly selectionHandle?: XlsxScopeHandle;
118
+ readonly blockers?: readonly XlsxUiBlocker[];
119
+ /**
120
+ * Not produced by the v1 encoder (markers are interned in the string
121
+ * table; see module docblock deviation 3) but honored when present so a
122
+ * contract-literal encoder still round-trips.
123
+ */
124
+ readonly postureMarkers?: readonly string[];
125
+ /**
126
+ * X5-U-009 (bridge v31): a linked cell's readback. Rare per window and
127
+ * nested, so it rides the side table instead of widening the frozen
128
+ * 96-byte record.
129
+ */
130
+ readonly hyperlink?: XlsxUiCellHyperlink;
131
+ }
132
+ /**
133
+ * The JSON half of the hybrid envelope. Everything O(1)-sized, rare, or
134
+ * deeply nested from `UiSheetWindowReadbackDto` — enumerated by the T5
135
+ * contract. `envelope`/`cache` ride here so cached binary bytes never need
136
+ * per-hit patching.
137
+ */
138
+ export interface XlsxSheetWindowBinaryRest {
139
+ readonly envelope: XlsxReadbackEnvelope;
140
+ readonly status: "accepted" | "refused";
141
+ readonly workbookId: string;
142
+ /**
143
+ * Session identity at emission — opaque pass-through of the readback's
144
+ * `canonicalHash`; equality/advancement only (see
145
+ * `XlsxRuntimeSessionMutationReceipt.canonicalHash`).
146
+ */
147
+ readonly canonicalHash: string;
148
+ readonly activeSheetId?: string;
149
+ readonly sheetName?: string;
150
+ readonly viewport: XlsxUiViewportReadback;
151
+ readonly coordinatePosture: XlsxUiSheetWindowCoordinatePosture;
152
+ /**
153
+ * X5-U-018: right-to-left sheet. The paint geometry column offsets are
154
+ * already mirrored (column A on the right); the surface uses this to set
155
+ * `dir="rtl"` for text and scroll direction.
156
+ */
157
+ readonly rightToLeft: boolean;
158
+ /**
159
+ * UX-P-104: the sheet's used-range bounds + exact pixel extent. Same
160
+ * reasoning as `rightToLeft` — an O(1) scalar block, not a bulk array, so
161
+ * it rides the JSON half and the frozen packed layout is unchanged. The
162
+ * decoder spreads it back onto the readback; absent on an empty sheet.
163
+ */
164
+ readonly sheetExtent?: XlsxUiSheetExtent;
165
+ /**
166
+ * UX-P-104 rework: where the loaded window sits on that extent. Two
167
+ * scalars, same JSON-half reasoning as `sheetExtent`.
168
+ */
169
+ readonly sheetWindowOrigin?: XlsxUiSheetWindowOrigin;
170
+ readonly cache?: XlsxUiSheetWindowCacheReadback;
171
+ readonly mergedRanges: readonly XlsxUiSheetWindowMergedRange[];
172
+ readonly panePartitions: readonly XlsxUiSheetWindowPanePartition[];
173
+ /** X5-U-011: typed rules ride the JSON half (rare, variable length). */
174
+ readonly dataValidations?: readonly XlsxUiSheetWindowDataValidation[];
175
+ readonly activeSelection?: XlsxUiSelectionReadback;
176
+ readonly accessibility?: XlsxUiAccessibilitySummary;
177
+ readonly capabilities: readonly XlsxUiOperationCapabilityRecord[];
178
+ readonly blockers: readonly XlsxUiBlocker[];
179
+ /** Mirrors header flag bit0; the flag is authoritative for the bytes. */
180
+ readonly paintGeometryPresent: boolean;
181
+ /** `paintGeometry.activeSelection` (nested + rare — stays JSON in v1). */
182
+ readonly paintGeometryActiveSelection?: XlsxUiPaintSelectionGeometry;
183
+ /** `paintGeometry.objects` (media/chart handles — nested, rare). */
184
+ readonly paintGeometryObjects?: readonly XlsxUiPaintObjectGeometry[];
185
+ /**
186
+ * X5-U-017: `paintGeometry.sparklines`. Rides the JSON half, never a fixed
187
+ * record — a sparkline carries a VARIABLE-LENGTH value series, which no
188
+ * fixed-stride record can hold, and sparklines are rare enough per window
189
+ * that widening the frozen packed layout for them would be a wire cost
190
+ * every ordinary workbook pays.
191
+ */
192
+ readonly paintGeometrySparklines?: readonly XlsxUiPaintSparklineGeometry[];
193
+ /**
194
+ * Nested-variant carrier a contract-literal encoder may use instead of the
195
+ * two flat fields above; the decoder accepts either spelling.
196
+ */
197
+ readonly paintGeometry?: {
198
+ readonly activeSelection?: XlsxUiPaintSelectionGeometry;
199
+ readonly objects?: readonly XlsxUiPaintObjectGeometry[];
200
+ readonly sparklines?: readonly XlsxUiPaintSparklineGeometry[];
201
+ };
202
+ readonly rareCells: readonly XlsxSheetWindowRareCell[];
203
+ /** Miss-only rust-side encode cost diagnostic (`performance.now` when the global carries it). */
204
+ readonly encodeMs?: number;
205
+ }
206
+ /** The hybrid wire unit returned by `readRuntimeSessionSheetWindowBinary`. */
207
+ export interface XlsxSheetWindowBinaryEnvelope {
208
+ readonly schemaId: string;
209
+ readonly bytes: Uint8Array;
210
+ readonly rest: XlsxSheetWindowBinaryRest;
211
+ }
212
+ /**
213
+ * Options for {@link decodeSheetWindowBinary}.
214
+ */
215
+ export interface SheetWindowBinaryDecodeOptions {
216
+ /**
217
+ * Invoked when one of the LAZY section getters (`rows`/`columns`/`cells`/
218
+ * `paintGeometry`) fails to decode at first consumer access — stride
219
+ * mismatches, out-of-range string ids, blob escapes, missing
220
+ * `rareCells`/`mergedRanges` references. Return a substitute
221
+ * `XlsxUiSheetWindowReadback` (typically a fresh JSON readback for the same
222
+ * request) and the failing section is served from it instead of throwing;
223
+ * return `undefined` to rethrow the original decode error. Eager
224
+ * header/section-table/STRTAB validation errors still throw from
225
+ * `decodeSheetWindowBinary` itself and are NOT routed here.
226
+ */
227
+ readonly onSectionDecodeError?: (error: unknown) => XlsxUiSheetWindowReadback | undefined;
228
+ }
229
+ /**
230
+ * Decode the hybrid binary envelope into the exact JSON readback shape.
231
+ *
232
+ * `rows`/`columns`/`cells`/`paintGeometry` are memoized lazy getters —
233
+ * consumers that only touch `paintGeometry` (the tile scheduler) never pay
234
+ * for cell decoding, and vice versa. Everything else spreads through from
235
+ * `rest` unchanged (transport-internal fields are stripped). Because those
236
+ * getters run at consumer access time, callers that need the documented
237
+ * permanent-JSON fallback must pass `onSectionDecodeError` (the bridge does,
238
+ * via {@link createSheetWindowDecodedReader}) — a bare try/catch around this
239
+ * call only covers the eager header validation.
240
+ */
241
+ export declare function decodeSheetWindowBinary(env: XlsxSheetWindowBinaryEnvelope, options?: SheetWindowBinaryDecodeOptions): XlsxUiSheetWindowReadback;
242
+ /**
243
+ * Dependencies for {@link createSheetWindowDecodedReader}. Generic over the
244
+ * read-call argument tuple so the bridge threads its own
245
+ * `(handleId, viewportHint, activeHandle?, workflowContext?)` signature
246
+ * without this module importing runtime types.
247
+ */
248
+ export interface SheetWindowDecodedReaderDeps<Args extends readonly unknown[]> {
249
+ /** Binary export fetch; `undefined` when the wasm build lacks the T5 export. */
250
+ readonly readBinary?: (...args: Args) => XlsxSheetWindowBinaryEnvelope;
251
+ /** JSON export fetch — the permanent fallback lane. */
252
+ readonly readJson: (...args: Args) => XlsxUiSheetWindowReadback;
253
+ /** Warn hook (defaults to `console.warn`); invoked once, when the latch flips. */
254
+ readonly warn?: (message: string, error: unknown) => void;
255
+ }
256
+ /**
257
+ * Build the `readSheetWindowDecoded` seam with the permanent-JSON-fallback
258
+ * latch. Covers BOTH failure surfaces of the binary lane:
259
+ *
260
+ * - EAGER decode errors (header/section-table/STRTAB validation) throw from
261
+ * `decodeSheetWindowBinary` synchronously — caught here, latch flips, and
262
+ * the SAME call returns the JSON readback;
263
+ * - LAZY section decode errors (stride mismatch, out-of-range string id,
264
+ * blob escape, missing rareCells/mergedRanges reference in
265
+ * rows/columns/cells/paintGeometry) surface at first CONSUMER access,
266
+ * possibly frames later — routed back through `onSectionDecodeError`,
267
+ * which flips the latch for every subsequent call AND substitutes the
268
+ * failing section from a fresh JSON readback for the same request so the
269
+ * in-flight frame degrades instead of throwing. The substituted section
270
+ * may reflect a marginally newer document state than the rest of the
271
+ * decoded object if the session mutated between decode and access — an
272
+ * accepted one-frame degradation on an already-failing lane (all later
273
+ * frames are pure JSON). If even the JSON re-read fails (e.g. the session
274
+ * was disposed), the original decode error rethrows.
275
+ *
276
+ * The latch is per-reader (= per bridge instance), mirroring the previous
277
+ * `binarySheetWindowDisabled` flag.
278
+ */
279
+ export declare function createSheetWindowDecodedReader<Args extends readonly unknown[]>(deps: SheetWindowDecodedReaderDeps<Args>): (...args: Args) => XlsxUiSheetWindowReadback;