moshcode 0.58.0 → 0.60.0

package/src/engines.mjs

@@ -19,6 +19,14 @@
 // repeating; only put a pattern here when it is this engine's own wording.
 // Every pattern is matched against the bottom of the screen with ANSI stripped.
 //
+// `hooks` (optional) is how this engine reports its own state, so the herd can
+// stop reading paint (PRD 0011 R1). It sits here for the same reason `state`
+// does — and because the two are the same fact at different confidence: a hook
+// spec supersedes the screen rules below it, so an engine that gains one should
+// keep its rules rather than delete them. A missing `hooks` is not a gap to
+// paper over with a guess; it means this engine is classified from its screen,
+// which is what every engine did before.
+//
 // `resume` (optional) is the argv that reopens this engine's last conversation,
 // used by `moshcode restore --resume` after a reboot. Omit it rather than guess:
 // a session that starts fresh is a small disappointment, and one that starts
@@ -82,6 +90,30 @@ export const ENGINES = {
       "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_CHILD_SESSION",
     ],
     resume: ["--continue"],
+    // The engine speaking for itself (PRD 0011 R1). Claude Code's lifecycle
+    // hooks are documented and stable, which is why it is the one engine that
+    // ships a spec here rather than a promise to write one: a hook schema we
+    // guessed at would be a rule that rots with no screen to fall back to.
+    //
+    // `file` is a function, not a path, because the whole install is a write to
+    // the user's home and the only honest way to test that is to move HOME.
+    hooks: {
+      format: "claude-settings",
+      file: () => path.join(homedir(), ".claude", "settings.json"),
+      // Stop fires when the turn ends, which is the end of the *task* — A2A
+      // calls the same moment `completed`. Notification covers both halves of
+      // blocked (a permission request and a plain question). UserPromptSubmit
+      // is the cheapest honest `working`: PreToolUse would also do it, at the
+      // cost of forking a moshcode per tool call for a state it is already in.
+      // `label` is what moshcode calls the event; `event` is what the engine
+      // calls it. They differ because one is a sentence and the other is a
+      // schema key, and printing the schema key at someone is not an answer.
+      events: [
+        { event: "Stop", state: "done", label: "stop" },
+        { event: "Notification", state: "blocked", label: "notification" },
+        { event: "UserPromptSubmit", state: "working", label: "prompt-submit" },
+      ],
+    },
     state: {
       // The permission dialog's own heading, and the selector on its first
       // option — the generic numbered-menu pattern would catch the second only

package/src/games-breakout.mjs

@@ -5,6 +5,7 @@
 // a wall. Without that you cannot dig a channel up the side of the wall, and
 // digging a channel is the entire reason anybody still plays this.
 import { advanceBall, drawnBall, drawnCell, snapBall } from "./games-draw.mjs";
+import { glidePaddle, holdPaddle, paddleMotion, perSecond, pressPaddle, releasePaddle } from "./games-paddle.mjs";
 import { acid, amber, bone, danger, rgb } from "./ui.mjs";
 
 export const WIDTH = 40;
@@ -17,11 +18,11 @@ export const BRICK_TOP = 1;
 
 export const PADDLE_W = 7;
 export const PADDLE_ROW = HEIGHT - 1;
-// A keypress, not a tick, so this is unchanged by the tick rate — but it does
-// have to keep up with the ball, and a ball taken off the end of the paddle now
-// crosses a column in under two ticks. Three columns a press stays ahead of it
-// at a terminal's key-repeat rate; two only just did.
-const PADDLE_STEP = 3;
+// Three columns a press was enough to keep up with the ball and much too much
+// to watch: at a terminal's repeat rate the paddle covered ninety columns a
+// second in jumps you could count. It is now a press's worth of *travel* rather
+// than a jump, paid out over the ticks that follow — see games-paddle.mjs.
+const PADDLE_STEP = 3;            // columns one press is worth
 
 /**
  * How often the wall is stepped. See the note in games-pong.mjs: the ball can
@@ -59,6 +60,23 @@ const MAX_VX = 1.4 * SCALE;
 const MIN_VX = 0.15 * SCALE;    // never let it go vertical and unsteerable
 const LEVEL_UP = 1.12;          // a multiplier on pace, so it does not scale
 
+/**
+ * How fast the paddle runs while you hold an arrow, in columns per second.
+ *
+ * The fastest the ball ever travels sideways is `MAX_VX`, which is fifty-three
+ * columns a second. A paddle slower than that is one that a ball taken off the
+ * end can simply outrun, so this sits just above it: you can always still get
+ * there, and only just, which is the game. It crosses the board in a little
+ * over half a second.
+ */
+const PADDLE_RATE = perSecond(58, TICK_MS);
+
+/** The board's edges, as far as the paddle is concerned. */
+const PADDLE_GLIDE = { rate: PADDLE_RATE, step: PADDLE_STEP, lo: 0, hi: WIDTH - PADDLE_W };
+
+/** Which way an arrow moves the paddle, and 0 for a key that is not one. */
+const towards = (key) => (key === "left" ? -1 : key === "right" ? 1 : 0);
+
 /** Top rows are worth more, which is what makes the ball worth risking. */
 export const ROW_POINTS = [50, 40, 30, 20, 10];
 const ROW_COLOR = [danger, amber, acid, rgb(90, 200, 250), rgb(190, 130, 255)];
@@ -97,6 +115,11 @@ export function launch(state) {
 
 /** One tick. Exported so a test can clear a whole wall with no clock. */
 export function step(state) {
+  // The paddle moves here, with the ball, rather than back in `onKey` — so it
+  // travels at a speed instead of jumping at the keyboard's repeat rate. It
+  // goes first so that a ball resting on it is put where it has just got to.
+  state.paddle = glidePaddle(state.motion, state.paddle, PADDLE_GLIDE);
+
   if (state.stuck) {
     // A ball that has not been launched rides the paddle, so moving before you
     // serve aims the serve. It is carried rather than travelling, so it is put
@@ -175,11 +198,13 @@ export const BREAKOUT = {
   blurb: "dig a channel up the side and let the ball do the rest",
   keys: "← → paddle · space launch · q quit",
   tickMs: TICK_MS,
+  heldKeys: true,   // worth asking the terminal for key releases — see games.mjs
 
   create({ rng = Math.random } = {}) {
     const state = {
       wall: buildWall(),
       paddle: Math.floor((WIDTH - PADDLE_W) / 2),
+      motion: paddleMotion(),
       score: 0,
       lives: LIVES,
       level: 1,
@@ -192,10 +217,36 @@ export const BREAKOUT = {
 
   tick: step,
 
-  onKey(state, key) {
-    if (key === "left") state.paddle = clamp(state.paddle - PADDLE_STEP, 0, WIDTH - PADDLE_W);
-    else if (key === "right") state.paddle = clamp(state.paddle + PADDLE_STEP, 0, WIDTH - PADDLE_W);
-    else if (key === "space" || key === "up" || key === "enter") launch(state);
+  onKey(state, key, ctx) {
+    const dir = towards(key);
+    if (dir) {
+      // Told when the key comes back up, the paddle is simply put in gear and
+      // the tick does the rest — including for the auto-repeats that keep
+      // arriving while it is held, which must not be allowed to add a second
+      // helping of speed on top of the one the tick is already paying.
+      if (ctx?.heldKeys) { holdPaddle(state.motion, dir); return state; }
+      // Not told, it is paid for a press at a time. A press that finds it
+      // standing still is also spent immediately, so the frame this keypress
+      // draws already has it moving; a press that finds it already moving is
+      // not, because the tick is paying it out evenly and a second helping on
+      // top would be the very jolt this is here to remove.
+      const resting = state.motion.owed === 0;
+      pressPaddle(state.motion, dir, PADDLE_STEP);
+      if (resting) state.paddle = glidePaddle(state.motion, state.paddle, PADDLE_GLIDE);
+      // A ball waiting on the paddle is carried by it, and aiming the serve is
+      // the only thing you can do before you launch: it would look broken if it
+      // stayed behind until the next tick.
+      if (state.stuck) {
+        state.ball.x = state.paddle + PADDLE_W / 2;
+        snapBall(state.drawn, state.ball.x, state.ball.y);
+      }
+    } else if (key === "space" || key === "up" || key === "enter") launch(state);
+    return state;
+  },
+
+  onRelease(state, key) {
+    const dir = towards(key);
+    if (dir) releasePaddle(state.motion, dir);
     return state;
   },
 
@@ -223,7 +274,10 @@ export const BREAKOUT = {
       }
     }
 
-    for (let i = 0; i < PADDLE_W; i++) put(state.paddle + i, PADDLE_ROW, bone("▀"));
+    // The paddle travels on fractions of a column and is drawn on whole ones,
+    // the same as the ball is.
+    const paddle = Math.round(state.paddle);
+    for (let i = 0; i < PADDLE_W; i++) put(paddle + i, PADDLE_ROW, bone("▀"));
     // Drawn on half-rows and on its own even clock, so the ball steps the same
     // distance down the wall as across it, and at a rate. See games-draw.mjs.
     const ball = drawnCell(state.drawn);

package/src/games-paddle.mjs

@@ -0,0 +1,128 @@
+// Shared paddle motion, for the games where the thing you hold is a paddle.
+//
+// Everything else on a pong or breakout board already moves on the tick. The
+// ball is stepped sixty times a second and then drawn on its own even clock
+// (games-draw.mjs) precisely so that it reads as travelling rather than
+// hopping. The paddle did not: it was moved by the keypress itself, one jump
+// per key, which left the one object you are actually steering as the only
+// thing on the board not moving at a rate.
+//
+// Two things fall out of that, and both of them read as a slow game rather than
+// as a coarse control.
+//
+// A terminal has no key-up. What it has is auto-repeat: one press, then a gap
+// of about half a second, then twenty-five or thirty a second for as long as
+// you hold the key. A paddle moved by the key therefore sits still for that
+// half second however hard you lean on the arrow — long enough for a pong ball
+// to cross a third of the table — and then crosses the board in a blur. None of
+// that is the paddle being slow. It is the paddle being on the keyboard's clock
+// instead of the game's.
+//
+// And a step big enough to be worth those half-second gaps is a step you can
+// watch land. Breakout moved three columns per key, which at thirty repeats a
+// second is ninety columns a second delivered in visible three-column jumps:
+// the paddle teleports, most of its own width, several times a second.
+//
+// So a key does not move the paddle here. It buys movement, and the tick spends
+// it. A press adds `step` cells of debt; each tick pays out at most `rate` of
+// it. Held, the debt is refilled faster than it can ever be paid, so the paddle
+// runs at exactly `rate` — a constant speed, on the game's clock, for as long
+// as the key is down, and identical whether the terminal repeats at fifteen a
+// second or a hundred. Tapped, the debt is one `step` and the paddle glides
+// that far and stops.
+//
+// The debt is capped at a single press, which is what makes letting go stop the
+// paddle. Without the cap a held key would bank seconds of travel it had no
+// time to spend, and the paddle would sail on long after the ball had gone by —
+// the one thing worse than a paddle that will not start.
+//
+// The position stays a plain number on the game's state. Only the debt lives
+// here, so a game keeps `state.you` or `state.paddle` as the coordinate it
+// always was and a test can still put the paddle somewhere by assigning to it.
+
+// All of that is what a terminal that will not say when a key comes back up
+// leaves you with, and it is as good as that gets: the half-second before
+// auto-repeat starts is a half second in which the terminal has told us
+// nothing, and no paddle can be tuned out of a gap in its own input.
+//
+// A terminal that answers `HELD_KEYS.ask` (games.mjs) does say. There the
+// paddle is not paced by presses at all — `holdPaddle` puts it in gear and it
+// stays there, at exactly `rate`, until `releasePaddle` takes it out. No
+// repeat delay to sit through, no overrun to bound, and the same `rate` and the
+// same glide either way, so a game plays the same in both and simply answers
+// sooner in one.
+
+/** A paddle owing no movement. Games keep the position; this is the rest. */
+export const paddleMotion = () => ({ owed: 0, held: 0 });
+
+/**
+ * A key held down, where the terminal will tell us when it is let go.
+ *
+ * The debt is refilled every tick for as long as this is in gear, so it can
+ * never run out and the paddle simply runs at `rate`.
+ */
+export function holdPaddle(motion, dir) {
+  motion.held = dir;
+  return motion;
+}
+
+/**
+ * That key let go. `dir` is checked so that releasing the arrow you are no
+ * longer pressing cannot stop the one you are — rolling from one direction
+ * straight into the other sends the release for the first *after* the press for
+ * the second, and stopping on it would drop every reversal.
+ */
+export function releasePaddle(motion, dir) {
+  if (motion.held !== dir) return motion;
+  motion.held = 0;
+  motion.owed = 0;
+  return motion;
+}
+
+/**
+ * A press: `dir` is -1 or 1, `step` is how far one press is worth.
+ *
+ * Pressing the other way drops whatever is left of the old direction first, so
+ * a reversal starts the moment you ask for it rather than after the paddle has
+ * finished paying out the way it was already going. Getting that wrong costs a
+ * press, and a lost press on a paddle is a lost ball.
+ */
+export function pressPaddle(motion, dir, step) {
+  if (motion.owed * dir < 0) motion.owed = 0;
+  motion.owed = dir * Math.min(step, Math.abs(motion.owed) + step);
+  return motion;
+}
+
+/**
+ * Pay out this tick's share of the debt and return where the paddle now is.
+ *
+ * Called once per tick — and once more by a press that finds the paddle
+ * standing still, so that the frame drawn for that press already shows it
+ * moving. A tick away is only sixteen milliseconds, but starting on the frame
+ * you pressed is the difference between a control that answers and one that
+ * agrees to answer shortly. A press that finds the paddle already moving does
+ * not, because the tick is paying it out evenly and a second helping on top is
+ * exactly the jolt this is here to remove.
+ */
+export function glidePaddle(motion, at, { rate, step, lo, hi }) {
+  // A key that is being held owes a fresh press every tick, so the debt below
+  // never runs dry and the paddle just runs.
+  if (motion.held) motion.owed = motion.held * step;
+  if (!motion.owed) return at;
+  const move = Math.sign(motion.owed) * Math.min(rate, Math.abs(motion.owed));
+  motion.owed -= move;
+  const next = Math.min(hi, Math.max(lo, at + move));
+  // A paddle against the end of the board owes nothing. Left standing, the debt
+  // would sit there and then fire the instant you pressed the other way.
+  if (next === at) motion.owed = 0;
+  return next;
+}
+
+/**
+ * Cells per tick, from a speed written in cells per second.
+ *
+ * Paddle speeds are a feel, and a feel is in seconds. Writing them per tick
+ * would silently re-tune every one of them the next time a game changed how
+ * often it steps.
+ */
+export const perSecond = (cells, tickMs) => (cells * tickMs) / 1000;

package/src/games-pong.mjs

@@ -8,6 +8,7 @@
 // not. That is the whole game, and it is why the angle off the paddle depends on
 // where the ball hit it.
 import { advanceBall, drawnBall, drawnCell, snapBall } from "./games-draw.mjs";
+import { glidePaddle, holdPaddle, paddleMotion, perSecond, pressPaddle, releasePaddle } from "./games-paddle.mjs";
 import { acid, bone, danger, dim } from "./ui.mjs";
 
 export const WIDTH = 44;
@@ -64,10 +65,34 @@ const THEM_SPEED = 0.3 * SCALE;   // slow enough that a ball into the corner bea
 const FLAT = 0.08 * SCALE;        // below this a rally has gone flat
 const NUDGE = 0.12 * SCALE;       // and this is the angle it is put back at
 const MAX_VY = 0.5 * SCALE;
-const YOU_STEP = 1;               // a keypress, not a tick — the same either way
+
+/**
+ * Your paddle, which moves on this game's clock and not on the keyboard's.
+ *
+ * `YOU_RATE` is the speed the paddle actually travels at while you hold an
+ * arrow, in rows per second, so it says something about the game rather than
+ * about the rate the game happens to tick at. Twenty-one rows a second crosses
+ * the table's twelve in a little over half a second — comfortably faster than
+ * the ball falls, which is what makes a ball put into the corner a shot you
+ * lost rather than one you were never allowed to reach. The machine is left at
+ * ten rows a second and so is still beatable exactly where it always was.
+ *
+ * `YOU_STEP` is what one press is worth, and therefore also how far the paddle
+ * will still glide after you let go: nudging without holding moves a shade over
+ * a row, and a released paddle is done within a tenth of a second. See
+ * games-paddle.mjs for why a press buys movement instead of performing it.
+ */
+const YOU_RATE = perSecond(21, TICK_MS);
+const YOU_STEP = 1.2;             // rows one press is worth
 
 const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
 
+/** The table's ends, as far as your paddle is concerned. */
+const YOU_GLIDE = { rate: YOU_RATE, step: YOU_STEP, lo: 0, hi: HEIGHT - PADDLE };
+
+/** Which way an arrow moves your paddle, and 0 for a key that is not one. */
+const towards = (key) => (key === "up" ? -1 : key === "down" ? 1 : 0);
+
 /** A ball in the middle, heading at whoever just lost the point. */
 export function serve(state, toward) {
   state.ball = {
@@ -103,6 +128,9 @@ function returned(ball, top, dir) {
 
 /** One tick of rally. Exported so a test can play a whole match with no clock. */
 export function step(state) {
+  // Your paddle moves here, with everything else, rather than back in `onKey`.
+  state.you = glidePaddle(state.motion, state.you, YOU_GLIDE);
+
   const ball = state.ball;
   ball.x += ball.vx;
   ball.y += ball.vy;
@@ -151,10 +179,12 @@ export const PONG = {
   blurb: "first to seven, and the angle is all in where you hit it",
   keys: "↑ ↓ move · q quit",
   tickMs: TICK_MS,
+  heldKeys: true,   // worth asking the terminal for key releases — see games.mjs
 
   create({ rng = Math.random } = {}) {
     const state = {
       you: (HEIGHT - PADDLE) / 2,
+      motion: paddleMotion(),
       them: (HEIGHT - PADDLE) / 2,
       yours: 0,
       theirs: 0,
@@ -166,9 +196,28 @@ export const PONG = {
 
   tick: step,
 
-  onKey(state, key) {
-    if (key === "up") state.you = clamp(state.you - YOU_STEP, 0, HEIGHT - PADDLE);
-    if (key === "down") state.you = clamp(state.you + YOU_STEP, 0, HEIGHT - PADDLE);
+  onKey(state, key, ctx) {
+    const dir = towards(key);
+    if (!dir) return state;
+    // Told when the key comes back up, the paddle is simply put in gear and the
+    // tick does the rest — including for the auto-repeats that keep arriving
+    // while it is held, which must not be allowed to add a second helping of
+    // speed on top of the one the tick is already paying. See games-paddle.mjs.
+    if (ctx?.heldKeys) { holdPaddle(state.motion, dir); return state; }
+    // Not told, the paddle is paid for a press at a time. A press that finds it
+    // standing still is also spent immediately, so the frame this keypress
+    // draws is already one it has moved in; a press that finds it already
+    // moving is not, because the tick is paying it out evenly and a second
+    // helping on top would be the very jolt this is here to remove.
+    const resting = state.motion.owed === 0;
+    pressPaddle(state.motion, dir, YOU_STEP);
+    if (resting) state.you = glidePaddle(state.motion, state.you, YOU_GLIDE);
+    return state;
+  },
+
+  onRelease(state, key) {
+    const dir = towards(key);
+    if (dir) releasePaddle(state.motion, dir);
     return state;
   },
 

package/src/games.mjs

@@ -45,8 +45,14 @@ import { OUTRUN } from "./games-outrun.mjs";
  * @property {number|Function} [tickMs]  real-time games only — a number, or (state) => number
  * @property {boolean} [vim]     false when a game wants h/j/k/l as letters, not arrows
  * @property {boolean} [restartable]  false when `r` is only a restart once the game is over
+ * @property {boolean} [heldKeys] true for a game where a key is held rather than
+ *   tapped, which is worth asking the terminal for key releases for. See
+ *   `HELD_KEYS`; `ctx.heldKeys` then says whether it agreed.
  * @property {Function} create   ({ rng }) => state
- * @property {Function} onKey    (state, key, { rng }) => state
+ * @property {Function} onKey    (state, key, { rng, heldKeys }) => state
+ * @property {Function} [onRelease] (state, key, ctx) => state — that key let go,
+ *   and only in a terminal that reports it. Never the first thing a game hears
+ *   about a key, so it is only ever a reason to stop.
  * @property {Function} [tick]   (state, { rng }) => state
  * @property {Function} render   (state) => string[]   the board, already coloured
  * @property {Function} status   (state) => string     right of the title
@@ -112,6 +118,48 @@ export function frame({ title = "", status = "", rows = [], keys = "" } = {}) {
 
 /* --------------------------------------------------------------------- keys */
 
+const VIM_KEYS = { h: "left", j: "down", k: "up", l: "right" };
+
+/** Codepoints that are a named key rather than a character. */
+const NAMED_CODES = { 9: "tab", 13: "enter", 27: "escape", 32: "space", 127: "backspace" };
+
+/** A CSI sequence ends at the first byte in this range. */
+const isFinal = (c) => c >= "\x40" && c <= "\x7e";
+
+/**
+ * One CSI sequence → a key name, or null for one the arcade does not use.
+ *
+ * Two shapes arrive here. Arrows are `CSI A`..`CSI D`, as they have been
+ * forever. Everything from the keyboard protocol (see `HELD_KEYS` below) is
+ * `CSI code ; modifiers : event u` — a codepoint, which modifier keys were
+ * down, and whether the key was pressed, repeated or released. Both carry the
+ * event in the same place, so both are read the same way.
+ */
+function csiKey(params, final, vim) {
+  const fields = params.split(";");
+  const key = (fields[0] ?? "").split(":");
+  const mod = (fields[1] ?? "").split(":");
+  // Modifiers are sent as a bitmask plus one, so that an absent field and "no
+  // modifiers" are the same thing.
+  const modifiers = mod[0] ? Number.parseInt(mod[0], 10) - 1 : 0;
+  const event = mod[1] ? Number.parseInt(mod[1], 10) : 1;
+
+  let name = { A: "up", B: "down", C: "right", D: "left" }[final] ?? null;
+  if (!name && final === "u") {
+    const code = Number.parseInt(key[0], 10);
+    if (!Number.isFinite(code)) return null;
+    name = NAMED_CODES[code]
+      ?? (code >= 32 && code <= 126 ? String.fromCodePoint(code).toLowerCase() : null);
+  }
+  if (!name) return null;
+  // Ctrl-c and ctrl-d are a quit however they arrive.
+  if (modifiers & 4) return name === "c" || name === "d" ? "quit" : null;
+  if (vim && VIM_KEYS[name]) name = VIM_KEYS[name];
+  // 1 is a press, 2 a repeat — both are the key being down, which is all a game
+  // that does not care about releases ever sees. 3 is the key coming back up.
+  return event === 3 ? `release:${name}` : name;
+}
+
 /**
  * Raw terminal bytes → key names the games understand.
  *
@@ -119,6 +167,10 @@ export function frame({ title = "", status = "", rows = [], keys = "" } = {}) {
  * hold several keypresses (hold an arrow key down and they arrive in batches),
  * which is why this returns a list.
  *
+ * A key coming back up arrives as `release:up`, and only in a terminal that was
+ * asked for them and agreed — see `HELD_KEYS`. Games that do not implement
+ * `onRelease` never see one.
+ *
  * `vim: false` is for the games that read letters — hangman cannot ask for a
  * word with an `h` in it while `h` means left, and blackjack wants `h` to be
  * hit. Arrows are unaffected either way; they arrive as escape sequences.
@@ -129,12 +181,22 @@ export function decodeKeys(chunk, { vim = true } = {}) {
   for (let i = 0; i < input.length; i++) {
     const c = input[i];
     if (c === "\x1b") {
-      const seq = input.slice(i, i + 3);
-      const arrow = { "\x1b[A": "up", "\x1b[B": "down", "\x1b[C": "right", "\x1b[D": "left" }[seq];
-      if (arrow) { keys.push(arrow); i += 2; continue; }
-      // A bare escape is a quit everywhere in the arcade; a longer sequence we
-      // don't know (mouse, function key) is swallowed rather than misread.
-      if (input[i + 1] === "[" || input[i + 1] === "O") { i += 2; continue; }
+      const intro = input[i + 1];
+      if (intro === "[" || intro === "O") {
+        // Run to the end of the sequence and read it as a whole. Skipping a
+        // fixed two bytes instead — which is what this used to do — leaves the
+        // tail of anything longer than an arrow to be read as if it had been
+        // typed, so a mouse report or a terminal's answer to a question lands
+        // in the game as a fistful of letters.
+        let j = i + 2;
+        while (j < input.length && !isFinal(input[j])) j++;
+        // A sequence split across two chunks is dropped rather than half-read.
+        if (j >= input.length) break;
+        const key = csiKey(input.slice(i + 2, j), input[j], vim);
+        if (key) keys.push(key);
+        i = j;
+        continue;
+      }
       keys.push("escape");
       continue;
     }
@@ -145,7 +207,7 @@ export function decodeKeys(chunk, { vim = true } = {}) {
     if (c === "\t") { keys.push("tab"); continue; }
     // vim keys, everywhere, for free — every game that reads arrows gets them
     // without knowing about them. A game that reads letters opts out.
-    const vimKey = vim ? { h: "left", j: "down", k: "up", l: "right" }[c] : null;
+    const vimKey = vim ? VIM_KEYS[c] : null;
     if (vimKey) { keys.push(vimKey); continue; }
     if (c >= " " && c <= "~") keys.push(c.toLowerCase());
   }
@@ -197,6 +259,36 @@ const ESC = {
   eraseLine: "\x1b[K",
 };
 
+/**
+ * Asking the terminal to say when a key comes back up.
+ *
+ * A terminal does not report key releases. What it reports is auto-repeat: the
+ * press, then nothing for about half a second, then thirty a second until you
+ * let go. For a game where you hold a direction that half second is the whole
+ * problem — a pong paddle cannot start moving until the ball is a third of the
+ * way down the table, and no amount of making the paddle faster fixes it,
+ * because there is nothing to be fast about yet.
+ *
+ * The keyboard protocol fixes it properly: `HELD_KEYS.on` asks for keys to be
+ * reported as press, repeat and release, so a paddle can move for exactly as
+ * long as the key is down and stop the instant it is not.
+ *
+ * Not every terminal implements it, so it is asked for rather than assumed:
+ * `ask` is a question a terminal that supports it answers and one that does not
+ * ignores, and only an answer turns it on. That is what keeps this free of
+ * risk — a terminal that stays quiet is sent nothing and behaves exactly as it
+ * did before, and one that answers has told us it understands the sequences it
+ * is about to be sent.
+ */
+const HELD_KEYS = {
+  ask: "\x1b[?u",
+  answer: /\x1b\[\?[\d;]*u/,
+  on: "\x1b[>3u",   // disambiguate escape codes, and report press/repeat/release
+  off: "\x1b[<u",   // put back whatever the terminal had before
+  /** How long a terminal gets to answer before we take the silence as a no. */
+  waitMs: 60,
+};
+
 /**
  * How many ticks a late clock is allowed to make up in one go.
  *
@@ -332,11 +424,44 @@ export async function runGame(game, deps = {}) {
     arm();
   }
 
+  /**
+   * Ask the terminal whether it will report key releases, and wait briefly.
+   *
+   * Only for the games that can use them, and only on a real terminal — a test
+   * hands in a stream that will never answer, and waiting on it would put a
+   * timeout in front of every game in the suite.
+   *
+   * Anything the player typed while we were waiting is handed back rather than
+   * eaten, so that a key pressed the instant a game starts still counts.
+   */
+  const askForReleases = () => {
+    if (!game.heldKeys || !input.isTTY) return Promise.resolve({ held: false, typed: "" });
+    return new Promise((res) => {
+      let seen = "";
+      let settled = false;
+      const finish = (held) => {
+        if (settled) return;
+        settled = true;
+        clearTimer(waiting);
+        input.off?.("data", listen);
+        res({ held, typed: seen.replace(HELD_KEYS.answer, "") });
+      };
+      const listen = (chunk) => {
+        seen += String(chunk);
+        if (HELD_KEYS.answer.test(seen)) finish(true);
+      };
+      const waiting = setTimer(() => finish(false), HELD_KEYS.waitMs);
+      input.on?.("data", listen);
+      output.write(HELD_KEYS.ask);
+    });
+  };
+
   const wasRaw = Boolean(input.isRaw);
   const restore = () => {
     if (closed) return;
     closed = true;
     stop();
+    if (ctx.heldKeys) output.write(HELD_KEYS.off);
     output.write(ESC.showCursor);
     try { input.setRawMode?.(wasRaw); } catch { /* already gone */ }
     input.off?.("data", onData);
@@ -345,18 +470,34 @@ export async function runGame(game, deps = {}) {
   const onSignal = () => { restore(); process.exit(130); };
 
   function onData(chunk) {
+    // One chunk can carry several keypresses — holding an arrow down delivers
+    // them in batches — and every one of them is applied before anything is
+    // drawn. Drawing per key instead paints frames nobody can see: the batch is
+    // consumed in the same millisecond, so all but the last are overwritten
+    // before the terminal has finished with them, having cost a full frame
+    // build and a write each on the way past.
+    let moved = false;
     for (const key of decodeKeys(chunk, { vim: game.vim !== false })) {
+      // A key coming back up is not a move. It only ever tells a game to stop
+      // doing something, so it cannot start, restart or end one.
+      if (key.startsWith("release:")) {
+        if (game.onRelease && !state.over) {
+          state = game.onRelease(state, key.slice(8), ctx) || state;
+          moved = true;
+        }
+        continue;
+      }
       if (key === "quit" || key === "q" || key === "escape") { restore(); resolve(); return; }
       if (key === "r" && (state.over || game.restartable !== false)) {
         state = game.create(ctx);
         dueAt = null; // a new game starts its clock from now, not from the old one
-        draw();
+        moved = true;
         arm();
         continue;
       }
       if (state.over) continue; // a finished board takes r and q, nothing else
       state = game.onKey(state, key, ctx) || state;
-      draw();
+      moved = true;
       // A key can end a real-time game — a hard drop into the ceiling — so the
       // clock is stopped when that happens. Otherwise see `nudge`.
       if (game.tickMs) {
@@ -364,6 +505,7 @@ export async function runGame(game, deps = {}) {
         else nudge();
       }
     }
+    if (moved) draw();
   }
 
   let resolve;
@@ -373,12 +515,22 @@ export async function runGame(game, deps = {}) {
   try { input.setRawMode?.(true); } catch { /* not a tty */ }
   input.setEncoding?.("utf8");
   input.resume?.();
-  input.on?.("data", onData);
   process.on("SIGINT", onSignal);
   process.on("SIGTERM", onSignal);
 
+  // The board goes up before the terminal is asked anything, so that a game
+  // still starts instantly on a terminal that takes the full wait to not answer.
   draw();
-  arm();
+  const { held, typed } = await askForReleases();
+  // Quitting while the terminal was being asked leaves nothing to set up, and
+  // turning the protocol on now would leave it on with no game to turn it off.
+  if (!closed) {
+    ctx.heldKeys = held;
+    if (held) output.write(HELD_KEYS.on);
+    input.on?.("data", onData);
+    if (typed) onData(typed);
+    arm();
+  }
   await done;
   restore();
   process.off("SIGINT", onSignal);