Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(witness): document the recorder, the compiler and what it refuses to keep

nirholasc48eb2943cba
diff --git a/docs/feedback.md b/docs/feedback.md
index 2f1660d44..4e93b34fa 100644
--- a/docs/feedback.md
+++ b/docs/feedback.md
@@ -43,10 +43,11 @@ the top of [`api/_lib/feedback/triage.js`](../api/_lib/feedback/triage.js).
## How a report travels
1. **Capture.** [`src/feedback-companion.js`](../src/feedback-companion.js)
- installs two bounded ring buffers at module load (window errors and
- unhandled rejections in one, failed fetches and failed resource loads in the
- other). No timers, no network, nothing sent anywhere: this costs nothing
- until something goes wrong.
+ starts [`@three-ws/witness`](./witness.md) at module load, before the
+ companion finishes mounting. It keeps a bounded semantic trace: the sequence
+ of intents plus the failures, with a stable selector for every element
+ touched and no typed value ever held. No timers, no network, nothing sent
+ anywhere: this costs nothing until something goes wrong.
2. **The ask.** On a real failure the companion offers, once per route per
session, never in a background tab, and never again on a route where the
visitor said "not now". The chrome control next to the narration and trails
@@ -64,8 +65,29 @@ the top of [`api/_lib/feedback/triage.js`](../api/_lib/feedback/triage.js).
a fact and a model that decides it does not matter should not be able to
bury it.
5. **Read.** `/feedback` groups reports into one row per distinct problem,
- loudest first, showing how many people hit each one. A maintainer accepts,
- fixes, or dismisses.
+ loudest first, showing how many people hit each one. A cluster with a
+ recorded session carries a **Copy test** button. A maintainer accepts, fixes,
+ or dismisses.
+
+## From report to failing test
+
+Every report also carries the **session** the visitor recorded: the sequence of
+things they did, with a stable selector synthesized for each one, and the failure
+at the end. That trace compiles into a Playwright spec which asserts the failure
+is gone, so it is red while the bug exists and green once it is fixed.
+
+```bash
+npm run feedback:repro -- --list # reports with a replayable session
+npm run feedback:repro -- <id> --run # compile it and watch it fail
+```
+
+The reconstruction step, which is where most bug reports die, is done before a
+maintainer opens the queue. Full detail, including the selector ladder and the
+privacy rules: [Witness](./witness.md).
+
+Nothing about this changes the boundary above. The trace is machine-written data
+validated by shape at the API edge, the compiler is a pure function with no
+network and no filesystem, and the output is a file a human chooses to run.
## Severity
@@ -110,14 +132,20 @@ curl -X POST https://three.ws/api/feedback/report \
"viewport": "390x844@3",
"locale": "en-GB",
"console_errors": ["TypeError: exportGLB is not a function (studio.js:412)"],
- "failed_requests": ["POST /api/export -> 500"]
+ "failed_requests": ["POST /api/export -> 500"],
+ "trace": { "version": 1, "environment": {}, "events": [{ "type": "goto", "detail": "/avatar-studio" }] }
}'
```
```json
-{ "ok": true, "id": "8c2f...", "received_at": "2026-08-28T14:02:11.884Z" }
+{ "ok": true, "id": "8c2f...", "received_at": "2026-08-28T14:02:11.884Z", "replayable": true }
```
+`trace` is optional and machine-written by [`@three-ws/witness`](./witness.md).
+It is validated by shape at this boundary (known event types only, 80 events,
+every string capped), because the endpoint is open to anyone. `replayable` says
+whether a usable trace survived that validation.
+
Rate limited to 20 reports per hour per account, browser key, or IP. Every text
field is capped server-side and the two signal lists keep their first five
entries.
@@ -135,14 +163,26 @@ entries.
Pass `id` instead of `cluster` to move a single report.
+### `GET /api/feedback/repro?id=<report id>` (admin)
+
+The report as a runnable Playwright spec. `&format=json` returns the source
+alongside the narrated steps and the replay confidence; `&base=<origin>` points
+the replay somewhere other than production. See [Witness](./witness.md).
+
## What this deliberately does not do
It does not write code, open pull requests, change configuration, or deploy.
Those would each be a new decision with its own gate, and none of them should
-ever be triggered by text typed into a box by an anonymous visitor. If a
-proposal layer is ever built on top of this queue, the input to it must be the
-structured triage record a person has already accepted, never the raw report,
-and its output must be a pull request a person merges.
+ever be triggered by text typed into a box by an anonymous visitor.
+
+What it does instead is remove the reason people wanted that: the expensive part
+of acting on a bug report was never writing the fix, it was reproducing the bug.
+A compiled repro hands that over without handing over any authority. An agent
+with `feedback:read` can pull a reproduction over MCP, run it, change code in a
+branch, and run it again to prove the fix, and the pull request still needs a
+human to merge it. If a proposal layer is ever built here, that is its shape: the
+input is the structured triage record a person already accepted plus a spec that
+reproduces the failure, never the raw report, and the output is a pull request.
## Related
diff --git a/docs/witness.md b/docs/witness.md
new file mode 100644
index 000000000..6bdc4dc55
--- /dev/null
+++ b/docs/witness.md
@@ -0,0 +1,186 @@
+# Witness: bug reports that arrive as failing tests
+
+A bug report is a description of an experiment somebody else has to reconstruct.
+The reconstruction is the expensive part, it is where most reports die, and it is
+the part a machine can do.
+
+`@three-ws/witness` records what a person actually did, and compiles it into a
+Playwright spec that is **red while the bug exists and green once it is fixed**.
+
+- Package: [`packages/witness/`](../packages/witness) (`@three-ws/witness`, Apache-2.0, no dependencies)
+- On three.ws: the corner companion attaches a trace to every report, and
+ [`/feedback`](./feedback.md) hands you the compiled test with one click.
+- Standalone: it works on any site, with or without the rest of three.ws.
+
+## The idea in one screen
+
+```
+The visitor's session The compiled spec
+───────────────────── ─────────────────
+goto /avatar-studio await page.goto('/avatar-studio');
+click the button "Export" await page.getByTestId('export').click();
+fill "Model name" (11 chars) await page.getByLabel('Model name').fill('xxxxxxxxxxx');
+click the button "Download" await page.getByRole('button', { name: 'Download' }).click();
+xhr POST /api/export -> 500 expect(failedRequests).toEqual([]); <- RED
+error TypeError: exportGLB is not a fn expect(pageErrors).toEqual([]); <- RED
+```
+
+The last two lines are the whole design. The spec asserts the failure is **gone**,
+not that it happened. A recorder that emitted `expect(status).toBe(500)` would
+write a test that passes while the site is broken and fails once it is fixed,
+which is worse than no test at all.
+
+## Why not session replay
+
+Session replay records the DOM mutation stream. It is megabytes per session, it
+costs real money to keep, and what it gives you is a video. You still have to
+reproduce the bug yourself afterwards.
+
+Witness records intent, at about two kilobytes per session. Small enough to leave
+on permanently, and that is the point: **the trace already exists at the moment
+somebody decides to complain.** Nobody can reproduce a bug on request; everybody
+has just done it.
+
+| | Session replay | Witness |
+| --- | --- | --- |
+| Records | DOM mutations, pixels | Intents, failures, stable selectors |
+| Size | megabytes | ~2 KB |
+| Output | a video to watch | a test to run |
+| Answers "is it fixed?" | you rewatch and judge | the test goes green |
+| Typed values | usually captured, then masked | never held |
+
+## Using it on three.ws
+
+Nothing to do. Every page runs the corner companion, which starts the recorder
+before the page finishes booting. When something breaks the companion asks what
+you were doing, and the session rides along with the answer.
+
+At [`/feedback`](https://three.ws/feedback) a cluster with a recorded session
+shows a **Recorded session** card: the replay confidence, the narrated steps, and
+**Show test** / **Copy test** / **Download**.
+
+From the shell:
+
+```bash
+npm run feedback:repro -- --list # reports with a replayable session
+npm run feedback:repro -- <report-id> # writes tests/repros/<id>.spec.js
+npm run feedback:repro -- <report-id> --run # writes it, then runs it
+npm run feedback:repro -- <id> --base http://localhost:3000 # replay locally
+```
+
+Repros live in `tests/repros/` with [their own Playwright
+config](../tests/repros/playwright.config.mjs), deliberately outside the
+`tests/e2e` suite: a reproduction is red by definition until its bug is fixed, so
+folding them into the default run would mean `npm test` fails for every open
+report.
+
+```bash
+npx playwright test -c tests/repros/playwright.config.mjs
+```
+
+Over HTTP (admin session required):
+
+```bash
+curl -s 'https://three.ws/api/feedback/repro?id=<id>' -H "cookie: $SESSION" \
+ > tests/repros/export-does-nothing.spec.js
+```
+
+Add `&format=json` for the source plus the narrated steps and confidence, which
+is what the queue page renders.
+
+And from an agent over MCP (`/api/mcp`, scope `feedback:read`, admin account):
+
+| Tool | What it does |
+| --- | --- |
+| `list_feedback` | The queue, one row per problem, flagging which ones are replayable |
+| `get_feedback_repro` | Compiles one report into a spec, with steps and confidence |
+
+Both are read-only. An agent can reproduce a reported bug and verify its own fix
+against the real session, and it still cannot change a status or touch the
+product: see the boundary in [feedback.md](./feedback.md#the-boundary-that-makes-this-safe).
+
+## Replay confidence
+
+Every trace carries a score equal to its **weakest** selector, because one
+fragile locator breaks the whole spec:
+
+| Score | Meaning |
+| --- | --- |
+| 80-100 | Every step is anchored to a test id, an id, an aria-label, or a role and name. |
+| 60-79 | A step relies on visible text, which moves when copy changes. |
+| 40-59 | A step is anchored to a class name, which a restyle can break. |
+| 0-39 | A step falls back to a structural path and will not survive a refactor. |
+
+That number is honest feedback about your own markup, and it is actionable: add
+`data-testid` to the primary action on a page and every future report from that
+page compiles into a sturdier test. The full ladder is in the
+[package README](../packages/witness/README.md#the-selector-ladder).
+
+## Privacy
+
+Enforced at capture time, not by scrubbing afterwards. A recorder that captures
+everything and cleans up later has already put the secret in memory.
+
+- **Typed values are never held.** A filled field records `text:11`: eleven
+ characters of ordinary text. The characters do not exist in the trace.
+- **Password, hidden, email, tel and date inputs record nothing**, and neither
+ does any field whose name, id, `autocomplete`, label, or placeholder suggests
+ it holds something personal.
+- **URLs are stripped at capture**: userinfo and the hash go entirely, credential
+ parameter values are redacted, parameter names are kept.
+- **Free text is scanned** for emails, JWTs, API keys, card numbers, wallet
+ addresses, and long base58 runs.
+- **`data-witness="off"`** excludes a subtree completely. three.ws marks its own
+ feedback panel with it, because the act of reporting a bug is not part of the
+ bug.
+
+The visitor can see all of this before they send: the panel shows the exact step
+count and expands to the full list, above the line "Nothing you typed into a
+field is recorded, only how much."
+
+## When it cannot help, it says so
+
+If a session recorded no exception and no failed request, the visitor judged the
+*result* wrong, and no recorder can see that. The compiler does not invent an
+assertion to look useful:
+
+```js
+// The browser recorded no exception or failed request for this report:
+// the visitor judged the RESULT wrong, which no recorder can see.
+// Replace this with the assertion that states what should have happened.
+expect(pageErrors, 'no page errors during the reported flow').toEqual([]);
+test.fail(true, 'Add the assertion this report is really about.');
+```
+
+You get the reproduction steps for free and write the one line only a human can.
+
+## Using it on your own site
+
+```bash
+npm install @three-ws/witness
+```
+
+```js
+import { witness } from '@three-ws/witness';
+witness.start();
+witness.onFailure(() => openYourFeedbackForm());
+
+// when they submit:
+sendToYourBackend({ note, trace: witness.trace() });
+```
+
+```js
+import { compileToPlaywright } from '@three-ws/witness/compile';
+const { source, filename, confidence } = compileToPlaywright(trace, { title: note });
+```
+
+The recorder is browser-only; `compile` is pure and runs in Node, which is what
+lets one trace produce the maintainer's English steps in a dashboard and the
+engineer's spec file on disk. Full API in the
+[package README](../packages/witness/README.md#api).
+
+## Related
+
+- [Feedback](./feedback.md): the loop this is the second half of, and the
+ untrusted-input boundary that governs all of it.
+- [Notifications](./notifications.md): the same companion, delivering the other way.