hayao 0.4.0 → 0.4.2

package/design/20-genres/narrative-decisions.md

@@ -0,0 +1,122 @@
+---
+id: genre-narrative-decisions
+title: Narrative Decisions
+kind: genre
+tags: [narrative, decisions, reigns, swipe, meters, stewardship, choice, cards]
+summary: Impossible stewardship — every choice double-edged, meters balanced between two ditches; judgement beats any fixed policy.
+use-when: The design is a choice-driven game where balancing competing meters via double-edged decisions IS the gameplay (Reigns-like).
+composes-with: [system-economy, system-emergent-systems, pattern-risk-reward, pattern-feedback-loops, pattern-pacing-and-tension]
+anchors: [anchor-reigns]
+verify-with: docs/FUN.md#21-·-narrative-decisions-reigns-like
+---
+
+# Narrative Decisions
+
+**What it is.** You steward something fragile — a kingdom, a ship, a life — through
+a stream of decisions, each with two edges. Every choice moves competing meters; let
+any meter hit a ditch and you lose. The content is the game.
+
+**Player fantasy.** *"I'm holding it together by judgement alone."* The weary,
+compulsive pull of one-more-decision, of keeping every plate spinning when every
+plate-spin tips another.
+
+## Pillars
+
+1. **Every choice is double-edged.** No free wins. A decision that helps one meter
+   must cost another — the tension is the point. A no-op choice is a dead choice.
+2. **Meters live between two ditches.** Each meter loses at *both* extremes (too
+   little AND too much). You're threading, not maximising. Judgement, not a fixed
+   policy, must win (19/20 vs 0/20 in the campaign).
+3. **Content is the level.** Difficulty, pacing, and voice all live in the card
+   deck. When content is data, editorial judgement becomes CI (see below).
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Read a card, weigh two edges, commit; watch the meters twitch. |
+| **Encounter** | A chain of related cards — an arc that pays off or backfires. |
+| **Session** | A reign/run: survive until a doom fires or you reach an ending. |
+| **Meta** | Unlocked arcs/characters/endings; flags carried between runs; the map of what-ifs. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[world-narrative-delivery]] | Story is told *through* the choices and meters — embedded, not narrated at you. |
+| [[system-economy]] | Meters are currencies with faucets and sinks; the whole game is balancing them. |
+| [[system-emergent-systems]] | Flags/relationships that remember past choices turn a deck into a personal history. |
+| [[pattern-risk-reward]] | Every double-edged card is a push-your-luck bet on which meter can afford the hit. |
+| [[pattern-feedback-loops]] | Meters that feed each other (low treasury → unrest → worse options) create the death spiral. |
+
+## Content & difficulty model
+
+- **Editorial judgement is CI.** When choices are data, lint them: unique ids,
+  bounded effects (|Δ| ≤ 20), every needs-flag actually settable somewhere, no
+  no-op choices, no unreachable cards. The content lint *is* the balance test
+  (FUN.md §21).
+- **Doom attribution matters.** Each ending must fire from ITS meter at ITS edge —
+  a swapped ending string wrecks the fiction invisibly. Assert every doom fires its
+  own ending, at its own edge.
+- **Arcs terminate both ways.** A multi-card arc must be able to resolve well *and*
+  badly; a one-way arc is a cutscene.
+- **Prove judgement beats policy.** A balanced-policy bot survives; an
+  always-swipe-one-way bot loses (0/20). If a fixed policy wins, the meters aren't
+  really ditched on both sides.
+- **Pacing lives in the deck order.** A calm-cards-only stretch is a desert; a
+  crisis-cards-only stretch is a death march. Weight the draw so tension breathes —
+  a scare, then a reprieve, then the arc's payoff (see [[pattern-pacing-and-tension]]).
+- **Every card is a small risk-reward bet.** The player is betting which meter can
+  absorb the hit *this* turn; the fun is that the safe-looking edge is often the
+  slow poison. Author both edges to bite differently, never symmetrically.
+
+## Signature-mechanic seeds
+
+- **Reigns *but* the advisors lie, and trust is a hidden meter** — you're weighing
+  the source, not just the choice (mechanic-swap; composes [[system-emergent-systems]]).
+- **Reigns *but* one deck, played by two rulers taking turns** — competitive or
+  co-op stewardship (structure; composes [[genre-coop-chaos]], [[system-coop-and-competition]]).
+- **Reigns *but* your past selves' choices become cards for your heir** — the reign
+  is a run in a roguelite dynasty (structure; composes [[system-meta-progression]]).
+- **Reigns *but* the meters are people, and each ditch is a character leaving**
+  (theme/tonal — reframes numbers as relationships).
+- **Reigns *but* time-pressured — a card auto-resolves badly if you stall** (constraint;
+  adds a real-time clock over the turn-based deck).
+
+## Common pitfalls
+
+- **Dominant strategy.** If "always favour treasury" survives, a meter isn't ditched
+  on both sides — the balanced-policy proof is passing while the game is broken.
+  Fix the ditches, not the bot.
+- **Unbounded effects.** A card that swings a meter 60 points makes planning
+  impossible and the arc a coin flip. Cap |Δ| and assert it.
+- **Ending soup.** Dooms that fire from the wrong meter, or generic "you lost"
+  strings, gut the fiction. Attribute each ending to its own edge.
+- **Content that isn't data.** Hand-coded branches can't be linted and rot silently.
+  Keep choices in a pure data deck (FUN.md law 7) so editorial checks run in CI.
+
+## Anchors
+
+- [[anchor-reigns]] — swipe-choice narrative; meters between two ditches;
+  stewardship as the whole verb.
+
+## Verify
+
+Prove it against [FUN.md §21 — Narrative decisions](../../docs/FUN.md#21-·-narrative-decisions-reigns-like):
+balanced-policy bot survives; always-left loses 0/20; content lint (unique ids,
+|Δ| ≤ 20, settable flags, no no-ops); every doom fires its own ending; arcs
+terminate both ways. Chrome/menus via `showScreen()`; the card view is `cosmetic`.
+
+## Composes with
+
+- [[world-narrative-delivery]] — the story is delivered through choices; this genre
+  is its purest engine.
+- [[system-economy]] — treat meters as currencies and the balance problem becomes a
+  faucet/sink problem.
+- [[pattern-feedback-loops]] — inter-meter loops author the death spiral and the
+  comeback.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §21 — the content-lint recipe in full.
+- [[world-narrative-delivery]] — techniques for telling story with little text.

package/design/20-genres/physics-arcade.md

@@ -0,0 +1,124 @@
+---
+id: genre-physics-arcade
+title: Physics Arcade
+kind: genre
+tags: [physics, arcade, breakout, peggle, pinball, bounce, aim, swept-collision]
+summary: Trustworthy flight — aim, launch, watch a ball obey clean physics; maximal juice on one trivial input.
+use-when: The design is a launch-and-watch bouncer (Breakout/Peggle/pinball): one aim, deterministic flight, spectacle on impact.
+composes-with: [genre-tower-defense, system-reward-schedules, system-build-diversity, pattern-juice-choreography, pattern-risk-reward, pattern-pacing-and-tension]
+anchors: [anchor-peggle, anchor-tetris]
+verify-with: docs/FUN.md#19-·-physics-arcade-breakoutpeggle
+---
+
+# Physics Arcade
+
+**What it is.** You aim one launcher, release, and a ball obeys clean, predictable
+physics — bouncing off pegs, bricks, bumpers, walls — while you watch it pay off.
+Input is trivial (an angle, a power); the depth is in *reading the table* and the
+delight is in the cascade you set in motion.
+
+**Player fantasy.** *"I called that shot."* The satisfaction of a bank-shot you
+planned plus the slot-machine thrill of a ricochet you didn't — cause you own,
+consequence the physics authors.
+
+## Pillars
+
+1. **Trustworthy flight.** The ball never tunnels, never teleports, never cheats.
+   Swept collision (closed-form time-of-impact) makes the table *readable* — you
+   can plan a bank shot because the sim will honour it.
+2. **Big reward on tiny input.** One angle, maximal spectacle. The juice budget is
+   the game; a plain input earns a disproportionate light-and-sound payoff.
+3. **Legible table.** Every peg, bumper, and multiplier tells you what it does
+   *before* you fire. The board is a puzzle you solve with an aim.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Nudge the aim; the trajectory preview updates; commit. |
+| **Encounter** | One launch → a chain of bounces → clears + score, resolved and choreographed. |
+| **Session** | A board (all targets) or a run of boards; ball budget as the fail clock. |
+| **Meta** | Unlocked launchers/balls/perks; high-score chase; new table layouts. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-reward-schedules]] | The variable-ratio ricochet is the genre's dopamine engine; tune the payoff curve. |
+| [[pattern-juice-choreography]] | Impact feedback (hitstop, particles, pitch-rising combo) *is* the product. |
+| [[pattern-risk-reward]] | The greedy multiplier peg guarded behind a hard bank; last-ball pressure. |
+| [[system-build-diversity]] | Optional: launchers/balls/perks that change how the table plays. |
+| [[system-progression]] | Board-to-board unlocks; score thresholds that gate the next table. |
+
+## Content & difficulty model
+
+- **Layout is the level.** Difficulty is peg geometry, not ball speed — a tight
+  cluster behind a wall, a lone multiplier in a corner. Author boards, not stats.
+- **Ball budget is the fail clock.** Fewer balls, tighter clears. Grace = an extra
+  ball earned by a bucket catch or a full-clear bonus.
+- **Prove winnability with the aim-search bot.** Clone the world, fire candidate
+  aims, count clears. This is both your "is the board beatable?" gate and a
+  difficulty meter — a board only one aim clears is a spike.
+- **Energy honesty is a fairness rail.** A bounce never leaves the ball faster than
+  it arrived; a conservation check catches physics bugs that masquerade as
+  liveliness (see FUN.md §19).
+- **Ramp by geometry, then by budget.** Early boards teach one bank; later boards
+  chain them and starve the ball count. The aim-search bot's clear-count per board
+  is your ramp read-out — plot it, look for cliffs, smooth them.
+- **Skill delta is measurable.** The planned-aim bot must clear boards a
+  random-aim bot can't (FUN.md law 2). If firing blind competes with aiming, the
+  table has no puzzle — the depth is fake and the juice is doing all the work.
+
+## Signature-mechanic seeds
+
+- **Peggle *but* every peg you leave alive fires back next turn** — the table is an
+  enemy that reloads (constraint + mechanic-swap; composes [[genre-tower-defense]]).
+- **Breakout *but* the paddle is gravity** — you tilt the whole table instead of
+  moving a bar (perspective; the input becomes a field, not a position).
+- **Pinball *but* the flippers cost mana you bank from clears** — economy on the
+  twitchiest genre (mechanic-swap; composes [[system-economy]]).
+- **Peggle *but* co-op, one aims and one nudges the table mid-flight** (structure;
+  composes [[system-coop-and-competition]], [[genre-coop-chaos]]).
+- **Breakout *but* the bricks are a deck you drafted** — layout as loadout (structure;
+  composes [[genre-deckbuilder]]).
+
+## Common pitfalls
+
+- **Substep-and-pray collision.** Discrete steps tunnel the ball through thin walls
+  at speed; the shot the player trusted fails invisibly. Use swept TOI — the table
+  stops being trustworthy the first time a bank shot lies.
+- **Difficulty via ball speed.** Faster balls read as *unfair*, not *harder*. Make
+  it harder with geometry and budget.
+- **Juice with no sim consequence.** Screen-shake on every peg dilutes the payoff;
+  reserve the big choreography for multipliers and clears (the 2-senses contract).
+- **RNG that isn't yours.** Deflection randomness must run through `world.rng` or
+  goldens and shot-planning bots break (FUN.md law 7).
+- **No breather.** A wall of trick-shot boards with no easy clear exhausts; pace a
+  gimme board after a spike so the reward loop can reset (see [[pattern-pacing-and-tension]]).
+
+## Anchors
+
+- [[anchor-peggle]] — variable-ratio reward + maximal juice on a trivial input; the
+  canonical "big payoff, tiny action" loop.
+- [[anchor-tetris]] — the discipline of one perfectly-tuned verb; borrow its
+  restraint, not its board.
+
+## Verify
+
+Prove it against [FUN.md §19 — Physics arcade](../../docs/FUN.md#19-·-physics-arcade-breakoutpeggle):
+swept-collision no-tunnel proof (24k px/s + 1px-graze-misses), energy invariant,
+aim-search bot clears within the ball budget, golden run. See
+[`sandboxes/physics-lab`](../../sandboxes/physics-lab) for the collision primitive
+in isolation.
+
+## Composes with
+
+- [[genre-tower-defense]] — coverage geometry and "counter by placement" transfer
+  when pegs fight back.
+- [[pattern-juice-choreography]] — this genre lives or dies on impact feel.
+- [[system-reward-schedules]] — the ricochet is a variable-ratio drop; tune it ethically.
+
+## See also
+
+- [`docs/JUICE.md`](../../docs/JUICE.md) — the feel gates for impact choreography.
+- [`sandboxes/physics-lab`](../../sandboxes/physics-lab) · [`sandboxes/juice-lab`](../../sandboxes/juice-lab) — the parts, wired.

package/design/20-genres/precision-platformer.md

@@ -0,0 +1,127 @@
+---
+id: genre-precision-platformer
+title: Precision Platformer (Celeste-like)
+kind: genre
+tags: [platformer, precision, celeste, movement, grace, dash, coyote, feel]
+summary: Trust in inputs — a movement envelope so honest that every death is the player's own, and the retry is instant enough to make failure fuel.
+use-when: Designing a tight single-screen platformer where mastery of one movement verb is the whole game.
+composes-with: [system-grace, system-onboarding, system-difficulty-and-dda, system-save-and-checkpoint, system-collectibles]
+anchors: [anchor-celeste]
+verify-with: docs/FUN.md#2--precision-platformer-celeste-like
+---
+
+# Precision Platformer (Celeste-like)
+
+**What it is.** A character, a jump, usually one signature air-verb (dash,
+grapple, double-jump), and rooms built exactly to the edge of what that verb can
+do. Death is cheap; the room is the puzzle; your *hands* are the solution.
+
+**Player fantasy / why it's fun.** *"That was me."* The screen fills with your
+corpses and then you thread the room clean, and the difference was skill you can
+feel yourself having grown. The controls never betray you, so every failure is a
+lesson you accept.
+
+## Pillars
+
+1. **The controls are trustworthy.** Inputs land on the frame you press them.
+   Coyote time, jump buffering, corner correction — the [[system-grace]] canon
+   makes the character do what you *meant*. Deaths are never the game's fault.
+2. **Death is free.** Instant respawn, at the room's mouth, momentum unbroken.
+   Retry friction is the enemy of flow. (Corpus: CLAWSTRIKE sells itself on
+   "each retry is instant, keeping the momentum alive.")
+3. **The room is a sentence.** Each screen states one idea in your verb's
+   vocabulary and asks you to say it back cleanly. Rooms compose ideas; they
+   never pad.
+
+## The loop stack
+
+| Scale | The loop |
+|---|---|
+| **Moment** | Jump/dash across one gap. Land or die. Sub-second. |
+| **Encounter** | One room (screen): read the layout → attempt → die → adjust one input → thread it clean. |
+| **Session** | A chapter of ~20–40 rooms sharing a movement idea, ending on a room that combines them all. |
+| **Meta** | Optional B-side rooms, hidden collectibles, deathless-run and speedrun goals — the ceiling for players who own the floor. |
+
+## Essential systems
+
+| System | Why it's needed |
+|---|---|
+| [[system-grace]] | The genre's spine. Coyote/buffer/corner-correction/variable-height are ~15 unit tests, not vibes (FUN.md law 5). Spec every window in frames. |
+| [[system-onboarding]] | Teach the verb by *safe* rooms first — a dash over a pit you can't fall out of — before the verb is load-bearing over a spike. |
+| [[system-difficulty-and-dda]] | The chapter is the curve; assist mode (slower time, invincibility, air-dashes) extends the audience without touching the core (see Celeste). |
+| [[system-save-and-checkpoint]] | Per-room respawn is the checkpoint; deaths must never rewind more than the current room. |
+| [[system-collectibles]] | Optional off-path collectibles give the skilled a reason to master rooms twice. |
+
+## Content & difficulty model
+
+- **Derive the room from the envelope, never eyeball it.** Compute
+  `jumpDistance` / `dashJumpDistance` from the actual config *first*; a gap that's
+  one pixel past the dash isn't hard, it's broken. Leave human slack — a
+  frame-perfect gap is a bug. See [`recipes/platformer-feel.md`](../../recipes/platformer-feel.md)
+  for the movement-envelope recipe and [FUN.md law 3](../../docs/FUN.md#part-1--universal-laws).
+- **One idea per room, then combine.** Room introduces "dash *up*," next room
+  "dash up into a wall-slide," boss room chains four ideas at speed.
+- **Difficulty = execution length between checkpoints, not gap tightness.** A
+  long clean sequence is harder than one brutal jump; scale by *how many* honest
+  inputs in a row, not by shaving pixels.
+- **Momentum must survive flight.** Split air-acceleration from air-friction so
+  inherited speed carries; a dash off a moving lift should feel like the lift gave
+  it to you (FUN.md §2).
+
+Reference wiring: [`examples/updrift`](../../examples/updrift) — the golden
+platformer-feel reference; [`examples/kintsugi`](../../examples/kintsugi) — how
+five abilities extend the movement envelope; [`examples/shard-ascent`](../../examples/shard-ascent) —
+the reactive waypoint bot pattern that proves every room 0-deaths.
+
+## Signature-mechanic seeds
+
+"X but Y" ([[process-the-twist]]) — bend the *verb* or the *cost of death*.
+
+- **Celeste but you keep one echo of your last run** — a ghost replays your prior
+  attempt and you must not touch it. (mechanic-swap)
+- **Celeste but the dash paints the platform it lands on** — traversal builds the
+  level for a second lap. (mechanic-swap)
+- **Celeste but momentum never resets** — no braking; the room is solved by
+  *shedding* speed, not adding it. (constraint)
+- **Celeste but death rewinds time three seconds** — failure is a scrub, not a
+  respawn; you re-enter your own recent past. (structure)
+- **Celeste but two characters, one jump button** — mirrored twins share input;
+  the room resolves only when both survive. (constraint)
+
+## Common pitfalls
+
+- **Untrustworthy input.** No coyote/buffer/corner-correction → the player blames
+  the game, correctly. This is the one non-negotiable; ship the grace canon or
+  don't ship. [[system-grace]].
+- **Retry friction.** A death animation, a fade, a "you died" screen — each one
+  bleeds flow. Respawn on the next frame.
+- **Difficulty by pixel-shaving.** Frame-perfect gaps read as unfair. Depth comes
+  from *sequences*, not from tolerances.
+- **Momentum amnesia.** Flight that discards inherited speed makes dashes feel
+  dead. Preserve it (FUN.md §2).
+- **Verb creep.** Adding a fourth air-move dilutes mastery of the first. One
+  signature verb, deeply explored, beats four shallow ones.
+
+## Anchors
+
+- [[anchor-celeste]] — the precision platformer *and* the humaneness of assist
+  mode; grace as a first-class system, not polish.
+
+## Verify
+
+Prove it with **[FUN.md §2 · Precision platformer](../../docs/FUN.md#2--precision-platformer-celeste-like)** —
+waypoint bot beats every room 0-deaths; movement-envelope inequalities asserted
+against config; grace windows tested edge-in/edge-out. Design the feel here; prove
+the trust there.
+
+## Composes with
+
+- [[system-grace]] — the load-bearing system; the pillar-1 promise made mechanical.
+- [[pattern-mastery-and-flow]] — the retry loop lives or dies on flow.
+- [[pattern-anti-frustration]] — free death is the whole forgiveness contract.
+
+## See also
+
+- [`recipes/platformer-feel.md`](../../recipes/platformer-feel.md) — the movement-feel recipe.
+- [`examples/updrift`](../../examples/updrift) — the golden feel reference.
+- [`docs/FUN.md §2`](../../docs/FUN.md#2--precision-platformer-celeste-like) — the proof playbook.

package/design/20-genres/racing.md

@@ -0,0 +1,126 @@
+---
+id: genre-racing
+title: Racing
+kind: genre
+tags: [racing, driving, top-down, understeer, braking, line, checkpoint, laps]
+summary: The speed/line tradeoff made physical — brake to hold the line or floor it and drift wide; the racing line is the skill.
+use-when: The design is a top-down/arcade racer where cornering is a real physics tradeoff and lap time is the score.
+composes-with: [system-enemy-ai, system-difficulty-and-dda, system-progression, pattern-mastery-and-flow, pattern-risk-reward, pattern-pacing-and-tension]
+anchors: []
+verify-with: docs/FUN.md#20-·-top-down-racing
+---
+
+# Racing
+
+**What it is.** You drive a line through corners where speed and control genuinely
+trade off — flooring it understeers you wide, braking tucks you tight. The whole
+game is finding and holding the fast line lap after lap, usually against rivals.
+
+**Player fantasy.** *"I found the perfect line."* Mastery you can feel in your
+thumbs: the corner you used to blow now flows, and the clock proves it.
+
+## Pillars
+
+1. **The speed/line tradeoff is physical.** Turn authority *falls* with speed
+   (understeer), not grip that magically holds — so flat-out must NOT make every
+   bend. Braking is the skill the genre sells; make it a dedicated control.
+2. **The clock never lies.** Lap time is the honest, legible score. Every tenth is
+   a decision you made three corners ago. Ghosts and rivals externalise it.
+3. **The track is the level.** Corner radius, track width, and sequence author the
+   difficulty. Design the geometry against the car's turn radius, not by vibes.
+
+## The loop stack
+
+| Scale | The beat |
+|---|---|
+| **Moment** | Brake point → apex → throttle out; one corner, committed. |
+| **Encounter** | A lap: chain corners into a rhythm, defend/overtake a rival. |
+| **Session** | A race or time-trial; the grand prix; podium or PB. |
+| **Meta** | Unlocked tracks/cars/tuning; championship standings; leaderboard chase. |
+
+## Essential systems
+
+| System | Why it's load-bearing |
+|---|---|
+| [[system-enemy-ai]] | The rival `driveLine()` is difficulty dial, completability proof, and skill-delta meter in one. |
+| [[system-difficulty-and-dda]] | Rubber-banding, assist braking, racing-line guides — the ramp for a wide skill range. |
+| [[pattern-mastery-and-flow]] | The corner you now flow through *is* the flow channel; the genre is a mastery curve. |
+| [[system-progression]] | Track/car unlocks; tuning as a shallow build layer. |
+| [[pattern-risk-reward]] | Late braking, cutting the kerb, the overtake into a blind corner. |
+
+## Content & difficulty model
+
+- **Derive geometry from the car, not the other way.** The inequality chain: turn
+  radius (speed ÷ steer-authority) < corner radius < track width. State it as a
+  comment and assert it against the actual track and config (FUN.md law 3, §20).
+- **Ordered checkpoints are the entire anti-cheat.** Only the NEXT checkpoint
+  counts; cutting the track advances nothing. This single rule replaces a
+  collision-fence forest.
+- **Off-track has a speed cap**, not a wall — punish the sloppy line without a
+  hard stop that reads as unfair.
+- **The rival is your difficulty dial.** One good `driveLine()` at scalable pace
+  gives you completability proof (it finishes) and a skill-delta meter (a braking
+  line beats a flooring line: 26.2s vs 27.7s in the campaign).
+- **Track sequence is a tension curve.** Alternate a technical corner-cluster with a
+  flat-out straight so the player exhales; a circuit of nothing but hairpins reads
+  as punishment, not mastery (see [[pattern-pacing-and-tension]]).
+- **A ghost is the gentlest teacher.** Racing your own PB (or the rival's line)
+  externalises the ideal line without a tutorial pop-up — onboarding by contrast.
+
+## Signature-mechanic seeds
+
+- **Top-down racer *but* the track is drawn behind you and erased ahead** — commit
+  to a line you can't preview (constraint; composes [[system-procgen-design]]).
+- **Racing *but* braking recharges a boost you spend on straights** — the tradeoff
+  becomes an economy, not just a physics fact (mechanic-swap; [[system-economy]]).
+- **Racing *but* every rival remembers how you overtook them and blocks it next
+  lap** (mechanic-swap + emergence; composes [[system-emergent-systems]]).
+- **Racing *but* one screen, no scroll — the whole circuit visible, you optimise
+  the global line** (perspective/constraint).
+- **Racing *but* cargo shifts your mass and turn radius as you deliver it** — the
+  car changes under you mid-race (mechanic-swap).
+
+## Common pitfalls
+
+- **Grip instead of understeer.** If more speed just means "more traction needed,"
+  flat-out beats braking and the whole genre collapses. Authority must fall with
+  speed; assert flat-out fails a real corner.
+- **No dedicated brake.** Braking-as-absence-of-throttle robs the player of the
+  skill expression the genre is built on. Bind brake to its own key (corpus:
+  WitchCup1276, DR1V3N WILD both do).
+- **Rubber-band that erases skill.** DDA that pulls rivals to your bumper regardless
+  of your line makes lap time meaningless. Band the *field*, not the outcome.
+- **Wall-collision anti-cheat.** Fencing every shortcut is brittle; ordered
+  checkpoints make cutting simply not count.
+- **Wall-clock timing.** Lap timing and physics must step on sim time, not
+  `Date.now`, or the golden grand prix and PB ghosts drift (FUN.md law 6).
+
+## Anchors
+
+*(No dedicated anchor module yet.)* Borrow structure from [[anchor-tetris]] for the
+"one tuned verb, endless mastery" discipline, and from [[anchor-into-the-breach]]
+for perfect-information honesty if you telegraph rival intent. Corpus references:
+WitchCup1276 (2023 gameplay #10), DR1V3N WILD (2024 gameplay #3).
+
+## Verify
+
+Prove it against [FUN.md §20 — Top-down racing](../../docs/FUN.md#20-·-top-down-racing):
+the `driveLine()` bot finishes laps; braking beats flooring (skill delta); cutting
+advances nothing; off-track speed cap holds; golden grand prix. See
+[`sandboxes/physics-lab`](../../sandboxes/physics-lab) for the vehicle-physics
+primitives and [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) for
+the racing-line follower.
+
+## Composes with
+
+- [[system-enemy-ai]] — the rival driver is the beating heart of both difficulty
+  and proof.
+- [[pattern-mastery-and-flow]] — cornering mastery is the flow channel; pace the
+  track to keep the player in it.
+- [[system-difficulty-and-dda]] — assist braking and line guides widen the audience.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) law 3 — derive the turn-radius inequality
+  before you lay a single corner.
+- [`sandboxes/physics-lab`](../../sandboxes/physics-lab) — the car, in isolation.

package/design/20-genres/rhythm.md

@@ -0,0 +1,125 @@
+---
+id: genre-rhythm
+title: Rhythm
+kind: genre
+tags: [rhythm, beat, timing, window, bpm, frame-exact, music, tempo]
+summary: Beat-locked timing game where the beat IS sim time and fairness is three frame-exact assertions — tight but fair.
+use-when: Designing a rhythm/beat game where inputs must land in frame-honest windows and the music is an observer of the beat clock.
+composes-with: [pattern-juice-choreography, system-grace, system-difficulty-and-dda, system-onboarding]
+anchors: [anchor-tetris, anchor-peggle]
+verify-with: docs/FUN.md#18--rhythm
+---
+
+# Rhythm
+
+**What it is.** Actions that only count on the beat. A clock ticks in musical time; you
+press inside a window around each beat, and the world answers in tempo. Whether it's
+tap-the-note, move-on-beat, or fight-on-beat, the game is a legality filter over time:
+right thing, right frame.
+
+**Player fantasy / why it's fun.** *"I'm locked into the groove and the game is moving
+with me."* The pull is embodied precision — the satisfaction of a press that lands
+exactly, the whole system pulsing in time. Fun is **tight but fair**: a window narrow
+enough to demand mastery, honest enough that a miss is always yours.
+
+## Pillars
+
+1. **The beat is sim time.** Pick a BPM so **one beat is an integer frame count**. The
+   sim advances on the beat counter; audio is an *observer* that schedules sound off
+   that counter. Never the reverse — audio-driven timing is unprovable and drifts.
+2. **Fairness is frame-exact.** Three assertions define the whole feel: the input is
+   accepted at the **window edge**, refused at **edge+1**, and **hammering acts once**.
+   If those three hold, the game is fair; if any fails, it's a lie you can feel.
+3. **Rhythm is a filter over a turn-based game.** Underneath the beat is a discrete
+   turn system; the rhythm layer is a thin input-legality gate (~30 lines over a
+   roguelike). Design the turn game first, then constrain *when* moves are legal.
+
+## The loop stack
+
+| Layer | The beat |
+|---|---|
+| **Moment** | Hit the window on the beat → the action fires in tempo. |
+| **Encounter** | A phrase/pattern: a run of beats to nail without breaking the chain. |
+| **Session** | A track/level: sustain accuracy from start to finish. |
+| **Meta** | Song select, difficulty tiers, combo/score mastery, new charts. |
+
+## Essential systems
+
+| System | Why this genre needs it |
+|---|---|
+| [[pattern-juice-choreography]] | Feel IS choreography timed to the beat; every hit's flash/pop must land on the frame the sim fired. |
+| [[system-grace]] | The hit window and input buffer are a grace system — accepted-inside / refused-outside, proven to the frame. |
+| [[system-difficulty-and-dda]] | Difficulty = window width, note density, and tempo; the tuning dials of "tight but fair". |
+| [[system-onboarding]] | Teach the window by doing on a slow, forgiving track before narrowing it. |
+| [[system-mastery-curve]] | The skill ceiling is timing precision; charts must reward tighter play with higher scores. |
+| [[system-procgen-design]] | Charts as content; generate/validate patterns that stay hittable at tempo. |
+
+## Content & difficulty model
+
+- **BPM is chosen, not found.** Solve for a BPM where a beat is an integer number of
+  frames; every chart is authored on that grid. A non-integer beat makes the window
+  jitter and the three frame assertions impossible to state cleanly.
+- **Window honesty is the whole verify.** Assert the edge-in, edge+1-out, and
+  hammer-acts-once cases frame-exactly. These three are the genre's mechanical truth —
+  state them before charting a single note.
+- **Foes are frozen between beats.** If the underlying turn game has enemies, prove they
+  act *only* on their beats — no between-beat movement — or the rhythm read breaks.
+- **Difficulty ramps three dials.** Narrow the window, raise the density, lift the tempo
+  — independently, so a chart can be fast-but-forgiving or slow-but-strict. Never make a
+  chart "hard" by making the window dishonest.
+- **Hash-identical replay.** A beat-perfect bot must clear, and the same inputs must
+  replay to an identical `world.hash()` — the beat clock makes the whole sim reproducible.
+
+## Signature-mechanic seeds
+
+- **Rhythm but it's a roguelike — every step is a beat** — move, attack, and dodge only
+  on the pulse; the dungeon is a turn game with a metronome (structure; the literal
+  "filter over a turn-based game").
+- **Rhythm but you're clearing a match-3 board on tempo** — swaps only register on the
+  beat, cascades resolve in time (mechanic-swap; fuses [[genre-match3]]'s cascade with
+  the beat clock).
+- **Rhythm but the beat is a duel** — attacks land only on-beat against a telegraphing
+  foe; parries are windows (mechanic-swap; a fighting game gated by tempo).
+- **Rhythm but one button, one lane, escalating tempo** — a hard constraint that makes
+  pure timing the entire skill (constraint; the [[anchor-tetris]] "one perfect verb" read).
+- **Rhythm but missing isn't failing, it's souring** — off-beat presses detune the music
+  instead of ending the run (tonal; forgiveness as feel, pairs with [[system-grace]]).
+
+## Common pitfalls
+
+- **Audio-driven timing.** Scheduling the sim off sound makes it drift and unprovable;
+  the beat counter drives, audio observes. This inversion is the genre's cardinal sin.
+- **Non-integer beats.** A beat that isn't a whole frame count makes windows jitter and
+  the fairness assertions unstateable. Choose the BPM to fix this.
+- **Dishonest windows.** A window that's secretly wider/narrower than shown, or that
+  accepts a hammered double-press, feels like a cheat even when the player can't name it.
+- **Between-beat enemy motion.** Foes that drift off the pulse destroy the read; freeze
+  them between beats and prove it.
+- **Charts before the clock.** Authoring notes before the frame-exact window is proven
+  bakes unfairness into every level. Prove the three assertions first.
+
+## Anchors
+
+- [[anchor-tetris]] — the perfectly-tuned single verb and pure endless mastery; the
+  reference for the one-button, escalating-tempo bend.
+- [[anchor-peggle]] — maximal juice on a precisely-timed input; the choreography-on-hit
+  feel the rhythm genre lives or dies on.
+
+## Verify
+
+Beat-perfect bot clears; window honest to the frame; foes provably frozen between
+beats; hash-identical replay → **[docs/FUN.md §18 · Rhythm](../../docs/FUN.md#18--rhythm)**.
+Design the beat grid and turn game here; prove the three frame assertions there.
+
+## Composes with
+
+- [[pattern-juice-choreography]] — the on-beat feel; every hit choreographed to sim time.
+- [[system-grace]] — the hit window as a frame-exact grace system.
+- [[system-difficulty-and-dda]] — window/density/tempo as the difficulty dials.
+
+## See also
+
+- [docs/FUN.md §18](../../docs/FUN.md#18--rhythm) — mechanical truth + verify recipe.
+- [docs/JUICE.md](../../docs/JUICE.md) — feel gates for the on-beat choreography.
+- [`sandboxes/`](../../sandboxes/) — reach for the tweens/timing lab to prove a
+  window frame-exactly before charting.