@combos-fun/plugin-development-tool 0.0.47 → 0.0.49

package/README.md

@@ -1,9 +1,19 @@
 # @combos-fun/plugin-development-tool
 
-Scene / tagged object tap development tool: outline overlay and parent postMessage
+Scene / tagged object tap development tool: canvas overlay (2D + 3D) and parent postMessage
 
 Keywords: `devtool`, `inspector`, `selection`, `outline`, `editor`, `debug`.
 
+Game `GameObject` nodes are tagged at build time. Add the Vite plugin to the **game** config:
+
+```ts
+import { combosDevelopmentTargetPlugin } from '@combos-fun/plugin-development-tool/vite';
+
+export default defineConfig({
+  plugins: [combosDevelopmentTargetPlugin()],
+});
+```
+
 ## Documentation
 
 - Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)

package/agent-skill.md

@@ -1,46 +1,70 @@
 # `@combos-fun/plugin-development-tool` — Agent notes
 
-**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`.
+**Shared editor iframe picker** (2D and 3D). Outline, markers, and pick hit-testing are drawn on a transparent HTML canvas overlay with the Canvas 2D API. It does **not** depend on `plugin-renderer`, `plugin-renderer-event`, `plugin-renderer-graphics`, or any `plugin-renderer-3d*` package.
+
+Game authors do **not** mount Targets or write `payload.source`. The host Vite plugin rewrites `new GameObject(...)`.
 
 ## When to read
 
-Read when integrating the Combos editor iframe, pick mode, Scene Edit messages, or marker overlays.
+Read when integrating the Combos editor iframe, pick mode, Scene Edit messages, marker overlays, or the host Vite plugin.
 
 ## Public API
 
-`CombosDevelopmentToolTarget` marks a selectable GameObject. Its optional `payload` is included in snapshots; source persistence requires `payload.source.file` and `payload.source.anchor`.
+`attachDevelopmentTarget(go, { file, anchor })` is the runtime helper the Vite plugin inserts. It is idempotent.
 
 `CombosDevelopmentToolSystem` accepts:
 
 - `postMessageOrigin`: outbound parent `targetOrigin`, default `'*'`.
 - `allowedMessageOrigins`: inbound origins merged with the default `knoffice.tech` and `converge.ai` host suffixes.
 
-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`.
+It exposes `setEnabled`, `requestSceneRescan`, and `setMarkerOverlay`, plus matching `COMBOS_DEVELOPMENT_TOOL_*` constants and protocol helpers. `setMuted` still forwards to `SoundSystem` but host mute messages are owned by `@combos-fun/plugin-sound`. There is no `CombosDevelopmentToolSelectScope`. `COMBOS_DEVELOPMENT_TOOL_READY` is exported but never posted; wait for engine `combos-game:ready`.
 
 ## Required setup
 
-Register the 2D renderer before Event and Graphics, then the development tool:
+Register the dimension renderer first, then the development tool. Event / Graphics systems are **not** required for picking.
+
+2D:
 
 ```ts
 new Game({
   systems: [
     new RendererSystem({ canvas, width, height }),
-    new EventSystem(),
-    new GraphicsSystem(),
     new CombosDevelopmentToolSystem(),
   ],
 });
 ```
 
-Attach `CombosDevelopmentToolTarget` only to objects the editor may pick.
+3D:
+
+```ts
+new Game({
+  systems: [
+    new Renderer3DSystem({ canvas, width, height }),
+    new CombosDevelopmentToolSystem(),
+  ],
+});
+```
+
+In the **game** Vite config (host / Creator), not in game source:
+
+```ts
+import { defineConfig } from 'vite';
+import { combosDevelopmentTargetPlugin } from '@combos-fun/plugin-development-tool/vite';
+
+export default defineConfig({
+  plugins: [combosDevelopmentTargetPlugin()],
+});
+```
+
+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`).
 
 ## Runtime behaviour
 
-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 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.
 
-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.
+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.
 
-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.
+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).
 
 ## postMessage protocol
 
@@ -49,7 +73,6 @@ Parent → iframe:
 - `set-pick-mode { enabled }`
 - `refresh`, `clear-selection`
 - `apply-property`
-- `set-muted { muted }`
 - `set-marker-overlay { enabled }`
 
 Iframe → parent:
@@ -57,33 +80,24 @@ Iframe → parent:
 - `pick-mode-success { enabled }`
 - `gameobject-selected { snapshot, pointer }`
 - `gameobject-deselected { reason }`
-- `state-changed { muted }`
 - `marker-overlay-success { enabled, total, markers }`
 
 Inbound messages are origin-checked. `allowedMessageOrigins: ['localhost']` adds local development; `['*']` alone disables the check. `postMessageOrigin` controls outbound delivery separately.
 
 ## Scene Edit fields
 
-Snapshots expose described schema-backed `fieldDescriptors`, not raw fields. For authoritative `@Field` metadata rules, read `@combos-fun/inspector-decorator`.
+Snapshots expose described schema-backed `fieldDescriptors`, not raw fields. For authoritative `@Field` metadata rules, read `@combos-fun/inspector-decorator`. Persist lookup uses `payload.source.file` + `payload.source.anchor` injected by the Vite plugin.
 
 ## Common pitfalls
 
-- Selection requires `RendererSystem`, `EventSystem`, and `GraphicsSystem`.
+- 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.
 - 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.
+- Persistence fails if the game build did not run `combosDevelopmentTargetPlugin`.
 - Markers are visual only and do not create a Target.
-
-## Minimal example
-
-```ts
-editableGo.addComponent(new CombosDevelopmentToolTarget({
-  payload: {
-    source: { file: 'src/scene.ts', anchor: 'start-button' },
-  },
-}));
-```
+- Creator-managed game code must not call `setEnabled` / `requestSceneRescan` or emit `combos-development-tool:*` control messages.
 
 ## Verification
 
-Run `pnpm --filter @combos-fun/plugin-development-tool run build`.
+Run `pnpm --filter @combos-fun/plugin-development-tool run test` and `pnpm --filter @combos-fun/plugin-development-tool run build`.

package/combos-plugin.json

@@ -2,18 +2,17 @@
   "name": "@combos-fun/plugin-development-tool",
   "pluginId": "development-tool",
   "category": "devtool",
-  "dimension": "2d",
+  "dimension": "shared",
   "isCore": false,
   "keywords": ["devtool", "inspector", "selection", "outline", "editor", "debug"],
   "agentSkill": "./agent-skill.md",
   "requires": [
-    "@combos-fun/engine",
-    "@combos-fun/plugin-renderer-event",
-    "@combos-fun/plugin-renderer-graphics"
+    "@combos-fun/engine"
   ],
   "exports": [
     "CombosDevelopmentToolSystem",
     "CombosDevelopmentToolTarget",
+    "attachDevelopmentTarget",
     "COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED",
     "COMBOS_DEVELOPMENT_TOOL_REFRESH",
     "COMBOS_DEVELOPMENT_TOOL_SET_PICK_MODE",