@viewscript/renderer 0.1.0-202605140721 → 0.1.0-202605141229

package/dist/runtime/ffi-dispatcher.js

@@ -0,0 +1,291 @@
+/**
+ * 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 Dispatcher
+// =============================================================================
+export class FfiDispatcher {
+    /** Function registry: ffi_id -> entry */
+    registry = new Map();
+    /** Pending modules awaiting registration */
+    pendingModules = new Set();
+    /** Buffered results for next frame */
+    resultBuffer = [];
+    /** In-flight async calls (prevents duplicate dispatch while awaiting) */
+    inflight = new Set();
+    /** Entity coordinate resolver (injected) */
+    coordResolver = null;
+    /** Q-variable resolver (injected) */
+    qResolver = null;
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Load FFI manifest and build function registry.
+     *
+     * @param manifest - Parsed FfiManifest JSON
+     */
+    loadManifest(manifest) {
+        this.registry.clear();
+        this.pendingModules.clear();
+        // Register bindings
+        for (const binding of manifest.bindings) {
+            this.registry.set(binding.ffi_id, {
+                ffi_id: binding.ffi_id,
+                bind_name: binding.bind_name,
+                module_path: binding.module_path,
+                export_name: binding.export_name,
+                args: binding.args,
+                fn: null,
+            });
+            this.pendingModules.add(binding.module_path);
+        }
+        // Register triggers (each trigger has its own function reference)
+        for (const trigger of manifest.triggers) {
+            if (!this.registry.has(trigger.ffi_id)) {
+                this.registry.set(trigger.ffi_id, {
+                    ffi_id: trigger.ffi_id,
+                    bind_name: `trigger_${trigger.trigger_id}`, // Triggers don't have bind names
+                    module_path: trigger.module_path,
+                    export_name: trigger.export_name,
+                    args: trigger.args,
+                    fn: null,
+                });
+                this.pendingModules.add(trigger.module_path);
+            }
+        }
+    }
+    /**
+     * 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, module) {
+        for (const entry of this.registry.values()) {
+            if (entry.module_path === modulePath) {
+                const fn = module[entry.export_name];
+                if (typeof fn === 'function') {
+                    entry.fn = fn;
+                }
+                else {
+                    console.warn(`[FfiDispatcher] Export '${entry.export_name}' from '${modulePath}' is not a function`);
+                }
+            }
+        }
+        this.pendingModules.delete(modulePath);
+    }
+    /**
+     * Set the coordinate resolver for EntityCoord arguments.
+     */
+    setCoordinateResolver(resolver) {
+        this.coordResolver = resolver;
+    }
+    /**
+     * Set the Q-variable resolver for QRef arguments.
+     */
+    setQResolver(resolver) {
+        this.qResolver = resolver;
+    }
+    /**
+     * Get list of module paths that need to be imported.
+     */
+    getPendingModules() {
+        return [...this.pendingModules];
+    }
+    /**
+     * Check if all modules have been registered.
+     */
+    isReady() {
+        return this.pendingModules.size === 0;
+    }
+    /**
+     * 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) {
+        for (const call of pendingCalls) {
+            const entry = this.registry.get(call.ffi_id);
+            if (!entry) {
+                console.warn(`[FfiDispatcher] Unknown ffi_id: ${call.ffi_id}`);
+                continue;
+            }
+            if (!entry.fn) {
+                console.warn(`[FfiDispatcher] Function not registered for ffi_id ${call.ffi_id} ` +
+                    `(${entry.module_path}::${entry.export_name})`);
+                continue;
+            }
+            // In-flight guard: skip if previous async call hasn't completed
+            if (this.inflight.has(call.ffi_id)) {
+                continue;
+            }
+            try {
+                // Resolve arguments
+                const resolvedArgs = this.resolveArgs(entry.args, call.args);
+                // Call the function
+                const result = entry.fn(...resolvedArgs);
+                // Handle async (Promise) results
+                if (result instanceof Promise) {
+                    this.inflight.add(call.ffi_id);
+                    result
+                        .then((value) => {
+                        this.bufferResult(entry.bind_name, value);
+                    })
+                        .catch((error) => {
+                        console.error(`[FfiDispatcher] Async error in ${entry.export_name}:`, error);
+                    })
+                        .finally(() => {
+                        this.inflight.delete(call.ffi_id);
+                    });
+                }
+                else {
+                    // Handle sync results
+                    this.bufferResult(entry.bind_name, result);
+                }
+            }
+            catch (error) {
+                console.error(`[FfiDispatcher] Error calling ${entry.export_name}:`, error);
+            }
+        }
+    }
+    /**
+     * Buffer a result value if it's numeric.
+     */
+    bufferResult(bindName, result) {
+        const timestamp = performance.now();
+        if (typeof result === 'number') {
+            this.resultBuffer.push({
+                name: bindName,
+                value: result,
+                timestamp,
+            });
+        }
+        else if (result !== undefined && result !== null) {
+            // Attempt numeric coercion for non-number results
+            const numValue = Number(result);
+            if (!isNaN(numValue)) {
+                this.resultBuffer.push({
+                    name: bindName,
+                    value: numValue,
+                    timestamp,
+                });
+            }
+            // Non-numeric results are silently ignored (side-effect only functions)
+        }
+    }
+    /**
+     * 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() {
+        const results = this.resultBuffer;
+        this.resultBuffer = [];
+        return results;
+    }
+    /**
+     * Get the number of buffered results (for diagnostics).
+     */
+    getBufferedCount() {
+        return this.resultBuffer.length;
+    }
+    /**
+     * Get the number of in-flight async calls (for diagnostics/testing).
+     */
+    getInflightCount() {
+        return this.inflight.size;
+    }
+    /**
+     * Check if a specific ffi_id has an in-flight async call.
+     */
+    isInflight(ffiId) {
+        return this.inflight.has(ffiId);
+    }
+    // ===========================================================================
+    // Internal Helpers
+    // ===========================================================================
+    /**
+     * Resolve FfiArg array to concrete values.
+     *
+     * @param argSpecs - Argument specifications from manifest
+     * @param runtimeArgs - Runtime argument overrides from PendingFfiCall
+     */
+    resolveArgs(argSpecs, runtimeArgs) {
+        // If runtime args are provided, use them directly (pre-resolved by WASM)
+        if (runtimeArgs.length > 0) {
+            return runtimeArgs;
+        }
+        // Otherwise, resolve from specs
+        return argSpecs.map((spec) => this.resolveArg(spec));
+    }
+    /**
+     * Resolve a single FfiArg to its concrete value.
+     */
+    resolveArg(spec) {
+        switch (spec.type) {
+            case 'static':
+                return spec.value;
+            case 'q_ref':
+                if (this.qResolver) {
+                    return this.qResolver.getQValue(spec.name);
+                }
+                console.warn(`[FfiDispatcher] No Q resolver, cannot resolve ${spec.name}`);
+                return 0;
+            case 'entity_coord':
+                if (this.coordResolver) {
+                    return this.coordResolver.getEntityCoord(spec.entity_id, spec.component);
+                }
+                console.warn(`[FfiDispatcher] No coord resolver, cannot resolve entity ${spec.entity_id}.${spec.component}`);
+                return 0;
+            default:
+                console.warn(`[FfiDispatcher] Unknown arg type: ${spec.type}`);
+                return 0;
+        }
+    }
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a new FFI dispatcher instance.
+ */
+export function createFfiDispatcher() {
+    return new FfiDispatcher();
+}

