@viewscript/renderer 0.1.0-202605140639

package/dist/runtime/render-loop.js

@@ -0,0 +1,435 @@
+/**
+ * Atomic Render Loop for ViewScript
+ *
+ * This module implements a frame-synchronous render pipeline that guarantees
+ * Canvas and DOM layers are updated atomically within a single animation frame.
+ *
+ * ## Architectural Invariant: No Frame Tearing
+ *
+ * If a button's visual representation moves at frame N, its DOM hit region
+ * MUST also move at frame N. Any desynchronization causes Q-dimension inputs
+ * to "hit the void" - a catastrophic UX failure.
+ *
+ * ## Strategy: Double-Buffered Dirty Tracking
+ *
+ * ```
+ * Frame N:
+ *   ┌─────────────────────────────────────────────────────────────────┐
+ *   │ 1. Flush pending T-vector mutations (from Q-dimension events)  │
+ *   │ 2. Evaluate constraint graph (P-dimension solver)              │
+ *   │ 3. Topology-preserving rounding (with error distribution)      │
+ *   │ 4. Diff against previous frame's RasterBounds                  │
+ *   │ 5. Batch Canvas draw commands (wgpu)                          │
+ *   │ 6. Batch DOM style mutations (transform only, no reflow)       │
+ *   │ 7. Commit: GpuRenderer.flush() + requestAnimationFrame boundary│
+ *   └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Reflow Prevention Strategy
+ *
+ * DOM mutations are restricted to compositor-only properties:
+ * - transform: translate3d(x, y, 0) - GPU-accelerated, no reflow
+ * - opacity - compositor-only
+ * - will-change: transform - hint to browser
+ *
+ * We NEVER touch: width, height, top, left, margin, padding (reflow triggers)
+ */
+// =============================================================================
+// Core Render Loop
+// =============================================================================
+export class AtomicRenderLoop {
+    config;
+    frameState;
+    pendingMutations = [];
+    isRunning = false;
+    rafHandle = null;
+    // External dependencies (injected)
+    constraintSolver;
+    topologyRounder;
+    canvasRenderer;
+    domLayer;
+    /**
+     * Event buffer for async event atomicity.
+     *
+     * Injected via setEventBuffer() to support mergeAsyncEvents() at tick start.
+     */
+    eventBuffer = null;
+    constructor(config, constraintSolver, topologyRounder, canvasRenderer, domLayer) {
+        this.config = {
+            targetFPS: 60,
+            debugTiming: false,
+            maxMutationsPerFrame: 100,
+            ...config,
+        };
+        this.frameState = {
+            previousBounds: new Map(),
+            currentBounds: new Map(),
+            dirtyEntities: new Set(),
+            frameNumber: 0,
+        };
+        this.constraintSolver = constraintSolver;
+        this.topologyRounder = topologyRounder;
+        this.canvasRenderer = canvasRenderer;
+        this.domLayer = domLayer;
+    }
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Start the render loop.
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.scheduleFrame();
+    }
+    /**
+     * Stop the render loop.
+     */
+    stop() {
+        this.isRunning = false;
+        if (this.rafHandle !== null) {
+            cancelAnimationFrame(this.rafHandle);
+            this.rafHandle = null;
+        }
+    }
+    /**
+     * Queue a T-vector mutation from Q-dimension event.
+     * Called from event handlers (backpressure-controlled).
+     */
+    queueMutation(mutation) {
+        this.pendingMutations.push(mutation);
+    }
+    /**
+     * Set the event buffer for async event atomicity.
+     *
+     * The event buffer is used to merge async events (from fetch, setTimeout, etc.)
+     * at the start of each tick, ensuring deterministic event ordering.
+     */
+    setEventBuffer(buffer) {
+        this.eventBuffer = buffer;
+    }
+    // ===========================================================================
+    // Frame Execution (Atomic Commit)
+    // ===========================================================================
+    /**
+     * Execute a single frame tick.
+     *
+     * CRITICAL: This function executes entirely within a single rAF callback,
+     * ensuring Canvas and DOM updates are committed atomically before the
+     * browser's compositor thread runs.
+     */
+    tick(timestamp) {
+        if (!this.isRunning)
+            return;
+        const frameStart = performance.now();
+        this.frameState.frameNumber++;
+        // -------------------------------------------------------------------------
+        // Phase 0: Merge Async Events (MUST be first - async atomicity)
+        // -------------------------------------------------------------------------
+        // Events from async callbacks (fetch, setTimeout, promises) are isolated
+        // in a separate buffer to prevent race conditions. They are merged here
+        // at the START of the tick, before any sync event processing.
+        //
+        // This ensures:
+        // 1. Deterministic ordering: async events processed before sync events
+        // 2. Atomicity: no async events can arrive mid-tick
+        // 3. Consistency: the tick sees a complete snapshot of async state
+        if (this.eventBuffer) {
+            this.eventBuffer.mergeAsyncEvents();
+        }
+        // -------------------------------------------------------------------------
+        // Phase 1: Flush Pending Mutations (Backpressure-Limited)
+        // -------------------------------------------------------------------------
+        const mutations = this.flushMutations();
+        // -------------------------------------------------------------------------
+        // Phase 2: Evaluate Constraint Graph
+        // -------------------------------------------------------------------------
+        const pVectorBounds = this.constraintSolver.evaluate(mutations);
+        // -------------------------------------------------------------------------
+        // Phase 3: Topology-Preserving Rounding (with Error Distribution)
+        // -------------------------------------------------------------------------
+        const rasterResult = this.topologyRounder.round(pVectorBounds);
+        // -------------------------------------------------------------------------
+        // Phase 4: Compute Dirty Set (Diff Against Previous Frame)
+        // -------------------------------------------------------------------------
+        this.computeDirtySet(rasterResult.bounds);
+        // -------------------------------------------------------------------------
+        // Phase 5: Batch Canvas Draw Commands
+        // -------------------------------------------------------------------------
+        const drawCommands = this.buildDrawCommands();
+        // -------------------------------------------------------------------------
+        // Phase 6: Batch DOM Mutations (Transform Only)
+        // -------------------------------------------------------------------------
+        const domMutations = this.buildDOMMutations();
+        // -------------------------------------------------------------------------
+        // Phase 7: Atomic Commit
+        // -------------------------------------------------------------------------
+        this.commitFrame(drawCommands, domMutations);
+        // -------------------------------------------------------------------------
+        // Swap Buffers
+        // -------------------------------------------------------------------------
+        this.swapBuffers();
+        // -------------------------------------------------------------------------
+        // Schedule Next Frame
+        // -------------------------------------------------------------------------
+        const frameEnd = performance.now();
+        if (this.config.debugTiming) {
+            console.log(`Frame ${this.frameState.frameNumber}: ${(frameEnd - frameStart).toFixed(2)}ms`);
+        }
+        this.scheduleFrame();
+    }
+    scheduleFrame() {
+        this.rafHandle = requestAnimationFrame((ts) => this.tick(ts));
+    }
+    // ===========================================================================
+    // Phase Implementations
+    // ===========================================================================
+    /**
+     * Phase 1: Flush pending mutations with backpressure limit.
+     */
+    flushMutations() {
+        const limit = this.config.maxMutationsPerFrame;
+        const flushed = this.pendingMutations.splice(0, limit);
+        return flushed;
+    }
+    /**
+     * Phase 4: Compute which entities changed this frame.
+     */
+    computeDirtySet(currentBounds) {
+        this.frameState.dirtyEntities.clear();
+        this.frameState.currentBounds = currentBounds;
+        for (const [entityId, bounds] of currentBounds) {
+            const prev = this.frameState.previousBounds.get(entityId);
+            if (!prev || !boundsEqual(prev, bounds)) {
+                this.frameState.dirtyEntities.add(entityId);
+            }
+        }
+        // Detect removed entities
+        for (const entityId of this.frameState.previousBounds.keys()) {
+            if (!currentBounds.has(entityId)) {
+                this.frameState.dirtyEntities.add(entityId);
+            }
+        }
+    }
+    /**
+     * Phase 5: Build Canvas draw commands for dirty entities only.
+     */
+    buildDrawCommands() {
+        const commands = [];
+        for (const entityId of this.frameState.dirtyEntities) {
+            const bounds = this.frameState.currentBounds.get(entityId);
+            if (!bounds)
+                continue;
+            // Get entity's canvas node and build draw command
+            const entity = this.canvasRenderer.getEntity(entityId);
+            if (entity?.canvas) {
+                commands.push({
+                    entityId,
+                    type: entity.canvas.kind,
+                    bounds,
+                    payload: entity.canvas,
+                });
+            }
+        }
+        return commands;
+    }
+    /**
+     * Phase 6: Build DOM mutations (transform-only, no reflow).
+     *
+     * CRITICAL: We use transform: translate3d() which is compositor-only.
+     * This means the GPU handles the positioning without triggering
+     * the browser's layout engine.
+     */
+    buildDOMMutations() {
+        const mutations = [];
+        for (const entityId of this.frameState.dirtyEntities) {
+            const bounds = this.frameState.currentBounds.get(entityId);
+            if (!bounds)
+                continue;
+            const element = this.domLayer.getElement(entityId);
+            if (!element)
+                continue;
+            // Use translate3d for GPU acceleration
+            // Note: Element must have position: absolute and will-change: transform
+            const transform = `translate3d(${bounds.x}px, ${bounds.y}px, 0)`;
+            mutations.push({
+                entityId,
+                element,
+                transform,
+            });
+        }
+        return mutations;
+    }
+    /**
+     * Phase 7: Atomic commit of Canvas and DOM updates.
+     *
+     * This function guarantees that by the time rAF callback returns:
+     * 1. All wgpu draw commands have been flushed to GPU
+     * 2. All DOM transforms have been written
+     * 3. Browser's compositor will see consistent state
+     *
+     * ## Strict DOM Proxy Enforcement
+     *
+     * DOM elements are initialized with `initializeDOMProxyElement()` which
+     * installs a Proxy guard. Only `transform` can be modified here.
+     */
+    commitFrame(drawCommands, domMutations) {
+        // --- Canvas Commit ---
+        // GPU renderer batches internally; we just need to issue commands and flush
+        for (const cmd of drawCommands) {
+            this.canvasRenderer.draw(cmd);
+        }
+        this.canvasRenderer.flush();
+        // --- DOM Commit (Single Write Batch) ---
+        // Using updateDOMProxyTransform which is the only allowed mutation
+        for (const mutation of domMutations) {
+            updateDOMProxyTransform(mutation.element, this.frameState.currentBounds.get(mutation.entityId)?.x ?? 0, this.frameState.currentBounds.get(mutation.entityId)?.y ?? 0);
+        }
+        // No reads after writes in this function = no reflow triggered
+    }
+    /**
+     * Swap frame buffers for next frame's diff.
+     */
+    swapBuffers() {
+        this.frameState.previousBounds = new Map(this.frameState.currentBounds);
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+function boundsEqual(a, b) {
+    return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+// =============================================================================
+// DOM Proxy Enforcement (Architect Directive: Strict DOM Proxy)
+// =============================================================================
+/**
+ * CSS properties allowed on DOM proxy elements.
+ *
+ * These are compositor-only properties that do NOT trigger browser reflow.
+ * Any attempt to set other properties (margin, padding, display, etc.)
+ * will throw a runtime error.
+ */
+const ALLOWED_CSS_PROPERTIES = new Set([
+    'transform',
+    'opacity',
+    'pointerEvents',
+    'pointer-events', // Allow both camelCase and kebab-case
+    'willChange',
+    'will-change',
+]);
+/**
+ * Initialize a DOM element as a strict ViewScript proxy.
+ *
+ * This function:
+ * 1. Sets all required CSS properties for compositor-only updates
+ * 2. Wraps the style object in a Proxy to prevent layout-triggering mutations
+ * 3. Ensures the element is a "transparent tactile proxy" with no visual rendering
+ *
+ * ## Architect Directive: Zero Layout Engine Intervention
+ *
+ * The browser's layout engine (Reflow) must NEVER be invoked by DOM proxy
+ * elements. All positioning is done via GPU-accelerated `transform: translate3d()`.
+ */
+export function initializeDOMProxyElement(element, bounds) {
+    // Store original style object for Proxy wrapping
+    const originalStyle = element.style;
+    // Apply mandatory CSS for compositor-only updates
+    originalStyle.position = 'absolute';
+    originalStyle.top = '0';
+    originalStyle.left = '0';
+    originalStyle.width = `${bounds.width}px`;
+    originalStyle.height = `${bounds.height}px`;
+    originalStyle.opacity = '0'; // Visually transparent
+    originalStyle.pointerEvents = 'auto'; // Tactile proxy active
+    originalStyle.willChange = 'transform'; // GPU layer hint
+    originalStyle.margin = '0'; // Explicit zero
+    originalStyle.padding = '0'; // Explicit zero
+    originalStyle.border = 'none'; // Explicit none
+    originalStyle.boxSizing = 'border-box'; // Predictable sizing
+    originalStyle.overflow = 'hidden'; // No scrollbars
+    originalStyle.transform = `translate3d(${bounds.x}px, ${bounds.y}px, 0)`;
+    // Create a Proxy to guard against layout-triggering mutations
+    const guardedStyle = new Proxy(originalStyle, {
+        set(target, property, value) {
+            // Allow setting allowed properties
+            if (ALLOWED_CSS_PROPERTIES.has(property)) {
+                return Reflect.set(target, property, value);
+            }
+            // Block all other properties with a clear error
+            throw new Error(`[ViewScript DOM Proxy Violation] Cannot set CSS property '${property}' on DOM proxy element. ` +
+                `Only compositor-only properties are allowed: ${[...ALLOWED_CSS_PROPERTIES].join(', ')}. ` +
+                `This restriction prevents browser layout engine intervention.`);
+        },
+        get(target, property) {
+            return Reflect.get(target, property);
+        },
+    });
+    // Replace the element's style with the guarded proxy
+    // Note: We can't directly assign to element.style, but we can use defineProperty
+    Object.defineProperty(element, 'style', {
+        value: guardedStyle,
+        writable: false,
+        configurable: false,
+    });
+}
+/**
+ * Update a DOM proxy element's transform (position).
+ *
+ * This is the ONLY way to change a proxy element's position after initialization.
+ * It uses compositor-only transform, avoiding layout recalculation.
+ */
+export function updateDOMProxyTransform(element, x, y) {
+    // Direct property access bypasses our Proxy guard (intentionally)
+    // because this is an internal, trusted call
+    element.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+}
+// =============================================================================
+// Control Flow Summary (for Architect)
+// =============================================================================
+/**
+ * ## tick() Control Flow (Pseudocode)
+ *
+ * ```
+ * function tick(timestamp):
+ *   // 1. Backpressure: Take at most N mutations from queue
+ *   mutations = pendingMutations.splice(0, MAX_PER_FRAME)
+ *
+ *   // 2. P-dimension: Solve constraints with new T-vector values
+ *   pBounds = constraintSolver.evaluate(mutations)
+ *
+ *   // 3. Rasterize: Rational → Integer with topology preservation
+ *   rBounds = topologyRounder.round(pBounds)
+ *
+ *   // 4. Diff: Find entities that changed since last frame
+ *   dirtySet = diff(previousBounds, rBounds)
+ *
+ *   // 5. Canvas: Build draw commands for dirty entities only
+ *   drawCmds = buildDrawCommands(dirtySet)
+ *
+ *   // 6. DOM: Build transform mutations (no width/height!)
+ *   domMuts = buildDOMMutations(dirtySet)
+ *
+ *   // 7. ATOMIC COMMIT (no interleaved reads/writes)
+ *   for cmd in drawCmds: canvasRenderer.draw(cmd)
+ *   canvasRenderer.flush()  // GPU sync point
+ *   for mut in domMuts: mut.element.style.transform = mut.transform
+ *
+ *   // 8. Swap buffers
+ *   previousBounds = rBounds
+ *
+ *   // 9. Schedule next frame
+ *   requestAnimationFrame(tick)
+ * ```
+ *
+ * ## Reflow Prevention Strategy
+ *
+ * 1. DOM elements are created once with fixed dimensions (via CSS)
+ * 2. Position changes use ONLY transform: translate3d()
+ * 3. translate3d() is compositor-only (GPU, no layout recalc)
+ * 4. will-change: transform hints browser to promote layer
+ * 5. All style writes happen before any reads (no thrashing)
+ * 6. Size changes require re-creating the element (rare)
+ */

package/dist/runtime/wasm-resource-manager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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) |
+ */
+/**
+ * Any GPU WASM object with a delete() method.
+ */
+interface Deletable {
+    delete(): void;
+    isDeleted?(): boolean;
+}
+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;
+}
+export declare class WASMResourceManager {
+    /** FinalizationRegistry for automatic cleanup on GC */
+    private registry;
+    /** Active resources (strong references for explicit management) */
+    private resources;
+    /** Statistics */
+    private stats;
+    /** Cleanup queue (for batch processing) */
+    private cleanupQueue;
+    private cleanupScheduled;
+    constructor();
+    /**
+     * 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): symbol;
+    /**
+     * Explicitly release a resource by token.
+     * Preferred over waiting for GC.
+     */
+    release(token: symbol): boolean;
+    /**
+     * Release all resources associated with an entity.
+     * Called on entity removal or HMR update.
+     */
+    releaseByEntity(entityId: number): number;
+    /**
+     * Release all resources of a specific type.
+     */
+    releaseByType(type: ResourceType): number;
+    /**
+     * Force cleanup of all queued finalizations.
+     * Call after GC to ensure WASM memory is freed.
+     */
+    flushCleanupQueue(): number;
+    /**
+     * Release ALL resources. Use with caution.
+     */
+    releaseAll(): number;
+    /**
+     * Get current resource statistics.
+     */
+    getStats(): ResourceStats;
+    /**
+     * Mark a resource as recently accessed (resets leak timer).
+     */
+    touch(token: symbol): void;
+    /**
+     * Queue a cleanup token for batch processing.
+     */
+    private queueCleanup;
+}
+/**
+ * Singleton resource manager for the renderer.
+ */
+export declare const wasmResources: WASMResourceManager;
+/**
+ * RAII-style guard for temporary WASM resources.
+ *
+ * Usage:
+ * ```
+ * using(canvasKit.Paint(), paint => {
+ *   canvas.drawRect(rect, paint);
+ * }); // paint.delete() called automatically
+ * ```
+ */
+export declare function using<T extends Deletable, R>(resource: T, fn: (resource: T) => R): R;
+/**
+ * Async version of using().
+ */
+export declare function usingAsync<T extends Deletable, R>(resource: T, fn: (resource: T) => Promise<R>): Promise<R>;
+export {};