@vectojs/core 1.19.0 → 1.20.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import {
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent
-} from "./chunk-XWBVBXFZ.mjs";
+} from "./chunk-TJCXB2F6.mjs";
 
 // src/tree/Scene.ts
 import { SpringDriver, TweenDriver } from "@vectojs/animation";
@@ -1538,6 +1538,70 @@ var Scene = class _Scene {
   renderMode = "always";
   /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
   static MAX_DIRTY_REASONS = 200;
+  _phaseTiming = false;
+  _phaseTotals = /* @__PURE__ */ new Map();
+  /**
+   * Start or stop per-phase render timing.
+   *
+   * Off by default, and the probes compile to a single boolean test when off:
+   * these sit on the frame path, so the disabled cost has to be nothing. Enable,
+   * run the scene, then read {@link renderPhases}.
+   *
+   * Exists because a frame total cannot tell you where the time went. The
+   * markdown streaming benchmark put render at 85-99% of an append's cost, and
+   * there was no way to decompose that number further — which is exactly the
+   * position that led to two wrong optimisation guesses earlier
+   * (`CodeBlock` reuse, hit-grid fusion), both of which measured as no change.
+   */
+  setPhaseTiming(enabled) {
+    this._phaseTiming = enabled;
+    if (!enabled) this.clearRenderPhases();
+  }
+  /** Whether per-phase render timing is being recorded. */
+  get phaseTiming() {
+    return this._phaseTiming;
+  }
+  /**
+   * Accumulate one phase sample.
+   *
+   * Totals rather than a per-frame log: the question is always "which phase owns
+   * the frame", and a log of thousands of samples answers it less directly while
+   * costing far more memory. `maxMs` is kept because a phase that is cheap on
+   * average but spikes is a different problem from one that is uniformly slow.
+   */
+  _recordPhase(phase, ms) {
+    const existing = this._phaseTotals.get(phase);
+    if (existing) {
+      existing.totalMs += ms;
+      existing.calls++;
+      if (ms > existing.maxMs) existing.maxMs = ms;
+      return;
+    }
+    this._phaseTotals.set(phase, { totalMs: ms, calls: 1, maxMs: ms });
+  }
+  /**
+   * Recorded phase timings, most expensive first, with each phase's share of the
+   * measured total.
+   *
+   * `share` is the number that matters: a phase at 4% cannot be worth optimising
+   * however inefficient it looks in isolation.
+   */
+  get renderPhases() {
+    const entries = [...this._phaseTotals.entries()];
+    const denominator = entries.filter(([phase]) => phase !== "render").reduce((sum, [, v]) => sum + v.totalMs, 0);
+    return entries.map(([phase, v]) => ({
+      phase,
+      totalMs: +v.totalMs.toFixed(3),
+      calls: v.calls,
+      avgMs: +(v.totalMs / Math.max(1, v.calls)).toFixed(4),
+      maxMs: +v.maxMs.toFixed(3),
+      share: phase === "render" ? null : +(100 * v.totalMs / Math.max(1e-9, denominator)).toFixed(1)
+    })).sort((a, b) => b.totalMs - a.totalMs);
+  }
+  /** Drop recorded phase timings, keeping timing enabled. */
+  clearRenderPhases() {
+    this._phaseTotals.clear();
+  }
   _dirtyTracking = false;
   _dirtyReasons = /* @__PURE__ */ new Map();
   dirty = true;
@@ -2834,6 +2898,20 @@ var Scene = class _Scene {
     delete el.dataset.vectoGridCalibrationMs;
     this.releaseContentSelectionForRebuild(el);
   }
+  /**
+   * Drop any projected elements under `node` without touching the entity tree.
+   *
+   * Used when the walk reaches an invisible subtree: the entities stay put (a
+   * later `show()` re-projects them), but nothing under here may remain
+   * focusable or announced while hidden.
+   */
+  pruneA11ySubtree(node) {
+    if (this.a11yElements.has(node.id) || this.contentElements.has(node.id)) {
+      this.removeA11yRecursively(node);
+      return;
+    }
+    for (const child of node.children) this.pruneA11ySubtree(child);
+  }
   removeA11yRecursively(node) {
     if (node.isDOMPortal) {
       node.releaseDOMBindings();
@@ -3151,7 +3229,9 @@ var Scene = class _Scene {
   step(dt) {
     const time = this.lastTime + dt;
     this.lastTime = time;
+    const t0 = this._phaseTiming ? performance.now() : 0;
     this.render(this.renderer, dt, time);
+    if (this._phaseTiming) this._recordPhase("render", performance.now() - t0);
     this.dirty = false;
   }
   /**
@@ -3286,6 +3366,10 @@ var Scene = class _Scene {
     if (node.isDOMPortal) {
       return;
     }
+    if (node.a11yHidden) {
+      this.pruneA11ySubtree(node);
+      return;
+    }
     if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
@@ -4372,7 +4456,9 @@ var Scene = class _Scene {
     }
     this._lastRenderTick = time;
     this._lastDt = dt;
+    const phaseClock = this._phaseTiming ? performance.now() : 0;
     this.render(this.renderer, dt, time);
+    if (this._phaseTiming) this._recordPhase("render", performance.now() - phaseClock);
     this._lastFrameMs = (typeof performance !== "undefined" ? performance.now() : time) - now;
     this._renderedFrames++;
     const hasActiveAnimation = this.frameHadAnimation;
@@ -4382,9 +4468,13 @@ var Scene = class _Scene {
     if ((hasInteractive || this.a11yElements.size > 0 || wantsContentSync) && (shouldSyncInterval || this.a11yPendingSyncAfterAnimation)) {
       this.lastA11ySync = time;
       if (hasInteractive || wantsContentSync) {
+        const t0 = this._phaseTiming ? performance.now() : 0;
         this.syncA11y(this.root);
+        if (this._phaseTiming) this._recordPhase("a11ySync", performance.now() - t0);
       }
+      const t1 = this._phaseTiming ? performance.now() : 0;
       this.enforceA11yDomOrder();
+      if (this._phaseTiming) this._recordPhase("a11yOrder", performance.now() - t1);
       this.a11yPendingSyncAfterAnimation = hasActiveAnimation;
     } else if (hasActiveAnimation) {
       this.a11yPendingSyncAfterAnimation = true;
@@ -4558,7 +4648,9 @@ var Scene = class _Scene {
       updateWalk(this.root);
       for (const overlay of this.overlayRoot.children) updateWalk(overlay);
     }
+    const wasmT0 = this._phaseTiming ? performance.now() : 0;
     const wasmWorld = wasmMain ? this._syncWasmStore() : null;
+    if (this._phaseTiming) this._recordPhase("transform", performance.now() - wasmT0);
     const wasmSlotEntity = this._slotEntity;
     const renderNode = (node, pa, pb, pc, pd, pe, pf, parentOpacity) => {
       if (isMainRenderer && !wasmMain) {
@@ -4688,7 +4780,13 @@ var Scene = class _Scene {
             );
           }
         } else {
-          node.render(renderer);
+          if (this._phaseTiming) {
+            const t0 = performance.now();
+            node.render(renderer);
+            this._recordPhase("entityPaint", performance.now() - t0);
+          } else {
+            node.render(renderer);
+          }
         }
       }
       if (node.clipChildren) {
@@ -4700,20 +4798,24 @@ var Scene = class _Scene {
       renderer.flush();
       renderer.restore();
     };
+    const drawT0 = this._phaseTiming ? performance.now() : 0;
     renderNode(this.root, 1, 0, 0, 1, 0, 0, 1);
     for (const overlay of this.overlayRoot.children) {
       renderNode(overlay, 1, 0, 0, 1, 0, 0, 1);
     }
+    if (this._phaseTiming) this._recordPhase("drawWalk", performance.now() - drawT0);
     if (isMainRenderer) {
       this.frameHadAnimation = walkHadAnimation;
       this.frameHadInteractive = walkHadInteractive;
       this.reconcilePortals();
     }
+    const flushT0 = this._phaseTiming ? performance.now() : 0;
     renderer.flush();
     if (isMainRenderer) {
       this.pointRenderer?.flush();
     }
     renderer.present?.();
+    if (this._phaseTiming) this._recordPhase("flush", performance.now() - flushT0);
     if (this._devActive) {
       this._devFrameCount++;
       this._devRunChecks();

package/dist/text.js

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

package/dist/text.mjs

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

package/dist/tree/Entity.d.ts

@@ -416,6 +416,24 @@ export declare abstract class Entity {
      * nodes, so on-top components stay clickable.
      */
     a11yFullViewport: boolean;
+    /**
+     * Hide this entity AND its whole subtree from the accessibility/automation
+     * projection, regardless of each node's own `interactive` flag.
+     *
+     * For a container that is logically closed while still mounted — an `Overlay`
+     * after `hide()`, a collapsed panel kept in the tree for its transition. Setting
+     * `interactive = false` on the container alone is not enough: the projection walk
+     * still descends, and any still-interactive child is re-created on the next
+     * frame. Measured before this existed: after `Popover.hide()` the popover's own
+     * element was gone while its button stayed projected with `tabIndex: 0` and a
+     * live box, so a keyboard user could Tab into a hidden popover.
+     *
+     * Deliberately NOT inferred from `opacity`: `Overlay.hide()` springs opacity
+     * toward 0, so mid-transition it reads nonzero (~0.26 when measured) and an
+     * `=== 0` test never fires; a threshold would instead silently un-project a
+     * faint-but-live control.
+     */
+    a11yHidden: boolean;
     /**
      * Clip this node's children to its local box (`[0,0]–[width,height]`) while
      * rendering. Combined with translating a content child, this is how

package/dist/tree/Scene.d.ts

@@ -17,6 +17,27 @@ import { type CoreWasmRuntime } from '../wasm/runtime';
 import { type HitModuleSource, type HitTestBackend } from '../wasm/hit-backend';
 import { type AnimModuleSource, type AnimBackend } from '../wasm/anim-backend';
 import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particle-backend';
+/**
+ * A timed phase of a frame.
+ *
+ * `render` is the ENCLOSING phase — it contains `transform`, `drawWalk` and
+ * `flush` — so it is reported without a share to avoid double-counting.
+ * `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'
+/** Sum of every entity's own render(), nested inside drawWalk. */
+ | 'entityPaint';
+export interface RenderPhaseEntry {
+    phase: RenderPhase;
+    totalMs: number;
+    calls: number;
+    avgMs: number;
+    /** Worst single sample — a spiky phase is a different problem from a slow one. */
+    maxMs: number;
+    /** Percent of the measured total, or `null` for the enclosing `render` phase. */
+    share: number | null;
+}
 /**
  * Who marked the scene dirty, and why.
  *
@@ -230,6 +251,43 @@ export declare class Scene {
     renderMode: 'always' | 'onDemand';
     /** Cap on distinct recorded dirty reasons (see `recordDirtyReason`). */
     private static readonly MAX_DIRTY_REASONS;
+    private _phaseTiming;
+    private _phaseTotals;
+    /**
+     * Start or stop per-phase render timing.
+     *
+     * Off by default, and the probes compile to a single boolean test when off:
+     * these sit on the frame path, so the disabled cost has to be nothing. Enable,
+     * run the scene, then read {@link renderPhases}.
+     *
+     * Exists because a frame total cannot tell you where the time went. The
+     * markdown streaming benchmark put render at 85-99% of an append's cost, and
+     * there was no way to decompose that number further — which is exactly the
+     * position that led to two wrong optimisation guesses earlier
+     * (`CodeBlock` reuse, hit-grid fusion), both of which measured as no change.
+     */
+    setPhaseTiming(enabled: boolean): void;
+    /** Whether per-phase render timing is being recorded. */
+    get phaseTiming(): boolean;
+    /**
+     * Accumulate one phase sample.
+     *
+     * Totals rather than a per-frame log: the question is always "which phase owns
+     * the frame", and a log of thousands of samples answers it less directly while
+     * costing far more memory. `maxMs` is kept because a phase that is cheap on
+     * average but spikes is a different problem from one that is uniformly slow.
+     */
+    private _recordPhase;
+    /**
+     * Recorded phase timings, most expensive first, with each phase's share of the
+     * measured total.
+     *
+     * `share` is the number that matters: a phase at 4% cannot be worth optimising
+     * however inefficient it looks in isolation.
+     */
+    get renderPhases(): RenderPhaseEntry[];
+    /** Drop recorded phase timings, keeping timing enabled. */
+    clearRenderPhases(): void;
     private _dirtyTracking;
     private _dirtyReasons;
     private dirty;
@@ -779,6 +837,14 @@ export declare class Scene {
      */
     add(entity: Entity): this;
     private clearContentGridState;
+    /**
+     * Drop any projected elements under `node` without touching the entity tree.
+     *
+     * Used when the walk reaches an invisible subtree: the entities stay put (a
+     * later `show()` re-projects them), but nothing under here may remain
+     * focusable or announced while hidden.
+     */
+    private pruneA11ySubtree;
     private removeA11yRecursively;
     /**
      * If `el` is about to be removed from the DOM while it holds browser focus,

package/package.json

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