@vectojs/core 1.38.0 → 1.39.0

package/dist/index.mjs

@@ -11,14 +11,14 @@ import {
   parseColorToRGBA,
   sanitizeUrl,
   setRendererDevMode
-} from "./chunk-LWEMD34D.mjs";
+} from "./chunk-RUM2KEDI.mjs";
 import {
   Entity,
   MSDFTextEntity,
   SVGEntity,
   VectoJSEvent,
   contentLineInHint
-} from "./chunk-QVTCKWDO.mjs";
+} from "./chunk-7PYD5UDX.mjs";
 
 // src/tree/ComputeParticleEntity.ts
 var PARTICLE_STRIDE_FLOATS = 8;
@@ -224,14 +224,14 @@ var ComputeParticleEntity = class extends Entity {
     const bounceDamping = Math.max(0, Math.min(1, this.bounceDamping));
     const maxVelocity = Math.max(1, this.maxVelocity);
     for (let i = 0; i < this.maxParticles; i++) {
-      const offset = i * 8;
-      let px = this.particleData[offset];
-      let py = this.particleData[offset + 1];
-      let vx = this.particleData[offset + 2];
-      let vy = this.particleData[offset + 3];
-      const ox = this.particleData[offset + 4];
-      const oy = this.particleData[offset + 5];
-      const life = this.particleData[offset + 7];
+      const offset = i * PARTICLE_STRIDE_FLOATS;
+      let px = this.particleData[offset + PARTICLE_OFFSET_POSITION_X];
+      let py = this.particleData[offset + PARTICLE_OFFSET_POSITION_Y];
+      let vx = this.particleData[offset + PARTICLE_OFFSET_VELOCITY_X];
+      let vy = this.particleData[offset + PARTICLE_OFFSET_VELOCITY_Y];
+      const ox = this.particleData[offset + PARTICLE_OFFSET_ORIGIN_X];
+      const oy = this.particleData[offset + PARTICLE_OFFSET_ORIGIN_Y];
+      const life = this.particleData[offset + PARTICLE_OFFSET_LIFE];
       if (isNaN(px)) px = ox;
       if (isNaN(py)) py = oy;
       if (isNaN(vx)) vx = 0;
@@ -289,11 +289,11 @@ var ComputeParticleEntity = class extends Entity {
       if (life >= 0) {
         nlife = Math.max(0, life - safeDt * 0.5);
       }
-      this.particleData[offset] = npx;
-      this.particleData[offset + 1] = npy;
-      this.particleData[offset + 2] = nvx;
-      this.particleData[offset + 3] = nvy;
-      this.particleData[offset + 7] = nlife;
+      this.particleData[offset + PARTICLE_OFFSET_POSITION_X] = npx;
+      this.particleData[offset + PARTICLE_OFFSET_POSITION_Y] = npy;
+      this.particleData[offset + PARTICLE_OFFSET_VELOCITY_X] = nvx;
+      this.particleData[offset + PARTICLE_OFFSET_VELOCITY_Y] = nvy;
+      this.particleData[offset + PARTICLE_OFFSET_LIFE] = nlife;
     }
     this.pendingExplosion = null;
   }
@@ -593,7 +593,12 @@ var ContentGridProjector = class {
           lineIndex === 0
         );
         const reusable = existingLines[domIndex];
-        if (reusable !== void 0 && reusable.dataset.vectoGridLineSig === lineSignature && reusable.dataset.vectoGridLine === `${lineIndex}`) {
+        if (reusable !== void 0 && reusable.dataset.vectoGridLineSig === lineSignature) {
+          const indexLabel = `${lineIndex}`;
+          if (reusable.dataset.vectoGridLine !== indexLabel) {
+            reusable.dataset.vectoGridLine = indexLabel;
+            reusable.style.top = `${(projectedLine?.y ?? lineIndex * grid.lineHeight) + baseline - cssLineBoxBaseline(lineFont, lineHeight)}px`;
+          }
           continue;
         }
         if (selectionLine !== null && selectionLine === lineIndex) rebuiltSelectionLine = true;
@@ -779,6 +784,12 @@ function projectionCaretAt(root, absoluteOffset, affinity) {
 }
 
 // src/tree/scene/A11yProjectionManager.ts
+function orderBandBottom(r) {
+  return r.container ? r.top + 4 : r.top + Math.max(Number.parseFloat(r.el.style.height) || 0, 4);
+}
+var byTopThenIndex = (p, q) => p.top - q.top || p.i - q.i;
+var byLeftAscThenIndex = (p, q) => p.left - q.left || p.i - q.i;
+var byLeftDescThenIndex = (p, q) => q.left - p.left || p.i - q.i;
 var A11yProjectionManager = class {
   /**
    * Set by anything that changes which elements exist or how they nest, and
@@ -820,6 +831,18 @@ var A11yProjectionManager = class {
    * implicit root region. See {@link sortNormalElementsVisually}.
    */
   orderRegions = /* @__PURE__ */ new Map();
+  /**
+   * Decoration records for {@link sortNormalElementsVisually}: one per ordered
+   * element, pooled across passes and rewritten in place — the sort runs on
+   * structure-change frames, where the module's zero-GC policy applies.
+   */
+  orderDecorated = [];
+  /** Region → decorated elements, reused by {@link sortNormalElementsVisually}. */
+  orderBucketByRegion = /* @__PURE__ */ new Map();
+  /** Pool of bucket arrays backing {@link orderBucketByRegion} across passes. */
+  orderBuckets = [];
+  /** Scratch for one visual row inside {@link sortNormalElementsVisually}. */
+  orderRowScratch = [];
   /** Mark the projected DOM as needing a reorder on the next pass. */
   markNeedsReorder() {
     this.needsReorder = true;
@@ -877,7 +900,8 @@ var A11yProjectionManager = class {
       this.orderCursors.set(parent, at + 1);
       const current = parent.childNodes[at];
       if (current !== expected) {
-        const refocus = document.activeElement === expected;
+        const active = document.activeElement;
+        const refocusTarget = active && (active === expected || expected.contains(active)) ? active : null;
         if (!selectionSnapshotTaken) {
           selectionSnapshotTaken = true;
           const live = typeof window !== "undefined" && typeof window.getSelection === "function" ? window.getSelection() : null;
@@ -893,7 +917,7 @@ var A11yProjectionManager = class {
           selectionMoved = true;
         }
         parent.insertBefore(expected, current || null);
-        if (refocus) expected.focus({ preventScroll: true });
+        if (refocusTarget) refocusTarget.focus({ preventScroll: true });
       }
     }
     if (selectionMoved && selection && selAnchorNode && selFocusNode) {
@@ -940,7 +964,6 @@ var A11yProjectionManager = class {
   sortNormalElementsVisually(rtl) {
     const els = this.normalElements;
     if (els.length < 2) return;
-    const heightOf = (el) => Math.max(Number.parseFloat(el.style.height) || 0, 4);
     const members = this.orderMembers;
     const containers = this.orderContainers;
     members.clear();
@@ -951,52 +974,70 @@ var A11yProjectionManager = class {
         if (members.has(p)) containers.add(p);
       }
     }
-    const absolute = (el) => {
+    const decorated = this.orderDecorated;
+    while (decorated.length < els.length) {
+      decorated.push({ el: els[0], i: 0, top: 0, left: 0, container: false });
+    }
+    for (let i = 0; i < els.length; i++) {
+      const rec = decorated[i];
       let top = 0;
       let left = 0;
-      for (let node = el; node; node = node.parentElement) {
+      for (let node = els[i]; node; node = node.parentElement) {
         top += Number.parseFloat(node.style.top) || 0;
         left += Number.parseFloat(node.style.left) || 0;
         const parent = node.parentElement;
         if (!parent || !members.has(parent)) break;
       }
-      return { top, left };
-    };
-    const decorated = els.map((el, i) => {
-      const { top, left } = absolute(el);
-      return { el, i, top, left, container: containers.has(el) };
-    });
+      rec.el = els[i];
+      rec.i = i;
+      rec.top = top;
+      rec.left = left;
+      rec.container = containers.has(els[i]);
+    }
     const regions = this.orderRegions;
-    const buckets = /* @__PURE__ */ new Map();
-    for (const d of decorated) {
-      const key = regions.get(d.el) ?? null;
-      const bucket = buckets.get(key);
-      if (bucket) bucket.push(d);
-      else buckets.set(key, [d]);
-    }
-    const bandBottom = (r) => r.top + (r.container ? 4 : heightOf(r.el));
-    const sorted = [];
+    const buckets = this.orderBucketByRegion;
+    const bucketPool = this.orderBuckets;
+    let bucketsUsed = 0;
+    buckets.clear();
+    for (let i = 0; i < els.length; i++) {
+      const rec = decorated[i];
+      const key = regions.get(rec.el) ?? null;
+      let bucket = buckets.get(key);
+      if (!bucket) {
+        bucket = bucketPool[bucketsUsed];
+        if (bucket === void 0) {
+          bucket = [];
+          bucketPool.push(bucket);
+        }
+        bucketsUsed++;
+        bucket.length = 0;
+        buckets.set(key, bucket);
+      }
+      bucket.push(rec);
+    }
+    let out = 0;
     for (const order of buckets.values()) {
-      order.sort((p, q) => p.top - q.top || p.i - q.i);
+      order.sort(byTopThenIndex);
       let rowStart = 0;
-      let rowBottom = order.length ? bandBottom(order[0]) : 0;
+      let rowBottom = order.length ? orderBandBottom(order[0]) : 0;
       const flushRow = (end) => {
-        const row = order.slice(rowStart, end);
-        row.sort((p, q) => (rtl ? q.left - p.left : p.left - q.left) || p.i - q.i);
-        for (const r of row) sorted.push(r.el);
+        const row = this.orderRowScratch;
+        row.length = 0;
+        for (let m = rowStart; m < end; m++) row.push(order[m]);
+        row.sort(rtl ? byLeftDescThenIndex : byLeftAscThenIndex);
+        for (const r of row) els[out++] = r.el;
       };
       for (let k = 1; k < order.length; k++) {
         if (order[k].top < rowBottom) {
-          rowBottom = Math.max(rowBottom, bandBottom(order[k]));
+          rowBottom = Math.max(rowBottom, orderBandBottom(order[k]));
         } else {
           flushRow(k);
           rowStart = k;
-          rowBottom = bandBottom(order[k]);
+          rowBottom = orderBandBottom(order[k]);
         }
       }
       flushRow(order.length);
     }
-    for (let i = 0; i < sorted.length; i++) els[i] = sorted[i];
   }
 };
 
@@ -1327,6 +1368,8 @@ var DriverTicker = class {
     tD.length = tweenCount;
     backend.ensure(springCount, tweenCount);
     backend.revalidateViews();
+    let springsRejected = false;
+    let tweensRejected = false;
     if (springCount > 0) {
       const sv = backend.springView();
       for (let i = 0; i < springCount; i++) {
@@ -1342,8 +1385,7 @@ var DriverTicker = class {
         for (let i = 0; i < springCount; i++) sD[i].syncExternal(sv.val[i], sv.vel[i]);
       } else {
         for (let i = 0; i < springCount; i++) sD[i].tick(dt);
-        this.backends.animReason = "rejected";
-        this.backends.animBatchedLastFrame = false;
+        springsRejected = true;
       }
     }
     if (tweenCount > 0) {
@@ -1361,10 +1403,13 @@ var DriverTicker = class {
         for (let i = 0; i < tweenCount; i++) tD[i].syncExternal(tv.val[i], tv.elapsed[i]);
       } else {
         for (let i = 0; i < tweenCount; i++) tD[i].tick(dt);
-        this.backends.animReason = "rejected";
-        this.backends.animBatchedLastFrame = false;
+        tweensRejected = true;
       }
     }
+    if (springsRejected || tweensRejected) {
+      this.backends.animReason = springsRejected && tweensRejected ? "rejected" : springsRejected ? "springs-rejected" : "tweens-rejected";
+      this.backends.animBatchedLastFrame = springCount > 0 && !springsRejected || tweenCount > 0 && !tweensRejected;
+    }
     for (let i = 0; i < springCount; i++) sE[i]._applyDriverTick(sP[i], sD[i]);
     for (let i = 0; i < tweenCount; i++) tE[i]._applyDriverTick(tP[i], tD[i]);
   }
@@ -1525,9 +1570,6 @@ function intersectBounds(a, b) {
     height: Math.max(0, bottom - y)
   };
 }
-function pointInBounds(b, x, y) {
-  return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
-}
 var HitTester = class {
   root;
   overlayRoot;
@@ -1574,7 +1616,7 @@ var HitTester = class {
       this.backends.hitReason = "not-installed";
       return false;
     }
-    if (this.backends.hitGridFrame === frame) {
+    if (this.backends.hitGridFrame === frame && this.backends.hitGridStructureVersion === this.backends.structureVersion) {
       return this.backends.hitGridOk;
     }
     let gathered = null;
@@ -1605,6 +1647,7 @@ var HitTester = class {
     this.slotEntity = gathered.slotEntity;
     this.boundless = gathered.boundless;
     this.backends.hitGridFrame = frame;
+    this.backends.hitGridStructureVersion = this.backends.structureVersion;
     this.backends.hitGridOk = ok;
     this.backends.hitReason = ok ? "active" : "rejected";
     return ok;
@@ -1655,7 +1698,7 @@ var HitTester = class {
       const hit = this.findHitRecursively(node.children[i], x, y, childClip);
       if (hit) return hit;
     }
-    if (node.isPointInside && node.isPointInside(x, y) && (!clip || pointInBounds(clip, x, y)) && !this.isPointerTransparent(node)) {
+    if (node.isPointInside && node.isPointInside(x, y) && this.isInsideAllClippers(node, x, y) && !this.isPointerTransparent(node)) {
       return node;
     }
     return null;
@@ -1667,6 +1710,25 @@ var HitTester = class {
     const attrs = node.getA11yAttributes();
     return attrs.disabled === true || attrs.pointerEvents === "none";
   }
+  /**
+   * Exact rotation-aware `clipChildren` test shared by BOTH hit paths: the
+   * point must lie inside every clipChildren ancestor's local rect — the same
+   * shape rendering clips to — not merely inside the ancestor's world AABB.
+   * For a rotated clipper those disagree, and until both paths used the exact
+   * rect a query's answer depended on which backend was active (#680). The
+   * clip-stack AABB intersection in {@link findHitRecursively} remains purely
+   * as a subtree-pruning pre-filter; this is the authoritative gate.
+   */
+  isInsideAllClippers(node, x, y) {
+    for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+      if (!ancestor.clipChildren) continue;
+      const local = ancestor.worldToLocal(x, y);
+      if (!local || local.x < 0 || local.y < 0 || local.x > ancestor.width || local.y > ancestor.height) {
+        return false;
+      }
+    }
+    return true;
+  }
   /**
    * Whether a confirmed geometric hit on `node` at world `(x, y)` is a REAL hit,
    * applying the same visibility/input gating as {@link findHitRecursively} but
@@ -1681,14 +1743,8 @@ var HitTester = class {
     if (node.opacity <= 0) return false;
     for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
       if (ancestor.opacity <= 0) return false;
-      if (ancestor.clipChildren && ancestor.width > 0 && ancestor.height > 0) {
-        const local = ancestor.worldToLocal(x, y);
-        if (!local || local.x < 0 || local.y < 0 || local.x > ancestor.width || local.y > ancestor.height) {
-          return false;
-        }
-      }
     }
-    return true;
+    return this.isInsideAllClippers(node, x, y);
   }
 };
 
@@ -2441,7 +2497,8 @@ var WasmTransformBackend = class {
       this.lastStatus = WASM_STATUS.CAPACITY;
       return;
     }
-    const status = kernel === "scalar" ? this.ex.compose_scalar() : this.ex.compose_simd();
+    const simd = kernel === "simd" && typeof this.ex.compose_simd === "function";
+    const status = simd ? this.ex.compose_simd() : this.ex.compose_scalar();
     this.lastStatus = status;
     if (status !== WASM_STATUS.OK) return;
     store.wa.set(this.vwa.subarray(0, n));
@@ -2463,7 +2520,8 @@ var WasmTransformBackend = class {
    * {@link uploadRuns} after a topology change.
    */
   runKernel(kernel = "simd") {
-    const status = kernel === "scalar" ? this.ex.compose_scalar() : this.ex.compose_simd();
+    const simd = kernel === "simd" && typeof this.ex.compose_simd === "function";
+    const status = simd ? this.ex.compose_simd() : this.ex.compose_scalar();
     this.lastStatus = status;
     return status;
   }
@@ -2515,21 +2573,21 @@ var WasmTransformBackend = class {
   /**
    * Compute world-space AABBs for `store` in WASM (G1+), writing back into its
    * `aminx/aminy/amaxx/amaxy` arrays. Uploads the local bounds, runs the AABB
-   * pass, reads results back. Result is bit-identical to `computeAabbsJS(store)`.
-   * `compose` (or `runKernel`) must have populated the world matrices first —
-   * this pass reads them. For the resident (no-copy) integration, write bounds
-   * via {@link boundsView} and read via {@link aabbView} + call
-   * {@link runAabbs} instead.
+   * pass, reads results back. Result is bit-identical to `computeAabbsJS(store)`
+   * for both kernels. `compose` (or `runKernel`) must have populated the world
+   * matrices first — this pass reads them. For the resident (no-copy)
+   * integration, write bounds via {@link boundsView} and read via
+   * {@link aabbView} + call {@link runAabbs} instead.
    */
-  computeAabbs(store) {
+  computeAabbs(store, kernel = "simd") {
     this.ensure(store.count, store.runCount);
     const n = store.count;
     this.vbx.set(store.bx.subarray(0, n));
     this.vby.set(store.by.subarray(0, n));
     this.vbw.set(store.bw.subarray(0, n));
     this.vbh.set(store.bh.subarray(0, n));
-    this.lastStatus = this.ex.compute_aabbs(n);
-    if (this.lastStatus !== WASM_STATUS.OK) return;
+    const ok = this.runAabbs(n, kernel);
+    if (!ok) return;
     store.aminx.set(this.vaminx.subarray(0, n));
     store.aminy.set(this.vaminy.subarray(0, n));
     store.amaxx.set(this.vamaxx.subarray(0, n));
@@ -2540,8 +2598,9 @@ var WasmTransformBackend = class {
    *  composed). No upload/readback — the per-frame resident path. Returns
    *  `false` if the kernel rejected `count` (beyond capacity, or uninitialized),
    *  in which case {@link aabbView} still holds the previous frame's bounds. */
-  runAabbs(count) {
-    this.lastStatus = this.ex.compute_aabbs(count);
+  runAabbs(count, kernel = "simd") {
+    const simd = kernel === "simd" && typeof this.ex.compute_aabbs_simd === "function";
+    this.lastStatus = simd ? this.ex.compute_aabbs_simd(count) : this.ex.compute_aabbs(count);
     return this.lastStatus === WASM_STATUS.OK;
   }
   /** Resident wasm local-bounds input views (`bx,by,bw,bh`) for the AABB pass. */
@@ -3204,6 +3263,7 @@ var WasmBackendFacade = class {
   setHit(backend) {
     this._hit = backend;
     this.hitGridFrame = -1;
+    this.hitGridStructureVersion = -1;
     this.hitReason = backend ? "not-applicable" : "not-installed";
   }
   /** The installed batched-animation backend, or `null` for the JS tick. */
@@ -3260,6 +3320,13 @@ var WasmBackendFacade = class {
   // domain.
   /** Frame the hit grid was last built for; `-1` forces a rebuild. */
   hitGridFrame = -1;
+  /**
+   * Structure version the hit grid was built for; `-1` forces a rebuild.
+   * Half of the cache key the comment above promises: without it, a pointer
+   * query in the same frame as a structural mutation would resolve against
+   * pre-mutation geometry while the JS walk sees live state.
+   */
+  hitGridStructureVersion = -1;
   /** Whether that build succeeded (did not overflow its item budget). */
   hitGridOk = false;
   /**
@@ -3399,6 +3466,38 @@ var WasmBackendFacade = class {
   }
 };
 
+// src/tree/scene/keyboard.ts
+function normalizeChord(input) {
+  if (typeof input === "string") {
+    const parts = input.split("+").map((p) => p.trim()).filter(Boolean);
+    const mods = /* @__PURE__ */ new Set();
+    let key2 = "";
+    for (const p of parts) {
+      const low = p.toLowerCase();
+      if (low === "ctrl" || low === "control") mods.add("Control");
+      else if (low === "alt") mods.add("Alt");
+      else if (low === "shift") mods.add("Shift");
+      else if (low === "meta" || low === "cmd" || low === "super") mods.add("Meta");
+      else key2 = p.length === 1 ? p.toUpperCase() : p;
+    }
+    const ordered2 = ["Control", "Alt", "Shift", "Meta"].filter((m) => mods.has(m));
+    return key2 ? [...ordered2, key2].join("+") : ordered2.join("+");
+  }
+  const ordered = [];
+  if (input.ctrlKey) ordered.push("Control");
+  if (input.altKey) ordered.push("Alt");
+  if (input.shiftKey) ordered.push("Shift");
+  if (input.metaKey) ordered.push("Meta");
+  let key = input.key;
+  if (key === " ") key = "Space";
+  else if (key.length === 1) key = key.toUpperCase();
+  if (["Control", "Alt", "Shift", "Meta"].includes(key)) {
+    return ordered.join("+");
+  }
+  ordered.push(key);
+  return ordered.join("+");
+}
+
 // src/tree/Scene.ts
 var RANGE_VALUE_ROLES = /* @__PURE__ */ new Set(["slider", "spinbutton", "progressbar", "scrollbar", "meter"]);
 var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
@@ -3412,6 +3511,24 @@ var INTERACTIVE_A11Y_ROLES = /* @__PURE__ */ new Set([
   "slider",
   "combobox"
 ]);
+var KEYBOARD_OWNING_ROLES = /* @__PURE__ */ new Set([
+  ...INTERACTIVE_A11Y_ROLES,
+  "option",
+  "listbox",
+  "textbox",
+  "searchbox",
+  "spinbutton"
+]);
+function ownsKeyboard(el) {
+  if (!el) return false;
+  if (el === document.body || el === document.documentElement) return false;
+  if (el.hasAttribute("data-vecto-a11y-root")) return false;
+  const tag = el.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (el.isContentEditable) return true;
+  const role = el.getAttribute("role");
+  return role !== null && KEYBOARD_OWNING_ROLES.has(role);
+}
 var A11Y_REQUIRED_OWNED = /* @__PURE__ */ new Map([
   ["grid", /* @__PURE__ */ new Set(["row", "rowgroup"])],
   ["table", /* @__PURE__ */ new Set(["row", "rowgroup"])],
@@ -3950,6 +4067,9 @@ var Scene = class _Scene {
   // server-side (e.g. headless layout / vector export) without jsdom.
   a11yRoot;
   a11yElements = /* @__PURE__ */ new Map();
+  /** Elements that already have the synthetic Enter/Space activation handler
+   *  (see the syncA11y refresh pass) — install-once bookkeeping (#694). */
+  keyboardActivatedA11y = /* @__PURE__ */ new WeakSet();
   // --- domain: content-projection — projected DOM, sync state, calibration, selection ---
   /** DOM nodes mirroring static text content, keyed by entity id. */
   contentElements = /* @__PURE__ */ new Map();
@@ -4574,6 +4694,15 @@ var Scene = class _Scene {
   _registerActiveDriverSubtree(entity) {
     this._driverTicker.registerSubtree(entity);
   }
+  /**
+   * The `dt` of the frame currently executing its update walk (the WASM-mode
+   * pre-pass or the JS-mode interleaved render walk), or `null` outside it.
+   * Read by `Entity._spawnDriver`: a driver spawned mid-walk onto an entity the
+   * batched pass already claimed this frame must be advanced once here, or
+   * `tickDrivers()`'s per-frame stamp would skip it a full frame — a one-frame
+   * JS/WASM divergence. Written in {@link render} next to `_tickBatchedDrivers`.
+   */
+  _updateWalkDt = null;
   // --- domain: render-scheduler — batched driver tick (extraction 6), reads the anim backend ---
   /**
    * Advance every registered entity's active drivers for this frame, batching
@@ -4661,6 +4790,13 @@ var Scene = class _Scene {
   /** Element the pointer listeners are bound to (parent container if present,
    *  else the canvas). Stored so `destroy()` detaches from the same element. */
   pointerEventTarget = null;
+  // --- scene-level keyboard channel state (see on/off/registerShortcut) ---
+  keydownHandlers = [];
+  keyupHandlers = [];
+  /** Chord-normalized shortcut table, matched on keydown only. */
+  shortcuts = [];
+  windowKeyDownHandler = null;
+  windowKeyUpHandler = null;
   hasWarnedZeroSize = false;
   /**
    * Latch for {@link Scene.resize}'s invalid-dimension warning.
@@ -5267,6 +5403,19 @@ var Scene = class _Scene {
       window.removeEventListener("blur", this.contentSelectionEndListener);
       this.contentSelectionEndListener = null;
     }
+    if (typeof window !== "undefined") {
+      if (this.windowKeyDownHandler) {
+        window.removeEventListener("keydown", this.windowKeyDownHandler);
+      }
+      if (this.windowKeyUpHandler) {
+        window.removeEventListener("keyup", this.windowKeyUpHandler);
+      }
+    }
+    this.windowKeyDownHandler = null;
+    this.windowKeyUpHandler = null;
+    this.keydownHandlers.length = 0;
+    this.keyupHandlers.length = 0;
+    this.shortcuts.length = 0;
     if (typeof window !== "undefined" && this.pointerEventTarget && typeof this.pointerEventTarget.removeEventListener === "function") {
       if (this.pointerMoveListener) {
         this.pointerEventTarget.removeEventListener("pointermove", this.pointerMoveListener);
@@ -5366,6 +5515,7 @@ var Scene = class _Scene {
     this.lastTime = typeof performance !== "undefined" ? performance.now() : 0;
     this.watchCanvasVisibility();
     this.scheduleFrame();
+    this.attachWindowKeyListeners();
     const isTextFocused = this.focusedA11yElement instanceof HTMLInputElement || this.focusedA11yElement instanceof HTMLTextAreaElement;
     if (isTextFocused && this.renderMode === "onDemand" && !this.caretBlinkTimer) {
       this.caretBlinkTimer = setInterval(() => {
@@ -5433,6 +5583,132 @@ var Scene = class _Scene {
     }
     this._canvasOnScreen = true;
   }
+  // --- domain: input — scene-level keyboard channel ---
+  /**
+   * Register a listener on the scene-level keyboard channel.
+   *
+   * Mirrors {@link Entity.on} minus the options parameter (bubble-only, and
+   * there is no capture phase for a single window tap). Handlers fire only
+   * when ALL of these hold:
+   *
+   * 1. the native event was not already `defaultPrevented`,
+   * 2. it is not an auto-repeat (`e.repeat`),
+   * 3. `document.activeElement` does not own the keyboard
+   *    (see {@link ownsKeyboard}) — typing in an `<input>` or focusing a
+   *    slider-role element suppresses the scene channel, unconditionally,
+   *    including modifier chords.
+   *
+   * The listeners are window-level BUBBLE-phase taps, so an entity handler
+   * that calls `nativeEvent.stopPropagation()` keeps the key from ever
+   * reaching this channel. Deliberately not registered in the capture phase:
+   * a window-capture listener would preempt Modal's document-capture trap.
+   *
+   * Listeners attach at `start()` and survive `stop()`; only `destroy()`
+   * removes them.
+   *
+   * @param event - `'keydown'` or `'keyup'`; anything else is rejected with a
+   *   dev warning (guards JS callers — TypeScript already narrows this).
+   * @param callback - Handler invoked with a {@link SceneKeyEvent}.
+   * @returns `this` for method chaining.
+   */
+  on(event, callback) {
+    if (event !== "keydown" && event !== "keyup") {
+      console.warn(
+        `[VectoJS] Scene.on: unsupported event '${String(event)}'. Only 'keydown' and 'keyup' are supported.`
+      );
+      return this;
+    }
+    (event === "keydown" ? this.keydownHandlers : this.keyupHandlers).push(callback);
+    return this;
+  }
+  /**
+   * Remove a listener previously registered with {@link Scene.on}. Silent
+   * no-op for unknown handlers, unsupported event names, or after
+   * {@link Scene.destroy}.
+   *
+   * @returns `this` for method chaining.
+   */
+  off(event, callback) {
+    if (event !== "keydown" && event !== "keyup") {
+      console.warn(
+        `[VectoJS] Scene.off: unsupported event '${String(event)}'. Only 'keydown' and 'keyup' are supported.`
+      );
+      return this;
+    }
+    const handlers = event === "keydown" ? this.keydownHandlers : this.keyupHandlers;
+    const idx = handlers.indexOf(callback);
+    if (idx !== -1) handlers.splice(idx, 1);
+    return this;
+  }
+  /**
+   * Sugar over the keyboard channel: invoke `spec.handler` whenever a
+   * non-repeat `keydown` whose normalized chord matches `spec.chord`
+   * (via {@link normalizeChord}) passes the same gates as {@link Scene.on} —
+   * including the unconditional `ownsKeyboard(activeElement)` suppression.
+   *
+   * @param spec - `{ chord, handler }`; the chord is normalized once at
+   *   registration, so `'ctrl+n'`, `'Control+n'` and `'Ctrl+N'` are aliases.
+   * @returns `this` for method chaining.
+   */
+  registerShortcut(spec) {
+    this.shortcuts.push({ chord: normalizeChord(spec.chord), handler: spec.handler });
+    return this;
+  }
+  /**
+   * Remove a shortcut previously registered with {@link Scene.registerShortcut}.
+   * Matches on normalized chord + exact handler reference; silent no-op when
+   * nothing matches.
+   *
+   * @param spec - The same spec object (chord spelling may differ; it is
+   *   re-normalized before matching).
+   * @returns `this` for method chaining.
+   */
+  unregisterShortcut(spec) {
+    const chord = normalizeChord(spec.chord);
+    const idx = this.shortcuts.findIndex((s) => s.chord === chord && s.handler === spec.handler);
+    if (idx !== -1) this.shortcuts.splice(idx, 1);
+    return this;
+  }
+  /** Attach the window bubble-phase keyboard listeners exactly once. */
+  attachWindowKeyListeners() {
+    if (this.windowKeyDownHandler || typeof window === "undefined") return;
+    this.windowKeyDownHandler = (e) => this.dispatchKeyboard(e, "keydown");
+    this.windowKeyUpHandler = (e) => this.dispatchKeyboard(e, "keyup");
+    window.addEventListener("keydown", this.windowKeyDownHandler);
+    window.addEventListener("keyup", this.windowKeyUpHandler);
+  }
+  /**
+   * Gate a native keyboard event and fan it out to scene handlers +
+   * chord-matched shortcuts. See {@link Scene.on} for the gate contract.
+   */
+  dispatchKeyboard(e, type) {
+    if (e.defaultPrevented) return;
+    if (e.repeat) return;
+    const active = typeof document !== "undefined" ? document.activeElement : null;
+    if (ownsKeyboard(active)) return;
+    const event = {
+      type,
+      key: e.key,
+      code: e.code,
+      repeat: e.repeat,
+      ctrlKey: e.ctrlKey,
+      altKey: e.altKey,
+      shiftKey: e.shiftKey,
+      metaKey: e.metaKey,
+      target: e.target,
+      nativeEvent: e,
+      stopPropagation: () => e.stopPropagation(),
+      preventDefault: () => e.preventDefault()
+    };
+    const handlers = type === "keydown" ? this.keydownHandlers : this.keyupHandlers;
+    for (const handler of [...handlers]) handler(event);
+    if (type === "keydown") {
+      const chord = normalizeChord(e);
+      for (const shortcut of [...this.shortcuts]) {
+        if (shortcut.chord === chord) shortcut.handler(event);
+      }
+    }
+  }
   // --- domain: scene-facade — tree accessors ---
   /**
    * Manually advance the scene clock by `dt` milliseconds and render synchronously.
@@ -5772,7 +6048,9 @@ var Scene = class _Scene {
           }
         };
         el.addEventListener("pointerdown", (e) => {
-          if (typeof capEl.setPointerCapture === "function") capEl.setPointerCapture(e.pointerId);
+          if (e.target === capEl && typeof capEl.setPointerCapture === "function") {
+            capEl.setPointerCapture(e.pointerId);
+          }
           node.dispatchEvent(new VectoJSEvent("pointerdown", node, e));
         });
         el.addEventListener("pointerup", (e) => {
@@ -5880,14 +6158,6 @@ var Scene = class _Scene {
           }
           node.emit("blur", {});
         });
-        if (!isNativelyFocusable(el) && attrs.role && INTERACTIVE_A11Y_ROLES.has(attrs.role)) {
-          el.addEventListener("keydown", (e) => {
-            if (e.key === "Enter" || e.key === " ") {
-              e.preventDefault();
-              node.dispatchEvent(new VectoJSEvent("click", node, e));
-            }
-          });
-        }
         if (node.a11yFullViewport) {
           this.a11yRoot.insertBefore(el, this.a11yRoot.firstChild);
         } else {
@@ -5906,7 +6176,24 @@ var Scene = class _Scene {
       if (renderOrder !== void 0 && el.style.zIndex !== String(renderOrder)) {
         el.style.zIndex = String(renderOrder);
       }
-      const implicitTabIndex = !isNativelyFocusable(el) && attrs.role && INTERACTIVE_A11Y_ROLES.has(attrs.role) ? 0 : null;
+      const interactiveRole = !isNativelyFocusable(el) && !!attrs.role && INTERACTIVE_A11Y_ROLES.has(attrs.role);
+      if (interactiveRole && !this.keyboardActivatedA11y.has(el)) {
+        el.addEventListener("keydown", (e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            node.dispatchEvent(new VectoJSEvent("click", node, e));
+          } else if (e.key === " ") {
+            e.preventDefault();
+          }
+        });
+        el.addEventListener("keyup", (e) => {
+          if (e.key === " ") {
+            node.dispatchEvent(new VectoJSEvent("click", node, e));
+          }
+        });
+        this.keyboardActivatedA11y.add(el);
+      }
+      const implicitTabIndex = interactiveRole ? 0 : null;
       const desiredTabIndex = attrs.tabIndex ?? implicitTabIndex;
       if (desiredTabIndex === null) {
         if (el.hasAttribute("tabindex")) el.removeAttribute("tabindex");
@@ -6848,6 +7135,7 @@ var Scene = class _Scene {
       this.renderOrderCounter = 0;
       this.a11yRenderOrders.clear();
       this.activePortalsThisFrame.clear();
+      this._updateWalkDt = dt;
       this._tickBatchedDrivers(dt);
     }
     const computeEntities = this._computeEntitiesFor(this._structureVersion);
@@ -7018,6 +7306,7 @@ var Scene = class _Scene {
       };
       updateWalk(this.root);
       for (const overlay of this.overlayRoot.children) updateWalk(overlay);
+      this._updateWalkDt = null;
     }
     const transformTiming = this.phases.userTiming ? beginVectoUserTiming(VECTO_USER_TIMING.scene.transform) : null;
     const wasmT0 = this.phases.enabled ? performance.now() : 0;
@@ -7218,6 +7507,7 @@ var Scene = class _Scene {
     for (const overlay of this.overlayRoot.children) {
       renderNode(overlay, 1, 0, 0, 1, 0, 0, 1);
     }
+    if (isMainRenderer) this._updateWalkDt = null;
     if (this.phases.enabled) this.phases.record("drawWalk", performance.now() - drawT0);
     if (drawTiming) endVectoUserTiming(drawTiming);
     if (this.phases.userTiming) {
@@ -8363,6 +8653,7 @@ export {
   GlyphRasterAtlas,
   GridTextEntity,
   Group,
+  KEYBOARD_OWNING_ROLES,
   MSDFTextEntity,
   PARTICLE_OFFSET_LIFE,
   PARTICLE_OFFSET_ORIGIN_X,
@@ -8394,6 +8685,8 @@ export {
   isSafeUrl,
   loadSpline,
   measureVectoUserTiming,
+  normalizeChord,
+  ownsKeyboard,
   parseColorToRGBA,
   polySegmentToBezier,
   sanitizeUrl,