@vectojs/three 0.1.2 → 0.1.4

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/ThreeAdapter.d.ts

@@ -0,0 +1,67 @@
+import * as THREE from 'three';
+import { Scene as VectoScene, SceneOptions } from '@vectojs/core';
+export interface ThreeAdapterOptions {
+    /** Physical layout width of the 2D UI canvas. */
+    width: number;
+    /** Physical layout height of the 2D UI canvas. */
+    height: number;
+    /** Optional pre-existing canvas element. If omitted, a new canvas is created. */
+    canvas?: HTMLCanvasElement;
+    /** Options passed to the VectoScene constructor. */
+    sceneOptions?: SceneOptions;
+}
+/**
+ * Adapts a VectoJS Scene into a Three.js CanvasTexture, allowing VectoJS
+ * components to be rendered in 3D space (e.g. on a plane, screen, or VR dashboard).
+ */
+export declare class ThreeAdapter {
+    /** The Three.js CanvasTexture wrapping the offscreen Vecto canvas. */
+    texture: THREE.CanvasTexture;
+    /** The active VectoJS Scene instance. */
+    vectoScene: VectoScene;
+    /** The offscreen HTMLCanvasElement on which Vecto draws. */
+    canvas: HTMLCanvasElement;
+    /** A pre-built THREE.Mesh with PlaneGeometry and this texture for immediate use. */
+    mesh: THREE.Mesh;
+    /** Track hover states independently per pointerId for WebXR / Multi-Touch. */
+    private activePointers;
+    /**
+     * Holds the original `vectoScene.render` reference so {@link dispose} can
+     * restore it. Without restoring, a later render call would write
+     * `needsUpdate` on a disposed (deleted) `CanvasTexture`, which Three.js
+     * flags with `"THREE.Texture: trying to use deleted texture"`.
+     */
+    private _originalRender;
+    /** Tracks whether this adapter owns the canvas it is rendering to. */
+    private _ownsCanvas;
+    private _disposed;
+    constructor(options: ThreeAdapterOptions);
+    /**
+     * Processes 3D Raycasting intersections and forwards pointer/scroll events.
+     * Call this from window/document event listeners passing the raycaster.
+     *
+     * @param raycaster Three.js Raycaster instance.
+     * @param type Pointer event type: 'pointerdown' | 'pointerup' | 'pointermove' | 'wheel' | 'click'.
+     * @param originalEvent Optional original DOM Event to forward scroll deltas or button states.
+     * @returns true if the ray intersected the VectoJS mesh; false otherwise.
+     */
+    updateIntersection(raycaster: THREE.Raycaster, type: 'pointerdown' | 'pointerup' | 'pointermove' | 'wheel' | 'click', originalEvent?: Event): boolean;
+    /**
+     * Dispatches pointer events mapped from UV coordinates [0, 1] to VectoJS entities.
+     */
+    private dispatchAtUv;
+    /**
+     * Routes events to the associated A11y DOM element, or Vecto's own event dispatch system.
+     */
+    private dispatchEventToTarget;
+    private createDOMEvent;
+    private findEntityById;
+    /**
+     * Resizes the offscreen canvas and VectoScene dimensions.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Disposes of Three.js textures, geometries, and VectoJS scenes to prevent memory leaks.
+     */
+    dispose(): void;
+}

package/dist/ThreeRenderer.d.ts

@@ -0,0 +1,89 @@
+import { IRenderer } from '@vectojs/core';
+import * as THREE from 'three';
+export declare class WebGLGradient {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    colorStops: {
+        stop: number;
+        color: string;
+    }[];
+    type: string;
+    constructor(x0: number, y0: number, x1: number, y1: number, colorStops: {
+        stop: number;
+        color: string;
+    }[]);
+}
+/**
+ * WebGL/Three.js implementation of {@link IRenderer}.
+ *
+ * Bridges VectoJS's 2D canvas API to Three.js for 3D hardware-accelerated rendering.
+ */
+export declare class ThreeRenderer implements IRenderer {
+    scene: THREE.Scene;
+    camera: THREE.OrthographicCamera;
+    renderer: THREE.WebGLRenderer;
+    private width;
+    private height;
+    private matrix;
+    private stack;
+    private globalAlpha;
+    private alphaStack;
+    private currentPath;
+    private activeObjects;
+    private scissorStack;
+    constructor(canvas: HTMLCanvasElement);
+    resize(width: number, height: number): void;
+    clear(): void;
+    private disposeActiveObjects;
+    save(): void;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(x: number, y: number): void;
+    rotate(angle: number): void;
+    setGlobalAlpha(alpha: number): void;
+    clip(x: number, y: number, width: number, height: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    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;
+    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;
+    }[]): any;
+    private disposed;
+    dispose(): void;
+}

