@combos-fun/plugin-a11y 0.0.5 → 0.0.7

package/README.md

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

package/agent-skill.md

@@ -0,0 +1,84 @@
+# `@combos-fun/plugin-a11y` — Agent notes
+
+Accessibility plugin. Creates a positioned `<div>` overlay over the canvas;
+for each `GameObject` carrying an `A11y` component, creates a child `<div>`
+with `aria-label` / `role`. Click on the overlay forwards to the
+GameObject's `Event` component as `touchstart` / `touchend` / `tap`.
+
+## When to read
+
+Read for any accessibility task: screen-reader hints, keyboard-friendly
+DOM interaction, A11y debugging.
+
+## Public API
+
+```ts
+import { A11ySystem, A11y, A11yActivate } from '@combos-fun/plugin-a11y';
+```
+
+### `A11yParams`
+
+| Field | Notes |
+|-------|-------|
+| `hint` | Required. Used as `aria-label` |
+| `role` | ARIA role |
+| `delay` | Per-element activation delay |
+| `interactive` | Whether the overlay div is clickable |
+| `a11yId` | Optional stable id |
+| `event` | Forward target (defaults to the GameObject's `Event`) |
+| `props` / `state` / `attr` | Free-form ARIA `aria-*` props |
+
+### `A11yActivate`
+
+| Value | Numeric | Meaning |
+|-------|---------|---------|
+| `ENABLE` | `0` | Always on |
+| `DISABLE` | `1` | Always off |
+| `CHECK` | `2` | Use the system's `checkA11yOpen()` callback |
+
+### `A11ySystemParams`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `debug` | `boolean?` | Red overlay on a11y elements |
+| `activate` | `A11yActivate?` | Default `ENABLE` |
+| `checkA11yOpen` | `() => Promise<boolean>?` | Async check used when `activate === CHECK` |
+| `delay` / `zIndex` | optional | |
+
+## Required setup
+
+`A11ySystem` should be added after `RendererSystem` and `EventSystem`. The
+overlay is appended to the canvas's parent element.
+
+## Runtime behaviour
+
+- The overlay div is a sibling of the canvas, not a child. It tracks the
+  canvas position and scales accordingly.
+- Click on an overlay child forwards to the matching GameObject's `Event`
+  component as `touchstart` → `touchend` → `tap` in sequence.
+- Use Event + A11y on the **same** GameObject. Subscribe to events on
+  `Event`, not on `A11y`.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| No screen reader output | Verify `hint` is non-empty and `activate` is `ENABLE` |
+| Click only fires once | Don't add multiple `Event` subscriptions; reuse a single Component handler |
+| Visual misalignment | Ensure canvas's CSS `transform` doesn't differ from the overlay parent |
+
+## Minimal example
+
+```ts
+import { Event, HIT_AREA_TYPE } from '@combos-fun/plugin-renderer-event';
+import { A11y } from '@combos-fun/plugin-a11y';
+
+const button = new GameObject('start-button');
+button.addComponent(new Transform({ position: { x: 100, y: 100 }, size: { x: 200, y: 80 } }));
+button.addComponent(new Event({ hitArea: { type: HIT_AREA_TYPE.Rect, style: { width: 200, height: 80 } } }));
+button.addComponent(new A11y({ hint: 'Start game', role: 'button', interactive: true }));
+```
+
+## Verification
+
+`pnpm --filter @combos-fun/plugin-a11y run build`.

package/combos-plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "@combos-fun/plugin-a11y",
+  "pluginId": "a11y",
+  "category": "a11y",
+  "dimension": "shared",
+  "isCore": false,
+  "keywords": ["a11y", "accessibility", "aria", "screen-reader", "overlay"],
+  "agentSkill": "./agent-skill.md",
+  "requires": [
+    "@combos-fun/engine",
+    "@combos-fun/plugin-renderer",
+    "@combos-fun/plugin-renderer-event"
+  ],
+  "exports": ["A11ySystem", "A11y", "A11yActivate"]
+}

package/package.json

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