package/dist/runtime/render-loop.d.ts

@@ -35,6 +35,8 @@
  * We NEVER touch: width, height, top, left, margin, padding (reflow triggers)
  */
 import type { EntityId, RenderableEntity, RasterBounds, PVectorBounds } from '../ast/types';
+import type { FfiDispatcher, PendingFfiCall } from './ffi-dispatcher.js';
+import type { WasmSolverBridge } from './wasm-solver-bridge.js';
 /**
  * Semantic T-vector state keys.
  * Mirrors the type from event-backpressure.ts.
@@ -91,6 +93,23 @@ export declare class AtomicRenderLoop {
      * Injected via setEventBuffer() to support mergeAsyncEvents() at tick start.
      */
     private eventBuffer;
+    /**
+     * FFI dispatcher for Phase 8 function evaluation.
+     *
+     * Injected via setFfiDispatcher() to support JS function calls after frame commit.
+     */
+    private ffiDispatcher;
+    /**
+     * Latest tick result from WASM solver (for Phase 8 FFI dispatch).
+     */
+    private latestTickResult;
+    /**
+     * Concrete solver bridge for FFI result injection (Phase 0.5).
+     *
+     * This is the concrete type of constraintSolver, used only for
+     * injectFfiResults(). The ConstraintSolver interface remains FFI-agnostic.
+     */
+    private solverBridge;
     constructor(config: Partial<RenderLoopConfig>, constraintSolver: ConstraintSolver, topologyRounder: TopologyRounder, canvasRenderer: CanvasRenderer, domLayer: DOMLayer);
     /**
      * Start the render loop.
@@ -112,6 +131,21 @@ export declare class AtomicRenderLoop {
      * at the start of each tick, ensuring deterministic event ordering.
      */
     setEventBuffer(buffer: EventBufferInterface): void;
