@viewscript/renderer 0.1.0-202605140639

package/dist/runtime/event-backpressure.d.ts

@@ -0,0 +1,393 @@
+/**
+ * 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)
+ */
+import type { EntityId } from '../ast/types';
+/**
+ * Semantic T-vector state keys.
+ *
+ * Q-dimension events MUST target these state keys, NOT spatial coordinates.
+ * P-dimension spatial coordinates (X, Y, Z) are derived from constraints
+ * that reference T-vector state, never directly from Q-dimension input.
+ *
+ * ## The Ouroboros Prevention Principle
+ *
+ * If Q-dimension input (e.g., MouseEvent.clientX) were allowed to directly
+ * mutate P-dimension spatial coordinates, it would create a self-referential
+ * loop: mouse position → entity position → canvas render → mouse position...
+ *
+ * Instead, Q-dimension input mutates T-vector STATE, and the constraint
+ * solver derives spatial coordinates as a FUNCTION of that state.
+ */
+export type TStateKey = 'hover' | 'pressed' | 'focused' | 'scroll_x' | 'scroll_y' | 'drag_progress' | 'animation_t' | 'gesture_phase';
+/**
+ * Raw Q-dimension event from DOM.
+ *
+ * CRITICAL INVARIANT: Q-dimension events target T-vector STATE keys only.
+ * They NEVER directly modify P-dimension spatial coordinates (X, Y, Z).
+ */
+export interface QDimensionEvent {
+    /** Source entity that fired the event */
+    entityId: EntityId;
+    /** DOM event type */
+    eventType: QEventType;
+    /**
+     * Target T-vector state key.
+     *
+     * ARCHITECTURAL CONSTRAINT: This is a semantic state key, NOT a spatial
+     * coordinate. P-dimension coordinates are derived via constraint evaluation.
+     */
+    targetState: TStateKey;
+    /**
+     * State value (interpretation depends on targetState).
+     *
+     * - Boolean states: 0 = false, 1 = true
+     * - Normalized states: 0.0 to 1.0
+     * - Phase states: discrete integers
+     */
+    value: number;
+    /** Event timestamp (performance.now()) */
+    timestamp: number;
+    /** Priority (higher = more important) */
+    priority: EventPriority;
+}
+export type QEventType = 'click' | 'pointerdown' | 'pointerup' | 'pointermove' | 'scroll' | 'wheel' | 'keydown' | 'keyup' | 'focus' | 'blur';
+export declare enum EventPriority {
+    /** Immediate: click, keydown (user intent) */
+    CRITICAL = 3,
+    /** High: pointerdown/up (gesture start/end) */
+    HIGH = 2,
+    /** Normal: scroll, wheel (continuous) */
+    NORMAL = 1,
+    /** Low: pointermove (high frequency, lossy OK) */
+    LOW = 0
+}
+/**
+ * Coalesced event ready for frame processing.
+ *
+ * This represents a T-vector state mutation, NOT a spatial coordinate change.
+ */
+export interface CoalescedEvent {
+    entityId: EntityId;
+    /** The T-vector state key being mutated */
+    state: TStateKey;
+    /** The new state value */
+    value: number;
+    timestamp: number;
+}
+/**
+ * Backpressure configuration.
+ */
+export interface BackpressureConfig {
+    /** Max events to process per frame */
+    maxEventsPerFrame: number;
+    /** Throttle interval for LOW priority events (ms) */
+    lowPriorityThrottleMs: number;
+    /** Enable event coalescing (latest-only for same entity+component) */
+    enableCoalescing: boolean;
+}
+/**
+ * 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 declare class EventBuffer {
+    private config;
+    /** Coalesced events (latest-only per entity+component) */
+    private writeBuffer;
+    /** Non-coalesced critical events (click, keydown) */
+    private priorityQueue;
+    /** Last event time per key (for throttling) */
+    private lastEventTime;
+    /**
+     * Pending async events (from fetch, setTimeout, promises).
+     *
+     * These are isolated from sync events and merged at tick start
+     * to ensure deterministic ordering.
+     */
+    private pendingAsyncEvents;
+    constructor(config?: Partial<BackpressureConfig>);
+    /**
+     * 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: QDimensionEvent): void;
+    /**
+     * 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(): CoalescedEvent[];
+    /**
+     * Get current buffer sizes (for debugging/metrics).
+     */
+    getStats(): {
+        priorityQueueSize: number;
+        coalescedSize: number;
+        asyncPendingSize: number;
+    };
+    /**
+     * 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: QDimensionEvent): void;
+    /**
+     * 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(): void;
+}
+/**
+ * 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 declare class EventController {
+    private buffer;
+    private entityElements;
+    private boundHandlers;
+    constructor(buffer: EventBuffer);
+    /**
+     * Register a DOM element for event handling.
+     */
+    registerElement(entityId: EntityId, element: HTMLElement): void;
+    /**
+     * 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: EntityId, eventType: QEventType, targetState: TStateKey, valueMapper: (event: Event) => number): void;
+    /**
+     * Unbind all events for an entity.
+     */
+    unbindEntity(entityId: EntityId): void;
+    /**
+     * Map event type to priority.
+     */
+    private getPriority;
+}
+/**
+ * ## 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)
+ */