@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-art/references/cost.md

@@ -0,0 +1,107 @@
+# What effects cost, and how to find out
+
+Numbers from the recipe lab (28 Sep 2026): a scratch scaffold per engine, each recipe a declared
+view, profiled with `npx @funpixel/tools profile` at the phone viewport (844×390 CSS px, DPR 2, so
+a 1688×780 canvas). "Desktop GPU" = Apple M4 Max through ANGLE/Metal, where everything held the
+display's 60 fps. "Software" = SwiftShader (`--software`), a CPU renderer much slower than any
+phone GPU, which is exactly why fill cost shows there. The machine was busy (load average near 34
+from other jobs), which is why the timing numbers carry their spread.
+
+## The profile loop (the Astra method)
+
+1. Name a view (`playing`, `boss`, `reveal`) and pin what varies: viewport, seed (`--seed`, which
+   sets `window.__FPX_SEED__` before the game runs; read it in your RNG), renderer.
+2. `npx @funpixel/tools profile --views reveal,playing --repeat 3` before the change. The file
+   lands in `.funtools/profile/<view>-<viewport>.json`.
+3. Change one thing. Run the same command. It prints each number that moved, with its percentage.
+4. Keep a control view in the same run (a view you did not touch). If the control moved as much as
+   the view you changed, the timing difference is the machine, not your change.
+
+Which numbers to trust:
+
+| Signal | Stable between runs? | What it tells you |
+|---|---|---|
+| draw calls, triangles | yes | how many times and how much the GPU is asked to draw |
+| scene counts (sprites, meshes, instances, particles, filtered objects, shadow lights) | yes | what the frame is made of |
+| texture MB (estimated) | yes | memory the effect holds (filters and bloom allocate render textures) |
+| fetched KB, dist KB by kind | yes | what a player downloads |
+| JS work a frame | fairly | CPU time in the game's frame callbacks; not capped by vsync |
+| frame ms p50/p95 | no, on a busy or fast machine | on a desktop GPU it sits at 16.7 (vsync); on software it moves with load |
+
+## Measured, Pixi 8.21 (phone viewport)
+
+| View | Draw calls | Texture MB | Notes |
+|---|---|---|---|
+| base (the lab world) | 1 | 0.1 | everything batches into one call |
+| additive glow sprites | 3 | 0.2 | cheapest way to make light |
+| `AdvancedBloomFilter` on the lantern layer | 9 | 2.1 | filters allocate render textures |
+| `OutlineFilter` on the hero | 3 | 0.1 | |
+| grade: colour matrix + vignette on the world, `resolution: 'inherit'` | 3 | 10.2 | full-screen at DPR 2 |
+| the same grade at resolution 1 | 3 | 4.1 | softer on a DPR 2 screen |
+| `DisplacementFilter` on the pond | 4 | 0.3 | |
+| 400 particles in a `ParticleContainer` | 2 | 0.1 | one call for all particles |
+| `MeshRope` trail | 2 | 0.1 | |
+| night (multiply layer + additive lights) | 3 | 0.4 | |
+| godrays + shockwave + blur on the world | 8 | 8.1 | a moment, not a steady state |
+
+Software renderer, grade at `'inherit'` vs resolution 1, median of 3: frame p50 66.6 → 50 ms,
+while the untouched base view moved 50 → 83 ms between the same runs. The texture memory
+(10.2 → 4.1 MB) is the reliable part of that comparison.
+
+## Measured, three 0.170 (phone viewport)
+
+| View | Draw calls | Triangles | Software p50 (median of 3) |
+|---|---|---|---|
+| base (60 instanced trees, pond, hero, lanterns) | 15 | 5,168 | 16.7 ms |
+| `UnrealBloomPass` + `OutputPass`, half-res on phones | 29 | 5,182 | 49.9 ms |
+| fog + sky dome | 16 | 5,696 | 16.7 ms |
+| shadow map (PCF soft, fitted camera) | 28 | 10,256 | 16.7 ms |
+| blob shadow instead | 16 | 5,170 | 16.7 ms |
+| AgX tone mapping | 15 | 5,168 | 16.7 ms |
+| 1,200 additive points | 16 | 5,168 | 16.7 ms |
+| inverted-hull outline on the hero | 16 | 5,576 | 16.7 ms |
+| wow (bloom swell + camera ease + 1,200 sparks) | 30 | 5,182 | 66.7 ms |
+
+Reading it: post-processing is the expensive thing (a full-screen pass per bloom mip, every
+frame); a shadow map doubles the draw calls and triangles (the scene is drawn again from the
+light); fog, tone mapping, points and a hull outline are nearly free.
+
+## Quality tiers
+
+Decide once, from the device, and step down if the first seconds run slow:
+
+```ts
+const coarse = matchMedia('(pointer: coarse)').matches;
+export const quality = {
+  dpr: Math.min(devicePixelRatio, coarse ? 2 : 2.5),
+  bloomScale: coarse ? 0.5 : 1,          // UnrealBloomPass resolution, or a Pixi filter's resolution
+  shadowMap: coarse ? 1024 : 2048,       // or 0 for blob shadows
+  particles: coarse ? 300 : 1200,
+  filterResolution: coarse ? 1 : 'inherit' as const,
+};
+// After the first 2 s of play: if the median frame is over ~22 ms, drop a tier (bloom off, fewer particles).
+```
+
+Headless numbers are not a phone's. When a phone is at hand, play the heaviest view on it; the
+profile tells you what changed, the phone tells you whether it matters.
+
+## Reduced motion and comfort
+
+- `matchMedia('(prefers-reduced-motion: reduce)')`: keep colour, light and glow; drop camera
+  moves, screen shake, big distortion (shockwave, heavy displacement), fast flicker; cut particles.
+- Avoid full-screen flashes brighter than the scene for more than a frame or two, and anything
+  flashing three or more times a second.
+- A settings toggle for effects the game leans on (bloom, shake, particles) is cheap and kind.
+
+## Silent traps met in the lab
+
+- Pixi: a top-level `await app.init()` in the entry module never resolved (Vite's renderer chunk
+  imports the entry back). No error; the canvas never appeared. Initialise inside a function.
+- Pixi: a custom filter redeclaring `uInputSize` in its fragment shader failed to link
+  ("precisions differ"), and everything under it rendered black. Pass a varying from the vertex.
+- Pixi: filters render at resolution 1 by default, soft on a DPR 2 phone.
+- Three: with an `EffectComposer`, tone mapping and sRGB conversion happen in `OutputPass`; leave
+  it out and the image is dark.
+- `profile` reads Three through `window.__THREEJS_RENDERER__` and `__THREEJS_SCENE__`, and Pixi
+  through `window.__PIXI_APP__`; without them it still counts WebGL draw calls but cannot say what
+  the scene holds.

