@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/codex/skills/funpixel-verify/references/fidelity.md

@@ -0,0 +1,126 @@
+# Plan fidelity: what was planned against what was built
+
+The critic panel never sees the plan, so it cannot see that the game drifted from it. Held Note (a
+third-person horror chapter, the Held Note lane, 29 Sep 2026) scored 6.55 overall and 7.62 on look
+from the panel; a blind judge holding the same build against its own GDD gave art direction 4 and
+creative direction 3, and named what the panel could not: the thesis frame's fingers missing from
+the seam, the first walker at arm's length instead of far down the corridor, a stencil colour that
+had drifted, a camera low and to the side where the plan put it high over the shoulder. A pass later
+held the dark, the camera and the stencils (AD-3 held) and still missed the fingers. That judge is now
+the fidelity seat in `funtools playtest`.
+
+## What the seat sees, and nothing else
+
+- The GDD's creative direction in its own words: the pitch, the promise, the thesis, the 6-second ad.
+- The declared style (the first paragraph under the look or art direction heading).
+- The AD rules.
+- Each target frame's moment and intent (what the frame must carry).
+- The measured facts (F…, and P1: which moments were paired and which were not, and why).
+- Image pairs: the target frame beside the game's frame of the same moment, and a strip of
+  consecutive frames when the moment is animated.
+- The last round's findings, last.
+
+It scores each moment on art (camera and composition, light, materials, how the actors read, the
+world's marks, the grade) and creative (does the frame carry the moment's intent), 0–10; then art
+direction and creative direction overall, each AD rule as held, partly or broken, and five changes.
+It ignores the HUD, and where the plan's words and its own picture disagree, the words win.
+
+## Pairing the moments
+
+The GDD template's target-frames table ties each target to its moment:
+
+| Moment | Target | Game frame | Intent | Pins |
+|---|---|---|---|---|
+| 1:00 the first walker | design/first-look/frame-walker.png | view firstWalker | dread: a lone figure far down the corridor, joints lit, torso dark | AD-2, AD-3 |
+
+A game frame is a declared view (`view firstWalker`, shot by `capture --all`), a journey mark
+(`journey chapter1 walker`, the frame the latest run held at that mark) or a file. With no table,
+`design/target.png` is paired with the play view. A moment with no game frame is listed in P1 with
+the reason, never scored.
+
+**Shoot the moment the plan means, not a fixed timestamp.** The walker at the six metres the target
+drew, the splice as it completes, the merge at its pop. A view whose `enter()` replays a recorded run
+to that beat (the playtest reference's `game.replay.seek('first-walker')`), or a journey mark placed
+at it, lands there on every build; a clock time drifts the first time the level changes. Two of our
+own fallback pairs show the cost: Plush Pop's play view was captured with an empty basket, so the
+seat could only say the target's pile and squish were missing; Gesundheit's was captured before
+any sneeze, so the flowers the target promises were not on the ground.
+
+**Or pin it to a time on the saved route, and name both.** From the first playtest on, the blind
+player's steps are kept as the route (`test/journeys/playtest-route.json`) and every playtest replays
+it with the same viewport and seed. A game frame `at 1:00` (or a moment written `1:00 the first
+walker`) is the route's frame at that time on the script's own clock: like with like every round,
+as Held Note's films were (0:10, 1:00, 2:00, 3:00, 5:00). A row that names both, `at 1:00, view
+firstWalker`, is judged on the played frame, and the view stays beside it as the staged frame. When
+the played route never reaches what a staged view or a lane's file shows (no moment, screen or beat
+by that name in play), the report says so: Held Note's Diver was showcase art in its lane's frame
+and "a few coral points" in play. A moment past the route's end is play that never got there. Keep
+the route while the level holds; when the level changes, record a new one (`journey record
+playtest-route --force`) and read the history's next column as a new baseline, which the report marks.
+
+## How the judging is kept honest
+
+Borrowed, with credit, from Scenario's quality skills (MIT; research 06 §2.2–2.3):
+
+- **The rubric comes first** (Scenario). The plan's words were written before the build; a rubric
+  written after seeing the frames inherits their flaws. Every miss cites the line it fails:
+  `[AD-2]`, `[intent: the seam]`, `[direction]`.
+- **Declared style is intent, never a finding**. Pixel art that looks pixelated is
+  what was asked for; the style applied inconsistently still is a finding.
+- **Sweep an animated moment for identity** (Scenario). Across a strip, a named part gained, lost,
+  recoloured or reshaped is drift; a part moving with the action is animation. A spot check at one
+  frame missed a defect that faded in half a second later.
+- **Facts over the frame**. The numbered facts outrank a reading of one picture: a
+  world that looks empty in one frame while the facts count what is off-camera is not empty.
+- **Adjudicate the last round**. Each earlier finding comes back marked fixed,
+  unchanged or worse, and a score whose evidence did not change does not move.
+
+## The plan's interface: UI and UX as imagined or not
+
+The owner's second question, from the Held Note lane: is the interface the one the plan designed?
+Held Note's GDD draws its phone HUD and its message screen as HTML at 852 × 393, each element
+numbered with a line of spec ("1 collar ring: health, five cyan lights"; "nothing sits in the middle
+of the screen"). When a GDD has such mockups (a `.phone` or `[data-mockup]` element in any page under
+`design/`, the first look's `hud.html` first), `funtools playtest` renders each as an element
+screenshot and pairs it with the game's same screen, captured through a view at phone size in touch
+mode (the GDD's `| Screen | Mockup | Game frame |` row names the view; a HUD pairs with the play
+view). A still auto-presses a screen that waits for input, so a screen that waits is opened through
+a view, never reached by a capture pressing on.
+
+Pictures count as mockups too: the style bible's `**HUD target:**` and `**Title target:**` lines
+(skill `funpixel-art`, ui.md) and a GDD mockups row naming an image pair with the play and
+title views, carrying the bible's `## UI` section as their words. The seat also reads `look --hud`'s
+dressing facts (system type, dark neutral plates, the scaffold's own glyphs, icons typed as
+characters, a plain wordmark), and
+judges the title as a player meets it: look, readability and whether it makes one want to press
+Play, beside the genre hit's opening when a still named `title` or `opening` is in its evidence.
+
+After the blind round, `playtest experience` also writes the UI seat (`panel/fidelity-ui.md`): the
+screens' words and numbered elements, the plan's interface rules, the image pairs, and the blind
+phone player's round as play facts, because UX is how it plays (a goal the player could not find,
+a dodge never taught). Per screen it scores ui (layout, what sits on the character against the
+glass, sizes, the visual language) and ux (does it work as intended); each numbered element held,
+partly or missing; what the game adds that the plan does not have, and whether each serves or fights
+the plan's rules; then UI and UX fidelity and five changes. The report puts them beside the art
+seat's scores and ranks the changes, a missing planned element first. On Held Note's two mockups
+it gave UI 5 and UX 4: of 15 planned elements 3 held, 8 partly and 4 missing, and four additions
+(a tutorial line at top centre, a permanent minimap) fought "nothing sits in the middle".
+
+## Reading the result
+
+The report puts art direction and creative direction beside the last round, each rule's state, and
+ranks the seat's changes among the next steps (a broken rule first). A low creative score with a
+held look usually means the moment was shot at the wrong time or the frame's subject is missing;
+fix the view or the moment before the art. When three of our games were judged against their
+single target frame, Lantern Night kept its palette and lantern design (art 8) but lost the wheel of
+lanterns and the visible chain (creative 6); Plush Pop built the target's set but not its round felt
+critters or the squish (5 and 3, AD-1 broken).
+
+## After a greenlight lock: reference-match rounds
+
+When `design/greenlight/lock.json` exists (skill `funpixel-gdd`, the greenlight), the seat reads the
+style bible's locked target table first, its facts name the locked version and anything changed
+since, and its brief gains `panel/reference-match.md`: compare the establishing view first, then
+the player's view, and list the biggest differences between the accepted pictures and the running
+game, each with the one change that closes it. Those targets cleared the genre hit before any code,
+so a large gap here is the build falling short of its own plan, not the plan's taste.

