@vectojs/core 0.2.2 → 0.2.3

package/dist/tree/DOMPortalEntity.d.ts

@@ -10,9 +10,10 @@ export declare class DOMPortalEntity extends Entity {
     lastHeight: string;
     lastTransform: string;
     lastZIndex: string;
+    lastOpacity: string;
     constructor(domElement: HTMLElement, width?: number, height?: number, id?: string);
     isPointInside(globalX: number, globalY: number): boolean;
-    add(child: Entity): this;
+    add(_child: Entity): this;
     render(): void;
     destroy(): void;
 }

package/dist/tree/Entity.d.ts

@@ -8,6 +8,15 @@ export interface Point {
     x: number;
     y: number;
 }
+/** Six-scalar 2D affine transform matching CanvasRenderingContext2D. */
+export interface AffineTransform {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
 /**
  * An axis-aligned bounding box in an entity's local coordinate space.
  *
@@ -114,9 +123,10 @@ export declare class VectoJSEvent<N = unknown> {
     readonly nativeEvent: N | undefined;
     /** Whether the event bubbles past its target (capture always runs). */
     readonly bubbles: boolean;
+    private readonly explicitScenePoint;
     private stopped;
     private stoppedImmediate;
-    constructor(type: VectoEvent, target: Entity, nativeEvent?: N, bubbles?: boolean);
+    constructor(type: VectoEvent, target: Entity, nativeEvent?: N, bubbles?: boolean, scenePoint?: Point);
     /** Stop the event from reaching the next node in the propagation path. */
     stopPropagation(): void;
     /** Stop propagation AND skip any remaining listeners on the current node. */
@@ -137,6 +147,19 @@ export declare class VectoJSEvent<N = unknown> {
     get clientX(): number | undefined;
     /** Native pointer Y, if this wraps a pointer/mouse event. */
     get clientY(): number | undefined;
+    private get resolvedScenePoint();
+    /** Pointer X in the Scene's logical coordinate space. */
+    get sceneX(): number | undefined;
+    /** Pointer Y in the Scene's logical coordinate space. */
+    get sceneY(): number | undefined;
+    /** Pointer X local to the entity whose listener is currently running. */
+    get localX(): number | undefined;
+    /** Pointer Y local to the entity whose listener is currently running. */
+    get localY(): number | undefined;
+    get shiftKey(): boolean;
+    get ctrlKey(): boolean;
+    get altKey(): boolean;
+    get metaKey(): boolean;
     /** Native key, if this wraps a keyboard event. */
     get key(): string | undefined;
 }
@@ -263,6 +286,7 @@ export declare abstract class Entity {
      * that need to seed a starting state (e.g. the presence helper's enter `from`).
      */
     protected setImmediate(prop: AnimatableProp, v: number): void;
+    private _settleDriver;
     private _spawnDriver;
     /** Assignment path when a declarative transition is configured for `prop`. */
     private _animateProp;
@@ -342,6 +366,23 @@ export declare abstract class Entity {
      * @returns World-space {@link Point} for this entity.
      */
     getGlobalPosition(): Point;
+    /**
+     * Return the exact accumulated Canvas `T * S * R` transform for this entity.
+     */
+    getWorldTransform(): AffineTransform;
+    /** Convert a point from this entity's local space to Scene/world space. */
+    localToWorld(localX: number, localY: number): Point;
+    /**
+     * Convert a Scene/world point into this entity's local space.
+     * Returns `null` when the accumulated transform is singular.
+     */
+    worldToLocal(worldX: number, worldY: number): Point | null;
+    /**
+     * Return the entity's local bounds transformed into a world-space AABB.
+     * Falls back to the entity's `[0, 0, width, height]` box when `getBounds()`
+     * does not provide a render-specific box.
+     */
+    getWorldBounds(): Bounds;
     /**
      * Accumulated world scale factors: this entity's own `scaleX`/`scaleY` times
      * those of every ancestor (excluding the scene root). Useful for mapping a
@@ -393,12 +434,12 @@ export declare abstract class Entity {
      * Opt into the renderer's draw-call batching fast-path for point-cloud /
      * particle entities that draw as a single filled circle at their local origin.
      *
-     * When a leaf entity returns a {@link BatchCircle} and has uniform scale, the
-     * {@link Scene} skips its per-entity `save`/`translate`/`scale`/`rotate`/
-     * `restore` and {@link render}, emitting the circle through
-     * {@link IRenderer.fillCircle} so runs of same-color siblings coalesce into a
-     * single `fill()`. Returns `null` by default (normal render path). Read each
-     * frame, so an animated color/radius is honored.
+     * When a leaf entity returns a {@link BatchCircle} and its accumulated
+     * transform is representable by the selected batch backend, the {@link Scene}
+     * skips its per-entity `save`/`translate`/`scale`/`rotate`/`restore` and
+     * {@link render}. Canvas mode or an unsupported affine transform uses the
+     * normal render path, so implementations must keep {@link render} correct.
+     * Returns `null` by default. Read each frame, so animated color/radius works.
      *
      * @returns The circle to batch, or `null` to use the normal {@link render} path.
      */

package/dist/tree/Scene.d.ts

@@ -28,7 +28,7 @@ export interface SceneOptions {
     /**
      * Backend for particle simulation and rendering:
      * - `'auto'` (default): tries WebGPU first, falls back to CPU if WebGPU is unavailable or fails.
-     * - `'webgpu'`: forces WebGPU.
+     * - `'webgpu'`: explicitly requests WebGPU; the current runtime still falls back to CPU if initialization fails.
      * - `'cpu'`: forces CPU simulation and rendering (disabling WebGPU completely).
      */
     particleBackend?: 'auto' | 'webgpu' | 'cpu';
@@ -189,6 +189,11 @@ export declare class Scene {
      * @returns The active renderer instance.
      */
     getRenderer(): IRenderer;
+    /** Convert browser viewport coordinates into this Scene's logical coordinates. */
+    clientToScene(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
     /**
      * Add a top-level entity to the scene graph.
      *
@@ -224,6 +229,7 @@ export declare class Scene {
      * Remove an overlay entity from the overlay root.
      */
     hideOverlay(overlay: Entity): void;
+    private destroyEntitySubtree;
     /**
      * Tear down the Scene, halt the loop, and clean up event listeners and DOM elements.
      */
@@ -262,6 +268,8 @@ export declare class Scene {
     private hasAnyInteractive;
     private syncA11y;
     private enforceA11yDomOrder;
+    /** Keep DOM/WebGL overlay layers aligned with the canvas's CSS box. */
+    private syncOverlayGeometry;
     getA11yTree(): A11yTreeNode[];
     private renderPortalDOM;
     private reconcilePortals;

package/package.json

@@ -1,17 +1,15 @@
 {
   "name": "@vectojs/core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public"
   },
-  "description": "A zero-DOM, Canvas 2D Entity Component System (ECS) rendering framework — 60 FPS with 100,000+ entities.",
+  "description": "A mathematical Canvas 2D scene-graph framework with layout, events, accessibility projection, and optional GPU backends.",
   "keywords": [
     "canvas",
-    "ecs",
     "fourier",
     "spline",
     "rendering",
-    "60fps",
     "typescript",
     "vectorization"
   ],