@kupcad/wasm 0.1.0 → 0.1.2

package/README.md

@@ -38,7 +38,9 @@ Both take `wasm` (the module: a URL, its bytes or a compiled `WebAssembly.Module
 `createKupcad` a fetch `Response` too, which can't be posted to a worker; by default the
 `kupcad.wasm` this package ships) and `log` (where the module's log goes, a line at a time; by
 default `console.debug`). A worker is given a relative URL resolved against the page, as the
-page means it.
+page means it. The worker is always handed its module, this package's by default: only the
+page's side names the shipped `kupcad.wasm` (`src/create.js`), so a site's bundler, which copies
+the file for each bundle that names it, ships it once rather than once more for the worker.
 
 ## What a call can fail with
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kupcad/wasm",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The KupCAD core compiled to WebAssembly: preview, build, check, format and read the parameters of a script in the browser or Node, directly or in a Web Worker.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@kupcad/protocol": "0.1.0"
+    "@kupcad/protocol": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",

package/src/client.js

@@ -1,9 +1,11 @@
 // The core in a Web Worker, with createKupcad's API: a long build runs there and the page goes
 // on. Calls run one at a time, the next waiting its turn. A call's AbortSignal drops it while
 // it waits, and stops the worker while it runs: the worker is replaced on the next call, as
-// one that crashed is.
+// one that crashed is. The worker is given its module, this package's unless the host's: the
+// page's side alone names it (create.js), so a site's bundler copies it once.
 
 import { ProtocolError } from '@kupcad/protocol';
+import { DEFAULT_WASM } from './create.js';
 import { KupcadCrashError, KupcadError } from './errors.js';
 
 /** @import { Finding, Preview, UiSchema, VersionInfo } from '@kupcad/protocol/types' */
@@ -55,7 +57,7 @@ export class KupcadWorker {
   /** @param {WorkerOptions} options */
   constructor(options) {
     this.#spawn = options.worker ?? moduleWorker;
-    this.#wasm = postable(options.wasm);
+    this.#wasm = postable(options.wasm ?? DEFAULT_WASM);
     this.#log = options.log ?? ((line) => console.debug(line));
   }
 
@@ -267,7 +269,7 @@ export class KupcadWorker {
 /**
  * The module as the worker is given it: a URL as its href, a relative one resolved against the
  * page (the worker would resolve it against its own script's).
- * @param {WorkerWasmSource | undefined} wasm
+ * @param {WorkerWasmSource} wasm
  * @returns {Extract<ToWorker, { type: 'init' }>['wasm']}
  */
 function postable(wasm) {

package/src/create.js

@@ -0,0 +1,23 @@
+// The module this package ships, and createKupcad, which runs it in this thread by default. The
+// module's URL is named here alone, in what only the page's side of the package loads (this and
+// the client, which hands it to its worker): a site's bundler copies kupcad.wasm for each bundle
+// that names it, so the worker, given its module, names none, and a site ships the file once.
+
+import { instantiateKupcad } from './kupcad.js';
+
+/** @import { CreateOptions } from './types.js' */
+/** @import { Kupcad } from './kupcad.js' */
+
+/** The module this package ships, built by core/build.zig and copied in by `pnpm build`. */
+export const DEFAULT_WASM = new URL('../dist/kupcad.wasm', import.meta.url);
+
+/**
+ * The core, instantiated in this thread: on `options.wasm`, else on the module this package
+ * ships. A long build blocks it: a page runs the core in a worker (`createKupcadWorker`).
+ * @param {CreateOptions} [options]
+ * @returns {Promise<Kupcad>}
+ * @throws {ProtocolError} when the module speaks a protocol version this package doesn't read
+ */
+export function createKupcad(options = {}) {
+  return instantiateKupcad({ ...options, wasm: options.wasm ?? DEFAULT_WASM });
+}

package/src/index.js

@@ -1,6 +1,7 @@
 // @kupcad/wasm: the core compiled to WebAssembly, in this thread (createKupcad) or in a Web
 // Worker (createKupcadWorker), with one API.
 
-export { createKupcad, Kupcad } from './kupcad.js';
+export { createKupcad } from './create.js';
+export { Kupcad } from './kupcad.js';
 export { createKupcadWorker } from './client.js';
 export { KupcadCrashError, KupcadError } from './errors.js';

package/src/kupcad.js

@@ -10,10 +10,8 @@ import { loadModule } from './load.js';
 import { createWasi, WasiExit } from './wasi.js';
 
 /** @import { Finding, Preview, UiSchema, VersionInfo } from '@kupcad/protocol/types' */
-/** @import { BuildOptions, CallOptions, CreateOptions, KupcadApi, KupcadExports, PreviewOptions } from './types.js' */
+/** @import { BuildOptions, CallOptions, CreateOptions, KupcadApi, KupcadExports, PreviewOptions, WasmSource } from './types.js' */
 
-/** The module this package ships, built by core/build.zig and copied in by `pnpm build`. */
-const DEFAULT_WASM = new URL('../dist/kupcad.wasm', import.meta.url);
 /** A `usize` of wasm32: the slot an export writes its result's length to. */
 const USIZE_BYTES = 4;
 /** The longest message get_last_error holds (core/src/wasm.zig's MAX_ERROR_MSG_LEN). */
@@ -33,14 +31,15 @@ const decoder = new TextDecoder();
 const address = (ptr) => ptr >>> 0;
 
 /**
- * The core, instantiated in this thread. A long build blocks it: a page runs the core in a
- * worker (`createKupcadWorker`).
- * @param {CreateOptions} [options]
+ * The core, instantiated in this thread from the module `wasm`: createKupcad's, which names the
+ * module this package ships, and the worker's, which is given its module. Naming none here keeps
+ * the shipped module's URL out of the worker's bundle (create.js).
+ * @param {CreateOptions & { wasm: WasmSource }} options
  * @returns {Promise<Kupcad>}
  * @throws {ProtocolError} when the module speaks a protocol version this package doesn't read
  */
-export async function createKupcad(options = {}) {
-  const module = await loadModule(options.wasm ?? DEFAULT_WASM);
+export async function instantiateKupcad(options) {
+  const module = await loadModule(options.wasm);
   const wasi = createWasi(options.log ?? ((line) => console.debug(line)));
   const instance = await WebAssembly.instantiate(module, {
     wasi_snapshot_preview1: wasi.imports(module),

package/src/serve.js

@@ -1,11 +1,12 @@
-// The worker's side: the core instantiated in the worker, answering the client's calls on
-// `port` in the order they come. A result's buffer is transferred, not copied.
+// The worker's side: the core instantiated in the worker on the module the client gives it,
+// answering the client's calls on `port` in the order they come. A result's buffer is
+// transferred, not copied.
 
-import { createKupcad } from './kupcad.js';
+import { instantiateKupcad } from './kupcad.js';
 import { KupcadCrashError } from './errors.js';
 
 /** @import { Preview } from '@kupcad/protocol/types' */
-/** @import { CreateOptions, FromWorker, KupcadApi, Method, PortLike, SentError, ToWorker } from './types.js' */
+/** @import { CreateOptions, FromWorker, KupcadApi, Method, PortLike, SentError, ToWorker, WasmSource } from './types.js' */
 
 /** @type {Record<Method, (kupcad: KupcadApi, args: any[]) => Promise<unknown>>} */
 const CALLS = {
@@ -21,9 +22,9 @@ const CALLS = {
  * Serves the core on `port`: an `init` message makes it (`create`, the module given), and each
  * `call` is answered with a `reply`. The core's log goes as `log` messages.
  * @param {PortLike} port
- * @param {(options: CreateOptions) => Promise<KupcadApi>} [create]
+ * @param {(options: CreateOptions & { wasm: WasmSource }) => Promise<KupcadApi>} [create]
  */
-export function serve(port, create = createKupcad) {
+export function serve(port, create = instantiateKupcad) {
   /** @type {Promise<KupcadApi> | null} */
   let kupcad = null;
   /** @param {FromWorker} message @param {Transferable[]} [transfer] */

package/src/testing.js

@@ -1,7 +1,7 @@
 // For the tests of a package that shows what the core makes: the real module, made once a test
 // process and silent, and what it gives of a script. A script that fails fails the test.
 
-import { createKupcad } from './kupcad.js';
+import { createKupcad } from './create.js';
 
 /** @import { Model, UiSchema } from '@kupcad/protocol/types' */
 /** @import { Kupcad } from './kupcad.js' */

package/src/types.d.ts

@@ -115,8 +115,8 @@ export interface SentError {
 export type ToWorker =
   | {
       type: 'init';
-      /** A URL as its href. */
-      wasm: Exclude<WorkerWasmSource, URL> | undefined;
+      /** The module (a URL as its href): the host's, else the one the package ships. */
+      wasm: Exclude<WorkerWasmSource, URL>;
     }
   | { type: 'call'; id: number; method: Method; args: unknown[] };