@vectojs/core 1.15.0 → 1.16.0

package/dist/{chunk-J6NHSFIE.js → chunk-DUYB4GX4.js}

@@ -1,4 +1,6 @@
-"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; var _class3; var _class4;// src/tree/Entity.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; var _class3; var _class4;const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
+
+// src/tree/Entity.ts
 
 
 
@@ -146,8 +148,42 @@ var Entity = (_class2 = class {
   // Danmaku hot loop), so a bare `entity.x = v` is one boolean check + field write.
   __init11() {this._hasTransitions = false}
   __init12() {this._transitions = null}
-  __init13() {this._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.
+  __init13() {this._drivers = null}
   __init14() {this._mounted = false}
+  __init15() {this._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.
+  __init16() {this._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).
+  __init17() {this._trig = { cos: 1, sin: 0 }}
+  __init18() {this._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.
+  __init19() {this._wa = 1}
+  __init20() {this._wb = 0}
+  __init21() {this._wc = 0}
+  __init22() {this._wd = 1}
+  __init23() {this._we = 0}
+  __init24() {this._wf = 0}
+  __init25() {this._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.
+  __init26() {this._storeSlot = -1}
   get x() {
     return this._x;
   }
@@ -190,8 +226,8 @@ var Entity = (_class2 = class {
     if (this._hasTransitions) this._animateProp("opacity", v);
     else this._opacity = v;
   }
-  __init15() {this.isDOMPortal = false}
-  __init16() {this._interactive = false}
+  __init27() {this.isDOMPortal = false}
+  __init28() {this._interactive = false}
   get interactive() {
     return this._interactive;
   }
@@ -205,10 +241,10 @@ var Entity = (_class2 = class {
       }
     }
   }
-  __init17() {this.width = 0}
-  __init18() {this.height = 0}
-  __init19() {this.a11yOffsetX = 0}
-  __init20() {this.a11yOffsetY = 0}
+  __init29() {this.width = 0}
+  __init30() {this.height = 0}
+  __init31() {this.a11yOffsetX = 0}
+  __init32() {this.a11yOffsetY = 0}
   /**
    * Opt in to a viewport-filling accessibility/automation shadow node even when
    * this entity has no intrinsic box (`width`/`height` of `0`). Use for
@@ -216,19 +252,21 @@ var Entity = (_class2 = class {
    * that need global pointer events. The node is mounted behind all other shadow
    * nodes, so on-top components stay clickable.
    */
-  __init21() {this.a11yFullViewport = false}
+  __init33() {this.a11yFullViewport = false}
   /**
    * Clip this node's children to its local box (`[0,0]–[width,height]`) while
    * rendering. Combined with translating a content child, this is how
    * scroll/overflow containers (e.g. `ScrollView`) keep their content inside a
    * fixed viewport. Off by default (children render unclipped). Canvas2D only.
    */
-  __init22() {this.clipChildren = false}
-  __init23() {this.listeners = /* @__PURE__ */ new Map()}
+  __init34() {this.clipChildren = false}
+  // Lazily allocated (see _drivers above). Most entities never register a
+  // listener or an imperative animate() tween.
+  __init35() {this.listeners = null}
   /** Capture-phase listeners (fired root→target before bubble). */
-  __init24() {this.captureListeners = /* @__PURE__ */ new Map()}
-  __init25() {this.animations = []}
-  constructor(id) {;_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);_class2.prototype.__init6.call(this);_class2.prototype.__init7.call(this);_class2.prototype.__init8.call(this);_class2.prototype.__init9.call(this);_class2.prototype.__init10.call(this);_class2.prototype.__init11.call(this);_class2.prototype.__init12.call(this);_class2.prototype.__init13.call(this);_class2.prototype.__init14.call(this);_class2.prototype.__init15.call(this);_class2.prototype.__init16.call(this);_class2.prototype.__init17.call(this);_class2.prototype.__init18.call(this);_class2.prototype.__init19.call(this);_class2.prototype.__init20.call(this);_class2.prototype.__init21.call(this);_class2.prototype.__init22.call(this);_class2.prototype.__init23.call(this);_class2.prototype.__init24.call(this);_class2.prototype.__init25.call(this);
+  __init36() {this.captureListeners = null}
+  __init37() {this.animations = null}
+  constructor(id) {;_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);_class2.prototype.__init6.call(this);_class2.prototype.__init7.call(this);_class2.prototype.__init8.call(this);_class2.prototype.__init9.call(this);_class2.prototype.__init10.call(this);_class2.prototype.__init11.call(this);_class2.prototype.__init12.call(this);_class2.prototype.__init13.call(this);_class2.prototype.__init14.call(this);_class2.prototype.__init15.call(this);_class2.prototype.__init16.call(this);_class2.prototype.__init17.call(this);_class2.prototype.__init18.call(this);_class2.prototype.__init19.call(this);_class2.prototype.__init20.call(this);_class2.prototype.__init21.call(this);_class2.prototype.__init22.call(this);_class2.prototype.__init23.call(this);_class2.prototype.__init24.call(this);_class2.prototype.__init25.call(this);_class2.prototype.__init26.call(this);_class2.prototype.__init27.call(this);_class2.prototype.__init28.call(this);_class2.prototype.__init29.call(this);_class2.prototype.__init30.call(this);_class2.prototype.__init31.call(this);_class2.prototype.__init32.call(this);_class2.prototype.__init33.call(this);_class2.prototype.__init34.call(this);_class2.prototype.__init35.call(this);_class2.prototype.__init36.call(this);_class2.prototype.__init37.call(this);
     this.id = id || `entity_${Math.random().toString(36).substring(2, 9)}`;
   }
   /**
@@ -262,6 +300,7 @@ var Entity = (_class2 = class {
     const s = this.scene;
     if (s) {
       s.a11yNeedsReorder = true;
+      _optionalChain([s, 'access', _40 => _40.markStructureChanged, 'optionalCall', _41 => _41()]);
       s.markDirty();
       child._notifyMounted();
     }
@@ -291,6 +330,7 @@ var Entity = (_class2 = class {
       if (s) {
         s.detachA11y(child);
         s.a11yNeedsReorder = true;
+        _optionalChain([s, 'access', _42 => _42.markStructureChanged, 'optionalCall', _43 => _43()]);
         s.markDirty();
       }
     }
@@ -339,13 +379,13 @@ var Entity = (_class2 = class {
    * @example entity.animate({ x: 400, opacity: 0 }, 500);
    */
   animate(targetProps, durationMs) {
-    this.animations.push({
+    (this.animations ??= []).push({
       target: targetProps,
       duration: durationMs,
       startTime: -1,
       startProps: {}
     });
-    _optionalChain([this, 'access', _40 => _40.scene, 'optionalAccess', _41 => _41.markDirty, 'call', _42 => _42()]);
+    _optionalChain([this, 'access', _44 => _44.scene, 'optionalAccess', _45 => _45.markDirty, 'call', _46 => _46()]);
     return this;
   }
   /** Write a driver-computed value to a backing field without re-triggering the setter. */
@@ -392,26 +432,26 @@ var Entity = (_class2 = 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 = _optionalChain([this, 'access', _47 => _47._drivers, 'optionalAccess', _48 => _48.get, 'call', _49 => _49(prop)]);
     if (existing) this._settleDriver(existing);
-    this._drivers.delete(prop);
+    _optionalChain([this, 'access', _50 => _50._drivers, 'optionalAccess', _51 => _51.delete, 'call', _52 => _52(prop)]);
     this._applyAnimated(prop, v);
   }
   _settleDriver(driver) {
     const active = driver;
     const onDone = active.onDone;
     active.onDone = void 0;
-    _optionalChain([onDone, 'optionalCall', _43 => _43()]);
+    _optionalChain([onDone, 'optionalCall', _53 => _53()]);
   }
   _spawnDriver(prop, to, cfg) {
-    if (prop !== "opacity" && _optionalChain([this, 'access', _44 => _44.scene, 'optionalAccess', _45 => _45.prefersReducedMotion])) {
-      const existing2 = this._drivers.get(prop);
+    if (prop !== "opacity" && _optionalChain([this, 'access', _54 => _54.scene, 'optionalAccess', _55 => _55.prefersReducedMotion])) {
+      const existing2 = _optionalChain([this, 'access', _56 => _56._drivers, 'optionalAccess', _57 => _57.get, 'call', _58 => _58(prop)]);
       if (existing2) this._settleDriver(existing2);
-      this._drivers.delete(prop);
+      _optionalChain([this, 'access', _59 => _59._drivers, 'optionalAccess', _60 => _60.delete, 'call', _61 => _61(prop)]);
       this._applyAnimated(prop, to);
       return;
     }
-    const existing = this._drivers.get(prop);
+    const existing = _optionalChain([this, 'access', _62 => _62._drivers, 'optionalAccess', _63 => _63.get, 'call', _64 => _64(prop)]);
     if (existing) {
       this._settleDriver(existing);
       existing.retarget(to);
@@ -419,12 +459,13 @@ var Entity = (_class2 = class {
     }
     const from = this._currentOf(prop);
     const driver = _animation.isTweenConfig.call(void 0, cfg) ? new (0, _animation.TweenDriver)(from, to, cfg) : new (0, _animation.SpringDriver)(from, to, cfg === "spring" ? {} : cfg);
-    this._drivers.set(prop, driver);
-    _optionalChain([this, 'access', _46 => _46.scene, 'optionalAccess', _47 => _47.markDirty, 'call', _48 => _48()]);
+    (this._drivers ??= /* @__PURE__ */ new Map()).set(prop, driver);
+    _optionalChain([this, 'access', _65 => _65.scene, 'optionalAccess', _66 => _66.markDirty, 'call', _67 => _67()]);
+    _optionalChain([this, 'access', _68 => _68.scene, 'optionalAccess', _69 => _69._registerActiveDriverEntity, 'call', _70 => _70(this)]);
   }
   /** Assignment path when a declarative transition is configured for `prop`. */
   _animateProp(prop, to) {
-    const cfg = _optionalChain([this, 'access', _49 => _49._transitions, 'optionalAccess', _50 => _50.get, 'call', _51 => _51(prop)]);
+    const cfg = _optionalChain([this, 'access', _71 => _71._transitions, 'optionalAccess', _72 => _72.get, 'call', _73 => _73(prop)]);
     if (!cfg) {
       this._applyAnimated(prop, to);
       return;
@@ -453,7 +494,7 @@ var Entity = (_class2 = class {
       entries.map(
         (e) => new Promise((resolve) => {
           this._spawnDriver(e[0], e[1], cfg);
-          const d = this._drivers.get(e[0]);
+          const d = _optionalChain([this, 'access', _74 => _74._drivers, 'optionalAccess', _75 => _75.get, 'call', _76 => _76(e[0])]);
           if (!d)
             resolve();
           else d.onDone = resolve;
@@ -463,7 +504,8 @@ var Entity = (_class2 = 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()) {
@@ -474,7 +516,39 @@ var Entity = (_class2 = class {
         this._applyAnimated(prop, driver.value);
       }
     }
-    _optionalChain([this, 'access', _52 => _52.scene, 'optionalAccess', _53 => _53.markDirty, 'call', _54 => _54()]);
+    _optionalChain([this, 'access', _77 => _77.scene, 'optionalAccess', _78 => _78.markDirty, 'call', _79 => _79()]);
+  }
+  /**
+   * 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);
+      _optionalChain([this, 'access', _80 => _80._drivers, 'optionalAccess', _81 => _81.delete, 'call', _82 => _82(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 +561,7 @@ var Entity = (_class2 = 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 +602,7 @@ var Entity = (_class2 = class {
    * @example entity.on('click', (e) => console.log('clicked', e));
    */
   on(event, callback, options) {
-    const map = _optionalChain([options, 'optionalAccess', _55 => _55.capture]) ? this.captureListeners : this.listeners;
+    const map = _optionalChain([options, 'optionalAccess', _83 => _83.capture]) ? this.captureListeners ??= /* @__PURE__ */ new Map() : this.listeners ??= /* @__PURE__ */ new Map();
     if (!map.has(event)) {
       map.set(event, []);
     }
@@ -544,7 +618,7 @@ var Entity = (_class2 = class {
    * @returns `this` for method chaining.
    */
   off(event, callback, options) {
-    const handlers = (_optionalChain([options, 'optionalAccess', _56 => _56.capture]) ? this.captureListeners : this.listeners).get(event);
+    const handlers = _optionalChain([(_optionalChain([options, 'optionalAccess', _84 => _84.capture]) ? this.captureListeners : this.listeners), 'optionalAccess', _85 => _85.get, 'call', _86 => _86(event)]);
     if (handlers) {
       const idx = handlers.indexOf(callback);
       if (idx !== -1) handlers.splice(idx, 1);
@@ -552,17 +626,37 @@ var Entity = (_class2 = 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();
+    _optionalChain([this, 'access', _87 => _87.listeners, 'optionalAccess', _88 => _88.clear, 'call', _89 => _89()]);
+    _optionalChain([this, 'access', _90 => _90.captureListeners, 'optionalAccess', _91 => _91.clear, 'call', _92 => _92()]);
     if (this.parent) {
       this.parent.remove(this);
     }
@@ -577,7 +671,7 @@ var Entity = (_class2 = class {
    * @param payload - Arbitrary data forwarded to each listener.
    */
   emit(event, payload) {
-    const handlers = this.listeners.get(event);
+    const handlers = _optionalChain([this, 'access', _93 => _93.listeners, 'optionalAccess', _94 => _94.get, 'call', _95 => _95(event)]);
     if (handlers) {
       handlers.forEach((h) => h(payload));
     }
@@ -591,19 +685,19 @@ var Entity = (_class2 = class {
    * with `requestAnimationFrame(() => document.getElementById(id)?.focus())`.
    */
   focus() {
-    const el = _optionalChain([this, 'access', _57 => _57.scene, 'optionalAccess', _58 => _58.getA11yElement, 'call', _59 => _59(this.id)]);
+    const el = _optionalChain([this, 'access', _96 => _96.scene, 'optionalAccess', _97 => _97.getA11yElement, 'call', _98 => _98(this.id)]);
     if (el) {
       el.focus();
       return;
     }
     requestAnimationFrame(() => {
-      const retry = _optionalChain([this, 'access', _60 => _60.scene, 'optionalAccess', _61 => _61.getA11yElement, 'call', _62 => _62(this.id)]);
+      const retry = _optionalChain([this, 'access', _99 => _99.scene, 'optionalAccess', _100 => _100.getA11yElement, 'call', _101 => _101(this.id)]);
       if (retry) retry.focus();
     });
   }
   /** Run one node's listeners for the event, honoring stopImmediatePropagation. */
   fireListeners(node, map, event) {
-    const handlers = map.get(event.type);
+    const handlers = _optionalChain([map, 'optionalAccess', _102 => _102.get, 'call', _103 => _103(event.type)]);
     if (!handlers) return;
     event.currentTarget = node;
     for (const h of handlers.slice()) {
@@ -642,10 +736,45 @@ var Entity = (_class2 = 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 +789,9 @@ var Entity = (_class2 = 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 +813,37 @@ var Entity = (_class2 = 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 +873,12 @@ var Entity = (_class2 = class {
    * does not provide a render-specific box.
    */
   getWorldBounds() {
-    const bounds = _nullishCoalesce(this.getBounds(), () => ( { x: 0, y: 0, width: this.width, height: this.height }));
+    const bounds = _nullishCoalesce(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 +1019,7 @@ var Entity = (_class2 = class {
    * @returns `true` if at least one animation or property driver remains.
    */
   hasPendingAnimations() {
-    return this.animations.length > 0 || this._drivers.size > 0;
+    return (_nullishCoalesce(_optionalChain([this, 'access', _104 => _104.animations, 'optionalAccess', _105 => _105.length]), () => ( 0))) > 0 || (_nullishCoalesce(_optionalChain([this, 'access', _106 => _106._drivers, 'optionalAccess', _107 => _107.size]), () => ( 0))) > 0;
   }
 }, _class2);
 
@@ -869,13 +1035,21 @@ var MSDFTextEntity = (_class3 = class extends Entity {
   
   
   
-  __init26() {this.text = ""}
-  __init27() {this.lastRenderedSeqId = 0}
-  __init28() {this.rgbColorCache = /* @__PURE__ */ new Map()}
-  __init29() {this.fontStringCache = []}
-  __init30() {this.layoutResult = null}
+  
+  // 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.
+  __init38() {this.hyphenator = null}
+  __init39() {this.layoutText = ""}
+  __init40() {this.text = ""}
+  __init41() {this.lastRenderedSeqId = 0}
+  __init42() {this.rgbColorCache = /* @__PURE__ */ new Map()}
+  __init43() {this.fontStringCache = []}
+  __init44() {this.layoutResult = null}
   constructor(text, options) {
-    super();_class3.prototype.__init26.call(this);_class3.prototype.__init27.call(this);_class3.prototype.__init28.call(this);_class3.prototype.__init29.call(this);_class3.prototype.__init30.call(this);;
+    super();_class3.prototype.__init38.call(this);_class3.prototype.__init39.call(this);_class3.prototype.__init40.call(this);_class3.prototype.__init41.call(this);_class3.prototype.__init42.call(this);_class3.prototype.__init43.call(this);_class3.prototype.__init44.call(this);;
     this.font = options.font;
     this.texture = options.texture;
     this.fallbackFont = _nullishCoalesce(options.fallbackFont, () => ( "sans-serif"));
@@ -885,6 +1059,7 @@ var MSDFTextEntity = (_class3 = class extends Entity {
     this.lineHeight = options.lineHeight;
     this.maxWidth = _nullishCoalesce(options.maxWidth, () => ( 1e3));
     this.maxHeight = _nullishCoalesce(options.maxHeight, () => ( 1e3));
+    this.textAlign = _nullishCoalesce(options.textAlign, () => ( "left"));
     this.setText(text);
   }
   /** Change the wrap boundary and re-run layout for the current text. */
@@ -893,13 +1068,53 @@ var MSDFTextEntity = (_class3 = 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() {
-    _layout.LayoutWorkerManager.getInstance().queueLayout(this.id, this.text, {
+    _layout.LayoutWorkerManager.getInstance().queueLayout(this.id, this.layoutText, {
       fontId: this.font.id,
       fontSize: this.fontSize,
       maxWidth: this.maxWidth,
@@ -907,11 +1122,12 @@ var MSDFTextEntity = (_class3 = 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;
         this.layoutResult = res;
-        _optionalChain([this, 'access', _63 => _63.scene, 'optionalAccess', _64 => _64.markDirty, 'call', _65 => _65()]);
+        _optionalChain([this, 'access', _108 => _108.scene, 'optionalAccess', _109 => _109.markDirty, 'call', _110 => _110()]);
       }
     });
   }
@@ -1016,7 +1232,7 @@ var MSDFTextEntity = (_class3 = class extends Entity {
     }
   }
   destroy() {
-    _layout.LayoutWorkerManager.getInstance().cancelLayout(this.id);
+    _layout.LayoutWorkerManager.cancelLayoutForEntity(this.id);
     super.destroy();
   }
 }, _class3);
@@ -1053,19 +1269,19 @@ function readSvgAttribute(source, name) {
   return null;
 }
 var SVGEntity = (_class4 = class extends Entity {
-  __init31() {this.svgSource = ""}
-  __init32() {this.imageBitmap = null}
-  __init33() {this.imageElement = null}
-  __init34() {this.blobURL = null}
-  __init35() {this.currentImg = null}
-  __init36() {this.lodTimeout = null}
-  __init37() {this.cachedDoc = null}
-  __init38() {this.baseWidth = 100}
-  __init39() {this.baseHeight = 100}
-  __init40() {this.lastRasterizedScale = 1}
-  __init41() {this.targetScale = 1}
+  __init45() {this.svgSource = ""}
+  __init46() {this.imageBitmap = null}
+  __init47() {this.imageElement = null}
+  __init48() {this.blobURL = null}
+  __init49() {this.currentImg = null}
+  __init50() {this.lodTimeout = null}
+  __init51() {this.cachedDoc = null}
+  __init52() {this.baseWidth = 100}
+  __init53() {this.baseHeight = 100}
+  __init54() {this.lastRasterizedScale = 1}
+  __init55() {this.targetScale = 1}
   constructor(svgSource, id) {
-    super(id);_class4.prototype.__init31.call(this);_class4.prototype.__init32.call(this);_class4.prototype.__init33.call(this);_class4.prototype.__init34.call(this);_class4.prototype.__init35.call(this);_class4.prototype.__init36.call(this);_class4.prototype.__init37.call(this);_class4.prototype.__init38.call(this);_class4.prototype.__init39.call(this);_class4.prototype.__init40.call(this);_class4.prototype.__init41.call(this);;
+    super(id);_class4.prototype.__init45.call(this);_class4.prototype.__init46.call(this);_class4.prototype.__init47.call(this);_class4.prototype.__init48.call(this);_class4.prototype.__init49.call(this);_class4.prototype.__init50.call(this);_class4.prototype.__init51.call(this);_class4.prototype.__init52.call(this);_class4.prototype.__init53.call(this);_class4.prototype.__init54.call(this);_class4.prototype.__init55.call(this);;
     this.setSVGSource(svgSource);
   }
   setSVGSource(svgSource) {