@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.
- package/LICENSE.md +31 -0
- package/README.md +135 -2
- package/dist/ai/agent-metadata.d.ts +363 -0
- package/dist/ai/agent-metadata.js +227 -0
- package/dist/ai/index.d.ts +6 -0
- package/dist/ai/index.js +7 -0
- package/dist/ai/mutation-bridge.d.ts +82 -0
- package/dist/ai/mutation-bridge.js +179 -0
- package/dist/ai/types.d.ts +765 -0
- package/dist/ai/types.js +23 -0
- package/dist/index.d.ts +50 -0
- package/dist/index.js +90 -0
- package/dist/runtime/index.d.ts +2 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/types.d.ts +1435 -0
- package/dist/runtime/types.js +15 -0
- package/dist/shared.d.ts +69 -0
- package/dist/shared.js +1 -0
- package/dist/ui/index.d.ts +2 -0
- package/dist/ui/index.js +1 -0
- package/dist/ui/types.d.ts +765 -0
- package/dist/ui/types.js +12 -0
- package/dist/wasm/ai-session-bridge.d.ts +97 -0
- package/dist/wasm/ai-session-bridge.js +154 -0
- package/dist/wasm/bridge-contract.d.ts +643 -0
- package/dist/wasm/bridge-contract.js +1001 -0
- package/dist/wasm/index.d.ts +50 -0
- package/dist/wasm/index.js +297 -0
- package/dist/wasm/memory-budget.d.ts +77 -0
- package/dist/wasm/memory-budget.js +532 -0
- package/dist/wasm/runtime-guard.d.ts +141 -0
- package/dist/wasm/runtime-guard.js +373 -0
- package/dist/wasm/session-router.d.ts +98 -0
- package/dist/wasm/session-router.js +184 -0
- package/dist/wasm/sheet-window-binary-reference.d.ts +9 -0
- package/dist/wasm/sheet-window-binary-reference.js +308 -0
- package/dist/wasm/sheet-window-binary.d.ts +279 -0
- package/dist/wasm/sheet-window-binary.js +636 -0
- package/dist/wasm/web.d.ts +72 -0
- package/dist/wasm/web.js +142 -0
- package/generated/wasm-web/package.json +3 -0
- package/generated/wasm-web/snippets/ironcalc_base-89b4f49381e1e289/inline0.js +42 -0
- package/generated/wasm-web/xlsx_substrate_wasm.d.ts +532 -0
- package/generated/wasm-web/xlsx_substrate_wasm.js +2493 -0
- package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
- package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm.d.ts +120 -0
- package/package.json +55 -3
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
import { SHEET_WINDOW_BINARY_HEADER_BYTES, SHEET_WINDOW_BINARY_MAGIC, SHEET_WINDOW_BINARY_SCHEMA_ID, SHEET_WINDOW_BINARY_SECTION_ENTRY_BYTES, SHEET_WINDOW_BINARY_VERSION, SHEET_WINDOW_CELL_RECORD_BYTES, SHEET_WINDOW_FLAG_PAINT_GEOMETRY, SHEET_WINDOW_LINE_RECORD_BYTES, SHEET_WINDOW_MARKER_SEPARATOR, SHEET_WINDOW_OUTLINE_NONE, SHEET_WINDOW_PAINT_CELL_RECORD_BYTES, SHEET_WINDOW_PAINT_LINE_RECORD_BYTES, SHEET_WINDOW_RECT_RECORD_BYTES, SHEET_WINDOW_SECTION_CELLS, SHEET_WINDOW_SECTION_COLS, SHEET_WINDOW_SECTION_PAINT_CELLS, SHEET_WINDOW_SECTION_PAINT_COLS, SHEET_WINDOW_SECTION_PAINT_ROWS, SHEET_WINDOW_SECTION_RECTS, SHEET_WINDOW_SECTION_ROWS, SHEET_WINDOW_SECTION_STRBLOB, SHEET_WINDOW_SECTION_STRTAB, SHEET_WINDOW_STRTAB_ENTRY_BYTES, SHEET_WINDOW_U32_NONE } from "./sheet-window-binary.js";
|
|
2
|
+
/**
|
|
3
|
+
* TS REFERENCE ENCODER for the `xlsx-sheet-window-binary/1` layout.
|
|
4
|
+
*
|
|
5
|
+
* Test/bench support only — production encoding is the Rust
|
|
6
|
+
* `encode_sheet_window_binary` in crates/sheets-wasm (the wasm export owns
|
|
7
|
+
* the hot path). This module exists so that:
|
|
8
|
+
*
|
|
9
|
+
* 1. the decoder is provable TODAY against live JSON readbacks (encode the
|
|
10
|
+
* JSON readback -> decode -> deepStrictEqual), independent of the Rust
|
|
11
|
+
* encoder landing;
|
|
12
|
+
* 2. the golden-bytes fixture freezes the byte layout — any layout drift on
|
|
13
|
+
* either side breaks the golden and forces re-agreeing the layout spec +
|
|
14
|
+
* a header version bump;
|
|
15
|
+
* 3. the bench can measure the JS decode lane before the wasm export exists.
|
|
16
|
+
*
|
|
17
|
+
* The input is the exact object shape the JSON path produces, so encoding is
|
|
18
|
+
* a structural transcription; see sheet-window-binary.ts for the layout and
|
|
19
|
+
* the documented deviations from the T5 contract draft.
|
|
20
|
+
*/
|
|
21
|
+
class StringInterner {
|
|
22
|
+
ids = new Map();
|
|
23
|
+
entries = [""]; // entry 0 reserved (absent)
|
|
24
|
+
intern(value) {
|
|
25
|
+
if (value === undefined) {
|
|
26
|
+
return 0;
|
|
27
|
+
}
|
|
28
|
+
const existing = this.ids.get(value);
|
|
29
|
+
if (existing !== undefined) {
|
|
30
|
+
return existing;
|
|
31
|
+
}
|
|
32
|
+
const id = this.entries.length;
|
|
33
|
+
this.entries.push(value);
|
|
34
|
+
this.ids.set(value, id);
|
|
35
|
+
return id;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function align8(value) {
|
|
39
|
+
return (value + 7) & ~7;
|
|
40
|
+
}
|
|
41
|
+
function rangeKey(range) {
|
|
42
|
+
return `${range.start.row}:${range.start.column}:${range.end.row}:${range.end.column}`;
|
|
43
|
+
}
|
|
44
|
+
function encodeLineSection(lines, lineField, metricField, customField, interner) {
|
|
45
|
+
const bytes = new Uint8Array(lines.length * SHEET_WINDOW_LINE_RECORD_BYTES);
|
|
46
|
+
const view = new DataView(bytes.buffer);
|
|
47
|
+
lines.forEach((line, i) => {
|
|
48
|
+
const o = i * SHEET_WINDOW_LINE_RECORD_BYTES;
|
|
49
|
+
view.setUint32(o, line[lineField], true);
|
|
50
|
+
view.setUint32(o + 4, interner.intern(line[metricField]), true);
|
|
51
|
+
view.setUint32(o + 8, interner.intern(line.precision), true);
|
|
52
|
+
view.setUint32(o + 12, interner.intern(line.hiddenPosture ?? undefined), true);
|
|
53
|
+
let flags = 0;
|
|
54
|
+
if (line.hidden)
|
|
55
|
+
flags |= 0x01;
|
|
56
|
+
if (line[customField])
|
|
57
|
+
flags |= 0x02;
|
|
58
|
+
if (line.collapsed)
|
|
59
|
+
flags |= 0x04;
|
|
60
|
+
view.setUint8(o + 16, flags);
|
|
61
|
+
const outline = line.outlineLevel;
|
|
62
|
+
view.setUint8(o + 17, outline === undefined || outline === null ? SHEET_WINDOW_OUTLINE_NONE : outline);
|
|
63
|
+
});
|
|
64
|
+
return bytes;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Encode a JSON sheet-window readback into the hybrid binary envelope.
|
|
68
|
+
* Throws when the readback holds structure the v1 layout cannot represent
|
|
69
|
+
* (which would indicate the layout spec needs re-agreement, not a silent
|
|
70
|
+
* widening here).
|
|
71
|
+
*/
|
|
72
|
+
export function encodeSheetWindowBinaryReference(readback) {
|
|
73
|
+
const interner = new StringInterner();
|
|
74
|
+
const rareCells = [];
|
|
75
|
+
const mergedIndexByKey = new Map();
|
|
76
|
+
readback.mergedRanges.forEach((merged, index) => {
|
|
77
|
+
mergedIndexByKey.set(rangeKey(merged.sourceRange), index);
|
|
78
|
+
});
|
|
79
|
+
const cellBytes = new Uint8Array(readback.cells.length * SHEET_WINDOW_CELL_RECORD_BYTES);
|
|
80
|
+
const cellView = new DataView(cellBytes.buffer);
|
|
81
|
+
readback.cells.forEach((cell, i) => {
|
|
82
|
+
const o = i * SHEET_WINDOW_CELL_RECORD_BYTES;
|
|
83
|
+
cellView.setUint32(o, cell.address.row, true);
|
|
84
|
+
cellView.setUint32(o + 4, cell.address.column, true);
|
|
85
|
+
const strIds = [
|
|
86
|
+
cell.cellId,
|
|
87
|
+
cell.displayText,
|
|
88
|
+
cell.valueKind,
|
|
89
|
+
cell.formulaText,
|
|
90
|
+
cell.displayFingerprint,
|
|
91
|
+
cell.styleRef,
|
|
92
|
+
cell.displayFormatPosture,
|
|
93
|
+
cell.formatCode,
|
|
94
|
+
cell.fillColor,
|
|
95
|
+
cell.fontColor,
|
|
96
|
+
cell.fontName,
|
|
97
|
+
cell.fontSizePoints,
|
|
98
|
+
cell.displayTextColor,
|
|
99
|
+
cell.horizontalAlignment,
|
|
100
|
+
cell.mergeRole,
|
|
101
|
+
cell.editability
|
|
102
|
+
];
|
|
103
|
+
strIds.forEach((value, slot) => {
|
|
104
|
+
cellView.setUint32(o + 8 + slot * 4, interner.intern(value), true);
|
|
105
|
+
});
|
|
106
|
+
cellView.setUint32(o + 72, cell.numFmtId === undefined ? SHEET_WINDOW_U32_NONE : cell.numFmtId, true);
|
|
107
|
+
let flags = 0;
|
|
108
|
+
if (cell.bold)
|
|
109
|
+
flags |= 0x0001;
|
|
110
|
+
if (cell.italic)
|
|
111
|
+
flags |= 0x0002;
|
|
112
|
+
if (cell.underline)
|
|
113
|
+
flags |= 0x0004;
|
|
114
|
+
if (cell.wrapText)
|
|
115
|
+
flags |= 0x0008;
|
|
116
|
+
if (cell.borderTop)
|
|
117
|
+
flags |= 0x0010;
|
|
118
|
+
if (cell.borderRight)
|
|
119
|
+
flags |= 0x0020;
|
|
120
|
+
if (cell.borderBottom)
|
|
121
|
+
flags |= 0x0040;
|
|
122
|
+
if (cell.borderLeft)
|
|
123
|
+
flags |= 0x0080;
|
|
124
|
+
// X5-U-008 (ii): two spare bits (8-9) carry vertical alignment.
|
|
125
|
+
if (cell.verticalAlignment === "top")
|
|
126
|
+
flags |= 0x0100;
|
|
127
|
+
else if (cell.verticalAlignment === "middle")
|
|
128
|
+
flags |= 0x0200;
|
|
129
|
+
else if (cell.verticalAlignment === "bottom")
|
|
130
|
+
flags |= 0x0300;
|
|
131
|
+
cellView.setUint16(o + 76, flags, true);
|
|
132
|
+
let mergedIdx = SHEET_WINDOW_U32_NONE;
|
|
133
|
+
if (cell.mergeRole !== "unmerged") {
|
|
134
|
+
if (!cell.mergeRange || !cell.mergeOwner) {
|
|
135
|
+
throw new Error(`sheet-window reference encoder: merged cell ${i} lacks mergeRange/mergeOwner`);
|
|
136
|
+
}
|
|
137
|
+
const found = mergedIndexByKey.get(rangeKey(cell.mergeRange));
|
|
138
|
+
if (found === undefined) {
|
|
139
|
+
throw new Error(`sheet-window reference encoder: merged cell ${i} range not present in mergedRanges — layout re-agreement needed`);
|
|
140
|
+
}
|
|
141
|
+
mergedIdx = found;
|
|
142
|
+
}
|
|
143
|
+
cellView.setUint32(o + 80, mergedIdx, true);
|
|
144
|
+
const hasRare = cell.selectionHandle !== undefined || cell.blockers.length > 0 || cell.hyperlink !== undefined;
|
|
145
|
+
let rareIdx = SHEET_WINDOW_U32_NONE;
|
|
146
|
+
if (hasRare) {
|
|
147
|
+
rareIdx = rareCells.length;
|
|
148
|
+
rareCells.push({
|
|
149
|
+
...(cell.selectionHandle !== undefined ? { selectionHandle: cell.selectionHandle } : {}),
|
|
150
|
+
...(cell.blockers.length > 0 ? { blockers: cell.blockers } : {}),
|
|
151
|
+
// X5-U-009 (bridge v31): the link rides the side table.
|
|
152
|
+
...(cell.hyperlink !== undefined ? { hyperlink: cell.hyperlink } : {})
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
cellView.setUint32(o + 84, rareIdx, true);
|
|
156
|
+
const markers = cell.postureMarkers;
|
|
157
|
+
if (markers.some((marker) => marker.includes(SHEET_WINDOW_MARKER_SEPARATOR))) {
|
|
158
|
+
throw new Error("sheet-window reference encoder: posture marker contains the reserved separator");
|
|
159
|
+
}
|
|
160
|
+
cellView.setUint32(o + 88, markers.length === 0 ? 0 : interner.intern(markers.join(SHEET_WINDOW_MARKER_SEPARATOR)), true);
|
|
161
|
+
});
|
|
162
|
+
const geometry = readback.paintGeometry;
|
|
163
|
+
const sections = [
|
|
164
|
+
{
|
|
165
|
+
sectionId: SHEET_WINDOW_SECTION_ROWS,
|
|
166
|
+
bytes: encodeLineSection(readback.rows, "row", "heightPoints", "customHeight", interner),
|
|
167
|
+
recordCount: readback.rows.length
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
sectionId: SHEET_WINDOW_SECTION_COLS,
|
|
171
|
+
bytes: encodeLineSection(readback.columns, "column", "width", "customWidth", interner),
|
|
172
|
+
recordCount: readback.columns.length
|
|
173
|
+
},
|
|
174
|
+
{ sectionId: SHEET_WINDOW_SECTION_CELLS, bytes: cellBytes, recordCount: readback.cells.length }
|
|
175
|
+
];
|
|
176
|
+
if (geometry) {
|
|
177
|
+
const paintLines = (lines, field) => {
|
|
178
|
+
const bytes = new Uint8Array(lines.length * SHEET_WINDOW_PAINT_LINE_RECORD_BYTES);
|
|
179
|
+
const view = new DataView(bytes.buffer);
|
|
180
|
+
lines.forEach((line, i) => {
|
|
181
|
+
const o = i * SHEET_WINDOW_PAINT_LINE_RECORD_BYTES;
|
|
182
|
+
view.setUint32(o, line[field], true);
|
|
183
|
+
view.setUint32(o + 4, interner.intern(line.precision), true);
|
|
184
|
+
view.setUint8(o + 8, line.hidden ? 0x01 : 0x00);
|
|
185
|
+
view.setFloat64(o + 16, line.offsetPx, true);
|
|
186
|
+
view.setFloat64(o + 24, line.sizePx, true);
|
|
187
|
+
});
|
|
188
|
+
return bytes;
|
|
189
|
+
};
|
|
190
|
+
const rectCountTotal = geometry.cells.reduce((count, cell) => count + cell.rects.length, 0);
|
|
191
|
+
const rectBytes = new Uint8Array(rectCountTotal * SHEET_WINDOW_RECT_RECORD_BYTES);
|
|
192
|
+
const rectView = new DataView(rectBytes.buffer);
|
|
193
|
+
const paintCellBytes = new Uint8Array(geometry.cells.length * SHEET_WINDOW_PAINT_CELL_RECORD_BYTES);
|
|
194
|
+
const paintCellView = new DataView(paintCellBytes.buffer);
|
|
195
|
+
let rectCursor = 0;
|
|
196
|
+
geometry.cells.forEach((cell, i) => {
|
|
197
|
+
const o = i * SHEET_WINDOW_PAINT_CELL_RECORD_BYTES;
|
|
198
|
+
paintCellView.setUint32(o, cell.address.row, true);
|
|
199
|
+
paintCellView.setUint32(o + 4, cell.address.column, true);
|
|
200
|
+
paintCellView.setUint32(o + 8, rectCursor, true);
|
|
201
|
+
paintCellView.setUint16(o + 12, cell.rects.length, true);
|
|
202
|
+
paintCellView.setUint8(o + 14, cell.hidden ? 0x01 : 0x00);
|
|
203
|
+
paintCellView.setUint32(o + 16, interner.intern(cell.precision), true);
|
|
204
|
+
paintCellView.setUint32(o + 20, cell.mergeOwner ? cell.mergeOwner.row : SHEET_WINDOW_U32_NONE, true);
|
|
205
|
+
paintCellView.setUint32(o + 24, cell.mergeOwner ? cell.mergeOwner.column : SHEET_WINDOW_U32_NONE, true);
|
|
206
|
+
for (const rect of cell.rects) {
|
|
207
|
+
const ro = rectCursor * SHEET_WINDOW_RECT_RECORD_BYTES;
|
|
208
|
+
rectView.setFloat64(ro, rect.xPx, true);
|
|
209
|
+
rectView.setFloat64(ro + 8, rect.yPx, true);
|
|
210
|
+
rectView.setFloat64(ro + 16, rect.widthPx, true);
|
|
211
|
+
rectView.setFloat64(ro + 24, rect.heightPx, true);
|
|
212
|
+
rectView.setUint32(ro + 32, interner.intern(rect.coordinateSpace.kind), true);
|
|
213
|
+
const region = "region" in rect.coordinateSpace ? rect.coordinateSpace.region : undefined;
|
|
214
|
+
rectView.setUint32(ro + 36, interner.intern(region), true);
|
|
215
|
+
rectView.setUint32(ro + 40, interner.intern(rect.precision), true);
|
|
216
|
+
rectCursor += 1;
|
|
217
|
+
}
|
|
218
|
+
});
|
|
219
|
+
sections.push({
|
|
220
|
+
sectionId: SHEET_WINDOW_SECTION_PAINT_ROWS,
|
|
221
|
+
bytes: paintLines(geometry.rows, "row"),
|
|
222
|
+
recordCount: geometry.rows.length
|
|
223
|
+
}, {
|
|
224
|
+
sectionId: SHEET_WINDOW_SECTION_PAINT_COLS,
|
|
225
|
+
bytes: paintLines(geometry.columns, "column"),
|
|
226
|
+
recordCount: geometry.columns.length
|
|
227
|
+
}, { sectionId: SHEET_WINDOW_SECTION_RECTS, bytes: rectBytes, recordCount: rectCountTotal }, {
|
|
228
|
+
sectionId: SHEET_WINDOW_SECTION_PAINT_CELLS,
|
|
229
|
+
bytes: paintCellBytes,
|
|
230
|
+
recordCount: geometry.cells.length
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
// String sections encode LAST so every interned id exists.
|
|
234
|
+
const encoder = new TextEncoder();
|
|
235
|
+
const encodedStrings = interner.entries.map((value) => encoder.encode(value));
|
|
236
|
+
const blobLen = encodedStrings.reduce((len, chunk) => len + chunk.byteLength, 0);
|
|
237
|
+
const blobBytes = new Uint8Array(blobLen);
|
|
238
|
+
const strtabBytes = new Uint8Array(encodedStrings.length * SHEET_WINDOW_STRTAB_ENTRY_BYTES);
|
|
239
|
+
const strtabView = new DataView(strtabBytes.buffer);
|
|
240
|
+
let blobCursor = 0;
|
|
241
|
+
encodedStrings.forEach((chunk, id) => {
|
|
242
|
+
if (id !== 0) {
|
|
243
|
+
blobBytes.set(chunk, blobCursor);
|
|
244
|
+
strtabView.setUint32(id * SHEET_WINDOW_STRTAB_ENTRY_BYTES, blobCursor, true);
|
|
245
|
+
strtabView.setUint32(id * SHEET_WINDOW_STRTAB_ENTRY_BYTES + 4, chunk.byteLength, true);
|
|
246
|
+
blobCursor += chunk.byteLength;
|
|
247
|
+
}
|
|
248
|
+
});
|
|
249
|
+
sections.push({ sectionId: SHEET_WINDOW_SECTION_STRTAB, bytes: strtabBytes, recordCount: encodedStrings.length }, { sectionId: SHEET_WINDOW_SECTION_STRBLOB, bytes: blobBytes, recordCount: blobLen });
|
|
250
|
+
const tableBytes = sections.length * SHEET_WINDOW_BINARY_SECTION_ENTRY_BYTES;
|
|
251
|
+
let cursor = align8(SHEET_WINDOW_BINARY_HEADER_BYTES + tableBytes);
|
|
252
|
+
const offsets = sections.map((section) => {
|
|
253
|
+
const offset = cursor;
|
|
254
|
+
cursor = align8(cursor + section.bytes.byteLength);
|
|
255
|
+
return offset;
|
|
256
|
+
});
|
|
257
|
+
const totalByteLen = cursor;
|
|
258
|
+
const bytes = new Uint8Array(totalByteLen);
|
|
259
|
+
const view = new DataView(bytes.buffer);
|
|
260
|
+
view.setUint32(0, SHEET_WINDOW_BINARY_MAGIC, true);
|
|
261
|
+
view.setUint16(4, SHEET_WINDOW_BINARY_VERSION, true);
|
|
262
|
+
view.setUint16(6, geometry ? SHEET_WINDOW_FLAG_PAINT_GEOMETRY : 0, true);
|
|
263
|
+
view.setUint32(8, sections.length, true);
|
|
264
|
+
view.setUint32(12, totalByteLen, true);
|
|
265
|
+
sections.forEach((section, i) => {
|
|
266
|
+
const o = SHEET_WINDOW_BINARY_HEADER_BYTES + i * SHEET_WINDOW_BINARY_SECTION_ENTRY_BYTES;
|
|
267
|
+
view.setUint32(o, section.sectionId, true);
|
|
268
|
+
view.setUint32(o + 4, offsets[i], true);
|
|
269
|
+
view.setUint32(o + 8, section.bytes.byteLength, true);
|
|
270
|
+
view.setUint32(o + 12, section.recordCount, true);
|
|
271
|
+
bytes.set(section.bytes, offsets[i]);
|
|
272
|
+
});
|
|
273
|
+
const rest = {
|
|
274
|
+
envelope: readback.envelope,
|
|
275
|
+
status: readback.status,
|
|
276
|
+
workbookId: readback.workbookId,
|
|
277
|
+
canonicalHash: readback.canonicalHash,
|
|
278
|
+
activeSheetId: readback.activeSheetId,
|
|
279
|
+
sheetName: readback.sheetName,
|
|
280
|
+
viewport: readback.viewport,
|
|
281
|
+
coordinatePosture: readback.coordinatePosture,
|
|
282
|
+
// X5-U-018: carry the right-to-left flag through the reference encoder's
|
|
283
|
+
// `rest` (default false for the common left-to-right sheet).
|
|
284
|
+
rightToLeft: readback.rightToLeft ?? false,
|
|
285
|
+
// UX-P-104: the sheet extent rides the `rest` half too, matching the Rust
|
|
286
|
+
// encoder's `sheetExtent`.
|
|
287
|
+
sheetExtent: readback.sheetExtent,
|
|
288
|
+
sheetWindowOrigin: readback.sheetWindowOrigin,
|
|
289
|
+
cache: readback.cache,
|
|
290
|
+
mergedRanges: readback.mergedRanges,
|
|
291
|
+
panePartitions: readback.panePartitions,
|
|
292
|
+
// X5-U-011: typed data-validation rules ride the `rest` half, matching the
|
|
293
|
+
// Rust encoder's `dataValidations` (always present, empty when none).
|
|
294
|
+
dataValidations: readback.dataValidations ?? [],
|
|
295
|
+
activeSelection: readback.activeSelection,
|
|
296
|
+
accessibility: readback.accessibility,
|
|
297
|
+
capabilities: readback.capabilities,
|
|
298
|
+
blockers: readback.blockers,
|
|
299
|
+
paintGeometryPresent: geometry !== undefined,
|
|
300
|
+
paintGeometryActiveSelection: geometry?.activeSelection,
|
|
301
|
+
paintGeometryObjects: geometry?.objects,
|
|
302
|
+
// X5-U-017: sparkline glyphs ride the `rest` half, matching the Rust
|
|
303
|
+
// encoder's `paintGeometrySparklines`.
|
|
304
|
+
paintGeometrySparklines: geometry?.sparklines,
|
|
305
|
+
rareCells
|
|
306
|
+
};
|
|
307
|
+
return { schemaId: SHEET_WINDOW_BINARY_SCHEMA_ID, bytes, rest };
|
|
308
|
+
}
|
|
@@ -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;
|