@combos-fun/plugin-development-tool 0.0.37 → 0.0.39

package/agent-skill.md

@@ -16,7 +16,7 @@ import {
   COMBOS_DEVELOPMENT_TOOL_CLEAR_SELECTION,
   COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED,
   COMBOS_DEVELOPMENT_TOOL_REFRESH,
-  COMBOS_DEVELOPMENT_TOOL_SET,
+  COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE,
   type CombosDevelopmentToolTargetParams,
   type CombosDevelopmentToolSystemParams,
   type CombosDevelopmentToolSelectScope,
@@ -33,22 +33,7 @@ import {
 
 | Field | Type | Notes |
 |---|---|---|
-| `payload` | `Record<string, unknown>?` | Extra JSON-serializable data included in the selected-object snapshot. |
-
-Creator source persistence uses the optional `payload.source` convention:
-
-```ts
-go.addComponent(new CombosDevelopmentToolTarget({
-  payload: {
-    source: {
-      file: 'src/scenes/main-scene.ts', // project-relative
-      anchor: 'hero',                   // stable source key; defaults to go.name in snapshots
-    },
-  },
-}));
-```
-
-Use a stable `file` + `anchor` pair when property edits must resolve the same GameObject after reload. The Target accepts arbitrary JSON-safe payload fields, but only `payload.source.file` and `payload.source.anchor` participate in source lookup.
+| `payload` | `Record<string, unknown>?` | Snapshot extras. Creator persist needs `payload.source.file` + `payload.source.anchor`. Who to tag and how to pick the pair: `$combos-engine-development` → `references/development-tool-target-policy.md`. |
 
 ## Required setup
 
@@ -93,6 +78,7 @@ Set `transform.size` for `Img`, `Text`, `Sprite`, and `SpriteAnimation` GameObje
 | Parent frame never receives messages | The page must be in an iframe / embedded context; `window.parent !== window` |
 | Parent postMessage ignored | Check `allowedMessageOrigins` — defaults allow `knoffice.tech` and `converge.ai` (+ subdomains). Pass `['localhost']` to merge local dev hosts |
 | Selection stuck after a parent-driven structural replacement | Have the parent/tooling send `COMBOS_DEVELOPMENT_TOOL_REFRESH`; ordinary Target add/remove is automatic |
+| Scene Edit cannot persist / object not found after reload | Target is missing `payload.source.file` + `payload.source.anchor` |
 
 ## Inbound postMessage security
 
@@ -116,7 +102,8 @@ Outbound `postMessageOrigin` is separate — it limits which parent origin recei
 
 | Direction | type | Payload | Behavior |
 |-----------|------|---------|----------|
-| parent → iframe | `combos-development-tool:set` | `{ enabled: boolean }` | Enable/disable pick mode |
+| parent → iframe | `combos-development-tool:set-pick-mode` | `{ enabled: boolean }` | Enable/disable pick mode |
+| iframe → parent | `combos-development-tool:pick-mode-success` | `{ enabled: boolean }` | Pick mode finished attaching or restoring |
 | parent → iframe | `combos-development-tool:clear-selection` | `{}` | Clear in-canvas outline |
 | parent → iframe | `combos-development-tool:apply-property` | component field mutation | Live preview |
 | parent → iframe | `combos-development-tool:set-marker-overlay` | `{ enabled: boolean }` | Toggle the marker overlay (independent of pick mode) |
@@ -140,11 +127,8 @@ triggers / spawn points later) but nothing else is registered yet.
   `CombosDevelopmentToolTarget` pick gets a clickable hit area, so selecting and
   editing (e.g. `Sound.volume`) go through the normal
   selection → snapshot (`fieldDescriptors`) → `apply-property` flow and **persist to source** like any
-  other scene edit. **The marked object must therefore carry a
-  `CombosDevelopmentToolTarget`** added by game code. Objects with a `Sound`
-  component must be given a Target when they should be editable even when they
-  render nothing. Space independently editable Sound GameObjects apart so their
-  marker badges do not overlap.
+  other scene edit. Sound objects that should be editable need a Target (source
+  pair and spacing: Target policy).
 - On (re)build it posts `combos-development-tool:marker-overlay-success` with per-component counts.
 
 ## Scene Edit fieldDescriptors

package/combos-plugin.json

@@ -16,7 +16,7 @@
     "CombosDevelopmentToolTarget",
     "COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED",
     "COMBOS_DEVELOPMENT_TOOL_REFRESH",
-    "COMBOS_DEVELOPMENT_TOOL_SET",
-    "COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS"
+    "COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE",
+    "COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS"
   ]
 }

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

