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.
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/(@three-ws/witness, Apache-2.0, no dependencies) - On three.ws: the corner companion attaches a trace to every report, and
/feedbackhands 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 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:
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, 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.
npx playwright test -c tests/repros/playwright.config.mjs
Over HTTP (admin session required):
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.
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.
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:
// 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
npm install @three-ws/witness
import { witness } from '@three-ws/witness';
witness.start();
witness.onFailure(() => openYourFeedbackForm());
// when they submit:
sendToYourBackend({ note, trace: witness.trace() });
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.
Related
- Feedback: the loop this is the second half of, and the untrusted-input boundary that governs all of it.
- Notifications: the same companion, delivering the other way.