@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-mobile-ui/references/recipes.md

@@ -0,0 +1,279 @@
+# Phone recipes
+
+Worked code for the rules in the skill. Each one exists because the simpler version failed on a
+real phone while passing on the desktop.
+
+## Viewport meta and the safe-area bridge
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+```css
+:root {
+  --sai-top: env(safe-area-inset-top);
+  --sai-right: env(safe-area-inset-right);
+  --sai-bottom: env(safe-area-inset-bottom);
+  --sai-left: env(safe-area-inset-left);
+}
+.hud-top      { top:    max(16px, env(safe-area-inset-top)); }
+.hud-bottom   { bottom: max(16px, env(safe-area-inset-bottom)); }
+.control-left { left:   max(16px, env(safe-area-inset-left)); }
+.control-right{ right:  max(16px, env(safe-area-inset-right)); }
+```
+
+The `--sai-*` block is only needed when JavaScript reads the insets (a HUD drawn in the canvas):
+
+```ts
+import { safeArea } from '@funpixel/sdk/device';
+let insets = safeArea.insets();                         // zeros without the CSS bridge above
+// inside the game's one setupGameResize callback, after the renderer refit:
+insets = safeArea.insets(); layoutHud(w, h, insets);
+```
+
+## Canvas sized by CSS
+
+A canvas given inline pixel sizes at boot keeps them after fullscreen or a visual-viewport change,
+leaving a dead band.
+
+```ts
+import { setupGameResize } from '@funpixel/sdk';
+Object.assign(canvas.style, { width: '100%', height: '100%', display: 'block' });
+const refit = (w: number, h: number) => {
+  renderer.setSize(w, h, false);                        // Three; false = no inline px sizes
+  camera.aspect = w / h; camera.updateProjectionMatrix();
+  // Pixi: app.renderer.resize(w, h)
+};
+setupGameResize(refit);                                 // fires once now; create the renderer first
+document.addEventListener('fullscreenchange', () => refit(innerWidth, innerHeight));
+visualViewport?.addEventListener('resize', () => refit(innerWidth, innerHeight));
+```
+
+## Last input wins
+
+```ts
+const body = document.body;
+addEventListener('pointerdown', (e) => {
+  const touch = e.pointerType === 'touch' || e.pointerType === 'pen';
+  body.classList.toggle('fp-touch', touch);
+  body.classList.toggle('fp-mouse', !touch);
+}, { capture: true });
+addEventListener('touchstart', () => {
+  body.classList.add('fp-touch'); body.classList.remove('fp-mouse');
+}, { capture: true, passive: true });
+if (matchMedia('(pointer: coarse)').matches || navigator.maxTouchPoints > 0) body.classList.add('fp-touch');
+```
+
+```css
+.touch-controls { display: none; }
+body.fp-touch .touch-controls { display: flex; }
+body.fp-mouse .touch-controls { display: none; }
+```
+
+The JavaScript first guess matters: review browsers emulate touch through `matchMedia` and
+`maxTouchPoints`, and a CSS media query alone never fires there.
+
+## A swipe on the play (the usual first choice for board, grid and sliding puzzles)
+
+The hits of the genre give the phone's screen to the board and take the move on it: Threes and
+2048 slide on a swipe anywhere, Two Dots on a drag through the dots, Monument Valley on a tap in
+the world. The player's eyes stay on the board, and a pad under it costs a third of the screen
+(one ice puzzle's first phone build: a 5×5 board under half the screen, four arrows plus Undo, Restart and
+Hint panels in the bottom third, all repeating what the swipe already did).
+
+```ts
+// One listener on the play element: direction on release, a live preview while the finger is down.
+const play = document.querySelector<HTMLElement>('#play')!;   // data-fpx-gesture="ArrowUp ArrowDown ArrowLeft ArrowRight"
+let start: { x: number; y: number; id: number } | null = null;
+play.addEventListener('pointerdown', (e) => { play.setPointerCapture(e.pointerId); start = { x: e.clientX, y: e.clientY, id: e.pointerId }; });
+play.addEventListener('pointermove', (e) => {
+  if (!start || e.pointerId !== start.id) return;
+  preview(dirOf(e.clientX - start.x, e.clientY - start.y, 12));   // where the move would go: a ghost path, the tiles it crosses
+});
+play.addEventListener('pointerup', (e) => {
+  if (!start) return;
+  const d = dirOf(e.clientX - start.x, e.clientY - start.y, 24); start = null; preview(null);
+  if (d) move(d);                     // the same function the arrow keys call (one input path)
+});
+function dirOf(dx: number, dy: number, min: number) {
+  if (Math.max(Math.abs(dx), Math.abs(dy)) < min) return null;       // a tap is not a swipe
+  return Math.abs(dx) > Math.abs(dy) ? (dx > 0 ? 'right' : 'left') : (dy > 0 ? 'down' : 'up');
+}
+```
+
+- About 24 CSS px of travel makes a swipe; under it the release is a tap. The preview starts
+  earlier (about 12 px) so the finger sees the move before it commits, and a swipe dragged back to
+  where it began cancels.
+- `touch-action: none` on the play element, or the browser scrolls the page instead.
+- Size the board first, the chrome after: in portrait the board takes the full width less the
+  gutters and whatever height the HUD leaves; Undo, Restart and Hint fit as small icons in a
+  corner or one row, not panels.
+- Teach the first swipe by play: a ghost finger that swipes once over the board and fades at the
+  first move, instead of a banner of text over the play.
+- On-screen arrows stay available as an accessibility option in settings (off by default), for
+  players who cannot swipe.
+
+## A swipe that steers a maze (queued turn)
+
+Phone maze hits (Pac-Man 256) take a swipe anywhere and keep it: the hero runs on, and the turn is
+taken at the next junction where that way is open. A swipe a little early is never lost.
+
+```ts
+let queued: Dir | null = null;                    // set by a swipe or an arrow key, the same path
+function onSwipe(d: Dir) { if (canGo(hero, d)) hero.dir = d; else queued = d; }
+function atCell(hero: Hero) {                     // each time the hero reaches a cell centre
+  if (queued && canGo(hero, queued)) { hero.dir = queued; queued = null; }
+}
+```
+
+- Commit on the move, not the release (about 16–24 px): a chase gives no time to lift the finger.
+- Show the queue: an arrow or chevron at the hero's next junction until it is taken, so the finger
+  sees that it was heard.
+- Drop a stale queued turn after a second or two.
+- Any second verb (a lure, a dash) needs its own gesture (a tap on the maze, a two-finger tap) or one
+  small button in the thumb's corner, not a pad.
+
+## On-screen buttons (where no gesture carries the action, or as a setting)
+
+```tsx
+const input = { left: false, right: false, jump: false };   // the loop reads this each frame
+function hold(el: HTMLElement, key: keyof typeof input) {
+  el.addEventListener('pointerdown', (e) => { el.setPointerCapture(e.pointerId); input[key] = true; });
+  for (const t of ['pointerup', 'pointercancel', 'lostpointercapture'])
+    el.addEventListener(t, () => { input[key] = false; });
+}
+```
+
+```html
+<button class="control dpad-left" data-fpx-touch="ArrowLeft" aria-label="Move left">
+  <svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor"
+       stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 6 9 12 15 18"/></svg>
+</button>
+```
+
+```css
+.control { touch-action: none; user-select: none; -webkit-tap-highlight-color: transparent;
+  width: clamp(48px, 14vw, 84px); height: clamp(48px, 14vw, 84px); }
+```
+
+A keyboard handler that overwrites touch loses it: a per-frame `input.left =
+keys.has('ArrowLeft')` erases the button's `true` every frame. Keep separate sources and OR them
+where the value is read.
+
+## Touch input and thumb reach
+
+- Pointer events with `setPointerCapture` keep a drag that slides off its control.
+- 44 by 44 CSS px of hit area: in one fix round an iPhone SE's smallest taps went from 38.7 to 44
+  px and the misses stopped. The glyph inside may be smaller.
+- Inverted controls are a silent failure: they build, pass and play backwards. One input object
+  where ArrowUp, W, the up button and a stick pushed up all mean +1, converted to the engine's axis
+  once where the value is applied, keeps every source agreeing.
+- Where thumbs rest, as a starting point to move from when the design wants otherwise:
+
+  | Layout | Frequent controls usually sit |
+  |---|---|
+  | Portrait | the bottom 30 to 40% of the screen |
+  | Landscape | the lower corners, where both thumbs rest |
+  | Either | away from the top centre, the hardest reach |
+
+- Orientation by the design: one-thumb games tend to portrait; racing, flight, first-person,
+  side-scrolling and twin-stick games tend to landscape. A landscape game held upright needs to
+  say "turn me"; the rotate card below keeps the game visible behind it, so the player sees
+  what they are about to play.
+
+## Blur clears held input
+
+```ts
+function releaseAll() {
+  heldKeys.clear();
+  for (const k of Object.keys(input) as (keyof typeof input)[]) input[k] = false;
+  stick.x = 0; stick.y = 0;
+  game.setPaused(true);
+}
+addEventListener('blur', releaseAll);
+document.addEventListener('visibilitychange', () => { if (document.hidden) releaseAll(); });
+```
+
+## The rotate card
+
+For a landscape game held upright. The game keeps rendering behind the card, dimmed and blurred,
+so the player sees what they are about to play.
+
+```ts
+const card = document.getElementById('rotate-card')!;
+function checkOrientation() {
+  const upright = innerHeight > innerWidth;
+  card.hidden = !upright;
+  game.setPaused(upright);
+}
+checkOrientation();   // and again from the one setupGameResize callback that refits the canvas
+```
+
+```css
+#rotate-card { position: fixed; inset: 0; display: grid; place-content: center;
+  backdrop-filter: blur(8px) brightness(0.5); z-index: 20; }
+#rotate-card[hidden] { display: none; }
+```
+
+`screen.orientation.lock` and `requestFullscreen` cannot be the fix: the lock is refused
+inside the Funpixel player frame, and iPhone has no element fullscreen.
+
+## Audio unlock on a real activation
+
+```ts
+import { AudioEngine } from '@funpixel/sdk/audio';
+const audio = new AudioEngine({ iosPatch: false }); // the ringer switch mutes it
+const unlock = () => { if (audio.ctx.state !== 'running') { audio.unlock(); audio.ctx.resume(); } };
+for (const t of ['pointerup', 'touchend', 'keydown']) addEventListener(t, unlock);
+```
+
+A touch `pointerdown` is not a user activation, and `unlock()` latches on its first call even when
+the resume failed, so keep retrying `resume()` until the context runs.
+
+## Short landscape screens
+
+A landscape phone is 375 to 430 px tall. Size by the smaller side:
+
+```css
+.title h1 { font-size: clamp(22px, 9vmin, 64px); white-space: nowrap; }
+.screen   { min-height: 100dvh; padding: max(12px, 3vmin); display: grid; place-content: center; }
+.cta      { margin-block: 2vmin; }
+```
+
+## Text that fits: measure the glyphs
+
+An element's box can fit while its text overflows it, wraps mid-word or sits under a sibling. Measure
+the rendered text:
+
+```ts
+function textInside(el: HTMLElement, box: HTMLElement = el.parentElement!): boolean {
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  const t = range.getBoundingClientRect(), b = box.getBoundingClientRect();
+  const lines = range.getClientRects().length;
+  return t.left >= b.left - 0.5 && t.right <= b.right + 0.5 && t.top >= b.top - 0.5 &&
+         t.bottom <= b.bottom + 0.5 && el.scrollWidth <= el.clientWidth + 1 &&
+         (el.dataset.maxLines ? lines <= Number(el.dataset.maxLines) : true);
+}
+window.__FPX_SELFTEST__ = [
+  ...(window.__FPX_SELFTEST__ ?? []),
+  { name: 'title fits on one line', run: () => textInside(document.querySelector('.title h1')!) },
+];
+```
+
+Give a title `data-max-lines="1"`. For text drawn in a canvas, compare `ctx.measureText(s).width`
+(and the `actualBoundingBox*` values) against the panel it sits in.
+
+A title that does not fit fits with a smaller clamp or a shorter string; `word-break: break-all`
+is how a word gets split mid-letter.
+
+## Viewports to check
+
+| Phone | Portrait | Landscape |
+|---|---|---|
+| Small (SE class) | 375x667 | 667x375 |
+| Funpixel review frame | 390x844 | 844x390 |
+| Large (Pro Max class) | 430x932 | 932x430 |
+
+Check portrait and the game's own orientation at the two extremes. In local device emulation, turn
+touch on, or the controls stay hidden and the check proves nothing.

