@combos-fun/plugin-development-tool 0.0.52 → 0.0.54

package/agent-skill.md

@@ -60,7 +60,7 @@ Do not add `CombosDevelopmentToolTarget` from game code. Opt out of a construct
 
 ## Runtime behaviour
 
-The System starts disabled. In pick mode it shows a full-canvas overlay (`pointer-events: auto`) so game `Event` / `Event3D` do not receive the tap. Targets are hit-tested from engine transforms projected to overlay CSS pixels. Target additions/removals are observed automatically; `requestSceneRescan()` is for parent-driven structural refreshes.
+The System starts disabled. In pick mode it shows a full-canvas overlay (`pointer-events: auto`) so game `Event` / `Event3D` do not receive the tap, and it also listens on `window` capture so a DOM HUD above the canvas cannot swallow the tap. Targets are hit-tested from engine transforms projected to overlay CSS pixels. Overlapping hits prefer content: hollow / invisible / low-alpha nodes and rects covering ≥75% of the overlay lose to a smaller target underneath; two covering layers pick the earlier scene-walk item. Target additions/removals are observed automatically; `requestSceneRescan()` is for parent-driven structural refreshes.
 
 2D bounds come from `Transform` size / hierarchy (position, origin, anchor, scale, rotation). Set `transform.size` when the visual does not match a zero size. 3D bounds project `Transform3D` world position through the active `Renderer3DSystem` camera; a mesh bounding box is used when the Three object is available, otherwise a screen-space pad around the projected point.
 
@@ -92,6 +92,8 @@ Snapshots expose described schema-backed `fieldDescriptors`, not raw fields. For
 
 - 2D picking needs a positive `transform.size` to get a usable hit rect.
 - 3D picking needs `Renderer3DSystem` (for the camera) at runtime; there is no package dependency.
+- Pick ranking is not pixel-perfect: a fullscreen `Img` with `alpha: 1` still counts as drawable even if the PNG is mostly transparent.
+- A covering overlay is still selected when it is the only hit under the pointer.
 - Parent messages require an iframe (`window.parent !== window`) and an allowed origin.
 - Structural replacement needs `refresh`; ordinary Target add/remove does not.
 - Persistence fails if the game build did not run `combosDevelopmentTargetPlugin`.

package/dist/plugin-development-tool.cjs.js

