@combos-fun/plugin-development-tool 0.0.44 → 0.0.46

package/agent-skill.md

@@ -1,43 +1,25 @@
 # `@combos-fun/plugin-development-tool` — Agent notes
 
-In-canvas debugging / inspection plugin. Adds a `CombosDevelopmentToolTarget` Component that, when tapped, draws an outline overlay around the GameObject and posts a parent-frame message identifying the selected node. Used by the Combos Fun editor / inspector to wire up two-way selection between the editor tree and the running game.
+**2D-only editor iframe picker.** It uses the Pixi renderer Event/Graphics plugins to select tagged GameObjects, draw an outline, and exchange selection data with the parent editor. For 3D picking, use `@combos-fun/plugin-renderer-3d-event`.
 
 ## When to read
 
-Read whenever building tooling, integrating with the Combos editor, or debugging which GameObject is being tapped at runtime.
+Read when integrating the Combos editor iframe, pick mode, Scene Edit messages, or marker overlays.
 
 ## Public API
 
-```ts
-import {
-  CombosDevelopmentToolSystem,
-  CombosDevelopmentToolTarget,
-  COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED,
-  COMBOS_DEVELOPMENT_TOOL_CLEAR_SELECTION,
-  COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED,
-  COMBOS_DEVELOPMENT_TOOL_REFRESH,
-  COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE,
-  type CombosDevelopmentToolTargetParams,
-  type CombosDevelopmentToolSystemParams,
-  type CombosDevelopmentToolSelectScope,
-} from '@combos-fun/plugin-development-tool';
-```
+`CombosDevelopmentToolTarget` marks a selectable GameObject. Its optional `payload` is included in snapshots; source persistence requires `payload.source.file` and `payload.source.anchor`.
 
-- `CombosDevelopmentToolTarget` — Component to attach to any GameObject
-  that should be selectable in editor mode.
-- `CombosDevelopmentToolSystem` — System that listens to taps, draws the
-  outline, and posts `COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED`
-  messages to the parent window.
+`CombosDevelopmentToolSystem` accepts:
 
-### `CombosDevelopmentToolTargetParams`
+- `postMessageOrigin`: outbound parent `targetOrigin`, default `'*'`.
+- `allowedMessageOrigins`: inbound origins merged with the default `knoffice.tech` and `converge.ai` host suffixes.
 
-| Field | Type | Notes |
-|---|---|---|
-| `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`. |
+It exposes `setEnabled`, `requestSceneRescan`, `setMuted`, and `setMarkerOverlay`, plus matching `COMBOS_DEVELOPMENT_TOOL_*` constants and protocol helpers. There is no `CombosDevelopmentToolSelectScope`. `COMBOS_DEVELOPMENT_TOOL_READY` is exported but never posted; wait for engine `combos-game:ready`.
 
 ## Required setup
 
-This plugin depends on `@combos-fun/plugin-renderer-event` (for taps) and `@combos-fun/plugin-renderer-graphics` (for the outline). `RendererSystem`, `EventSystem`, `GraphicsSystem`, and `CombosDevelopmentToolSystem` must all be registered before edit mode runs. `RendererSystem` must come before renderer plugins; the relative constructor-array position of Event, Graphics, and Development Tool is not significant when edit mode is enabled only after system bootstrap. Recommended order:
+Register the 2D renderer before Event and Graphics, then the development tool:
 
 ```ts
 new Game({
@@ -45,100 +27,63 @@ new Game({
     new RendererSystem({ canvas, width, height }),
     new EventSystem(),
     new GraphicsSystem(),
-    new CombosDevelopmentToolSystem({ /* options */ }),
+    new CombosDevelopmentToolSystem(),
   ],
 });
 ```
 
-## Pick-mode behavior
+Attach `CombosDevelopmentToolTarget` only to objects the editor may pick.
 
-- The System starts disabled.
-- While enabled, only GameObjects carrying `CombosDevelopmentToolTarget` receive editor pick bindings.
-- Existing game `Event` hit targets are soft-disabled by setting their renderer containers non-interactive; they are restored when pick mode is disabled.
-- Adding a Target while enabled automatically soft-disables that object's game Event and installs its pick binding through the Component observer.
-- Removing a Target automatically releases its pick binding and clears selection when necessary.
-- Dynamic Target additions and removals do not require `requestSceneRescan()`. A full rescan exists for parent/tooling-driven structural refreshes.
+## Runtime behaviour
 
-## Pick bounds
+The System starts disabled. In pick mode it soft-disables existing game Event containers, installs pick Events only on Target objects, and restores game Events when disabled. Target additions/removals are observed automatically; `requestSceneRescan()` is for parent-driven structural refreshes.
 
-The generated pick Event resolves local bounds in this order:
+Pick bounds resolve in this order: own rendered Graphics bounds, positive `transform.size`, renderer-container bounds, then `1×1`. Set `transform.size` for non-Graphics renderers when precise bounds matter.
 
-1. A GameObject with `Graphics` uses its own Pixi `Graphics.getLocalBounds()` first.
-2. Other renderers use positive `transform.size` as a `(0, 0, width, height)` box.
-3. The renderer container's local bounds are used as a fallback.
-4. A 1×1 box is the final fallback.
+The marker overlay is independent of pick mode and mute. It currently draws a 28×28 Graphics marker only for `Sound`; the owner still needs a Target for selection and persistence.
 
