@vectojs/core 1.9.2 → 1.11.0

package/dist/index.mjs

@@ -12,7 +12,7 @@ import {
   isSafeUrl,
   parseColorToRGBA,
   sanitizeUrl
-} from "./chunk-WT2XZHJQ.mjs";
+} from "./chunk-XZEPHCDZ.mjs";
 import {
   Easing,
   Entity,
@@ -27,7 +27,7 @@ import {
   cssLineBoxBaseline,
   isTweenConfig,
   prepareContentGrid
-} from "./chunk-J2P6QZJV.mjs";
+} from "./chunk-XIEQHSBB.mjs";
 import {
   ArabicShaper,
   BidiResolver,
@@ -708,6 +708,8 @@ var Scene = class _Scene {
   width;
   height;
   disableWindowResize = false;
+  /** See {@link SceneOptions.maxDPR}. `undefined` = uncapped (real DPR). */
+  maxDPR;
   // WebGPU properties
   destroyed = false;
   device = null;
@@ -733,10 +735,72 @@ var Scene = class _Scene {
   pointerLeaveListener = null;
   hasWarnedZeroSize = false;
   fontLoadHandler = null;
+  // ── Dev-mode warning infrastructure ──────────────────────────────
+  //
+  // Enable with `Scene.devMode = true` or by setting `globalThis.__DEV__`.
+  // Auto-detected when `NODE_ENV === 'development'`.
+  //
+  // 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 devMode = false;
+  static _devModeDetected() {
+    if (_Scene.devMode) return true;
+    const gp = typeof globalThis !== "undefined" ? globalThis : void 0;
+    if (gp?.__DEV__) return true;
+    if (gp?.process?.env?.NODE_ENV === "development") return true;
+    return false;
+  }
+  _devActive;
+  _devFrameCount = 0;
+  _devWarn(message) {
+    if (!this._devActive) return;
+    console.warn(`[vectojs/dev] ${message}`);
+  }
+  /** @internal Periodic dev checks — called once per frame in dev mode. */
+  _devRunChecks() {
+    this._devFrameCount++;
+    if (this._devFrameCount % 120 !== 0) return;
+    if (this.a11yElements) {
+      let interactiveCount = 0;
+      const walk = (node) => {
+        if (node.interactive && node.width > 0) interactiveCount++;
+        for (const c of node.children) walk(c);
+      };
+      walk(this.root);
+      for (const c of this.overlayRoot.children) walk(c);
+      const shadowCount = this.a11yElements.size;
+      if (shadowCount > interactiveCount + 2) {
+        this._devWarn(
+          `a11yElements (${shadowCount}) exceeds interactive entities (${interactiveCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
+        );
+      }
+    }
+    let checked = 0;
+    const walkProjections = (node) => {
+      if (checked > 10) return;
+      const proj = node.getContentProjection?.();
+      if (proj?.text && proj.selectable !== false) {
+        const el = this.contentElements?.get(node.id);
+        if (el) {
+          const projectedText = el.textContent || "";
+          if (projectedText !== "" && projectedText !== proj.text) {
+            this._devWarn(
+              `Content projection mismatch for entity "${node.id}": projection says "${proj.text.slice(0, 60)}" but DOM shows "${projectedText.slice(0, 60)}". Ensure getContentProjection() output matches what drawSelf renders.`
+            );
+          }
+        }
+      }
+      checked++;
+      for (const c of node.children) walkProjections(c);
+    };
+    walkProjections(this.root);
+  }
   constructor(canvas, options = {}) {
     this.canvas = canvas;
     this.debugA11y = options.debugA11y ?? false;
     this.disableWindowResize = options.disableWindowResize ?? false;
+    this.maxDPR = options.maxDPR;
     if (this.disableWindowResize) {
       const styleWidth = parseInlinePx(canvas.style?.width);
       const styleHeight = parseInlinePx(canvas.style?.height);
@@ -754,6 +818,7 @@ var Scene = class _Scene {
     this.particleBackend = options.particleBackend ?? "auto";
     this.a11ySyncInterval = options.a11ySyncInterval ?? 0;
     this.contentProjectionEnabled = options.contentProjection ?? true;
+    this._devActive = _Scene._devModeDetected();
     this.reducedMotionQuery = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
     this.root = new class RootEntity extends Entity {
       isPointInside() {
@@ -777,7 +842,8 @@ var Scene = class _Scene {
     } else {
       this.renderer = new CanvasRenderer(
         canvas,
-        this.disableWindowResize ? { width: this.width, height: this.height } : void 0
+        this.disableWindowResize ? { width: this.width, height: this.height } : void 0,
+        this.maxDPR
       );
     }
     if (typeof document !== "undefined") {
@@ -903,6 +969,7 @@ var Scene = class _Scene {
       if (canvas.parentElement) canvas.parentElement.appendChild(gl);
       const pr = _Scene.webglCreator ? _Scene.webglCreator(gl) : null;
       if (pr) {
+        pr.maxDPR = this.maxDPR;
         pr.resize(this.width, this.height);
         this.glCanvas = gl;
         this.pointRenderer = pr;
@@ -1268,6 +1335,9 @@ var Scene = class _Scene {
         el.addEventListener("click", (e) => {
           node.dispatchEvent(new VectoJSEvent("click", node, e));
         });
+        el.addEventListener("dblclick", (e) => {
+          node.dispatchEvent(new VectoJSEvent("dblclick", node, e));
+        });
         el.addEventListener("mouseenter", (e) => {
           if (this.debugA11y) el.style.backgroundColor = "rgba(56, 189, 248, 0.2)";
           node.dispatchEvent(new VectoJSEvent("hover", node, e, false));
@@ -2284,6 +2354,13 @@ var Scene = class _Scene {
         node.update(dt, time);
         if (!walkHadAnimation && node.hasPendingAnimations()) walkHadAnimation = true;
         if (!walkHadInteractive && node.interactive) walkHadInteractive = true;
+        if (this._devActive && this._devFrameCount % 120 === 0) {
+          if (node.update !== Entity.prototype.update && 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.`
+            );
+          }
+        }
       }
       const cos = Math.cos(node.rotation);
       const sin = Math.sin(node.rotation);
@@ -2414,6 +2491,10 @@ var Scene = class _Scene {
       this.pointRenderer?.flush();
     }
     renderer.present?.();
+    if (this._devActive) {
+      this._devFrameCount++;
+      this._devRunChecks();
+    }
   }
   /**
    * Export the current scene state to a lightweight, flat SVG XML string.
@@ -2431,9 +2512,13 @@ var Scene = class _Scene {
     this.height = height;
     this.contentFontEpoch++;
     if (typeof this.renderer.resize === "function") {
+      if ("maxDPR" in this.renderer) this.renderer.maxDPR = this.maxDPR;
       this.renderer.resize(width, height);
     }
-    this.pointRenderer?.resize(width, height);
+    if (this.pointRenderer) {
+      this.pointRenderer.maxDPR = this.maxDPR;
+      this.pointRenderer.resize(width, height);
+    }
     if (this.gpuCanvas) {
       this.gpuCanvas.width = width;
       this.gpuCanvas.height = height;

package/dist/renderer/CanvasRenderer.d.ts

@@ -3,6 +3,15 @@ export declare class CanvasRenderer implements IRenderer {
     private ctx;
     private width;
     private height;
+    /**
+     * Cap on the effective device pixel ratio applied by the constructor and
+     * {@link resize}. `undefined` (default) uses the real, uncapped
+     * `devicePixelRatio` — unchanged from prior versions. Set directly, or via
+     * the constructor's third argument; `Scene` (see `SceneOptions.maxDPR`)
+     * keeps this in sync on every {@link resize} call, since the real DPR can
+     * change at runtime (e.g. a window dragged between displays).
+     */
+    maxDPR?: number;
     /**
      * Max circles per batched `fill()`. A single Canvas 2D `fill()` over a path is
      * superlinear in sub-path count, so an unbounded batch is *slower* than many
@@ -21,11 +30,12 @@ export declare class CanvasRenderer implements IRenderer {
      *   fullscreen canvas and sizes to the window — pass this for embedded /
      *   custom-container canvases (the Scene does when `disableWindowResize` is
      *   set) so the canvas's own dimensions aren't clobbered by the window's.
+     * @param maxDPR - See {@link maxDPR}.
      */
     constructor(canvas: HTMLCanvasElement, size?: {
         width: number;
         height: number;
-    });
+    }, maxDPR?: number);
     /**
      * Expose the underlying `CanvasRenderingContext2D` for operations not
      * covered by the {@link IRenderer} interface.
@@ -33,6 +43,8 @@ export declare class CanvasRenderer implements IRenderer {
      * @returns The raw 2D rendering context.
      */
     getContext(): CanvasRenderingContext2D;