package/plugins/codex/skills/funpixel-verify/references/hit-bar.md

@@ -0,0 +1,31 @@
+# Comparing a slice against a genre hit
+
+Use this when the person asks for the stronger bar. A short, satisfying loop can be compared
+fairly without promising a commercial game's content volume. Pick a named genre hit and state
+which skill and device the comparison covers before judging. The internal 6.0 overall / 7.0 look
+floor is still useful; it does not certify this comparison.
+
+The provisional bands from the platform's HITS_CALIBRATION evaluation are:
+
+1. Overall and look-and-feel each within 0.5 of the chosen hit, using the same unanchored rubric.
+2. Fun and juice each within 1.0 of it. Stills only partly observe these: add actual play and
+   matched motion evidence, and report what the reviewer could not observe.
+3. Order-normalized head-to-head win rate at least 0.375, with the player seat winning or tying
+   at least one pair. Use phone against phone when the hit ships there; otherwise desktop against
+   desktop. This is not a raw count of wins in eight calls.
+
+Keep the supplied platform evaluator's normalization unchanged and record its inputs and result.
+If that evaluator is unavailable, keep both presentation orders and raw seat verdicts, mark the
+normalized criterion uncomputed, and do not invent a pass. These thresholds came from a small
+calibration set and need further validation; disclose that in the review.
+
+Use like-for-like evidence: a normal playable moment against a normal playable moment, comparable
+viewport, duration and UI visibility. No trailer against raw gameplay. Seat reviewers blind to
+who made each game. Separate appearance findings from directly observed controls and rhythm.
+Do not show other seats' scores or the target score to a reviewer before its verdict.
+
+Keep each round's source fingerprint, captures, clip paths, player report, reference, rubric,
+seat verdicts and normalized result. Fix the highest actionable difference, then rebuild and
+repeat the same protocol. At the fix-round limit, report the shortfall and the next concrete
+change; never lower the bar to make a green badge. The person's own play session remains a
+separate acceptance step, recorded only when it happens.

