typefaster-cli 0.2.0__tar.gz → 0.3.1__tar.gz

typefaster_cli-0.3.1/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Every change requests a review from the project owner by default.
+# https://docs.github.com/articles/about-code-owners
+*       @Anoshor

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -43,7 +43,7 @@ jobs:
 
       - name: Upload coverage artifact
         if: matrix.python-version == '3.12'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage
           path: coverage.xml
@@ -52,8 +52,8 @@ jobs:
     name: server lint · test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -70,8 +70,8 @@ jobs:
     name: dependency audit (pip-audit)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -86,14 +86,14 @@ jobs:
     runs-on: ubuntu-latest
     needs: [quality, server]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
       - run: python -m pip install build
       - run: python -m build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/*

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/.github/workflows/codeql.yml

@@ -16,8 +16,8 @@ jobs:
       actions: read
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: github/codeql-action/init@v3
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
         with:
           languages: python
-      - uses: github/codeql-action/analyze@v3
+      - uses: github/codeql-action/analyze@v4

typefaster_cli-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,145 @@
+name: Release
+
+# Publishes to PyPI and creates a GitHub Release whenever you push a version tag
+# (e.g. `git tag v0.1.0 && git push origin v0.1.0`).
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API tokens stored in the repo. You
+# must configure the trusted publisher once on PyPI (see docs/RELEASING.md).
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write   # create the GitHub Release
+  id-token: write   # OIDC token for PyPI Trusted Publishing
+  packages: write   # push the server image to GHCR
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build            # creates dist/*.whl and dist/*.tar.gz
+      - run: python -m pip install twine && twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # optional: add manual approval in repo settings
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  bump-homebrew:
+    name: bump Homebrew tap formula
+    needs: publish-pypi          # only bump once the sdist is live on PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the tap repo
+        uses: actions/checkout@v7
+        with:
+          repository: Anoshor/homebrew-typefaster
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}   # fine-grained PAT, contents:write on the tap
+          path: tap
+
+      - name: Update url + sha256 from PyPI
+        env:
+          VERSION: ${{ github.ref_name }}            # e.g. v0.2.1
+        run: |
+          python3 - <<'PY'
+          import json, os, re, sys, time, urllib.request
+
+          version = os.environ["VERSION"].lstrip("v")
+          api = f"https://pypi.org/pypi/typefaster-cli/{version}/json"
+
+          # PyPI's JSON index can lag a few seconds behind the upload; retry.
+          data = None
+          for attempt in range(10):
+              try:
+                  with urllib.request.urlopen(api) as r:
+                      data = json.load(r)
+                  break
+              except Exception as e:                  # noqa: BLE001
+                  print(f"attempt {attempt+1}: {e}; retrying in 6s")
+                  time.sleep(6)
+          if data is None:
+              sys.exit(f"could not fetch {api}")
+
+          sdist = next(u for u in data["urls"] if u["packagetype"] == "sdist")
+          url, sha = sdist["url"], sdist["digests"]["sha256"]
+          print(f"new url:  {url}\nnew sha:  {sha}")
+
+          path = "tap/Formula/typefaster.rb"
+          text = open(path, encoding="utf-8").read()
+          # Only touch the top-level url/sha256 (everything before the first resource).
+          head, sep, rest = text.partition("\n  resource ")
+          head = re.sub(r'url "[^"]*"', f'url "{url}"', head, count=1)
+          head = re.sub(r'sha256 "[^"]*"', f'sha256 "{sha}"', head, count=1)
+          open(path, "w", encoding="utf-8").write(head + sep + rest)
+          PY
+
+      - name: Commit & push the bump
+        working-directory: tap
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet; then
+            echo "Formula already up to date — nothing to bump."
+            exit 0
+          fi
+          git add Formula/typefaster.rb
+          git commit -m "typefaster ${VERSION#v}"
+          git push
+
+  server-image:
+    name: build & push server image (GHCR)
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/typefaster-server
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: server/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

typefaster_cli-0.3.1/CLAUDE.md

@@ -0,0 +1,110 @@
+# CLAUDE.md
+
+Guidance for working in this repo. TYPEFASTER is a terminal-first typing game:
+an offline TUI plus an online real-time multiplayer server. Distributed via PyPI
+(`typefaster-cli`) and a Homebrew tap. Hosted at $0 on an Oracle Always-Free VM.
+
+## Repo layout
+
+```
+client/typefaster/   the CLI/TUI app  (domain · services · infra · ui · net · assets)
+server/app/          online server (FastAPI · WebSockets · Redis · routers · ws)
+shared/typefaster_shared/   schemas (dto), WS events, scoring, anti-cheat — used by both
+tests/               client tests (unit/ + integration/)
+server/tests/        server tests (fakeredis + Starlette TestClient)
+docs/                architecture, schemas, WS protocol, deploy, security, releasing
+Formula lives in a SEPARATE repo: Anoshor/homebrew-typefaster (the tap).
+```
+
+## Architecture & layering (do not violate)
+
+Clean layering, enforced by convention:
+
+- **`domain/`** is pure: dataclasses, enums, and deterministic logic. It must NOT
+  import Rich/Textual/SQLite/httpx. Time is injected (`Clock`), so logic is
+  unit-testable without a real clock.
+- **`services/`** orchestrate domain + repositories. UI-free, reusable headlessly.
+- **`infra/`** (SQLite, config, paths, quote loader) and **`ui/`** (Textual)
+  depend inward only.
+- **Repository port**: `infra/repository.py` is a `typing.Protocol`; the SQLite
+  impl satisfies it. Services depend on the Protocol, not SQLite.
+- **Server is authoritative**: the WS server re-scores every race from raw inputs
+  using `shared/typefaster_shared/scoring.py` (the SAME math as the client's
+  `domain/calculators.py`) and never trusts client-reported WPM/accuracy.
+
+When adding code, put it in the right layer and keep `domain/` pure.
+
+## Commands
+
+Client (from repo root; uses `client/` on PYTHONPATH via the Makefile):
+```bash
+make install     # editable install + dev deps into a venv
+make play        # launch the TUI (offline)
+make check       # ruff + mypy --strict + pytest  ← run before every PR
+make test        # pytest only
+make up / down   # start/stop the online stack (redis + server) via Docker
+```
+
+Server (separate package; mirror CI exactly):
+```bash
+cd server && pytest                                   # server suite (fakeredis)
+ruff check server shared --select E,F,I,UP,B --ignore UP042   # the server lint gate
+```
+
+Notes:
+- The package lives at `client/typefaster`; `make` sets `PYTHONPATH=client`. If
+  running tools directly, prefix with `PYTHONPATH=client`.
+- Client gate = ruff + black + mypy --strict + pytest. **Server CI runs ruff +
+  pytest only — no mypy** (the server has known pre-existing mypy noise from the
+  untyped `typefaster_shared` import; don't chase it).
+- Tests use markers: `unit`, `integration`, `ui` (Textual pilot smoke tests).
+
+## Conventions
+
+- Add/adjust tests for any behavior change. UI gets Textual pilot smoke tests in
+  `tests/integration/test_ui_smoke.py`; logic gets unit/integration tests.
+- Adding a TUI screen: create it under `ui/screens/`, register it in `_PANELS`
+  in `ui/app.py`, and add a menu row in `ui/screens/main_menu.py`. Read-only
+  panels subclass `PanelScreen` (`ui/screens/_base.py`); override `body()`.
+- Adding a SQLite migration: append a `(version, sql)` tuple to `_MIGRATIONS` in
+  `infra/migrations.py` (use `IF NOT EXISTS`; never edit a shipped migration).
+- Adding quotes: edit `scripts/seed_quotes.py`, run it, commit the regenerated
+  `client/typefaster/assets/quotes.json`.
+- Conventional, focused commits. Don't commit generated artifacts (git-ignored).
+
+## Release flow (automated)
+
+Per release, edit the version in **two** files that must stay in sync:
+`pyproject.toml` and `client/typefaster/__init__.py`. Then:
+```bash
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+The tag triggers `.github/workflows/release.yml`, which: builds → publishes to
+PyPI (OIDC Trusted Publishing, gated by the `pypi` environment approval) →
+creates a GitHub Release → **auto-bumps the Homebrew tap formula** (needs the
+`HOMEBREW_TAP_TOKEN` secret) → pushes the server image to GHCR.
+
+## Git / PR workflow
+
+`main` is protected: PRs require a passing CI + a CODEOWNERS review before merge;
+no force-push/deletion. As repo admin you can bypass for your own pushes, but
+prefer feature branches. Branch from `main`; do not commit directly unless asked.
+
+## Key facts / gotchas
+
+- **Public server**: client default `server_url` lives in
+  `client/typefaster/net/token_store.py` (`DEFAULT_SERVER_URL`). It self-heals a
+  dead `*.trycloudflare.com` URL to the default on load.
+- **Online is server-authoritative** with per-IP rate limiting on auth/oauth and
+  app-layer flood guards (see `docs/ddos-protection.md`). A true volumetric DDoS
+  needs an upstream edge (Cloudflare) — app code can't stop it.
+- **Daily challenge** is keyed by UTC date (`datetime.now(UTC).date()`), matching
+  how results are filed — don't switch it to local `date.today()`.
+- **Secrets are never committed.** JWT secret + OAuth client IDs/secret live only
+  in `/opt/typefaster/.env` on the VM. `.env` and `docs/MARKETING.md` are
+  git-ignored.
+- **Two repos by design**: the code repo and the mandatory `homebrew-typefaster`
+  tap (one formula file, auto-bumped by CI). The tap is not a second project to
+  maintain.
+- The TUI footer credits "Anoshor Paul" intentionally; keep it.
+- $0 hosting is a project goal — prefer free tiers; flag anything that adds cost.

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/CONTRIBUTING.md

@@ -48,6 +48,25 @@ Quality gates (all must pass):
 - **mypy --strict** — types (the `typefaster` package)
 - **pytest** — tests; add/adjust tests for any behavior change
 
+## Pull request process
+
+`main` is a protected branch — you can't push to it directly. Work on a fork or
+a feature branch and open a PR:
+
+1. **Fork** the repo (or branch, if you're a collaborator) and create a topic
+   branch: `git checkout -b fix/ghost-timing`.
+2. Make your change with tests, then run `make check` locally.
+3. **Open a PR** against `main`. CI runs automatically.
+4. **All checks must be green** — `lint · type · test (3.11/3.12)`,
+   `server lint · test`, and `dependency audit (pip-audit)`.
+5. A **maintainer review is required** (you'll be auto-requested via
+   `CODEOWNERS`), and any review conversations must be resolved before merge.
+6. Keep PRs small and focused; squash-friendly, conventional commit messages
+   help.
+
+Dependency and GitHub-Actions updates are proposed automatically by Dependabot —
+no action needed from contributors.
+
 ## Guidelines
 
 - **Keep the domain pure** and deterministic (time is injected via `Clock`).

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typefaster-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: A terminal-first typing game inspired by MonkeyType and TypeRacer.
 Project-URL: Homepage, https://github.com/Anoshor/typefaster-cli
 Project-URL: Repository, https://github.com/Anoshor/typefaster-cli
@@ -53,14 +53,16 @@ typefaster
 **Homebrew** (macOS / Linux)
 ```bash
 brew install Anoshor/typefaster/typefaster
+# or tap once, then use the short name:
+brew tap anoshor/typefaster && brew install typefaster
 ```
 
-**pipx** (any OS with Python 3.11+) — fastest
+**pipx** (any OS with Python 3.11+) — fastest install
 ```bash
 pipx install typefaster-cli
 ```
 
-Verify: `typefaster version`
+Verify: `typefaster version` · Upgrade: `brew upgrade typefaster` or `pipx upgrade typefaster-cli`
 
 ## Play (offline — no account, no internet)
 
@@ -73,8 +75,14 @@ Keyboard-only menu:
 - **Time Attack** — type for 30 / 60 / 120s (←/→ to change the duration inline).
 - **Practice** — pick a mode/ghost.
 - **Daily Challenge** — same quote for everyone each day, local leaderboard.
+- **🎯 Typing Coach** — see the keys you miss most, a per-key accuracy heatmap, and
+  finger-position tips; press **d** to launch a drill weighted toward your weak
+  keys. All computed locally — no account, no internet, no AI service.
 - **Stats / History / Profile / Leaderboard / Settings**.
 
+**Practice modes (MonkeyType-style):** in **Settings**, toggle **Lowercase only**
+or **Words only** (pure a–z, no punctuation or numbers) to strip the text down.
+
 Live WPM, accuracy, progress, and an animated ghost bar. Backspace corrects
 mistakes (original errors still count, MonkeyType-style). All progress is saved
 locally in SQLite.
@@ -136,9 +144,11 @@ Deploy guides: [`docs/deploy-oracle.md`](docs/deploy-oracle.md) (free 24/7 VM)
 ```bash
 make install     # editable install + dev deps
 make play        # run it
-make check       # ruff + mypy + pytest
+make check       # ruff + mypy + pytest  (CI parity)
 ```
-Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions welcome! `main` is protected — fork, branch, and open a PR; CI must
+pass and a maintainer review is required before merge. Full guide:
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/README.md

@@ -21,14 +21,16 @@ typefaster
 **Homebrew** (macOS / Linux)
 ```bash
 brew install Anoshor/typefaster/typefaster
+# or tap once, then use the short name:
+brew tap anoshor/typefaster && brew install typefaster
 ```
 
-**pipx** (any OS with Python 3.11+) — fastest
+**pipx** (any OS with Python 3.11+) — fastest install
 ```bash
 pipx install typefaster-cli
 ```
 
-Verify: `typefaster version`
+Verify: `typefaster version` · Upgrade: `brew upgrade typefaster` or `pipx upgrade typefaster-cli`
 
 ## Play (offline — no account, no internet)
 
@@ -41,8 +43,14 @@ Keyboard-only menu:
 - **Time Attack** — type for 30 / 60 / 120s (←/→ to change the duration inline).
 - **Practice** — pick a mode/ghost.
 - **Daily Challenge** — same quote for everyone each day, local leaderboard.
+- **🎯 Typing Coach** — see the keys you miss most, a per-key accuracy heatmap, and
+  finger-position tips; press **d** to launch a drill weighted toward your weak
+  keys. All computed locally — no account, no internet, no AI service.
 - **Stats / History / Profile / Leaderboard / Settings**.
 
+**Practice modes (MonkeyType-style):** in **Settings**, toggle **Lowercase only**
+or **Words only** (pure a–z, no punctuation or numbers) to strip the text down.
+
 Live WPM, accuracy, progress, and an animated ghost bar. Backspace corrects
 mistakes (original errors still count, MonkeyType-style). All progress is saved
 locally in SQLite.
@@ -104,9 +112,11 @@ Deploy guides: [`docs/deploy-oracle.md`](docs/deploy-oracle.md) (free 24/7 VM)
 ```bash
 make install     # editable install + dev deps
 make play        # run it
-make check       # ruff + mypy + pytest
+make check       # ruff + mypy + pytest  (CI parity)
 ```
-Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions welcome! `main` is protected — fork, branch, and open a PR; CI must
+pass and a maintainer review is required before merge. Full guide:
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/client/typefaster/__init__.py

@@ -1,3 +1,3 @@
 """TYPEFASTER-CLI — a terminal-first typing game."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"

typefaster_cli-0.3.1/client/typefaster/domain/drills.py

@@ -0,0 +1,39 @@
+"""Adaptive drill generation — assemble practice text biased toward weak keys.
+
+Pure and deterministic (the word list and RNG are injected). The service layer
+supplies words from the quote corpus.
+"""
+
+from __future__ import annotations
+
+import random
+
+
+def build_drill(
+    weak_keys: list[str],
+    words: list[str],
+    *,
+    length: int = 30,
+    rng: random.Random | None = None,
+) -> str:
+    """Return a space-joined drill of ``length`` words, weighted so words
+    containing the player's weak keys appear more often. Falls back to a plain
+    random sample when there are no weak keys or no matching words."""
+    rng = rng or random.Random()
+    clean = [w.lower() for w in words if w.isalpha()]
+    if not clean:
+        raise ValueError("no words available to build a drill")
+
+    weak = {c.lower() for c in weak_keys if c.strip()}  # ignore the space key
+    if not weak:
+        return " ".join(rng.choices(clean, k=length))
+
+    # Weight each word by how many distinct weak keys it exercises.
+    scored = [(w, sum(1 for ch in set(w) if ch in weak)) for w in clean]
+    weighted = [(w, s) for w, s in scored if s > 0]
+    if not weighted:
+        weighted = [(w, 1) for w in clean]
+
+    population = [w for w, _ in weighted]
+    weights = [s for _, s in weighted]
+    return " ".join(rng.choices(population, weights=weights, k=length))

typefaster_cli-0.3.1/client/typefaster/domain/keyboard.py

@@ -0,0 +1,74 @@
+"""Static QWERTY touch-typing model — which finger reaches each key and how.
+
+Pure reference data (no I/O), used by the typing coach to give finger-position
+guidance and to lay out the per-key heatmap. Keyed by the lowercase character,
+matching how ``TypingEngine`` records key stats.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Visual rows for the heatmap, left-to-right, top-to-bottom.
+ROWS: tuple[str, ...] = ("qwertyuiop", "asdfghjkl", "zxcvbnm")
+
+# Finger assignment for the standard touch-typing layout.
+_FINGER: dict[str, str] = {
+    **dict.fromkeys("qaz", "left pinky"),
+    **dict.fromkeys("wsx", "left ring"),
+    **dict.fromkeys("edc", "left middle"),
+    **dict.fromkeys("rfvtgb", "left index"),
+    **dict.fromkeys("yhnujm", "right index"),
+    **dict.fromkeys("ik,", "right middle"),
+    **dict.fromkeys("ol.", "right ring"),
+    **dict.fromkeys("p;/", "right pinky"),
+    " ": "thumb",
+}
+
+# The resting (home-row) key for each finger.
+_HOME: dict[str, str] = {
+    "left pinky": "a",
+    "left ring": "s",
+    "left middle": "d",
+    "left index": "f",
+    "right index": "j",
+    "right middle": "k",
+    "right ring": "l",
+    "right pinky": ";",
+    "thumb": "space",
+}
+
+HOME_ROW: frozenset[str] = frozenset("asdfjkl;")
+
+
+@dataclass(frozen=True, slots=True)
+class KeyInfo:
+    finger: str
+    home_key: str
+    tip: str
+
+
+def key_info(ch: str) -> KeyInfo | None:
+    """Finger/home/tip for a single key, or None if it's not on the model
+    (e.g. digits or symbols we don't coach)."""
+    ch = ch.lower()
+    finger = _FINGER.get(ch)
+    if finger is None:
+        return None
+    home = _HOME[finger]
+    if ch == " ":
+        tip = "tap with your thumb"
+    elif ch in HOME_ROW:
+        tip = f"home row — rest your {finger} here"
+    elif _row_of(ch) == 0:
+        tip = f"reach up from {home.upper()} with your {finger}"
+    else:
+        tip = f"reach down from {home.upper()} with your {finger}"
+    return KeyInfo(finger=finger, home_key=home, tip=tip)
+
+
+def _row_of(ch: str) -> int:
+    for i, row in enumerate(ROWS):
+        if ch in row:
+            return i
+    return 1  # default to home row

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/client/typefaster/domain/models.py

@@ -135,6 +135,8 @@ class RaceResult:
     # Set when the run is implausible (paste/auto-input) — not recorded.
     suspicious: bool = False
     flags: tuple[str, ...] = ()
+    # Per-key (attempts, misses), folded by case — feeds the typing coach.
+    key_stats: dict[str, tuple[int, int]] = field(default_factory=dict)
 
     @property
     def completed(self) -> bool:

typefaster_cli-0.3.1/client/typefaster/domain/text_modifiers.py

@@ -0,0 +1,34 @@
+"""MonkeyType-style text modifiers — pure transforms applied to race text.
+
+These reshape the *target text* a player types (e.g. strip everything down to
+lowercase words) without touching the original quote that gets persisted. Kept
+dependency-free and deterministic so they're trivially unit-testable.
+"""
+
+from __future__ import annotations
+
+import re
+
+_NON_WORD = re.compile(r"[^A-Za-z ]+")
+_WHITESPACE = re.compile(r"\s+")
+
+
+def apply_modifiers(text: str, *, lowercase: bool, words_only: bool) -> str:
+    """Apply the active modifiers to ``text``.
+
+    - ``words_only`` keeps only ``[a-z]`` and single spaces (implies lowercase).
+    - ``lowercase`` (when words_only is off) just lowercases.
+
+    Never returns an empty string: if a transform would empty the text (e.g. a
+    quote made entirely of digits/punctuation), the original is returned, since
+    ``TypingEngine`` rejects an empty target.
+    """
+    out = text
+    if words_only:
+        out = _WHITESPACE.sub(" ", out)  # tabs/newlines become separators first
+        out = _NON_WORD.sub("", out)  # drop punctuation/digits, keep letters + space
+        out = _WHITESPACE.sub(" ", out).strip()  # collapse any doubled spaces
+        out = out.lower()
+    elif lowercase:
+        out = out.lower()
+    return out or text

{typefaster_cli-0.2.0 → typefaster_cli-0.3.1}/client/typefaster/domain/typing_engine.py

@@ -37,6 +37,11 @@ class TypingEngine:
         self._total_keystrokes = 0
         self._correct_keystrokes = 0
 
+        # Per-key (case-folded) attempt/miss counts for the typing coach. These
+        # count every keypress, so a mistake counts even if later corrected.
+        self._key_attempts: dict[str, int] = {}
+        self._key_misses: dict[str, int] = {}
+
         self._timeline: list[ReplayPoint] = [ReplayPoint(0, 0.0)]
         self._last_progress_pct = 0.0
 
@@ -57,6 +62,12 @@ class TypingEngine:
         if is_correct:
             self._correct_keystrokes += 1
 
+        # Track the *expected* key (case-folded) so the coach can rank weak keys.
+        k = expected.lower()
+        self._key_attempts[k] = self._key_attempts.get(k, 0) + 1
+        if not is_correct:
+            self._key_misses[k] = self._key_misses.get(k, 0) + 1
+
         self._record(t_ms)
 
     def backspace(self, t_ms: int) -> None:
@@ -95,6 +106,13 @@ class TypingEngine:
     def correct_keystrokes(self) -> int:
         return self._correct_keystrokes
 
+    @property
+    def key_stats(self) -> dict[str, tuple[int, int]]:
+        """Per-key (attempts, misses), case-folded, for the typing coach."""
+        return {
+            k: (attempts, self._key_misses.get(k, 0)) for k, attempts in self._key_attempts.items()
+        }
+
     @property
     def progress(self) -> float:
         """Completion fraction 0..1 based on cursor position."""
@@ -147,4 +165,5 @@ class TypingEngine:
             timeline=self.timeline,
             ghost_kind=ghost_kind,
             ghost_won=ghost_won,
+            key_stats=self.key_stats,
         )