package/plugins/kiro/skills/funpixel-art/references/effects.md

@@ -0,0 +1,85 @@
+# Visual effects: light, air and the big moment
+
+Effects are how a flat scene becomes a place at a time of day, and how a payoff becomes a moment
+someone remembers. They are also the easiest way to lose a phone's frame rate. This skill is a
+shelf of working recipes for Pixi 8 and Three.js, each run and captured in a scratch scaffold, with
+what each one measured. Pick what serves the look the game chose; a clean flat style may want none.
+
+## Tools
+
+- `capture_view`, or `npx @funpixel/tools capture --view <name> --viewport phone`, to see an effect
+  at phone size; `capture_view` on a `moment: true` view shoots a burst of the payoff.
+- `npx @funpixel/tools profile --views <name>`: frame times, the JS work of a frame, draw calls,
+  triangles, the scene by kind, texture memory and load, saved per view; the next run prints the
+  change. `--software` renders on the CPU so fill cost shows; `--repeat 3` steadies a noisy machine.
+  Funpixel's in-app builder samples with the same page script, so the numbers read alike.
+- `inspect_scene`, locally `npx @funpixel/tools scene`, lists what the scene holds.
+- `generate_skybox` for a 3D sky, `find_material` and `get_material` for Poly Haven HDRIs;
+  `generate_image` for a light cookie, a noise map or a painted sky gradient if code will not do.
+
+## The shelf
+
+| Effect | Pixi 8 | Three.js | Recipe |
+|---|---|---|---|
+| Glow around bright things | additive light sprite; `AdvancedBloomFilter` on the bright layer | emissive + `UnrealBloomPass` | [pixi](pixi.md#glow-and-bloom), [three](three.md#bloom) |
+| Mood and colour | `ColorMatrixFilter` + a custom vignette/shadow-tint filter | tone mapping (ACES, AgX) + exposure | [pixi](pixi.md#grade), [three](three.md#tone-mapping) |
+| A readable hero | `OutlineFilter` | inverted-hull outline | [pixi](pixi.md#outline), [three](three.md#outline) |
+| Water, heat, magic | `DisplacementFilter` with a scrolling noise map | a shader on the surface | [pixi](pixi.md#water) |
+| Particles | `ParticleContainer` + `Particle`, a fixed pool | `Points` with an additive soft sprite | [pixi](pixi.md#particles), [three](three.md#particles) |
+| Trails | `MeshRope` along recent positions | a ribbon or `Points` history | [pixi](pixi.md#trail) |
+| Night and lights | multiply darkness + additive lights | light colour, intensity, fog | [pixi](pixi.md#night), [three](three.md#time-of-day) |
+| Depth and air | lighter, bluer far layers | fog in the sky's colour + a sky dome | [three](three.md#atmosphere) |
+| Shadows | a soft blob under each actor | fitted shadow map, or blob shadows | [three](three.md#shadows) |
+| Time of day | keyframed tints | sun angle, colours, fog, sky | [pixi](pixi.md#time-of-day), [three](three.md#time-of-day) |
+| The reveal | shockwave + godrays + a blur settle | camera ease-in + bloom swell + sparks | [pixi](pixi.md#the-wow-beat), [three](three.md#the-wow-beat) |
+
+## Craft on the shelf
+
+1. **Start from the frame you want.** Name the time of day, the light source and what should glow.
+   An effect that is not in that sentence is probably noise.
+2. **Effect the few, not the stage.** A filter on the whole stage re-renders every pixel every
+   frame; put it on the layer that needs it (the lanterns, the water, the hero). Save full-screen
+   passes for the grade and the reveal.
+3. **Glow picks its source.** In Three, bloom whatever is emissive above the threshold and keep
+   the rest under it; in Pixi, bloom the bright layer only, or fake glow with additive sprites.
+4. **Budgets as constants.** Particles come from a fixed pool whose size is one number you can
+   change per quality tier; a burst reuses dead particles.
+5. **Quality tiers.** Decide once at start (and after a slow first second): phones get half-res
+   bloom, a 1024 shadow map or blob shadows, fewer particles, a DPR cap of 2. Details and the
+   measured costs: [cost.md](cost.md).
+6. **Reduced motion.** Under `prefers-reduced-motion`, keep light and colour, drop shake, big
+   distortion and camera moves, cut particle counts. The recipes read this flag.
+7. **Measure the change.** Profile the view before and after an effect, same viewport, same seed.
+   Counts (draw calls, triangles, texture MB) are stable; frame times move with the machine, so
+   repeat and compare against a control view in the same run.
+8. **Look at it at phone size.** Capture before, during and after a reveal; effects that read at
+   1440 px can turn to mush at 390.
+9. **In a whole 3D game, read the slow frames.** Averages hide hitches: read p95/p99 at a named
+   beat (the first fight, not the whole run), and name what appeared on each slow frame (a shader
+   compile, a texture upload) before fixing it. Warm-up, culling skinned actors, a pixel budget,
+   pacing to the refresh, and the leaks one game met: [frames.md](frames.md).
+
+## Worked example
+
+A dusk valley in Pixi with five lanterns. The lab's base view profiled at 1 draw call; additive
+halos per lantern took it to 3 with no change in JS work, and read as warm light in the capture.
+`AdvancedBloomFilter` on the lantern layer only: 9 draw calls and 2.1 MB of filter textures. A
+full-screen grade (colour matrix and vignette) at `resolution: 'inherit'` held 10.2 MB of filter
+textures; at resolution 1 it held 4.1 MB, and on the software renderer its frame p50 went 66.6 →
+50 ms (the control view moved 50 → 83 ms in the same runs: the texture number is the solid one). The game kept the halos, the lantern bloom and a resolution-1 grade.
+
+## Common mistakes
+
+- A filter or bloom on the whole stage when one layer needed it: every pixel pays, every frame.
+- Top-level `await app.init()` in the entry module: Vite's renderer chunk imports the entry back
+  and the page never starts, with no error. Initialise inside an async function.
+- A custom Pixi filter that redeclares `uInputSize` in the fragment shader: the precisions differ
+  from the vertex stage and the program fails to link (a black screen). Pass a varying instead.
+- `EffectComposer` without `OutputPass`: colours come out dark and tone mapping is skipped.
+- A white starburst or full-screen flash on contact: one racer's (Oct 2026) read as glare, one 38% clipped.
+  A small warm glow at the contact point, about 0.16 s, answers the hit.
+- Dither or halftone transparency in a shader: at phone size it reads as a glitch. Fade in broad, slow bands or
+  real alpha. To find which module owns a fault, capture with one module off
+  ([judging-frames.md](judging-frames.md)).
+- An additive volume checked only at the hero distance: seen down its own axis at melee range, a
+  summed beam became a white disc that hid the enemy. Soft-clip the sum and look up close.

package/plugins/kiro/skills/funpixel-art/references/frames.md

@@ -0,0 +1,87 @@
+# Smooth frames in a whole 3D game
+
+The recipe lab ([cost](cost.md)) measures one effect in a small scene. A whole game adds things a
+lab never meets: first-use compiles, a crowd of skinned actors, level rebuilds, big retina windows
+and displays faster than 60 Hz. This is what one game (a three.js third-person horror game, 29 Sep
+2026, `design/PERF.md` in its repo) measured, and what each fix bought. The numbers are that game's
+on that machine; the causes recur.
+
+## Smooth is a distribution, not an average
+
+At 78 fps average that game still stuttered. Read p95, p99 and the worst frame, and where the slow
+frames land. Then name each slow frame's cause before changing anything: on a hitch frame, read
+`renderer.info` for what appeared (new shader programs, textures, geometries). Every hitch it
+found had a cause that showed there.
+
+Profile the named beat, not the whole run. A whole-run phone profile read p95 16.8 ms, mostly
+exploring; `funtools profile --views firstWalker --viewport phone --throttle 4` on the first fight
+read p95 33.4 ms (about 41 fps). The fight is the phone's worst case, and the average hid it.
+
+Profile vsync-capped, as a player sees it. An uncapped run (`--disable-frame-rate-limit`) fooled
+the game's own refresh detection into cutting resolution at 2.5 ms frames. And profile on a machine
+nobody is playing on: films and profilers share the GPU and read as lag to the player.
+
+## What that game found, and what each fix bought
+
+| Symptom | Cause (measured) | Fix |
+|---|---|---|
+| 57–88 ms hitches at 0.7–1.3 s and at the first fight | a new shader program compiling on first use (her first steps; the first severed limb, a static copy of a skinned material, is its own program) | a warm-up behind the chapter card: `renderer.compile`, `initTexture` on every texture, then one frame with everything visible and nothing culled, plus one throwaway of each thing that can spawn mid-play. All 88 programs compiled before play |
+| a 76 ms phone frame at 1.2 s | 57 bone textures created lazily when the rigs first updated, after the warm-up | build every rig before the warm frame |
+| phone frames flipping 15 ↔ 33 ms (p95 31.5) | CPU-bound on three's per-object work: 506 draw calls, 1.3 M triangles, 274 shadow casters | the next five rows |
+| every enemy drawn, animated and shadowed everywhere | skinned meshes run with `frustumCulled = false` (bind-pose bounds lie), so nothing culled them | cull by hand: drawn and animated within 8 m, or on screen within 30 m (a sphere against the frustum); hidden rigs set `matrixWorldAutoUpdate = false` so three skips their bones |
+| the torch's shadow pass redrew most of the level | 274 casters, every wall module and prop | the environment receives but does not cast; one merged wall mesh still casts so light never leaks through a wall |
+| static geometry never culled | batches merged per material across the whole level | merge per material and per 10 m tile |
+| everything drawn to 80 m | fog is total by about 34 m (FogExp2 0.058) | `camera.far = 36` |
+| 594 matrices recomputed a frame | statics left with `matrixAutoUpdate` on | off for statics, and `matrixWorldAutoUpdate = false` once placed |
+| 3–4% of main-thread time in one HUD helper | reading `innerWidth` after the HUD wrote styles forces a layout, several times a frame | cache the size on `resize`; read the cache |
+
+Results on the same recorded run: desktop 1600×900 @2x worst frame 87 → 29 ms (5 hitches → 0 over
+33 ms); phone 844×390 @3x with the CPU ×4, p95 31.5 → 16.8 ms; draw calls 506 → 298 and triangles
+1.3 M → 0.69 M on the first-fight frame.
+
+## Big windows and fast displays
+
+A 1950×1090 window at pixel ratio 1.5 is 4.8 M pixels through AO, depth of field and bloom:
+GPU-bound (p99 26 ms). On a 120 Hz display, 9 ms frames flip between 8 and 16 ms and judder.
+
+- **A pixel budget** caps the ratio by pixel count (that game: 2.6 M on desktop, 1.3 M on a phone);
+  the DOM HUD stays at full retina.
+- **Pace to the refresh.** Detect the refresh from the fastest frames, judge each second's p90
+  against that slot, and when 120 cannot hold, lock to 60 (render every other refresh) before
+  lowering resolution.
+- **Hysteresis.** Each resolution change rebuilds the post-processing targets (41 textures, a 70–100
+  ms frame), so an oscillating scaler stutters every few seconds. Its rule: no step up within
+  12 s of a step down, five fast seconds to earn one, none after two downs.
+
+Result: 119.2 fps on a 120 Hz display at 1950×1090 @2x, p99 9.4 ms, worst 17.5 ms, zero hitches.
+
+## Leaks that read as "it gets laggy after a while"
+
+The Funpixel profiler (`funtools profile`, and `window.__funpixelProfiler.getReport()` in dev) found
+what the game's own tools missed: +405 textures on every level rebuild, never freed, which every
+death's Retry triggered. `renderer.info.memory` went 957 → 1362 → 1767 → 2172 → 2577 over four
+rebuilds. A rebuild disposes each old `SkinnedMesh.skeleton` (its bone texture), the per-build
+materials and their canvas textures, and keeps the shared model materials whose images are reused.
+Reading `renderer.info.memory` before and after a Retry catches it.
+
+Draw calls counted at the WebGL call (verify's renderer note: 494 desktop, 511 phone) include
+every pass (shadow, AO, beauty, post); one `composer.render()` counted 298. Know which one a number
+is before comparing.
+
+A title faded to opacity 0 kept animating its Ken Burns and motes over the canvas every frame, and
+`audit-screens` saw it cover the play in 25 of 25 views. `visibility: hidden` once the fade ends,
+with its animations paused, removed it.
+
+## When something glows that should not
+
+"Anything that looks like a white ball is a light" held four times in that game: the torch's
+hotspot on a close surface, the beam cone seen end-on, coral pushed past the bloom's white point,
+and the worst one, an additive ray-marched beam seen down its own axis. From the camera behind her,
+the view ray ran down the whole lit cone and eight summed samples bloomed into a white disc that
+hid an enemy at knife range. It was found only by asking "what is that?" of a melee still and hiding
+one thing at a time.
+
+- Soft-clip any additive sum (`1 - exp(-x)`), and thin a volume when the view runs along its axis.
+- Check effects at melee range, not only at the hero distance the recipe was tuned at.
+- An on/off A/B is only honest when the frame's own update does not re-set what you turned off
+  (the torch and emissives were re-posed every frame; the albedo was not).

package/plugins/kiro/skills/funpixel-art/references/judging-frames.md

@@ -0,0 +1,64 @@
+# Judging frames against the targets: a fixed rubric, fixes by module, eye comfort
+
+From a Unity 6 3D racer (Oct 2026) built by several module agents (world, racers, levels) and one
+integrator. An independent judge scored real captures against the painted targets every round; what follows is
+what held up, with its numbers. `funtools score` measures the same frames (layout, palette and light, density,
+comfort); this is the judge that reads what numbers cannot.
+
+## The rubric, fixed before the frames
+
+| Category | Points | What it reads |
+|---|---|---|
+| Composition | 30 | the camera, where the eye goes, what fills the frame, the pack or cast on screen |
+| Light | 25 | a key light, a rim, depth in the air, the contrast range (deep darks under bright cores) |
+| Detail | 25 | authored surfaces (rivets, frost, glass) rather than primitives with a streaky texture |
+| Effects | 20 | trails, glows and weather that read as the target's and do not strain the eye |
+
+- **The same rubric every round**, written before seeing the frames, so a score moves only when a frame changed.
+- **Full-resolution phone captures from the real build** (the player on the target device size, not the editor, not
+  a web stand-in): the racer judged 1172×2532 frames; half-size shots hid the material detail being scored.
+- **Per frame:** a total, the four category scores, the change since last round, and one eye-comfort word
+  (yes, mild, glare, busy, no): could a person look at it for a minute without strain?
+
+## Fix lists tagged by module
+
+Every fix names the module that owns it, `[WORLD]`, `[RACERS]`, `[LEVELS]` (or the game's own lanes), with the
+frame, the pixel region and the number: "[WORLD] the sun bloom washes out the upper right (11% clipped): bloom
+intensity −50%, exposure −0.4 EV". The integrator routes each tag to that module's agent (its lane, where
+`funtools lanes` runs them), so no agent reads another's list. End with the five changes that would raise the average most,
+each with its expected gain; the racer's round-2 list predicted 76–80 from 64.
+
+**Find the owner before assigning a fault.** Capture the same frame with one module turned off (a launch flag
+per module: no world dressing, no racer effects). The fault that disappears belongs to the module that was off;
+a stripe under the racer that stays with the effects off is not the effects agent's.
+
+## Read the categories, not only the total
+
+The racer's round 2 rose 55.6 → 64.2, but composition gave +5.1 and effects +2.2 while light gave +0.7 and
+detail +0.6: the gain came from removing noise (a white halo, crossing speed lines, a fourth trail), not from
+adding quality. Calm is not finished. When light and detail stall, give materials and lighting a round of their
+own (per place: a key light, a rim, a regrade, authored hero surfaces, a bake-off of each hero asset against
+its target) rather than another effects pass.
+
+## Eye comfort: match the targets' quality, not their density
+
+Generated targets are busier than a game should be. The owner rejects crowded, noisy, tiring worlds, and calmer
+frames than the targets are the goal, as long as the quality matches.
+
+- `funtools score` prints each frame's **busyness** (the mean brightness step between neighbouring pixels on a grey
+  copy 360 px on its short side) and **clipped share** (pixels at luma ≤ 2 or ≥ 253) beside its target's, and
+  stamps the zero board's `comfort` counter. It warns, never fails: over 14, over 1.25× the targets' busiest, or
+  over 6% clipped. The racer's painted targets read 9.2–15.4 there and its web frames 6.9–8.5; our liked
+  games' frames 2.0–11.9; one heist game's room read 7.8% clipped before its light round and 0 after.
+- A calm frame has room for detail: add mid-ground surface detail at about half the target's density, low
+  contrast and slow (the racer's near road, on its judge's own scale: a bottom-quarter gradient of about 3,
+  against 1–2 then and 5–6 in the targets).
+- Clip sources are fixes, not taste: blown bloom, a white flash, an emissive that clips to white instead of
+  keeping its colour (clamp it).
+
+## Framing calls are the owner's
+
+A rubric's framing numbers are a judge's proposal. The racer's rubric asked for the racer at 80% of the frame
+width; the owner settled on about 40%. Record the owner's number as a rule in the GDD (a tuning row), tell the
+judge it is fixed and not to mark it down, and judge what fills the space the smaller hero leaves instead. Ask
+the owner before a judge's hero size, camera height or crop becomes a fix.

package/plugins/kiro/skills/funpixel-art/references/look.md

@@ -0,0 +1,102 @@
+# Art direction for a Funpixel game
+
+Choose a look that serves the player, then prove it in the running game. A simple style still owes
+clear silhouettes, coherent screens and feedback. Name stand-ins as stand-ins.
+
+## Match the scope
+
+For an asset repair or a supplied look, use the accepted asset, style guide and real background.
+Identify what is locked (identity, palette, silhouette) and what may change. A moodboard offers
+possibilities; only the brief or agreed style rules make them binding.
+
+For an unresolved direction, explore a few alternatives, a familiar one and an unexpected one;
+`npx @funpixel/tools variety` shows which games on this machine a choice sits close to. For a new complete
+game, the moves below are what held our bar games' looks together.
+
+## Establish the look
+
+1. **State the choice.** In the design document (`design/GDD.md`, skill `funpixel-gdd`), name
+   the medium, palette roles, camera and why they suit this game's audience and actions. Before a new complete
+   game's code, the style bible (skill `funpixel-gdd`, the greenlight) holds it: several directions
+   tried, a plain one pushed up with a concrete note ("too simple: richer colour, more contrast"),
+   and a route for every asset (generated, authored, or
+   procedural proven by a rendered study; "primitives for now" is a stand-in, not a route).
+   At the first look the world's kit stands beside the hero: sheets of its structures, ground,
+   props and living cast, cut (`npx @funpixel/tools cut`) before the slice is built from them;
+   without it one fresh build coded its world from shapes.
+2. **Write five AD rules.** The critic panel reads them:
+   each checkable in a frame (colour roles, outline weight, light, material, actor readability at
+   a stated phone size); no universal percentage for hero size.
+3. **Make a target frame,** so captures have something to be measured against: `design/target.png`
+   at the real aspect, showing play area, player, threat or puzzle element, an action moment and HUD. It may be drawn, generated or rendered
+   from a small procedural study. Label its origin and status; a mock-up describes intent, never
+   proves gameplay or approval.
+4. **Compare the implementation.** Capture at the target's viewport and measure gaps in
+   play-area share, actor size, HUD coverage and colour roles. Fix framing in layout before
+   paying for new art. Check phone and desktop; a rule revised to excuse a defect stops measuring anything.
+   For a game with a moment ladder, a target frame per moment and captures of the same seconds
+   from a recorded run make a loop: name the biggest difference, fix it, recapture. Judge
+   generated models under the game's own light, where one game's near-black textures were
+   lifted into white blow-outs. Both, with what they found:
+   [prompts.md](prompts.md#target-frames-at-moments-and-the-loop-that-closes-the-gap).
+   Match the targets' quality, not their density (`score` warns on a busy or clipped frame); the rubric,
+   fixes by module and the owner's framing calls: [judging-frames.md](judging-frames.md).
+5. **Direct the UI too.** The HUD and the screens are part of the look: plates of the world's
+   material made as art, a display face, one icon family drawn like the art, a target for the HUD
+   and one for the title, the game's first promise. Undirected, every game kept the scaffold's
+   dark pills: [ui.md](ui.md).
+
+## Tools
+
+- Use `generate_image` for a target or world art, `generate_sprite` for isolated objects;
+  [2d-assets](2d-assets.md) covers sheets, transparency, packing and loading.
+- Check the tool's current estimate, total the planned jobs and follow the brief's spending
+  authorization. Reuse accepted assets first. Candidate batches are optional and reserved for
+  a target, hero or key art where the comparison is worth its cost.
+- Before the game exists, `npx @funpixel/tools look --sheet` puts every sprite at play heights
+  (24, 48, 96 px) on a neutral band and on the real ground colour (`roles.ground` or `--ground`)
+  and measures each against it. One game's sheet found its terracotta army vanishing on the
+  pass floor at 24 px before any game code.
+- A pixel-art look can be exact rather than imitated: `pixelArt` (scale, palette) in
+  `funpixel.json` has `assets process` and `gen` snap every picture to the grid and palette, and
+  `npx @funpixel/tools assets pixels` measures soft edges and stray inks ([2d-assets](2d-assets.md)).
+- For a new asset family, record `assets/style.json` before expanding the set
+  ([style-file.md](style-file.md)). Reuse its medium, family clause and
+  exclusions; vary the intended subject or repair while keeping the other choices stable. Pass a world style frame for scenery and an isolated hero
+  reference for characters. A landscape reference alone tends to produce scenery.
+- Write three to six measurable acceptance lines per asset type before seeing the result.
+  Examples: [prompts.md](prompts.md).
+- Fix the cheapest way that preserves identity: layout, crop/alpha repair, an edit, or a new
+  generation. Keep the source; recheck edges, silhouettes and palette on the real background. One variable per round keeps each change attributable; Scenario's
+  stop rule (three rounds without a clean one, or one line failing two fixes) is where naming the
+  remaining miss usually beats another paid round.
+- Start independent jobs together and collect by id with `get_job`; after a timeout, collect
+  rather than submit again. `npx @funpixel/tools job <id> --wait --out <path>` saves provenance.
+  Without MCP, `gen image|sprite` uses a paid key; lacking a key does not preclude authored art.
+
+## Check before handing back
+
+For a focused repair, compare the accepted baseline and repaired asset on the actual background
+at display size, then the changed in-game view. Check the stated repair and preserved
+identity; no new target or full critic panel is required.
+
+For a new asset family, compare contact sheets on the actual ground and current in-game captures.
+For a complete-game review, the `art-director` checks target consistency and the blind `critic`
+panel judges what shipped. Generation receipts prove origin and spend, not visual quality.
+Name failed jobs, stand-ins and provisional choices. In a 3D game, `npx @funpixel/tools look --3d`
+says whether the heroes are code primitives or models; code-built heroes are a style only when
+funpixel.json `art3d` declares it with its reason and a proof frame (skill `funpixel-3d`).
+
+## Worked example
+
+One game's sandstone rooms wore dark pills: `look --hud` read system type, 20 dark plates and
+the scaffold's glyphs. A `## UI` section chose sandstone plaques, a carved face and an inked icon
+family; a generated plate went in through `border-image`.
+
+## Common mistakes
+
+- Text and glyphs drawn into generated art blur and cannot change (the wordmark excepted).
+- Long prompts and chains of edits: each drifts, so work from the accepted baseline.
+- Calling the declared medium a defect: inconsistent execution is the defect, not the medium.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

package/plugins/kiro/skills/funpixel-art/references/measure.md

@@ -0,0 +1,119 @@
+# Measuring a generated image
+
+Detail for step 6 of [2d-assets](2d-assets.md) and the alignment pass in [sheets.md](sheets.md). Use
+the verdict the tool returns when it returns one; use this when it does not, or to check a
+suspicious pass.
+
+The snippet needs no dependencies. Paste it into the running game's page (`npx @funpixel/tools
+dev`, then your browser tool's evaluate step or the devtools console) and call it with the served
+path. It reads pixels only; it changes nothing.
+
+```js
+async function measure(url, { roles = [], cols = 1, rows = 1 } = {}) {
+  const img = await createImageBitmap(await (await fetch(url)).blob());
+  const c = new OffscreenCanvas(img.width, img.height);
+  const g = c.getContext('2d');
+  g.drawImage(img, 0, 0);
+  const { data, width: W, height: H } = g.getImageData(0, 0, img.width, img.height);
+  const px = (x, y) => { const i = (y * W + x) * 4; return [data[i], data[i + 1], data[i + 2], data[i + 3]]; };
+  const hsl = ([r, gg, b]) => {
+    r /= 255; gg /= 255; b /= 255;
+    const mx = Math.max(r, gg, b), mn = Math.min(r, gg, b), l = (mx + mn) / 2, d = mx - mn;
+    if (!d) return [0, 0, l];
+    const s = d / (1 - Math.abs(2 * l - 1));
+    const h = mx === r ? ((gg - b) / d) % 6 : mx === gg ? (b - r) / d + 2 : (r - gg) / d + 4;
+    return [(h * 60 + 360) % 360, s, l];
+  };
+  const hexHue = (hex) => hsl([1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)))[0];
+  const roleHues = roles.map(hexHue);
+  const hueDist = (a, b) => Math.min(Math.abs(a - b), 360 - Math.abs(a - b));
+
+  let clear = 0, coloured = 0, onRole = 0;
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const p = px(x, y);
+    if (p[3] < 16) { clear++; continue; }
+    const [h, s] = hsl(p);
+    if (s < 0.15) continue; // ink, greys and whites carry no hue
+    coloured++;
+    if (roleHues.some((rh) => hueDist(h, rh) <= 20)) onRole++;
+  }
+  const corner = (x0, y0) => {
+    let a = 0, n = 0; const hs = [];
+    for (let y = y0; y < y0 + 8; y++) for (let x = x0; x < x0 + 8; x++) { const p = px(x, y); a += p[3]; n++; hs.push(hsl(p)[0]); }
+    return { alpha: Math.round(a / n), hue: Math.round(hs.sort((p, q) => p - q)[hs.length >> 1]) };
+  };
+  const cw = Math.floor(W / cols), ch = Math.floor(H / rows), cells = [];
+  for (let r = 0; r < rows; r++) for (let k = 0; k < cols; k++) {
+    let x0 = cw, y0 = ch, x1 = -1, y1 = -1; const colFill = new Array(cw).fill(0);
+    for (let y = 0; y < ch; y++) for (let x = 0; x < cw; x++) {
+      if (px(k * cw + x, r * ch + y)[3] > 128) { x0 = Math.min(x0, x); x1 = Math.max(x1, x); y0 = Math.min(y0, y); y1 = Math.max(y1, y); colFill[x]++; }
+    }
+    let best = [0, -1], run = null; // widest run of columns at least 3% occupied
+    colFill.forEach((n, x) => { if (n >= ch * 0.03) { run ??= x; if (x - run > best[1] - best[0]) best = [run, x]; } else run = null; });
+    cells.push(x1 < 0 ? { empty: true } : {
+      box: [x0, y0, x1, y1], bottom: y1, centre: best[1] < 0 ? (x0 + x1) / 2 : (best[0] + best[1]) / 2,
+      touchesEdge: x0 === 0 || y0 === 0 || x1 === cw - 1 || y1 === ch - 1,
+    });
+  }
+  return {
+    size: [W, H],
+    transparentShare: +(clear / (W * H)).toFixed(3),
+    corners: [corner(0, 0), corner(W - 8, 0), corner(0, H - 8), corner(W - 8, H - 8)],
+    onRoleShare: coloured ? +(onRole / coloured).toFixed(3) : null,
+    cells,
+  };
+}
+
+// await measure('assets/fox.png', { roles: ['#FF6B5A', '#E8D8B0', '#7FE0B0'] })
+// await measure('assets/fox-sheet.png', { cols: 4, rows: 2 })
+```
+
+## Reading it
+
+| Check | Pass | A fail means |
+|---|---|---|
+| `transparentShare` on a sprite asked to be transparent | 0.12 or more for a compact object; a failed key often reads under 0.05 | Inspect the plate; repair alpha if the subject can be preserved, otherwise regenerate |
+| `corners` alpha on a transparent sprite | all four near 0 | The subject or its scene reaches the edge |
+| `corners` hue on an opaque plate before keying | all four within about 20° | The model drew a scene, not a subject on a field |
+| `onRoleShare` | 0.85 or more | Inspect the mismatch; repair a local colour error or refine the generation clause |
+| `cells[i].touchesEdge` | false for every cell | Check actual clipping; repair if complete source pixels exist, otherwise regenerate or separate the effect |
+| `cells[i].bottom` spread across grounded frames | under 3% of the cell height | Feet jump; run the alignment pass |
+| `cells` count and `empty` | as many filled cells as frames asked for | Inspect indexing and slicing first; repair the layout or regenerate missing content |
+| `box` aspect | close to the brief (a tall knight is taller than wide) | Wrong framing, or a contact sheet of parts |
+
+Hue, not RGB distance, decides the palette check: the same colour in light and shadow is far apart
+in RGB and close in hue. Whites, greys and the ink outline carry no reliable hue, which is why
+pixels below 15% saturation are skipped.
+
+Numbers are the floor, not the verdict. A sprite that passes every row can still be the wrong
+character; compare it with the hero reference and the style frame on one sheet before wiring.
+
+Two optional checks see what numbers cannot, each one seat on your own agent (funtools calls no
+model; a seat reads each picture once, a few thousand tokens):
+
+- **Structure.** An artifact score has praised a car with two different wheels. `npx @funpixel/tools
+  judge structure <file|folder> --prompt "what it should be"` asks five fixed yes/no questions with
+  evidence: matched pairs, part counts, attachment, lettering, the frame. Any no fails, and it is
+  never averaged into a look score. On one generated four-pose bee set it caught tangled antennae
+  in one pose. Worth it for a hero, a face the player stares at, or anything with lettering.
+- **Identity.** `judge identity <frames|folder> --concept hero.png` holds every pose to the hero on
+  silhouette, palette, key features and proportions, and names the worst frame per trait. Major
+  drift fails, minor is said; an expression the pose asks for is animation, not drift.
+
+`judge report` reads the answer back: exit 0 pass, 1 fail, 2 not observed (nothing filed, a
+question left without evidence, or the picture changed since).
+
+When a check fails, diagnose the cause before choosing a repair. For an accepted sprite with an
+alpha fringe, preserve the original and repair the alpha or edge without changing its silhouette,
+colours or identity. A crop is appropriate only when it removes unwanted border content and
+leaves the subject and required anchors whole. Record the transformation so it is reproducible;
+then remeasure and inspect at the real display size on the actual game background.
+
+Use `edit_image` for a generative edit when needed. Regenerate from the accepted reference only
+when the defect cannot be repaired without losing the intended identity or missing the brief;
+change the failing clause, not the entire direction. A passing numeric check alone is not approval.
+
+**Which route says no, measured.** `npx @funpixel/tools jobs --refusals` tallies, per tool, how often your
+own jobs were refused and by what (policy, the asset gate, bad input) over the latest 500. A route that
+refuses often wants plainer, generic descriptors; judge our routes by these numbers, not by any vendor's
+reputation for strictness.