@viewscript/renderer 0.1.0-202605140639

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

@@ -0,0 +1,277 @@
+/**
+ * Atomic Render Loop for ViewScript
+ *
+ * This module implements a frame-synchronous render pipeline that guarantees
+ * Canvas and DOM layers are updated atomically within a single animation frame.
+ *
+ * ## Architectural Invariant: No Frame Tearing
+ *
+ * If a button's visual representation moves at frame N, its DOM hit region
+ * MUST also move at frame N. Any desynchronization causes Q-dimension inputs
+ * to "hit the void" - a catastrophic UX failure.
+ *
+ * ## Strategy: Double-Buffered Dirty Tracking
+ *
+ * ```
+ * Frame N:
+ *   ┌─────────────────────────────────────────────────────────────────┐
+ *   │ 1. Flush pending T-vector mutations (from Q-dimension events)  │
+ *   │ 2. Evaluate constraint graph (P-dimension solver)              │
+ *   │ 3. Topology-preserving rounding (with error distribution)      │
+ *   │ 4. Diff against previous frame's RasterBounds                  │
+ *   │ 5. Batch Canvas draw commands (wgpu)                          │
+ *   │ 6. Batch DOM style mutations (transform only, no reflow)       │
+ *   │ 7. Commit: GpuRenderer.flush() + requestAnimationFrame boundary│
+ *   └─────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Reflow Prevention Strategy
+ *
+ * DOM mutations are restricted to compositor-only properties:
+ * - transform: translate3d(x, y, 0) - GPU-accelerated, no reflow
+ * - opacity - compositor-only
+ * - will-change: transform - hint to browser
+ *
+ * We NEVER touch: width, height, top, left, margin, padding (reflow triggers)
+ */
+import type { EntityId, RenderableEntity, RasterBounds, PVectorBounds } from '../ast/types';
+/**
+ * Semantic T-vector state keys.
+ * Mirrors the type from event-backpressure.ts.
+ */
+type TStateKey = 'hover' | 'pressed' | 'focused' | 'scroll_x' | 'scroll_y' | 'drag_progress' | 'animation_t' | 'gesture_phase';
+/**
+ * Pending T-vector state mutation from Q-dimension event.
+ *
+ * CRITICAL: These are SEMANTIC state mutations, not spatial coordinate
+ * assignments. P-dimension coordinates (X, Y, Z) are derived by the
+ * constraint solver as functions of T-vector state.
+ */
+interface TStateMutation {
+    entityId: EntityId;
+    /** Semantic state key (hover, scroll_y, etc.) - NOT spatial coordinates */
+    state: TStateKey;
+    /** State value (boolean as 0/1, normalized 0-1, or discrete phase) */
+    value: number;
+    timestamp: number;
+}
+/**
+ * Canvas draw command (batched for GPU renderer).
+ */
+interface DrawCommand {
+    entityId: EntityId;
+    type: 'path' | 'text' | 'image' | 'group';
+    bounds: RasterBounds;
+    payload: unknown;
+}
+/**
+ * Render loop configuration.
+ */
+export interface RenderLoopConfig {
+    /** Target frames per second (default: 60) */
+    targetFPS: number;
+    /** Enable debug timing logs */
+    debugTiming: boolean;
+    /** Maximum mutations per frame (backpressure) */
+    maxMutationsPerFrame: number;
+}
+export declare class AtomicRenderLoop {
+    private config;
+    private frameState;
+    private pendingMutations;
+    private isRunning;
+    private rafHandle;
+    private constraintSolver;
+    private topologyRounder;
+    private canvasRenderer;
+    private domLayer;
+    /**
+     * Event buffer for async event atomicity.
+     *
+     * Injected via setEventBuffer() to support mergeAsyncEvents() at tick start.
+     */
+    private eventBuffer;
+    constructor(config: Partial<RenderLoopConfig>, constraintSolver: ConstraintSolver, topologyRounder: TopologyRounder, canvasRenderer: CanvasRenderer, domLayer: DOMLayer);
+    /**
+     * Start the render loop.
+     */
+    start(): void;
+    /**
+     * Stop the render loop.
+     */
+    stop(): void;
+    /**
+     * Queue a T-vector mutation from Q-dimension event.
+     * Called from event handlers (backpressure-controlled).
+     */
+    queueMutation(mutation: TStateMutation): void;
+    /**
+     * Set the event buffer for async event atomicity.
+     *
+     * The event buffer is used to merge async events (from fetch, setTimeout, etc.)
+     * at the start of each tick, ensuring deterministic event ordering.
+     */
+    setEventBuffer(buffer: EventBufferInterface): void;
+    /**
+     * Execute a single frame tick.
+     *
+     * CRITICAL: This function executes entirely within a single rAF callback,
+     * ensuring Canvas and DOM updates are committed atomically before the
+     * browser's compositor thread runs.
+     */
+    private tick;
+    private scheduleFrame;
+    /**
+     * Phase 1: Flush pending mutations with backpressure limit.
+     */
+    private flushMutations;
+    /**
+     * Phase 4: Compute which entities changed this frame.
+     */
+    private computeDirtySet;
+    /**
+     * Phase 5: Build Canvas draw commands for dirty entities only.
+     */
+    private buildDrawCommands;
+    /**
+     * Phase 6: Build DOM mutations (transform-only, no reflow).
+     *
+     * CRITICAL: We use transform: translate3d() which is compositor-only.
+     * This means the GPU handles the positioning without triggering
+     * the browser's layout engine.
+     */
+    private buildDOMMutations;
+    /**
+     * Phase 7: Atomic commit of Canvas and DOM updates.
+     *
+     * This function guarantees that by the time rAF callback returns:
+     * 1. All wgpu draw commands have been flushed to GPU
+     * 2. All DOM transforms have been written
+     * 3. Browser's compositor will see consistent state
+     *
+     * ## Strict DOM Proxy Enforcement
+     *
+     * DOM elements are initialized with `initializeDOMProxyElement()` which
+     * installs a Proxy guard. Only `transform` can be modified here.
+     */
+    private commitFrame;
+    /**
+     * Swap frame buffers for next frame's diff.
+     */
+    private swapBuffers;
+}
+/**
+ * Constraint solver interface.
+ *
+ * ## P/Q Boundary Enforcement
+ *
+ * The solver receives T-vector STATE mutations (hover, scroll_y, etc.)
+ * and returns P-dimension SPATIAL coordinates (X, Y, Z).
+ *
+ * The solver is the ONLY component that derives spatial coordinates.
+ * It does so by evaluating constraints of the form:
+ *
+ *   A.x = 100 when A.T.hover = 1
+ *   A.x = 0 when A.T.hover = 0
+ *
+ * This ensures the constraint graph is the single source of truth.
+ */
+interface ConstraintSolver {
+    evaluate(mutations: TStateMutation[]): Map<EntityId, PVectorBounds>;
+}
+interface TopologyRounder {
+    round(bounds: Map<EntityId, PVectorBounds>): {
+        bounds: Map<EntityId, RasterBounds>;
+        violations: unknown[];
+    };
+}
+interface CanvasRenderer {
+    getEntity(id: EntityId): RenderableEntity | undefined;
+    draw(command: DrawCommand): void;
+    flush(): void;
+}
+interface DOMLayer {
+    getElement(id: EntityId): HTMLElement | undefined;
+    initializeProxyElement(id: EntityId, element: HTMLElement, bounds: RasterBounds): void;
+}
+/**
+ * Event buffer interface for async event atomicity.
+ *
+ * The render loop calls mergeAsyncEvents() at the start of each tick
+ * to integrate events from async callbacks (fetch, setTimeout, etc.)
+ * before processing sync events.
+ */
+interface EventBufferInterface {
+    /**
+     * Merge pending async events into the main buffers.
+     *
+     * Called at tick start to ensure deterministic event ordering.
+     */
+    mergeAsyncEvents(): void;
+}
+/**
+ * Initialize a DOM element as a strict ViewScript proxy.
+ *
+ * This function:
+ * 1. Sets all required CSS properties for compositor-only updates
+ * 2. Wraps the style object in a Proxy to prevent layout-triggering mutations
+ * 3. Ensures the element is a "transparent tactile proxy" with no visual rendering
+ *
+ * ## Architect Directive: Zero Layout Engine Intervention
+ *
+ * The browser's layout engine (Reflow) must NEVER be invoked by DOM proxy
+ * elements. All positioning is done via GPU-accelerated `transform: translate3d()`.
+ */
+export declare function initializeDOMProxyElement(element: HTMLElement, bounds: RasterBounds): void;
+/**
+ * Update a DOM proxy element's transform (position).
+ *
+ * This is the ONLY way to change a proxy element's position after initialization.
+ * It uses compositor-only transform, avoiding layout recalculation.
+ */
+export declare function updateDOMProxyTransform(element: HTMLElement, x: number, y: number): void;
+export {};
+/**
+ * ## tick() Control Flow (Pseudocode)
+ *
+ * ```
+ * function tick(timestamp):
+ *   // 1. Backpressure: Take at most N mutations from queue
+ *   mutations = pendingMutations.splice(0, MAX_PER_FRAME)
+ *
+ *   // 2. P-dimension: Solve constraints with new T-vector values
+ *   pBounds = constraintSolver.evaluate(mutations)
+ *
+ *   // 3. Rasterize: Rational → Integer with topology preservation
+ *   rBounds = topologyRounder.round(pBounds)
+ *
+ *   // 4. Diff: Find entities that changed since last frame
+ *   dirtySet = diff(previousBounds, rBounds)
+ *
+ *   // 5. Canvas: Build draw commands for dirty entities only
+ *   drawCmds = buildDrawCommands(dirtySet)
+ *
+ *   // 6. DOM: Build transform mutations (no width/height!)
+ *   domMuts = buildDOMMutations(dirtySet)
+ *
+ *   // 7. ATOMIC COMMIT (no interleaved reads/writes)
+ *   for cmd in drawCmds: canvasRenderer.draw(cmd)
+ *   canvasRenderer.flush()  // GPU sync point
+ *   for mut in domMuts: mut.element.style.transform = mut.transform
+ *
+ *   // 8. Swap buffers
+ *   previousBounds = rBounds
+ *
+ *   // 9. Schedule next frame
+ *   requestAnimationFrame(tick)
+ * ```
+ *
+ * ## Reflow Prevention Strategy
+ *
+ * 1. DOM elements are created once with fixed dimensions (via CSS)
+ * 2. Position changes use ONLY transform: translate3d()
+ * 3. translate3d() is compositor-only (GPU, no layout recalc)
+ * 4. will-change: transform hints browser to promote layer
+ * 5. All style writes happen before any reads (no thrashing)
+ * 6. Size changes require re-creating the element (rare)
+ */