+    /**
+     * Set the FFI dispatcher for Phase 8 function evaluation.
+     *
+     * The FFI dispatcher evaluates JS functions after frame commit and buffers
+     * results for the next frame's QSnapshot merge.
+     */
+    setFfiDispatcher(dispatcher: FfiDispatcher): void;
+    /**
+     * Set the concrete solver bridge for FFI result injection.
+     *
+     * The solver bridge is the concrete implementation of ConstraintSolver
+     * that supports injectFfiResults(). This must be the same instance
+     * as the constraintSolver passed to the constructor.
+     */
+    setSolverBridge(bridge: WasmSolverBridge): void;
     /**
      * Execute a single frame tick.
      *
@@ -176,8 +210,19 @@ export declare class AtomicRenderLoop {
  *
  * This ensures the constraint graph is the single source of truth.
  */
+/**
+ * Result of constraint solver evaluation.
+ *
+ * Contains both P-dimension bounds and pending FFI calls from WASM tick().
+ */
+interface SolverEvaluationResult {
+    /** P-dimension bounds for all entities */
+    bounds: Map<EntityId, PVectorBounds>;
+    /** Pending FFI calls from trigger evaluation (may be empty) */
+    pendingFfiCalls: PendingFfiCall[];
+}
 interface ConstraintSolver {
-    evaluate(mutations: TStateMutation[]): Map<EntityId, PVectorBounds>;
+    evaluate(mutations: TStateMutation[]): SolverEvaluationResult;
 }
 interface TopologyRounder {
     round(bounds: Map<EntityId, PVectorBounds>): {

package/dist/runtime/render-loop.js

@@ -54,6 +54,23 @@ export class AtomicRenderLoop {
      * Injected via setEventBuffer() to support mergeAsyncEvents() at tick start.
      */
     eventBuffer = null;
+    /**
+     * FFI dispatcher for Phase 8 function evaluation.
+     *
+     * Injected via setFfiDispatcher() to support JS function calls after frame commit.
+     */
+    ffiDispatcher = null;
+    /**
+     * Latest tick result from WASM solver (for Phase 8 FFI dispatch).
+     */
+    latestTickResult = null;
+    /**
+     * Concrete solver bridge for FFI result injection (Phase 0.5).
+     *
+     * This is the concrete type of constraintSolver, used only for
+     * injectFfiResults(). The ConstraintSolver interface remains FFI-agnostic.
+     */
+    solverBridge = null;
     constructor(config, constraintSolver, topologyRounder, canvasRenderer, domLayer) {
         this.config = {
             targetFPS: 60,
@@ -110,6 +127,25 @@ export class AtomicRenderLoop {
     setEventBuffer(buffer) {
         this.eventBuffer = buffer;
     }
+    /**
+     * Set the FFI dispatcher for Phase 8 function evaluation.
+     *
+     * The FFI dispatcher evaluates JS functions after frame commit and buffers
+     * results for the next frame's QSnapshot merge.
+     */
+    setFfiDispatcher(dispatcher) {
+        this.ffiDispatcher = dispatcher;
+    }
+    /**
+     * Set the concrete solver bridge for FFI result injection.
+     *
+     * The solver bridge is the concrete implementation of ConstraintSolver
+     * that supports injectFfiResults(). This must be the same instance
+     * as the constraintSolver passed to the constructor.
+     */
+    setSolverBridge(bridge) {
+        this.solverBridge = bridge;
+    }
     // ===========================================================================
     // Frame Execution (Atomic Commit)
     // ===========================================================================
@@ -140,13 +176,31 @@ export class AtomicRenderLoop {
             this.eventBuffer.mergeAsyncEvents();
         }
         // -------------------------------------------------------------------------
+        // Phase 0.5: Merge FFI Results from Previous Frame
+        // -------------------------------------------------------------------------
+        // FFI function results from Phase 8 of the previous frame are drained
+        // here and injected into the solver bridge. The bridge will include these
+        // values in the QSnapshot when evaluate() is called in Phase 2.
+        //
+        // This maintains the 1-frame latency required by Axiom 2 (Ouroboros Binding):
+        // FFI results flow Q→T→P, never directly into P-dimension.
+        if (this.ffiDispatcher && this.solverBridge) {
+            const ffiResults = this.ffiDispatcher.drainResults();
+            if (ffiResults.length > 0) {
+                this.solverBridge.injectFfiResults(ffiResults);
+            }
+        }
+        // -------------------------------------------------------------------------
         // Phase 1: Flush Pending Mutations (Backpressure-Limited)
         // -------------------------------------------------------------------------
         const mutations = this.flushMutations();
         // -------------------------------------------------------------------------
         // Phase 2: Evaluate Constraint Graph
         // -------------------------------------------------------------------------
-        const pVectorBounds = this.constraintSolver.evaluate(mutations);
+        const solverResult = this.constraintSolver.evaluate(mutations);
+        const pVectorBounds = solverResult.bounds;
+        // Store pending FFI calls for Phase 8 (after commit)
+        this.latestTickResult = { pending_ffi_calls: solverResult.pendingFfiCalls };
         // -------------------------------------------------------------------------
         // Phase 3: Topology-Preserving Rounding (with Error Distribution)
         // -------------------------------------------------------------------------
@@ -168,6 +222,18 @@ export class AtomicRenderLoop {
         // -------------------------------------------------------------------------
         this.commitFrame(drawCommands, domMutations);
         // -------------------------------------------------------------------------
+        // Phase 8: FFI Dispatch (Post-Commit)
+        // -------------------------------------------------------------------------
+        // FFI functions are evaluated AFTER frame commit to keep the rendering
+        // critical path (Phase 2-7) free of unpredictable latency. Results are
+        // buffered for consumption in the next frame's Phase 0.5.
+        //
+        // This utilizes the idle time between commitFrame() and the next rAF.
+        if (this.ffiDispatcher && this.latestTickResult) {
+            this.ffiDispatcher.dispatch(this.latestTickResult.pending_ffi_calls);
+            this.latestTickResult = null;
+        }
+        // -------------------------------------------------------------------------
         // Swap Buffers
         // -------------------------------------------------------------------------
         this.swapBuffers();

package/dist/runtime/wasm-solver-bridge.d.ts

@@ -0,0 +1,122 @@
+/**
+ * WASM Solver Bridge
+ *
+ * Implements ConstraintSolver by delegating to WasmViewScriptEngine.tick().
+ * Handles QSnapshot construction and TickResult parsing.
+ *
+ * ## Responsibilities
+ *
+ * 1. Convert TStateMutation[] to QSnapshot JSON format
+ * 2. Inject FFI results into QSnapshot.values (via injectFfiResults)
+ * 3. Call WasmViewScriptEngine.tick() with JSON payload
+ * 4. Parse TickResult and extract bounds + pendingFfiCalls
+ *
+ * ## Data Flow
+ *
+ * ```
+ * TStateMutation[] + FfiResult[]
+ *        │
+ *        ▼
+ *   buildQSnapshot()
+ *        │
+ *        ▼
+ *   QSnapshot JSON ─────► WasmViewScriptEngine.tick()
+ *                                   │
+ *                                   ▼
+ *                            TickResult JSON
+ *                                   │
+ *                                   ▼
+ *                         SolverEvaluationResult
+ * ```
+ */
+import type { EntityId, PVectorBounds } from '../ast/types.js';
+import type { FfiResult, PendingFfiCall } from './ffi-dispatcher.js';
+/**
+ * Semantic T-vector state keys.
+ */
+type TStateKey = 'hover' | 'pressed' | 'focused' | 'scroll_x' | 'scroll_y' | 'drag_progress' | 'animation_t' | 'gesture_phase';
+/**
+ * T-vector state mutation from Q-dimension event.
+ */
+export interface TStateMutation {
+    entityId: EntityId;
+    state: TStateKey;
+    value: number;
+    timestamp: number;
+}
+/**
+ * Result of constraint solver evaluation.
+ */
+export interface SolverEvaluationResult {
+    bounds: Map<EntityId, PVectorBounds>;
+    pendingFfiCalls: PendingFfiCall[];
+}
+/**
+ * ConstraintSolver interface.
+ *
+ * Note: This interface is FFI-agnostic. FFI result injection
+ * is handled by the concrete WasmSolverBridge implementation.
+ */
+export interface ConstraintSolver {
+    evaluate(mutations: TStateMutation[]): SolverEvaluationResult;
+}
+/**
+ * WASM engine interface (subset used by bridge).
+ */
+export interface WasmEngine {
+    tick(inputJson: string): string;
+}
+export declare class WasmSolverBridge implements ConstraintSolver {
+    private engine;
+    /** Pending FFI results to inject into next QSnapshot */
+    private pendingFfiResults;
+    /** Entity name to ID mapping (for mutation conversion) */
+    private entityNameToId;
+    /** Q-variable name to entity+state mapping */
+    private qVarMapping;
+    constructor(engine: WasmEngine);
+    /**
+     * Inject FFI results for the next evaluate() call.
+     *
+     * Called from render-loop Phase 0.5. Results are consumed
+     * and cleared when evaluate() runs.
+     *
+     * @param results - FFI function results from previous frame
+     */
+    injectFfiResults(results: FfiResult[]): void;
+    /**
+     * Register entity name to ID mapping.
+     *
+     * Called during initialization to enable mutation conversion.
+     */
+    registerEntity(name: string, id: EntityId): void;
+    /**
+     * Register Q-variable mapping.
+     *
+     * Maps Q-variable names to entity+state for mutation routing.
+     */
+    registerQVariable(name: string, entityId: EntityId, state: TStateKey): void;
+    /**
+     * Evaluate constraints and return solver result.
+     *
+     * Implements ConstraintSolver interface.
+     */
+    evaluate(mutations: TStateMutation[]): SolverEvaluationResult;
+    /**
+     * Build QSnapshot from mutations and FFI results.
+     */
+    private buildQSnapshot;
+    /**
+     * Get Q-variable name for an entity's T-state.
+     *
+     * Convention: `{entityId}_{state}` (e.g., "1_hover", "2_scroll_y")
+     */
+    private getQVarName;
+}
+/**
+ * Create a WASM solver bridge instance.
+ *
+ * @param engine - WasmViewScriptEngine instance
+ */
+export declare function createWasmSolverBridge(engine: WasmEngine): WasmSolverBridge;
+export {};