@@ -7,10 +7,10 @@ var pluginRendererGraphics = require('@combos-fun/plugin-renderer-graphics');
 var pluginRendererEvent = require('@combos-fun/plugin-renderer-event');
 var inspectorDecorator = require('@combos-fun/inspector-decorator');
 
-/** Toggle development-tool selection / parent postMessage. Payload: `{ enabled: boolean }`. */
-const COMBOS_DEVELOPMENT_TOOL_SET = 'combos-development-tool:set';
-/** iframe → parent: `setEnabled` finished (pick attach after enable, or restore after disable). Payload: `{ enabled: boolean }`. */
-const COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS = 'combos-development-tool:set-success';
+/** Parent → iframe (also `window` CustomEvent / `game.emit`): toggle pick mode. Payload: `{ enabled: boolean }`. */
+const COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE = 'combos-development-tool:set-pick-mode';
+/** iframe → parent (and `game.emit`): pick mode finished attaching (enable) or restoring (disable). Payload: `{ enabled: boolean }`. */
+const COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS = 'combos-development-tool:pick-mode-success';
 /** Re-scan the scene tree while the development tool is enabled. */
 const COMBOS_DEVELOPMENT_TOOL_REFRESH = 'combos-development-tool:refresh';
 /** Emitted to `window.parent` when an object is selected while the tool is on. */
@@ -597,9 +597,9 @@ const MARKER_GO_NAME_PREFIX = '__combosDevelopmentToolMarker:';
  * - attaches pick `Event` + outline only on nodes with {@link CombosDevelopmentToolTarget}.
  *
  * Turn on/off via:
- * - `window.dispatchEvent(new CustomEvent(COMBOS_DEVELOPMENT_TOOL_SET, { detail: { enabled: true } }))`
- * - `window.postMessage({ type: COMBOS_DEVELOPMENT_TOOL_SET, enabled: true }, targetOrigin)` (e.g. from parent iframe)
- * - `game.emit(COMBOS_DEVELOPMENT_TOOL_SET, { enabled: true })` or `getSystem(CombosDevelopmentToolSystem).setEnabled(true)`
+ * - `window.dispatchEvent(new CustomEvent(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, { detail: { enabled: true } }))`
+ * - `window.postMessage({ type: COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, enabled: true }, targetOrigin)` (e.g. from parent iframe)
+ * - `game.emit(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, { enabled: true })` or `getSystem(CombosDevelopmentToolSystem).setEnabled(true)`
  *
  * Mute (independent of pick mode; parent toolbar or in-game debug UI):
  * - `postMessage({ type: COMBOS_DEVELOPMENT_TOOL_SET_MUTED, muted: true })`
@@ -643,7 +643,7 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.needsMarkerRescan = false;
         /** ownerGoId → its marker GO (icon child, Graphics only). */
         this.markerGoByOwner = new Map();
