@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/src/splash-funpixel/OFL.txt

@@ -0,0 +1,94 @@
+Geist Bold (subset to "funpixel"): Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+Silkscreen Regular (subset to "MADE WITH"): Copyright 2001 The Silkscreen Project Authors (https://github.com/googlefonts/silkscreen)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/common/src/splash-funpixel/card.css

@@ -0,0 +1,18 @@
+/* The "Made with Funpixel" card, in Funpixel's own mark, colours and faces as the brand ships them:
+   the mark is the website's solid gamepad (FunpixelMark), the colours are the apps' tokens (bg
+   #0c0c0d, text #f2f2f2 and #a3a3a3), the name is lower case in Geist Bold and the label is in
+   Silkscreen caps. Both faces are subset to the letters shown and inlined here (OFL: OFL.txt).
+   Chosen by funpixel.json "splash": "funpixel"; with any other choice this folder does not ship. */
+@font-face { font-family: 'fpx-geist'; font-weight: 700; font-display: block; src: url(data:font/woff;base64,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) format('woff'); }
+@font-face { font-family: 'fpx-silkscreen'; font-display: block; src: url(data:font/woff;base64,d09GRgABAAAAAATEAA4AAAAABlwAAQBCAAAAAAAAAAAAAAAAAAAAAAAAAABHREVGAAAEbAAAABYAAAAWABEACUdQT1MAAASEAAAAIAAAACBEdkx1R1NVQgAABKQAAAAgAAAAIER2THVPUy8yAAACvAAAAEYAAABgXDRjVWNtYXAAAAMEAAAASQAAAGQBEQGmZ2FzcAAABGQAAAAIAAAACAAAABBnbHlmAAABRAAAAMkAAAFsKhsY4GhlYWQAAAJEAAAANgAAADb6rdwnaGhlYQAAApwAAAAeAAAAJAezAYJobXR4AAACfAAAAB8AAAAoGl4EZWxvY2EAAAIsAAAAFgAAABYCDwHEbWF4cAAAAhAAAAAZAAAAIAAXAEpuYW1lAAADUAAAAQAAAAIELAFEWnBvc3QAAARQAAAAEwAAACD/nwAyeJxNkD0OgzAMhZ10YChSFVU5AMrQA0So58pEFx+AiZt2gsUSUZ+dtCoCkyjv5wPyxES++EJXuhHlkOccc0hzilgmZsEt4nbmOuK9vCD/eQa44JnUER8Y7Bboj8MXritjR+RU7XZrMG2K2R6cIlkg1avpOolyRJAYR2PwReTcRJqOsKeL6QKzL+fWqd7mv/cEbZpTmJCjaVZkiNxa66obmP8oB/WmGZxBVNs+ndD2zR96A5K15Yk59DVIQStWs9fxNxf8jQ93EGXwAAAAeJxjYGRgYOBiUGFgBWMQDwGYGBgBCK8AYgAAAAAAAAAAGgAxAEUAWQBlAIQAlQC2ALYAAAABAAAAAQBCsoSUkl8PPPUADwPoAAAAALkY+g8AAAAA3seeBf9F/wYEZQPoAAAABgACAAAAAAAAeJxjKmSoZXoHxVA2YzlDLXM2hA+iGb8wMAAA58cK2AB4nGNgZGBgYfvPBiQf/Xf928+SygAUQQFcAH4JBTsAAHicY2BhOsA4gYGVgYGpiymCgYHBG0IzxjEYMfxiQAWMyJxQP28/hgMMCgzhLGz/2RgYmF+A1YPVMH5h2gOkFBiYATHEDD4AAHicY2BgYGJgYGAGYhEgyQimWRgCgLQAEILEFRgcGVwZPBl8GUIYwv//h4q4MHjARP6//H/g/77/e/7v/L/5/0awGSgAANIzFKsAAAB4nHWQO07DQBRFj0kA0aRiAS4ooOCTCAQiFaJEQggCBR0JjhMIMbITJDbAglgEK2BBHE9cQGT09Gbuu3Pfb4B17mkQNTeAT32BIzaNFniFFl8VbnDKd4WbbEWtCq/SizoVXpP/4JyMV97JGZMyYkZMhwOtLerJJN43vk54pmCgMtGmslfijCejQcg7Y+49kstVxmyHejPrF86zr6XWKRVz+uyZlfES2ExL7ZAwFE3VFPJFTded2lmuPVOrTniQa1t7sUGXWy650Lu1ebtLmfV7/tXcGeVhtiy8/u4Wh32H6sqfyNx0HLYp/+ItKE/0Q/3Y3kc86v1/dlqa7Qczq1F7eJxjYGYAg/9zGIwYsAAAKoMB0QAAAQAB//8ADwABAAAADAAAAAAAAAACAAEAAQAIAAEAAAABAAAACgAcAB4AAURGTFQACAAEAAAAAP//AAAAAAAAAAEAAAAKABwAHgABREZMVAAIAAQAAAAA//8AAAAAAAA=) format('woff'); }
+.fpx-made {
+  position: absolute; inset: 0; display: grid; place-content: center; justify-items: center; gap: clamp(10px, 2.6vmin, 20px);
+  padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
+  background: #0c0c0d; color: #f2f2f2;
+}
+.fpx-made-label { margin: 0; font: 400 clamp(12px, 2.6vmin, 18px)/1 'fpx-silkscreen', ui-monospace, monospace; letter-spacing: 0.14em; color: #a3a3a3; }
+.fpx-made-name { display: flex; align-items: center; gap: 0.32em; margin: 0; font: 700 clamp(34px, 9vmin, 72px)/1 'fpx-geist', system-ui, sans-serif; letter-spacing: -0.01em; }
+.fpx-made-name svg { height: 0.82em; width: auto; flex-shrink: 0; }
+.splash:not(.still) .fpx-made-name svg { animation: fpx-made-hop 0.5s 0.15s cubic-bezier(0.3, 1.6, 0.6, 1) both; }
+@keyframes fpx-made-hop { from { transform: translateY(18%) scale(0.86); } }
+@media (prefers-reduced-motion: reduce) { .fpx-made-name svg { animation: none !important; } }

package/templates/common/src/splash-funpixel/card.tsx

@@ -0,0 +1,22 @@
+// "Made with Funpixel": a ready splash card for a game that wants to say where it was made.
+// Optional: funpixel.json "splash": "funpixel" loads it (src/splash.tsx); "own" or "none" leave
+// this folder out of what ships. Draw it as it is: the mark, colours and faces are Funpixel's.
+import './card.css';
+
+/** Funpixel's mark: the solid gamepad on its tight viewBox, as the website draws it. */
+function Mark() {
+  return (
+    <svg viewBox="85 135 340 265" fill="currentColor" aria-hidden="true">
+      <path d="M90 200 Q90 140,150 140 L362 140 Q422 140,422 200 L422 270 Q422 310,390 340 L360 370 Q340 390,310 370 L280 340 Q256 320,232 340 L202 370 Q172 390,152 370 L122 340 Q90 310,90 270 Z" />
+    </svg>
+  );
+}
+
+export function FunpixelCard() {
+  return (
+    <div class="fpx-made" role="img" aria-label="Made with funpixel">
+      <p class="fpx-made-label">MADE WITH</p>
+      <p class="fpx-made-name"><Mark />funpixel</p>
+    </div>
+  );
+}

package/templates/common/src/splash.css

@@ -0,0 +1,15 @@
+/* splash.tsx: the first card at a fresh load (funpixel.json "splash"). Yours: restyle it freely;
+   colours come from the theme in styles.css. */
+.splash { position: fixed; inset: 0; z-index: 10; background: var(--bg); animation: splash-in 0.25s ease-out; transition: opacity 0.25s ease-in; }
+.splash.leaving { opacity: 0; }
+.splash-own {
+  position: absolute; inset: 0; display: grid; place-content: center; justify-items: center; gap: 12px; text-align: center;
+  padding: max(24px, env(safe-area-inset-top)) max(24px, env(safe-area-inset-right)) max(24px, env(safe-area-inset-bottom)) max(24px, env(safe-area-inset-left));
+}
+.splash-own h1 { margin: 0; font-size: clamp(32px, 9vmin, 72px); letter-spacing: 0.02em; }
+.splash-studio { margin: 0; font-size: clamp(13px, 2.6vmin, 18px); font-weight: 600; letter-spacing: 0.18em; text-transform: uppercase; opacity: 0.8; }
+.splash-bar { width: clamp(48px, 14vmin, 120px); height: 4px; border-radius: 2px; background: var(--primary); transform-origin: left; animation: splash-grow 0.6s 0.1s ease-out both; }
+.splash.still, .splash.still * { animation: none; transition: none; }
+@keyframes splash-in { from { opacity: 0; } }
+@keyframes splash-grow { from { transform: scaleX(0); } }
+@media (prefers-reduced-motion: reduce) { .splash, .splash * { animation: none; transition: none; } }

package/templates/common/src/splash.tsx

@@ -0,0 +1,86 @@
+// The first card at a fresh load, before the title: the game's first impression and a studio's
+// signature. One line in funpixel.json picks it, and nothing requires one:
+//   "splash": "own"       the card below; make it yours (your name, your mark). The title is its default.
+//   "splash": "funpixel"  the ready "Made with Funpixel" card in src/splash-funpixel/
+//   "splash": "none"      (or no line) straight to the title
+// It hands over to the title on its own (about 1.2 s), a tap or a key skips it, a reload within
+// AGAIN_MS goes straight to the title, and while it is up the state verify reads says screen: "splash".
+
+import type { ComponentType } from 'preact';
+import { useEffect, useState } from 'preact/hooks';
+import { go, store } from './store';
+import './splash.css';
+
+/** Your studio or your name, shown above the title; empty shows the title alone. */
+const STUDIO = '';
+const HOLD_MS = 1200, LEAVE_MS = 250, AGAIN_MS = 10 * 60_000;
+
+type Card = ComponentType<{ title: string }>;
+const chosen = String(Object.values(import.meta.glob('../funpixel.json', { eager: true, import: 'splash' }))[0] ?? 'none');
+/** Is there a splash at all (session.ts declares the view only then). */
+export const hasSplash = chosen === 'own' || chosen === 'funpixel';
+// Loaded only when chosen, and only when the folder is there: funtools stages and exports
+// src/splash-funpixel/ only when funpixel.json says "funpixel" (delete the folder to drop it).
+const funpixelCard = Object.values(import.meta.glob<{ FunpixelCard: Card }>('./splash-funpixel/card.tsx'))[0];
+
+let held = false;
+
+/** At a fresh load: the splash once per tab, unless the manifest says none. */
+export function startSplash(): void {
+  if (!hasSplash) return;
+  try {
+    if (Date.now() - Number(sessionStorage.getItem('fpx-splash')) < AGAIN_MS) return;
+    sessionStorage.setItem('fpx-splash', String(Date.now()));
+  } catch { /* storage refused: show it */ }
+  go('splash');
+}
+
+/** The splash as a declared view: it holds until another screen is entered (capture, audits). */
+export function enterSplash(): void {
+  held = true;
+  go('splash');
+}
+
+function OwnCard({ title }: { title: string }) {
+  return (
+    <div class="splash-own">
+      {STUDIO && <p class="splash-studio">{STUDIO}</p>}
+      <h1>{title}</h1>
+      <span class="splash-bar" />
+    </div>
+  );
+}
+
+export function Splash({ title }: { title: string }) {
+  const [card, setCard] = useState<{ C: Card } | null>(null);
+  const [leaving, setLeaving] = useState(false);
+  useEffect(() => {
+    let alive = true;
+    const timers: ReturnType<typeof setTimeout>[] = [];
+    const leave = () => { if (store.screen === 'splash' && !held) go('title'); };
+    // Captured first, so the skipping tap or key never also reaches the game or the title under it.
+    const skip = (e: Event) => { if (store.screen === 'splash') { e.stopPropagation(); held = false; leave(); } };
+    addEventListener('keydown', skip, true);
+    addEventListener('click', skip, true);
+    const load: Promise<Card> = chosen === 'funpixel' && funpixelCard
+      ? funpixelCard().then((m) => m.FunpixelCard, () => OwnCard)
+      : Promise.resolve(OwnCard);
+    void load.then((C) => {
+      if (!alive) return;
+      setCard({ C });
+      timers.push(setTimeout(() => setLeaving(true), HOLD_MS - LEAVE_MS), setTimeout(leave, HOLD_MS));
+    });
+    return () => {
+      alive = false;
+      held = false;
+      timers.forEach(clearTimeout);
+      removeEventListener('keydown', skip, true);
+      removeEventListener('click', skip, true);
+    };
+  }, []);
+  return (
+    <div class={`splash${leaving && !held ? ' leaving' : ''}${store.motion ? '' : ' still'}`}>
+      {card && <card.C title={title} />}
+    </div>
+  );
+}

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';