@mirage-engine/core 0.2.0 → 0.2.2

package/src/renderer/Renderer.ts

@@ -7,8 +7,11 @@ import {
   MirageMode,
   USER_LAYER,
   SYSTEM_LAYER,
+  travelerClipArea,
 } from "../types";
 import { Painter } from "@mirage-engine/painter";
+import { MeshRegistry } from "../store/MeshRegistry";
+import { TextureLifecycleManager } from "../store/TextureLifecycleManager";
 
 export class Renderer {
   public readonly canvas: HTMLCanvasElement;
@@ -19,23 +22,38 @@ export class Renderer {
   private renderOrder: number = 0;
   private qualityFactor: number = 2;
   private mode: MirageMode = "overlay";
+  private clipArea: travelerClipArea = 1;
 
   private target: HTMLElement;
   private mountContainer: HTMLElement;
+  private registry: MeshRegistry;
   private targetRect: DOMRect;
 
-  private meshMap: Map<HTMLElement, THREE.Mesh> = new Map();
+  private travelers: Set<THREE.Mesh> = new Set();
+  private textureManager: TextureLifecycleManager;
+  // private meshMap: Map<HTMLElement, THREE.Mesh> = new Map();
+
+  public readonly fixedMeshes: Set<THREE.Mesh> = new Set();
 
   constructor(
     target: HTMLElement,
     config: CoreConfig,
     mountContainer: HTMLElement,
+    registry: MeshRegistry,
   ) {
     this.target = target;
     this.mountContainer = mountContainer;
+    this.registry = registry;
+    
+    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.mode = config.mode ?? "overlay";
-
+    this.clipArea = config.travelerClipArea ?? 1;
     this.canvas = document.createElement("canvas");
     this.scene = new THREE.Scene();
 
@@ -58,8 +76,6 @@ export class Renderer {
     this.camera.position.z = 100;
     this.camera.layers.set(0);
 
-    // [new]
-    // THREE.ColorManagement.enabled = false;
 
     this.renderer = new THREE.WebGLRenderer({
       canvas: this.canvas,
@@ -69,6 +85,11 @@ export class Renderer {
       // premultipliedAlpha: true
     });
 
+     
+    THREE.ColorManagement.enabled = false;
+    this.renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
+
+
     this.renderer.setPixelRatio(window.devicePixelRatio);
     this.renderer.setSize(width, height);
 
@@ -84,7 +105,7 @@ export class Renderer {
         format: THREE.RGBAFormat,
         stencilBuffer: false,
         depthBuffer: true,
-        samples: 4,
+        // samples: 0.7,
       },
     );
   }
@@ -136,6 +157,7 @@ export class Renderer {
   public dispose() {
     this.renderer.dispose();
     this.canvas.remove();
+    this.textureManager.disposeAll();
     // TODO: Scene 내부 Mesh들도 순회하며 dispose
   }
 
@@ -154,7 +176,7 @@ export class Renderer {
     this.camera.updateProjectionMatrix();
   }
 
-  public syncScene(graphNode: SceneNode) {
+  public syncScene(graphNode: SceneNode, pendingDeletions: Set<HTMLElement>) {
     const newRect = this.target.getBoundingClientRect();
 
     const isResized =
@@ -180,28 +202,59 @@ export class Renderer {
 
     this.renderOrder = 0;
 
-    const activeElements = new Set<HTMLElement>();
-
-    this.reconcileNode(graphNode, activeElements);
-
-    for (const [el, mesh] of this.meshMap.entries()) {
-      if (!activeElements.has(el)) {
-        this.scene.remove(mesh);
-
-        mesh.geometry.dispose();
-        if (mesh.material instanceof THREE.Material) mesh.material.dispose();
-        this.meshMap.delete(el);
-      }
+    // const activeElements = new Set<HTMLElement>();
+
+    // this.reconcileNode(graphNode, activeElements);
+    this.reconcileNode(graphNode);
+
+    if (pendingDeletions.size > 0) {
+      pendingDeletions.forEach((el) => {
+        const meshToDestroy = this.registry.get(el) as THREE.Mesh | undefined;
+        if (meshToDestroy) {
+          this.scene.remove(meshToDestroy);
+          this.travelers.delete(meshToDestroy);
+          this.fixedMeshes.delete(meshToDestroy);
+          meshToDestroy.geometry.dispose();
+          meshToDestroy.traverse((child) => {
+            if (child instanceof THREE.Mesh) {
+              if (child.geometry) child.geometry.dispose();
+              if (child.material) {
+                if (Array.isArray(child.material)) {
+                  child.material.forEach((mat) => mat.dispose());
+                } else {
+                  child.material.dispose();
+                }
+              }
+            }
+          });
+          this.registry.remove(el);
+          this.textureManager.unregister(el);
+        }
+      });
     }
+
+    //     mesh.geometry.dispose();
+    //     if (mesh.material instanceof THREE.Material) mesh.material.dispose();
+    //     this.meshMap.delete(el);
+    //   }
+    // }
   }
 
-  private reconcileNode(node: SceneNode, activeElements: Set<HTMLElement>) {
-    activeElements.add(node.element);
+  // 탐색 후 완성된 Scene node를 이용하여 mesh를 만들거나 조정
+  // => 이 과정에서 scene node에 있는 ele를 넣은 hash => activeElements
+  // => 이후 activeElements를 이용하여 mesh를 정리!!!+ map에서도 삭제
 
-    let mesh = this.meshMap.get(node.element);
+  // private reconcileNode(node: SceneNode, activeElements: Set<HTMLElement>) {
+  private reconcileNode(node: SceneNode) {
+    // activeElements.add(node.element);
+
+    // let mesh = this.meshMap.get(node.element);
+    let mesh = this.registry.get(node.element) as THREE.Mesh | undefined;
     if (!mesh) {
       const geometry = new THREE.PlaneGeometry(1, 1);
       let material: THREE.MeshBasicMaterial | THREE.Material;
+      const initialTexture = node.isTraveler ? this.renderTarget?.texture : this.textureManager.get(node.element);
+
       material = Painter.create(
         "BOX",
         node.styles,
@@ -209,23 +262,43 @@ export class Renderer {
         node.rect.width,
         node.rect.height,
         this.qualityFactor,
-        node.isTraveler ? this.renderTarget?.texture : undefined,
+        initialTexture,
+        node.shaderHooks,
       );
       mesh = new THREE.Mesh(geometry, material);
       if (node.type === "TEXT") mesh.name = "BG_MESH";
       this.scene.add(mesh);
-      this.meshMap.set(node.element, mesh);
+      this.registry.register(node.element, mesh);
     }
 
+    // [Important] use whene mesh animating with js
     mesh.userData.domRect = node.rect;
 
     this.updateMeshProperties(mesh, node);
     this.updateMeshLayers(mesh, node);
-    if (node.isTraveler) mesh.layers.enable(28);
+    if (node.isTraveler) {
+      mesh.layers.enable(28);
+      this.travelers.add(mesh);
+    } else {
+      mesh.layers.disable(28);
+      this.travelers.delete(mesh);
+    }
+
+    if (node.isFixed) {
+      this.fixedMeshes.add(mesh);
+    } else {
+      this.fixedMeshes.delete(mesh);
+    }
+
+    if (node.styles.imageSrc) {
+      this.textureManager.register(node.element, node.styles.imageSrc);
+    } else {
+      this.textureManager.unregister(node.element);
+    }
 
     if (node.type === "BOX") {
       for (const child of node.children) {
-        this.reconcileNode(child, activeElements);
+        this.reconcileNode(child);
       }
     } else if (node.type === "TEXT") {
       this.reconcileTextChild(mesh, node);
@@ -233,55 +306,66 @@ export class Renderer {
   }
 
   private reconcileTextChild(parentMesh: THREE.Mesh, node: SceneNode) {
-    let textMesh = parentMesh.children.find(
-      (c) => c.name === "TEXT_CHILD",
-    ) as THREE.Mesh;
-
-    const currentStyleHash = JSON.stringify(node.textStyles);
-    const cachedStyleHash = textMesh?.userData?.styleHash;
+    const lines = node.textLines || [{ text: node.textContent || "", rect: node.rect }];
+    const currentStyleHash = JSON.stringify(node.textStyles) + node.textContent + lines.map(l => l.text).join("|");
+    const cachedStyleHash = parentMesh.userData?.textChildStyleHash;
     const isDirty =
-      !textMesh ||
       node.dirtyMask & DIRTY_CONTENT ||
       currentStyleHash !== cachedStyleHash;
 
     if (isDirty) {
-      if (textMesh) {
+      // Remove all existing TEXT_CHILD meshes
+      const existingChildren = parentMesh.children.filter(c => c.name.startsWith("TEXT_CHILD"));
+      existingChildren.forEach(child => {
+        const textMesh = child as THREE.Mesh;
         (textMesh.material as THREE.MeshBasicMaterial).map?.dispose();
         textMesh.geometry.dispose();
         parentMesh.remove(textMesh);
-      }
-
-      const material = Painter.create(
-        "TEXT",
-        node.textStyles!,
-        node.textContent || "",
-        node.rect.width,
-        node.rect.height,
-        this.qualityFactor,
-      );
-
-      const geometry = new THREE.PlaneGeometry(1, 1);
-      textMesh = new THREE.Mesh(geometry, material);
-
-      textMesh.name = "TEXT_CHILD";
-      textMesh.userData = { styleHash: currentStyleHash };
-      this.updateMeshLayers(textMesh, node);
-      textMesh.position.z = 0.005;
-      parentMesh.add(textMesh);
-    }
+      });
 
-    if (textMesh) {
-      const parentRect = parentMesh.userData.domRect;
+      const parentRect = node.rect;
       const parentCenterX = parentRect.x + parentRect.width / 2;
       const parentCenterY = parentRect.y + parentRect.height / 2;
 
-      const textCenterX = node.rect.x + node.rect.width / 2;
-      const textCenterY = node.rect.y + node.rect.height / 2;
-
-      const offsetX = textCenterX - parentCenterX;
-      const offsetY = -(textCenterY - parentCenterY);
-
-      textMesh.position.set(offsetX, offsetY, 0.005);
+      lines.forEach((line, index) => {
+        const material = Painter.create(
+          "TEXT",
+          node.textStyles!,
+          line.text,
+          line.rect.width,
+          line.rect.height,
+          this.qualityFactor,
+        );
+
+        const geometry = new THREE.PlaneGeometry(1, 1);
+        const textMesh = new THREE.Mesh(geometry, material);
+
+        textMesh.name = `TEXT_CHILD_${index}`;
+        this.updateMeshLayers(textMesh, node);
+
+        // Parent is already scaled to node.rect.width/height. 
+        // We counter-scale the child so its absolute size is exactly line.rect.width/height.
+        const scaleX = node.rect.width === 0 ? 1 : line.rect.width / node.rect.width;
+        const scaleY = node.rect.height === 0 ? 1 : line.rect.height / node.rect.height;
+        textMesh.scale.set(scaleX, scaleY, 1);
+
+        const textCenterX = line.rect.x + line.rect.width / 2;
+        const textCenterY = line.rect.y + line.rect.height / 2;
+
+        const offsetX = textCenterX - parentCenterX;
+        const offsetY = -(textCenterY - parentCenterY);
+
+        // Position must also be counter-scaled relative to parent's scale
+        textMesh.position.set(
+          node.rect.width === 0 ? 0 : offsetX / node.rect.width,
+          node.rect.height === 0 ? 0 : offsetY / node.rect.height,
+          0.005
+        );
+
+        parentMesh.add(textMesh);
+      });
+
+      parentMesh.userData.textChildStyleHash = currentStyleHash;
     }
   }
 
@@ -303,11 +387,44 @@ export class Renderer {
     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;
+
     mesh.position.set(
-      localX - canvasWidth / 2 + rect.width / 2,
-      -localY + canvasHeight / 2 - rect.height / 2,
+      baseX,
+      baseY,
       styles.zIndex + this.renderOrder * Z_MICRO_OFFSET,
     );
+    const pureDOM_X = rect.x; // 트랜스폼 오염 전 순수 좌표 (가정)
+    const pureDOM_Y = rect.y;
+
+    mesh.userData.basePosition = { x: baseX, y: baseY };
+    mesh.userData.originalBasePosition = { x: baseX, y: baseY };
+    mesh.userData.baseSize = { width: rect.width, height: rect.height };
+    // ✨ 추가: 역산을 위한 순수 DOM 초기 좌표 저장
+    mesh.userData.baseDOM = { x: pureDOM_X, y: pureDOM_Y };
+    mesh.userData.isFixed = node.isFixed;
+    mesh.userData.initialScroll = { x: window.scrollX, y: window.scrollY };
+
+    // ✨ 추가: 초기 transform 상태를 저장하여 애니메이션 시 delta 값만 적용하도록 함 (이중 적용 방지)
+    const targetEl = node.element.nodeType === Node.TEXT_NODE ? node.element.parentElement! : node.element;
+    const computed = window.getComputedStyle(targetEl);
+    let baseTx = 0, baseTy = 0;
+    if (computed.transform && computed.transform !== "none") {
+      const matrix = new DOMMatrix(computed.transform);
+      baseTx = matrix.m41;
+      baseTy = matrix.m42;
+    }
+    mesh.userData.baseTransform = { x: baseTx, y: baseTy };
+
+    // ✨ 추가: 애니메이션이 끝나고 씬이 갱신되면 비율 캐시 초기화!
+    delete mesh.userData.originRatioX;
+    delete mesh.userData.originRatioY;
+    // mesh.position.set(
+    //   localX - canvasWidth / 2 + rect.width / 2,
+    //   -localY + canvasHeight / 2 - rect.height / 2,
+    //   styles.zIndex + this.renderOrder * Z_MICRO_OFFSET,
+    // );
     Painter.update(
       mesh.material as THREE.Material,
       "BOX",
@@ -316,7 +433,7 @@ export class Renderer {
       node.rect.width,
       node.rect.height,
       this.qualityFactor,
-      node.isTraveler ? this.renderTarget?.texture : undefined,
+      node.isTraveler ? this.renderTarget?.texture : this.textureManager.get(node.element),
     );
   }
 
@@ -327,13 +444,11 @@ export class Renderer {
   }
 
   private captureRenderTarget() {
-    const travelers: THREE.Mesh[] = [];
-    for (const mesh of this.meshMap.values()) {
-      if ((mesh.layers.mask & (1 << 28)) !== 0) {
-        travelers.push(mesh);
-      }
-    }
-    if (travelers.length === 0) return;
+    // [Problem] this method called on requestAnimationFrame
+    // => this logic travers all meshes every frame, need optimization
+
+    // if (travelers.length === 0) return;
+    if (this.travelers.size === 0) return;
 
     const oldClearColor = new THREE.Color();
     const oldClearAlpha = this.renderer.getClearAlpha();
@@ -354,23 +469,34 @@ export class Renderer {
 
     const pixelRatio = this.renderer.getPixelRatio();
 
-    for (const traveler of travelers) {
+    for (const traveler of this.travelers) {
       vector.setFromMatrixPosition(traveler.matrixWorld);
       vector.project(this.camera);
 
       const centerX = ((vector.x + 1) / 2) * canvasWidth;
       const centerY = ((vector.y + 1) / 2) * canvasHeight;
 
-      const width = traveler.scale.x;
-      const height = traveler.scale.y;
+      let clipDiff = 0;
+      let clipRadito = 1;
+      if (typeof this.clipArea === "number") {
+        clipRadito = this.clipArea;
+      } else if (this.clipArea.endsWith("%")) {
+        clipRadito = parseFloat(this.clipArea) / 100;
+      } else if (this.clipArea.endsWith("px")) {
+        clipDiff = parseFloat(this.clipArea);
+      }
+
+      const width = traveler.scale.x * clipRadito + 0.5;
+      const height = traveler.scale.y * clipRadito + 0.5;
 
       const localX = centerX - width / 2;
       const localY = centerY - height / 2;
 
-      const scissorX = (localX * this.qualityFactor) / pixelRatio;
-      const scissorY = (localY * this.qualityFactor) / pixelRatio;
-      const scissorW = (width * this.qualityFactor) / pixelRatio;
-      const scissorH = (height * this.qualityFactor) / pixelRatio;
+      const scissorX = (localX * this.qualityFactor - clipDiff) / pixelRatio;
+      const scissorY = (localY * this.qualityFactor - clipDiff) / pixelRatio;
+      const scissorW = (width * this.qualityFactor + clipDiff * 2) / pixelRatio;
+      const scissorH =
+        (height * this.qualityFactor + clipDiff * 2) / pixelRatio;
 
       this.renderer.setScissor(scissorX, scissorY, scissorW, scissorH);
       this.renderer.render(this.scene, this.camera);
@@ -378,7 +504,7 @@ export class Renderer {
     this.renderer.setScissorTest(false);
     this.renderer.autoClear = true;
     this.renderer.setRenderTarget(null);
-    this.camera.layers.set(28);
+    this.camera.layers.set(0);
     this.renderer.setClearColor(oldClearColor, oldClearAlpha);
   }
 

package/src/store/MeshRegistry.ts

@@ -0,0 +1,32 @@
+import * as THREE from "three";
+
+export class MeshRegistry {
+  private store: WeakMap<HTMLElement, THREE.Mesh>;
+
+  constructor() {
+    this.store = new WeakMap();
+  }
+  public register(element: HTMLElement, mesh: THREE.Mesh): void {
+    this.store.set(element, mesh);
+  }
+
+  public get(element: HTMLElement): THREE.Mesh | undefined {
+    return this.store.get(element);
+  }
+  // public register(element: HTMLElement, meshGroup: THREE.Group): void {
+  //   this.store.set(element, meshGroup);
+  // }
+
+  // public get(element: HTMLElement): THREE.Group | undefined {
+  //   return this.store.get(element);
+  // }
+
+  public has(element: HTMLElement): boolean {
+    return this.store.has(element);
+  }
+
+  // Optional
+  public remove(element: HTMLElement): void {
+    this.store.delete(element);
+  }
+}

package/src/store/TextureLifecycleManager.ts

@@ -0,0 +1,111 @@
+import * as THREE from "three";
+
+export type TextureReadyCallback = (
+  element: HTMLElement,
+  texture: THREE.Texture | null,
+) => void;
+
+export class TextureLifecycleManager {
+  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) {
+    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);
+          }
+        }
+      },
+      { rootMargin: "300px" },
+    );
+  }
+
+  public register(element: HTMLElement, url: string) {
+    if (element.nodeType !== Node.ELEMENT_NODE) return;
+    const currentUrl = this.elementUrls.get(element);
+    if (currentUrl !== url) {
+      this.elementUrls.set(element, url);
+      // Restart observation to trigger intersecting check
+      this.observer.unobserve(element);
+      this.observer.observe(element);
+    }
+  }
+
+  public unregister(element: HTMLElement) {
+    if (element.nodeType === Node.ELEMENT_NODE) {
+      this.observer.unobserve(element);
+    }
+    this.disposeTexture(element);
+    this.elementUrls.delete(element);
+    this.loadStatus.delete(element);
+  }
+
+  private async loadTexture(element: HTMLElement) {
+    if (this.loadStatus.get(element) || this.textures.has(element)) return;
+
+    const url = this.elementUrls.get(element);
+    if (!url) return;
+
+    this.loadStatus.set(element, true);
+
+    try {
+      const response = await fetch(url);
+      const blob = await response.blob();
+      const bitmap = await createImageBitmap(blob, { imageOrientation: "flipY" });
+
+      // Check if URL changed or element was unregistered while decoding
+      if (this.elementUrls.get(element) !== url) {
+        bitmap.close();
+        return;
+      }
+
+      // Check if element is no longer intersecting (debounced unobserve might have fired)
+      // Actually we just check if it's still observed and has the URL. 
+      // A more robust check for intersection state might be needed, but for now we rely on disposeTexture.
+
+      const texture = new THREE.CanvasTexture(bitmap);
+      texture.needsUpdate = true;
+      this.textures.set(element, texture);
+      this.onUpdate(element, texture);
+    } catch (e) {
+      console.warn("[MirageEngine] Failed to load texture:", url, e);
+    } finally {
+      // Re-check url, if it changed, we should probably trigger loadTexture again,
+      // but IntersectionObserver will handle it if it's still intersecting.
+      if (this.elementUrls.has(element)) {
+        this.loadStatus.set(element, false);
+      }
+    }
+  }
+
+  private disposeTexture(element: HTMLElement) {
+    const texture = this.textures.get(element);
+    if (texture) {
+      texture.dispose();
+      this.textures.delete(element);
+      this.onUpdate(element, null);
+    }
+    // Also cancel loading state if we had one
+    this.loadStatus.set(element, false);
+  }
+
+  public get(element: HTMLElement) {
+    return this.textures.get(element);
+  }
+
+  public disposeAll() {
+    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/animate.ts

@@ -0,0 +1,26 @@
+export interface StyleData {
+    // 1. Transform
+    x?: number;
+    y?: number;
+    z?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scaleZ?: number;
+    rotateX?: number;
+    rotateY?: number;
+    rotateZ?: number;
+
+    // for future use
+    matrix?: Float32Array; 
+
+    // 2. Material / Appearance
+    opacity?: number;
+    backgroundColor?: [number, number, number]; 
+    backgroundImage?: string;
+    borderRadius?: number | [number, number, number, number]; 
+
+    // 3. Layout / Depth
+    width?: number;
+    height?: number;
+    zIndex?: number;
+}

package/src/types/common.ts

@@ -1,4 +1,4 @@
-import { TextStyles, BoxStyles } from "@mirage-engine/painter";
+import { TextStyles, BoxStyles, ShaderHooks } from "@mirage-engine/painter";
 import { Visibility } from "./flags";
 
 export type NodeType = "BOX" | "TEXT";
@@ -20,12 +20,15 @@ export interface SceneNode {
 
   textContent?: string;
   textStyles?: TextStyles;
+  textLines?: { text: string; rect: NodeRect }[];
 
   dirtyMask: number;
   // TODO: SceneNode의 sort 로직 추가(아마도)
 
   visibility: Visibility;
   isTraveler: boolean;
+  isFixed: boolean;
+  shaderHooks?: ShaderHooks;
 
   children: SceneNode[];
 }

package/src/types/config.ts

@@ -1,5 +1,8 @@
 export type Quality = "low" | "medium" | "high" | number;
 export type MirageMode = "overlay" | "duplicate";
+export type PxUnit = `${number}px`;
+export type PercentUnit = `${number}%`;
+export type travelerClipArea = PxUnit | PercentUnit | number;
 export interface FilterConfig {
   includeTree?: string[];
   excludeTree?: string[];
@@ -22,6 +25,7 @@ interface BaseConfig {
   };
   filter?: FilterConfig;
   resizeDebounce?: boolean | ResizeConfig;
+  travelerClipArea? : travelerClipArea;
 }
 
 export interface OverlayConfig extends BaseConfig {

package/src/types/index.ts

@@ -1,3 +1,4 @@
 export * from './config';
 export * from './common';
-export * from './flags';
+export * from './flags';
+export * from './animate';