@combos-fun/plugin-renderer-event 0.0.6 → 0.0.8

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-renderer-event
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-renderer-event — part of the Combos Fun engine monorepo.
+
+Keywords: `pointer`, `touch`, `tap`, `hit-area`, `input`, `event`.
+
+## 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-renderer-event/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-renderer-event/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,95 @@
+# `@combos-fun/plugin-renderer-event` — Agent notes
+
+Pointer / touch event input for the 2D pipeline via Pixi v8 interaction. Provides hit-area shapes and a unified `tap` / `touchstart` / `touchmove` / `touchend` event surface on the `Event` Component.
+
+## When to read
+
+Read for any input task: tap detection, drag, swipe, hit-area shapes, or when integrating with `plugin-a11y` (which forwards DOM clicks as Event events).
+
+## Public API
+
+```ts
+import {
+  EventSystem,
+  Event,
+  HIT_AREA_TYPE,
+  type EventParams,
+  type EventSystemParams,
+} from '@combos-fun/plugin-renderer-event';
+```
+
+### `HIT_AREA_TYPE`
+
+`Circle`, `Ellipse`, `Polygon`, `Rect`, `RoundedRect`.
+
+### `EventParams`
+
+```ts
+{
+  hitArea: {
+    type: HIT_AREA_TYPE;
+    style?: { x?, y?, radius?, width?, height?, paths? };
+  };
+}
+```
+
+### `EventSystemParams`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `moveWhenInside` | `boolean?` | Drives Pixi `events.features.globalMove` |
+
+### Events emitted by the `Event` component
+
+`touchstart`, `touchmove`, `touchend`, `tap`, `touchendoutside`, `touchcancel`.
+
+Callback payload:
+
+```ts
+(payload) => {
+  payload.stopPropagation();
+  payload.data.pointerId;
+  payload.data.position;        // global / canvas-space
+  payload.data.localPosition;   // local to the GameObject
+  payload.gameObject;
+};
+```
+
+## Required setup
+
+- Add `RendererSystem` (from `plugin-renderer`) before `EventSystem`.
+- Provide `hitArea.style` in the same coordinate space as the visual:
+  `style` is interpreted in **local space** of the GameObject.
+
+## Runtime behaviour
+
+- Each `Event` component installs a Pixi hit-area on its container; the
+  system routes Pixi pointer events into Combos events.
+- `plugin-a11y` forwards DOM clicks on the a11y overlay as
+  `touchstart` / `touchend` / `tap` on the matching `Event` component.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| `tap` never fires | Add `EventSystem`, attach an `Event` component with a `hitArea` |
+| Hit area off-target | `style` coords are in local space — origin is the GameObject's `Transform.origin` |
+| Double-fire from a11y + canvas | Only attach handler once; A11y forwards through Event so a single subscription is enough |
+
+## Minimal example
+
+```ts
+import { Event, HIT_AREA_TYPE } from '@combos-fun/plugin-renderer-event';
+
+go.addComponent(new Event({
+  hitArea: { type: HIT_AREA_TYPE.Rect, style: { width: 200, height: 80 } },
+}));
+
+go.getComponent(Event)!.on('tap', (e) => {
+  /* handle */
+});
+```
+
+## Verification
+
+`pnpm --filter @combos-fun/plugin-renderer-event run build`.

package/combos-plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "@combos-fun/plugin-renderer-event",
+  "pluginId": "renderer-event",
+  "category": "input",
+  "dimension": "2d",
+  "isCore": false,
+  "keywords": ["pointer", "touch", "tap", "hit-area", "input", "event"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/plugin-renderer"],
+  "exports": ["EventSystem", "Event", "HIT_AREA_TYPE"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-event",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "@combos-fun/plugin-renderer-event",
   "main": "index.js",
   "module": "dist/plugin-renderer-event.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.renderer.event.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-renderer-event.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-renderer-event.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-renderer-event.d.ts",
   "keywords": [
     "combos-fun",
@@ -18,8 +32,8 @@
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
     "pixi.js": "^8.18.1",
-    "@combos-fun/engine": "0.0.6",
-    "@combos-fun/plugin-renderer": "0.0.6"
+    "@combos-fun/plugin-renderer": "0.0.8",
+    "@combos-fun/engine": "0.0.8"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"