@vectojs/core 1.17.0 → 1.18.0

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

@@ -237,7 +237,7 @@ var Entity = (_class2 = class {
       const s = this.scene;
       if (s) {
         s.a11yNeedsReorder = true;
-        s.markDirty();
+        s.markDirty({ entity: this.id, reason: "a11y-reorder" });
       }
     }
   }
@@ -301,7 +301,7 @@ var Entity = (_class2 = class {
     if (s) {
       s.a11yNeedsReorder = true;
       _optionalChain([s, 'access', _40 => _40.markStructureChanged, 'optionalCall', _41 => _41()]);
-      s.markDirty();
+      s.markDirty({ entity: this.id, reason: "child-added" });
       child._notifyMounted();
     }
   }
@@ -331,7 +331,7 @@ var Entity = (_class2 = class {
         s.detachA11y(child);
         s.a11yNeedsReorder = true;
         _optionalChain([s, 'access', _42 => _42.markStructureChanged, 'optionalCall', _43 => _43()]);
-        s.markDirty();
+        s.markDirty({ entity: this.id, reason: "child-removed" });
       }
     }
     return this;
@@ -385,7 +385,7 @@ var Entity = (_class2 = class {
       startTime: -1,
       startProps: {}
     });
-    _optionalChain([this, 'access', _44 => _44.scene, 'optionalAccess', _45 => _45.markDirty, 'call', _46 => _46()]);
+    _optionalChain([this, 'access', _44 => _44.scene, 'optionalAccess', _45 => _45.markDirty, 'call', _46 => _46({ entity: this.id, reason: "animation-start" })]);
     return this;
   }
   /** Write a driver-computed value to a backing field without re-triggering the setter. */
@@ -460,7 +460,7 @@ 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 ??= /* @__PURE__ */ new Map()).set(prop, driver);
-    _optionalChain([this, 'access', _65 => _65.scene, 'optionalAccess', _66 => _66.markDirty, 'call', _67 => _67()]);
+    _optionalChain([this, 'access', _65 => _65.scene, 'optionalAccess', _66 => _66.markDirty, 'call', _67 => _67({ entity: this.id, reason: "driver-added" })]);
     _optionalChain([this, 'access', _68 => _68.scene, 'optionalAccess', _69 => _69._registerActiveDriverEntity, 'call', _70 => _70(this)]);
   }
   /** Assignment path when a declarative transition is configured for `prop`. */
@@ -516,7 +516,7 @@ var Entity = (_class2 = class {
         this._applyAnimated(prop, driver.value);
       }
     }
-    _optionalChain([this, 'access', _77 => _77.scene, 'optionalAccess', _78 => _78.markDirty, 'call', _79 => _79()]);
+    _optionalChain([this, 'access', _77 => _77.scene, 'optionalAccess', _78 => _78.markDirty, 'call', _79 => _79({ entity: this.id, reason: "driver-tick" })]);
   }
   /**
    * Internal: this entity's active-driver map (read-only view), or `null` if

package/dist/{chunk-AQTO7OSU.mjs → chunk-XWBVBXFZ.mjs}

@@ -235,7 +235,7 @@ var Entity = class {
       const s = this.scene;
       if (s) {
         s.a11yNeedsReorder = true;
-        s.markDirty();
+        s.markDirty({ entity: this.id, reason: "a11y-reorder" });
       }
     }
   }
@@ -299,7 +299,7 @@ var Entity = class {
     if (s) {
       s.a11yNeedsReorder = true;
       s.markStructureChanged?.();
-      s.markDirty();
+      s.markDirty({ entity: this.id, reason: "child-added" });
       child._notifyMounted();
     }
   }
@@ -329,7 +329,7 @@ var Entity = class {
         s.detachA11y(child);
         s.a11yNeedsReorder = true;
         s.markStructureChanged?.();
-        s.markDirty();
+        s.markDirty({ entity: this.id, reason: "child-removed" });
       }
     }
     return this;
@@ -383,7 +383,7 @@ var Entity = class {
       startTime: -1,
       startProps: {}
     });
-    this.scene?.markDirty();
+    this.scene?.markDirty({ entity: this.id, reason: "animation-start" });
     return this;
   }
   /** Write a driver-computed value to a backing field without re-triggering the setter. */
@@ -458,7 +458,7 @@ 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 ??= /* @__PURE__ */ new Map()).set(prop, driver);
-    this.scene?.markDirty();
+    this.scene?.markDirty({ entity: this.id, reason: "driver-added" });
     this.scene?._registerActiveDriverEntity(this);
   }
   /** Assignment path when a declarative transition is configured for `prop`. */
@@ -514,7 +514,7 @@ var Entity = class {
         this._applyAnimated(prop, driver.value);
       }
     }
-    this.scene?.markDirty();
+    this.scene?.markDirty({ entity: this.id, reason: "driver-tick" });
   }
   /**
    * Internal: this entity's active-driver map (read-only view), or `null` if

package/dist/index.js

@@ -14,7 +14,7 @@ var _chunkL4SWVP2Hjs = require('./chunk-L4SWVP2H.js');
 
 
 
-var _chunkDUYB4GX4js = require('./chunk-DUYB4GX4.js');
+var _chunkIA3KW4CGjs = require('./chunk-IA3KW4CG.js');
 
 // src/tree/Scene.ts
 var _animation = require('@vectojs/animation'); _createStarExport(_animation);
@@ -29,7 +29,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 _chunkDUYB4GX4js.Entity {
+var ComputeParticleEntity = (_class = class extends _chunkIA3KW4CGjs.Entity {
   
   
   
@@ -1107,10 +1107,10 @@ function cacheKey(source) {
   if (source instanceof URL) return source.href;
   return null;
 }
-async function compile(source) {
-  if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
-    return new WebAssembly.Module(source);
-  }
+function compileBytes(bytes) {
+  return new WebAssembly.Module(bytes);
+}
+async function compileRemote(source) {
   const response = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
   if (typeof WebAssembly.compileStreaming === "function") {
     const buffered = response.clone();
@@ -1135,7 +1135,7 @@ async function loadCoreWasmModule(source) {
       }
     }
   }
-  const pending = compile(source);
+  const pending = source instanceof ArrayBuffer || ArrayBuffer.isView(source) ? Promise.resolve().then(() => compileBytes(source)) : compileRemote(source);
   if (key !== null) moduleCache.set(key, pending);
   try {
     return await pending;
@@ -1191,6 +1191,7 @@ async function loadCoreWasmRuntime(source) {
 
 // src/tree/Scene.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
+var RANGE_VALUE_ROLES = /* @__PURE__ */ new Set(["slider", "spinbutton", "progressbar", "scrollbar", "meter"]);
 var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
   "button",
   "switch",
