typefaster-cli 0.1.0__py3-none-any.whl

typefaster/ui/screens/race.py

@@ -0,0 +1,238 @@
+"""The race screen — countdown, live typing, ghost animation.
+
+Drives a pure ``TypingEngine`` from keyboard events and ticks a timer to update
+the clock, live stats, and the ghost bar. On finish it dismisses with the
+computed ``RaceResult`` so the app can persist it and show results.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from rich.text import Text
+from textual import events
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.timer import Timer
+from textual.widgets import Static
+
+from ...domain import anti_cheat
+from ...domain.ghost import ghost_won, progress_at
+from ...domain.models import RaceKind, RaceResult
+from ...domain.typing_engine import TypingEngine
+from ...infra.clock import Clock, SystemClock
+from ...services.race_service import RaceSetup
+from ..widgets import bigtext
+from ..widgets.live_stats import LiveStats
+from ..widgets.progress_bars import ProgressBars
+from ..widgets.typing_field import TypingField
+
+_COUNTDOWN_FROM = 3
+_TICK = 1 / 15  # ~15 fps updates
+
+
+class RaceScreen(Screen[RaceResult | None]):
+    BINDINGS = [
+        ("escape", "quit_race", "Quit"),
+    ]
+
+    def __init__(self, setup: RaceSetup, clock: Clock | None = None) -> None:
+        super().__init__()
+        self.setup = setup
+        self.clock = clock or SystemClock()
+        self.engine = TypingEngine(setup.target_text, allow_backspace=setup.allow_backspace)
+        # The clock starts on the FIRST keystroke (MonkeyType/TypeRacer style),
+        # so _start_ms stays None until the player actually types.
+        self._start_ms: int | None = None
+        self._typing_enabled = False
+        self._finished = False
+        self._pasted = False
+        self._countdown = _COUNTDOWN_FROM
+        self._countdown_timer: Timer | None = None
+        self._race_timer: Timer | None = None
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="race-wrap"):
+            yield Static("", id="countdown")
+            yield LiveStats()
+            yield TypingField()
+            yield ProgressBars()
+            if self.setup.kind is RaceKind.TIME:
+                label = f"TIME mode · {self.setup.mode.value}s"
+            else:
+                label = f"QUOTE mode · {self.setup.quote.source or 'unknown'}"
+            yield Static(f"{label} · esc to quit", classes="dim")
+
+    def on_mount(self) -> None:
+        self.query_one(LiveStats).display = False
+        self.query_one(TypingField).display = False
+        self.query_one(ProgressBars).display = False
+        self._render_countdown()
+        self._countdown_timer = self.set_interval(1.0, self._tick_countdown)
+
+    # ── countdown ──────────────────────────────────────────────────────
+    def _render_countdown(self) -> None:
+        big = bigtext.render(str(self._countdown))
+        self.query_one("#countdown", Static).update(Text(f"Get ready…\n\n{big}", justify="center"))
+
+    def _tick_countdown(self) -> None:
+        self._countdown -= 1
+        if self._countdown <= 0:
+            # Stop the countdown timer so it can't fire again (and re-run _begin).
+            if self._countdown_timer is not None:
+                self._countdown_timer.stop()
+            self._begin()
+            return
+        self._render_countdown()
+
+    def _begin(self) -> None:
+        if self._typing_enabled:  # guard: only ever begin once
+            return
+        self.query_one("#countdown", Static).update(
+            Text(bigtext.render("GO!"), justify="center", style="bold green")
+        )
+        self.query_one(LiveStats).display = True
+        self.query_one(TypingField).display = True
+        self.query_one(ProgressBars).display = True
+        self._typing_enabled = True
+        # Note: the clock is NOT started here — it starts on the first keystroke.
+        self._refresh_field()
+        self._race_timer = self.set_interval(_TICK, self._tick_race)
+
+    # ── live loop ──────────────────────────────────────────────────────
+    def _elapsed_ms(self) -> int:
+        if self._start_ms is None:
+            return 0
+        return self.clock.now_ms() - self._start_ms
+
+    def _tick_race(self) -> None:
+        if self._finished:
+            return
+        # Before the first keystroke the clock hasn't started: show a full timer.
+        if self._start_ms is None:
+            self.query_one(LiveStats).show(
+                wpm=0.0,
+                accuracy=self.engine.live_accuracy(),
+                progress=0.0,
+                seconds_left=float(self.setup.mode.value),
+            )
+            self._refresh_bars(0)
+            return
+
+        elapsed = self._elapsed_ms()
+
+        if self.setup.kind is RaceKind.TIME:
+            limit_ms = self.setup.mode.value * 1000
+            seconds_left = (limit_ms - elapsed) / 1000.0
+            # TIME mode: progress is how far through the clock we are.
+            progress = min(1.0, elapsed / limit_ms) if limit_ms else 0.0
+            self.query_one(LiveStats).show(
+                wpm=self.engine.live_wpm(max(elapsed, 1)),
+                accuracy=self.engine.live_accuracy(),
+                progress=progress,
+                seconds_left=seconds_left,
+            )
+            self._refresh_bars(elapsed, player_pct=progress * 100.0)
+            if elapsed >= limit_ms or self.engine.finished:
+                self._finish(elapsed)
+        else:
+            # QUOTE mode: no time limit; the clock counts up; end on completion.
+            self.query_one(LiveStats).show(
+                wpm=self.engine.live_wpm(max(elapsed, 1)),
+                accuracy=self.engine.live_accuracy(),
+                progress=self.engine.progress,
+                seconds_left=elapsed / 1000.0,  # shown as elapsed time
+            )
+            self._refresh_bars(elapsed, player_pct=self.engine.progress * 100.0)
+            if self.engine.finished:
+                self._finish(elapsed)
+
+    def _refresh_field(self) -> None:
+        self.query_one(TypingField).show(self.engine.target, self.engine.states, self.engine.cursor)
+
+    def _refresh_bars(self, elapsed: int, *, player_pct: float | None = None) -> None:
+        ghost = self.setup.ghost
+        ghost_pct = None
+        ghost_label = ""
+        if ghost is not None:
+            ghost_pct = progress_at(ghost.timeline, elapsed)
+            ghost_label = ghost.label
+        if player_pct is None:
+            player_pct = self.engine.progress * 100.0
+        self.query_one(ProgressBars).show(
+            player_pct=player_pct,
+            ghost_pct=ghost_pct,
+            ghost_label=ghost_label,
+        )
+
+    # ── input ──────────────────────────────────────────────────────────
+    def on_paste(self, event: events.Paste) -> None:
+        # Pasting the quote is not typing — swallow it and flag the race so the
+        # result is not recorded.
+        if self._typing_enabled and not self._finished:
+            self._pasted = True
+            event.stop()
+
+    def on_key(self, event: events.Key) -> None:
+        if not self._typing_enabled or self._finished:
+            return
+        if event.key == "backspace":
+            if self._start_ms is None:
+                return  # nothing typed yet; clock hasn't started
+            self.engine.backspace(self._elapsed_ms())
+            event.stop()
+        elif event.character is not None and event.character.isprintable():
+            # The clock starts on the first real keystroke.
+            if self._start_ms is None:
+                self._start_ms = self.clock.now_ms()
+                self.query_one("#countdown", Static).display = False  # hide "GO!"
+            self.engine.type_char(event.character, self._elapsed_ms())
+            event.stop()
+        else:
+            return
+        self._refresh_field()
+        if self.engine.finished:
+            self._finish(self._elapsed_ms())
+
+    # ── finish ─────────────────────────────────────────────────────────
+    def _finish(self, elapsed: int) -> None:
+        if self._finished:
+            return
+        self._finished = True
+        ghost = self.setup.ghost
+
+        # ``ghost_won`` in the result means the *player* beat the ghost: the
+        # player completed the quote before the ghost reached 100%. Only
+        # meaningful when there is a ghost and the player actually finished.
+        player_beat_ghost: bool | None = None
+        if ghost is not None and self.engine.finished:
+            player_beat_ghost = not ghost_won(ghost.timeline, elapsed)
+
+        mode_seconds = self.setup.mode.value if self.setup.kind is RaceKind.TIME else 0
+        result = self.engine.result(
+            max(elapsed, 1),
+            kind=self.setup.kind,
+            mode_seconds=mode_seconds,
+            ghost_kind=ghost.kind if ghost else None,
+            ghost_won=player_beat_ghost,
+        )
+
+        # Reject physically-impossible results (paste, held key, auto-input) so
+        # they don't pollute stats or personal bests.
+        suspicious, flags = anti_cheat.evaluate(
+            wpm=result.wpm,
+            raw_wpm=result.raw_wpm,
+            duration_ms=result.duration_ms,
+            total_keystrokes=self.engine.total_keystrokes,
+            quote_length=len(self.setup.quote.text),
+            pasted=self._pasted,
+        )
+        if suspicious:
+            result = replace(result, suspicious=True, flags=flags)
+
+        self.dismiss(result)
+
+    def action_quit_race(self) -> None:
+        self._finished = True
+        self.dismiss(None)

typefaster/ui/screens/results.py

@@ -0,0 +1,89 @@
+"""Post-race results screen."""
+
+from __future__ import annotations
+
+from rich.table import Table
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import Static
+
+from ...domain.models import RaceResult
+from ...services.race_service import RaceSetup, RaceSummary
+from ..widgets import bigtext
+
+
+class ResultsScreen(Screen[str]):
+    """Shows the outcome. Dismisses with an action string: 'again' or 'menu'.
+
+    ``summary`` is ``None`` when the run was implausible (paste/auto-input) and
+    therefore not recorded.
+    """
+
+    BINDINGS = [
+        ("enter", "again", "Race again"),
+        ("escape", "menu", "Menu"),
+    ]
+
+    def __init__(
+        self, result: RaceResult, setup: RaceSetup, summary: RaceSummary | None = None
+    ) -> None:
+        super().__init__()
+        self.result = result
+        self.setup = setup
+        self.summary = summary
+
+    def compose(self) -> ComposeResult:
+        r = self.result
+        with Vertical(id="panel-wrap"):
+            yield Static(Text("RESULTS", justify="center"), id="title")
+
+            banner = self._banner()
+            if banner:
+                yield Static(banner)
+
+            # Big, prominent WPM number.
+            yield Static(Text(bigtext.render(f"{r.wpm:.0f}"), justify="center", style="bold cyan"))
+            yield Static(Text("WPM", justify="center", style="grey58"))
+
+            table = Table.grid(padding=(0, 2))
+            table.add_column(justify="right", style="grey58")
+            table.add_column(justify="left")
+            table.add_row("Raw WPM", f"{r.raw_wpm:.0f}")
+            table.add_row("Accuracy", f"[bold green]{r.accuracy * 100:.1f}%[/]")
+            table.add_row("Chars", f"{r.correct_chars} correct · {r.incorrect_chars} wrong")
+            table.add_row("Completion", f"{r.progress * 100:.0f}%")
+            table.add_row("Time", f"{r.duration_ms / 1000:.1f}s")
+            if self.summary and self.summary.new_personal_best:
+                table.add_row(
+                    "Personal best",
+                    f"[grey58]{self.summary.previous_best_wpm:.0f}[/] → "
+                    f"[bold yellow]{r.wpm:.0f}[/]  ▲ new best",
+                )
+            yield Static(table)
+            yield Static("", classes="dim")
+            yield Static("⏎ race again    esc menu", classes="dim")
+
+    def _banner(self) -> Text | None:
+        r = self.result
+        if r.suspicious:
+            reasons = ", ".join(r.flags) if r.flags else "implausible result"
+            return Text(
+                f"⚠ Not recorded — {reasons}.\n"
+                "Type the text yourself (no pasting) for a valid result.",
+                style="bold red",
+            )
+        if r.ghost_won is True:
+            return Text("✓ You beat your ghost!", style="bold green")
+        if r.ghost_won is False:
+            return Text("✗ The ghost won this time.", style="bold red")
+        if self.summary and self.summary.new_personal_best:
+            return Text("🏆 New personal best!", style="bold yellow")
+        return None
+
+    def action_again(self) -> None:
+        self.dismiss("again")
+
+    def action_menu(self) -> None:
+        self.dismiss("menu")

typefaster/ui/screens/settings.py

@@ -0,0 +1,81 @@
+"""Settings screen — toggle/cycle options; changes persist immediately."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import OptionList, Static
+from textual.widgets.option_list import Option
+
+from ...infra.config import Settings
+
+
+class SettingsScreen(Screen[None]):
+    BINDINGS = [("escape", "back", "Back")]
+
+    _THEMES = ["dark", "light"]
+    _TIMES = [30, 60, 120]
+    _GHOSTS = ["personal-best", "last", "random"]
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="menu-wrap"):
+            yield Static(Text("SETTINGS", justify="center"), id="title")
+            yield OptionList(id="settings-list")
+            yield Static("⏎ change value    esc back (auto-saves)", classes="dim")
+
+    def on_mount(self) -> None:
+        self._refresh()
+        self.query_one(OptionList).focus()
+
+    def _settings(self) -> Settings:
+        return self.app.services.settings  # type: ignore[attr-defined,no-any-return]
+
+    def _refresh(self) -> None:
+        s = self._settings()
+        ol = self.query_one(OptionList)
+        ol.clear_options()
+        rows = [
+            ("theme", f"Theme           ‹ {s.theme} ›"),
+            ("default_time", f"Default race    ‹ {s.default_time}s ›"),
+            (
+                "allow_backspace",
+                f"Backspace       ‹ {'allowed' if s.allow_backspace else 'strict'} ›",
+            ),
+            ("default_ghost", f"Default ghost   ‹ {s.default_ghost} ›"),
+            ("sound", f"Sound (bell)    ‹ {'on' if s.sound else 'off'} ›"),
+        ]
+        for key, label in rows:
+            ol.add_option(Option(label, id=key))
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        s = self._settings()
+        key = event.option.id
+        if key == "theme":
+            s.theme = self._cycle(self._THEMES, s.theme)
+        elif key == "default_time":
+            s.default_time = self._cycle(self._TIMES, s.default_time)
+        elif key == "allow_backspace":
+            s.allow_backspace = not s.allow_backspace
+        elif key == "default_ghost":
+            s.default_ghost = self._cycle(self._GHOSTS, s.default_ghost)
+        elif key == "sound":
+            s.sound = not s.sound
+        s.save()
+        idx = event.option_index
+        self._refresh()
+        self.query_one(OptionList).highlighted = idx
+
+    @staticmethod
+    def _cycle(values: list[Any], current: Any) -> Any:
+        try:
+            i = values.index(current)
+        except ValueError:
+            i = -1
+        return values[(i + 1) % len(values)]
+
+    def action_back(self) -> None:
+        self.app.pop_screen()

