@vectojs/core 1.37.0 → 1.38.0

package/dist/{chunk-3MTVDXZQ.mjs → chunk-QVTCKWDO.mjs}

@@ -134,6 +134,12 @@ var VectoJSEvent = class {
   }
 };
 var Entity = class {
+  /**
+   * Whether Scene may ask {@link getRenderChildRange} to prune this entity's
+   * visual child traversal. Off by default so ordinary containers pay no
+   * viewport-inversion cost.
+   */
+  viewportCullChildren = false;
   id;
   children = [];
   parent = null;
@@ -1094,6 +1100,25 @@ var Entity = class {
   getBounds() {
     return null;
   }
+  /**
+   * Select a contiguous subset of direct children for visual rendering.
+   *
+   * Return `null` (the default) to visit every child. Containers may override
+   * this only when child order and geometry prove that every skipped child's
+   * entire painted subtree lies outside `localViewport`. The Scene still keeps
+   * all children resident, and hit testing, accessibility, and content
+   * projection continue to see the complete tree. Skipped subtrees do not run
+   * `update()` or `render()` in the visual pass, so opt in only for children that
+   * are static while offscreen or whose state advances outside those methods.
+   *
+   * The returned range is half-open and is clamped to `children.length`.
+   * `localViewport` is a conservative axis-aligned box obtained by mapping the
+   * Scene viewport into this entity's local coordinate space.
+   */
+  getRenderChildRange(localViewport) {
+    void localViewport;
+    return null;
+  }
   /**
    * 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.

package/dist/{chunk-DSYYQ6BQ.js → chunk-SRXU3ZXK.js}

@@ -136,9 +136,15 @@ var VectoJSEvent = (_class = class {
   }
 }, _class);
 var Entity = (_class2 = class {
+  /**
+   * Whether Scene may ask {@link getRenderChildRange} to prune this entity's
+   * visual child traversal. Off by default so ordinary containers pay no
+   * viewport-inversion cost.
+   */
+  __init3() {this.viewportCullChildren = false}
   
-  __init3() {this.children = []}
-  __init4() {this.parent = null}
+  __init4() {this.children = []}
+  __init5() {this.parent = null}
   /**
    * Walk up the parent chain to find the scene this entity is currently attached to.
    */
@@ -146,52 +152,52 @@ var Entity = (_class2 = class {
     if (this._scene) return this._scene;
     return this.parent ? this.parent.scene : null;
   }
-  __init5() {this._x = 0}
-  __init6() {this._y = 0}
-  __init7() {this._scaleX = 1}
-  __init8() {this._scaleY = 1}
-  __init9() {this._rotation = 0}
-  __init10() {this._opacity = 1}
+  __init6() {this._x = 0}
+  __init7() {this._y = 0}
+  __init8() {this._scaleX = 1}
+  __init9() {this._scaleY = 1}
+  __init10() {this._rotation = 0}
+  __init11() {this._opacity = 1}
   // Fast-path flag: false for the overwhelming majority of entities (incl. the
   // Danmaku hot loop), so a bare `entity.x = v` is one boolean check + field write.
-  __init11() {this._hasTransitions = false}
-  __init12() {this._transitions = null}
+  __init12() {this._hasTransitions = false}
+  __init13() {this._transitions = null}
   // 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}
+  __init14() {this._drivers = null}
+  __init15() {this._mounted = false}
+  __init16() {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}
+  __init17() {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}
+  __init18() {this._trig = { cos: 1, sin: 0 }}
+  __init19() {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}
+  __init20() {this._wa = 1}
+  __init21() {this._wb = 0}
+  __init22() {this._wc = 0}
+  __init23() {this._wd = 1}
+  __init24() {this._we = 0}
+  __init25() {this._wf = 0}
+  __init26() {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}
+  __init27() {this._storeSlot = -1}
   get x() {
     return this._x;
   }
@@ -234,8 +240,8 @@ var Entity = (_class2 = class {
     if (this._hasTransitions) this._animateProp("opacity", v);
     else this._opacity = v;
   }
-  __init27() {this.isDOMPortal = false}
-  __init28() {this._interactive = false}
+  __init28() {this.isDOMPortal = false}
+  __init29() {this._interactive = false}
   get interactive() {
     return this._interactive;
   }
@@ -249,10 +255,10 @@ var Entity = (_class2 = class {
       }
     }
   }
-  __init29() {this.width = 0}
-  __init30() {this.height = 0}
-  __init31() {this.a11yOffsetX = 0}
-  __init32() {this.a11yOffsetY = 0}
+  __init30() {this.width = 0}
+  __init31() {this.height = 0}
+  __init32() {this.a11yOffsetX = 0}
+  __init33() {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
@@ -260,7 +266,7 @@ var Entity = (_class2 = class {
    * that need global pointer events. The node is mounted behind all other shadow
    * nodes, so on-top components stay clickable.
    */
-  __init33() {this.a11yFullViewport = false}
+  __init34() {this.a11yFullViewport = false}
   /**
    * When this entity's a11y shadow node is materialized.
    *
@@ -307,7 +313,7 @@ var Entity = (_class2 = class {
    * `vectojs-native/danmaku`. Use `'onDemand'` to stop paying per entity, not as
    * the whole accessibility story.
    */
-  __init34() {this.a11yProjection = "eager"}
+  __init35() {this.a11yProjection = "eager"}
   /**
    * Hide this entity AND its whole subtree from the accessibility/automation
    * projection, regardless of each node's own `interactive` flag.
@@ -325,14 +331,14 @@ var Entity = (_class2 = class {
    * `=== 0` test never fires; a threshold would instead silently un-project a
    * faint-but-live control.
    */
-  __init35() {this.a11yHidden = false}
+  __init36() {this.a11yHidden = 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.
    */
-  __init36() {this.clipChildren = false}
+  __init37() {this.clipChildren = false}
   /**
    * Group this subtree's projected text into its own accessibility **region**,
    * without clipping anything.
@@ -359,14 +365,14 @@ var Entity = (_class2 = class {
    *
    * Off by default. Regions nest: the nearest enclosing region wins.
    */
-  __init37() {this.a11yRegion = false}
+  __init38() {this.a11yRegion = false}
   // Lazily allocated (see _drivers above). Most entities never register a
   // listener or an imperative animate() tween.
-  __init38() {this.listeners = null}
+  __init39() {this.listeners = null}
   /** Capture-phase listeners (fired root→target before bubble). */
-  __init39() {this.captureListeners = null}
-  __init40() {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);_class2.prototype.__init38.call(this);_class2.prototype.__init39.call(this);_class2.prototype.__init40.call(this);
+  __init40() {this.captureListeners = null}
+  __init41() {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);_class2.prototype.__init38.call(this);_class2.prototype.__init39.call(this);_class2.prototype.__init40.call(this);_class2.prototype.__init41.call(this);
     this.id = id || `entity_${Math.random().toString(36).substring(2, 9)}`;
   }
   /**
@@ -1096,6 +1102,25 @@ var Entity = (_class2 = class {
   getBounds() {
     return null;
   }
+  /**
+   * Select a contiguous subset of direct children for visual rendering.
+   *
+   * Return `null` (the default) to visit every child. Containers may override
+   * this only when child order and geometry prove that every skipped child's
+   * entire painted subtree lies outside `localViewport`. The Scene still keeps
+   * all children resident, and hit testing, accessibility, and content
+   * projection continue to see the complete tree. Skipped subtrees do not run
+   * `update()` or `render()` in the visual pass, so opt in only for children that
+   * are static while offscreen or whose state advances outside those methods.
+   *
+   * The returned range is half-open and is clamped to `children.length`.
+   * `localViewport` is a conservative axis-aligned box obtained by mapping the
+   * Scene viewport into this entity's local coordinate space.
+   */
+  getRenderChildRange(localViewport) {
+    void localViewport;
+    return null;
+  }
   /**
    * 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.
@@ -1208,28 +1233,28 @@ var MSDFTextEntity = (_class3 = class extends Entity {
   // 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.
-  __init41() {this.hyphenator = null}
-  __init42() {this.layoutText = ""}
-  __init43() {this.text = ""}
-  __init44() {this.lastRenderedSeqId = 0}
+  __init42() {this.hyphenator = null}
+  __init43() {this.layoutText = ""}
+  __init44() {this.text = ""}
+  __init45() {this.lastRenderedSeqId = 0}
   /** Bumped by {@link queueLayout}; read by `Scene` to skip an unchanged sync. */
-  __init45() {this.contentEpoch = 0}
+  __init46() {this.contentEpoch = 0}
   // Atlas-decode subscription (see watchAtlasDecode). Held so `destroy()` can
   // release it: the handler closes over `this`, so leaving it attached to a
   // long-lived shared atlas image would retain the whole entity.
-  __init46() {this.atlasDecodeTarget = null}
-  __init47() {this.atlasDecodeHandler = null}
-  __init48() {this.rgbColorCache = /* @__PURE__ */ new Map()}
-  __init49() {this.fontStringCache = []}
-  __init50() {this.layoutResult = null}
+  __init47() {this.atlasDecodeTarget = null}
+  __init48() {this.atlasDecodeHandler = null}
+  __init49() {this.rgbColorCache = /* @__PURE__ */ new Map()}
+  __init50() {this.fontStringCache = []}
+  __init51() {this.layoutResult = null}
   /**
    * Visual rows rebuilt from {@link layoutResult} (see
    * {@link rebuildProjectionLines}). Empty until a layout reply lands and the
    * reply's shaped glyphs can be mapped back to the source text 1:1.
    */
-  __init51() {this.projectionLines = []}
+  __init52() {this.projectionLines = []}
   constructor(text, options) {
-    super();_class3.prototype.__init41.call(this);_class3.prototype.__init42.call(this);_class3.prototype.__init43.call(this);_class3.prototype.__init44.call(this);_class3.prototype.__init45.call(this);_class3.prototype.__init46.call(this);_class3.prototype.__init47.call(this);_class3.prototype.__init48.call(this);_class3.prototype.__init49.call(this);_class3.prototype.__init50.call(this);_class3.prototype.__init51.call(this);;
+    super();_class3.prototype.__init42.call(this);_class3.prototype.__init43.call(this);_class3.prototype.__init44.call(this);_class3.prototype.__init45.call(this);_class3.prototype.__init46.call(this);_class3.prototype.__init47.call(this);_class3.prototype.__init48.call(this);_class3.prototype.__init49.call(this);_class3.prototype.__init50.call(this);_class3.prototype.__init51.call(this);_class3.prototype.__init52.call(this);;
     this.font = options.font;
     this.texture = options.texture;
     this.fallbackFont = _nullishCoalesce(options.fallbackFont, () => ( "sans-serif"));
@@ -1596,23 +1621,23 @@ var SVGEntity = (_class4 = class extends Entity {
    * rasterized. Set to `'transparent'` to opt out and keep the box empty.
    * Default `'rgba(248,113,113,0.9)'`.
    */
-  __init52() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
+  __init53() {this.fallbackStroke = "rgba(248,113,113,0.9)"}
   /** Fill behind the fallback marker. Default `'rgba(248,113,113,0.12)'`. */
-  __init53() {this.fallbackFill = "rgba(248,113,113,0.12)"}
-  __init54() {this.svgSource = ""}
-  __init55() {this.imageBitmap = null}
-  __init56() {this.imageElement = null}
-  __init57() {this.blobURL = null}
-  __init58() {this.currentImg = null}
-  __init59() {this.lodTimeout = null}
-  __init60() {this.rasterFailed = false}
-  __init61() {this.cachedDoc = null}
-  __init62() {this.baseWidth = 100}
-  __init63() {this.baseHeight = 100}
-  __init64() {this.lastRasterizedScale = 1}
-  __init65() {this.targetScale = 1}
+  __init54() {this.fallbackFill = "rgba(248,113,113,0.12)"}
+  __init55() {this.svgSource = ""}
+  __init56() {this.imageBitmap = null}
+  __init57() {this.imageElement = null}
+  __init58() {this.blobURL = null}
+  __init59() {this.currentImg = null}
+  __init60() {this.lodTimeout = null}
+  __init61() {this.rasterFailed = false}
+  __init62() {this.cachedDoc = null}
+  __init63() {this.baseWidth = 100}
+  __init64() {this.baseHeight = 100}
+  __init65() {this.lastRasterizedScale = 1}
+  __init66() {this.targetScale = 1}
   constructor(svgSource, id) {
-    super(id);_class4.prototype.__init52.call(this);_class4.prototype.__init53.call(this);_class4.prototype.__init54.call(this);_class4.prototype.__init55.call(this);_class4.prototype.__init56.call(this);_class4.prototype.__init57.call(this);_class4.prototype.__init58.call(this);_class4.prototype.__init59.call(this);_class4.prototype.__init60.call(this);_class4.prototype.__init61.call(this);_class4.prototype.__init62.call(this);_class4.prototype.__init63.call(this);_class4.prototype.__init64.call(this);_class4.prototype.__init65.call(this);;
+    super(id);_class4.prototype.__init53.call(this);_class4.prototype.__init54.call(this);_class4.prototype.__init55.call(this);_class4.prototype.__init56.call(this);_class4.prototype.__init57.call(this);_class4.prototype.__init58.call(this);_class4.prototype.__init59.call(this);_class4.prototype.__init60.call(this);_class4.prototype.__init61.call(this);_class4.prototype.__init62.call(this);_class4.prototype.__init63.call(this);_class4.prototype.__init64.call(this);_class4.prototype.__init65.call(this);_class4.prototype.__init66.call(this);;
     this.setSVGSource(svgSource);
   }
   setSVGSource(svgSource) {

package/dist/index.js

@@ -19,7 +19,7 @@ var _chunkZYYP2M5Djs = require('./chunk-ZYYP2M5D.js');
 
 
 
-var _chunkDSYYQ6BQjs = require('./chunk-DSYYQ6BQ.js');
+var _chunkSRXU3ZXKjs = require('./chunk-SRXU3ZXK.js');
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -31,7 +31,7 @@ var PARTICLE_OFFSET_ORIGIN_X = 4;
 var PARTICLE_OFFSET_ORIGIN_Y = 5;
 var PARTICLE_OFFSET_SIZE = 6;
 var PARTICLE_OFFSET_LIFE = 7;
-var ComputeParticleEntity = (_class = class extends _chunkDSYYQ6BQjs.Entity {
+var ComputeParticleEntity = (_class = class extends _chunkSRXU3ZXKjs.Entity {
   
   
   
@@ -4824,7 +4824,7 @@ var Scene = (_class15 = class _Scene {
       this.forcedColorsChangeHandler = () => this.markDirty();
       _optionalChain([this, 'access', _118 => _118.forcedColorsQuery, 'access', _119 => _119.addEventListener, 'optionalCall', _120 => _120("change", this.forcedColorsChangeHandler)]);
     }
-    this.root = new class RootEntity extends _chunkDSYYQ6BQjs.Entity {
+    this.root = new class RootEntity extends _chunkSRXU3ZXKjs.Entity {
       isPointInside() {
         return false;
       }
@@ -4834,7 +4834,7 @@ var Scene = (_class15 = class _Scene {
     }("root");
     this.root._scene = this;
     this._wasmBackend = new WasmBackendFacade(this.root);
-    this.overlayRoot = new class OverlayRoot extends _chunkDSYYQ6BQjs.Entity {
+    this.overlayRoot = new class OverlayRoot extends _chunkSRXU3ZXKjs.Entity {
       isPointInside() {
         return false;
       }
@@ -5154,7 +5154,7 @@ var Scene = (_class15 = class _Scene {
       }
       if (this.hoveredA11yElements.has(el)) {
         this.hoveredA11yElements.delete(el);
-        node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointerleave", node, void 0, false));
+        node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointerleave", node, void 0, false));
       }
       this.preserveFocusOnRemoval(el);
       el.remove();
@@ -5745,20 +5745,20 @@ var Scene = (_class15 = class _Scene {
           el.style.background = "transparent";
         }
         el.addEventListener("click", (e) => {
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("click", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("click", node, e));
         });
         el.addEventListener("dblclick", (e) => {
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("dblclick", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("dblclick", node, e));
         });
         el.addEventListener("mouseenter", (e) => {
           if (this.debugA11y) el.style.backgroundColor = "rgba(56, 189, 248, 0.2)";
           this.hoveredA11yElements.add(el);
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("hover", node, e, false));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("hover", node, e, false));
         });
         el.addEventListener("mouseleave", (e) => {
           if (this.debugA11y) el.style.backgroundColor = "rgba(56, 189, 248, 0.05)";
           this.hoveredA11yElements.delete(el);
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointerleave", node, e, false));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointerleave", node, e, false));
         });
         const capEl = el;
         const releasePointer = (event) => {
@@ -5774,24 +5774,24 @@ var Scene = (_class15 = class _Scene {
         };
         el.addEventListener("pointerdown", (e) => {
           if (typeof capEl.setPointerCapture === "function") capEl.setPointerCapture(e.pointerId);
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointerdown", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointerdown", node, e));
         });
         el.addEventListener("pointerup", (e) => {
           releasePointer(e);
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointerup", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointerup", node, e));
         });
         el.addEventListener("pointercancel", (e) => {
           releasePointer(e);
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointercancel", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointercancel", node, e));
         });
         el.addEventListener(
           "pointermove",
-          (e) => node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("pointermove", node, e))
+          (e) => node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("pointermove", node, e))
         );
         el.addEventListener(
           "wheel",
           (e) => {
-            node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("wheel", node, e));
+            node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("wheel", node, e));
           },
           { passive: false }
         );
@@ -5816,10 +5816,10 @@ var Scene = (_class15 = class _Scene {
         );
         emitInitialScroll = emitScroll;
         el.addEventListener("keydown", (e) => {
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("keydown", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("keydown", node, e));
         });
         el.addEventListener("keyup", (e) => {
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("keyup", node, e));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("keyup", node, e));
         });
         if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
           const input = el;
@@ -5885,7 +5885,7 @@ var Scene = (_class15 = class _Scene {
           el.addEventListener("keydown", (e) => {
             if (e.key === "Enter" || e.key === " ") {
               e.preventDefault();
-              node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("click", node, e));
+              node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("click", node, e));
             }
           });
         }
@@ -6322,7 +6322,7 @@ var Scene = (_class15 = class _Scene {
       el.addEventListener(
         "wheel",
         (e2) => {
-          node.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)("wheel", node, e2));
+          node.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)("wheel", node, e2));
         },
         { passive: false }
       );
@@ -6991,7 +6991,7 @@ var Scene = (_class15 = class _Scene {
     let walkHadAnimation = false;
     let walkHadInteractive = false;
     const runUpdate = (node) => {
-      const overridesUpdate = node.update !== _chunkDSYYQ6BQjs.Entity.prototype.update;
+      const overridesUpdate = node.update !== _chunkSRXU3ZXKjs.Entity.prototype.update;
       let pending = node.hasPendingAnimations();
       if (pending || overridesUpdate) {
         node.update(dt, time);
@@ -7000,7 +7000,7 @@ var Scene = (_class15 = class _Scene {
       if (pending) walkHadAnimation = true;
       if (!walkHadInteractive && node.interactive) walkHadInteractive = true;
       if (this._devActive && this._devFrameCount % 120 === 0) {
-        if (overridesUpdate && node.hasPendingAnimations === _chunkDSYYQ6BQjs.Entity.prototype.hasPendingAnimations) {
+        if (overridesUpdate && node.hasPendingAnimations === _chunkSRXU3ZXKjs.Entity.prototype.hasPendingAnimations) {
           this._devWarn(
             `Entity "${node.id}" overrides update() but not hasPendingAnimations(). Custom motion in update() without overriding hasPendingAnimations() causes the idle throttle to slow the animation. Override hasPendingAnimations() to return true while motion is in flight.`
           );
@@ -7172,8 +7172,43 @@ var Scene = (_class15 = class _Scene {
       if (node.clipChildren) {
         renderer.clip(0, 0, node.width, node.height);
       }
-      for (const child of node.children) {
-        renderNode(child, a, b, c, d, te, tf, worldOpacity);
+      const children = node.children;
+      let childStart = 0;
+      let childEnd = children.length;
+      if (childEnd > 0 && node.viewportCullChildren) {
+        const det = a * d - b * c;
+        if (Number.isFinite(det) && Math.abs(det) > 1e-12) {
+          const invDet = 1 / det;
+          let minLocalX = Infinity;
+          let minLocalY = Infinity;
+          let maxLocalX = -Infinity;
+          let maxLocalY = -Infinity;
+          for (let i = 0; i < 4; i++) {
+            const worldX = i & 1 ? vw : 0;
+            const worldY = i & 2 ? vh : 0;
+            const dx = worldX - te;
+            const dy = worldY - tf;
+            const localX = (d * dx - c * dy) * invDet;
+            const localY = (-b * dx + a * dy) * invDet;
+            if (localX < minLocalX) minLocalX = localX;
+            if (localX > maxLocalX) maxLocalX = localX;
+            if (localY < minLocalY) minLocalY = localY;
+            if (localY > maxLocalY) maxLocalY = localY;
+          }
+          const range = node.getRenderChildRange({
+            x: minLocalX,
+            y: minLocalY,
+            width: maxLocalX - minLocalX,
+            height: maxLocalY - minLocalY
+          });
+          if (range) {
+            childStart = Math.max(0, Math.min(childEnd, Math.floor(range.start)));
+            childEnd = Math.max(childStart, Math.min(childEnd, Math.ceil(range.end)));
+          }
+        }
+      }
+      for (let i = childStart; i < childEnd; i++) {
+        renderNode(children[i], a, b, c, d, te, tf, worldOpacity);
       }
       renderer.flush();
       renderer.restore();
@@ -7426,7 +7461,7 @@ function defaultMeasurer() {
   sharedMeasurer ??= _layout.resolveGlyphMeasurer.call(void 0, "sans-serif");
   return sharedMeasurer;
 }
-var TextEntity = (_class16 = class extends _chunkDSYYQ6BQjs.Entity {
+var TextEntity = (_class16 = class extends _chunkSRXU3ZXKjs.Entity {
   
   
   
@@ -7630,7 +7665,7 @@ var TextEntity = (_class16 = class extends _chunkDSYYQ6BQjs.Entity {
 }, _class16);
 
 // src/components/GridTextEntity.ts
-var GridTextEntity = (_class17 = class extends _chunkDSYYQ6BQjs.Entity {
+var GridTextEntity = (_class17 = class extends _chunkSRXU3ZXKjs.Entity {
   
   __init185() {this.fillStyle = "#ffffff"}
   __init186() {this.grid = []}
@@ -7724,7 +7759,7 @@ function distSqToSegment(px, py, x1, y1, x2, y2) {
   const ey = py - cy;
   return ex * ex + ey * ey;
 }
-var SplineEntity = (_class18 = class extends _chunkDSYYQ6BQjs.Entity {
+var SplineEntity = (_class18 = class extends _chunkSRXU3ZXKjs.Entity {
   
   
   
@@ -8052,7 +8087,7 @@ async function loadSpline(url) {
 }
 
 // src/components/Rect.ts
-var Rect = class extends _chunkDSYYQ6BQjs.Entity {
+var Rect = class extends _chunkSRXU3ZXKjs.Entity {
   
   
   
@@ -8108,7 +8143,7 @@ var Rect = class extends _chunkDSYYQ6BQjs.Entity {
 };
 
 // src/components/Circle.ts
-var Circle = class extends _chunkDSYYQ6BQjs.Entity {
+var Circle = class extends _chunkSRXU3ZXKjs.Entity {
   
   
   
@@ -8172,7 +8207,7 @@ var Circle = class extends _chunkDSYYQ6BQjs.Entity {
 };
 
 // src/components/Group.ts
-var Group = class extends _chunkDSYYQ6BQjs.Entity {
+var Group = class extends _chunkSRXU3ZXKjs.Entity {
   constructor(...children) {
     super();
     if (children.length > 0) this.add(...children);
@@ -8191,7 +8226,7 @@ var _math = require('@vectojs/math'); _createStarExport(_math);
 
 
 // src/tree/DOMPortalEntity.ts
-var DOMPortalEntity = (_class19 = class extends _chunkDSYYQ6BQjs.Entity {
+var DOMPortalEntity = (_class19 = class extends _chunkSRXU3ZXKjs.Entity {
   
   __init196() {this.isDOMPortal = true}
   __init197() {this.domListeners = []}
@@ -8247,7 +8282,7 @@ var DOMPortalEntity = (_class19 = class extends _chunkDSYYQ6BQjs.Entity {
     ];
     for (const type of events) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)(type, this, e));
+        this.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)(type, this, e));
       };
       this.domElement.addEventListener(type, handler);
       this.domListeners.push({ type, handler, capture: false });
@@ -8258,7 +8293,7 @@ var DOMPortalEntity = (_class19 = class extends _chunkDSYYQ6BQjs.Entity {
     ];
     for (const { native, vecto } of hoverEvents) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)(vecto, this, e, false));
+        this.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)(vecto, this, e, false));
       };
       this.domElement.addEventListener(native, handler);
       this.domListeners.push({ type: native, handler, capture: false });
@@ -8266,7 +8301,7 @@ var DOMPortalEntity = (_class19 = class extends _chunkDSYYQ6BQjs.Entity {
     const focusEvents = ["focus", "blur"];
     for (const type of focusEvents) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDSYYQ6BQjs.VectoJSEvent)(type, this, e, true));
+        this.dispatchEvent(new (0, _chunkSRXU3ZXKjs.VectoJSEvent)(type, this, e, true));
       };
       this.domElement.addEventListener(type, handler, true);
       this.domListeners.push({ type, handler, capture: true });
@@ -8364,4 +8399,4 @@ Scene.registerWebGPUParticleSystemManager(_chunkZYYP2M5Djs.WebGPUParticleSystemM
 
 
 
-exports.CanvasRenderer = _chunkZYYP2M5Djs.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DEFAULT_CONTENT_SEMANTIC_BUDGET = DEFAULT_CONTENT_SEMANTIC_BUDGET; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkDSYYQ6BQjs.Entity; exports.GlyphRasterAtlas = _chunkZYYP2M5Djs.GlyphRasterAtlas; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkDSYYQ6BQjs.MSDFTextEntity; exports.PARTICLE_OFFSET_LIFE = PARTICLE_OFFSET_LIFE; exports.PARTICLE_OFFSET_ORIGIN_X = PARTICLE_OFFSET_ORIGIN_X; exports.PARTICLE_OFFSET_ORIGIN_Y = PARTICLE_OFFSET_ORIGIN_Y; exports.PARTICLE_OFFSET_POSITION_X = PARTICLE_OFFSET_POSITION_X; exports.PARTICLE_OFFSET_POSITION_Y = PARTICLE_OFFSET_POSITION_Y; exports.PARTICLE_OFFSET_SIZE = PARTICLE_OFFSET_SIZE; exports.PARTICLE_OFFSET_VELOCITY_X = PARTICLE_OFFSET_VELOCITY_X; exports.PARTICLE_OFFSET_VELOCITY_Y = PARTICLE_OFFSET_VELOCITY_Y; exports.PARTICLE_STRIDE_FLOATS = PARTICLE_STRIDE_FLOATS; exports.REDUCED_MOTION_FPS = REDUCED_MOTION_FPS; exports.Rect = Rect; exports.SCENE_OPTION_KEYS = SCENE_OPTION_KEYS; exports.SVGEntity = _chunkDSYYQ6BQjs.SVGEntity; exports.SVGRenderer = _chunkZYYP2M5Djs.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkZYYP2M5Djs.TextRasterCache; exports.VECTO_USER_TIMING = VECTO_USER_TIMING; exports.VectoJSEvent = _chunkDSYYQ6BQjs.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkZYYP2M5Djs.WebGPUParticleSystemManager; exports.beginVectoUserTiming = beginVectoUserTiming; exports.contentLineInHint = _chunkDSYYQ6BQjs.contentLineInHint; exports.createWebGLPointRenderer = _chunkZYYP2M5Djs.createWebGLPointRenderer; exports.endVectoUserTiming = endVectoUserTiming; exports.installRendererDevTraps = _chunkZYYP2M5Djs.installRendererDevTraps; exports.isRendererDevMode = _chunkZYYP2M5Djs.isRendererDevMode; exports.isSafeUrl = _chunkZYYP2M5Djs.isSafeUrl; exports.loadSpline = loadSpline; exports.measureVectoUserTiming = measureVectoUserTiming; exports.parseColorToRGBA = _chunkZYYP2M5Djs.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkZYYP2M5Djs.sanitizeUrl; exports.setRendererDevMode = _chunkZYYP2M5Djs.setRendererDevMode;
+exports.CanvasRenderer = _chunkZYYP2M5Djs.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DEFAULT_CONTENT_SEMANTIC_BUDGET = DEFAULT_CONTENT_SEMANTIC_BUDGET; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkSRXU3ZXKjs.Entity; exports.GlyphRasterAtlas = _chunkZYYP2M5Djs.GlyphRasterAtlas; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkSRXU3ZXKjs.MSDFTextEntity; exports.PARTICLE_OFFSET_LIFE = PARTICLE_OFFSET_LIFE; exports.PARTICLE_OFFSET_ORIGIN_X = PARTICLE_OFFSET_ORIGIN_X; exports.PARTICLE_OFFSET_ORIGIN_Y = PARTICLE_OFFSET_ORIGIN_Y; exports.PARTICLE_OFFSET_POSITION_X = PARTICLE_OFFSET_POSITION_X; exports.PARTICLE_OFFSET_POSITION_Y = PARTICLE_OFFSET_POSITION_Y; exports.PARTICLE_OFFSET_SIZE = PARTICLE_OFFSET_SIZE; exports.PARTICLE_OFFSET_VELOCITY_X = PARTICLE_OFFSET_VELOCITY_X; exports.PARTICLE_OFFSET_VELOCITY_Y = PARTICLE_OFFSET_VELOCITY_Y; exports.PARTICLE_STRIDE_FLOATS = PARTICLE_STRIDE_FLOATS; exports.REDUCED_MOTION_FPS = REDUCED_MOTION_FPS; exports.Rect = Rect; exports.SCENE_OPTION_KEYS = SCENE_OPTION_KEYS; exports.SVGEntity = _chunkSRXU3ZXKjs.SVGEntity; exports.SVGRenderer = _chunkZYYP2M5Djs.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkZYYP2M5Djs.TextRasterCache; exports.VECTO_USER_TIMING = VECTO_USER_TIMING; exports.VectoJSEvent = _chunkSRXU3ZXKjs.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkZYYP2M5Djs.WebGPUParticleSystemManager; exports.beginVectoUserTiming = beginVectoUserTiming; exports.contentLineInHint = _chunkSRXU3ZXKjs.contentLineInHint; exports.createWebGLPointRenderer = _chunkZYYP2M5Djs.createWebGLPointRenderer; exports.endVectoUserTiming = endVectoUserTiming; exports.installRendererDevTraps = _chunkZYYP2M5Djs.installRendererDevTraps; exports.isRendererDevMode = _chunkZYYP2M5Djs.isRendererDevMode; exports.isSafeUrl = _chunkZYYP2M5Djs.isSafeUrl; exports.loadSpline = loadSpline; exports.measureVectoUserTiming = measureVectoUserTiming; exports.parseColorToRGBA = _chunkZYYP2M5Djs.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkZYYP2M5Djs.sanitizeUrl; exports.setRendererDevMode = _chunkZYYP2M5Djs.setRendererDevMode;

package/dist/index.mjs

@@ -18,7 +18,7 @@ import {
   SVGEntity,
   VectoJSEvent,
   contentLineInHint
-} from "./chunk-3MTVDXZQ.mjs";
+} from "./chunk-QVTCKWDO.mjs";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -7171,8 +7171,43 @@ var Scene = class _Scene {
       if (node.clipChildren) {
         renderer.clip(0, 0, node.width, node.height);
       }
-      for (const child of node.children) {
-        renderNode(child, a, b, c, d, te, tf, worldOpacity);
+      const children = node.children;
+      let childStart = 0;
+      let childEnd = children.length;
+      if (childEnd > 0 && node.viewportCullChildren) {
+        const det = a * d - b * c;
+        if (Number.isFinite(det) && Math.abs(det) > 1e-12) {
+          const invDet = 1 / det;
+          let minLocalX = Infinity;
+          let minLocalY = Infinity;
+          let maxLocalX = -Infinity;
+          let maxLocalY = -Infinity;
+          for (let i = 0; i < 4; i++) {
+            const worldX = i & 1 ? vw : 0;
+            const worldY = i & 2 ? vh : 0;
+            const dx = worldX - te;
+            const dy = worldY - tf;
+            const localX = (d * dx - c * dy) * invDet;
+            const localY = (-b * dx + a * dy) * invDet;
+            if (localX < minLocalX) minLocalX = localX;
+            if (localX > maxLocalX) maxLocalX = localX;
+            if (localY < minLocalY) minLocalY = localY;
+            if (localY > maxLocalY) maxLocalY = localY;
+          }
+          const range = node.getRenderChildRange({
+            x: minLocalX,
+            y: minLocalY,
+            width: maxLocalX - minLocalX,
+            height: maxLocalY - minLocalY
+          });
+          if (range) {
+            childStart = Math.max(0, Math.min(childEnd, Math.floor(range.start)));
+            childEnd = Math.max(childStart, Math.min(childEnd, Math.ceil(range.end)));
+          }
+        }
+      }
+      for (let i = childStart; i < childEnd; i++) {
+        renderNode(children[i], a, b, c, d, te, tf, worldOpacity);
       }
       renderer.flush();
       renderer.restore();

package/dist/text.js

@@ -2,11 +2,11 @@
 
 
 
-var _chunkDSYYQ6BQjs = require('./chunk-DSYYQ6BQ.js');
+var _chunkSRXU3ZXKjs = require('./chunk-SRXU3ZXK.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkDSYYQ6BQjs.MSDFTextEntity; exports.SVGEntity = _chunkDSYYQ6BQjs.SVGEntity;
+exports.MSDFTextEntity = _chunkSRXU3ZXKjs.MSDFTextEntity; exports.SVGEntity = _chunkSRXU3ZXKjs.SVGEntity;

package/dist/text.mjs

@@ -1,7 +1,7 @@
 import {
   MSDFTextEntity,
   SVGEntity
-} from "./chunk-3MTVDXZQ.mjs";
+} from "./chunk-QVTCKWDO.mjs";
 
 // src/text/index.ts
 export * from "@vectojs/text";

package/dist/tree/Entity.d.ts

@@ -29,6 +29,13 @@ export interface Bounds {
     width: number;
     height: number;
 }
+/** Half-open child index range selected for the current render traversal. */
+export interface RenderChildRange {
+    /** Index of the first child to visit. */
+    start: number;
+    /** Index after the last child to visit. */
+    end: number;
+}
 /**
  * Describes an entity that renders as a single filled circle at its local
  * origin, returned from {@link Entity.getBatchCircle} to opt into the renderer's
@@ -577,6 +584,12 @@ export declare class VectoJSEvent<N = unknown> {
  * }
  */
 export declare abstract class Entity {
+    /**
+     * Whether Scene may ask {@link getRenderChildRange} to prune this entity's
+     * visual child traversal. Off by default so ordinary containers pay no
+     * viewport-inversion cost.
+     */
+    viewportCullChildren: boolean;
     id: string;
     children: Entity[];
     parent: Entity | null;
@@ -1057,6 +1070,22 @@ export declare abstract class Entity {
      * @returns The local bounds, or `null` to opt out of culling.
      */
     getBounds(): Bounds | null;
+    /**
+     * Select a contiguous subset of direct children for visual rendering.
+     *
+     * Return `null` (the default) to visit every child. Containers may override
+     * this only when child order and geometry prove that every skipped child's
+     * entire painted subtree lies outside `localViewport`. The Scene still keeps
+     * all children resident, and hit testing, accessibility, and content
+     * projection continue to see the complete tree. Skipped subtrees do not run
+     * `update()` or `render()` in the visual pass, so opt in only for children that
+     * are static while offscreen or whose state advances outside those methods.
+     *
+     * The returned range is half-open and is clamped to `children.length`.
+     * `localViewport` is a conservative axis-aligned box obtained by mapping the
+     * Scene viewport into this entity's local coordinate space.
+     */
+    getRenderChildRange(localViewport: Bounds): RenderChildRange | null;
     /**
      * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "publishConfig": {
     "access": "public"
   },