@viewscript/wasm 0.1.0-202605140639

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@viewscript/wasm",
+  "type": "module",
+  "version": "0.1.0-202605140639",
+  "license": "MIT OR Apache-2.0",
+  "files": [
+    "vsc_wasm_bg.wasm",
+    "vsc_wasm.js",
+    "vsc_wasm.d.ts"
+  ],
+  "main": "vsc_wasm.js",
+  "types": "vsc_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/vsc_wasm.d.ts

@@ -0,0 +1,373 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * WebGPU surface manager for browser environment.
+ *
+ * This struct manages the WebGPU surface lifecycle for browser rendering.
+ * It does NOT contain a `GpuRenderer` - rendering is delegated to `WebTarget`.
+ *
+ * ## Responsibilities
+ *
+ * - Surface creation and configuration
+ * - Surface texture acquisition (`surface_texture_view()`)
+ * - Resize handling
+ * - Device/queue sharing with `WebTarget`
+ */
+export class WasmGpuRenderer {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Create a new WebGPU renderer bound to a canvas element.
+     *
+     * This is an async operation that:
+     * 1. Requests a GPU adapter from the browser
+     * 2. Requests a device and queue from the adapter
+     * 3. Creates a surface from the canvas element
+     * 4. Configures the surface for rendering
+     *
+     * # Arguments
+     *
+     * * `canvas` - The HTML canvas element to render to
+     *
+     * # Returns
+     *
+     * A `Promise` that resolves to `WasmGpuRenderer` or rejects with an error.
+     */
+    static create(canvas: HTMLCanvasElement): Promise<WasmGpuRenderer>;
+    /**
+     * Resize the rendering surface.
+     *
+     * Call this when the canvas element is resized.
+     *
+     * # Arguments
+     *
+     * * `width` - New width in device pixels
+     * * `height` - New height in device pixels
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Get the current height in device pixels.
+     */
+    readonly height: number;
+    /**
+     * Get the current width in device pixels.
+     */
+    readonly width: number;
+}
+
+/**
+ * ViewScript rendering engine for browser environment.
+ *
+ * This struct integrates the full rendering pipeline:
+ * - `ConstraintSolver`: Evaluates P-dimension constraints
+ * - `VsBuildInfo`: Event-sourcing ledger for constraint operations
+ * - `SceneBuilder`: Converts solver output to scene graph
+ * - `SceneConverter`: Converts scene graph to canvas nodes with topology rounding
+ * - `WasmGpuRenderer`: WebGPU-based rendering to canvas
+ *
+ * ## Architecture
+ *
+ * ```text
+ * TypeScript                    WASM Boundary                     Rust
+ * ─────────────────────────────────────────────────────────────────────────────
+ * const engine =                wasm-bindgen
+ *   await WasmViewScriptEngine   ─────────────►  WasmViewScriptEngine::create()
+ *     .create(canvas, dpr);                              │
+ *                                                        ▼
+ * engine.add_component(...)     ─────────────►  add_component() → VsBuildInfo
+ *                                                        │
+ *                                                        ▼
+ * engine.tick(mutations_json)   ─────────────►  tick()
+ *                                                │
+ *                                                ├─► Apply mutations (T-vector)
+ *                                                ├─► ConstraintSolver.solve()
+ *                                                ├─► SceneBuilder.build_scene()
+ *                                                ├─► SceneConverter.convert_with_rounding()
+ *                                                └─► WasmGpuRenderer.render_nodes()
+ * ```
+ *
+ * ## Mutation Format (JSON)
+ *
+ * ```typescript
+ * // Translate: move component by delta
+ * engine.tick(JSON.stringify([
+ *   { type: "Translate", entity_id: 1000, dx: 10, dy: 5 }
+ * ]));
+ *
+ * // SetPosition: move component to absolute position
+ * engine.tick(JSON.stringify([
+ *   { type: "SetPosition", entity_id: 1000, x: 200, y: 150 }
+ * ]));
+ * ```
+ *
+ * ## Usage (TypeScript)
+ *
+ * ```typescript
+ * import init, { WasmViewScriptEngine } from 'vsc-wasm';
+ *
+ * await init();
+ *
+ * const canvas = document.getElementById('viewport') as HTMLCanvasElement;
+ * const engine = await WasmViewScriptEngine.create(canvas, window.devicePixelRatio);
+ *
+ * // Add a rounded rectangle component
+ * engine.add_component('RoundedRect', JSON.stringify({
+ *   x: 100, y: 100, width: 200, height: 150, radius: 20, fill: '#ff0000'
+ * }));
+ *
+ * // Animation loop
+ * function animate() {
+ *   engine.tick('[]'); // Empty mutations for static content
+ *   requestAnimationFrame(animate);
+ * }
+ * animate();
+ * ```
+ */
+export class WasmViewScriptEngine {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add a component to the scene.
+     *
+     * This method creates the necessary path entities and control points
+     * in the VsBuildInfo ledger based on the component type.
+     *
+     * # Arguments
+     *
+     * * `component_type` - Type of component: "RoundedRect", "Circle", "Path", etc.
+     * * `params_json` - JSON object with component parameters
+     *
+     * # Example JSON for RoundedRect
+     *
+     * ```json
+     * {
+     *   "x": 100,
+     *   "y": 100,
+     *   "width": 200,
+     *   "height": 150,
+     *   "radius": 20,
+     *   "fill": "#ff0000"
+     * }
+     * ```
+     *
+     * # Returns
+     *
+     * The entity ID of the created component.
+     */
+    add_component(component_type: string, params_json: string): bigint;
+    /**
+     * Create a new ViewScript engine bound to a canvas element.
+     *
+     * This is an async operation that initializes the WebGPU pipeline
+     * and sets up the constraint solver.
+     *
+     * # Arguments
+     *
+     * * `canvas` - The HTML canvas element to render to
+     * * `device_pixel_ratio` - DPR for coordinate scaling (e.g., 2.0 for Retina)
+     *
+     * # Returns
+     *
+     * A `Promise` that resolves to `WasmViewScriptEngine` or rejects with an error.
+     */
+    static create(canvas: HTMLCanvasElement, device_pixel_ratio: number): Promise<WasmViewScriptEngine>;
+    /**
+     * Register a static image texture.
+     *
+     * The pixel data must be in RGBA8 format with length `width * height * 4`.
+     * Returns the assigned texture ID for use with `FillSpec::ExternalTexture`.
+     *
+     * # Arguments
+     *
+     * * `width` - Texture width in pixels
+     * * `height` - Texture height in pixels
+     * * `pixels` - RGBA8 pixel data
+     *
+     * # Returns
+     *
+     * A unique texture ID that can be used in `FillSpec::ExternalTexture.handle_name`
+     * as `"resource.texture.<id>"`.
+     */
+    register_image_texture(width: number, height: number, pixels: Uint8Array): bigint;
+    /**
+     * Register a video texture (requires per-frame updates).
+     *
+     * Unlike `register_image_texture`, this does not upload pixel data immediately.
+     * Call `update_texture_pixels()` each frame to update the video frame.
+     *
+     * # Arguments
+     *
+     * * `width` - Video frame width in pixels
+     * * `height` - Video frame height in pixels
+     *
+     * # Returns
+     *
+     * A unique texture ID for use with `update_texture_pixels()`.
+     */
+    register_video_texture(width: number, height: number): bigint;
+    /**
+     * Remove a texture from the registry.
+     *
+     * Frees the GPU resources associated with the texture.
+     *
+     * # Arguments
+     *
+     * * `texture_id` - ID returned by `register_*_texture()`
+     *
+     * # Returns
+     *
+     * `true` if the texture was found and removed, `false` otherwise.
+     */
+    remove_texture(texture_id: bigint): boolean;
+    /**
+     * Resize the rendering surface.
+     *
+     * # Arguments
+     *
+     * * `width` - New width in device pixels
+     * * `height` - New height in device pixels
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Set a component's fill to an external texture.
+     *
+     * This modifies the `PathEntityEntry` in `build_info.path_entities` to use
+     * `FillSpec::ExternalTexture` with the specified texture ID.
+     *
+     * # Arguments
+     *
+     * * `component_entity_id` - Entity ID of the component (path) to modify
+     * * `texture_id` - Texture ID returned by `register_image_texture()`
+     *
+     * # Returns
+     *
+     * `Ok(())` if the component was found and updated, `Err` otherwise.
+     */
+    set_component_fill_texture(component_entity_id: bigint, texture_id: bigint): void;
+    /**
+     * Get the number of registered textures.
+     */
+    texture_count(): number;
+    /**
+     * Execute one frame of the rendering pipeline.
+     *
+     * This method implements the Q→T→P pipeline with derived variable evaluation:
+     * 1. Phase 1: Inject Q-dimension values or apply legacy mutations
+     * 2. Phase 2: solve → derive → re-solve loop (max 2 iterations)
+     *    - Run constraint solver
+     *    - Build scene graph
+     *    - Evaluate derived Q-variables (e.g., hover detection)
+     *    - If derived values changed, re-inject and loop
+     * 3. Render the final scene
+     *
+     * # Arguments
+     *
+     * * `input_json` - Either:
+     *   - New format: `{"values": {"input.pointer.x": {"type": "Float", "value": 100}}}`
+     *   - Legacy format: `[{"type": "Translate", "entity_id": 1, "dx": 10, "dy": 5}]`
+     *
+     * # Returns
+     *
+     * `Ok(())` on success, or a JavaScript error on failure.
+     */
+    tick(input_json: string): void;
+    /**
+     * Update texture pixel data.
+     *
+     * Use this for video textures (every frame) or animated images (on frame change).
+     * The pixel data must be RGBA8 format with length `width * height * 4`.
+     *
+     * # Arguments
+     *
+     * * `texture_id` - ID returned by `register_*_texture()`
+     * * `pixels` - RGBA8 pixel data
+     *
+     * # Returns
+     *
+     * `true` if the texture was found and updated, `false` otherwise.
+     */
+    update_texture_pixels(texture_id: bigint, pixels: Uint8Array): boolean;
+    /**
+     * Get the current canvas height in device pixels.
+     */
+    readonly height: number;
+    /**
+     * Get the current canvas width in device pixels.
+     */
+    readonly width: number;
+}
+
+/**
+ * Get WebGPU adapter info as a JSON string.
+ *
+ * Returns information about the GPU adapter, or an error if WebGPU is not available.
+ */
+export function get_adapter_info(): Promise<string>;
+
+/**
+ * Check if WebGPU is available in the current browser.
+ *
+ * Returns `true` if `navigator.gpu` exists and is not undefined.
+ */
+export function is_webgpu_available(): boolean;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_wasmgpurenderer_free: (a: number, b: number) => void;
+    readonly __wbg_wasmviewscriptengine_free: (a: number, b: number) => void;
+    readonly get_adapter_info: () => number;
+    readonly is_webgpu_available: () => number;
+    readonly wasmgpurenderer_create: (a: number) => number;
+    readonly wasmgpurenderer_height: (a: number) => number;
+    readonly wasmgpurenderer_resize: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmgpurenderer_width: (a: number) => number;
+    readonly wasmviewscriptengine_add_component: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly wasmviewscriptengine_create: (a: number, b: number) => number;
+    readonly wasmviewscriptengine_height: (a: number) => number;
+    readonly wasmviewscriptengine_register_image_texture: (a: number, b: number, c: number, d: number, e: number) => bigint;
+    readonly wasmviewscriptengine_register_video_texture: (a: number, b: number, c: number) => bigint;
+    readonly wasmviewscriptengine_remove_texture: (a: number, b: bigint) => number;
+    readonly wasmviewscriptengine_resize: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmviewscriptengine_set_component_fill_texture: (a: number, b: number, c: bigint, d: bigint) => void;
+    readonly wasmviewscriptengine_texture_count: (a: number) => number;
+    readonly wasmviewscriptengine_tick: (a: number, b: number, c: number, d: number) => void;
+    readonly wasmviewscriptengine_update_texture_pixels: (a: number, b: bigint, c: number, d: number) => number;
+    readonly wasmviewscriptengine_width: (a: number) => number;
+    readonly __wasm_bindgen_func_elem_3241: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_3263: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1613: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1613_2: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export5: (a: number, b: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;