@mrigx/core 0.1.0

package/src/MrigEngine.ts

@@ -0,0 +1,834 @@
+export interface MrigConfig {
+  fluidViscosity?: number;
+  refractionScale?: number;
+  tearLimit?: number;
+  rippleHeight?: number;
+  abyssIntensity?: number;
+  parallaxIntensity?: number;
+}
+
+const DEFAULT_CONFIG: Required<MrigConfig> = {
+  fluidViscosity: 0.99,
+  refractionScale: 0.05,
+  tearLimit: 0.015,
+  rippleHeight: 1.0,
+  abyssIntensity: 0.0,
+  parallaxIntensity: 1.0
+};
+/**
+ * @file MrigEngine.ts
+ * @description The core WebGPU rendering engine and physics simulator for the Mrig Optical UI.
+ * Highly optimized, well-documented, and mathematically rigorous.
+ */
+
+import { WebGPUManager } from './WebGPUManager';
+import { AtlasManager } from './AtlasManager';
+import { toCanvas } from 'html-to-image';
+import type { SurfaceData, InteractionSource } from './types';
+import { simulationWGSL, surfaceMaskWGSL, opticalWGSL } from './shaders';
+import { resolveMaterialProps } from './utils';
+
+export class MrigEngine {
+  public gpuManager: WebGPUManager;
+  public atlasManager: AtlasManager;
+  private canvas: HTMLCanvasElement | null = null;
+  
+  // Pipeline state
+  private simPipeline!: GPURenderPipeline;
+  private maskPipeline!: GPURenderPipeline;
+  private opticalPipeline!: GPURenderPipeline;
+  
+  // Resources
+  private simTextures: GPUTexture[] = [];
+  private maskTexture!: GPUTexture;
+  private domTexture!: GPUTexture;
+  private dummyDomTexture!: GPUTexture;
+  private uniformBuffer!: GPUBuffer;
+  private uniformData!: Float32Array;
+  private sampler!: GPUSampler;
+  
+  // Bind Groups
+  private simBindGroups: GPUBindGroup[] = [];
+  private maskBindGroup!: GPUBindGroup;
+  private opticalBindGroups: GPUBindGroup[] = [];
+
+  // Data tracking
+  private surfaces: Map<string, SurfaceData> = new Map();
+  private interactions: InteractionSource[] = [];
+    private icePatches: { x: number, y: number, life: number }[] = [];
+  
+  // Loop state
+  private animationId: number = 0;
+  private frameIndex: number = 0;
+  private startTime: number = performance.now();
+  private isRunning: boolean = false;
+  private isInitialized: boolean = false;
+  
+  // Atlas Rasterization Queue
+  private rasterQueue = new Map<string, { data: SurfaceData, el: HTMLElement }>();
+  private isRasterizing = false;
+  private rasterStateListeners: ((state: boolean) => void)[] = [];
+  public onRasterStateChange(cb: (state: boolean) => void) {
+      this.rasterStateListeners.push(cb);
+      return () => { this.rasterStateListeners = this.rasterStateListeners.filter(l => l !== cb); };
+  }
+  private setRasterState(state: boolean) {
+      if (this.isRasterizing !== state) {
+          this.isRasterizing = state;
+          this.rasterStateListeners.forEach(cb => cb(state));
+      }
+  }
+  
+
+  constructor() {
+    if (typeof window !== 'undefined') {
+      const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+      this.prefersReducedMotion = mq.matches;
+      mq.addEventListener('change', e => this.prefersReducedMotion = e.matches);
+    }
+    this.gpuManager = new WebGPUManager();
+    this.atlasManager = new AtlasManager(this);
+    this.handleScroll = this.handleScroll.bind(this);
+    this.handlePointerMove = this.handlePointerMove.bind(this);
+        this.handlePointerDown = this.handlePointerDown.bind(this);
+      this.handleSelectionChange = this.handleSelectionChange.bind(this);
+    
+  }
+
+  /**
+   * Initializes the WebGPU context, builds pipelines, and allocates textures.
+   */
+  public async init(canvas: HTMLCanvasElement): Promise<boolean> {
+    if (this.isInitialized) return true;
+    this.isInitialized = true;
+
+    this.canvas = canvas;
+    const success = await this.gpuManager.init(canvas);
+    if (!success) return false;
+
+    this.createPipelines();
+    this.atlasManager.init();
+    this.createTextures();
+    
+    // Attach listeners
+    window.addEventListener('scroll', this.handleScroll, { passive: true });
+    window.addEventListener('mousemove', this.handlePointerMove, { passive: true });
+        window.addEventListener('mousedown', this.handlePointerDown, { passive: true });
+        window.addEventListener('mouseup', this.handlePointerUp, { passive: true });
+    document.addEventListener('selectionchange', this.handleSelectionChange, { passive: true });
+    
+    this.isRunning = true;
+    this.renderLoop();
+    return true;
+  }
+
+  private previousHighlightCount = 0;
+  private lastScrollY: number = window.scrollY || 0;
+  private accumulatedScroll: number = 0;
+  private prefersReducedMotion = false;
+  private transitionState = 1.0;
+  private transitionY = 0.0;
+  private config: Required<MrigConfig> = { ...DEFAULT_CONFIG };
+  
+  public setConfig(newConfig: MrigConfig) {
+      this.config = { ...this.config, ...newConfig };
+  }
+  public setTransition(opacity: number, y: number) {
+      this.transitionState = opacity;
+      this.transitionY = y;
+  }
+  
+  public setSelectionRects(rects: {x:number, y:number, w:number, h:number}[]) {
+      // Clear old highlights
+      for (let i = 0; i < this.previousHighlightCount; i++) {
+          this.unregisterSurface('hl_' + i);
+      }
+      this.previousHighlightCount = 0;
+
+      let registeredCount = 0;
+      for (let i = 0; i < rects.length; i++) {
+          const rect = rects[i];
+          if (rect.w === 0 || rect.h === 0) continue;
+          this.registerSurface('hl_' + registeredCount, {
+              x: rect.x,
+              y: rect.y,
+              width: rect.w,
+              height: rect.h,
+              config: {
+                  material: 'crystal',
+                  materialStrength: 3.0,
+                  borderRadius: 0,
+                  isHighlight: true
+              } as any
+          });
+          registeredCount++;
+      }
+      this.previousHighlightCount = registeredCount;
+  }
+
+  private handleSelectionChange() {
+    const selection = window.getSelection();
+    
+    // Clear old highlights
+    for (let i = 0; i < this.previousHighlightCount; i++) {
+        this.unregisterSurface('hl_' + i);
+    }
+    this.previousHighlightCount = 0;
+
+    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return;
+
+    let range;
+    try {
+        range = selection.getRangeAt(0);
+    } catch (e) {
+        return;
+    }
+    
+    const rects = range.getClientRects();
+    
+    const canvasWidth = window.innerWidth;
+    const canvasHeight = window.innerHeight;
+
+    let registeredCount = 0;
+    for (let i = 0; i < rects.length; i++) {
+        const rect = rects[i];
+        if (rect.width === 0 || rect.height === 0) continue;
+        
+        // Register the selection rect as an optical surface!
+        this.registerSurface('hl_' + registeredCount, {
+            x: rect.left / canvasWidth,
+            y: rect.top / canvasHeight,
+            width: rect.width / canvasWidth,
+            height: rect.height / canvasHeight,
+            config: {
+                material: 'crystal',
+                materialStrength: 3.0,
+                borderRadius: 0,
+                isHighlight: true
+            } as any
+        });
+        registeredCount++;
+    }
+    this.previousHighlightCount = registeredCount;
+  }
+
+  public destroy(): void {
+    this.isRunning = false;
+    cancelAnimationFrame(this.animationId);
+    window.removeEventListener('scroll', this.handleScroll);
+    window.removeEventListener('mousemove', this.handlePointerMove);
+        window.removeEventListener('mousedown', this.handlePointerDown);
+        window.removeEventListener('mouseup', this.handlePointerUp);
+    document.removeEventListener('selectionchange', this.handleSelectionChange);
+    this.simTextures.forEach(t => t.destroy());
+    if (this.maskTexture) this.maskTexture.destroy();
+    if (this.uniformBuffer) this.uniformBuffer.destroy();
+    this.atlasManager.destroy();
+    this.gpuManager.destroy();
+  }
+
+  /**
+   * Compiles the WGSL shaders and creates the render pipelines.
+   */
+  private createPipelines() {
+    const device = this.gpuManager.device!;
+    const format = this.gpuManager.format;
+
+    const simModule = device.createShaderModule({ code: simulationWGSL });
+    const maskModule = device.createShaderModule({ code: surfaceMaskWGSL });
+    const opticalModule = device.createShaderModule({ code: opticalWGSL });
+
+    // 1. Simulation Pipeline
+    this.simPipeline = device.createRenderPipeline({
+      layout: 'auto',
+      vertex: { module: simModule, entryPoint: 'vs_main' },
+      fragment: {
+        module: simModule,
+        entryPoint: 'fs_main',
+        targets: [{ format: 'rgba16float' }]
+      },
+      primitive: { topology: 'triangle-list' }
+    });
+
+    // 2. Surface Mask Pipeline (Draws instanced quads for surfaces)
+    this.maskPipeline = device.createRenderPipeline({
+      layout: 'auto',
+      vertex: { module: maskModule, entryPoint: 'vs_main' },
+      fragment: {
+        module: maskModule,
+        entryPoint: 'fs_main',
+        targets: [{
+          format: 'rgba16float',
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' }
+          }
+        }]
+      },
+      primitive: { topology: 'triangle-list' }
+    });
+
+    // 3. Final Optical Pipeline
+    this.opticalPipeline = device.createRenderPipeline({
+      layout: 'auto',
+      vertex: { module: opticalModule, entryPoint: 'vs_main' },
+      fragment: {
+        module: opticalModule,
+        entryPoint: 'fs_main',
+        targets: [{ format }]
+      },
+      primitive: { topology: 'triangle-list' }
+    });
+  }
+
+  /**
+   * Allocates the ping-pong simulation textures, mask texture, and uniform buffers.
+   */
+  private createTextures() {
+    const device = this.gpuManager.device!;
+    if (!this.canvas) return;
+
+    // Simulation uses half-resolution for performance and fluid dispersion
+    const simWidth = Math.max(1, Math.floor(this.canvas.width * 0.5));
+    const simHeight = Math.max(1, Math.floor(this.canvas.height * 0.5));
+
+    // Cleanup old textures if recreating
+    this.simTextures.forEach(t => t.destroy());
+    if (this.maskTexture) this.maskTexture.destroy();
+
+    this.simTextures = [];
+    for (let i = 0; i < 2; i++) {
+      this.simTextures.push(device.createTexture({
+        size: [simWidth, simHeight, 1],
+        format: 'rgba16float',
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+      }));
+    }
+
+    this.maskTexture = device.createTexture({
+      size: [this.canvas.width, this.canvas.height, 1],
+      format: 'rgba16float',
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+    });
+
+    this.sampler = device.createSampler({
+      magFilter: 'linear',
+      minFilter: 'linear',
+    });
+
+    if (!this.dummyDomTexture) {
+      this.dummyDomTexture = device.createTexture({
+        size: [1, 1, 1],
+        format: 'rgba8unorm',
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      });
+      device.queue.writeTexture(
+        { texture: this.dummyDomTexture },
+        new Uint8Array([0, 0, 0, 0]),
+        { bytesPerRow: 4 },
+        [1, 1, 1]
+      );
+      this.domTexture = this.dummyDomTexture;
+    }
+
+    // Uniform Buffer Layout:
+    // 0-11: Globals (time, scroll, resolution, counts, etc) -> 12 floats
+    // 12-267: 32 Interaction Sources (8 floats each = 256 floats)
+    // 268-779: 64 Surfaces (8 floats each = 512 floats)
+    // Total: 780 floats (3120 bytes). We round up to 4096 for alignment safety.
+    if (!this.uniformBuffer) {
+      this.uniformData = new Float32Array(2048);
+      this.uniformBuffer = device.createBuffer({
+        size: this.uniformData.byteLength,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      });
+    }
+
+    this.updateBindGroups();
+  }
+
+  /**
+   * Updates bind groups, usually called when textures (like domTexture) are recreated.
+   */
+  private updateBindGroups() {
+    const device = this.gpuManager.device!;
+    
+    this.maskBindGroup = device.createBindGroup({
+      layout: this.maskPipeline.getBindGroupLayout(0),
+      entries: [{ binding: 0, resource: { buffer: this.uniformBuffer } }]
+    });
+
+    this.simBindGroups = [];
+    this.opticalBindGroups = [];
+    for (let i = 0; i < 2; i++) {
+      this.simBindGroups.push(device.createBindGroup({
+        layout: this.simPipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: { buffer: this.uniformBuffer } },
+          { binding: 1, resource: this.simTextures[i].createView() },
+          { binding: 2, resource: this.sampler },
+          { binding: 3, resource: this.maskTexture.createView() }
+        ]
+      }));
+      
+      this.opticalBindGroups.push(device.createBindGroup({
+        layout: this.opticalPipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: { buffer: this.uniformBuffer } },
+          { binding: 1, resource: this.simTextures[i].createView() },
+          { binding: 2, resource: this.sampler },
+          { binding: 3, resource: this.maskTexture.createView() },
+          { binding: 4, resource: this.domTexture.createView() },
+          { binding: 5, resource: (this.atlasManager.texture || this.dummyDomTexture).createView() }
+        ]
+      }));
+    }
+  }
+
+  // --- Interaction & Surface API ---
+
+  public registerSurface(id: string, data: SurfaceData, el?: HTMLElement) {
+    // Instantly update the surface bounds for zero-latency GPU movement
+    this.surfaces.set(id, data);
+
+    // If dynamic, queue it for background rasterization to avoid blocking the main thread
+    if (data.config.isDynamic && el && this.atlasManager) {
+      this.rasterQueue.set(id, { data, el });
+      this.processRasterQueue();
+    }
+  }
+  
+  private processRasterQueue() {
+    if (this.isRasterizing || this.rasterQueue.size === 0) return;
+    this.setRasterState(true);
+
+    const runIdle = (window as any).requestIdleCallback || ((cb: any) => setTimeout(cb, 1));
+    
+    runIdle(async () => {
+      // Get the first item in the queue
+      const nextEntry = this.rasterQueue.entries().next().value;
+      if (!nextEntry) {
+          this.setRasterState(false);
+          return;
+      }
+      const [id, payload] = nextEntry;
+      this.rasterQueue.delete(id);
+
+      try {
+        const dpr = window.devicePixelRatio || 1;
+        // The heavy CPU work
+        const canvas = await toCanvas(payload.el, { backgroundColor: 'transparent', skipFonts: true, pixelRatio: dpr });
+        
+        // Ensure the surface wasn't unregistered while we were rendering
+        if (this.surfaces.has(id)) {
+          const region = this.atlasManager.uploadSprite(id, canvas);
+          if (region) {
+            // We mutate the live data object in the surfaces map
+            const liveData = this.surfaces.get(id);
+            if (liveData) liveData.atlasUV = region.uv;
+          }
+        }
+      } catch (e) {
+        console.warn('Mrig Atlas upload failed for', id, e);
+      }
+
+      this.setRasterState(false);
+      // Recursively process the rest of the queue
+      if (this.rasterQueue.size > 0) {
+        this.processRasterQueue();
+      }
+    });
+  }
+
+  public unregisterSurface(id: string) {
+    this.surfaces.delete(id);
+  }
+
+  public triggerDisturbance(x: number, y: number, strength: number = 1.0, radius: number = 0.06, type: number = 0.0, vx: number = 0, vy: number = 0) {
+    const dpr = window.devicePixelRatio || 1;
+      const docY = y + (window.scrollY / (window.innerHeight || 1));
+      this.interactions.push({ x, y, vx, vy, radius, strength, isActive: 1.0, type, docY });
+  }
+
+  /**
+   * Replaces the DOM texture used for optical refraction, triggering a bind group rebuild.
+   */
+  public updateDomTexture(newTexture: GPUTexture) {
+    const oldTexture = this.domTexture;
+    this.domTexture = newTexture;
+    this.updateBindGroups();
+    
+    if (oldTexture && oldTexture !== this.dummyDomTexture) {
+      oldTexture.destroy();
+    }
+  }
+
+  private handleScroll() {}
+
+  private lastMoveTime = 0;
+    private lastPointerX = 0;
+  private cursorState = { x: 0.5, y: 0.5, isText: 0.0, isClicking: 0.0 };
+    private lastPointerY = 0;
+    private handlePointerMove(e: MouseEvent) {
+      this.cursorState.x = e.clientX / window.innerWidth;
+      this.cursorState.y = e.clientY / window.innerHeight;
+      const target = e.target as HTMLElement;
+      if (target && target.tagName) {
+        const tag = target.tagName;
+        this.cursorState.isText = (tag === 'P' || tag === 'H1' || tag === 'H2' || tag === 'H3' || tag === 'H4' || tag === 'H5' || tag === 'H6' || tag === 'SPAN' || tag === 'A' || tag === 'LI' || tag === 'TD' || tag === 'TH' || (tag === 'INPUT' && (target as HTMLInputElement).type === 'text')) ? 1.0 : 0.0;
+      }
+      if (!this.canvas) return;
+      const now = performance.now();
+      const dt = Math.max(1, now - this.lastMoveTime);
+      if (dt < 16) return;
+      this.lastMoveTime = now;
+      
+      const rect = this.canvas.getBoundingClientRect();
+      const x = (e.clientX - rect.left) / rect.width;
+      const y = (e.clientY - rect.top) / rect.height;
+      
+      const vx = (x - this.lastPointerX) / dt;
+      const vy = (y - this.lastPointerY) / dt;
+      this.lastPointerX = x;
+      this.lastPointerY = y;
+      
+      this.triggerDisturbance(x, y, 0.1, 0.015, 0.0, vx, vy);
+    }
+
+
+  private handlePointerUp = (e: MouseEvent) => {
+    this.cursorState.isClicking = 0.0;
+  };
+  private handlePointerDown(e: MouseEvent) {
+    this.cursorState.isClicking = 1.0;
+    if (!this.canvas) return;
+    const rect = this.canvas.getBoundingClientRect();
+    const x = (e.clientX - rect.left) / rect.width;
+    const y = (e.clientY - rect.top) / rect.height;
+    this.triggerDisturbance(x, y, 0.3, 0.02, 0.0); // Tighter click ripple
+  }
+
+  private boats: InteractionSource[] = [];
+
+  /**
+   * Syncs CPU state (surfaces, interactions, time) to the GPU uniform buffer.
+   */
+  private updateUniforms() {
+      
+    const time = (performance.now() - this.startTime) / 1000.0;
+    const dpr = window.devicePixelRatio || 1;
+    const normScroll = window.scrollY / (window.innerHeight || 1);
+    
+    // Find true DOM bounds of the first section
+    const homeSection = document.querySelector('section');
+    const homeHeightNorm = homeSection ? (homeSection.offsetHeight / (window.innerHeight || 1)) : 1.0;
+    
+    // Initialize autonomous boats
+    if (this.boats.length === 0) {
+      for (let i = 0; i < 3; i++) {
+        this.boats.push({
+          x: 0.2 + Math.random() * 0.6,
+          y: 0,
+          docY: 0.2 + Math.random() * (homeHeightNorm - 0.4),
+          vx: 0,
+          vy: 0,
+          radius: 0.07,
+          strength: 0.4,
+          isActive: 1.0,
+          type: 1.0, // Boat type
+          angle: Math.random() * Math.PI * 2
+        });
+      }
+    }
+
+    // Update boats organic roaming (anchored to document space)
+    const aspect = this.canvas ? (this.canvas.width / this.canvas.height) : 1.0;
+    const lhX = 1.0 - (0.35 / aspect);
+    const lhDocY = 0.40;
+
+    // Age ice patches
+      this.icePatches.forEach(p => p.life -= 0.0015);
+      this.icePatches = this.icePatches.filter(p => p.life > 0);
+
+      this.boats.forEach(b => {
+        let inIce = false;
+        for (let j = 0; j < this.icePatches.length; j++) {
+            const p = this.icePatches[j];
+            const dist = Math.hypot(b.x - p.x, b.y - p.y);
+            if (dist < 0.06) { inIce = true; break; }
+        }
+        
+        const speed = inIce ? 0.000004 : 0.000024; // Lowered engine power by 12x to account for momentum accumulation
+        
+        // Accumulate desired steering forces
+        let desiredVx = Math.cos(b.angle!) * speed;
+        let desiredVy = Math.sin(b.angle!) * speed;
+        
+        // 1. Avoid Lighthouse (Collision Prevention)
+        const distLh = Math.sqrt(Math.pow(b.x - lhX, 2) + Math.pow(b.docY! - lhDocY, 2));
+        if (distLh < 0.15) {
+            const avoidForce = (0.15 - distLh) * 0.002;
+            desiredVx += ((b.x - lhX) / distLh) * avoidForce;
+            desiredVy += ((b.docY! - lhDocY) / distLh) * avoidForce;
+        }
+  
+        // 2. Avoid Other Boats (Collision Prevention)
+        this.boats.forEach(other => {
+            if (other === b) return;
+            const dx = b.x - other.x;
+            const dy = b.docY! - other.docY!;
+            const distSq = dx*dx + dy*dy;
+            if (distSq < 0.015) {
+                const dist = Math.max(0.0001, Math.sqrt(distSq));
+                  const avoidForce = (0.12 - dist) * 0.002;
+                desiredVx += (dx / dist) * avoidForce;
+                desiredVy += (dy / dist) * avoidForce;
+            }
+        });
+        
+        // 2.5 Follow Cursor Waves
+          this.interactions.forEach(interaction => {
+              if (interaction.isActive > 0 && interaction.docY !== undefined && interaction.type !== 1.0) {
+                  const dx = b.x - interaction.x;
+                  const dy = b.docY! - interaction.docY;
+                  const distSq = dx*dx + dy*dy;
+                  const dist = Math.max(0.0001, Math.sqrt(distSq));
+                  if (dist < 0.08) { 
+                      // Pushing it along the wave current (cursor velocity)
+                      const pushForce = (0.08 - dist) * 2.0; // Reduced force for Newtonian momentum
+                      desiredVx += interaction.vx * pushForce;
+                      desiredVy += interaction.vy * pushForce;
+                      
+                      // Outward radial push from the ripple
+                      const radialPush = (0.08 - dist) * 0.0002;
+                      desiredVx += (dx / dist) * radialPush;
+                      desiredVy += (dy / dist) * radialPush;
+                  }
+              }
+          });
+          
+          // 3. Soft boundaries
+        const margin = 0.1;
+        const turnForce = 0.001;
+        if (b.x < margin) desiredVx += turnForce;
+        if (b.x > 1.0 - margin) desiredVx -= turnForce;
+        if (b.docY! < margin) desiredVy += turnForce;
+        if (b.docY! > homeHeightNorm - margin) desiredVy -= turnForce;
+  
+        // 4. True Newtonian Physics
+        // Instead of erasing forces, we accumulate them!
+        b.vx += desiredVx;
+        b.vy += desiredVy;
+        
+        // Fluid drag
+        b.vx *= 0.92;
+        b.vy *= 0.92;
+        
+        // Boat Hull naturally tries to align with its velocity vector (like a weather vane)
+        const currentSpeed = Math.hypot(b.vx, b.vy);
+        if (currentSpeed > 0.0001) {
+            let targetAngle = Math.atan2(b.vy, b.vx);
+            let diff = targetAngle - b.angle!;
+            while (diff > Math.PI) diff -= Math.PI * 2;
+            while (diff < -Math.PI) diff += Math.PI * 2;
+            
+            // Turn slowly towards velocity vector (Creates natural wobble/drift when hit by side waves!)
+            let maxTurn = inIce ? 0.01 : 0.06;
+            b.angle! += Math.max(-maxTurn, Math.min(maxTurn, diff));
+        }
+        
+        b.x += b.vx;
+        if (b.docY === undefined) b.docY = b.y; 
+        b.docY += b.vy;
+        
+        // Map to screen coordinates based on scroll
+        b.y = b.docY - normScroll;
+      b.isActive = 1.0; 
+
+      
+    });
+    
+    // Globals
+    this.uniformData[0] = time;
+    this.uniformData[1] = window.scrollY * dpr;
+    this.uniformData[2] = this.canvas!.width;
+    this.uniformData[3] = this.canvas!.height;
+    
+    const u32 = new Uint32Array(this.uniformData.buffer);
+    
+    // Combine pointers (decayed separately) and autonomous boats
+    const activeInteractions = [
+      ...this.interactions.slice(0, 29),
+      ...this.boats
+    ].slice(0, 32);
+    
+    const activeSurfaces = Array.from(this.surfaces.values()).slice(0, 128);
+    
+    u32[4] = activeInteractions.length;
+    u32[5] = activeSurfaces.length;
+    this.uniformData[6] = (document.documentElement.scrollHeight || window.innerHeight) * dpr;
+    const rawScrollDelta = window.scrollY - this.lastScrollY;
+      this.lastScrollY = window.scrollY;
+      if (rawScrollDelta !== 0 && this.previousHighlightCount > 0) { this.handleSelectionChange(); }
+      
+      this.accumulatedScroll += rawScrollDelta * dpr;
+      const pixelShift = Math.round(this.accumulatedScroll);
+      this.accumulatedScroll -= pixelShift; // keep remainder
+      
+      this.uniformData[7] = pixelShift; // Pass exact integer pixel shift
+    this.uniformData[8] = (document.documentElement.scrollWidth || window.innerWidth) * dpr;
+      this.uniformData[9] = this.prefersReducedMotion ? 1.0 : 0.0;
+      this.uniformData[10] = this.transitionState;
+      this.uniformData[11] = this.transitionY * dpr;
+      this.uniformData[12] = this.config.fluidViscosity;
+      this.uniformData[13] = this.config.refractionScale;
+      this.uniformData[14] = this.config.tearLimit;
+      this.uniformData[15] = this.config.rippleHeight;
+      this.uniformData[16] = this.config.abyssIntensity;
+      this.uniformData[17] = this.config.parallaxIntensity;
+        this.uniformData[20] = this.cursorState.x;
+      this.uniformData[21] = this.cursorState.y;
+      this.uniformData[22] = this.cursorState.isText;
+      this.uniformData[23] = this.cursorState.isClicking;
+    
+    // Interactions
+    for (let i = 0; i < activeInteractions.length; i++) {
+      const src = activeInteractions[i];
+      const offset = 24 + i * 8;
+      this.uniformData[offset + 0] = src.x;
+      this.uniformData[offset + 1] = src.y;
+      this.uniformData[offset + 2] = src.vx;
+      this.uniformData[offset + 3] = src.vy;
+      this.uniformData[offset + 4] = src.radius;
+      this.uniformData[offset + 5] = src.strength;
+      this.uniformData[offset + 6] = src.isActive;
+      // Pack type and angle into padding. Base 1000 = boat.
+      this.uniformData[offset + 7] = src.type === 1.0 ? (1000.0 + src.angle!) : (src.type === 2.0 ? 2000.0 : 0.0);
+    }
+    
+    // Surfaces
+    for (let i = 0; i < activeSurfaces.length; i++) {
+      const surf = activeSurfaces[i];
+      const offset = 280 + i * 12; // 12 floats per surface
+      this.uniformData[offset + 0] = surf.x;
+      this.uniformData[offset + 1] = surf.y;
+      this.uniformData[offset + 2] = surf.width;
+      this.uniformData[offset + 3] = surf.height;
+      this.uniformData[offset + 4] = surf.config.borderRadius / window.innerHeight;
+      const props = resolveMaterialProps(surf.config.material);
+      this.uniformData[offset + 5] = (0.2 + surf.config.materialStrength * 0.8) * props.refMult;
+      this.uniformData[offset + 6] = surf.config.materialStrength * props.highMult;
+      this.uniformData[offset + 7] = (surf.config as any).isHighlight ? 1.0 : 0.0;
+      
+      if (surf.atlasUV) {
+        this.uniformData[offset + 8] = surf.atlasUV[0];
+        this.uniformData[offset + 9] = surf.atlasUV[1];
+        this.uniformData[offset + 10] = surf.atlasUV[2];
+        this.uniformData[offset + 11] = surf.atlasUV[3];
+      } else {
+        this.uniformData[offset + 8] = 0.0;
+        this.uniformData[offset + 9] = 0.0;
+        this.uniformData[offset + 10] = 0.0;
+        this.uniformData[offset + 11] = 0.0;
+      }
+    }
+
+    this.gpuManager.device!.queue.writeBuffer(
+      this.uniformBuffer, 0, this.uniformData.buffer, this.uniformData.byteOffset, this.uniformData.byteLength
+    );
+  }
+
+  /**
+   * The core WebGPU render loop executing the 3-pass physical pipeline.
+   */
+  private renderLoop() {
+    if (!this.isRunning || !this.gpuManager.device) return;
+
+    this.updateUniforms();
+
+    // Decay interactions after updating uniforms so they get rendered at least once
+    this.interactions = this.interactions
+      .map(i => ({ ...i, isActive: i.isActive - 0.25 }))
+      .filter(i => i.isActive > 0);
+
+    const readIndex = this.frameIndex % 2;
+    const writeIndex = (this.frameIndex + 1) % 2;
+    const commandEncoder = this.gpuManager.device.createCommandEncoder();
+
+    // Pass 1: Draw Surface Masks (Instanced Quads)
+    const surfaceCount = Math.min(this.surfaces.size, 64);
+    const maskPass = commandEncoder.beginRenderPass({
+      colorAttachments: [{
+        view: this.maskTexture.createView(),
+        clearValue: { r: 0.0, g: 0.0, b: 0.0, a: 0.0 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      }]
+    });
+    if (surfaceCount > 0) {
+      maskPass.setPipeline(this.maskPipeline);
+      maskPass.setBindGroup(0, this.maskBindGroup);
+      maskPass.draw(6, surfaceCount, 0, 0);
+    }
+    maskPass.end();
+
+    // Pass 2: Wave Simulation (Ping-Pong Compute over Fragment)
+    const simPass = commandEncoder.beginRenderPass({
+      colorAttachments: [{
+        view: this.simTextures[writeIndex].createView(),
+        clearValue: { r: 0.0, g: 0.0, b: 0.0, a: 0.0 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      }]
+    });
+    simPass.setPipeline(this.simPipeline);
+    simPass.setBindGroup(0, this.simBindGroups[readIndex]);
+    simPass.draw(3, 1, 0, 0);
+    simPass.end();
+
+    // Pass 3: Final Optical Compositing (Draws to screen)
+    const opticalPass = commandEncoder.beginRenderPass({
+      colorAttachments: [{
+        view: this.gpuManager.context!.getCurrentTexture().createView(),
+        clearValue: { r: 0.0, g: 0.0, b: 0.0, a: 1.0 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      }]
+    });
+    opticalPass.setPipeline(this.opticalPipeline);
+    opticalPass.setBindGroup(0, this.opticalBindGroups[writeIndex]);
+    opticalPass.draw(3, 1, 0, 0);
+    opticalPass.end();
+
+    this.gpuManager.device.queue.submit([commandEncoder.finish()]);
+    this.frameIndex++;
+    this.animationId = requestAnimationFrame(() => this.renderLoop());
+  }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+