@vectojs/dom 0.2.0 → 0.2.1

package/dist/DOMProjection.d.ts

@@ -12,6 +12,8 @@ export interface DOMProjectionStats {
     opacityWrites: number;
     sizeWrites: number;
     contentWrites: number;
+    /** `clip-path` writes for the r5 `clipChildren` agreement (dirty-checked). */
+    clipWrites: number;
     poolHits: number;
     poolMisses: number;
 }
@@ -46,6 +48,24 @@ export interface DOMKindSpec {
  * field does not re-apply every frame.
  */
 export declare function writeField(cached: Map<string, string>, key: string, next: string | undefined, apply: (value: string | undefined) => void, onWrite?: () => void): boolean;
+/**
+ * CSS `clip-path` for `node`'s projected element so DOM rendering agrees with
+ * canvas / `HitTester.isHitEligible` clipping (r5): the intersection of every
+ * `clipChildren` ancestor's local box, expressed in the node's own local
+ * pixels (the element's `clip-path` reference box shares that origin, since
+ * the element itself is positioned purely by its world-matrix transform).
+ *
+ * Uses only public core surface (`parent`, `clipChildren`, `width`/`height`,
+ * `getWorldTransform`, `worldToLocal`) — no core internals, so no core change
+ * was needed. Zero-area clippers are skipped: they clip nothing on canvas and
+ * are skipped by `Scene.projectionBoxVisible` and the a11y region walk too.
+ *
+ * Returns `''` when nothing clips (the element stays unclipped), and a
+ * zero-area `polygon()` when the intersection is empty (fully clipped). A
+ * degenerate node transform also returns `''` — its singular matrix already
+ * paints nothing, so there is nothing to clip.
+ */
+export declare function clipPathForNode(node: Entity): string;
 /**
  * The `DOMProjection` (`'dom'`) backend (RFC §§4/5/6/7, P1 prototype).
  *
@@ -74,6 +94,12 @@ export declare class DOMProjection implements ProjectionBackend {
     /** Nodes owning a live press: `pointerId`s per node id (RFC4 §5 pin source). */
     private readonly activeGestures;
     private mountSeq;
+    /**
+     * First-mount z per node id (r6): an unmount/remount cycle restores the same
+     * z instead of taking a fresh `mountSeq` slot that would reorder the pooled
+     * element above later siblings. FIFO-capped at {@link MOUNT_ORDER_CAP}.
+     */
+    private readonly mountOrder;
     private readonly stats;
     /**
      * @param canvas - The scene's canvas. The root is appended to its

package/dist/eventBridge.d.ts

@@ -45,10 +45,21 @@ export interface DOMBridgeHandle {
     setInteractionMode(mode: DOMInteractionMode): void;
     /** Current policy. */
     getInteractionMode(): DOMInteractionMode;
+    /**
+     * Whether this bridge instance currently owns a live press for `pointerId`
+     * (r7: per-instance scope — the authoritative answer for one element, where
+     * the module-global {@link getGestureOwner} is the cross-scene election
+     * view RFC4's arbitration gate will consult).
+     */
+    hasGesture(pointerId: number): boolean;
     /** Remove every listener this bridge installed. Idempotent. */
     release(): void;
 }
-/** Test/contract introspection: who owns `pointerId`, if anyone. */
+/**
+ * Test/contract introspection: the node id owning `pointerId`, if anyone.
+ * Single-scene contract preserved (still answers "who owns this press");
+ * the value is now the owning node id rather than the constant `'dom'`.
+ */
 export declare function getGestureOwner(pointerId: number): string | undefined;
 /**
  * Bridge native DOM events on a projected element into the Vecto event system.

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * materialize as live `HTMLElement`s positioned by their world matrix. Depends
  * on `@vectojs/core`, never the reverse.
  */
