evolutionary-arcade 0.0.1 → 0.1.1

package/package.json

@@ -1,12 +1,43 @@
 {
   "name": "evolutionary-arcade",
-  "version": "0.0.1",
-  "description": "Evolutionary Arcade creator CLI. Coming soon.",
+  "version": "0.1.1",
+  "description": "The arcade CLI for Evolutionary Arcade. Publish, update, regen, fork, and blend AI-made browser games with your own coding agent.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Evolutionary Arcade <hello@evolutionaryarcade.com> (https://evolutionaryarcade.com)",
+  "bin": {
+    "arcade": "dist/cli.js"
+  },
   "files": [
-    "README.md"
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/DamDam98/evolutionary-arcade.git"
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://evolutionaryarcade.com",
+  "keywords": [
+    "games",
+    "arcade",
+    "ai",
+    "agents",
+    "cli",
+    "threejs"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "15.0.0"
+  },
+  "devDependencies": {
+    "@ea/format": "0.0.0",
+    "@types/node": "26.6.3",
+    "tsup": "8.5.1"
   }
 }

package/skills/arcade-building-games/SKILL.md

@@ -0,0 +1,602 @@
+---
+name: arcade-building-games
+description: Use when building or improving a browser game for Evolutionary Arcade (evolutionaryarcade.com). That covers starting one with `arcade new`, making a fork, blend, or regen playable, tuning feel, designing progression that keeps players coming back for weeks, adding gamepad, touch, or phone tilt support, saving progress to the player's profile, posting scores to global leaderboards, and checking that the game runs in the arcade's sandboxed iframe and CSP before `arcade publish`. It separates what the arcade enforces (publish fails or the game breaks) from house rules, says what makes a game feel great, and shows how to verify it by actually playing it.
+---
+
+# Building arcade games
+
+## The situation
+
+Your game runs in an iframe on evolutionaryarcade.com. It's served from
+`https://<slug>.evolutionaryarcade.games/_g/<generationId>/...` in this frame:
+
+```html
+<iframe sandbox="allow-scripts allow-same-origin allow-pointer-lock allow-orientation-lock"
+        allow="fullscreen; gamepad; autoplay; accelerometer; gyroscope; magnetometer" allowfullscreen>
+```
+
+The games host sends a CSP that allows inline scripts, `eval`, WebAssembly, and workers. It blocks
+every outside connection (`connect-src 'self'`) and all forms. Inside the frame, `alert`,
+`confirm`, and `prompt` do nothing. Popups, `target="_blank"` links, downloads, and top-level
+navigation all fail. `screen.orientation.lock()` works only in fullscreen on Android. The camera,
+microphone, and geolocation are off; the motion sensors are on for tilt games (Phone tilt, below). The page isn't cross-origin isolated, so there's no `SharedArrayBuffer`, which rules out
+threaded WASM builds. Draw your dialogs inside the game.
+
+The player is a 16:9 box across the game page, with the arcade's own fullscreen and restart
+buttons. Restart reloads the frame, so a fresh load must always come up clean. A player comes in
+from a card that showed a thumbnail and a hover preview, clicks, and decides within seconds whether
+to stay. Everything you ship is public, and other people's agents will read your source and fork
+it. A game that breaks under these conditions can't publish or fails in front of players, and the
+seed games Starwake (a space dogfighter) and Last Signal (an FPS) hit every trap below.
+
+Start with `arcade new <slug> [dir]`. It writes a starter `arcade.json`, an `index.html` that loads
+`./main.js`, and `media/`. For setup and login, see `arcade-getting-started`. For building on
+someone else's game, see `arcade-remix-and-blend`.
+
+## What good looks like
+
+- Within ten seconds of clicking, a player thinks "wait, an AI made this?"
+- One core action feels great before you add more content.
+- It works in the frame at any size on the first try, with no console errors and zero outside requests.
+- The source is organized well enough that someone else's agent can fork it and change it.
+
+## Enforced: publish fails or the game breaks
+
+1. **Static folder with an entry page.** Players get `play.root` (default `.`) and its
+   `play.entry` (default `index.html`). Publish fails if that file isn't in the upload. If you use
+   a bundler, ship the built output and point `play.root` at it (for Vite,
+   `"play": {"root": "dist"}`). The rest of the folder is published as readable source.
+2. **Relative URLs, exact case.** The game is served under `/_g/<generationId>/`, so an absolute
+   `/assets/x.js` path returns 404. For Vite, set `base: "./"`. Live file lookup is case-sensitive,
+   so `Ship.png` won't load a file named `ship.png`. `arcade dev` serves at `/` from your disk,
+   which is case-insensitive on macOS, so you won't see either mistake locally. Check the build
+   instead. This should print nothing:
+   `grep -rnE "(src|href)=[\"']/|url\([\"']?/|(from|import\() *[\"']/|fetch\([\"']/" dist/`
+3. **No network at runtime.** CDNs, Google Fonts, analytics, APIs, WebSockets, remote leaderboards,
+   and multiplayer servers are all blocked (the arcade's own leaderboards and saves go through the
+   page; see below). Vendor every dependency into the folder, or bundle it.
+   Use relative imports or a bundler, not an import map that points at a CDN. Fetching your own
+   files by relative URL is fine. `arcade dev` lets `ws:` through but the arcade doesn't, so don't
+   trust dev for sockets. Don't add tracking code; the arcade measures play from outside the frame.
+4. **Start on a click or keypress.** Show a title screen with "Click to play". Create or resume the
+   `AudioContext` inside that handler. Request pointer lock and fullscreen only from a gesture. Esc
+   and gamepad buttons don't count as gestures, so a controller-only player can't turn on sound.
+   Show "click or press any key once."
+5. **Pointer lock comes from the sandbox token.** The arcade grants `allow-pointer-lock`, and Chrome
+   ignores `allow="pointer-lock"`. Expect lock to be refused. Automated browsers usually refuse it,
+   and Chrome refuses a re-lock for about a second after the player presses Esc. In Chrome,
+   `requestPointerLock()` returns a promise that rejects when lock is refused. Catch it, or it
+   shows up as a page error. Handle `pointerlockerror` and `pointerlockchange`: pause when the lock
+   is lost, and keep a fallback that steers with the absolute mouse position.
+6. **Handle any frame size.** The frame can be under 200 px tall (a phone in portrait) or the whole
+   screen. On `resize`, update the renderer size and the camera aspect. Cap `devicePixelRatio` at
+   about 2. Lay out the HUD relative to the viewport, not in fixed pixels.
+7. **Sizes and file types.** Keep the upload under 50 MB (aim for under 20), each file under 25 MB,
+   and at most 800 files. Source and built copies both count, so a 10 MB file in Vite's `public/`
+   costs 20 MB once it's copied into `dist/`. Media counts too (`arcade-publishing` has its limits).
+   Allowed: html, htm, js, mjs, cjs, css, json, map, wasm, glb, gltf, bin, ktx2, png, jpg, jpeg,
+   webp, gif, avif, svg, ico, mp3, ogg, wav, m4a, mp4, webm, woff, woff2, ttf, otf. Served as plain
+   text: txt, md, glsl, wgsl, vert, frag, yml, yaml, toml, csv, xml, sh, py, ts, tsx, jsx. Also
+   LICENSE, LICENCE, NOTICE, COPYING, AUTHORS, README, and CHANGELOG (no extension, any case), and
+   config dotfiles like `.gitignore`. **ts, tsx, and jsx never run**: they're served as `text/plain`
+   with `nosniff`, so ship compiled `.js`. Any other file (`yarn.lock`, `.zip`, `.fbx`, `.blend`,
+   `.psd`, `.envrc`) makes `arcade publish` exit 2 and list it; move it out or convert it (`.fbx`
+   and `.blend` become `.glb`). The CLI ignores `.gitignore`: everything uploads except `.git`,
+   `node_modules`, a few tool and editor folders, and secret files (`arcade-publishing` lists them).
+
+## House rules: arcade policy, not validators
+
+8. **Aim for 60 fps on a laptop.** Drive updates with clamped delta time, so a 120 Hz display
+   doesn't double the speed and a stall doesn't teleport anything. Clamp cooldown timers at zero.
+   Pause on `visibilitychange`.
+9. **Make your own assets.** Build geometry from primitives, merged geometry, and shaders. Generate
+   textures on a canvas. Synthesize sound with Web Audio (oscillators, noise buffers, envelopes, a
+   small step sequencer), through a master gain and compressor so loud moments don't clip. Don't
+   download third-party models, sprites, sound packs, or fonts. Nothing checks this. It's the rule
+   the seed games set, and it keeps licensing clean for everyone who forks you. Your game is MIT,
+   like every game here. Anything you do bundle from others, like a vendored Three.js, keeps its
+   own license: ship its LICENSE beside it (`vendor/three/LICENSE`), and only bundle what's yours
+   to share.
+10. **Storage is optional, and shared.** `localStorage` works (a saved high score is nice), but wrap
+    every access in try/catch. Every version and generation of a game shares one origin, including
+    other people's regens. Prefix keys with your slug, version your save format, and handle old or
+    malformed data. To keep progress across devices, use profile saves (below).
+
+## Judgment: what makes a game feel great
+
+- **The first ten seconds decide it.** Make the title screen beautiful: a live scene behind the
+  logo, not a flat card. After the click, get into the action fast, with no wall of text. Teach the
+  controls through the first minute of play.
+- **Feel comes before breadth.** Find the action the player repeats most and make it feel great
+  before you add content: instant response, clear feedback on every input, a payoff when it lands.
+  From the shooter and flight seeds: a crisp fire rate, recoil that recovers, tracers that line up
+  with the crosshair, hit markers with a sound, enemies that react, responsive banking, a boost
+  with an FOV kick, and bounded screen shake. Other genres have their own version: a puzzle piece
+  that snaps in with a sound, a car's grip and drift, a unit that answers a click at once. In
+  tower defense and strategy games the repeated action is "place it, then watch it pay off": show
+  the range before you build, confirm the build instantly, and make kills readable in a crowd.
+- **Keep it readable.** Starwake's first look had bloom blowing out the ship, a clipped title
+  ("STARWAK"), and enemy bolts that looked like giant beams near the camera. Effects should never
+  hide the action.
+- **Make the HUD readable.** Show what the player needs to decide, like health, ammo, the objective,
+  and the score. Keep it out of the center of the action, and check it in a small frame.
+- **Add pause and restart.** P or Esc pauses. The game-over screen shows stats, and restarting takes
+  one key.
+- **Balance for humans.** Bots don't play the way people do. Keep the opening forgiving, and don't
+  starve the player. Last Signal added an ammo cache because running out of ammo made it unfun.
+  When only a bot has played it, soak several seeds and report the spread, not your best run
+  (Gatecrashers first claimed its best case). A handicapped bot is a rough stand-in for a
+  first-time player.
+- **Keep crowds and effects cheap.** Instance repeated meshes (Gatecrashers ran 150+ ragdoll
+  goblins at 60 fps that way). Prefer glow sprites to many dynamic lights, because adding lights
+  recompiles shaders and stalls. Fold post-processing into as few passes as you can, and lower the
+  render resolution on slow frames instead of dropping frames.
+- **Write source someone can fork.** Split modules by system (player, enemies, audio, HUD), and keep
+  the tuning constants in one place.
+
+## Long-term fun
+
+The first bar is "wait, an AI made this?" within ten seconds. The harder bar, and the better
+showcase of what a model can build, is a player still coming back in week three. Ridiculous
+Fishing and Ski Safari hold people for weeks because skill, gear, and the world's demands grow
+together. Design that growth, prove its pacing with a script, and save it.
+
+**Pick the shape first. Not every game wants a shop.** A **loop plus economy** pays out every run
+and sells reach: Ridiculous Fishing's longer line opens deeper water. **Levels plus mastery** rate
+how well you play fixed levels, like Angry Birds' three stars or Jet Car Stunts' medals for time
+and respawns. **Skill modes plus unlocks** tie rewards to feats: Fruit Ninja's early blades
+unlocked for things like slicing 50 bananas. A **finished journey** like Monument Valley runs
+about 90 minutes with no stars and no grind, and its makers say "length does not equal value."
+Don't bolt an economy onto that.
+
+**Write a progression spec before you code.** Put it in `PROGRESSION.md` in the game folder,
+where forks will find it. It covers:
+- the run length and the session length (say, 60 to 90 s runs in a 5 to 10 minute sitting)
+- target sessions: the first upgrade inside session 1, the credits in about 25 to 40 sessions,
+  and 100% in 60 or more. At one sitting a day, that's weeks to finish and months to master.
+- the unlock schedule, as a table of session numbers that the economy sim below has to match
+- four lists: what gets **harder** (the world: deeper water, steeper slopes, new hazards), what
+  gets **stronger** (the player: line length, gear, a second chance), what gets **wider** (an
+  animal to ride, a blade, a hat, a mode), and what **never changes** (the controls and the skill
+  they reward)
+- where the currency comes from, what it's spent on, and the price curve
+
+**Upgrades open doors; skill decides what happens inside.** An upgrade adds reach (deeper,
+farther, a new area), options (a new animal or tool), or a little early forgiveness. It never does
+the part the player is there to master. In Ridiculous Fishing the line decides how deep you can
+go, but dodging fish on the way down and shooting on the way up decide the haul. Put rising
+difficulty in the new places upgrades open, and leave old levels alone so an old best still means
+something. If a player can grind past a skill check, the check is gone: Angry Birds 2's boosters
+made stars easier to get, which turned mastery into a purchase. Keep failure cheap, too. Halfbrick
+counts lost time, the sting, and restart friction as its costs, so keep runs short and restarts
+instant, and let every run pay toward the next goal.
+
+**Missions give each run a reason beyond the high score.** Jetpack Joyride took the idea from Tiny
+Wings, and Ski Safari uses it too: three goals at once, and clearing all three ranks you up.
+- Make most missions about a skill or a corner of the game ("backflip off a yeti," "reach 300 m
+  without touching a jellyfish"), not tallies like "play 20 runs."
+- Make finishing one loud: Halfbrick's stars slam in with sparks, and the rank became a draw of
+  its own.
+- Halfbrick tested daily, optional, and progressive missions and shipped progressive, so players
+  wouldn't get stuck or burn out. Let players swap out a mission they've been stuck on for a few
+  sessions.
+
+**Collections turn the world into a checklist.** Ridiculous Fishing's Fish-o-pedia lists every
+species by area, with catch counts, values, and hints for the ones you're missing, and catching
+fish unlocks the next area. Show a silhouette and a hint for each missing entry, so the collection
+says where to go next. Rares should take skill or the right gear, not only luck.
+
+**Mastery ratings make replays worth it.** Rate each level with one to three stars or a medal,
+from what the player did (score, time, respawns), and show the target for the next one. Gate bonus
+content on star totals, as Angry Birds did at 30, 60, and 90 stars per episode, so players choose
+which levels to perfect. Keep personal bests, and a ghost to race where it fits (Jet Car Stunts'
+time trials have one). Neither needs a network, and nothing a player buys earns a star.
+
+**Give a reason to come back tomorrow, never a penalty for staying away.** Offer a daily run
+seeded from the local date, like Spelunky's daily: the same run for everyone that day, with one
+scored attempt, so players compare in the comments and on Discord. Name the next goal on the
+game-over screen ("240 coins to the next line"). No streaks that reset, no energy or lives, no
+timers, and nothing lost for missing a day.
+
+**Prove the pacing with an economy sim.** No builder can play for a month, so a script does, in
+the spirit of Keepfall's solver. `tools/economy-sim.mjs` imports the real prices, payouts, and
+unlock rules from the browser-free sim (never a copy), plays simulated players through many
+sessions, and prints sessions to each unlock next to the spec's schedule. Worked examples has a
+sketch.
+- **Skill model:** three players (slow, typical, expert) whose skill rises with practice and
+  levels off at different heights. Best is the game's own sim driven by the autopilot at matching
+  handicaps. Cheaper is a run model that turns skill into outcomes (depth, catches, hits) and
+  prices them with the game's payout code. Run several seeds and report the spread, not the best
+  run.
+- **Pass bar** (the spec can change a number, and says why):
+  - The slow player buys a first upgrade inside session 1.
+  - No dead zones: the typical player gets something new (an upgrade, unlock, collection entry,
+    or rank) at least every 2 sessions, and the slow player at least every 4.
+  - The typical player reaches the credits within 25% of the target.
+  - Money never sits for more than 2 sessions with nothing worth buying, until the endgame.
+  - Mastery still decides: fully upgraded, the expert earns at least twice what the slow player
+    does per run, and the slow player can't get top ratings on the hardest levels.
+- The sim checks the math, not the fun. After a few days of real play, ask what felt like a chore.
+
+**Avoid what a free game doesn't need.** These games have no store and no ads, so monetization
+patterns only make them worse.
+- **Grind walls:** prices that grow exponentially against flat earnings outrun every player in
+  the end. Earnings have to grow with the places upgrades open. The sim finds the walls.
+- **Pay-to-win pacing with no pay:** a wall, then a shortcut (boosters, continues, doubled
+  coins). With no store, it's just a wall. So are energy, lives, timers, and dailies you must log
+  in for.
+- **Fake scarcity:** limited-time offers, rotating shops, countdowns. Everything stays earnable.
+- **Random boxes as the path to progress, and extra currencies.** Every currency needs something
+  worth buying, or it piles up and the loop that earns it goes dead.
+
+**Save the long game, and keep it small.** Use profile saves (below) so the progress follows the
+player. Save the currency, owned upgrades and unlocks, the collection (a count and a best per
+species), mission slots and rank, the best rating or time per level, the last daily date and its
+best, settings, and tutorial flags. Save ids and numbers, not copies of config, so a price change
+can't break a save. Skip what you can recompute, and keep ghost replays out.
+
+**Let the depth evolve.** The arcade keeps every version and every model's regen side by side, so
+a game's history is a record of what each model could build.
+- Updates carry progress forward and never reset it: migrate old saves (Profile saves has how),
+  and keep owned things owned when you rebalance. Months of progress should survive the game
+  changing under them.
+- Publish `PROGRESSION.md` and the sim in the folder, as Keepfall publishes
+  `tools/solve-route.mjs`. A fork that retunes the economy reruns the sim instead of guessing.
+- A regen gets only the prompt. Put the progression targets and the pass bar in the kickoff prompt
+  you share, and the sim's summary in `provenance.notes`. Then the same-prompt comparison on the
+  Models page shows which model built the better month, not only the better first ten seconds.
+  Describe the save format and its key there too, and a regen can carry players' progress over
+  with `from`.
+
+## Input
+
+- **Keyboard and mouse** is the default (`input.keyboard_mouse: true`). Describe the bindings in
+  `controls`.
+- **Gamepad:** poll `navigator.getGamepads()` every frame and use the `"standard"` mapping, which
+  covers both Xbox and PlayStation. Add stick deadzones and a curved aim response. Start pauses, and
+  A starts or restarts. Set `input.gamepad: true` only when the whole game, menus included, works on
+  a controller. The arcade shows a controller badge and a filter.
+- **Touch:** without `input.touch: true`, phones get your demo video instead of the game. Set it
+  only if the game has real touch controls, like an on-screen stick and buttons with large targets
+  (48 px or more). Use pointer events, put `touch-action: none` on the canvas, and don't rely on
+  hover. Test at phone width, where the 16:9 frame is tiny until the player goes fullscreen. To
+  try it on a real phone, run `arcade dev --host` and open the network address it prints on a
+  phone on the same Wi-Fi.
+- **Tilt:** see Phone tilt, next.
+
+## Phone tilt
+
+Set `"input": { "touch": true, "tilt": true }` when tilting the phone steers the game. The game page
+shows a Tilt badge. Tilt needs `touch` (publish fails without it), because phones only get games
+that have touch on, and every tilt game needs touch controls anyway.
+
+- **Ask on a tap.** iPhones send no motion events until the player allows them, and Safari only
+  asks from a tap. Call `requestPermission()` first thing in your "Tap to play" handler, before
+  any `await`. Android and desktop browsers don't ask.
+- **Ship a touch fallback.** Players say no, iOS may not ask again, and computers have no sensors
+  (desktop Chrome sends one event with null angles). If permission isn't granted, or no event
+  with real numbers arrives within about a second, steer by touch, and let players switch in
+  settings.
+- **Calibrate neutral on start.** Nobody holds a phone flat. Take the angle when play starts as
+  zero, steer by the difference with a small deadzone, clamp around 25 degrees, and smooth it a
+  little. Put "Recenter" in the pause menu.
+- **Turn the axes with the screen.** `gamma` is left-right only in portrait. In landscape it's
+  `beta`, and the sign flips with the side the phone is turned to (`screen.orientation.angle`).
+- **Landscape lock only works in fullscreen on Android.** The arcade's Fullscreen button already
+  locks landscape there. A game that goes fullscreen from its own tap can lock too (a portrait
+  game can lock `"portrait"`). iPhones never lock and have no fullscreen for games, so show
+  "Turn your phone sideways" while a landscape game is held upright.
+
+```js
+const LANDSCAPE = true;                                // a landscape-first game
+let tiltOk = false, zero = null, tilt = 0;             // tilt: -1..1; steer by touch until tiltOk
+async function onStartTap() {                          // the "Tap to play" handler
+  const DOE = globalThis.DeviceOrientationEvent;
+  const asking = typeof DOE?.requestPermission === "function"
+    ? DOE.requestPermission().catch(() => "denied")    // iPhone: asks, so call it before any await
+    : Promise.resolve(DOE ? "granted" : "denied");
+  if (LANDSCAPE) document.documentElement.requestFullscreen?.()
+    .then(() => screen.orientation.lock("landscape")).catch(() => {}); // Android only
+  tiltOk = (await asking) === "granted";
+  zero = null;                                         // "Recenter" does this too
+  startOrResume();
+}
+const across = (e) => {                                // left-right degrees, however it's turned
+  const a = ((screen.orientation?.angle ?? globalThis.orientation ?? 0) + 360) % 360;
+  return a === 90 ? e.beta : a === 270 ? -e.beta : a === 180 ? -e.gamma : e.gamma;
+};
+addEventListener("deviceorientation", (e) => {
+  if (!tiltOk || e.beta == null) return;               // no sensor: keep touch steering
+  const x = across(e);
+  zero ??= x;                                          // neutral is how they hold it at the start
+  const d = x - zero;
+  tilt = Math.abs(d) < 2 ? 0 : Math.max(-1, Math.min(1, d / 25));
+});
+```
+
+Testing tilt:
+- Motion events only fire on HTTPS or localhost. In a desktop browser on `arcade dev`, set angles
+  in Chrome DevTools (More tools, Sensors). A phone on `arcade dev --host` gets plain http and no
+  events: on Android, add the address under `chrome://flags` "Insecure origins treated as
+  secure"; on an iPhone, use an HTTPS tunnel to the dev server.
+- In Playwright, drive it with synthetic events in the game's frame:
+  `dispatchEvent(new DeviceOrientationEvent("deviceorientation", { beta: 10, gamma: 15 }))`.
+  Test the calibration, the clamp, and the touch fallback when no events arrive (the default in
+  an automated browser).
+- After publishing, play it on a real iPhone in Safari and on an Android phone: the prompt shows
+  once on the tap, steering is centered where you hold it, and saying no leaves touch working.
+
+## Mute button
+
+The arcade's player bar shows a Mute button for games that listen for it, and the player's choice
+carries over to the next game that does. Your frame is on another site, so the bar can't silence
+it; the game does. Say you listen once at startup (protocol `mute/1`), then follow what the bar
+sends, before and after the first click:
+
+```js
+// Call once at startup. setMuted(true | false) runs now (with the player's choice) and on every press.
+function listenForArcadeMute(setMuted) {
+  if (window.parent === window) return; // not in a frame: nothing to listen to
+  addEventListener("message", (e) => {
+    const m = e.data;
+    if (e.source === window.parent && m?.arcade === "mute/1" && typeof m.muted === "boolean")
+      setMuted(m.muted);
+  });
+  window.parent.postMessage({ arcade: "mute/1", op: "ready" }, "*");
+}
+listenForArcadeMute((muted) => { master.gain.value = muted ? 0 : 1; }); // your master GainNode
+```
+
+Route every sound through one master `GainNode` and mute that. Don't `suspend()` the
+`AudioContext`: sounds scheduled while it's suspended all play at once when it resumes. Mute
+`<audio>` and `<video>` elements with their `muted` property. Keep your own mute key too: it's the
+only one players have outside the arcade.
+
+## Profile saves
+
+A game can save progress to the player's arcade profile, so it follows them to any device. Games
+with `"profile_saves": true` in arcade.json get a "Saves progress" badge and a Browse filter.
+
+Your frame can't reach the arcade (rule 3), so the arcade page around it does the saving. Copy
+`arcade-saves.js` from this skill's folder into your game and use it:
+
+```js
+import { createSaves } from "./arcade-saves.js";
+const saves = createSaves({ key: "my-game:save:v1" }); // one key per save format
+let state = sanitize(await saves.load()); // once at startup, before any save; null the first time
+saves.save(state);                         // later, at a meaningful moment
+```
+
+- **Signed in, the profile is the truth.** `load()` returns the profile's save, and `save()`
+  sends it there through the arcade page: at most one write every 10 seconds (the latest), and
+  one more when the page is hidden or closed. Every save also lands in `localStorage`.
+- **Signed out, the device copy is all there is.** The same goes for `arcade dev` and the frame
+  harness, where `load()` stops waiting for an arcade page after 1.5 s (on the arcade itself it
+  waits up to 8 s). Progress made signed out moves up once, into a profile that has nothing saved
+  for this game yet. It never replaces a profile's save, and on a shared computer one signed-in
+  player's progress never moves into another's profile.
+- `saves.signedIn` is true after `load()` when saves reach the profile. It's there for an
+  optional "Sign in to keep your progress" line on your title screen.
+- **One slot per player per game, with one entry per key.** Your versions share the slot, and so
+  does a regen you make or pick as main. A regen someone else made plays from the device until
+  you pick it as main. Forks get their own slot. Since each key keeps its own entry, a player can open an
+  old version or another model's regen from the game's history and still find their progress in
+  the main one.
+- Under the hood it's a small postMessage protocol (`saves/1`) that the arcade answers only for
+  your game's own frame, and only for your game's slot. Use the helper instead of speaking it.
+
+**A new save format, or a game that already saves to `localStorage`:** give the helper a new key
+and list the old one in `from`. When the new key has nothing yet, `load()` hands you the save
+under the first `from` key that has one, from the profile or this device, including a plain
+`localStorage` save your old code wrote. `saves.loadedFrom` names the key it came from, so you
+know which migration to run. Your first `save()` writes the new key. Never write an old key in
+the new format: older versions still read it. Golden Hour Pier's existing players would keep
+their catch like this:
+
+```js
+const saves = createSaves({ key: "golden-hour-pier:save:v1", from: ["golden-hour-pier:v1"] });
+let state = sanitize(await saves.load()); // the same shape, so the same sanitize
+```
+
+The rules:
+
+1. **Set `profile_saves` only if the game really uses the helper.** It's your claim, like
+   `input.gamepad`. The arcade gives no slot to a build without it.
+2. **Save at meaningful moments:** the end of a run, a purchase, an unlock, a settings change.
+   Never every frame.
+3. **Keep saves small:** well under 64 KB for the whole slot (every key's entry counts), with no
+   images, blobs, or logs. A player has 512 KB across every game. A save past either cap stays
+   on the device.
+4. **Version the save and never trust it.** Include `v`. Sanitize every field on load: clamp
+   numbers, drop ids you don't know, and fall back to defaults, as Golden Hour Pier's
+   `src/save.js` does. Migrate anything old instead of resetting it. When the shape changes,
+   change the key (above). If `load()` ever hands you a save newer than your code understands, play from
+   defaults and don't `save()` over it that session.
+5. **Work signed out.** Never block play on signing in.
+6. **Nothing secret or personal goes in a save:** no names, emails, or tokens.
+
+Under `arcade dev`, check that a reload restores progress from the device copy, and that a
+corrupted save (edit it in devtools) resets cleanly. The profile path only runs on the arcade, so
+after publishing, play signed in, reload, and check that your progress came back.
+
+## Leaderboards
+
+A game can post scores to global leaderboards. The game page shows each board's top 10 under
+the game, and where the player stands. List up to 4 boards under `"leaderboards"` in arcade.json:
+
+```json
+"leaderboards": [
+  { "id": "best-run", "label": "Best run", "max": 5000000 },
+  { "id": "world-1", "label": "World 1 time", "order": "asc", "format": "time_ms",
+    "min": 95000, "max": 3600000 }
+]
+```
+
+- `id`: lowercase letters, digits, and hyphens, up to 32. It's permanent: if the scoring rules
+  change, use a new id.
+- `label` (up to 40 characters) is what the game page shows.
+- `order`: `"desc"` (higher is better, the default) or `"asc"` (lower is better, for times).
+- `format`: `"points"` (the default) shows 1,240, `"time_ms"` shows 1:02.345, and `"distance_m"`
+  shows 1,240 m.
+- `max` is required and `min` defaults to 0. The arcade refuses any whole number outside them, so
+  they're the board's only plausibility check. Set `max` near what a great player could reach (2 to
+  3 times your simulation's best), not "infinity". On an `asc` board, `min` is the cap that
+  matters: the fastest a perfect run could be.
+
+Boards are per game, not per level. A 60-level puzzle game posts a total (stars, or a world's
+total time), not 60 boards. Copy `arcade-scores.js` from this skill's folder into your game:
+
+```js
+import { createScores, formatScore } from "./arcade-scores.js";
+const scores = createScores({ boards: LEADERBOARDS });   // the same array as arcade.json
+scores.submit("best-run", runScore).then(showResult);    // once per finished run
+scores.best("best-run").then(({ best, rank }) => ...);   // for the title screen
+```
+
+- `submit` resolves `{ accepted, signedIn, best, rank, newBest, reason }`. Accepted, `best` and
+  `rank` are the player's leaderboard best and its rank (ties share one). Otherwise `best` is this
+  device's best, and `reason` says why: `signed_out`, `offline` (not on the arcade, or no answer
+  in 10 s), `not_enabled`, `unknown_board`, `invalid`, `rate_limited`, or `error`.
+- Signed-out scores stay on the device and never move up later, since on a shared computer they
+  could be someone else's.
+
+The rules:
+
+1. **Post once per finished run, never per frame, and never block the restart on it.** The arcade
+   takes one submit per player per board every 2 seconds.
+2. **Show the run's value at once.** When `submit` resolves, add one line: `New best! #12`,
+   `Best 1,240 · #37`, `Sign in on the arcade to post your score` (for `signed_out`), or
+   `Best on this device: 1,240` (anything else). Never show error text. On the title screen,
+   `Your best 1,240 · #37` from `best()`.
+3. **No in-game global top 10.** The game page already shows it.
+4. **Only builds the owner stands behind post.** Like profile saves: your own builds, or a regen
+   you pick as main. `arcade regen` leaves `leaderboards` out, because the scoring code doesn't come
+   along. Forks are new games with boards of their own.
+
+Off the arcade (`arcade dev`, the frame harness), `submit` answers `offline` and keeps a device
+best, so build and test against that. After publishing, finish a run signed in and check that the
+game page's leaderboard shows it.
+
+## Verify by actually playing
+
+- Build, then run `arcade dev` in the game folder. It serves `play.root` at
+  `http://localhost:5173/` (this computer only) with the arcade's CSP, so outside calls fail right
+  away. If Vite already has port 5173, pass `--port 5174`. Play it end to
+  end: title, play, lose, restart. Dev isn't the frame (see rules 2 and 3). It has no sandbox and
+  no `frame-ancestors`, so anything that breaks only in the frame shows up only in the harness.
+- Drive it with Playwright. Click the title, hold keys, move the mouse, fire. Collect console
+  errors and page errors, and record every request.
+- Add a small debug hook, like `window.__game` with state, fps, the player, and a spawn function,
+  so scripts can set up exact situations. A **bot hit test** freezes a target at several ranges and
+  fires N shots, and every shot should hit. In Last Signal it caught a real bug: the cooldown went
+  negative while idle, so every tap fired two shots.
+- Add an **autopilot** (`?autopilot`) that plays the game by itself. It gives you repeatable soak
+  runs and demo footage. If your media is bot-driven, say so in `provenance.notes`.
+- **Keep seeded runs repeatable.** If you seed gameplay randomness (`?seed=N`), give particles,
+  sparks, blinks and audio their own generator, or cosmetic effects will drift the game within a
+  second. Prove it: run the same seed twice and compare the game state.
+- **Stage only states a player can reach.** A debug hook makes it easy to screenshot something no
+  player could ever see, like a build menu over an occupied pad. Set up shots through the real
+  input path.
+- **Capture in game time.** When you record frame by frame, banners and CSS animations driven by
+  `setTimeout` or wall-clock time come and go depending on capture speed. Drive them from the game
+  clock.
+- **Test with the sound off.** You are usually testing on someone's computer. Launch browsers with
+  `--mute-audio` and check audio by analysis instead: the AudioContext state, plus analyser RMS and
+  peak levels. The flag is Chromium-only, so in WebKit or Firefox don't make the first gesture that
+  starts audio.
+- **Let a script prove the level.** Keep the simulation free of browser APIs so Node can run it.
+  Keepfall's solver ran the game's own physics to prove the climb beatable, even with the hero's
+  jump cut by 12%. That is stronger evidence than any number of soak runs.
+- **Check your arcade.json before publishing.** `arcade publish --dry-run` validates it against
+  the server. Offline, import `parseArcadeJson` from `@ea/format` and pass it the parsed object,
+  not the file's text.
+- **2D canvas games** have their own traps: cap the backing store on hi-DPI screens, overlap tiles
+  by a pixel to hide seams, cache sprites per zoom level, and draw a facade over any secret room
+  that a side view would reveal. Test that one wall can't be climbed forever with wall jumps.
+- **Frame harness.** Open the harness page below as a local file, so the game is cross-origin the
+  way it is on the arcade, and drive it through `page.frameLocator("iframe")`. Check that it
+  starts, that the AudioContext state is `running`, that lock or its fallback works, and that pause
+  works. Check that it looks right at about 640x360 and at full screen.
+- Look at what you made. Open the screenshots and watch the recording, or a contact sheet of it.
+  Whiteouts and clipped text only showed up in footage.
+- Say what automation can't prove. Automated browsers usually refuse pointer lock (they test the
+  fallback), they can't hear the mix, and they don't play like people. Ask the human to play for
+  two minutes and tell you what felt worst.
+
+Capture media from real gameplay. The rules for media and publishing are in `arcade-publishing`.
+
+## Worked examples
+
+A Vite and three.js game. Install three from npm so it gets bundled, not loaded from a CDN:
+
+```js
+// vite.config.js
+export default { base: "./", build: { outDir: "dist" } };
+// arcade.json: "play": { "root": "dist" }, and run `arcade dev` after `npm run build`
+```
+
+Start or resume on a click or key, and survive a refused lock:
+
+```js
+let audio;
+function onGesture() {                         // title and pause screens both call this
+  audio ??= new AudioContext();
+  audio.resume();
+  canvas.requestPointerLock?.()?.catch?.(useAbsoluteMouse); // Chrome's promise rejects on refusal
+  startOrResume();
+}
+overlay.addEventListener("click", onGesture);
+addEventListener("keydown", (e) => { if (!playing && e.key !== "Escape") onGesture(); });
+document.addEventListener("pointerlockerror", useAbsoluteMouse);
+document.addEventListener("pointerlockchange", () => {
+  if (!document.pointerLockElement && playing) pause();
+});
+```
+
+A frame harness. Keep it outside the game folder (say, `../harness/frame.html`), because everything
+in the folder is published:
+
+```html
+<div style="width:640px;aspect-ratio:16/9;resize:both;overflow:hidden">
+  <iframe src="http://localhost:5173/" style="width:100%;height:100%;border:0"
+    sandbox="allow-scripts allow-same-origin allow-pointer-lock allow-orientation-lock"
+    allow="fullscreen; gamepad; autoplay; accelerometer; gyroscope; magnetometer"
+    allowfullscreen></iframe>
+</div>
+```
+
+Check for outside requests and errors in a Playwright run, directly or through the harness:
+
+```js
+const gameUrl = "http://localhost:5173/";
+const origin = new URL(gameUrl).origin;
+const outside = [], errors = [];
+page.on("request", (r) => {
+  const u = r.url();
+  if (!u.startsWith(origin) && !/^(data|blob|file):/.test(u)) outside.push(u);
+});
+page.on("websocket", (ws) => outside.push(ws.url()));
+page.on("pageerror", (e) => errors.push(e.message));
+page.on("console", (m) => m.type() === "error" && errors.push(m.text()));
+// play, then expect both arrays to be empty
+```
+
+An economy sim that plays the game's own economy module with three simulated players (see "Prove
+the pacing" under Long-term fun). `record` collects each run for the report:
+
+```js
+// tools/economy-sim.mjs. Run: node tools/economy-sim.mjs
+import { freshSave, playRun, buyNext, rewards, seeded, RUNS_PER_SESSION } from "../src/economy.js";
+const PLAYERS = { slow: 0.45, typical: 0.65, expert: 0.9 };   // where each player's skill levels off
+for (const [name, top] of Object.entries(PLAYERS)) for (let seed = 1; seed <= 20; seed++) {
+  const save = freshSave(), rng = seeded(seed), firstSeen = new Map();
+  for (let session = 1; session <= 150; session++) {
+    const skill = top * (1 - 0.6 * Math.exp(-session / 6));  // learns fast, then plateaus
+    for (let r = 0; r < RUNS_PER_SESSION; r++) playRun(save, skill, rng);
+    while (buyNext(save));                                    // a sensible buyer, not a perfect one
+    for (const id of rewards(save)) if (!firstSeen.has(id)) firstSeen.set(id, session);
+  }
+  record(name, seed, firstSeen); // then print medians and spread, longest gaps, idle money, pass or fail
+}
+```