@beyondwork/xlsx-substrate-bindings 0.3.1 → 0.4.1
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/README.md +60 -3
- package/dist/runtime/types.d.ts +34 -0
- package/dist/wasm/bridge-contract.d.ts +1 -1
- package/dist/wasm/bridge-contract.js +1 -1
- package/dist/wasm/web-sha256.d.ts +1 -0
- package/dist/wasm/web-sha256.js +3 -0
- package/dist/wasm/web.d.ts +2 -1
- package/dist/wasm/web.js +7 -1
- package/generated/wasm-web/xlsx_substrate_wasm_bg.wasm +0 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ and the TypeScript bridge over it.
|
|
|
10
10
|
| --- | --- |
|
|
11
11
|
| `@beyondwork/xlsx-substrate-bindings` | Plain-value AI and UI types, the Conductor agent metadata, `BRIDGE_VERSION` and `BRIDGE_CAPABILITIES`. No wasm. |
|
|
12
12
|
| `@beyondwork/xlsx-substrate-bindings/wasm` | The Node loader and the full bridge contract. |
|
|
13
|
-
| `@beyondwork/xlsx-substrate-bindings/wasm/web` | The browser loader
|
|
13
|
+
| `@beyondwork/xlsx-substrate-bindings/wasm/web` | The browser loader, the capability helpers, the typed bridge errors (`isXlsxWasmBridgeError`) and `XLSX_WASM_WEB_SHA256`. No `node:` imports. |
|
|
14
14
|
| `@beyondwork/xlsx-substrate-bindings/wasm/web/glue` | The wasm-bindgen glue (ES module) the browser loader takes. |
|
|
15
15
|
| `@beyondwork/xlsx-substrate-bindings/wasm/web/binary` | The one `.wasm` binary, for hosts that serve or preload it. |
|
|
16
16
|
| `@beyondwork/xlsx-substrate-bindings/blank-workbook` | `createBlankWorkbookBytes()`: a new one-sheet workbook to open and edit. No imports at all, so it bundles for a browser. |
|
|
@@ -70,6 +70,21 @@ const loaded = await loadXlsxWasmBridgeWeb({ glueModule: glue, wasmSource: wasmU
|
|
|
70
70
|
Serve the `.wasm` from a cacheable route with the `application/wasm` MIME
|
|
71
71
|
type, or preload it and pass the bytes.
|
|
72
72
|
|
|
73
|
+
`XLSX_WASM_WEB_SHA256` (from `@beyondwork/xlsx-substrate-bindings/wasm/web`)
|
|
74
|
+
is the SHA-256, in lowercase hex, of the `.wasm` this package carries. A host
|
|
75
|
+
that fetches the binary from a URL it does not control (the exact-version
|
|
76
|
+
`https://unpkg.com/@beyondwork/xlsx-substrate-bindings@<version>/generated/wasm-web/xlsx_substrate_wasm_bg.wasm`)
|
|
77
|
+
or receives it as bytes hashes what it got and compares it to the constant
|
|
78
|
+
before passing it to the loader. The value is written when the package is
|
|
79
|
+
packed; an unpacked workspace build carries the empty string, which no binary
|
|
80
|
+
matches.
|
|
81
|
+
|
|
82
|
+
The React package `@beyondwork/xlsx-react-component` wraps this loader for
|
|
83
|
+
in-browser apps (`loadConductorRuntime` and `openConductorWorkbook` from its
|
|
84
|
+
`./embed` entry). Its README shows the three ways to deliver the `.wasm` to a
|
|
85
|
+
Beyond Work workblock and how load and save go through `bw.fetchBlob` and
|
|
86
|
+
`bw.saveBlob`.
|
|
87
|
+
|
|
73
88
|
## Memory contract
|
|
74
89
|
|
|
75
90
|
- **Maximum.** The binary is linked with a 2 GiB linear-memory maximum
|
|
@@ -121,6 +136,40 @@ and can rebuild the error with `deserializeXlsxWasmBridgeError`.
|
|
|
121
136
|
|
|
122
137
|
## Release notes
|
|
123
138
|
|
|
139
|
+
### 0.4.1 (bridge `xlsx-wasm-bridge-v50`)
|
|
140
|
+
|
|
141
|
+
A PATCH release on the same bridge.
|
|
142
|
+
|
|
143
|
+
- `XLSX_WASM_WEB_SHA256` is exported from `./wasm/web`: the sha256 of the
|
|
144
|
+
packed web wasm, written at pack time, so a browser host can check bytes it
|
|
145
|
+
fetched from a URL before compiling them.
|
|
146
|
+
- `@beyondwork/xlsx-react-component` 0.1.0 (the live embedded grid,
|
|
147
|
+
`ConductorEmbeddedWorkbook`) depends on this release.
|
|
148
|
+
|
|
149
|
+
### 0.4.0 (bridge `xlsx-wasm-bridge-v50`)
|
|
150
|
+
|
|
151
|
+
A MINOR release: the bridge moved from v49 to v50.
|
|
152
|
+
|
|
153
|
+
- **A stateless commit says when its recalculation did not apply.** The
|
|
154
|
+
commit answers `applied-with-warnings` with a `recalculation-not-refreshed`
|
|
155
|
+
warning whose typed `recalculation` field gives the reason
|
|
156
|
+
(`missing-volatile-inputs`, `guard-refused`, `evaluation-failed`,
|
|
157
|
+
`writeback-failed` or `readback-missing`), the blocker codes, the scope and
|
|
158
|
+
the formula cells left, and each affected formula cell in the readback
|
|
159
|
+
carries `valueRecalculated: false`. Before 0.4.0 such a commit answered
|
|
160
|
+
`applied` with stale values. Hosts that check `verdict === "applied"`
|
|
161
|
+
should also accept `applied-with-warnings` and read the warning.
|
|
162
|
+
- **Kernel runs list what they wrote.** A kernel run or a delete that clears
|
|
163
|
+
its output lists its written region and the formulas that recalculated in
|
|
164
|
+
the commit's changed cells, readback and audit.
|
|
165
|
+
- **`fullCalcOnLoad` is dropped once it is honoured.** A stateless export
|
|
166
|
+
whose full recalculation applied removes a carried `fullCalcOnLoad="1"`, so
|
|
167
|
+
later commits take the dirty path.
|
|
168
|
+
- **Cell edits on sheets with x14 rule lists.** A value, formula or format
|
|
169
|
+
edit on a worksheet whose extension list carries x14 conditional formats or
|
|
170
|
+
data validations now applies and exports with that list byte for byte. A
|
|
171
|
+
Move or a row or column insert or delete on such a sheet still refuses.
|
|
172
|
+
|
|
124
173
|
### 0.3.1 (bridge `xlsx-wasm-bridge-v49`)
|
|
125
174
|
|
|
126
175
|
A PATCH release on the same bridge.
|
|
@@ -136,7 +185,7 @@ A PATCH release on the same bridge.
|
|
|
136
185
|
|
|
137
186
|
### 0.3.0 (bridge `xlsx-wasm-bridge-v49`)
|
|
138
187
|
|
|
139
|
-
A MINOR release: the bridge moved from v46 (0.2.0) to
|
|
188
|
+
A MINOR release: the bridge moved from v46 (0.2.0) to v50. Hosts on 0.2.0
|
|
140
189
|
should upgrade; 0.3.0 carries correctness fixes.
|
|
141
190
|
|
|
142
191
|
- **Format edits on Excel-saved workbooks export.** A format edit (bold,
|
|
@@ -154,7 +203,15 @@ should upgrade; 0.3.0 carries correctness fixes.
|
|
|
154
203
|
- **Stateless commits recalculate honestly.** A stateless (bytes-in,
|
|
155
204
|
bytes-out) commit recalculates the formulas its edit dirties, including
|
|
156
205
|
volatile functions when the host passes the volatile inputs (v48). Before
|
|
157
|
-
0.3.0 such a commit could return stale formula values.
|
|
206
|
+
0.3.0 such a commit could return stale formula values. When the
|
|
207
|
+
recalculation does not apply, the answer says so: a
|
|
208
|
+
`recalculation-not-refreshed` warning carries a typed `recalculation` field
|
|
209
|
+
(the reason, any blocker codes and the cells left), and each formula cell it
|
|
210
|
+
left reads back with `valueRecalculated: false` (v50). The bytes keep the
|
|
211
|
+
file's cached values and ask Excel to recalculate on open.
|
|
212
|
+
- **Kernel writes are in the commit's answer.** A kernel run or delete lists
|
|
213
|
+
the cells it wrote, and the formula cells that read them and recalculated,
|
|
214
|
+
in the commit's `cells` (v50).
|
|
158
215
|
- **Smaller and faster runtime.** One evaluator serves every cell store: the
|
|
159
216
|
wasm binary went from about 11.9 MB to about 8.0 MB, and cold load is faster.
|
|
160
217
|
- **Name reads and go-to.** A sheet-qualified read of a name the sheet defines
|
package/dist/runtime/types.d.ts
CHANGED
|
@@ -1252,6 +1252,15 @@ export interface XlsxKernelMutationResult {
|
|
|
1252
1252
|
readonly undoBoundary?: XlsxRuntimeUndoBoundary;
|
|
1253
1253
|
readonly blockers: readonly XlsxBlocker[];
|
|
1254
1254
|
readonly warnings: readonly XlsxRuntimeWarning[];
|
|
1255
|
+
/**
|
|
1256
|
+
* X5-U-093: the cells a kernel run or a clearing delete changed: its
|
|
1257
|
+
* written output region, then the formulas that read the region and that
|
|
1258
|
+
* the export's recalculation refreshed (with their new values). The
|
|
1259
|
+
* service forwards them as the commit's changed cells; the audit's
|
|
1260
|
+
* `targetIds` name the region and each refreshed reader. Absent for a
|
|
1261
|
+
* kernel command that changes no cell value.
|
|
1262
|
+
*/
|
|
1263
|
+
readonly cells?: readonly XlsxRuntimeCellReadback[];
|
|
1255
1264
|
}
|
|
1256
1265
|
export interface XlsxKernelMutationReadback {
|
|
1257
1266
|
readonly bindingId: string;
|
|
@@ -1339,6 +1348,12 @@ export interface XlsxRuntimeCellReadback {
|
|
|
1339
1348
|
* `XlsxRuntimeSessionMutationReceipt.canonicalHash`).
|
|
1340
1349
|
*/
|
|
1341
1350
|
readonly workbookCanonicalHash: string;
|
|
1351
|
+
/**
|
|
1352
|
+
* X5-U-092: `false` on a formula cell of a stateless commit's readback
|
|
1353
|
+
* whose value the commit's recalculation did not refresh; the answer's
|
|
1354
|
+
* `recalculation-not-refreshed` warning says why. Absent otherwise.
|
|
1355
|
+
*/
|
|
1356
|
+
readonly valueRecalculated?: false;
|
|
1342
1357
|
}
|
|
1343
1358
|
export interface XlsxRuntimeAuditEnvelope {
|
|
1344
1359
|
readonly command: string;
|
|
@@ -1421,6 +1436,25 @@ export interface XlsxRuntimeWarning {
|
|
|
1421
1436
|
/** X5-U-011: a `warning` / `information` rule was violated; the value committed. */
|
|
1422
1437
|
| "data-validation-warning";
|
|
1423
1438
|
readonly message: string;
|
|
1439
|
+
/**
|
|
1440
|
+
* X5-U-092: on the `recalculation-not-refreshed` warning of a stateless
|
|
1441
|
+
* commit whose recalculation did not apply (the commit applied; its bytes
|
|
1442
|
+
* keep the file's caches and ask Excel for a full calculation on load).
|
|
1443
|
+
*/
|
|
1444
|
+
readonly recalculation?: XlsxStatelessRecalculationNotApplied;
|
|
1445
|
+
}
|
|
1446
|
+
/** X5-U-092: a stateless commit's recalculation that did not apply. */
|
|
1447
|
+
export interface XlsxStatelessRecalculationNotApplied {
|
|
1448
|
+
readonly reason: "missing-volatile-inputs" | "guard-refused" | "evaluation-failed" | "writeback-failed" | "readback-missing";
|
|
1449
|
+
/** The recalculation's blocker codes, where it refused with blockers. */
|
|
1450
|
+
readonly blockerCodes: readonly string[];
|
|
1451
|
+
/** `workbook`: a full plan did not apply, so no formula was recalculated; `cells`: only `cells` were left. */
|
|
1452
|
+
readonly scope: "workbook" | "cells";
|
|
1453
|
+
readonly cells: readonly {
|
|
1454
|
+
readonly sheetId: string;
|
|
1455
|
+
readonly cellId: string;
|
|
1456
|
+
readonly address: XlsxCellAddress;
|
|
1457
|
+
}[];
|
|
1424
1458
|
}
|
|
1425
1459
|
export interface XlsxWorkflowContextInput {
|
|
1426
1460
|
readonly revision?: number;
|
|
@@ -10,7 +10,7 @@ export { estimateXlsxPackageMemory, readWasmMemoryLimits, XLSX_WASM_LINEAR_MEMOR
|
|
|
10
10
|
export interface XlsxWasmBridgeStatus {
|
|
11
11
|
readonly packageName: "@beyondwork/xlsx-substrate-bindings";
|
|
12
12
|
readonly role: "wasm-ai-ui-runtime-binding";
|
|
13
|
-
readonly bridgeVersion: "xlsx-wasm-bridge-
|
|
13
|
+
readonly bridgeVersion: "xlsx-wasm-bridge-v50";
|
|
14
14
|
readonly capabilities: readonly ("workflow-context-v1" | "workflow-context-v2" | "workflow-overlay-lanes-v1" | "sheet-window-paint-geometry-v1" | "sheet-window-coordinate-posture-v1" | "formula-diagnostics-v2" | "formula-address-commit-v1" | "formula-recalculate-commit-v1" | "formula-recalculate-volatile-inputs-v1" | "formula-translation-interaction-v1" | "kernel-ui-v1" | "runtime-session-handles-v1" | "runtime-session-mutations-v1" | "staged-open-v1" | "sheet-window-cache-v1" | "readback-envelope-v1" | "preserve-only-entities-v1" | "selection-set-v1" | "multi-area-mutation-v1" | "range-fill-commit-v1" | "range-paste-commit-v1" | "range-clear-commit-v1" | "range-format-commit-v1" | "range-transfer-v1" | "layout-metric-resize-v1" | "layout-metric-visibility-v1" | "outline-group-visibility-v1" | "sheet-structure-v1" | "sheet-tabs-v1" | "table-mutation-v1" | "filter-sort-v1" | "sort-commit-v1" | "operation-pattern-hints-v1" | "ai-compressed-bundles-v1" | "ui-capability-records-v1" | "drawing-media-v1" | "drawing-chart-v1" | "sheet-window-binary-v1" | "frozen-pane-v1" | "sheet-window-extent-v1" | "selection-cursor-v1" | "merge-cells-v1" | "shift-cells-v1" | "selection-set-capabilities-v1" | "find-v1" | "go-to-v1" | "data-region-v1" | "ai-session-agent-v1" | "defined-names-v1")[];
|
|
15
15
|
readonly wasmBinding: "mounted";
|
|
16
16
|
readonly nativeBinding: "not-mounted";
|
|
@@ -70,7 +70,7 @@ export function supportsRuntimeSessionMutations(bridge) {
|
|
|
70
70
|
RUNTIME_SESSION_MUTATION_METHODS.every((method) => typeof bridge[method] === "function"));
|
|
71
71
|
}
|
|
72
72
|
export { createSheetWindowDecodedReader, decodeSheetWindowBinary, SHEET_WINDOW_BINARY_SCHEMA_ID } from "./sheet-window-binary.js";
|
|
73
|
-
const requiredBridgeVersion = "xlsx-wasm-bridge-
|
|
73
|
+
const requiredBridgeVersion = "xlsx-wasm-bridge-v50"; // v50: X5-U-092 (stateless commit answers type a recalculation that did not apply; kernel answers carry their written cells; v49 was X5-U-023)
|
|
74
74
|
const requiredCapabilities = [
|
|
75
75
|
"workflow-context-v2",
|
|
76
76
|
"workflow-overlay-lanes-v1",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const XLSX_WASM_WEB_SHA256: string;
|
package/dist/wasm/web.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type RawXlsxWasmModule, type XlsxWasmBridgeLoadResult } from "./bridge-contract.ts";
|
|
2
|
-
export { BRIDGE_CAPABILITIES, BRIDGE_VERSION, missingXlsxWasmCapabilities, supportsRuntimeSessionMutations, type XlsxRuntimeSessionHandle, type XlsxRuntimeSessionMutationBridge, type XlsxRuntimeSessionOpenRequest, type XlsxSelectionSetRequest, type XlsxWasmBridge, type XlsxWasmBridgeLoadResult, type XlsxWasmBridgeStatus } from "./bridge-contract.ts";
|
|
2
|
+
export { BRIDGE_CAPABILITIES, BRIDGE_VERSION, isXlsxWasmBridgeError, missingXlsxWasmCapabilities, supportsRuntimeSessionMutations, XlsxWasmBridgeError, type XlsxRuntimeSessionHandle, type XlsxRuntimeSessionMutationBridge, type XlsxRuntimeSessionOpenRequest, type XlsxSelectionSetRequest, type XlsxWasmBridge, type XlsxWasmBridgeErrorCode, type XlsxWasmBridgeLoadResult, type XlsxWasmBridgeStatus } from "./bridge-contract.ts";
|
|
3
3
|
export { createXlsxWorkbookMutationRouter, type XlsxWorkbookBytesSnapshot, type XlsxWorkbookMutationMode, type XlsxWorkbookMutationRouter, type XlsxWorkbookMutationRouterInit } from "./session-router.ts";
|
|
4
|
+
export { XLSX_WASM_WEB_SHA256 } from "./web-sha256.ts";
|
|
4
5
|
/**
|
|
5
6
|
* Accepted wasm sources for the web glue's init entry point
|
|
6
7
|
* (wasm-bindgen `--target web`): URL/string/Request/Response stream through
|
package/dist/wasm/web.js
CHANGED
|
@@ -14,8 +14,14 @@ import { createXlsxWasmBridge, createXlsxWasmRuntime, readWasmMemoryLimits, vali
|
|
|
14
14
|
// comes from a module with no `node:` import; the bundling guard
|
|
15
15
|
// test/xlsx/browser-entry-node-free.test.ts holds that for every browser
|
|
16
16
|
// entry of the package.
|
|
17
|
-
export { BRIDGE_CAPABILITIES, BRIDGE_VERSION,
|
|
17
|
+
export { BRIDGE_CAPABILITIES, BRIDGE_VERSION,
|
|
18
|
+
// X1-D-088: a browser host recognises the two typed bridge errors
|
|
19
|
+
// (out-of-memory-budget, wasm-instance-lost) without the Node loader.
|
|
20
|
+
isXlsxWasmBridgeError, missingXlsxWasmCapabilities, supportsRuntimeSessionMutations, XlsxWasmBridgeError } from "./bridge-contract.js";
|
|
18
21
|
export { createXlsxWorkbookMutationRouter } from "./session-router.js";
|
|
22
|
+
// X1-D-088: the packed binary's SHA-256, for hosts that check the wasm they
|
|
23
|
+
// fetched or received before instantiating it (written at prepack).
|
|
24
|
+
export { XLSX_WASM_WEB_SHA256 } from "./web-sha256.js";
|
|
19
25
|
/**
|
|
20
26
|
* Instantiate and mount the XLSX wasm bridge from the web-target artifact.
|
|
21
27
|
*
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@beyondwork/xlsx-substrate-bindings",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Conductor, the Ensemble spreadsheet runtime: native XLSX sessions compiled to WebAssembly for Node and browsers.",
|
|
5
5
|
"conductor": {
|
|
6
|
-
"bridgeVersion": "xlsx-wasm-bridge-
|
|
6
|
+
"bridgeVersion": "xlsx-wasm-bridge-v50",
|
|
7
7
|
"versionPolicy": "Versions stay 0.x. A release is MINOR when its bridgeVersion differs from the last published release's, PATCH for fixes on the same bridgeVersion, and MAJOR only for removing a required method or capability. A bridge version change on pe2 does not by itself need a release.",
|
|
8
8
|
"wasm": "generated/wasm-web/xlsx_substrate_wasm_bg.wasm",
|
|
9
9
|
"linearMemoryMaximumBytes": 2147483648
|