@vectojs/core 1.15.0 → 1.16.1

package/dist/{chunk-64UFEHOJ.mjs → chunk-AQTO7OSU.mjs}

@@ -146,8 +146,42 @@ var Entity = class {
   // Danmaku hot loop), so a bare `entity.x = v` is one boolean check + field write.
   _hasTransitions = false;
   _transitions = null;
-  _drivers = /* @__PURE__ */ new Map();
+  // Lazily allocated: null until first use. A scene of many passive entities
+  // (particles, data points) never touches these, so paying an empty-Map/array
+  // allocation per entity in the constructor is pure waste at scale.
+  _drivers = null;
   _mounted = false;
+  _destroyed = false;
+  // Frame this entity's active drivers were last advanced by Scene's batched
+  // WASM animation pass (see Scene._tickBatchedDrivers), or -1 if never. When
+  // it equals the current frame, tickDrivers() must skip its own tick loop —
+  // otherwise a driver already advanced by the batch pass would be ticked a
+  // second time by the normal per-entity update() walk in the same frame.
+  // Irrelevant (and harmless) for entities never touched by WASM batching.
+  _driversTickedFrame = -1;
+  // Cached cos/sin, recomputed only when rotation actually changes. renderNode
+  // and getWorldTransform() both read this instead of calling Math.cos/sin per
+  // entity per frame (V8's are ~2.5x slower than other engines).
+  _trig = { cos: 1, sin: 0 };
+  _trigRotation = Number.NaN;
+  // NaN !== any rotation -> first read computes
+  // Per-frame world-matrix cache. Written by Scene during the render walk;
+  // getWorldTransform() returns it only while `_worldFrame === scene.currentFrame`
+  // and otherwise falls back to the full ancestor walk, so it can never return a
+  // stale/wrong transform — only sometimes miss the fast path.
+  _wa = 1;
+  _wb = 0;
+  _wc = 0;
+  _wd = 1;
+  _we = 0;
+  _wf = 0;
+  _worldFrame = -1;
+  // Slot in the Scene's resident WASM transform store, or -1 when this entity is
+  // not in that store (JS transform path, overlay/detached, or before the first
+  // structural rebuild). Assigned by Scene on a structural rebuild; the Scene
+  // validates it against its slot table before trusting it, so a stale value can
+  // only cost a JS-path fallback, never a wrong read.
+  _storeSlot = -1;
   get x() {
     return this._x;
   }
@@ -224,10 +258,12 @@ var Entity = class {
    * fixed viewport. Off by default (children render unclipped). Canvas2D only.
    */
   clipChildren = false;
-  listeners = /* @__PURE__ */ new Map();
+  // Lazily allocated (see _drivers above). Most entities never register a
+  // listener or an imperative animate() tween.
+  listeners = null;
   /** Capture-phase listeners (fired root→target before bubble). */
-  captureListeners = /* @__PURE__ */ new Map();
-  animations = [];
+  captureListeners = null;
+  animations = null;
   constructor(id) {
     this.id = id || `entity_${Math.random().toString(36).substring(2, 9)}`;
   }
@@ -262,6 +298,7 @@ var Entity = class {
     const s = this.scene;
     if (s) {
       s.a11yNeedsReorder = true;
+      s.markStructureChanged?.();
       s.markDirty();
       child._notifyMounted();
     }
@@ -291,6 +328,7 @@ var Entity = class {
       if (s) {
         s.detachA11y(child);
         s.a11yNeedsReorder = true;
+        s.markStructureChanged?.();
         s.markDirty();
       }
     }
@@ -339,7 +377,7 @@ var Entity = class {
    * @example entity.animate({ x: 400, opacity: 0 }, 500);
    */
   animate(targetProps, durationMs) {
-    this.animations.push({
+    (this.animations ??= []).push({
       target: targetProps,
       duration: durationMs,
       startTime: -1,
@@ -392,9 +430,9 @@ 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);
+    const existing = this._drivers?.get(prop);
     if (existing) this._settleDriver(existing);
-    this._drivers.delete(prop);
+    this._drivers?.delete(prop);
     this._applyAnimated(prop, v);
   }
   _settleDriver(driver) {
@@ -405,13 +443,13 @@ var Entity = class {
   }
   _spawnDriver(prop, to, cfg) {
     if (prop !== "opacity" && this.scene?.prefersReducedMotion) {
-      const existing2 = this._drivers.get(prop);
+      const existing2 = this._drivers?.get(prop);
       if (existing2) this._settleDriver(existing2);
-      this._drivers.delete(prop);
+      this._drivers?.delete(prop);
       this._applyAnimated(prop, to);
       return;
     }
-    const existing = this._drivers.get(prop);
+    const existing = this._drivers?.get(prop);
     if (existing) {
       this._settleDriver(existing);
       existing.retarget(to);
@@ -419,8 +457,9 @@ var Entity = class {
     }
     const from = this._currentOf(prop);
     const driver = isTweenConfig(cfg) ? new TweenDriver(from, to, cfg) : new SpringDriver(from, to, cfg === "spring" ? {} : cfg);
-    this._drivers.set(prop, driver);
+    (this._drivers ??= /* @__PURE__ */ new Map()).set(prop, driver);
     this.scene?.markDirty();
+    this.scene?._registerActiveDriverEntity(this);
   }
   /** Assignment path when a declarative transition is configured for `prop`. */
   _animateProp(prop, to) {
@@ -453,7 +492,7 @@ var Entity = class {
       entries.map(
         (e) => new Promise((resolve) => {
           this._spawnDriver(e[0], e[1], cfg);
-          const d = this._drivers.get(e[0]);
+          const d = this._drivers?.get(e[0]);
           if (!d)
             resolve();
           else d.onDone = resolve;
@@ -463,7 +502,8 @@ var Entity = class {
   }
   /** Advance active property drivers one frame. Call from update(). */
   tickDrivers(dt) {
-    if (this._drivers.size === 0) return;
+    if (!this._drivers || this._drivers.size === 0) return;
+    if (this.scene && this._driversTickedFrame === this.scene.currentFrame) return;
     for (const [prop, driver] of this._drivers) {
       driver.tick(dt);
       if (driver.isDone()) {
@@ -476,6 +516,38 @@ var Entity = class {
     }
     this.scene?.markDirty();
   }
+  /**
+   * Internal: this entity's active-driver map (read-only view), or `null` if
+   * it has none. Called only by Scene's batched WASM animation pass, never
+   * application code. Returns the Map directly (not a callback iteration) so
+   * a caller can `for...of` it with zero per-entity closure allocation — the
+   * integrated benchmark (benchmarks/anim-wasm-scene) found a fresh callback
+   * per entity per frame was a real cost, not a negligible one.
+   */
+  _driverEntries() {
+    return this._drivers;
+  }
+  /**
+   * Internal: finalize one driver that was ALREADY advanced externally this
+   * frame (e.g. by Scene's batched WASM tick via `driver.syncExternal`, or a
+   * direct `driver.tick()` call for a driver the batch can't offload) —
+   * exactly mirrors tickDrivers()'s own per-driver completion logic, so a
+   * driver behaves identically regardless of which path ticked it. Called
+   * only by Scene, never application code.
+   */
+  _applyDriverTick(prop, driver) {
+    if (driver.isDone()) {
+      this._applyAnimated(prop, driver.target);
+      this._settleDriver(driver);
+      this._drivers?.delete(prop);
+    } else {
+      this._applyAnimated(prop, driver.value);
+    }
+  }
+  /** Internal: true if this entity currently has any active property driver. */
+  _hasActiveDrivers() {
+    return !!this._drivers && this._drivers.size > 0;
+  }
   /**
    * Advance the entity's internal state for one frame.
    *
@@ -487,7 +559,7 @@ var Entity = class {
    */
   update(dt, time) {
     this.tickDrivers(dt);
-    if (this.animations.length > 0) {
+    if (this.animations && this.animations.length > 0) {
       const anim = this.animations[0];
       if (anim.startTime === -1) {
         anim.startTime = time;
@@ -528,7 +600,7 @@ var Entity = class {
    * @example entity.on('click', (e) => console.log('clicked', e));
    */
   on(event, callback, options) {
-    const map = options?.capture ? this.captureListeners : this.listeners;
+    const map = options?.capture ? this.captureListeners ??= /* @__PURE__ */ new Map() : this.listeners ??= /* @__PURE__ */ new Map();
     if (!map.has(event)) {
       map.set(event, []);
     }
@@ -544,7 +616,7 @@ var Entity = class {
    * @returns `this` for method chaining.
    */
   off(event, callback, options) {
-    const handlers = (options?.capture ? this.captureListeners : this.listeners).get(event);
+    const handlers = (options?.capture ? this.captureListeners : this.listeners)?.get(event);
     if (handlers) {
       const idx = handlers.indexOf(callback);
       if (idx !== -1) handlers.splice(idx, 1);
@@ -552,17 +624,37 @@ var Entity = class {
     return this;
   }
   /**
-   * Tear down this entity: clear all animations, event listeners, and detach
-   * from parent. Call before discarding an entity to prevent memory leaks.
+   * Tear down this entity **and its entire subtree**: recursively destroy every
+   * descendant (leaf-first), clear all animations, event listeners, and property
+   * drivers, then detach from the parent. Call before discarding an entity to
+   * prevent memory leaks.
+   *
+   * Recursing here is what frees a subtree's GPU buffers, layout workers, and DOM
+   * observers when an app does `entity.destroy()` or `scene.remove(subtree)` on a
+   * route change — without it, only the root's own state was released and every
+   * descendant (and its subclass resources) was stranded. Subclasses that own
+   * external resources override `destroy()`, free their resource, then call
+   * `super.destroy()`; because children don't depend on a parent's resource, the
+   * order (parent resource first, then descendants) is safe.
+   *
+   * Idempotent and re-entrancy safe: a second call is a no-op, and because each
+   * child is detached as it is destroyed, destroying a subtree never double-frees.
    */
   destroy() {
-    this.animations = [];
-    for (const driver of this._drivers.values()) {
-      this._settleDriver(driver);
+    if (this._destroyed) return;
+    this._destroyed = true;
+    while (this.children.length > 0) {
+      this.children.at(-1).destroy();
+    }
+    this.animations = null;
+    if (this._drivers) {
+      for (const driver of this._drivers.values()) {
+        this._settleDriver(driver);
+      }
+      this._drivers.clear();
     }
-    this._drivers.clear();
-    this.listeners.clear();
-    this.captureListeners.clear();
+    this.listeners?.clear();
+    this.captureListeners?.clear();
     if (this.parent) {
       this.parent.remove(this);
     }
@@ -577,7 +669,7 @@ var Entity = class {
    * @param payload - Arbitrary data forwarded to each listener.
    */
   emit(event, payload) {
-    const handlers = this.listeners.get(event);
+    const handlers = this.listeners?.get(event);
     if (handlers) {
       handlers.forEach((h) => h(payload));
     }
@@ -603,7 +695,7 @@ var Entity = class {
   }
   /** Run one node's listeners for the event, honoring stopImmediatePropagation. */
   fireListeners(node, map, event) {
-    const handlers = map.get(event.type);
+    const handlers = map?.get(event.type);
     if (!handlers) return;
     event.currentTarget = node;
     for (const h of handlers.slice()) {
@@ -642,10 +734,45 @@ var Entity = class {
   getGlobalPosition() {
     return this.localToWorld(0, 0);
   }
+  /**
+   * Internal: read this entity's cached world matrix into `out` — the SAME
+   * cache {@link getWorldTransform} reads — without allocating a wrapper
+   * object. Returns `false` (leaving `out` untouched) when the cache isn't
+   * valid for `frame` (typically the caller's `scene.currentFrame`), exactly
+   * mirroring {@link getWorldTransform}'s own validity check; the caller
+   * falls back to {@link getWorldTransform}'s full walk in that case. Exists
+   * so a per-entity gather that runs every entity through this (e.g. G3's
+   * `gatherHitAABBs`) pays for six scalar reads instead of one object
+   * allocation per entity per call — the exact class of per-frame garbage
+   * the G2 integrated benchmark found dominating its own gather cost.
+   */
+  _readWorldCache(frame, out) {
+    if (this._worldFrame < 0 || this._worldFrame !== frame) return false;
+    out.a = this._wa;
+    out.b = this._wb;
+    out.c = this._wc;
+    out.d = this._wd;
+    out.e = this._we;
+    out.f = this._wf;
+    return true;
+  }
   /**
    * Return the exact accumulated Canvas `T * S * R` transform for this entity.
    */
   getWorldTransform() {
+    if (this._worldFrame >= 0) {
+      const s = this.scene;
+      if (s && this._worldFrame === s.currentFrame) {
+        return {
+          a: this._wa,
+          b: this._wb,
+          c: this._wc,
+          d: this._wd,
+          e: this._we,
+          f: this._wf
+        };
+      }
+    }
     const path = [this];
     let ancestor = this.parent;
     while (ancestor) {
@@ -660,8 +787,9 @@ var Entity = class {
     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 trig = node._getTrig();
+      const cos = trig.cos;
+      const sin = trig.sin;
       const la = node.scaleX * cos;
       const lb = node.scaleY * sin;
       const lc = -node.scaleX * sin;
@@ -683,6 +811,37 @@ var Entity = class {
     }
     return { a, b, c, d, e, f };
   }
+  /**
+   * Return this entity's cached `{ cos, sin }` of its current rotation,
+   * recomputing only when `rotation` has actually changed since the last call.
+   * The same object identity is returned across calls with an unchanged
+   * rotation, so callers must treat it as read-only. Used by the render walk
+   * and {@link getWorldTransform} to avoid V8's comparatively slow Math.cos/sin
+   * (a software libm call, ~2.5x slower than other engines) per entity/frame.
+   */
+  _getTrig() {
+    if (this._trigRotation !== this._rotation) {
+      this._trig.cos = Math.cos(this._rotation);
+      this._trig.sin = Math.sin(this._rotation);
+      this._trigRotation = this._rotation;
+    }
+    return this._trig;
+  }
+  /**
+   * Store the world matrix Scene computed for this entity during the render
+   * walk, stamped with the frame it belongs to. {@link getWorldTransform}
+   * returns it verbatim while `frame === scene.currentFrame`. Internal: called
+   * only by Scene's renderer, never by application code.
+   */
+  _setWorldCache(a, b, c, d, e, f, frame) {
+    this._wa = a;
+    this._wb = b;
+    this._wc = c;
+    this._wd = d;
+    this._we = e;
+    this._wf = f;
+    this._worldFrame = frame;
+  }
   /** 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();
@@ -712,7 +871,12 @@ var Entity = class {
    * does not provide a render-specific box.
    */
   getWorldBounds() {
-    const bounds = this.getBounds() ?? { x: 0, y: 0, width: this.width, height: this.height };
+    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;
@@ -853,7 +1017,7 @@ var Entity = class {
    * @returns `true` if at least one animation or property driver remains.
    */
   hasPendingAnimations() {
-    return this.animations.length > 0 || this._drivers.size > 0;
+    return (this.animations?.length ?? 0) > 0 || (this._drivers?.size ?? 0) > 0;
   }
 };
 
@@ -869,6 +1033,14 @@ var MSDFTextEntity = class extends Entity {
   lineHeight;
   maxWidth;
   maxHeight;
+  textAlign;
+  // Optional hyphenator. Runs on the MAIN thread (a function can't be
+  // structure-cloned into the layout worker), turning each word into parts
+  // joined by soft hyphens (U+00AD); the worker then treats those as break
+  // opportunities. `text` keeps the original string for a11y/content
+  // projection; `layoutText` is the soft-hyphen-annotated string sent to layout.
+  hyphenator = null;
+  layoutText = "";
   text = "";
   lastRenderedSeqId = 0;
   rgbColorCache = /* @__PURE__ */ new Map();
@@ -885,6 +1057,7 @@ var MSDFTextEntity = class extends Entity {
     this.lineHeight = options.lineHeight;
     this.maxWidth = options.maxWidth ?? 1e3;
     this.maxHeight = options.maxHeight ?? 1e3;
+    this.textAlign = options.textAlign ?? "left";
     this.setText(text);
   }
   /** Change the wrap boundary and re-run layout for the current text. */
@@ -893,13 +1066,53 @@ var MSDFTextEntity = class extends Entity {
     this.maxWidth = maxWidth;
     this.queueLayout();
   }
+  /**
+   * Set horizontal alignment (`'justify'` stretches wrapped lines flush to
+   * {@link setMaxWidth}'s width; the last line stays ragged) and re-run layout.
+   */
+  setTextAlign(align) {
+    if (this.textAlign === align) return;
+    this.textAlign = align;
+    this.queueLayout();
+  }
+  /**
+   * Plug a hyphenator (word → parts). Break opportunities are inserted as soft
+   * hyphens (U+00AD) into the string sent to layout, so a word that doesn't fit
+   * can break with a visible hyphen. Soft hyphens already present in the text
+   * work without one. Pass `null` to disable. The original text is preserved
+   * for accessibility — only the layout string carries the hyphens.
+   */
+  setHyphenator(fn) {
+    this.hyphenator = fn;
+    this.rebuildLayoutText();
+    this.queueLayout();
+  }
   setText(text) {
     if (this.text === text && this.layoutResult) return;
     this.text = text;
+    this.rebuildLayoutText();
     this.queueLayout();
   }
+  /**
+   * Recompute {@link layoutText} from {@link text}: with a hyphenator active,
+   * split each whitespace-delimited word and rejoin its parts with U+00AD so
+   * the worker sees the break opportunities. Without one, the layout string is
+   * the text unchanged.
+   */
+  rebuildLayoutText() {
+    if (!this.hyphenator) {
+      this.layoutText = this.text;
+      return;
+    }
+    const SHY = "\xAD";
+    this.layoutText = this.text.replace(/[^\s]+/g, (word) => {
+      if (word.length <= 3 || word.includes(SHY)) return word;
+      const parts = this.hyphenator(word);
+      return parts.length > 1 ? parts.join(SHY) : word;
+    });
+  }
   queueLayout() {
-    LayoutWorkerManager.getInstance().queueLayout(this.id, this.text, {
+    LayoutWorkerManager.getInstance().queueLayout(this.id, this.layoutText, {
       fontId: this.font.id,
       fontSize: this.fontSize,
       maxWidth: this.maxWidth,
@@ -907,6 +1120,7 @@ var MSDFTextEntity = class extends Entity {
       fontData: this.font.data,
       letterSpacing: this.letterSpacing,
       lineHeight: this.lineHeight,
+      textAlign: this.textAlign,
       callback: (res) => {
         if (res.seqId < this.lastRenderedSeqId) return;
         this.lastRenderedSeqId = res.seqId;
@@ -1016,7 +1230,7 @@ var MSDFTextEntity = class extends Entity {
     }
   }
   destroy() {
-    LayoutWorkerManager.getInstance().cancelLayout(this.id);
+    LayoutWorkerManager.cancelLayoutForEntity(this.id);
     super.destroy();
   }
 };