-export { DOMProjection, writeField, DOM_VISUAL_Z_INDEX, DOM_ROOT_ATTR } from './DOMProjection';
+export { DOMProjection, writeField, clipPathForNode, DOM_VISUAL_Z_INDEX, DOM_ROOT_ATTR, } from './DOMProjection';
 export type { DOMProjectionStats, DOMKindSpec, DOMSyncFields } from './DOMProjection';
 export { attachDOMBridge, getGestureOwner } from './eventBridge';
 export type { DOMInteractionMode, DOMBridgeOptions, DOMBridgeHandle } from './eventBridge';

package/dist/index.js

@@ -30,6 +30,7 @@ __export(index_exports, {
   DOM_VISUAL_Z_INDEX: () => DOM_VISUAL_Z_INDEX,
   affineToMatrix3d: () => affineToMatrix3d,
   attachDOMBridge: () => attachDOMBridge,
+  clipPathForNode: () => clipPathForNode,
   getGestureOwner: () => getGestureOwner,
   writeField: () => writeField
 });
@@ -52,6 +53,7 @@ var PRESS_EVENTS = ["pointerdown", "mousedown", "touchstart"];
 function attachDOMBridge(el, node, options = {}) {
   const listeners = [];
   let mode = options.mode ?? "selection";
+  const owned = /* @__PURE__ */ new Set();
   const on = (type, handler, capture = false) => {
     el.addEventListener(type, handler, capture);
     listeners.push({ type, handler, capture });
@@ -59,7 +61,8 @@ function attachDOMBridge(el, node, options = {}) {
   const pressCapture = (e) => {
     if (e.type === "pointerdown") {
       const id = e.pointerId ?? 0;
-      if (!gestureOwner.has(id)) gestureOwner.set(id, "dom");
+      if (!gestureOwner.has(id)) gestureOwner.set(id, node.id);
+      owned.add(id);
       options.onGestureStart?.(node.id, id);
       node.dispatchEvent(new import_core.VectoJSEvent("pointerdown", node, e, true, void 0, "dom"));
     }
@@ -70,7 +73,8 @@ function attachDOMBridge(el, node, options = {}) {
     on(type, (e) => {
       if (type === "pointerup" || type === "pointercancel") {
         const id = e.pointerId ?? 0;
-        gestureOwner.delete(id);
+        owned.delete(id);
+        if (gestureOwner.get(id) === node.id) gestureOwner.delete(id);
         options.onGestureEnd?.(node.id, id);
       }
       node.dispatchEvent(new import_core.VectoJSEvent(type, node, e, true, void 0, "dom"));
@@ -114,6 +118,9 @@ function attachDOMBridge(el, node, options = {}) {
     getInteractionMode() {
       return mode;
     },
+    hasGesture(pointerId) {
+      return owned.has(pointerId);
+    },
     release() {
       if (released) return;
       released = true;
@@ -121,6 +128,10 @@ function attachDOMBridge(el, node, options = {}) {
         el.removeEventListener(type, handler, capture);
       }
       listeners.length = 0;
+      for (const id of owned) {
+        if (gestureOwner.get(id) === node.id) gestureOwner.delete(id);
+      }
+      owned.clear();
     }
   };
 }
@@ -134,6 +145,7 @@ function affineToMatrix3d(m) {
 var DOM_VISUAL_Z_INDEX = "9";
 var DOM_ROOT_ATTR = "data-vecto-dom-root";
 var POOL_CAP_PER_TAG = 8;
+var MOUNT_ORDER_CAP = 2048;
 function strProp(node, key) {
   const value = node[key];
   return typeof value === "string" ? value : void 0;
@@ -198,6 +210,90 @@ var passthroughSpec = (tag) => ({
   }
 });
 var fallbackSpec = passthroughSpec("div");
+function roundClip(v) {
+  if (!Number.isFinite(v)) return 0;
+  const r = Math.round(v * 1e3) / 1e3;
+  return r === 0 ? 0 : r;
+}
+function signedArea(poly) {
+  let area = 0;
+  for (let i = 0; i < poly.length; i++) {
+    const p = poly[i];
+    const q = poly[(i + 1) % poly.length];
+    area += p.x * q.y - q.x * p.y;
+  }
+  return area / 2;
+}
+function intersectConvexPolygons(subject, clip) {
+  const ccw = signedArea(clip) >= 0;
+  let output = subject;
+  for (let i = 0; i < clip.length; i++) {
+    const a = clip[i];
+    const b = clip[(i + 1) % clip.length];
+    const inside = (p) => {
+      const cross = (b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x);
+      return ccw ? cross >= -1e-9 : cross <= 1e-9;
+    };
+    const crossing = (p, q) => {
+      const dx = q.x - p.x;
+      const dy = q.y - p.y;
+      const ex = b.x - a.x;
+      const ey = b.y - a.y;
+      const denom = dx * ey - dy * ex;
+      if (Math.abs(denom) < 1e-12) return { x: p.x, y: p.y };
+      const t = ((a.x - p.x) * ey - (a.y - p.y) * ex) / denom;
+      return { x: p.x + t * dx, y: p.y + t * dy };
+    };
+    const input = output;
+    output = [];
+    if (input.length === 0) break;
+    for (let j = 0; j < input.length; j++) {
+      const current = input[j];
+      const previous = input[(j + input.length - 1) % input.length];
+      const currentIn = inside(current);
+      const previousIn = inside(previous);
+      if (currentIn) {
+        if (!previousIn) output.push(crossing(previous, current));
+        output.push(current);
+      } else if (previousIn) {
+        output.push(crossing(previous, current));
+      }
+    }
+  }
+  return output;
+}
+function clipPathForNode(node) {
+  let poly = null;
+  for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+    if (!ancestor.clipChildren || ancestor.width <= 0 || ancestor.height <= 0) continue;
+    const t = ancestor.getWorldTransform();
+    const corners = [
+      { x: t.e, y: t.f },
+      { x: t.a * ancestor.width + t.e, y: t.b * ancestor.width + t.f },
+      {
+        x: t.a * ancestor.width + t.c * ancestor.height + t.e,
+        y: t.b * ancestor.width + t.d * ancestor.height + t.f
+      },
+      { x: t.c * ancestor.height + t.e, y: t.d * ancestor.height + t.f }
+    ];
+    const quad = [];
+    let degenerate = false;
+    for (const corner of corners) {
+      const local = node.worldToLocal(corner.x, corner.y);
+      if (!local) {
+        degenerate = true;
+        break;
+      }
+      quad.push({ x: local.x, y: local.y });
+    }
+    if (degenerate) return "";
+    poly = poly ? intersectConvexPolygons(poly, quad) : quad;
+    if (poly.length === 0) break;
+  }
+  if (!poly) return "";
+  if (poly.length === 0) return "polygon(0px 0px, 0px 0px, 0px 0px)";
+  return `polygon(${poly.map((p) => `${roundClip(p.x)}px ${roundClip(p.y)}px`).join(", ")})`;
+}
 var DOMProjection = class {
   kind = "dom";
   root = null;
@@ -209,6 +305,12 @@ var DOMProjection = class {
   /** Nodes owning a live press: `pointerId`s per node id (RFC4 §5 pin source). */
   activeGestures = /* @__PURE__ */ new Map();
   mountSeq = 0;
+  /**
+   * First-mount z per node id (r6): an unmount/remount cycle restores the same
+   * z instead of taking a fresh `mountSeq` slot that would reorder the pooled
+   * element above later siblings. FIFO-capped at {@link MOUNT_ORDER_CAP}.
+   */
+  mountOrder = /* @__PURE__ */ new Map();
   stats = {
     mounts: 0,
     unmounts: 0,
@@ -216,6 +318,7 @@ var DOMProjection = class {
     opacityWrites: 0,
     sizeWrites: 0,
     contentWrites: 0,
+    clipWrites: 0,
     poolHits: 0,
     poolMisses: 0
   };
@@ -302,6 +405,7 @@ var DOMProjection = class {
       this.stats.poolHits += 1;
       if (node.domKind === "text") el.style.userSelect = "text";
       el.style.display = "";
+      el.style.clipPath = "";
     } else {
       this.stats.poolMisses += 1;
       el = spec.create(node);
@@ -347,6 +451,7 @@ var DOMProjection = class {
       lastOpacity: "",
       lastWidth: "",
       lastHeight: "",
+      lastClip: "",
       intrinsicWidth: 0,
       intrinsicHeight: 0
     };
@@ -363,7 +468,16 @@ var DOMProjection = class {
       state.observer = observer;
     }
     this.states.set(node.id, state);
-    el.style.zIndex = String(1 + this.mountSeq++);
+    let z = this.mountOrder.get(node.id);
+    if (z === void 0) {
+      z = 1 + this.mountSeq++;
+      if (this.mountOrder.size >= MOUNT_ORDER_CAP) {
+        const oldest = this.mountOrder.keys().next();
+        if (!oldest.done) this.mountOrder.delete(oldest.value);
+      }
+      this.mountOrder.set(node.id, z);
+    }
+    el.style.zIndex = String(z);
     node.domResident = true;
     this.stats.mounts += 1;
   }
@@ -405,6 +519,12 @@ var DOMProjection = class {
         this.stats.sizeWrites += 1;
       }
     }
+    const clip = clipPathForNode(node);
+    if (state.lastClip !== clip) {
+      state.el.style.clipPath = clip;
+      state.lastClip = clip;
+      this.stats.clipWrites += 1;
+    }
     const spec = this.specFor(node);
     const cached = state.cached;
     const fields = {
@@ -448,6 +568,7 @@ var DOMProjection = class {
     this.states.clear();
     this.pools.clear();
     this.activeGestures.clear();
+    this.mountOrder.clear();
     this.root?.remove();
     this.root = null;
     this.sentinel = null;
@@ -584,6 +705,7 @@ var DOMTransform = class extends import_core2.Entity {
   DOM_VISUAL_Z_INDEX,
   affineToMatrix3d,
   attachDOMBridge,
+  clipPathForNode,
   getGestureOwner,
   writeField
 });

package/dist/index.mjs

@@ -15,6 +15,7 @@ var PRESS_EVENTS = ["pointerdown", "mousedown", "touchstart"];
 function attachDOMBridge(el, node, options = {}) {
   const listeners = [];
   let mode = options.mode ?? "selection";
+  const owned = /* @__PURE__ */ new Set();
   const on = (type, handler, capture = false) => {
     el.addEventListener(type, handler, capture);
     listeners.push({ type, handler, capture });
@@ -22,7 +23,8 @@ function attachDOMBridge(el, node, options = {}) {
   const pressCapture = (e) => {
     if (e.type === "pointerdown") {
       const id = e.pointerId ?? 0;
-      if (!gestureOwner.has(id)) gestureOwner.set(id, "dom");
+      if (!gestureOwner.has(id)) gestureOwner.set(id, node.id);
+      owned.add(id);
       options.onGestureStart?.(node.id, id);
       node.dispatchEvent(new VectoJSEvent("pointerdown", node, e, true, void 0, "dom"));
     }
@@ -33,7 +35,8 @@ function attachDOMBridge(el, node, options = {}) {
     on(type, (e) => {
       if (type === "pointerup" || type === "pointercancel") {
         const id = e.pointerId ?? 0;
-        gestureOwner.delete(id);
+        owned.delete(id);
+        if (gestureOwner.get(id) === node.id) gestureOwner.delete(id);
         options.onGestureEnd?.(node.id, id);
       }
       node.dispatchEvent(new VectoJSEvent(type, node, e, true, void 0, "dom"));
@@ -77,6 +80,9 @@ function attachDOMBridge(el, node, options = {}) {
     getInteractionMode() {
       return mode;
     },
+    hasGesture(pointerId) {
+      return owned.has(pointerId);
+    },
     release() {
       if (released) return;
       released = true;
@@ -84,6 +90,10 @@ function attachDOMBridge(el, node, options = {}) {
         el.removeEventListener(type, handler, capture);
       }
       listeners.length = 0;
+      for (const id of owned) {
+        if (gestureOwner.get(id) === node.id) gestureOwner.delete(id);
+      }
+      owned.clear();
     }
   };
 }
@@ -97,6 +107,7 @@ function affineToMatrix3d(m) {
 var DOM_VISUAL_Z_INDEX = "9";
 var DOM_ROOT_ATTR = "data-vecto-dom-root";
 var POOL_CAP_PER_TAG = 8;
+var MOUNT_ORDER_CAP = 2048;
 function strProp(node, key) {
   const value = node[key];
   return typeof value === "string" ? value : void 0;
@@ -161,6 +172,90 @@ var passthroughSpec = (tag) => ({
   }
 });
 var fallbackSpec = passthroughSpec("div");
+function roundClip(v) {
+  if (!Number.isFinite(v)) return 0;
+  const r = Math.round(v * 1e3) / 1e3;
+  return r === 0 ? 0 : r;
+}
+function signedArea(poly) {
+  let area = 0;
+  for (let i = 0; i < poly.length; i++) {
+    const p = poly[i];
+    const q = poly[(i + 1) % poly.length];
+    area += p.x * q.y - q.x * p.y;
+  }
+  return area / 2;
+}
+function intersectConvexPolygons(subject, clip) {
+  const ccw = signedArea(clip) >= 0;
+  let output = subject;
+  for (let i = 0; i < clip.length; i++) {
+    const a = clip[i];
+    const b = clip[(i + 1) % clip.length];
+    const inside = (p) => {
+      const cross = (b.x - a.x) * (p.y - a.y) - (b.y - a.y) * (p.x - a.x);
+      return ccw ? cross >= -1e-9 : cross <= 1e-9;
+    };
+    const crossing = (p, q) => {
+      const dx = q.x - p.x;
+      const dy = q.y - p.y;
+      const ex = b.x - a.x;
+      const ey = b.y - a.y;
+      const denom = dx * ey - dy * ex;
+      if (Math.abs(denom) < 1e-12) return { x: p.x, y: p.y };
+      const t = ((a.x - p.x) * ey - (a.y - p.y) * ex) / denom;
+      return { x: p.x + t * dx, y: p.y + t * dy };
+    };
+    const input = output;
+    output = [];
+    if (input.length === 0) break;
+    for (let j = 0; j < input.length; j++) {
+      const current = input[j];
+      const previous = input[(j + input.length - 1) % input.length];
+      const currentIn = inside(current);
+      const previousIn = inside(previous);
+      if (currentIn) {
+        if (!previousIn) output.push(crossing(previous, current));
+        output.push(current);
+      } else if (previousIn) {
+        output.push(crossing(previous, current));
+      }
+    }
+  }
+  return output;
+}
+function clipPathForNode(node) {
+  let poly = null;
+  for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
+    if (!ancestor.clipChildren || ancestor.width <= 0 || ancestor.height <= 0) continue;
+    const t = ancestor.getWorldTransform();
+    const corners = [
+      { x: t.e, y: t.f },
+      { x: t.a * ancestor.width + t.e, y: t.b * ancestor.width + t.f },
+      {
+        x: t.a * ancestor.width + t.c * ancestor.height + t.e,
+        y: t.b * ancestor.width + t.d * ancestor.height + t.f
+      },
+      { x: t.c * ancestor.height + t.e, y: t.d * ancestor.height + t.f }
+    ];
+    const quad = [];
+    let degenerate = false;
+    for (const corner of corners) {
+      const local = node.worldToLocal(corner.x, corner.y);
+      if (!local) {
+        degenerate = true;
+        break;
+      }
+      quad.push({ x: local.x, y: local.y });
+    }
+    if (degenerate) return "";
+    poly = poly ? intersectConvexPolygons(poly, quad) : quad;
+    if (poly.length === 0) break;
+  }
+  if (!poly) return "";
+  if (poly.length === 0) return "polygon(0px 0px, 0px 0px, 0px 0px)";
+  return `polygon(${poly.map((p) => `${roundClip(p.x)}px ${roundClip(p.y)}px`).join(", ")})`;
+}
 var DOMProjection = class {
   kind = "dom";
   root = null;
@@ -172,6 +267,12 @@ var DOMProjection = class {
   /** Nodes owning a live press: `pointerId`s per node id (RFC4 §5 pin source). */
   activeGestures = /* @__PURE__ */ new Map();
   mountSeq = 0;
+  /**
+   * First-mount z per node id (r6): an unmount/remount cycle restores the same
+   * z instead of taking a fresh `mountSeq` slot that would reorder the pooled
+   * element above later siblings. FIFO-capped at {@link MOUNT_ORDER_CAP}.
+   */
+  mountOrder = /* @__PURE__ */ new Map();
   stats = {
     mounts: 0,
     unmounts: 0,
@@ -179,6 +280,7 @@ var DOMProjection = class {
     opacityWrites: 0,
     sizeWrites: 0,
     contentWrites: 0,
+    clipWrites: 0,
     poolHits: 0,
     poolMisses: 0
   };
@@ -265,6 +367,7 @@ var DOMProjection = class {
       this.stats.poolHits += 1;
       if (node.domKind === "text") el.style.userSelect = "text";
       el.style.display = "";
+      el.style.clipPath = "";
     } else {
       this.stats.poolMisses += 1;
       el = spec.create(node);
@@ -310,6 +413,7 @@ var DOMProjection = class {
       lastOpacity: "",
       lastWidth: "",
       lastHeight: "",
+      lastClip: "",
       intrinsicWidth: 0,
       intrinsicHeight: 0
     };
@@ -326,7 +430,16 @@ var DOMProjection = class {
       state.observer = observer;
     }
     this.states.set(node.id, state);
-    el.style.zIndex = String(1 + this.mountSeq++);
+    let z = this.mountOrder.get(node.id);
+    if (z === void 0) {
+      z = 1 + this.mountSeq++;
+      if (this.mountOrder.size >= MOUNT_ORDER_CAP) {
+        const oldest = this.mountOrder.keys().next();
+        if (!oldest.done) this.mountOrder.delete(oldest.value);
+      }
+      this.mountOrder.set(node.id, z);
+    }
+    el.style.zIndex = String(z);
     node.domResident = true;
     this.stats.mounts += 1;
   }
@@ -368,6 +481,12 @@ var DOMProjection = class {
         this.stats.sizeWrites += 1;
       }
     }
+    const clip = clipPathForNode(node);
+    if (state.lastClip !== clip) {
+      state.el.style.clipPath = clip;
+      state.lastClip = clip;
+      this.stats.clipWrites += 1;
+    }
     const spec = this.specFor(node);
     const cached = state.cached;
     const fields = {
@@ -411,6 +530,7 @@ var DOMProjection = class {
     this.states.clear();
     this.pools.clear();
     this.activeGestures.clear();
+    this.mountOrder.clear();
     this.root?.remove();
     this.root = null;
     this.sentinel = null;
@@ -546,6 +666,7 @@ export {
   DOM_VISUAL_Z_INDEX,
   affineToMatrix3d,
   attachDOMBridge,
+  clipPathForNode,
   getGestureOwner,
   writeField
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/dom",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -41,7 +41,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vectojs/core": "^1.40.0"
+    "@vectojs/core": "^1.40.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",