@lib3mf-rs/lib3mf-wasm 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# lib3mf-wasm
+
+WebAssembly bindings for `lib3mf-rs`.
+
+Allows running 3MF validation, parsing, and analysis directly in the browser.
+
+## Building
+
+```bash
+wasm-pack build --target web
+```

package/lib3mf_wasm.d.ts

@@ -0,0 +1,189 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * WebAssembly wrapper around the core 3MF Model.
+ *
+ * This struct provides JavaScript-accessible methods for working with 3MF files
+ * in the browser. It wraps [`lib3mf_core::Model`] and exposes a subset of its
+ * functionality through WASM bindings.
+ *
+ * # Primary API Surface
+ *
+ * The main way to use this from JavaScript:
+ *
+ * 1. Parse a 3MF file from bytes using [`WasmModel::from_bytes()`]
+ * 2. Query model properties: [`unit()`](WasmModel::unit), [`object_count()`](WasmModel::object_count)
+ *
+ * # JavaScript Usage
+ *
+ * ```javascript
+ * const model = WasmModel.from_bytes(fileBytes);
+ * console.log(`Unit: ${model.unit()}`);
+ * console.log(`Objects: ${model.object_count()}`);
+ * ```
+ *
+ * # Full Workflow Example
+ *
+ * ```javascript
+ * import init, { WasmModel, set_panic_hook } from './lib3mf_wasm.js';
+ *
+ * await init();
+ * set_panic_hook();
+ *
+ * // Load from file input
+ * const file = document.getElementById('file-input').files[0];
+ * const buffer = await file.arrayBuffer();
+ * const model = WasmModel.from_bytes(new Uint8Array(buffer));
+ *
+ * // Display basic info
+ * document.getElementById('unit').textContent = model.unit();
+ * document.getElementById('count').textContent = model.object_count();
+ * ```
+ */
+export class WasmModel {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Parse a 3MF file from a byte array (e.g. from a file upload).
+     *
+     * This is the primary way to load 3MF files in the browser. It handles the full
+     * parsing pipeline:
+     *
+     * 1. Interprets bytes as a ZIP archive
+     * 2. Parses OPC relationships to locate the model XML
+     * 3. Parses the XML into the in-memory model structure
+     * 4. Returns a [`WasmModel`] ready for inspection
+     *
+     * # Arguments
+     *
+     * * `data` - The bytes of the .3mf file (ZIP archive). Typically obtained from a
+     *   browser file input via `FileReader` or `File.arrayBuffer()`.
+     *
+     * # Returns
+     *
+     * Returns a [`WasmModel`] on success, or throws a JavaScript error on failure.
+     *
+     * # Errors
+     *
+     * This function can fail in several ways:
+     *
+     * - **Invalid ZIP**: The bytes don't represent a valid ZIP archive
+     * - **Missing model part**: The archive lacks a valid OPC relationship to a 3D model
+     * - **Malformed XML**: The model XML is invalid or doesn't conform to the 3MF schema
+     * - **Parser errors**: Semantic errors in the 3MF structure (invalid references, etc.)
+     *
+     * Errors are returned as JavaScript exceptions with descriptive messages.
+     *
+     * # Example (Rust)
+     *
+     * ```ignore
+     * use lib3mf_wasm::WasmModel;
+     *
+     * let file_bytes = std::fs::read("model.3mf")?;
+     * let model = WasmModel::from_bytes(&file_bytes)?;
+     * ```
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * try {
+     *     const buffer = await file.arrayBuffer();
+     *     const model = WasmModel.from_bytes(new Uint8Array(buffer));
+     *     console.log("Parsed successfully");
+     * } catch (error) {
+     *     console.error(`Parse failed: ${error}`);
+     * }
+     * ```
+     */
+    static from_bytes(data: Uint8Array): WasmModel;
+    /**
+     * Create a new empty 3MF Model.
+     *
+     * This creates a model with default values (millimeters unit, no objects, empty build).
+     * In most cases, you should use [`WasmModel::from_bytes()`] instead to parse an existing
+     * 3MF file.
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const model = new WasmModel();
+     * // Model is empty - unit is Millimeter by default
+     * ```
+     *
+     * # Note
+     *
+     * This constructor has limited utility since the WASM bindings don't currently expose
+     * model-building APIs. It's primarily for internal use and testing.
+     */
+    constructor();
+    /**
+     * Get the total number of objects in the model resources.
+     *
+     * This counts all objects in the model's resource collection, not just
+     * objects referenced by build items.
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const count = model.object_count();
+     * console.log(`Model contains ${count} objects`);
+     * ```
+     *
+     * # Note
+     *
+     * Build items may reference the same object multiple times (instances),
+     * so the number of build items may differ from the object count.
+     */
+    object_count(): number;
+    /**
+     * Get the unit of measurement used in the model.
+     *
+     * Returns the unit as a string for display in JavaScript.
+     *
+     * # Possible Return Values
+     *
+     * - `"Millimeter"` (default, most common)
+     * - `"Centimeter"`
+     * - `"Inch"`
+     * - `"Foot"`
+     * - `"Meter"`
+     * - `"MicroMeter"`
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const unit = model.unit();
+     * console.log(`Model uses ${unit} units`);
+     * ```
+     */
+    unit(): string;
+}
+
+/**
+ * Set up better panic messages for debugging in browser console.
+ *
+ * This function configures the panic hook to provide detailed error messages
+ * when the WASM module panics. Without this, panics will show generic
+ * "unreachable executed" messages that are difficult to debug.
+ *
+ * # When to Call
+ *
+ * Call this once during initialization, before any other API calls:
+ *
+ * ```javascript
+ * import init, { set_panic_hook } from './lib3mf_wasm.js';
+ *
+ * await init();
+ * set_panic_hook();  // Call once at startup
+ *
+ * // Now make other API calls...
+ * ```
+ *
+ * # Performance
+ *
+ * This adds a small amount of overhead to panics, but has no impact on normal
+ * execution. It's recommended for development builds but can be omitted in
+ * production if you want minimal bundle size.
+ */
+export function set_panic_hook(): void;

