@vectojs/core 1.25.0 → 1.27.0

package/dist/{chunk-KHGHP2J3.js → chunk-K2UGEIT6.js}

@@ -1,5 +1,52 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5;const __vecto_cjs_url=require("url").pathToFileURL(__filename).href;
 
+// src/renderer/IRenderer.ts
+var RENDERER_STYLE_PROPERTY_HINTS = {
+  globalAlpha: "setGlobalAlpha(alpha)",
+  strokeStyle: "stroke(color, lineWidth)",
+  lineWidth: "stroke(color, lineWidth)",
+  fillStyle: "fill(color) \u2014 or fillText(text, x, y, font, color)",
+  font: "fillText(text, x, y, font, color)",
+  lineCap: "stroke(color, lineWidth) (cap is backend-chosen)",
+  lineJoin: "stroke(color, lineWidth) (join is backend-chosen)",
+  globalCompositeOperation: "no equivalent \u2014 composite via a separate canvas",
+  shadowBlur: "no equivalent \u2014 draw the shadow explicitly",
+  shadowColor: "no equivalent \u2014 draw the shadow explicitly",
+  textAlign: "no equivalent \u2014 measure and offset x yourself",
+  textBaseline: "no equivalent \u2014 measure and offset y yourself"
+};
+var rendererDevMode = false;
+function setRendererDevMode(active) {
+  rendererDevMode = active;
+}
+function isRendererDevMode() {
+  if (rendererDevMode) return true;
+  const g = typeof globalThis !== "undefined" ? globalThis : void 0;
+  if (_optionalChain([g, 'optionalAccess', _ => _.__DEV__])) return true;
+  return _optionalChain([g, 'optionalAccess', _2 => _2.process, 'optionalAccess', _3 => _3.env, 'optionalAccess', _4 => _4.NODE_ENV]) === "development";
+}
+function installRendererDevTraps(renderer, label) {
+  if (!isRendererDevMode()) return;
+  for (const [prop, hint] of Object.entries(RENDERER_STYLE_PROPERTY_HINTS)) {
+    if (prop in renderer) continue;
+    let stored;
+    let warned = false;
+    Object.defineProperty(renderer, prop, {
+      configurable: true,
+      enumerable: false,
+      get: () => stored,
+      set: (value) => {
+        stored = value;
+        if (warned) return;
+        warned = true;
+        console.warn(
+          `[vectojs/dev] \`${prop}\` is not a renderer property \u2014 assigning it on ${label} has no effect on what is drawn. Call \`${hint}\` instead.`
+        );
+      }
+    });
+  }
+}
+
 // src/renderer/CanvasRenderer.ts
 function emptyDrawCounters() {
   return {
@@ -79,8 +126,8 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
   constructor(canvas, size, maxDPR) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);_class.prototype.__init3.call(this);_class.prototype.__init4.call(this);_class.prototype.__init5.call(this);_class.prototype.__init6.call(this);_class.prototype.__init7.call(this);_class.prototype.__init8.call(this);_class.prototype.__init9.call(this);_class.prototype.__init10.call(this);_class.prototype.__init11.call(this);
     this.maxDPR = maxDPR;
     const dpr = this.effectiveDPR();
-    this.width = _nullishCoalesce(_optionalChain([size, 'optionalAccess', _ => _.width]), () => ( (typeof window !== "undefined" ? window.innerWidth : canvas.width || 0)));
-    this.height = _nullishCoalesce(_optionalChain([size, 'optionalAccess', _2 => _2.height]), () => ( (typeof window !== "undefined" ? window.innerHeight : canvas.height || 0)));
+    this.width = _nullishCoalesce(_optionalChain([size, 'optionalAccess', _5 => _5.width]), () => ( (typeof window !== "undefined" ? window.innerWidth : canvas.width || 0)));
+    this.height = _nullishCoalesce(_optionalChain([size, 'optionalAccess', _6 => _6.height]), () => ( (typeof window !== "undefined" ? window.innerHeight : canvas.height || 0)));
     canvas.width = this.width * dpr;
     canvas.height = this.height * dpr;
     if (canvas.style) {
@@ -92,6 +139,7 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
     if (ctx) ctx.scale(dpr, dpr);
     this.canvas = canvas;
     this.setupContextLossRecovery();
+    installRendererDevTraps(this, "CanvasRenderer");
   }
   /** Register a callback fired after a lost 2D context is restored + re-scaled,
    *  so the owner can repaint (the restored canvas comes back cleared). */
@@ -122,7 +170,7 @@ var CanvasRenderer = (_class = class _CanvasRenderer {
       this.batchActive = false;
       this.batchCount = 0;
       this.contextLost = false;
-      _optionalChain([this, 'access', _3 => _3.contextRestoredCb, 'optionalCall', _4 => _4()]);
+      _optionalChain([this, 'access', _7 => _7.contextRestoredCb, 'optionalCall', _8 => _8()]);
     });
   }
   /**
@@ -491,6 +539,7 @@ var SVGRenderer = (_class2 = class {
   constructor(width, height) {;_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);
     this.width = width;
     this.height = height;
+    installRendererDevTraps(this, "SVGRenderer");
   }
   clear() {
     this.buffer = [];
@@ -712,8 +761,8 @@ var SVGRenderer = (_class2 = class {
   }
   drawImage(source, dx, dy, dw, dh) {
     this.flush();
-    const fromCanvas2 = typeof _optionalChain([source, 'optionalAccess', _5 => _5.toDataURL]) === "function";
-    const rawHref = fromCanvas2 ? source.toDataURL() : _optionalChain([source, 'optionalAccess', _6 => _6.src]) || "";
+    const fromCanvas2 = typeof _optionalChain([source, 'optionalAccess', _9 => _9.toDataURL]) === "function";
+    const rawHref = fromCanvas2 ? source.toDataURL() : _optionalChain([source, 'optionalAccess', _10 => _10.src]) || "";
     const href = fromCanvas2 && this.isSafeRasterDataUrl(rawHref) ? rawHref : sanitizeUrl(String(rawHref));
     const transformStr = `matrix(${this.ma},${this.mb},${this.mc},${this.md},${this.me},${this.mf})`;
     if (href) {
@@ -2285,4 +2334,7 @@ var TextRasterCache = (_class5 = class {
 
 
 
-exports.CanvasRenderer = CanvasRenderer; exports.sanitizeUrl = sanitizeUrl; exports.isSafeUrl = isSafeUrl; exports.SVGRenderer = SVGRenderer; exports.parseColorToRGBA = parseColorToRGBA; exports.createWebGLPointRenderer = createWebGLPointRenderer; exports.WebGPUParticleSystemManager = WebGPUParticleSystemManager; exports.GlyphRasterAtlas = GlyphRasterAtlas; exports.TextRasterCache = TextRasterCache;
+
+
+
+exports.setRendererDevMode = setRendererDevMode; exports.isRendererDevMode = isRendererDevMode; exports.installRendererDevTraps = installRendererDevTraps; exports.CanvasRenderer = CanvasRenderer; exports.sanitizeUrl = sanitizeUrl; exports.isSafeUrl = isSafeUrl; exports.SVGRenderer = SVGRenderer; exports.parseColorToRGBA = parseColorToRGBA; exports.createWebGLPointRenderer = createWebGLPointRenderer; exports.WebGPUParticleSystemManager = WebGPUParticleSystemManager; exports.GlyphRasterAtlas = GlyphRasterAtlas; exports.TextRasterCache = TextRasterCache;

package/dist/{chunk-I4WQY7CJ.mjs → chunk-TI5EMJGL.mjs}

@@ -1,3 +1,50 @@
+// src/renderer/IRenderer.ts
+var RENDERER_STYLE_PROPERTY_HINTS = {
+  globalAlpha: "setGlobalAlpha(alpha)",
+  strokeStyle: "stroke(color, lineWidth)",
+  lineWidth: "stroke(color, lineWidth)",
+  fillStyle: "fill(color) \u2014 or fillText(text, x, y, font, color)",
+  font: "fillText(text, x, y, font, color)",
+  lineCap: "stroke(color, lineWidth) (cap is backend-chosen)",
+  lineJoin: "stroke(color, lineWidth) (join is backend-chosen)",
+  globalCompositeOperation: "no equivalent \u2014 composite via a separate canvas",
+  shadowBlur: "no equivalent \u2014 draw the shadow explicitly",
+  shadowColor: "no equivalent \u2014 draw the shadow explicitly",
+  textAlign: "no equivalent \u2014 measure and offset x yourself",
+  textBaseline: "no equivalent \u2014 measure and offset y yourself"
+};
+var rendererDevMode = false;
+function setRendererDevMode(active) {
+  rendererDevMode = active;
+}
+function isRendererDevMode() {
+  if (rendererDevMode) return true;
+  const g = typeof globalThis !== "undefined" ? globalThis : void 0;
+  if (g?.__DEV__) return true;
+  return g?.process?.env?.NODE_ENV === "development";
+}
+function installRendererDevTraps(renderer, label) {
+  if (!isRendererDevMode()) return;
+  for (const [prop, hint] of Object.entries(RENDERER_STYLE_PROPERTY_HINTS)) {
+    if (prop in renderer) continue;
+    let stored;
+    let warned = false;
+    Object.defineProperty(renderer, prop, {
+      configurable: true,
+      enumerable: false,
+      get: () => stored,
+      set: (value) => {
+        stored = value;
+        if (warned) return;
+        warned = true;
+        console.warn(
+          `[vectojs/dev] \`${prop}\` is not a renderer property \u2014 assigning it on ${label} has no effect on what is drawn. Call \`${hint}\` instead.`
+        );
+      }
+    });
+  }
+}
+
 // src/renderer/CanvasRenderer.ts
 function emptyDrawCounters() {
   return {
@@ -90,6 +137,7 @@ var CanvasRenderer = class _CanvasRenderer {
     if (ctx) ctx.scale(dpr, dpr);
     this.canvas = canvas;
     this.setupContextLossRecovery();
+    installRendererDevTraps(this, "CanvasRenderer");
   }
   /** Register a callback fired after a lost 2D context is restored + re-scaled,
    *  so the owner can repaint (the restored canvas comes back cleared). */
