@viewscript/renderer 0.1.0-202605140639

package/tests/e2e/fullstack.spec.ts

@@ -0,0 +1,681 @@
+/**
+ * Full-Stack E2E Tests: CLI -> Solver -> HMR -> Renderer Pipeline
+ *
+ * Phase 16: Comprehensive integration tests verifying the complete
+ * ViewScript pipeline from CODL command execution to visual rendering.
+ *
+ * ## Test Architecture
+ *
+ * These tests verify end-to-end correctness across all system layers:
+ *
+ * 1. CLI Layer: CODL command parsing and constraint generation
+ * 2. Solver Layer: Constraint graph evaluation in P-dimension
+ * 3. HMR Layer: Hot module replacement with T-vector preservation
+ * 4. Renderer Layer: Bilayer atomic updates (Canvas + DOM)
+ *
+ * ## Zero-Flakiness Strategy
+ *
+ * - Q-dimension isolation: Mock font metrics, fixed viewport, manual frame stepping
+ * - Deterministic synchronization: Double rAF wait for stable frame
+ * - No time-based assertions: Query actual state, not assumed timing
+ */
+
+import { test, expect, type Page } from '@playwright/test';
+
+// =============================================================================
+// Test Configuration
+// =============================================================================
+
+interface EntityBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface Constraint {
+  id: number;
+  target: number;
+  component: 'x' | 'y' | 'width' | 'height';
+  term: ConstraintTerm;
+}
+
+type ConstraintTerm =
+  | { type: 'const'; value: number }
+  | { type: 'linear'; coefficient: number; offset: number; tState: string }
+  | { type: 'ref'; entityId: number; component: string };
+
+// =============================================================================
+// Scenario A: CODL Command -> Constraint Propagation -> Visual Update
+// =============================================================================
+
+test.describe('Scenario A: CODL Execution to Visual Update', () => {
+  /**
+   * Test: CODL stack_horizontal command produces correct visual layout
+   *
+   * Initial State:
+   *   - box_a at x=100 (fixed)
+   *   - box_b unconstrained
+   *
+   * Trigger:
+   *   - Execute CODL: stack_horizontal(instances=[box_a, box_b], gap=20)
+   *
+   * Expected:
+   *   - box_b.x = box_a.x + box_a.width + gap
+   *   - Visual positions match constraint evaluation
+   */
+  test('CODL stack_horizontal produces correct visual positions', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Initial state: two boxes
+    const boxA: EntityBounds = { x: 100, y: 100, width: 80, height: 50 };
+    const boxB: EntityBounds = { x: 0, y: 100, width: 80, height: 50 };
+
+    await renderEntities(page, [
+      { id: 1, bounds: boxA, fill: '#0064C8' },
+      { id: 2, bounds: boxB, fill: '#C86400' },
+    ]);
+
+    // Verify initial state
+    let boundsA = await getEntityBounds(page, 1);
+    let boundsB = await getEntityBounds(page, 2);
+    expect(boundsA.x).toBe(100);
+    expect(boundsB.x).toBe(0);
+
+    // Simulate CODL execution: apply stack_horizontal constraint
+    // This mimics: vs run stack_horizontal --instances [1, 2] --gap 20
+    const gap = 20;
+    const constraints: Constraint[] = [
+      {
+        id: 1001,
+        target: 2,
+        component: 'x',
+        term: { type: 'const', value: boxA.x + boxA.width + gap },
+      },
+    ];
+
+    await applyConstraints(page, constraints);
+    await waitForStableFrame(page);
+
+    // Verify constraint propagation
+    boundsB = await getEntityBounds(page, 2);
+    const expectedX = boxA.x + boxA.width + gap; // 100 + 80 + 20 = 200
+    expect(boundsB.x).toBe(expectedX);
+
+    // Verify visual matches (sample pixel at expected position)
+    const pixelColor = await samplePixel(page, expectedX + 10, boxB.y + 10);
+    expect(pixelColor.r).toBeGreaterThan(150); // Orange has high R
+  });
+
+  /**
+   * Test: Transactional atomicity - rollback on overconstrained graph
+   *
+   * If applying a CODL command would create an overconstrained graph,
+   * the entire transaction must roll back with no visual changes.
+   */
+  test('overconstrained command rolls back without visual change', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Setup: box with two conflicting hard constraints
+    const boxA: EntityBounds = { x: 100, y: 100, width: 80, height: 50 };
+
+    await renderEntities(page, [
+      { id: 1, bounds: boxA, fill: '#0064C8' },
+    ]);
+
+    // Apply conflicting constraints (simulating rigidity error)
+    // In production, this would be caught by check_rigidity_for_codl_batch
+    const conflictingConstraints: Constraint[] = [
+      { id: 1001, target: 1, component: 'x', term: { type: 'const', value: 100 } },
+      { id: 1002, target: 1, component: 'x', term: { type: 'const', value: 200 } },
+    ];
+
+    // Capture state before
+    const boundsBefore = await getEntityBounds(page, 1);
+
+    // Attempt to apply (should fail and rollback)
+    const success = await applyConstraintsWithRollback(page, conflictingConstraints);
+    expect(success).toBe(false);
+
+    // Verify no visual change
+    const boundsAfter = await getEntityBounds(page, 1);
+    expect(boundsAfter.x).toBe(boundsBefore.x);
+  });
+});
+
+// =============================================================================
+// Scenario C: HMR Hot Reload -> T-Vector Preservation
+// =============================================================================
+
+test.describe('Scenario C: HMR with T-Vector Preservation', () => {
+  /**
+   * Test: User-dragged position preserved during HMR reload
+   *
+   * Critical invariant: If user has dragged an element (modifying T-vector),
+   * and source file changes trigger HMR, the dragged position MUST be
+   * preserved if the new constraints are satisfiable with current T-vector.
+   *
+   * Initial State:
+   *   - 3 boxes stacked vertically with gap=20
+   *   - User drags box_b to custom position
+   *
+   * Trigger:
+   *   - Source file change: gap updated from 20 to 40
+   *   - HMR fires constraint update
+   *
+   * Expected:
+   *   - box_b retains user-dragged position (T-vector preserved)
+   *   - box_c moves to accommodate new gap
+   */
+  test('HMR preserves user-dragged T-vector when satisfiable', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Setup: 3 boxes with vertical stack constraints
+    const boxes = [
+      { id: 1, bounds: { x: 100, y: 100, width: 80, height: 50 }, fill: '#FF0000' },
+      { id: 2, bounds: { x: 100, y: 170, width: 80, height: 50 }, fill: '#00FF00' },
+      { id: 3, bounds: { x: 100, y: 240, width: 80, height: 50 }, fill: '#0000FF' },
+    ];
+
+    await renderEntities(page, boxes);
+
+    // Apply initial constraints (gap = 20)
+    const initialConstraints: Constraint[] = [
+      { id: 1001, target: 2, component: 'y', term: { type: 'const', value: 170 } }, // 100 + 50 + 20
+      { id: 1002, target: 3, component: 'y', term: { type: 'const', value: 240 } }, // 170 + 50 + 20
+    ];
+    await applyConstraints(page, initialConstraints);
+    await waitForStableFrame(page);
+
+    // Simulate user drag: modify box_b's T-vector state
+    const userDraggedY = 200; // User dragged box_b down
+    await simulateUserDrag(page, 2, { x: 100, y: userDraggedY });
+    await waitForStableFrame(page);
+
+    // Verify dragged position
+    let boundsB = await getEntityBounds(page, 2);
+    expect(boundsB.y).toBe(userDraggedY);
+
+    // Simulate HMR: source file change updates gap from 20 to 40
+    // New constraints would be:
+    // box_b.y = box_a.y + box_a.height + 40 = 100 + 50 + 40 = 190
+    // box_c.y = box_b.y + box_b.height + 40 = (user position) + 50 + 40
+    //
+    // T-vector satisfiability check: Is userDraggedY compatible with new constraints?
+    // In this case, we have soft constraints, so T-vector is preserved.
+    await simulateHMRUpdate(page, {
+      preserveTVector: true,
+      newConstraints: [
+        { id: 1001, target: 2, component: 'y', term: { type: 'const', value: 190 } },
+        { id: 1002, target: 3, component: 'y', term: { type: 'const', value: userDraggedY + 50 + 40 } },
+      ],
+    });
+    await waitForStableFrame(page);
+
+    // Verify: box_b retains user-dragged position
+    boundsB = await getEntityBounds(page, 2);
+    expect(boundsB.y).toBe(userDraggedY);
+
+    // Verify: box_c moved to new position based on preserved box_b position
+    const boundsC = await getEntityBounds(page, 3);
+    expect(boundsC.y).toBe(userDraggedY + 50 + 40); // 290
+  });
+
+  /**
+   * Test: T-vector reset when new constraints are unsatisfiable
+   *
+   * If HMR produces constraints that conflict with current T-vector,
+   * the solver must recompute T-vector from scratch (no preservation).
+   */
+  test('HMR recomputes T-vector when constraints unsatisfiable', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Setup: single box with constraint
+    await renderEntities(page, [
+      { id: 1, bounds: { x: 100, y: 100, width: 80, height: 50 }, fill: '#FF0000' },
+    ]);
+
+    // Initial constraint
+    await applyConstraints(page, [
+      { id: 1001, target: 1, component: 'x', term: { type: 'const', value: 100 } },
+    ]);
+    await waitForStableFrame(page);
+
+    // Simulate user drag (soft override)
+    await simulateUserDrag(page, 1, { x: 200, y: 100 });
+    await waitForStableFrame(page);
+
+    // Verify drag applied
+    let bounds = await getEntityBounds(page, 1);
+    expect(bounds.x).toBe(200);
+
+    // HMR with hard constraint that conflicts with dragged position
+    // preserveTVector: false forces recomputation
+    await simulateHMRUpdate(page, {
+      preserveTVector: false,
+      newConstraints: [
+        { id: 1001, target: 1, component: 'x', term: { type: 'const', value: 50 } },
+      ],
+    });
+    await waitForStableFrame(page);
+
+    // Verify: position reset to new constraint value
+    bounds = await getEntityBounds(page, 1);
+    expect(bounds.x).toBe(50);
+  });
+});
+
+// =============================================================================
+// Task 4: Bilayer Synchronization Atomicity
+// =============================================================================
+
+test.describe('Bilayer Sync: Atomic Canvas + DOM Updates', () => {
+  /**
+   * Test: Canvas and DOM update in same rAF cycle
+   *
+   * Critical invariant: When a constraint update occurs, both the
+   * Canvas visual and DOM hit region must update atomically within
+   * the same requestAnimationFrame cycle.
+   *
+   * Verification method:
+   * - Instrument rAF to capture both Canvas state and DOM state
+   * - Assert they are updated in the same frame
+   */
+  test('constraint update applies to Canvas and DOM in same frame', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Setup: interactive box
+    await renderInteractiveEntities(page, [
+      { id: 1, bounds: { x: 100, y: 100, width: 80, height: 50 }, fill: '#0064C8' },
+    ]);
+    await waitForStableFrame(page);
+
+    // Instrument frame capture
+    await page.evaluate(() => {
+      (window as any).__VS_FRAME_CAPTURES__ = [];
+
+      const originalRAF = window.requestAnimationFrame;
+      window.requestAnimationFrame = (callback) => {
+        return originalRAF((timestamp) => {
+          // Capture state BEFORE callback
+          const renderer = (window as any).__VS_RENDERER__;
+          const canvasBounds = renderer.getEntityBounds(1);
+          const domEl = document.querySelector('[data-entity-id="1"]') as HTMLElement;
+          const domTransform = domEl?.style.transform || '';
+
+          (window as any).__VS_FRAME_CAPTURES__.push({
+            timestamp,
+            canvasX: canvasBounds?.x,
+            domTransform,
+            phase: 'before',
+          });
+
+          callback(timestamp);
+
+          // Capture state AFTER callback
+          const canvasBoundsAfter = renderer.getEntityBounds(1);
+          const domTransformAfter = domEl?.style.transform || '';
+
+          (window as any).__VS_FRAME_CAPTURES__.push({
+            timestamp,
+            canvasX: canvasBoundsAfter?.x,
+            domTransform: domTransformAfter,
+            phase: 'after',
+          });
+        });
+      };
+    });
+
+    // Wait one frame so the render loop re-registers itself through the wrapper.
+    // Without this, the first render loop rAF was queued before the wrapper was installed
+    // and would fire unwrapped, causing the constraint-apply frame to go undetected.
+    await waitForStableFrame(page);
+
+    // Apply constraint that moves entity
+    await applyConstraints(page, [
+      { id: 1001, target: 1, component: 'x', term: { type: 'const', value: 300 } },
+    ]);
+
+    // Wait for update to process (constraint is applied in the next rAF cycle)
+    await waitForStableFrame(page);
+
+    // Analyze frame captures
+    const captures = await page.evaluate(() => (window as any).__VS_FRAME_CAPTURES__);
+
+    // Find the frame where Canvas changed
+    let canvasChangeFrame: number | null = null;
+    let domChangeFrame: number | null = null;
+
+    for (let i = 1; i < captures.length; i++) {
+      const prev = captures[i - 1];
+      const curr = captures[i];
+
+      if (prev.canvasX !== curr.canvasX && curr.canvasX === 300) {
+        canvasChangeFrame = curr.timestamp;
+      }
+      if (prev.domTransform !== curr.domTransform && curr.domTransform.includes('300')) {
+        domChangeFrame = curr.timestamp;
+      }
+    }
+
+    // Assert: Both changes happened in the same frame
+    expect(canvasChangeFrame).not.toBeNull();
+    expect(domChangeFrame).not.toBeNull();
+    expect(canvasChangeFrame).toBe(domChangeFrame);
+  });
+
+  /**
+   * Test: No intermediate frame with desynchronized layers
+   *
+   * Verify that there is never a frame where Canvas shows new position
+   * but DOM still has old position (or vice versa).
+   */
+  test('no frame with desynchronized Canvas and DOM positions', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Setup
+    await renderInteractiveEntities(page, [
+      { id: 1, bounds: { x: 100, y: 100, width: 80, height: 50 }, fill: '#0064C8' },
+    ]);
+    await waitForStableFrame(page);
+
+    // Instrument detailed frame capture
+    await page.evaluate(() => {
+      (window as any).__VS_SYNC_VIOLATIONS__ = [];
+
+      const originalRAF = window.requestAnimationFrame;
+      window.requestAnimationFrame = (callback) => {
+        return originalRAF((timestamp) => {
+          callback(timestamp);
+
+          // After each frame, check synchronization
+          const renderer = (window as any).__VS_RENDERER__;
+          const canvasBounds = renderer.getEntityBounds(1);
+          const domEl = document.querySelector('[data-entity-id="1"]') as HTMLElement;
+
+          if (canvasBounds && domEl) {
+            // Extract X from transform
+            const match = domEl.style.transform.match(/translate3d\((\d+)px/);
+            const domX = match ? parseInt(match[1], 10) : null;
+
+            if (domX !== null && canvasBounds.x !== domX) {
+              (window as any).__VS_SYNC_VIOLATIONS__.push({
+                timestamp,
+                canvasX: canvasBounds.x,
+                domX,
+              });
+            }
+          }
+        });
+      };
+    });
+
+    // Apply multiple rapid constraint updates
+    for (let i = 0; i < 5; i++) {
+      await applyConstraints(page, [
+        { id: 1001, target: 1, component: 'x', term: { type: 'const', value: 100 + i * 50 } },
+      ]);
+      await page.waitForTimeout(16); // ~1 frame
+    }
+
+    await waitForStableFrame(page);
+
+    // Check for violations
+    const violations = await page.evaluate(() => (window as any).__VS_SYNC_VIOLATIONS__);
+    expect(violations).toHaveLength(0);
+  });
+});
+
+// =============================================================================
+// Q-Dimension Isolation (Zero-Flakiness)
+// =============================================================================
+
+test.describe('Q-Dimension Isolation', () => {
+  /**
+   * Test: Mocked measureText returns deterministic values
+   *
+   * Font metrics are Q-dimension (non-deterministic). This test verifies
+   * that our mock produces consistent results across runs.
+   */
+  test('mocked measureText returns deterministic width', async ({ page }) => {
+    await setupTestPage(page);
+
+    // Inject deterministic font metric mock via evaluate (page is already loaded)
+    // addInitScript would not apply after page.goto, so we use page.evaluate instead
+    await page.evaluate(() => {
+      CanvasRenderingContext2D.prototype.measureText = function(text: string) {
+        // Deterministic: 8px per character
+        return {
+          width: text.length * 8,
+          actualBoundingBoxAscent: 12,
+          actualBoundingBoxDescent: 3,
+          fontBoundingBoxAscent: 14,
+          fontBoundingBoxDescent: 4,
+          actualBoundingBoxLeft: 0,
+          actualBoundingBoxRight: text.length * 8,
+        } as unknown as TextMetrics;
+      };
+    });
+
+    // Measure same text multiple times
+    const results: number[] = [];
+    for (let i = 0; i < 10; i++) {
+      const width = await page.evaluate(() => {
+        const canvas = document.getElementById('vs-canvas') as HTMLCanvasElement;
+        const ctx = canvas.getContext('2d')!;
+        return ctx.measureText('Hello, ViewScript!').width;
+      });
+      results.push(width);
+    }
+
+    // All measurements must be identical
+    const firstResult = results[0];
+    for (const result of results) {
+      expect(result).toBe(firstResult);
+    }
+    expect(firstResult).toBe(18 * 8); // "Hello, ViewScript!" = 18 chars * 8px
+  });
+});
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+async function setupTestPage(page: Page): Promise<void> {
+  await page.goto('/test-harness.html');
+  await page.waitForFunction(() => (window as any).__VS_RENDERER_READY__ === true, {
+    timeout: 10000,
+  });
+}
+
+interface EntitySpec {
+  id: number;
+  bounds: EntityBounds;
+  fill: string;
+}
+
+async function renderEntities(page: Page, entities: EntitySpec[]): Promise<void> {
+  await page.evaluate((ents) => {
+    const renderer = (window as any).__VS_RENDERER__;
+    renderer.render({
+      entities: ents.map(e => ({
+        id: e.id,
+        type: 'rect',
+        bounds: e.bounds,
+        fill: e.fill,
+        interactive: false,
+      })),
+      constraints: [],
+    });
+  }, entities);
+  await waitForStableFrame(page);
+}
+
+async function renderInteractiveEntities(page: Page, entities: EntitySpec[]): Promise<void> {
+  await page.evaluate((ents) => {
+    const renderer = (window as any).__VS_RENDERER__;
+    renderer.render({
+      entities: ents.map(e => ({
+        id: e.id,
+        type: 'rect',
+        bounds: e.bounds,
+        fill: e.fill,
+        interactive: true,
+      })),
+      constraints: [],
+    });
+  }, entities);
+  await waitForStableFrame(page);
+}
+
+async function applyConstraints(page: Page, constraints: Constraint[]): Promise<void> {
+  await page.evaluate((cs) => {
+    const renderer = (window as any).__VS_RENDERER__;
+
+    // Use setConstraints to avoid recreating DOM elements (which would
+    // invalidate any cached DOM element references in frame-capture tests).
+    // The render loop's evaluateConstraints() will apply constraints each rAF cycle.
+    if (renderer.setConstraints) {
+      renderer.setConstraints(cs);
+    } else {
+      // Fallback: re-render preserving all entities
+      const allEntities = renderer.getAllEntities ? renderer.getAllEntities() : [];
+      renderer.render({ entities: allEntities, constraints: cs });
+    }
+  }, constraints);
+}
+
+async function applyConstraintsWithRollback(page: Page, constraints: Constraint[]): Promise<boolean> {
+  return await page.evaluate((cs) => {
+    // Check for conflicts
+    const targetComponents = new Map<string, number>();
+    for (const c of cs) {
+      const key = `${c.target}:${c.component}`;
+      const count = (targetComponents.get(key) || 0) + 1;
+      targetComponents.set(key, count);
+
+      if (count > 1) {
+        // Conflict detected - rollback (don't apply)
+        return false;
+      }
+    }
+
+    // No conflict - apply
+    const renderer = (window as any).__VS_RENDERER__;
+    for (const c of cs) {
+      const entity = renderer.getEntityBounds(c.target);
+      if (entity && c.term.type === 'const') {
+        entity[c.component] = c.term.value;
+      }
+    }
+    return true;
+  }, constraints);
+}
+
+async function getEntityBounds(page: Page, entityId: number): Promise<EntityBounds> {
+  return await page.evaluate((id) => {
+    const renderer = (window as any).__VS_RENDERER__;
+    return renderer.getEntityBounds(id);
+  }, entityId);
+}
+
+async function simulateUserDrag(
+  page: Page,
+  entityId: number,
+  newPosition: { x: number; y: number },
+): Promise<void> {
+  await page.evaluate(({ id, pos }) => {
+    const renderer = (window as any).__VS_RENDERER__;
+
+    // Use updateEntityBounds to modify the actual stored entity (not a stale copy)
+    renderer.updateEntityBounds(id, { x: pos.x, y: pos.y });
+
+    // Update T-vector state to mark as user-dragged
+    const tState = renderer.getTVectorState?.();
+    if (tState && tState[id]) {
+      tState[id].drag_progress = 1;
+    }
+  }, { id: entityId, pos: newPosition });
+}
+
+interface HMRUpdateConfig {
+  preserveTVector: boolean;
+  newConstraints: Constraint[];
+}
+
+async function simulateHMRUpdate(page: Page, config: HMRUpdateConfig): Promise<void> {
+  await page.evaluate((cfg) => {
+    const renderer = (window as any).__VS_RENDERER__;
+
+    if (!cfg.preserveTVector) {
+      // Reset T-vector state
+      const tState = renderer.getTVectorState?.();
+      if (tState) {
+        for (const id of Object.keys(tState)) {
+          tState[id] = {
+            hover: 0,
+            pressed: 0,
+            focused: 0,
+            scroll_x: 0,
+            scroll_y: 0,
+            drag_progress: 0,
+            animation_t: 0,
+            gesture_phase: 0,
+          };
+        }
+      }
+    }
+
+    // Register new constraints so the render loop evaluates them each rAF
+    renderer.setConstraints(cfg.newConstraints);
+
+    // Apply bounds immediately for non-dragged entities
+    for (const c of cfg.newConstraints) {
+      if (c.term.type !== 'const') continue;
+
+      const tState = renderer.getTVectorState?.();
+      const isDragged = cfg.preserveTVector && (tState?.[c.target]?.drag_progress > 0);
+
+      if (!isDragged) {
+        renderer.updateEntityBounds(c.target, { [c.component]: c.term.value });
+      }
+    }
+  }, config);
+}
+
+async function waitForStableFrame(page: Page): Promise<void> {
+  await page.evaluate(() => {
+    return new Promise<void>((resolve) => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => resolve());
+      });
+    });
+  });
+}
+
+async function samplePixel(
+  page: Page,
+  x: number,
+  y: number,
+): Promise<{ r: number; g: number; b: number }> {
+  return await page.evaluate(({ px, py }) => {
+    const canvas = document.getElementById('vs-canvas') as HTMLCanvasElement;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('No 2D context');
+
+    const rect = canvas.getBoundingClientRect();
+    const canvasX = px - rect.left;
+    const canvasY = py - rect.top;
+
+    const dpr = window.devicePixelRatio || 1;
+    const backingX = Math.floor(canvasX * dpr);
+    const backingY = Math.floor(canvasY * dpr);
+
+    const imageData = ctx.getImageData(backingX, backingY, 1, 1);
+    return {
+      r: imageData.data[0],
+      g: imageData.data[1],
+      b: imageData.data[2],
+    };
+  }, { px: x, py: y });
+}