typefaster/ui/screens/stats.py

@@ -0,0 +1,65 @@
+"""Statistics screen."""
+
+from __future__ import annotations
+
+from rich.console import Group, RenderableType
+from rich.table import Table
+from rich.text import Text
+
+from ._base import PanelScreen
+
+_SPARK = "▁▂▃▄▅▆▇█"
+
+
+def _sparkline(values: list[float]) -> str:
+    if not values:
+        return "—"
+    lo, hi = min(values), max(values)
+    span = hi - lo or 1.0
+    return "".join(_SPARK[min(7, int((v - lo) / span * 7))] for v in values)
+
+
+class StatsScreen(PanelScreen):
+    title_text = "STATS"
+
+    def body(self) -> RenderableType:
+        s = self.app.services.stats.summary()  # type: ignore[attr-defined]
+        p = s.profile
+
+        lifetime = Table.grid(padding=(0, 3))
+        lifetime.add_column(justify="right", style="grey58")
+        lifetime.add_column(justify="left")
+        lifetime.add_row("Races played", str(p.races_played))
+        lifetime.add_row("Races won", str(p.races_won))
+        lifetime.add_row("Best WPM", f"{p.best_wpm:.0f}")
+        lifetime.add_row("Avg WPM", f"{s.avg_wpm:.0f}")
+        lifetime.add_row("Best accuracy", f"{p.best_accuracy * 100:.1f}%")
+        lifetime.add_row("Avg accuracy", f"{s.avg_accuracy * 100:.1f}%")
+        lifetime.add_row("Total chars", f"{p.total_chars:,}")
+        lifetime.add_row("Total time", _fmt_ms(p.total_time_ms))
+
+        time_tbl = Table(title="Time Attack · best WPM", title_style="bold")
+        time_tbl.add_column("Duration")
+        time_tbl.add_column("Best WPM", justify="right")
+        for seconds in (30, 60, 120):
+            time_tbl.add_row(f"{seconds}s", f"{s.time_best_by_mode.get(seconds, 0.0):.0f}")
+
+        quote_tbl = Table(title="Quote · personal bests", title_style="bold")
+        quote_tbl.add_column("Metric")
+        quote_tbl.add_column("Value", justify="right")
+        quote_tbl.add_row("Best WPM", f"{s.quote_best_wpm:.0f}")
+        quote_tbl.add_row("Fastest finish", _fmt_ms(s.quote_best_ms) if s.quote_best_ms else "—")
+
+        spark = Text(f"Recent WPM  {_sparkline(s.recent_wpm)}", style="cyan")
+        return Group(lifetime, Text(""), time_tbl, Text(""), quote_tbl, Text(""), spark)
+
+
+def _fmt_ms(ms: int) -> str:
+    secs = ms // 1000
+    h, rem = divmod(secs, 3600)
+    m, sec = divmod(rem, 60)
+    if h:
+        return f"{h}h {m}m"
+    if m:
+        return f"{m}m {sec}s"
+    return f"{sec}s"

