@viewscript/renderer 0.1.0-202605140721 → 0.1.0-202605141229

package/dist/runtime/__tests__/wasm-solver-bridge.test.js

@@ -0,0 +1,214 @@
+/**
+ * Tests for WASM Solver Bridge
+ *
+ * Validates:
+ * 1. QSnapshot construction from mutations + FFI results
+ * 2. WASM tick() delegation and result parsing
+ * 3. FFI result injection lifecycle
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { WasmSolverBridge, createWasmSolverBridge, } from '../wasm-solver-bridge.js';
+// =============================================================================
+// Mock WASM Engine
+// =============================================================================
+function createMockEngine() {
+    return {
+        lastInput: null,
+        tick(inputJson) {
+            this.lastInput = inputJson;
+            return JSON.stringify({ pending_ffi_calls: [] });
+        },
+    };
+}
+function createMockEngineWithCalls(calls) {
+    return {
+        tick() {
+            return JSON.stringify({ pending_ffi_calls: calls });
+        },
+    };
+}
+// =============================================================================
+// Tests
+// =============================================================================
+describe('WasmSolverBridge', () => {
+    let bridge;
+    let mockEngine;
+    beforeEach(() => {
+        mockEngine = createMockEngine();
+        bridge = createWasmSolverBridge(mockEngine);
+    });
+    // ===========================================================================
+    // Basic Evaluation
+    // ===========================================================================
+    describe('evaluate', () => {
+        it('calls engine.tick() with QSnapshot JSON', () => {
+            const mutations = [];
+            bridge.evaluate(mutations);
+            expect(mockEngine.lastInput).not.toBeNull();
+            const snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot).toHaveProperty('values');
+            expect(snapshot).toHaveProperty('mutations');
+        });
+        it('returns empty bounds and pendingFfiCalls by default', () => {
+            const result = bridge.evaluate([]);
+            expect(result.bounds.size).toBe(0);
+            expect(result.pendingFfiCalls).toEqual([]);
+        });
+        it('extracts pendingFfiCalls from tick result', () => {
+            const calls = [{ ffi_id: 1, args: [1, 2, 3] }];
+            bridge = createWasmSolverBridge(createMockEngineWithCalls(calls));
+            const result = bridge.evaluate([]);
+            expect(result.pendingFfiCalls).toEqual(calls);
+        });
+    });
+    // ===========================================================================
+    // Mutation Conversion
+    // ===========================================================================
+    describe('mutation conversion', () => {
+        it('converts TStateMutation to QSnapshot values', () => {
+            const mutations = [
+                { entityId: 1, state: 'hover', value: 1, timestamp: 100 },
+                { entityId: 2, state: 'scroll_y', value: 0.5, timestamp: 100 },
+            ];
+            bridge.evaluate(mutations);
+            const snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot.values['1_hover']).toEqual({ type: 'float', value: 1 });
+            expect(snapshot.values['2_scroll_y']).toEqual({ type: 'float', value: 0.5 });
+        });
+        it('includes mutations array for legacy format', () => {
+            const mutations = [
+                { entityId: 1, state: 'pressed', value: 1, timestamp: 100 },
+            ];
+            bridge.evaluate(mutations);
+            const snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot.mutations).toHaveLength(1);
+            expect(snapshot.mutations[0]).toMatchObject({
+                entity_id: 1,
+                state: 'pressed',
+                value: 1,
+            });
+        });
+    });
+    // ===========================================================================
+    // FFI Result Injection
+    // ===========================================================================
+    describe('injectFfiResults', () => {
+        it('includes injected FFI results in QSnapshot values', () => {
+            const ffiResults = [
+                { name: 'clamped_opacity', value: 0.75, timestamp: 100 },
+                { name: 'distance', value: 42, timestamp: 100 },
+            ];
+            bridge.injectFfiResults(ffiResults);
+            bridge.evaluate([]);
+            const snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot.values['clamped_opacity']).toEqual({ type: 'float', value: 0.75 });
+            expect(snapshot.values['distance']).toEqual({ type: 'float', value: 42 });
+        });
+        it('clears FFI results after evaluate()', () => {
+            bridge.injectFfiResults([{ name: 'test', value: 1, timestamp: 100 }]);
+            // First evaluate includes FFI result
+            bridge.evaluate([]);
+            let snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot.values['test']).toBeDefined();
+            // Second evaluate should NOT include FFI result
+            bridge.evaluate([]);
+            snapshot = JSON.parse(mockEngine.lastInput);
+            expect(snapshot.values['test']).toBeUndefined();
+        });
+        it('FFI results override mutation values with same name', () => {
+            // This tests the merge order: FFI results come first, then mutations
+            // If there's a naming collision, the mutation should win
+            const ffiResults = [
+                { name: '1_hover', value: 0.5, timestamp: 100 },
+            ];
+            const mutations = [
+                { entityId: 1, state: 'hover', value: 1, timestamp: 100 },
+            ];
+            bridge.injectFfiResults(ffiResults);
+            bridge.evaluate(mutations);
+            const snapshot = JSON.parse(mockEngine.lastInput);
+            // Mutation overwrites FFI result (processed later)
+            expect(snapshot.values['1_hover'].value).toBe(1);
+        });
+    });
+    // ===========================================================================
+    // Error Handling
+    // ===========================================================================
+    describe('error handling', () => {
+        it('handles engine.tick() throwing', () => {
+            const errorEngine = {
+                tick() {
+                    throw new Error('WASM panic');
+                },
+            };
+            bridge = createWasmSolverBridge(errorEngine);
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const result = bridge.evaluate([]);
+            expect(result.bounds.size).toBe(0);
+            expect(result.pendingFfiCalls).toEqual([]);
+            expect(errorSpy).toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+        it('preserves FFI results when tick() throws for next frame retry', () => {
+            let callCount = 0;
+            const flakyEngine = {
+                lastInput: null,
+                tick(inputJson) {
+                    callCount++;
+                    if (callCount === 1) {
+                        throw new Error('Transient WASM error');
+                    }
+                    this.lastInput = inputJson;
+                    return JSON.stringify({ pending_ffi_calls: [] });
+                },
+            };
+            bridge = createWasmSolverBridge(flakyEngine);
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            // Inject FFI results
+            bridge.injectFfiResults([{ name: 'important_value', value: 42, timestamp: 100 }]);
+            // First evaluate fails - FFI results should be preserved
+            bridge.evaluate([]);
+            expect(errorSpy).toHaveBeenCalled();
+            // Second evaluate succeeds - FFI results should still be included
+            bridge.evaluate([]);
+            const snapshot = JSON.parse(flakyEngine.lastInput);
+            expect(snapshot.values['important_value']).toEqual({ type: 'float', value: 42 });
+            errorSpy.mockRestore();
+        });
+        it('handles invalid JSON from tick()', () => {
+            const badEngine = {
+                tick() {
+                    return 'not valid json';
+                },
+            };
+            bridge = createWasmSolverBridge(badEngine);
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const result = bridge.evaluate([]);
+            expect(result.pendingFfiCalls).toEqual([]);
+            expect(errorSpy).toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+        it('handles missing pending_ffi_calls in result', () => {
+            const partialEngine = {
+                tick() {
+                    return JSON.stringify({}); // No pending_ffi_calls field
+                },
+            };
+            bridge = createWasmSolverBridge(partialEngine);
+            const result = bridge.evaluate([]);
+            expect(result.pendingFfiCalls).toEqual([]);
+        });
+    });
+    // ===========================================================================
+    // Factory Function
+    // ===========================================================================
+    describe('createWasmSolverBridge', () => {
+        it('creates a new instance', () => {
+            const engine = createMockEngine();
+            const b1 = createWasmSolverBridge(engine);
+            const b2 = createWasmSolverBridge(engine);
+            expect(b1).not.toBe(b2);
+            expect(b1).toBeInstanceOf(WasmSolverBridge);
+        });
+    });
+});

package/dist/runtime/ffi-dispatcher.d.ts

@@ -0,0 +1,217 @@
+/**
+ * FFI Dispatcher for ViewScript Runtime
+ *
+ * Evaluates pending FFI calls after frame commit (Phase 8) and buffers
+ * results for consumption in the next frame's QSnapshot merge (Phase 0-1).
+ *
+ * ## Design Rationale
+ *
+ * FFI function execution time is non-deterministic (user-defined functions).
+ * By executing after commitFrame(), we:
+ * 1. Keep the rendering critical path (Phase 2-7) free of unpredictable latency
+ * 2. Utilize the idle time between commitFrame() and the next rAF callback
+ * 3. Maintain 1-frame latency for FFI results (Axiom 2: Ouroboros Binding)
+ *
+ * ## Data Flow
+ *
+ * ```
+ * Frame N:
+ *   Phase 2: tick() → TickResult { pending_ffi_calls }
+ *   Phase 8: dispatch(pending_ffi_calls) → buffer results
+ *
+ * Frame N+1:
+ *   Phase 0-1: drainResults() → QSnapshot.values merge
+ *   Phase 2: solver sees FFI results as Q-dimension input
+ * ```
+ */
+/**
+ * FFI argument types from manifest.
+ */
+export type FfiArg = {
+    type: 'static';
+    value: unknown;
+} | {
+    type: 'q_ref';
+    name: string;
+} | {
+    type: 'entity_coord';
+    entity_id: number;
+    component: string;
+};
+/**
+ * FFI binding from manifest.
+ */
+export interface FfiBinding {
+    ffi_id: number;
+    bind_name: string;
+    module_path: string;
+    export_name: string;
+    args: FfiArg[];
+}
+/**
+ * FFI trigger from manifest.
+ */
+export interface FfiTrigger {
+    trigger_id: number;
+    ffi_id: number;
+    module_path: string;
+    export_name: string;
+    condition: {
+        kind: string;
+        entity_a?: number;
+        entity_b?: number;
+    };
+    args: FfiArg[];
+}
+/**
+ * Complete FFI manifest.
+ */
+export interface FfiManifest {
+    version: number;
+    entity_map: Record<string, number>;
+    bindings: FfiBinding[];
+    triggers: FfiTrigger[];
+}
+/**
+ * Pending FFI call from WASM tick() result.
+ */
+export interface PendingFfiCall {
+    ffi_id: number;
+    trigger_id?: number;
+    args: unknown[];
+}
+/**
+ * Result of an FFI call, ready for QSnapshot merge.
+ */
+export interface FfiResult {
+    /** Q-variable name to update */
+    name: string;
+    /** Computed value */
+    value: number;
+    /** Timestamp for event ordering */
+    timestamp: number;
+}
+export declare class FfiDispatcher {
+    /** Function registry: ffi_id -> entry */
+    private registry;
+    /** Pending modules awaiting registration */
+    private pendingModules;
+    /** Buffered results for next frame */
+    private resultBuffer;
+    /** In-flight async calls (prevents duplicate dispatch while awaiting) */
+    private inflight;
+    /** Entity coordinate resolver (injected) */
+    private coordResolver;
+    /** Q-variable resolver (injected) */
+    private qResolver;
+    /**
+     * Load FFI manifest and build function registry.
+     *
+     * @param manifest - Parsed FfiManifest JSON
+     */
+    loadManifest(manifest: FfiManifest): void;
+    /**
+     * Register a dynamically imported ESM module.
+     *
+     * Call this after `import(modulePath)` resolves.
+     *
+     * @param modulePath - Resolved module path (must match manifest's module_path)
+     * @param module - The imported module object
+     */
+    registerModule(modulePath: string, module: Record<string, unknown>): void;
+    /**
+     * Set the coordinate resolver for EntityCoord arguments.
+     */
+    setCoordinateResolver(resolver: CoordinateResolver): void;
+    /**
+     * Set the Q-variable resolver for QRef arguments.
+     */
+    setQResolver(resolver: QVariableResolver): void;
+    /**
+     * Get list of module paths that need to be imported.
+     */
+    getPendingModules(): string[];
+    /**
+     * Check if all modules have been registered.
+     */
+    isReady(): boolean;
+    /**
+     * Dispatch pending FFI calls (Phase 8).
+     *
+     * Evaluates JS functions and buffers results. Supports both sync and async
+     * functions. For async functions, results are buffered when the Promise
+     * resolves (may be multiple frames later).
+     *
+     * In-flight guard: If an async call for a given ffi_id is still pending,
+     * subsequent dispatch requests for the same ffi_id are skipped until the
+     * previous call completes.
+     *
+     * @param pendingCalls - Array of PendingFfiCall from TickResult
+     */
+    dispatch(pendingCalls: PendingFfiCall[]): void;
+    /**
+     * Buffer a result value if it's numeric.
+     */
+    private bufferResult;
+    /**
+     * Drain buffered results for QSnapshot merge (Phase 0-1).
+     *
+     * Returns all buffered results and clears the buffer.
+     * Call this at the start of the next frame.
+     *
+     * @returns Array of FfiResult for QSnapshot.values merge
+     */
+    drainResults(): FfiResult[];
+    /**
+     * Get the number of buffered results (for diagnostics).
+     */
+    getBufferedCount(): number;
+    /**
+     * Get the number of in-flight async calls (for diagnostics/testing).
+     */
+    getInflightCount(): number;
+    /**
+     * Check if a specific ffi_id has an in-flight async call.
+     */
+    isInflight(ffiId: number): boolean;
+    /**
+     * Resolve FfiArg array to concrete values.
+     *
+     * @param argSpecs - Argument specifications from manifest
+     * @param runtimeArgs - Runtime argument overrides from PendingFfiCall
+     */
+    private resolveArgs;
+    /**
+     * Resolve a single FfiArg to its concrete value.
+     */
+    private resolveArg;
+}
+/**
+ * Interface for resolving entity coordinates.
+ */
+export interface CoordinateResolver {
+    /**
+     * Get a coordinate component for an entity.
+     *
+     * @param entityId - Entity ID
+     * @param component - Component name ('x', 'y', 'width', 'height')
+     * @returns Coordinate value (integer pixels)
+     */
+    getEntityCoord(entityId: number, component: string): number;
+}
+/**
+ * Interface for resolving Q-variable values.
+ */
+export interface QVariableResolver {
+    /**
+     * Get current value of a Q-variable.
+     *
+     * @param name - Q-variable name
+     * @returns Current value
+     */
+    getQValue(name: string): number;
+}
+/**
+ * Create a new FFI dispatcher instance.
+ */
+export declare function createFfiDispatcher(): FfiDispatcher;