@vectojs/core 1.12.0 → 1.13.0

package/dist/index.js

@@ -667,16 +667,29 @@ var Scene = (_class2 = class _Scene {
   __init10() {this.dirty = true}
   /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
   __init11() {this.autoThrottle = true}
+  // --- Frame telemetry (read via `frameStats`) ---------------------------
+  /** Wall-clock ms spent inside the last `render()` call. */
+  __init12() {this._lastFrameMs = 0}
+  /** Rolling exponential average of rendered-frame intervals, in ms. */
+  __init13() {this._avgFrameIntervalMs = 0}
+  /** dt (ms) handed to the last rendered frame. */
+  __init14() {this._lastDt = 0}
+  /** Count of frames actually rendered since the loop started. */
+  __init15() {this._renderedFrames = 0}
+  /** Count of rAF ticks skipped (idle / capped) since the loop started. */
+  __init16() {this._skippedFrames = 0}
+  /** `time` of the previous *rendered* frame, for interval measurement. */
+  __init17() {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}.
    */
-  __init12() {this.maxFPS = 60}
+  __init18() {this.maxFPS = 60}
   /** Whether the OS prefers-reduced-motion setting auto-caps the loop. */
-  __init13() {this.respectReducedMotion = true}
+  __init19() {this.respectReducedMotion = true}
   /** Cached media-query list; `.matches` is read live each frame. */
-  __init14() {this.reducedMotionQuery = null}
+  __init20() {this.reducedMotionQuery = 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]);
@@ -685,95 +698,95 @@ var Scene = (_class2 = class _Scene {
    * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
    * frame. See {@link SceneOptions.a11ySyncInterval}.
    */
-  __init15() {this.a11ySyncInterval = 0}
+  __init21() {this.a11ySyncInterval = 0}
   /** Timestamp of the last a11y sync, for throttling. */
-  __init16() {this.lastA11ySync = -Infinity}
+  __init22() {this.lastA11ySync = -Infinity}
   /** True if we skipped an a11y sync during animation and need to sync when at rest. */
-  __init17() {this.a11yPendingSyncAfterAnimation = false}
+  __init23() {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.
   
-  __init18() {this.a11yElements = /* @__PURE__ */ new Map()}
+  __init24() {this.a11yElements = /* @__PURE__ */ new Map()}
   /** DOM nodes mirroring static text content, keyed by entity id. */
-  __init19() {this.contentElements = /* @__PURE__ */ new Map()}
+  __init25() {this.contentElements = /* @__PURE__ */ new Map()}
   /** Pending cold font-calibration frame per projected grid entity. */
-  __init20() {this.contentGridCalibrationFrames = /* @__PURE__ */ new Map()}
+  __init26() {this.contentGridCalibrationFrames = /* @__PURE__ */ new Map()}
   /** Detached, untransformed font probes used by the cold calibration pass. */
-  __init21() {this.contentGridCalibrationProbes = /* @__PURE__ */ new Map()}
+  __init27() {this.contentGridCalibrationProbes = /* @__PURE__ */ new Map()}
   /** Invalidates grid font calibration after browser font availability changes. */
-  __init22() {this.contentFontEpoch = 0}
+  __init28() {this.contentFontEpoch = 0}
   /** Cached Canvas-to-client scale for the current font/viewport epoch. */
-  __init23() {this.contentMetricScaleEpoch = -1}
-  __init24() {this.contentMetricScaleX = 1}
-  __init25() {this.contentProjectionEnabled = true}
+  __init29() {this.contentMetricScaleEpoch = -1}
+  __init30() {this.contentMetricScaleX = 1}
+  __init31() {this.contentProjectionEnabled = true}
   /**
    * 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.
    */
-  __init26() {this.blankRegionSelectionDrag = false}
-  __init27() {this.contentSelectionAnchor = null}
-  __init28() {this.contentSelectionEndListener = null}
+  __init32() {this.blankRegionSelectionDrag = false}
+  __init33() {this.contentSelectionAnchor = null}
+  __init34() {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.
-  __init29() {this.frameHadAnimation = true}
-  __init30() {this.frameHadInteractive = true}
+  __init35() {this.frameHadAnimation = true}
+  __init36() {this.frameHadInteractive = true}
   
-  __init31() {this.focusedA11yElement = null}
-  __init32() {this.caretBlinkTimer = null}
-  __init33() {this.a11yNeedsReorder = true}
-  __init34() {this.portalRoot = null}
-  __init35() {this.fullViewportElements = []}
-  __init36() {this.normalElements = []}
-  __init37() {this.activeIds = /* @__PURE__ */ new Set()}
-  __init38() {this.activePortalsThisFrame = /* @__PURE__ */ new Set()}
-  __init39() {this.activePortalsPrevFrame = /* @__PURE__ */ new Set()}
-  __init40() {this.portalEntities = /* @__PURE__ */ new Map()}
-  __init41() {this.renderOrderCounter = 0}
+  __init37() {this.focusedA11yElement = null}
+  __init38() {this.caretBlinkTimer = null}
+  __init39() {this.a11yNeedsReorder = true}
+  __init40() {this.portalRoot = null}
+  __init41() {this.fullViewportElements = []}
+  __init42() {this.normalElements = []}
+  __init43() {this.activeIds = /* @__PURE__ */ new Set()}
+  __init44() {this.activePortalsThisFrame = /* @__PURE__ */ new Set()}
+  __init45() {this.activePortalsPrevFrame = /* @__PURE__ */ new Set()}
+  __init46() {this.portalEntities = /* @__PURE__ */ new Map()}
+  __init47() {this.renderOrderCounter = 0}
   /**
    * Authoritative paint order for semantic nodes discovered during the main
    * render. A node may not have a DOM projection until the following a11y
    * sync, so retaining the order prevents a newly opened overlay from spending
    * its first frame below previously projected controls.
    */
-  __init42() {this.a11yRenderOrders = /* @__PURE__ */ new Map()}
+  __init48() {this.a11yRenderOrders = /* @__PURE__ */ new Map()}
   // Optional WebGL point-cloud layer (see SceneOptions.pointBackend).
-  __init43() {this.pointRenderer = null}
-  __init44() {this.glCanvas = null}
+  __init49() {this.pointRenderer = null}
+  __init50() {this.glCanvas = null}
   
   
   
-  __init45() {this.disableWindowResize = false}
+  __init51() {this.disableWindowResize = false}
   /** See {@link SceneOptions.maxDPR}. `undefined` = uncapped (real DPR). */
   
   // WebGPU properties
-  __init46() {this.destroyed = false}
-  __init47() {this.device = null}
-  __init48() {this.deviceLost = false}
-  __init49() {this.particleBackend = "auto"}
-  __init50() {this._webgpuDisabled = false}
+  __init52() {this.destroyed = false}
+  __init53() {this.device = null}
+  __init54() {this.deviceLost = false}
+  __init55() {this.particleBackend = "auto"}
+  __init56() {this._webgpuDisabled = false}
   get webgpuDisabled() {
     return this._webgpuDisabled || this.particleBackend === "cpu";
   }
   set webgpuDisabled(value) {
     this._webgpuDisabled = value;
   }
-  __init51() {this.recoveryTimerId = null}
-  __init52() {this.manager = null}
-  __init53() {this.initializingWebGPU = false}
-  __init54() {this.gpuCanvas = null}
-  __init55() {this.gpuContext = null}
+  __init57() {this.recoveryTimerId = null}
+  __init58() {this.manager = null}
+  __init59() {this.initializingWebGPU = false}
+  __init60() {this.gpuCanvas = null}
+  __init61() {this.gpuContext = null}
   /** True while the GPU canvas holds a presented particle frame (needs clearing when they leave). */
-  __init56() {this.gpuHasContent = false}
-  __init57() {this.mouseX = -9999}
-  __init58() {this.mouseY = -9999}
-  __init59() {this.pointerMoveListener = null}
-  __init60() {this.pointerLeaveListener = null}
-  __init61() {this.hasWarnedZeroSize = false}
-  __init62() {this.fontLoadHandler = null}
+  __init62() {this.gpuHasContent = false}
+  __init63() {this.mouseX = -9999}
+  __init64() {this.mouseY = -9999}
+  __init65() {this.pointerMoveListener = null}
+  __init66() {this.pointerLeaveListener = null}
+  __init67() {this.hasWarnedZeroSize = false}
+  __init68() {this.fontLoadHandler = null}
   // ── Dev-mode warning infrastructure ──────────────────────────────
   //
   // Enable with `Scene.devMode = true` or by setting `globalThis.__DEV__`.
@@ -791,7 +804,7 @@ var Scene = (_class2 = class _Scene {
     return false;
   }
   
-  __init63() {this._devFrameCount = 0}
+  __init69() {this._devFrameCount = 0}
   _devWarn(message) {
     if (!this._devActive) return;
     console.warn(`[vectojs/dev] ${message}`);
@@ -835,7 +848,7 @@ var Scene = (_class2 = class _Scene {
     };
     walkProjections(this.root);
   }
-  constructor(canvas, options = {}) {;_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);_class2.prototype.__init42.call(this);_class2.prototype.__init43.call(this);_class2.prototype.__init44.call(this);_class2.prototype.__init45.call(this);_class2.prototype.__init46.call(this);_class2.prototype.__init47.call(this);_class2.prototype.__init48.call(this);_class2.prototype.__init49.call(this);_class2.prototype.__init50.call(this);_class2.prototype.__init51.call(this);_class2.prototype.__init52.call(this);_class2.prototype.__init53.call(this);_class2.prototype.__init54.call(this);_class2.prototype.__init55.call(this);_class2.prototype.__init56.call(this);_class2.prototype.__init57.call(this);_class2.prototype.__init58.call(this);_class2.prototype.__init59.call(this);_class2.prototype.__init60.call(this);_class2.prototype.__init61.call(this);_class2.prototype.__init62.call(this);_class2.prototype.__init63.call(this);
+  constructor(canvas, options = {}) {;_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);_class2.prototype.__init42.call(this);_class2.prototype.__init43.call(this);_class2.prototype.__init44.call(this);_class2.prototype.__init45.call(this);_class2.prototype.__init46.call(this);_class2.prototype.__init47.call(this);_class2.prototype.__init48.call(this);_class2.prototype.__init49.call(this);_class2.prototype.__init50.call(this);_class2.prototype.__init51.call(this);_class2.prototype.__init52.call(this);_class2.prototype.__init53.call(this);_class2.prototype.__init54.call(this);_class2.prototype.__init55.call(this);_class2.prototype.__init56.call(this);_class2.prototype.__init57.call(this);_class2.prototype.__init58.call(this);_class2.prototype.__init59.call(this);_class2.prototype.__init60.call(this);_class2.prototype.__init61.call(this);_class2.prototype.__init62.call(this);_class2.prototype.__init63.call(this);_class2.prototype.__init64.call(this);_class2.prototype.__init65.call(this);_class2.prototype.__init66.call(this);_class2.prototype.__init67.call(this);_class2.prototype.__init68.call(this);_class2.prototype.__init69.call(this);
     this.canvas = canvas;
     this.debugA11y = _nullishCoalesce(options.debugA11y, () => ( false));
     this.disableWindowResize = _nullishCoalesce(options.disableWindowResize, () => ( false));
@@ -1318,6 +1331,36 @@ var Scene = (_class2 = class _Scene {
   markDirty() {
     this.dirty = true;
   }
+  /**
+   * Live frame telemetry for profilers and devtools overlays. All timings are
+   * measured on the `requestAnimationFrame` loop; a scene driven only by
+   * {@link step} (e.g. deterministic video export) leaves these at their zero
+   * defaults.
+   *
+   * `fps` is derived from the interval between *rendered* frames, so idle
+   * `onDemand` scenes and frames skipped by the {@link maxFPS} cap or the
+   * static auto-throttle do not deflate it — it reports the cadence of actual
+   * redraws, not the raw rAF rate. `frameTimeMs` is the wall-clock cost of the
+   * last `render()` pass alone (excludes a11y/content-projection sync).
+   *
+   * The renderer always repaints the full canvas, so there is no partial
+   * dirty-rectangle to expose; `dirty` is the boolean redraw-pending flag and
+   * `pendingRedraw` reflects whether the next `onDemand` tick will actually
+   * render.
+   */
+  get frameStats() {
+    const interval = this._avgFrameIntervalMs;
+    return {
+      fps: interval > 0 ? Math.min(1e3 / interval, this.maxFPS > 0 ? this.maxFPS : 1e3 / interval) : 0,
+      frameTimeMs: this._lastFrameMs,
+      frameIntervalMs: interval,
+      dt: this._lastDt,
+      renderedFrames: this._renderedFrames,
+      skippedFrames: this._skippedFrames,
+      renderMode: this.renderMode,
+      dirty: this.dirty
+    };
+  }
   /** True when any node in the subtree has a pending animation. */
   /** True when any node in the subtree is interactive (drives a11y sync). */
   syncOptionalAttribute(element, name, value) {
@@ -2221,6 +2264,7 @@ var Scene = (_class2 = class _Scene {
       cap = Math.min(cap, 2);
     }
     if (cap > 0 && time - this.lastTime < 1e3 / cap - 1) {
+      this._skippedFrames++;
       this.scheduleFrame();
       return;
     }
@@ -2231,11 +2275,23 @@ var Scene = (_class2 = class _Scene {
     }
     this.lastTime = time;
     if (this.renderMode === "onDemand" && isIdle) {
+      this._skippedFrames++;
       this.scheduleFrame();
       return;
     }
     this.dirty = false;
+    const now = typeof performance !== "undefined" ? performance.now() : time;
+    if (this._lastRenderTick > 0) {
+      const interval = time - this._lastRenderTick;
+      if (interval > 0) {
+        this._avgFrameIntervalMs = this._avgFrameIntervalMs === 0 ? interval : this._avgFrameIntervalMs * 0.9 + interval * 0.1;
+      }
+    }
+    this._lastRenderTick = time;
+    this._lastDt = dt;
     this.render(this.renderer, dt, time);
+    this._lastFrameMs = (typeof performance !== "undefined" ? performance.now() : time) - now;
+    this._renderedFrames++;
     const hasActiveAnimation = this.frameHadAnimation;
     const hasInteractive = this.frameHadInteractive;
     const wantsContentSync = this.contentProjectionEnabled;
@@ -2762,15 +2818,15 @@ var TextEntity = (_class3 = class extends _chunk2Z23LTH3js.Entity {
   
   
   
-  __init64() {this.nodes = []}
+  __init70() {this.nodes = []}
   
-  __init65() {this.fillStyle = "#94a3b8"}
-  __init66() {this.strokeStyle = null}
-  __init67() {this.hoveredFillStyle = "#ffffff"}
-  __init68() {this.lineWidth = 1}
-  __init69() {this.isHovered = false}
+  __init71() {this.fillStyle = "#94a3b8"}
+  __init72() {this.strokeStyle = null}
+  __init73() {this.hoveredFillStyle = "#ffffff"}
+  __init74() {this.lineWidth = 1}
+  __init75() {this.isHovered = false}
   constructor(text, atlas, maxWidth, fontSize = 24) {
-    super();_class3.prototype.__init64.call(this);_class3.prototype.__init65.call(this);_class3.prototype.__init66.call(this);_class3.prototype.__init67.call(this);_class3.prototype.__init68.call(this);_class3.prototype.__init69.call(this);;
+    super();_class3.prototype.__init70.call(this);_class3.prototype.__init71.call(this);_class3.prototype.__init72.call(this);_class3.prototype.__init73.call(this);_class3.prototype.__init74.call(this);_class3.prototype.__init75.call(this);;
     this.text = text;
     this.atlas = atlas;
     this.fontSize = fontSize;
@@ -2885,15 +2941,15 @@ var TextEntity = (_class3 = class extends _chunk2Z23LTH3js.Entity {
 // src/components/GridTextEntity.ts
 var GridTextEntity = (_class4 = class extends _chunk2Z23LTH3js.Entity {
   
-  __init70() {this.fillStyle = "#ffffff"}
-  __init71() {this.grid = []}
+  __init76() {this.fillStyle = "#ffffff"}
+  __init77() {this.grid = []}
   // Array of rows
-  __init72() {this.cols = 0}
-  __init73() {this.rows = 0}
+  __init78() {this.cols = 0}
+  __init79() {this.rows = 0}
   
   
   constructor(_atlas, fontSize = 10) {
-    super();_class4.prototype.__init70.call(this);_class4.prototype.__init71.call(this);_class4.prototype.__init72.call(this);_class4.prototype.__init73.call(this);;
+    super();_class4.prototype.__init76.call(this);_class4.prototype.__init77.call(this);_class4.prototype.__init78.call(this);_class4.prototype.__init79.call(this);;
     this.fontSize = fontSize;
     this.charWidth = fontSize * 1;
     this.charHeight = fontSize * 1.1;
@@ -2985,23 +3041,23 @@ var SplineEntity = (_class5 = class extends _chunk2Z23LTH3js.Entity {
   
   
   
-  __init74() {this.offscreen = null}
-  __init75() {this.baked = false}
+  __init80() {this.offscreen = null}
+  __init81() {this.baked = false}
   /** Logical (CSS-pixel) size of the baked bitmap — the blit destination size. */
-  __init76() {this.bakedWidth = 0}
-  __init77() {this.bakedHeight = 0}
+  __init82() {this.bakedWidth = 0}
+  __init83() {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. */
-  __init78() {this.polylines = null}
+  __init84() {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`.
    */
-  __init79() {this.showBounds = false}
+  __init85() {this.showBounds = false}
   constructor(doc, opts = {}) {
-    super();_class5.prototype.__init74.call(this);_class5.prototype.__init75.call(this);_class5.prototype.__init76.call(this);_class5.prototype.__init77.call(this);_class5.prototype.__init78.call(this);_class5.prototype.__init79.call(this);;
+    super();_class5.prototype.__init80.call(this);_class5.prototype.__init81.call(this);_class5.prototype.__init82.call(this);_class5.prototype.__init83.call(this);_class5.prototype.__init84.call(this);_class5.prototype.__init85.call(this);;
     this.doc = doc;
     this.lineWidth = _nullishCoalesce(opts.lineWidth, () => ( 2));
     this.cache = _nullishCoalesce(opts.cache, () => ( true));
@@ -3376,9 +3432,9 @@ var Group = class extends _chunk2Z23LTH3js.Entity {
 // src/math/SpatialHashGrid.ts
 var SpatialHashGrid = (_class6 = class {
   
-  __init80() {this.grid = /* @__PURE__ */ new Map()}
-  __init81() {this.entityCells = /* @__PURE__ */ new Map()}
-  constructor(cellSize = 64) {;_class6.prototype.__init80.call(this);_class6.prototype.__init81.call(this);
+  __init86() {this.grid = /* @__PURE__ */ new Map()}
+  __init87() {this.entityCells = /* @__PURE__ */ new Map()}
+  constructor(cellSize = 64) {;_class6.prototype.__init86.call(this);_class6.prototype.__init87.call(this);
     this.cellSize = cellSize;
   }
   hash(cx, cy) {
@@ -3470,18 +3526,18 @@ var SpatialHashGrid = (_class6 = class {
 // src/tree/DOMPortalEntity.ts
 var DOMPortalEntity = (_class7 = class extends _chunk2Z23LTH3js.Entity {
   
-  __init82() {this.isDOMPortal = true}
-  __init83() {this.domListeners = []}
-  __init84() {this.resizeObserver = null}
-  __init85() {this.cachedWidth = 100}
-  __init86() {this.cachedHeight = 100}
-  __init87() {this.lastWidth = ""}
-  __init88() {this.lastHeight = ""}
-  __init89() {this.lastTransform = ""}
-  __init90() {this.lastZIndex = ""}
-  __init91() {this.lastOpacity = ""}
+  __init88() {this.isDOMPortal = true}
+  __init89() {this.domListeners = []}
+  __init90() {this.resizeObserver = null}
+  __init91() {this.cachedWidth = 100}
+  __init92() {this.cachedHeight = 100}
+  __init93() {this.lastWidth = ""}
+  __init94() {this.lastHeight = ""}
+  __init95() {this.lastTransform = ""}
+  __init96() {this.lastZIndex = ""}
+  __init97() {this.lastOpacity = ""}
   constructor(domElement, width, height, id) {
-    super(id);_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);;
+    super(id);_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);;
     this.domElement = domElement;
     this.width = _nullishCoalesce(width, () => ( 0));
     this.height = _nullishCoalesce(height, () => ( 0));

package/dist/index.mjs

@@ -667,6 +667,19 @@ var Scene = class _Scene {
   dirty = true;
   /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
   autoThrottle = true;
+  // --- Frame telemetry (read via `frameStats`) ---------------------------
+  /** Wall-clock ms spent inside the last `render()` call. */
+  _lastFrameMs = 0;
+  /** Rolling exponential average of rendered-frame intervals, in ms. */
+  _avgFrameIntervalMs = 0;
+  /** dt (ms) handed to the last rendered frame. */
+  _lastDt = 0;
+  /** Count of frames actually rendered since the loop started. */
+  _renderedFrames = 0;
+  /** Count of rAF ticks skipped (idle / capped) since the loop started. */
+  _skippedFrames = 0;
+  /** `time` of the previous *rendered* frame, for interval measurement. */
+  _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,
@@ -1318,6 +1331,36 @@ var Scene = class _Scene {
   markDirty() {
     this.dirty = true;
   }
+  /**
+   * Live frame telemetry for profilers and devtools overlays. All timings are
+   * measured on the `requestAnimationFrame` loop; a scene driven only by
+   * {@link step} (e.g. deterministic video export) leaves these at their zero
+   * defaults.
+   *
+   * `fps` is derived from the interval between *rendered* frames, so idle
+   * `onDemand` scenes and frames skipped by the {@link maxFPS} cap or the
+   * static auto-throttle do not deflate it — it reports the cadence of actual
+   * redraws, not the raw rAF rate. `frameTimeMs` is the wall-clock cost of the
+   * last `render()` pass alone (excludes a11y/content-projection sync).
+   *
+   * The renderer always repaints the full canvas, so there is no partial
+   * dirty-rectangle to expose; `dirty` is the boolean redraw-pending flag and
+   * `pendingRedraw` reflects whether the next `onDemand` tick will actually
+   * render.
+   */
+  get frameStats() {
+    const interval = this._avgFrameIntervalMs;
+    return {
+      fps: interval > 0 ? Math.min(1e3 / interval, this.maxFPS > 0 ? this.maxFPS : 1e3 / interval) : 0,
+      frameTimeMs: this._lastFrameMs,
+      frameIntervalMs: interval,
+      dt: this._lastDt,
+      renderedFrames: this._renderedFrames,
+      skippedFrames: this._skippedFrames,
+      renderMode: this.renderMode,
+      dirty: this.dirty
+    };
+  }
   /** True when any node in the subtree has a pending animation. */
   /** True when any node in the subtree is interactive (drives a11y sync). */
   syncOptionalAttribute(element, name, value) {
@@ -2221,6 +2264,7 @@ var Scene = class _Scene {
       cap = Math.min(cap, 2);
     }
     if (cap > 0 && time - this.lastTime < 1e3 / cap - 1) {
+      this._skippedFrames++;
       this.scheduleFrame();
       return;
     }
@@ -2231,11 +2275,23 @@ var Scene = class _Scene {
     }
     this.lastTime = time;
     if (this.renderMode === "onDemand" && isIdle) {
+      this._skippedFrames++;
       this.scheduleFrame();
       return;
     }
     this.dirty = false;
+    const now = typeof performance !== "undefined" ? performance.now() : time;
+    if (this._lastRenderTick > 0) {
+      const interval = time - this._lastRenderTick;
+      if (interval > 0) {
+        this._avgFrameIntervalMs = this._avgFrameIntervalMs === 0 ? interval : this._avgFrameIntervalMs * 0.9 + interval * 0.1;
+      }
+    }
+    this._lastRenderTick = time;
+    this._lastDt = dt;
     this.render(this.renderer, dt, time);
+    this._lastFrameMs = (typeof performance !== "undefined" ? performance.now() : time) - now;
+    this._renderedFrames++;
     const hasActiveAnimation = this.frameHadAnimation;
     const hasInteractive = this.frameHadInteractive;
     const wantsContentSync = this.contentProjectionEnabled;

package/dist/tree/Scene.d.ts

@@ -101,6 +101,28 @@ export interface SceneOptions {
 }
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
+/**
+ * Live render-loop telemetry, read from {@link Scene.frameStats}. See that
+ * getter for how each field is measured.
+ */
+export interface FrameStats {
+    /** Rendered-frame cadence (Hz), clamped to `maxFPS`. `0` before the first pair of rendered frames. */
+    fps: number;
+    /** Wall-clock ms of the last `render()` pass (excludes a11y/content sync). */
+    frameTimeMs: number;
+    /** Smoothed interval between rendered frames, in ms (EMA). */
+    frameIntervalMs: number;
+    /** dt (ms) handed to the last rendered frame. */
+    dt: number;
+    /** Total frames rendered since `start()`. */
+    renderedFrames: number;
+    /** Total rAF ticks skipped (idle/onDemand/capped) since `start()`. */
+    skippedFrames: number;
+    /** The scene's current render mode. */
+    renderMode: 'always' | 'onDemand';
+    /** Whether a redraw is currently pending (the boolean dirty flag). */
+    dirty: boolean;
+}
 export interface A11yTreeNode {
     id: string;
     tag: string;
@@ -147,6 +169,18 @@ export declare class Scene {
     private dirty;
     /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
     autoThrottle: boolean;
+    /** Wall-clock ms spent inside the last `render()` call. */
+    private _lastFrameMs;
+    /** Rolling exponential average of rendered-frame intervals, in ms. */
+    private _avgFrameIntervalMs;
+    /** dt (ms) handed to the last rendered frame. */
+    private _lastDt;
+    /** Count of frames actually rendered since the loop started. */
+    private _renderedFrames;
+    /** Count of rAF ticks skipped (idle / capped) since the loop started. */
+    private _skippedFrames;
+    /** `time` of the previous *rendered* frame, for interval measurement. */
+    private _lastRenderTick;
     /**
      * Frame-rate cap (power saving). `0` = uncapped (native refresh). When set,
      * the loop renders at most `maxFPS` times per second; animations still run,
@@ -339,6 +373,24 @@ export declare class Scene {
      * entity state outside of {@link Entity.animate} so the change is rendered.
      */
     markDirty(): void;
+    /**
+     * Live frame telemetry for profilers and devtools overlays. All timings are
+     * measured on the `requestAnimationFrame` loop; a scene driven only by
+     * {@link step} (e.g. deterministic video export) leaves these at their zero
+     * defaults.
+     *
+     * `fps` is derived from the interval between *rendered* frames, so idle
+     * `onDemand` scenes and frames skipped by the {@link maxFPS} cap or the
+     * static auto-throttle do not deflate it — it reports the cadence of actual
+     * redraws, not the raw rAF rate. `frameTimeMs` is the wall-clock cost of the
+     * last `render()` pass alone (excludes a11y/content-projection sync).
+     *
+     * The renderer always repaints the full canvas, so there is no partial
+     * dirty-rectangle to expose; `dirty` is the boolean redraw-pending flag and
+     * `pendingRedraw` reflects whether the next `onDemand` tick will actually
+     * render.
+     */
+    get frameStats(): FrameStats;
     /** True when any node in the subtree has a pending animation. */
     /** True when any node in the subtree is interactive (drives a11y sync). */
     private syncOptionalAttribute;

package/package.json

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