@combos-fun/plugin-transition 0.0.5 → 0.0.7

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-transition
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-transition — part of the Combos Fun engine monorepo.
+
+Keywords: `tween`, `animation`, `easing`, `transition`, `property`.
+
+## 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/plugin-transition/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-transition/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,112 @@
+# `@combos-fun/plugin-transition` — Agent notes
+
+Data-driven tween / property animation. Tweens any numeric Component
+property via dot-path (e.g. `positionX`, `rotationY`, `alpha`). No
+rendering dependency — works with both 2D and 3D pipelines.
+
+## When to read
+
+Read for any tween / motion / value animation: button bounce, fade-in /
+out, easing curves on transforms, scripted dialog motion.
+
+## Public API
+
+```ts
+import { Transition, TransitionSystem } from '@combos-fun/plugin-transition';
+```
+
+`componentName = 'Transition'`,
+**`systemName = 'transition'` (lowercase)** — use the class reference with
+`game.getSystem(TransitionSystem)`, not the string.
+
+### Init params
+
+```ts
+{
+  group: Record<string, AnimationStruct[]>;
+}
+
+interface AnimationStruct {
+  name: string;
+  component: ComponentClass;
+  values: { time: number; value: any; tween?: EasingName }[];
+}
+```
+
+`values` is a keyframe list. `time` is the timestamp on the timeline,
+`value` is the target value, `tween` selects easing for the segment ending
+at this keyframe.
+
+### Methods
+
+`play(name?, iteration?)` — play a named animation; pass `name` undefined
+to play all. `stop(name?)` — stop one or all.
+
+### Events
+
+`'finish'` is emitted with the animation name when iteration count is
+reached.
+
+### Easing names
+
+`linear`, `ease-in`, `ease-out`, `ease-in-out`, `bounce-in`,
+`bounce-out`, `bounce-in-out`, `none`.
+
+## Required setup
+
+`TransitionSystem` is a stub — the heavy lifting happens inside the
+`Transition` component's `update()`. You still need to register it so the
+engine routes lifecycle hooks correctly.
+
+```ts
+new Game({
+  systems: [/* ...renderer / physics ... */, new TransitionSystem()],
+});
+```
+
+## Runtime behaviour
+
+- The component reads / writes target Component fields via dot-path each
+  frame, using the easing function for the current segment.
+- `'finish'` fires when iteration count is exhausted; for an infinite
+  loop, pass `iteration = 0` (or omit) — `'finish'` will not fire.
+- Tween source data is registered up-front in `group`; modify it
+  imperatively only when needed (the system observes the component).
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| `getSystem('transition')` returns undefined | Use class reference: `game.getSystem(TransitionSystem)` |
+| Tween jumps to final value | Add intermediate keyframes; `time` must be increasing |
+| Tween fires on wrong component | The `component` field in each `AnimationStruct` is the **target Component class**, not a Component instance |
+| Pause / resume drifts | Tween uses internal timeline; pause via `Game.pause()` covers it correctly |
+
+## Minimal example
+
+```ts
+import { Transition, TransitionSystem } from '@combos-fun/plugin-transition';
+import { Transform } from '@combos-fun/engine';
+
+const go = new GameObject('moving-box');
+go.addComponent(new Transform({ position: { x: 0, y: 0 } }));
+go.addComponent(new Transition({
+  group: {
+    slideRight: [{
+      name: 'slideRight',
+      component: Transform,
+      values: [
+        { time: 0,    value: { positionX: 0 } },
+        { time: 1000, value: { positionX: 500 }, tween: 'ease-in-out' },
+      ],
+    }],
+  },
+}));
+
+// Trigger from a Component lifecycle hook (not bootstrap):
+// gameObject.getComponent(Transition)?.play('slideRight', 1);
+```
+
+## Verification
+
+`pnpm --filter @combos-fun/plugin-transition run build`.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-transition",
+  "pluginId": "transition",
+  "category": "animation",
+  "dimension": "shared",
+  "isCore": false,
+  "keywords": ["tween", "animation", "easing", "transition", "property"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine"],
+  "exports": ["Transition", "TransitionSystem"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-transition",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-transition",
   "main": "index.js",
   "module": "dist/plugin-transition.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.transition.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-transition.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-transition.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-transition.d.ts",
   "keywords": [
     "combos-fun",
@@ -19,7 +33,7 @@
   "dependencies": {
     "@tweenjs/tween.js": "^25.0.0",
     "sprite-timeline": "^1.10.2",
-    "@combos-fun/engine": "0.0.5"
+    "@combos-fun/engine": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"