package/templates/common/.agents/skills/funpixel-mobile-ui/references/restyle-ui.md

@@ -0,0 +1,229 @@
+# Restyling the scaffold's HUD and screens in the game's style
+
+The scaffold ships a working interface in neutral clothes: dark translucent plates, a system type
+stack, filled glyphs. They are there so the first build has a HUD, not as a look. This page is how
+a game dresses them in its own world (skill `funpixel-art`, reference `ui.md`, has the
+direction: material, faces, icons, colour roles, motion). The markup stays; the theme changes.
+
+## The order that keeps it cheap
+
+1. **Tokens first.** A scaffold made since 30 Sep already declares the UI roles in `:root`
+   (`--plate`, `--plate-edge`, `--plate-ink`, `--plate-radius`, `--font-display`, `--font-body`,
+   `--icon-line`, `--icon-fill`, `--icon-stroke`) and dresses every plate with one `.plate` class.
+   Since 3 Oct their values live in one file, `src/look.json`, applied at load: fill it from the
+   style file's `ui` block with `npx @funpixel/tools look set` (below). It refuses an unknown token
+   with the closest name and proposes a readable ink for any pair that fails contrast. The
+   stylesheet keeps the starter's values as the fallback.
+2. **Faces.** Install the two families as packages, so they ship with the game and load offline,
+   and name them in `funpixel.json` so `verify` checks both load (a failed face falls back to
+   the system stack without an error).
+3. **Plates.** One rule dresses every plate: `.plate`, worn by the HUD row, the cards, the pad
+   and the message lane. The material is gradients, an edge and shadows; a generated plate image goes
+   in through `border-image`.
+4. **Icons.** Redraw `src/icons.tsx` as one family (below). Same names, so no call site changes.
+   The scaffold's two-tone set is a placeholder and says so.
+5. **Screens.** The scaffold's title is already a scene: no dimmer, a wordmark slot (`WORDMARK` in
+   `screens.tsx`, the art or the name in `--font-display`) in the upper band, `button.start` low in
+   the thumb zone, laid out upright and sideways. Put the world behind it. Pause and end cards take
+   the same plate.
+6. **Check it.** `npx @funpixel/tools look report` (every pair, every dropped token),
+   `look --hud --viewport phone` and `--view title` on a phone, `check --phone` (the safe band in
+   every view), and the UI targets beside the captures.
+
+```sh
+# src/look.json: the UI roles, taken from the style file's `ui` block (a token of your own: x-<name>, read as --x-<name>)
+npx @funpixel/tools look set plate=#c9a171 plate-edge=#7a5433 plate-ink=#3a2618 accent=#ffb238 harm=#ff4fa3
+npx @funpixel/tools look set font-display="'Cinzel', Georgia, serif" font-body="'Nunito', system-ui, sans-serif" plate-radius=6px
+```
+
+```css
+body { font-family: var(--font-body); }
+.card h1, .hud-value, .title h1 { font-family: var(--font-display); }
+```
+
+```sh
+pnpm add @fontsource/cinzel @fontsource/nunito
+```
+
+```ts
+// src/main.tsx: the faces ship inside the build
+import '@fontsource/cinzel/700.css';
+import '@fontsource/nunito/600.css';
+```
+
+```json
+{ "metadata": { "fonts": ["Cinzel", "Nunito"] } }
+```
+
+## Plates, buttons and the wordmark as art
+
+The UI pieces are made from the style frame like the cast, and CSS only places and scales them.
+A plate is one generated picture (the panel recipe in `ui.md`: front-on, even border, decoration
+only in the corners, flat centre, no text), saved under `public/ui/` so it ships, and sliced nine
+ways so any size keeps its corners:
+
+```css
+.hud-row, .card, .goal, button.primary {
+  border: 16px solid transparent;
+  border-image: url('/ui/plaque.png') 40 fill / 16px stretch;   /* 40 = the corner inset in the picture's pixels */
+  background: none; color: var(--plate-ink);
+}
+button.primary:active { filter: brightness(1.1); transform: translateY(2px); }
+```
+
+Measure the inset on the picture (where the corner ornament ends), and read the plate at its
+smallest size: a corner that is larger than half the smallest plate squeezes. A button's pressed and
+disabled states can be the same picture filtered, or a second generation with the same reference.
+
+What the sandstone proof ran into (30 Sep):
+- `border-image` owns the border: it ignores `border-radius` (a round button under a plate rule
+  turns square and loses its glow; give discs `border-image: none` and draw them as a medallion,
+  a bevelled border and an inlaid centre) and `border-color` (a warning state that recolours the
+  border does nothing; use a glow). The lantern game hit the second.
+- A pale plate cannot carry the world's light colours: cyan, amber and magenta measured 1.3 to
+  1.9:1 on sandstone. A dark inlay (a deep umber medallion behind the icon, 5.8 to 14:1) carries
+  them and still reads as stone.
+- An ink derived to exactly 4.5:1 measured lower on the rendered frame (glyph edges blend):
+  The lantern game's small HUD numbers needed 5 to 5.5:1 on paper.
+- A one-off class on a `button.primary` loses to `button.primary`'s own rule (element plus class
+  outweighs a class): select it as `button.my-class`.
+
+The wordmark is generated alone on a plain field in the world's material, then keyed or cropped and
+placed as `<img src="/ui/wordmark.png" alt="Game name">`; its size comes from `clamp()` so it fits a
+phone upright and sideways. Read every letter before using it; when a name will not come out right
+after one redraw, the display face with a carved treatment (below) is the honest fallback.
+
+## An icon family
+
+Every icon on one grid, one stroke, one corner, two tones: the outline in the plate's ink, the fill
+in a role colour. Draw them like the game's sprites (if the art has a 3 px outline at 48 px, the
+icons carry a 2.5 px stroke at 24). The same names as the scaffold's set keep every call site.
+
+```tsx
+// src/icons.tsx: one family, stroke and fill from the theme
+const PATHS = {
+  pause: { line: 'M8 5v14M16 5v14', fill: '' },
+  play: { line: 'M8 5l11 7-11 7z', fill: 'M8 5l11 7-11 7z' },
+  soundOn: { line: 'M4 9h4l5-4v14l-5-4H4zM16.5 9a4 4 0 0 1 0 6', fill: 'M4 9h4l5-4v14l-5-4H4z' },
+  star: { line: 'M12 3.5l2.6 5.3 5.9.9-4.3 4.1 1 5.8-5.2-2.8-5.2 2.8 1-5.8-4.3-4.1 5.9-.9z', fill: 'M12 3.5l2.6 5.3 5.9.9-4.3 4.1 1 5.8-5.2-2.8-5.2 2.8 1-5.8-4.3-4.1 5.9-.9z' },
+} as const;
+export type IconName = keyof typeof PATHS;
+export const Icon = ({ name, size = 24 }: { name: IconName; size?: number }) => (
+  <svg viewBox="0 0 24 24" width={size} height={size} aria-hidden="true" class="ico">
+    {PATHS[name].fill && <path class="ico-fill" d={PATHS[name].fill} />}
+    <path class="ico-line" d={PATHS[name].line} />
+  </svg>
+);
+```
+
+A hint drawn as the world's own object (a lit lamp, a snowflake, a paper crane) says more than a
+bulb. Put the set on one sheet at 24 and 48 px on the plate colour and compare it with the cast
+before the game uses it.
+
+## Worked example 1: a sandstone puzzle, plaques
+
+**Before** (R7, iPhone, landscape): the court is warm carved sandstone at sunset; the HUD is dark
+navy pills (`rgba(10, 13, 28, 0.82)`) with cyan outlines, `ui-rounded` system type and the
+scaffold's glyphs; the title a white bold wordmark, a cyan pill and three icon circles. `look
+--hud` read every text in the system stack, 20 of 29 plates flat dark fills and the scaffold's pause
+and sound glyphs in play; on the title, a 47 px system wordmark and three scaffold glyphs.
+
+**Direction** (the `ui` block): objects of the world; sandstone plaques with a chiselled bevel;
+Cinzel for the wordmark, banners and the clock, Nunito for the goal line and toasts; icons with an
+ink stroke and a role-colour fill; plaques drop 12 px and settle. Four pieces of art from the style
+frame, $0.11 in all: the title and HUD targets, one nine-slice plaque, the wordmark.
+
+```css
+:root { --plate: #dba15c; --plate-light: #f0c27a; --plate-edge: #8a5a24; --plate-ink: #3a2618; --plate-deep: #241509; }
+.hud-row, .pips, .card, .wordmark-plaque {
+  border: 4px solid var(--plate-edge);
+  border-image: url('/ui/plaque.png') 96 fill / 18px stretch;   /* the generated plaque, corners kept */
+  color: var(--plate-ink); animation: plaque-in 0.22s cubic-bezier(0.3, 1.4, 0.5, 1);
+}
+/* anything carrying a light colour sits on a dark inlay: cyan 12:1, amber 9.8:1, magenta 5.8:1 */
+.goal, .tap, .turn, button.icon {
+  border-image: none; border: 2px solid var(--plate-edge); color: #f4ecd8;
+  background: radial-gradient(circle at 50% 38%, color-mix(in srgb, var(--plate-deep) 88%, var(--tone, #f4ecd8)), var(--plate-deep) 70%);
+}
+button.fold-start {                                               /* "Step in": a stone arch */
+  border-image: none; border: 3px solid var(--plate-edge);
+  border-radius: 50% 50% 10% 10% / 62% 62% 10% 10%;
+  background: linear-gradient(180deg, var(--plate-light), var(--plate));
+}
+button.fold-start .arch-glow { animation: arch-glow 2.4s ease-in-out infinite; }  /* the fold's cyan, breathing */
+@keyframes plaque-in { from { transform: translateY(-12px); opacity: 0; } }
+```
+
+The ink `#3a2618` on the plaque is 6.3:1, so the goal line reads on any wall. Colour still means
+what the rooms mean: a step's icon takes the tone of the light it names, on its umber inlay.
+
+**The title:** the court itself behind; the game's name as generated carved-sandstone lettering on a
+plaque (about a third of the width sideways, the upper band upright) with the caption carved in
+Cinzel under it; Play as "Step in", a small stone arch whose opening glows the fold's cyan, low in
+the thumb zone and clear of the real doorway; sound, help and settings as stone medallions.
+**After:** `look --hud` reads 0% system type, 0 of 29 plates flat dark fills and no scaffold glyphs
+in play; on the title, the wordmark in its own face. The busiest views came down from 26% HUD cover
+to 25%, and verify still passes 22 of 22.
+
+## Worked example 2: a lantern garden, paper lanterns
+
+**Before** (owner, iPhone, 30 Sep): a glowing wordmark, then a small dark board preview (about 40%
+of the width) floating in empty night sky, an orange Play pill, an outlined "Gardens" button and
+round stock glyphs for sound, help and settings. Nothing shows the promise: a night garden of paper
+lanterns lighting up, fireflies.
+
+**Direction:** objects of the world; buttons are paper lanterns that light when pressed, the
+secondary choice is a path of small lanterns, icons are drawn as lantern shapes in the same ink,
+the amber glow is the one accent (it means lit), and the title is a scene, not a floating board.
+
+```css
+:root { --paper: #ffd98a; --paper-deep: #e8912f; --frame: #3b2410; --glow: rgb(255 181 71 / 0.6); }
+button.primary {
+  position: relative; color: #3b1d06; border: var(--ui-stroke) solid var(--frame);
+  border-radius: 42% / 32%;
+  background: radial-gradient(ellipse at 50% 38%, #fff1c9, var(--paper) 45%, var(--paper-deep));
+  box-shadow: 0 0 18px 2px var(--glow);
+  transition: box-shadow 0.25s, filter 0.25s;
+}
+button.primary::before, button.primary::after {
+  content: ''; position: absolute; left: 22%; right: 22%; height: 6px; border-radius: 3px; background: var(--frame);
+}
+button.primary::before { top: -5px; }
+button.primary::after { bottom: -5px; }
+button.primary:active { filter: brightness(1.2); box-shadow: 0 0 34px 10px var(--glow); }
+.path-choice {
+  background: radial-gradient(circle, var(--paper) 0 2.5px, transparent 3.5px) 0 100% / 16px 8px repeat-x;
+  border: 0; padding-bottom: 12px; color: var(--paper);
+}
+.path-choice:hover, .path-choice:active { filter: drop-shadow(0 0 6px var(--glow)); }
+```
+
+**The title as a scene:** the garden fills the screen (the play canvas in an attract state: a
+lantern lights every second along a path, fireflies drift), the wordmark in the upper band in the
+display face with a warm glow, the lantern Play low in the thumb zone, the lit path "Gardens"
+under it, and sound, help and settings as small lantern icons in the top corner. The board preview
+goes; the garden itself is the preview.
+
+**After** (the proof, 30 Sep, four generations for $0.10): the title key art as the backdrop,
+the game's name lettered onto a string of lanterns (spelled right first time, keyed out), paper
+tag plates nine-sliced on the HUD, Shippori Mincho and Zen Maru Gothic. `look --hud` went from all
+system type, 9 of 10 dark plates and the scaffold's glyphs to none of the three; verify still
+passes. Left for the next round: the HUD tags sit too close to the goal line.
+
+## Other worlds, one line each
+
+| World | Plate | Edge | Motion |
+|---|---|---|---|
+| Frosted ice | pale teal gradient, 70% opaque, `backdrop-filter: blur(6px)` | a 1 px bright top rim, soft inner glow | slides in and frosts from the edge |
+| Carved wood | warm brown with a darker grain band | 3 px ink outline, a hard 3 px drop | drops and bounces once |
+| Plush and felt | soft pastel, `border-radius` 40% | a dashed stitch 4 px inside the edge | squashes on press |
+
+## What not to do
+
+- Keep the scaffold's class names; restyle, never rebuild the HUD. The rows and words in `hud.tsx`
+  change with the design; the theme changes with the look.
+- Emoji and system glyphs in a button still read as the default even on a good plate.
+- A texture over text lowers contrast: measure the text on the real frame (`look --hud`), not the
+  stylesheet.
+- A plate as big as a card over the play is the old fault in a new material: sizes and the HUD
+  zone still hold ([hud-genres.md](hud-genres.md)).

package/templates/common/.agents/skills/funpixel-mobile-ui/references/unity.md

@@ -0,0 +1,61 @@
+# Screens and HUD on a phone
+
+UI fit was the most frequent owner correction across the Unity games, and mobile UI passes took 3 rounds on one game and 6 or more on another. The failure this skill prevents is an audit that reports 0 issues while the phone shows broken UI: one game's capture audit of 144 shots passed, then the owner found overflowing cards on a phone.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, these checks, a UGUI helper kit of your own (a canvas scaled at 1170×2532, match 0.5; one safe rect from `Screen.safeArea`; text and images that take no taps), a font builder and the per-game audit and capture scripts. "Partial" below means a version exists in one studio's games, not in the kit. Until the starter ships, write each check as an Edit Mode or Play Mode test in your own project, capture screens on a Simulator of your own (`funtools sim lease`, then `funtools sim shot <udid> --out shot.png` after a launch with a dev flag per screen; a landscape game comes back upright), and look at every shot yourself.
+
+| Check | Passes when | Status |
+|---|---|---|
+| `ui_audit` | 0 overflows against parent panel and visible art, siblings under 8 units apart, taps under 44 pt, or items outside the safe area | partial: one game (a `-uicheck` launch flag), two others (screen capture scripts) |
+| `raycast_ownership` | a raycast at each button's centre hits that button | proposed |
+| `screen_sheet` | N of N registered screens and states captured | partial: one game; another (a tour flag that writes every menu to PNG); `funtools unity capture --all` shoots every registered view |
+| `touch_wording` | 0 keyboard or gamepad words in visible text | partial: one game's smoke run |
+| `frame_law` | player head and feet on screen, at least 9% of screen height, every journey step | partial: one game |
+| `hud_occlusion` | 0% of frames where the hero's or boss's opaque bounds cross a HUD rect | partial: one game, a probe |
+| `drawn_vs_solid` | drawn mesh bounds against collider bounds within the baseline per category | partial: one game |
+
+Also proposed: a TMP SDF font builder (use TMP's Font Asset Creator) and `glyph_coverage` (every UI character exists in the static TMP atlas; `TMP_FontAsset.HasCharacters` in a test does it).
+
+## Procedure
+
+1. Build every screen in code with UGUI and TextMeshPro. Scale with screen size at 1170×2532, match 0.5 (portrait); one port uses constant pixel size where 1 unit is 1 web CSS px, so a ported layout keeps its numbers.
+2. Fix orientation per game (puzzle and idle portrait, action landscape) in an editor setup method (`PlayerSettings.defaultInterfaceOrientation`, run with `-executeMethod`) and check it: cloned settings came up wrong twice.
+3. Size controls from this table.
+
+   | Element | Size |
+   |---|---|
+   | Any tap target | 44 pt or more |
+   | Hero call to action | 64 pt, one per screen, in the thumb zone |
+   | Buttons | primary 44 pt, secondary 36 pt, icon plus a 15–16 pt label |
+   | Thumb action buttons | 72–80 pt (one game); 56 units with a 20 gap (another) |
+   | Body text | 16 pt or more, 12 pt hard floor; HUD numerals 40 pt |
+   | HUD share of screen | 25% or less; one 44 pt top row |
+   | Margins and spacing | 24 pt or more from safe edges; spacing only 4/8/12/16/24/32 |
+
+4. Take safe areas from `Screen.safeArea` through one helper (rebuild it if the screen changes). In landscape the full inset (about 60 pt each side) read as too much padding. One game's own helper clears only the rounded corner (radius 62 pt) on the top and bottom rows and applies the full inset only on the island's side, in the band at 32–68% of height. Centre a split or versus layout on the real screen, not on the lopsided safe area. `Screen.cutouts` allocates on every call, so read it when the screen changes.
+5. Stay in touch mode on iOS. `touch_wording` runs the regex `Press|Enter|Esc|WASD|Click|Keyboard` over visible text and expects 0 hits.
+   One input path: the new Input System only. One game lays an invisible full-screen graphic under the HUD to take touch; HUD buttons are not raycast targets, and the game asks the HUD for a hit with a 44 pt minimum box. `Gamepad.current` covers MFi, Xbox and PlayStation pads. A twin-stick game defers the system's edge gestures (`PlayerSettings.iOS.deferSystemGesturesMode`, top and bottom) and hides the home indicator. Reduce Motion follows the system setting through a native plugin in two games; the others have only a manual "screen effects" setting.
+6. Use full fonts and warm every glyph behind the title. A web subset lacked Ş Ğ İ; Nunito lacks ▶ ◀ ★. First-use glyph baking cost 183–266 ms in one game against 17–20 ms once warm.
+7. Give a label its own hit area: text stretched over its parent with raycast on takes the parent's taps.
+8. Capture every state, not only every screen: scroll positions, fresh and full saves, extreme values, 125% and 150% text, and every mode's end screen. Register each state with `FunpixelProbe.View(name, enter)` (`com.funpixel.probe`); `funtools unity capture --all` shoots them all, upright and without the development watermark.
+9. Run `ui_audit` at SE, Pro, Pro Max and 2000×920 (the owner's phone). It compares text with the parent panel and the visible art: text checked against its own box passed overlapping labels.
+10. After every UI change, rebuild the all-screens sheet with before, now and reference columns and the same file names, so an open viewer stays current. Then self-review each screen from 100% crops.
+11. For play screens, run `frame_law`, `hud_occlusion` and `drawn_vs_solid`.
+12. Keep a mobile pass to size, depth, placement, copy and motion. Palette, fonts and art stay: on one game the owner said style and identity are kept.
+
+## Worked example
+
+A landscape port. The capture audit ran at 2868×1320 and 1334×750, took 144 shots and reported 0 issues. On a phone the owner found broken dog cards: the Pick screen overflowed at 2000×920, a shape the audit never ran. Every capture had been a Quick Match, so a stuck vs-Bot result screen shipped. The owner asked for all screens in a sheet twice. Steps 8 to 10 came out of it.
+
+## Common mistakes
+
+- Checking text against its own box. In one game `-uicheck` passed while the 'SHOTS' label sat on a shield rim drawn with `preserveAspect`.
+- Capturing only the top of a scrolling sheet. One game's roster labels were broken from the first port until the owner found them on a phone.
+- A label stretched over its card. A shared text helper put the Restore label over the whole shop card; taps on products showed "Restoring purchases" in four games, until its text stopped taking taps.
+- Keyboard wording: one game showed "Press Enter to continue" on the Simulator; another's captures said "A / D to steer".
+- Naive safe areas: One game's HUD corners moved from 74 to 38–43 px.
+- UGUI geometry: `Slider` stretches fill and thumb to the row height, and stretch anchors plus a non-zero `sizeDelta` double the width. One game's Photo pill sat over the paywall's Done and took its taps.
+- A player nobody can see. One game's smallest hero drew at about 2% of screen height; another's boss heads sat under the boss bar in 100% of frames.
+- Art without a matching collider: 42 props in one game had none.