package/plugins/codex/skills/funpixel-verify/references/journeys.md

@@ -0,0 +1,77 @@
+# Journeys: the real controls, replayed
+
+A scene in `__FPX_VIEWS__` reproduces a state; it says nothing about whether a player can reach
+it. A journey is the other half: what a player does from the visible start, through the real
+controls, kept as a script that replays on the same seed and the same screen size, so two runs can
+be set side by side. OpenAI's Astra write-up keeps the two apart for this reason, and our own games
+show why: a staged victory passed every check while the real Play button did nothing (the front
+door: Sonnet pressed it in 1 of 72 lab sessions).
+
+## The script
+
+`test/journeys/<name>.json` (a test, kept with the game):
+
+```json
+{ "name": "first-win", "viewport": "phone", "seed": 1,
+  "steps": ["mark start screen=title", "tap 0.5 0.62", "wait 800",
+            "mark playing screen=playing", "drag 0.3 0.8 0.7 0.8 400", "wait 2500",
+            "mark first-score score>0", "tap 0.5 0.5", "wait 20000", "mark round-end screen!=playing"] }
+```
+
+- Steps are `funtools play`'s: `tap X Y`, `drag X1 Y1 X2 Y2 ms`, `hold X Y ms`, `hold KEY ms`,
+  `press KEY [n]`, `wait ms`, and `A & B` for two fingers at once, or a key held under another
+  (`hold ShiftLeft 1500 & hold ArrowRight 1500`, a held run; modifiers go down first), and
+  `look DX DY [ms]` (the mouse moved with no button: a camera look, also under pointer lock). A decimal
+  from 0 to 1 is a fraction of the screen, a whole number a CSS pixel. A phone takes touch only.
+  play's `hold … until` / `wait until` are not journey steps: `from-play` writes each as the fixed
+  hold or wait it took in the round.
+- `view` and `verb` are refused: they reach a state without the controls, which is what a scene
+  is for (`funtools capture --view`).
+- `mark NAME` is a checkpoint: the game's clock is held, the frame kept and `__FPX_STATE__` read.
+  Each `field=value` after the name is an expectation (`=`, `!=`, `>`, `<`, `>=`, `<=`; `player.x`
+  and `enemies.length` reach inside). A mark with no expectation still keeps its frame and counters.
+- `seed` is set as `window.__FPX_SEED__` before the game's code runs. The scaffold's rounds read
+  it; a game that draws from `Math.random()` or the clock replays differently each time, and the
+  noise run below shows how much.
+
+## Three ways to get one
+
+- `npx @funpixel/tools journey record <name> --viewport phone`: a window opens on the built game;
+  play it; close the window. Your taps, drags and keys become steps with the waits between them,
+  and each screen `__FPX_STATE__().screen` reaches becomes a mark expecting it. A drag replays as a
+  straight line; presses that overlapped replay one after the other (say it by hand with `&`).
+  This is the one a person makes: the creator's own path through the game.
+- `npx @funpixel/tools journey from-play last <name>`: the blind player's round (`funtools play`)
+  up to its first `view`/`verb` jump, with a mark after each act expecting the screen the player
+  saw. The player's clock was held while it thought, so marks can land earlier in game time.
+- Written by hand, when you know the path (a tutorial, the first level's solution).
+
+## Replay and compare
+
+`npx @funpixel/tools journey replay <name>` loads the game as a player finds it (no hook called),
+plays the steps and judges each mark. Exit 0 every expectation held, 1 a step or an expectation
+failed, 2 nothing judged (no expectation, or no state to read), 3 error. The run is kept in
+`.funtools/journeys/<name>/<n>/` and set beside the previous one: how much of each mark's frame
+changed, which counters moved, which expectations flipped. `--repeat 2` plays it twice on one build
+first: what differs between those two runs is noise, and a later difference smaller than that is
+not a finding. `journey diff <name> 3 7` compares any two runs; runs with another seed, viewport or
+script are named "not the same test".
+
+## When it helps
+
+- **Before and after a change to the title, menus, input, audio unlock or level flow**: replay the
+  journey that crosses it. A broken start shows as the first mark that did not reach its screen.
+- **A balance or feel change**: the counters at each mark (score, lives, enemies alive, time) on
+  the same seed say what moved; the frames say whether it shows.
+- **A regression the blind player found**: `from-play` keeps its exact path; after the fix, the
+  replay's marks should pass where the round was blocked.
+- **Phone layouts**: a phone journey presses the on-screen controls a thumb would; a key-only path
+  cannot pass there.
+
+`funtools feel --journey <name>` plays a journey's steps with every frame's state traced: the
+verb's numbers, tells, the death beat and looks by state along a player's real path (skill
+`funpixel-game-feel`, `references/measure.md`).
+
+What a journey does not prove: that the game is fun, readable or good to look at. It proves a path
+still works and says what changed along it. Frames from a software renderer are not a phone's
+performance (`funtools profile` says the same).

package/plugins/codex/skills/funpixel-verify/references/mobile-qa.md

@@ -0,0 +1,123 @@
+# Mobile QA: is it native to a phone?
+
+The critic panel scores stills (each seat re-reading the phone captures), and the blind player plays by touch.
+Neither asks whether the game was made for the phone it runs on. Floe (an ice-slide puzzle, round 3,
+29 Sep 2026) scored mobile 7 and up from the panel and passed its blind phone round, and the owner
+opened it on an iPhone simulator and saw desktop thinking: the board under half the screen, four
+large on-screen arrows repeating the swipe the board already took, Undo/Restart/Hint panels in the
+bottom third, a tip banner over play. The Mobile QA seat is the reviewer that catches that, from
+what phones showed.
+
+## What it sees
+
+`npx @funpixel/tools mobile-qa` (alone) and `playtest` (as one of its seats) gather it, free:
+
+| Where | What it adds | Cost |
+|---|---|---|
+| Chromium at phone size (the capture set) | every view at 390x844 (844x390 held sideways), touch on, DPR 2, the review phone's insets | seconds |
+| Playwright's WebKit | the play view in Safari's engine: its CSS and layout, no Safari bars | seconds, optional install |
+| iOS Simulator, real Mobile Safari (`funtools phone`, both orientations) | Safari's bars, the notch and home bar, DPR 3, iOS taps, the start control pressed by name, the page's own frames and errors | about a minute a run, Apple Silicon and baguette |
+| Key parity at phone size | each declared key against the on-screen controls that name it | seconds |
+| `look --fit`, five windows (1700x800, 1280x600, 1024x1024, the phone sideways and upright) | per window, opened fresh: how long it stays one flat colour, then the first screen and the play view: the content's share of the window, flat bars at the edges, content bunched in a corner | a few seconds a window, a minute at most |
+| audit-screens, look --hud | text under 12 px, hit areas under 44, safe-area pieces; how much of play the HUD covers | from the playtest's measurements |
+| The blind phone round | how a stranger tried to move (drags against taps) and what hurt | the player's round |
+
+Our phone viewport is already touch-true (`isMobile`, `hasTouch`, DPR 2, `?funpixel_touch=1`) with a
+desktop user agent; the Simulator is the one with Safari's own agent, DPR 3 and bars. `playtest
+--phone` and `mobile-qa --phone` run `phone` first. Each platform is marked observed or not, and a
+platform not observed is unknown, never a pass.
+
+The phone runs press the start control and nothing else; the other images are stills. An idle board
+after start is not a dead control. In the first calibration run the seat read a still board as a
+swipe that did not register and filed a false high on a game whose swipe works; the prompt now says
+what was pressed, and the finding went away.
+
+## What it judges, and why each
+
+1. **Controls native to touch.** Play by touching the play itself reads as made for a phone. A
+   button that repeats a gesture the play area already takes costs room and teaches the button
+   instead of the gesture. Controls a verb needs are never clutter: a fire button while a thumb
+   steers, a stick, pause, undo. Judge only repetition.
+2. **The play area's share of the screen.** Phone-native puzzle and arcade games give play most of
+   the screen. The seat says the share, measured when the gesture check has written it, else
+   estimated from the frame and said so.
+3. **Thumb reach.** What is pressed every few seconds belongs in the bottom third, or at the edges
+   when held sideways. The harness's mobile rules put primary actions in the bottom 30–40% and call
+   top-centre the worst place for a control pressed every session.
+4. **Tap targets.** 44 by 44 points of hit area; seven of the 28 phone fixes in one batch of 45
+   reviewed games were targets (skill `funpixel-mobile-ui`, `references/phone-check.md`).
+5. **Chrome during play.** Banners, stacked HUD rows, a tip still up after the first move.
+6. **Safe areas.** The HUD under the status bar is the harness reviewer's most common real defect.
+7. **Orientation and window fit.** Twelve of those 28 fixes were portrait fit, orientation or
+   scale: a landscape world in a sliver of a portrait screen. The captures use fixed sizes, so a
+   game can ship a wide, short desktop window that is black and mostly empty with its content
+   bunched in a corner (the owner found one at about 1700x800); `look --fit` sweeps the windows
+   people give a game. Its content is anything not the ground colour, so a busy backdrop counts:
+   it catches empty windows, bars and corners, not a small board on a painted sea (that is item 2).
+8. **Readability at arm's length.** What a phone shows at its size and brightness.
+9. **First touch.** Where to touch and what a touch does, from the first screen; the blind round is
+   the witness.
+
+**Key parity** (research 01, B12): a declared key that no touch route reaches, neither a control nor a
+gesture, is a finding, high when the game declares the phone its primary platform and medium
+otherwise. The parity probe counts only controls that name a key, so it lists the arrows of a swipe
+game as unreached; the seat decides whether the play area's gesture covers them and says which. A
+gesture with no key is never a finding.
+
+## Declaring the platform
+
+`"platform": "phone"` in `funpixel.json` metadata says the phone is primary: the seat then ranks an unreachable key high. `"both"` is the
+same seat without that; `"desktop"` says there is no phone target, and the seat is not prepared.
+Undeclared, a game is a phone target: Funpixel games are played on phones.
+
+## Severity and the score
+
+High is desktop thinking on the core loop or a phone player blocked: play under half the screen
+while chrome takes the rest, controls that repeat the play area's gesture and take the room play
+needs, the primary control out of reach on every frame, a start control that does not answer in
+Mobile Safari. Medium costs a phone player something but plays. Low is polish. Phone-native 0–10:
+9–10 made for the phone (Threes, Suika Game, Monument Valley), 7–8 native with small misses, 5–6
+plays but thinks like a desktop in one area, 3–4 a squeezed desktop layout.
+
+A finding names the platforms that showed it. The report says a finding every observed platform
+showed once, plainly, and prefixes one only some showed with them, "[iOS Safari landscape] …"
+(research 01, B13): there the platform is the information.
+
+## Where it lands
+
+- `playtest report` ranks its findings with the other seats: a high sits beside a blind player's
+  high defect (a phone player meets it first), above the panel's fixes; the report has an "On a
+  phone" section and a phone-native row against the last playtest.
+- `mobile-qa report` does the same for a standalone run.
+- The Stop hook's hand-back names an open high finding once per answer. It is advisory: the seat's
+  findings are yours to pick, edit or ignore. The harness's own MobileReview forces a corrective
+  turn on a high; the GDK does not.
+
+## Calibration (29 Sep 2026)
+
+Floe round 3 (read-only copy) and Drift, a scratch swipe puzzle made phone-first for this (swipe
+anywhere, board 75% of the screen, one undo button bottom-left, pause top-right), each through one
+seat, real Mobile Safari in both orientations:
+
+| Game | Seat | Phone-native | High findings |
+|---|---|---|---|
+| Floe R3 | Opus-class | 5 | controls (four arrows repeat the swipe), play-share (board ~48%) |
+| Floe R3 | Opus-class, second run | 6 | controls (arrows repeat the swipe; board ~37% of the screen) |
+| Floe R3 | Sonnet-class | 4 | controls, play-share (board ~40%) |
+| Floe R3 | Opus-class, with the window sweep | 6 | controls (arrows repeat the swipe; board ~44%) |
+| Drift | Opus-class | 8 | none (landscape board small: medium) |
+| Drift | Sonnet-class | 7 | none |
+| Plush Pop R3 | Opus-class, with the window sweep | 6 | none; medium: left/right/Drop buttons beside a drag the basket takes, the basket ~35% of the Mobile Safari page, landscape a squeezed sidebar |
+
+The first-paint times of the window sweep ran 2.5–7.7 s for Floe on a machine at load 50–60: read
+them against runs made the same way, as the profile's numbers.
+
+The funtools scaffold is gesture-first since the Riad Rush phone round: a swipe on the play steps,
+a tap or swipe up hops, and its on-screen buttons are a setting, off by default.
+
+## Sources
+
+- The harness's mobile reviewer: `mobile_review.txt` (severity discipline, plan as intent),
+  `quirks_mobile.txt` (thumb zones, targets, safe areas), `sections/base/mobile.txt`.
+- Skill `funpixel-mobile-ui`, `references/phone-check.md`: the 28 phone fixes and the four looks.
+- Floe's round 3 and the owner's look at it on an iPhone simulator.

package/plugins/codex/skills/funpixel-verify/references/playtest.md

@@ -0,0 +1,161 @@
+# A great playtest, and why it works
+
+A playtest is the mirror held up between creator rounds: free measurements, three blind critics and
+a blind phone player look at the same build, and a short ranked list says what stands between this
+round and the next. It applies nothing. This page is what the Held Note lane learned running that
+loop on a survival-horror chapter in Three.js (29 Sep 2026): what made the evidence trustworthy,
+what misled once, and what the person read. Take what fits your game.
+
+Held Note, round by round, same panel words and bar:
+
+| Round | Overall | Look and feel | What happened |
+|---|---|---|---|
+| v1 | 6.25 | 7.15 | first full playtest; past the gate, under the 7.3 aim |
+| v2, first try | 4.9 | — | every capture sat at the opening shot; the seats said "no walker in any capture" |
+| v2, fixed | 6.55 | 7.62 | same build with the capture views working; look past 7.0 by 0.62 |
+
+## The loop, and why each part is its own
+
+`npx @funpixel/tools playtest` builds, verifies, captures every declared view at both sizes (a
+moment view as a strip of frames), audits the phone screens, samples the HUD in play (`look --hud`),
+reads the actors against their ground (`look --read`), reads what a 3D game's heroes are made of
+(`look --3d`: code primitives read as stand-ins unless the style is declared), profiles, runs `sim` and
+`feel` when their scripts exist, and writes one prompt file per seat. Each prompt opens with the numbers as facts F1,
+F2… so a seat reads the instruments before the pictures.
+
+Then every seat runs as a fresh agent handed only its prompt file: the three critics (veteran player,
+UX designer, skeptic) in parallel, and the blind player at phone size with `player.md`. A seat that
+sees the code or another seat's answer drifts toward them, and one told why a frame looks as it
+does scores it kinder (0.2 in the calibration): the separation is the instrument. `npx @funpixel/tools playtest report` then ranks
+3 to 4 next steps, each with a quote, a frame and a number, beside the last round.
+
+| Part | Sees | Why it is separate |
+|---|---|---|
+| free measures | the build | numbers nobody argues with: HUD cover, text size, contrast, ΔE, frame time, verb timings |
+| three critic seats | premise, frames, facts | three personas notice different things; each re-reads the phone captures (no mobile seat) |
+| blind phone player | premise, the screen, touch | the only seat that plays: it finds what stills cannot (Held Note: the camera entering walls, a tell too short to see on a muted phone, a tap that cut nothing and showed nothing) |
+| report | all of the above | ranks what blocks a new player first, then what several seats asked for, weighted by where the game trails its genre hit most, so one loud seat does not set the agenda |
+
+## The loop, round after round (the default)
+
+Held Note's v1 → v4 pages were worth reading because the instrument stayed the same; `playtest`
+runs that loop by default, and a round can run less.
+
+- **One route, one camera.** The first blind round's steps become the saved route; later playtests
+  replay it (same steps, viewport, seed) and shoot the plan's timed moments beside its targets.
+- **Per moment, per rule**: art and creative per moment, UI and UX where the plan drew the screen,
+  each AD line held, partly or broken; a staged frame play never reached is flagged.
+- **Round history** (`.funtools/playtest/history.json`), every round in one table, each drop marked
+  and listed: HN v4 fell on every axis (readability −0.85), which is why its next fix was right.
+- **Last round's blockers first**, judged fixed, still there or changed by the ledger seat; one
+  still there ranks up. No evidence is never "fixed".
+- **Do not regress.** Up to eight things the panel named as working ride every brief; one the
+  ledger seat finds lost leads the steps and fails the report.
+
+## Look at the captures before you trust a score
+
+Held Note's first v2 round scored 4.9, and the seats were right about what they were shown. When the
+game was split into modules, the capture hooks reached the game through a loose cast; the replay
+cursor and the intro timer had moved, the cast hid it, and every view's fast-forward silently left
+the game at t = 0 behind the opening shot. Twenty frames of the title card's camera, scored as a
+survival-horror fight. Typed against the real game, with an error logged when a view misses its
+beat, the same build scored 6.55 / 7.62.
+
+What guards against it:
+
+- **Open a few frames first.** Does each named view show its beat: the walker in `firstWalker`, the
+  bead on the door in `seam`? A minute of looking saves a round of seats scoring the wrong game.
+- **Type the hooks against the real game.** A view's `enter()` that reaches internals through `as
+  any` compiles after a refactor and does nothing. With the real type, the move breaks the build.
+- **Let a view say when it misses.** After fast-forwarding, check the thing the view exists to show
+  and `console.error` when it is not there. `capture` reports what the page logged while a view
+  was entered, and `playtest` opens its report with "Look at the captures first" when views logged
+  errors or when several declared views are the same picture.
+
+```ts
+import type { Game } from './game';           // the real type, so a moved field breaks the build
+export function views(game: Game) {
+  return {
+    firstWalker: {
+      enter() {
+        game.replay.seek('first-walker');       // the recorded run, to its mark
+        if (!game.threats.some((t) => t.inView)) console.error('view firstWalker missed its beat: no walker in view');
+      },
+    },
+  };
+}
+```
+
+## Measure the right things
+
+- **Name the actors so the instruments find them.** `look --read` measures the player and the
+  threats against the ground around them. Name each actor's root node `player-…` or `threat-…`
+  (or set `userData.role`); once a scene tags a role, only tagged nodes play it. Without tags it
+  falls back to the usual words, which in Held Note took a prop, `hazard_barrier`, as a threat, and
+  the seats read "threat ΔE 0.7, weakest hazard_barrier at ΔE 0.5". Read the line `look --read` prints per role (how it found the
+  role, the nodes it took) before reading its number.
+- **Wire `feel` early.** Expose `hero { x, y, grounded, unit, vx, state, invulnerable }`,
+  `threats [{ id, phase }]` with a tell and a strike phase, `dead` and `control` in `__FPX_STATE__`,
+  and write `test/feel.json` (skill `funpixel-game-feel`, references/measure.md). It read Held
+  Note's dodge back from real key presses: 1.92 m in 0.30 s against the design's 2.0 m in 0.26 s,
+  untouchable for 0.217 s against 0.21. Its script never reached a walker, so the tell, the death
+  beat and the restart stayed "not measured": a script that walks to the first threat is what
+  measures the fight.
+- **Run `feel` twice.** The first run's long frame (a warm-up shader compile) moved the wall-clock
+  windows; one run's dodge hit the rail. Two runs that agree are a measurement; one is an anecdote.
+- **Faded screens.** The HUD judge and the phone audit skip what a faded or hidden ancestor hides.
+  Held Note's chapter card, faded to opacity 0 but still on the page, once counted as HUD all
+  chapter (41% of the play); taking faded layers out of the page after their fade also keeps them
+  from screen readers.
+
+## Films that show the game
+
+A still cannot carry a fight, so the review page leads with one filmed run: a bot on the real
+controls, nothing staged. Bots that only walk the route make films with no combat: Held Note's
+route bots never fired the driver or used the knife, so no film showed the weapons the owner asked
+for. A film-only `fighter` bot style that plays the verbs a keen player would fixed it, while the
+tests keep the median bot, because tests measure a typical player and a film shows what the game
+is at its best. Give the blind player and the films a stable build (`vite build`, then `vite
+preview` on its own port): a dev server's hot reloads read as glitches to someone playing, and a
+rebuild partway through a round leaves late steps on newer code (say so when it happens).
+
+## What the review page carries
+
+`playtest report` writes `report.md`: the ranked steps, this round against the last and the genre
+hit, what each seat said, the measures and the cost. The page Held Note's owner read added what
+only the creator can assemble, and each part earned its place:
+
+1. **The score against the last round**, overall and look-and-feel, the seats' scores, each
+   axis as a bar with the last round beside it and the 7.3 aim marked, and the gate lines (6.0 overall,
+   7.0 look) with pass or not yet. The person sees where the work moved the needle and where it did not.
+2. **A broken round, explained.** The 4.9 round stayed on the page with its cause and its fix;
+   a number that vanished would make every other number suspect.
+3. **What changed since the last round**, one line each, so the steps can be read against the work.
+4. **One filmed run**, 60 to 90 s of real play with the fight in it, and a few captioned stills
+   from it (the counter, the prompt lit, contact, the quiet after).
+5. **Screens**: the opening, a death with its cause, the chapter's end, the phone layout.
+6. **The HUD audit frames** (`look --hud`'s outlined frame), before and after the fix.
+7. **A measured-facts table**: instrument, what it read, verdict, with "not measured" rows kept
+   (a script that never reached a walker is a finding about the script, not a pass).
+8. **Target frames against the game**: each GDD target frame beside the same beat in the game,
+   one line each, "Close" or "Right idea", then what is missing.
+9. **A pillar audit against the GDD**: each pillar graded, what matches, what still drifts. Held
+   Note found requests made mid-build ("add guns", "make her faster") had quietly broken stated
+   pillars; re-reading the pillars after each request folded them back in.
+10. **The critics in their own words**: each seat's one-line quote and its overall.
+11. **The blind round**: the steps where it struggled, as frames, its verdict and the caveats.
+12. **Next, ranked**, most blocking first, each concrete ("a tell you can see: the arm builds to
+    white across the whole 0.7 s warning"), none needing new content where none is needed.
+
+The kit does not build this page yet: `report.json` holds the numbers, `frames/` and
+`hud-*-phone.png` the images, and the rest is the creator's. A page skeleton emitted from
+`report.json` would save the assembly; it is an open idea, not a tool.
+
+## When the numbers disagree with your eyes
+
+Trust neither alone. Held Note's threat read ΔE 0.7 on the phone, part of it measured on a prop, and
+the critics independently called the walkers hard to read in the dark; the step stood on the
+critics and the frames: light the dark a notch. When a
+number says pass and the frames look wrong, the instrument may be measuring the wrong thing (the
+prop, the faded card): read what it matched. When the frames look right and the score is low, open
+them all: the seats may be scoring frames that never reached the game.

package/plugins/codex/skills/funpixel-verify/references/review.md

@@ -0,0 +1,105 @@
+# The critic panel
+
+**One verdict per round:** the targets (`score --target` at `accuracy_min`, default 75) and a blind
+player with no high finding (`play`). **At hand-back, the panel too:** three blind critics on real
+captures, phone shots included, at the bar our bar games passed (rule
+R1): overall 6.0, look and feel 7.0; 7.3 the aim on a curated set. Other tools find why.
+The local hook mirrors open evidence (advisory by default); a quiet hook is not acceptance.
+
+## Tools
+
+- The judge is the `critic` agent in this kit, run once per persona. With the MCP,
+  `capture_view` shoots each declared view at a named state, held still, at a phone or desktop
+  size; `audit_screens` and `probe` supply measurements (text size, hit areas, overlaps, clipping,
+  safe area). Review what they miss, painted glyphs included.
+- Locally and free: `npx @funpixel/tools capture --all` (every view, both sizes, repeatable; the Stop hook
+  reads its index) and `audit-screens --viewport phone`.
+- Before the panel, locally and free: the `player` agent plays the build blind through
+  `npx @funpixel/tools play` (never the source); `look --read` measures whether the player and the
+  threats stand out from the ground, `look --hud` whether the HUD keeps out of play; `lessons add`
+  records a settled finding.
+- Between creator rounds, `/fp:playtest` (`npx @funpixel/tools playtest`) runs all of this in one
+  pass and ranks 3 to 4 next steps, each with a quote, a frame and a number; games rose from
+  6.8–7.05 to 7.4–7.6 over 3–4 rounds. The loop:
+  [playtest.md](playtest.md). Beside the panel, what stills cannot see: the plan
+  against the game ([fidelity.md](fidelity.md)), depth, story, world and
+  replay ([experience.md](experience.md)), and whether it is phone-native,
+  judged in real Mobile Safari ([mobile-qa.md](mobile-qa.md)).
+- Hosted, for credits (quoted, confirm over 50): `review` runs the panel on your frames or the
+  draft, `play` the blind player on the draft; `playtest --hosted` uses both.
+
+## The checklist
+
+1. **After green.** A panel on a build verify has not passed spends its seats on what verify
+   already knows.
+
+1a. **Play it blind first.** The `player` agent at phone size, handed only the store description,
+   plays through `funtools play`, judges the `criteria` in `funpixel.json` and reports the three
+   worst defects with a screenshot and an exact repro each. A round with no high defect is the
+   usual point to move on. The Stop hook reads the latest
+   phone report on these files, so build before a round and keep source still during it.
+
+2. **Capture the matrix.** Every view in `__FPX_VIEWS__` (title, play, pause, end, and
+   any other; the `moment: true` view plays as a burst and keeps its payoff frame) at desktop and
+   at phone size in the game's orientation, after the last change to the files, plus each core
+   verb mid-answer (`capture --view playing --verbs <verb> --hold 60`) so the veteran seat can judge the juice table.
+   Run `audit-screens` at phone size too; use its measurements.
+
+3. **Seat the panel, blind.** Three `critic` runs in parallel in the foreground (a background
+   seat answers too late), one persona each: veteran
+   player, UX designer, skeptic ([bar.md](bar.md)). Each
+   sees what the calibrated panel saw: the frames by full path (a seat may not list folders), a
+   store description of four to six sentences (never the note's intentions), `audit-screens`'
+   numbers, the five AD rules and its own previous verdict. A seat told why a frame looks as it
+   does scores it kinder (briefed seats scored 0.2 above blind ones), so fix the frame; keep the
+   design note, target frame and verify summary out. A seat that sees another's scores,
+   the code or the builder converges on them. The bar was calibrated with Opus-class seats
+   (BAR.md), so a lighter model's scores sit on another scale. Target matching
+   is the `art-director` agent's job; its findings join the fix round unscored.
+
+4. **Settle the last round first.** Status per finding: `fixed`, `unchanged`
+   (same selector and number), `worse`, or `unseen` (name the view). A settled finding is never filed again in new words. A score moves only on an axis whose frame changed.
+
+5. **Compute the panel means.** Two numbers: the mean of the seats' `overall`, and the mean
+   of their `lookAndFeel`. Write the round to `design/review.json` (`/design/` in
+   `.harnessignore`).
+
+6. **The agreed bar.** Report both means and seat scores; the gate is a minimum, and a hit-level
+   slice has its own ([hit-bar.md](hit-bar.md)). Averages hide single
+   failures, so open player findings, a `missing` bar item and a high critic finding stay open
+   whatever the mean; `unseen` stays unproved.
+
+7. **Under the gate: a recorded fix round.** Merge the seats' findings, fix the highest-severity
+   ones (a `missing` release-bar item first), verify, capture the matrix again and re-run all four
+   seats (`compare --baseline` before, `compare` after). Record the round as the note's `## Fix round` table, one row per open finding by name
+   (bar key or finding id) with its next step; the Stop hook reports it as an unfinished
+   hand-back, and a finding it does not name stays open. A finding settled `fixed` goes to `funtools lessons add "<finding>" --fix
+   "<what fixed it>" --delta <mean change>`. How many rounds is yours: the bar games rose over
+   five to fourteen panels (BAR.md). When three rounds stop moving the means, report rather than respin: the mean, the open findings, the next round.
+
+8. **The declared style is the standard.** Pixel, flat, 1-bit, a two-ink print: if the design
+   chose it, "looks simple" is not a finding; inconsistent execution or an unfinished stand-in is.
+   Thumb controls over a phone scene are fine unless they hide what the player steers or are
+   under 44 px.
+
+Seat prompts and the release bar: [bar.md](bar.md); the axes and output:
+[rubric.md](rubric.md).
+
+## Worked example
+
+Window-cleaner, verify 0.
+1. Captures: five views at both sizes; `audit-screens` flags the lives readout at 10 px.
+2. Three seats, blind: veteran 6.0 ("a pot hitting the cradle has no hit answer"), UX 5.5 (lives
+   at 10 px), skeptic 5.8 ("end screen is a flat colour"). Means 5.8
+   and 6.8 look: under the gate.
+3. Fix round 1: hits get flash, spray and 60 ms hitstop; lives to 24 px; an illustrated end screen.
+4. Round 2, the confirm round: prior findings `fixed`; mean 6.65, look 7.4: above the floor; stop.
+
+## Common mistakes
+
+- Judging captures older than the files.
+- A third panel on one milestone (judge, fix, confirm once, stop).
+- One critic playing all three seats, or seats that see each other's scores: the panel collapses
+  into one opinion.
+- Phone frames skipped because desktop looked fine.
+- Handing back under the bar without naming the next round.