@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 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. No `node:` imports. |
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 v49. Hosts on 0.2.0
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
@@ -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-v49";
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-v49"; // v49: X5-U-023 (go-to answers carry a multi-area target's further areas; v48 was X5-U-089)
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;
@@ -0,0 +1,3 @@
1
+ // Written by scripts/prepare-package.mjs at pack time: the SHA-256 of
2
+ // generated/wasm-web/xlsx_substrate_wasm_bg.wasm in this package.
3
+ export const XLSX_WASM_WEB_SHA256 = "754fda62d96244132594606ce5a7f2a6f5038a35f4b3c98bfc64ee4cb5afa026";
@@ -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, missingXlsxWasmCapabilities, supportsRuntimeSessionMutations } from "./bridge-contract.js";
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
  *
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@beyondwork/xlsx-substrate-bindings",
3
- "version": "0.3.1",
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-v49",
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