@kupcad/wasm 0.0.0-stage → 0.1.1

package/src/kupcad.js

@@ -0,0 +1,260 @@
+// The core in this thread: the module instantiated once, its exports given a typed face. Every
+// string and buffer goes in through `wasm_alloc` and is freed after the call; every result is
+// copied out and freed (`wasm_free`), and an export's null result is the core's refusal, its
+// message read from `get_last_error`.
+
+import { isCompatible, PROTOCOL_VERSION, ProtocolError, readFrame } from '@kupcad/protocol';
+import { KupcadCrashError, KupcadError } from './errors.js';
+import { packFiles } from './files.js';
+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' */
+
+/** 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). */
+const MAX_ERROR_BYTES = 1024;
+const DEFAULT_FORMAT = 'glb';
+/** What a call without files gives the core. */
+const NO_FILES = new Uint8Array();
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * A wasm32 pointer an export returned: a u32 that JavaScript gets as an i32, so an address
+ * past 2 GiB comes negative, as does an empty block's (0xFFFFFFFF, which `wasm_alloc(0)` gives).
+ * @param {number} ptr
+ */
+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]
+ * @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);
+  const wasi = createWasi(options.log ?? ((line) => console.debug(line)));
+  const instance = await WebAssembly.instantiate(module, {
+    wasi_snapshot_preview1: wasi.imports(module),
+  });
+  const exports = /** @type {KupcadExports} */ (/** @type {unknown} */ (instance.exports));
+  wasi.bind(exports.memory);
+  // oxlint-disable-next-line no-underscore-dangle -- the WASI reactor's initializer, by that name
+  exports._initialize();
+  return Kupcad.fromExports(exports);
+}
+
+/** @implements {KupcadApi} */
+export class Kupcad {
+  /**
+   * The core over a module a host instantiated itself (its own WASI, its own memory), once it
+   * is initialized.
+   * @param {KupcadExports} exports
+   * @returns {Promise<Kupcad>}
+   * @throws {ProtocolError} when the module speaks a protocol version this package doesn't read
+   */
+  static async fromExports(exports) {
+    const kupcad = new Kupcad(exports);
+    const { version, protocolVersion } = await kupcad.version();
+    if (!isCompatible(protocolVersion)) {
+      throw new ProtocolError(
+        `kupcad.wasm ${version} speaks protocol version ${protocolVersion}; this package reads version ${PROTOCOL_VERSION}`,
+      );
+    }
+    return kupcad;
+  }
+
+  /** @type {KupcadExports} */
+  #exports;
+  /** Where every export writes its result's length. */
+  #outLen;
+  /** Why the module can't be used again, once it stopped. @type {KupcadCrashError | null} */
+  #crashed = null;
+
+  /** @param {KupcadExports} exports an instantiated, initialized kupcad.wasm's */
+  constructor(exports) {
+    this.#exports = exports;
+    this.#outLen = address(exports.wasm_alloc(USIZE_BYTES));
+    if (this.#outLen === 0) throw new KupcadError('kupcad.wasm has no memory to start in');
+  }
+
+  /** The module's linear memory, in bytes: it grows as builds need, and stays grown. */
+  get memoryBytes() {
+    return this.#exports.memory.buffer.byteLength;
+  }
+
+  /**
+   * @param {string} source
+   * @param {PreviewOptions} [options]
+   * @returns {Promise<Preview>}
+   */
+  async preview(source, options = {}) {
+    options.signal?.throwIfAborted();
+    const params = options.params ? JSON.stringify(options.params) : '';
+    const files = options.files ? packFiles(options.files) : NO_FILES;
+    return this.#run(() =>
+      readFrame(
+        this.#withInputs([source, params, files], ([s, p, f]) =>
+          this.#take(
+            this.#exports.preview_wasm(s.ptr, s.len, p.ptr, p.len, f.ptr, f.len, this.#outLen),
+          ),
+        ),
+      ),
+    );
+  }
+
+  /**
+   * @param {string} source
+   * @param {BuildOptions} [options]
+   * @returns {Promise<Uint8Array>}
+   */
+  async build(source, options = {}) {
+    options.signal?.throwIfAborted();
+    const params = options.params ? JSON.stringify(options.params) : '';
+    const files = options.files ? packFiles(options.files) : NO_FILES;
+    const format = options.format ?? DEFAULT_FORMAT;
+    const draco = options.draco ? 1 : 0;
+    return this.#run(() =>
+      this.#withInputs([source, params, files, format], ([s, p, fs, f]) =>
+        this.#take(
+          this.#exports.build_model_wasm(
+            s.ptr,
+            s.len,
+            p.ptr,
+            p.len,
+            fs.ptr,
+            fs.len,
+            f.ptr,
+            f.len,
+            draco,
+            this.#outLen,
+          ),
+        ),
+      ),
+    );
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<Finding[]>}
+   */
+  async check(source, options = {}) {
+    options.signal?.throwIfAborted();
+    return this.#run(() => JSON.parse(this.#text(this.#exports.check_code_wasm, source)));
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<string>}
+   */
+  async format(source, options = {}) {
+    options.signal?.throwIfAborted();
+    return this.#run(() => this.#text(this.#exports.format_code_wasm, source));
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<UiSchema>}
+   */
+  async params(source, options = {}) {
+    options.signal?.throwIfAborted();
+    return this.#run(() => JSON.parse(this.#text(this.#exports.extract_params_wasm, source)));
+  }
+
+  /** @returns {Promise<VersionInfo>} */
+  async version() {
+    return this.#run(() =>
+      JSON.parse(decoder.decode(this.#take(this.#exports.version_wasm(this.#outLen)))),
+    );
+  }
+
+  /**
+   * Runs `work` unless the module stopped; a trap or an exit in it stops the module for good.
+   * @template T
+   * @param {() => T} work
+   * @returns {T}
+   */
+  #run(work) {
+    if (this.#crashed) throw this.#crashed;
+    try {
+      return work();
+    } catch (err) {
+      if (!(err instanceof WebAssembly.RuntimeError || err instanceof WasiExit)) throw err;
+      this.#crashed = new KupcadCrashError(`kupcad.wasm stopped: ${err.message}`, { cause: err });
+      throw this.#crashed;
+    }
+  }
+
+  /**
+   * The text an export of one source gives (check, format, params).
+   * @param {(source: number, sourceLen: number, outLen: number) => number} exported
+   * @param {string} source
+   * @returns {string}
+   */
+  #text(exported, source) {
+    return decoder.decode(
+      this.#withInputs([source], ([s]) => this.#take(exported(s.ptr, s.len, this.#outLen))),
+    );
+  }
+
+  /**
+   * Copies `inputs` into the module's memory for `call`, and frees them after.
+   * @template T
+   * @param {(string | Uint8Array)[]} inputs
+   * @param {(placed: { ptr: number, len: number }[]) => T} call
+   * @returns {T}
+   */
+  #withInputs(inputs, call) {
+    /** @type {{ ptr: number, len: number }[]} */
+    const placed = [];
+    try {
+      for (const input of inputs) {
+        const bytes = typeof input === 'string' ? encoder.encode(input) : input;
+        const ptr = address(this.#exports.wasm_alloc(bytes.byteLength));
+        if (ptr === 0)
+          throw new KupcadError(`kupcad.wasm has no room for ${bytes.byteLength} bytes`);
+        placed.push({ ptr, len: bytes.byteLength });
+        if (bytes.byteLength > 0) {
+          new Uint8Array(this.#exports.memory.buffer, ptr, bytes.byteLength).set(bytes);
+        }
+      }
+      return call(placed);
+    } finally {
+      for (const { ptr, len } of placed) this.#exports.wasm_free(ptr, len);
+    }
+  }
+
+  /**
+   * An export's result, copied out of the module's memory and freed there; its null is the
+   * core's refusal.
+   * @param {number} result
+   * @returns {Uint8Array}
+   */
+  #take(result) {
+    const ptr = address(result);
+    if (ptr === 0) throw new KupcadError(this.#lastError());
+    const len = new DataView(this.#exports.memory.buffer).getUint32(this.#outLen, true);
+    const bytes =
+      len > 0 ? new Uint8Array(this.#exports.memory.buffer, ptr, len).slice() : new Uint8Array();
+    this.#exports.wasm_free(ptr, len);
+    return bytes;
+  }
+
+  #lastError() {
+    const at = address(this.#exports.get_last_error());
+    const bytes = new Uint8Array(this.#exports.memory.buffer, at, MAX_ERROR_BYTES);
+    const end = bytes.indexOf(0);
+    return decoder.decode(bytes.subarray(0, end === -1 ? MAX_ERROR_BYTES : end));
+  }
+}

package/src/load.js

@@ -0,0 +1,36 @@
+// The compiled module from what a host gives: a compiled WebAssembly.Module, its bytes, a
+// fetch Response, or a URL (a `file:` one read from the disk in Node).
+
+import { readFile } from '#read-file';
+
+/** @import { WasmSource } from './types.js' */
+
+/**
+ * @param {WasmSource} source
+ * @returns {Promise<WebAssembly.Module>}
+ */
+export async function loadModule(source) {
+  if (source instanceof WebAssembly.Module) return source;
+  if (source instanceof ArrayBuffer || ArrayBuffer.isView(source))
+    return WebAssembly.compile(source);
+  if (source instanceof Response) return compileResponse(source);
+  const url = new URL(source, globalThis.location?.href);
+  if (url.protocol === 'file:') return WebAssembly.compile(await readFile(url));
+  return compileResponse(await fetch(url));
+}
+
+/**
+ * Compiles while it downloads when the server says it is wasm; compileStreaming refuses
+ * another content type, so then the bytes are compiled once they are all there.
+ * @param {Response} response
+ * @returns {Promise<WebAssembly.Module>}
+ */
+async function compileResponse(response) {
+  if (!response.ok) {
+    throw new Error(`kupcad.wasm: ${response.status} ${response.statusText} from ${response.url}`);
+  }
+  if (response.headers.get('content-type')?.startsWith('application/wasm')) {
+    return WebAssembly.compileStreaming(response);
+  }
+  return WebAssembly.compile(await response.arrayBuffer());
+}

package/src/read-file.browser.js

@@ -0,0 +1,12 @@
+// A browser can't read a `file:` URL (#read-file); a page gives the module by an http(s) URL,
+// its bytes or a compiled WebAssembly.Module.
+
+/**
+ * @param {URL} url
+ * @returns {Promise<Uint8Array<ArrayBuffer>>}
+ */
+export async function readFile(url) {
+  throw new Error(
+    `kupcad.wasm: a browser can't read ${url.href}; give the module by URL or as bytes`,
+  );
+}

package/src/read-file.node.js

@@ -0,0 +1,11 @@
+// Node's reader of a `file:` URL, for a module loaded from the disk (#read-file).
+
+import { readFile as readFromDisk } from 'node:fs/promises';
+
+/**
+ * @param {URL} url
+ * @returns {Promise<Uint8Array<ArrayBuffer>>}
+ */
+export async function readFile(url) {
+  return readFromDisk(url);
+}

package/src/serve.js

@@ -0,0 +1,84 @@
+// 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.
+
+import { createKupcad } 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' */
+
+/** @type {Record<Method, (kupcad: KupcadApi, args: any[]) => Promise<unknown>>} */
+const CALLS = {
+  preview: (kupcad, [source, options]) => kupcad.preview(source, options),
+  build: (kupcad, [source, options]) => kupcad.build(source, options),
+  check: (kupcad, [source]) => kupcad.check(source),
+  format: (kupcad, [source]) => kupcad.format(source),
+  params: (kupcad, [source]) => kupcad.params(source),
+  version: (kupcad) => kupcad.version(),
+};
+
+/**
+ * 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]
+ */
+export function serve(port, create = createKupcad) {
+  /** @type {Promise<KupcadApi> | null} */
+  let kupcad = null;
+  /** @param {FromWorker} message @param {Transferable[]} [transfer] */
+  const send = (message, transfer = []) => port.postMessage(message, transfer);
+
+  /** @param {Extract<ToWorker, { type: 'init' }>} init */
+  const start = ({ wasm }) => create({ wasm, log: (line) => send({ type: 'log', line }) });
+
+  /** @param {Extract<ToWorker, { type: 'call' }>} call */
+  const answer = async ({ id, method, args }) => {
+    /** @type {KupcadApi} */
+    let ready;
+    try {
+      if (!kupcad) throw new Error('the kupcad worker was called before it was given its module');
+      ready = await kupcad;
+    } catch (err) {
+      send({ type: 'reply', id, ok: false, error: sent(err, true) });
+      return;
+    }
+    try {
+      const value = await CALLS[method](ready, args);
+      send({ type: 'reply', id, ok: true, value }, transferOf(value));
+    } catch (err) {
+      send({ type: 'reply', id, ok: false, error: sent(err, err instanceof KupcadCrashError) });
+    }
+  };
+
+  port.addEventListener('message', ({ data }) => {
+    if (data.type === 'init') {
+      kupcad = start(data);
+      // A core that didn't start is told to each call, which awaits it
+      kupcad.catch(() => {});
+      return;
+    }
+    void answer(data);
+  });
+}
+
+/**
+ * @param {unknown} err
+ * @param {boolean} fatal
+ * @returns {SentError}
+ */
+function sent(err, fatal) {
+  if (err instanceof Error) return { name: err.name, message: err.message, fatal };
+  return { name: 'Error', message: String(err), fatal };
+}
+
+/**
+ * The buffers a result holds, to transfer: a build's bytes, a preview's GLB.
+ * @param {unknown} value
+ * @returns {Transferable[]}
+ */
+function transferOf(value) {
+  if (value instanceof Uint8Array) return [value.buffer];
+  const model = /** @type {Partial<Preview> | null} */ (value)?.model;
+  return model?.kind === '3d' ? [model.glb.buffer] : [];
+}

package/src/testing.js

@@ -0,0 +1,39 @@
+// 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 { Model, UiSchema } from '@kupcad/protocol/types' */
+/** @import { Kupcad } from './kupcad.js' */
+
+/** @type {Promise<Kupcad> | null} */
+let core = null;
+
+/**
+ * The core, made on first use, its log dropped.
+ * @returns {Promise<Kupcad>}
+ */
+export function testCore() {
+  core ??= createKupcad({ log: () => {} });
+  return core;
+}
+
+/**
+ * The model the core's preview of `source` shows.
+ * @param {string} source
+ * @returns {Promise<Model>}
+ */
+export async function modelOf(source) {
+  const { header, model } = await (await testCore()).preview(source);
+  if (header.error) throw new Error(`the test's script failed: ${header.error.message}`);
+  return model;
+}
+
+/**
+ * The schema of `source`'s parameters.
+ * @param {string} source
+ * @returns {Promise<UiSchema>}
+ */
+export async function schemaOf(source) {
+  return (await testCore()).params(source);
+}

package/src/types.d.ts

@@ -0,0 +1,141 @@
+// The shapes of @kupcad/wasm's API. What the core gives back is @kupcad/protocol's.
+
+import type {
+  ExportFormat,
+  Finding,
+  ParamValues,
+  Preview,
+  UiSchema,
+  VersionInfo,
+} from '@kupcad/protocol/types';
+
+/** Where the module comes from: compiled, its bytes, a fetch Response, or a URL. */
+export type WasmSource = WebAssembly.Module | BufferSource | Response | URL | string;
+
+/** What a call may be stopped by. */
+export interface CallOptions {
+  signal?: AbortSignal;
+}
+
+export interface PreviewOptions extends CallOptions {
+  /** The parameters' values; those not given take their defaults. */
+  params?: ParamValues;
+  /**
+   * The files the script reads, by the paths it names them by (`import { } from "./lib.kup"`
+   * reads `lib.kup`, `import_json("data/size.json")` reads `data/size.json`): a module it
+   * imports, data it reads. The core keeps them for this call alone.
+   */
+  files?: Record<string, Uint8Array | string>;
+}
+
+export interface BuildOptions extends PreviewOptions {
+  /** Default 'glb'. */
+  format?: ExportFormat;
+  /** Draco-compressed meshes, for glb and gltf. */
+  draco?: boolean;
+}
+
+export interface CreateOptions {
+  /** The module; by default the kupcad.wasm this package ships. */
+  wasm?: WasmSource;
+  /** Where the module's log goes, a line at a time (a failure is thrown too); by default console.debug. */
+  log?: (line: string) => void;
+}
+
+/** What both `createKupcad` and `createKupcadWorker` give. */
+export interface KupcadApi {
+  /** The script's preview frame: a run that fails, or values refused, is a frame saying why. */
+  preview(source: string, options?: PreviewOptions): Promise<Preview>;
+  /** The script's model written as `format`; a KupcadError says why it couldn't be. */
+  build(source: string, options?: BuildOptions): Promise<Uint8Array>;
+  /** `kupcad check`'s findings, syntax errors among them. */
+  check(source: string, options?: CallOptions): Promise<Finding[]>;
+  /** The source as `kupcad fmt` writes it; a KupcadError for one that doesn't parse. */
+  format(source: string, options?: CallOptions): Promise<string>;
+  /** The parameters' schema, as `kupcad doc` gives it, without running the script. */
+  params(source: string, options?: CallOptions): Promise<UiSchema>;
+  /** What the module says of itself. */
+  version(): Promise<VersionInfo>;
+}
+
+/** The exports of kupcad.wasm (core/src/wasm.zig). Pointers and lengths are byte offsets. */
+export interface KupcadExports {
+  memory: WebAssembly.Memory;
+  _initialize(): void;
+  wasm_alloc(len: number): number;
+  wasm_free(ptr: number, len: number): void;
+  get_last_error(): number;
+  preview_wasm(
+    source: number,
+    sourceLen: number,
+    params: number,
+    paramsLen: number,
+    files: number,
+    filesLen: number,
+    outLen: number,
+  ): number;
+  build_model_wasm(
+    source: number,
+    sourceLen: number,
+    params: number,
+    paramsLen: number,
+    files: number,
+    filesLen: number,
+    format: number,
+    formatLen: number,
+    draco: number,
+    outLen: number,
+  ): number;
+  check_code_wasm(source: number, sourceLen: number, outLen: number): number;
+  format_code_wasm(source: number, sourceLen: number, outLen: number): number;
+  extract_params_wasm(source: number, sourceLen: number, outLen: number): number;
+  version_wasm(outLen: number): number;
+}
+
+/** Where a worker's module comes from: what can be posted to it (not a Response). */
+export type WorkerWasmSource = Exclude<WasmSource, Response>;
+
+export interface WorkerOptions extends Omit<CreateOptions, 'wasm'> {
+  /** The module; by default the kupcad.wasm this package ships. A relative URL is the page's. */
+  wasm?: WorkerWasmSource;
+  /** Starts a worker running src/worker.js; by default a module Web Worker. */
+  worker?: () => WorkerLike;
+}
+
+/** What a client calls the worker's core with: the methods of KupcadApi. */
+export type Method = 'preview' | 'build' | 'check' | 'format' | 'params' | 'version';
+
+/** A failure, as it crosses to the client: `fatal` when the worker's core can't go on. */
+export interface SentError {
+  name: string;
+  message: string;
+  fatal: boolean;
+}
+
+export type ToWorker =
+  | {
+      type: 'init';
+      /** A URL as its href. */
+      wasm: Exclude<WorkerWasmSource, URL> | undefined;
+    }
+  | { type: 'call'; id: number; method: Method; args: unknown[] };
+
+export type FromWorker =
+  | { type: 'reply'; id: number; ok: true; value: unknown }
+  | { type: 'reply'; id: number; ok: false; error: SentError }
+  | { type: 'log'; line: string };
+
+/** The client's end of a worker: a Web Worker, or a stand-in in tests. */
+export interface WorkerLike {
+  postMessage(message: ToWorker): void;
+  addEventListener(type: 'message', listener: (event: MessageEvent<FromWorker>) => void): void;
+  addEventListener(type: 'error', listener: (event: ErrorEvent) => void): void;
+  addEventListener(type: 'messageerror', listener: (event: MessageEvent) => void): void;
+  terminate(): void;
+}
+
+/** The worker's end: its global scope, or a MessagePort in tests. */
+export interface PortLike {
+  postMessage(message: FromWorker, transfer?: Transferable[]): void;
+  addEventListener(type: 'message', listener: (event: MessageEvent<ToWorker>) => void): void;
+}