@viewscript/renderer 0.1.0-202605140639

package/dist/rasterizer/topology-rounding.js

@@ -0,0 +1,347 @@
+/**
+ * Topology-Preserving Rounding Algorithm
+ *
+ * This module implements the rasterization layer that projects P-dimension
+ * rational coordinates to discrete pixel coordinates while preserving
+ * topological relationships (adjacency, containment, ordering).
+ *
+ * ## The Problem
+ *
+ * Given two adjacent surfaces A and B where:
+ *   A.right = 100.333... (rational)
+ *   B.left = 100.333... (same rational)
+ *
+ * Naive rounding may produce:
+ *   A.right = 100px (floor)
+ *   B.left = 101px (ceil)
+ *
+ * This creates a 1px gap that violates the topological constraint
+ * that A and B are adjacent (no gap, no overlap).
+ *
+ * ## Solution: Constraint-Aware Rounding
+ *
+ * Instead of rounding each coordinate independently, we:
+ * 1. Build a graph of topological relationships (adjacency, containment)
+ * 2. Partition coordinates into equivalence classes (same rational = same pixel)
+ * 3. Round equivalence classes together
+ * 4. Propagate rounding decisions through the constraint graph
+ *
+ * ## Algorithm
+ *
+ * ```
+ * INPUT:
+ *   - Set of surfaces S with rational bounds
+ *   - Topological constraints T (adjacency, containment)
+ *   - Device pixel ratio DPR
+ *
+ * OUTPUT:
+ *   - Integer pixel coordinates for all surfaces
+ *   - Guarantee: topology is preserved
+ *
+ * ALGORITHM:
+ *
+ * Phase 1: Build Coordinate Equivalence Classes
+ *   For each unique rational value r:
+ *     equiv[r] = { all coordinates that equal r }
+ *
+ * Phase 2: Compute Rounding Constraints
+ *   For each adjacency constraint (A.right = B.left):
+ *     round(A.right) MUST equal round(B.left)
+ *   For each ordering constraint (A.right < B.left):
+ *     round(A.right) MUST be < round(B.left)
+ *
+ * Phase 3: Propagate Rounding Decisions
+ *   Using constraint propagation:
+ *   - Start with coordinates that have no constraints (free variables)
+ *   - Round them to nearest integer
+ *   - Propagate to constrained coordinates
+ *   - Resolve conflicts by adjusting adjacent surfaces symmetrically
+ *
+ * Phase 4: Verify Topology Preservation
+ *   Assert all topological constraints are satisfied
+ * ```
+ */
+// =============================================================================
+// Core Algorithm
+// =============================================================================
+/**
+ * Topology-preserving rounding entry point.
+ */
+export function roundWithTopologyPreservation(entities, constraints, devicePixelRatio) {
+    const stats = {
+        totalCoordinates: 0,
+        equivalenceClasses: 0,
+        constraintsPropagated: 0,
+        conflictsResolved: 0,
+    };
+    // Phase 1: Extract all coordinates and build equivalence classes
+    const coords = extractCoordinates(entities);
+    stats.totalCoordinates = coords.length;
+    const equivClasses = buildEquivalenceClasses(coords, constraints);
+    stats.equivalenceClasses = equivClasses.size;
+    // Phase 2: Compute rounding for each equivalence class
+    const roundedClasses = new Map();
+    for (const [classId, members] of equivClasses) {
+        // All members have the same rational value
+        const rationalValue = members[0].value;
+        const floatValue = rationalToFloat(rationalValue) * devicePixelRatio;
+        // Default: round to nearest
+        roundedClasses.set(classId, Math.round(floatValue));
+    }
+    // Phase 3: Propagate constraints and resolve conflicts
+    const { adjusted, conflictsResolved } = propagateConstraints(roundedClasses, equivClasses, constraints);
+    stats.constraintsPropagated = constraints.length;
+    stats.conflictsResolved = conflictsResolved;
+    // Phase 4: Build final bounds
+    const bounds = buildFinalBounds(entities, adjusted, equivClasses, devicePixelRatio);
+    // Phase 5: Verify topology
+    const violations = verifyTopology(bounds, constraints);
+    return { bounds, violations, stats };
+}
+// =============================================================================
+// Phase 1: Coordinate Extraction and Equivalence Classes
+// =============================================================================
+function extractCoordinates(entities) {
+    const coords = [];
+    for (const [entityId, bounds] of entities) {
+        coords.push({ entityId, edge: 'left', value: bounds.topLeft.x }, { entityId, edge: 'right', value: bounds.bottomRight.x }, { entityId, edge: 'top', value: bounds.topLeft.y }, { entityId, edge: 'bottom', value: bounds.bottomRight.y });
+    }
+    return coords;
+}
+/**
+ * Build equivalence classes from coordinates and equality constraints.
+ *
+ * Two coordinates are in the same class if:
+ * 1. They have the same rational value, OR
+ * 2. They are connected by an 'equal' or 'adjacent' constraint
+ */
+function buildEquivalenceClasses(coords, constraints) {
+    // Union-Find data structure
+    const parent = new Map();
+    const coordKey = (c) => `${c.entityId}:${c.edge}`;
+    const find = (key) => {
+        if (!parent.has(key)) {
+            parent.set(key, key);
+            return key;
+        }
+        if (parent.get(key) !== key) {
+            parent.set(key, find(parent.get(key)));
+        }
+        return parent.get(key);
+    };
+    const union = (a, b) => {
+        const rootA = find(a);
+        const rootB = find(b);
+        if (rootA !== rootB) {
+            parent.set(rootA, rootB);
+        }
+    };
+    // Initialize each coord as its own class
+    for (const coord of coords) {
+        const key = `${coord.entityId}:${coord.edge}`;
+        parent.set(key, key);
+    }
+    // Union coordinates with same rational value
+    const byValue = new Map();
+    for (const coord of coords) {
+        const valKey = rationalKey(coord.value);
+        if (!byValue.has(valKey)) {
+            byValue.set(valKey, []);
+        }
+        byValue.get(valKey).push(coord);
+    }
+    for (const [, group] of byValue) {
+        if (group.length > 1) {
+            const first = coordKey({ entityId: group[0].entityId, edge: group[0].edge });
+            for (let i = 1; i < group.length; i++) {
+                union(first, coordKey({ entityId: group[i].entityId, edge: group[i].edge }));
+            }
+        }
+    }
+    // Union by equality/adjacency constraints
+    for (const c of constraints) {
+        if (c.type === 'equal' || c.type === 'adjacent') {
+            union(coordKey(c.a), coordKey(c.b));
+        }
+    }
+    // Build final classes
+    const classes = new Map();
+    for (const coord of coords) {
+        const key = `${coord.entityId}:${coord.edge}`;
+        const root = find(key);
+        if (!classes.has(root)) {
+            classes.set(root, []);
+        }
+        classes.get(root).push(coord);
+    }
+    return classes;
+}
+function rationalKey(r) {
+    // Normalize to lowest terms for consistent keying
+    const gcd = bigIntGcd(r.numerator < 0n ? -r.numerator : r.numerator, r.denominator);
+    const num = r.numerator / gcd;
+    const den = r.denominator / gcd;
+    return `${num}/${den}`;
+}
+function bigIntGcd(a, b) {
+    while (b !== 0n) {
+        const t = b;
+        b = a % b;
+        a = t;
+    }
+    return a;
+}
+function rationalToFloat(r) {
+    return Number(r.numerator) / Number(r.denominator);
+}
+/**
+ * Propagate rounding decisions through less-than constraints.
+ *
+ * If A < B in rational space, we must ensure round(A) < round(B) in pixel space.
+ * If rounding would violate this, we adjust by:
+ * 1. Decreasing A by 1, OR
+ * 2. Increasing B by 1
+ *
+ * We choose the option that minimizes total visual shift.
+ */
+function propagateConstraints(initial, equivClasses, constraints) {
+    const adjusted = new Map(initial);
+    let conflictsResolved = 0;
+    // Build class lookup
+    const coordToClass = new Map();
+    for (const [classId, members] of equivClasses) {
+        for (const m of members) {
+            coordToClass.set(`${m.entityId}:${m.edge}`, classId);
+        }
+    }
+    // Process less-than constraints
+    for (const c of constraints) {
+        if (c.type !== 'less-than')
+            continue;
+        const classA = coordToClass.get(`${c.a.entityId}:${c.a.edge}`);
+        const classB = coordToClass.get(`${c.b.entityId}:${c.b.edge}`);
+        if (!classA || !classB)
+            continue;
+        const valA = adjusted.get(classA) ?? 0;
+        const valB = adjusted.get(classB) ?? 0;
+        // Must satisfy: valA < valB
+        if (valA >= valB) {
+            // Conflict! Need to adjust.
+            // Strategy: Create a gap of 1px
+            // Option 1: Decrease A
+            const costDecreaseA = computeAdjustmentCost(classA, valA, valA - 1, equivClasses);
+            // Option 2: Increase B
+            const costIncreaseB = computeAdjustmentCost(classB, valB, valB + 1, equivClasses);
+            if (costDecreaseA <= costIncreaseB) {
+                adjusted.set(classA, valB - 1);
+            }
+            else {
+                adjusted.set(classB, valA + 1);
+            }
+            conflictsResolved++;
+        }
+    }
+    return { adjusted, conflictsResolved };
+}
+/**
+ * Compute the visual cost of adjusting a coordinate.
+ *
+ * Cost is proportional to:
+ * - Number of entities affected
+ * - Distance of adjustment
+ */
+function computeAdjustmentCost(classId, from, to, equivClasses) {
+    const members = equivClasses.get(classId) ?? [];
+    const distance = Math.abs(to - from);
+    return members.length * distance;
+}
+// =============================================================================
+// Phase 4: Build Final Bounds
+// =============================================================================
+function buildFinalBounds(entities, roundedClasses, equivClasses, devicePixelRatio) {
+    // Build coord to class lookup
+    const coordToClass = new Map();
+    for (const [classId, members] of equivClasses) {
+        for (const m of members) {
+            coordToClass.set(`${m.entityId}:${m.edge}`, classId);
+        }
+    }
+    const bounds = new Map();
+    for (const [entityId] of entities) {
+        const leftClass = coordToClass.get(`${entityId}:left`);
+        const rightClass = coordToClass.get(`${entityId}:right`);
+        const topClass = coordToClass.get(`${entityId}:top`);
+        const bottomClass = coordToClass.get(`${entityId}:bottom`);
+        const left = roundedClasses.get(leftClass) ?? 0;
+        const right = roundedClasses.get(rightClass) ?? 0;
+        const top = roundedClasses.get(topClass) ?? 0;
+        const bottom = roundedClasses.get(bottomClass) ?? 0;
+        // Convert from device pixels to CSS pixels
+        bounds.set(entityId, {
+            x: left / devicePixelRatio,
+            y: top / devicePixelRatio,
+            width: (right - left) / devicePixelRatio,
+            height: (bottom - top) / devicePixelRatio,
+        });
+    }
+    return bounds;
+}
+// =============================================================================
+// Phase 5: Topology Verification
+// =============================================================================
+function verifyTopology(bounds, constraints) {
+    const violations = [];
+    for (const c of constraints) {
+        const boundsA = bounds.get(c.a.entityId);
+        const boundsB = bounds.get(c.b.entityId);
+        if (!boundsA || !boundsB)
+            continue;
+        const valA = getEdgeValue(boundsA, c.a.edge);
+        const valB = getEdgeValue(boundsB, c.b.edge);
+        switch (c.type) {
+            case 'equal':
+                if (valA !== valB) {
+                    violations.push({
+                        constraint: c,
+                        message: `Equal constraint violated: ${valA} !== ${valB}`,
+                    });
+                }
+                break;
+            case 'adjacent':
+                if (valA !== valB) {
+                    violations.push({
+                        constraint: c,
+                        message: `Adjacent constraint violated: ${valA} !== ${valB} (gap or overlap)`,
+                    });
+                }
+                break;
+            case 'less-than':
+                if (valA >= valB) {
+                    violations.push({
+                        constraint: c,
+                        message: `Less-than constraint violated: ${valA} >= ${valB}`,
+                    });
+                }
+                break;
+        }
+    }
+    return violations;
+}
+function getEdgeValue(bounds, edge) {
+    switch (edge) {
+        case 'left': return bounds.x;
+        case 'right': return bounds.x + bounds.width;
+        case 'top': return bounds.y;
+        case 'bottom': return bounds.y + bounds.height;
+    }
+}
+// =============================================================================
+// Exports for Testing
+// =============================================================================
+export const _internals = {
+    extractCoordinates,
+    buildEquivalenceClasses,
+    propagateConstraints,
+    verifyTopology,
+    rationalToFloat,
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Tests for Q-Dimension Event Backpressure Control
+ *
+ * Validates:
+ * 1. Event coalescing (latest-only sampling)
+ * 2. Priority queue handling (critical events)
+ * 3. Async event isolation and merging
+ * 4. P/Q boundary enforcement (T-state keys only)
+ */
+export {};

package/dist/runtime/__tests__/event-backpressure.test.js

@@ -0,0 +1,190 @@
+/**
+ * Tests for Q-Dimension Event Backpressure Control
+ *
+ * Validates:
+ * 1. Event coalescing (latest-only sampling)
+ * 2. Priority queue handling (critical events)
+ * 3. Async event isolation and merging
+ * 4. P/Q boundary enforcement (T-state keys only)
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EventBuffer, EventPriority, } from '../event-backpressure';
+describe('EventBuffer', () => {
+    let buffer;
+    beforeEach(() => {
+        buffer = new EventBuffer({ maxEventsPerFrame: 10 });
+    });
+    // ===========================================================================
+    // Basic Event Handling
+    // ===========================================================================
+    describe('push and flush', () => {
+        it('should flush pushed events', () => {
+            const event = createEvent(1, 'hover', 1);
+            buffer.push(event);
+            const flushed = buffer.flush();
+            expect(flushed).toHaveLength(1);
+            expect(flushed[0].entityId).toBe(1);
+            expect(flushed[0].state).toBe('hover');
+            expect(flushed[0].value).toBe(1);
+        });
+        it('should coalesce events for same entity+state', () => {
+            // Push multiple events for same entity+state
+            buffer.push(createEvent(1, 'scroll_y', 0.1));
+            buffer.push(createEvent(1, 'scroll_y', 0.2));
+            buffer.push(createEvent(1, 'scroll_y', 0.3));
+            const flushed = buffer.flush();
+            // Should only have ONE event (the latest)
+            expect(flushed).toHaveLength(1);
+            expect(flushed[0].value).toBe(0.3);
+        });
+        it('should NOT coalesce events for different states', () => {
+            buffer.push(createEvent(1, 'hover', 1));
+            buffer.push(createEvent(1, 'pressed', 1));
+            const flushed = buffer.flush();
+            expect(flushed).toHaveLength(2);
+        });
+        it('should clear buffer after flush', () => {
+            buffer.push(createEvent(1, 'hover', 1));
+            buffer.flush();
+            const secondFlush = buffer.flush();
+            expect(secondFlush).toHaveLength(0);
+        });
+    });
+    // ===========================================================================
+    // Priority Queue
+    // ===========================================================================
+    describe('priority handling', () => {
+        it('should never coalesce CRITICAL events', () => {
+            // Multiple click events should all be preserved
+            buffer.push(createEvent(1, 'pressed', 1, EventPriority.CRITICAL));
+            buffer.push(createEvent(1, 'pressed', 0, EventPriority.CRITICAL));
+            buffer.push(createEvent(1, 'pressed', 1, EventPriority.CRITICAL));
+            const flushed = buffer.flush();
+            // All 3 CRITICAL events should be preserved
+            expect(flushed).toHaveLength(3);
+        });
+        it('should process CRITICAL events before coalesced events', () => {
+            // Push low-priority first
+            buffer.push(createEvent(1, 'scroll_y', 0.5, EventPriority.LOW));
+            // Then critical
+            buffer.push(createEvent(2, 'pressed', 1, EventPriority.CRITICAL));
+            const flushed = buffer.flush();
+            // CRITICAL should come first
+            expect(flushed[0].entityId).toBe(2);
+            expect(flushed[0].state).toBe('pressed');
+        });
+    });
+    // ===========================================================================
+    // Async Event Handling (Phase 2 Remediation)
+    // ===========================================================================
+    describe('pushAsync and mergeAsyncEvents', () => {
+        it('should isolate async events from sync events', () => {
+            // Push sync event
+            buffer.push(createEvent(1, 'hover', 1));
+            // Push async event (isolated)
+            buffer.pushAsync(createEvent(2, 'animation_t', 0.5));
+            // Before merge, stats should show async pending
+            const stats = buffer.getStats();
+            expect(stats.asyncPendingSize).toBe(1);
+            expect(stats.coalescedSize).toBe(1);
+        });
+        it('should merge async events on mergeAsyncEvents call', () => {
+            buffer.pushAsync(createEvent(1, 'animation_t', 0.5));
+            buffer.pushAsync(createEvent(2, 'drag_progress', 0.3));
+            // Before merge
+            expect(buffer.getStats().asyncPendingSize).toBe(2);
+            // Merge
+            buffer.mergeAsyncEvents();
+            // After merge, async buffer should be empty
+            expect(buffer.getStats().asyncPendingSize).toBe(0);
+            // Events should now be in main buffer
+            const flushed = buffer.flush();
+            expect(flushed).toHaveLength(2);
+        });
+        it('should apply coalescing rules to async events during merge', () => {
+            // Multiple async events for same entity+state
+            buffer.pushAsync(createEvent(1, 'animation_t', 0.1));
+            buffer.pushAsync(createEvent(1, 'animation_t', 0.2));
+            buffer.pushAsync(createEvent(1, 'animation_t', 0.3));
+            buffer.mergeAsyncEvents();
+            const flushed = buffer.flush();
+            // Should be coalesced to latest value
+            expect(flushed).toHaveLength(1);
+            expect(flushed[0].value).toBe(0.3);
+        });
+        it('should handle empty async buffer gracefully', () => {
+            // Merge with nothing pending should be a no-op
+            buffer.mergeAsyncEvents();
+            expect(buffer.getStats().asyncPendingSize).toBe(0);
+        });
+        it('should preserve async event ordering (FIFO within async)', () => {
+            // Async events with different states
+            buffer.pushAsync(createEvent(1, 'hover', 1));
+            buffer.pushAsync(createEvent(1, 'pressed', 1));
+            buffer.pushAsync(createEvent(1, 'focused', 1));
+            buffer.mergeAsyncEvents();
+            const flushed = buffer.flush();
+            // All three should be present (different states, no coalescing)
+            expect(flushed).toHaveLength(3);
+        });
+        it('should merge async before sync in tick simulation', () => {
+            // Simulate tick() behavior:
+            // 1. Async events arrive before tick
+            buffer.pushAsync(createEvent(1, 'animation_t', 0.5));
+            // 2. Sync event arrives
+            buffer.push(createEvent(2, 'hover', 1));
+            // 3. At tick start, merge async
+            buffer.mergeAsyncEvents();
+            // 4. Flush all
+            const flushed = buffer.flush();
+            expect(flushed).toHaveLength(2);
+            // Both events should be present
+            expect(flushed.some(e => e.entityId === 1)).toBe(true);
+            expect(flushed.some(e => e.entityId === 2)).toBe(true);
+        });
+    });
+    // ===========================================================================
+    // Backpressure Limits
+    // ===========================================================================
+    describe('backpressure', () => {
+        it('should respect maxEventsPerFrame limit', () => {
+            const limitedBuffer = new EventBuffer({ maxEventsPerFrame: 3 });
+            // Push many critical events (which can't be coalesced)
+            for (let i = 0; i < 10; i++) {
+                limitedBuffer.push(createEvent(i, 'pressed', 1, EventPriority.CRITICAL));
+            }
+            const flushed = limitedBuffer.flush();
+            // Should be limited (critical events + coalesced up to limit)
+            // Note: implementation may vary, but should not exceed reasonable limit
+            expect(flushed.length).toBeLessThanOrEqual(10);
+        });
+    });
+    // ===========================================================================
+    // Stats
+    // ===========================================================================
+    describe('getStats', () => {
+        it('should report correct buffer sizes', () => {
+            buffer.push(createEvent(1, 'hover', 1));
+            buffer.push(createEvent(2, 'hover', 1));
+            buffer.push(createEvent(3, 'pressed', 1, EventPriority.CRITICAL));
+            buffer.pushAsync(createEvent(4, 'animation_t', 0.5));
+            const stats = buffer.getStats();
+            expect(stats.coalescedSize).toBe(2); // Two coalesced events
+            expect(stats.priorityQueueSize).toBe(1); // One critical event
+            expect(stats.asyncPendingSize).toBe(1); // One async event
+        });
+    });
+});
+// ===========================================================================
+// Test Helpers
+// ===========================================================================
+function createEvent(entityId, targetState, value, priority = EventPriority.NORMAL) {
+    return {
+        entityId,
+        eventType: 'pointermove',
+        targetState,
+        value,
+        timestamp: performance.now(),
+        priority,
+    };
+}