@combos-fun/inspector-decorator 0.0.45 → 0.0.47

package/agent-skill.md

@@ -1,77 +1,70 @@
 # `@combos-fun/inspector-decorator` — Agent notes
 
-Runtime decorator helpers used by Combos Fun engine and plugin packages to expose Component fields to editor / inspector tooling. Built on `reflect-metadata`.
+Decorator metadata consumed by the Combos editor/inspector. Built on `reflect-metadata`.
 
 ## When to read
 
-Read when authoring a new Component / System and you want its fields to be visible in the Combos Fun editor inspector, or when investigating why a field appears (or fails to appear) in the inspector.
+Read when exposing Component fields to the inspector or diagnosing missing field metadata.
 
 ## Public API
 
 ```ts
-import 'reflect-metadata';
-import { Field, ExecuteInEditMode, getPropertiesOf, type, step } from '@combos-fun/inspector-decorator';
+import {
+  Field,
+  ExecuteInEditMode,
+  getPropertiesOf,
+  shouldExecuteInEditMode,
+  type,
+  step,
+} from '@combos-fun/inspector-decorator';
 ```
 
-| Export | Use |
-|--------|-----|
-| `Field()` / `Field(options)` / `Field(returnTypeFunc)` | Property decorator on a Component class field. Records a `FieldMetadata` entry that the editor reads to render an input control. |
-| `ExecuteInEditMode` | Class decorator marking a Component that should also run in editor mode (in addition to game mode). |
-| `getPropertiesOf(ComponentClass)` | Inspector-side helper. Returns the `FieldMetadata` tree for a Component. |
-| `type` / `step` | Legacy `IDEProp`-style decorators kept for backwards compatibility with older Combos plugins. |
+- `Field()` accepts options, a return-type function, or both and records `FieldMetadata`.
+- `ExecuteInEditMode` marks the class for edit-mode execution only.
+- `getPropertiesOf(ComponentClass)` returns the nested metadata tree.
+- `type` / `step` are legacy writers to `constructor.IDEProps`.
+- Metadata constants are also exported; `IDE_PROPERTY_METADATA` is a string key.
 
-`FieldOptions` accepts at minimum `{ name?, type?, default?, options?, ... }` — check the `interface.ts` source for the full surface.
+Use `@Field` for new code. Scene Edit prefers it, falls back to this package's legacy `IDEProps` object, and ignores engine `@IDEProp` arrays.
+
+Supported editor hints are `volume-slider`, `number-slider`, `number-stepper`, `color`, `enum`, `toggle`, and `text`. Common options include `type`, `label`, `description`, `group`, `enumOptions`, `min`, `max`, `step`, and `unit`. Initialize defaults on the class field, not in a `default` option.
 
 ## Required setup
 
-- `reflect-metadata` must be imported once per app entry. The package's
-  `lib/index.ts` already does this on import, so importing anything from
-  `@combos-fun/inspector-decorator` in your plugin entry is enough.
-- TypeScript: `experimentalDecorators` and `emitDecoratorMetadata` must be
-  enabled in your plugin's `tsconfig.json`.
+Enable `experimentalDecorators` and `emitDecoratorMetadata`. Importing this package also imports `reflect-metadata`.
 
 ## Runtime behaviour
 
-- `Field` reads `design:type` metadata via `reflect-metadata` and stores a
-  per-class property descriptor on the class constructor under the
-  `IDE_PROPERTY_METADATA` symbol.
-- `getPropertiesOf` walks that metadata tree, recursing into nested
-  Component types and arrays.
-- These decorators have **no runtime cost during a normal game frame** —
-  they only emit metadata at class load time and are read on demand by the
-  editor.
+`Field` reads `design:type` and stores class metadata. `getPropertiesOf` resolves nested and array types on demand; decorators do no per-frame work.
 
 ## Common pitfalls
 
-- Forgetting `experimentalDecorators` / `emitDecoratorMetadata` produces a
-  compile-time TypeScript error like `"Decorators are not valid here"` or
-  silently missing metadata at runtime.
-- Importing `@combos-fun/inspector-decorator` without `reflect-metadata`
-  installed throws at module load. Pin it in `dependencies`, not
-  `devDependencies`, of any plugin that uses `Field`.
-- Using `Symbol` keys for fields throws `SymbolKeysNotSupportedError` —
-  always use `string` property keys.
+- Symbol property keys throw `SymbolKeysNotSupportedError`; use string keys.
+- Supply a return-type function for nested types that reflection cannot infer.
+- Fields intended for Scene Edit need useful `label` and `description` metadata.
+- On a new field, use only `@Field`; do not mix it with legacy `@type`,
+  `@step`, or engine `@IDEProp`.
 
 ## Minimal example
 
 ```ts
-import 'reflect-metadata';
-import { Field } from '@combos-fun/inspector-decorator';
 import { Component } from '@combos-fun/engine';
+import { Field } from '@combos-fun/inspector-decorator';
 
-export class MyHealth extends Component {
-  static componentName = 'MyHealth';
+class Health extends Component {
+  static componentName = 'Health';
 
-  @Field({ default: 100 })
+  @Field({
+    type: 'number',
+    label: 'HP',
+    description: 'Current hit points.',
+    group: 'Health',
+    editor: 'number-stepper',
+  })
   hp = 100;
-
-  @Field({ default: false })
-  invincible = false;
 }
 ```
 
 ## Verification
 
-- `pnpm --filter @combos-fun/inspector-decorator run build` should succeed.
-- In the consumer plugin, `getPropertiesOf(MyHealth)` should return a
-  `FieldMetadata` tree containing the `hp` and `invincible` entries.
+Run `pnpm --filter @combos-fun/inspector-decorator run build`; `getPropertiesOf(Health)` should include `hp`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/inspector-decorator",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "Runtime decorator helpers used by Combos Fun engine and plugin packages to expose Component fields to editor / inspector tooling",
   "publishConfig": {
     "access": "public"