@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,72 @@
1
+ import { type RawXlsxWasmModule, type XlsxWasmBridgeLoadResult } from "./bridge-contract.ts";
2
+ /**
3
+ * Accepted wasm sources for the web glue's init entry point
4
+ * (wasm-bindgen `--target web`): URL/string/Request/Response stream through
5
+ * `WebAssembly.instantiateStreaming` (with the glue's built-in MIME-type
6
+ * fallback); BufferSource/Module instantiate directly.
7
+ */
8
+ export type XlsxWasmWebInitSource = URL | string | Request | Response | BufferSource | WebAssembly.Module;
9
+ /**
10
+ * Shape of the `--target web` glue module namespace: the same raw bridge
11
+ * exports as the nodejs artifact plus the wasm-bindgen web-target init
12
+ * entry points (`default` async init and `initSync`).
13
+ */
14
+ export interface RawXlsxWasmWebModule extends RawXlsxWasmModule {
15
+ readonly default: (init?: {
16
+ module_or_path?: XlsxWasmWebInitSource;
17
+ }) => Promise<unknown>;
18
+ readonly initSync?: (init: {
19
+ module: BufferSource | WebAssembly.Module;
20
+ }) => unknown;
21
+ /**
22
+ * Runtime 0.2.0 glue (scripts/build-wasm.mjs): a fresh glue object with its
23
+ * own instance state per call. With it the loader instantiates from one
24
+ * compiled Module and can replace a trapped instance (R4); without it (an
25
+ * older glue) a trap leaves the bridge lost.
26
+ */
27
+ readonly createXlsxSubstrateGlue?: () => RawXlsxWasmWebModule;
28
+ }
29
+ export interface XlsxWasmWebLoadRequest {
30
+ /**
31
+ * The imported `generated/wasm-web/xlsx_substrate_wasm.js` module
32
+ * namespace. The host adapter performs the ESM import (statically from
33
+ * its own bundle or via a same-origin dynamic import it owns) — the
34
+ * bindings package never resolves artifact URLs itself.
35
+ */
36
+ readonly glueModule: RawXlsxWasmWebModule;
37
+ /**
38
+ * Explicit wasm source. Always pass one — never rely on the glue's
39
+ * `import.meta.url`-relative default, which would encode a fetch the
40
+ * host did not choose.
41
+ */
42
+ readonly wasmSource: XlsxWasmWebInitSource;
43
+ /**
44
+ * Browser analogue of `XLSX_WASM_REQUIRED=1` (browsers have no
45
+ * `process.env`): when true, every not-mounted outcome throws instead of
46
+ * returning a soft result. Defaults to false.
47
+ */
48
+ readonly required?: boolean;
49
+ /** A host cap on what one open or recalculation may be estimated to need (R4). */
50
+ readonly memoryBudgetBytes?: number;
51
+ /** "off" skips pre-admission; trap containment stays on. */
52
+ readonly admission?: "enforce" | "off";
53
+ }
54
+ /**
55
+ * Instantiate and mount the XLSX wasm bridge from the web-target artifact.
56
+ *
57
+ * Feature-detects WebAssembly, runs the glue's async init against the
58
+ * host-supplied source, then applies the exact same mount gate as the
59
+ * Node.js loader (`validateRawXlsxWasmModule`) and wraps the raw module
60
+ * with the shared `createXlsxWasmBridge` — the returned `XlsxWasmBridge`
61
+ * surface is identical across both artifacts.
62
+ *
63
+ * With the runtime 0.2.0 glue (`createXlsxSubstrateGlue`), the source is
64
+ * compiled once into a Module and each call mounts a new instance from it;
65
+ * a trapped instance is replaced from the same Module (R4). An older glue
66
+ * holds one module-level instance, so repeated calls reuse it and later
67
+ * `wasmSource` values are ignored. EP3-2 note:
68
+ * Conductor's `/api` responses are no-store; the wasm asset must be served
69
+ * from a cacheable route (or preloaded by the host) before the mirror
70
+ * session ships, or every boot re-downloads the multi-megabyte module.
71
+ */
72
+ export declare function loadXlsxWasmBridgeWeb(request: XlsxWasmWebLoadRequest): Promise<XlsxWasmBridgeLoadResult>;
@@ -0,0 +1,142 @@
1
+ // Browser loader for the `--target web` ESM wasm artifact in
2
+ // `generated/wasm-web/` (EP3-1). Browser-safe by construction: zero `node:`
3
+ // imports and zero static references to the gitignored generated artifacts.
4
+ // Per `docs/architecture/xlsx/00-overview.md` §Implementation Split, the
5
+ // HOST adapter owns bytes and asset URLs: it performs the ESM import of the
6
+ // glue module and supplies an explicit wasm source (same-origin URL,
7
+ // Response, or preloaded bytes). This keeps the bindings package free of
8
+ // dynamic remote imports — self-contained for Beyond Work iframe
9
+ // deployments where the wasm bytes are host-supplied, never CDN-fetched.
10
+ import { createXlsxWasmBridge, createXlsxWasmRuntime, readWasmMemoryLimits, validateRawXlsxWasmModule, XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES } from "./bridge-contract.js";
11
+ /**
12
+ * Instantiate and mount the XLSX wasm bridge from the web-target artifact.
13
+ *
14
+ * Feature-detects WebAssembly, runs the glue's async init against the
15
+ * host-supplied source, then applies the exact same mount gate as the
16
+ * Node.js loader (`validateRawXlsxWasmModule`) and wraps the raw module
17
+ * with the shared `createXlsxWasmBridge` — the returned `XlsxWasmBridge`
18
+ * surface is identical across both artifacts.
19
+ *
20
+ * With the runtime 0.2.0 glue (`createXlsxSubstrateGlue`), the source is
21
+ * compiled once into a Module and each call mounts a new instance from it;
22
+ * a trapped instance is replaced from the same Module (R4). An older glue
23
+ * holds one module-level instance, so repeated calls reuse it and later
24
+ * `wasmSource` values are ignored. EP3-2 note:
25
+ * Conductor's `/api` responses are no-store; the wasm asset must be served
26
+ * from a cacheable route (or preloaded by the host) before the mirror
27
+ * session ships, or every boot re-downloads the multi-megabyte module.
28
+ */
29
+ export async function loadXlsxWasmBridgeWeb(request) {
30
+ const required = request.required === true;
31
+ const notMounted = (reason) => {
32
+ if (required) {
33
+ throw new Error(reason);
34
+ }
35
+ return { wasmBinding: "not-mounted", reason };
36
+ };
37
+ if (typeof WebAssembly !== "object" ||
38
+ WebAssembly === null ||
39
+ typeof WebAssembly.instantiate !== "function") {
40
+ return notMounted("WebAssembly is unavailable in this environment");
41
+ }
42
+ try {
43
+ const glue = request.glueModule;
44
+ const runtimeOptions = {
45
+ ...(request.memoryBudgetBytes !== undefined ? { memoryBudgetBytes: request.memoryBudgetBytes } : {}),
46
+ ...(request.admission !== undefined ? { admission: request.admission } : {})
47
+ };
48
+ if (typeof glue.createXlsxSubstrateGlue !== "function") {
49
+ // An older glue: one module-level instance, no re-instantiation.
50
+ const wasmExports = await glue.default({ module_or_path: request.wasmSource });
51
+ const validation = validateRawXlsxWasmModule(glue);
52
+ if (!validation.ok) {
53
+ return notMounted(validation.reason);
54
+ }
55
+ const runtime = createXlsxWasmRuntime({ instance: instanceSource(glue, wasmExports), ...runtimeOptions });
56
+ return { wasmBinding: "mounted", bridge: createXlsxWasmBridge(glue, validation.status, runtime) };
57
+ }
58
+ const compiled = await compileWasmSource(request.wasmSource);
59
+ const first = glue.createXlsxSubstrateGlue();
60
+ const firstExports = await first.default({ module_or_path: compiled.module });
61
+ const holder = { ...first };
62
+ const validation = validateRawXlsxWasmModule(holder);
63
+ if (!validation.ok) {
64
+ return notMounted(validation.reason);
65
+ }
66
+ const adopt = (fresh, freshExports) => {
67
+ Object.assign(holder, fresh);
68
+ return instanceSource(holder, freshExports);
69
+ };
70
+ const runtime = createXlsxWasmRuntime({
71
+ instance: instanceSource(holder, firstExports),
72
+ maximumMemoryBytes: compiled.maximumBytes,
73
+ ...runtimeOptions,
74
+ reinstantiate() {
75
+ const fresh = glue.createXlsxSubstrateGlue();
76
+ try {
77
+ // Synchronous where the engine allows it (workers, Node).
78
+ if (typeof fresh.initSync === "function") {
79
+ return adopt(fresh, fresh.initSync({ module: compiled.module }));
80
+ }
81
+ }
82
+ catch {
83
+ // A browser main thread may refuse synchronous instantiation of a
84
+ // large module; fall through to the asynchronous init.
85
+ }
86
+ return fresh.default({ module_or_path: compiled.module }).then((freshExports) => adopt(fresh, freshExports));
87
+ }
88
+ });
89
+ return { wasmBinding: "mounted", bridge: createXlsxWasmBridge(holder, validation.status, runtime) };
90
+ }
91
+ catch (error) {
92
+ if (required) {
93
+ throw error;
94
+ }
95
+ return {
96
+ wasmBinding: "not-mounted",
97
+ reason: error instanceof Error ? error.message : String(error)
98
+ };
99
+ }
100
+ }
101
+ function instanceSource(raw, wasmExports) {
102
+ const memory = wasmExports?.memory;
103
+ return memory instanceof WebAssembly.Memory ? { raw, memory } : { raw };
104
+ }
105
+ /**
106
+ * Compile the host-supplied source into a Module once, so every instance
107
+ * (the first and any replacement after a trap) instantiates from it.
108
+ */
109
+ async function compileWasmSource(source) {
110
+ if (source instanceof WebAssembly.Module) {
111
+ return { module: source, maximumBytes: XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES };
112
+ }
113
+ if (typeof source === "string" || source instanceof URL || (typeof Request === "function" && source instanceof Request)) {
114
+ return compileWasmSource(await fetch(source));
115
+ }
116
+ if (typeof Response === "function" && source instanceof Response) {
117
+ if (typeof WebAssembly.compileStreaming === "function") {
118
+ try {
119
+ const module = await WebAssembly.compileStreaming(source.clone());
120
+ return { module, maximumBytes: XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES };
121
+ }
122
+ catch {
123
+ // Wrong MIME type or no streaming support: compile from the bytes.
124
+ }
125
+ }
126
+ return compileWasmSource(await source.arrayBuffer());
127
+ }
128
+ let view;
129
+ if (source instanceof ArrayBuffer) {
130
+ view = new Uint8Array(source);
131
+ }
132
+ else if (ArrayBuffer.isView(source)) {
133
+ view = new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
134
+ }
135
+ else {
136
+ throw new TypeError("unsupported wasm source: expected a URL, Request, Response, BufferSource or WebAssembly.Module");
137
+ }
138
+ return {
139
+ module: await WebAssembly.compile(source),
140
+ maximumBytes: readWasmMemoryLimits(view)?.maximumBytes ?? XLSX_WASM_LINEAR_MEMORY_MAXIMUM_BYTES
141
+ };
142
+ }
@@ -0,0 +1,3 @@
1
+ {
2
+ "type": "module"
3
+ }
@@ -0,0 +1,42 @@
1
+
2
+ const _fmtCache = new Map();
3
+ function getFormatter(tz) {
4
+ let f = _fmtCache.get(tz);
5
+ if (!f) {
6
+ f = new Intl.DateTimeFormat('en-US', {
7
+ timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit',
8
+ hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23'
9
+ });
10
+ _fmtCache.set(tz, f);
11
+ }
12
+ return f;
13
+ }
14
+ export function ic_tz_validate(name) {
15
+ try { getFormatter(name); return true; }
16
+ catch(_) { return false; }
17
+ }
18
+ export function ic_tz_all() {
19
+ try {
20
+ const list = Intl.supportedValuesOf('timeZone');
21
+
22
+ const zones = new Set(list);
23
+
24
+ const extras = [ 'UTC', 'GMT' ];
25
+
26
+ for (const tz of extras) {
27
+ zones.add(tz);
28
+ }
29
+
30
+ return Array.from(zones);
31
+ } catch(e) {
32
+ // no support
33
+ console.log(e);
34
+ return [ ];
35
+ }
36
+ }
37
+ export function ic_tz_parts(ms, tz) {
38
+ const p = {};
39
+ for (const x of getFormatter(tz).formatToParts(new Date(ms))) p[x.type] = x.value | 0;
40
+ return [p.year, p.month, p.day, p.hour, p.minute, p.second];
41
+ }
42
+