@viewscript/renderer 0.1.0-202605140639

package/dist/runtime/event-backpressure.js

@@ -0,0 +1,458 @@
+/**
+ * Q-Dimension Event Backpressure Control
+ *
+ * High-frequency DOM events (mousemove, scroll, pointermove) can fire
+ * hundreds of times per second. Without backpressure, each event would
+ * trigger a full constraint graph evaluation, overwhelming the solver.
+ *
+ * ## Strategy: Latest-Only Sampling with Frame Alignment
+ *
+ * ```
+ * Event Stream (60+ events/frame):
+ *   ─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─►
+ *    │ │ │ │ │ │ │ │ │ │ │ │
+ *    └─┴─┴─┴─┬─┴─┴─┴─┴─┬─┴─┴─►  Frame boundaries
+ *            │         │
+ *            ▼         ▼
+ *   Sampled: [latest]  [latest]   ← One value per frame
+ * ```
+ *
+ * This module provides:
+ * 1. Per-entity, per-component event coalescing
+ * 2. Frame-aligned sampling (sync with rAF)
+ * 3. Configurable throttle strategies
+ * 4. Priority queues for critical events (click > mousemove)
+ */
+export var EventPriority;
+(function (EventPriority) {
+    /** Immediate: click, keydown (user intent) */
+    EventPriority[EventPriority["CRITICAL"] = 3] = "CRITICAL";
+    /** High: pointerdown/up (gesture start/end) */
+    EventPriority[EventPriority["HIGH"] = 2] = "HIGH";
+    /** Normal: scroll, wheel (continuous) */
+    EventPriority[EventPriority["NORMAL"] = 1] = "NORMAL";
+    /** Low: pointermove (high frequency, lossy OK) */
+    EventPriority[EventPriority["LOW"] = 0] = "LOW";
+})(EventPriority || (EventPriority = {}));
+/**
+ * Double-buffered event accumulator.
+ *
+ * ## Data Structure
+ *
+ * ```
+ * writeBuffer (current frame events):
+ *   Map<CoalesceKey, QDimensionEvent>
+ *   - Key: "entity42:x"
+ *   - Value: Latest event for that entity+component
+ *   - Overwrites: Yes (latest-only sampling)
+ *
+ * priorityQueue (critical events):
+ *   Array<QDimensionEvent>
+ *   - Never coalesced (click, keydown must all fire)
+ *   - Processed first
+ *
+ * pendingAsyncEvents (async callback events):
+ *   Array<QDimensionEvent>
+ *   - Events from async callbacks (fetch, setTimeout, promises)
+ *   - Isolated from sync events to prevent race conditions
+ *   - Merged at tick start via mergeAsyncEvents()
+ * ```
+ *
+ * ## Async Atomicity (Phase 2 Remediation)
+ *
+ * Events from async callbacks (fetch handlers, setTimeout, etc.) arrive
+ * outside the rAF tick boundary. Without isolation, they could interleave
+ * with sync events causing non-deterministic ordering.
+ *
+ * Solution: Async events are buffered separately and merged atomically
+ * at the START of each tick, before any sync event processing.
+ */
+export class EventBuffer {
+    config;
+    /** Coalesced events (latest-only per entity+component) */
+    writeBuffer = new Map();
+    /** Non-coalesced critical events (click, keydown) */
+    priorityQueue = [];
+    /** Last event time per key (for throttling) */
+    lastEventTime = new Map();
+    /**
+     * Pending async events (from fetch, setTimeout, promises).
+     *
+     * These are isolated from sync events and merged at tick start
+     * to ensure deterministic ordering.
+     */
+    pendingAsyncEvents = [];
+    constructor(config = {}) {
+        this.config = {
+            maxEventsPerFrame: 50,
+            lowPriorityThrottleMs: 16, // ~60fps
+            enableCoalescing: true,
+            ...config,
+        };
+    }
+    /**
+     * Push a Q-dimension event into the buffer.
+     *
+     * ## Coalescing Rules
+     *
+     * 1. CRITICAL priority: Always queued, never coalesced
+     * 2. HIGH/NORMAL/LOW: Coalesced by entity+state (latest wins)
+     * 3. LOW with throttle: Dropped if within throttle window
+     */
+    push(event) {
+        const key = `${event.entityId}:${event.targetState}`;
+        // Critical events bypass coalescing
+        if (event.priority === EventPriority.CRITICAL) {
+            this.priorityQueue.push(event);
+            return;
+        }
+        // Throttle check for low-priority events
+        if (event.priority === EventPriority.LOW) {
+            const lastTime = this.lastEventTime.get(key) ?? 0;
+            if (event.timestamp - lastTime < this.config.lowPriorityThrottleMs) {
+                // Drop: within throttle window
+                return;
+            }
+        }
+        // Coalesce: overwrite previous event for same entity+component
+        if (this.config.enableCoalescing) {
+            this.writeBuffer.set(key, event);
+        }
+        else {
+            // No coalescing: treat as priority queue
+            this.priorityQueue.push(event);
+        }
+        this.lastEventTime.set(key, event.timestamp);
+    }
+    /**
+     * Flush buffer for frame processing.
+     *
+     * Returns events in priority order:
+     * 1. All CRITICAL events (in order received)
+     * 2. Coalesced events (limited by maxEventsPerFrame)
+     *
+     * ## Frame Alignment
+     *
+     * This method is called once per rAF tick. Events that arrive
+     * after flush() but before next tick accumulate in the buffer.
+     */
+    flush() {
+        const result = [];
+        const limit = this.config.maxEventsPerFrame;
+        // 1. Critical events first (never dropped)
+        for (const event of this.priorityQueue) {
+            result.push({
+                entityId: event.entityId,
+                state: event.targetState,
+                value: event.value,
+                timestamp: event.timestamp,
+            });
+        }
+        this.priorityQueue = [];
+        // 2. Coalesced events (up to limit)
+        const remaining = limit - result.length;
+        if (remaining > 0) {
+            const coalesced = Array.from(this.writeBuffer.values())
+                .sort((a, b) => b.priority - a.priority) // Higher priority first
+                .slice(0, remaining);
+            for (const event of coalesced) {
+                result.push({
+                    entityId: event.entityId,
+                    state: event.targetState,
+                    value: event.value,
+                    timestamp: event.timestamp,
+                });
+            }
+        }
+        // Clear coalesced buffer (events not taken are dropped)
+        this.writeBuffer.clear();
+        return result;
+    }
+    /**
+     * Get current buffer sizes (for debugging/metrics).
+     */
+    getStats() {
+        return {
+            priorityQueueSize: this.priorityQueue.length,
+            coalescedSize: this.writeBuffer.size,
+            asyncPendingSize: this.pendingAsyncEvents.length,
+        };
+    }
+    /**
+     * Push an event from an async callback.
+     *
+     * Use this method for events originating from:
+     * - fetch() handlers
+     * - setTimeout / setInterval callbacks
+     * - Promise .then() / .catch() handlers
+     * - WebSocket message handlers
+     * - IndexedDB callbacks
+     * - Any other async context
+     *
+     * ## Why Separate From push()?
+     *
+     * Async callbacks can fire at any time, potentially mid-tick or between
+     * ticks. If mixed with sync events without ordering guarantees, the result
+     * is non-deterministic constraint evaluation.
+     *
+     * By isolating async events, we ensure:
+     * 1. All async events are processed in FIFO order
+     * 2. They are merged BEFORE sync events at tick start
+     * 3. The tick sees a consistent snapshot of async state
+     *
+     * ## Example
+     *
+     * ```typescript
+     * fetch('/api/data').then(response => {
+     *   // WRONG: buffer.push(event) - could race with sync events
+     *   // CORRECT: buffer.pushAsync(event) - isolated until tick start
+     *   buffer.pushAsync({
+     *     entityId: 42,
+     *     eventType: 'custom',
+     *     targetState: 'animation_t',
+     *     value: response.progress,
+     *     timestamp: performance.now(),
+     *     priority: EventPriority.NORMAL,
+     *   });
+     * });
+     * ```
+     */
+    pushAsync(event) {
+        this.pendingAsyncEvents.push(event);
+    }
+    /**
+     * Merge pending async events into the main buffers.
+     *
+     * MUST be called at the START of each tick, BEFORE flush().
+     *
+     * This ensures:
+     * 1. Async events are processed before sync events from the same frame
+     * 2. No async events can arrive mid-flush (atomicity)
+     * 3. Deterministic ordering: async (FIFO) → sync (coalesced/priority)
+     *
+     * ## Call Site
+     *
+     * AtomicRenderLoop.tick():
+     * ```typescript
+     * function tick(timestamp) {
+     *   // FIRST: Merge async events atomically
+     *   eventBuffer.mergeAsyncEvents();
+     *
+     *   // THEN: Flush and process all events
+     *   const mutations = eventBuffer.flush();
+     *   // ... rest of tick
+     * }
+     * ```
+     */
+    mergeAsyncEvents() {
+        if (this.pendingAsyncEvents.length === 0) {
+            return;
+        }
+        // Process async events through the normal push() pipeline
+        // This applies coalescing and priority rules consistently
+        for (const event of this.pendingAsyncEvents) {
+            this.push(event);
+        }
+        // Clear the async buffer
+        this.pendingAsyncEvents = [];
+    }
+}
+// =============================================================================
+// Event Controller (DOM Binding Layer)
+// =============================================================================
+/**
+ * DOM event controller with automatic backpressure.
+ *
+ * ## Data Flow
+ *
+ * ```
+ * DOM Event (mousemove)
+ *     │
+ *     ▼
+ * EventController.handleEvent()
+ *     │
+ *     ├─▶ Compute T-vector value (from event data)
+ *     │
+ *     ├─▶ Wrap as QDimensionEvent
+ *     │
+ *     ▼
+ * EventBuffer.push()
+ *     │
+ *     ├─▶ Throttle check (LOW priority)
+ *     │
+ *     ├─▶ Coalesce (latest-only)
+ *     │
+ *     ▼
+ * Buffer accumulates until next rAF
+ *     │
+ *     ▼
+ * AtomicRenderLoop.tick()
+ *     │
+ *     ├─▶ EventBuffer.flush()
+ *     │
+ *     ▼
+ * CoalescedEvent[] → ConstraintSolver
+ * ```
+ */
+export class EventController {
+    buffer;
+    entityElements = new Map();
+    boundHandlers = new Map();
+    constructor(buffer) {
+        this.buffer = buffer;
+    }
+    /**
+     * Register a DOM element for event handling.
+     */
+    registerElement(entityId, element) {
+        this.entityElements.set(entityId, element);
+    }
+    /**
+     * Bind an event type to a T-vector state key.
+     *
+     * ## Ouroboros Prevention
+     *
+     * The valueMapper function MUST return a SEMANTIC state value, not a
+     * raw spatial coordinate. For example:
+     *
+     * CORRECT (semantic state):
+     *   - `'hover'` → (e) => e.type === 'pointerenter' ? 1 : 0
+     *   - `'scroll_y'` → (e) => e.target.scrollTop / e.target.scrollHeight
+     *   - `'drag_progress'` → (e) => computeNormalizedDragProgress(e)
+     *
+     * FORBIDDEN (spatial coordinate - would violate P/Q boundary):
+     *   - `'x'` → (e) => e.clientX   // NEVER DO THIS
+     *   - `'y'` → (e) => e.clientY   // NEVER DO THIS
+     *
+     * @param entityId - Entity to bind the event to
+     * @param eventType - DOM event type
+     * @param targetState - T-vector state key (semantic, not spatial)
+     * @param valueMapper - Function to compute state value from DOM event
+     */
+    bindEvent(entityId, eventType, targetState, valueMapper) {
+        const element = this.entityElements.get(entityId);
+        if (!element)
+            return;
+        const handler = (domEvent) => {
+            const qEvent = {
+                entityId,
+                eventType,
+                targetState,
+                value: valueMapper(domEvent),
+                timestamp: performance.now(),
+                priority: this.getPriority(eventType),
+            };
+            this.buffer.push(qEvent);
+        };
+        const key = `${entityId}:${eventType}`;
+        this.boundHandlers.set(key, handler);
+        // Use passive listeners where possible (scroll, wheel, pointermove)
+        const passive = ['scroll', 'wheel', 'pointermove'].includes(eventType);
+        element.addEventListener(eventType, handler, { passive });
+    }
+    /**
+     * Unbind all events for an entity.
+     */
+    unbindEntity(entityId) {
+        const element = this.entityElements.get(entityId);
+        if (!element)
+            return;
+        for (const [key, handler] of this.boundHandlers) {
+            if (key.startsWith(`${entityId}:`)) {
+                const eventType = key.split(':')[1];
+                element.removeEventListener(eventType, handler);
+                this.boundHandlers.delete(key);
+            }
+        }
+        this.entityElements.delete(entityId);
+    }
+    /**
+     * Map event type to priority.
+     */
+    getPriority(eventType) {
+        switch (eventType) {
+            case 'click':
+            case 'keydown':
+            case 'keyup':
+                return EventPriority.CRITICAL;
+            case 'pointerdown':
+            case 'pointerup':
+            case 'focus':
+            case 'blur':
+                return EventPriority.HIGH;
+            case 'scroll':
+            case 'wheel':
+                return EventPriority.NORMAL;
+            case 'pointermove':
+                return EventPriority.LOW;
+            default:
+                return EventPriority.NORMAL;
+        }
+    }
+}
+// =============================================================================
+// Usage Example
+// =============================================================================
+/**
+ * ## Integration with Render Loop
+ *
+ * ```typescript
+ * const buffer = new EventBuffer({ maxEventsPerFrame: 50 });
+ * const controller = new EventController(buffer);
+ *
+ * // Register entity's DOM element
+ * controller.registerElement(entity.id, domElement);
+ *
+ * // CORRECT: Bind semantic state (hover) to T-vector
+ * controller.bindEvent(
+ *   entity.id,
+ *   'pointerenter',
+ *   'hover',
+ *   () => 1  // hover = true
+ * );
+ * controller.bindEvent(
+ *   entity.id,
+ *   'pointerleave',
+ *   'hover',
+ *   () => 0  // hover = false
+ * );
+ *
+ * // CORRECT: Bind normalized scroll position
+ * controller.bindEvent(
+ *   entity.id,
+ *   'scroll',
+ *   'scroll_y',
+ *   (e: Event) => {
+ *     const target = e.target as HTMLElement;
+ *     const maxScroll = target.scrollHeight - target.clientHeight;
+ *     return maxScroll > 0 ? target.scrollTop / maxScroll : 0;
+ *   }
+ * );
+ *
+ * // In render loop tick():
+ * const events = buffer.flush();
+ *
+ * // Events are T-vector STATE mutations, not spatial coordinates
+ * // The constraint solver evaluates P-dimension coordinates AS A FUNCTION
+ * // of T-vector state (via constraints like: A.x = 100 when T.hover = 1)
+ * const stateMutations = events.map(e => ({
+ *   entityId: e.entityId,
+ *   state: e.state,      // Semantic state key (hover, scroll_y, etc.)
+ *   value: e.value,      // State value
+ *   timestamp: e.timestamp,
+ * }));
+ *
+ * // Constraint solver derives X, Y, Z from T-vector state
+ * constraintSolver.evaluateWithTVector(stateMutations);
+ * ```
+ *
+ * ## Architectural Guarantee: P/Q Boundary Preservation
+ *
+ * By restricting Q-dimension events to T-vector STATE keys (not spatial
+ * coordinates), we ensure that:
+ *
+ * 1. Mouse coordinates (clientX/Y) are NEVER directly assigned to P-dimension
+ * 2. P-dimension coordinates are always derived via constraint evaluation
+ * 3. The constraint graph is the SINGLE SOURCE OF TRUTH for spatial layout
+ * 4. LEAN 4 decidability proofs remain valid (no floating-point pollution)
+ */