@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,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;
|