package/dist/index.d.ts

@@ -1,123 +1,2 @@
-import { IRenderer, Scene, SceneOptions } from '@vectojs/core';
-import * as THREE from 'three';
-
-declare class WebGLGradient {
-    x0: number;
-    y0: number;
-    x1: number;
-    y1: number;
-    colorStops: {
-        stop: number;
-        color: string;
-    }[];
-    type: string;
-    constructor(x0: number, y0: number, x1: number, y1: number, colorStops: {
-        stop: number;
-        color: string;
-    }[]);
-}
-/**
- * WebGL/Three.js implementation of {@link IRenderer}.
- *
- * Bridges VectoJS's 2D canvas API to Three.js for 3D hardware-accelerated rendering.
- */
-declare class ThreeRenderer implements IRenderer {
-    scene: THREE.Scene;
-    camera: THREE.OrthographicCamera;
-    renderer: THREE.WebGLRenderer;
-    private width;
-    private height;
-    private matrix;
-    private stack;
-    private globalAlpha;
-    private alphaStack;
-    private currentPath;
-    private activeObjects;
-    private scissorStack;
-    constructor(canvas: HTMLCanvasElement);
-    resize(width: number, height: number): void;
-    clear(): void;
-    save(): void;
-    restore(): void;
-    translate(x: number, y: number): void;
-    scale(x: number, y: number): void;
-    rotate(angle: number): void;
-    setGlobalAlpha(alpha: number): void;
-    clip(x: number, y: number, width: number, height: number): void;
-    beginPath(): void;
-    moveTo(x: number, y: number): void;
-    lineTo(x: number, y: number): void;
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-    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;
-    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;
-    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;
-    flush(): void;
-    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
-        stop: number;
-        color: string;
-    }[]): any;
-}
-
-interface ThreeAdapterOptions {
-    /** Physical layout width of the 2D UI canvas. */
-    width: number;
-    /** Physical layout height of the 2D UI canvas. */
-    height: number;
-    /** Optional pre-existing canvas element. If omitted, a new canvas is created. */
-    canvas?: HTMLCanvasElement;
-    /** Options passed to the VectoScene constructor. */
-    sceneOptions?: SceneOptions;
-}
-/**
- * Adapts a VectoJS Scene into a Three.js CanvasTexture, allowing VectoJS
- * components to be rendered in 3D space (e.g. on a plane, screen, or VR dashboard).
- */
-declare class ThreeAdapter {
-    /** The Three.js CanvasTexture wrapping the offscreen Vecto canvas. */
-    texture: THREE.CanvasTexture;
-    /** The active VectoJS Scene instance. */
-    vectoScene: Scene;
-    /** The offscreen HTMLCanvasElement on which Vecto draws. */
-    canvas: HTMLCanvasElement;
-    /** A pre-built THREE.Mesh with PlaneGeometry and this texture for immediate use. */
-    mesh: THREE.Mesh;
-    /** Track hover states independently per pointerId for WebXR / Multi-Touch. */
-    private activePointers;
-    constructor(options: ThreeAdapterOptions);
-    /**
-     * Processes 3D Raycasting intersections and forwards pointer/scroll events.
-     * Call this from window/document event listeners passing the raycaster.
-     *
-     * @param raycaster Three.js Raycaster instance.
-     * @param type Pointer event type: 'pointerdown' | 'pointerup' | 'pointermove' | 'wheel' | 'click'.
-     * @param originalEvent Optional original DOM Event to forward scroll deltas or button states.
-     * @returns true if the ray intersected the VectoJS mesh; false otherwise.
-     */
-    updateIntersection(raycaster: THREE.Raycaster, type: 'pointerdown' | 'pointerup' | 'pointermove' | 'wheel' | 'click', originalEvent?: Event): boolean;
-    /**
-     * Dispatches pointer events mapped from UV coordinates [0, 1] to VectoJS entities.
-     */
-    private dispatchAtUv;
-    /**
-     * Routes events to the associated A11y DOM element, or Vecto's own event dispatch system.
-     */
-    private dispatchEventToTarget;
-    private createDOMEvent;
-    private findEntityById;
-    /**
-     * Resizes the offscreen canvas and VectoScene dimensions.
-     */
-    resize(width: number, height: number): void;
-    /**
-     * Disposes of Three.js textures, geometries, and VectoJS scenes to prevent memory leaks.
-     */
-    dispose(): void;
-}
-
-export { ThreeAdapter, type ThreeAdapterOptions, ThreeRenderer, WebGLGradient };
+export * from './ThreeRenderer';
+export * from './ThreeAdapter';