@funpixel/tools 0.0.0-stage → 0.1.0

package/templates/common/src/store.ts

@@ -0,0 +1,68 @@
+// The one screen state the loop, the screens, the HUD and every
+// __FPX_VIEWS__ enter() share. Change it only through go() and show().
+// The player's settings (sound, motion, on-screen buttons) live here too, saved on this device.
+
+import { useEffect, useState } from 'preact/hooks';
+import { progress } from './save';
+
+export type Screen = 'splash' | 'title' | 'howto' | 'settings' | 'playing' | 'paused' | 'won' | 'lost';
+
+const reduced = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+const saved = (() => { try { return JSON.parse(localStorage.getItem('settings') ?? '{}'); } catch { return {}; } })();
+
+export const store = {
+  screen: 'title' as Screen,
+  /** Where Back goes from how-to and settings. */
+  back: 'title' as Screen,
+  /** The best is kept across reloads (save.ts); the rest is this session's. */
+  score: 0, best: Number(progress.data.best) || 0, timeLeft: 0, wins: 0, losses: 0,
+  /** Metres to the next goal, shown beside the objective (the Silt bar S2: the objective and its distance on screen at the first control); null when the game has none. */
+  goal: null as number | null,
+  /** What ended the last lost round: the lost card names it. */
+  lostTo: 'time' as 'time' | 'spike',
+  /** Floating "+1"s by the score readout; each fades on its own. */
+  pops: [] as Array<{ id: number; text: string }>,
+  muted: saved.muted === true,
+  /** Shake and full-screen flashes; off under prefers-reduced-motion until the player turns them on. */
+  motion: typeof saved.motion === 'boolean' ? saved.motion : !reduced,
+  /** On-screen buttons over the play: an accessibility setting, off by default (a swipe on the play moves). */
+  pad: saved.pad === true,
+};
+
+type Listener = (next: Screen, prev: Screen) => void;
+const screenListeners = new Set<Listener>();
+const renders = new Set<() => void>();
+
+/** Change screen; the game reacts (playing from anywhere but a pause starts a run). */
+export function go(screen: Screen): void {
+  const prev = store.screen;
+  if ((screen === 'howto' || screen === 'settings') && prev !== 'howto' && prev !== 'settings') store.back = prev;
+  store.screen = screen;
+  for (const l of screenListeners) l(screen, prev);
+  for (const r of renders) r();
+}
+
+/** Update what the HUD and screens show; a settings change is saved. */
+export function show(patch: Partial<Omit<typeof store, 'screen'>>): void {
+  Object.assign(store, patch);
+  if ('best' in patch) progress.update({ best: store.best });
+  if ('muted' in patch || 'motion' in patch || 'pad' in patch) {
+    try { localStorage.setItem('settings', JSON.stringify({ muted: store.muted, motion: store.motion, pad: store.pad })); } catch { /* private mode */ }
+  }
+  for (const r of renders) r();
+}
+
+export function onScreen(l: Listener): void {
+  screenListeners.add(l);
+}
+
+/** Re-render a Preact component whenever the store changes. */
+export function useStore(): typeof store {
+  const [, bump] = useState(0);
+  useEffect(() => {
+    const r = () => bump((n) => n + 1);
+    renders.add(r);
+    return () => { renders.delete(r); };
+  }, []);
+  return store;
+}

package/templates/common/src/strike.ts

