@mirage-engine/core 0.3.2 → 0.3.4

package/src/renderer/Renderer.ts

@@ -25,8 +25,14 @@ export class Renderer {
   private renderOrder: number = 0;
   public qualityFactor: number = 2;
   private mode: MirageMode = "overlay";
+  private canvasSize: "viewport" | "document" = "viewport";
   private clipArea: travelerClipArea = 1;
   public targetLayer: number | LayerTarget = "base";
+  private readonly overscan: number = 200;
+
+  private get isViewport(): boolean {
+    return this.mode === "overlay" && this.canvasSize === "viewport";
+  }
 
   private target: HTMLElement;
   private mountContainer: HTMLElement;
@@ -52,22 +58,24 @@ export class Renderer {
     this.mountContainer = mountContainer;
     this.registry = registry;
 
+    this.mode = config.mode ?? "overlay";
+    this.canvasSize = (config as any).canvasSize ?? "viewport";
+    this.clipArea = config.travelerClipArea ?? 1;
+    this.targetLayer = config.layer ?? "base";
+
     this.textureManager = new TextureLifecycleManager((el, texture) => {
       const mesh = this.registry.get(el);
       if (mesh && mesh.material instanceof THREE.ShaderMaterial) {
         Painter.forceUpdateUniforms(mesh.material, { texture: texture });
       }
-    });
+    }, this.isViewport);
 
-    this.mode = config.mode ?? "overlay";
-    this.clipArea = config.travelerClipArea ?? 1;
-    this.targetLayer = config.layer ?? "base";
     this.canvas = document.createElement("canvas");
     this.scene = new THREE.Scene();
 
     this.targetRect = this.target.getBoundingClientRect();
-    const width = this.targetRect.width;
-    const height = this.targetRect.height;
+    const width = this.isViewport ? window.innerWidth + this.overscan * 2 : this.targetRect.width;
+    const height = this.isViewport ? window.innerHeight + this.overscan * 2 : this.targetRect.height;
 
     // target duplicate mode
     // const width = target.parentElement!.clientWidth;
