@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-gdd/references/the-path.md

@@ -0,0 +1,133 @@
+# The path, step by step
+
+The brief's path, step by step. This is the long form: what each step is for, the tool that helps,
+and the signal that says it is done. It is how the owner's best games were made (one game's
+`design/MAKING.md` writes it down end to end; four others ran the same way): a plan that is a contract, target frames that show what done
+looks like, the sim first, assets generated and made to behave, and every round spent closing the
+gap between the game and its targets.
+
+**The locked plan is the job; how you build it is yours.** Choose the code, the order, the tricks
+and the tools freely. What the game must be (its look, its numbers, its content) is the plan's,
+and only the owner relaxes it. Checks are mirrors: they tell you how far the game is from its
+plan. Scope, time and spend are the creator's: the kit never shrinks a game to save them.
+
+**One flow drives it.** `npx @funpixel/tools flow` says where the run is and the one next step;
+the owner's open notes come first. The owner stops the run in two places only: **the lock**
+(`flow ask`; their "good, let's build" stands until they say otherwise; a new direction is a
+new GDD version they lock again) and **their rounds per
+session** (`flow.rounds_per_session`, default 3; the next session resumes with `/fp:flow`).
+
+## 1 · Brief back
+
+**For:** turning one sentence into a game both sides mean the same way.
+**Do:** write a short brief (title, kind, the verb, world, length, how failing works, look, phone
+and desktop) and show it once. Then pick the genre, engine and title yourself and say why in one
+line.
+**Done when:** the person said yes to the brief, or edited it.
+
+## 2 · First look, then a first playable
+
+**For:** something real and nice to steer, before the whole game is planned. The owner reacts to a
+picture, then plays; a plan made around a game they played beats one made around a sentence.
+**Do:** the key art (the game's look in its own light, at the play framing; a target) and the hero's
+reference sheet, shown in the chat; their words steer them before anything 3D is paid for. Then a
+first playable built from them, in the game itself, with real assets: the hero, the place in the key
+art's light, the title, a music loop, the verb's sounds. Sized by the game: a short game about a
+minute, mostly the place and its feel; a long one 3 to 5 minutes, the core loop once, a win and a
+loss. Judge it against the key art before showing it.
+**Tool:** `flow` (stages `key-look` and `prototype`), `gen`, `assets gen`, `score --target`,
+`check --front-door`; their verdict: `note verdict prototype accept "<their words>"`.
+**Done when:** they played it and said it has potential (else: a new key art, or drop the idea).
+
+## 3 · Plan the whole game around it, at its real size
+
+**For:** naming the whole game before the build, so the build has something to reach and every round
+something to compare with.
+**Do (skill `funpixel-gdd`):** pillars; the look and its rules (a few numbered lines: what each
+colour means, what never appears); screens and HUD for phone and desktop; characters; story;
+levels and their content, counted (`references/plan-at-size.md`); feel. Then **Part 2, the
+numbers contract**: every number the game depends on (speeds, windows, costs), with tests named
+after them. Then **target frames**: generated key art for the moments that matter (the first
+input, the first payoff, each level's signature moment), which say what done looks like. Then
+**the asset list with its price**: the GDD's `## Asset script` names every piece the game ships
+(cast, environments, props, title and HUD art, sound, music; skill `funpixel-gdd`,
+`references/world-and-identity.md`); `npx @funpixel/tools assets script --write` makes it the
+list `assets gen` makes, replacing the starter's demo items, and `assets gen --dry-run` prices it.
+The first look's pictures (under `design/`) are references for the shipped art, never the shipped
+art itself.
+**Done when:** the plan holds the whole game at the length in the brief, never smaller.
+
+## 4 · Lock
+
+**For:** one agreement, so the build can run without stopping.
+**Do:** `npx @funpixel/tools flow ask` readies the plan, its target frames and its price; show
+them in the chat and wait for the owner's yes, then record it with their words (`flow agree --by
+owner "<their words>"`). Their decisions stand from then on. When the build has to move
+(a number that doesn't play, a frame the engine can't reach), write it in the plan's
+`## Where the build moved` table with why, and keep the target unless the owner relaxes it.
+**Done when:** the owner approved.
+
+## 5 · Sim first
+
+**For:** rules you can trust before anything is drawn.
+**Do:** the rules and the numbers as plain, seeded code with bots that play the level over many
+seeds (`npx @funpixel/tools sim`, `test`). Bots that finish the level are the regression net for
+every balance change.
+**Done when:** the bots play the level and the contract's tests pass.
+
+## 6 · Build with the assets as they land
+
+**For:** a first playable that is already the planned game, not a stand-in for it.
+**Do:** generate the plan's assets into `public/assets/` while you build: the hero from its
+reference sheet (rigged and animated where it moves), the world's kit, title art, sound and music.
+You decide each route yourself (free built-in, the library or the cast,
+generate, hand-built last) and say the route and cost in one line. Judge every asset under the
+game's own light and camera, not the generator's preview. A 3D line starts from the 3D world
+starter (`--framework three-world`: follow camera, lit world, controller, phone stick; skill
+`funpixel-game-spine`, `references/three.md`). Its designed shapes only keep the game booting
+until the models land. Show the first built frame in the chat early (`capture`), with the
+preview link.
+**Done when:** the player moves, one verb works through real input, a win and a loss fire,
+progress shows, keys and touch both work, and `check` exits 0.
+
+## 7 · Each round, the look-dev loop
+
+**For:** closing the gap between the game and its plan, which is what made the owner's games.
+**Do:**
+1. Capture the game at the target moments (`npx @funpixel/tools capture`; recorded intents and
+   seeds make the same moment the same frame every time).
+2. Set each capture beside its target (`compare --target`) and name the biggest difference.
+3. Fix that one thing.
+4. Play it: `play` (a blind phone player), `playtest` (the panel and the fidelity seat).
+5. Repeat until each beat is "close".
+Matching a target is the job, never a style choice; only the owner relaxes one. `check` stays
+green throughout.
+**Done when:** each target beat is close and the blind player has no high finding.
+
+## 8 · Extend
+
+**For:** a game long enough to keep: more levels, more story, a later chapter.
+**Do:** work down the plan's content list, a row a round, each one through the same loop. A long
+game goes chapter by chapter (the GDD's `## Chapters`, the `chapters` stage): plan the chapter with
+the owner, make its target frames first, build it to them, show it, and open the next only on their
+yes (`note verdict chapter:<id> accept "<their words>"`). Fold a
+mid-build request back into the pillars before you build it: one game's "add guns", "make her
+faster" and "make maneuvers easier" each broke a stated rule until they were folded back.
+**Done when:** the content list is reached in play.
+
+## 9 · Hand back
+
+**For:** ending on a game someone accepted, not on a score.
+**Do:** what plays now (keys and touch), how it compares with its targets ("below the bar: <why>"
+when it is), what is out on purpose, every fallback still in the game, the next two or three
+steps; the dev log with `report_feedback`.
+**Done when:** the person has played it and said yes. Then stop editing.
+
+## Keep the game
+
+A game in a temp folder dies with it: on 3 Oct a `/tmp` wipe took a dozen builds and their evidence.
+Make the game in a folder of its own, never under `/tmp`, `/private/tmp` or a scratchpad. `funtools init`
+makes it a git repository with a first commit (`--no-git` skips that); commit as you go and push to a
+remote (`git remote add origin <url>`, then `git push -u origin HEAD`) before you hand back. `.funtools/`
+is the evidence the game earned (reports, scores, small frames): it stays in git, and `funtools export`
+carries it into the clean folder.

package/plugins/cursor/skills/funpixel-gdd/references/track.md

@@ -0,0 +1,29 @@
+# Versions and the track
+
+How a GDD is versioned, and the stages a game has gone through on the way to its owner's yes. Each
+gate is help to reach for, never a wall: a stage may be skipped, and the owner's word is the only
+hard line.
+
+## Versions
+
+v0.1 before code or assets; v0.2 after the first look; a version per stage or per request bending a
+pillar, in `## Versions`; as built, Part 2 from the code with a drift list.
+
+**A pivot** (the world changes mid-plan): archive the old GDD to `design/archive/<version>/`,
+log it in `## Versions` (what changed, why), set the locked sections it touches back to draft, keep
+what survives.
+
+## The track
+
+| Stage | Gate | Evidence |
+|---|---|---|
+| Design | the invention, hits per axis, worth, the studio pitch locked, v0.1 | `design/GDD.md`, `design/studio.json` |
+| First look | the whole game (`funtools firstlook`) | `design/first-look/` |
+| Greenlight (option) | pitches judged; frames beside a matching hit, HUD mockup included | `design/greenlight/` |
+| Scaffold | `funtools init` once the GDD names the genre and the controls | the game folder |
+| Gray-box and slice | the loop through real input; one level in art and sound | `verify.json`, captures |
+| Panel 7.3 | blind seats on fresh captures (skill `funpixel-verify`) | the verdicts |
+| Ship | the person plays it and accepts it | their note |
+
+A stage may be skipped (a jam game: Design to Slice); say which. Rounds that disagree are decided
+once with `funtools decide`, both reasons kept; a phone measurement beats a still.

package/plugins/cursor/skills/funpixel-gdd/references/world-and-identity.md

@@ -0,0 +1,165 @@
+# The world and its identities
+
+One pitch (a courier walks a sleeping child across six moons), was planned twice on
+30 September 2026. The plan made through the kit had the better mechanics and story. The plan
+written by hand had the better world and held together: every place drawn, every recurring design
+the same in every picture. Its panel never complained of drift; the kit plan's panel named drift as
+its first blocker ("lock one model sheet"). This file is what the hand-written plan did, as five
+GDD sections and a first-look order. Size each to the game: a three-minute arcade round gets a line
+or a decline, a two-hour game gets all of it.
+
+## Identity lock
+
+A game made of generated pictures drifts unless its designs are pinned. Across the first thirteen
+images the courier's hair, jacket and trousers changed from picture to picture, the
+ship was a different ship in each shot, and the walker robot was two robots. A studio fixes this
+with model sheets; so does the plan.
+
+- **One reference sheet per recurring design**: the hero, a companion, a vehicle, the pursuer, the
+  thing carried. A turnaround (front, side, back) on a plain ground, drawn from the best draft that
+  already exists, never from words alone: the draft is the design the person liked.
+- **One style block, verbatim**: the medium, the palette by hex with what each colour may be used
+  for, the bans ("no pure black, no text, original designs"). It is `assets/style.json` (`medium`
+  and `never`), appended to every prompt word for word. Paraphrasing it per picture is how a palette
+  drifts.
+- **Every later picture names its sheets**: as input references where the image tool takes them,
+  and always in words (the sheet's `pins`: "short dark jaw-length hair, a scar through one
+  eyebrow, a patched burnt-orange flight jacket"). With the sheets and the block, seven of seven
+  redraws came back on-model on the first try, for $0.30.
+
+```markdown
+## Identity lock
+| Ref | What it pins | Source | Used in |
+|---|---|---|---|
+| REF-HERO | face, hair, outfit and its colours, the pack | design/first-look/ref-hero.png, from frame-2 | key art, all four frames, the poses |
+| REF-SHIP | hull shape, stripe, the lit window, four legs | design/first-look/ref-ship.png, a crop of the machine sheet | key art, the delivery, the hub |
+
+Style block (verbatim in every prompt): <medium · palette by hex with each colour's one use · bans>
+Proportions: <the hero is 7 heads; the companion 0.6 of her height>; the same numbers the models are checked against
+```
+
+The lock holds in the game too: one palette ramp every mesh samples, one material and outline pass,
+the proportion numbers, a palette check on captures, and the cast as black shapes at 40 px told
+apart by a blind look (skill `funpixel-art`). Pictures agree only as well as their
+references; the models will not match them pixel for pixel, which is why those checks exist.
+
+## Places
+
+One row per level or area, and a picture of each. A place is a rule and a landmark, and its
+atmosphere is design rather than decoration: each place changes **one** number of play, and what
+you see and hear warns you before it matters.
+
+```markdown
+## Places
+| Place | Sky and light | In the air | Sound bed | The play number it changes | Landmark | Picture |
+|---|---|---|---|---|---|---|
+| Calder · Run 01 | indigo dusk over salt | salt dust in gusts | wind in the rigging | gusts add sway; kites flatten 0.8 s before each one | the dead relay | design/first-look/place-calder.png |
+| Wren · Run 02 | teal overcast, a storm wall | snow near the front | creaking ice | ice halves grip; warmth drains near the front | the seed vault | design/first-look/place-wren.png |
+```
+
+- The foreshadow is the craft: a gust read from kites, ice read from a herd that slows. A number
+  with no tell is a trap; a tell with no number is decoration.
+- A chart of the whole world (a map, a system, the hub seen from above) shows how the places hang
+  together and gives the person one picture to point at.
+- One level on purpose is a fine answer: say it in the content list ("one place on purpose") and
+  `funtools gdd` stops asking.
+
+## Creatures and machines: a job and a cost
+
+Fold these into `## Living world` and `## Actors` rather than a section of their own. Every creature
+and machine does one job in play and has a price; nothing is there only to decorate, except a
+wonder you name as one.
+
+| Kind | Job in play | Cost or catch |
+|---|---|---|
+| Jelly-kites | the wind gauge without a HUD: they flatten 0.8 s before a gust | none: they are information |
+| Salt crabs | a scatter is noise the pursuer hears at 25 m | walk around them, or scare them on purpose to pull it away |
+| The cargo walker | carries 12 kg of the load | loud (heard at 18 m), slips on ice |
+| The ferry | the second route on the lake | a rhythm input; out of time, you drift |
+| The sky whale | wonder, on purpose | none |
+
+A machine that is a free ride stops being a choice, the same rule as a verb with no price.
+
+## Getting around
+
+The hub can be the world. Rather than menu screens between you and play, each transition can be a
+camera move through one space: the chart zooms into a moon, the moon into the paper map, the map
+folds down into the ground under the hero's feet, and the woken relay lights the moon on the chart.
+
+```markdown
+## Getting around
+| # | The move | What you see | Length | Why |
+|---|---|---|---|---|
+| 1 | The chart | the hub above: moons turn, woken relays glow | idle loop | progress in one glance |
+| 2 | The descent | tap a moon: the camera dives, the landmark rises out of haze | 2.5 s, skippable | arrival as a place; the level loads under it |
+| 3 | The map unfolds | the route drawn on paper becomes a glow on the ground | 1.2 s | the plan becomes the path |
+
+Budgets: 60 fps on a mid-range phone; under 3 s after the first viewing (repeats at double speed);
+reduced motion cuts each move to a cross-fade.
+```
+
+A move that loads the next level while it plays hides the wait. A menu is still right where a choice
+needs reading (a shop, settings); the table is where that choice is written down.
+
+## Asset script
+
+Every piece the game ships, one row per family, tied to the beat it serves, the locks it used, what it
+cost and where it stands. The next piece is a row added here first. `npx @funpixel/tools assets
+script --write` makes it the list `assets gen` makes (one item per piece), replacing the starter's
+demo items; `assets gen --dry-run` prices it, and that price is what the owner approves at the lock.
+The `## Art budget` is its totals. Give every row its **Kind** and **Count**: a row without a Kind is
+read from its words, and a guess is the wrong place for a 3D game's models to depend on.
+
+Kinds: character / creature (a pose set), strip (a sprite animation), model or character3d (a 3D
+model; character3d is rigged, and the words after its colon are its moves: walk, run, attack and death become rig clips; wave, nod, hop, strike, flinch or stumble, and celebrate become authored motions; any other move is named for you to animate in code), structure / prop / ui / icon (cut-outs), place / background
+(pictures), tile / texture, sound, music.
+
+```markdown
+## Asset script
+| ID | What | Kind | Count | Cast | Beat it serves | Locks used | Cost | Status |
+|---|---|---|---|---|---|---|---|---|
+| REN3D | Ren, the courier: walks, leans, stumbles | character3d | | ren | every Run | REF-REN, style | | planned |
+| TUG | the tug Late Show | model | 1 | | the hub between Runs | REF-SHIP, style | | planned |
+| CALDER | Calder's ground: rock; ice; dust | texture | 3 | | Run 01's routes | style | | planned |
+| TITLE | the title lettered as art | ui | 1 | | the title screen | style | | planned |
+| SFX | footstep; load creak; stumble; sign-for chime | sound | 4 | | every Run | | | planned |
+| BGM | Signed For, a slow D-minor jazz ballad | music | 1 | | the title and the ending | | | planned |
+| KA-01 | title key art | place | 1 | | the promise | REF-REN, REF-SHIP, style | $0.08 | locked |
+```
+The first look's pictures (key art, target frames, turnarounds under `design/`) are references the
+shipped pieces are drawn to; the shipped pieces are the rows above.
+
+`funtools assets` keeps the facts for its rows: its lock records each picture's cost and the sheets
+it was drawn to (`references`), so Cost and Locks used are read, not remembered.
+
+## The honest breaks
+
+After the lock, lay the pictures side by side and write down where they still break the plan's own
+rules, and keep them: "the market lanterns are amber, which AD-1 keeps for the cargo; the built
+level makes them cream". A named break is a note for the build; a hidden one ships. The list goes
+under `## First look` in the GDD, beside what the pictures settled.
+
+## The hook: Wow, Fun and Hook per place and screen
+
+The owner (1 Oct): "the WOW factor, the FUN factors, and how this would HOOK the player." Every
+place and screen row carries three short cells: **Wow** (the one thing a player remembers or
+shares there), **Fun** (what they do there that feels good) and **Hook** (why they keep going: a
+question, a promise, a reward ahead). An empty cell is a place nobody will talk about.
+
+`## The hook` puts the first minutes on the clock with 2 to 4 wow moments. The courier game's plan
+(v0.8) named four: the title (the lounge window lights up and a sky whale drifts past), 0:42 (the
+hatch opens and the camera pulls back over the Dry Sea), 1:00 (the first searchlight sweeps the
+valley and the crabs scatter), and about 3:00 (moths settle on the cradle and the child hums).
+Each is proven twice: a fixed-framing strip beside its target, and a blind player who mentions it
+without being asked. The playtest's blind player answers, per screen, what they remembered, what
+was fun and whether they wanted to go on; set those beside the cells.
+
+## What `funtools` reads
+
+`funtools gdd` warns, never blocks, when a plan of several places has a recurring cast and no
+`## Identity lock`, or a level with no row under `## Places` (a "Declined:" line, or "one place on
+purpose", silences it).
+`funtools assets` makes `ref-*` items first and warns when a `look-*` picture names no sheet. The
+greenlight shows the sheets beside the targets and names each off-model frame.
+`funtools gdd` also warns when a game of 5 minutes or more has no `## The hook`, or a screen or
+place row with an empty Wow or Hook cell.

package/plugins/cursor/skills/funpixel-gdd/references/worth.md

@@ -0,0 +1,74 @@
+# Worth building at this length?
+
+Not every idea is worth building, and not every idea fills the length the owner wants. Say so at the
+pitch, with numbers, before a single first-look picture is paid for. The owner asked for exactly this
+(4 Oct 2026): "If [this game] is not a game to play 1.5 hours, challenge me; not every idea is worth
+building; size the story and the game; also the best games in similar genres."
+
+## Why
+
+One game's GDD promised 30 minutes "in 5 chapters of 2 flights each, about 3 minutes each". Its
+own numbers said one flight is about 70 s and there are 10 flights: about 12 minutes of flight. Four
+areas whose frames look alike, three graft kinds, one character, no progression beyond a score. The
+genre's best that it cited hold one to three hours with a distinct place every 15–20 minutes. Nobody
+said so until the owner did, after the first look was drawn.
+
+## What the plan writes
+
+- `## The numbers`: a row that ties a time to one unit ("level time | about 75 s a level", or "one
+  flight is about 70 s" in its why), and a row with how many ("24 levels", "10 flights"). Retries
+  only if you can defend them ("1.2 tries a level: the undo keeps first solves to one try").
+- `## Content list`: counted rows for places, verbs or mechanics, characters and the meta (upgrades,
+  unlocks, goals, collectibles). The read counts these, not the prose.
+- `## Worth against the genre`: 3–5 of the genre's best, one row each:
+
+| Game | Length | Distinct places | Verbs / mechanics | Characters | Progression / meta | Source |
+|---|---|---|---|---|---|---|
+| Flower | ~2 h | 6 levels, each its own twist | 6 | 0 | none | approx, from memory |
+
+Every number carries a source URL in the row, or is marked "approx, from memory". Never invent
+precision: "~2 h", not "2 h 07 min". Prices, sales and review counts stay out. "endless" is a
+length; its places and verbs still count.
+
+## The read
+
+`npx @funpixel/tools greenlight worth` (also shown by `greenlight`):
+
+- **Supplied minutes**: seconds per unit × how many × retries, from the numbers (the rooms' pars when
+  `design/spec/rooms.json` has them). Never the Play length line: that is the promise being checked.
+- **Target**: the owner's `funpixel.json` `target_minutes` (only they set it: the page's box, or
+  `--target <min> --by owner`), else their bar's length line, else the plan's own promise.
+- **Density**: the genre's medians (a place every N minutes, a new thing every N minutes, characters
+  an hour, the share that carry a meta) against this plan's content list at the target.
+- **One verdict**: `fits` · `stretch` (what to add, by category, with counts) · `does not carry`
+  (shrink, reshape, or drop) · `prove the core first` (nobody has played the core yet and the target
+  is 45 minutes or more: a 5-minute prototype costs less than a wrong plan).
+
+Anything but `fits`, or supplied minutes under 2/3 of the target, is the owner's scope question:
+ask it in the chat, with the numbers, before the first look's art; it goes to them with the plan,
+and `greenlight lock` waits for their answer. Under the owner's own autonomy
+`go`, record your choice and why: `greenlight worth choose <option> --why "<the numbers>"`.
+
+## Challenge the owner
+
+- Lead with the two numbers: "your target 90 min; the plan's numbers supply 12".
+- Set it beside the genre's best, by name: "Journey: ~8 areas in ~2 h; we have 4 that look alike".
+- Name what would carry the length, with counts: "+2 places, a meta, +79 minutes of play".
+- Recommend one option and say why. **Drop it** is a legitimate recommendation: when the core was
+  played and did not hold, more content will not fix the verb; when the idea is thin even at its own
+  length, inflating it costs more than a new idea. Do not soften it into "grow it a little".
+- A new game already opens with a first playable (the `prototype` stage), so this route matters
+  for a game started before 5 Oct. "Prove the core first" routes to a prototype stage: one session of the core verb in the starter,
+  measured with `check --front-door` and a blind player (`play`), then the owner plays it, then the
+  question again with that evidence. Short in content, never bare in look: build it in the game's own
+  starter and camera and dress it with what the first look already made (title, how-to-play, the HUD
+  on phone and desktop, one real place, the hero, the sounds and music, the core verb's juice). A grey
+  page beside the game is not a prototype the owner can judge (the same game, 5 Oct: "this initial look
+  is worst of all I have seen").
+
+## That game, read
+
+At the owner's 90 minutes: prove the core first (11.7 of 90 minutes; +2 places, a meta; recommended:
+the prototype). At 20 minutes: stretch (+9 minutes of play and a meta; recommended: shrink to the
+12-minute game it is). A genuinely fitting plan (Tide Locks, 24 levels × 75 s × 1.2 tries = 36 of
+30 minutes, its places and mechanics at puzzle density) reads `fits` and asks nothing.

package/plugins/cursor/skills/funpixel-mobile-ui/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: funpixel-mobile-ui
+description: Use when building a HUD, title screen, menus or touch controls, when something sits under the notch, is too small to tap, overlaps or is hard to read on a phone, or a game must work on phones. Covers safe areas, thumb zones, orientation, contrast and a phone check. In Unity (UGUI, the notch), follow references/unity.md.
+---
+
+# Phone HUD, controls and legibility
+
+Most people play Funpixel games on a phone, inside an iframe that resizes, rotates and goes
+fullscreen. A layout that looks right on the desktop can put the score under the notch and the jump
+button under the home bar, and both still build and pass a desktop verify. Here the phone layout is rules you can check.
+
+## Tools
+
+- `mobile_check` runs the phone check (step 11's matrix) on an uploaded draft; fix the first
+  failure it names (it cannot see the pixel ratio or insets).
+- `screenshot` captures one view at a chosen viewport; `audit_screens` measures text, hit areas
+  and overlaps on every declared view.
+- `probe` reports render health, including key parity (declared keys with no touch control).
+- Local fallback: `npx @funpixel/tools verify --viewport phone` (390x844, 844x390 when landscape,
+  touch on) or `both`; `npx @funpixel/tools dev` with device emulation for the rest.
+  `audit-screens --viewport phone` (`--orientation landscape` turns it; `capture`, `scene` and `play`
+  too); `funtools doctor` checks the viewport meta.
+- `npx @funpixel/tools look --hud`: HUD cover, text contrast on the real frame, HUD over the
+  actors in play, toast pile-ups, and whether the HUD and title still wear the scaffold's clothes.
+
+## Steps
+
+What broke on real phones and why each fix works (28 of the fixes in one batch of 45 reviewed
+games were phone layout: [references/phone-check.md](references/phone-check.md)).
+
+1. **The shell.** Without `viewport-fit=cover` in the viewport meta every `env()` inset is 0. The
+   Funpixel frame resizes and rotates, so the canvas is sized by CSS (100%) and the renderer
+   through `setupGameResize((w, h) => …)`, refit on `fullscreenchange` and `visualViewport`
+   resize. Pixel ratio 3 fills nine times the pixels of ratio 1: a cap (1.5 in 3D, 2 in 2D) is the
+   usual first fix when `profile` shows the phone dropping frames.
+2. **Safe areas.** The notch and the home bar cover whatever touches the edge, and the top is the
+   side people forget; `max(16px, env(safe-area-inset-*))` keeps edge-anchored elements clear.
+   `safeArea.insets()` from `@funpixel/sdk/device` returns zeros until CSS defines `--sai-top`,
+   `--sai-right`, `--sai-bottom` and `--sai-left` from `env()`
+   ([references/recipes.md](references/recipes.md)).
+3. **Touch facts.** Without `touch-action: none` the browser takes a drag as a scroll. A second
+   `onpointerdown = …` silently replaces the first; `addEventListener` keeps both. 44 by 44 CSS px
+   of hit area is where thumbs stop missing (`audit-screens` measures it). Thumb reach, one input
+   sign across keys, buttons and sticks, and drags: [references/recipes.md](references/recipes.md).
+4. **Touch controls for touch only.** Last input wins: a touch shows them, a key or mouse hides
+   them (the last `pointerdown`'s `pointerType`; starters: `.touch-only`), as `pointer:
+   coarse` lies on touch laptops; `look --hud` warns on desktops.
+5. **Blur.** The `keyup` for a key held across an app switch never arrives; on `blur` and on
+   hidden `visibilitychange`, clear held keys, end pointers, zero sticks, pause.
+6. **The gesture before the button.** Phone hits take the move on the play itself and give the
+   freed screen to the board: a puzzle swipe or drag that previews where it goes (Threes, Two
+   Dots), a maze swipe anywhere that queues the next turn (Pac-Man 256). A pad repeating the
+   swipe reads as a desktop port. Buttons earn a place where no gesture
+   carries the action, or as an accessibility setting. `data-fpx-gesture="ArrowLeft …"` on the
+   swiped or dragged element claims those keys (a lift that fires: `Space`) for key parity;
+   on a phone `look --hud` reports `play_area_share` and `controls_duplicate_gesture`
+   ([references/recipes.md](references/recipes.md)). A key kept keyboard-only on purpose is named
+   in the hand-back.
+7. **Orientation** follows the design (genre tendencies and the rotate card:
+   [references/recipes.md](references/recipes.md)). Size landscape by the smaller side (`vmin`,
+   `dvh`) so the primary button survives a 375 px tall screen. Orientation lock and iPhone element
+   fullscreen do not exist here, so neither can be the fix. Audio
+   unlock and fullscreen need `pointerup`, `touchend` or `keydown`: a touch `pointerdown` is not a
+   user activation.
+8. **Text that fits.** A title broken mid-word, overlapped labels or a cut score read as a broken
+   game to every reviewer. `clamp()` or viewport units scale where fixed px overflow the narrow
+   phone; `tabular-nums` stops a counting number jittering. Measure rendered glyph bounds, not the
+   element's box ([references/recipes.md](references/recipes.md)).
+9. **Contrast is arithmetic.** Three vision reviewers missed cream on mustard (1.9:1); the WCAG
+   ratio did not: 4.5:1 for body text, 3:1 for large text, icons and control edges. An ink of the
+   same hue, lighter or darker until it passes, keeps the palette where white drops it
+   ([references/contrast.md](references/contrast.md)).
+10. **HUD, title and splash, in the game's world.** The scaffold's dark pills, system type and
+    glyphs are there so a first build has a HUD, not as a look: plates, faces, icons and the
+    wordmark come from the world (dressing them, with worked examples:
+    [references/restyle-ui.md](references/restyle-ui.md)). Emoji cannot take the palette; inline
+    `<svg>` can. A HUD kept as a list plus theme tokens changes by a row
+    ([references/hud-and-title.md](references/hud-and-title.md)); the hits' HUDs and a layout per
+    genre: [references/hud-genres.md](references/hud-genres.md). A splash is optional (same reference).
+11. **Check it the way a thumb plays it** on the matrix in
+    [references/phone-check.md](references/phone-check.md) (both orientations, touch on): it drew
+    (an all-black frame was once marked ok), the named controls respond, nothing sits under the
+    notch or home bar, the frame rate held; `funtools phone` shows it in real iOS Safari.
+
+## Worked example
+
+A portrait block puzzle, fixing a phone report:
+1. `screenshot` at 375x667: the score chip sits under the status bar; the title reads `BLOC` with
+   an orphaned `K` on the next line.
+2. The chip gets `top: max(16px, env(safe-area-inset-top))`; the viewport meta already has
+   `viewport-fit=cover`.
+3. The title gets `white-space: nowrap` and `font-size: clamp(22px, 11vmin, 56px)`; its rendered
+   bounds stay inside its card at both extremes.
+4. Contrast: cream `#F4E9D8` on mustard `#D9A21B` computes 1.9:1. Keeping the mustard's hue and
+   saturation and lowering the lightness to 16% gives `#493609`, 5.0:1.
+5. Rotate is a tap on the piece, not a button; `probe` lists `KeyF` (fullscreen) as unreachable,
+   kept on purpose (no fullscreen on iPhone) and named in the hand-back.
+
+## Common mistakes
+
+- A rotate card over a blank screen, or none on a landscape game.
+- Trusting `safeArea.insets()` without the `--sai-*` bridge: zeros, and the HUD hugs the edge.
+- A toast per repeat: ×n badges heap over play (one game's `look --hud` found eight at once).
+- A tip banner over the board: a ghost finger that swipes once and fades at the first move teaches
+  by play.
+- A layer faded to opacity 0 but left in the tree: it still covers the play and still animates
+  (one game's HUD read 41% until faded layers went `visibility: hidden`).

package/plugins/cursor/skills/funpixel-mobile-ui/references/contrast.md

@@ -0,0 +1,123 @@
+# Contrast by arithmetic
+
+Vision reviewers pass unreadable text: cream on mustard went through three of them. A ratio does
+not. Compute it for every pair the game draws and put the numbers in a self-test, so a palette
+change that breaks legibility fails verify instead of shipping.
+
+## Worked out for you
+
+`npx @funpixel/tools look set` and `look report` do this arithmetic for the starters' pairs (ink on
+the page, plate ink on the plate, the accent on a plate, the primary button's label, icons) at every
+change of `src/look.json`, and propose the ink that passes: the failing colour's lightness walked
+away from its ground, hue kept. `check` repeats it. The pairs below are the ones a game adds.
+
+## The pairs to check
+
+Only pairs that appear on screen, each as foreground on the background it actually sits on:
+- body and HUD text on its panel or on the scene behind it;
+- labels on primary and secondary buttons;
+- danger or warning colours used as text (a red "Low fuel" on dark blue);
+- icons and control edges against what surrounds them;
+- text over a painted or photographic background: sample the lightest and darkest area under the
+  text, and check both.
+
+## The thresholds (WCAG 2 AA)
+
+| What | Minimum |
+|---|---|
+| Body text, HUD numbers, labels | 4.5:1 |
+| Large text: 24 px and up, or 18.7 px and up in bold | 3:1 |
+| Icons, control boundaries, focus rings | 3:1 |
+
+## The formula
+
+Relative luminance of an sRGB colour, channels in 0 to 1:
+
+```ts
+const lin = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+function luminance(hex: string): number {
+  const n = parseInt(hex.replace('#', ''), 16);
+  const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => lin(v / 255));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+```
+
+Worked numbers: cream `#F4E9D8` on mustard `#D9A21B` is 1.9:1; white on the same mustard is only
+2.3:1, which is why "just use white" is not the fix.
+
+## Deriving an ink that keeps the hue
+
+A failing text colour is replaced by one of the same hue and saturation, moved in lightness until
+it passes. That keeps the palette's character, where a swap to white or black flattens it.
+
+```ts
+function hexToHsl(hex: string): [number, number, number] {
+  const n = parseInt(hex.replace('#', ''), 16);
+  const [r, g, b] = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => v / 255);
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2, d = max - min;
+  if (d === 0) return [0, 0, l];
+  const s = d / (1 - Math.abs(2 * l - 1));
+  const h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  return [(h * 60 + 360) % 360, s, l];
+}
+function hslToHex(h: number, s: number, l: number): string {
+  const c = (1 - Math.abs(2 * l - 1)) * s, x = c * (1 - Math.abs(((h / 60) % 2) - 1)), m = l - c / 2;
+  const [r, g, b] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x]
+    : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  return '#' + [r, g, b].map((v) => Math.round((v + m) * 255).toString(16).padStart(2, '0')).join('');
+}
+/** The closest same-hue ink to `seed` that reaches `min` on `bg`, darker or lighter. */
+function deriveInk(seed: string, bg: string, min = 4.5): string | null {
+  const [h, s, l0] = hexToHsl(seed);
+  for (let step = 0; step <= 100; step++) {
+    for (const l of [l0 - step / 100, l0 + step / 100]) {
+      if (l < 0 || l > 1) continue;
+      const ink = hslToHex(h, s, l);
+      if (contrast(ink, bg) >= min) return ink;
+    }
+  }
+  return null;                                          // no ink of this hue passes: change the background
+}
+```
+
+For cream text on mustard, `deriveInk('#D9A21B', '#D9A21B')`, seeded with the mustard's own hue,
+returns `#513C0A` at 4.6:1. Taking a little margin (lightness 16%) gives `#493609` at 5.0:1: a deep
+brown that still reads as part of the same palette and survives dimmer screens.
+
+## The self-test
+
+Read the colours from the CSS custom properties the game already uses, so the test follows the
+palette instead of a copy of it:
+
+```ts
+const css = getComputedStyle(document.documentElement);
+const v = (name: string) => css.getPropertyValue(name).trim();
+const PAIRS: [string, string, number][] = [
+  ['--ink', '--panel', 4.5],
+  ['--on-primary', '--primary', 4.5],
+  ['--danger', '--bg', 4.5],
+  ['--icon', '--control-bg', 3],
+];
+window.__FPX_SELFTEST__ = [
+  ...(window.__FPX_SELFTEST__ ?? []),
+  ...PAIRS.map(([fg, bg, min]) => ({
+    name: `contrast ${fg} on ${bg} >= ${min}`,
+    run: () => contrast(v(fg), v(bg)) >= min,
+  })),
+];
+```
+
+The properties must hold plain hex values for this to parse; resolve any `var()` chains to hex
+first.
+
+## What contrast does not cover
+
+- Text over a moving scene: add a panel, a scrim or an outline, then check the text against that.
+- Colour as the only signal (red means danger): pair it with a shape or a word, since some players
+  cannot tell the hues apart.
+- Size: a passing ratio at 9 px is still unreadable on a phone. Text sizes come from `clamp()` with
+  a sensible floor (about 12 px for secondary text, more for anything read during play).