-Set `transform.size` for `Img`, `Text`, `Sprite`, and `SpriteAnimation` GameObjects so picking matches their displayed box. Graphics GameObjects should draw their actual geometry; the System deliberately prefers rendered Graphics bounds over the Transform size box, including circles and polygons drawn around a local origin.
+## postMessage protocol
 
-## Common pitfalls
+Parent → iframe:
 
-| Symptom | Fix |
-|---------|-----|
-| Selection box never appears | Ensure both `EventSystem` and `GraphicsSystem` are registered |
-| 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` |
+- `set-pick-mode { enabled }`
+- `refresh`, `clear-selection`
+- `apply-property`
+- `set-muted { muted }`
+- `set-marker-overlay { enabled }`
 
-## Inbound postMessage security
+Iframe → parent:
 
-`CombosDevelopmentToolSystem` validates `MessageEvent.origin` before handling parent commands.
+- `pick-mode-success { enabled }`
+- `gameobject-selected { snapshot, pointer }`
+- `gameobject-deselected { reason }`
+- `state-changed { muted }`
+- `marker-overlay-success { enabled, total, markers }`
 
-- Default allowlist: `knoffice.tech`, `converge.ai` (each matches the host and all subdomains).
-- `allowedMessageOrigins` **merges** with defaults (deduped). Pass `['localhost']` for local parent pages without repeating the defaults.
-- Pass `['*']` alone to accept any origin (disables the check).
-- Local dev with a non-knoffice parent (e.g. `http://localhost:9001`): `allowedMessageOrigins: ['localhost']`.
+Inbound messages are origin-checked. `allowedMessageOrigins: ['localhost']` adds local development; `['*']` alone disables the check. `postMessageOrigin` controls outbound delivery separately.
 
-```ts
-new CombosDevelopmentToolSystem({
-  allowedMessageOrigins: ['localhost'],
-});
-// effective: knoffice.tech, converge.ai, localhost
-```
+## Scene Edit fields
 
-Outbound `postMessageOrigin` is separate — it limits which parent origin receives selection snapshots.
+Snapshots expose described schema-backed `fieldDescriptors`, not raw fields. For authoritative `@Field` metadata rules, read `@combos-fun/inspector-decorator`.
 
-## postMessage protocol
+## Common pitfalls
+
+- Selection requires `RendererSystem`, `EventSystem`, and `GraphicsSystem`.
+- Parent messages require an iframe (`window.parent !== window`) and an allowed origin.
+- Structural replacement needs `refresh`; ordinary Target add/remove does not.
+- Persistence fails without both source file and anchor in Target payload.
+- Markers are visual only and do not create a Target.
 
-| Direction | type | Payload | Behavior |
-|-----------|------|---------|----------|
-| 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) |
-| iframe → parent | `combos-development-tool:gameobject-selected` | `{ snapshot, pointer }` | Object picked |
-| iframe → parent | `combos-development-tool:gameobject-deselected` | `{ reason }` | Selection cleared (`parent-request`, `pick-disabled`, `target-removed`) |
-| iframe → parent | `combos-development-tool:marker-overlay-success` | `{ enabled, total, markers: { componentName, count }[] }` | Marker overlay finished (re)building |
-
-## Marker overlay (surface invisible components)
-
-A reusable "pin a persistent icon on every object owning an otherwise invisible
-component" layer. Registry-driven (`markerLayer.ts` → `MARKER_COMPONENTS`).
-**For now it is `Sound` only** — the mechanism is generic (append `Physics` / `Camera` /
-triggers / spawn points later) but nothing else is registered yet.
-
-- Independent toggle, orthogonal to pick mode and mute: `setMarkerOverlay(true)` or
-  `postMessage({ type: 'combos-development-tool:set-marker-overlay', enabled: true })`
-  (also `window` CustomEvent / `game.emit`).
-- Draws a fixed **28×28** icon **in-engine** from the owner GameObject's local origin (a `Graphics` child GO pinned to the owner, so it
-  follows the object). The layer is **purely visual** — it does not wire up its own
-  selection. Because the icon adds to the owner's rendered bounds, the owner's own
-  `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. 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
-
-Selection snapshots no longer dump raw component `fields`. The host receives only
-schema-backed `fieldDescriptors` derived from `@Field` metadata (`label`,
-`description`, editor hints, min/max/step, etc.). Fields without a non-empty
-`description` are omitted. Custom game Components that should appear in Creator
-must declare `@Field({ label, description, ... })` in the user's language.
+## Minimal example
+
+```ts
+editableGo.addComponent(new CombosDevelopmentToolTarget({
+  payload: {
+    source: { file: 'src/scene.ts', anchor: 'start-button' },
+  },
+}));
+```
 
 ## Verification
 
-`pnpm --filter @combos-fun/plugin-development-tool run build`.
+Run `pnpm --filter @combos-fun/plugin-development-tool run build`.

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

@@ -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.44",
+    packageVersion: "0.0.46",
 });
 
 exports.COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY = COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY;