@vectojs/core 1.24.0 → 1.26.0

package/dist/index.mjs

@@ -8,13 +8,13 @@ import {
   isSafeUrl,
   parseColorToRGBA,
   sanitizeUrl
-} from "./chunk-ME4LB2HB.mjs";
+} from "./chunk-I4WQY7CJ.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-FRMLD4PP.mjs";
+} from "./chunk-MVFPN4Y5.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1370,6 +1370,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;
@@ -2803,6 +2854,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 +2949,9 @@ 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();
+    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)");
@@ -5709,11 +5793,11 @@ function contentGridLineSignature(grid, line, projected, lineHeight, baseline, f
 // src/components/TextEntity.ts
 import {
   LayoutEngine,
-  createCanvasMeasurer
+  resolveGlyphMeasurer
 } from "@vectojs/layout";
-var sharedMeasurer;
+var sharedMeasurer = null;
 function defaultMeasurer() {
-  if (sharedMeasurer === void 0) sharedMeasurer = createCanvasMeasurer("sans-serif");
+  sharedMeasurer ??= resolveGlyphMeasurer("sans-serif");
   return sharedMeasurer;
 }
 var TextEntity = class extends Entity {
@@ -6488,6 +6572,7 @@ export {
   PARTICLE_STRIDE_FLOATS,
   REDUCED_MOTION_FPS,
   Rect,
+  SCENE_OPTION_KEYS,
   SVGEntity,
   SVGRenderer,
   Scene,

package/dist/renderer.js

@@ -7,7 +7,7 @@
 
 
 
-var _chunkKEBYJVD6js = require('./chunk-KEBYJVD6.js');
+var _chunkKHGHP2J3js = require('./chunk-KHGHP2J3.js');
 
 
 
@@ -16,4 +16,4 @@ var _chunkKEBYJVD6js = require('./chunk-KEBYJVD6.js');
 
 
 
-exports.CanvasRenderer = _chunkKEBYJVD6js.CanvasRenderer; exports.GlyphRasterAtlas = _chunkKEBYJVD6js.GlyphRasterAtlas; exports.SVGRenderer = _chunkKEBYJVD6js.SVGRenderer; exports.TextRasterCache = _chunkKEBYJVD6js.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkKEBYJVD6js.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkKEBYJVD6js.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkKEBYJVD6js.parseColorToRGBA;
+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;

package/dist/renderer.mjs

@@ -6,7 +6,7 @@ import {
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-ME4LB2HB.mjs";
+} from "./chunk-I4WQY7CJ.mjs";
 export {
   CanvasRenderer,
   GlyphRasterAtlas,

package/dist/text/MSDFTextEntity.d.ts

@@ -34,10 +34,34 @@ export declare class MSDFTextEntity extends Entity {
     private layoutText;
     private text;
     private lastRenderedSeqId;
+    private atlasDecodeTarget;
+    private atlasDecodeHandler;
     private rgbColorCache;
     private fontStringCache;
     private layoutResult;
     constructor(text: string, options: MSDFTextEntityOptions);
+    /**
+     * Repaint once the atlas raster decodes.
+     *
+     * The WebGL backend refuses to upload a not-yet-decoded atlas (it would pin an
+     * empty texture in its identity cache forever), so the upload has to happen on
+     * a LATER frame — and nothing else schedules one. Layout marks the scene dirty
+     * when the worker replies, which for a network-served atlas is long before the
+     * image lands, so the scene is already idle by then.
+     *
+     * 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
+     * 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.
+     *
+     * Only `HTMLImageElement`-shaped sources have a decode to wait for; a canvas,
+     * `ImageBitmap`, or `VideoFrame` atlas is ready on arrival.
+     */
+    private watchAtlasDecode;
+    private detachAtlasDecodeListener;
     /** Change the wrap boundary and re-run layout for the current text. */
     setMaxWidth(maxWidth: number): void;
     /**

package/dist/text/SVGEntity.d.ts

@@ -1,12 +1,21 @@
 import { Entity } from '../tree/Entity';
 import { IRenderer } from '../renderer/IRenderer';
 export declare class SVGEntity extends Entity {
+    /**
+     * Stroke colour of the fallback marker drawn when the source cannot be
+     * rasterized. Set to `'transparent'` to opt out and keep the box empty.
+     * Default `'rgba(248,113,113,0.9)'`.
+     */
+    fallbackStroke: string;
+    /** Fill behind the fallback marker. Default `'rgba(248,113,113,0.12)'`. */
+    fallbackFill: string;
     private svgSource;
     private imageBitmap;
     private imageElement;
     private blobURL;
     private currentImg;
     private lodTimeout;
+    private rasterFailed;
     private cachedDoc;
     private baseWidth;
     private baseHeight;
@@ -16,7 +25,22 @@ export declare class SVGEntity extends Entity {
     setSVGSource(svgSource: string): void;
     private parseSVGDimensions;
     private triggerRasterization;
+    /**
+     * Whether the source genuinely rasterized to a bitmap.
+     *
+     * Distinguishes "drew the real artwork" from "drew the fallback marker",
+     * which pixel counts alone cannot tell apart — both are non-blank.
+     */
+    hasRasterBitmap(): boolean;
+    /**
+     * Whether rasterization failed, so {@link render} draws the fallback marker.
+     *
+     * `false` while a raster is still in flight; only a settled failure sets it.
+     */
+    hasRasterFailed(): boolean;
     isPointInside(globalX: number, globalY: number): boolean;
     render(r: IRenderer): void;
+    /** Box outline plus a diagonal cross — the conventional "broken image" mark. */
+    private drawFallback;
     destroy(): void;
 }

package/dist/text.js

@@ -2,11 +2,11 @@
 
 
 
-var _chunkAGP4VLF4js = require('./chunk-AGP4VLF4.js');
+var _chunkZ3HFY75Rjs = require('./chunk-Z3HFY75R.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkAGP4VLF4js.MSDFTextEntity; exports.SVGEntity = _chunkAGP4VLF4js.SVGEntity;
+exports.MSDFTextEntity = _chunkZ3HFY75Rjs.MSDFTextEntity; exports.SVGEntity = _chunkZ3HFY75Rjs.SVGEntity;

package/dist/text.mjs

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

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;
 /**
@@ -955,6 +985,20 @@ export declare class Scene {
     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.24.0",
+  "version": "1.26.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,20 +61,20 @@
   "scripts": {
     "build": "(cd ../math && bun run build) && (cd ../text && bun run build) && (cd ../layout && bun run build) && (cd ../animation && bun run build) && tsup && tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "test:e2e": "bun e2e/hidpi.e2e.ts && bun e2e/text-projection.e2e.ts"
+    "test:e2e": "bun e2e/hidpi.e2e.ts && bun e2e/text-projection.e2e.ts && bun e2e/svg-fallback.e2e.ts && bun e2e/msdf-atlas-decode.e2e.ts && bun e2e/layout-worker-fallback.e2e.ts"
   },
   "dependencies": {
     "@vectojs/animation": "^0.1.1",
-    "@vectojs/layout": "^0.4.0",
+    "@vectojs/layout": "^0.5.0",
     "@vectojs/math": "^0.1.1",
-    "@vectojs/text": "^0.2.0"
+    "@vectojs/text": "^0.3.0"
   },
   "devDependencies": {
     "@guidepup/virtual-screen-reader": "0.32.1",
     "@vitest/coverage-v8": "^4.1.10",
     "esbuild": "^0.28.1",
-    "jsdom": "^29.1.1",
-    "puppeteer-core": "^25.3.0",
+    "jsdom": "^30.0.1",
+    "puppeteer-core": "^25.4.0",
     "tsup": "^8.3.5",
     "vitest": "^4.1.10"
   }