package/lib3mf_wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./lib3mf_wasm.d.ts" */
+
+import * as wasm from "./lib3mf_wasm_bg.wasm";
+import { __wbg_set_wasm } from "./lib3mf_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    WasmModel, set_panic_hook
+} from "./lib3mf_wasm_bg.js";

package/lib3mf_wasm_bg.js

@@ -0,0 +1,382 @@
+/**
+ * WebAssembly wrapper around the core 3MF Model.
+ *
+ * This struct provides JavaScript-accessible methods for working with 3MF files
+ * in the browser. It wraps [`lib3mf_core::Model`] and exposes a subset of its
+ * functionality through WASM bindings.
+ *
+ * # Primary API Surface
+ *
+ * The main way to use this from JavaScript:
+ *
+ * 1. Parse a 3MF file from bytes using [`WasmModel::from_bytes()`]
+ * 2. Query model properties: [`unit()`](WasmModel::unit), [`object_count()`](WasmModel::object_count)
+ *
+ * # JavaScript Usage
+ *
+ * ```javascript
+ * const model = WasmModel.from_bytes(fileBytes);
+ * console.log(`Unit: ${model.unit()}`);
+ * console.log(`Objects: ${model.object_count()}`);
+ * ```
+ *
+ * # Full Workflow Example
+ *
+ * ```javascript
+ * import init, { WasmModel, set_panic_hook } from './lib3mf_wasm.js';
+ *
+ * await init();
+ * set_panic_hook();
+ *
+ * // Load from file input
+ * const file = document.getElementById('file-input').files[0];
+ * const buffer = await file.arrayBuffer();
+ * const model = WasmModel.from_bytes(new Uint8Array(buffer));
+ *
+ * // Display basic info
+ * document.getElementById('unit').textContent = model.unit();
+ * document.getElementById('count').textContent = model.object_count();
+ * ```
+ */
+export class WasmModel {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmModel.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmModelFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmModelFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmmodel_free(ptr, 0);
+    }
+    /**
+     * Parse a 3MF file from a byte array (e.g. from a file upload).
+     *
+     * This is the primary way to load 3MF files in the browser. It handles the full
+     * parsing pipeline:
+     *
+     * 1. Interprets bytes as a ZIP archive
+     * 2. Parses OPC relationships to locate the model XML
+     * 3. Parses the XML into the in-memory model structure
+     * 4. Returns a [`WasmModel`] ready for inspection
+     *
+     * # Arguments
+     *
+     * * `data` - The bytes of the .3mf file (ZIP archive). Typically obtained from a
+     *   browser file input via `FileReader` or `File.arrayBuffer()`.
+     *
+     * # Returns
+     *
+     * Returns a [`WasmModel`] on success, or throws a JavaScript error on failure.
+     *
+     * # Errors
+     *
+     * This function can fail in several ways:
+     *
+     * - **Invalid ZIP**: The bytes don't represent a valid ZIP archive
+     * - **Missing model part**: The archive lacks a valid OPC relationship to a 3D model
+     * - **Malformed XML**: The model XML is invalid or doesn't conform to the 3MF schema
+     * - **Parser errors**: Semantic errors in the 3MF structure (invalid references, etc.)
+     *
+     * Errors are returned as JavaScript exceptions with descriptive messages.
+     *
+     * # Example (Rust)
+     *
+     * ```ignore
+     * use lib3mf_wasm::WasmModel;
+     *
+     * let file_bytes = std::fs::read("model.3mf")?;
+     * let model = WasmModel::from_bytes(&file_bytes)?;
+     * ```
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * try {
+     *     const buffer = await file.arrayBuffer();
+     *     const model = WasmModel.from_bytes(new Uint8Array(buffer));
+     *     console.log("Parsed successfully");
+     * } catch (error) {
+     *     console.error(`Parse failed: ${error}`);
+     * }
+     * ```
+     * @param {Uint8Array} data
+     * @returns {WasmModel}
+     */
+    static from_bytes(data) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmmodel_from_bytes(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WasmModel.__wrap(ret[0]);
+    }
+    /**
+     * Create a new empty 3MF Model.
+     *
+     * This creates a model with default values (millimeters unit, no objects, empty build).
+     * In most cases, you should use [`WasmModel::from_bytes()`] instead to parse an existing
+     * 3MF file.
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const model = new WasmModel();
+     * // Model is empty - unit is Millimeter by default
+     * ```
+     *
+     * # Note
+     *
+     * This constructor has limited utility since the WASM bindings don't currently expose
+     * model-building APIs. It's primarily for internal use and testing.
+     */
+    constructor() {
+        const ret = wasm.wasmmodel_new();
+        this.__wbg_ptr = ret >>> 0;
+        WasmModelFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Get the total number of objects in the model resources.
+     *
+     * This counts all objects in the model's resource collection, not just
+     * objects referenced by build items.
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const count = model.object_count();
+     * console.log(`Model contains ${count} objects`);
+     * ```
+     *
+     * # Note
+     *
+     * Build items may reference the same object multiple times (instances),
+     * so the number of build items may differ from the object count.
+     * @returns {number}
+     */
+    object_count() {
+        const ret = wasm.wasmmodel_object_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Get the unit of measurement used in the model.
+     *
+     * Returns the unit as a string for display in JavaScript.
+     *
+     * # Possible Return Values
+     *
+     * - `"Millimeter"` (default, most common)
+     * - `"Centimeter"`
+     * - `"Inch"`
+     * - `"Foot"`
+     * - `"Meter"`
+     * - `"MicroMeter"`
+     *
+     * # JavaScript Usage
+     *
+     * ```javascript
+     * const unit = model.unit();
+     * console.log(`Model uses ${unit} units`);
+     * ```
+     * @returns {string}
+     */
+    unit() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmmodel_unit(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) WasmModel.prototype[Symbol.dispose] = WasmModel.prototype.free;
+
+/**
+ * Set up better panic messages for debugging in browser console.
+ *
+ * This function configures the panic hook to provide detailed error messages
+ * when the WASM module panics. Without this, panics will show generic
+ * "unreachable executed" messages that are difficult to debug.
+ *
+ * # When to Call
+ *
+ * Call this once during initialization, before any other API calls:
+ *
+ * ```javascript
+ * import init, { set_panic_hook } from './lib3mf_wasm.js';
+ *
+ * await init();
+ * set_panic_hook();  // Call once at startup
+ *
+ * // Now make other API calls...
+ * ```
+ *
+ * # Performance
+ *
+ * This adds a small amount of overhead to panics, but has no impact on normal
+ * execution. It's recommended for development builds but can be omitted in
+ * production if you want minimal bundle size.
+ */
+export function set_panic_hook() {
+    wasm.set_panic_hook();
+}
+export function __wbg_Error_8c4e43fe74559d73(arg0, arg1) {
+    const ret = Error(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
+export function __wbg___wbindgen_throw_be289d5034ed271b(arg0, arg1) {
+    throw new Error(getStringFromWasm0(arg0, arg1));
+}
+export function __wbg_error_7534b8e9a36f1ab4(arg0, arg1) {
+    let deferred0_0;
+    let deferred0_1;
+    try {
+        deferred0_0 = arg0;
+        deferred0_1 = arg1;
+        console.error(getStringFromWasm0(arg0, arg1));
+    } finally {
+        wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+    }
+}
+export function __wbg_new_8a6f238a6ece86ea() {
+    const ret = new Error();
+    return ret;
+}
+export function __wbg_stack_0ed75d68575b0f3c(arg0, arg1) {
+    const ret = arg1.stack;
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbindgen_init_externref_table() {
+    const table = wasm.__wbindgen_externrefs;
+    const offset = table.grow(4);
+    table.set(0, undefined);
+    table.set(offset + 0, undefined);
+    table.set(offset + 1, null);
+    table.set(offset + 2, true);
+    table.set(offset + 3, false);
+}
+const WasmModelFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmmodel_free(ptr >>> 0, 1));
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+
+let wasm;
+export function __wbg_set_wasm(val) {
+    wasm = val;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@lib3mf-rs/lib3mf-wasm",
+  "type": "module",
+  "collaborators": [
+    "Steve Scargall <steve@example.com>"
+  ],
+  "description": "WebAssembly bindings for lib3mf-rs",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sscargal/lib3mf-rs"
+  },
+  "files": [
+    "lib3mf_wasm_bg.wasm",
+    "lib3mf_wasm.js",
+    "lib3mf_wasm_bg.js",
+    "lib3mf_wasm.d.ts"
+  ],
+  "main": "lib3mf_wasm.js",
+  "types": "lib3mf_wasm.d.ts",
+  "sideEffects": [
+    "./lib3mf_wasm.js",
+    "./snippets/*"
+  ]
+}