@combos-fun/inspector-decorator 0.0.6 → 0.0.7

package/README.md

@@ -1 +1,27 @@
 # @combos-fun/inspector-decorator
+
+Runtime decorators used by Combos Fun engine packages (Field + legacy type/step IDEProps).
+
+Keywords: `decorators`, `inspector`, `editor`, `ide`, `field`, `metadata`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/inspector-decorator/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/inspector-decorator/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,82 @@
+# `@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`.
+
+## 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.
+
+## Public API
+
+```ts
+import 'reflect-metadata';
+import { Field, ExecuteInEditMode, getPropertiesOf, 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. |
+
+`FieldOptions` accepts at minimum `{ name?, type?, default?, options?, ... }`
+— check the `interface.ts` source for the full surface.
+
+## 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`.
+
+## 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.
+
+## 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.
+
+## Minimal example
+
+```ts
+import 'reflect-metadata';
+import { Field } from '@combos-fun/inspector-decorator';
+import { Component } from '@combos-fun/engine';
+
+export class MyHealth extends Component {
+  static componentName = 'MyHealth';
+
+  @Field({ default: 100 })
+  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.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/inspector-decorator",
+  "pluginId": "inspector-decorator",
+  "category": "core",
+  "dimension": "shared",
+  "isCore": true,
+  "keywords": ["decorators", "inspector", "editor", "ide", "field", "metadata"],
+  "agentSkill": "./agent-skill.md",
+  "requires": [],
+  "exports": ["Field", "ExecuteInEditMode", "getPropertiesOf", "type", "step"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/inspector-decorator",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Runtime decorators used by Combos Fun engine packages (Field + legacy type/step IDEProps).",
   "publishConfig": {
     "access": "public"
@@ -10,8 +10,22 @@
   "types": "dist/inspector-decorator.d.ts",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/inspector-decorator.esm.js",
+      "require": "./index.js",
+      "types": "./dist/inspector-decorator.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "keywords": [
     "combos-fun",
     "decorators"