@vectojs/core 1.16.2 → 1.16.3

package/dist/index.js

@@ -2162,17 +2162,17 @@ var Scene = (_class6 = class _Scene {
     this._devFrameCount++;
     if (this._devFrameCount % 120 !== 0) return;
     if (this.a11yElements) {
-      let interactiveCount = 0;
+      let projectableCount = 0;
       const walk = (node) => {
-        if (node.interactive && node.width > 0) interactiveCount++;
+        if (this.shouldProjectA11y(node)) projectableCount++;
         for (const c of node.children) walk(c);
       };
       walk(this.root);
       for (const c of this.overlayRoot.children) walk(c);
       const shadowCount = this.a11yElements.size;
-      if (shadowCount > interactiveCount + 2) {
+      if (shadowCount > projectableCount) {
         this._devWarn(
-          `a11yElements (${shadowCount}) exceeds interactive entities (${interactiveCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
+          `a11yElements (${shadowCount}) exceeds projectable entities (${projectableCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
         );
       }
     }
@@ -2643,7 +2643,19 @@ var Scene = (_class6 = class _Scene {
    * without removing it from the scene graph. Components that manage dynamic
    * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
    * this before discarding those children so their shadow `<a>`/controls don't
-   * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
+   * leak.
+   *
+   * `syncA11y` itself only creates and updates, never prunes — but it is always
+   * followed by `enforceA11yDomOrder`, whose prune pass removes any element
+   * whose entity is no longer reachable in the tree or no longer satisfies
+   * {@link shouldProjectA11y}. So an entity that is `remove()`d, or whose
+   * `interactive` flips to `false`, has its element torn down on the next synced
+   * frame without any explicit call.
+   *
+   * This method is for the case that pass cannot see: a child dropped from a
+   * component's own bookkeeping while still parented, or one discarded before
+   * the next sync runs. Calling it is always safe and is the right habit for
+   * pooled children.
    *
    * @param entity - The subtree whose shadow nodes should be removed.
    */
@@ -2932,12 +2944,34 @@ var Scene = (_class6 = class _Scene {
     }
     if (element.getAttribute(name) !== value) element.setAttribute(name, value);
   }
+  /**
+   * Whether `node` should have an a11y shadow element projected for it.
+   *
+   * The single authority for that decision. It was previously inlined verbatim
+   * at four call sites — `syncA11y` (create/update), `enforceA11yDomOrder`
+   * (which ids survive pruning), `getA11yTree` (the public snapshot) and
+   * `render` (z-index / reading-order assignment). Four copies of one predicate
+   * is a standing correctness hazard: if any of them drifts, elements either
+   * leak (created but never marked active, so pruned every frame and rebuilt) or
+   * go missing from the semantic tree while still present in the DOM.
+   *
+   * A box is required because a zero-size element is unfocusable and
+   * unhittable; `a11yFullViewport` is the deliberate exception, since those
+   * nodes are boundless interaction surfaces mounted behind everything else.
+   *
+   * Keep this the only place the rule is written. A planned per-entity
+   * `a11yProjection` mode ('eager' | 'onDemand' | 'never') extends exactly this
+   * predicate, which is only tractable while it has one home.
+   */
+  shouldProjectA11y(node) {
+    return node.interactive && (node.width > 0 || node.a11yFullViewport);
+  }
   syncA11y(node) {
     if (!this.a11yRoot) return;
     if (node.isDOMPortal) {
       return;
     }
-    if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+    if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
       const expectedTag = attrs.tag || "div";
@@ -3713,7 +3747,7 @@ var Scene = (_class6 = class _Scene {
         if (node.a11yFullViewport) this.fullViewportElements.push(contentEl);
         else this.normalElements.push(contentEl);
       }
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           this.activeIds.add(node.id);
@@ -3852,7 +3886,7 @@ var Scene = (_class6 = class _Scene {
     const traverse = (node, parentNode) => {
       if (node.isDOMPortal) return;
       let currentA11yNode = null;
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           const attrs = node.getA11yAttributes();
@@ -4222,7 +4256,7 @@ var Scene = (_class6 = class _Scene {
       const orthogonalTolerance = Math.max(1, worldScaleX * worldScaleY) * 1e-6;
       const isSimilarityTransform = Number.isFinite(worldScaleX) && Number.isFinite(worldScaleY) && Math.abs(worldScaleX - worldScaleY) <= scaleTolerance && Math.abs(a * c + b * d) <= orthogonalTolerance;
       const a11yEl = isMainRenderer ? this.a11yElements.get(node.id) : void 0;
-      const willProjectA11y = isMainRenderer && node.interactive && (node.width > 0 || node.a11yFullViewport);
+      const willProjectA11y = isMainRenderer && this.shouldProjectA11y(node);
       if (a11yEl || willProjectA11y) {
         const renderOrder = this.renderOrderCounter++;
         if (willProjectA11y) this.a11yRenderOrders.set(node.id, renderOrder);

package/dist/index.mjs

@@ -2161,17 +2161,17 @@ var Scene = class _Scene {
     this._devFrameCount++;
     if (this._devFrameCount % 120 !== 0) return;
     if (this.a11yElements) {
-      let interactiveCount = 0;
+      let projectableCount = 0;
       const walk = (node) => {
-        if (node.interactive && node.width > 0) interactiveCount++;
+        if (this.shouldProjectA11y(node)) projectableCount++;
         for (const c of node.children) walk(c);
       };
       walk(this.root);
       for (const c of this.overlayRoot.children) walk(c);
       const shadowCount = this.a11yElements.size;
-      if (shadowCount > interactiveCount + 2) {
+      if (shadowCount > projectableCount) {
         this._devWarn(
-          `a11yElements (${shadowCount}) exceeds interactive entities (${interactiveCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
+          `a11yElements (${shadowCount}) exceeds projectable entities (${projectableCount}). Call scene.detachA11y(entity) before removing interactive children from the tree, or their shadow nodes leak.`
         );
       }
     }
@@ -2642,7 +2642,19 @@ var Scene = class _Scene {
    * without removing it from the scene graph. Components that manage dynamic
    * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
    * this before discarding those children so their shadow `<a>`/controls don't
-   * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
+   * leak.
+   *
+   * `syncA11y` itself only creates and updates, never prunes — but it is always
+   * followed by `enforceA11yDomOrder`, whose prune pass removes any element
+   * whose entity is no longer reachable in the tree or no longer satisfies
+   * {@link shouldProjectA11y}. So an entity that is `remove()`d, or whose
+   * `interactive` flips to `false`, has its element torn down on the next synced
+   * frame without any explicit call.
+   *
+   * This method is for the case that pass cannot see: a child dropped from a
+   * component's own bookkeeping while still parented, or one discarded before
+   * the next sync runs. Calling it is always safe and is the right habit for
+   * pooled children.
    *
    * @param entity - The subtree whose shadow nodes should be removed.
    */
@@ -2931,12 +2943,34 @@ var Scene = class _Scene {
     }
     if (element.getAttribute(name) !== value) element.setAttribute(name, value);
   }
+  /**
+   * Whether `node` should have an a11y shadow element projected for it.
+   *
+   * The single authority for that decision. It was previously inlined verbatim
+   * at four call sites — `syncA11y` (create/update), `enforceA11yDomOrder`
+   * (which ids survive pruning), `getA11yTree` (the public snapshot) and
+   * `render` (z-index / reading-order assignment). Four copies of one predicate
+   * is a standing correctness hazard: if any of them drifts, elements either
+   * leak (created but never marked active, so pruned every frame and rebuilt) or
+   * go missing from the semantic tree while still present in the DOM.
+   *
+   * A box is required because a zero-size element is unfocusable and
+   * unhittable; `a11yFullViewport` is the deliberate exception, since those
+   * nodes are boundless interaction surfaces mounted behind everything else.
+   *
+   * Keep this the only place the rule is written. A planned per-entity
+   * `a11yProjection` mode ('eager' | 'onDemand' | 'never') extends exactly this
+   * predicate, which is only tractable while it has one home.
+   */
+  shouldProjectA11y(node) {
+    return node.interactive && (node.width > 0 || node.a11yFullViewport);
+  }
   syncA11y(node) {
     if (!this.a11yRoot) return;
     if (node.isDOMPortal) {
       return;
     }
-    if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+    if (this.shouldProjectA11y(node)) {
       let el = this.a11yElements.get(node.id);
       const attrs = node.getA11yAttributes();
       const expectedTag = attrs.tag || "div";
@@ -3712,7 +3746,7 @@ var Scene = class _Scene {
         if (node.a11yFullViewport) this.fullViewportElements.push(contentEl);
         else this.normalElements.push(contentEl);
       }
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           this.activeIds.add(node.id);
@@ -3851,7 +3885,7 @@ var Scene = class _Scene {
     const traverse = (node, parentNode) => {
       if (node.isDOMPortal) return;
       let currentA11yNode = null;
-      if (node.interactive && (node.width > 0 || node.a11yFullViewport)) {
+      if (this.shouldProjectA11y(node)) {
         const el = this.a11yElements.get(node.id);
         if (el) {
           const attrs = node.getA11yAttributes();
@@ -4221,7 +4255,7 @@ var Scene = class _Scene {
       const orthogonalTolerance = Math.max(1, worldScaleX * worldScaleY) * 1e-6;
       const isSimilarityTransform = Number.isFinite(worldScaleX) && Number.isFinite(worldScaleY) && Math.abs(worldScaleX - worldScaleY) <= scaleTolerance && Math.abs(a * c + b * d) <= orthogonalTolerance;
       const a11yEl = isMainRenderer ? this.a11yElements.get(node.id) : void 0;
-      const willProjectA11y = isMainRenderer && node.interactive && (node.width > 0 || node.a11yFullViewport);
+      const willProjectA11y = isMainRenderer && this.shouldProjectA11y(node);
       if (a11yEl || willProjectA11y) {
         const renderOrder = this.renderOrderCounter++;
         if (willProjectA11y) this.a11yRenderOrders.set(node.id, renderOrder);

package/dist/tree/Scene.d.ts

@@ -673,7 +673,19 @@ export declare class Scene {
      * without removing it from the scene graph. Components that manage dynamic
      * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
      * this before discarding those children so their shadow `<a>`/controls don't
-     * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
+     * leak.
+     *
+     * `syncA11y` itself only creates and updates, never prunes — but it is always
+     * followed by `enforceA11yDomOrder`, whose prune pass removes any element
+     * whose entity is no longer reachable in the tree or no longer satisfies
+     * {@link shouldProjectA11y}. So an entity that is `remove()`d, or whose
+     * `interactive` flips to `false`, has its element torn down on the next synced
+     * frame without any explicit call.
+     *
+     * This method is for the case that pass cannot see: a child dropped from a
+     * component's own bookkeeping while still parented, or one discarded before
+     * the next sync runs. Calling it is always safe and is the right habit for
+     * pooled children.
      *
      * @param entity - The subtree whose shadow nodes should be removed.
      */
@@ -756,6 +768,26 @@ export declare class Scene {
     /** True when any node in the subtree has a pending animation. */
     /** True when any node in the subtree is interactive (drives a11y sync). */
     private syncOptionalAttribute;
+    /**
+     * Whether `node` should have an a11y shadow element projected for it.
+     *
+     * The single authority for that decision. It was previously inlined verbatim
+     * at four call sites — `syncA11y` (create/update), `enforceA11yDomOrder`
+     * (which ids survive pruning), `getA11yTree` (the public snapshot) and
+     * `render` (z-index / reading-order assignment). Four copies of one predicate
+     * is a standing correctness hazard: if any of them drifts, elements either
+     * leak (created but never marked active, so pruned every frame and rebuilt) or
+     * go missing from the semantic tree while still present in the DOM.
+     *
+     * A box is required because a zero-size element is unfocusable and
+     * unhittable; `a11yFullViewport` is the deliberate exception, since those
+     * nodes are boundless interaction surfaces mounted behind everything else.
+     *
+     * Keep this the only place the rule is written. A planned per-entity
+     * `a11yProjection` mode ('eager' | 'onDemand' | 'never') extends exactly this
+     * predicate, which is only tractable while it has one home.
+     */
+    private shouldProjectA11y;
     private syncA11y;
     /**
      * Mirror one entity's static text ({@link Entity.getContentProjection}) as a

package/package.json

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