@@ -489,6 +537,7 @@ var SVGRenderer = class {
   constructor(width, height) {
     this.width = width;
     this.height = height;
+    installRendererDevTraps(this, "SVGRenderer");
   }
   clear() {
     this.buffer = [];
@@ -2274,6 +2323,9 @@ var TextRasterCache = class {
 };
 
 export {
+  setRendererDevMode,
+  isRendererDevMode,
+  installRendererDevTraps,
   CanvasRenderer,
   sanitizeUrl,
   isSafeUrl,

package/dist/index.js

@@ -9,7 +9,10 @@
 
 
 
-var _chunkKHGHP2J3js = require('./chunk-KHGHP2J3.js');
+
+
+
+var _chunkK2UGEIT6js = require('./chunk-K2UGEIT6.js');
 
 
 
@@ -94,7 +97,7 @@ var ComputeParticleEntity = (_class = class extends _chunkZ3HFY75Rjs.Entity {
       this.particleData[idx + PARTICLE_OFFSET_LIFE] = -1;
     }
     this.needsInit = true;
-    _optionalChain([this, 'access', _ => _.scene, 'optionalAccess', _2 => _2.markDirty, 'call', _3 => _3()]);
+    _optionalChain([this, 'access', _2 => _2.scene, 'optionalAccess', _3 => _3.markDirty, 'call', _4 => _4()]);
   }
   /**
    * Sets the origins (ox, oy) for a subset or all particles.
@@ -120,7 +123,7 @@ var ComputeParticleEntity = (_class = class extends _chunkZ3HFY75Rjs.Entity {
       }
     }
     this.needsInit = true;
-    _optionalChain([this, 'access', _4 => _4.scene, 'optionalAccess', _5 => _5.markDirty, 'call', _6 => _6()]);
+    _optionalChain([this, 'access', _5 => _5.scene, 'optionalAccess', _6 => _6.markDirty, 'call', _7 => _7()]);
   }
   /**
    * Sets the current positions (x, y) for a subset or all particles.
@@ -136,7 +139,7 @@ var ComputeParticleEntity = (_class = class extends _chunkZ3HFY75Rjs.Entity {
       this.particleData[idx + PARTICLE_OFFSET_POSITION_Y] = positions[ptIdx + 1];
     }
     this.needsInit = true;
-    _optionalChain([this, 'access', _7 => _7.scene, 'optionalAccess', _8 => _8.markDirty, 'call', _9 => _9()]);
+    _optionalChain([this, 'access', _8 => _8.scene, 'optionalAccess', _9 => _9.markDirty, 'call', _10 => _10()]);
   }
   /**
    * Sets the current velocities (vx, vy) for a subset or all particles.
@@ -152,7 +155,7 @@ var ComputeParticleEntity = (_class = class extends _chunkZ3HFY75Rjs.Entity {
       this.particleData[idx + PARTICLE_OFFSET_VELOCITY_Y] = velocities[ptIdx + 1];
     }
     this.needsInit = true;
-    _optionalChain([this, 'access', _10 => _10.scene, 'optionalAccess', _11 => _11.markDirty, 'call', _12 => _12()]);
+    _optionalChain([this, 'access', _11 => _11.scene, 'optionalAccess', _12 => _12.markDirty, 'call', _13 => _13()]);
   }
   /**
    * Triggers an explosion force center.
@@ -1259,7 +1262,7 @@ var VECTO_USER_TIMING = {
 var nextSpanId = 0;
 function beginVectoUserTiming(name) {
   const candidate = globalThis.performance;
-  if (typeof _optionalChain([candidate, 'optionalAccess', _13 => _13.mark]) !== "function" || typeof candidate.measure !== "function") {
+  if (typeof _optionalChain([candidate, 'optionalAccess', _14 => _14.mark]) !== "function" || typeof candidate.measure !== "function") {
     return null;
   }
   const id = nextSpanId++;
@@ -1286,15 +1289,15 @@ function endVectoUserTiming(span) {
   } catch (e8) {
   } finally {
     try {
-      _optionalChain([timing, 'access', _14 => _14.clearMarks, 'optionalCall', _15 => _15(span.startMark)]);
-      _optionalChain([timing, 'access', _16 => _16.clearMarks, 'optionalCall', _17 => _17(span.endMark)]);
+      _optionalChain([timing, 'access', _15 => _15.clearMarks, 'optionalCall', _16 => _16(span.startMark)]);
+      _optionalChain([timing, 'access', _17 => _17.clearMarks, 'optionalCall', _18 => _18(span.endMark)]);
     } catch (e9) {
     }
   }
 }
 function measureVectoUserTiming(name, durationMs) {
   const candidate = globalThis.performance;
-  if (typeof _optionalChain([candidate, 'optionalAccess', _18 => _18.now]) !== "function" || typeof candidate.mark !== "function" || typeof candidate.measure !== "function") {
+  if (typeof _optionalChain([candidate, 'optionalAccess', _19 => _19.now]) !== "function" || typeof candidate.mark !== "function" || typeof candidate.measure !== "function") {
     return;
   }
   const id = nextSpanId++;
@@ -1309,8 +1312,8 @@ function measureVectoUserTiming(name, durationMs) {
   } catch (e10) {
   } finally {
     try {
-      _optionalChain([candidate, 'access', _19 => _19.clearMarks, 'optionalCall', _20 => _20(startMark)]);
-      _optionalChain([candidate, 'access', _21 => _21.clearMarks, 'optionalCall', _22 => _22(endMark)]);
+      _optionalChain([candidate, 'access', _20 => _20.clearMarks, 'optionalCall', _21 => _21(startMark)]);
+      _optionalChain([candidate, 'access', _22 => _22.clearMarks, 'optionalCall', _23 => _23(endMark)]);
     } catch (e11) {
     }
   }
@@ -1371,6 +1374,57 @@ function rebaseChildBox(parent, parentOriginX, parentOriginY, child, childOrigin
   REBASED_BOX.matrix = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
   return REBASED_BOX;
 }
+var SCENE_OPTION_KEYS = [
+  "a11ySyncInterval",
+  "autoThrottle",
+  "contentProjection",
+  "contentProjectionMargin",
+  "debugA11y",
+  "disableWindowResize",
+  "maxDPR",
+  "maxFPS",
+  "particleBackend",
+  "pointBackend",
+  "readingDirection",
+  "renderer",
+  "renderMode",
+  "respectReducedMotion",
+  "userTiming"
+];
+var SCENE_FIELD_NOT_OPTION = {
+  devMode: "set the static `Scene.devMode = true` before constructing"
+};
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0 || n === 0) return Math.max(m, n);
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  const curr = Array.from({ length: n + 1 });
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr.slice();
+  }
+  return prev[n];
+}
+function closestOptionKey(key) {
+  const lower = key.toLowerCase();
+  let best;
+  let bestScore = Infinity;
+  for (const candidate of SCENE_OPTION_KEYS) {
+    if (candidate.toLowerCase() === lower) return candidate;
+    const d = editDistance(lower, candidate.toLowerCase());
+    if (d < bestScore) {
+      bestScore = d;
+      best = candidate;
+    }
+  }
+  const limit = Math.max(2, Math.floor(key.length / 3));
+  return bestScore <= limit ? best : void 0;
+}
 var REDUCED_MOTION_FPS = 30;
 function parseInlinePx(value) {
   if (!value || !value.endsWith("px")) return null;
@@ -1456,9 +1510,9 @@ function parseCssMatrix(transform) {
 }
 function clientToGridLocal(contentEl, canvas, clientX, clientY) {
   const line = contentEl.querySelector("[data-vecto-grid-line]");
-  const originMarker = _optionalChain([line, 'optionalAccess', _23 => _23.querySelector, 'call', _24 => _24('[data-vecto-grid-basis="origin"]')]);
-  const xMarker = _optionalChain([line, 'optionalAccess', _25 => _25.querySelector, 'call', _26 => _26('[data-vecto-grid-basis="x"]')]);
-  const yMarker = _optionalChain([line, 'optionalAccess', _27 => _27.querySelector, 'call', _28 => _28('[data-vecto-grid-basis="y"]')]);
+  const originMarker = _optionalChain([line, 'optionalAccess', _24 => _24.querySelector, 'call', _25 => _25('[data-vecto-grid-basis="origin"]')]);
+  const xMarker = _optionalChain([line, 'optionalAccess', _26 => _26.querySelector, 'call', _27 => _27('[data-vecto-grid-basis="x"]')]);
+  const yMarker = _optionalChain([line, 'optionalAccess', _28 => _28.querySelector, 'call', _29 => _29('[data-vecto-grid-basis="y"]')]);
   if (line && originMarker && xMarker && yMarker) {
     const origin = originMarker.getBoundingClientRect();
     const xPoint = xMarker.getBoundingClientRect();
@@ -1542,7 +1596,7 @@ function nearestTextPositionInLine(line, x, y) {
       nearest = { position: { node, offset }, distance: candidate.distance };
     }
   }
-  return _nullishCoalesce(_optionalChain([nearest, 'optionalAccess', _29 => _29.position]), () => ( null));
+  return _nullishCoalesce(_optionalChain([nearest, 'optionalAccess', _30 => _30.position]), () => ( null));
 }
 function nearestTextPositionInProjection(contentEl, canvas, x, y, eventTarget) {
   if (contentEl.dataset.vectoContentGrid !== void 0) {
@@ -1556,7 +1610,7 @@ function nearestTextPositionInProjection(contentEl, canvas, x, y, eventTarget) {
     }
     targetLine = targetLine.parentElement;
   }
-  if (_optionalChain([targetLine, 'optionalAccess', _30 => _30.parentElement]) === contentEl) {
+  if (_optionalChain([targetLine, 'optionalAccess', _31 => _31.parentElement]) === contentEl) {
     return nearestTextPositionInLine(targetLine, x, y);
   }
   let bestLine = null;
@@ -1834,7 +1888,7 @@ var Scene = (_class7 = class _Scene {
   __init50() {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', _31 => _31.reducedMotionQuery, 'optionalAccess', _32 => _32.matches]);
+    return this.respectReducedMotion && !!_optionalChain([this, 'access', _32 => _32.reducedMotionQuery, 'optionalAccess', _33 => _33.matches]);
   }
   /**
    * True when the OS is in a forced-colors mode (Windows High Contrast, and the
@@ -1845,7 +1899,7 @@ var Scene = (_class7 = class _Scene {
    * when the setting toggles.
    */
   get forcedColors() {
-    return !!_optionalChain([this, 'access', _33 => _33.forcedColorsQuery, 'optionalAccess', _34 => _34.matches]);
+    return !!_optionalChain([this, 'access', _34 => _34.forcedColorsQuery, 'optionalAccess', _35 => _35.matches]);
   }
   /**
    * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
@@ -2281,7 +2335,7 @@ var Scene = (_class7 = class _Scene {
         const idx = cell[k];
         if (x < minx[idx] || x > maxx[idx] || y < miny[idx] || y > maxy[idx]) continue;
         const entity = this._hitSlotEntity[idx];
-        if (_optionalChain([entity, 'optionalAccess', _35 => _35.isPointInside, 'call', _36 => _36(x, y)]) && this.isHitEligible(entity, x, y)) {
+        if (_optionalChain([entity, 'optionalAccess', _36 => _36.isPointInside, 'call', _37 => _37(x, y)]) && this.isHitEligible(entity, x, y)) {
           bestIndex = idx;
           bestEntity = entity;
           break;
@@ -2752,7 +2806,7 @@ var Scene = (_class7 = class _Scene {
    * active.
    */
   get webglDrawStats() {
-    return _nullishCoalesce(_optionalChain([this, 'access', _37 => _37.pointRenderer, 'optionalAccess', _38 => _38.stats, 'optionalCall', _39 => _39()]), () => ( null));
+    return _nullishCoalesce(_optionalChain([this, 'access', _38 => _38.pointRenderer, 'optionalAccess', _39 => _39.stats, 'optionalCall', _40 => _40()]), () => ( null));
   }
   /**
    * Whether a WebGPU device is currently live for particle compute.
@@ -2789,13 +2843,29 @@ 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 __initStatic5() {this.devMode = false}
+  static __initStatic5() {this._devMode = false}
+  /**
+   * Toggle development-mode runtime warnings globally.
+   *
+   * An accessor rather than a plain field so the renderer layer learns about it
+   * immediately: renderers cannot import `Scene` (the dependency runs
+   * `Scene → renderer`), and their diagnostics are installed per instance at
+   * construction. A plain field would only reach them the next time a `Scene`
+   * happened to be built, which made a directly-constructed `CanvasRenderer`
+   * silently untrapped.
+   */
+  static get devMode() {
+    return _Scene._devMode;
+  }
+  static set devMode(active) {
+    _Scene._devMode = active;
+    _chunkK2UGEIT6js.setRendererDevMode.call(void 0, active);
+  }
   static _devModeDetected() {
-    if (_Scene.devMode) return true;
+    if (_Scene._devMode) return true;
     const gp = typeof globalThis !== "undefined" ? globalThis : void 0;
-    if (_optionalChain([gp, 'optionalAccess', _40 => _40.__DEV__])) return true;
-    if (_optionalChain([gp, 'optionalAccess', _41 => _41.process, 'optionalAccess', _42 => _42.env, 'optionalAccess', _43 => _43.NODE_ENV]) === "development") return true;
+    if (_optionalChain([gp, 'optionalAccess', _41 => _41.__DEV__])) return true;
+    if (_optionalChain([gp, 'optionalAccess', _42 => _42.process, 'optionalAccess', _43 => _43.env, 'optionalAccess', _44 => _44.NODE_ENV]) === "development") return true;
     return false;
   }
   
@@ -2804,6 +2874,37 @@ var Scene = (_class7 = class _Scene {
     if (!this._devActive) return;
     console.warn(`[vectojs/dev] ${message}`);
   }
+  /**
+   * Warn (dev mode only) about `SceneOptions` keys this version does not read.
+   *
+   * A structural type makes an unrecognized key a silent no-op, and TypeScript
+   * only rejects one when the object literal sits inline at the call site — not
+   * when options are built dynamically, and never in plain JS. Since the
+   * failure mode is "the option appears to work", a runtime check is the only
+   * thing that surfaces it.
+   *
+   * Dev-mode only on purpose: the loop is O(keys × known keys) with an edit
+   * distance per pair, which is nothing at construction but is still pure
+   * overhead in production, where the value has already been shipped.
+   */
+  _warnUnknownOptions(options) {
+    if (!this._devActive) return;
+    const known = new Set(SCENE_OPTION_KEYS);
+    for (const key of Object.keys(options)) {
+      if (known.has(key)) continue;
+      const fieldHint = SCENE_FIELD_NOT_OPTION[key];
+      if (fieldHint) {
+        this._devWarn(
+          `SceneOptions: \`${key}\` is not a constructor option \u2014 ${fieldHint}. Passing it here has no effect.`
+        );
+        continue;
+      }
+      const suggestion = closestOptionKey(key);
+      this._devWarn(
+        `SceneOptions: unknown option \`${key}\` is ignored.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : "")
+      );
+    }
+  }
   /** @internal Periodic dev checks — called once per frame in dev mode. */
   _devRunChecks() {
     this._devFrameCount++;
@@ -2826,9 +2927,9 @@ var Scene = (_class7 = class _Scene {
     let checked = 0;
     const walkProjections = (node) => {
       if (checked > 10) return;
-      const proj = _optionalChain([node, 'access', _44 => _44.getContentProjection, 'optionalCall', _45 => _45()]);
-      if (_optionalChain([proj, 'optionalAccess', _46 => _46.text]) && proj.selectable !== false) {
-        const el = _optionalChain([this, 'access', _47 => _47.contentElements, 'optionalAccess', _48 => _48.get, 'call', _49 => _49(node.id)]);
+      const proj = _optionalChain([node, 'access', _45 => _45.getContentProjection, 'optionalCall', _46 => _46()]);
+      if (_optionalChain([proj, 'optionalAccess', _47 => _47.text]) && proj.selectable !== false) {
+        const el = _optionalChain([this, 'access', _48 => _48.contentElements, 'optionalAccess', _49 => _49.get, 'call', _50 => _50(node.id)]);
         if (el) {
           const projectedText = el.textContent || "";
           if (projectedText !== "" && projectedText !== proj.text) {
@@ -2849,8 +2950,8 @@ var Scene = (_class7 = class _Scene {
     this.disableWindowResize = _nullishCoalesce(options.disableWindowResize, () => ( false));
     this.maxDPR = options.maxDPR;
     if (this.disableWindowResize) {
-      const styleWidth = parseInlinePx(_optionalChain([canvas, 'access', _50 => _50.style, 'optionalAccess', _51 => _51.width]));
-      const styleHeight = parseInlinePx(_optionalChain([canvas, 'access', _52 => _52.style, 'optionalAccess', _53 => _53.height]));
+      const styleWidth = parseInlinePx(_optionalChain([canvas, 'access', _51 => _51.style, 'optionalAccess', _52 => _52.width]));
+      const styleHeight = parseInlinePx(_optionalChain([canvas, 'access', _53 => _53.style, 'optionalAccess', _54 => _54.height]));
       this.width = _nullishCoalesce(styleWidth, () => ( (canvas.width || canvas.clientWidth || 0)));
       this.height = _nullishCoalesce(styleHeight, () => ( (canvas.height || canvas.clientHeight || 0)));
     } else {
@@ -2858,7 +2959,7 @@ var Scene = (_class7 = class _Scene {
       this.height = typeof window !== "undefined" ? window.innerHeight : canvas.clientHeight || canvas.height || 600;
     }
     const globalProcess = typeof globalThis !== "undefined" ? globalThis.process : void 0;
-    const isTest = globalProcess && (_optionalChain([globalProcess, 'access', _54 => _54.env, 'optionalAccess', _55 => _55.NODE_ENV]) === "test" || _optionalChain([globalProcess, 'access', _56 => _56.env, 'optionalAccess', _57 => _57.VITEST]) === "true");
+    const isTest = globalProcess && (_optionalChain([globalProcess, 'access', _55 => _55.env, 'optionalAccess', _56 => _56.NODE_ENV]) === "test" || _optionalChain([globalProcess, 'access', _57 => _57.env, 'optionalAccess', _58 => _58.VITEST]) === "true");
     this.maxFPS = _nullishCoalesce(options.maxFPS, () => ( (isTest ? 0 : 60)));
     this.respectReducedMotion = _nullishCoalesce(options.respectReducedMotion, () => ( true));
     this.autoThrottle = _nullishCoalesce(options.autoThrottle, () => ( true));
@@ -2868,12 +2969,15 @@ var Scene = (_class7 = class _Scene {
     this.contentProjectionEnabled = _nullishCoalesce(options.contentProjection, () => ( true));
     this.contentProjectionMargin = options.contentProjectionMargin;
     this.readingDirection = _nullishCoalesce(options.readingDirection, () => ( "ltr"));
+    this.renderMode = _nullishCoalesce(options.renderMode, () => ( "always"));
     this._devActive = _Scene._devModeDetected();
+    _chunkK2UGEIT6js.setRendererDevMode.call(void 0, this._devActive);
+    this._warnUnknownOptions(options);
     this.reducedMotionQuery = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
     if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
       this.forcedColorsQuery = window.matchMedia("(forced-colors: active)");
       this.forcedColorsChangeHandler = () => this.markDirty();
-      _optionalChain([this, 'access', _58 => _58.forcedColorsQuery, 'access', _59 => _59.addEventListener, 'optionalCall', _60 => _60("change", this.forcedColorsChangeHandler)]);
+      _optionalChain([this, 'access', _59 => _59.forcedColorsQuery, 'access', _60 => _60.addEventListener, 'optionalCall', _61 => _61("change", this.forcedColorsChangeHandler)]);
     }
     this.root = new class RootEntity extends _chunkZ3HFY75Rjs.Entity {
       isPointInside() {
@@ -2895,15 +2999,15 @@ var Scene = (_class7 = class _Scene {
     if (options.renderer) {
       this.renderer = options.renderer;
     } else {
-      this.renderer = new (0, _chunkKHGHP2J3js.CanvasRenderer)(
+      this.renderer = new (0, _chunkK2UGEIT6js.CanvasRenderer)(
         canvas,
         this.disableWindowResize ? { width: this.width, height: this.height } : void 0,
         this.maxDPR
       );
     }
-    _optionalChain([this, 'access', _61 => _61.renderer, 'access', _62 => _62.onContextRestored, 'optionalCall', _63 => _63(() => {
+    _optionalChain([this, 'access', _62 => _62.renderer, 'access', _63 => _63.onContextRestored, 'optionalCall', _64 => _64(() => {
       this.markDirty();
-      if (_optionalChain([this, 'access', _64 => _64.renderer, 'access', _65 => _65.isContextLost, 'optionalCall', _66 => _66()]) !== true) this.render(this.renderer);
+      if (_optionalChain([this, 'access', _65 => _65.renderer, 'access', _66 => _66.isContextLost, 'optionalCall', _67 => _67()]) !== true) this.render(this.renderer);
     })]);
     if (typeof document !== "undefined") {
       this.a11yRoot = document.createElement("div");
@@ -3073,7 +3177,7 @@ var Scene = (_class7 = class _Scene {
   watchDevicePixelRatio() {
     if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
     if (this.dprMediaQuery && this.dprChangeHandler) {
-      _optionalChain([this, 'access', _67 => _67.dprMediaQuery, 'access', _68 => _68.removeEventListener, 'optionalCall', _69 => _69("change", this.dprChangeHandler)]);
+      _optionalChain([this, 'access', _68 => _68.dprMediaQuery, 'access', _69 => _69.removeEventListener, 'optionalCall', _70 => _70("change", this.dprChangeHandler)]);
     }
     const dpr = window.devicePixelRatio || 1;
     const query = window.matchMedia(`(resolution: ${dpr}dppx)`);
@@ -3081,7 +3185,7 @@ var Scene = (_class7 = class _Scene {
       this.resize(this.width, this.height);
       this.watchDevicePixelRatio();
     };
-    _optionalChain([query, 'access', _70 => _70.addEventListener, 'optionalCall', _71 => _71("change", handler)]);
+    _optionalChain([query, 'access', _71 => _71.addEventListener, 'optionalCall', _72 => _72("change", handler)]);
     this.dprMediaQuery = query;
     this.dprChangeHandler = handler;
   }
@@ -3101,7 +3205,7 @@ var Scene = (_class7 = class _Scene {
     if (typeof gl.addEventListener !== "function") return;
     this.glContextLostHandler = (e) => {
       e.preventDefault();
-      _optionalChain([this, 'access', _72 => _72.pointRenderer, 'optionalAccess', _73 => _73.destroy, 'call', _74 => _74()]);
+      _optionalChain([this, 'access', _73 => _73.pointRenderer, 'optionalAccess', _74 => _74.destroy, 'call', _75 => _75()]);
       this.pointRenderer = null;
     };
     this.glContextRestoredHandler = () => {
@@ -3131,26 +3235,26 @@ var Scene = (_class7 = class _Scene {
    * to the live DOM selection.
    */
   contentGridSelectionLine(el) {
-    const candidates = [_optionalChain([this, 'access', _75 => _75.contentSelectionAnchor, 'optionalAccess', _76 => _76.node])];
+    const candidates = [_optionalChain([this, 'access', _76 => _76.contentSelectionAnchor, 'optionalAccess', _77 => _77.node])];
     if (typeof window !== "undefined" && typeof window.getSelection === "function") {
       const selection = window.getSelection();
-      candidates.push(_optionalChain([selection, 'optionalAccess', _77 => _77.anchorNode]), _optionalChain([selection, 'optionalAccess', _78 => _78.focusNode]));
+      candidates.push(_optionalChain([selection, 'optionalAccess', _78 => _78.anchorNode]), _optionalChain([selection, 'optionalAccess', _79 => _79.focusNode]));
     }
     for (const candidate of candidates) {
       if (!candidate || !el.contains(candidate)) continue;
       let cursor = candidate;
       while (cursor && cursor.parentNode !== el) cursor = cursor.parentNode;
-      const lineIndex = _optionalChain([cursor, 'optionalAccess', _79 => _79.dataset, 'optionalAccess', _80 => _80.vectoGridLine]);
+      const lineIndex = _optionalChain([cursor, 'optionalAccess', _80 => _80.dataset, 'optionalAccess', _81 => _81.vectoGridLine]);
       if (lineIndex !== void 0) return Number(lineIndex);
     }
     return null;
   }
   releaseContentSelectionForRebuild(el) {
     const selection = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
-    const ownsSelection = this.contentSelectionAnchor && el.contains(this.contentSelectionAnchor.node) || (_optionalChain([selection, 'optionalAccess', _81 => _81.anchorNode]) ? el.contains(selection.anchorNode) : false) || (_optionalChain([selection, 'optionalAccess', _82 => _82.focusNode]) ? el.contains(selection.focusNode) : false);
+    const ownsSelection = this.contentSelectionAnchor && el.contains(this.contentSelectionAnchor.node) || (_optionalChain([selection, 'optionalAccess', _82 => _82.anchorNode]) ? el.contains(selection.anchorNode) : false) || (_optionalChain([selection, 'optionalAccess', _83 => _83.focusNode]) ? el.contains(selection.focusNode) : false);
     if (!ownsSelection) return;
     this.endContentSelectionDrag();
-    _optionalChain([selection, 'optionalAccess', _83 => _83.removeAllRanges, 'call', _84 => _84()]);
+    _optionalChain([selection, 'optionalAccess', _84 => _84.removeAllRanges, 'call', _85 => _85()]);
   }
   /**
    * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -3209,7 +3313,7 @@ var Scene = (_class7 = class _Scene {
   }
   /** Convert browser viewport coordinates into this Scene's logical coordinates. */
   clientToScene(clientX, clientY) {
-    const rect = _optionalChain([this, 'access', _85 => _85.canvas, 'access', _86 => _86.getBoundingClientRect, 'optionalCall', _87 => _87()]);
+    const rect = _optionalChain([this, 'access', _86 => _86.canvas, 'access', _87 => _87.getBoundingClientRect, 'optionalCall', _88 => _88()]);
     if (!rect) return { x: clientX, y: clientY };
     const cssWidth = rect.width || this.canvas.clientWidth || this.width;
     const cssHeight = rect.height || this.canvas.clientHeight || this.height;
@@ -3247,7 +3351,7 @@ var Scene = (_class7 = class _Scene {
       cancelAnimationFrame(calibrationFrame);
     }
     this.contentGridCalibrationFrames.delete(entityId);
-    _optionalChain([this, 'access', _88 => _88.contentGridCalibrationProbes, 'access', _89 => _89.get, 'call', _90 => _90(entityId), 'optionalAccess', _91 => _91.remove, 'call', _92 => _92()]);
+    _optionalChain([this, 'access', _89 => _89.contentGridCalibrationProbes, 'access', _90 => _90.get, 'call', _91 => _91(entityId), 'optionalAccess', _92 => _92.remove, 'call', _93 => _93()]);
     this.contentGridCalibrationProbes.delete(entityId);
     delete el.dataset.vectoGridCalibrationPending;
     delete el.dataset.vectoGridCalibration;
@@ -3401,12 +3505,12 @@ var Scene = (_class7 = class _Scene {
       this.canvasResizeObserver = null;
     }
     if (this.dprMediaQuery && this.dprChangeHandler) {
-      _optionalChain([this, 'access', _93 => _93.dprMediaQuery, 'access', _94 => _94.removeEventListener, 'optionalCall', _95 => _95("change", this.dprChangeHandler)]);
+      _optionalChain([this, 'access', _94 => _94.dprMediaQuery, 'access', _95 => _95.removeEventListener, 'optionalCall', _96 => _96("change", this.dprChangeHandler)]);
       this.dprMediaQuery = null;
       this.dprChangeHandler = null;
     }
     if (this.forcedColorsQuery && this.forcedColorsChangeHandler) {
-      _optionalChain([this, 'access', _96 => _96.forcedColorsQuery, 'access', _97 => _97.removeEventListener, 'optionalCall', _98 => _98("change", this.forcedColorsChangeHandler)]);
+      _optionalChain([this, 'access', _97 => _97.forcedColorsQuery, 'access', _98 => _98.removeEventListener, 'optionalCall', _99 => _99("change", this.forcedColorsChangeHandler)]);
       this.forcedColorsQuery = null;
       this.forcedColorsChangeHandler = null;
     }
@@ -3424,9 +3528,9 @@ var Scene = (_class7 = class _Scene {
       }
       this.pointerEventTarget = null;
     }
-    _optionalChain([this, 'access', _99 => _99.a11yRoot, 'optionalAccess', _100 => _100.remove, 'call', _101 => _101()]);
+    _optionalChain([this, 'access', _100 => _100.a11yRoot, 'optionalAccess', _101 => _101.remove, 'call', _102 => _102()]);
     this.focusSentinel = null;
-    _optionalChain([this, 'access', _102 => _102.portalRoot, 'optionalAccess', _103 => _103.remove, 'call', _104 => _104()]);
+    _optionalChain([this, 'access', _103 => _103.portalRoot, 'optionalAccess', _104 => _104.remove, 'call', _105 => _105()]);
     this.a11yElements.clear();
     for (const el of this.contentElements.values()) el.remove();
     this.contentElements.clear();
@@ -3449,10 +3553,10 @@ var Scene = (_class7 = class _Scene {
     }
     this.glContextLostHandler = null;
     this.glContextRestoredHandler = null;
-    _optionalChain([this, 'access', _105 => _105.pointRenderer, 'optionalAccess', _106 => _106.destroy, 'call', _107 => _107()]);
-    _optionalChain([this, 'access', _108 => _108.renderer, 'access', _109 => _109.dispose, 'optionalCall', _110 => _110()]);
-    _optionalChain([this, 'access', _111 => _111.glCanvas, 'optionalAccess', _112 => _112.remove, 'call', _113 => _113()]);
-    _optionalChain([this, 'access', _114 => _114.gpuCanvas, 'optionalAccess', _115 => _115.remove, 'call', _116 => _116()]);
+    _optionalChain([this, 'access', _106 => _106.pointRenderer, 'optionalAccess', _107 => _107.destroy, 'call', _108 => _108()]);
+    _optionalChain([this, 'access', _109 => _109.renderer, 'access', _110 => _110.dispose, 'optionalCall', _111 => _111()]);
+    _optionalChain([this, 'access', _112 => _112.glCanvas, 'optionalAccess', _113 => _113.remove, 'call', _114 => _114()]);
+    _optionalChain([this, 'access', _115 => _115.gpuCanvas, 'optionalAccess', _116 => _116.remove, 'call', _117 => _117()]);
     this.gpuCanvas = null;
     this.gpuContext = null;
     if (this.recoveryTimerId) {
@@ -3464,7 +3568,7 @@ var Scene = (_class7 = class _Scene {
       this.manager = null;
     }
     if (this.device) {
-      _optionalChain([this, 'access', _117 => _117.device, 'access', _118 => _118.destroy, 'optionalCall', _119 => _119()]);
+      _optionalChain([this, 'access', _118 => _118.device, 'access', _119 => _119.destroy, 'optionalCall', _120 => _120()]);
       this.device = null;
     }
   }
@@ -3897,7 +4001,7 @@ var Scene = (_class7 = class _Scene {
           el.addEventListener("compositionupdate", (e) => {
             const data = _nullishCoalesce(e.data, () => ( ""));
             composition = {
-              start: _nullishCoalesce(_optionalChain([composition, 'optionalAccess', _120 => _120.start]), () => ( 0)),
+              start: _nullishCoalesce(_optionalChain([composition, 'optionalAccess', _121 => _121.start]), () => ( 0)),
               length: data.length
             };
             forward();
@@ -3970,7 +4074,7 @@ var Scene = (_class7 = class _Scene {
         this.syncOptionalAttribute(
           el,
           "href",
-          attrs.href === void 0 ? void 0 : _chunkKHGHP2J3js.sanitizeUrl.call(void 0, attrs.href)
+          attrs.href === void 0 ? void 0 : _chunkK2UGEIT6js.sanitizeUrl.call(void 0, attrs.href)
         );
         this.syncOptionalAttribute(el, "target", attrs.target);
       }
@@ -4376,9 +4480,9 @@ var Scene = (_class7 = class _Scene {
       for (let lineIndex = 0; lineIndex < grid.lines.length; lineIndex++) {
         const gridLine = grid.lines[lineIndex];
         const projectedLine = projectionLines[lineIndex];
-        const lineHeight = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _121 => _121.lineHeight]), () => ( grid.lineHeight));
-        const baseline = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _122 => _122.baseline]), () => ( grid.baseline));
-        const lineFont = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _123 => _123.font]), () => ( grid.font));
+        const lineHeight = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _122 => _122.lineHeight]), () => ( grid.lineHeight));
+        const baseline = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _123 => _123.baseline]), () => ( grid.baseline));
+        const lineFont = _nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _124 => _124.font]), () => ( grid.font));
         const lineSignature = contentGridLineSignature(
           grid,
           gridLine,
@@ -4398,8 +4502,8 @@ var Scene = (_class7 = class _Scene {
         lineElement.dir = "ltr";
         lineElement.dataset.vectoGridLine = `${lineIndex}`;
         lineElement.style.position = "absolute";
-        lineElement.style.left = `${_nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _124 => _124.x]), () => ( 0))}px`;
-        lineElement.style.top = `${(_nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _125 => _125.y]), () => ( lineIndex * grid.lineHeight))) + baseline - _text.cssLineBoxBaseline.call(void 0, lineFont, lineHeight)}px`;
+        lineElement.style.left = `${_nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _125 => _125.x]), () => ( 0))}px`;
+        lineElement.style.top = `${(_nullishCoalesce(_optionalChain([projectedLine, 'optionalAccess', _126 => _126.y]), () => ( lineIndex * grid.lineHeight))) + baseline - _text.cssLineBoxBaseline.call(void 0, lineFont, lineHeight)}px`;
         lineElement.style.width = `${gridLine.width}px`;
         lineElement.style.height = `${lineHeight}px`;
         lineElement.style.whiteSpace = "pre";
@@ -4469,7 +4573,7 @@ var Scene = (_class7 = class _Scene {
         if (selectionLine !== null && selectionLine >= grid.lines.length) {
           rebuiltSelectionLine = true;
         }
-        _optionalChain([el, 'access', _126 => _126.lastElementChild, 'optionalAccess', _127 => _127.remove, 'call', _128 => _128()]);
+        _optionalChain([el, 'access', _127 => _127.lastElementChild, 'optionalAccess', _128 => _128.remove, 'call', _129 => _129()]);
       }
       if (rebuiltSelectionLine) this.releaseContentSelectionForRebuild(el);
       el.dataset.vectoProjectionLines = signature;
@@ -4533,7 +4637,7 @@ var Scene = (_class7 = class _Scene {
     if (previous !== void 0 && typeof cancelAnimationFrame === "function") {
       cancelAnimationFrame(previous);
     }
-    _optionalChain([this, 'access', _129 => _129.contentGridCalibrationProbes, 'access', _130 => _130.get, 'call', _131 => _131(entityId), 'optionalAccess', _132 => _132.remove, 'call', _133 => _133()]);
+    _optionalChain([this, 'access', _130 => _130.contentGridCalibrationProbes, 'access', _131 => _131.get, 'call', _132 => _132(entityId), 'optionalAccess', _133 => _133.remove, 'call', _134 => _134()]);
     this.contentGridCalibrationProbes.delete(entityId);
     const calibrationStart = typeof performance !== "undefined" ? performance.now() : 0;
     const probe = document.createElement("div");
@@ -4567,7 +4671,7 @@ var Scene = (_class7 = class _Scene {
         target.dataset.vectoGridCalib = generation;
         continue;
       }
-      const sourceText = _nullishCoalesce(_optionalChain([target, 'access', _134 => _134.textContent, 'optionalAccess', _135 => _135.slice, 'call', _136 => _136(0, sourceLength)]), () => ( ""));
+      const sourceText = _nullishCoalesce(_optionalChain([target, 'access', _135 => _135.textContent, 'optionalAccess', _136 => _136.slice, 'call', _137 => _137(0, sourceLength)]), () => ( ""));
       if (!sourceText) {
         target.dataset.vectoGridCalib = generation;
         continue;
@@ -4794,12 +4898,12 @@ var Scene = (_class7 = class _Scene {
   syncOverlayGeometry() {
     const parent = this.canvas.parentElement;
     if (!parent) return;
-    const canvasRect = _optionalChain([this, 'access', _137 => _137.canvas, 'access', _138 => _138.getBoundingClientRect, 'optionalCall', _139 => _139()]);
-    const parentRect = _optionalChain([parent, 'access', _140 => _140.getBoundingClientRect, 'optionalCall', _141 => _141()]);
-    const cssWidth = _optionalChain([canvasRect, 'optionalAccess', _142 => _142.width]) || this.canvas.clientWidth || this.width;
-    const cssHeight = _optionalChain([canvasRect, 'optionalAccess', _143 => _143.height]) || this.canvas.clientHeight || this.height;
-    const left = (_nullishCoalesce(_optionalChain([canvasRect, 'optionalAccess', _144 => _144.left]), () => ( 0))) - (_nullishCoalesce(_optionalChain([parentRect, 'optionalAccess', _145 => _145.left]), () => ( 0))) - (parent.clientLeft || 0) + parent.scrollLeft;
-    const top = (_nullishCoalesce(_optionalChain([canvasRect, 'optionalAccess', _146 => _146.top]), () => ( 0))) - (_nullishCoalesce(_optionalChain([parentRect, 'optionalAccess', _147 => _147.top]), () => ( 0))) - (parent.clientTop || 0) + parent.scrollTop;
+    const canvasRect = _optionalChain([this, 'access', _138 => _138.canvas, 'access', _139 => _139.getBoundingClientRect, 'optionalCall', _140 => _140()]);
+    const parentRect = _optionalChain([parent, 'access', _141 => _141.getBoundingClientRect, 'optionalCall', _142 => _142()]);
+    const cssWidth = _optionalChain([canvasRect, 'optionalAccess', _143 => _143.width]) || this.canvas.clientWidth || this.width;
+    const cssHeight = _optionalChain([canvasRect, 'optionalAccess', _144 => _144.height]) || this.canvas.clientHeight || this.height;
+    const left = (_nullishCoalesce(_optionalChain([canvasRect, 'optionalAccess', _145 => _145.left]), () => ( 0))) - (_nullishCoalesce(_optionalChain([parentRect, 'optionalAccess', _146 => _146.left]), () => ( 0))) - (parent.clientLeft || 0) + parent.scrollLeft;
+    const top = (_nullishCoalesce(_optionalChain([canvasRect, 'optionalAccess', _147 => _147.top]), () => ( 0))) - (_nullishCoalesce(_optionalChain([parentRect, 'optionalAccess', _148 => _148.top]), () => ( 0))) - (parent.clientTop || 0) + parent.scrollTop;
     const scaleX = this.width > 0 ? cssWidth / this.width : 1;
     const scaleY = this.height > 0 ? cssHeight / this.height : 1;
     const prev = this._overlayGeometry;
@@ -4938,7 +5042,7 @@ var Scene = (_class7 = class _Scene {
    * (and {@link respectReducedMotion} is on). `0` means uncapped.
    */
   effectiveMaxFPS() {
-    const reduced = this.respectReducedMotion && !!_optionalChain([this, 'access', _148 => _148.reducedMotionQuery, 'optionalAccess', _149 => _149.matches]);
+    const reduced = this.respectReducedMotion && !!_optionalChain([this, 'access', _149 => _149.reducedMotionQuery, 'optionalAccess', _150 => _150.matches]);
     if (reduced)
       return this.maxFPS > 0 ? Math.min(this.maxFPS, REDUCED_MOTION_FPS) : REDUCED_MOTION_FPS;
     return this.maxFPS;
@@ -5033,7 +5137,7 @@ var Scene = (_class7 = class _Scene {
    * @param time - Current absolute time in milliseconds (default 0).
    */
   render(renderer, dt = 0, time = 0) {
-    if (_optionalChain([renderer, 'access', _150 => _150.isContextLost, 'optionalCall', _151 => _151()])) return;
+    if (_optionalChain([renderer, 'access', _151 => _151.isContextLost, 'optionalCall', _152 => _152()])) return;
     const isMainRenderer = renderer === this.renderer;
     if (isMainRenderer && this.a11yRoot && this.canvas.parentElement) {
       const parentStyle = this.canvas.parentElement.style;
@@ -5177,7 +5281,7 @@ var Scene = (_class7 = class _Scene {
     }
     renderer.clear();
     if (isMainRenderer) {
-      _optionalChain([this, 'access', _152 => _152.pointRenderer, 'optionalAccess', _153 => _153.begin, 'call', _154 => _154()]);
+      _optionalChain([this, 'access', _153 => _153.pointRenderer, 'optionalAccess', _154 => _154.begin, 'call', _155 => _155()]);
     }
     const vw = this.width;
     const vh = this.height;
@@ -5391,9 +5495,9 @@ var Scene = (_class7 = class _Scene {
     const flushT0 = this._phaseTiming ? performance.now() : 0;
     renderer.flush();
     if (isMainRenderer) {
-      _optionalChain([this, 'access', _155 => _155.pointRenderer, 'optionalAccess', _156 => _156.flush, 'call', _157 => _157()]);
+      _optionalChain([this, 'access', _156 => _156.pointRenderer, 'optionalAccess', _157 => _157.flush, 'call', _158 => _158()]);
     }
-    _optionalChain([renderer, 'access', _158 => _158.present, 'optionalCall', _159 => _159()]);
+    _optionalChain([renderer, 'access', _159 => _159.present, 'optionalCall', _160 => _160()]);
     if (this._phaseTiming) this._recordPhase("flush", performance.now() - flushT0);
     if (flushTiming) endVectoUserTiming(flushTiming);
     if (this._devActive) {
@@ -5405,7 +5509,7 @@ var Scene = (_class7 = class _Scene {
    * Export the current scene state to a lightweight, flat SVG XML string.
    */
   toSVG() {
-    const renderer = new (0, _chunkKHGHP2J3js.SVGRenderer)(this.width, this.height);
+    const renderer = new (0, _chunkK2UGEIT6js.SVGRenderer)(this.width, this.height);
     this.render(renderer, 0, 0);
     return renderer.toXMLString();
   }
@@ -5674,8 +5778,8 @@ function pointInBounds(b, x, y) {
 function contentGridLineSignature(grid, line, projected, lineHeight, baseline, font, isFirstLine) {
   const parts = [
     // Line box: position, size, and the font that resolves its baseline.
-    `${_nullishCoalesce(_optionalChain([projected, 'optionalAccess', _160 => _160.x]), () => ( 0))}`,
-    `${_nullishCoalesce(_optionalChain([projected, 'optionalAccess', _161 => _161.y]), () => ( ""))}`,
+    `${_nullishCoalesce(_optionalChain([projected, 'optionalAccess', _161 => _161.x]), () => ( 0))}`,
+    `${_nullishCoalesce(_optionalChain([projected, 'optionalAccess', _162 => _162.y]), () => ( ""))}`,
     `${lineHeight}`,
     `${baseline}`,
     font,
@@ -5862,7 +5966,7 @@ var GridTextEntity = (_class9 = class extends _chunkZ3HFY75Rjs.Entity {
   updateGrid(ascii) {
     this.grid = ascii;
     this.rows = ascii.length;
-    this.cols = _optionalChain([ascii, 'access', _162 => _162[0], 'optionalAccess', _163 => _163.length]) || 0;
+    this.cols = _optionalChain([ascii, 'access', _163 => _163[0], 'optionalAccess', _164 => _164.length]) || 0;
   }
   isPointInside(_globalX, _globalY) {
     return false;
@@ -5972,7 +6076,7 @@ var SplineEntity = (_class10 = class extends _chunkZ3HFY75Rjs.Entity {
     this.width = this.bounds.width;
     this.height = this.bounds.height;
     const isGradient = (c) => c !== null && !Array.isArray(c);
-    this.containsGradient = (_nullishCoalesce(_optionalChain([this, 'access', _164 => _164.doc, 'access', _165 => _165.equations, 'optionalAccess', _166 => _166.some, 'call', _167 => _167((eq) => isGradient(eq.color_rgb))]), () => ( false))) || (_nullishCoalesce(_optionalChain([this, 'access', _168 => _168.doc, 'access', _169 => _169.paths, 'optionalAccess', _170 => _170.some, 'call', _171 => _171((p) => isGradient(p.color_rgb))]), () => ( false)));
+    this.containsGradient = (_nullishCoalesce(_optionalChain([this, 'access', _165 => _165.doc, 'access', _166 => _166.equations, 'optionalAccess', _167 => _167.some, 'call', _168 => _168((eq) => isGradient(eq.color_rgb))]), () => ( false))) || (_nullishCoalesce(_optionalChain([this, 'access', _169 => _169.doc, 'access', _170 => _170.paths, 'optionalAccess', _171 => _171.some, 'call', _172 => _172((p) => isGradient(p.color_rgb))]), () => ( false)));
     this.interactive = true;
   }
   computeBounds() {
@@ -6466,8 +6570,12 @@ var DOMPortalEntity = (_class11 = class extends _chunkZ3HFY75Rjs.Entity {
 }, _class11);
 
 // src/index.ts
-Scene.registerWebGLPointRendererCreator(_chunkKHGHP2J3js.createWebGLPointRenderer);
-Scene.registerWebGPUParticleSystemManager(_chunkKHGHP2J3js.WebGPUParticleSystemManager);
+Scene.registerWebGLPointRendererCreator(_chunkK2UGEIT6js.createWebGLPointRenderer);
+Scene.registerWebGPUParticleSystemManager(_chunkK2UGEIT6js.WebGPUParticleSystemManager);
+
+
+
+
 
 
 
@@ -6507,4 +6615,4 @@ Scene.registerWebGPUParticleSystemManager(_chunkKHGHP2J3js.WebGPUParticleSystemM
 
 
 
-exports.CanvasRenderer = _chunkKHGHP2J3js.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkZ3HFY75Rjs.Entity; exports.GlyphRasterAtlas = _chunkKHGHP2J3js.GlyphRasterAtlas; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkZ3HFY75Rjs.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 = _chunkZ3HFY75Rjs.SVGEntity; exports.SVGRenderer = _chunkKHGHP2J3js.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkKHGHP2J3js.TextRasterCache; exports.VECTO_USER_TIMING = VECTO_USER_TIMING; exports.VectoJSEvent = _chunkZ3HFY75Rjs.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkKHGHP2J3js.WebGPUParticleSystemManager; exports.beginVectoUserTiming = beginVectoUserTiming; exports.createWebGLPointRenderer = _chunkKHGHP2J3js.createWebGLPointRenderer; exports.endVectoUserTiming = endVectoUserTiming; exports.isSafeUrl = _chunkKHGHP2J3js.isSafeUrl; exports.loadSpline = loadSpline; exports.measureVectoUserTiming = measureVectoUserTiming; exports.parseColorToRGBA = _chunkKHGHP2J3js.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkKHGHP2J3js.sanitizeUrl;
+exports.CanvasRenderer = _chunkK2UGEIT6js.CanvasRenderer; exports.Circle = Circle; exports.ComputeParticleEntity = ComputeParticleEntity; exports.DOMPortalEntity = DOMPortalEntity; exports.Entity = _chunkZ3HFY75Rjs.Entity; exports.GlyphRasterAtlas = _chunkK2UGEIT6js.GlyphRasterAtlas; exports.GridTextEntity = GridTextEntity; exports.Group = Group; exports.MSDFTextEntity = _chunkZ3HFY75Rjs.MSDFTextEntity; exports.PARTICLE_OFFSET_LIFE = PARTICLE_OFFSET_LIFE; exports.PARTICLE_OFFSET_ORIGIN_X = PARTICLE_OFFSET_ORIGIN_X; exports.PARTICLE_OFFSET_ORIGIN_Y = PARTICLE_OFFSET_ORIGIN_Y; exports.PARTICLE_OFFSET_POSITION_X = PARTICLE_OFFSET_POSITION_X; exports.PARTICLE_OFFSET_POSITION_Y = PARTICLE_OFFSET_POSITION_Y; exports.PARTICLE_OFFSET_SIZE = PARTICLE_OFFSET_SIZE; exports.PARTICLE_OFFSET_VELOCITY_X = PARTICLE_OFFSET_VELOCITY_X; exports.PARTICLE_OFFSET_VELOCITY_Y = PARTICLE_OFFSET_VELOCITY_Y; exports.PARTICLE_STRIDE_FLOATS = PARTICLE_STRIDE_FLOATS; exports.REDUCED_MOTION_FPS = REDUCED_MOTION_FPS; exports.Rect = Rect; exports.SCENE_OPTION_KEYS = SCENE_OPTION_KEYS; exports.SVGEntity = _chunkZ3HFY75Rjs.SVGEntity; exports.SVGRenderer = _chunkK2UGEIT6js.SVGRenderer; exports.Scene = Scene; exports.SplineEntity = SplineEntity; exports.TextEntity = TextEntity; exports.TextRasterCache = _chunkK2UGEIT6js.TextRasterCache; exports.VECTO_USER_TIMING = VECTO_USER_TIMING; exports.VectoJSEvent = _chunkZ3HFY75Rjs.VectoJSEvent; exports.WebGPUParticleSystemManager = _chunkK2UGEIT6js.WebGPUParticleSystemManager; exports.beginVectoUserTiming = beginVectoUserTiming; exports.createWebGLPointRenderer = _chunkK2UGEIT6js.createWebGLPointRenderer; exports.endVectoUserTiming = endVectoUserTiming; exports.installRendererDevTraps = _chunkK2UGEIT6js.installRendererDevTraps; exports.isRendererDevMode = _chunkK2UGEIT6js.isRendererDevMode; exports.isSafeUrl = _chunkK2UGEIT6js.isSafeUrl; exports.loadSpline = loadSpline; exports.measureVectoUserTiming = measureVectoUserTiming; exports.parseColorToRGBA = _chunkK2UGEIT6js.parseColorToRGBA; exports.polySegmentToBezier = polySegmentToBezier; exports.sanitizeUrl = _chunkK2UGEIT6js.sanitizeUrl; exports.setRendererDevMode = _chunkK2UGEIT6js.setRendererDevMode;

package/dist/index.mjs

@@ -5,10 +5,13 @@ import {
   TextRasterCache,
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
+  installRendererDevTraps,
+  isRendererDevMode,
   isSafeUrl,
   parseColorToRGBA,
-  sanitizeUrl
-} from "./chunk-I4WQY7CJ.mjs";
+  sanitizeUrl,
+  setRendererDevMode
+} from "./chunk-TI5EMJGL.mjs";
 import {
   Entity,
   MSDFTextEntity,
@@ -1370,6 +1373,57 @@ function rebaseChildBox(parent, parentOriginX, parentOriginY, child, childOrigin
   REBASED_BOX.matrix = `matrix(${a}, ${b}, ${c}, ${d}, 0, 0)`;
   return REBASED_BOX;
 }
+var SCENE_OPTION_KEYS = [
+  "a11ySyncInterval",
+  "autoThrottle",
+  "contentProjection",
+  "contentProjectionMargin",
+  "debugA11y",
+  "disableWindowResize",
+  "maxDPR",
+  "maxFPS",
+  "particleBackend",
+  "pointBackend",
+  "readingDirection",
+  "renderer",
+  "renderMode",
+  "respectReducedMotion",
+  "userTiming"
+];
+var SCENE_FIELD_NOT_OPTION = {
+  devMode: "set the static `Scene.devMode = true` before constructing"
+};
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0 || n === 0) return Math.max(m, n);
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  const curr = Array.from({ length: n + 1 });
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr.slice();
+  }
+  return prev[n];
+}
+function closestOptionKey(key) {
+  const lower = key.toLowerCase();
+  let best;
+  let bestScore = Infinity;
+  for (const candidate of SCENE_OPTION_KEYS) {
+    if (candidate.toLowerCase() === lower) return candidate;
+    const d = editDistance(lower, candidate.toLowerCase());
+    if (d < bestScore) {
+      bestScore = d;
+      best = candidate;
+    }
+  }
+  const limit = Math.max(2, Math.floor(key.length / 3));
+  return bestScore <= limit ? best : void 0;
+}
 var REDUCED_MOTION_FPS = 30;
 function parseInlinePx(value) {
   if (!value || !value.endsWith("px")) return null;
@@ -2788,10 +2842,26 @@ var Scene = 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 devMode = false;
+  static _devMode = false;
+  /**
+   * Toggle development-mode runtime warnings globally.
+   *
+   * An accessor rather than a plain field so the renderer layer learns about it
+   * immediately: renderers cannot import `Scene` (the dependency runs
+   * `Scene → renderer`), and their diagnostics are installed per instance at
+   * construction. A plain field would only reach them the next time a `Scene`
+   * happened to be built, which made a directly-constructed `CanvasRenderer`
+   * silently untrapped.
+   */
+  static get devMode() {
+    return _Scene._devMode;
+  }
+  static set devMode(active) {
+    _Scene._devMode = active;
+    setRendererDevMode(active);
+  }
   static _devModeDetected() {
-    if (_Scene.devMode) return true;
+    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;
@@ -2803,6 +2873,37 @@ var Scene = class _Scene {
     if (!this._devActive) return;
     console.warn(`[vectojs/dev] ${message}`);
   }
+  /**
+   * Warn (dev mode only) about `SceneOptions` keys this version does not read.
+   *
+   * A structural type makes an unrecognized key a silent no-op, and TypeScript
+   * only rejects one when the object literal sits inline at the call site — not
+   * when options are built dynamically, and never in plain JS. Since the
+   * failure mode is "the option appears to work", a runtime check is the only
+   * thing that surfaces it.
+   *
+   * Dev-mode only on purpose: the loop is O(keys × known keys) with an edit
+   * distance per pair, which is nothing at construction but is still pure
+   * overhead in production, where the value has already been shipped.
+   */
+  _warnUnknownOptions(options) {
+    if (!this._devActive) return;
+    const known = new Set(SCENE_OPTION_KEYS);
+    for (const key of Object.keys(options)) {
+      if (known.has(key)) continue;
+      const fieldHint = SCENE_FIELD_NOT_OPTION[key];
+      if (fieldHint) {
+        this._devWarn(
+          `SceneOptions: \`${key}\` is not a constructor option \u2014 ${fieldHint}. Passing it here has no effect.`
+        );
+        continue;
+      }
+      const suggestion = closestOptionKey(key);
+      this._devWarn(
+        `SceneOptions: unknown option \`${key}\` is ignored.` + (suggestion ? ` Did you mean \`${suggestion}\`?` : "")
+      );
+    }
+  }
   /** @internal Periodic dev checks — called once per frame in dev mode. */
   _devRunChecks() {
     this._devFrameCount++;
@@ -2867,7 +2968,10 @@ var Scene = class _Scene {
     this.contentProjectionEnabled = options.contentProjection ?? true;
     this.contentProjectionMargin = options.contentProjectionMargin;
     this.readingDirection = options.readingDirection ?? "ltr";
+    this.renderMode = options.renderMode ?? "always";
     this._devActive = _Scene._devModeDetected();
+    setRendererDevMode(this._devActive);
+    this._warnUnknownOptions(options);
     this.reducedMotionQuery = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
     if (typeof window !== "undefined" && typeof window.matchMedia === "function") {
       this.forcedColorsQuery = window.matchMedia("(forced-colors: active)");
@@ -6488,6 +6592,7 @@ export {
   PARTICLE_STRIDE_FLOATS,
   REDUCED_MOTION_FPS,
   Rect,
+  SCENE_OPTION_KEYS,
   SVGEntity,
   SVGRenderer,
   Scene,
@@ -6500,10 +6605,13 @@ export {
   beginVectoUserTiming,
   createWebGLPointRenderer,
   endVectoUserTiming,
+  installRendererDevTraps,
+  isRendererDevMode,
   isSafeUrl,
   loadSpline,
   measureVectoUserTiming,
   parseColorToRGBA,
   polySegmentToBezier,
-  sanitizeUrl
+  sanitizeUrl,
+  setRendererDevMode
 };

package/dist/renderer/IRenderer.d.ts

@@ -299,3 +299,25 @@ export interface IRenderer {
      */
     onContextRestored?(cb: () => void): void;
 }
+/**
+ * Publish dev-mode state to the renderer layer. Called by `Scene`; also usable
+ * directly when a renderer is constructed without one.
+ */
+export declare function setRendererDevMode(active: boolean): void;
+/** Whether renderer dev diagnostics are currently enabled. */
+export declare function isRendererDevMode(): boolean;
+/**
+ * Install dev-mode-only accessors that warn when Canvas2D style *properties* are
+ * assigned on a renderer instead of calling the corresponding method.
+ *
+ * Call once per renderer instance, from its constructor. No-ops outside dev
+ * mode, so the accessors never exist in production.
+ * Each trapped property warns on its **first** write only — a per-frame
+ * assignment would otherwise flood the console at 240fps — and then stores and
+ * returns the value like a plain field, so a warned write is never a hard break
+ * for code that assigns and reads back.
+ *
+ * Skips any property the instance genuinely defines, so a backend that really
+ * does expose one keeps its own behavior.
+ */
+export declare function installRendererDevTraps(renderer: object, label: string): void;

package/dist/renderer.js

@@ -7,13 +7,19 @@
 
 
 
-var _chunkKHGHP2J3js = require('./chunk-KHGHP2J3.js');
 
 
 
+var _chunkK2UGEIT6js = require('./chunk-K2UGEIT6.js');
 
 
 
 
 
-exports.CanvasRenderer = _chunkKHGHP2J3js.CanvasRenderer; exports.GlyphRasterAtlas = _chunkKHGHP2J3js.GlyphRasterAtlas; exports.SVGRenderer = _chunkKHGHP2J3js.SVGRenderer; exports.TextRasterCache = _chunkKHGHP2J3js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkKHGHP2J3js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkKHGHP2J3js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkKHGHP2J3js.parseColorToRGBA;
+
+
+
+
+
+
+exports.CanvasRenderer = _chunkK2UGEIT6js.CanvasRenderer; exports.GlyphRasterAtlas = _chunkK2UGEIT6js.GlyphRasterAtlas; exports.SVGRenderer = _chunkK2UGEIT6js.SVGRenderer; exports.TextRasterCache = _chunkK2UGEIT6js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkK2UGEIT6js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkK2UGEIT6js.createWebGLPointRenderer; exports.installRendererDevTraps = _chunkK2UGEIT6js.installRendererDevTraps; exports.isRendererDevMode = _chunkK2UGEIT6js.isRendererDevMode; exports.parseColorToRGBA = _chunkK2UGEIT6js.parseColorToRGBA; exports.setRendererDevMode = _chunkK2UGEIT6js.setRendererDevMode;

package/dist/renderer.mjs

@@ -5,8 +5,11 @@ import {
   TextRasterCache,
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
-  parseColorToRGBA
-} from "./chunk-I4WQY7CJ.mjs";
+  installRendererDevTraps,
+  isRendererDevMode,
+  parseColorToRGBA,
+  setRendererDevMode
+} from "./chunk-TI5EMJGL.mjs";
 export {
   CanvasRenderer,
   GlyphRasterAtlas,
@@ -14,5 +17,8 @@ export {
   TextRasterCache,
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
-  parseColorToRGBA
+  installRendererDevTraps,
+  isRendererDevMode,
+  parseColorToRGBA,
+  setRendererDevMode
 };

package/dist/tree/Scene.d.ts

@@ -210,7 +210,37 @@ export interface SceneOptions {
      * (`'rtl'`). Also settable later via {@link Scene.readingDirection}.
      */
     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.
+     * - `'onDemand'`: paint only after {@link Scene.markDirty} (or an active
+     *   transition), so a genuinely static scene costs zero frames.
+     *
+     * Also settable later via {@link Scene.renderMode}. Prefer this option when
+     * the mode is known at construction: it applies before the first frame, so an
+     * `onDemand` scene never pays for the initial always-on frames.
+     */
+    renderMode?: 'always' | 'onDemand';
 }
+/**
+ * Every recognized {@link SceneOptions} key, used only to warn about unknown
+ * ones in dev mode.
+ *
+ * This exists because `SceneOptions` is structural: passing a key it does not
+ * declare is a **silent** no-op, and TypeScript only catches it when the object
+ * is written inline at the call site. Code that builds options dynamically, or
+ * 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.
+ *
+ * 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', 'debugA11y', 'disableWindowResize', '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;
 /**
@@ -949,12 +979,37 @@ export declare class Scene {
     private pointerEventTarget;
     private hasWarnedZeroSize;
     private fontLoadHandler;
-    /** Toggle development-mode runtime warnings globally. */
-    static devMode: boolean;
+    private static _devMode;
+    /**
+     * Toggle development-mode runtime warnings globally.
+     *
+     * An accessor rather than a plain field so the renderer layer learns about it
+     * immediately: renderers cannot import `Scene` (the dependency runs
+     * `Scene → renderer`), and their diagnostics are installed per instance at
+     * construction. A plain field would only reach them the next time a `Scene`
+     * happened to be built, which made a directly-constructed `CanvasRenderer`
+     * silently untrapped.
+     */
+    static get devMode(): boolean;
+    static set devMode(active: boolean);
     private static _devModeDetected;
     private _devActive;
     private _devFrameCount;
     private _devWarn;
+    /**
+     * Warn (dev mode only) about `SceneOptions` keys this version does not read.
+     *
+     * A structural type makes an unrecognized key a silent no-op, and TypeScript
+     * only rejects one when the object literal sits inline at the call site — not
+     * when options are built dynamically, and never in plain JS. Since the
+     * failure mode is "the option appears to work", a runtime check is the only
+     * thing that surfaces it.
+     *
+     * Dev-mode only on purpose: the loop is O(keys × known keys) with an edit
+     * distance per pair, which is nothing at construction but is still pure
+     * overhead in production, where the value has already been shipped.
+     */
+    private _warnUnknownOptions;
     /** @internal Periodic dev checks — called once per frame in dev mode. */
     private _devRunChecks;
     constructor(canvas: HTMLCanvasElement, options?: SceneOptions);

package/package.json

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