@viewscript/renderer 0.1.0-202605140639

package/src/runtime/wasm-resource-manager.ts

@@ -0,0 +1,349 @@
+/**
+ * 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) |
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Any GPU WASM object with a delete() method.
+ */
+interface Deletable {
+  delete(): void;
+  isDeleted?(): boolean;
+}
+
+/**
+ * Resource metadata for tracking.
+ */
+interface ResourceEntry {
+  type: ResourceType;
+  entityId: number | null;
+  createdAt: number;
+  accessed: number;
+}
+
+type ResourceType = 'paint' | 'path' | 'image' | 'font' | 'shader' | 'surface';
+
+/**
+ * Resource pool statistics.
+ */
+export interface ResourceStats {
+  totalAllocated: number;
+  totalReleased: number;
+  currentActive: number;
+  byType: Record<ResourceType, number>;
+  leakSuspects: number;
+}
+
+// =============================================================================
+// Resource Manager
+// =============================================================================
+
+export class WASMResourceManager {
+  /** FinalizationRegistry for automatic cleanup on GC */
+  private registry: FinalizationRegistry<CleanupToken>;
+
+  /** Active resources (strong references for explicit management) */
+  private resources: Map<symbol, { ref: WeakRef<Deletable>; entry: ResourceEntry }>;
+
+  /** Statistics */
+  private stats: {
+    allocated: number;
+    released: number;
+  };
+
+  /** Cleanup queue (for batch processing) */
+  private cleanupQueue: CleanupToken[] = [];
+  private cleanupScheduled = false;
+
+  constructor() {
+    this.resources = new Map();
+    this.stats = { allocated: 0, released: 0 };
+
+    // Create registry with cleanup callback
+    this.registry = new FinalizationRegistry((token: CleanupToken) => {
+      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<T extends Deletable>(
+    resource: T,
+    type: ResourceType,
+    entityId: number | null = null,
+  ): symbol {
+    const token = Symbol(`wasm-${type}-${this.stats.allocated}`);
+
+    const entry: ResourceEntry = {
+      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: 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: symbol): boolean {
+    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: number): number {
+    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: ResourceType): number {
+    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(): number {
+    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(): number {
+    let released = 0;
+
+    for (const token of this.resources.keys()) {
+      if (this.release(token)) {
+        released++;
+      }
+    }
+
+    return released;
+  }
+
+  /**
+   * Get current resource statistics.
+   */
+  getStats(): ResourceStats {
+    const byType: Record<ResourceType, number> = {
+      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: symbol): void {
+    const entry = this.resources.get(token);
+    if (entry) {
+      entry.entry.accessed = performance.now();
+    }
+  }
+
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+
+  /**
+   * Queue a cleanup token for batch processing.
+   */
+  private queueCleanup(token: CleanupToken): void {
+    this.cleanupQueue.push(token);
+
+    // Schedule batch cleanup on next microtask
+    if (!this.cleanupScheduled) {
+      this.cleanupScheduled = true;
+      queueMicrotask(() => {
+        this.flushCleanupQueue();
+        this.cleanupScheduled = false;
+      });
+    }
+  }
+}
+
+/**
+ * Token passed to FinalizationRegistry callback.
+ */
+interface CleanupToken {
+  token: symbol;
+  type: ResourceType;
+}
+
+// =============================================================================
+// 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<T extends Deletable, R>(
+  resource: T,
+  fn: (resource: T) => R,
+): R {
+  try {
+    return fn(resource);
+  } finally {
+    resource.delete();
+  }
+}
+
+/**
+ * Async version of using().
+ */
+export async function usingAsync<T extends Deletable, R>(
+  resource: T,
+  fn: (resource: T) => Promise<R>,
+): Promise<R> {
+  try {
+    return await fn(resource);
+  } finally {
+    resource.delete();
+  }
+}

package/src/runtime/wgpu-renderer-adapter.ts

@@ -0,0 +1,318 @@
+/**
+ * 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, CanvasNode, RenderableEntity, Rational } from '../ast/types.js';
+
+// =============================================================================
+// 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: string, value: unknown): unknown {
+  // 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: unknown): value is Rational {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'numerator' in value &&
+    'denominator' in value &&
+    typeof (value as Rational).numerator === 'bigint' &&
+    typeof (value as Rational).denominator === 'bigint'
+  );
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * 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>;
+}
+
+// =============================================================================
+// 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 implements CanvasRenderer {
+  /** WASM GPU renderer instance */
+  private renderer: WasmGpuRenderer;
+
+  /** Entity store for getEntity() lookups */
+  private entityStore: Map<EntityId, RenderableEntity>;
+
+  /** Accumulated draw commands for current frame */
+  private pendingCommands: DrawCommand[] = [];
+
+  /** Canvas element for resize handling */
+  private canvas: HTMLCanvasElement;
+
+  private constructor(
+    renderer: WasmGpuRenderer,
+    canvas: HTMLCanvasElement,
+    entityStore: Map<EntityId, RenderableEntity>,
+  ) {
+    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: HTMLCanvasElement,
+    entityStore: Map<EntityId, RenderableEntity>,
+    wasmModule: { WasmGpuRenderer: WasmGpuRendererStatic },
+  ): Promise<WgpuRendererAdapter> {
+    const renderer = await wasmModule.WasmGpuRenderer.create(canvas);
+    return new WgpuRendererAdapter(renderer, canvas, entityStore);
+  }
+
+  // ===========================================================================
+  // CanvasRenderer Interface
+  // ===========================================================================
+
+  /**
+   * Get a renderable entity by ID.
+   */
+  getEntity(id: EntityId): RenderableEntity | undefined {
+    return this.entityStore.get(id);
+  }
+
+  /**
+   * Queue a draw command for the current frame.
+   *
+   * Commands are accumulated until flush() is called.
+   */
+  draw(command: DrawCommand): void {
+    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(): void {
+    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: number, height: number): void {
+    this.renderer.resize(width, height);
+  }
+
+  /**
+   * Get the current render surface dimensions.
+   */
+  getDimensions(): { width: number; height: number } {
+    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: Map<EntityId, RenderableEntity>): void {
+    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.
+   */
+  private commandsToCanvasNodes(commands: DrawCommand[]): CanvasNode[] {
+    const nodes: CanvasNode[] = [];
+
+    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: HTMLCanvasElement,
+  entityStore: Map<EntityId, RenderableEntity>,
+  wasmModule: { WasmGpuRenderer: WasmGpuRendererStatic },
+): Promise<WgpuRendererAdapter> {
+  return WgpuRendererAdapter.create(canvas, entityStore, wasmModule);
+}