@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,373 @@
1
+ // Runtime 0.2.0 memory contract (R4), the JS side of every bridge call:
2
+ // pre-admission against the memory budget, trap containment with
3
+ // re-instantiation from the cached Module, the session ledger that names the
4
+ // sessions a trap lost, and the memory readbacks (`wasmMemoryBytes`,
5
+ // `highWater`). Browser-safe: no `node:` imports.
6
+ //
7
+ // Why this lives in JS: the wasm module is built with panic=abort and a
8
+ // link-time memory maximum, so an allocation past the maximum aborts and
9
+ // traps as `RuntimeError: unreachable`. Nothing inside wasm can turn that
10
+ // into a typed error, and a trapped instance may hold half-updated state
11
+ // (borrowed RefCells, a torn allocator). So the bridge never reuses it.
12
+ import { estimateXlsxPackageMemory, XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES } from "./memory-budget.js";
13
+ /**
14
+ * The typed errors the bridge throws instead of a raw trap or an
15
+ * out-of-memory abort. Hosts branch on `code` through
16
+ * `isXlsxWasmBridgeError`.
17
+ *
18
+ * Crossing a thread: structured clone (`postMessage`, `structuredClone`)
19
+ * keeps only the standard error names and drops own properties, so a cloned
20
+ * `XlsxWasmBridgeError` arrives as a plain `Error` with no `code` and is not
21
+ * recognised. Post `serializeXlsxWasmBridgeError(error)` instead; the plain
22
+ * object it returns survives the clone, `isXlsxWasmBridgeError` recognises
23
+ * it, and `deserializeXlsxWasmBridgeError` turns it back into an instance.
24
+ */
25
+ export class XlsxWasmBridgeError extends Error {
26
+ code;
27
+ method;
28
+ lostSessions;
29
+ recovered;
30
+ trapped;
31
+ estimatedBytes;
32
+ budgetBytes;
33
+ estimate;
34
+ constructor(details) {
35
+ super(details.message, details.cause === undefined ? undefined : { cause: details.cause });
36
+ this.name = "XlsxWasmBridgeError";
37
+ this.code = details.code;
38
+ this.method = details.method;
39
+ this.lostSessions = Object.freeze([...(details.lostSessions ?? [])]);
40
+ this.recovered = details.recovered ?? false;
41
+ this.trapped = details.trapped ?? false;
42
+ if (details.estimatedBytes !== undefined)
43
+ this.estimatedBytes = details.estimatedBytes;
44
+ if (details.budgetBytes !== undefined)
45
+ this.budgetBytes = details.budgetBytes;
46
+ if (details.estimate !== undefined)
47
+ this.estimate = details.estimate;
48
+ }
49
+ }
50
+ /**
51
+ * True for an `XlsxWasmBridgeError` from any realm, and for the plain object
52
+ * `serializeXlsxWasmBridgeError` returns. A raw structured clone of the error
53
+ * is not recognised: it has lost its name and code (see the class comment).
54
+ */
55
+ export function isXlsxWasmBridgeError(value, code) {
56
+ if (typeof value !== "object" || value === null)
57
+ return false;
58
+ const candidate = value;
59
+ if (candidate.name !== "XlsxWasmBridgeError")
60
+ return false;
61
+ if (candidate.code !== "wasm-instance-lost" && candidate.code !== "out-of-memory-budget")
62
+ return false;
63
+ return code === undefined || candidate.code === code;
64
+ }
65
+ /** A plain object carrying every field of `error` except `cause`, for `postMessage`. */
66
+ export function serializeXlsxWasmBridgeError(error) {
67
+ return {
68
+ name: "XlsxWasmBridgeError",
69
+ code: error.code,
70
+ method: error.method,
71
+ message: error.message,
72
+ lostSessions: [...error.lostSessions],
73
+ recovered: error.recovered,
74
+ trapped: error.trapped,
75
+ ...(error.estimatedBytes !== undefined ? { estimatedBytes: error.estimatedBytes } : {}),
76
+ ...(error.budgetBytes !== undefined ? { budgetBytes: error.budgetBytes } : {}),
77
+ ...(error.estimate !== undefined ? { estimate: { ...error.estimate } } : {})
78
+ };
79
+ }
80
+ /** An `XlsxWasmBridgeError` instance from its serialized form, or undefined when `value` is not one. */
81
+ export function deserializeXlsxWasmBridgeError(value) {
82
+ if (value instanceof XlsxWasmBridgeError)
83
+ return value;
84
+ if (!isXlsxWasmBridgeError(value))
85
+ return undefined;
86
+ const plain = value;
87
+ const lostSessions = Array.isArray(plain.lostSessions)
88
+ ? plain.lostSessions.filter((id) => typeof id === "string")
89
+ : [];
90
+ return new XlsxWasmBridgeError({
91
+ code: value.code,
92
+ method: typeof plain.method === "string" ? plain.method : "unknown",
93
+ message: typeof plain.message === "string" ? plain.message : value.code,
94
+ lostSessions,
95
+ recovered: plain.recovered === true,
96
+ trapped: plain.trapped === true,
97
+ ...(typeof plain.estimatedBytes === "number" ? { estimatedBytes: plain.estimatedBytes } : {}),
98
+ ...(typeof plain.budgetBytes === "number" ? { budgetBytes: plain.budgetBytes } : {}),
99
+ ...(plain.estimate && typeof plain.estimate === "object" ? { estimate: plain.estimate } : {})
100
+ });
101
+ }
102
+ const HANDLE_GENERATION_SEPARATOR = "@";
103
+ /** True for bridge methods whose first argument is a runtime-session handle id. */
104
+ function takesSessionHandle(method) {
105
+ return (method !== "openWorkbookRuntimeSession" &&
106
+ (method.includes("RuntimeSession") || method.endsWith("InSession") || method === "aiSessionCall"));
107
+ }
108
+ function isTrap(error) {
109
+ if (typeof WebAssembly === "object" && WebAssembly !== null && error instanceof WebAssembly.RuntimeError) {
110
+ return true;
111
+ }
112
+ // A wasm stack overflow surfaces as a RangeError and leaves the instance
113
+ // mid-call just like a trap.
114
+ return error instanceof RangeError && /call stack/iu.test(error.message);
115
+ }
116
+ function isPromise(value) {
117
+ return typeof value?.then === "function";
118
+ }
119
+ function admissionOf(options) {
120
+ if (options.memoryBudgetBytes !== undefined && !(options.memoryBudgetBytes >= 0)) {
121
+ throw new RangeError(`memoryBudgetBytes must be a non-negative byte count, got ${String(options.memoryBudgetBytes)}`);
122
+ }
123
+ return {
124
+ ...(options.memoryBudgetBytes !== undefined ? { memoryBudgetBytes: options.memoryBudgetBytes } : {}),
125
+ ...(options.admission !== undefined ? { admission: options.admission } : {})
126
+ };
127
+ }
128
+ export function createXlsxWasmRuntime(options) {
129
+ const maximumBytes = options.maximumMemoryBytes ?? XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES;
130
+ let current = options.instance;
131
+ // The last instance object, kept only so `typeof raw.method` probes still
132
+ // answer while the runtime is lost. It is never called.
133
+ let shape = options.instance.raw;
134
+ let recovering;
135
+ let generation = 0;
136
+ let peakBytes = 0;
137
+ let highWaterBytes;
138
+ /** External handle id -> its estimates, for every session the live instance holds. */
139
+ const liveSessions = new Map();
140
+ /** External handle ids a trap took. */
141
+ const lostSessions = new Set();
142
+ const currentBytes = () => {
143
+ const memory = current?.memory;
144
+ if (!memory)
145
+ return undefined;
146
+ const bytes = memory.buffer.byteLength;
147
+ if (bytes > peakBytes)
148
+ peakBytes = bytes;
149
+ return bytes;
150
+ };
151
+ currentBytes();
152
+ const lost = (method, sessions, message, cause, trapped = false) => new XlsxWasmBridgeError({
153
+ code: "wasm-instance-lost",
154
+ method,
155
+ lostSessions: sessions,
156
+ recovered: current !== undefined,
157
+ trapped,
158
+ message,
159
+ cause
160
+ });
161
+ const adopt = (instance) => {
162
+ current = instance;
163
+ shape = instance.raw;
164
+ currentBytes();
165
+ };
166
+ const recover = () => {
167
+ if (!options.reinstantiate || recovering)
168
+ return;
169
+ let next;
170
+ try {
171
+ next = options.reinstantiate();
172
+ }
173
+ catch {
174
+ return;
175
+ }
176
+ if (isPromise(next)) {
177
+ recovering = next.then((instance) => {
178
+ recovering = undefined;
179
+ adopt(instance);
180
+ }, () => {
181
+ recovering = undefined;
182
+ });
183
+ return;
184
+ }
185
+ adopt(next);
186
+ };
187
+ const externalId = (nativeId) => generation === 0 ? nativeId : `${nativeId}${HANDLE_GENERATION_SEPARATOR}${generation}`;
188
+ /** The native handle id for an external one, or a typed refusal when it is gone. */
189
+ const nativeId = (method, handleId) => {
190
+ if (lostSessions.has(handleId)) {
191
+ throw lost(method, [handleId], `runtime session ${handleId} was lost when the wasm instance trapped; reopen it`);
192
+ }
193
+ if (generation === 0)
194
+ return handleId;
195
+ const suffix = `${HANDLE_GENERATION_SEPARATOR}${generation}`;
196
+ if (handleId.endsWith(suffix))
197
+ return handleId.slice(0, -suffix.length);
198
+ // An id from an earlier instance must never reach this one: its native
199
+ // counter restarted and may have handed the same id to a new session.
200
+ throw lost(method, [handleId], `runtime session ${handleId} belongs to a wasm instance that no longer exists; reopen it`);
201
+ };
202
+ /** The open estimates of the sessions the live instance holds. */
203
+ const committedBytes = () => {
204
+ let total = 0;
205
+ for (const session of liveSessions.values())
206
+ total += session.openBytes;
207
+ return total;
208
+ };
209
+ const admit = (admission, method, estimatedBytes, estimate) => {
210
+ if (admission.admission === "off")
211
+ return;
212
+ // Never `maximum - byteLength`: linear memory does not shrink, so on a
213
+ // long-lived instance that gap only closes, even after the sessions that
214
+ // grew it are disposed and their memory is free for reuse.
215
+ const committed = committedBytes();
216
+ const headroom = maximumBytes - committed;
217
+ const budgetBytes = Math.max(0, Math.min(admission.memoryBudgetBytes ?? Number.POSITIVE_INFINITY, headroom));
218
+ if (estimatedBytes > budgetBytes) {
219
+ throw new XlsxWasmBridgeError({
220
+ code: "out-of-memory-budget",
221
+ method,
222
+ message: `${method} refused before calling into wasm: estimated ${estimatedBytes} bytes of linear memory, ` +
223
+ `budget ${budgetBytes} bytes (maximum ${maximumBytes}, ${committed} estimated for ${liveSessions.size} live session(s)` +
224
+ (admission.memoryBudgetBytes !== undefined ? `, host cap ${admission.memoryBudgetBytes}` : "") +
225
+ ")",
226
+ estimatedBytes,
227
+ budgetBytes,
228
+ ...(estimate ? { estimate } : {})
229
+ });
230
+ }
231
+ };
232
+ const invoke = (admission, method, args) => {
233
+ if (!current) {
234
+ recover();
235
+ if (!current) {
236
+ throw lost(method, [], `the wasm instance trapped and no fresh instance is available yet; ${method} did not run`);
237
+ }
238
+ }
239
+ const live = current;
240
+ let callArgs = args;
241
+ let handleId;
242
+ if (takesSessionHandle(method) && typeof args[0] === "string") {
243
+ handleId = args[0];
244
+ const native = nativeId(method, handleId);
245
+ if (native !== handleId)
246
+ callArgs = [native, ...args.slice(1)];
247
+ }
248
+ let openEstimate;
249
+ if (method === "openWorkbookRuntimeSession" && args[0] instanceof Uint8Array) {
250
+ openEstimate = estimateXlsxPackageMemory(args[0]);
251
+ admit(admission, method, openEstimate.estimatedBytes, openEstimate);
252
+ }
253
+ else if (method === "recalculateFormulas" && args[0] instanceof Uint8Array) {
254
+ const estimate = estimateXlsxPackageMemory(args[0]);
255
+ admit(admission, method, estimate.estimatedBytes + estimate.recalcEstimatedBytes, estimate);
256
+ }
257
+ else if (method === "recalculateInSession" && handleId !== undefined) {
258
+ admit(admission, method, liveSessions.get(handleId)?.recalcBytes ?? 0);
259
+ }
260
+ let result;
261
+ try {
262
+ const fn = live.raw[method];
263
+ if (typeof fn !== "function") {
264
+ throw new TypeError(`wasm bridge method ${method} is not a function`);
265
+ }
266
+ result = fn.apply(live.raw, callArgs);
267
+ }
268
+ catch (error) {
269
+ if (!isTrap(error)) {
270
+ currentBytes();
271
+ throw error;
272
+ }
273
+ currentBytes();
274
+ const taken = [...liveSessions.keys()];
275
+ liveSessions.clear();
276
+ for (const id of taken)
277
+ lostSessions.add(id);
278
+ current = undefined;
279
+ generation += 1;
280
+ recover();
281
+ throw lost(method, taken, `the wasm instance trapped in ${method} (${error instanceof Error ? error.message : String(error)}); ` +
282
+ `it was discarded with ${taken.length} session(s)` +
283
+ (current ? " and a fresh instance is live" : ""), error, true);
284
+ }
285
+ currentBytes();
286
+ return afterCall(method, handleId, callArgs[0], result, openEstimate);
287
+ };
288
+ const afterCall = (method, handleId, nativeHandle, result, openEstimate) => {
289
+ if (method === "openWorkbookRuntimeSession") {
290
+ const opened = result;
291
+ if (opened && typeof opened.handleId === "string") {
292
+ const id = externalId(opened.handleId);
293
+ liveSessions.set(id, {
294
+ openBytes: openEstimate?.estimatedBytes ?? 0,
295
+ recalcBytes: openEstimate?.recalcEstimatedBytes ?? 0
296
+ });
297
+ if (id !== opened.handleId)
298
+ return { ...opened, handleId: id };
299
+ }
300
+ return result;
301
+ }
302
+ if (handleId === undefined)
303
+ return result;
304
+ if (method === "disposeWorkbookRuntimeSession") {
305
+ liveSessions.delete(handleId);
306
+ }
307
+ else if (typeof result === "object" &&
308
+ result !== null &&
309
+ result.sessionDisposed === true) {
310
+ // The runtime disposed the session itself (an AI commit that failed
311
+ // after it ran): it no longer counts against the maximum.
312
+ liveSessions.delete(handleId);
313
+ }
314
+ if (generation === 0 || typeof result !== "object" || result === null)
315
+ return result;
316
+ // After a re-instantiation the native results echo native ids; hand the
317
+ // caller back the id it used.
318
+ let rewritten = result;
319
+ if (rewritten.handleId === nativeHandle)
320
+ rewritten = { ...rewritten, handleId };
321
+ const receipt = rewritten.session;
322
+ if (receipt && typeof receipt === "object" && receipt.handleId === nativeHandle) {
323
+ rewritten = { ...rewritten, session: { ...receipt, handleId } };
324
+ }
325
+ return rewritten;
326
+ };
327
+ const guardedRaw = (admission) => {
328
+ const wrappers = new Map();
329
+ return new Proxy({}, {
330
+ get(_target, property) {
331
+ const value = (current?.raw ?? shape)[property];
332
+ if (typeof value !== "function" || typeof property !== "string")
333
+ return value;
334
+ let wrapper = wrappers.get(property);
335
+ if (!wrapper) {
336
+ wrapper = (...args) => invoke(admission, property, args);
337
+ wrappers.set(property, wrapper);
338
+ }
339
+ return wrapper;
340
+ },
341
+ has(_target, property) {
342
+ return property in (current?.raw ?? shape);
343
+ }
344
+ });
345
+ };
346
+ const readback = () => {
347
+ const bytes = currentBytes();
348
+ return {
349
+ currentBytes: bytes,
350
+ peakBytes,
351
+ maximumBytes,
352
+ highWaterBytes,
353
+ aboveHighWater: highWaterBytes !== undefined && bytes !== undefined && bytes >= highWaterBytes,
354
+ generation
355
+ };
356
+ };
357
+ const highWater = (bytes) => {
358
+ if (bytes !== undefined) {
359
+ if (!Number.isFinite(bytes) || bytes <= 0) {
360
+ throw new RangeError(`highWater expects a positive byte count, got ${String(bytes)}`);
361
+ }
362
+ highWaterBytes = bytes;
363
+ }
364
+ return readback();
365
+ };
366
+ const view = (admission) => ({
367
+ raw: guardedRaw(admission),
368
+ wasmMemoryBytes: currentBytes,
369
+ highWater,
370
+ withAdmission: (next) => view(admissionOf(next))
371
+ });
372
+ return view(admissionOf(options));
373
+ }
@@ -0,0 +1,98 @@
1
+ import type { XlsxFormulaCommitRequest, XlsxFormulaCommitResult, XlsxFormulaRecalculateResult, XlsxLayoutMetricResizeRequest, XlsxLayoutMetricResizeResult, XlsxLayoutMetricVisibilityRequest, XlsxLayoutMetricVisibilityResult, XlsxFrozenPaneRequest, XlsxFrozenPaneResult, XlsxMergeCellsRequest, XlsxMergeCellsResult, XlsxRangeClearCommitRequest, XlsxRangeClearCommitResult, XlsxRangeFillCommitRequest, XlsxRangeFillCommitResult, XlsxRangeFormatCommitRequest, XlsxRangeFormatCommitResult, XlsxRangePasteCommitRequest, XlsxRangePasteCommitResult, XlsxRangeTransferCommitRequest, XlsxRangeTransferCommitResult, XlsxRuntimeSessionExportRequest, XlsxRuntimeSessionMutationReceipt, XlsxRuntimeWarning, XlsxSessionRecalculateRequest, XlsxSheetStructureMutationRequest, XlsxSheetStructureMutationResult, XlsxSheetTabMutationRequest, XlsxSheetTabMutationResult, XlsxShiftCellsCommitRequest, XlsxShiftCellsCommitResult, XlsxTableAppendRowRequest, XlsxTableAppendRowResult } from "../runtime/index.ts";
2
+ import type { XlsxBlocker } from "../shared.ts";
3
+ import type { XlsxRuntimeCommandVerdict } from "../runtime/index.ts";
4
+ import { type XlsxWasmBridge } from "./index.ts";
5
+ /**
6
+ * T1 (runtime-session-mutations-v1): host-side routing seam for workbook
7
+ * mutations.
8
+ *
9
+ * - `mode: "session"` — a runtime session handle exists AND the mounted wasm
10
+ * build exposes the full `*InSession` surface; every mutation family
11
+ * (formula, clear, fill, paste, transfer, format, resize, visibility,
12
+ * structure, tabs, table append) routes through the stateful session (no
13
+ * per-commit workbook re-parse, no per-commit byte export). Recalc defaults
14
+ * to the dirty differential path.
15
+ * - `mode: "bytes"` — no handle, or an older wasm build without the session
16
+ * exports (feature-detected via `supportsRuntimeSessionMutations`): edits
17
+ * route through today's byte-based exports byte-for-byte. Applied commits
18
+ * adopt `exportedBytes` as the current workbook truth, exactly like the
19
+ * existing byte pipeline.
20
+ *
21
+ * In BOTH modes results keep the byte-based DTO shape, so consumers keep
22
+ * consuming `result.invalidation` for tile damage exactly as today (the
23
+ * ui/react tile scheduler reads classes + range buckets unchanged).
24
+ *
25
+ * Byte-surface truth-fork protection: in session mode `currentBytes()` is
26
+ * auto-export-first — whenever the session revision advanced past the last
27
+ * export, it materializes fresh bytes through the read-only session export
28
+ * before returning. A consumer that mixes byte-based calls with an active
29
+ * session therefore always operates on post-mutation bytes; a failed export
30
+ * throws instead of silently serving stale pre-session bytes.
31
+ */
32
+ export type XlsxWorkbookMutationMode = "session" | "bytes";
33
+ export interface XlsxWorkbookMutationRouterInit {
34
+ /** Current workbook byte truth; required as the byte-mode fallback seed. */
35
+ readonly bytes: Uint8Array;
36
+ /**
37
+ * Open runtime-session handle (from `openWorkbookRuntimeSession`). When
38
+ * absent — or when the wasm build lacks runtime-session-mutations-v1 —
39
+ * the router stays on the byte path.
40
+ */
41
+ readonly sessionHandleId?: string;
42
+ }
43
+ export interface XlsxWorkbookBytesSnapshot {
44
+ readonly verdict: XlsxRuntimeCommandVerdict;
45
+ readonly bytes: Uint8Array;
46
+ /** Which pipeline produced the bytes. */
47
+ readonly source: "session-export" | "byte-truth";
48
+ /** Session receipt; present only when `source` is "session-export". */
49
+ readonly session?: XlsxRuntimeSessionMutationReceipt;
50
+ readonly blockers: readonly XlsxBlocker[];
51
+ readonly warnings: readonly XlsxRuntimeWarning[];
52
+ }
53
+ export interface XlsxWorkbookMutationRouter {
54
+ readonly mode: XlsxWorkbookMutationMode;
55
+ /** Present only in session mode. */
56
+ readonly sessionHandleId?: string;
57
+ /**
58
+ * Latest byte truth known to the router. Byte mode: advances with every
59
+ * applied commit. Session mode: auto-export-first — if any session
60
+ * mutation applied since the last export, a fresh read-only session export
61
+ * runs before returning, so byte-surface consumers can never silently fork
62
+ * from stale pre-session bytes (a failed export throws).
63
+ */
64
+ currentBytes(): Uint8Array;
65
+ commitCellFormula(request: XlsxFormulaCommitRequest): XlsxFormulaCommitResult;
66
+ commitRangeClear(request: XlsxRangeClearCommitRequest): XlsxRangeClearCommitResult;
67
+ commitRangeFill(request: XlsxRangeFillCommitRequest): XlsxRangeFillCommitResult;
68
+ commitRangePaste(request: XlsxRangePasteCommitRequest): XlsxRangePasteCommitResult;
69
+ commitRangeTransfer(request: XlsxRangeTransferCommitRequest): XlsxRangeTransferCommitResult;
70
+ commitRangeFormat(request: XlsxRangeFormatCommitRequest): XlsxRangeFormatCommitResult;
71
+ resizeColumnWidth(request: XlsxLayoutMetricResizeRequest): XlsxLayoutMetricResizeResult;
72
+ resizeRowHeight(request: XlsxLayoutMetricResizeRequest): XlsxLayoutMetricResizeResult;
73
+ setColumnHidden(request: XlsxLayoutMetricVisibilityRequest): XlsxLayoutMetricVisibilityResult;
74
+ setRowHidden(request: XlsxLayoutMetricVisibilityRequest): XlsxLayoutMetricVisibilityResult;
75
+ /** X5-U-004 freeze/unfreeze panes (frozen-pane-v1). */
76
+ setFrozenPane(request: XlsxFrozenPaneRequest): XlsxFrozenPaneResult;
77
+ /** X5-U-037 merge/unmerge cells (merge-cells-v1). */
78
+ mergeCells(request: XlsxMergeCellsRequest): XlsxMergeCellsResult;
79
+ mutateSheetStructure(request: XlsxSheetStructureMutationRequest): XlsxSheetStructureMutationResult;
80
+ mutateSheetTabs(request: XlsxSheetTabMutationRequest): XlsxSheetTabMutationResult;
81
+ commitTableAppendRow(request: XlsxTableAppendRowRequest): XlsxTableAppendRowResult;
82
+ /** X5-U-006 insert/delete cells with shift (shift-cells-v1). */
83
+ commitShiftCells(request: XlsxShiftCellsCommitRequest): XlsxShiftCellsCommitResult;
84
+ /**
85
+ * Session mode: `recalculateInSession` (dirty differential by default,
86
+ * `mode: "full"` forces the full plan). Byte mode: the existing full-plan
87
+ * `recalculateFormulas`; the session-only `mode` field is stripped and surfaced as a
88
+ * `session-request-fields-stripped` warning on the result.
89
+ */
90
+ recalculate(request?: XlsxSessionRecalculateRequest): XlsxFormulaRecalculateResult;
91
+ /**
92
+ * Materialize exportable workbook bytes. Session mode runs the read-only
93
+ * session export (no revision bump); byte mode returns the current byte
94
+ * truth as-is (it already IS the export of every applied commit).
95
+ */
96
+ exportWorkbookBytes(request?: XlsxRuntimeSessionExportRequest): XlsxWorkbookBytesSnapshot;
97
+ }
98
+ export declare function createXlsxWorkbookMutationRouter(bridge: XlsxWasmBridge, init: XlsxWorkbookMutationRouterInit): XlsxWorkbookMutationRouter;
@@ -0,0 +1,184 @@
1
+ import { supportsRuntimeSessionMutations } from "./index.js";
2
+ export function createXlsxWorkbookMutationRouter(bridge, init) {
3
+ let currentBytes = init.bytes;
4
+ if (init.sessionHandleId !== undefined && supportsRuntimeSessionMutations(bridge)) {
5
+ const handleId = init.sessionHandleId;
6
+ // Revision the cached `currentBytes` reflect. The opening bytes ARE
7
+ // revision 0 of the session, so byte reads before the first mutation
8
+ // skip the export round-trip.
9
+ let exportedAtRevision = 0;
10
+ let latestRevision = 0;
11
+ const track = (result) => {
12
+ if (result.session !== undefined) {
13
+ latestRevision = Math.max(latestRevision, result.session.revision);
14
+ }
15
+ return result;
16
+ };
17
+ const exportBytes = (request = {}) => {
18
+ const result = bridge.exportRuntimeSessionBytes(handleId, request);
19
+ track(result);
20
+ if (result.exportedBytes !== undefined) {
21
+ currentBytes = result.exportedBytes;
22
+ exportedAtRevision = result.session.revision;
23
+ }
24
+ return {
25
+ verdict: result.verdict,
26
+ bytes: result.exportedBytes ?? currentBytes,
27
+ source: "session-export",
28
+ session: result.session,
29
+ blockers: result.blockers,
30
+ warnings: result.warnings
31
+ };
32
+ };
33
+ return {
34
+ mode: "session",
35
+ sessionHandleId: handleId,
36
+ currentBytes: () => {
37
+ if (latestRevision === exportedAtRevision) {
38
+ return currentBytes;
39
+ }
40
+ // Auto-export-first: never hand out pre-session bytes while the
41
+ // session holds newer truth.
42
+ const snapshot = exportBytes();
43
+ if (snapshot.verdict !== "applied" && snapshot.verdict !== "applied-with-warnings") {
44
+ throw new Error(`xlsx session-mode currentBytes(): session export ${snapshot.verdict}; refusing to serve stale pre-session bytes (${snapshot.blockers[0]?.message ?? "no blocker detail"})`);
45
+ }
46
+ return snapshot.bytes;
47
+ },
48
+ commitCellFormula(request) {
49
+ return track(bridge.commitCellFormulaInSession(handleId, request));
50
+ },
51
+ commitRangeClear(request) {
52
+ return track(bridge.commitRangeClearInSession(handleId, request));
53
+ },
54
+ commitRangeFill(request) {
55
+ return track(bridge.commitRangeFillInSession(handleId, request));
56
+ },
57
+ commitRangePaste(request) {
58
+ return track(bridge.commitRangePasteInSession(handleId, request));
59
+ },
60
+ commitRangeTransfer(request) {
61
+ return track(bridge.commitRangeTransferInSession(handleId, request));
62
+ },
63
+ commitRangeFormat(request) {
64
+ return track(bridge.commitRangeFormatInSession(handleId, request));
65
+ },
66
+ resizeColumnWidth(request) {
67
+ return track(bridge.resizeColumnWidthInSession(handleId, request));
68
+ },
69
+ resizeRowHeight(request) {
70
+ return track(bridge.resizeRowHeightInSession(handleId, request));
71
+ },
72
+ setColumnHidden(request) {
73
+ return track(bridge.setColumnHiddenInSession(handleId, request));
74
+ },
75
+ setRowHidden(request) {
76
+ return track(bridge.setRowHiddenInSession(handleId, request));
77
+ },
78
+ setFrozenPane(request) {
79
+ return track(bridge.setFrozenPaneInSession(handleId, request));
80
+ },
81
+ mergeCells(request) {
82
+ return track(bridge.mergeCellsInSession(handleId, request));
83
+ },
84
+ mutateSheetStructure(request) {
85
+ return track(bridge.mutateSheetStructureInSession(handleId, request));
86
+ },
87
+ mutateSheetTabs(request) {
88
+ return track(bridge.mutateSheetTabsInSession(handleId, request));
89
+ },
90
+ commitTableAppendRow(request) {
91
+ return track(bridge.commitTableAppendRowInSession(handleId, request));
92
+ },
93
+ commitShiftCells(request) {
94
+ return track(bridge.commitShiftCellsInSession(handleId, request));
95
+ },
96
+ recalculate(request = {}) {
97
+ return track(bridge.recalculateInSession(handleId, request));
98
+ },
99
+ exportWorkbookBytes(request = {}) {
100
+ return exportBytes(request);
101
+ }
102
+ };
103
+ }
104
+ const adopt = (result) => {
105
+ if (result.exportedBytes !== undefined) {
106
+ currentBytes = result.exportedBytes;
107
+ }
108
+ return result;
109
+ };
110
+ return {
111
+ mode: "bytes",
112
+ currentBytes: () => currentBytes,
113
+ commitCellFormula(request) {
114
+ return adopt(bridge.commitCellFormula(currentBytes, request));
115
+ },
116
+ commitRangeClear(request) {
117
+ return adopt(bridge.commitRangeClear(currentBytes, request));
118
+ },
119
+ commitRangeFill(request) {
120
+ return adopt(bridge.commitRangeFill(currentBytes, request));
121
+ },
122
+ commitRangePaste(request) {
123
+ return adopt(bridge.commitRangePaste(currentBytes, request));
124
+ },
125
+ commitRangeTransfer(request) {
126
+ return adopt(bridge.commitRangeTransfer(currentBytes, request));
127
+ },
128
+ commitRangeFormat(request) {
129
+ return adopt(bridge.commitRangeFormat(currentBytes, request));
130
+ },
131
+ resizeColumnWidth(request) {
132
+ return adopt(bridge.resizeColumnWidth(currentBytes, request));
133
+ },
134
+ resizeRowHeight(request) {
135
+ return adopt(bridge.resizeRowHeight(currentBytes, request));
136
+ },
137
+ setColumnHidden(request) {
138
+ return adopt(bridge.setColumnHidden(currentBytes, request));
139
+ },
140
+ setRowHidden(request) {
141
+ return adopt(bridge.setRowHidden(currentBytes, request));
142
+ },
143
+ setFrozenPane(request) {
144
+ return adopt(bridge.setFrozenPane(currentBytes, request));
145
+ },
146
+ mergeCells(request) {
147
+ return adopt(bridge.mergeCells(currentBytes, request));
148
+ },
149
+ mutateSheetStructure(request) {
150
+ return adopt(bridge.mutateSheetStructure(currentBytes, request));
151
+ },
152
+ mutateSheetTabs(request) {
153
+ return adopt(bridge.mutateSheetTabs(currentBytes, request));
154
+ },
155
+ commitTableAppendRow(request) {
156
+ return adopt(bridge.commitTableAppendRow(currentBytes, request));
157
+ },
158
+ commitShiftCells(request) {
159
+ return adopt(bridge.commitShiftCells(currentBytes, request));
160
+ },
161
+ recalculate(request = {}) {
162
+ // Both paths accept explicit volatile inputs; only mode is session-only.
163
+ const { mode: strippedMode, ...byteRequest } = request;
164
+ const result = adopt(bridge.recalculateFormulas(currentBytes, byteRequest));
165
+ if (strippedMode === undefined) {
166
+ return result;
167
+ }
168
+ const warning = {
169
+ code: "session-request-fields-stripped",
170
+ message: "byte-based recalculate ignored session-only request field: mode (byte recalculation always uses the full plan)"
171
+ };
172
+ return { ...result, warnings: [...result.warnings, warning] };
173
+ },
174
+ exportWorkbookBytes() {
175
+ return {
176
+ verdict: "applied",
177
+ bytes: currentBytes,
178
+ source: "byte-truth",
179
+ blockers: [],
180
+ warnings: []
181
+ };
182
+ }
183
+ };
184
+ }
@@ -0,0 +1,9 @@
1
+ import type { XlsxUiSheetWindowReadback } from "../ui/index.ts";
2
+ import { type XlsxSheetWindowBinaryEnvelope } from "./sheet-window-binary.ts";
3
+ /**
4
+ * Encode a JSON sheet-window readback into the hybrid binary envelope.
5
+ * Throws when the readback holds structure the v1 layout cannot represent
6
+ * (which would indicate the layout spec needs re-agreement, not a silent
7
+ * widening here).
8
+ */
9
+ export declare function encodeSheetWindowBinaryReference(readback: XlsxUiSheetWindowReadback): XlsxSheetWindowBinaryEnvelope;