typefaster/ui/theme.py

@@ -0,0 +1,82 @@
+"""Shared color tokens and the Textual CSS for the app."""
+
+from __future__ import annotations
+
+# Semantic colors used by Rich renderables (widgets render their own text).
+CORRECT = "bold green"
+INCORRECT = "bold white on dark_red"
+PENDING = "grey42"
+CARET = "reverse"
+ACCENT = "bold cyan"
+MUTED = "grey58"
+
+APP_CSS = """
+Screen {
+    background: $surface;
+    align: center middle;
+}
+
+/* Menus/panels: fill most of the terminal instead of a tiny centered box. */
+#menu-wrap, #panel-wrap {
+    width: 100%;
+    height: 100%;
+    border: round $primary;
+    padding: 2 4;
+}
+
+#title {
+    content-align: center middle;
+    color: $accent;
+    text-style: bold;
+    padding-bottom: 1;
+}
+
+#subtitle {
+    content-align: center middle;
+    color: $text-muted;
+    padding-bottom: 1;
+}
+
+OptionList {
+    height: auto;
+    border: none;
+    background: $surface;
+}
+
+/* Race: full-bleed so the quote and bars are as large as the terminal allows. */
+#race-wrap {
+    width: 100%;
+    height: 100%;
+    border: round $primary;
+    padding: 2 4;
+}
+
+LiveStats {
+    height: 1;
+    color: $accent;
+    text-style: bold;
+    padding-bottom: 1;
+}
+
+TypingField {
+    height: 1fr;
+    min-height: 6;
+    padding: 2 2;
+    border-top: solid $primary-darken-2;
+    border-bottom: solid $primary-darken-2;
+}
+
+ProgressBars {
+    height: auto;
+    padding-top: 1;
+}
+
+#countdown {
+    content-align: center middle;
+    height: 1fr;
+    color: $accent;
+    text-style: bold;
+}
+
+.dim { color: $text-muted; }
+"""

