@homie-rocks/studio 0.48.4 → 0.50.0

package/guides/playtest/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: playtest
+description: Playtest a studio's app against its owner's Codex needs, or its game the way Homie holds its own games to a bar — real browsers on a computer and a phone held both ways, the first ten seconds timed, the look measured (black or flat frames, contrast, detail), how much of the screen the UI covers, the game's real sound captured and measured, a round played with one person trying and one doing nothing, the owner control tests and two strangers finishing a round — then a blind review by a fresh reviewer that never saw the code, and a ranked list of what is weak. Use when someone asks to playtest, test, review, critique or judge a game, asks what is weak or what to fix next, before calling a game finished or publishing it, and after every change that should make it better.
+---
+
+## Apps: judge the place against its owner’s words
+
+For an app, read `apps/<id>/CODEX.md` first. This is the app branch of the same playtest: no rounds, scores or invented entertainment. Run build and `check <id> --shots .checks` (including its Codex needs), then open the wall and phone in real Chrome. The game script below measures games; do not run a round instrument on an app.
+
+Walk in as the owner. Read **Their words** aloud to yourself, then inspect the wall capture: is the pictured place there, do recognisable things move/fill/arrive/light up as requested, and can someone across the room understand the work? A generic board of boxes fails a living-scene request even if every label is correct. Check an empty and a busy state without passing invented records off as real customers. Inspect state before and after a real action, not only a pretty still.
+
+Now arrive as a new customer on a phone: find the offer and correct price, book/give/log/sign up, understand success or failure, save the return link, reload and follow your own record. Use a second phone to check the link follows the same thing. As staff, sign in and perform the real work; as a public visitor, verify privileged writes are refused. Close all browsers and return: the work must remain. A simulated paid event is not a real charge; record payment connection gaps honestly.
+
+For every need, write `met / partly / not`, the exact capture or flow that demonstrates it, and what remains. Check phone portrait/landscape, wall readability, kiosk reset if present, native controls, keyboard focus and reduced motion. Do not infer usability from a build or a shared counter. Inspect the saved captures yourself; automated selector assertions cannot judge the dreamed scene. Copy the verdict and evidence into the Codex and redraw its page. Keep unfinished needs visibly unfinished. No approval question is needed for local checks or your visual review.
+
+A local review is labelled local, not independent. If a fresh reviewer was requested, give that reviewer the owner's original request, the Codex and real captures/flow addresses; ask them to judge as owner and customer, need by need. When comparing several businesses, they must read as different places with different work, not a common template recoloured. If one fails, identify what the builder read or skipped, repair that making path, and build/test again before saying done.
+
+# Playtest a game
+
+The question is never "does it run". It is: **would a stranger who pressed Play stay for a whole
+round, and come back?** Instruments measure what can be measured; a fresh reviewer who never saw
+the code answers the rest. A builder never grades its own work.
+
+One script: `scripts/playtest.mjs` in this skill's folder (Claude Code:
+`node "${CLAUDE_PLUGIN_ROOT}/skills/playtest/scripts/playtest.mjs" <command>`), run from inside the
+studio. It needs Node 22, Chrome and the studio's `@homie-rocks/studio` (for puppeteer-core and its
+checks). It opens at most two browsers at a time, all muted: nothing plays out loud.
+
+For rules games, build first: the guard, strict types and deterministic play check must pass
+before Chrome opens. Both online browsers are replicas of a server host; killing the first
+browser tests continuity, not host election. Use the real predicted pose in the probe, never
+fake movement or scores. Test local movement with 150 ms delay and also verify hits, scores,
+turns and results agree after authority arrives. A turn game, quiz or live app needs its actual
+buttons and workflow exercised: movement-only rows do not prove it works, and an app has no
+required game round. Use the app check for shared actions and reconnect. Report inapplicable
+rows honestly, and add a manual two-browser trial of the requested mechanic.
+
+## 1. Run the site and the instruments
+
+Start the site as a background task that outlives the command (Claude Code: the Bash tool's
+`run_in_background`), wait until the play page answers, then:
+
+```sh
+npm run dev                                     # background: http://127.0.0.1:8787 (another port: npx --no-install homie-studio dev --port <n>)
+node <playtest.mjs> run <game id> --url http://127.0.0.1:8787
+```
+
+It takes five to ten minutes; poll its output, never end your turn while it runs, and do not rebuild
+while it runs (a rebuild under `npm run dev` can stop the dev server). `--only first,look,ui,sound`
+runs some rows; `--seconds 30` plays longer. The live site works too (`--url` the studio's address).
+Stop the site afterwards with `npx --no-install homie-studio dev --stop`.
+
+| row | what it does | fails when |
+| --- | --- | --- |
+| `first <device>` | opens the play page like a stranger on a computer, a phone, a phone on its side, and times four separate things: a seat, the page's first paint (the loading card, not the game), the loading cover lifting, and the first picture of the game itself (cover gone, the game's own frames advancing); frames per second; the GPU | no seat, a cover that never lifts, or no picture of the game in 10 s |
+| `move <device>` | waits for a live round and a body that is the player's, then presses right and times the body moving; when nothing moves it presses left too and reports both, with the position, round phase and time left at each press | the body answers after 1.5 s, or neither way moves it in a live round. WARN when only the opposite way moved (a wall on that side looks like this). BLOCKED when no press fit inside a live round with a free body |
+| `look <device>` | plays like a person (holds a direction most of a second, sometimes the action, changes its mind) and shoots the screen: brightness, contrast, colour, visible detail, black or one-colour frames, holes where nothing drew, frames that did not change | a black or one-colour frame, pure-black holes; WARN for dark, flat, featureless or still frames |
+| `ui <phone>` | waits for active play, holds the thumb on the stick, hides the world, paints the page black then white, and counts what stays: the share of the screen the DOM UI covers and what is opaque in the middle third. Both frames are saved with the game's state at each | over 12% covered, or anything opaque in the middle, during active play. N/A when the screen was the results card, a spectator view, the loading cover or a browser cut off from its room (measured, labelled, not judged by that bar). BLOCKED when the game changed state between the two frames. WARN when it would pass and a DOM HUD element sits under one of the play page's own controls (the room button, the server or chat pill, the banner): the row names the element and the control |
+| `sound` | copies what the game sends to its speaker while it is played (no autoplay flag: the real first-touch rule); loudness overall and through a phone speaker, true peak, clipping, gaps, whether each action press answers with a sound, whether music started | silence, clipping; WARN for quiet, gaps, actions without sound, what a phone loses |
+| `play` | a computer plays (direction holds and the game's primary action) and a phone does nothing, in the same public room, for a round that starts after both are in: places, scores, round length against `game.json`, lead changes, and which inputs the script really pressed | no round finishes; WARN when doing nothing scores as well as playing, everyone ties, or a bot is far ahead (a measured gap in one scripted round, never "people cannot win") |
+| `controls` | the owner tests from `homie-studio port check`: hold a direction 5 s (one straight line, the camera's yaw moves under 10°), alternate directions 10 s (every press goes the pressed way), real touch on Android Chrome (and iPhone WebKit when Playwright's WebKit is installed; otherwise that row says skip), the first browser closing (server continuity; host election only for older games), a late joiner, the big screen, audio unlock, errors | any of them (`port` skill: `references/CHECKS.md` says what each failure usually means) |
+| `round` | `homie-studio check`: two fresh browsers press Play, meet in one room and both see a round finish with both of them in the results; reconnects are reported beside completion | they do not. WARN when the round finished and a browser reconnected on the way |
+| `errors` | uncaught errors and failed requests seen along the way | any uncaught error |
+
+**BLOCKED is never PASS.** A browser rendering at a few frames a second (a software renderer, a
+machine under heavy load) makes any game look stuck: the rows say BLOCKED and judge nothing. Run
+again on a quieter machine. "Could not test" and "tested and fine" must never sound the same.
+The same goes for the instrument's own faults: a screenshot decoder that does not finish in 20 s
+is stopped, that device's rows say BLOCKED, the browser is closed and the run exits non-zero; a
+site address this computer's Node.js cannot look up (a browser may still open it) stops the run as
+BLOCKED, "network preflight failed, before any page or game was opened" (the words `check`, `perf`
+and `port check` use for it too), and offers the local site. **N/A** means the row did not apply to what
+was on screen. One scripted run is one run: report a gap as measured once, and repeat before
+concluding.
+
+### What the game tells the instruments
+
+Every press and every picture is recorded with the game's state, read from its port probe
+(`exposePort`, the `port` skill) and the play page: round phase and time left, whether the body is
+the player's to steer (`busy`), where it is. A game with no probe still runs, and its rows say the
+phase was unknown. Three optional things make the rows sharper; none is required:
+
+- In `exposePort(net, { extra: { ... } })`: `alive: () => boolean` (false: spectating until the
+  next round), `mode: () => string` (the control mode on screen), `loadout: () => string` (what
+  the player holds, when it changes which controls show), `touchHeld: () => boolean`, and
+  `drawCalls` / `triangles` (`renderer.info.render.calls` / `.triangles`: the look row then
+  reports measured runtime scene cost, which is not the asset inventory's estimate).
+- In `game.json`, the primary action, so a shooter is played by firing and not by the space bar:
+
+  ```json
+  "playtest": { "primary": { "label": "fire",
+    "computer": { "mouse": "left" },
+    "phone": { "selector": "[data-action=fire]" } } }
+  ```
+
+  `computer` is `{ "key": "<KeyboardEvent.code>" }` or `{ "mouse": "left|right|middle", "at": [x, y] }`;
+  `phone` is `{ "selector": "<css, in the game's frame>" }` or `{ "region": [x, y, w, h] }`
+  (fractions of the screen). Undeclared, the script presses the space bar and taps a fixed spot,
+  says that was a guess, and qualifies anything it concludes from the scores. It does not aim.
+- In `game.json`, `"scoring": "together"`: every result row carries the room's one shared total,
+  so the play row marks the active-against-idle comparison not applicable.
+
+The UI row measures DOM coverage only. A HUD, labels or hints drawn inside the canvas are hidden
+with the world and are not checked for coverage or overlap; REPORT.md says so beside the result.
+
+The UI row also lays the game's visible DOM HUD against the play page's own controls, which the
+page draws over the game's frame and reports as `window.__shell.rects` (the game reads the same as
+`net.shell` / `net.on('shell')`). A HUD element under a control that stays is a WARN with both
+named; under the "N playing" chip, which fades, it is a note. Fix it by laying the HUD out around
+`net.shell`'s rectangles, or by moving the page's controls (`game.json` `screen.share`,
+`screen.chat`). A page that reports no layout (an older studio) is said to be unchecked.
+
+A reading taken while the browser was not in its room is labelled, never judged as play: the
+helper's link (`window.__homieNet.link`, and `window.__shell.link.state`) says `reconnecting`,
+`alone` (the room never answered; an older browser-hosted game may play locally), `offline` or `closed`, and a
+press, a picture or a UI frame sampled then is BLOCKED or N/A with "CUT OFF from its room" in its
+state. The round row says a browser "was seen cut off" beside completion.
+
+The run writes `.playtest/<game>/<time>/` in the studio (added to `.gitignore`): `REPORT.md`,
+`report.json`, contact sheets (`sheet-desk.png`, `sheet-phone.png`, `sheet-phone-landscape.png`),
+every screenshot (the UI row's pair as `*-ui-on-black.png` and `*-ui-on-white.png`), `sound-capture.wav` and its spectrogram, and the owner-test receipts.
+**Open the contact sheets and look at every picture before believing any number.**
+
+## 2. The blind review
+
+For a rules game with maxSpeed 0 on every player kind, the toolkit marks the
+movement probe stationary. First-move rows say N/A and directional owner tests
+say not applicable, never PASS. Exercise its actual choices/taps/turns in two
+browsers and measure local feedback separately from authoritative acceptance.
+Do not add movement, fake pose samples or a board-direction probe to silence a check.
+A hold entirely inside a hiding countdown, death or stun is blocked evidence.
+Wait for an active, steerable phase and repeat the real controls in both browsers;
+record that directed result beside the generic row. Keep the mechanic and honest
+busy/alive probes; never remove a freeze or disguise it to turn a row green.
+
+```sh
+node <playtest.mjs> review .playtest/<game>/<time>
+```
+
+It writes `REVIEW.md` in that folder: a brief for a FRESH reviewer, with the pictures, the numbers and
+a rubric.
+
+**An outside review is optional, only when requested.** Finish local checks and your own visual review without an extra question. When an outside review is requested, it hands screenshots outside this session: use the authorization already given, or ask once if the destination was not specified.
+The command prints `approval`: one self-contained question naming every file it sends (REVIEW.md,
+report.json and the listed pictures), the report folder they come from, and the destination (name
+it with `--to "<the reviewer>"`: a subagent in this session, or an external command such as a
+second coding agent). For a requested outside review without prior destination consent, ask that question once. One yes covers that report
+folder and that reviewer; another folder or reviewer is a new question. `review-request.json` in
+the folder keeps the same list. A host that reviews what an agent sends may still refuse the
+transfer: that is the host's decision. Do not rephrase and retry it, and do not send the pictures
+another way. Then one of:
+
+- `node <playtest.mjs> review <folder> --local` writes `REVIEW-LOCAL.md`: the same rubric for
+  this session to score the contact sheets itself. Nothing leaves the session. It is the builder
+  grading its own build, so it is labelled **not independent** everywhere, and you say so in the
+  first sentence when you report it.
+  Read that brief and every listed picture, follow its JSON rubric and write
+  `VERDICT.json` with `"review": "local"` in this exact run folder BEFORE calling
+  `reviewed --kind local`. The `reviewed` command records a verdict; it does not create one.
+  Rubric parts use 0–10; the overall JSON `score` and `--score` use **0–100**
+  (for example, an overall seven out of ten is `--score 70`, not `7`).
+- Record what happened, always: `node <playtest.mjs> reviewed <folder> --kind independent --by
+  "<who>"`, `--kind local --reason "<why>"`, or `--kind none --reason "<why>"`. REPORT.md and
+  `report <folder>` then say which review this run had. With no record, or `none`, the review line
+  is BLOCKED: a missing review never reads as a passed one. Hand its WHOLE TEXT, unchanged, to a reviewer that has not seen the code, the plan or your
+summary (Claude Code: the Agent tool with the file's full contents as the prompt, never just its path
+or your summary of it; Codex: a new session). Add nothing about what you built or changed. It plays the game itself, scores it
+0-100 in eight parts, and returns gaps ranked by impact, each with evidence it saw and one concrete
+fix. Its verdict outranks yours. Put it in the run folder as `VERDICT.json`.
+
+Comparing against other games (the person's references, the studio's last version, a game they
+admire): give the reviewer frames of each under shuffled labels, scored before the labels are revealed.
+A reference is a bar ("is it as good as that"), never a template ("make it look like that").
+
+A game with models: give the reviewer the style board, the golden images and the lineup pictures
+(`homie-studio assets lineup <id>`, in `.studio/art/<id>/`) beside the frames, and add one question: "does every
+frame look like ONE game?" (1-10, naming outliers). Record it with `homie-studio assets review <id> --score <n>
+--outliers <ids>`.
+
+## 3. Say what is weak
+
+Lead with the numbers and the review, most important first: what fails, then what the reviewer would
+fix first. Group findings by cause before proposing work (five complaints about flat shapes are one
+missing lighting model, not five jobs). Name the one change that would matter most. Then, if the
+person wants, fix it and run the same instruments again; a change that does not measure better than
+the version before it is a regression, not progress. When the weak thing is speed (a low frame rate in
+`first`, a slow first ten seconds, a phone that struggles), the `perf` skill measures it properly: frame
+times and CPU per frame for player browsers (server tick work is separate), alternating runs,
+and only changes that beat the noise.
+When the weak thing is how a move feels (a hit that does not land, a floaty jump), the `lab` skill compares the
+change with the last commit frame by frame, with the person.
+
+`references/METHOD.md` has the method behind the rows: playing like a person, the five numbers a
+round owes you, the scenarios, seats with different strategies, the do-nothing test, the ten-second
+test, and the traps that make an instrument lie.
+
+## Never
+
+- Never call a game good, fixed or finished from the code, a build that passed, or your own look at it.
+- Never report a local review as a blind one, and never read a BLOCKED or N/A row, or a missing review, as a pass.
+- Never turn one scripted round into a rule ("people cannot win", "input does not matter"): say what was measured, and run it again.
+- Never call the builder's local verdict an independent review: an independent reviewer is fresh every time.
+- Never script a player to make a number look good; the instruments play like a person on purpose.
+- Never leave a room open on a live site: the playtest's browsers leave when it ends; do not start
+  more than two browsers of your own beside it.

package/guides/playtest/references/METHOD.md

@@ -0,0 +1,124 @@
+# The method behind the rows
+
+How a game gets judged honestly, and the ways a test lies. Everything here was measured on games that
+passed their tests and still failed people.
+
+## Play it like a person
+
+Hold a direction for most of a second, not one frame. Press the thing whose label sounds fun. Try the
+control you would try first if nobody had told you anything. A script that presses every button in
+order is a conformance test, and conformance is not what is wrong with a boring game.
+
+## The five numbers a round owes you
+
+| | say | why |
+| --- | --- | --- |
+| how long | seconds from start to finish, against the clock the game set | a 150-second round that ends at 40 means nobody has seen most of the game |
+| how it ended | who won and by how much | if you cannot tell, a stranger cannot either |
+| the tense moment | one sentence about the best five seconds, or "there wasn't one" | the answer that unsticks a stalled game |
+| what did nothing | any control that produced no visible change | a dead control is the first thing people notice |
+| what you wanted | the one thing you reached for and could not do | the next change |
+
+Add **lead changes** (the number that separates a race from a procession) and **whether doing nothing
+scores as well as playing** (the `play` row measures both humans).
+
+## Different strategies in different seats
+
+Seats that all play the same way can only prove the game runs. Give simulated seats different
+standing strategies, one per side of the decision the game claims to be about: the greedy one that
+takes the risk the design says should pay, the safe one, the one that goes near other players on
+purpose, the middle. Then read which one scored zero. On one game whose whole idea was "carrying more
+makes you a target", the greedy runner finished on 0, 0 and 0 in three rounds because at a full carry
+it was slower than the hunter and could never escape: the exciting strategy was arithmetic, and the
+game everyone described was never actually played. No screenshot and no reading of the code found it;
+three rounds with four strategies did, in two minutes.
+
+## The do-nothing test
+
+Write it first: a player who stops touching anything, at every place a player plausibly stops, for
+longer than anyone's patience. The game must come to get them (a nudge, a timer, the round moving on),
+never freeze, never go black, never soft-lock the room. Continuous worlds must also be tuned in real
+seconds: a decay tuned on a fast test clock empties a real room in a minute. Simulate a long idle
+stretch and read the state before and after.
+
+## Every scenario before "finished"
+
+1. One person alone, with bots, on a computer.
+2. One person on a phone, portrait and landscape (a game that needs landscape says so and survives the
+   turn).
+3. Two strangers who pressed Play at different times, including one who arrives mid-round and takes a
+   bot's place (and its score: a joiner inherits the body, so only a round that starts after both are in
+   says how they played).
+4. The host leaving mid-round: someone else continues the same round, clock where it was.
+5. The big screen (`/<id>/tv`): a spectator with no body, a join QR, the game moving.
+6. Nobody touching anything.
+
+Say which you tried. "We could not test it" and "we tested it and it was fine" must never sound alike.
+
+## The ten-second test
+
+Ten seconds of silent video, no context, on a phone someone is scrolling past: do they stop? Every
+change should leave one moment worth clipping (a knockout that reads from across a room, a comeback you
+can see coming, something that happens once a round and is unmistakable). A change that produced
+nothing you would cut fifteen seconds around produced polish; polish compounds slowly and nobody shares
+it. Take a swing (a hazard, a rule that changes the last ten seconds) rather than tuning a number.
+Readable at a distance: whose is that, what just happened, who is winning. Punctuate: silence, then a
+hit. A thing that happens constantly is wallpaper; once a round it is an event.
+
+## Judging, not building
+
+- **The builder never grades its own work.** A reviewer gets the goal, the bar and the running game,
+  never the builder's reasons.
+- **Measure, don't assert.** "I differenced the two frames: nothing moved more than 8 of 255" ends an
+  argument that prose cannot.
+- **Two instruments on the same build.** A reviewer given only pictures grades the picture: one scored
+  a game 34/100 for a hunted player drawn at 1.14:1 contrast against the searchlight meant to mark
+  him, while a play measurement of the same build found the round always ended at 40 s of 150 and the
+  risky strategy scored zero. Neither could see what the other saw. When they disagree, the fight
+  outranks the frame.
+- **The whole frame and a real round, regularly.** A reviewer shown a crop can only ask about the crop:
+  thirty-five changes in a row once went into one decorative prop, each winning its own comparison,
+  while the game as a whole did not improve.
+- **Judge the set.** Twenty screens that each passed review were one layout repeated fourteen times.
+  Put the whole set in front of one reviewer: squint, how many distinct shapes are there?
+- **A reference is a bar, not a template.** Ask "is it as good as that", never "is it shaped like that".
+- **Group findings by cause** before assigning work; five findings, one cause, one fix in the shared layer.
+- **A finding that names a relation has two sides**: "the brightest thing is not a player" can be fixed
+  by darkening the floor or brightening the player; move one side on purpose and check the other.
+- **Stop on a regression.** A change that is not clearly better than the one before is worse. Scores
+  like 48, 54, 58, 50, 42 mean the peak was 58: go back to it.
+
+## Measured bars
+
+| what | bar |
+| --- | --- |
+| seated and moving | under 10 s from pressing Play, first press moves you within about a second |
+| hold a direction 5 s | one straight line the pressed way on screen, camera yaw change under 10° |
+| alternate directions 10 s | every press goes the pressed way within 600 ms |
+| UI during play | at most about 12% of the screen, nothing opaque in the middle third |
+| look | no black or one-colour frame; detail at several scales (edge share of a finished-looking frame is several times a placeholder's) |
+| sound | starts on the first touch; every action answers; -16 to -12 LUFS while played; nothing clips; little lost on a phone |
+| rounds | two strangers meet in one room and both see a round finish; a killed host hands over in 5 s; a late joiner takes a bot's place |
+
+## How instruments lie
+
+- **A software renderer fakes a stuck game.** Headless Chrome without the GPU draws a WebGL game at 1-2
+  fps; count animation frames first and say BLOCKED under ~20 fps. With the GPU flags a headless shot
+  matches the real screen within a fraction of a luma point.
+- **Reading a WebGL canvas from a script returns black** unless it is read inside a late animation frame;
+  use a screenshot of the page (the compositor's picture) instead.
+- **A full-page screenshot stretches the viewport**, so phone-landscape media queries stop matching; take
+  the viewport only.
+- **Emulated phones pass while real phones fail.** Real touch on iPhone Safari differs (coalesced
+  moves, passive listeners, pointer ids, 120 Hz); the iOS Simulator is the closest thing to an iPhone
+  on a Mac (`xcrun simctl openurl booted <url>`, mouse drags become real touches). Say when a result
+  is emulation only.
+- **A delivered press is not a correct press.** Only the body's movement on screen proves direction.
+- **Gate on the thing itself.** "A sound file plays" and "a texture is bound", not a number a hiss and a
+  flat cube would pass. Ask what the cheapest thing that passes the check would be.
+- **A still is not the game.** A title card or the moment before a round starts is a picture of
+  nothing happening; shoot while it is being played.
+- **Another run can replace what you are judging.** Note the build you judged (a digest, a commit) before
+  and after.
+- A reviewer that shares your working folder can "tidy" your half-written file: commit before you hand
+  work to one.

package/guides/playtest/references/REVIEWER.md

@@ -0,0 +1,78 @@
+# Blind review: {{GAME}}
+
+You are reviewing a multiplayer web game you did not make. You have not seen its code, its plan or its
+maker's notes, and you must not read them: judge only what a player gets. You are demanding and fair,
+you have played the best browser party games, and your job is to find what would make a stranger
+leave, not to encourage the maker.
+
+The game: {{URL}} (strangers who press Play land in the same public room; bots fill empty seats; rounds
+end and restart by themselves). The playtest instruments already ran; their folder is `{{FOLDER}}`.
+
+## Look at these yourself, every one, before you read any number
+
+{{PICTURES}}
+
+## What the instruments measured
+
+{{NUMBERS}}
+
+`report.json` in the folder has every number. A BLOCKED row measured nothing; never read it as a pass.
+
+## Play it
+
+Play at least one full round yourself in a headless Chrome on the GPU
+(`--use-angle=metal --enable-gpu-rasterization --ignore-gpu-blocklist` on a Mac): once as a computer
+with the keyboard, and once as a phone (390x844, touch events: a thumb that lands, slides and holds).
+Take your own screenshots at moments you choose. Close every browser you open, at most two at a time.
+If you cannot play it, say so and score only what you saw.
+
+## Score it
+
+Each part 0-10, then an overall 0-100 that is your honest judgement, not the average:
+
+1. **First ten seconds**: in, seated and moving, knowing what to do, with no instructions read.
+2. **Controls**: every press means the same thing every second; the camera never turns on its own; a
+   phone thumb is as good as a keyboard.
+3. **The round**: a goal you understand, tension that rises, a finish you can see coming, results
+   that say who won and why. Does playing well beat doing nothing?
+4. **Look**: does it look finished at phone size, readable at arm's length, with a clear subject, detail
+   at more than one scale, and nothing flat or placeholder-like?
+5. **Sound**: does every action answer, does the music carry the round and change with it, is it
+   balanced and clean on a phone speaker?
+6. **Phone**: one-thumb play, UI out of the way (the middle of the screen clear), portrait and landscape.
+7. **Strangers**: with bots and other people, is it fun together, and does a late joiner fit in?
+8. **Clip test**: ten seconds of silent video on a phone someone is scrolling past. Do they stop?
+
+Then answer plainly: would you play another round? Would you send it to a friend? Would you pick it
+over the best browser party game you know? "No, and here is why" is a useful answer.
+
+## Rules for your findings
+
+- **Measure, don't assert.** "The score text is 11 px on a 390 px screen" beats "the HUD is small".
+  Every gap names its evidence: a picture and what is in it, or a number from the report or your own play.
+- **The fight outranks the frame.** If the pictures look fine and the round is boring, say the round is
+  boring; if doing nothing scores as well as playing, that is the biggest finding there is.
+- **Group by cause.** Five findings with one cause (no lighting, one missing sound bus) are one gap.
+- **One concrete fix per gap**, the smallest change that would move it, and which side of a relation
+  it moves ("make the player brighter than the floor" can be done from either side: say which).
+- **Impact 1-10**: how much fixing it would raise your overall score.
+- Say what you verified yourself and what you could not test.
+
+## Return exactly this JSON (save it as `{{FOLDER}}/VERDICT.json`)
+
+```json
+{
+  "score": 0,
+  "parts": { "first10": 0, "controls": 0, "round": 0, "look": 0, "sound": 0, "phone": 0, "strangers": 0, "clip": 0 },
+  "wouldPlayAgain": false,
+  "wouldSendToAFriend": false,
+  "summary": "two or three sentences a person could act on",
+  "verified": ["what you checked yourself, with how"],
+  "couldNotTest": ["what you could not test, and why"],
+  "gaps": [
+    { "title": "", "evidence": "", "fix": "", "impact": 0 }
+  ]
+}
+```
+
+Gaps sorted by impact, the largest first. No praise padding; no gap without evidence.

package/guides/playtest/scripts/lib/exit.mjs

@@ -0,0 +1,31 @@
+/**
+ * Ending a controller: after its report is written and its browsers are closed, the process leaves, with the exit
+ * code its result earned.
+ *
+ * Why this exists: a full run wrote its report, its sheets and the reviewer command, every Chrome and ffmpeg it
+ * owned had closed, and the Node process stayed. Node only leaves by itself when nothing is left on its event loop,
+ * and a controller that drives browsers collects things that sit there: a socket puppeteer kept, a pipe a child's
+ * helper inherited, a race's losing timer, an AbortSignal's timer. Which one it was that time was never isolated,
+ * so the end does not depend on finding it: run the cleanup (bounded), flush what was printed, then exit.
+ *
+ * The exit code is the one already decided (`process.exitCode`, or `code`): a failed run still exits non-zero.
+ */
+
+/** Race `p` against `ms`; the losing timer is cleared, so the race itself leaves nothing on the event loop. */
+export function within(p, ms, fallback = null) {
+  let timer = null;
+  const late = new Promise((r) => { timer = setTimeout(() => r(fallback), ms); });
+  return Promise.race([Promise.resolve(p).catch(() => fallback), late]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Run `cleanup` (at most `graceMs`), wait for stdout and stderr to drain (at most 2 s), then exit with `code`
+ * (default: process.exitCode, else 0). `exit` is process.exit (a test passes its own).
+ */
+export async function finish({ code = null, cleanup = null, graceMs = 15_000, exit = (c) => process.exit(c) } = {}) {
+  if (cleanup) await within(Promise.resolve().then(cleanup), graceMs);
+  // A pipe (a caller reading our JSON) takes writes asynchronously: an exit before the drain would cut the report.
+  const drained = (s) => new Promise((r) => { if (!s?.writableLength) r(); else s.write('', () => r()); });
+  await within(Promise.all([drained(process.stdout), drained(process.stderr)]), 2000);
+  exit(code ?? process.exitCode ?? 0);
+}