@@ -113,10 +121,12 @@ export class Renderer {
 
   public createRenderTarget() {
     for (let i = 0; i < ATTR_TRAVEL.MAX_LAYERS; i++) {
+      const width = this.isViewport ? window.innerWidth + this.overscan * 2 : this.targetRect.width;
+      const height = this.isViewport ? window.innerHeight + this.overscan * 2 : this.targetRect.height;
       this.renderTargets.push(
         new THREE.WebGLRenderTarget(
-          this.targetRect.width * this.qualityFactor,
-          this.targetRect.height * this.qualityFactor,
+          width * this.qualityFactor,
+          height * this.qualityFactor,
           {
             minFilter: THREE.LinearFilter,
             magFilter: THREE.LinearFilter,
@@ -160,8 +170,10 @@ export class Renderer {
   }
 
   private updateCanvasLayout() {
-    this.canvas.style.width = `${this.targetRect.width}px`;
-    this.canvas.style.height = `${this.targetRect.height}px`;
+    const width = this.isViewport ? window.innerWidth + this.overscan * 2 : this.targetRect.width;
+    const height = this.isViewport ? window.innerHeight + this.overscan * 2 : this.targetRect.height;
+    this.canvas.style.width = `${width}px`;
+    this.canvas.style.height = `${height}px`;
 
     if (this.mode === "duplicate") {
       this.canvas.style.position = "";
@@ -169,9 +181,9 @@ export class Renderer {
       this.canvas.style.left = "";
       this.canvas.style.display = "block";
     } else {
-      this.canvas.style.position = "absolute";
-      this.canvas.style.top = `${this.target.offsetTop}px`;
-      this.canvas.style.left = `${this.target.offsetLeft}px`;
+      this.canvas.style.position = this.isViewport ? "fixed" : "absolute";
+      this.canvas.style.top = this.isViewport ? `-${this.overscan}px` : `${this.target.offsetTop}px`;
+      this.canvas.style.left = this.isViewport ? `-${this.overscan}px` : `${this.target.offsetLeft}px`;
       this.canvas.style.display = "block";
     }
   }
@@ -222,10 +234,14 @@ export class Renderer {
 
   public syncScene(graphNode: SceneNode, pendingDeletions: Set<HTMLElement>) {
     const newRect = this.target.getBoundingClientRect();
+    const newWidth = this.isViewport ? window.innerWidth + this.overscan * 2 : newRect.width;
+    const newHeight = this.isViewport ? window.innerHeight + this.overscan * 2 : newRect.height;
+    const oldWidth = this.isViewport ? this.canvas.clientWidth : this.targetRect.width;
+    const oldHeight = this.isViewport ? this.canvas.clientHeight : this.targetRect.height;
 
     const isResized =
-      Math.abs(newRect.width - this.targetRect.width) > 0.1 ||
-      Math.abs(newRect.height - this.targetRect.height) > 0.1;
+      Math.abs(newWidth - oldWidth) > 0.1 ||
+      Math.abs(newHeight - oldHeight) > 0.1;
 
     const isMoved =
       this.mode === "overlay" &&
@@ -234,7 +250,7 @@ export class Renderer {
 
     if (isResized) {
       this.targetRect = newRect;
-      this.setSize(this.targetRect.width, this.targetRect.height);
+      this.setSize(newWidth, newHeight);
 
       this.updateCanvasLayout();
     } else if (isMoved) {
@@ -300,6 +316,16 @@ export class Renderer {
   private reconcileNode(node: SceneNode) {
     let mesh = this.registry.get(node.element) as THREE.Mesh | undefined;
       
+    const currentShaderHash = JSON.stringify(node.shaderHooks || null);
+
+    if (mesh && mesh.userData.shaderHash !== currentShaderHash) {
+      this.scene.remove(mesh);
+      mesh.geometry.dispose();
+      if (mesh.material instanceof THREE.Material) mesh.material.dispose();
+      this.registry.remove(node.element);
+      mesh = undefined;
+    }
+
     if (!mesh) {
       const geometry = new THREE.PlaneGeometry(1, 1);
       const initialTexture = node.isTraveler
@@ -324,6 +350,8 @@ export class Renderer {
       
       this.registry.register(node.element, mesh);
       mesh.userData.baseMaterial = material;
+      mesh.userData.domElement = node.element;
+      mesh.userData.shaderHash = currentShaderHash;
     }
 
 
@@ -483,7 +511,8 @@ export class Renderer {
     mesh.scale.set(rect.width, rect.height, 1);
 
     mesh.userData.domRect = {
-      ...rect,
+      x: rect.x,
+      y: rect.y,
       width: rect.width,
       height: rect.height,
     };
@@ -494,11 +523,16 @@ export class Renderer {
     const targetPageX = this.targetRect.left + window.scrollX;
     const targetPageY = this.targetRect.top + window.scrollY;
 
-    const localX = rect.x - targetPageX;
-    const localY = rect.y - targetPageY;
-
-    const baseX = localX - canvasWidth / 2 + rect.width / 2;
-    const baseY = -localY + canvasHeight / 2 - rect.height / 2;
+    let baseX: number, baseY: number;
+    if (this.isViewport) {
+      baseX = rect.x - window.innerWidth / 2 + rect.width / 2;
+      baseY = -rect.y + window.innerHeight / 2 - rect.height / 2;
+    } else {
+      const localX = rect.x - targetPageX;
+      const localY = rect.y - targetPageY;
+      baseX = localX - canvasWidth / 2 + rect.width / 2;
+      baseY = -localY + canvasHeight / 2 - rect.height / 2;
+    }
 
     mesh.position.set(
       baseX,
@@ -571,10 +605,16 @@ export class Renderer {
       }
 
       const nativeMesh = mesh.userData.nativeMesh as THREE.Mesh;
-      const nativeLocalX = node.nativeRect.x - targetPageX;
-      const nativeLocalY = node.nativeRect.y - targetPageY;
-      const nativeBaseX = nativeLocalX - canvasWidth / 2 + node.nativeRect.width / 2;
-      const nativeBaseY = -nativeLocalY + canvasHeight / 2 - node.nativeRect.height / 2;
+      let nativeBaseX: number, nativeBaseY: number;
+      if (this.isViewport) {
+        nativeBaseX = node.nativeRect.x - window.innerWidth / 2 + node.nativeRect.width / 2;
+        nativeBaseY = -node.nativeRect.y + window.innerHeight / 2 - node.nativeRect.height / 2;
+      } else {
+        const nativeLocalX = node.nativeRect.x - targetPageX;
+        const nativeLocalY = node.nativeRect.y - targetPageY;
+        nativeBaseX = nativeLocalX - canvasWidth / 2 + node.nativeRect.width / 2;
+        nativeBaseY = -nativeLocalY + canvasHeight / 2 - node.nativeRect.height / 2;
+      }
 
       nativeMesh.scale.set(node.nativeRect.width, node.nativeRect.height, 1);
       nativeMesh.position.set(
@@ -661,8 +701,8 @@ export class Renderer {
     this.camera.layers.set(targetLayer);
 
     const vector = new THREE.Vector3();
-    const canvasWidth = this.targetRect.width;
-    const canvasHeight = this.targetRect.height;
+    const canvasWidth = this.isViewport ? window.innerWidth + this.overscan * 2 : this.targetRect.width;
+    const canvasHeight = this.isViewport ? window.innerHeight + this.overscan * 2 : this.targetRect.height;
 
     const pixelRatio = this.renderer.getPixelRatio();
 
@@ -719,5 +759,72 @@ export class Renderer {
     this.renderer.render(this.scene, this.camera);
   }
 
-  
+  public syncMeshesByDOM() {
+    // If not in viewport mode, we must account for page scroll in absolute positions.
+    const targetPageX = this.targetRect.left + window.scrollX;
+    const targetPageY = this.targetRect.top + window.scrollY;
+
+    const pixelRatio = this.renderer.getPixelRatio();
+    const canvasWidth = this.renderer.domElement.width / pixelRatio;
+    const canvasHeight = this.renderer.domElement.height / pixelRatio;
+
+    this.scene.children.forEach((child) => {
+      const mesh = child as THREE.Mesh;
+      if (!mesh.userData || !mesh.userData.domElement) return;
+
+      const element = mesh.userData.domElement as HTMLElement;
+      let rect: DOMRect;
+      if (element.nodeType === Node.TEXT_NODE) {
+        const range = document.createRange();
+        range.selectNode(element);
+        rect = range.getBoundingClientRect();
+      } else {
+        rect = element.getBoundingClientRect();
+      }
+      const cached = mesh.userData.domRect;
+
+      // Update if position or size changed by more than 0.5px
+      if (
+        !cached ||
+        Math.abs(rect.x - cached.x) > 0.5 ||
+        Math.abs(rect.y - cached.y) > 0.5 ||
+        Math.abs(rect.width - cached.width) > 0.5 ||
+        Math.abs(rect.height - cached.height) > 0.5
+      ) {
+        mesh.userData.domRect = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+
+        let baseX: number, baseY: number;
+        if (this.isViewport) {
+          baseX = rect.x - window.innerWidth / 2 + rect.width / 2;
+          baseY = -rect.y + window.innerHeight / 2 - rect.height / 2;
+        } else {
+          const localX = rect.x - targetPageX;
+          const localY = rect.y - targetPageY;
+          baseX = localX - canvasWidth / 2 + rect.width / 2;
+          baseY = -localY + canvasHeight / 2 - rect.height / 2;
+        }
+
+        // Apply new position and scale
+        mesh.position.setX(baseX);
+        mesh.position.setY(baseY);
+        mesh.scale.set(rect.width, rect.height, 1);
+
+        // Update uniforms so shader-based drawing (like border-radius) doesn't stretch
+        if (mesh.material instanceof THREE.ShaderMaterial) {
+          Painter.forceUpdateUniforms(mesh.material, {
+            width: rect.width,
+            height: rect.height,
+          });
+        }
+
+        // Update native mesh if exists
+        if (mesh.userData.nativeMesh) {
+          const nativeMesh = mesh.userData.nativeMesh as THREE.Mesh;
+          nativeMesh.position.setX(baseX);
+          nativeMesh.position.setY(baseY);
+          nativeMesh.scale.set(rect.width, rect.height, 1);
+        }
+      }
+    });
+  }
 }

package/src/store/TextureLifecycleManager.ts

@@ -6,27 +6,29 @@ export type TextureReadyCallback = (
 ) => void;
 
 export class TextureLifecycleManager {
-  private observer: IntersectionObserver;
+  private observer?: IntersectionObserver;
   private textures: WeakMap<HTMLElement, THREE.Texture> = new WeakMap();
   private loadStatus: WeakMap<HTMLElement, boolean> = new WeakMap();
   private elementUrls: WeakMap<HTMLElement, string> = new WeakMap();
   private onUpdate: TextureReadyCallback;
 
-  constructor(onUpdate: TextureReadyCallback) {
+  constructor(onUpdate: TextureReadyCallback, enableCulling: boolean = true) {
     this.onUpdate = onUpdate;
-    this.observer = new IntersectionObserver(
-      (entries) => {
-        for (const entry of entries) {
-          const el = entry.target as HTMLElement;
-          if (entry.isIntersecting) {
-            this.loadTexture(el);
-          } else {
-            this.disposeTexture(el);
+    if (enableCulling) {
+      this.observer = new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            const el = entry.target as HTMLElement;
+            if (entry.isIntersecting) {
+              this.loadTexture(el);
+            } else {
+              this.disposeTexture(el);
+            }
           }
-        }
-      },
-      { rootMargin: "300px" },
-    );
+        },
+        { rootMargin: "300px" },
+      );
+    }
   }
 
   public register(element: HTMLElement, url: string) {
@@ -35,13 +37,17 @@ export class TextureLifecycleManager {
     if (currentUrl !== url) {
       this.elementUrls.set(element, url);
       // Restart observation to trigger intersecting check
-      this.observer.unobserve(element);
-      this.observer.observe(element);
+      if (this.observer) {
+        this.observer.unobserve(element);
+        this.observer.observe(element);
+      } else {
+        this.loadTexture(element);
+      }
     }
   }
 
   public unregister(element: HTMLElement) {
-    if (element.nodeType === Node.ELEMENT_NODE) {
+    if (element.nodeType === Node.ELEMENT_NODE && this.observer) {
       this.observer.unobserve(element);
     }
     this.disposeTexture(element);
@@ -118,7 +124,9 @@ export class TextureLifecycleManager {
   }
 
   public disposeAll() {
-    this.observer.disconnect();
+    if (this.observer) {
+      this.observer.disconnect();
+    }
     // Assuming WeakMap handles GC of remaining textures, but in WebGL we must explicitly delete.
     // However, WeakMap is not iterable, so we can't easily iterate and delete. 
     // The renderer should unregister nodes upon pendingDeletions.

package/src/types/attributes.ts

@@ -11,6 +11,7 @@ export const ATTR_DOM = {
   KEY: "mirageDom",
   VALUES: {
     HIDE: "hide",
+    SHOW: "show",
   },
 } as const;
 

package/src/types/config.ts

@@ -25,6 +25,15 @@ interface BaseConfig {
 
 export interface OverlayConfig extends BaseConfig {
   mode?: "overlay";
+  /**
+   * Defines the render size of the canvas and camera behavior.
+   * 'viewport' (default) is optimized for long scrollable pages by allocating canvas size 
+   * to the current screen viewport only, significantly improving performance (60fps).
+   * 'document' allocates the canvas size to match the full height of the target element,
+   * which can cause performance drops on very tall documents but might be necessary 
+   * for specific visual needs.
+   */
+  canvasSize?: "viewport" | "document";
 }
 
 export interface DuplicateConfig extends BaseConfig {