+    /** Real `devicePixelRatio`, clamped to {@link maxDPR} when set. */
+    private effectiveDPR;
     /**
      * Resize the backing canvas buffer and re-apply DPR scaling.
      *

package/dist/renderer/WebGLPointRenderer.d.ts

@@ -7,6 +7,18 @@
 export interface PointRenderer {
     /** Resize the backing buffer + GL viewport to a logical `w × h` (DPR applied). */
     resize(width: number, height: number): void;
+    /**
+     * Cap on the effective device pixel ratio applied by {@link resize}.
+     * `undefined` (default) uses the real, uncapped `devicePixelRatio`. Set
+     * before calling `resize()` for it to take effect on that call (matches
+     * {@link import('../tree/Scene').SceneOptions.maxDPR} — `Scene` sets this
+     * once at construction and again before every `resize()` call, since a
+     * factory function has no other way to receive the option: the WebGL point
+     * layer's creator is a plain `(canvas) => PointRenderer` registered once by
+     * `@vectojs/core`'s module init, with no room for a per-Scene constructor
+     * argument).
+     */
+    maxDPR?: number;
     /** Begin a frame: reset the accumulated primitive buffers. */
     begin(): void;
     /** Add one circle in world (CSS-pixel) coordinates; `alpha` multiplies the color's. */

