@vectojs/core 0.2.1 → 0.2.3

package/README.md

@@ -1,7 +1,7 @@
 # @vectojs/core
 
-> The Zero-DOM, Canvas-native rendering engine behind **VectoJS** — ECS + Virtual Math Tree,
-> with an accessibility/automation shadow layer.
+> The Canvas-native rendering engine behind **VectoJS** — an entity scene graph and Virtual Math
+> Tree with an accessibility/automation projection layer.
 
 Part of the [VectoJS](https://github.com/vectojs/vectojs) ecosystem.
 
@@ -13,18 +13,17 @@ physics are pure math on a Virtual Math Tree, dispatched to a Canvas 2D (or WebG
 transparent DOM node through the **`a11yRoot`** shadow layer, so a pure-canvas page stays
 accessible and drivable by assistive tech and AI agents.
 
-Includes: `Scene` (render loop + a11y sync), `Entity` (ECS base), `LayoutEngine` (Intl.Segmenter
+Includes: `Scene` (render loop + a11y sync), `Entity` (scene-graph base), `LayoutEngine` (Intl.Segmenter
 with a cold/hot `prepare`/`layoutPrepared` split), `SpatialHashGrid`, `LayoutResultBuffer`
-(zero-GC), `SplineEntity` (native vectomancy math-curve rendering + curve-accurate hit-testing),
+(reusable typed storage), `SplineEntity` (native vectomancy math-curve rendering + curve-accurate hit-testing),
 `CanvasRenderer`, and a `WebGLPointRenderer` point/rect batch layer.
 
 ## Performance
 
-See the [main README](https://github.com/vectojs/vectojs#measured-performance) for measured,
-reproducible numbers (`bun run benchmark` / `bun run compare:dom`). Headline levers: viewport
-culling, on-demand redraw, draw-call batching, a WebGL2 point layer, and a cold/hot text layout
-split (~3.5× faster reflow). No fabricated comparisons — numbers are per-machine and
-complexity-dependent.
+See the [main README](https://github.com/vectojs/vectojs#testing--quality) for reproducible
+workloads (`bun run benchmark` / `bun run compare:dom`). Headline levers include viewport culling,
+on-demand redraw, draw-call batching, a WebGL2 point layer, and a cold/hot text layout split.
+Results are machine- and workload-dependent.
 
 ## Quick Start
 

package/dist/{chunk-RW6NC4RB.js → chunk-6I53LI3Z.js}

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } var _class; var _class2;// src/text/ArabicShaper.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2;// src/text/ArabicShaper.ts
 var ArabicShaper = (_class = class _ArabicShaper {
   static __initStatic() {this.MAPPINGS = {
     1569: { isolated: 65152, initial: 65152, medial: 65152, final: 65152, joining: "U" },
@@ -301,24 +301,57 @@ var WORKER_SOURCE_STRING = '"use strict";(()=>{var b=new Map;self.onmessage=x=>{
 // src/layout/LayoutWorkerManager.ts
 var LayoutWorkerManager = (_class2 = class _LayoutWorkerManager {
   
-  
-  __init() {this.registeredFonts = /* @__PURE__ */ new Set()}
-  __init2() {this.pendingCallbacks = /* @__PURE__ */ new Map()}
-  __init3() {this.seqIdCounter = /* @__PURE__ */ new Map()}
-  __init4() {this.debounceTimers = /* @__PURE__ */ new Map()}
-  constructor() {;_class2.prototype.__init.call(this);_class2.prototype.__init2.call(this);_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);
+  __init() {this.worker = null}
+  __init2() {this.registeredFonts = /* @__PURE__ */ new Set()}
+  __init3() {this.pendingCallbacks = /* @__PURE__ */ new Map()}
+  __init4() {this.seqIdCounter = /* @__PURE__ */ new Map()}
+  __init5() {this.debounceTimers = /* @__PURE__ */ new Map()}
+  constructor() {;_class2.prototype.__init.call(this);_class2.prototype.__init2.call(this);_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);
+    this.worker = this.createWorker();
+  }
+  createWorker() {
     const workerBlob = new Blob([WORKER_SOURCE_STRING], { type: "application/javascript" });
     const workerURL = URL.createObjectURL(workerBlob);
-    this.worker = new Worker(workerURL);
-    setTimeout(() => URL.revokeObjectURL(workerURL), 2e3);
-    this.worker.onmessage = (e) => {
+    let worker;
+    try {
+      worker = new Worker(workerURL);
+    } finally {
+      URL.revokeObjectURL(workerURL);
+    }
+    worker.onmessage = (e) => {
+      if (this.worker !== worker) return;
       const response = e.data;
-      const callback = this.pendingCallbacks.get(`${response.id}-${response.seqId}`);
+      const key = `${response.id}-${response.seqId}`;
+      const callback = this.pendingCallbacks.get(key);
       if (callback) {
+        this.pendingCallbacks.delete(key);
         callback(response);
-        this.pendingCallbacks.delete(`${response.id}-${response.seqId}`);
       }
     };
+    worker.onerror = () => this.handleWorkerFailure(worker);
+    worker.onmessageerror = () => this.handleWorkerFailure(worker);
+    return worker;
+  }
+  ensureWorker() {
+    if (!this.worker) this.worker = this.createWorker();
+    return this.worker;
+  }
+  handleWorkerFailure(worker) {
+    if (this.worker !== worker) return;
+    worker.terminate();
+    this.worker = null;
+    this.pendingCallbacks.clear();
+    this.registeredFonts.clear();
+  }
+  destroy() {
+    for (const timer of this.debounceTimers.values()) clearTimeout(timer);
+    this.debounceTimers.clear();
+    this.pendingCallbacks.clear();
+    this.seqIdCounter.clear();
+    this.registeredFonts.clear();
+    _optionalChain([this, 'access', _ => _.worker, 'optionalAccess', _2 => _2.terminate, 'call', _3 => _3()]);
+    this.worker = null;
+    if (_LayoutWorkerManager.instance === this) _LayoutWorkerManager.instance = void 0;
   }
   static getInstance() {
     if (!_LayoutWorkerManager.instance) {
@@ -332,6 +365,7 @@ var LayoutWorkerManager = (_class2 = class _LayoutWorkerManager {
       clearTimeout(existingTimer);
     }
     const runLayout = () => {
+      this.debounceTimers.delete(entityId);
       const nextSeqId = (_nullishCoalesce(this.seqIdCounter.get(entityId), () => ( 0))) + 1;
       this.seqIdCounter.set(entityId, nextSeqId);
       const request = {
@@ -350,7 +384,12 @@ var LayoutWorkerManager = (_class2 = class _LayoutWorkerManager {
         this.registeredFonts.add(options.fontId);
       }
       this.pendingCallbacks.set(`${entityId}-${nextSeqId}`, options.callback);
-      this.worker.postMessage(request);
+      try {
+        this.ensureWorker().postMessage(request);
+      } catch (e2) {
+        const worker = this.worker;
+        if (worker) this.handleWorkerFailure(worker);
+      }
     };
     if (!this.seqIdCounter.has(entityId)) {
       runLayout();
@@ -365,6 +404,9 @@ var LayoutWorkerManager = (_class2 = class _LayoutWorkerManager {
       clearTimeout(existingTimer);
       this.debounceTimers.delete(entityId);
     }
+    for (const key of this.pendingCallbacks.keys()) {
+      if (key.startsWith(`${entityId}-`)) this.pendingCallbacks.delete(key);
+    }
     this.seqIdCounter.delete(entityId);
   }
 }, _class2);

package/dist/{chunk-H3QIE77O.mjs → chunk-ISGOYXPF.mjs}

@@ -1,6 +1,6 @@
 import {
   LayoutWorkerManager
-} from "./chunk-YA2J5ZH7.mjs";
+} from "./chunk-YSS44ADQ.mjs";
 
 // src/math/SpringPhysics.ts
 var SpringPhysics = class {
@@ -128,14 +128,16 @@ var VectoJSEvent = class {
   nativeEvent;
   /** Whether the event bubbles past its target (capture always runs). */
   bubbles;
+  explicitScenePoint;
   stopped = false;
   stoppedImmediate = false;
-  constructor(type, target, nativeEvent, bubbles = true) {
+  constructor(type, target, nativeEvent, bubbles = true, scenePoint) {
     this.type = type;
     this.target = target;
     this.currentTarget = target;
     this.nativeEvent = nativeEvent;
     this.bubbles = bubbles;
+    this.explicitScenePoint = scenePoint;
   }
   /** Stop the event from reaching the next node in the propagation path. */
   stopPropagation() {
@@ -178,6 +180,51 @@ var VectoJSEvent = class {
   get clientY() {
     return this.nativeEvent?.clientY;
   }
+  get resolvedScenePoint() {
+    if (this.explicitScenePoint) return this.explicitScenePoint;
+    const native = this.nativeEvent;
+    if (native?.vectoSceneX !== void 0 && native.vectoSceneY !== void 0) {
+      return { x: native.vectoSceneX, y: native.vectoSceneY };
+    }
+    if (native?.clientX === void 0 || native.clientY === void 0) return void 0;
+    const scene = this.target.scene;
+    return scene?.clientToScene?.(native.clientX, native.clientY) ?? {
+      x: native.clientX,
+      y: native.clientY
+    };
+  }
+  /** Pointer X in the Scene's logical coordinate space. */
+  get sceneX() {
+    return this.resolvedScenePoint?.x;
+  }
+  /** Pointer Y in the Scene's logical coordinate space. */
+  get sceneY() {
+    return this.resolvedScenePoint?.y;
+  }
+  /** Pointer X local to the entity whose listener is currently running. */
+  get localX() {
+    const point = this.resolvedScenePoint;
+    if (!point) return void 0;
+    return this.currentTarget.worldToLocal(point.x, point.y)?.x;
+  }
+  /** Pointer Y local to the entity whose listener is currently running. */
+  get localY() {
+    const point = this.resolvedScenePoint;
+    if (!point) return void 0;
+    return this.currentTarget.worldToLocal(point.x, point.y)?.y;
+  }
+  get shiftKey() {
+    return !!this.nativeEvent?.shiftKey;
+  }
+  get ctrlKey() {
+    return !!this.nativeEvent?.ctrlKey;
+  }
+  get altKey() {
+    return !!this.nativeEvent?.altKey;
+  }
+  get metaKey() {
+    return !!this.nativeEvent?.metaKey;
+  }
   /** Native key, if this wraps a keyboard event. */
   get key() {
     return this.nativeEvent?.key;
@@ -412,17 +459,28 @@ var Entity = class {
    * that need to seed a starting state (e.g. the presence helper's enter `from`).
    */
   setImmediate(prop, v) {
+    const existing = this._drivers.get(prop);
+    if (existing) this._settleDriver(existing);
     this._drivers.delete(prop);
     this._applyAnimated(prop, v);
   }
+  _settleDriver(driver) {
+    const active = driver;
+    const onDone = active.onDone;
+    active.onDone = void 0;
+    onDone?.();
+  }
   _spawnDriver(prop, to, cfg) {
     if (prop !== "opacity" && this.scene?.prefersReducedMotion) {
+      const existing2 = this._drivers.get(prop);
+      if (existing2) this._settleDriver(existing2);
       this._drivers.delete(prop);
       this._applyAnimated(prop, to);
       return;
     }
     const existing = this._drivers.get(prop);
     if (existing) {
+      this._settleDriver(existing);
       existing.retarget(to);
       return;
     }
@@ -477,7 +535,7 @@ var Entity = class {
       driver.tick(dt);
       if (driver.isDone()) {
         this._applyAnimated(prop, driver.target);
-        driver.onDone?.();
+        this._settleDriver(driver);
         this._drivers.delete(prop);
       } else {
         this._applyAnimated(prop, driver.value);
@@ -621,19 +679,95 @@ var Entity = class {
    * @returns World-space {@link Point} for this entity.
    */
   getGlobalPosition() {
-    let px = this.x;
-    let py = this.y;
-    let curr = this.parent;
-    while (curr && curr.id !== "root") {
-      const cos = Math.cos(curr.rotation);
-      const sin = Math.sin(curr.rotation);
-      const rotatedX = px * cos - py * sin;
-      const rotatedY = px * sin + py * cos;
-      px = curr.x + curr.scaleX * rotatedX;
-      py = curr.y + curr.scaleY * rotatedY;
-      curr = curr.parent;
+    return this.localToWorld(0, 0);
+  }
+  /**
+   * Return the exact accumulated Canvas `T * S * R` transform for this entity.
+   */
+  getWorldTransform() {
+    const path = this.id === "root" ? [] : [this];
+    let ancestor = this.parent;
+    while (ancestor && ancestor.id !== "root") {
+      path.push(ancestor);
+      ancestor = ancestor.parent;
+    }
+    let a = 1;
+    let b = 0;
+    let c = 0;
+    let d = 1;
+    let e = 0;
+    let f = 0;
+    for (let i = path.length - 1; i >= 0; i--) {
+      const node = path[i];
+      const cos = Math.cos(node.rotation);
+      const sin = Math.sin(node.rotation);
+      const la = node.scaleX * cos;
+      const lb = node.scaleY * sin;
+      const lc = -node.scaleX * sin;
+      const ld = node.scaleY * cos;
+      const le = node.x;
+      const lf = node.y;
+      const nextA = a * la + c * lb;
+      const nextB = b * la + d * lb;
+      const nextC = a * lc + c * ld;
+      const nextD = b * lc + d * ld;
+      const nextE = a * le + c * lf + e;
+      const nextF = b * le + d * lf + f;
+      a = nextA;
+      b = nextB;
+      c = nextC;
+      d = nextD;
+      e = nextE;
+      f = nextF;
     }
-    return { x: px, y: py };
+    return { a, b, c, d, e, f };
+  }
+  /** Convert a point from this entity's local space to Scene/world space. */
+  localToWorld(localX, localY) {
+    const { a, b, c, d, e, f } = this.getWorldTransform();
+    return {
+      x: a * localX + c * localY + e,
+      y: b * localX + d * localY + f
+    };
+  }
+  /**
+   * Convert a Scene/world point into this entity's local space.
+   * Returns `null` when the accumulated transform is singular.
+   */
+  worldToLocal(worldX, worldY) {
+    const { a, b, c, d, e, f } = this.getWorldTransform();
+    const determinant = a * d - b * c;
+    if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-12) return null;
+    const x = worldX - e;
+    const y = worldY - f;
+    return {
+      x: (d * x - c * y) / determinant,
+      y: (-b * x + a * y) / determinant
+    };
+  }
+  /**
+   * 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() {
+    const bounds = this.getBounds() ?? { x: 0, y: 0, width: this.width, height: this.height };
+    const { a, b, c, d, e, f } = this.getWorldTransform();
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < 4; i++) {
+      const localX = i & 1 ? bounds.x + bounds.width : bounds.x;
+      const localY = i & 2 ? bounds.y + bounds.height : bounds.y;
+      const worldX = a * localX + c * localY + e;
+      const worldY = b * localX + d * localY + f;
+      minX = Math.min(minX, worldX);
+      minY = Math.min(minY, worldY);
+      maxX = Math.max(maxX, worldX);
+      maxY = Math.max(maxY, worldY);
+    }
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
   }
   /**
    * Accumulated world scale factors: this entity's own `scaleX`/`scaleY` times
@@ -705,12 +839,12 @@ var Entity = class {
    * 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.
    */
@@ -893,22 +1027,21 @@ var MSDFTextEntity = class extends Entity {
   }
   isPointInside(globalX, globalY) {
     if (!this.layoutResult) return false;
-    const pos = this.getGlobalPosition();
-    const scale = this.getWorldScale();
-    const lx = (globalX - pos.x) / scale.x;
-    const ly = (globalY - pos.y) / scale.y;
-    return lx >= 0 && lx <= this.layoutResult.width && ly >= 0 && ly <= this.layoutResult.height;
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.layoutResult.width && local.y >= 0 && local.y <= this.layoutResult.height;
   }
   render(renderer) {
     if (!this.layoutResult) return;
     const scene = this.scene;
-    if (scene && scene.pointRenderer && scene.glCanvas) {
+    const world = this.getWorldTransform();
+    const worldScaleX = Math.hypot(world.a, world.b);
+    const worldScaleY = Math.hypot(world.c, world.d);
+    const orthogonalTolerance = Math.max(1, worldScaleX * worldScaleY) * 1e-6;
+    const canUsePointGlyphs = Number.isFinite(worldScaleX) && Number.isFinite(worldScaleY) && world.a * world.d - world.b * world.c >= 0 && Math.abs(world.a * world.c + world.b * world.d) <= orthogonalTolerance;
+    if (scene && scene.pointRenderer && scene.glCanvas && canUsePointGlyphs) {
       scene.pointRenderer.setMSDFTexture(this.texture, this.font.distanceRange);
-      const globalPos = this.getGlobalPosition();
-      const scale = this.getWorldScale();
-      const worldRot = this.getWorldRotation();
-      const rCos = Math.cos(worldRot);
-      const rSin = Math.sin(worldRot);
+      const worldRot = Math.atan2(world.b, world.a);
       const len2 = this.layoutResult.codePoints.length;
       for (let i = 0; i < len2; i++) {
         const code = this.layoutResult.codePoints[i];
@@ -920,12 +1053,12 @@ var MSDFTextEntity = class extends Entity {
         const { atlasBounds: ab, planeBounds: pb } = def;
         const aw = this.font.atlasWidth;
         const ah = this.font.atlasHeight;
-        const lx = (nodeX + pb.left * this.fontSize) * scale.x;
-        const ly = (nodeY - pb.top * this.fontSize) * scale.y;
-        const glyphX = globalPos.x + lx * rCos - ly * rSin;
-        const glyphY = globalPos.y + lx * rSin + ly * rCos;
-        const glyphW = (pb.right - pb.left) * this.fontSize * scale.x;
-        const glyphH = (pb.top - pb.bottom) * this.fontSize * scale.y;
+        const lx = nodeX + pb.left * this.fontSize;
+        const ly = nodeY - pb.top * this.fontSize;
+        const glyphX = world.a * lx + world.c * ly + world.e;
+        const glyphY = world.b * lx + world.d * ly + world.f;
+        const glyphW = (pb.right - pb.left) * this.fontSize * worldScaleX;
+        const glyphH = (pb.top - pb.bottom) * this.fontSize * worldScaleY;
         const v0 = this.font.data.atlas.yOrigin === "bottom" ? 1 - ab.top / ah : ab.top / ah;
         const v1 = this.font.data.atlas.yOrigin === "bottom" ? 1 - ab.bottom / ah : ab.bottom / ah;
         const colorVal = packedStyle >>> 8;
@@ -1138,22 +1271,14 @@ var SVGEntity = class extends Entity {
     img.src = this.blobURL;
   }
   isPointInside(globalX, globalY) {
-    const pos = this.getGlobalPosition();
-    const scale = this.getWorldScale();
-    const rot = this.getWorldRotation();
-    const dx = globalX - pos.x;
-    const dy = globalY - pos.y;
-    const cos = Math.cos(-rot);
-    const sin = Math.sin(-rot);
-    const lx = (dx * cos - dy * sin) / scale.x;
-    const ly = (dx * sin + dy * cos) / scale.y;
-    return lx >= 0 && lx <= this.width && ly >= 0 && ly <= this.height;
+    const local = this.worldToLocal(globalX, globalY);
+    if (!local) return false;
+    return local.x >= 0 && local.x <= this.width && local.y >= 0 && local.y <= this.height;
   }
   render(r) {
-    const isSVGExporter = typeof r.toXMLString === "function";
-    if (isSVGExporter) {
-      const dataUri = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(this.svgSource);
-      r.drawImage({ src: dataUri }, 0, 0, this.width, this.height);
+    const svgRenderer = r;
+    if (typeof svgRenderer.drawSVG === "function") {
+      svgRenderer.drawSVG(this.svgSource, 0, 0, this.width, this.height);
       return;
     }
     const scale = this.getWorldScale();