@vectojs/three 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,94 @@
+# @vectojs/three
+
+> Put a live VectoJS 2D interface into Three.js/WebXR and route 3D pointer input back to the canvas.
+
+[![npm](https://img.shields.io/npm/v/@vectojs/three?color=22d3ee)](https://www.npmjs.com/package/@vectojs/three)
+[![CI](https://github.com/vectojs/vectojs/actions/workflows/ci.yml/badge.svg)](https://github.com/vectojs/vectojs/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-6366f1.svg)](https://github.com/vectojs/vectojs/blob/main/LICENSE)
+
+`@vectojs/three` renders a VectoJS `Scene` into a canvas-backed Three.js texture. The adapter maps
+raycast UV coordinates into the Scene's logical coordinate space, forwards pointer/hover/wheel
+events, and keeps texture uploads synchronized with VectoJS rendering.
+
+[Live 3D demo](https://vectojs.xuepoo.xyz/demos/dimension/) ·
+[Reference](https://vectojs.xuepoo.xyz/reference/three/) ·
+[Main repository](https://github.com/vectojs/vectojs)
+
+## Install
+
+```bash
+bun add @vectojs/core @vectojs/ui @vectojs/three three
+```
+
+`@vectojs/core` and `three` are peer dependencies. `@vectojs/ui` is used by the example and is
+optional when you supply your own core entities.
+
+## Basic usage
+
+```ts
+import { Button, Stack, Text } from '@vectojs/ui';
+import { ThreeAdapter } from '@vectojs/three';
+import * as THREE from 'three';
+
+const scene3d = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(50, innerWidth / innerHeight, 0.1, 100);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+
+const adapter = new ThreeAdapter({
+  width: 800,
+  height: 500,
+});
+
+const panel = new Stack({ direction: 'vertical', gap: 16 });
+panel.setPosition(36, 36);
+panel.add(new Text('VectoJS in 3D', { font: '700 28px Inter' }));
+panel.add(new Button('Select', { onClick: () => console.log('selected') }));
+adapter.vectoScene.add(panel);
+adapter.vectoScene.start();
+
+// Use the adapter's texture/material with a mesh in your Three.js scene.
+scene3d.add(adapter.mesh);
+```
+
+See the [reference](https://vectojs.xuepoo.xyz/reference/three/) for the exact constructor and
+mesh/material customization supported by the installed version.
+
+## Coordinate and event model
+
+- VectoJS layout uses the logical `width`/`height` passed to the adapter.
+- The backing canvas may be larger on HiDPI displays; raycast UVs are still mapped to logical space.
+- Pointer intersections are translated into VectoJS events and routed through its normal hit-test,
+  capture, target, and bubble phases.
+- Hover state is tracked per pointer, including pointer leave boundaries.
+- WebXR controllers can use the same raycast-to-2D route when supplied by the host application.
+
+The adapter does not own the application's Three.js render loop, camera, controls, or raycaster.
+
+## Texture synchronization
+
+The adapter wraps the VectoJS Scene render path so `texture.needsUpdate` is set after a dirty frame.
+On-demand VectoJS scenes therefore upload only when their visual state changes; the Three.js host
+still decides when to render its own frame.
+
+## Lifecycle
+
+```ts
+adapter.dispose();
+```
+
+`dispose()` restores the Scene render hook, releases adapter-owned Three.js resources, destroys the
+inner VectoJS Scene, and detaches event state. Call it when removing the panel or unmounting the host
+component.
+
+## Constraints
+
+- The default output is a flat textured plane; it is not DOM rendered in 3D.
+- Canvas clipping and logical hit-testing remain 2D even when the mesh is rotated in world space.
+- The host must provide correct raycast intersections and account for occlusion.
+- Texture resolution affects sharpness and upload cost. Choose logical size and DPR for the target
+  viewing distance rather than always maximizing both.
+- Three.js releases outside the declared peer range are not guaranteed.
+
+## License
+
+[MIT](https://github.com/vectojs/vectojs/blob/main/LICENSE) © 2026 Xuepoo

package/dist/ThreeRenderer.d.ts

@@ -51,13 +51,45 @@ export declare class ThreeRenderer implements IRenderer {
     closePath(): void;
     arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
     roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
+    /**
+     * Textures cached per drawImage source (identity-keyed). A frame that
+     * redraws the same image no longer re-uploads it. Mutable sources (a canvas
+     * you repaint) must call {@link invalidateImage} after changing pixels.
+     * Entries are skipped by the per-frame disposer and released on
+     * invalidation or {@link dispose}.
+     */
+    private imageTextureCache;
+    /** Drop the cached texture for a source whose pixels changed. */
+    invalidateImage(source: CanvasImageSource): void;
     drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
     fill(colorOrGradient: string | any): void;
     private fillSolidShape;
     stroke(colorOrGradient: string | any, lineWidth?: number): void;
+    /**
+     * Rasterized fillText textures keyed by `font|color|text`, LRU-evicted.
+     * HUD-style UIs redraw the same labels every frame; without the cache each
+     * call allocated a canvas, rasterized it, and uploaded a fresh GPU texture.
+     * Entries are skipped by {@link disposeActiveObjects} (flagged via
+     * `userData.vectoCached`) and released on eviction or {@link dispose}.
+     */
+    private textTextureCache;
+    private textTextureCacheLimit;
     fillText(text: string, x: number, y: number, font: string, color: string | any): void;
     fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
+    private frameDirty;
+    private presentScheduled;
+    /**
+     * The Scene calls flush() around every non-batched node (it commits the
+     * Canvas2D circle batch there). Rendering the whole Three scene on each of
+     * those calls made a frame cost O(N²) in entity count, so flush() only marks
+     * the frame dirty; the actual GL render happens once, in {@link present}.
+     *
+     * A microtask fallback keeps older `@vectojs/core` Scenes (that never call
+     * `present()`) painting: the many same-tick flushes coalesce into one render.
+     */
     flush(): void;
+    /** Render the accumulated frame once. Called by Scene at the end of each render pass. */
+    present(): void;
     createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
         stop: number;
         color: string;

package/dist/index.js

@@ -161,7 +161,7 @@ var ThreeRenderer = class {
       const materials = Array.isArray(object.material) ? object.material : [object.material];
       for (const material of materials) {
         const map = material.map;
-        if (map && !disposedTextures.has(map)) {
+        if (map && !map.userData.vectoCached && !disposedTextures.has(map)) {
           disposedTextures.add(map);
           map.dispose();
         }
@@ -218,7 +218,7 @@ var ThreeRenderer = class {
     const minY = Math.min(...corners.map((point) => point.y));
     const maxX = Math.max(...corners.map((point) => point.x));
     const maxY = Math.max(...corners.map((point) => point.y));
-    const dpr = window.devicePixelRatio || 1;
+    const dpr = this.renderer.getPixelRatio() || 1;
     const canvasHeight = this.renderer.domElement.height / dpr;
     let scissorX = minX * dpr;
     let scissorY = (canvasHeight - maxY) * dpr;
@@ -310,15 +310,35 @@ var ThreeRenderer = class {
     this.currentPath.lineTo(x, y + r_tl);
     this.currentPath.arc(x + r_tl, y + r_tl, r_tl, Math.PI, -Math.PI / 2, false);
   }
+  /**
+   * Textures cached per drawImage source (identity-keyed). A frame that
+   * redraws the same image no longer re-uploads it. Mutable sources (a canvas
+   * you repaint) must call {@link invalidateImage} after changing pixels.
+   * Entries are skipped by the per-frame disposer and released on
+   * invalidation or {@link dispose}.
+   */
+  imageTextureCache = /* @__PURE__ */ new Map();
+  /** Drop the cached texture for a source whose pixels changed. */
+  invalidateImage(source) {
+    const cached = this.imageTextureCache.get(source);
+    if (cached) {
+      cached.dispose();
+      this.imageTextureCache.delete(source);
+    }
+  }
   drawImage(source, dx, dy, dw, dh) {
-    let texture;
-    if (source instanceof HTMLImageElement || source instanceof HTMLCanvasElement || typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) {
-      texture = new THREE.CanvasTexture(source);
-    } else {
-      texture = new THREE.Texture(source);
-      texture.needsUpdate = true;
+    let texture = this.imageTextureCache.get(source);
+    if (!texture) {
+      if (source instanceof HTMLImageElement || source instanceof HTMLCanvasElement || typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) {
+        texture = new THREE.CanvasTexture(source);
+      } else {
+        texture = new THREE.Texture(source);
+        texture.needsUpdate = true;
+      }
+      texture.minFilter = THREE.LinearFilter;
+      texture.userData.vectoCached = true;
+      this.imageTextureCache.set(source, texture);
     }
-    texture.minFilter = THREE.LinearFilter;
     const material = new THREE.MeshBasicMaterial({
       map: texture,
       transparent: true,
@@ -481,33 +501,35 @@ var ThreeRenderer = class {
         color = grad.colorStops[0].color;
       }
     }
-    const points = this.currentPath.getPoints();
-    if (points.length === 0) return;
-    const geometry = new THREE.BufferGeometry().setFromPoints(points);
     const parsed = parseThreeColor(color);
     const opacity = this.globalAlpha * parsed.alpha;
-    const material = new THREE.LineBasicMaterial({
-      color: parsed.color,
-      transparent: opacity < 1,
-      opacity,
-      linewidth: lineWidth
-    });
-    const line = new THREE.Line(geometry, material);
-    line.applyMatrix4(this.matrix);
-    this.scene.add(line);
-    this.activeObjects.push(line);
+    for (const shape of this.currentPath.toShapes()) {
+      const points = shape.getPoints();
+      if (points.length < 2) continue;
+      const geometry = new THREE.BufferGeometry().setFromPoints(points);
+      const material = new THREE.LineBasicMaterial({
+        color: parsed.color,
+        transparent: opacity < 1,
+        opacity,
+        linewidth: lineWidth
+      });
+      const line = new THREE.Line(geometry, material);
+      line.applyMatrix4(this.matrix);
+      this.scene.add(line);
+      this.activeObjects.push(line);
+    }
   }
+  /**
+   * Rasterized fillText textures keyed by `font|color|text`, LRU-evicted.
+   * HUD-style UIs redraw the same labels every frame; without the cache each
+   * call allocated a canvas, rasterized it, and uploaded a fresh GPU texture.
+   * Entries are skipped by {@link disposeActiveObjects} (flagged via
+   * `userData.vectoCached`) and released on eviction or {@link dispose}.
+   */
+  textTextureCache = /* @__PURE__ */ new Map();
+  textTextureCacheLimit = 256;
   fillText(text, x, y, font, color) {
     if (typeof document === "undefined") return;
-    const canvas = document.createElement("canvas");
-    const ctx = canvas.getContext("2d");
-    ctx.font = font;
-    const width = Math.max(1, Math.ceil(ctx.measureText(text).width));
-    const fontSize = parseInt(font) || 16;
-    const height = Math.max(1, Math.ceil(fontSize * 1.5));
-    canvas.width = width;
-    canvas.height = height;
-    ctx.font = font;
     let fillCol = "#ffffff";
     if (typeof color === "string") {
       fillCol = color;
@@ -517,11 +539,36 @@ var ThreeRenderer = class {
         fillCol = grad.colorStops[0].color;
       }
     }
-    ctx.fillStyle = fillCol;
-    ctx.textBaseline = "alphabetic";
-    ctx.fillText(text, 0, fontSize);
-    const texture = new THREE.CanvasTexture(canvas);
-    texture.minFilter = THREE.LinearFilter;
+    const cacheKey = `${font}|${fillCol}|${text}`;
+    let entry = this.textTextureCache.get(cacheKey);
+    if (entry) {
+      this.textTextureCache.delete(cacheKey);
+      this.textTextureCache.set(cacheKey, entry);
+    } else {
+      const canvas = document.createElement("canvas");
+      const ctx = canvas.getContext("2d");
+      ctx.font = font;
+      const width2 = Math.max(1, Math.ceil(ctx.measureText(text).width));
+      const fontSize2 = parseInt(font) || 16;
+      const height2 = Math.max(1, Math.ceil(fontSize2 * 1.5));
+      canvas.width = width2;
+      canvas.height = height2;
+      ctx.font = font;
+      ctx.fillStyle = fillCol;
+      ctx.textBaseline = "alphabetic";
+      ctx.fillText(text, 0, fontSize2);
+      const texture2 = new THREE.CanvasTexture(canvas);
+      texture2.minFilter = THREE.LinearFilter;
+      texture2.userData.vectoCached = true;
+      entry = { texture: texture2, width: width2, height: height2, fontSize: fontSize2 };
+      this.textTextureCache.set(cacheKey, entry);
+      while (this.textTextureCache.size > Math.max(1, this.textTextureCacheLimit)) {
+        const oldestKey = this.textTextureCache.keys().next().value;
+        this.textTextureCache.get(oldestKey).texture.dispose();
+        this.textTextureCache.delete(oldestKey);
+      }
+    }
+    const { texture, width, height, fontSize } = entry;
     const material = new THREE.MeshBasicMaterial({
       map: texture,
       transparent: true,
@@ -551,7 +598,30 @@ var ThreeRenderer = class {
     this.scene.add(mesh);
     this.activeObjects.push(mesh);
   }
+  frameDirty = false;
+  presentScheduled = false;
+  /**
+   * The Scene calls flush() around every non-batched node (it commits the
+   * Canvas2D circle batch there). Rendering the whole Three scene on each of
+   * those calls made a frame cost O(N²) in entity count, so flush() only marks
+   * the frame dirty; the actual GL render happens once, in {@link present}.
+   *
+   * A microtask fallback keeps older `@vectojs/core` Scenes (that never call
+   * `present()`) painting: the many same-tick flushes coalesce into one render.
+   */
   flush() {
+    this.frameDirty = true;
+    if (this.presentScheduled) return;
+    this.presentScheduled = true;
+    queueMicrotask(() => {
+      this.presentScheduled = false;
+      if (this.frameDirty && !this.disposed) this.present();
+    });
+  }
+  /** Render the accumulated frame once. Called by Scene at the end of each render pass. */
+  present() {
+    if (this.disposed) return;
+    this.frameDirty = false;
     this.renderer.render(this.scene, this.camera);
   }
   createLinearGradient(x0, y0, x1, y1, colorStops) {
@@ -562,6 +632,14 @@ var ThreeRenderer = class {
     if (this.disposed) return;
     this.disposed = true;
     this.disposeActiveObjects();
+    for (const entry of this.textTextureCache.values()) {
+      entry.texture.dispose();
+    }
+    this.textTextureCache.clear();
+    for (const texture of this.imageTextureCache.values()) {
+      texture.dispose();
+    }
+    this.imageTextureCache.clear();
     this.currentPath = null;
     this.stack.length = 0;
     this.alphaStack.length = 0;

package/dist/index.mjs

@@ -123,7 +123,7 @@ var ThreeRenderer = class {
       const materials = Array.isArray(object.material) ? object.material : [object.material];
       for (const material of materials) {
         const map = material.map;
-        if (map && !disposedTextures.has(map)) {
+        if (map && !map.userData.vectoCached && !disposedTextures.has(map)) {
           disposedTextures.add(map);
           map.dispose();
         }
@@ -180,7 +180,7 @@ var ThreeRenderer = class {
     const minY = Math.min(...corners.map((point) => point.y));
     const maxX = Math.max(...corners.map((point) => point.x));
     const maxY = Math.max(...corners.map((point) => point.y));
-    const dpr = window.devicePixelRatio || 1;
+    const dpr = this.renderer.getPixelRatio() || 1;
     const canvasHeight = this.renderer.domElement.height / dpr;
     let scissorX = minX * dpr;
     let scissorY = (canvasHeight - maxY) * dpr;
@@ -272,15 +272,35 @@ var ThreeRenderer = class {
     this.currentPath.lineTo(x, y + r_tl);
     this.currentPath.arc(x + r_tl, y + r_tl, r_tl, Math.PI, -Math.PI / 2, false);
   }
+  /**
+   * Textures cached per drawImage source (identity-keyed). A frame that
+   * redraws the same image no longer re-uploads it. Mutable sources (a canvas
+   * you repaint) must call {@link invalidateImage} after changing pixels.
+   * Entries are skipped by the per-frame disposer and released on
+   * invalidation or {@link dispose}.
+   */
+  imageTextureCache = /* @__PURE__ */ new Map();
+  /** Drop the cached texture for a source whose pixels changed. */
+  invalidateImage(source) {
+    const cached = this.imageTextureCache.get(source);
+    if (cached) {
+      cached.dispose();
+      this.imageTextureCache.delete(source);
+    }
+  }
   drawImage(source, dx, dy, dw, dh) {
-    let texture;
-    if (source instanceof HTMLImageElement || source instanceof HTMLCanvasElement || typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) {
-      texture = new THREE.CanvasTexture(source);
-    } else {
-      texture = new THREE.Texture(source);
-      texture.needsUpdate = true;
+    let texture = this.imageTextureCache.get(source);
+    if (!texture) {
+      if (source instanceof HTMLImageElement || source instanceof HTMLCanvasElement || typeof ImageBitmap !== "undefined" && source instanceof ImageBitmap) {
+        texture = new THREE.CanvasTexture(source);
+      } else {
+        texture = new THREE.Texture(source);
+        texture.needsUpdate = true;
+      }
+      texture.minFilter = THREE.LinearFilter;
+      texture.userData.vectoCached = true;
+      this.imageTextureCache.set(source, texture);
     }
-    texture.minFilter = THREE.LinearFilter;
     const material = new THREE.MeshBasicMaterial({
       map: texture,
       transparent: true,
@@ -443,33 +463,35 @@ var ThreeRenderer = class {
         color = grad.colorStops[0].color;
       }
     }
-    const points = this.currentPath.getPoints();
-    if (points.length === 0) return;
-    const geometry = new THREE.BufferGeometry().setFromPoints(points);
     const parsed = parseThreeColor(color);
     const opacity = this.globalAlpha * parsed.alpha;
-    const material = new THREE.LineBasicMaterial({
-      color: parsed.color,
-      transparent: opacity < 1,
-      opacity,
-      linewidth: lineWidth
-    });
-    const line = new THREE.Line(geometry, material);
-    line.applyMatrix4(this.matrix);
-    this.scene.add(line);
-    this.activeObjects.push(line);
+    for (const shape of this.currentPath.toShapes()) {
+      const points = shape.getPoints();
+      if (points.length < 2) continue;
+      const geometry = new THREE.BufferGeometry().setFromPoints(points);
+      const material = new THREE.LineBasicMaterial({
+        color: parsed.color,
+        transparent: opacity < 1,
+        opacity,
+        linewidth: lineWidth
+      });
+      const line = new THREE.Line(geometry, material);
+      line.applyMatrix4(this.matrix);
+      this.scene.add(line);
+      this.activeObjects.push(line);
+    }
   }
+  /**
+   * Rasterized fillText textures keyed by `font|color|text`, LRU-evicted.
+   * HUD-style UIs redraw the same labels every frame; without the cache each
+   * call allocated a canvas, rasterized it, and uploaded a fresh GPU texture.
+   * Entries are skipped by {@link disposeActiveObjects} (flagged via
+   * `userData.vectoCached`) and released on eviction or {@link dispose}.
+   */
+  textTextureCache = /* @__PURE__ */ new Map();
+  textTextureCacheLimit = 256;
   fillText(text, x, y, font, color) {
     if (typeof document === "undefined") return;
-    const canvas = document.createElement("canvas");
-    const ctx = canvas.getContext("2d");
-    ctx.font = font;
-    const width = Math.max(1, Math.ceil(ctx.measureText(text).width));
-    const fontSize = parseInt(font) || 16;
-    const height = Math.max(1, Math.ceil(fontSize * 1.5));
-    canvas.width = width;
-    canvas.height = height;
-    ctx.font = font;
     let fillCol = "#ffffff";
     if (typeof color === "string") {
       fillCol = color;
@@ -479,11 +501,36 @@ var ThreeRenderer = class {
         fillCol = grad.colorStops[0].color;
       }
     }
-    ctx.fillStyle = fillCol;
-    ctx.textBaseline = "alphabetic";
-    ctx.fillText(text, 0, fontSize);
-    const texture = new THREE.CanvasTexture(canvas);
-    texture.minFilter = THREE.LinearFilter;
+    const cacheKey = `${font}|${fillCol}|${text}`;
+    let entry = this.textTextureCache.get(cacheKey);
+    if (entry) {
+      this.textTextureCache.delete(cacheKey);
+      this.textTextureCache.set(cacheKey, entry);
+    } else {
+      const canvas = document.createElement("canvas");
+      const ctx = canvas.getContext("2d");
+      ctx.font = font;
+      const width2 = Math.max(1, Math.ceil(ctx.measureText(text).width));
+      const fontSize2 = parseInt(font) || 16;
+      const height2 = Math.max(1, Math.ceil(fontSize2 * 1.5));
+      canvas.width = width2;
+      canvas.height = height2;
+      ctx.font = font;
+      ctx.fillStyle = fillCol;
+      ctx.textBaseline = "alphabetic";
+      ctx.fillText(text, 0, fontSize2);
+      const texture2 = new THREE.CanvasTexture(canvas);
+      texture2.minFilter = THREE.LinearFilter;
+      texture2.userData.vectoCached = true;
+      entry = { texture: texture2, width: width2, height: height2, fontSize: fontSize2 };
+      this.textTextureCache.set(cacheKey, entry);
+      while (this.textTextureCache.size > Math.max(1, this.textTextureCacheLimit)) {
+        const oldestKey = this.textTextureCache.keys().next().value;
+        this.textTextureCache.get(oldestKey).texture.dispose();
+        this.textTextureCache.delete(oldestKey);
+      }
+    }
+    const { texture, width, height, fontSize } = entry;
     const material = new THREE.MeshBasicMaterial({
       map: texture,
       transparent: true,
@@ -513,7 +560,30 @@ var ThreeRenderer = class {
     this.scene.add(mesh);
     this.activeObjects.push(mesh);
   }
+  frameDirty = false;
+  presentScheduled = false;
+  /**
+   * The Scene calls flush() around every non-batched node (it commits the
+   * Canvas2D circle batch there). Rendering the whole Three scene on each of
+   * those calls made a frame cost O(N²) in entity count, so flush() only marks
+   * the frame dirty; the actual GL render happens once, in {@link present}.
+   *
+   * A microtask fallback keeps older `@vectojs/core` Scenes (that never call
+   * `present()`) painting: the many same-tick flushes coalesce into one render.
+   */
   flush() {
+    this.frameDirty = true;
+    if (this.presentScheduled) return;
+    this.presentScheduled = true;
+    queueMicrotask(() => {
+      this.presentScheduled = false;
+      if (this.frameDirty && !this.disposed) this.present();
+    });
+  }
+  /** Render the accumulated frame once. Called by Scene at the end of each render pass. */
+  present() {
+    if (this.disposed) return;
+    this.frameDirty = false;
     this.renderer.render(this.scene, this.camera);
   }
   createLinearGradient(x0, y0, x1, y1, colorStops) {
@@ -524,6 +594,14 @@ var ThreeRenderer = class {
     if (this.disposed) return;
     this.disposed = true;
     this.disposeActiveObjects();
+    for (const entry of this.textTextureCache.values()) {
+      entry.texture.dispose();
+    }
+    this.textTextureCache.clear();
+    for (const texture of this.imageTextureCache.values()) {
+      texture.dispose();
+    }
+    this.imageTextureCache.clear();
     this.currentPath = null;
     this.stack.length = 0;
     this.alphaStack.length = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/three",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "publishConfig": {
     "access": "public"
   },