wpmx 1.0.0

package/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+- **Run**: `bun run src/index.tsx`
+- **Run (hot reload)**: `bun --hot src/index.tsx`
+- **Install deps**: `bun install`
+- **Test**: `bun test` (uses `bun:test`, not jest/vitest)
+- **Type check**: `bunx tsc --noEmit`
+
+Always use Bun, never Node.js, npm, or npx.
+
+## Architecture
+
+wpmx is a terminal typing test built with React + [Ink](https://github.com/vadimdemedes/ink) (React renderer for CLIs).
+
+**Screen flow**: Menu → Game → Results → (restart or menu)
+
+- `src/app.tsx` — Screen state machine. Manages which screen is shown and passes callbacks between them.
+- `src/hooks/useGame.ts` — Core game engine. All typing logic lives here: character input, word validation, backspace, scoring (WPM/accuracy). Returns state + handlers consumed by Game component.
+- `src/components/Game.tsx` — Renders game UI and pipes keyboard input to useGame hooks. Handles character-by-character color feedback.
+- `src/lib/storage.ts` — Persists history and settings to `~/.wpmx/`. Uses `Bun.write` for saves, `node:fs` for reads.
+- `src/data/words.json` — Word list (~380 common English words).
+
+**Key game logic** (`useGame.ts`):
+- `handleChar` → records typed character in `charInputs[wordIndex]`
+- `handleSpace` → validates current word (exact match), marks correct/incorrect, advances to next word
+- `handleBackspace` → deletes last char, or returns to previous word if at start
+- `getResults` → calculates WPM and accuracy from `charInputs` vs target words
+
+**Scoring**: WPM = `(correctChars / 5) / (time / 60)`. Accuracy counts individual correct characters, not whole words.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 handxr (wpmx)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# wpmx
+
+A minimal, fast typing test for the terminal. Built with [Bun](https://bun.sh), [React](https://react.dev), and [Ink](https://github.com/vadimdemedes/ink).
+
+## Features
+
+- **15s, 30s, or 60s** timed sessions
+- **Live WPM** counter as you type
+- **Character-level feedback** — correct chars in green, errors in red
+- **Personal best** tracking with local history
+- **Vim-style navigation** — `h`/`l` to pick duration
+
+## Install
+
+```bash
+bun install
+```
+
+## Run
+
+```bash
+bun run src/index.tsx
+```
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `h` / `l` or `←` / `→` | Select duration |
+| `Enter` | Start game |
+| `Tab` | Restart |
+| `Esc` | Back to menu |
+| `q` | Quit |
+
+## How it works
+
+Type the words as fast as you can. Errors are highlighted per-character so you can see exactly what you missed. Your WPM and accuracy are calculated at the end.
+
+Results are saved locally at `~/.wpmx/history.json`.
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,117 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "typesprint",
+      "dependencies": {
+        "ink": "^6.8.0",
+        "react": "^19.2.4",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "@types/react": "^19.2.14",
+      },
+      "peerDependencies": {
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@alcalzone/ansi-tokenize": ["@alcalzone/ansi-tokenize@0.2.5", "", { "dependencies": { "ansi-styles": "^6.2.1", "is-fullwidth-code-point": "^5.0.0" } }, "sha512-3NX/MpTdroi0aKz134A6RC2Gb2iXVECN4QaAXnvCIxxIm3C3AVB1mkUe8NaaiyvOpDfsrqWhYtj+Q6a62RrTsw=="],
+
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.3.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A=="],
+
+    "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
+
+    "ansi-escapes": ["ansi-escapes@7.3.0", "", { "dependencies": { "environment": "^1.0.0" } }, "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg=="],
+
+    "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
+
+    "ansi-styles": ["ansi-styles@6.2.3", "", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
+
+    "auto-bind": ["auto-bind@5.0.1", "", {}, "sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
+
+    "cli-boxes": ["cli-boxes@3.0.0", "", {}, "sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g=="],
+
+    "cli-cursor": ["cli-cursor@4.0.0", "", { "dependencies": { "restore-cursor": "^4.0.0" } }, "sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg=="],
+
+    "cli-truncate": ["cli-truncate@5.1.1", "", { "dependencies": { "slice-ansi": "^7.1.0", "string-width": "^8.0.0" } }, "sha512-SroPvNHxUnk+vIW/dOSfNqdy1sPEFkrTk6TUtqLCnBlo3N7TNYYkzzN7uSD6+jVjrdO4+p8nH7JzH6cIvUem6A=="],
+
+    "code-excerpt": ["code-excerpt@4.0.0", "", { "dependencies": { "convert-to-spaces": "^2.0.1" } }, "sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA=="],
+
+    "convert-to-spaces": ["convert-to-spaces@2.0.1", "", {}, "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "emoji-regex": ["emoji-regex@10.6.0", "", {}, "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="],
+
+    "environment": ["environment@1.1.0", "", {}, "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q=="],
+
+    "es-toolkit": ["es-toolkit@1.44.0", "", {}, "sha512-6penXeZalaV88MM3cGkFZZfOoLGWshWWfdy0tWw/RlVVyhvMaWSBTOvXNeiW3e5FwdS5ePW0LGEu17zT139ktg=="],
+
+    "escape-string-regexp": ["escape-string-regexp@2.0.0", "", {}, "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w=="],
+
+    "get-east-asian-width": ["get-east-asian-width@1.5.0", "", {}, "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA=="],
+
+    "indent-string": ["indent-string@5.0.0", "", {}, "sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg=="],
+
+    "ink": ["ink@6.8.0", "", { "dependencies": { "@alcalzone/ansi-tokenize": "^0.2.4", "ansi-escapes": "^7.3.0", "ansi-styles": "^6.2.1", "auto-bind": "^5.0.1", "chalk": "^5.6.0", "cli-boxes": "^3.0.0", "cli-cursor": "^4.0.0", "cli-truncate": "^5.1.1", "code-excerpt": "^4.0.0", "es-toolkit": "^1.39.10", "indent-string": "^5.0.0", "is-in-ci": "^2.0.0", "patch-console": "^2.0.0", "react-reconciler": "^0.33.0", "scheduler": "^0.27.0", "signal-exit": "^3.0.7", "slice-ansi": "^8.0.0", "stack-utils": "^2.0.6", "string-width": "^8.1.1", "terminal-size": "^4.0.1", "type-fest": "^5.4.1", "widest-line": "^6.0.0", "wrap-ansi": "^9.0.0", "ws": "^8.18.0", "yoga-layout": "~3.2.1" }, "peerDependencies": { "@types/react": ">=19.0.0", "react": ">=19.0.0", "react-devtools-core": ">=6.1.2" }, "optionalPeers": ["@types/react", "react-devtools-core"] }, "sha512-sbl1RdLOgkO9isK42WCZlJCFN9hb++sX9dsklOvfd1YQ3bQ2AiFu12Q6tFlr0HvEUvzraJntQCCpfEoUe9DSzA=="],
+
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@5.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.1" } }, "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ=="],
+
+    "is-in-ci": ["is-in-ci@2.0.0", "", { "bin": { "is-in-ci": "cli.js" } }, "sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w=="],
+
+    "mimic-fn": ["mimic-fn@2.1.0", "", {}, "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg=="],
+
+    "onetime": ["onetime@5.1.2", "", { "dependencies": { "mimic-fn": "^2.1.0" } }, "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg=="],
+
+    "patch-console": ["patch-console@2.0.0", "", {}, "sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA=="],
+
+    "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
+
+    "react-reconciler": ["react-reconciler@0.33.0", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.0" } }, "sha512-KetWRytFv1epdpJc3J4G75I4WrplZE5jOL7Yq0p34+OVOKF4Se7WrdIdVC45XsSSmUTlht2FM/fM1FZb1mfQeA=="],
+
+    "restore-cursor": ["restore-cursor@4.0.0", "", { "dependencies": { "onetime": "^5.1.0", "signal-exit": "^3.0.2" } }, "sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg=="],
+
+    "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
+
+    "signal-exit": ["signal-exit@3.0.7", "", {}, "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ=="],
+
+    "slice-ansi": ["slice-ansi@8.0.0", "", { "dependencies": { "ansi-styles": "^6.2.3", "is-fullwidth-code-point": "^5.1.0" } }, "sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg=="],
+
+    "stack-utils": ["stack-utils@2.0.6", "", { "dependencies": { "escape-string-regexp": "^2.0.0" } }, "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ=="],
+
+    "string-width": ["string-width@8.2.0", "", { "dependencies": { "get-east-asian-width": "^1.5.0", "strip-ansi": "^7.1.2" } }, "sha512-6hJPQ8N0V0P3SNmP6h2J99RLuzrWz2gvT7VnK5tKvrNqJoyS9W4/Fb8mo31UiPvy00z7DQXkP2hnKBVav76thw=="],
+
+    "strip-ansi": ["strip-ansi@7.1.2", "", { "dependencies": { "ansi-regex": "^6.0.1" } }, "sha512-gmBGslpoQJtgnMAvOVqGZpEz9dyoKTCzy2nfz/n8aIFhN/jCE/rCmcxabB6jOOHV+0WNnylOxaxBQPSvcWklhA=="],
+
+    "tagged-tag": ["tagged-tag@1.0.0", "", {}, "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng=="],
+
+    "terminal-size": ["terminal-size@4.0.1", "", {}, "sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ=="],
+
+    "type-fest": ["type-fest@5.4.4", "", { "dependencies": { "tagged-tag": "^1.0.0" } }, "sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+
+    "widest-line": ["widest-line@6.0.0", "", { "dependencies": { "string-width": "^8.1.0" } }, "sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA=="],
+
+    "wrap-ansi": ["wrap-ansi@9.0.2", "", { "dependencies": { "ansi-styles": "^6.2.1", "string-width": "^7.0.0", "strip-ansi": "^7.1.0" } }, "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww=="],
+
+    "ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+
+    "yoga-layout": ["yoga-layout@3.2.1", "", {}, "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ=="],
+
+    "cli-truncate/slice-ansi": ["slice-ansi@7.1.2", "", { "dependencies": { "ansi-styles": "^6.2.1", "is-fullwidth-code-point": "^5.0.0" } }, "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w=="],
+
+    "wrap-ansi/string-width": ["string-width@7.2.0", "", { "dependencies": { "emoji-regex": "^10.3.0", "get-east-asian-width": "^1.0.0", "strip-ansi": "^7.1.0" } }, "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "wpmx",
+  "version": "1.0.0",
+  "description": "A minimal, fast typing test for the terminal",
+  "type": "module",
+  "bin": {
+    "wpmx": "src/index.tsx"
+  },
+  "keywords": [
+    "typing",
+    "typing-test",
+    "wpm",
+    "terminal",
+    "cli",
+    "speed-typing"
+  ],
+  "author": "handxr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/handxr/wpmx"
+  },
+  "homepage": "https://github.com/handxr/wpmx",
+  "bugs": {
+    "url": "https://github.com/handxr/wpmx/issues"
+  },
+  "dependencies": {
+    "ink": "^6.8.0",
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/app.tsx

@@ -0,0 +1,90 @@
+import { useState, useCallback } from "react";
+import { useApp } from "ink";
+import { Menu } from "./components/Menu.tsx";
+import { Game } from "./components/Game.tsx";
+import { Results } from "./components/Results.tsx";
+import {
+  saveResult,
+  saveSettings,
+  loadSettings,
+  getPersonalBest,
+} from "./lib/storage.ts";
+
+type Screen = "menu" | "game" | "results";
+type Duration = 15 | 30 | 60;
+
+export type GameResults = {
+  wpm: number;
+  accuracy: number;
+  time: number;
+};
+
+export function App() {
+  const { exit } = useApp();
+  const settings = loadSettings();
+  const [screen, setScreen] = useState<Screen>("menu");
+  const [duration, setDuration] = useState<Duration>(settings.lastDuration);
+  const [results, setResults] = useState<GameResults | null>(null);
+  const [gameKey, setGameKey] = useState(0);
+
+  const handleStart = useCallback((d: Duration) => {
+    setDuration(d);
+    saveSettings({ lastDuration: d });
+    setGameKey((k) => k + 1);
+    setScreen("game");
+  }, []);
+
+  const handleFinish = useCallback(
+    (r: GameResults) => {
+      saveResult({
+        wpm: r.wpm,
+        accuracy: r.accuracy,
+        duration: r.time,
+        date: new Date().toISOString(),
+      });
+      setResults(r);
+      setScreen("results");
+    },
+    []
+  );
+
+  const handleRestart = useCallback(() => {
+    setGameKey((k) => k + 1);
+    setScreen("game");
+  }, []);
+
+  const handleMenu = useCallback(() => {
+    setScreen("menu");
+  }, []);
+
+  if (screen === "menu") {
+    return <Menu onStart={handleStart} onQuit={exit} defaultDuration={duration} />;
+  }
+
+  if (screen === "game") {
+    return (
+      <Game
+        key={gameKey}
+        duration={duration}
+        onFinish={handleFinish}
+        onExit={handleMenu}
+        onRestart={handleRestart}
+      />
+    );
+  }
+
+  if (screen === "results" && results) {
+    const pb = getPersonalBest(results.time);
+    return (
+      <Results
+        results={results}
+        personalBest={pb}
+        onRestart={handleRestart}
+        onMenu={handleMenu}
+        onQuit={exit}
+      />
+    );
+  }
+
+  return null;
+}

package/src/components/Game.tsx

@@ -0,0 +1,156 @@
+import { Box, Text, useInput } from "ink";
+import { useGame, type GameResults } from "../hooks/useGame.ts";
+import { useEffect } from "react";
+
+type GameProps = {
+  duration: number;
+  onFinish: (results: GameResults) => void;
+  onExit: () => void;
+  onRestart: () => void;
+};
+
+export function Game({ duration, onFinish, onExit, onRestart }: GameProps) {
+  const game = useGame(duration);
+
+  useEffect(() => {
+    if (game.isFinished) {
+      onFinish(game.getResults());
+    }
+  }, [game.isFinished]);
+
+  useInput((input, key) => {
+    if (key.escape) {
+      onExit();
+      return;
+    }
+    if (key.tab) {
+      onRestart();
+      return;
+    }
+    if (game.isFinished) return;
+
+    if (key.backspace || key.delete) {
+      game.handleBackspace();
+    } else if (input === " ") {
+      game.handleSpace();
+    } else if (input && !key.ctrl && !key.meta && input.length === 1) {
+      game.handleChar(input);
+    }
+  });
+
+  const liveWpm = game.isRunning && !game.isFinished
+    ? Math.round(
+        (() => {
+          let correct = 0;
+          for (let i = 0; i < game.currentWordIndex; i++) {
+            const word = game.words[i];
+            const input = game.charInputs[i].join("");
+            if (input === word) correct += word.length + 1;
+            else {
+              for (let j = 0; j < word.length; j++) {
+                if (input[j] === word[j]) correct++;
+              }
+            }
+          }
+          const elapsed = (duration - game.timeLeft) || 1;
+          return (correct / 5) / (elapsed / 60);
+        })()
+      )
+    : 0;
+
+  return (
+    <Box flexDirection="column" paddingX={2} paddingY={1}>
+      <Box justifyContent="space-between">
+        <Text color="yellow" bold>
+          {game.timeLeft}s
+        </Text>
+        <Text color="yellow" bold>
+          {liveWpm} wpm
+        </Text>
+      </Box>
+      <Box marginTop={1} flexWrap="wrap">
+        {game.words.slice(0, Math.min(game.words.length, game.currentWordIndex + 30)).map((word, wordIndex) => {
+          const isCurrentWord = wordIndex === game.currentWordIndex;
+          const isPast = wordIndex < game.currentWordIndex;
+          const wordResult = game.wordResults[wordIndex];
+
+          if (isPast) {
+            const inputChars = game.charInputs[wordIndex];
+            return (
+              <Box key={wordIndex} marginRight={1}>
+                {word.split("").map((char, charIndex) => {
+                  const inputChar = inputChars[charIndex];
+                  const isCorrect = inputChar === char;
+                  return (
+                    <Text key={charIndex} color={isCorrect ? "green" : "red"}>
+                      {char}
+                    </Text>
+                  );
+                })}
+                {inputChars.length > word.length &&
+                  inputChars
+                    .slice(word.length)
+                    .map((char, i) => (
+                      <Text key={`extra-${i}`} color="red" strikethrough>
+                        {char}
+                      </Text>
+                    ))}
+              </Box>
+            );
+          }
+
+          if (isCurrentWord) {
+            return (
+              <Box key={wordIndex} marginRight={1}>
+                {word.split("").map((char, charIndex) => {
+                  const inputChar = game.currentInput[charIndex];
+                  if (inputChar === undefined && charIndex === game.currentInput.length) {
+                    return (
+                      <Text key={charIndex} color="white" bold underline>
+                        {char}
+                      </Text>
+                    );
+                  }
+                  if (inputChar === undefined) {
+                    return (
+                      <Text key={charIndex} dimColor>
+                        {char}
+                      </Text>
+                    );
+                  }
+                  if (inputChar === char) {
+                    return (
+                      <Text key={charIndex} color="green">
+                        {char}
+                      </Text>
+                    );
+                  }
+                  return (
+                    <Text key={charIndex} color="red">
+                      {char}
+                    </Text>
+                  );
+                })}
+                {game.currentInput.length > word.length &&
+                  game.currentInput
+                    .slice(word.length)
+                    .split("")
+                    .map((char, i) => (
+                      <Text key={`extra-${i}`} color="red">
+                        {char}
+                      </Text>
+                    ))}
+              </Box>
+            );
+          }
+
+          return (
+            <Box key={wordIndex} marginRight={1}>
+              <Text dimColor>{word}</Text>
+            </Box>
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}

package/src/components/Menu.tsx

@@ -0,0 +1,67 @@
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+
+type Duration = 15 | 30 | 60;
+const DURATIONS: Duration[] = [15, 30, 60];
+
+type MenuProps = {
+  onStart: (duration: Duration) => void;
+  onQuit: () => void;
+  defaultDuration: Duration;
+};
+
+export function Menu({ onStart, onQuit, defaultDuration }: MenuProps) {
+  const [selectedIndex, setSelectedIndex] = useState(
+    DURATIONS.indexOf(defaultDuration)
+  );
+
+  useInput((input, key) => {
+    if (input === "q") {
+      onQuit();
+    } else if (key.leftArrow || input === "h") {
+      setSelectedIndex((prev) => Math.max(0, prev - 1));
+    } else if (key.rightArrow || input === "l") {
+      setSelectedIndex((prev) => Math.min(DURATIONS.length - 1, prev + 1));
+    } else if (key.return) {
+      onStart(DURATIONS[selectedIndex]);
+    }
+  });
+
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={2}>
+      <Text bold color="yellow">
+        wpmx
+      </Text>
+
+      <Box marginTop={2} gap={2}>
+        {DURATIONS.map((d, i) => (
+          <Text
+            key={d}
+            bold={i === selectedIndex}
+            color={i === selectedIndex ? "white" : "gray"}
+            underline={i === selectedIndex}
+          >
+            {d}s
+          </Text>
+        ))}
+      </Box>
+
+      <Box marginTop={1}>
+        <Text dimColor>h / l or ← / → to choose, Enter to start</Text>
+      </Box>
+
+      <Box flexDirection="column" marginTop={2} gap={0}>
+        <Text dimColor>─── keys ───</Text>
+        <Text dimColor>
+          <Text color="gray">Tab</Text>    restart game
+        </Text>
+        <Text dimColor>
+          <Text color="gray">Esc</Text>    back to menu
+        </Text>
+        <Text dimColor>
+          <Text color="gray">q</Text>      quit
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/src/components/Results.tsx

@@ -0,0 +1,58 @@
+import { Box, Text, useInput } from "ink";
+import type { GameResults } from "../hooks/useGame.ts";
+
+type ResultsProps = {
+  results: GameResults;
+  personalBest: number | null;
+  onRestart: () => void;
+  onMenu: () => void;
+  onQuit: () => void;
+};
+
+export function Results({
+  results,
+  personalBest,
+  onRestart,
+  onMenu,
+  onQuit,
+}: ResultsProps) {
+  useInput((input, key) => {
+    if (key.tab) {
+      onRestart();
+    } else if (key.escape) {
+      onMenu();
+    } else if (input === "q") {
+      onQuit();
+    }
+  });
+
+  const isNewPB = personalBest !== null && results.wpm >= personalBest;
+
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={2}>
+      <Text bold color="yellow">
+        wpmx
+      </Text>
+      <Box flexDirection="column" alignItems="center" marginTop={2} gap={0}>
+        <Text bold color="white">
+          {results.wpm} wpm
+        </Text>
+        {isNewPB && (
+          <Text color="greenBright" bold>
+            new personal best!
+          </Text>
+        )}
+        {personalBest !== null && !isNewPB && (
+          <Text dimColor>pb: {personalBest} wpm</Text>
+        )}
+        <Text color="white">{results.accuracy}% accuracy</Text>
+        <Text dimColor>{results.time}s</Text>
+      </Box>
+      <Box marginTop={2} gap={2}>
+        <Text dimColor>Tab → restart</Text>
+        <Text dimColor>Esc → menu</Text>
+        <Text dimColor>q → quit</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/data/words.json

@@ -0,0 +1,384 @@
+[
+  "the",
+  "be",
+  "to",
+  "of",
+  "and",
+  "a",
+  "in",
+  "that",
+  "have",
+  "i",
+  "it",
+  "for",
+  "not",
+  "on",
+  "with",
+  "he",
+  "as",
+  "you",
+  "do",
+  "at",
+  "this",
+  "but",
+  "his",
+  "by",
+  "from",
+  "they",
+  "we",
+  "say",
+  "her",
+  "she",
+  "or",
+  "an",
+  "will",
+  "my",
+  "one",
+  "all",
+  "would",
+  "there",
+  "their",
+  "what",
+  "so",
+  "up",
+  "out",
+  "if",
+  "about",
+  "who",
+  "get",
+  "which",
+  "go",
+  "me",
+  "when",
+  "make",
+  "can",
+  "like",
+  "time",
+  "no",
+  "just",
+  "him",
+  "know",
+  "take",
+  "people",
+  "into",
+  "year",
+  "your",
+  "good",
+  "some",
+  "could",
+  "them",
+  "see",
+  "other",
+  "than",
+  "then",
+  "now",
+  "look",
+  "only",
+  "come",
+  "its",
+  "over",
+  "think",
+  "also",
+  "back",
+  "after",
+  "use",
+  "two",
+  "how",
+  "our",
+  "work",
+  "first",
+  "well",
+  "way",
+  "even",
+  "new",
+  "want",
+  "because",
+  "any",
+  "these",
+  "give",
+  "day",
+  "most",
+  "us",
+  "great",
+  "between",
+  "need",
+  "large",
+  "under",
+  "never",
+  "each",
+  "right",
+  "hand",
+  "high",
+  "place",
+  "very",
+  "through",
+  "where",
+  "much",
+  "before",
+  "line",
+  "too",
+  "mean",
+  "old",
+  "same",
+  "tell",
+  "boy",
+  "did",
+  "three",
+  "long",
+  "small",
+  "read",
+  "run",
+  "keep",
+  "house",
+  "while",
+  "last",
+  "might",
+  "still",
+  "found",
+  "live",
+  "world",
+  "head",
+  "stand",
+  "own",
+  "page",
+  "should",
+  "city",
+  "tree",
+  "cross",
+  "hard",
+  "start",
+  "story",
+  "far",
+  "play",
+  "left",
+  "end",
+  "home",
+  "move",
+  "try",
+  "night",
+  "close",
+  "why",
+  "ask",
+  "men",
+  "change",
+  "went",
+  "light",
+  "kind",
+  "off",
+  "point",
+  "turn",
+  "real",
+  "leave",
+  "help",
+  "show",
+  "thought",
+  "name",
+  "every",
+  "open",
+  "seem",
+  "together",
+  "next",
+  "white",
+  "children",
+  "begin",
+  "walk",
+  "example",
+  "paper",
+  "group",
+  "always",
+  "music",
+  "those",
+  "both",
+  "often",
+  "letter",
+  "until",
+  "mile",
+  "river",
+  "car",
+  "feet",
+  "care",
+  "second",
+  "enough",
+  "plant",
+  "food",
+  "add",
+  "almost",
+  "family",
+  "young",
+  "important",
+  "school",
+  "body",
+  "side",
+  "something",
+  "life",
+  "water",
+  "mother",
+  "area",
+  "money",
+  "number",
+  "again",
+  "part",
+  "state",
+  "below",
+  "learn",
+  "country",
+  "build",
+  "eye",
+  "miss",
+  "hold",
+  "above",
+  "book",
+  "hear",
+  "horse",
+  "face",
+  "door",
+  "sure",
+  "become",
+  "girl",
+  "study",
+  "system",
+  "early",
+  "air",
+  "carry",
+  "eat",
+  "room",
+  "friend",
+  "power",
+  "question",
+  "answer",
+  "fish",
+  "mountain",
+  "stop",
+  "once",
+  "base",
+  "idea",
+  "fact",
+  "four",
+  "cut",
+  "grow",
+  "earth",
+  "color",
+  "class",
+  "main",
+  "space",
+  "problem",
+  "rest",
+  "along",
+  "best",
+  "better",
+  "nothing",
+  "plan",
+  "free",
+  "test",
+  "table",
+  "half",
+  "order",
+  "fire",
+  "south",
+  "top",
+  "cover",
+  "usually",
+  "warm",
+  "fall",
+  "note",
+  "voice",
+  "sit",
+  "common",
+  "strong",
+  "town",
+  "fine",
+  "certain",
+  "fly",
+  "lead",
+  "cry",
+  "dark",
+  "machine",
+  "whole",
+  "dog",
+  "box",
+  "bit",
+  "bring",
+  "word",
+  "red",
+  "able",
+  "road",
+  "yet",
+  "ten",
+  "land",
+  "rather",
+  "short",
+  "black",
+  "draw",
+  "happen",
+  "watch",
+  "front",
+  "easy",
+  "product",
+  "green",
+  "ready",
+  "toward",
+  "island",
+  "record",
+  "true",
+  "during",
+  "hundred",
+  "morning",
+  "several",
+  "clear",
+  "travel",
+  "less",
+  "simple",
+  "few",
+  "cold",
+  "step",
+  "total",
+  "round",
+  "may",
+  "late",
+  "boat",
+  "war",
+  "ground",
+  "field",
+  "rock",
+  "street",
+  "wind",
+  "ship",
+  "figure",
+  "piece",
+  "ago",
+  "today",
+  "drive",
+  "list",
+  "done",
+  "set",
+  "love",
+  "deep",
+  "inch",
+  "write",
+  "rule",
+  "gun",
+  "remember",
+  "forest",
+  "check",
+  "game",
+  "shape",
+  "yes",
+  "hot",
+  "brought",
+  "heat",
+  "snow",
+  "fast",
+  "five",
+  "bed",
+  "spend",
+  "sing",
+  "listen",
+  "six",
+  "size",
+  "wild",
+  "mark",
+  "west",
+  "north",
+  "east",
+  "past"
+]

package/src/hooks/useGame.ts

@@ -0,0 +1,180 @@
+import { useState, useCallback, useEffect, useRef } from "react";
+import words from "../data/words.json";
+
+export type GameState = {
+  words: string[];
+  currentWordIndex: number;
+  currentInput: string;
+  timeLeft: number;
+  isRunning: boolean;
+  isFinished: boolean;
+  wordResults: Array<"correct" | "incorrect" | "pending">;
+  charInputs: string[][];
+};
+
+export type GameResults = {
+  wpm: number;
+  accuracy: number;
+  time: number;
+};
+
+function generateWords(count: number): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < count; i++) {
+    result.push(words[Math.floor(Math.random() * words.length)]);
+  }
+  return result;
+}
+
+export function useGame(duration: number) {
+  const wordCount = Math.max(duration * 3, 50);
+  const [state, setState] = useState<GameState>({
+    words: generateWords(wordCount),
+    currentWordIndex: 0,
+    currentInput: "",
+    timeLeft: duration,
+    isRunning: false,
+    isFinished: false,
+    wordResults: Array(wordCount).fill("pending"),
+    charInputs: Array(wordCount).fill(null).map(() => []),
+  });
+
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const startTimeRef = useRef<number>(0);
+
+  useEffect(() => {
+    if (state.isRunning && !state.isFinished) {
+      timerRef.current = setInterval(() => {
+        setState((prev) => {
+          const newTimeLeft = prev.timeLeft - 1;
+          if (newTimeLeft <= 0) {
+            if (timerRef.current) clearInterval(timerRef.current);
+            return { ...prev, timeLeft: 0, isRunning: false, isFinished: true };
+          }
+          return { ...prev, timeLeft: newTimeLeft };
+        });
+      }, 1000);
+    }
+    return () => {
+      if (timerRef.current) clearInterval(timerRef.current);
+    };
+  }, [state.isRunning, state.isFinished]);
+
+  const startGame = useCallback(() => {
+    startTimeRef.current = Date.now();
+    setState((prev) => ({ ...prev, isRunning: true }));
+  }, []);
+
+  const handleChar = useCallback((char: string) => {
+    setState((prev) => {
+      if (prev.isFinished) return prev;
+      if (!prev.isRunning) {
+        startTimeRef.current = Date.now();
+        const newCharInputs = [...prev.charInputs];
+        newCharInputs[prev.currentWordIndex] = [
+          ...newCharInputs[prev.currentWordIndex],
+          char,
+        ];
+        return {
+          ...prev,
+          isRunning: true,
+          currentInput: prev.currentInput + char,
+          charInputs: newCharInputs,
+        };
+      }
+      const newCharInputs = [...prev.charInputs];
+      newCharInputs[prev.currentWordIndex] = [
+        ...newCharInputs[prev.currentWordIndex],
+        char,
+      ];
+      return {
+        ...prev,
+        currentInput: prev.currentInput + char,
+        charInputs: newCharInputs,
+      };
+    });
+  }, []);
+
+  const handleBackspace = useCallback(() => {
+    setState((prev) => {
+      if (prev.isFinished) return prev;
+
+      // If current input is empty, go back to previous word
+      if (prev.currentInput.length === 0) {
+        if (prev.currentWordIndex === 0) return prev;
+        const prevIndex = prev.currentWordIndex - 1;
+        const prevInput = prev.charInputs[prevIndex].join("");
+        const newWordResults = [...prev.wordResults];
+        newWordResults[prevIndex] = "pending";
+        return {
+          ...prev,
+          currentWordIndex: prevIndex,
+          currentInput: prevInput,
+          wordResults: newWordResults,
+        };
+      }
+
+      // Otherwise delete last char of current word
+      const newCharInputs = [...prev.charInputs];
+      newCharInputs[prev.currentWordIndex] = newCharInputs[
+        prev.currentWordIndex
+      ].slice(0, -1);
+      return {
+        ...prev,
+        currentInput: prev.currentInput.slice(0, -1),
+        charInputs: newCharInputs,
+      };
+    });
+  }, []);
+
+  const handleSpace = useCallback(() => {
+    setState((prev) => {
+      if (prev.isFinished || !prev.isRunning) return prev;
+      const word = prev.words[prev.currentWordIndex];
+      const isCorrect = prev.currentInput === word;
+      const newWordResults = [...prev.wordResults];
+      newWordResults[prev.currentWordIndex] = isCorrect
+        ? "correct"
+        : "incorrect";
+      return {
+        ...prev,
+        currentWordIndex: prev.currentWordIndex + 1,
+        currentInput: "",
+        wordResults: newWordResults,
+      };
+    });
+  }, []);
+
+  const getResults = useCallback((): GameResults => {
+    let correctChars = 0;
+    let totalChars = 0;
+
+    for (let i = 0; i < state.currentWordIndex; i++) {
+      const word = state.words[i];
+      const input = state.charInputs[i].join("");
+      totalChars += Math.max(word.length, input.length) + 1;
+      if (input === word) {
+        correctChars += word.length + 1;
+      } else {
+        for (let j = 0; j < word.length; j++) {
+          if (input[j] === word[j]) correctChars++;
+        }
+      }
+    }
+
+    const timeElapsed = duration;
+    const wpm = totalChars > 0 ? Math.round((correctChars / 5) / (timeElapsed / 60)) : 0;
+    const accuracy = totalChars > 0 ? Math.round((correctChars / totalChars) * 1000) / 10 : 0;
+
+    return { wpm, accuracy, time: duration };
+  }, [state.currentWordIndex, state.charInputs, state.words, duration]);
+
+  return {
+    ...state,
+    startGame,
+    handleChar,
+    handleBackspace,
+    handleSpace,
+    getResults,
+  };
+}

package/src/index.tsx

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { render } from "ink";
+import { App } from "./app.tsx";
+
+render(<App />);

package/src/lib/storage.ts

@@ -0,0 +1,59 @@
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, existsSync } from "fs";
+
+const DIR = join(homedir(), ".wpmx");
+const HISTORY_PATH = join(DIR, "history.json");
+const SETTINGS_PATH = join(DIR, "settings.json");
+
+function ensureDir() {
+  if (!existsSync(DIR)) {
+    mkdirSync(DIR, { recursive: true });
+  }
+}
+
+function readJSON<T>(path: string, fallback: T): T {
+  try {
+    if (!existsSync(path)) return fallback;
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export type HistoryEntry = {
+  wpm: number;
+  accuracy: number;
+  duration: number;
+  date: string;
+};
+
+export type Settings = {
+  lastDuration: 15 | 30 | 60;
+};
+
+export function getHistory(): HistoryEntry[] {
+  return readJSON<HistoryEntry[]>(HISTORY_PATH, []);
+}
+
+export function saveResult(entry: HistoryEntry): void {
+  ensureDir();
+  const history = getHistory();
+  history.push(entry);
+  Bun.write(HISTORY_PATH, JSON.stringify(history, null, 2));
+}
+
+export function getPersonalBest(duration: number): number | null {
+  const history = getHistory().filter((e) => e.duration === duration);
+  if (history.length === 0) return null;
+  return Math.max(...history.map((e) => e.wpm));
+}
+
+export function loadSettings(): Settings {
+  return readJSON<Settings>(SETTINGS_PATH, { lastDuration: 30 });
+}
+
+export function saveSettings(settings: Settings): void {
+  ensureDir();
+  Bun.write(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}