@@ -255,14 +255,17 @@ function mergeAllowedMessageOrigins(extra) {
 
 const OVERLAY_Z_INDEX = '2147483000';
 const OVERLAY_ATTR = 'data-combos-development-tool-overlay';
-function ensureParent(gameCanvas, overlay) {
-    const parent = gameCanvas.parentElement ?? document.body;
+function ensureParent(_gameCanvas, overlay) {
+    const parent = document.body;
+    if (!parent)
+        return;
     if (overlay.parentElement !== parent) {
         parent.appendChild(overlay);
     }
 }
 /**
- * Transparent HTML canvas stacked on the game canvas.
+ * Transparent HTML canvas stacked on the game canvas and mounted on `document.body`
+ * so a transformed canvas parent cannot trap `position: fixed` under a DOM HUD.
  * Pick mode sets `pointer-events: auto` so game Event / Event3D do not receive the tap.
  */
 function createOverlayCanvas() {
@@ -990,16 +993,100 @@ function projectGameObjectToScreen(go, opts) {
 function rectContains(rect, x, y) {
     return x >= rect.x && y >= rect.y && x <= rect.x + rect.width && y <= rect.y + rect.height;
 }
-/** Smallest containing rect wins; later items win ties (front-most in walk order). */
-function hitTestRects(x, y, items) {
+/** Fraction of the overlay a rect must cover to count as a fullscreen pass-through layer. */
+const COVERING_OVERLAY_RATIO = 0.75;
+/** `Render.alpha` / `Render3D.opacity` at or below this is treated as see-through. */
+const LOW_ALPHA_PASSTHROUGH = 0.35;
+/**
+ * Known drawable component names. Duck-typed so this package does not import
+ * renderer plugins. Unknown custom visuals are treated as non-drawable only for
+ * pass-through ranking; they remain pickable when they are the only hit.
+ */
+const KNOWN_VISUAL_COMPONENT_NAMES = [
+    'Img',
+    'Sprite',
+    'TilingSprite',
+    'NinePatch',
+    'Text',
+    'Graphics',
+    'SpriteAnimation',
+    'Img3D',
+    'Sprite3D',
+    'TilingSprite3D',
+    'Text3D',
+    'Graphics3D',
+    'Model3D',
+    'SpriteAnimation3D',
+];
+function rectOverlapArea(a, b) {
+    const width = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+    const height = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+    if (width <= 0 || height <= 0)
+        return 0;
+    return width * height;
+}
+function isCoveringOverlay(rect, viewport, ratio = COVERING_OVERLAY_RATIO) {
+    if (!viewport || viewport.width <= 0 || viewport.height <= 0) {
+        return false;
+    }
+    const viewportArea = viewport.width * viewport.height;
+    if (viewportArea <= 0)
+        return false;
+    return rectOverlapArea(rect, { x: 0, y: 0, width: viewport.width, height: viewport.height }) / viewportArea >= ratio;
+}
+function hasKnownVisual(go) {
+    return KNOWN_VISUAL_COMPONENT_NAMES.some(name => Boolean(go.getComponent(name)));
+}
+/**
+ * Higher = more likely to click through to a target underneath.
+ * Invisible / zero-alpha layers rank above hollow containers and low-alpha dimmers.
+ */
+function pickPassThrough(go) {
+    const render = go.getComponent('Render');
+    const render3d = go.getComponent('Render3D');
+    const visible = render?.visible !== false && render3d?.visible !== false;
+    const alpha = Math.min(typeof render?.alpha === 'number' && Number.isFinite(render.alpha) ? render.alpha : 1, typeof render3d?.opacity === 'number' && Number.isFinite(render3d.opacity) ? render3d.opacity : 1);
+    let score = 0;
+    if (!visible || alpha <= 0)
+        score += 2;
+    else if (alpha <= LOW_ALPHA_PASSTHROUGH)
+        score += 1;
+    if (!hasKnownVisual(go))
+        score += 1;
+    return score;
+}
+function isBetterHit(next, best) {
+    if (next.score !== best.score)
+        return next.score < best.score;
+    if (next.covering !== best.covering)
+        return !next.covering;
+    if (next.covering) {
+        return next.index < best.index;
+    }
+    if (next.area !== best.area)
+        return next.area < best.area;
+    return next.index > best.index;
+}
+/**
+ * Pick among overlapping targets:
+ * - lower pass-through score wins (content over invisible / hollow / low-alpha);
+ * - a covering fullscreen layer loses to any non-covering hit;
+ * - among covering-only hits, the earlier scene-walk item wins (what's behind);
+ * - among content hits, smallest rect wins, later items win ties (front-most).
+ */
+function hitTestRects(x, y, items, opts) {
     let best = null;
+    const coveringRatio = opts?.coveringRatio ?? COVERING_OVERLAY_RATIO;
     for (let i = 0; i < items.length; i++) {
         const item = items[i];
         if (!rectContains(item.rect, x, y))
             continue;
         const area = Math.max(item.rect.width, 0) * Math.max(item.rect.height, 0);
-        if (!best || area < best.area || (area === best.area && i > best.index)) {
-            best = { id: item.id, area, index: i };
+        const covering = isCoveringOverlay(item.rect, opts?.viewport, coveringRatio);
+        const score = (item.passThrough ?? 0) + (covering ? 1 : 0);
+        const next = { id: item.id, score, covering, area, index: i };
+        if (!best || isBetterHit(next, best)) {
+            best = next;
         }
     }
     return best ? best.id : null;
@@ -1011,8 +1098,10 @@ const OUTLINE_COLOR = '#55ffaa';
 /**
  * **Off** at start. While enabled:
  * - a transparent HTML canvas overlay captures pointer events (game Event / Event3D
- *   do not receive the tap);
+ *   do not receive the tap); pick also listens on `window` capture so a mostly
+ *   transparent DOM HUD above the canvas cannot swallow the tap;
  * - only nodes with {@link CombosDevelopmentToolTarget} are pickable;
+ * - fullscreen / hollow / low-alpha layers lose to content underneath;
  * - selection outline and markers are drawn with the Canvas 2D API (no renderer plugin).
  *
  * Turn on/off via:
@@ -1040,6 +1129,7 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.overlay = null;
         this.overlayCss = { width: 0, height: 0 };
         this.pointerDownGoId = null;
+        this.pickListening = false;
         this.needsRescan = false;
         /** Remembered mute when `SoundSystem` is not registered yet. */
         this.mutedWithoutSoundSystem = false;
@@ -1105,10 +1195,11 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             this.requestSceneRescan();
         };
         this.onPointerDown = (e) => {
-            if (!this.enabled)
+            if (!this.enabled || !this.isPickPointInGame(e))
                 return;
             e.preventDefault();
             e.stopPropagation();
+            e.stopImmediatePropagation();
             try {
                 this.overlay?.canvas.setPointerCapture(e.pointerId);
             }
@@ -1121,8 +1212,13 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.onPointerUp = (e) => {
             if (!this.enabled)
                 return;
+            if (!this.isPickPointInGame(e)) {
+                this.pointerDownGoId = null;
+                return;
+            }
             e.preventDefault();
             e.stopPropagation();
+            e.stopImmediatePropagation();
             const hit = this.hitTestPointer(e);
             if (hit && hit.id === this.pointerDownGoId) {
                 this.onSelect(hit, e);
@@ -1135,10 +1231,6 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.postMessageOrigin = params?.postMessageOrigin ?? '*';
         this.allowedMessageOrigins = mergeAllowedMessageOrigins(params?.allowedMessageOrigins);
         this.overlay = createOverlayCanvas();
-        if (this.overlay) {
-            this.overlay.canvas.addEventListener('pointerdown', this.onPointerDown);
-            this.overlay.canvas.addEventListener('pointerup', this.onPointerUp);
-        }
         if (typeof window !== 'undefined') {
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, this.onWindowSetPickMode);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onWindowSetMarkerOverlay);
@@ -1154,9 +1246,8 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         }
     }
     onDestroy() {
+        this.unbindPickListeners();
         if (this.overlay) {
-            this.overlay.canvas.removeEventListener('pointerdown', this.onPointerDown);
-            this.overlay.canvas.removeEventListener('pointerup', this.onPointerUp);
             this.overlay.destroy();
             this.overlay = null;
         }
@@ -1273,6 +1364,38 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         const active = this.enabled || this.markerOverlayEnabled;
         this.overlay?.setVisible(active);
         this.overlay?.setPickEnabled(this.enabled);
+        if (this.enabled) {
+            this.bindPickListeners();
+        }
+        else {
+            this.unbindPickListeners();
+        }
+    }
+    bindPickListeners() {
+        if (this.pickListening || typeof window === 'undefined')
+            return;
+        window.addEventListener('pointerdown', this.onPointerDown, true);
+        window.addEventListener('pointerup', this.onPointerUp, true);
+        this.pickListening = true;
+    }
+    unbindPickListeners() {
+        if (!this.pickListening || typeof window === 'undefined')
+            return;
+        window.removeEventListener('pointerdown', this.onPointerDown, true);
+        window.removeEventListener('pointerup', this.onPointerUp, true);
+        this.pickListening = false;
+    }
+    isPickPointInGame(e) {
+        const canvas = this.game.canvas ?? this.game.scene?.canvas ?? this.overlay?.canvas;
+        if (!canvas)
+            return false;
+        const rect = canvas.getBoundingClientRect();
+        return (rect.width > 0 &&
+            rect.height > 0 &&
+            e.clientX >= rect.left &&
+            e.clientX <= rect.right &&
+            e.clientY >= rect.top &&
+            e.clientY <= rect.bottom);
     }
     collectGameObjects(go, out) {
         out.push(go);
@@ -1312,13 +1435,14 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             if (!go.getComponent(CombosDevelopmentToolTarget))
                 continue;
             const rect = this.projectGo(go);
+            const passThrough = pickPassThrough(go);
             if (rect) {
-                hits.push({ go, rect });
+                hits.push({ go, rect, passThrough });
             }
             if (this.markerOverlayEnabled && resolveMarkerDef(go)) {
                 const markerRect = this.markerRectFor(go, rect);
                 if (markerRect) {
-                    hits.push({ go, rect: markerRect });
+                    hits.push({ go, rect: markerRect, passThrough });
                 }
             }
         }
@@ -1353,7 +1477,7 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
     hitTestPointer(e) {
         const pt = this.overlayPoint(e);
         const hits = this.collectOverlayHits();
-        return hitTestRects(pt.x, pt.y, hits.map(h => ({ id: h.go, rect: h.rect })));
+        return hitTestRects(pt.x, pt.y, hits.map(h => ({ id: h.go, rect: h.rect, passThrough: h.passThrough })), { viewport: this.overlayCss });
     }
     redrawOverlay() {
         const overlay = this.overlay;
@@ -1572,7 +1696,7 @@ var CombosDevelopmentToolSystem = CombosDevelopmentToolSystem$1;
 /** Auto-generated by scripts/build-package.mjs — do not edit. */
 Object.assign(CombosDevelopmentToolSystem, {
     packageName: "@combos-fun/plugin-development-tool",
-    packageVersion: "0.0.52",
+    packageVersion: "0.0.54",
 });
 
 function isInternalEditorGo(go) {