@@ -1536,30 +1537,34 @@ var Scene = (_class7 = class _Scene {
    *   event-driven UIs where idle frames should cost ~0.
    */
   __init29() {this.renderMode = "always"}
-  __init30() {this.dirty = true}
+  /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
+  static __initStatic4() {this.MAX_DIRTY_REASONS = 200}
+  __init30() {this._dirtyTracking = false}
+  __init31() {this._dirtyReasons = /* @__PURE__ */ new Map()}
+  __init32() {this.dirty = true}
   /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
-  __init31() {this.autoThrottle = true}
+  __init33() {this.autoThrottle = true}
   // --- Frame telemetry (read via `frameStats`) ---------------------------
   /** Wall-clock ms spent inside the last `render()` call. */
-  __init32() {this._lastFrameMs = 0}
+  __init34() {this._lastFrameMs = 0}
   /** Rolling exponential average of rendered-frame intervals, in ms. */
-  __init33() {this._avgFrameIntervalMs = 0}
+  __init35() {this._avgFrameIntervalMs = 0}
   /** dt (ms) handed to the last rendered frame. */
-  __init34() {this._lastDt = 0}
+  __init36() {this._lastDt = 0}
   /** Count of frames actually rendered since the loop started. */
-  __init35() {this._renderedFrames = 0}
+  __init37() {this._renderedFrames = 0}
   /** Count of rAF ticks skipped (idle / capped) since the loop started. */
-  __init36() {this._skippedFrames = 0}
+  __init38() {this._skippedFrames = 0}
   /** `time` of the previous *rendered* frame, for interval measurement. */
-  __init37() {this._lastRenderTick = 0}
+  __init39() {this._lastRenderTick = 0}
   /**
    * Frame-rate cap (power saving). `0` = uncapped (native refresh). When set,
    * the loop renders at most `maxFPS` times per second; animations still run,
    * just less often. See {@link SceneOptions.maxFPS}.
    */
-  __init38() {this.maxFPS = 60}
+  __init40() {this.maxFPS = 60}
   /** Whether the OS prefers-reduced-motion setting auto-caps the loop. */
-  __init39() {this.respectReducedMotion = true}
+  __init41() {this.respectReducedMotion = true}
   /**
    * Reading direction for accessibility tab/traversal order (`'ltr'` default,
    * `'rtl'`). Controls the inline sort within a visual row in
@@ -1575,15 +1580,15 @@ var Scene = (_class7 = class _Scene {
       this.a11yNeedsReorder = true;
     }
   }
-  __init40() {this._readingDirection = "ltr"}
+  __init42() {this._readingDirection = "ltr"}
   /** Cached media-query list; `.matches` is read live each frame. */
-  __init41() {this.reducedMotionQuery = null}
+  __init43() {this.reducedMotionQuery = null}
   /** Cached `(forced-colors: active)` query (Windows High Contrast etc.). A
    *  canvas gets NO automatic forced-colors treatment from the browser (it's
    *  opaque pixels), so components must read {@link forcedColors} and repaint
    *  with system colors themselves; a change listener repaints idle scenes. */
-  __init42() {this.forcedColorsQuery = null}
-  __init43() {this.forcedColorsChangeHandler = null}
+  __init44() {this.forcedColorsQuery = null}
+  __init45() {this.forcedColorsChangeHandler = null}
   /** True when the OS asks for reduced motion and we respect it. Read by the animation drivers. */
   get prefersReducedMotion() {
     return this.respectReducedMotion && !!_optionalChain([this, 'access', _21 => _21.reducedMotionQuery, 'optionalAccess', _22 => _22.matches]);
@@ -1603,82 +1608,82 @@ var Scene = (_class7 = class _Scene {
    * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
    * frame. See {@link SceneOptions.a11ySyncInterval}.
    */
-  __init44() {this.a11ySyncInterval = 0}
+  __init46() {this.a11ySyncInterval = 0}
   /** Timestamp of the last a11y sync, for throttling. */
-  __init45() {this.lastA11ySync = -Infinity}
+  __init47() {this.lastA11ySync = -Infinity}
   /** True if we skipped an a11y sync during animation and need to sync when at rest. */
-  __init46() {this.a11yPendingSyncAfterAnimation = false}
+  __init48() {this.a11yPendingSyncAfterAnimation = false}
   // A11y / Automation Layer. `null` in non-DOM (SSR/Node) environments — the
   // whole projection degrades to a no-op so the engine's logic stays usable
   // server-side (e.g. headless layout / vector export) without jsdom.
   
-  __init47() {this.a11yElements = /* @__PURE__ */ new Map()}
+  __init49() {this.a11yElements = /* @__PURE__ */ new Map()}
   /** DOM nodes mirroring static text content, keyed by entity id. */
-  __init48() {this.contentElements = /* @__PURE__ */ new Map()}
+  __init50() {this.contentElements = /* @__PURE__ */ new Map()}
   /** Pending cold font-calibration frame per projected grid entity. */
-  __init49() {this.contentGridCalibrationFrames = /* @__PURE__ */ new Map()}
+  __init51() {this.contentGridCalibrationFrames = /* @__PURE__ */ new Map()}
   /** Detached, untransformed font probes used by the cold calibration pass. */
-  __init50() {this.contentGridCalibrationProbes = /* @__PURE__ */ new Map()}
+  __init52() {this.contentGridCalibrationProbes = /* @__PURE__ */ new Map()}
   /** Invalidates grid font calibration after browser font availability changes. */
-  __init51() {this.contentFontEpoch = 0}
+  __init53() {this.contentFontEpoch = 0}
   /** Cached Canvas-to-client scale for the current font/viewport epoch. */
-  __init52() {this.contentMetricScaleEpoch = -1}
-  __init53() {this.contentMetricScaleX = 1}
-  __init54() {this.contentProjectionEnabled = true}
+  __init54() {this.contentMetricScaleEpoch = -1}
+  __init55() {this.contentMetricScaleX = 1}
+  __init56() {this.contentProjectionEnabled = true}
   // Virtualization margin (px) for content projection; `undefined` → one
   // viewport height, resolved at sync time. `Infinity` = materialize everything.
-  __init55() {this.contentProjectionMargin = void 0}
+  __init57() {this.contentProjectionMargin = void 0}
   /**
    * True while a text-selection drag that started on a projection's blank
    * region (no text node under the press) is being driven manually — the
    * browser has no native anchor for it, so mousemove extends the Selection
    * from the position we resolved ourselves.
    */
-  __init56() {this.blankRegionSelectionDrag = false}
-  __init57() {this.contentSelectionAnchor = null}
-  __init58() {this.contentSelectionEndListener = null}
+  __init58() {this.blankRegionSelectionDrag = false}
+  __init59() {this.contentSelectionAnchor = null}
+  __init60() {this.contentSelectionEndListener = null}
   // Animation/interactive flags collected during the render walk (tree-walk
   // fusion): the loop reads last frame's answers instead of re-walking the
   // tree up to 4× per tick. Start true so the first tick stays conservative.
-  __init59() {this.frameHadAnimation = true}
-  __init60() {this.frameHadInteractive = true}
+  __init61() {this.frameHadAnimation = true}
+  __init62() {this.frameHadInteractive = true}
   
   /** Active `(resolution: Ndppx)` media query watching for a runtime DPR change
    *  (window moved between monitors, browser zoom) so the canvas backing store
    *  can be re-scaled — otherwise it stays rasterized at the old DPR and blurs.
    *  A resolution media query only fires when leaving its exact value, so the
    *  handler re-arms a fresh query for the new DPR each time. */
-  __init61() {this.dprMediaQuery = null}
+  __init63() {this.dprMediaQuery = null}
   /** For embedded (`disableWindowResize`) scenes: observes the canvas element so
    *  a CSS/layout-driven size change re-runs `resize()`. A window `resize`
    *  listener never fires for these (the window isn't what changed), so without
    *  this an embedded canvas stayed at its initial size forever. */
-  __init62() {this.canvasResizeObserver = null}
-  __init63() {this.dprChangeHandler = null}
-  __init64() {this.focusedA11yElement = null}
+  __init64() {this.canvasResizeObserver = null}
+  __init65() {this.dprChangeHandler = null}
+  __init66() {this.focusedA11yElement = null}
   /** Last geometry `syncOverlayGeometry` wrote, so an unchanged frame can skip the
    *  style writes entirely. Reset to `null` to force the next sync (a new overlay
    *  layer was created and has never been positioned). */
-  __init65() {this._overlayGeometry = null}
+  __init67() {this._overlayGeometry = null}
   /** Shadow elements the pointer is currently inside. Lets a removal that happens
    *  mid-hover synthesize the `pointerleave` the browser never sends for a
    *  detached element, so the entity doesn't keep its hover state. */
-  __init66() {this.hoveredA11yElements = /* @__PURE__ */ new WeakSet()}
+  __init68() {this.hoveredA11yElements = /* @__PURE__ */ new WeakSet()}
   /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
    *  pruned (virtualization/streaming/removal) while it holds focus, we move
    *  focus here instead of letting the browser drop it to <body> — keeping the
    *  screen-reader virtual cursor inside the scene's a11y region. */
-  __init67() {this.focusSentinel = null}
-  __init68() {this.caretBlinkTimer = null}
-  __init69() {this.a11yNeedsReorder = true}
-  __init70() {this.portalRoot = null}
-  __init71() {this.fullViewportElements = []}
-  __init72() {this.normalElements = []}
-  __init73() {this.activeIds = /* @__PURE__ */ new Set()}
-  __init74() {this.activePortalsThisFrame = /* @__PURE__ */ new Set()}
-  __init75() {this.activePortalsPrevFrame = /* @__PURE__ */ new Set()}
-  __init76() {this.portalEntities = /* @__PURE__ */ new Map()}
-  __init77() {this.renderOrderCounter = 0}
+  __init69() {this.focusSentinel = null}
+  __init70() {this.caretBlinkTimer = null}
+  __init71() {this.a11yNeedsReorder = true}
+  __init72() {this.portalRoot = null}
+  __init73() {this.fullViewportElements = []}
+  __init74() {this.normalElements = []}
+  __init75() {this.activeIds = /* @__PURE__ */ new Set()}
+  __init76() {this.activePortalsThisFrame = /* @__PURE__ */ new Set()}
+  __init77() {this.activePortalsPrevFrame = /* @__PURE__ */ new Set()}
+  __init78() {this.portalEntities = /* @__PURE__ */ new Map()}
+  __init79() {this.renderOrderCounter = 0}
   /**
    * Monotonic render-frame counter, bumped once per authoritative `render()`
    * pass. Entities stamp their per-frame world-matrix cache with this value and
@@ -1687,7 +1692,7 @@ var Scene = (_class7 = class _Scene {
    * back to the ancestor walk. Public for the same reason `Entity._getTrig`/
    * `_setWorldCache` are: it is a cross-class render-internal contract.
    */
-  __init78() {this.currentFrame = 0}
+  __init80() {this.currentFrame = 0}
   // ── WASM transform backend (invisible accelerator) ──────────────────────────
   // When `_transformBackend === 'wasm'`, the main render walk sources each
   // entity's world matrix from an SoA store composed by `_wasm` (see
@@ -1695,24 +1700,24 @@ var Scene = (_class7 = class _Scene {
   // fallback and the default: a null backend, a non-main renderer, or any entity
   // absent from the store all fall back to the JS composition, so WASM can only
   // ever change *how fast* a world matrix is produced, never *what* it is.
-  __init79() {this._wasm = null}
-  __init80() {this._transformBackend = "js"}
+  __init81() {this._wasm = null}
+  __init82() {this._transformBackend = "js"}
   // Resident store state (Stage 3). The store layout — slot assignment + sibling
   // runs — depends only on tree TOPOLOGY, so it is rebuilt only when the
   // structure changes (add/remove/reparent bump `_structureVersion`). Between
   // rebuilds the per-frame cost is: gather each entity's transform into the
   // resident wasm input view + run the kernel — no reallocation, no readback.
-  __init81() {this._treeStore = null}
-  __init82() {this._slotEntity = []}
+  __init83() {this._treeStore = null}
+  __init84() {this._slotEntity = []}
   // store slot -> entity (also validates slots)
-  __init83() {this._wasmInputs = null}
-  __init84() {this._wasmWorld = null}
-  __init85() {this._structureVersion = 0}
-  __init86() {this._storeStructureVersion = -1}
+  __init85() {this._wasmInputs = null}
+  __init86() {this._wasmWorld = null}
+  __init87() {this._structureVersion = 0}
+  __init88() {this._storeStructureVersion = -1}
   // Cached list of ComputeParticleEntity instances in the tree, keyed by the
   // structure version it was gathered at. Rebuilt only on a topology change.
-  __init87() {this._computeEntities = []}
-  __init88() {this._computeEntitiesVersion = -1}
+  __init89() {this._computeEntities = []}
+  __init90() {this._computeEntitiesVersion = -1}
   /** Invalidate the resident WASM store layout; the next wasm-mode frame rebuilds
    *  it. Called by `Entity.add`/`remove` (topology changes only). */
   markStructureChanged() {
@@ -1794,7 +1799,7 @@ var Scene = (_class7 = class _Scene {
    * cached globally; the instance is per-Scene, which is the isolation that
    * actually matters.
    */
-  __init89() {this._wasmRuntime = null}
+  __init91() {this._wasmRuntime = null}
   /**
    * Load (or reuse) this Scene's shared WASM runtime.
    *
@@ -1822,30 +1827,30 @@ var Scene = (_class7 = class _Scene {
   get wasmRuntime() {
     return this._wasmRuntime;
   }
-  __init90() {this._hitWasm = null}
+  __init92() {this._hitWasm = null}
   // Cache key: which frame + structure version the grid was last (successfully,
   // non-overflowing) built for. findEntityAt is called ad-hoc (pointer
   // hover/click), not every frame, so the grid is refreshed lazily on demand
   // rather than proactively every render() — unlike the transform store, which
   // every frame's draw depends on.
-  __init91() {this._hitGridFrame = -1}
-  __init92() {this._hitGridOk = false}
-  __init93() {this._hitSlotEntity = []}
-  __init94() {this._hitBoundless = []}
+  __init93() {this._hitGridFrame = -1}
+  __init94() {this._hitGridOk = false}
+  __init95() {this._hitSlotEntity = []}
+  __init96() {this._hitBoundless = []}
   /** Reused buffer for the fused gather, so a pointer query allocates nothing. */
-  __init95() {this._hitGatherBuffer = null}
+  __init97() {this._hitGatherBuffer = null}
   /**
    * Whether the last grid build sourced its AABBs from the WASM transform store
    * rather than recomputing them in JS. Diagnostic only — both paths must
    * produce the same entity for a given point.
    */
-  __init96() {this._hitFusedGather = false}
+  __init98() {this._hitFusedGather = false}
   /**
    * Whether `compute_aabbs` has run against the current frame's world matrices.
    * The AABB pass is only meaningful after a `compose_*`, so the fused gather
    * must not read the views before then.
    */
-  __init97() {this._wasmAabbsFresh = false}
+  __init99() {this._wasmAabbsFresh = false}
   /** Did the last hit-grid build use the fused (WASM-store) gather? */
   get hitGatherPath() {
     return this._hitFusedGather ? "fused" : "js";
@@ -1959,25 +1964,25 @@ var Scene = (_class7 = class _Scene {
   // EasingFn (which cannot cross into WASM) all fall through to it — WASM can
   // only ever change *how* a driver is advanced, never *what* value it lands
   // on.
-  __init98() {this._animWasm = null}
+  __init100() {this._animWasm = null}
   // Entities with at least one active driver, added by Entity._spawnDriver.
   // Self-pruning: _tickBatchedDrivers drops an entry the first time it visits
   // an entity whose drivers have since all completed or been removed. This is
   // what lets the batch pass find its candidates in O(active drivers), not
   // O(tree size) — the exact mistake G3's first integrated benchmark made.
-  __init99() {this._activeDriverEntities = /* @__PURE__ */ new Set()}
+  __init101() {this._activeDriverEntities = /* @__PURE__ */ new Set()}
   // Reused across frames instead of allocating a fresh array + N {entity,prop,
   // driver} objects every call — the integrated benchmark
   // (benchmarks/anim-wasm-scene) found that allocation churn was the
   // dominant integrated cost, not the wasm kernel itself. Parallel arrays,
   // truncated to the live count after each use so a stale tail slot never
   // pins a no-longer-active entity/driver in memory.
-  __init100() {this._springEntities = []}
-  __init101() {this._springProps = []}
-  __init102() {this._springDrivers = []}
-  __init103() {this._tweenEntities = []}
-  __init104() {this._tweenProps = []}
-  __init105() {this._tweenDrivers = []}
+  __init102() {this._springEntities = []}
+  __init103() {this._springProps = []}
+  __init104() {this._springDrivers = []}
+  __init105() {this._tweenEntities = []}
+  __init106() {this._tweenProps = []}
+  __init107() {this._tweenDrivers = []}
   /**
    * Minimum number of batchable (spring, or named-easing tween) active drivers
    * before a frame engages the WASM batch path at all; below it, every driver
@@ -2049,7 +2054,7 @@ var Scene = (_class7 = class _Scene {
    * Setting {@link animDriverGateCount} overwrites all three, so existing code
    * that tuned the single knob keeps working unchanged.
    */
-  __init106() {this._animBatchedLastFrame = false}
+  __init108() {this._animBatchedLastFrame = false}
   /**
    * Whether the WASM batch path actually ran on the most recent frame.
    *
@@ -2061,7 +2066,7 @@ var Scene = (_class7 = class _Scene {
   get animBatchedLastFrame() {
     return this._animBatchedLastFrame;
   }
-  __init107() {this.animGate = {
+  __init109() {this.animGate = {
     spring: 128,
     tween: 256,
     mixed: 128
@@ -2099,7 +2104,7 @@ var Scene = (_class7 = class _Scene {
   // (benchmarks/particle-wasm). f32 (matches the WGSL shader), bit-identical to
   // a JS f32 reference oracle; updateCPU (f64) stays the permanent fallback when
   // no backend is installed or a scene runs on WebGPU.
-  __init108() {this._particleWasm = null}
+  __init110() {this._particleWasm = null}
   /** Which backend runs the CPU particle simulation. Reflects only whether a
    *  backend is installed (the WebGPU compute path, when active, is used first
    *  regardless). */
@@ -2349,46 +2354,46 @@ var Scene = (_class7 = class _Scene {
    * sync, so retaining the order prevents a newly opened overlay from spending
    * its first frame below previously projected controls.
    */
-  __init109() {this.a11yRenderOrders = /* @__PURE__ */ new Map()}
+  __init111() {this.a11yRenderOrders = /* @__PURE__ */ new Map()}
   // Optional WebGL point-cloud layer (see SceneOptions.pointBackend).
-  __init110() {this.pointRenderer = null}
-  __init111() {this.glCanvas = null}
-  __init112() {this.glContextLostHandler = null}
-  __init113() {this.glContextRestoredHandler = null}
+  __init112() {this.pointRenderer = null}
+  __init113() {this.glCanvas = null}
+  __init114() {this.glContextLostHandler = null}
+  __init115() {this.glContextRestoredHandler = null}
   
   
   
-  __init114() {this.disableWindowResize = false}
+  __init116() {this.disableWindowResize = false}
   /** See {@link SceneOptions.maxDPR}. `undefined` = uncapped (real DPR). */
   
   // WebGPU properties
-  __init115() {this.destroyed = false}
-  __init116() {this.device = null}
-  __init117() {this.deviceLost = false}
-  __init118() {this.particleBackend = "auto"}
-  __init119() {this._webgpuDisabled = false}
+  __init117() {this.destroyed = false}
+  __init118() {this.device = null}
+  __init119() {this.deviceLost = false}
+  __init120() {this.particleBackend = "auto"}
+  __init121() {this._webgpuDisabled = false}
   get webgpuDisabled() {
     return this._webgpuDisabled || this.particleBackend === "cpu";
   }
   set webgpuDisabled(value) {
     this._webgpuDisabled = value;
   }
-  __init120() {this.recoveryTimerId = null}
-  __init121() {this.manager = null}
-  __init122() {this.initializingWebGPU = false}
-  __init123() {this.gpuCanvas = null}
-  __init124() {this.gpuContext = null}
+  __init122() {this.recoveryTimerId = null}
+  __init123() {this.manager = null}
+  __init124() {this.initializingWebGPU = false}
+  __init125() {this.gpuCanvas = null}
+  __init126() {this.gpuContext = null}
   /** True while the GPU canvas holds a presented particle frame (needs clearing when they leave). */
-  __init125() {this.gpuHasContent = false}
-  __init126() {this.mouseX = -9999}
-  __init127() {this.mouseY = -9999}
-  __init128() {this.pointerMoveListener = null}
-  __init129() {this.pointerLeaveListener = null}
+  __init127() {this.gpuHasContent = false}
+  __init128() {this.mouseX = -9999}
+  __init129() {this.mouseY = -9999}
+  __init130() {this.pointerMoveListener = null}
+  __init131() {this.pointerLeaveListener = null}
   /** Element the pointer listeners are bound to (parent container if present,
    *  else the canvas). Stored so `destroy()` detaches from the same element. */
-  __init130() {this.pointerEventTarget = null}
-  __init131() {this.hasWarnedZeroSize = false}
-  __init132() {this.fontLoadHandler = null}
+  __init132() {this.pointerEventTarget = null}
+  __init133() {this.hasWarnedZeroSize = false}
+  __init134() {this.fontLoadHandler = null}
   // ── Dev-mode warning infrastructure ──────────────────────────────
   //
   // Enable with `Scene.devMode = true` or by setting `globalThis.__DEV__`.
@@ -2397,7 +2402,7 @@ var Scene = (_class7 = class _Scene {
   // Checks run once every ~120 frames (~2s at 60fps) to keep overhead
   // negligible even when dev mode is on.
   /** Toggle development-mode runtime warnings globally. */
-  static __initStatic4() {this.devMode = false}
+  static __initStatic5() {this.devMode = false}
   static _devModeDetected() {
     if (_Scene.devMode) return true;
     const gp = typeof globalThis !== "undefined" ? globalThis : void 0;
@@ -2406,7 +2411,7 @@ var Scene = (_class7 = class _Scene {
     return false;
   }
   
-  __init133() {this._devFrameCount = 0}
+  __init135() {this._devFrameCount = 0}
   _devWarn(message) {
     if (!this._devActive) return;
     console.warn(`[vectojs/dev] ${message}`);
@@ -2450,7 +2455,7 @@ var Scene = (_class7 = class _Scene {
     };
     walkProjections(this.root);
   }
-  constructor(canvas, options = {}) {;_class7.prototype.__init25.call(this);_class7.prototype.__init26.call(this);_class7.prototype.__init27.call(this);_class7.prototype.__init28.call(this);_class7.prototype.__init29.call(this);_class7.prototype.__init30.call(this);_class7.prototype.__init31.call(this);_class7.prototype.__init32.call(this);_class7.prototype.__init33.call(this);_class7.prototype.__init34.call(this);_class7.prototype.__init35.call(this);_class7.prototype.__init36.call(this);_class7.prototype.__init37.call(this);_class7.prototype.__init38.call(this);_class7.prototype.__init39.call(this);_class7.prototype.__init40.call(this);_class7.prototype.__init41.call(this);_class7.prototype.__init42.call(this);_class7.prototype.__init43.call(this);_class7.prototype.__init44.call(this);_class7.prototype.__init45.call(this);_class7.prototype.__init46.call(this);_class7.prototype.__init47.call(this);_class7.prototype.__init48.call(this);_class7.prototype.__init49.call(this);_class7.prototype.__init50.call(this);_class7.prototype.__init51.call(this);_class7.prototype.__init52.call(this);_class7.prototype.__init53.call(this);_class7.prototype.__init54.call(this);_class7.prototype.__init55.call(this);_class7.prototype.__init56.call(this);_class7.prototype.__init57.call(this);_class7.prototype.__init58.call(this);_class7.prototype.__init59.call(this);_class7.prototype.__init60.call(this);_class7.prototype.__init61.call(this);_class7.prototype.__init62.call(this);_class7.prototype.__init63.call(this);_class7.prototype.__init64.call(this);_class7.prototype.__init65.call(this);_class7.prototype.__init66.call(this);_class7.prototype.__init67.call(this);_class7.prototype.__init68.call(this);_class7.prototype.__init69.call(this);_class7.prototype.__init70.call(this);_class7.prototype.__init71.call(this);_class7.prototype.__init72.call(this);_class7.prototype.__init73.call(this);_class7.prototype.__init74.call(this);_class7.prototype.__init75.call(this);_class7.prototype.__init76.call(this);_class7.prototype.__init77.call(this);_class7.prototype.__init78.call(this);_class7.prototype.__init79.call(this);_class7.prototype.__init80.call(this);_class7.prototype.__init81.call(this);_class7.prototype.__init82.call(this);_class7.prototype.__init83.call(this);_class7.prototype.__init84.call(this);_class7.prototype.__init85.call(this);_class7.prototype.__init86.call(this);_class7.prototype.__init87.call(this);_class7.prototype.__init88.call(this);_class7.prototype.__init89.call(this);_class7.prototype.__init90.call(this);_class7.prototype.__init91.call(this);_class7.prototype.__init92.call(this);_class7.prototype.__init93.call(this);_class7.prototype.__init94.call(this);_class7.prototype.__init95.call(this);_class7.prototype.__init96.call(this);_class7.prototype.__init97.call(this);_class7.prototype.__init98.call(this);_class7.prototype.__init99.call(this);_class7.prototype.__init100.call(this);_class7.prototype.__init101.call(this);_class7.prototype.__init102.call(this);_class7.prototype.__init103.call(this);_class7.prototype.__init104.call(this);_class7.prototype.__init105.call(this);_class7.prototype.__init106.call(this);_class7.prototype.__init107.call(this);_class7.prototype.__init108.call(this);_class7.prototype.__init109.call(this);_class7.prototype.__init110.call(this);_class7.prototype.__init111.call(this);_class7.prototype.__init112.call(this);_class7.prototype.__init113.call(this);_class7.prototype.__init114.call(this);_class7.prototype.__init115.call(this);_class7.prototype.__init116.call(this);_class7.prototype.__init117.call(this);_class7.prototype.__init118.call(this);_class7.prototype.__init119.call(this);_class7.prototype.__init120.call(this);_class7.prototype.__init121.call(this);_class7.prototype.__init122.call(this);_class7.prototype.__init123.call(this);_class7.prototype.__init124.call(this);_class7.prototype.__init125.call(this);_class7.prototype.__init126.call(this);_class7.prototype.__init127.call(this);_class7.prototype.__init128.call(this);_class7.prototype.__init129.call(this);_class7.prototype.__init130.call(this);_class7.prototype.__init131.call(this);_class7.prototype.__init132.call(this);_class7.prototype.__init133.call(this);
+  constructor(canvas, options = {}) {;_class7.prototype.__init25.call(this);_class7.prototype.__init26.call(this);_class7.prototype.__init27.call(this);_class7.prototype.__init28.call(this);_class7.prototype.__init29.call(this);_class7.prototype.__init30.call(this);_class7.prototype.__init31.call(this);_class7.prototype.__init32.call(this);_class7.prototype.__init33.call(this);_class7.prototype.__init34.call(this);_class7.prototype.__init35.call(this);_class7.prototype.__init36.call(this);_class7.prototype.__init37.call(this);_class7.prototype.__init38.call(this);_class7.prototype.__init39.call(this);_class7.prototype.__init40.call(this);_class7.prototype.__init41.call(this);_class7.prototype.__init42.call(this);_class7.prototype.__init43.call(this);_class7.prototype.__init44.call(this);_class7.prototype.__init45.call(this);_class7.prototype.__init46.call(this);_class7.prototype.__init47.call(this);_class7.prototype.__init48.call(this);_class7.prototype.__init49.call(this);_class7.prototype.__init50.call(this);_class7.prototype.__init51.call(this);_class7.prototype.__init52.call(this);_class7.prototype.__init53.call(this);_class7.prototype.__init54.call(this);_class7.prototype.__init55.call(this);_class7.prototype.__init56.call(this);_class7.prototype.__init57.call(this);_class7.prototype.__init58.call(this);_class7.prototype.__init59.call(this);_class7.prototype.__init60.call(this);_class7.prototype.__init61.call(this);_class7.prototype.__init62.call(this);_class7.prototype.__init63.call(this);_class7.prototype.__init64.call(this);_class7.prototype.__init65.call(this);_class7.prototype.__init66.call(this);_class7.prototype.__init67.call(this);_class7.prototype.__init68.call(this);_class7.prototype.__init69.call(this);_class7.prototype.__init70.call(this);_class7.prototype.__init71.call(this);_class7.prototype.__init72.call(this);_class7.prototype.__init73.call(this);_class7.prototype.__init74.call(this);_class7.prototype.__init75.call(this);_class7.prototype.__init76.call(this);_class7.prototype.__init77.call(this);_class7.prototype.__init78.call(this);_class7.prototype.__init79.call(this);_class7.prototype.__init80.call(this);_class7.prototype.__init81.call(this);_class7.prototype.__init82.call(this);_class7.prototype.__init83.call(this);_class7.prototype.__init84.call(this);_class7.prototype.__init85.call(this);_class7.prototype.__init86.call(this);_class7.prototype.__init87.call(this);_class7.prototype.__init88.call(this);_class7.prototype.__init89.call(this);_class7.prototype.__init90.call(this);_class7.prototype.__init91.call(this);_class7.prototype.__init92.call(this);_class7.prototype.__init93.call(this);_class7.prototype.__init94.call(this);_class7.prototype.__init95.call(this);_class7.prototype.__init96.call(this);_class7.prototype.__init97.call(this);_class7.prototype.__init98.call(this);_class7.prototype.__init99.call(this);_class7.prototype.__init100.call(this);_class7.prototype.__init101.call(this);_class7.prototype.__init102.call(this);_class7.prototype.__init103.call(this);_class7.prototype.__init104.call(this);_class7.prototype.__init105.call(this);_class7.prototype.__init106.call(this);_class7.prototype.__init107.call(this);_class7.prototype.__init108.call(this);_class7.prototype.__init109.call(this);_class7.prototype.__init110.call(this);_class7.prototype.__init111.call(this);_class7.prototype.__init112.call(this);_class7.prototype.__init113.call(this);_class7.prototype.__init114.call(this);_class7.prototype.__init115.call(this);_class7.prototype.__init116.call(this);_class7.prototype.__init117.call(this);_class7.prototype.__init118.call(this);_class7.prototype.__init119.call(this);_class7.prototype.__init120.call(this);_class7.prototype.__init121.call(this);_class7.prototype.__init122.call(this);_class7.prototype.__init123.call(this);_class7.prototype.__init124.call(this);_class7.prototype.__init125.call(this);_class7.prototype.__init126.call(this);_class7.prototype.__init127.call(this);_class7.prototype.__init128.call(this);_class7.prototype.__init129.call(this);_class7.prototype.__init130.call(this);_class7.prototype.__init131.call(this);_class7.prototype.__init132.call(this);_class7.prototype.__init133.call(this);_class7.prototype.__init134.call(this);_class7.prototype.__init135.call(this);
     this.canvas = canvas;
     this.debugA11y = _nullishCoalesce(options.debugA11y, () => ( false));
     this.disableWindowResize = _nullishCoalesce(options.disableWindowResize, () => ( false));
@@ -2481,7 +2486,7 @@ var Scene = (_class7 = class _Scene {
       this.forcedColorsChangeHandler = () => this.markDirty();
       _optionalChain([this, 'access', _45 => _45.forcedColorsQuery, 'access', _46 => _46.addEventListener, 'optionalCall', _47 => _47("change", this.forcedColorsChangeHandler)]);
     }
-    this.root = new class RootEntity extends _chunkDUYB4GX4js.Entity {
+    this.root = new class RootEntity extends _chunkIA3KW4CGjs.Entity {
       isPointInside() {
         return false;
       }
@@ -2490,7 +2495,7 @@ var Scene = (_class7 = class _Scene {
       }
     }("root");
     this.root._scene = this;
-    this.overlayRoot = new class OverlayRoot extends _chunkDUYB4GX4js.Entity {
+    this.overlayRoot = new class OverlayRoot extends _chunkIA3KW4CGjs.Entity {
       isPointInside() {
         return false;
       }
@@ -2856,7 +2861,7 @@ var Scene = (_class7 = class _Scene {
       }
       if (this.hoveredA11yElements.has(el)) {
         this.hoveredA11yElements.delete(el);
-        node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("pointerleave", node, void 0, false));
+        node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointerleave", node, void 0, false));
       }
       this.preserveFocusOnRemoval(el);
       el.remove();
@@ -3156,8 +3161,65 @@ var Scene = (_class7 = class _Scene {
    * Only meaningful in `onDemand` {@link renderMode}: call it after mutating
    * entity state outside of {@link Entity.animate} so the change is rendered.
    */
-  markDirty() {
+  markDirty(source) {
     this.dirty = true;
+    if (this._dirtyTracking && source) this.recordDirtyReason(source);
+  }
+  /**
+   * Record who marked the scene dirty and why.
+   *
+   * Kept separate from {@link markDirty} so the hot path is not a function call
+   * with a branch — V8 inlines the one-field version reliably.
+   */
+  recordDirtyReason(source) {
+    const key = `${_nullishCoalesce(source.entity, () => ( "scene"))}:${source.reason}${source.property ? `.${source.property}` : ""}`;
+    const existing = this._dirtyReasons.get(key);
+    if (existing) {
+      existing.count++;
+      existing.lastFrame = this.currentFrame;
+      return;
+    }
+    if (this._dirtyReasons.size >= _Scene.MAX_DIRTY_REASONS) {
+      const oldest = this._dirtyReasons.keys().next().value;
+      if (oldest !== void 0) this._dirtyReasons.delete(oldest);
+    }
+    this._dirtyReasons.set(key, {
+      entity: source.entity,
+      reason: source.reason,
+      property: source.property,
+      count: 1,
+      firstFrame: this.currentFrame,
+      lastFrame: this.currentFrame
+    });
+  }
+  /**
+   * Start or stop recording dirty attributions.
+   *
+   * Off by default. `renderMode: 'onDemand'` silently degrades to always-on when
+   * something marks the scene dirty every frame, and until now there was no way
+   * to find out what — `dirty === true` said nothing about the cause. Enable
+   * this, run the scene, then read {@link dirtyReasons}.
+   */
+  setDirtyTracking(enabled) {
+    this._dirtyTracking = enabled;
+    if (!enabled) this._dirtyReasons.clear();
+  }
+  /** Whether dirty attribution is currently being recorded. */
+  get dirtyTracking() {
+    return this._dirtyTracking;
+  }
+  /**
+   * Recorded dirty attributions, most frequent first.
+   *
+   * `count` is what matters for the `onDemand` diagnosis: a reason appearing once
+   * per frame over hundreds of frames is the thing keeping the scene awake.
+   */
+  get dirtyReasons() {
+    return [...this._dirtyReasons.values()].sort((a, b) => b.count - a.count);
+  }
+  /** Drop recorded attributions, keeping tracking enabled. */
+  clearDirtyReasons() {
+    this._dirtyReasons.clear();
   }
   /**
    * Live frame telemetry for profilers and devtools overlays. All timings are
@@ -3266,20 +3328,20 @@ var Scene = (_class7 = class _Scene {
           el.style.background = "transparent";
         }
         el.addEventListener("click", (e) => {
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("click", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("click", node, e));
         });
         el.addEventListener("dblclick", (e) => {
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("dblclick", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.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, _chunkDUYB4GX4js.VectoJSEvent)("hover", node, e, false));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.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, _chunkDUYB4GX4js.VectoJSEvent)("pointerleave", node, e, false));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointerleave", node, e, false));
         });
         const capEl = el;
         const releasePointer = (event) => {
@@ -3295,32 +3357,32 @@ var Scene = (_class7 = class _Scene {
         };
         el.addEventListener("pointerdown", (e) => {
           if (typeof capEl.setPointerCapture === "function") capEl.setPointerCapture(e.pointerId);
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("pointerdown", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointerdown", node, e));
         });
         el.addEventListener("pointerup", (e) => {
           releasePointer(e);
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("pointerup", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointerup", node, e));
         });
         el.addEventListener("pointercancel", (e) => {
           releasePointer(e);
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("pointercancel", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointercancel", node, e));
         });
         el.addEventListener(
           "pointermove",
-          (e) => node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("pointermove", node, e))
+          (e) => node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("pointermove", node, e))
         );
         el.addEventListener(
           "wheel",
           (e) => {
-            node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("wheel", node, e));
+            node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("wheel", node, e));
           },
           { passive: false }
         );
         el.addEventListener("keydown", (e) => {
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("keydown", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("keydown", node, e));
         });
         el.addEventListener("keyup", (e) => {
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("keyup", node, e));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("keyup", node, e));
         });
         if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
           const input = el;
@@ -3386,7 +3448,7 @@ var Scene = (_class7 = class _Scene {
           el.addEventListener("keydown", (e) => {
             if (e.key === "Enter" || e.key === " ") {
               e.preventDefault();
-              node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("click", node, e));
+              node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("click", node, e));
             }
           });
         }
@@ -3477,11 +3539,17 @@ var Scene = (_class7 = class _Scene {
       this.syncOptionalAttribute(el, "aria-modal", attrs.ariaModal);
       this.syncOptionalAttribute(el, "aria-labelledby", attrs.labelledby);
       this.syncOptionalAttribute(el, "aria-describedby", attrs.describedby);
-      this.syncOptionalAttribute(
-        el,
-        "aria-required",
-        attrs.required === void 0 ? void 0 : String(attrs.required)
-      );
+      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+        const wantRequired = attrs.required === true;
+        if (el.required !== wantRequired) el.required = wantRequired;
+        this.syncOptionalAttribute(el, "aria-required", void 0);
+      } else {
+        this.syncOptionalAttribute(
+          el,
+          "aria-required",
+          attrs.required === void 0 ? void 0 : String(attrs.required)
+        );
+      }
       this.syncOptionalAttribute(
         el,
         "aria-invalid",
@@ -3501,8 +3569,10 @@ var Scene = (_class7 = class _Scene {
               el._lastSyncedValue = attrs.value;
             }
           }
-        } else {
+        } else if (RANGE_VALUE_ROLES.has(_nullishCoalesce(attrs.role, () => ( "")))) {
           this.syncOptionalAttribute(el, "aria-valuenow", attrs.value);
+        } else {
+          this.syncOptionalAttribute(el, "aria-valuenow", void 0);
         }
       } else if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement)) {
         this.syncOptionalAttribute(el, "aria-valuenow", void 0);
@@ -3638,7 +3708,7 @@ var Scene = (_class7 = class _Scene {
       el.addEventListener(
         "wheel",
         (e2) => {
-          node.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)("wheel", node, e2));
+          node.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)("wheel", node, e2));
         },
         { passive: false }
       );
@@ -4441,7 +4511,7 @@ var Scene = (_class7 = class _Scene {
     let walkHadAnimation = false;
     let walkHadInteractive = false;
     const runUpdate = (node) => {
-      const overridesUpdate = node.update !== _chunkDUYB4GX4js.Entity.prototype.update;
+      const overridesUpdate = node.update !== _chunkIA3KW4CGjs.Entity.prototype.update;
       let pending = node.hasPendingAnimations();
       if (pending || overridesUpdate) {
         node.update(dt, time);
@@ -4450,7 +4520,7 @@ var Scene = (_class7 = class _Scene {
       if (pending) walkHadAnimation = true;
       if (!walkHadInteractive && node.interactive) walkHadInteractive = true;
       if (this._devActive && this._devFrameCount % 120 === 0) {
-        if (overridesUpdate && node.hasPendingAnimations === _chunkDUYB4GX4js.Entity.prototype.hasPendingAnimations) {
+        if (overridesUpdate && node.hasPendingAnimations === _chunkIA3KW4CGjs.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 drop the animation to ~2fps. Override hasPendingAnimations() to return true while motion is in flight.`
           );
@@ -4882,7 +4952,7 @@ var Scene = (_class7 = class _Scene {
     }
     return true;
   }
-}, _class7.__initStatic(), _class7.__initStatic2(), _class7.__initStatic3(), _class7.__initStatic4(), _class7);
+}, _class7.__initStatic(), _class7.__initStatic2(), _class7.__initStatic3(), _class7.__initStatic4(), _class7.__initStatic5(), _class7);
 function intersectBounds(a, b) {
   const x = Math.max(a.x, b.x);
   const y = Math.max(a.y, b.y);
@@ -4909,20 +4979,20 @@ function defaultMeasurer() {
   if (sharedMeasurer === void 0) sharedMeasurer = _layout.createCanvasMeasurer.call(void 0, "sans-serif");
   return sharedMeasurer;
 }
-var TextEntity = (_class8 = class extends _chunkDUYB4GX4js.Entity {
+var TextEntity = (_class8 = class extends _chunkIA3KW4CGjs.Entity {
   
   
   
   
-  __init134() {this.nodes = []}
+  __init136() {this.nodes = []}
   
-  __init135() {this.fillStyle = "#94a3b8"}
-  __init136() {this.strokeStyle = null}
-  __init137() {this.hoveredFillStyle = "#ffffff"}
-  __init138() {this.lineWidth = 1}
-  __init139() {this.isHovered = false}
+  __init137() {this.fillStyle = "#94a3b8"}
+  __init138() {this.strokeStyle = null}
+  __init139() {this.hoveredFillStyle = "#ffffff"}
+  __init140() {this.lineWidth = 1}
+  __init141() {this.isHovered = false}
   constructor(text, atlas, maxWidth, fontSize = 24) {
-    super();_class8.prototype.__init134.call(this);_class8.prototype.__init135.call(this);_class8.prototype.__init136.call(this);_class8.prototype.__init137.call(this);_class8.prototype.__init138.call(this);_class8.prototype.__init139.call(this);;
+    super();_class8.prototype.__init136.call(this);_class8.prototype.__init137.call(this);_class8.prototype.__init138.call(this);_class8.prototype.__init139.call(this);_class8.prototype.__init140.call(this);_class8.prototype.__init141.call(this);;
     this.text = text;
     this.atlas = atlas;
     this.fontSize = fontSize;
@@ -5035,17 +5105,17 @@ var TextEntity = (_class8 = class extends _chunkDUYB4GX4js.Entity {
 }, _class8);
 
 // src/components/GridTextEntity.ts
-var GridTextEntity = (_class9 = class extends _chunkDUYB4GX4js.Entity {
+var GridTextEntity = (_class9 = class extends _chunkIA3KW4CGjs.Entity {
   
-  __init140() {this.fillStyle = "#ffffff"}
-  __init141() {this.grid = []}
+  __init142() {this.fillStyle = "#ffffff"}
+  __init143() {this.grid = []}
   // Array of rows
-  __init142() {this.cols = 0}
-  __init143() {this.rows = 0}
+  __init144() {this.cols = 0}
+  __init145() {this.rows = 0}
   
   
   constructor(_atlas, fontSize = 10) {
-    super();_class9.prototype.__init140.call(this);_class9.prototype.__init141.call(this);_class9.prototype.__init142.call(this);_class9.prototype.__init143.call(this);;
+    super();_class9.prototype.__init142.call(this);_class9.prototype.__init143.call(this);_class9.prototype.__init144.call(this);_class9.prototype.__init145.call(this);;
     this.fontSize = fontSize;
     this.charWidth = fontSize * 1;
     this.charHeight = fontSize * 1.1;
@@ -5129,7 +5199,7 @@ function distSqToSegment(px, py, x1, y1, x2, y2) {
   const ey = py - cy;
   return ex * ex + ey * ey;
 }
-var SplineEntity = (_class10 = class extends _chunkDUYB4GX4js.Entity {
+var SplineEntity = (_class10 = class extends _chunkIA3KW4CGjs.Entity {
   
   
   
@@ -5137,23 +5207,23 @@ var SplineEntity = (_class10 = class extends _chunkDUYB4GX4js.Entity {
   
   
   
-  __init144() {this.offscreen = null}
-  __init145() {this.baked = false}
+  __init146() {this.offscreen = null}
+  __init147() {this.baked = false}
   /** Logical (CSS-pixel) size of the baked bitmap — the blit destination size. */
-  __init146() {this.bakedWidth = 0}
-  __init147() {this.bakedHeight = 0}
+  __init148() {this.bakedWidth = 0}
+  __init149() {this.bakedHeight = 0}
   /** Gradient strokes can't be baked to a solid-color bitmap; they render per-frame. */
   
   /** Lazily-flattened polylines (one Float32Array of [x,y,...] per segment) for hit-testing. */
-  __init148() {this.polylines = null}
+  __init150() {this.polylines = null}
   /**
    * When `true`, the renderer draws a rounded-rect outline of the entity's
    * local bounds after painting the curves. Useful for drag feedback and
    * debugging hit areas. Defaults to `false`.
    */
-  __init149() {this.showBounds = false}
+  __init151() {this.showBounds = false}
   constructor(doc, opts = {}) {
-    super();_class10.prototype.__init144.call(this);_class10.prototype.__init145.call(this);_class10.prototype.__init146.call(this);_class10.prototype.__init147.call(this);_class10.prototype.__init148.call(this);_class10.prototype.__init149.call(this);;
+    super();_class10.prototype.__init146.call(this);_class10.prototype.__init147.call(this);_class10.prototype.__init148.call(this);_class10.prototype.__init149.call(this);_class10.prototype.__init150.call(this);_class10.prototype.__init151.call(this);;
     this.doc = doc;
     this.lineWidth = _nullishCoalesce(opts.lineWidth, () => ( 2));
     this.cache = _nullishCoalesce(opts.cache, () => ( true));
@@ -5404,7 +5474,7 @@ async function loadSpline(url) {
 }
 
 // src/components/Rect.ts
-var Rect = class extends _chunkDUYB4GX4js.Entity {
+var Rect = class extends _chunkIA3KW4CGjs.Entity {
   
   
   
@@ -5453,7 +5523,7 @@ var Rect = class extends _chunkDUYB4GX4js.Entity {
 };
 
 // src/components/Circle.ts
-var Circle = class extends _chunkDUYB4GX4js.Entity {
+var Circle = class extends _chunkIA3KW4CGjs.Entity {
   
   
   
@@ -5513,7 +5583,7 @@ var Circle = class extends _chunkDUYB4GX4js.Entity {
 };
 
 // src/components/Group.ts
-var Group = class extends _chunkDUYB4GX4js.Entity {
+var Group = class extends _chunkIA3KW4CGjs.Entity {
   constructor(...children) {
     super();
     if (children.length > 0) this.add(...children);
@@ -5532,21 +5602,21 @@ var _math = require('@vectojs/math'); _createStarExport(_math);
 
 
 // src/tree/DOMPortalEntity.ts
-var DOMPortalEntity = (_class11 = class extends _chunkDUYB4GX4js.Entity {
+var DOMPortalEntity = (_class11 = class extends _chunkIA3KW4CGjs.Entity {
   
-  __init150() {this.isDOMPortal = true}
-  __init151() {this.domListeners = []}
-  __init152() {this.resizeObserver = null}
-  __init153() {this.domBound = false}
-  __init154() {this.cachedWidth = 100}
-  __init155() {this.cachedHeight = 100}
-  __init156() {this.lastWidth = ""}
-  __init157() {this.lastHeight = ""}
-  __init158() {this.lastTransform = ""}
-  __init159() {this.lastZIndex = ""}
-  __init160() {this.lastOpacity = ""}
+  __init152() {this.isDOMPortal = true}
+  __init153() {this.domListeners = []}
+  __init154() {this.resizeObserver = null}
+  __init155() {this.domBound = false}
+  __init156() {this.cachedWidth = 100}
+  __init157() {this.cachedHeight = 100}
+  __init158() {this.lastWidth = ""}
+  __init159() {this.lastHeight = ""}
+  __init160() {this.lastTransform = ""}
+  __init161() {this.lastZIndex = ""}
+  __init162() {this.lastOpacity = ""}
   constructor(domElement, width, height, id) {
-    super(id);_class11.prototype.__init150.call(this);_class11.prototype.__init151.call(this);_class11.prototype.__init152.call(this);_class11.prototype.__init153.call(this);_class11.prototype.__init154.call(this);_class11.prototype.__init155.call(this);_class11.prototype.__init156.call(this);_class11.prototype.__init157.call(this);_class11.prototype.__init158.call(this);_class11.prototype.__init159.call(this);_class11.prototype.__init160.call(this);;
+    super(id);_class11.prototype.__init152.call(this);_class11.prototype.__init153.call(this);_class11.prototype.__init154.call(this);_class11.prototype.__init155.call(this);_class11.prototype.__init156.call(this);_class11.prototype.__init157.call(this);_class11.prototype.__init158.call(this);_class11.prototype.__init159.call(this);_class11.prototype.__init160.call(this);_class11.prototype.__init161.call(this);_class11.prototype.__init162.call(this);;
     this.domElement = domElement;
     this.width = _nullishCoalesce(width, () => ( 0));
     this.height = _nullishCoalesce(height, () => ( 0));
@@ -5588,7 +5658,7 @@ var DOMPortalEntity = (_class11 = class extends _chunkDUYB4GX4js.Entity {
     ];
     for (const type of events) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)(type, this, e));
+        this.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)(type, this, e));
       };
       this.domElement.addEventListener(type, handler);
       this.domListeners.push({ type, handler, capture: false });
@@ -5599,7 +5669,7 @@ var DOMPortalEntity = (_class11 = class extends _chunkDUYB4GX4js.Entity {
     ];
     for (const { native, vecto } of hoverEvents) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)(vecto, this, e, false));
+        this.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)(vecto, this, e, false));
       };
       this.domElement.addEventListener(native, handler);
       this.domListeners.push({ type: native, handler, capture: false });
@@ -5607,7 +5677,7 @@ var DOMPortalEntity = (_class11 = class extends _chunkDUYB4GX4js.Entity {
     const focusEvents = ["focus", "blur"];
     for (const type of focusEvents) {
       const handler = (e) => {
-        this.dispatchEvent(new (0, _chunkDUYB4GX4js.VectoJSEvent)(type, this, e, true));
+        this.dispatchEvent(new (0, _chunkIA3KW4CGjs.VectoJSEvent)(type, this, e, true));
       };
       this.domElement.addEventListener(type, handler, true);
       this.domListeners.push({ type, handler, capture: true });
@@ -5694,4 +5764,4 @@ Scene.registerWebGPUParticleSystemManager(_chunkL4SWVP2Hjs.WebGPUParticleSystemM
 
 
 
-exports.CanvasRenderer = _chunkL4SWVP2Hjs.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkDUYB4GX4js.Entity; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkDUYB4GX4js.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.SVGEntity = _chunkDUYB4GX4js.SVGEntity; exports.SVGRenderer = _chunkL4SWVP2Hjs.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkL4SWVP2Hjs.TextRasterCache; exports.VectoJSEvent = _chunkDUYB4GX4js.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkL4SWVP2Hjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkL4SWVP2Hjs.createWebGLPointRenderer; exports.isSafeUrl = _chunkL4SWVP2Hjs.isSafeUrl; exports.loadSpline = loadSpline; exports.parseColorToRGBA = _chunkL4SWVP2Hjs.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkL4SWVP2Hjs.sanitizeUrl;
+exports.CanvasRenderer = _chunkL4SWVP2Hjs.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkIA3KW4CGjs.Entity; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkIA3KW4CGjs.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.SVGEntity = _chunkIA3KW4CGjs.SVGEntity; exports.SVGRenderer = _chunkL4SWVP2Hjs.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkL4SWVP2Hjs.TextRasterCache; exports.VectoJSEvent = _chunkIA3KW4CGjs.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkL4SWVP2Hjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkL4SWVP2Hjs.createWebGLPointRenderer; exports.isSafeUrl = _chunkL4SWVP2Hjs.isSafeUrl; exports.loadSpline = loadSpline; exports.parseColorToRGBA = _chunkL4SWVP2Hjs.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkL4SWVP2Hjs.sanitizeUrl;

package/dist/index.mjs

@@ -13,7 +13,7 @@ import {
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-AQTO7OSU.mjs";
+} from "./chunk-XWBVBXFZ.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1106,10 +1106,10 @@ function cacheKey(source) {
   if (source instanceof URL) return source.href;
   return null;
 }
-async function compile(source) {
-  if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
-    return new WebAssembly.Module(source);
-  }
+function compileBytes(bytes) {
+  return new WebAssembly.Module(bytes);
+}
+async function compileRemote(source) {
   const response = typeof source === "string" || source instanceof URL ? await fetch(String(source)) : await source;
   if (typeof WebAssembly.compileStreaming === "function") {
     const buffered = response.clone();
@@ -1134,7 +1134,7 @@ async function loadCoreWasmModule(source) {
       }
     }
   }
-  const pending = compile(source);
+  const pending = source instanceof ArrayBuffer || ArrayBuffer.isView(source) ? Promise.resolve().then(() => compileBytes(source)) : compileRemote(source);
   if (key !== null) moduleCache.set(key, pending);
   try {
     return await pending;
@@ -1190,6 +1190,7 @@ async function loadCoreWasmRuntime(source) {
 
 // src/tree/Scene.ts
 import { clearCssLineBoxMetrics, cssLineBoxBaseline } from "@vectojs/text";
+var RANGE_VALUE_ROLES = /* @__PURE__ */ new Set(["slider", "spinbutton", "progressbar", "scrollbar", "meter"]);
 var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
   "button",
   "switch",
@@ -1535,6 +1536,10 @@ var Scene = class _Scene {
    *   event-driven UIs where idle frames should cost ~0.
    */
   renderMode = "always";
+  /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
+  static MAX_DIRTY_REASONS = 200;
+  _dirtyTracking = false;
+  _dirtyReasons = /* @__PURE__ */ new Map();
   dirty = true;
   /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
   autoThrottle = true;
@@ -3155,8 +3160,65 @@ var Scene = class _Scene {
    * Only meaningful in `onDemand` {@link renderMode}: call it after mutating
    * entity state outside of {@link Entity.animate} so the change is rendered.
    */
-  markDirty() {
+  markDirty(source) {
     this.dirty = true;
+    if (this._dirtyTracking && source) this.recordDirtyReason(source);
+  }
+  /**
+   * Record who marked the scene dirty and why.
+   *
+   * Kept separate from {@link markDirty} so the hot path is not a function call
+   * with a branch — V8 inlines the one-field version reliably.
+   */
+  recordDirtyReason(source) {
+    const key = `${source.entity ?? "scene"}:${source.reason}${source.property ? `.${source.property}` : ""}`;
+    const existing = this._dirtyReasons.get(key);
+    if (existing) {
+      existing.count++;
+      existing.lastFrame = this.currentFrame;
+      return;
+    }
+    if (this._dirtyReasons.size >= _Scene.MAX_DIRTY_REASONS) {
+      const oldest = this._dirtyReasons.keys().next().value;
+      if (oldest !== void 0) this._dirtyReasons.delete(oldest);
+    }
+    this._dirtyReasons.set(key, {
+      entity: source.entity,
+      reason: source.reason,
+      property: source.property,
+      count: 1,
+      firstFrame: this.currentFrame,
+      lastFrame: this.currentFrame
+    });
+  }
+  /**
+   * Start or stop recording dirty attributions.
+   *
+   * Off by default. `renderMode: 'onDemand'` silently degrades to always-on when
+   * something marks the scene dirty every frame, and until now there was no way
+   * to find out what — `dirty === true` said nothing about the cause. Enable
+   * this, run the scene, then read {@link dirtyReasons}.
+   */
+  setDirtyTracking(enabled) {
+    this._dirtyTracking = enabled;
+    if (!enabled) this._dirtyReasons.clear();
+  }
+  /** Whether dirty attribution is currently being recorded. */
+  get dirtyTracking() {
+    return this._dirtyTracking;
+  }
+  /**
+   * Recorded dirty attributions, most frequent first.
+   *
+   * `count` is what matters for the `onDemand` diagnosis: a reason appearing once
+   * per frame over hundreds of frames is the thing keeping the scene awake.
+   */
+  get dirtyReasons() {
+    return [...this._dirtyReasons.values()].sort((a, b) => b.count - a.count);
+  }
+  /** Drop recorded attributions, keeping tracking enabled. */
+  clearDirtyReasons() {
+    this._dirtyReasons.clear();
   }
   /**
    * Live frame telemetry for profilers and devtools overlays. All timings are
@@ -3476,11 +3538,17 @@ var Scene = class _Scene {
       this.syncOptionalAttribute(el, "aria-modal", attrs.ariaModal);
       this.syncOptionalAttribute(el, "aria-labelledby", attrs.labelledby);
       this.syncOptionalAttribute(el, "aria-describedby", attrs.describedby);
-      this.syncOptionalAttribute(
-        el,
-        "aria-required",
-        attrs.required === void 0 ? void 0 : String(attrs.required)
-      );
+      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+        const wantRequired = attrs.required === true;
+        if (el.required !== wantRequired) el.required = wantRequired;
+        this.syncOptionalAttribute(el, "aria-required", void 0);
+      } else {
+        this.syncOptionalAttribute(
+          el,
+          "aria-required",
+          attrs.required === void 0 ? void 0 : String(attrs.required)
+        );
+      }
       this.syncOptionalAttribute(
         el,
         "aria-invalid",
@@ -3500,8 +3568,10 @@ var Scene = class _Scene {
               el._lastSyncedValue = attrs.value;
             }
           }
-        } else {
+        } else if (RANGE_VALUE_ROLES.has(attrs.role ?? "")) {
           this.syncOptionalAttribute(el, "aria-valuenow", attrs.value);
+        } else {
+          this.syncOptionalAttribute(el, "aria-valuenow", void 0);
         }
       } else if (!(el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement)) {
         this.syncOptionalAttribute(el, "aria-valuenow", void 0);

package/dist/text.js

@@ -2,11 +2,11 @@
 
 
 
-var _chunkDUYB4GX4js = require('./chunk-DUYB4GX4.js');
+var _chunkIA3KW4CGjs = require('./chunk-IA3KW4CG.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkDUYB4GX4js.MSDFTextEntity; exports.SVGEntity = _chunkDUYB4GX4js.SVGEntity;
+exports.MSDFTextEntity = _chunkIA3KW4CGjs.MSDFTextEntity; exports.SVGEntity = _chunkIA3KW4CGjs.SVGEntity;

package/dist/text.mjs

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

package/dist/tree/Scene.d.ts

@@ -17,6 +17,31 @@ import { type CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
 import { type AnimModuleSource, type AnimBackend } from '../wasm/anim-backend';
 import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particle-backend';
+/**
+ * Who marked the scene dirty, and why.
+ *
+ * Every field is optional except `reason` so a call site can be as specific as it
+ * cheaply can — an entity id costs nothing to pass, a property name is often
+ * already in scope.
+ */
+export interface DirtySource {
+    /** Entity id responsible, when one is. Omitted for scene-level invalidation. */
+    entity?: string;
+    /** Short, stable category — e.g. `'text-changed'`, `'animation'`, `'resize'`. */
+    reason: string;
+    /** Property that changed, when the reason alone is ambiguous. */
+    property?: string;
+}
+/** An aggregated dirty attribution. */
+export interface DirtyReasonEntry {
+    entity?: string;
+    reason: string;
+    property?: string;
+    /** How many times this exact attribution was recorded. */
+    count: number;
+    firstFrame: number;
+    lastFrame: number;
+}
 /**
  * Options for {@link Scene}.
  */
@@ -203,6 +228,10 @@ export declare class Scene {
      *   event-driven UIs where idle frames should cost ~0.
      */
     renderMode: 'always' | 'onDemand';
+    /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
+    private static readonly MAX_DIRTY_REASONS;
+    private _dirtyTracking;
+    private _dirtyReasons;
     private dirty;
     /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
     autoThrottle: boolean;
@@ -845,7 +874,34 @@ export declare class Scene {
      * Only meaningful in `onDemand` {@link renderMode}: call it after mutating
      * entity state outside of {@link Entity.animate} so the change is rendered.
      */
-    markDirty(): void;
+    markDirty(source?: DirtySource): void;
+    /**
+     * Record who marked the scene dirty and why.
+     *
+     * Kept separate from {@link markDirty} so the hot path is not a function call
+     * with a branch — V8 inlines the one-field version reliably.
+     */
+    private recordDirtyReason;
+    /**
+     * Start or stop recording dirty attributions.
+     *
+     * Off by default. `renderMode: 'onDemand'` silently degrades to always-on when
+     * something marks the scene dirty every frame, and until now there was no way
+     * to find out what — `dirty === true` said nothing about the cause. Enable
+     * this, run the scene, then read {@link dirtyReasons}.
+     */
+    setDirtyTracking(enabled: boolean): void;
+    /** Whether dirty attribution is currently being recorded. */
+    get dirtyTracking(): boolean;
+    /**
+     * Recorded dirty attributions, most frequent first.
+     *
+     * `count` is what matters for the `onDemand` diagnosis: a reason appearing once
+     * per frame over hundreds of frames is the thing keeping the scene awake.
+     */
+    get dirtyReasons(): DirtyReasonEntry[];
+    /** Drop recorded attributions, keeping tracking enabled. */
+    clearDirtyReasons(): void;
     /**
      * Live frame telemetry for profilers and devtools overlays. All timings are
      * measured on the `requestAnimationFrame` loop; a scene driven only by

package/package.json

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