typefaster/ui/widgets/__init__.py

@@ -0,0 +1 @@
+"""Reusable Textual widgets for the race experience."""

typefaster/ui/widgets/bigtext.py

@@ -0,0 +1,39 @@
+"""Tiny block-font renderer for big, prominent numbers/words (countdown, WPM).
+
+A terminal can't enlarge its own font, so we draw oversized glyphs out of block
+characters instead. Supports digits, a few letters, and basic punctuation.
+"""
+
+from __future__ import annotations
+
+_H = 5  # rows per glyph
+_FONT: dict[str, list[str]] = {
+    "0": ["█████", "█   █", "█   █", "█   █", "█████"],
+    "1": ["  ██ ", "   █ ", "   █ ", "   █ ", "  ███"],
+    "2": ["█████", "    █", "█████", "█    ", "█████"],
+    "3": ["█████", "    █", " ████", "    █", "█████"],
+    "4": ["█   █", "█   █", "█████", "    █", "    █"],
+    "5": ["█████", "█    ", "█████", "    █", "█████"],
+    "6": ["█████", "█    ", "█████", "█   █", "█████"],
+    "7": ["█████", "    █", "   █ ", "  █  ", "  █  "],
+    "8": ["█████", "█   █", "█████", "█   █", "█████"],
+    "9": ["█████", "█   █", "█████", "    █", "█████"],
+    "G": ["█████", "█    ", "█  ██", "█   █", "█████"],
+    "O": ["█████", "█   █", "█   █", "█   █", "█████"],
+    "W": ["█   █", "█   █", "█ █ █", "██ ██", "█   █"],
+    "P": ["█████", "█   █", "█████", "█    ", "█    "],
+    "M": ["█   █", "██ ██", "█ █ █", "█   █", "█   █"],
+    "!": ["  █  ", "  █  ", "  █  ", "     ", "  █  "],
+    "%": ["█   █", "   █ ", "  █  ", " █   ", "█   █"],
+    " ": ["     ", "     ", "     ", "     ", "     "],
+    ".": ["     ", "     ", "     ", "     ", "  █  "],
+}
+
+
+def render(text: str) -> str:
+    """Render ``text`` as multi-line block art (unsupported chars are skipped)."""
+    glyphs = [_FONT.get(ch.upper(), _FONT[" "]) for ch in text]
+    rows = []
+    for r in range(_H):
+        rows.append("  ".join(g[r] for g in glyphs))
+    return "\n".join(rows)

