@mocanvas/wasm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Symbio Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @mocanvas/wasm
+
+The Rust/WebAssembly engine behind [mocanvas](https://github.com/SYMBIO/mocanvas)
+and its TypeScript bridge. The engine owns the scene: it holds shape geometry,
+maintains a spatial index, hit-tests, culls to the viewport, tessellates and
+batches, and writes vertex/index/batch buffers into linear memory that the host
+uploads to the GPU by pointer — no per-frame copying.
+
+Most applications use `mocanvas` or `@mocanvas/editor` instead of this package
+directly. No React, no other dependencies.
+
+## Install
+
+```bash
+npm install @mocanvas/wasm
+```
+
+## Use
+
+```ts
+import { loadEngine } from "@mocanvas/wasm"
+
+const bridge = await loadEngine()
+
+// handle, kind, parent, z-lo, z-hi, flags, x, y, rotation, w, h
+bridge.cmd.upsert(1, 0, 0, 0, 0, 0, 0, 0, 0, 200, 120)
+bridge.cmd.setStyle(1, { fill: 0x4465e9ff, stroke: 0x000000ff, strokeWidth: 2, dash: 0, opacity: 1 })
+bridge.cmd.flush()
+
+const frame = bridge.frame({ x: 0, y: 0, z: 1 }, 800, 600)
+console.log(frame.drawn, frame.batches.length / 7)
+```
+
+## Loading the `.wasm` file
+
+`loadEngine()` needs no configuration in any bundler.
+
+With no argument it resolves the module as
+`new URL("../pkg/mocanvas_bg.wasm", import.meta.url)` — Vite, webpack 5 and
+Rollup all recognise that form and emit the file as an asset — then fetches it
+and checks the first four bytes are the WebAssembly magic number. The file is
+~256 KB and is fetched separately; it is deliberately not inlined into the
+JavaScript bundle.
+
+If those bytes are not a module, the URL is not usable: a dev server answering
+every unknown path with `index.html`, a 404 page, a JSON error. Rather than let
+a `CompileError: expected magic word 00 61 73 6d` escape, the loader falls back
+to a base64 copy of the engine that ships in the package, pulled in with a
+dynamic `import()` so it sits in its own chunk and is never downloaded on the
+happy path. It logs one warning when it does.
+
+### Avoiding the fallback
+
+The one common way to end up on that path is Vite's dependency optimizer, which
+pre-bundles with esbuild and rewrites `import.meta.url` without moving the
+asset. Excluding the package skips the extra download:
+
+```ts
+// vite.config.ts — an optimisation, not a requirement
+export default defineConfig({ optimizeDeps: { exclude: ["@mocanvas/wasm"] } })
+```
+
+`vite build` is unaffected either way: Rollup emits the `.wasm` as an asset and
+the URL resolves.
+
+### Pointing at the file yourself
+
+A bundler that does not understand `new URL(..., import.meta.url)` at all, or a
+setup that serves the asset from somewhere specific, can pass the location in.
+Copy or serve `node_modules/@mocanvas/wasm/pkg/mocanvas_bg.wasm` and pass its
+URL — or a `Response`, or the compiled bytes, or a `WebAssembly.Module`:
+
+```ts
+await loadEngine("/assets/mocanvas_bg.wasm")
+await loadEngine(fetch("/assets/mocanvas_bg.wasm"))
+```
+
+An explicit input is taken at face value: it is handed straight to the glue,
+with no validation and no fallback, so a wrong location surfaces as its own
+error instead of being papered over.
+
+### Node
+
+In Node `fetch` does not read `file:` URLs, so `loadEngine()` with no argument
+reaches the embedded copy (with the warning). For tests and scripts, load the
+bytes yourself instead:
+
+```ts
+import { readFileSync } from "node:fs"
+import { loadEngineSync } from "@mocanvas/wasm"
+
+const bridge = loadEngineSync(readFileSync("node_modules/@mocanvas/wasm/pkg/mocanvas_bg.wasm"))
+```
+
+The engine is a process-wide singleton: the first `loadEngine` call decides how
+the module is loaded, and later calls reuse it.
+
+ESM only.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import { Engine, InitInput, SyncInitInput } from '../pkg/mocanvas.js';
+export { Engine } from '../pkg/mocanvas.js';
+
+/**
+ * Typed loader and zero-copy bridge over the mocanvas WebAssembly engine.
+ *
+ * See docs/ARCHITECTURE.md → "Bridge ABI".
+ */
+
+/** Command opcodes; must match `crates/mocanvas-wasm/src/lib.rs::op`. */
+declare const OP: {
+    readonly UPSERT_SHAPE: 1;
+    readonly REMOVE_SHAPE: 2;
+    readonly SET_GEOMETRY: 3;
+    readonly SET_STYLE: 4;
+    readonly CLEAR: 5;
+    readonly SET_TEXTURE: 6;
+};
+/** Path opcodes; must match `mocanvas-geo::PathCmd`. */
+declare const PATH_OP: {
+    readonly MOVE: 0;
+    readonly LINE: 1;
+    readonly QUAD: 2;
+    readonly CUBIC: 3;
+    readonly CLOSE: 4;
+};
+/** Shape flags; must match `mocanvas-scene`. */
+declare const FLAG: {
+    readonly HIDDEN: number;
+    readonly LOCKED: number;
+    readonly OVERLAY: number;
+    readonly NO_FILL: number;
+    /** GPU-drawn and also reported to the DOM overlay (labels). */
+    readonly LABEL: number;
+    /** Descendants are clipped to this shape's page-space geometry AABB (frames). */
+    readonly CLIP: number;
+};
+/** Hit-test filter bits. */
+declare const HIT_FILTER: {
+    readonly INCLUDE_LOCKED: 1;
+    readonly INCLUDE_HIDDEN: 2;
+    readonly HOLLOW_ONLY: 4;
+};
+type Handle = number;
+interface CameraState {
+    /** Page-space offset. screen = (page + cam) * z */
+    x: number;
+    y: number;
+    z: number;
+}
+/** Floats per vertex in `FrameBuffers.vertices`: `x y u v r g b a`. */
+declare const VERTEX_FLOATS = 8;
+/** `u32` words per record in `FrameBuffers.batches`. */
+declare const BATCH_WORDS = 7;
+/** `u32` words per record in `FrameBuffers.overlay`. */
+declare const OVERLAY_WORDS = 10;
+/** Page-space clip rectangle `[minX, minY, maxX, maxY]`. */
+type ClipRect = [number, number, number, number];
+interface FrameBuffers {
+    /**
+     * Interleaved `x y u v r g b a` (8 floats) in page space; solid geometry has
+     * `u = v = 0`. View into WASM memory; valid until the next engine call.
+     */
+    vertices: Float32Array;
+    indices: Uint32Array;
+    /**
+     * `BATCH_WORDS` (7) words per batch: `firstIndex indexCount texture clipMinX
+     * clipMinY clipMaxX clipMaxY`. The clip words are f32 bits in page space; all
+     * four zero means unclipped. Texture 0 = solid color. A new batch starts
+     * whenever the texture or the clip rect changes — use `readBatch`.
+     */
+    batches: Uint32Array;
+    /**
+     * `OVERLAY_WORDS` (10) words per entry: `handle x y w h rot clipMinX clipMinY
+     * clipMaxX clipMaxY` with floats as bits — use `readOverlay`.
+     */
+    overlay: Uint32Array;
+    drawn: number;
+    culled: number;
+    /**
+     * Build counter, bumped only when the buffers are rebuilt. The vertex data is
+     * page-space and the camera is a shader uniform, so a moving camera alone does
+     * not change it: a backend that has already uploaded version `v` can skip the
+     * upload for as long as this reads `v`.
+     */
+    version: number;
+    /** Whether the call that produced this frame rebuilt the buffers. */
+    dirty: boolean;
+    /**
+     * Shapes were deferred by the per-frame tessellation budget and are drawn as
+     * flat placeholder quads meanwhile. Keep scheduling frames until this is false.
+     */
+    pending: boolean;
+}
+interface Batch {
+    firstIndex: number;
+    indexCount: number;
+    /** Host texture id, 0 = solid color. */
+    texture: number;
+    /** Page-space clip rect, or undefined when unclipped. */
+    clip?: ClipRect;
+}
+interface OverlayEntry {
+    handle: Handle;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rotation: number;
+    /** Page-space clip rect inherited from the nearest clipping ancestor, if any. */
+    clip?: ClipRect;
+}
+interface StyleWords {
+    /** 0xRRGGBBAA, alpha 0 = none */
+    fill: number;
+    stroke: number;
+    strokeWidth: number;
+    dash: number;
+    opacity: number;
+    /**
+     * Host texture id (0 or undefined = none). Not part of SET_STYLE; send it with
+     * `CommandWriter.setTexture`. When set, the fill is drawn as one textured quad
+     * over the shape's local bounds (uv 0..1), tinted white × opacity.
+     */
+    texture?: number;
+    /**
+     * Per-shape random seed (0 or undefined = 0). Only `dash: 3` (hand-drawn) reads
+     * it: it picks that shape's wobble, so the same seed always redraws the same
+     * outline. Derive it from the shape's stable id, never from its handle or its
+     * position in the scene, or a shape will change shape when it is re-added.
+     */
+    seed?: number;
+}
+/** Bit-cast a float to u32 without allocation. */
+declare function f32bits(v: number): number;
+/** Bit-cast a u32 to float without allocation. */
+declare function bitsf32(v: number): number;
+/** Four clip words (f32 bits) at `offset` → rect, or undefined when all zero (unclipped). */
+declare function readClip(words: Uint32Array, offset: number): ClipRect | undefined;
+/**
+ * Writes commands straight into the engine's command buffer in WASM memory.
+ * Call `flush()` once per store transaction.
+ */
+declare class CommandWriter {
+    private readonly engine;
+    private readonly memory;
+    private view;
+    private cap;
+    private len;
+    constructor(engine: Engine, memory: WebAssembly.Memory, initialWords?: number);
+    /** Words queued but not yet applied. */
+    get pending(): number;
+    private ensure;
+    upsert(handle: Handle, kind: number, parent: Handle, zlo: number, zhi: number, flags: number, x: number, y: number, rotation: number, w: number, h: number): void;
+    remove(handle: Handle): void;
+    /** `pathWords` is the flat f32 path encoding (opcode, args...). */
+    setGeometry(handle: Handle, pathWords: ArrayLike<number>): void;
+    setStyle(handle: Handle, s: StyleWords): void;
+    /** Set the fill texture of a shape (0 = solid fill). Independent of `setStyle`. */
+    setTexture(handle: Handle, texture: number): void;
+    clear(): void;
+    /** Apply queued commands. Returns the number of commands applied. Throws on a malformed stream. */
+    flush(): number;
+}
+/** High-level wrapper: owns the engine, the command writer, and typed views. */
+declare class EngineBridge {
+    readonly engine: Engine;
+    readonly memory: WebAssembly.Memory;
+    readonly cmd: CommandWriter;
+    /**
+     * Shapes the engine may tessellate in one `frame()` call; the rest are drawn as
+     * level-of-detail quads and picked up by later frames, which keeps a viewport
+     * full of never-seen shapes from stalling on one frame. Read from the engine so
+     * `mocanvas_render::DEFAULT_TESS_BUDGET` stays the single source of truth.
+     */
+    tessBudget: number;
+    private lastFrame;
+    constructor(engine: Engine, memory: WebAssembly.Memory);
+    get shapeCount(): number;
+    get epoch(): number;
+    /**
+     * Build (or reuse) the frame for a camera. `tessBudget` overrides
+     * {@link EngineBridge.tessBudget} for this call; pass `0` for no cap, which is
+     * what tests want when they need one deterministic frame.
+     *
+     * When the engine reports the buffers unchanged the previous `FrameBuffers`
+     * object is returned as-is, views included, so `frame.version` is a stable
+     * identity a backend can compare against what it last uploaded.
+     */
+    frame(cam: CameraState, viewportW: number, viewportH: number, tessBudget?: number): FrameBuffers;
+    /** Decode the overlay buffer of a frame. */
+    static readOverlay(overlay: Uint32Array): OverlayEntry[];
+    /** Decode one batch record starting at word `offset` (a multiple of `BATCH_WORDS`). */
+    static readBatch(batches: Uint32Array, offset: number): Batch;
+    /** Decode the batch buffer of a frame. */
+    static readBatches(batches: Uint32Array): Batch[];
+    /**
+     * Grow the box each frame is built for by `pad` (a fraction of the viewport size)
+     * on every side, so a camera panning inside that margin reuses the buffers instead
+     * of rebuilding and re-uploading them.
+     *
+     * Zero by default: the pad submits `(1 + 2 * pad)²` more geometry on every frame in
+     * exchange for skipping the upload on some of them, which only pays when the host's
+     * upload is expensive relative to its per-triangle cost. It is on a hardware GPU;
+     * it is emphatically not under software rasterisation.
+     */
+    setViewportPad(pad: number): void;
+    /** The current viewport pad. */
+    get viewportPad(): number;
+    hitTest(pageX: number, pageY: number, tolerance: number, filter?: number): Handle;
+    /** Handles in draw order. `mode` 0 = intersects, 1 = contains. Returns a copy. */
+    queryBox(minX: number, minY: number, maxX: number, maxY: number, mode?: 0 | 1, filter?: number): Uint32Array;
+    private readBox;
+    /**
+     * Ink page bounds `[minX, minY, maxX, maxY]` or null: the shape's outline
+     * expanded by half its stroke width. This is what the spatial index, the
+     * viewport cull and clipping run on. For a user-facing measurement of where
+     * the shape *is*, use {@link geometryBounds}.
+     */
+    bounds(handle: Handle): [number, number, number, number] | null;
+    /** Geometry page bounds `[minX, minY, maxX, maxY]` or null: `bounds` without the stroke pad. */
+    geometryBounds(handle: Handle): [number, number, number, number] | null;
+    unionBounds(handles: ArrayLike<number>): [number, number, number, number] | null;
+    /** Union of every shape's ink bounds, or null when the scene is empty. */
+    allBounds(): [number, number, number, number] | null;
+    /** Union of every shape's geometry bounds, or null when the scene is empty. */
+    allGeometryBounds(): [number, number, number, number] | null;
+    /** Page transform `[a b c d e f]` or null. */
+    pageTransform(handle: Handle): [number, number, number, number, number, number] | null;
+    dispose(): void;
+}
+/**
+ * Load the WASM module (once) and create an engine.
+ *
+ * With no argument the module is resolved as
+ * `new URL("../pkg/mocanvas_bg.wasm", import.meta.url)` — which Vite, webpack 5
+ * and Rollup all recognise: they emit the `.wasm` file as an asset and rewrite
+ * the URL — then fetched and checked for the WebAssembly magic number. If those
+ * bytes are not a module (a dev server's HTML fallback, a 404 page, a JSON
+ * error), an embedded base64 copy is used instead and a one-time warning is
+ * logged. No consumer configuration is required either way.
+ *
+ * Passing an input takes over completely: `loadEngine("/assets/mocanvas_bg.wasm")`,
+ * a `URL`, a `Response`, the compiled bytes or a `WebAssembly.Module` are handed
+ * to the glue as-is, with no validation and no fallback, so a mistake in the
+ * location you chose surfaces as its own error. See the package README.
+ */
+declare function loadEngine(input?: InitInput): Promise<EngineBridge>;
+/** Synchronous variant for tests / Node: pass the compiled bytes. */
+declare function loadEngineSync(bytes: SyncInitInput): EngineBridge;
+declare function engineVersion(): string;
+
+export { BATCH_WORDS, type Batch, type CameraState, type ClipRect, CommandWriter, EngineBridge, FLAG, type FrameBuffers, HIT_FILTER, type Handle, OP, OVERLAY_WORDS, type OverlayEntry, PATH_OP, type StyleWords, VERTEX_FLOATS, bitsf32, engineVersion, f32bits, loadEngine, loadEngineSync, readClip };