@viewscript/renderer 0.1.0-202605140639

package/dist/runtime/wasm-resource-manager.js

@@ -0,0 +1,253 @@
+/**
+ * WASM Resource Manager
+ *
+ * This module provides explicit lifecycle management for WASM GPU resources.
+ * JavaScript's garbage collector cannot free WASM heap memory - we must call
+ * delete() explicitly on GPU objects.
+ *
+ * ## Problem
+ *
+ * ```
+ * const paint = canvasKit.Paint();  // Allocates on WASM heap
+ * paint = null;                      // JS reference gone, but WASM memory leaked!
+ * ```
+ *
+ * ## Solution: FinalizationRegistry
+ *
+ * We track all WASM resources and ensure delete() is called when the JS wrapper
+ * is garbage collected, OR when explicitly released via the resource pool.
+ *
+ * ## Resource Categories
+ *
+ * | Resource | Lifetime | Release Strategy |
+ * |----------|----------|------------------|
+ * | PaintSpec  | Entity   | On entity remove / HMR update |
+ * | PathEntity | Entity   | On path change / entity remove |
+ * | GpuImage   | Async    | On image unload / src change |
+ * | GpuFont    | Global   | On font unload (rare) |
+ */
+// =============================================================================
+// Resource Manager
+// =============================================================================
+export class WASMResourceManager {
+    /** FinalizationRegistry for automatic cleanup on GC */
+    registry;
+    /** Active resources (strong references for explicit management) */
+    resources;
+    /** Statistics */
+    stats;
+    /** Cleanup queue (for batch processing) */
+    cleanupQueue = [];
+    cleanupScheduled = false;
+    constructor() {
+        this.resources = new Map();
+        this.stats = { allocated: 0, released: 0 };
+        // Create registry with cleanup callback
+        this.registry = new FinalizationRegistry((token) => {
+            this.queueCleanup(token);
+        });
+    }
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Register a WASM resource for tracking.
+     *
+     * @param resource - GPU WASM object with delete() method
+     * @param type - Resource category
+     * @param entityId - Associated entity (optional)
+     * @returns Symbol token for explicit release
+     */
+    register(resource, type, entityId = null) {
+        const token = Symbol(`wasm-${type}-${this.stats.allocated}`);
+        const entry = {
+            type,
+            entityId,
+            createdAt: performance.now(),
+            accessed: performance.now(),
+        };
+        // Store weak reference for tracking
+        this.resources.set(token, {
+            ref: new WeakRef(resource),
+            entry,
+        });
+        // Register for finalization (GC-triggered cleanup)
+        const cleanupToken = { token, type };
+        this.registry.register(resource, cleanupToken, resource);
+        this.stats.allocated++;
+        return token;
+    }
+    /**
+     * Explicitly release a resource by token.
+     * Preferred over waiting for GC.
+     */
+    release(token) {
+        const entry = this.resources.get(token);
+        if (!entry)
+            return false;
+        const resource = entry.ref.deref();
+        if (resource && !resource.isDeleted?.()) {
+            try {
+                resource.delete();
+                this.registry.unregister(resource);
+            }
+            catch (e) {
+                console.warn('[WASM] Failed to delete resource:', e);
+            }
+        }
+        this.resources.delete(token);
+        this.stats.released++;
+        return true;
+    }
+    /**
+     * Release all resources associated with an entity.
+     * Called on entity removal or HMR update.
+     */
+    releaseByEntity(entityId) {
+        let released = 0;
+        for (const [token, { entry }] of this.resources) {
+            if (entry.entityId === entityId) {
+                if (this.release(token)) {
+                    released++;
+                }
+            }
+        }
+        return released;
+    }
+    /**
+     * Release all resources of a specific type.
+     */
+    releaseByType(type) {
+        let released = 0;
+        for (const [token, { entry }] of this.resources) {
+            if (entry.type === type) {
+                if (this.release(token)) {
+                    released++;
+                }
+            }
+        }
+        return released;
+    }
+    /**
+     * Force cleanup of all queued finalizations.
+     * Call after GC to ensure WASM memory is freed.
+     */
+    flushCleanupQueue() {
+        const count = this.cleanupQueue.length;
+        for (const token of this.cleanupQueue) {
+            this.release(token.token);
+        }
+        this.cleanupQueue = [];
+        return count;
+    }
+    /**
+     * Release ALL resources. Use with caution.
+     */
+    releaseAll() {
+        let released = 0;
+        for (const token of this.resources.keys()) {
+            if (this.release(token)) {
+                released++;
+            }
+        }
+        return released;
+    }
+    /**
+     * Get current resource statistics.
+     */
+    getStats() {
+        const byType = {
+            paint: 0,
+            path: 0,
+            image: 0,
+            font: 0,
+            shader: 0,
+            surface: 0,
+        };
+        let leakSuspects = 0;
+        const now = performance.now();
+        const LEAK_THRESHOLD_MS = 60000; // 1 minute without access
+        for (const { ref, entry } of this.resources.values()) {
+            const resource = ref.deref();
+            if (resource) {
+                byType[entry.type]++;
+                // Check for potential leaks (old, unaccessed resources)
+                if (now - entry.accessed > LEAK_THRESHOLD_MS) {
+                    leakSuspects++;
+                }
+            }
+        }
+        return {
+            totalAllocated: this.stats.allocated,
+            totalReleased: this.stats.released,
+            currentActive: this.resources.size,
+            byType,
+            leakSuspects,
+        };
+    }
+    /**
+     * Mark a resource as recently accessed (resets leak timer).
+     */
+    touch(token) {
+        const entry = this.resources.get(token);
+        if (entry) {
+            entry.entry.accessed = performance.now();
+        }
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Queue a cleanup token for batch processing.
+     */
+    queueCleanup(token) {
+        this.cleanupQueue.push(token);
+        // Schedule batch cleanup on next microtask
+        if (!this.cleanupScheduled) {
+            this.cleanupScheduled = true;
+            queueMicrotask(() => {
+                this.flushCleanupQueue();
+                this.cleanupScheduled = false;
+            });
+        }
+    }
+}
+// =============================================================================
+// Global Instance
+// =============================================================================
+/**
+ * Singleton resource manager for the renderer.
+ */
+export const wasmResources = new WASMResourceManager();
+// =============================================================================
+// Helper: Scoped Resource Guard
+// =============================================================================
+/**
+ * RAII-style guard for temporary WASM resources.
+ *
+ * Usage:
+ * ```
+ * using(canvasKit.Paint(), paint => {
+ *   canvas.drawRect(rect, paint);
+ * }); // paint.delete() called automatically
+ * ```
+ */
+export function using(resource, fn) {
+    try {
+        return fn(resource);
+    }
+    finally {
+        resource.delete();
+    }
+}
+/**
+ * Async version of using().
+ */
+export async function usingAsync(resource, fn) {
+    try {
+        return await fn(resource);
+    }
+    finally {
+        resource.delete();
+    }
+}

package/dist/runtime/wgpu-renderer-adapter.d.ts

@@ -0,0 +1,168 @@
+/**
+ * wgpu Renderer Adapter
+ *
+ * This module provides a `CanvasRenderer` implementation that delegates to
+ * `WasmGpuRenderer` from the vsc-wasm crate.
+ *
+ * ## Phase F: wgpu Migration
+ *
+ * This adapter implements the wgpu-based renderer:
+ *
+ * ```text
+ * Before (legacy):
+ *   RenderLoop → GpuRenderer → PathEntity → WebGL
+ *
+ * After (wgpu):
+ *   RenderLoop → WgpuRendererAdapter → WasmGpuRenderer → wgpu → WebGPU/WebGL
+ * ```
+ *
+ * ## Key Differences from legacy renderer
+ *
+ * 1. **No Resource Management**: wgpu resources are managed on the Rust side.
+ *    TypeScript does NOT need to call delete() on GPU objects.
+ *
+ * 2. **JSON Serialization**: DrawCommands are converted to CanvasNode JSON
+ *    and passed to WASM. This adds serialization overhead but simplifies
+ *    the boundary significantly.
+ *
+ * 3. **Batched Rendering**: draw() accumulates commands; flush() sends them
+ *    all to the GPU in a single render pass.
+ */
+import type { EntityId, RasterBounds, RenderableEntity } from '../ast/types.js';
+/**
+ * Canvas draw command (batched for wgpu).
+ */
+interface DrawCommand {
+    entityId: EntityId;
+    type: 'path' | 'text' | 'image' | 'group';
+    bounds: RasterBounds;
+    payload: unknown;
+}
+/**
+ * CanvasRenderer interface from render-loop.ts
+ */
+interface CanvasRenderer {
+    getEntity(id: EntityId): RenderableEntity | undefined;
+    draw(command: DrawCommand): void;
+    flush(): void;
+}
+/**
+ * WasmGpuRenderer interface (from vsc-wasm with "gpu" feature).
+ *
+ * This is the TypeScript-side view of the Rust struct.
+ */
+interface WasmGpuRenderer {
+    render(nodes_json: string): void;
+    resize(width: number, height: number): void;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Factory function for WasmGpuRenderer.
+ */
+interface WasmGpuRendererStatic {
+    create(canvas: HTMLCanvasElement): Promise<WasmGpuRenderer>;
+}
+/**
+ * wgpu-based CanvasRenderer implementation.
+ *
+ * This adapter accumulates DrawCommands during a frame, converts them to
+ * CanvasNode JSON, and sends them to WasmGpuRenderer on flush().
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createWgpuRendererAdapter } from './wgpu-renderer-adapter';
+ *
+ * const canvas = document.getElementById('viewport') as HTMLCanvasElement;
+ * const adapter = await createWgpuRendererAdapter(canvas, entityStore);
+ *
+ * // In render loop:
+ * adapter.draw(command1);
+ * adapter.draw(command2);
+ * adapter.flush(); // Sends all commands to GPU
+ * ```
+ */
+export declare class WgpuRendererAdapter implements CanvasRenderer {
+    /** WASM GPU renderer instance */
+    private renderer;
+    /** Entity store for getEntity() lookups */
+    private entityStore;
+    /** Accumulated draw commands for current frame */
+    private pendingCommands;
+    /** Canvas element for resize handling */
+    private canvas;
+    private constructor();
+    /**
+     * Create a new wgpu renderer adapter.
+     *
+     * @param canvas - HTML canvas element to render to
+     * @param entityStore - Map of entities for getEntity() lookups
+     * @param wasmModule - WASM module containing WasmGpuRenderer
+     */
+    static create(canvas: HTMLCanvasElement, entityStore: Map<EntityId, RenderableEntity>, wasmModule: {
+        WasmGpuRenderer: WasmGpuRendererStatic;
+    }): Promise<WgpuRendererAdapter>;
+    /**
+     * Get a renderable entity by ID.
+     */
+    getEntity(id: EntityId): RenderableEntity | undefined;
+    /**
+     * Queue a draw command for the current frame.
+     *
+     * Commands are accumulated until flush() is called.
+     */
+    draw(command: DrawCommand): void;
+    /**
+     * Flush all pending commands to the GPU.
+     *
+     * This converts accumulated DrawCommands to CanvasNode JSON and
+     * sends them to the WASM renderer in a single call.
+     *
+     * ## Serialization
+     *
+     * Uses `wasmBoundaryReplacer` to handle:
+     * - `bigint` values (not supported by standard JSON.stringify)
+     * - `Rational` objects → `"num/den"` string format (Rust expectation)
+     */
+    flush(): void;
+    /**
+     * Handle canvas resize.
+     *
+     * Call this when the canvas element is resized.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Get the current render surface dimensions.
+     */
+    getDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Update the entity store reference.
+     *
+     * Call this when the entity store is replaced (e.g., after HMR).
+     */
+    setEntityStore(store: Map<EntityId, RenderableEntity>): void;
+    /**
+     * Convert DrawCommands to CanvasNodes.
+     *
+     * This is the key translation layer between the render loop's command
+     * abstraction and the GPU renderer's scene graph.
+     */
+    private commandsToCanvasNodes;
+}
+/**
+ * Create a wgpu renderer adapter.
+ *
+ * This is the main entry point for creating a wgpu-based renderer.
+ *
+ * @param canvas - HTML canvas element to render to
+ * @param entityStore - Map of entities for getEntity() lookups
+ * @param wasmModule - WASM module containing WasmGpuRenderer
+ */
+export declare function createWgpuRendererAdapter(canvas: HTMLCanvasElement, entityStore: Map<EntityId, RenderableEntity>, wasmModule: {
+    WasmGpuRenderer: WasmGpuRendererStatic;
+}): Promise<WgpuRendererAdapter>;
+export {};

package/dist/runtime/wgpu-renderer-adapter.js

@@ -0,0 +1,230 @@
+/**
+ * wgpu Renderer Adapter
+ *
+ * This module provides a `CanvasRenderer` implementation that delegates to
+ * `WasmGpuRenderer` from the vsc-wasm crate.
+ *
+ * ## Phase F: wgpu Migration
+ *
+ * This adapter implements the wgpu-based renderer:
+ *
+ * ```text
+ * Before (legacy):
+ *   RenderLoop → GpuRenderer → PathEntity → WebGL
+ *
+ * After (wgpu):
+ *   RenderLoop → WgpuRendererAdapter → WasmGpuRenderer → wgpu → WebGPU/WebGL
+ * ```
+ *
+ * ## Key Differences from legacy renderer
+ *
+ * 1. **No Resource Management**: wgpu resources are managed on the Rust side.
+ *    TypeScript does NOT need to call delete() on GPU objects.
+ *
+ * 2. **JSON Serialization**: DrawCommands are converted to CanvasNode JSON
+ *    and passed to WASM. This adds serialization overhead but simplifies
+ *    the boundary significantly.
+ *
+ * 3. **Batched Rendering**: draw() accumulates commands; flush() sends them
+ *    all to the GPU in a single render pass.
+ */
+// =============================================================================
+// JSON Serialization Helpers
+// =============================================================================
+/**
+ * Custom JSON replacer for WASM boundary serialization.
+ *
+ * ## Problem
+ *
+ * JavaScript's `JSON.stringify()` does not support `bigint`:
+ * ```
+ * JSON.stringify({ n: 100n }) // TypeError: BigInt value can't be serialized
+ * ```
+ *
+ * ## Solution
+ *
+ * This replacer converts:
+ * - `bigint` → string (e.g., `100n` → `"100"`)
+ * - `Rational` object → `"numerator/denominator"` string
+ *
+ * The Rust side expects Rational as `"num/den"` string format
+ * (see `vsc-core/src/types.rs` Deserialize impl).
+ */
+function wasmBoundaryReplacer(_key, value) {
+    // Handle raw bigint (shouldn't occur in well-typed code, but safety first)
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    // Handle Rational objects: { numerator: bigint, denominator: bigint }
+    if (isRational(value)) {
+        return `${value.numerator}/${value.denominator}`;
+    }
+    return value;
+}
+/**
+ * Type guard for Rational objects.
+ */
+function isRational(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'numerator' in value &&
+        'denominator' in value &&
+        typeof value.numerator === 'bigint' &&
+        typeof value.denominator === 'bigint');
+}
+// =============================================================================
+// Adapter Implementation
+// =============================================================================
+/**
+ * wgpu-based CanvasRenderer implementation.
+ *
+ * This adapter accumulates DrawCommands during a frame, converts them to
+ * CanvasNode JSON, and sends them to WasmGpuRenderer on flush().
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createWgpuRendererAdapter } from './wgpu-renderer-adapter';
+ *
+ * const canvas = document.getElementById('viewport') as HTMLCanvasElement;
+ * const adapter = await createWgpuRendererAdapter(canvas, entityStore);
+ *
+ * // In render loop:
+ * adapter.draw(command1);
+ * adapter.draw(command2);
+ * adapter.flush(); // Sends all commands to GPU
+ * ```
+ */
+export class WgpuRendererAdapter {
+    /** WASM GPU renderer instance */
+    renderer;
+    /** Entity store for getEntity() lookups */
+    entityStore;
+    /** Accumulated draw commands for current frame */
+    pendingCommands = [];
+    /** Canvas element for resize handling */
+    canvas;
+    constructor(renderer, canvas, entityStore) {
+        this.renderer = renderer;
+        this.canvas = canvas;
+        this.entityStore = entityStore;
+    }
+    /**
+     * Create a new wgpu renderer adapter.
+     *
+     * @param canvas - HTML canvas element to render to
+     * @param entityStore - Map of entities for getEntity() lookups
+     * @param wasmModule - WASM module containing WasmGpuRenderer
+     */
+    static async create(canvas, entityStore, wasmModule) {
+        const renderer = await wasmModule.WasmGpuRenderer.create(canvas);
+        return new WgpuRendererAdapter(renderer, canvas, entityStore);
+    }
+    // ===========================================================================
+    // CanvasRenderer Interface
+    // ===========================================================================
+    /**
+     * Get a renderable entity by ID.
+     */
+    getEntity(id) {
+        return this.entityStore.get(id);
+    }
+    /**
+     * Queue a draw command for the current frame.
+     *
+     * Commands are accumulated until flush() is called.
+     */
+    draw(command) {
+        this.pendingCommands.push(command);
+    }
+    /**
+     * Flush all pending commands to the GPU.
+     *
+     * This converts accumulated DrawCommands to CanvasNode JSON and
+     * sends them to the WASM renderer in a single call.
+     *
+     * ## Serialization
+     *
+     * Uses `wasmBoundaryReplacer` to handle:
+     * - `bigint` values (not supported by standard JSON.stringify)
+     * - `Rational` objects → `"num/den"` string format (Rust expectation)
+     */
+    flush() {
+        if (this.pendingCommands.length === 0) {
+            return;
+        }
+        // Convert DrawCommands to CanvasNodes
+        const nodes = this.commandsToCanvasNodes(this.pendingCommands);
+        // Serialize with custom replacer for Rational/bigint handling
+        const json = JSON.stringify(nodes, wasmBoundaryReplacer);
+        this.renderer.render(json);
+        // Clear pending commands
+        this.pendingCommands = [];
+    }
+    // ===========================================================================
+    // Public Utilities
+    // ===========================================================================
+    /**
+     * Handle canvas resize.
+     *
+     * Call this when the canvas element is resized.
+     */
+    resize(width, height) {
+        this.renderer.resize(width, height);
+    }
+    /**
+     * Get the current render surface dimensions.
+     */
+    getDimensions() {
+        return {
+            width: this.renderer.width,
+            height: this.renderer.height,
+        };
+    }
+    /**
+     * Update the entity store reference.
+     *
+     * Call this when the entity store is replaced (e.g., after HMR).
+     */
+    setEntityStore(store) {
+        this.entityStore = store;
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Convert DrawCommands to CanvasNodes.
+     *
+     * This is the key translation layer between the render loop's command
+     * abstraction and the GPU renderer's scene graph.
+     */
+    commandsToCanvasNodes(commands) {
+        const nodes = [];
+        for (const cmd of commands) {
+            const entity = this.entityStore.get(cmd.entityId);
+            if (!entity?.canvas) {
+                continue;
+            }
+            // Use the entity's CanvasNode directly
+            // The payload in DrawCommand may contain overrides, but for now
+            // we use the entity's stored canvas representation
+            nodes.push(entity.canvas);
+        }
+        return nodes;
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a wgpu renderer adapter.
+ *
+ * This is the main entry point for creating a wgpu-based renderer.
+ *
+ * @param canvas - HTML canvas element to render to
+ * @param entityStore - Map of entities for getEntity() lookups
+ * @param wasmModule - WASM module containing WasmGpuRenderer
+ */
+export async function createWgpuRendererAdapter(canvas, entityStore, wasmModule) {
+    return WgpuRendererAdapter.create(canvas, entityStore, wasmModule);
+}

package/dist/semantic/__tests__/semantic-translator.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for SemanticTranslator (Phase 7: Task 20)
+ */
+export {};