@@ -0,0 +1,82 @@
+// A strike as data: five key poses (guard → wind-up → contact → follow-through → guard), four timed
+// phases with an easing each, and a body lead (hips and chest start before the arm). The hit is
+// tested on the CONTACT frame, never on the press. Engine-free; out-of-range values are held and
+// named in `warnings`, never thrown. Per frame:
+//   const r = strikeAt(s, t, tBefore);
+//   if (r.contact) resolveHit();                 // once, on the frame the strike reaches contact
+//   arm.rotation.x = -r.pose.raise * 1.6; arm.position.z = r.pose.reach * reachM; chest.rotation.y = r.body.twist * 0.6;
+
+import type { MotionWarning } from './motion';
+
+/** A key pose: reach (−1 drawn back … 1 extended), raise (−1 low … 1 overhead), twist (torso −1 … 1), crouch (0 … 0.3 of height). */
+export interface StrikePose { reach: number; raise: number; twist: number; crouch: number }
+export type Ease = 'in' | 'out' | 'inOut' | 'linear';
+export type StrikePhase = 'anticipation' | 'strike' | 'followThrough' | 'recovery';
+export interface Strike {
+  /** Seconds per phase. */
+  anticipation: number; strike: number; followThrough: number; recovery: number;
+  /** Seconds the body leads the arm. */
+  bodyLead: number;
+  guard: StrikePose; windup: StrikePose; contact: StrikePose; through: StrikePose;
+  /** An overhead move may raise the arm past the shoulder. */
+  overhead?: boolean;
+}
+
+export const STRIKE_DIALS = {
+  anticipation: [0.08, 0.6, 'the wind-up: shorter and the strike has no weight, longer and the player waits'],
+  strike: [0.03, 0.15, 'wind-up to contact: fast, or it reads as a push'],
+  followThrough: [0.05, 0.4, 'past the target: the weight carries on'],
+  recovery: [0.1, 0.8, 'back to guard: the window the opponent punishes'],
+  bodyLead: [0, 0.12, 'hips and chest start this long before the arm'],
+} as const;
+/** The easing of each phase: settle out into the wind-up, accelerate in to contact, carry out, ease home. */
+export const PHASE_EASE: Record<StrikePhase, Ease> = { anticipation: 'out', strike: 'in', followThrough: 'out', recovery: 'inOut' };
+
+const guard: StrikePose = { reach: 0, raise: 0, twist: 0, crouch: 0.03 };
+export const STRIKES = {
+  jab: { anticipation: 0.1, strike: 0.05, followThrough: 0.08, recovery: 0.15, bodyLead: 0.03, guard, windup: { reach: -0.3, raise: 0.1, twist: -0.2, crouch: 0.04 }, contact: { reach: 1, raise: 0.2, twist: 0.3, crouch: 0.03 }, through: { reach: 0.9, raise: 0.15, twist: 0.35, crouch: 0.03 } },
+  heavy: { anticipation: 0.4, strike: 0.09, followThrough: 0.25, recovery: 0.45, bodyLead: 0.08, overhead: true, guard, windup: { reach: -0.6, raise: 1, twist: -0.5, crouch: 0.02 }, contact: { reach: 0.8, raise: -0.2, twist: 0.4, crouch: 0.12 }, through: { reach: 0.6, raise: -0.6, twist: 0.5, crouch: 0.15 } },
+  sweep: { anticipation: 0.22, strike: 0.08, followThrough: 0.2, recovery: 0.3, bodyLead: 0.06, guard, windup: { reach: 0.2, raise: 0.3, twist: -0.9, crouch: 0.05 }, contact: { reach: 0.9, raise: 0.25, twist: 0.4, crouch: 0.06 }, through: { reach: 0.6, raise: 0.2, twist: 0.9, crouch: 0.06 } },
+  kick: { anticipation: 0.18, strike: 0.07, followThrough: 0.12, recovery: 0.28, bodyLead: 0.05, guard, windup: { reach: -0.4, raise: -0.3, twist: -0.3, crouch: 0.08 }, contact: { reach: 1, raise: -0.1, twist: 0.2, crouch: 0.02 }, through: { reach: 0.8, raise: -0.2, twist: 0.3, crouch: 0.04 } },
+  // A creature's bite: coil low, snap forward with the whole body.
+  lunge: { anticipation: 0.3, strike: 0.06, followThrough: 0.1, recovery: 0.4, bodyLead: 0.04, guard, windup: { reach: -0.7, raise: -0.2, twist: 0, crouch: 0.2 }, contact: { reach: 1, raise: 0.1, twist: 0, crouch: 0 }, through: { reach: 0.9, raise: 0, twist: 0, crouch: 0.02 } },
+} as const satisfies Record<string, Strike>;
+export type StrikeName = keyof typeof STRIKES;
+
+/** What reads wrong in a strike, by dial; never throws. */
+export function checkStrike(s: Strike): MotionWarning[] {
+  const out: MotionWarning[] = [];
+  for (const [k, [lo, hi, why]] of Object.entries(STRIKE_DIALS) as Array<[keyof typeof STRIKE_DIALS, readonly [number, number, string]]>) {
+    const v = s[k];
+    if (!Number.isFinite(v) || v < lo || v > hi) out.push({ dial: k, value: v, range: [lo, hi], why: `held at the edge: ${why}` });
+  }
+  if (s.anticipation < 1.5 * s.strike) out.push({ dial: 'anticipation', value: s.anticipation, why: 'a wind-up under 1.5× the strike: the blow reads weightless' });
+  for (const k of ['windup', 'contact', 'through'] as const) {
+    if (!s.overhead && s[k].raise > 0.8) out.push({ dial: `${k}.raise`, value: s[k].raise, why: 'the arm over the shoulder reads out of control unless the move is an overhead (overhead: true)' });
+  }
+  return out;
+}
+
+const clampDial = (k: keyof typeof STRIKE_DIALS, v: number) => Math.min(STRIKE_DIALS[k][1], Math.max(STRIKE_DIALS[k][0], Number.isFinite(v) ? v : STRIKE_DIALS[k][0]));
+const EASE: Record<Ease, (p: number) => number> = { in: (p) => p * p, out: (p) => 1 - (1 - p) * (1 - p), inOut: (p) => 0.5 - 0.5 * Math.cos(Math.PI * p), linear: (p) => p };
+const mix = (a: StrikePose, b: StrikePose, p: number): StrikePose => ({ reach: a.reach + (b.reach - a.reach) * p, raise: a.raise + (b.raise - a.raise) * p, twist: a.twist + (b.twist - a.twist) * p, crouch: a.crouch + (b.crouch - a.crouch) * p });
+
+export interface StrikeFrame { phase: StrikePhase | 'done'; p: number; pose: StrikePose; body: StrikePose; contact: boolean; impactPhase: number; total: number }
+
+/** The strike `t` seconds in (and `before` = last frame's t, so contact fires once on the frame that crosses it). */
+export function strikeAt(s: Strike, t: number, before = -1): StrikeFrame {
+  const d = { anticipation: clampDial('anticipation', s.anticipation), strike: clampDial('strike', s.strike), followThrough: clampDial('followThrough', s.followThrough), recovery: clampDial('recovery', s.recovery) };
+  const total = d.anticipation + d.strike + d.followThrough + d.recovery;
+  const contactAt = d.anticipation + d.strike;
+  const keys: Array<[StrikePhase, StrikePose, StrikePose]> = [['anticipation', s.guard, s.windup], ['strike', s.windup, s.contact], ['followThrough', s.contact, s.through], ['recovery', s.through, s.guard]];
+  const at = (time: number): { phase: StrikePhase | 'done'; p: number; pose: StrikePose } => {
+    let start = 0;
+    for (const [ph, a, b] of keys) {
+      if (time < start + d[ph]) { const p = Math.max(0, (time - start) / d[ph]); return { phase: ph, p, pose: mix(a, b, EASE[PHASE_EASE[ph]](p)) }; }
+      start += d[ph];
+    }
+    return { phase: 'done', p: 1, pose: s.guard };
+  };
+  const now = at(t);
+  return { ...now, body: at(Math.min(total, t + clampDial('bodyLead', s.bodyLead))).pose, contact: before < contactAt && t >= contactAt, impactPhase: contactAt / total, total };
+}

package/templates/common/src/styles.css

@@ -0,0 +1,81 @@
+@import './screens.css';
+@import './hud-kit.css';
+/* The scaffold's placeholder palette: replace it with the design note's (smoke warns while it ships). */
+:root { --bg: #101018; --ink: #f4f1ea; --primary: #4fd1c5; --accent: #f6ad55; --harm: #ff6b6b; }
+/* The UI roles, the one place the interface takes its look (assets/style.json's `ui` block): every
+   plate, button, icon and face below reads these. The values are placeholders (dark glass, the
+   system face), so `look --hud` still names them until the game's own material replaces them
+   (skill funpixel-art-direction, references/ui.md; skill funpixel-mobile-ui, references/restyle-ui.md). */
+:root {
+  --plate: rgba(16, 16, 24, 0.82); --plate-edge: transparent; --plate-ink: var(--ink);
+  --plate-radius: 12px; --plate-shadow: none; --ui-stroke: 2px;
+  --icon-line: currentColor; --icon-fill: var(--accent); --icon-stroke: 2; --button-ink: var(--bg);
+  --font-display: system-ui, sans-serif; --font-body: system-ui, sans-serif;
+  --panel: var(--plate); /* the older name, kept for games that read it */
+}
+html, body {
+  margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden;
+  overscroll-behavior: none; -webkit-user-select: none; user-select: none;
+  -webkit-touch-callout: none; -webkit-tap-highlight-color: transparent;
+  background: var(--bg); color: var(--ink); font-family: var(--font-body);
+}
+/* One plate dresses the HUD row, the cards, the message lane and the pad: restyle it once
+   (a gradient, an edge, a nine-sliced picture through border-image), not per piece. */
+.plate {
+  background: var(--plate); color: var(--plate-ink); border: var(--ui-stroke) solid var(--plate-edge);
+  border-radius: var(--plate-radius); box-shadow: var(--plate-shadow);
+}
+#app, .stage { position: fixed; inset: 0; }
+.stage { touch-action: none; } /* the swipe is the game's, not the page's scroll */
+/* A hurt shows at the edges (juice.vignette sets --vignette), never as a full-screen flash. */
+.stage::after { content: ''; position: absolute; inset: 0; pointer-events: none; box-shadow: inset 0 0 16vmin 3vmin var(--harm); opacity: var(--vignette, 0); }
+canvas { display: block; width: 100%; height: 100%; }
+button {
+  font: inherit; font-weight: 700; color: var(--ink); background: transparent; cursor: pointer;
+  min-width: 48px; min-height: 48px; padding: 0 20px; border: 2px solid currentColor; border-radius: 12px;
+  display: inline-flex; gap: 8px; align-items: center; justify-content: center;
+  touch-action: manipulation; transition: transform 0.12s ease-out, filter 0.12s;
+}
+button:hover { filter: brightness(1.12); transform: translateY(-1px); }
+button:active { transform: scale(0.97); }
+button.primary { background: var(--primary); border-color: var(--primary); color: var(--button-ink); }
+button.icon { padding: 0; width: 48px; border-radius: 50%; }
+/* A one-off class loses to `button.primary` (element + class outweighs a class): select a styled
+   control as `button.<class>`, as the start control is here. */
+button.start { min-width: min(260px, 70vw); min-height: 60px; font-size: 1.25em; font-family: var(--font-display); }
+
+/* Every edge piece keeps to the safe band (frame.ts: the safe-area insets, never under the phone floors;
+   --band-* on :root). The fallbacks are for a game that drops frame.ts. */
+.hud {
+  position: fixed; left: var(--band-left, max(16px, env(safe-area-inset-left))); right: var(--band-right, max(16px, env(safe-area-inset-right)));
+  top: var(--band-top, max(12px, env(safe-area-inset-top))); display: flex; gap: 16px; align-items: center;
+  font-size: clamp(16px, 4.2vmin, 24px); font-weight: 800; pointer-events: none;
+}
+/* The HUD band: one slim row along the top edge; the message lane (.kit-top) sits just under it. */
+.hud-row { position: relative; display: inline-flex; gap: 6px; align-items: center; padding: 4px 10px; }
+.hud-label { font-size: max(12px, 0.6em); font-weight: 600; opacity: 0.75; text-transform: uppercase; letter-spacing: 0.06em; }
+.hud-value { font-variant-numeric: tabular-nums; }
+.hud-time { color: var(--accent); }
+.hud-buttons { margin-left: auto; display: flex; gap: 8px; pointer-events: auto; }
+.pop { position: absolute; left: 100%; top: 0; margin-left: 6px; color: var(--accent); animation: rise 0.7s ease-out forwards; }
+.pad {
+  position: fixed; left: var(--band-left, max(16px, env(safe-area-inset-left))); right: var(--band-right, max(16px, env(safe-area-inset-right)));
+  bottom: var(--band-bottom, max(16px, env(safe-area-inset-bottom))); display: flex; justify-content: space-between;
+}
+.pad button { width: 72px; height: 72px; padding: 0; border-radius: 50%; }
+/* Phones keep clear of the notch and the home bar even where env() reads 0: frame.ts's FLOORS (48 px on the
+   notch sides held sideways, 48 px over the status bar held upright), published as --band-*. */
+
+@keyframes pop { from { transform: scale(0.92); opacity: 0; } }
+@keyframes fade { from { opacity: 0; } }
+@keyframes breathe { 50% { transform: scale(1.03); } }
+@keyframes rise { from { transform: translateY(0) scale(1.3); opacity: 1; } to { transform: translateY(-28px) scale(1); opacity: 0; } }
+/* Icons (icons.tsx): two tones, the line in the plate's ink, the fill in a role colour. */
+.ico { flex-shrink: 0; }
+.ico-fill { fill: var(--icon-fill); opacity: 0.9; }
+.ico-line { fill: none; stroke: var(--icon-line); stroke-width: var(--icon-stroke); stroke-linecap: round; stroke-linejoin: round; }
+@media (prefers-reduced-motion: reduce) { .card, .screen, .wordmark, .pop, [class*='kit-'] { animation: none; } }
+.load-failed { position: fixed; inset: auto 16px 40%; margin: auto; max-width: 320px; padding: 20px; text-align: center; z-index: 50; }
+
+/* On-screen controls are for touch only (platform.ts inputMode: last input wins; a key or a mouse hides them). */
+html:not([data-input="touch"]) .touch-only { display: none !important; }

package/templates/common/src/toasts.ts

@@ -0,0 +1,75 @@
+// The message lane: short messages (a wave, a combo, NEW) shown ONE at a time in the HUD band,
+// never over the middle of the play. Eight GDK games covered the play with stacked banners at the
+// moment that mattered, or faded them before they could be read; this lane is the default that
+// avoids both. Each message stays at least as long as its words take to read (0.8 s, plus about
+// 0.3 s a word); a new one waits until the one on screen has been read, then takes its place; the
+// same key again merges (its count goes up and it pulses); a critical one clears the lane at once.
+// Where it paints is the band away from the player. Pure, no DOM (funtools test/hud-kit.test.ts);
+// hud-kit.tsx draws it. An option: keep, restyle or delete (skill funpixel-mobile-ui, hud-genres.md).
+
+export interface Toast { id: number; key: string; text: string; count: number; until: number; critical: boolean; bumps: number; shown: number; life: number }
+
+export const TOASTS = { maxVisible: 1, ms: 1600, readMs: 800, perWordMs: 300, waiting: 2 };
+
+/** On screen now: at most one. */
+export const toasts: Toast[] = [];
+/** Waiting for the lane, oldest first; over `TOASTS.waiting` the oldest is dropped (stale news). */
+export const waiting: Toast[] = [];
+const listeners = new Set<() => void>();
+let seq = 0;
+
+const notify = () => { for (const l of listeners) l(); };
+const now = () => (typeof performance === 'object' ? performance.now() : Date.now());
+const words = (text: string) => text.split(/\s+/).filter((w) => /\p{L}{2,}/u.test(w)).length;
+
+/** The time `text` needs to be read: "+10" is glanced, "Wave 3: beetles" is read. */
+export const readTime = (text: string) => Math.max(TOASTS.readMs, words(text) * TOASTS.perWordMs);
+
+/** Show `text`; the same key again merges (×2, ×3 …) rather than stacking, and one message shows at a time. */
+export function toast(text: string, opts: { key?: string; ms?: number; critical?: boolean; at?: number } = {}): Toast {
+  const at = opts.at ?? now(), key = opts.key ?? text, life = Math.max(opts.ms ?? TOASTS.ms, readTime(text));
+  const same = toasts.find((t) => t.key === key) ?? waiting.find((t) => t.key === key);
+  if (same) {
+    Object.assign(same, { text, life, until: at + life, count: same.count + 1, bumps: same.bumps + 1 });
+    notify();
+    return same;
+  }
+  const t: Toast = { id: ++seq, key, text, count: 1, until: at + life, critical: !!opts.critical, bumps: 0, shown: at, life };
+  const current = toasts[0];
+  if (opts.critical) { toasts.length = 0; waiting.length = 0; toasts.push(t); }
+  else if (!current || (!current.critical && at - current.shown >= readTime(current.text))) { toasts.length = 0; toasts.push(t); }
+  else {
+    waiting.push(t);
+    while (waiting.length > TOASTS.waiting) waiting.shift();
+  }
+  notify();
+  return t;
+}
+
+/** Drop the message whose time is up and bring in the next; call once a frame (hud-kit.tsx does). */
+export function expire(at = now()): void {
+  let changed = false;
+  for (let i = toasts.length - 1; i >= 0; i--) if (toasts[i].until <= at) { toasts.splice(i, 1); changed = true; }
+  if (!toasts.length && waiting.length) {
+    const next = waiting.shift()!;
+    Object.assign(next, { shown: at, until: at + next.life });
+    toasts.push(next);
+    changed = true;
+  }
+  if (changed) notify();
+}
+
+export function clearToasts(): void {
+  toasts.length = 0;
+  waiting.length = 0;
+  notify();
+}
+
+export function onToasts(fn: () => void): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+/** The band a message may use: the one away from the player (`playerY` is 0 at the top, 1 at the bottom). */
+export const zoneFor = (playerY: number | null | undefined): 'top' | 'bottom' =>
+  typeof playerY === 'number' && playerY < 0.45 ? 'bottom' : 'top';

package/templates/common/src/world.ts

@@ -0,0 +1,91 @@
+// The world `npx @funpixel/tools world forge` writes (design/world/world.json and its room files),
+// read with no engine: rooms, tiles, heights, props, places and each room's light. Nothing imports
+// it until the game has a world; drawing it is the game's own (yours to change or drop). In Vite:
+//
+//   import { loadWorld, room, eachTile, heightAt, place, lightOf } from './world';
+//   const world = loadWorld(import.meta.glob('../design/world/**/*.json', { eager: true, import: 'default' }));
+//   const here = room(world!, world!.critical_path[0]);
+//   // Pixi: eachTile(here, (x, y, kind) => { if (kind === 'solid') wall(x * TILE, y * TILE); });
+//   // Three: for (const i of here.instances) spawn(i.kind, i.pos, i.rot, i.scale);
+//   //        ground vertex y = heightAt(here, x, z, world!.cell); start at place(here, 'arrival'); fog from lightOf(world!, here)
+//
+// A name that is not there degrades with a warning naming the ones that are: a typo never throws in
+// the load path, and never quietly drops the player at (0, 0).
+
+export type TileKind = 'solid' | 'floor' | 'hazard' | 'arrival' | 'goal' | 'pickup' | 'door';
+const TILES: Record<string, TileKind> = { '#': 'solid', '.': 'floor', '^': 'hazard', S: 'arrival', G: 'goal', '*': 'pickup', D: 'door' };
+
+export interface WorldInstance { id: string; kind: string; role: string; pos: number[]; rot: number; scale: number; solid: boolean }
+export interface WorldDoor { id: string; to: string; at: [number, number]; kind: string }
+export interface WorldPlace { name: string; at: number[]; label?: string }
+export interface Light { sky?: string; fog?: { color: string; near: number; far: number }; light?: { color: string; intensity: number }; ambient?: number }
+export interface WorldRoom {
+  id: string; chapter: string; role: string; shape: string; size: [number, number];
+  tiles?: string[]; heights?: number[][]; doors: WorldDoor[]; places: WorldPlace[]; instances: WorldInstance[]; atmosphere: Light;
+}
+export interface World {
+  kind: '2d' | '3d'; seed: number; cell: number; atmosphere: Light; movement?: { step: number };
+  chapters: Array<{ id: string; name: string; rooms: string[]; landmark?: string }>;
+  rooms: WorldRoom[]; edges: Array<{ id: string; from: string; to: string; kind: string }>; critical_path: string[];
+}
+
+/** The world from a map of path → parsed JSON (Vite's import.meta.glob, or your own fetches); null when there is none. */
+export function loadWorld(files: Record<string, unknown>): World | null {
+  const find = (rel: string) => Object.entries(files).find(([k]) => k === rel || k.endsWith(`/${rel}`))?.[1] as any;
+  const w = find('world/world.json') ?? find('world.json');
+  if (!w || !Array.isArray(w.rooms)) return null;
+  const rooms = w.rooms.map((r: any) => ({
+    ...r,
+    tiles: r.tiles ?? (r.file ? find(`world/${r.file}`)?.tiles : undefined),
+    heights: typeof r.heights === 'string' ? find(`world/${r.heights}`)?.heights : r.heights,
+  }));
+  return { ...w, rooms };
+}
+
+const warnMissing = (what: string, name: string, known: string[]) => console.warn(`[world] no ${what} "${name}"; there is ${known.join(', ') || 'none'}`);
+
+/** A room by id; a missing id warns and gives the first room. */
+export function room(world: World, id: string): WorldRoom {
+  const r = world.rooms.find((x) => x.id === id);
+  if (!r) warnMissing('room', id, world.rooms.map((x) => x.id));
+  return r ?? world.rooms[0];
+}
+
+/** What stands at a tile (2D); outside the room is solid. */
+export function tileAt(r: WorldRoom, x: number, y: number): TileKind {
+  return TILES[r.tiles?.[y]?.[x] ?? '#'] ?? 'floor';
+}
+
+export function eachTile(r: WorldRoom, fn: (x: number, y: number, kind: TileKind) => void): void {
+  r.tiles?.forEach((row, y) => { for (let x = 0; x < row.length; x++) fn(x, y, TILES[row[x]] ?? 'floor'); });
+}
+
+/** Ground height (3D) at world x, z in metres, smooth between cell centres. */
+export function heightAt(r: WorldRoom, x: number, z: number, cell = 2): number {
+  const h = r.heights;
+  if (!h?.length) return 0;
+  const cx = Math.max(0, Math.min(h[0].length - 1, x / cell - 0.5)), cz = Math.max(0, Math.min(h.length - 1, z / cell - 0.5));
+  const x0 = Math.floor(cx), z0 = Math.floor(cz), x1 = Math.min(x0 + 1, h[0].length - 1), z1 = Math.min(z0 + 1, h.length - 1);
+  const tx = cx - x0, tz = cz - z0;
+  const a = h[z0][x0] + (h[z0][x1] - h[z0][x0]) * tx, b = h[z1][x0] + (h[z1][x1] - h[z1][x0]) * tx;
+  return a + (b - a) * tz;
+}
+
+/** A named spot (arrival, goal, reward, vista, landmark); a missing one warns and gives the arrival. */
+export function place(r: WorldRoom, name: string): number[] {
+  const p = r.places.find((x) => x.name === name);
+  if (!p) warnMissing(`place in ${r.id}`, name, r.places.map((x) => x.name));
+  return (p ?? r.places.find((x) => x.name === 'arrival') ?? r.places[0])?.at ?? [0, 0, 0];
+}
+
+/** The room's light: the world's default with the room's own changes over it. */
+export function lightOf(world: World, r: WorldRoom): Light {
+  const a = world.atmosphere, o = r.atmosphere ?? {};
+  return { ...a, ...o, ...(a.fog || o.fog ? { fog: { ...a.fog!, ...o.fog } } : {}), ...(a.light || o.light ? { light: { ...a.light!, ...o.light } } : {}) };
+}
+
+/** Where a door leads, or null when it leads nowhere. */
+export function through(world: World, r: WorldRoom, doorId: string): WorldRoom | null {
+  const d = r.doors.find((x) => x.id === doorId);
+  return d ? world.rooms.find((x) => x.id === d.to) ?? null : null;
+}

package/templates/common/test/feel.json

@@ -0,0 +1,36 @@
+{
+  "name": "feel",
+  "viewport": "desktop",
+  "seed": 1,
+  "steps": [
+    "until screen=title 3000",
+    "press Space",
+    "until screen=playing 3000",
+    "press ArrowRight 2",
+    "wait 400",
+    "press ArrowUp",
+    "wait 700",
+    "press ArrowUp 12",
+    "wait 600",
+    "until control=false 9000",
+    "until screen=lost 3000",
+    "retry press Space",
+    "wait 500"
+  ],
+  "expect": {
+    "hop height": "0.8 body",
+    "time in the air": "0.5 s",
+    "apex hang": "0.16 s",
+    "invulnerable window": "0.35 s",
+    "hop cooldown": "0.1 s",
+    "spike tell": "0.6 s",
+    "death beat": "0.5 s",
+    "restart": "under 2 s",
+    "coyote time (late hop)": "0.1 s",
+    "hop buffer (early press)": "0.1 s"
+  },
+  "sweeps": {
+    "coyote": { "steps": ["until screen=title 3000", "press Space", "until screen=playing 3000"], "anchor": "threats.0.phase=strike", "press": "ArrowUp", "success": "hero.grounded=false", "within": 200 },
+    "buffer": { "steps": ["until screen=title 3000", "press Space", "until screen=playing 3000", "wait 300"], "cue": "ArrowUp", "anchor": "hero.grounded=true", "press": "ArrowUp", "success": "hero.grounded=false", "within": 300 }
+  }
+}

package/templates/common/test/platform.test.ts

@@ -0,0 +1,42 @@
+// The page boots where storage is blocked, and progress survives a reload: outcomes a player meets in a
+// sandboxed frame, private browsing or a full disk (The Last Good Robot's platform test, in small).
+// save.ts is engine-free so this runs under Node beside the rules.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+const g = globalThis as unknown as Record<string, unknown>;
+/** A storage whose every access throws, as a sandboxed frame or blocked site data gives. */
+const denyStorage = () => Object.defineProperty(globalThis, 'localStorage', { configurable: true, get() { throw new Error('SecurityError: access denied'); } });
+/** A working in-memory storage, shared by every load of save.ts in this test (a "reload"). */
+function fakeStorage(): Map<string, string> {
+  const m = new Map<string, string>();
+  const s = { getItem: (k: string) => m.get(k) ?? null, setItem: (k: string, v: string) => { m.set(k, String(v)); }, removeItem: (k: string) => { m.delete(k); } };
+  Object.defineProperty(globalThis, 'localStorage', { configurable: true, value: s, writable: true });
+  return m;
+}
+
+test('the page boots where storage throws: progress starts at its defaults and saving never throws', async () => {
+  denyStorage();
+  const { progress, storage } = await import('../src/save.ts?denied');
+  assert.equal(progress.data.best, 0);
+  progress.update({ best: 9 });
+  assert.equal(progress.flush().ok, true, 'the session keeps its copy');
+  storage.setItem('k', 'v');
+  assert.equal(storage.getItem('k'), 'v');
+  delete g.localStorage;
+});
+
+test('progress survives a reload, and a corrupt save falls back to the defaults', async () => {
+  const m = fakeStorage();
+  const first = await import('../src/save.ts?first');
+  first.progress.update({ best: 42, reached: 3 });
+  first.progress.flush();
+  const again = await import('../src/save.ts?reload');
+  assert.equal(again.progress.data.best, 42);
+  assert.equal(again.progress.data.reached, 3);
+  m.set('progress', '{not json');
+  const broken = await import('../src/save.ts?corrupt');
+  assert.equal(broken.progress.data.best, 0);
+  delete g.localStorage;
+});

package/templates/common/test/probes.ts

@@ -0,0 +1,72 @@
+// The rules played by five policies over 100 seeds each (src/probe-kit.ts), printed as JSON for
+// `npx @funpixel/tools sim`, which reads it: standing still must not win, a naive player should not
+// do as well as a sharp one unless the design says so, doing what the game teaches should pay.
+// Rewrite the policies with your rules: each sees only what a player could see. Run: node test/probes.ts
+// This file and src/rules.ts are one piece: when you rewrite the rules, rewrite this in the same
+// step (it plays the demo until then), and set the seconds per run past the length the game means
+// to have — sim reads play length from the sharp bot (15 min and an ending, the design doc's
+// play-length line; name the ending in ended(run)). With levels, add level(run) to the game below: sim splits clear rate, loss
+// rate and time per level for each player and warns on a flat level, a wall and a run nothing loses.
+//
+// Optional, when the game has them: a staged moment (the seed and time that give the best REAL
+// signature moment; the moment view's enter() replays it with replayTo) and a music timeline
+// (the game's own musicMix(run) sampled while a bot plays; `follow` names the layer and the
+// on-screen number it should rise with).
+
+import { bestStep, GOAL, hop, inReach, move, newRun, phase, SLOTS, TELL_SECONDS, tick, type Run } from '../src/rules.ts';
+import { cohort, stageMoment, type Ev, type Policy, type ProbeGame } from '../src/probe-kit.ts';
+import { humanRate } from '../src/probe-human.ts';
+
+/** A step (±1), a hop (2) or nothing (0). A run a spike ended is kept in `spiked`. */
+type Press = 1 | -1 | 0 | 2;
+const spiked = new WeakSet<Run>();
+const game: ProbeGame<Run, Press> = {
+  newRun, dt: 0.05,
+  step(run, p) {
+    const ev: Ev[] = [];
+    if (p === 2) { if (hop(run)) ev.push({ type: 'hop' }); }
+    else if (p) { const m = move(run, p); if (m.picked !== null) ev.push({ type: 'pickup' }); if (m.bumped) ev.push({ type: 'bump' }); }
+    if (tick(run, 0.05) === 'lost' && run.timeLeft > 0) { spiked.add(run); ev.push({ type: 'spiked' }); }
+    return ev;
+  },
+  outcome: (run) => (run.score >= GOAL ? 'won' : run.timeLeft <= 0 || spiked.has(run) ? 'lost' : null),
+  progress: (run) => run.score,
+  firstSuccess: (run) => run.score >= 5,
+  broken: (run) => (Number.isFinite(run.x) ? null : 'position is not a number'),
+};
+
+/** Straight at the nearest gem that is there, cracks or not: the naive line. */
+const toGem = (run: Run): Press => {
+  let best = Infinity;
+  for (let i = 0; i < SLOTS; i++) if (run.gems[i] === 0 && i !== run.x && Math.abs(i - run.x) < Math.abs(best)) best = i - run.x;
+  return best === Infinity ? 0 : best > 0 ? 1 : -1;
+};
+/** The crack is under the player and the strike is near: a hop now clears it. */
+const hopTime = (run: Run) => phase(run) === 'tell' && inReach(run) && run.spike!.t >= TELL_SECONDS - 0.2;
+
+/** Press `choose(run)` once every `react` seconds, as a hand would; `reflex` presses between (a hop). */
+const every = (react: number, choose: (run: Run, rnd: () => number) => Press, reflex?: (run: Run) => Press) => (seed: number) => {
+  let wait = 0, s = seed;
+  const rnd = () => ((s = (s * 1103515245 + 12345) >>> 0) / 4294967296);
+  return (run: Run): Press => reflex?.(run) || ((wait -= 0.05) > 0 ? 0 : ((wait = react), choose(run, rnd)));
+};
+
+const policies: Policy<Run, Press>[] = [
+  { name: 'idle', role: 'idle', says: 'never presses', make: () => () => 0 },
+  { name: 'naive', role: 'naive', says: 'steers straight at the nearest gem, a press every 0.35 s, cracks or not', make: every(0.35, toGem) },
+  { name: 'taught', role: 'taught', says: 'what the how-to says: walk, turn at the wall, hop the spike late in its glow, a press every 0.18 s', make: every(0.18, (run) => (run.x <= 0 ? 1 : run.x >= SLOTS - 1 ? -1 : run.facing), (run) => (hopTime(run) ? 2 : 0)) },
+  { name: 'skilled', role: 'skilled', says: 'nearest gem, stepping off every crack, a press every 0.12 s', make: every(0.12, bestStep) },
+  { name: 'novice', role: 'novice', says: 'nearest gem every 0.6 s, one press in five the wrong way; hops when it sees the crack under it', make: every(0.6, (run, rnd) => (phase(run) === 'tell' && inReach(run) ? 2 : rnd() < 0.2 ? (-toGem(run) as Press) : toGem(run))) },
+];
+
+const best = policies.find((p) => p.role === 'skilled')!;
+// The sharp line again at a thumb's rate (12 decisions a second, 200 ms to react): a level only the bot clears is a wall.
+policies.push(humanRate({ ...best, make: () => (run) => bestStep(run) }, game.dt, { rest: 0 }));
+
+const seeds = Array.from({ length: 100 }, (_, i) => i + 1);
+console.log(JSON.stringify({
+  probes: 1,
+  cohorts: policies.map((p) => cohort(game, p, seeds, 60)),
+  moments: [{ name: 'streak', says: 'gems picked in 2 s', candidates: stageMoment(game, best, { seeds: seeds.slice(0, 20), at: [2, 4, 6], window: 2, score: (e) => (e.type === 'pickup' ? 1 : 0) }) }],
+  timelines: [],
+}));

package/templates/common/test/rules.test.ts

@@ -0,0 +1,88 @@
+// The rules under Node: `npm test` (Node 22.18+ runs TypeScript as is). Kept
+// outside src/, so the platform's build never type-checks it. Name a
+// test after the rule it proves, and grow this file with the rules: the team's
+// best games carry hundreds.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { botRound, GOAL, HOP_BUFFER, HOP_COOLDOWN, HOP_LATE, HOP_SAFE, HOP_SECONDS, hop, move, newRun, phase, ROUND_SECONDS, SLOTS, SPIKE_FIRST, TELL_SECONDS, tick } from '../src/rules.ts';
+
+test('a press moves half a slot, and the wall stops it', () => {
+  const r = newRun(1);
+  move(r, 1);
+  assert.equal(r.x, Math.floor(SLOTS / 2) + 0.5);
+  for (let i = 0; i < SLOTS * 2; i++) move(r, 1);
+  assert.equal(move(r, 1).bumped, true);
+});
+
+test('a gem scores once, then comes back after a moment', () => {
+  const r = newRun(1);
+  move(r, 1);
+  assert.equal(move(r, 1).picked, Math.floor(SLOTS / 2) + 1);
+  move(r, -1);
+  assert.equal(move(r, 1).picked, null, 'not back yet');
+  tick(r, 1);
+  move(r, -1);
+  assert.notEqual(move(r, 1).picked, null, 'back after a second');
+});
+
+test(`collecting ${GOAL} wins, dodging the spikes; the clock running out loses`, () => {
+  assert.equal(botRound(newRun(5), 0.25), 'won');
+  const r = newRun(5);
+  r.nextSpike = Infinity;
+  assert.equal(tick(r, ROUND_SECONDS), 'lost');
+  assert.equal(r.timeLeft, 0);
+});
+
+test(`a spike's crack glows ${TELL_SECONDS} s before it strikes; standing on it loses, a slot away is clear`, () => {
+  const r = newRun(2);
+  assert.equal(tick(r, SPIKE_FIRST), null);
+  assert.equal(phase(r), 'tell');
+  assert.equal(tick(r, TELL_SECONDS - 0.1), null, 'the warning is not the hit');
+  assert.equal(tick(r, 0.1 + HOP_LATE), 'lost');
+  const away = newRun(2);
+  tick(away, SPIKE_FIRST);
+  move(away, 1); move(away, 1);
+  assert.equal(tick(away, 1), null);
+});
+
+test(`the hop: ${HOP_SECONDS} s in the air, safe for ${HOP_SAFE} s, ready again ${HOP_COOLDOWN} s after landing`, () => {
+  const r = newRun(3);
+  tick(r, SPIKE_FIRST + TELL_SECONDS - 0.15);
+  assert.ok(hop(r), 'a hop late in the tell');
+  assert.equal(hop(r), false, 'not twice in the air');
+  assert.equal(tick(r, HOP_SECONDS), null, 'it clears the strike');
+  assert.equal(hop(r), false, 'resting: the press is kept');
+  tick(r, HOP_COOLDOWN);
+  assert.ok(r.hop >= 0, 'and takes off the moment the hop is ready');
+  const early = newRun(3);
+  tick(early, SPIKE_FIRST);
+  hop(early);
+  assert.equal(tick(early, TELL_SECONDS + 0.1), 'lost', 'a hop taken at the first glow lands in the strike: the committed landing is open');
+});
+
+test(`forgiveness: a press ${HOP_BUFFER} s before landing hops when ready; a spike hits ${HOP_LATE} s after it stands`, () => {
+  const r = newRun(3);
+  hop(r);
+  tick(r, HOP_SECONDS - HOP_BUFFER);
+  assert.equal(hop(r), false, 'still in the air');
+  tick(r, HOP_BUFFER + HOP_COOLDOWN);
+  assert.ok(r.hop >= 0, 'the early press took off when the hop was ready');
+  const early = newRun(3);
+  hop(early);
+  tick(early, HOP_SECONDS - HOP_BUFFER - 0.05);
+  hop(early);
+  tick(early, 0.1 + HOP_COOLDOWN);
+  assert.equal(early.hop, -1, 'a press before the buffer is dropped');
+  const late = newRun(3);
+  assert.equal(tick(late, SPIKE_FIRST + TELL_SECONDS + HOP_LATE - 0.05), null, 'the spike stands, not yet a hit');
+  assert.ok(hop(late));
+  assert.equal(tick(late, 0.5), null, 'a hop that late still clears it');
+  assert.equal(tick(newRun(3), SPIKE_FIRST + TELL_SECONDS + HOP_LATE), 'lost', 'later than that is a hit');
+});
+
+test('the same seed replays the same round', () => {
+  const a = newRun(9), b = newRun(9);
+  for (let i = 0; i < 12; i++) { move(a, 1); move(b, 1); tick(a, 0.7); tick(b, 0.7); }
+  assert.deepEqual(a, b);
+});