@vectojs/core 1.20.0 → 1.22.0

package/dist/renderer/IRenderer.d.ts

@@ -12,7 +12,70 @@
  *   r.fill('#38bdf8');
  * }
  */
+/**
+ * Per-backend draw counters, for a DevTools GPU readout.
+ *
+ * Opt-in via {@link IRenderer.setDrawCounters}: when off, counting compiles to a
+ * single boolean test per op, matching how `Scene` gates its phase timing and
+ * dirty tracking. Totals are cumulative until cleared rather than per-frame,
+ * because a per-frame log answers the question less directly at far more memory —
+ * the same reasoning `Scene.renderPhases` documents.
+ */
+export interface DrawCounters {
+    /** `fill()` calls, each committing one path. */
+    fills: number;
+    /** `stroke()` calls. */
+    strokes: number;
+    /** `fillText()` calls. */
+    texts: number;
+    /** `drawImage`/`drawImageRect` blits. */
+    images: number;
+    /** `fillCircle()` calls — batched, so this exceeds the fills they produce. */
+    circles: number;
+    /** Batch commits from {@link IRenderer.flush}. */
+    flushes: number;
+    /** `save()` calls. */
+    saves: number;
+    /** `restore()` calls. */
+    restores: number;
+    /** `clip()` calls. */
+    clips: number;
+    /**
+     * Times a font or fill style actually changed, as opposed to being re-set to
+     * the value it already had.
+     *
+     * The renderer already elides redundant sets; this counts the ones that got
+     * through, which is the number that costs anything.
+     */
+    stateSwitches: number;
+    /**
+     * Sum of drawn primitive areas divided by canvas area.
+     *
+     * A PROXY for overdraw, not a measurement: Canvas2D exposes no pixel-coverage
+     * readback, so this counts area submitted, ignoring clipping and off-screen
+     * rejection. It overstates, sometimes badly. Useful as a trend between two
+     * states of the same scene; meaningless as an absolute.
+     */
+    overdrawRatio: number;
+}
 export interface IRenderer {
+    /**
+     * Stable backend identifier.
+     *
+     * A discriminator rather than `constructor.name`, which minifies to something
+     * unusable in a production bundle — and a debug tool that cannot name the
+     * backend in the build where it matters is not much of a debug tool.
+     */
+    readonly kind?: 'canvas2d' | 'svg' | 'three' | string;
+    /**
+     * Enable or disable draw counting. Optional; a backend that cannot count omits
+     * it and a reader treats the absence as "not available".
+     */
+    setDrawCounters?(enabled: boolean): void;
+    /** Current counter totals, or null when counting is off. */
+    getDrawCounters?(): DrawCounters | null;
+    /** Zero the totals without disabling counting. */
+    clearDrawCounters?(): void;
     /** Clear the entire drawing surface to transparent / background color. */
     clear(): void;
     /** Push the current transform + state onto the renderer's stack. */
@@ -115,6 +178,37 @@ export interface IRenderer {
      * @param dh - Destination height.
      */
     drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+    /**
+     * Draw a sub-rectangle of an image source — the 9-argument `drawImage`.
+     *
+     * **Optional.** Callers must feature-detect and keep a fallback path:
+     *
+     * ```ts
+     * if (r.drawImageRect) r.drawImageRect(atlas, sx, sy, sw, sh, dx, dy, dw, dh);
+     * else r.fillText(glyph, x, baselineY, font, color);
+     * ```
+     *
+     * This exists for texture atlases (see `GlyphRasterAtlas`), where selecting one slot
+     * out of a shared canvas is what makes the blit cheap: a per-source-canvas
+     * cache re-binds a different texture almost every call and measured *slower*
+     * than the `fillText` it replaced on Chrome at scale, while atlas blits stay
+     * flat and run ~2x faster on both engines.
+     *
+     * `SVGRenderer` deliberately omits it: an SVG image embeds its source as a data
+     * URL, so a per-cell sub-rect would inline the entire atlas once per cell —
+     * and vector text is the correct output for a vector export regardless.
+     *
+     * @param source - The image source.
+     * @param sx - Source X, in source-image pixels.
+     * @param sy - Source Y, in source-image pixels.
+     * @param sw - Source width, in source-image pixels.
+     * @param sh - Source height, in source-image pixels.
+     * @param dx - Destination X.
+     * @param dy - Destination Y.
+     * @param dw - Destination width.
+     * @param dh - Destination height.
+     */
+    drawImageRect?(source: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
     /**
      * Fill the current path with the given color or gradient.
      *

package/dist/renderer/SVGRenderer.d.ts

@@ -13,6 +13,8 @@ export interface SVGLinearGradient {
     createMatrix: number[];
 }
 export declare class SVGRenderer implements IRenderer {
+    /** Backend discriminator; see {@link IRenderer.kind}. */
+    readonly kind = "svg";
     private width;
     private height;
     private buffer;

package/dist/renderer/WebGLPointRenderer.d.ts

@@ -4,6 +4,29 @@
  * render `getBatchCircle()` / `getBatchRect()` entities — the point-cloud /
  * particle case where Canvas2D tops out at ~7 fps for 100k primitives.
  */
+/** Per-frame and cumulative WebGL draw accounting. */
+export interface WebGLDrawStats {
+    /** Draw calls issued for the last completed frame. */
+    drawCalls: number;
+    /** Cumulative draw calls since creation. */
+    totalDrawCalls: number;
+    /** Cumulative mid-frame MSDF atlas switches, each costing an extra draw. */
+    atlasSwitches: number;
+    /** Programs compiled at creation — a fixed capability, not a per-frame cost. */
+    programs: number;
+    /** Textures currently allocated (colour atlas and/or MSDF atlas). */
+    textures: number;
+    /**
+     * Circles routed to the quad path rather than `gl.POINTS`, cumulatively.
+     *
+     * A circle takes the quad path when it could clip off-viewport or exceeds the
+     * driver's maximum aliased point size. A high share means the POINTS fast path
+     * is not being used and each circle costs four vertices instead of one.
+     */
+    circleQuadFallbacks: number;
+    /** Circles drawn through the `gl.POINTS` fast path, cumulatively. */
+    circlePoints: number;
+}
 export interface PointRenderer {
     /** Resize the backing buffer + GL viewport to a logical `w × h` (DPR applied). */
     resize(width: number, height: number): void;
@@ -21,6 +44,16 @@ export interface PointRenderer {
     maxDPR?: number;
     /** Begin a frame: reset the accumulated primitive buffers. */
     begin(): void;
+    /**
+     * Draw-call counters for the most recent frame, plus cumulative totals.
+     *
+     * Batching here is by primitive type — one draw per active type — so draw calls
+     * and batches are the same number, and both are bounded at five plus one per
+     * mid-frame MSDF atlas switch. That switch is the only variable term and the
+     * only thing worth watching: it forces a commit of glyphs batched against the
+     * previous font.
+     */
+    stats?(): WebGLDrawStats;
     /** Add one circle in world (CSS-pixel) coordinates; `alpha` multiplies the color's. */
     addCircle(x: number, y: number, radius: number, color: string, alpha?: number): void;
     /**

package/dist/renderer/index.d.ts

@@ -4,4 +4,5 @@ export * from './WebGLPointRenderer';
 export * from './WebGPUParticleSystemManager';
 export * from './IRenderer';
 export * from './colorParse';
+export * from './GlyphRasterAtlas';
 export * from './TextRasterCache';

package/dist/renderer.js

@@ -6,12 +6,14 @@
 
 
 
-var _chunkL4SWVP2Hjs = require('./chunk-L4SWVP2H.js');
 
+var _chunkLHONR3GOjs = require('./chunk-LHONR3GO.js');
 
 
 
 
 
 
-exports.CanvasRenderer = _chunkL4SWVP2Hjs.CanvasRenderer; exports.SVGRenderer = _chunkL4SWVP2Hjs.SVGRenderer; exports.TextRasterCache = _chunkL4SWVP2Hjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkL4SWVP2Hjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkL4SWVP2Hjs.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkL4SWVP2Hjs.parseColorToRGBA;
+
+
+exports.CanvasRenderer = _chunkLHONR3GOjs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkLHONR3GOjs.GlyphRasterAtlas; exports.SVGRenderer = _chunkLHONR3GOjs.SVGRenderer; exports.TextRasterCache = _chunkLHONR3GOjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkLHONR3GOjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkLHONR3GOjs.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkLHONR3GOjs.parseColorToRGBA;

package/dist/renderer.mjs

@@ -1,13 +1,15 @@
 import {
   CanvasRenderer,
+  GlyphRasterAtlas,
   SVGRenderer,
   TextRasterCache,
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-QS3CUV7H.mjs";
+} from "./chunk-UPULSLKA.mjs";
 export {
   CanvasRenderer,
+  GlyphRasterAtlas,
   SVGRenderer,
   TextRasterCache,
   WebGPUParticleSystemManager,

package/dist/text.js

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

package/dist/text.mjs

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

package/dist/tree/Entity.d.ts

@@ -159,6 +159,107 @@ export interface TextInputStyle {
  * to create and label the shadow DOM node (e.g. a real `<button>` or `<a href>`)
  * so the canvas stays accessible and clickable by automation/agents.
  */
+/**
+ * One value in a {@link DevtoolsDescriptor} group.
+ *
+ * JSON-safe by construction: DevTools serializes descriptors to render a panel,
+ * to write a snapshot, and to cross a `postMessage` bridge, so a value that
+ * cannot survive `structuredClone` is a bug rather than a limitation.
+ */
+export interface DevtoolsField {
+    /** Field name as shown in the inspector, e.g. `'scrollTop'`. */
+    label: string;
+    /** Current value. Keep to primitives, or short arrays/records of primitives. */
+    value: string | number | boolean | null | ReadonlyArray<string | number> | Record<string, string | number | boolean>;
+    /**
+     * Optional one-line explanation, shown as a tooltip.
+     *
+     * Worth spending: a reader looking at `visibleRange: [12, 34]` cannot tell
+     * whether the bounds are inclusive without being told.
+     */
+    hint?: string;
+    /**
+     * Mark a value that reflects derived or externally-owned state, so the panel
+     * can show it as read-only rather than inviting an edit that will be silently
+     * reverted. A `Stack`-laid-out child's `x` is the canonical example.
+     */
+    readOnly?: boolean;
+}
+/**
+ * A component's self-description for DevTools.
+ *
+ * Without this, the inspector can only show generic `Entity` properties —
+ * position, size, opacity — so everything that makes a component a component is
+ * invisible: `Input.value`, `Slider.min`/`max`, `ScrollView.scrollTop`,
+ * `VirtualList.visibleRange`, a `Markdown` block's token counts. The alternative
+ * is DevTools carrying a table of component types, which inverts the dependency
+ * (a debug tool would gate every new component) and breaks under minified builds
+ * where `constructor.name` is unreliable.
+ *
+ * Implement {@link Entity.getDevtoolsDescriptor} to opt in. Cost is paid only
+ * when a panel actually inspects the entity, so a descriptor may compute values
+ * it would not compute per frame.
+ *
+ * @example
+ * ```ts
+ * public override getDevtoolsDescriptor(): DevtoolsDescriptor {
+ *   return {
+ *     kind: 'ScrollView',
+ *     groups: [{
+ *       label: 'Scroll',
+ *       fields: [
+ *         { label: 'scrollTop', value: this.scrollTop },
+ *         { label: 'contentHeight', value: this.contentHeight, readOnly: true },
+ *       ],
+ *     }],
+ *   };
+ * }
+ * ```
+ */
+export interface DevtoolsDescriptor {
+    /**
+     * Component kind for display, e.g. `'VirtualList'`.
+     *
+     * Provided explicitly rather than read from `constructor.name`, which minifies
+     * to something meaningless in a production bundle.
+     */
+    kind: string;
+    /** Grouped fields, rendered as sections in the order given. */
+    groups: ReadonlyArray<{
+        label: string;
+        fields: ReadonlyArray<DevtoolsField>;
+    }>;
+    /**
+     * Free-form notes: a caveat, a known-slow path, a link to a doc section.
+     * Rendered under the groups.
+     */
+    notes?: ReadonlyArray<string>;
+    /**
+     * Stable identity for snapshot diffing, independent of tree position.
+     *
+     * Snapshot paths are structural indices (`root > Card[0] > Text[2]`), so
+      * inserting at the head of a list renames every sibling, so the diff describes
+   * different nodes than the ones that changed. A key that survives reordering — a
+   * row id, a message id — keeps each entry attributed to the node it belongs to.
+   * Most relevant to `VirtualList` and `Table`, where recycling moves entities
+   * constantly.
+  
+     */
+    devtoolsKey?: string;
+}
+/**
+ * Entity properties a parent computes for its children.
+ *
+ * Editing one of these on a child is silently reverted by the next layout pass,
+ * which looks like the editor being broken rather than the value being owned
+ * elsewhere. A container declares what it controls so a tool can say so up front
+ * instead of letting a user discover it by watching their change disappear.
+ *
+ * Declared by the parent rather than detected by the tool: only the container
+ * knows whether it writes `x` unconditionally, and a table of container types
+ * inside DevTools would gate every new layout component on a debug-tool change.
+ */
+export type LayoutControlledProperty = 'x' | 'y' | 'width' | 'height' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity';
 export interface A11yAttributes {
     /** Shadow element tag to create. Defaults to `'div'`. */
     tag?: 'div' | 'a' | 'button' | 'img' | 'input' | 'textarea';
@@ -726,6 +827,33 @@ export declare abstract class Entity {
      *
      * @returns The {@link A11yAttributes} for this entity's shadow node.
      */
+    /**
+     * Describe this entity's own debug surface for DevTools.
+     *
+     * Returns `null` by default, meaning "nothing beyond the generic `Entity`
+     * fields the inspector already shows". Override in a component to expose the
+     * state that makes it inspectable — see {@link DevtoolsDescriptor}.
+     *
+     * Called only while a panel is inspecting this entity, never per frame, so it
+     * may compute values that would be too expensive to track continuously.
+     *
+     * @returns A descriptor, or `null` to opt out.
+     */
+    getDevtoolsDescriptor(): DevtoolsDescriptor | null;
+    /**
+     * Which of a child's properties this entity computes during layout.
+     *
+     * Returns an empty array by default, meaning "this entity does not position its
+     * children". A container that lays out children — `Stack`, `Table`, `Tabs` —
+     * overrides it so tooling can mark those values as parent-owned: editing `x` on
+     * a `Stack` child is reverted by the next layout, and knowing that in advance is
+     * the difference between a confusing tool and a correct one.
+     *
+     * @param child - The child being asked about. Containers whose control depends
+     *   on the child (a `Table` cell versus its header) can answer per child.
+     * @returns Property names this entity overwrites on that child.
+     */
+    getLayoutControlledProperties(child: Entity): ReadonlyArray<LayoutControlledProperty>;
     getA11yAttributes(): A11yAttributes;
     /**
      * Local-space axis-aligned bounding box of what this entity's {@link render}

package/dist/tree/Scene.d.ts

@@ -12,6 +12,7 @@ export interface IWebGPUParticleSystemManager {
 }
 import { Entity } from './Entity';
 import { IRenderer } from '../renderer/IRenderer';
+import type { WebGLDrawStats } from '../renderer/WebGLPointRenderer';
 import { type WasmModuleSource, type WasmTransformBackend } from '../wasm/backend';
 import { type CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
@@ -25,7 +26,41 @@ import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particl
  * `a11ySync` and `a11yOrder` run after `render` in the frame loop, so they are
  * siblings of it, not children.
  */
-export type RenderPhase = 'render' | 'transform' | 'drawWalk' | 'flush' | 'a11ySync' | 'a11yOrder'
+export type RenderPhase = 'render' | 'transform' | 'drawWalk' | 'flush' | 'a11ySync'
+/**
+ * Time inside {@link Scene.syncContentGridProjection} materializing DOM
+ * carriers, nested inside `a11ySync`.
+ *
+ * Split out because `a11ySync` for a streaming code block measured 1661-1875 ms
+ * against a 210-671 ms render, and attributing that to grid materialization was
+ * an assumption. Nothing should be optimised here on the strength of the parent
+ * phase alone.
+ */
+ | 'gridMaterialize'
+/**
+ * Whole of {@link Scene.syncContentProjection}, nested inside `a11ySync`.
+ *
+ * Measured at 99.8-99.9% of `a11ySync` for a streaming code block, so per-node
+ * a11y attribute and geometry work is not where that phase's cost lives.
+ */
+ | 'contentProjection'
+/** Per-node a11y attribute/geometry work, excluding content projection and descendants. */
+ | 'a11yNodes'
+/** Whole of `syncContentGridProjection`, of which `gridMaterialize` is one part. */
+ | 'gridSync'
+/**
+ * Synchronous part of `scheduleContentGridCalibration` — building the probe DOM.
+ *
+ * The measurement itself is deferred to a rAF, but the probe is constructed
+ * here. Measured at 77-80% of `gridSync` on Chrome (3.7-4.5 ms per frame, i.e.
+ * the entire 240Hz budget) against about 1 ms on Firefox, making it the largest
+ * remaining cost of projecting a streaming code block once carrier reuse landed.
+ */
+ | 'gridCalibrateSchedule'
+/** The `querySelectorAll` + per-cell scan inside calibration scheduling. */
+ | 'calibScan'
+/** Probe DOM construction and insertion inside calibration scheduling. */
+ | 'calibProbeBuild' | 'a11yOrder'
 /** Sum of every entity's own render(), nested inside drawWalk. */
  | 'entityPaint';
 export interface RenderPhaseEntry {
@@ -358,6 +393,29 @@ export declare class Scene {
     private contentGridCalibrationFrames;
     /** Detached, untransformed font probes used by the cold calibration pass. */
     private contentGridCalibrationProbes;
+    /**
+     * Monotonic stamp identifying the conditions grid cells were calibrated under.
+     *
+     * Calibration measures the difference between the advance the canvas grid assigns
+     * a cluster and the width the browser lays it out at, then writes a per-cell
+     * `scaleX`. That result stays valid until the font or the page scale changes, and
+     * it lives on the cell element — so a cell carrying this stamp needs no further
+     * work.
+     *
+     * The scan that feeds calibration was O(cells) on every revision bump: for a
+     * streaming code block it re-derived a measurement key for every cell in the
+     * block each frame in order to produce only ~20 distinct keys, costing about
+     * 2.5 ms/frame after the `style.font` fix and still over half of `a11ySync`. Since
+     * carrier reuse (#244) leaves untouched lines — and therefore their calibrated
+     * transforms — in place, cells stamped with the current generation can simply be
+     * skipped, making the scan O(new cells) instead.
+     *
+     * A plain incrementing integer rather than the descriptive calibration key,
+     * because it goes into an attribute selector and must not need escaping.
+     */
+    private contentGridCalibrationGeneration;
+    /** The `(fontEpoch, pageScale)` pair the current generation corresponds to. */
+    private contentGridCalibrationStamp;
     /** Invalidates grid font calibration after browser font availability changes. */
     private contentFontEpoch;
     /** Cached Canvas-to-client scale for the current font/viewport epoch. */
@@ -751,6 +809,23 @@ export declare class Scene {
     particleBackend: 'auto' | 'webgpu' | 'cpu';
     private _webgpuDisabled;
     get webgpuDisabled(): boolean;
+    /**
+     * Draw accounting for the WebGL point layer, or null when that layer is not in
+     * use.
+     *
+     * Null and all-zero mean different things: null is "this backend is not
+     * running", zero is "it ran and drew nothing". A readout that conflates them
+     * sends someone looking for a performance problem in a backend that was never
+     * active.
+     */
+    get webglDrawStats(): WebGLDrawStats | null;
+    /**
+     * Whether a WebGPU device is currently live for particle compute.
+     *
+     * The WebGPU path only activates when a `ComputeParticleEntity` is present, so
+     * most scenes never touch it.
+     */
+    get webgpuActive(): boolean;
     set webgpuDisabled(value: boolean);
     private recoveryTimerId;
     private manager;
@@ -800,6 +875,15 @@ export declare class Scene {
      */
     private setupGLContextRecovery;
     private endContentSelectionDrag;
+    /**
+     * Index of the carrier line currently holding a selection inside `el`, or
+     * `null`.
+     *
+     * Lets a partial re-materialization decide whether the user's selection is even
+     * affected. Checks the tracked anchor first (it survives a drag) and falls back
+     * to the live DOM selection.
+     */
+    private contentGridSelectionLine;
     private releaseContentSelectionForRebuild;
     /**
      * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -836,6 +920,17 @@ export declare class Scene {
      * @example scene.add(new CircleEntity());
      */
     add(entity: Entity): this;
+    /**
+     * Reset per-grid calibration and bookkeeping before a (re)materialization.
+     *
+     * @param entityId - Owning entity, keyed into the calibration maps.
+     * @param el - The projection element.
+     * @param releaseSelection - Whether to drop a selection this element owns.
+     *   Pass `false` when carrier lines are being reused: the selection's DOM nodes
+     *   survive the pass, so tearing it down would wipe a user's selection on every
+     *   streamed chunk — the exact bug `preserveContentSelectionAcrossRebuild`
+     *   exists to prevent on the non-grid path.
+     */
     private clearContentGridState;
     /**
      * Drop any projected elements under `node` without touching the entity tree.
@@ -933,6 +1028,26 @@ export declare class Scene {
     get rootEntity(): Entity;
     /** The overlay layer root (see {@link showOverlay}), read-only for tooling. */
     get overlayRootEntity(): Entity;
+    /**
+     * Advance and render exactly one frame, synchronously.
+     *
+     * This renders UNCONDITIONALLY: it consults neither {@link renderMode} nor
+     * {@link dirty}, and it does not apply the `always`-mode idle auto-throttle.
+     * That is deliberate — a deterministic driver (video export, a test, a
+     * fixed-step benchmark) asks for a frame because it wants that frame, not a
+     * scheduler opinion about whether it is needed.
+     *
+     * The consequence is a measurement footgun worth stating explicitly: a
+     * benchmark that drives frames through `step()` CANNOT observe frame skipping,
+     * so `always` and `onDemand` produce byte-identical draw counts through this
+     * path. An investigation into whether `onDemand` skips redundant repaints once
+     * concluded "it does not" on exactly that basis; on the real rAF loop the same
+     * workload rendered ~1.0 frames per content change. To measure anything about
+     * scheduling, use {@link start} and let `requestAnimationFrame` drive.
+     *
+     * @param dt Seconds to advance. Not clamped by `MAX_FRAME_DT` — the caller
+     *   chooses the step, since determinism is the point.
+     */
     step(dt: number): void;
     /**
      * Mark the scene as needing a redraw on the next frame.
@@ -941,6 +1056,22 @@ export declare class Scene {
      * entity state outside of {@link Entity.animate} so the change is rendered.
      */
     markDirty(source?: DirtySource): void;
+    /**
+     * Increments whenever the tree's shape changes: add, remove or reparent.
+     *
+     * Already maintained for the resident WASM transform store (see
+     * {@link markStructureChanged}, called from `Entity.add`/`remove`), and exposed
+     * here because a cache of the tree's shape — a DevTools tree model, a serialized
+     * snapshot — is valid exactly as long as this value is unchanged. Comparing it is
+     * O(1) against re-walking the tree, which is what it replaces: DevTools rebuilt
+     * both trees on a fixed 500 ms interval, a constant cost proportional to entity
+     * count, purely because it had no way to ask whether the shape had changed.
+     *
+     * Property changes do NOT bump it. Moving or restyling an entity leaves the
+     * shape intact, so a consumer that also cares about values must read those
+     * directly rather than rebuilding a tree.
+     */
+    get structureVersion(): number;
     /**
      * Record who marked the scene dirty and why.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "publishConfig": {
     "access": "public"
   },
@@ -65,7 +65,7 @@
   },
   "dependencies": {
     "@vectojs/animation": "^0.1.1",
-    "@vectojs/layout": "^0.3.0",
+    "@vectojs/layout": "^0.4.0",
     "@vectojs/math": "^0.1.1",
     "@vectojs/text": "^0.2.0"
   },