@combos-fun/plugin-development-tool 0.0.33 → 0.0.34

package/agent-skill.md

@@ -29,30 +29,9 @@ import {
   outline, and posts `COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED`
   messages to the parent window.
 
-### `CombosDevelopmentToolTargetParams`
-
-| 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.
-
 ## 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:
+This plugin depends on `@combos-fun/plugin-renderer-event` (for taps) and `@combos-fun/plugin-renderer-graphics` (for the outline). Register all of them after `RendererSystem`:
 
 ```ts
 new Game({
@@ -65,26 +44,6 @@ new Game({
 });
 ```
 
-## Pick-mode behavior
-
-- 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.
-
-## Pick bounds
-
-The generated pick Event resolves local bounds in this order:
-
-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.
-
-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.
-
 ## Common pitfalls
 
 | Symptom | Fix |
@@ -92,7 +51,7 @@ Set `transform.size` for `Img`, `Text`, `Sprite`, and `SpriteAnimation` GameObje
 | 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 |
+| Selection stuck on stale node | Listen for `COMBOS_DEVELOPMENT_TOOL_REFRESH` to clear |
 
 ## Inbound postMessage security
 
@@ -134,19 +93,26 @@ 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
+- Draws the icon **in-engine** (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.config.volume`) go through the normal
-  selection → snapshot → `apply-property` flow and **persist to source** like any
+  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.
+  `CombosDevelopmentToolTarget`** (added by the game code — see the game template's
+  Scene Edit rules; objects with a `Sound` component must be given a Target even
+  when they render nothing).
 - 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.
+
 ## Verification
 
 `pnpm --filter @combos-fun/plugin-development-tool run build`.

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

@@ -5,6 +5,7 @@ var engine = require('@combos-fun/engine');
 var pluginRenderer = require('@combos-fun/plugin-renderer');
 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';
@@ -201,30 +202,17 @@ function isSceneSourceAnchor(v) {
         typeof v.file === 'string');
 }
 
-const SKIP_KEYS = new Set([
-    'gameObject',
-    'name',
-    'started',
-    '__componentDefaultParams',
-    'destroyed',
-    'inScene',
-    'worldTransform',
-    'children',
-    '_parent',
-]);
-const COMPONENT_SKIP_KEYS = {
-    Graphics: new Set(['graphics']),
-    Physics: new Set([
-        'body',
-        'Body',
-        'PhysicsEngine',
-        'World',
-        'Constraint',
-        'mouseConstraint',
-        'bodyParams',
-    ]),
-    Event: new Set(['hitArea']),
-};
+function resolveValueType(value) {
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (value !== null && typeof value === 'object')
+        return 'object';
+    return 'unsupported';
+}
 function cloneJsonSafe(value, depth = 0) {
     if (value === null || value === undefined)
         return value;
@@ -249,20 +237,171 @@ function cloneJsonSafe(value, depth = 0) {
     }
     return undefined;
 }
+function readFieldReflectSchema(ctor) {
+    const properties = Reflect.getMetadata(inspectorDecorator.IDE_PROPERTY_METADATA, ctor) ||
+        {};
+    return Object.keys(properties).map(key => ({
+        key,
+        ...properties[key],
+    }));
+}
+/** Legacy `@type` / `@step` write `constructor.IDEProps` as an object keyed by property name. */
+function readLegacyIdePropsSchema(ctor) {
+    const raw = ctor.IDEProps;
+    if (!raw || Array.isArray(raw) || typeof raw !== 'object') {
+        return [];
+    }
+    return Object.keys(raw).map(key => {
+        const entry = raw[key] || {};
+        return {
+            key,
+            type: typeof entry.type === 'string' ? entry.type : undefined,
+            step: typeof entry.step === 'number' ? entry.step : undefined,
+            min: typeof entry.min === 'number' ? entry.min : undefined,
+            max: typeof entry.max === 'number' ? entry.max : undefined,
+            label: typeof entry.label === 'string' ? entry.label : undefined,
+            description: typeof entry.description === 'string' ? entry.description : undefined,
+            group: typeof entry.group === 'string' ? entry.group : undefined,
+            editor: entry.editor,
+            enumOptions: Array.isArray(entry.enumOptions) ? entry.enumOptions : undefined,
+            unit: typeof entry.unit === 'string' ? entry.unit : undefined,
+        };
+    });
+}
+function collectSchemaProps(comp) {
+    const ctor = comp.constructor;
+    const fromField = readFieldReflectSchema(ctor);
+    if (fromField.length > 0) {
+        return fromField;
+    }
+    return readLegacyIdePropsSchema(ctor);
+}
+function mapEditorKind(options, valueType) {
+    if (options.editor) {
+        return options.editor;
+    }
+    if (valueType === 'boolean')
+        return 'toggle';
+    if (options.enumOptions?.length && valueType === 'string')
+        return 'enum';
+    if (valueType === 'number') {
+        if (options.min !== undefined && options.max !== undefined) {
+            return 'number-slider';
+        }
+        return 'number-stepper';
+    }
+    if (valueType === 'string')
+        return 'text';
+    return undefined;
+}
+function buildNumberMeta(options) {
+    if (options.min === undefined &&
+        options.max === undefined &&
+        options.step === undefined &&
+        options.unit === undefined) {
+        return undefined;
+    }
+    return {
+        min: options.min,
+        max: options.max,
+        step: options.step,
+        unit: options.unit,
+    };
+}
+function titleCaseLeaf(leaf) {
+    return leaf
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/_/g, ' ')
+        .replace(/^./, char => char.toUpperCase());
+}
+function resolveLabel(options, path) {
+    if (options.label?.trim()) {
+        return options.label.trim();
+    }
+    const leaf = path[path.length - 1];
+    return leaf ? titleCaseLeaf(leaf) : undefined;
+}
+function leafDescriptorsFromValue(componentName, options, path, value) {
+    const description = options.description?.trim();
+    if (!description) {
+        // Scene Edit only exposes fields that include a human description.
+        return [];
+    }
+    const valueType = resolveValueType(value);
+    if (valueType === 'unsupported') {
+        return [];
+    }
+    const typeHint = options.type;
+    const isVector = typeHint === 'vector2' ||
+        (valueType === 'object' &&
+            value !== null &&
+            'x' in value &&
+            'y' in value);
+    const isSize = typeHint === 'size' ||
+        (valueType === 'object' &&
+            value !== null &&
+            'width' in value &&
+            'height' in value);
+    if (isVector || isSize) {
+        const record = value;
+        const axes = isSize ? ['width', 'height'] : ['x', 'y'];
+        const baseLabel = resolveLabel(options, path) ?? componentName;
+        const out = [];
+        for (const axis of axes) {
+            const axisValue = record[axis];
+            const axisType = resolveValueType(axisValue);
+            if (axisType === 'unsupported' || axisType === 'object')
+                continue;
+            const axisPath = [...path, axis];
+            out.push({
+                path: axisPath,
+                value: axisValue,
+                valueType: axisType,
+                label: `${baseLabel} ${axis.toUpperCase()}`,
+                description,
+                group: options.group ?? componentName,
+                editorKind: mapEditorKind(options, axisType),
+                numberMeta: buildNumberMeta(options),
+                persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+            });
+        }
+        return out;
+    }
+    if (valueType === 'object') {
+        return [];
+    }
+    const label = resolveLabel(options, path);
+    if (!label) {
+        return [];
+    }
+    return [
+        {
+            path,
+            value: cloneJsonSafe(value),
+            valueType,
+            label,
+            description,
+            group: options.group ?? componentName,
+            editorKind: mapEditorKind(options, valueType),
+            enumOptions: options.enumOptions,
+            numberMeta: buildNumberMeta(options),
+            persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+        },
+    ];
+}
 function serializeComponent(comp) {
-    const out = {};
-    const componentSkips = COMPONENT_SKIP_KEYS[comp.name];
-    for (const key of Object.keys(comp)) {
-        if (SKIP_KEYS.has(key) || key.startsWith('_'))
-            continue;
-        if (componentSkips?.has(key))
-            continue;
-        const value = comp[key];
+    const componentName = comp.name;
+    const schema = collectSchemaProps(comp);
+    if (schema.length === 0) {
+        return [];
+    }
+    const out = [];
+    const record = comp;
+    for (const prop of schema) {
+        const value = record[prop.key];
         if (typeof value === 'function')
             continue;
-        const cloned = cloneJsonSafe(value);
-        if (cloned !== undefined)
-            out[key] = cloned;
+        out.push(...leafDescriptorsFromValue(componentName, prop, [prop.key], value));
     }
     return out;
 }
@@ -281,8 +420,9 @@ function buildGameObjectSnapshot(go) {
         .filter(c => c.name !== 'CombosDevelopmentToolTarget')
         .map(c => ({
         componentName: c.name,
-        fields: serializeComponent(c),
-    }));
+        fieldDescriptors: serializeComponent(c),
+    }))
+        .filter(c => c.fieldDescriptors.length > 0);
     return {
         id: go.id,
         name: go.name,
@@ -1235,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.33",
+    packageVersion: "0.0.34",
 });
 
 exports.COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY = COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY;