@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/src/probe-kit.ts

@@ -0,0 +1,99 @@
+// probe-kit.ts — the rules played by simple policies over many seeds, engine-free: does standing still win? does a
+// naive steer-to-target bot do as well as a sharp one (no skill ceiling)? does the taught line pay? how long does a good
+// run last, and does it reach an ending? which seed stages the best REAL moment? test/probes.ts wires the game in; `npx @funpixel/tools sim` reads it.
+
+export type Outcome = 'won' | 'lost' | null; export interface Ev { type: string } export type Role = 'idle' | 'naive' | 'taught' | 'skilled' | 'novice' | 'middle';
+
+/** The game as the probes see it: its own rules, advanced a fixed step at a time. */
+export interface ProbeGame<R, I> {
+  newRun(seed: number): R;
+  /** One fixed step of `dt` seconds with the policy's input; events are data ({ type }). */
+  step(run: R, input: I): readonly Ev[]; dt: number;
+  outcome(run: R): Outcome;
+  /** How far the run got (waves cleared, score, level): higher is further. */
+  progress(run: R): number;
+  /** The first success a newcomer must reach (the novice floor), when the game names one. */
+  firstSuccess?(run: R): boolean;
+  /** What must never happen (NaN, off the map, inside a wall): its name, else null. */
+  broken?(run: R): string | null;
+  /** level: the level, stage or wave the run is on (1, 2 …; sim splits play length by it). ended: the ending (the last content, an end screen; a win counts): the run stops there, timed apart from losses. */
+  level?(run: R): number; ended?(run: R): boolean;
+}
+
+/** A player: `make(seed)` returns its press each step from what it can see; `human`: probe-human.ts; `foresight`: what it knows
+ *  a person cannot (clones the run, simulates ahead: never counted as human); role `middle` does SOME of what is taught. */
+export interface Policy<R, I> { name: string; role: Role; says: string; make(seed: number): (run: R) => I; human?: { hz: number; reactMs: number }; foresight?: string }
+export interface Cohort {
+  policy: string; role: Role; says: string; seeds: number; seconds: number; won: number; lost: number; open: number;
+  progress: { mean: number; min: number; max: number }; meanSeconds: number;
+  /** Seeds that reached game.firstSuccess (null: none named); events: mean count per run by type; ended/endedAt: seeds that reached the ending (or won; never a loss), and when. */
+  firstSuccess: number | null; events: Record<string, number>; ended: number; endedAt: number | null;
+  /** broken: absent with no broken() check, null when never broken. spread: run length across seeds. levels (with
+   *  game.level): seeds that reached, cleared (went on or won there) and lost each level, when and how long there. */
+  broken?: { what: string; seed: number; at: number } | null; lostSeeds: number[]; spread: { min: number; median: number; max: number };
+  levels?: Array<{ level: number; reached: number; meanAt: number; cleared: number; lost: number; meanSeconds: number }>; human?: Policy<unknown, unknown>['human']; foresight?: string;
+}
+const r2 = (n: number) => Math.round(n * 100) / 100;
+/** Play one policy from each seed until the run ends or `seconds` pass. */
+export function cohort<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seeds: number[], seconds: number): Cohort {
+  const prog: number[] = [], events: Record<string, number> = {}, lostSeeds: number[] = [], times: number[] = [];
+  const per = new Map<number, { at: number[]; spent: number[]; cleared: number; lost: number }>();
+  const at = (lv: number) => per.get(lv) ?? (per.set(lv, { at: [], spent: [], cleared: 0, lost: 0 }), per.get(lv)!);
+  let won = 0, lost = 0, time = 0, first = 0, broken: Cohort['broken'] = null; const ends: number[] = [];
+  for (const seed of seeds) {
+    const run = game.newRun(seed), input = p.make(seed);
+    let t = 0, reached = false, lv = game.level?.(run), since = 0;
+    if (lv !== undefined) at(lv).at.push(0);
+    while (t < seconds && !game.outcome(run) && !game.ended?.(run)) {
+      for (const e of game.step(run, input(run))) events[e.type] = (events[e.type] ?? 0) + 1;
+      t += game.dt; reached ||= game.firstSuccess?.(run) ?? false;
+      const b: string | null | undefined = broken ? null : game.broken?.(run);
+      if (b) broken = { what: b, seed, at: r2(t) };
+      const now = game.level?.(run);
+      if (now !== lv) {
+        if (lv !== undefined) { at(lv).spent.push(t - since); at(lv).cleared += now !== undefined && now > lv ? 1 : 0; }
+        if (now !== undefined) at(now).at.push(t); lv = now; since = t;
+      }
+    }
+    const o = game.outcome(run); if (o === 'won' || (o !== 'lost' && game.ended?.(run))) ends.push(t);
+    if (lv !== undefined) { at(lv).spent.push(t - since); if (o === 'won') at(lv).cleared++; else if (o === 'lost') at(lv).lost++; }
+    if (o === 'won') won++; else if (o === 'lost') { lost++; lostSeeds.push(seed); }
+    first += reached ? 1 : 0; prog.push(game.progress(run)); time += t; times.push(t);
+  }
+  const n = seeds.length || 1; times.sort((a, b) => a - b);
+  const mean = (xs: number[]) => (xs.length ? r2(xs.reduce((a, b) => a + b, 0) / xs.length) : 0), levels = [...per].sort((a, b) => a[0] - b[0]).map(([level, l]) => ({ level, reached: l.at.length, meanAt: mean(l.at), cleared: l.cleared, lost: l.lost, meanSeconds: mean(l.spent) }));
+  return {
+    policy: p.name, role: p.role, says: p.says, seeds: seeds.length, seconds, won, lost, open: seeds.length - won - lost,
+    progress: { mean: r2(prog.reduce((a, b) => a + b, 0) / n), min: Math.min(...prog), max: Math.max(...prog) },
+    meanSeconds: r2(time / n), firstSuccess: game.firstSuccess ? first : null, ended: ends.length, endedAt: ends.length ? mean(ends) : null,
+    events: Object.fromEntries(Object.entries(events).map(([k, v]) => [k, r2(v / n)])), lostSeeds: lostSeeds.slice(0, 12),
+    spread: { min: r2(times[0] ?? 0), median: r2(times[times.length >> 1] ?? 0), max: r2(times[times.length - 1] ?? 0) },
+    ...(game.level ? { levels } : {}), ...(game.broken ? { broken } : {}), ...(p.human ? { human: p.human } : {}), ...(p.foresight ? { foresight: p.foresight } : {}),
+  };
+}
+
+function advance<R, I>(game: ProbeGame<R, I>, run: R, input: (run: R) => I, seconds: number): Ev[] {
+  const out: Ev[] = []; for (let t = 0; t < seconds && !game.outcome(run); t += game.dt) out.push(...game.step(run, input(run))); return out;
+}
+/** The run a policy reaches from `seed` after `seconds`: a moment view's enter() replays the staged moment with it. */
+export function replayTo<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seed: number, seconds: number): R {
+  const run = game.newRun(seed); advance(game, run, p.make(seed), seconds); return run;
+}
+/** Search seeds × start times for the best REAL signature moment: `score` rates each event in the window after. */
+export function stageMoment<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, o: { seeds: number[]; at: number[]; window: number; score: (e: Ev) => number }) {
+  const found: Array<{ seed: number; at: number; score: number }> = [];
+  for (const seed of o.seeds) for (const at of o.at) {
+    const run = game.newRun(seed), input = p.make(seed); advance(game, run, input, at);
+    found.push({ seed, at, score: r2(advance(game, run, input, o.window).reduce((s, e) => s + o.score(e), 0)) });
+  }
+  return found.sort((a, b) => b.score - a.score || a.seed - b.seed || a.at - b.at).slice(0, 5);
+}
+/** Sample the run every `every` s while a policy plays: e.g. the game's own musicMix(run) beside what is on screen. */
+export function timeline<R, I>(game: ProbeGame<R, I>, p: Policy<R, I>, seed: number, seconds: number, every: number, sample: (run: R, since: Ev[]) => Record<string, number>) {
+  const run = game.newRun(seed), input = p.make(seed), rows: Array<Record<string, number>> = []; let since: Ev[] = [];
+  for (let t = 0, next = 0; t < seconds && !game.outcome(run); t += game.dt) {
+    since.push(...game.step(run, input(run)));
+    if (t >= next) { rows.push({ t: r2(t), ...sample(run, since) }); since = []; next += every; }
+  }
+  return rows;
+}

package/templates/common/src/rules.ts

@@ -0,0 +1,99 @@
+// The game's rules, engine-free (no Pixi, Three or DOM): the renderer draws this state and the self-tests
+// grade it offline, so a rule is testable without a frame. Grow the game here first. A track of slots with
+// a gem in each: step onto GOAL gems before the clock runs out. From SPIKE_FIRST on, a crack glows under the
+// player (the tell), then a spike stands there: hop it or step away. random(run) is seeded (__FPX_SEED__ + n).
+
+/** One key press moves STEP (half a slot), so two presses reach the next gem. */ export const SLOTS = 12, ROUND_SECONDS = 60, GOAL = 30, STEP = 0.5;
+/** A picked gem comes back after RESPAWN_SECONDS plus up to RESPAWN_JITTER, from the run's seed. */ export const RESPAWN_SECONDS = 0.3, RESPAWN_JITTER = 0.2;
+/** The hero's height in slots (the drawn body): hop heights are in body heights. */ export const BODY = 0.8;
+/** The hop, the one defensive verb: in the air HOP_SECONDS, HOP_HEIGHT bodies at the top, safe from
+ *  a spike for HOP_SAFE after take-off, then a committed, open landing; ready HOP_COOLDOWN after.
+ *  Forgiveness (Celeste: a 4-frame buffer, 0.1 s coyote time): a press up to HOP_BUFFER before the
+ *  landing hops when ready; a spike hits only HOP_LATE after it stands, so a hop or step that late saves. */
+export const HOP_SECONDS = 0.5, HOP_HEIGHT = 0.8, HOP_SAFE = 0.35, HOP_COOLDOWN = 0.1, HOP_BUFFER = 0.1, HOP_LATE = 0.1;
+/** The spike: the crack glows TELL_SECONDS, the spike stands STRIKE_SECONDS; the first at SPIKE_FIRST s (past
+ *  the arcade idle floor: a player reading the screen is not killed for it), the next SPIKE_EVERY s (plus up to a second) after one ends. */
+export const TELL_SECONDS = 0.6, STRIKE_SECONDS = 0.15, SPIKE_FIRST = 8, SPIKE_EVERY = 2.5;
+export interface Run {
+  /** Position in slots (0 … SLOTS - 1); per slot, seconds until its gem is back (0 = there). */
+  x: number; score: number; timeLeft: number; facing: 1 | -1; gems: number[];
+  /** Seconds since the hop took off (-1 on the ground), until it is ready again, and an early press kept for then. */
+  hop: number; hopCool: number; queued: boolean;
+  /** The spike under way (its slot, seconds since its crack began to glow), and the wait for the next. */
+  spike: { slot: number; t: number } | null; nextSpike: number;
+  seed: number; // the random source's state: newRun(seed) with the same seed replays the same round
+}
+export type Outcome = 'won' | 'lost' | null; export type Phase = 'rest' | 'tell' | 'strike';
+/** The rules' one random source (mulberry32): a number in [0, 1) that advances the run's seed. */
+export function random(run: Run): number {
+  run.seed = (run.seed + 0x6d2b79f5) | 0;
+  let t = Math.imul(run.seed ^ (run.seed >>> 15), 1 | run.seed);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+let runs = 0; /* runs started in this page */ const nextSeed = (fixed = (globalThis as { __FPX_SEED__?: unknown }).__FPX_SEED__): number => (typeof fixed === 'number' ? (fixed + runs++) | 0 : Date.now() | 0);
+export function newRun(seed = nextSeed()): Run {
+  const start = Math.floor(SLOTS / 2);
+  const gems = Array.from({ length: SLOTS }, (_, i) => (i === start ? RESPAWN_SECONDS : 0));
+  return { x: start, score: 0, timeLeft: ROUND_SECONDS, facing: 1, gems, hop: -1, hopCool: 0, queued: false, spike: null, nextSpike: SPIKE_FIRST, seed };
+}
+export function move(run: Run, dir: 1 | -1): { picked: number | null; bumped: boolean; outcome: Outcome } {
+  run.facing = dir;
+  const next = Math.min(SLOTS - 1, Math.max(0, run.x + dir * STEP));
+  if (next === run.x) return { picked: null, bumped: true, outcome: null };
+  run.x = next;
+  const slot = Math.round(run.x);
+  if (Math.abs(run.x - slot) > 1e-9 || run.gems[slot] > 0) return { picked: null, bumped: false, outcome: null };
+  run.gems[slot] = RESPAWN_SECONDS + RESPAWN_JITTER * random(run);
+  run.score += 1;
+  return { picked: slot, bumped: false, outcome: run.score >= GOAL ? 'won' : null };
+}
+
+/** Take off, when on the ground and rested; false when it is not ready, keeping a press made within
+ *  HOP_BUFFER of the landing (or while resting) to take off the moment it is. */
+export function hop(run: Run): boolean {
+  const ready = run.hop < 0 && run.hopCool <= 0;
+  if (ready) run.hop = 0;
+  run.queued = !ready && (run.queued || run.hop < 0 || HOP_SECONDS - run.hop <= HOP_BUFFER + 1e-6);
+  return ready;
+}
+export const hopHeight = (run: Run): number => (run.hop < 0 ? 0 : 4 * HOP_HEIGHT * BODY * (run.hop / HOP_SECONDS) * (1 - run.hop / HOP_SECONDS));
+export const safe = (run: Run): boolean => run.hop >= 0 && run.hop < HOP_SAFE;
+export const phase = (run: Run): Phase => (!run.spike ? 'rest' : run.spike.t < TELL_SECONDS ? 'tell' : 'strike');
+/** Within a spike's reach: half a slot away is still hit, a whole slot is clear. */
+export const inReach = (run: Run, x = run.x): boolean => !!run.spike && Math.abs(x - run.spike.slot) < 0.75;
+
+/** Advance the clock in steps of at most 50 ms; 'lost' when a spike or the clock ends the round this tick. */
+export function tick(run: Run, dt: number): Outcome {
+  const n = Math.max(1, Math.ceil(dt / 0.05 - 1e-6)), h = dt / n, E = 1e-6;
+  for (let k = 0; k < n; k++) {
+    for (let i = 0; i < run.gems.length; i++) run.gems[i] = Math.max(0, run.gems[i] - h);
+    if (run.hop >= 0 && (run.hop += h) >= HOP_SECONDS - E) { run.hop = -1; run.hopCool = HOP_COOLDOWN; } else if (run.hop < 0) run.hopCool = Math.max(0, run.hopCool - h);
+    if (run.queued && run.hop < 0 && run.hopCool <= E) { run.hopCool = 0; hop(run); }
+    if (!run.spike && (run.nextSpike -= h) <= E) run.spike = { slot: Math.round(run.x), t: 0 };
+    else if (run.spike && (run.spike.t += h) >= TELL_SECONDS - E) {
+      if (run.spike.t >= TELL_SECONDS + HOP_LATE - E && inReach(run) && !safe(run)) return 'lost';
+      if (run.spike.t >= TELL_SECONDS + STRIKE_SECONDS - E) { run.spike = null; run.nextSpike = SPIKE_EVERY + random(run); }
+    }
+    const was = run.timeLeft;
+    if ((run.timeLeft = run.timeLeft - h <= E ? 0 : run.timeLeft - h) === 0 && was > 0) return 'lost';
+  }
+  return null;
+}
+/** Which way a sharp player steps now: off a glowing crack, else toward the nearest gem (never into a crack), or 0. */
+export function bestStep(run: Run): 1 | -1 | 0 {
+  if (run.spike && inReach(run)) return run.x > run.spike.slot || (run.x === run.spike.slot && run.x < SLOTS - 1) ? 1 : -1;
+  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;
+  const dir = best === Infinity ? 0 : best > 0 ? 1 : -1;
+  return dir && !inReach(run, run.x + dir * STEP) ? dir : 0;
+}
+/** Play a round through the rules: a sharp bot pressing every `react` seconds, or never (null). */
+export function botRound(run: Run, react: number | null): Outcome {
+  for (let t = 0; t <= ROUND_SECONDS; t += react ?? 0.1) {
+    const dir = react === null ? 0 : bestStep(run);
+    const outcome = (dir ? move(run, dir).outcome : null) ?? tick(run, react ?? 0.1);
+    if (outcome) return outcome;
+  }
+  return null;
+}

package/templates/common/src/save.ts

@@ -0,0 +1,21 @@
+// Saving, engine-free so the rules' tests can load it: storage that never throws and progress kept through the
+// SDK's SaveManager. Yours to reshape (a chapter list, a level map, settings); what a check reads is the
+// outcome: progress survives a reload, and the page boots where storage is blocked (test/platform.test.ts;
+// one of the owner's games boots its own with storage that throws).
+
+import { SaveManager } from '@funpixel/sdk/save';
+
+const mem = new Map<string, string>();
+const real = (): Storage | null => { try { return globalThis.localStorage ?? null; } catch { return null; } };
+/** localStorage, with a memory copy where it throws (a sandboxed frame, blocked site data, a full quota): the game always boots. */
+export const storage = {
+  getItem(k: string): string | null { try { const v = real()?.getItem(k); if (v != null) return v; } catch { /* blocked */ } return mem.get(k) ?? null; },
+  setItem(k: string, v: string): void { mem.set(k, v); try { real()?.setItem(k, v); } catch { /* quota or blocked: the session keeps its copy */ } },
+  removeItem(k: string): void { mem.delete(k); try { real()?.removeItem(k); } catch { /* blocked */ } },
+} as unknown as Storage;
+
+/**
+ * Progress that survives a reload: the furthest level or chapter reached, the ones done, the best. Versioned:
+ * a change of shape bumps `version` with a migration; a corrupt save falls back to these defaults.
+ */
+export const progress = new SaveManager({ key: 'progress', version: 1, defaults: { reached: 0, done: [] as string[], best: 0 } }, storage);

package/templates/common/src/screens.css

@@ -0,0 +1,34 @@
+/* The screens around the round (screens.tsx): cards on the shared .plate, and the title as a scene. */
+.screen { position: fixed; inset: 0; display: grid; place-items: center; background: rgba(0, 0, 0, 0.45); animation: fade 0.2s ease-out; }
+.card {
+  display: grid; gap: 14px; justify-items: center; padding: 28px 32px; max-width: min(420px, 86vw);
+  text-align: center; animation: pop 0.25s ease-out;
+}
+.card h1 { margin: 0; font-size: clamp(28px, 6vw, 44px); letter-spacing: 0.02em; font-family: var(--font-display); }
+/* The title is a scene, not a card: the play's world behind (no dimmer), the wordmark in the upper
+   band, one line of how to play, the start control low in the thumb zone. Held sideways the
+   wordmark and the start sit side by side so neither squeezes the other. */
+.title-screen {
+  background: none; display: grid; grid-template-rows: auto 1fr auto; place-items: center;
+  padding: max(48px, env(safe-area-inset-top)) var(--band-right, max(16px, env(safe-area-inset-right))) max(36px, env(safe-area-inset-bottom)) var(--band-left, max(16px, env(safe-area-inset-left)));
+} /* the sides keep to the band (frame.ts): clear of the notch held sideways */
+.title-band { display: grid; gap: 10px; justify-items: center; text-align: center; }
+.wordmark { margin: 0; font-family: var(--font-display); font-size: clamp(40px, 11vw, 72px); line-height: 1; letter-spacing: 0.02em; animation: breathe 3.2s ease-in-out infinite; text-shadow: 0 2px 0 var(--bg), 0 0 18px var(--bg); }
+img.wordmark { width: min(80vw, 520px); height: auto; font-size: 0; }
+.title-band .hint { max-width: 32ch; text-shadow: 0 1px 2px var(--bg); }
+.thumb-zone { grid-row: 3; display: grid; gap: 14px; justify-items: center; }
+@media (orientation: landscape) and (max-height: 500px) {
+  .title-screen { grid-template-rows: 1fr; grid-template-columns: 1fr auto; padding-top: max(16px, env(safe-area-inset-top)); padding-bottom: max(20px, env(safe-area-inset-bottom)); }
+  .title-band { grid-column: 1; align-self: start; justify-self: start; justify-items: start; text-align: left; }
+  .wordmark { font-size: clamp(32px, 9vh, 56px); transform-origin: left center; } /* it breathes away from the notch */
+  img.wordmark { width: min(46vw, 420px); }
+  .thumb-zone { grid-row: 1; grid-column: 2; align-self: end; justify-self: end; justify-items: end; }
+}
+.row { display: flex; gap: 12px; }
+.hint, .step { margin: 0; opacity: 0.85; line-height: 1.4; }
+.step { display: flex; gap: 10px; align-items: center; text-align: left; }
+.step svg { flex-shrink: 0; }
+.score { margin: 0; font-size: 48px; font-weight: 800; font-variant-numeric: tabular-nums; }
+.score span { display: block; font-size: 16px; font-weight: 600; opacity: 0.7; }
+.won h1 { color: var(--primary); }
+.lost h1 { color: var(--accent); }

package/templates/common/src/screens.tsx

@@ -0,0 +1,95 @@
+// Every screen around the round: the title (a real start control, marked
+// data-fpx-start so `verify --front-door` presses it), how to play, settings
+// (sound, motion), pause, and the two endings, each with an instant replay.
+// Each is a declared view (session.ts); each fades in (styles.css). The words
+// are the game's: replace them, keep the set. The title is a scene, not a card:
+// the play's world behind it with no dimmer, the wordmark in the upper band, one
+// line of how to play, the start control low in the thumb zone (styles.css lays
+// it out upright and sideways). The cards take the shared .plate.
+
+import type { ComponentChildren } from 'preact';
+import { applyMute } from './sound';
+import { Icon } from './icons';
+import { GOAL, ROUND_SECONDS } from './rules';
+import { go, show, useStore } from './store';
+import { Splash } from './splash';
+
+/** The wordmark as art from the style frame (e.g. '/ui/wordmark.png' in public/), or null: the name in --font-display. */
+export const WORDMARK: string | null = null;
+
+function Wordmark({ title }: { title: string }) {
+  return WORDMARK ? <img class="wordmark" src={WORDMARK} alt={title} /> : <h1 class="wordmark">{title}</h1>;
+}
+
+function Card({ heading, kind = '', children }: { heading: string; kind?: string; children?: ComponentChildren }) {
+  return (
+    <div class={`screen ${kind}`}>
+      <div class="card plate">
+        <h1>{heading}</h1>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+function Toggles() {
+  const s = useStore();
+  return (
+    <div class="row">
+      <button class="icon" data-fpx-touch="KeyM" aria-label={s.muted ? 'sound off' : 'sound on'}><Icon name={s.muted ? 'soundOff' : 'soundOn'} /></button>
+      <button class="icon" aria-label="how to play" onClick={() => go('howto')}><Icon name="help" /></button>
+      <button class="icon" aria-label="settings" onClick={() => go('settings')}><Icon name="settings" /></button>
+    </div>
+  );
+}
+
+export function Screens({ title }: { title: string }) {
+  const s = useStore();
+  switch (s.screen) {
+    case 'playing': return null;
+    case 'splash': return <Splash title={title} />;
+    case 'paused': return (
+      <Card heading="Paused">
+        <button class="primary" onClick={() => go('playing')}>Resume</button>
+        <Toggles />
+        <button onClick={() => go('title')}>Quit</button>
+      </Card>
+    );
+    case 'howto': return (
+      <Card heading="How to play">
+        <p class="step"><Icon name="gem" /> Step onto a gem to collect it. Get {GOAL}.</p>
+        <p class="step"><Icon name="clock" /> Before the {ROUND_SECONDS} seconds run out.</p>
+        <p class="step"><Icon name="up" /> A crack glows under you: hop over the spike (up arrow, W or Space) or step a slot away.</p>
+        <p class="step"><Icon name="right" /> Arrow keys or A and D; on a phone, swipe left or right on the play; tap or swipe up to hop.</p>
+        <button class="primary" onClick={() => go(s.back)}>Back</button>
+      </Card>
+    );
+    case 'settings': return (
+      <Card heading="Settings">
+        <button onClick={() => { show({ muted: !s.muted }); applyMute(); }}>Sound: {s.muted ? 'off' : 'on'}</button>
+        <button onClick={() => show({ motion: !s.motion })}>Screen shake and flashes: {s.motion ? 'on' : 'off'}</button>
+        <button onClick={() => show({ pad: !s.pad })}>On-screen buttons: {s.pad ? 'on' : 'off'}</button>
+        <button class="primary" onClick={() => go(s.back)}>Back</button>
+      </Card>
+    );
+    case 'won': case 'lost': return (
+      <Card heading={s.screen === 'won' ? 'You got them all' : s.lostTo === 'spike' ? 'Spiked' : "Time's up"} kind={s.screen}>
+        <p class="score">{s.score}<span>best {s.best}</span></p>
+        <button class="primary" onClick={() => go('playing')}>Play again</button>
+        <button onClick={() => go('title')}>Title</button>
+      </Card>
+    );
+    default: return (
+      <div class="screen title-screen">
+        <header class="title-band">
+          <Wordmark title={title} />
+          <p class="hint">Collect {GOAL} gems before the clock runs out. Hop the spikes.</p>
+        </header>
+        <footer class="thumb-zone">
+          <button class="primary start" data-fpx-start onClick={() => go('playing')}><Icon name="play" /> Play</button>
+          <Toggles />
+        </footer>
+      </div>
+    );
+  }
+}

package/templates/common/src/selftests.ts

@@ -0,0 +1,22 @@
+// The game's own tests, run in the page by verify (window.__FPX_SELFTEST__):
+// the rules alone, a sharp bot for balance, and the juice table. The same
+// rules are tested under Node too (test/rules.test.ts, `npm test`).
+
+import { botRound, GOAL, hop, HOP_LATE, move, newRun, phase, RESPAWN_SECONDS, ROUND_SECONDS, SPIKE_FIRST, TELL_SECONDS, tick } from './rules';
+import { feelTest, scaleTest } from './feel';
+
+export const selfTests = [
+  { name: 'a round starts with the clock full', run: () => newRun().timeLeft === ROUND_SECONDS },
+  { name: 'stepping onto a gem scores once', run: () => { const r = newRun(1); move(r, 1); move(r, 1); move(r, -1); move(r, 1); return r.score === 1; } },
+  { name: 'the same seed replays the same round', run: () => {
+    const a = newRun(7), b = newRun(7);
+    for (let i = 0; i < 8; i++) { move(a, 1); move(b, 1); }
+    return JSON.stringify(a) === JSON.stringify(b) && a.gems.some((g) => g > RESPAWN_SECONDS);
+  } },
+  { name: `a spike's crack glows ${TELL_SECONDS} s before it strikes`, run: () => { const r = newRun(2); return tick(r, SPIKE_FIRST) === null && phase(r) === 'tell' && tick(r, TELL_SECONDS - 0.1) === null && tick(r, 0.1 + HOP_LATE) === 'lost'; } },
+  { name: 'a hop late in the tell clears the strike', run: () => { const r = newRun(2); tick(r, SPIKE_FIRST + TELL_SECONDS - 0.15); return hop(r) && tick(r, 0.5) === null; } },
+  { name: `a sharp player (0.25 s a press) collects ${GOAL} and wins`, run: () => botRound(newRun(3), 0.25) === 'won' },
+  { name: 'a player who never moves loses', run: () => botRound(newRun(3), null) === 'lost' },
+  feelTest,
+  scaleTest,
+];

package/templates/common/src/session.ts

@@ -0,0 +1,99 @@
+// One round at a time, wired once for both engines: the rules, the screens,
+// input, the juice table, sound and the hooks verify reads (expose.ts). The
+// engine's game.ts only draws `session.run` and calls update() every frame.
+
+import { bestStep, hop, move, newRun, phase, tick, type Outcome } from './rules';
+import { go, onScreen, show, store } from './store';
+import { bindInput, pollGamepad, type Verb } from './input';
+import { juice, stepJuice } from './juice';
+import { answer } from './feel';
+import { exposeRound } from './expose';
+import { exposeHooks } from './fpx-hooks';
+import { applyMute, loadSounds, unlockAudio } from './sound';
+
+/** Seconds a lost round holds on the hit before its card: the death beat (the hero topples where it
+ *  fell, the spike still up), short enough that a retry is under a second away. */ export const DEATH_BEAT = 0.5;
+/** The round, the death beat left, how long the hero still shows its step, and the game's own clock
+ *  (seconds of every dt the loop gives update(): state `t`, the clock `funtools feel` measures on). */
+export const session = { run: newRun(), beat: 0, stepFor: 0, t: 0 };
+export const inControl = (): boolean => store.screen === 'playing' && session.beat === 0;
+
+function end(outcome: Outcome): void {
+  if (!outcome || !inControl()) return;
+  const spiked = outcome === 'lost' && session.run.timeLeft > 0;
+  answer(outcome === 'won' ? 'won' : spiked ? 'hit' : 'lost', session.run.x);
+  show(outcome === 'won' ? { wins: store.wins + 1 } : { losses: store.losses + 1, lostTo: spiked ? 'spike' : 'time' });
+  if (outcome === 'won') go('won'); else session.beat = DEATH_BEAT;
+}
+
+/** The beat over (or cut short by a view): the lost card, which takes a retry at once. */
+function endBeat(): void {
+  if (session.beat === 0) return;
+  session.beat = 0;
+  go('lost');
+}
+
+function step(dir: 1 | -1): void {
+  if (!inControl()) return;
+  const moved = move(session.run, dir);
+  if (moved.bumped) answer('bump', session.run.x); else session.stepFor = 0.15;
+  if (moved.picked !== null) answer('pickup', moved.picked);
+  show({ score: session.run.score });
+  end(moved.outcome);
+}
+
+function press(verb: Verb): void {
+  unlockAudio();
+  if (store.screen === 'splash') { go('title'); return; } // any press skips the splash (splash.tsx)
+  if (verb === 'mute') { show({ muted: !store.muted }); applyMute(); return; }
+  if (session.beat > 0) return; // the beat: input waits for the card
+  if (verb === 'left' || verb === 'right') step(verb === 'left' ? -1 : 1);
+  else if ((verb === 'hop' || verb === 'confirm') && inControl()) { if (hop(session.run)) answer('hop', session.run.x); }
+  else if (verb === 'pause' && (store.screen === 'playing' || store.screen === 'paused')) go(store.screen === 'playing' ? 'paused' : 'playing');
+  else if (verb === 'confirm' && store.screen !== 'playing') go('playing');
+}
+
+// Playing from anywhere but a pause starts a fresh round; an ending keeps the best.
+onScreen((next, prev) => {
+  if (next === 'playing' && prev !== 'paused') {
+    Object.assign(session, { run: newRun(), beat: 0, stepFor: 0 });
+    show({ score: 0, timeLeft: session.run.timeLeft });
+  }
+  if (next === 'won' || next === 'lost') show({ best: Math.max(store.best, session.run.score) });
+});
+
+/** Run the round's clock forward; the round ends through the rule, never around it. */
+function advance(dt: number): void {
+  const was = phase(session.run), grounded = session.run.hop < 0;
+  const outcome = tick(session.run, dt);
+  if (was === 'rest' && phase(session.run) === 'tell') answer('tell', session.run.spike!.slot);
+  if (grounded && session.run.hop >= 0) answer('hop', session.run.x); // a buffered press took off
+  if (Math.ceil(session.run.timeLeft) !== Math.ceil(store.timeLeft)) show({ timeLeft: session.run.timeLeft });
+  end(outcome);
+}
+
+/** Advance one frame: the gamepad and the juice always; the beat, then the round, except in hitstop. */
+export function update(dt: number): void {
+  pollGamepad(press);
+  stepJuice(dt);
+  session.t += dt; session.stepFor = Math.max(0, session.stepFor - dt);
+  if (store.screen !== 'playing') return;
+  if (session.beat > 0) { session.beat -= dt; if (session.beat <= 0) endBeat(); return; }
+  if (juice.freeze > 0) { juice.freeze -= dt; return; }
+  advance(dt);
+}
+
+/** A sharp player through the real rules: off a crack, toward the nearest gem, or a frame's wait. */
+function playToEnd(): void {
+  for (let i = 0; i < 20000 && inControl(); i++) {
+    const dir = bestStep(session.run);
+    if (dir) step(dir); else advance(0.05);
+  }
+}
+
+export function startSession(stage: HTMLElement): void {
+  bindInput(stage, press);
+  for (const ev of ['pointerup', 'keydown', 'touchend']) addEventListener(ev, unlockAudio);
+  exposeRound({ session, inControl, press, advance, playToEnd, endBeat });
+  void loadSounds(['pickup', 'bump', 'hop', 'crack', 'win', 'lose'], 'theme').then((any) => { if (any) exposeHooks({ audio: true }); });
+}

package/templates/common/src/sound.ts

@@ -0,0 +1,85 @@
+// Sound through the SDK's one AudioEngine: effects and one music bed on their
+// own buses into its master, which the mute drives. The first input unlocks
+// it and starts the bed; a big moment ducks the bed so its sound reads. The
+// sounds are the conventional files; a missing one is silent. `iosPatch:
+// false` lets the iPhone ringer switch mute the game; `true` plays through it
+// (rhythm, music games).
+
+import { AudioEngine } from '@funpixel/sdk/audio';
+import { findAsset } from './assets';
+import { store } from './store';
+
+/** The SDK's engine; platform.ts suspends its context while the game is held (the tab hidden). */
+export const audio = new AudioEngine({ iosPatch: false });
+audio.init();
+const sfxBus = audio.ctx.createGain();
+const musicBus = audio.ctx.createGain();
+const MUSIC_LEVEL = 0.5;
+sfxBus.connect(audio.master);
+musicBus.connect(audio.master);
+musicBus.gain.value = MUSIC_LEVEL;
+const buffers = new Map<string, AudioBuffer>();
+let bed: AudioBuffer | null = null;
+let bedPlaying = false;
+
+async function decode(url: string | null): Promise<AudioBuffer | null> {
+  if (!url) return null;
+  try {
+    return await audio.ctx.decodeAudioData(await (await fetch(url)).arrayBuffer());
+  } catch {
+    return null;
+  }
+}
+
+/** Load the effects and the music bed that exist; true when any did (the game makes sound). */
+export async function loadSounds(effects: string[], music: string): Promise<boolean> {
+  for (const name of effects) {
+    const b = await decode(await findAsset('sfx', name));
+    if (b) buffers.set(name, b);
+  }
+  bed = await decode(await findAsset('music', music));
+  applyMute();
+  return buffers.size > 0 || bed !== null;
+}
+
+export function play(name: string): void {
+  const b = buffers.get(name);
+  if (!b) return;
+  const src = audio.ctx.createBufferSource();
+  src.buffer = b;
+  src.connect(sfxBus);
+  src.start();
+}
+
+/** Lower the music bed for a moment so a big sound reads, then bring it back. */
+export function duck(seconds = 1.2): void {
+  const g = musicBus.gain, now = audio.ctx.currentTime;
+  g.cancelScheduledValues(now);
+  g.setTargetAtTime(MUSIC_LEVEL * 0.3, now, 0.05);
+  g.setTargetAtTime(MUSIC_LEVEL, now + seconds, 0.3);
+}
+
+/** The master follows store.muted; call after every change to it. */
+export function applyMute(): void {
+  audio.master.gain.setTargetAtTime(store.muted ? 0 : 1, audio.ctx.currentTime, 0.02);
+}
+
+/** Call from every input: unlocks audio once and starts the music bed. */
+export function unlockAudio(): void {
+  void audio.unlock();
+  if (!bed || bedPlaying) return;
+  bedPlaying = true;
+  const src = audio.ctx.createBufferSource();
+  src.buffer = bed;
+  src.loop = true;
+  src.connect(musicBus);
+  src.start();
+  bedStart = audio.ctx.currentTime;
+}
+
+let bedStart: number | null = null;
+/** Seconds into the music bed (looping), from the audio clock; null before it starts. Feed beat.ts this. */
+export function musicTime(): number | null {
+  if (!bed || bedStart === null) return null;
+  return (audio.ctx.currentTime - bedStart) % bed.duration;
+}