@combos-fun/plugin-development-tool 0.0.53 → 0.1.0

package/agent-skill.md

@@ -56,13 +56,13 @@ export default defineConfig({
 });
 ```
 
-Do not add `CombosDevelopmentToolTarget` from game code. Opt out of a construct with `// combos-no-target` or `{ editor: { pickable: false } }` on the `GameObject` params object (the extra key is ignored by `Transform`).
+Do not add `CombosDevelopmentToolTarget` from game code. Opt out of a construct with `// combos-no-target`.
 
 ## 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.
+2D bounds come from `Transform2D` size plus `GameObject` hierarchy (position, origin, anchor, scale, rotation). Set `Transform2D.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.
 
 The marker overlay is independent of pick mode and mute. It currently draws a 28×28 canvas badge only for `Sound`; the owner still needs a Target for selection and persistence (the Vite plugin attaches that Target).
 
@@ -90,8 +90,10 @@ Snapshots expose described schema-backed `fieldDescriptors`, not raw fields. For
 
 ## Common pitfalls
 
-- 2D picking needs a positive `transform.size` to get a usable hit rect.
+- 2D picking needs a positive `Transform2D.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() {
@@ -498,7 +501,7 @@ function leafDescriptorsFromValue(componentName, options, path, value) {
                 group: options.group ?? componentName,
                 editorKind: mapEditorKind(options, axisType),
                 numberMeta: buildNumberMeta(options),
-                persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+                persistTarget: 'component',
             });
         }
         return out;
@@ -521,7 +524,7 @@ function leafDescriptorsFromValue(componentName, options, path, value) {
             editorKind: mapEditorKind(options, valueType),
             enumOptions: options.enumOptions,
             numberMeta: buildNumberMeta(options),
-            persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+            persistTarget: 'component',
         },
     ];
 }
@@ -618,7 +621,10 @@ function syncPhysicsBodyFromTransform(go) {
     if (!physics?.body) {
         return;
     }
-    const { x, y } = go.transform.position;
+    const pose = go.getComponent('Transform2D');
+    if (!pose)
+        return;
+    const { x, y } = pose.position;
     if (physics.Body?.setPosition) {
         physics.Body.setPosition(physics.body, { x, y });
         return;
@@ -631,11 +637,16 @@ function syncMoverOriginFromTransform(go) {
     if (!mover) {
         return;
     }
-    mover.originX = go.transform.position.x;
-    mover.originY = go.transform.position.y;
+    const pose = go.getComponent('Transform2D');
+    if (!pose)
+        return;
+    mover.originX = pose.position.x;
+    mover.originY = pose.position.y;
 }
 function applyTransformProperty(go, _comp, path, value) {
-    const transform = go.transform;
+    const transform = go.getComponent('Transform2D');
+    if (!transform)
+        return false;
     const transformRecord = transform;
     if (path.length === 1 && path[0] === 'rotation') {
         const next = asNumber(value);
@@ -693,7 +704,7 @@ function applySoundProperty(_go, comp, path, value) {
     return false;
 }
 const APPLY_HOOKS = {
-    Transform: applyTransformProperty,
+    Transform2D: applyTransformProperty,
     Text: applyTextProperty,
     Sound: applySoundProperty,
 };
@@ -977,6 +988,32 @@ function projectTransform3D(transform, camera, css, object3D) {
     const scale = Math.max(Math.abs(transform.scaleX ?? 1), Math.abs(transform.scaleY ?? 1), Math.abs(transform.scaleZ ?? 1), 1);
     return padAround(projected, DEFAULT_POINT_EXTENT * scale);
 }
+function asTransform2DPose(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const t = value;
+    if (!t.position || !t.size)
+        return null;
+    return {
+        position: t.position,
+        size: t.size,
+        origin: t.origin ?? { x: 0, y: 0 },
+        anchor: t.anchor ?? { x: 0, y: 0 },
+        scale: t.scale ?? { x: 1, y: 1 },
+        skew: t.skew ?? { x: 0, y: 0 },
+        rotation: t.rotation ?? 0,
+    };
+}
+function pose2DFromGameObject(go) {
+    const pose = asTransform2DPose(go.getComponent('Transform2D'));
+    if (!pose)
+        return null;
+    const parentGo = go.parent && go.parent !== go.scene ? go.parent : null;
+    return {
+        ...pose,
+        parent: parentGo ? pose2DFromGameObject(parentGo) : null,
+    };
+}
 function projectGameObjectToScreen(go, opts) {
     if (opts.css.width <= 0 || opts.css.height <= 0) {
         return null;
@@ -985,21 +1022,108 @@ function projectGameObjectToScreen(go, opts) {
     if (t3d && opts.camera) {
         return projectTransform3D(t3d, opts.camera, opts.css, opts.object3D);
     }
-    return projectTransform2D(go.transform, opts.css, opts.design ?? null);
+    const t2d = pose2DFromGameObject(go);
+    if (!t2d)
+        return null;
+    return projectTransform2D(t2d, opts.css, opts.design ?? null);
 }
 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 +1135,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 +1166,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 +1232,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 +1249,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 +1268,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 +1283,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,20 +1401,52 @@ 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);
-        for (const tr of go.transform.children) {
-            this.collectGameObjects(tr.gameObject, out);
+        for (const child of go.children) {
+            this.collectGameObjects(child, out);
         }
     }
     listSceneObjects() {
         const list = [];
         const scene = this.game.scene;
-        if (!scene?.transform?.children)
+        if (!scene?.children)
             return list;
-        for (const tr of scene.transform.children) {
-            this.collectGameObjects(tr.gameObject, list);
+        for (const child of scene.children) {
+            this.collectGameObjects(child, list);
         }
         return list;
     }
@@ -1312,13 +1472,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 +1514,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 +1733,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.53",
+    packageVersion: "0.1.0",
 });
 
 function isInternalEditorGo(go) {