-        this.onWindowSet = (e) => {
+        this.onWindowSetPickMode = (e) => {
             const d = e.detail;
             if (d && typeof d.enabled === 'boolean') {
                 this.setEnabled(d.enabled);
@@ -673,7 +673,7 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             const d = e.data;
             if (!d || typeof d !== 'object')
                 return;
-            if (d.type === COMBOS_DEVELOPMENT_TOOL_SET && typeof d.enabled === 'boolean') {
+            if (d.type === COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE && typeof d.enabled === 'boolean') {
                 this.setEnabled(d.enabled);
             }
             else if (d.type === COMBOS_DEVELOPMENT_TOOL_SET_MUTED && typeof d.muted === 'boolean') {
@@ -693,7 +693,7 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
                 this.handleApplyProperty(d);
             }
         };
-        this.onGameSet = (payload) => {
+        this.onGameSetPickMode = (payload) => {
             if (payload && typeof payload.enabled === 'boolean') {
                 this.setEnabled(payload.enabled);
             }
@@ -715,13 +715,13 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.postMessageOrigin = params?.postMessageOrigin ?? '*';
         this.allowedMessageOrigins = mergeAllowedMessageOrigins(params?.allowedMessageOrigins);
         if (typeof window !== 'undefined') {
-            window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET, this.onWindowSet);
+            window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, this.onWindowSetPickMode);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onWindowSetMuted);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onWindowSetMarkerOverlay);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onWindowRefresh);
             window.addEventListener('message', this.onWindowMessage);
         }
-        this.game.on(COMBOS_DEVELOPMENT_TOOL_SET, this.onGameSet);
+        this.game.on(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, this.onGameSetPickMode);
         this.game.on(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onGameSetMuted);
         this.game.on(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onGameSetMarkerOverlay);
         this.game.on(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onGameRefresh);
@@ -731,13 +731,13 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
     }
     onDestroy() {
         if (typeof window !== 'undefined') {
-            window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET, this.onWindowSet);
+            window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, this.onWindowSetPickMode);
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onWindowSetMuted);
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onWindowSetMarkerOverlay);
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onWindowRefresh);
             window.removeEventListener('message', this.onWindowMessage);
         }
-        this.game.off(COMBOS_DEVELOPMENT_TOOL_SET, this.onGameSet);
+        this.game.off(COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE, this.onGameSetPickMode);
         this.game.off(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onGameSetMuted);
         this.game.off(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onGameSetMarkerOverlay);
         this.game.off(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onGameRefresh);
@@ -1096,13 +1096,13 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
     }
     postSetSuccess(enabled) {
         const payload = {
-            type: COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS,
+            type: COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS,
             enabled,
         };
         if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
             window.parent.postMessage(payload, this.postMessageOrigin);
         }
-        this.game.emit(COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS, { enabled });
+        this.game.emit(COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS, { enabled });
     }
     postStateChanged() {
         const state = {
@@ -1375,7 +1375,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.37",
+    packageVersion: "0.0.39",
 });
 
 exports.COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY = COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY;
@@ -1383,12 +1383,12 @@ exports.COMBOS_DEVELOPMENT_TOOL_CLEAR_SELECTION = COMBOS_DEVELOPMENT_TOOL_CLEAR_
 exports.COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED = COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED;
 exports.COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED = COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED;
 exports.COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS = COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS;
+exports.COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS = COMBOS_DEVELOPMENT_TOOL_PICK_MODE_SUCCESS;
 exports.COMBOS_DEVELOPMENT_TOOL_READY = COMBOS_DEVELOPMENT_TOOL_READY;
 exports.COMBOS_DEVELOPMENT_TOOL_REFRESH = COMBOS_DEVELOPMENT_TOOL_REFRESH;
-exports.COMBOS_DEVELOPMENT_TOOL_SET = COMBOS_DEVELOPMENT_TOOL_SET;
 exports.COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY = COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY;
 exports.COMBOS_DEVELOPMENT_TOOL_SET_MUTED = COMBOS_DEVELOPMENT_TOOL_SET_MUTED;
-exports.COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS = COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS;
+exports.COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE = COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE;
 exports.COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED = COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED;
 exports.CombosDevelopmentToolSystem = CombosDevelopmentToolSystem;
 exports.CombosDevelopmentToolTarget = CombosDevelopmentToolTarget;