@vectojs/core 1.35.3 → 1.37.0

package/dist/index.mjs

@@ -11,14 +11,14 @@ import {
   parseColorToRGBA,
   sanitizeUrl,
   setRendererDevMode
-} from "./chunk-25PS5K7R.mjs";
+} from "./chunk-LWEMD34D.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent,
   contentLineInHint
-} from "./chunk-CHDJEHML.mjs";
+} from "./chunk-3MTVDXZQ.mjs";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -178,8 +178,8 @@ var ComputeParticleEntity = class extends Entity {
    * render-tree walk, but this entity is still a normal tree member that
    * walk visits — without this override, the base `Entity.hasPendingAnimations()`
    * (always `false`) is what Scene sees, so `renderMode: 'always'`'s idle
-   * auto-throttle drops the WHOLE scene to ~2fps the instant nothing else in
-   * the tree is animating, even while thousands of particles are visibly
+   * auto-throttle drops the WHOLE scene to the idle FPS floor the instant
+   * nothing else in the tree is animating, even while thousands of particles are visibly
    * drifting or spring-settling. A spring+damping system asymptotically
    * approaches zero velocity but never reaches it exactly, so this checks
    * against a small epsilon rather than `!== 0` — otherwise this would
@@ -3435,6 +3435,7 @@ var SCENE_OPTION_KEYS = [
   "contentSemanticMargin",
   "debugA11y",
   "disableWindowResize",
+  "idleFPS",
   "maxDPR",
   "maxFPS",
   "particleBackend",
@@ -3863,8 +3864,17 @@ var Scene = class _Scene {
     if (value) this._dirty.mark(void 0, this.currentFrame);
     else this._dirty.clear();
   }
-  /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
+  /**
+   * Whether to throttle the `'always'` loop when the scene is static to save
+   * power. The idle floor is {@link Scene.idleFPS} (default 60).
+   */
   autoThrottle = true;
+  /**
+   * Frame-rate floor for an idle `'always'` scene when {@link Scene.autoThrottle}
+   * is on. Default `60`. Set `2` for the legacy aggressive idle sleep, `0` to
+   * keep the scene's `maxFPS` cadence while idle.
+   */
+  idleFPS = 60;
   // --- Frame telemetry (read via `frameStats`) ---------------------------
   /** Wall-clock ms spent inside the last `render()` call. */
   _lastFrameMs = 0;
@@ -4794,6 +4804,7 @@ var Scene = class _Scene {
     this.maxFPS = options.maxFPS ?? (isTest ? 0 : 60);
     this.respectReducedMotion = options.respectReducedMotion ?? true;
     this.autoThrottle = options.autoThrottle ?? true;
+    this.idleFPS = options.idleFPS ?? 60;
     this.phases.userTiming = options.userTiming ?? false;
     this.particleBackend = options.particleBackend ?? "auto";
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
@@ -6739,7 +6750,7 @@ var Scene = class _Scene {
     let cap = this.effectiveMaxFPS();
     const isIdle = !this.dirty && !this.frameHadAnimation && !this.contentSemanticDeferred;
     if (isIdle && this.autoThrottle && this.renderMode === "always" && this.maxFPS > 0) {
-      cap = Math.min(cap, 2);
+      cap = Math.min(cap, this.idleFPS);
     }
     if (cap > 0 && time - this.lastTime < 1e3 / cap - 1) {
       this._skippedFrames++;
@@ -6990,7 +7001,7 @@ var Scene = class _Scene {
       if (this._devActive && this._devFrameCount % 120 === 0) {
         if (overridesUpdate && node.hasPendingAnimations === 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.`
+            `Entity "${node.id}" overrides update() but not hasPendingAnimations(). Custom motion in update() without overriding hasPendingAnimations() causes the idle throttle to slow the animation. Override hasPendingAnimations() to return true while motion is in flight.`
           );
         }
       }

package/dist/renderer/CanvasRenderer.d.ts

@@ -133,7 +133,7 @@ export declare class CanvasRenderer implements IRenderer {
     /** @inheritdoc */
     setGlobalAlpha(alpha: number): void;
     /** @inheritdoc */
-    clip(x: number, y: number, width: number, height: number): void;
+    clip(x: number, y: number, width: number, height: number, radii?: number | number[]): void;
     /** @inheritdoc */
     beginPath(): void;
     /** @inheritdoc */

package/dist/renderer/IRenderer.d.ts

@@ -129,12 +129,19 @@ export interface IRenderer {
      * Intersect the current clip region with a rectangle. Affects all subsequent
      * draws until the next {@link restore}; wrap in {@link save}/{@link restore}.
      *
+     * When `radii` is provided the clip is a rounded rectangle instead of a sharp
+     * one. Backends that can only express a rectangular clip (e.g. a scissor-test
+     * GPU path) may ignore `radii`, so it must be treated as a progressive
+     * enhancement rather than a guarantee.
+     *
      * @param x - Left edge.
      * @param y - Top edge.
      * @param width - Rectangle width.
      * @param height - Rectangle height.
+     * @param radii - Optional corner radius (uniform) or per-corner array, matching
+     *   {@link roundRect}. Omit for a sharp rectangle.
      */
-    clip(x: number, y: number, width: number, height: number): void;
+    clip(x: number, y: number, width: number, height: number, radii?: number | number[]): void;
     /** Begin a new sub-path, discarding the current path. */
     beginPath(): void;
     /**

package/dist/renderer/SVGRenderer.d.ts

@@ -72,7 +72,7 @@ export declare class SVGRenderer implements IRenderer {
         stop: number;
         color: string;
     }[]): SVGLinearGradient;
-    clip(x: number, y: number, width: number, height: number): void;
+    clip(x: number, y: number, width: number, height: number, radii?: number | number[]): void;
     toXMLString(): string;
     private resolveGradient;
     private escapeXML;

package/dist/renderer.js

@@ -10,7 +10,7 @@
 
 
 
-var _chunkMO24PVGTjs = require('./chunk-MO24PVGT.js');
+var _chunkZYYP2M5Djs = require('./chunk-ZYYP2M5D.js');
 
 
 
@@ -22,4 +22,4 @@ var _chunkMO24PVGTjs = require('./chunk-MO24PVGT.js');
 
 
 
-exports.CanvasRenderer = _chunkMO24PVGTjs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkMO24PVGTjs.GlyphRasterAtlas; exports.SVGRenderer = _chunkMO24PVGTjs.SVGRenderer; exports.TextRasterCache = _chunkMO24PVGTjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkMO24PVGTjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkMO24PVGTjs.createWebGLPointRenderer; exports.installRendererDevTraps = _chunkMO24PVGTjs.installRendererDevTraps; exports.isRendererDevMode = _chunkMO24PVGTjs.isRendererDevMode; exports.parseColorToRGBA = _chunkMO24PVGTjs.parseColorToRGBA; exports.setRendererDevMode = _chunkMO24PVGTjs.setRendererDevMode;
+exports.CanvasRenderer = _chunkZYYP2M5Djs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkZYYP2M5Djs.GlyphRasterAtlas; exports.SVGRenderer = _chunkZYYP2M5Djs.SVGRenderer; exports.TextRasterCache = _chunkZYYP2M5Djs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkZYYP2M5Djs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkZYYP2M5Djs.createWebGLPointRenderer; exports.installRendererDevTraps = _chunkZYYP2M5Djs.installRendererDevTraps; exports.isRendererDevMode = _chunkZYYP2M5Djs.isRendererDevMode; exports.parseColorToRGBA = _chunkZYYP2M5Djs.parseColorToRGBA; exports.setRendererDevMode = _chunkZYYP2M5Djs.setRendererDevMode;

package/dist/renderer.mjs

@@ -9,7 +9,7 @@ import {
   isRendererDevMode,
   parseColorToRGBA,
   setRendererDevMode
-} from "./chunk-25PS5K7R.mjs";
+} from "./chunk-LWEMD34D.mjs";
 export {
   CanvasRenderer,
   GlyphRasterAtlas,

package/dist/text/MSDFTextEntity.d.ts

@@ -59,8 +59,8 @@ export declare class MSDFTextEntity extends Entity {
      *
      * Measured on Chromium and Firefox (2026-07-31) with a 600 ms atlas: the
      * scene's own rAF loop never uploaded a decoded atlas in EITHER render mode.
-     * `onDemand` skips idle frames outright; `always` throttles to 2 FPS when
-     * idle, so whether it recovers is down to whether a throttled tick happens to
+     * `onDemand` skips idle frames outright; `always` throttles to the idle FPS
+     * floor when idle, so whether it recovers is down to whether a throttled tick happens to
      * land after the decode — Chromium got one, Firefox did not. Neither is a
      * mechanism, which is why this listener exists rather than relying on the
      * frame loop to come back around.

package/dist/text.js

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

package/dist/text.mjs

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

package/dist/tree/ComputeParticleEntity.d.ts

@@ -113,8 +113,8 @@ export declare class ComputeParticleEntity extends Entity {
      * render-tree walk, but this entity is still a normal tree member that
      * walk visits — without this override, the base `Entity.hasPendingAnimations()`
      * (always `false`) is what Scene sees, so `renderMode: 'always'`'s idle
-     * auto-throttle drops the WHOLE scene to ~2fps the instant nothing else in
-     * the tree is animating, even while thousands of particles are visibly
+     * auto-throttle drops the WHOLE scene to the idle FPS floor the instant
+     * nothing else in the tree is animating, even while thousands of particles are visibly
      * drifting or spring-settling. A spring+damping system asymptotically
      * approaches zero velocity but never reaches it exactly, so this checks
      * against a small epsilon rather than `!== 0` — otherwise this would

package/dist/tree/Entity.d.ts

@@ -658,9 +658,20 @@ export declare abstract class Entity {
      * and promotes it.
      *
      * `'never'` suppresses the node entirely. Prefer `interactive = false` unless
-     * the entity genuinely needs pointer events without any semantic presence;
-     * this exists so a purely decorative interactive surface can opt out without
-     * losing canvas hit-testing.
+     * the entity genuinely needs to stay hit-testable without any semantic
+     * presence — this exists so a purely decorative interactive surface can opt
+     * out of the a11y tree.
+     *
+     * **Pointer input is routed through the projected mirror.** The engine binds
+     * `pointerdown`/`pointermove`/`pointerup`/`click`/`dblclick` to each shadow
+     * element (the canvas itself only tracks `mouseX`/`mouseY`), so an entity
+     * with no materialized node receives **no pointer events at all** — neither
+     * in `'never'` mode nor in `'onDemand'` before it is engaged (focused,
+     * pointer target, or `requestA11yProjection`). Canvas hit-testing exists
+     * (`Scene.findEntityAt`) but is a query API, not a dispatch path. For a
+     * pointer-reactive region with no role (e.g. a desktop click-catcher), use
+     * `'eager'` + `a11yFullViewport` + `tabIndex: -1` with a role-less
+     * `getA11yAttributes()`: the mirror is AT-invisible but pointer-visible.
      *
      * **This does not replace an aggregate description.** A thousand `'onDemand'`
      * danmaku are individually reachable but say nothing collectively. The proven

package/dist/tree/Scene.d.ts

@@ -98,10 +98,22 @@ export interface SceneOptions {
      */
     maxDPR?: number;
     /**
-     * Enable automatic throttling to 2 FPS when the scene is static (no active transitions
-     * and not marked dirty) to save power/CPU. Default is `true`.
+     * Enable automatic throttling of the `'always'` loop when the scene is
+     * static (no active transitions and not marked dirty) to save power/CPU.
+     * The idle floor is 60 FPS by default; raise or lower it with
+     * {@link SceneOptions.idleFPS}. Default is `true`.
      */
     autoThrottle?: boolean;
+    /**
+     * Frame-rate floor for an idle `'always'` scene when
+     * {@link SceneOptions.autoThrottle} is on. Default `60` — an idle scene
+     * keeps animating smoothly instead of stuttering at the old 2 FPS floor.
+     * Set e.g. `2` to restore the aggressive deep sleep for battery-critical
+     * scenes (the developer's explicit choice); `0` means "keep the scene's
+     * `maxFPS` cadence while idle". Ignored when `autoThrottle` is `false` or
+     * `renderMode` is `'onDemand'` (onDemand already renders zero idle frames).
+     */
+    idleFPS?: number;
     /**
      * Emit User Timing marks and measures for render phases. Default `false`.
      * Intended for short profiler captures; enable only while collecting one.
@@ -196,8 +208,9 @@ export interface SceneOptions {
     readingDirection?: 'ltr' | 'rtl';
     /**
      * When to repaint:
-     * - `'always'` (default): drive a continuous rAF loop, throttling to 2 FPS
-     *   while the scene is idle if {@link SceneOptions.autoThrottle} is on.
+     * - `'always'` (default): drive a continuous rAF loop, throttling to the
+     *   {@link SceneOptions.idleFPS} floor (default 60) while the scene is idle
+     *   if {@link SceneOptions.autoThrottle} is on.
      * - `'onDemand'`: paint only after {@link Scene.markDirty} (or an active
      *   transition), so a genuinely static scene costs zero frames.
      *
@@ -217,14 +230,14 @@ export interface SceneOptions {
  * plain untranspiled JS, gets no diagnostic at all. `renderMode` was a public
  * field with no matching option for several releases, and four `@vectojs` demos
  * shipped `new Scene(canvas, { renderMode: 'onDemand' })` — reading correctly,
- * doing nothing, and sitting on the 2 FPS idle floor.
+ * doing nothing, and sitting on the idle FPS floor.
  *
  * Kept as a literal rather than derived from a type: `keyof SceneOptions` does
  * not survive to runtime, so this list is the only form a constructor can check
  * against. A new option must be added here too — the test suite asserts the two
  * stay in sync.
  */
-export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticBudget', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
+export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticBudget', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'idleFPS', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
 export type { AcceleratorReason, AcceleratorStatus, AcceleratorReport };
@@ -406,8 +419,17 @@ export declare class Scene {
      */
     private get dirty();
     private set dirty(value);
-    /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
+    /**
+     * Whether to throttle the `'always'` loop when the scene is static to save
+     * power. The idle floor is {@link Scene.idleFPS} (default 60).
+     */
     autoThrottle: boolean;
+    /**
+     * Frame-rate floor for an idle `'always'` scene when {@link Scene.autoThrottle}
+     * is on. Default `60`. Set `2` for the legacy aggressive idle sleep, `0` to
+     * keep the scene's `maxFPS` cadence while idle.
+     */
+    idleFPS: number;
     /** Wall-clock ms spent inside the last `render()` call. */
     private _lastFrameMs;
     /** Rolling exponential average of rendered-frame intervals, in ms. */

package/package.json

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