package/dist/renderer.js

@@ -4,11 +4,11 @@
 
 
 
-var _chunkBPMNCGU7js = require('./chunk-BPMNCGU7.js');
+var _chunkORCPCIJ7js = require('./chunk-ORCPCIJ7.js');
 
 
 
 
 
 
-exports.CanvasRenderer = _chunkBPMNCGU7js.CanvasRenderer; exports.SVGRenderer = _chunkBPMNCGU7js.SVGRenderer; exports.WebGPUParticleSystemManager = _chunkBPMNCGU7js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkBPMNCGU7js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkBPMNCGU7js.parseColorToRGBA;
+exports.CanvasRenderer = _chunkORCPCIJ7js.CanvasRenderer; exports.SVGRenderer = _chunkORCPCIJ7js.SVGRenderer; exports.WebGPUParticleSystemManager = _chunkORCPCIJ7js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkORCPCIJ7js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkORCPCIJ7js.parseColorToRGBA;

package/dist/renderer.mjs

@@ -4,7 +4,7 @@ import {
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-WT2XZHJQ.mjs";
+} from "./chunk-XZEPHCDZ.mjs";
 export {
   CanvasRenderer,
   SVGRenderer,

package/dist/text.js

@@ -5,7 +5,7 @@
 
 
 
-var _chunkGKLTTGBRjs = require('./chunk-GKLTTGBR.js');
+var _chunk2Z23LTH3js = require('./chunk-2Z23LTH3.js');
 
 
 
@@ -19,4 +19,4 @@ var _chunk4AR425ARjs = require('./chunk-4AR425AR.js');
 
 
 
-exports.ArabicShaper = _chunk4AR425ARjs.ArabicShaper; exports.BidiResolver = _chunk4AR425ARjs.BidiResolver; exports.MSDFFont = _chunkGKLTTGBRjs.MSDFFont; exports.MSDFTextEntity = _chunkGKLTTGBRjs.MSDFTextEntity; exports.SVGEntity = _chunkGKLTTGBRjs.SVGEntity; exports.clearCssLineBoxMetrics = _chunkGKLTTGBRjs.clearCssLineBoxMetrics; exports.cssLineBoxBaseline = _chunkGKLTTGBRjs.cssLineBoxBaseline; exports.prepareContentGrid = _chunkGKLTTGBRjs.prepareContentGrid;
+exports.ArabicShaper = _chunk4AR425ARjs.ArabicShaper; exports.BidiResolver = _chunk4AR425ARjs.BidiResolver; exports.MSDFFont = _chunk2Z23LTH3js.MSDFFont; exports.MSDFTextEntity = _chunk2Z23LTH3js.MSDFTextEntity; exports.SVGEntity = _chunk2Z23LTH3js.SVGEntity; exports.clearCssLineBoxMetrics = _chunk2Z23LTH3js.clearCssLineBoxMetrics; exports.cssLineBoxBaseline = _chunk2Z23LTH3js.cssLineBoxBaseline; exports.prepareContentGrid = _chunk2Z23LTH3js.prepareContentGrid;

package/dist/text.mjs

@@ -5,7 +5,7 @@ import {
   clearCssLineBoxMetrics,
   cssLineBoxBaseline,
   prepareContentGrid
-} from "./chunk-J2P6QZJV.mjs";
+} from "./chunk-XIEQHSBB.mjs";
 import {
   ArabicShaper,
   BidiResolver

package/dist/tree/Entity.d.ts

@@ -192,7 +192,7 @@ export interface A11yAttributes {
 /**
  * Union of all pointer/interaction events that can be emitted by an {@link Entity}.
  */
-export type VectoEvent = 'click' | 'hover' | 'pointerdown' | 'pointerup' | 'pointercancel' | 'pointermove' | 'pointerleave' | 'change' | 'focus' | 'blur' | 'wheel' | 'keydown' | 'keyup';
+export type VectoEvent = 'click' | 'dblclick' | 'hover' | 'pointerdown' | 'pointerup' | 'pointercancel' | 'pointermove' | 'pointerleave' | 'change' | 'focus' | 'blur' | 'wheel' | 'keydown' | 'keyup';
 /** Options for {@link Entity.on} / {@link Entity.off}. */
 export interface ListenerOptions {
     /** Register the listener for the capture phase (root→target) instead of bubble. */
@@ -470,6 +470,15 @@ export declare abstract class Entity {
      * @param payload - Arbitrary data forwarded to each listener.
      */
     emit(event: VectoEvent, payload: any): void;
+    /**
+     * Programmatically focus the entity's projected a11y shadow element, if one
+     * exists. After `scene.add(entity)` the shadow element is typically created
+     * on the next a11y sync (within one animation frame), so this method retries
+     * once on the next rAF if the element isn't immediately available — matching
+     * the timing pattern the prior workaround described in findings.md achieved
+     * with `requestAnimationFrame(() => document.getElementById(id)?.focus())`.
+     */
+    focus(): void;
     /** Run one node's listeners for the event, honoring stopImmediatePropagation. */
     private fireListeners;
     /**

package/dist/tree/Scene.d.ts

@@ -70,6 +70,21 @@ export interface SceneOptions {
      * Useful when Vecto is running inside a custom layout container or offscreen canvas.
      */
     disableWindowResize?: boolean;
+    /**
+     * Cap the effective device pixel ratio used to size the Canvas2D and WebGL
+     * point-layer backing stores. `undefined` (default) reads the real,
+     * uncapped `window.devicePixelRatio` — unchanged from prior versions.
+     * Backing-store render cost scales with `logical size × dpr²`, so a
+     * full-screen HiDPI scene (`pointBackend: 'webgl'` in particular) can
+     * overrun its frame budget on a DPR-3 display while running fine on the
+     * DPR-1 dev machine it was tuned on (findings.md, 2026-07-16). `maxDPR: 2`
+     * keeps the display retina-crisp (2x already exceeds what most eyes
+     * resolve) while roughly halving the backing-store pixel count at DPR 3.
+     * Applied at construction and re-applied on every {@link resize} call
+     * (including the automatic window-resize listener), since the real DPR
+     * can change at runtime (a window dragged between displays).
+     */
+    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`.
@@ -196,6 +211,8 @@ export declare class Scene {
     width: number;
     height: number;
     private disableWindowResize;
+    /** See {@link SceneOptions.maxDPR}. `undefined` = uncapped (real DPR). */
+    maxDPR?: number;
     private destroyed;
     private device;
     private deviceLost;
@@ -216,6 +233,14 @@ export declare class Scene {
     private pointerLeaveListener;
     private hasWarnedZeroSize;
     private fontLoadHandler;
+    /** Toggle development-mode runtime warnings globally. */
+    static devMode: boolean;
+    private static _devModeDetected;
+    private _devActive;
+    private _devFrameCount;
+    private _devWarn;
+    /** @internal Periodic dev checks — called once per frame in dev mode. */
+    private _devRunChecks;
     constructor(canvas: HTMLCanvasElement, options?: SceneOptions);
     private endContentSelectionDrag;
     private releaseContentSelectionForRebuild;

package/package.json

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