@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/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. 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)
+
+An ice puzzle's 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 |
+|---|---|---|---|
+| Ice puzzle R3 | Opus-class | 5 | controls (four arrows repeat the swipe), play-share (board ~48%) |
+| Ice puzzle R3 | Opus-class, second run | 6 | controls (arrows repeat the swipe; board ~37% of the screen) |
+| Ice puzzle R3 | Sonnet-class | 4 | controls, play-share (board ~40%) |
+| Ice puzzle 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 |
+| Basket game 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 the ice puzzle 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 one game's 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.
+- The ice puzzle's round 3 and the owner's look at it on an iPhone simulator.

package/plugins/cursor/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 one game's 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.
+
+That game, 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 (one game: 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)
+
+That game'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
+
+Its 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 that game 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 one
+  game'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.
+  One game'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: one game'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 that game'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. One game
+   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. One game'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/cursor/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.

package/plugins/cursor/skills/funpixel-verify/references/rubric.md

@@ -0,0 +1,67 @@
+# The review rubric
+
+Seven axes and an overall, scored 1 to 10 per surface (phone and desktop apart), one decimal
+allowed: the calibrated panel's axes, so an in-loop verdict
+and the milestone panel use the same fields. Revised presentation anchors require fresh
+comparative calibration; historical numbers are context, not a demonstrated equivalent scale. The declared style is the standard: a flat two-colour
+puzzle can earn an 8. Scores describe what is visible in a frame; frame rate is never part of one.
+
+| Score | Means |
+|---|---|
+| 5 | substantial visible gaps |
+| 6 | mostly coherent with noticeable gaps |
+| 7 | coherent and readable with minor gaps |
+| 8 | strong execution of the declared style |
+| 9–10 | exceptional execution in the supplied evidence |
+
+| Axis | The question |
+|---|---|
+| `lookAndFeel` | One world from title to end card? Art direction, coherence, coherent assets, readable state changes |
+| `readability` | Can you read the state of play at a glance: you, the threats, what just happened? |
+| `intuitiveness` | Would a new player know what to do and why? |
+| `juice` | Do impacts, feedback and payoffs land? |
+| `fun` | Does the loop offer decisions, as far as the frames show it? |
+| `mobile` | Not its own rubric: the seat's overall on the phone shots, the same axes re-read for a hand (thumbs, safe areas, text at arm's length, the orientation it is held in). Touch controls are never clutter for being there |
+| `hud` | HUD and UI placement, clutter, overlaps, one system |
+| `overall` | The critic's own verdict, not an average |
+
+The gate (BAR.md, R1): the seats' `overall` mean at least 6.0 and their `lookAndFeel` mean at
+least 7.0 on standard captures. 7.3 overall is the aim, on a curated capture set: our bar games sit
+at 6.05–6.60 overall and 7.28–7.42 look-and-feel on standard captures.
+
+Scores do not predict enjoyment, store readiness or commercial success. Use blind play for
+controls and timing, and actual player evidence for engagement.
+
+**Severity.** `high`: the game cannot be played or presented from this frame (text that does not
+read as words, a control that cannot be reached, a screen that never changes). `medium`: degraded
+but playable. `low`: polish. Measure before filing a `high`: a bounding box or a contrast ratio,
+at a stated viewport.
+
+**Before a verdict is final**, write down what would prove it wrong ("is the heart really 18 px,
+or was that the desktop frame?") and check each against the frames and measurements. Revise and
+say so.
+
+## Output
+
+```json
+{
+  "surface": "phone 390x844",
+  "persona": "UX designer",
+  "prior": [
+    { "id": "P1", "status": "fixed", "note": "hearts 28px, ink on bone" }
+  ],
+  "findings": [
+    { "id": "P3", "severity": "medium", "view": "playing", "where": ".hud-score",
+      "issue": "score digits 12px at 390 wide", "change": "clamp(18px, 5vmin, 28px)" }
+  ],
+  "scores": { "lookAndFeel": 7.3, "readability": 6.8, "intuitiveness": 6.5, "juice": 5.8, "fun": 6.2,
+    "mobile": 6.5, "hud": 6, "overall": 6.4 },
+  "bar": { "art_direction": "met", "consistency": "met", "motion": "met",
+    "juice": "missing", "fun": "met", "screens": "met", "hud": "met", "sound": "unseen", "input": "met" }
+}
+```
+The panel means are the mean of the seats' `overall` and of their `lookAndFeel`
+([bar.md](bar.md)). Ids continue across rounds so the next review can
+settle them. Return both surfaces with every score, `findings` (even when empty), and at least
+`art_direction`, `consistency`, `motion`, `juice`, `screens` in `bar`. Carry unresolved high findings
+in `findings` as well as `prior`; passing means do not cancel missing bar items or high findings.

package/plugins/cursor/skills/funpixel-verify/references/scenes.md

@@ -0,0 +1,49 @@
+# Named test scenes
+
+`window.__FPX_VIEWS__` is the game's library of repeatable scenes. Add one whenever a state is
+slow to reach by hand — `boss-arrival`, `late-swarm`, `last-life`, the busiest moment of the
+third wave — each entered through the game's own rules and a fixed seed, so every capture,
+measurement and repair of that state starts from the same place.
+
+```js
+window.__FPX_VIEWS__ = {
+  playing: { motion: true, enter() { startRun({ seed: 7 }); } },
+  'late-swarm': { enter() { startRun({ seed: 7 }); skipToWave(9); } },
+  'boss-arrival': { moment: true, enter() { startRun({ seed: 7 }); spawnBoss(); } },
+};
+```
+
+Expose the counters that say what a scene holds in `__FPX_STATE__` (enemies alive, particles,
+pooled objects, the wave, the frame budget in use). They turn "it felt heavy" into a number the
+next change can be compared against on the same scene (skill `funpixel-game-spine`, performance).
+
+An `enter()` that does nothing is worse than no entry: the checker believes it. A staged view
+shows a state real play reaches, with numbers that agree: an end view gets there through a short
+seeded run, so its card reads that run, and `playing` and `paused` sit over a live board. Our
+generated games' staged cards read "0:00 · 0", "Score 0" over a full basket and a typed-in "1234",
+and every blind critic cited them first. Leave a screen you cannot reach directly undeclared.
+
+## Repeatable frames
+
+`funtools capture` (with `--all`, and `score --target`, `compare --target`) holds the page's clock
+from before your first line and moves it in fixed 1/60 s frames from one seed, so two captures of a
+view are the same frame and a round's before and after differ only by what the round changed. It
+needs no code; what keeps your game repeatable under it:
+
+- Seed every round from `window.__FPX_SEED__` (the starters' `rules.ts`); `--seed 7` plays another.
+- Run the loop on `requestAnimationFrame` or timers and read time from `performance.now()` or the
+  frame's timestamp. `AudioContext.currentTime`, a Worker or `new Date()` run free.
+- Let `enter()` reset what it shows: a fresh round, and the camera CUT to a named shot, never left
+  blending from the last one. Report the shot in `window.__FPX_CAMERA__()` as `{ shot }` (the 3D
+  starter's `shots.ts`).
+
+Each shot says how it was framed: "repeatable: held clock, seed 1, … camera "play"", or
+"free-running" with why (`--free-running` asks for the wall clock). `compare` names a pair that
+was not framed alike as not comparable; read only a pair framed alike as before and after.
+
+What a scene proves is limited: it reproduces a state; it says nothing about whether a player can
+reach it. Acceptance is a separate journey from the visible start through the real controls:
+`npx @funpixel/tools verify --front-door` presses the real start control, `funtools play`
+gives a blind player only the screen, and `funtools journey` keeps a path as a script that replays
+on the same seed and compares run to run ([journeys.md](journeys.md)). A staged victory is a test
+fixture, never evidence of a winnable game.

package/plugins/cursor/skills/funpixel-verify/references/unity.md

@@ -0,0 +1,60 @@
+# Proving a Unity build plays
+
+This skill is the order of checks that shows a build boots, plays to a win and a loss, and logs no exception. The failure it prevents is trusting what a capture shows: one game's tour log held 321 exceptions while every screenshot looked fine, and another's first TestFlight build drew every moving platform frozen after the first level, behind 1,118 green tests. A check sees only the path it runs, so these steps run the paths players take.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, its one `check` command (exit codes 0 pass, 1 fail, 2 not observed, 3 error), the checks below and the studio scripts they were learned with (`unity_check.py`, `unity_sim.sh`, `smoke_sim.sh`, `pcplay.py`, `testflight.sh`'s pre-flight, per-game smoke, remote-play and perf scripts) are proposed. Until the starter ships, run each step with what exists:
+
+- Compile and test: `dotnet build` and `dotnet test` on the engine-free core (its `CoreTests~` project; Unity ships a `dotnet` under `Contents/Resources/Scripting/DotNetSdk/`), and Unity's test runner for the rest: `funtools unity run -- -nographics -runTests -testPlatform EditMode -testResults results.xml` (the machine-wide queue: one run per project across agents; never with `-quit`: the test runner exits by itself). Play Mode tests run the same way with `-testPlatform PlayMode`; one game's `unity/build.sh test` runs Edit Mode then Play Mode and reads the NUnit XML, the only project that does.
+- Build for the Simulator with the game's own build method: `funtools unity run -- -nographics -buildTarget iOS -executeMethod Setup.BuildSimulatorDev` (a development build: its dev flags and test ads work; keep a stripped release Simulator build beside it), then `xcodebuild -project Unity-iPhone.xcodeproj -scheme Unity-iPhone -sdk iphonesimulator build`; install and launch on a Simulator of your own (`udid=$(funtools sim lease)`) with `xcrun simctl install $udid <app>` and `xcrun simctl launch --console-pty $udid <bundle id> -smoke`, never `booted` (it may be another agent's), and `funtools sim release $udid` at the end. About 5–10 minutes a round.
+- A smoke run: a dev-only launch flag in your game that plays from the title to an ending and writes `smoke.txt` to the app's Documents; read it with `xcrun simctl get_app_container $udid <bundle id> data`.
+- Dev flags: launch arguments for dev builds that jump to a state or start a bot (the games used `-autoplay -startlevel N`, `-seed 7 -autoplay`, and a tour flag that writes every menu to PNG), read natively (Mono never sees `simctl launch` arguments) behind the game's own dev gate, with telemetry muted while a flag is on.
+- Hand play from a script: `npx @funpixel/tools unity play start`, then `play tap`, `drag`, `key`, `pad`, `state`, `ui`, `shot`, `record` and `end` (the kit's `com.funpixel.probe`, lifted from one game's remote play: real Input System device state, in the game's own upright coordinates). `unity probe --path path.json` plays a scripted path and measures it; `unity capture --all` shoots every registered view (funpixel-unity-game, `references/probe.md`).
+- Screens: `funtools sim shot $udid --out shot.png`, upright in the game's orientation; `funtools sim tap $udid x y` presses a point of that picture.
+
+## Checks
+
+| Check | Passes when | Status |
+|---|---|---|
+| `compile_fast` | 0 errors | proposed (a studio script, not in the kit) |
+| `core_tests` | 0 failures, count at or above baseline, csproj tracked in git | partial |
+| `flag_free_launch` | 0 exceptions in 40–60 s with no dev flags | proposed |
+| `smoke_to_ending` | ending reached, 0 errors, average 58 fps or more excluding capture frames | partial |
+| `entry_path` | view state equals sim (rules) state in a level entered as the second or later | proposed |
+| `console_exceptions` | 0 in the player log of any tour or autoplay | partial; tours not covered |
+| `audio_runtime` | 1 AudioListener, 48 kHz, music playing within 3 s | partial |
+| `frame_budget` | first entry under 34 ms, none over 20 ms after warm-up, p99 at most 17.5 ms | `funtools unity probe` (no phone measured yet) |
+| `invisible_work` | 0 world cameras behind full-screen menus, 1 pass in play | proposed |
+| `look_leak` | `RenderSettings` and shared materials identical before and after each level and warm-up | proposed |
+
+## Procedure
+
+1. Compile (`dotnet build` on the core, or a batch-mode Unity build). Read the full output: `| tail` hid a failing compile and a commit went through.
+2. Run the core tests: in the game's `CoreTests~` folder, run `dotnet test` (the SDK inside the Unity app, `Contents/Resources/Scripting/DotNetSdk/dotnet`, if none is on the PATH). Compare the count with the baseline.
+3. Build a stripped Simulator build onto your own Simulator, with your own port and scratch folder. One agent's install on a shared Simulator killed another's remote-play session.
+4. Launch once with no dev flags for 60 s and count exceptions. Dev flags mute telemetry, so a flagged launch skips code a player runs.
+5. Run the smoke to an ending and to a loss, and assert the ending itself.
+6. Enter at least one level through Next, Continue or Restart. Audits that start every level fresh at boot miss state the previous level left behind.
+7. Run the tour and require every registered screen. Fail the tour, and any autoplay, on one exception in the player log. `Debug.Log` on iOS goes to stdout, so launch with `--console-pty`.
+8. Run `audio_runtime`. Simulator captures carry no audio.
+9. Run the remaining Runtime checks in the table; funpixel-unity-game has the detail.
+10. End every fix loop by playing: `unity play` or a `unity probe --path` script, with a measured outcome such as kicks connected or falls per hop. This is the owner's direction, "verify it yourself by playing". Thresholds for those outcomes are not in the report.
+11. Run each new regression test against the parent commit and confirm it fails there.
+12. Before upload, run the archive pre-flight (funpixel-store says what it checks; the script is proposed).
+
+A person still checks feel on a real phone and audio by ear.
+
+## Worked example
+
+A three.js port with 26 levels. Build 1 went to TestFlight behind 1,118 green tests, and every level after the first of a session drew its movers frozen: a warm-up had left the views bound to a throwaway sim. Every audit had started levels fresh at boot, so none saw it. Once fixed, the audit's frozen category went from 219 to 0. A production gate (fresh install, every level through real flows, 7 kill-and-relaunch cycles, every setting persisted) found 4 more bugs behind 1,377 green tests. Hand play through the game's remote-play server found what bots had passed: fans that looked walkable, the smallest hero drawn as a speck, and threats under the buttons.
+
+## Common mistakes
+
+- Launching with dev flags every time. One game's dev flags muted telemetry, so a Firebase crash path first ran when the owner launched normally.
+- A smoke that asserts only "no errors". One game's bot failed to beat the boss for 11 minutes, then stood holding USE; the run now uses a god-mode flag, `DebugBossHit` and a walk-to-lever script.
+- Reading screenshots and skipping the log. In one game a NullReferenceException in `Hud.Pad` hung a demo match silently.
+- Trusting benches for boot. A static cache declared after the colours it used threw a TypeInitializationException and no build booted for about 7 h; which game is not in the report.
+- Hand-written `.csproj` files left ignored by git. One game's tests could not run from a fresh clone.
+- A regression test that passes on the old code, as one game's cheat test did.
+- Shipping without the audio check. All four first games reached TestFlight silent, because a camera made in code has no AudioListener (`funtools doctor` warns before the build).