@yagejs-tools/feedback 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,319 @@
-# Temporary Holding Version
+# @yagejs-tools/feedback
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime feedback for [YAGE](https://yage.dev) games. Freeze the running game,
+comment on the whole view, on entities, or on an area, and read each comment
+back from a CLI together with its screenshot and inspector snapshot. Made for
+handing observations to a coding agent.
+
+`@yagejs-tools` scope, independently versioned — an engine release never forces
+a bump here, and vice versa.
+
+## Install
+
+```bash
+npm install -D @yagejs-tools/feedback
+```
+
+Peers: `@yagejs/core`, `@yagejs/renderer`, `@yagejs/debug`, and `vite`, all of
+which a YAGE game already has. `@yagejs/input` is an optional peer; when the
+game installs `InputPlugin`, feedback clears held input on entry and exit.
+Engine peers are `>=0.11.0 <0.12.0`. The 0.10 packages do not provide the
+inspector clock leases that comment mode uses.
+
+The package is a development tool. The Vite plugin serves feedback only from
+the dev server, and a production build contains no feedback routes or
+discovery metadata. Keep `FeedbackPlugin` behind the game's debug flag so a
+release build mounts no UI.
+
+## Usage
+
+Add the dev-server plugin to `vite.config.ts` (Vite 8):
+
+```ts
+import { defineConfig } from "vite";
+import { yageFeedback } from "@yagejs-tools/feedback/vite";
+
+export default defineConfig({ plugins: [yageFeedback()] });
+```
+
+Install the runtime plugin after `RendererPlugin` and `DebugPlugin`:
+
+```ts
+/// <reference types="vite/client" />
+import { Engine } from "@yagejs/core";
+import { FeedbackPlugin } from "@yagejs-tools/feedback";
+
+const debug = import.meta.env.DEV;
+const engine = new Engine({ debug });
+// engine.use(new RendererPlugin(...)); engine.use(new DebugPlugin());
+engine.use(
+  new FeedbackPlugin({
+    enabled: debug,
+    context: () => ({ host: "runtime", level: "forest-1" }),
+  }),
+);
+```
+
+Start Vite. Feedback runs on the same port, and the browser plugin discovers
+its API from a `<meta>` tag the Vite plugin injects. An explicit `server`
+option overrides discovery.
+
+Open **Feedback gallery** from the game controls, or visit
+`/__yage/feedback/` on the game's origin. The API is at
+`/__yage/feedback/api/`. Both paths include Vite's configured `base` and
+follow its actual port if the preferred port is occupied. Use that full API
+URL in CLI `--server` arguments, including the path.
+
+`yageFeedback({ directory: ".yage/feedback", basePath: "/__yage/feedback/" })`
+configures storage relative to Vite's root and routes relative to Vite's base.
+Add `.yage/feedback/` to your project's `.gitignore` if captures should stay local.
+Each running server must own a different storage directory. A second owner
+fails with a lock error; it never creates a different directory silently.
+Restarting Vite preserves comments and releases/reacquires the lock.
+
+The integration requires local HTTP. Feedback routes reject nonlocal clients
+even when the game dev server is exposed on the network. Closing Vite stops
+feedback; use the standalone server with the same directory to review saved
+comments afterward.
+
+## Leave a comment
+
+1. Open **Leave feedback** (F8). The game freezes and a captured image appears.
+2. Choose **Whole view**, **Entities**, or **Area**. Click an entity or use
+   the searchable entity dropdown; hold Shift to add another on the image. In Area mode, drag a rectangle.
+3. Write a comment and save. Add more comments or return to the view.
+4. Resume and capture another frame to collect more observations in the same
+   session.
+
+The entity dropdown filters by name, ID, or scene and displays 50 results per
+page. Filtering preserves selected entities; their summary stays visible below
+the dropdown.
+
+Screenshots hide the debug HUD during capture and immediately restore its
+previous visibility, including when capture fails.
+
+The server saves comments, PNGs, and inspector snapshots in the chosen
+directory. Use one server per directory. Failed uploads keep their draft for
+retry; **Discard unsaved draft** lets you leave without retrying. Discarding
+the local draft does not delete anything already stored on the server.
+
+## Review and hand off comments
+
+The gallery defaults to **Pending** (open and ingested). Filter by status,
+search text or entity names, and open **View evidence** for the original image,
+target outlines, inspector snapshot, host context, and status history.
+Cards show 24 comments per page. **Refresh** reloads saved comments and status.
+
+Select comments, then choose **Copy for Codex** or **Copy for Claude**.
+The instruction includes the skill invocation, project directory, actual API
+URL, and explicit comment IDs. Paste it into an agent session opened in that
+project. Install the `yage-feedback` skill separately in that agent first.
+If clipboard access fails, a dialog offers selectable text. Reading, selecting,
+and copying do not ingest comments. Changing the filter clears selection;
+changing pages retains it.
+
+## Read the evidence
+
+```sh
+npx yage-feedback list --status open --server http://localhost:5173/__yage/feedback/api/
+npx yage-feedback show COMMENT_ID --server http://localhost:5173/__yage/feedback/api/
+```
+
+Output is JSON. `show` includes the original comment, target, capture
+metadata, full inspector snapshot, and absolute screenshot path. The browser
+can close before the CLI reads the data. Restart the server with the same
+directory to read earlier comments. Use `--server URL` to read another local
+endpoint, including its base path.
+
+## Track agent work
+
+Reading leaves status unchanged. Use `ingest` once an agent has read the
+comment and evidence, `address` after applying changes, and `resolve` after
+verification. `reopen` returns any non-open comment to `open`.
+
+```sh
+npx yage-feedback ingest COMMENT_ID \
+  --server http://localhost:5173/__yage/feedback/api/ \
+  --revision 0 --by codex/session-name \
+  --request-id 7582a71c-ffab-4b16-b7d3-145b34fafac5
+```
+
+Use `comment.revision` from `show`. Every new action needs a new request UUID;
+retry an uncertain action with the same UUID and unchanged arguments. A retry
+never adds a second history entry. A stale revision fails so another agent's
+work cannot be overwritten. `--note TEXT` records an optional explanation.
+All transitions retain the original comment, target, screenshot, and snapshot.
+`list --status STATUS` filters open, ingested, addressed, or resolved comments.
+
+The server records actor, timestamp, status, revision, and request ID in
+`comment.history`. Comments saved before workflow tracking existed read as
+revision 0 without rewriting their files. Retrying an upload preserves
+existing workflow state.
+
+## Standalone server
+
+Without Vite, or to review a directory after the game closed:
+
+```sh
+npx yage-feedback serve --dir .yage/feedback
+```
+
+The standalone server binds `127.0.0.1:5212` and prints its API URL. Set the
+runtime plugin's `server` option to that URL when the game runs without the
+Vite plugin. `--port 0` asks the OS for an available port. `--base-path
+/review/api/` changes its API prefix; its gallery is under
+`/review/api/gallery/`. `--project PATH` sets the project directory used in
+copied instructions; it defaults to the working directory. Cross-origin
+browser requests are allowed from `http://localhost:5173` and
+`http://127.0.0.1:5173`, Vite's default origins. Supply repeatable `--origin
+URL` arguments for another origin; supplying any replaces the defaults. A
+directory lock prevents simultaneous servers. Graceful shutdown releases it.
+After a crash, check the PID recorded in `.server.lock` before removing a
+stale lock.
+
+## Plugin options
+
+```ts yage-group="options" yage-context="engine"
+/// <reference types="vite/client" />
+import { FeedbackPlugin } from "@yagejs-tools/feedback";
+
+const debug = import.meta.env.DEV;
+engine.use(
+  new FeedbackPlugin({
+    enabled: debug, // Same flag passed to new Engine({ debug }).
+    server: "http://127.0.0.1:5212",
+    context: () => ({ host: "runtime", experiment: "formation" }),
+  }),
+);
+```
+
+Set `enabled` to the application’s debug flag. Disabled feedback mounts no UI
+or keyboard listeners. The compact controls become fully visible on hover or
+focus. F8 opens feedback and F9 toggles freeze; `shortcuts: false` disables
+those keys. Shortcuts ignore editable fields and open dialogs.
+
+Override keyboard bindings in the runtime plugin:
+
+```ts yage-group="options" yage-context="engine"
+new FeedbackPlugin({
+  enabled: debug,
+  shortcuts: {
+    feedback: { code: "KeyF", shift: true },
+    freeze: { code: "KeyP", shift: true },
+    stepFrame: { code: "Period" },
+    stepTenFrames: { code: "Period", shift: true },
+  },
+});
+```
+
+Bindings use physical `KeyboardEvent.code` values, such as `KeyF`, `Space`,
+or `Backquote`. Optional `ctrl`, `alt`, `shift`, and `meta` modifiers must
+match exactly; omitted modifiers are false. Omitted actions keep F8/F9 and F10/Shift+F10.
+Set an action to `false` to disable only its shortcut, or use `shortcuts: false`
+to disable all feedback shortcuts. Buttons remain available and tooltips show each
+configured binding. Duplicate bindings are rejected. Choose combinations that
+your browser and OS do not reserve. Configured step keys stay reserved even
+when stepping is unavailable, except while typing or in a dialog.
+
+Once the game is frozen, **+1 frame** and **+10 frames** advance it and leave
+it frozen. Their default keys are F10 and Shift+F10. Stepping uses the
+inspector's configured frame delta, clears held input, and is unavailable
+while a comment dialog is open or another tool owns the clock. Return to the
+game before stepping; saved captures and pending comment evidence stay unchanged.
+
+Feedback uses the existing inspector time lease and never advances simulation
+during capture. Context must be finite, acyclic JSON and is copied with the
+capture. The same plugin can be included in a `@yagejs-tools/lab` harness's
+`plugins` array, as shown in [the demo harness](demo/lab/harness.ts).
+
+## Limits
+
+- Pause lab playback before opening feedback: lab playback owns the clock.
+- Selection uses rendered bounding boxes. Use the entity dropdown for overlapping
+  objects. Masks, displaced pixels, and exact paint order are not resolved.
+- Regions use screenshot pixels. The inspector retains entity world state
+  and camera information; feedback does not infer a world region.
+- Capture covers the canvas, not surrounding HTML. Chrome/WebGL was verified.
+- Freezing engine time does not stop external timers, network callbacks, or
+  audio. Comments display an immutable captured image.
+- The tool collects evidence and tracks its status; it does not apply fixes or
+  run an agent.
+
+Uploads can be cancelled with **Cancel save**, **Return to view**, or Escape.
+Requests time out after 30 seconds. A pending draft keeps its original capture,
+text, target, and request identity when you return to the game; reopen feedback
+to retry it. The draft lasts until saved, discarded, or the plugin is destroyed
+(including a page reload). Cancellation cannot undo a completed server write.
+
+The server validates PNG checksums and decodes the pixels before saving.
+Screenshots must be non-interlaced and contain at most 16,777,216 pixels. The
+server accepts only loopback Host headers, including CLI requests without an
+Origin header. Object-property order does not affect upload retry identity.
+
+## Contributing
+
+Everything below runs inside the YAGE monorepo checkout.
+
+Install dependencies and build:
+
+```sh
+npm install
+npx turbo run build --filter=@yagejs-tools/feedback --filter=@yagejs-tools/lab
+```
+
+Run the demo game; its Vite plugin starts feedback automatically:
+
+```sh
+npm run demo --workspace=@yagejs-tools/feedback
+```
+
+Open [the game](http://127.0.0.1:5213). Its data is in
+`packages/tools/feedback/demo/.yage/feedback`.
+
+The lab harness uses the standalone server. Start these in separate terminals:
+
+```sh
+node packages/tools/feedback/dist/cli.js serve --dir output/playwright/feedback-data --origin http://127.0.0.1:5214 --origin http://localhost:5214
+npm run lab --workspace=@yagejs-tools/feedback
+```
+
+Open [the lab](http://127.0.0.1:5214). In the lab, press **Pause** before
+**Leave feedback**.
+
+The demo also accepts `?shortcuts=custom` to try Shift+K for feedback, Shift+P
+for freeze, and Period/Shift+Period for stepping.
+
+Verify:
+
+```sh
+npx turbo run typecheck lint test build --filter=@yagejs-tools/feedback
+```
+
+For CLI lifecycle verification after saving a browser comment:
+
+```sh
+node packages/tools/feedback/checks/cli.mjs http://127.0.0.1:5213/__yage/feedback/api/
+```
+
+This creates one acceptance comment using existing captured evidence and checks
+all transitions, exact retries, stale rejection, and read-only source access.
+
+For repeatable browser checks, start the servers above and use Playwright CLI:
+
+```sh
+playwright-cli open http://127.0.0.1:5213
+playwright-cli snapshot
+playwright-cli run-code --filename packages/tools/feedback/checks/runtime.js
+playwright-cli run-code --filename packages/tools/feedback/checks/controls.js
+playwright-cli run-code --filename packages/tools/feedback/checks/shortcuts.js
+playwright-cli goto http://127.0.0.1:5213/__yage/feedback/
+playwright-cli run-code --filename packages/tools/feedback/checks/gallery.js
+playwright-cli goto "http://127.0.0.1:5213/?debug=false"
+playwright-cli run-code --filename packages/tools/feedback/checks/disabled.js
+playwright-cli goto http://127.0.0.1:5214
+playwright-cli snapshot
+playwright-cli run-code --filename packages/tools/feedback/checks/lab.js
+```
+
+The scripts create real comments and save screenshots under
+`output/playwright/`.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node