typefaster/ui/widgets/live_stats.py

@@ -0,0 +1,19 @@
+"""Header line: live WPM / accuracy / progress / timer."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.widgets import Static
+
+
+class LiveStats(Static):
+    def show(self, *, wpm: float, accuracy: float, progress: float, seconds_left: float) -> None:
+        text = Text()
+        text.append(f"WPM {wpm:5.0f}", style="bold cyan")
+        text.append("   ")
+        text.append(f"ACC {accuracy * 100:4.0f}%", style="bold green")
+        text.append("   ")
+        text.append(f"{progress * 100:3.0f}%", style="bold")
+        text.append("   ")
+        text.append(f"⏱ {max(0, int(seconds_left)):>3}s", style="bold yellow")
+        self.update(text)

typefaster/ui/widgets/progress_bars.py

@@ -0,0 +1,44 @@
+"""You-vs-ghost progress bars that rescale to the available width."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.widgets import Static
+
+_MIN_WIDTH = 24
+_BLOCK = "█"
+_EMPTY = "─"
+
+
+def _bar(progress_pct: float, width: int) -> str:
+    filled = max(0, min(width, round(progress_pct / 100.0 * width)))
+    return _BLOCK * filled + _EMPTY * (width - filled)
+
+
+class ProgressBars(Static):
+    """You-vs-ghost bars that grow to fill the available width."""
+
+    def _bar_width(self) -> int:
+        # Reserve room for the "You  [" prefix + "] 100% (Ghost)" suffix.
+        avail = (self.size.width or 60) - 18
+        return max(_MIN_WIDTH, avail)
+
+    def show(
+        self,
+        *,
+        player_pct: float,
+        ghost_pct: float | None = None,
+        ghost_label: str = "",
+    ) -> None:
+        width = self._bar_width()
+        text = Text()
+        text.append("You    ", style="bold")
+        text.append(f"{_bar(player_pct, width)} ", style="cyan")
+        text.append(f"{player_pct:3.0f}%\n", style="bold")
+        if ghost_pct is not None:
+            text.append("Ghost  ", style="bold")
+            text.append(f"{_bar(ghost_pct, width)} ", style="magenta")
+            text.append(f"{ghost_pct:3.0f}%", style="bold")
+            if ghost_label:
+                text.append(f"  ({ghost_label})", style="grey58")
+        self.update(text)