docs: updated readme with new text + images

README.md

@@ -6,13 +6,25 @@
    |  |       |  |   |  | --'    |  |    
    `--'       `--'   `--'        `--'    
   </pre>
+
+  <b>A Monkeytype-style typing test for your terminal.</b>
+
+  Type words or real code, watch your WPM, and pick a theme you like. Built with
+  <a href="https://ratatui.rs/">ratatui</a>.
+
+  <br/>
+
+  <img src="./docs/assets/home.png" alt="Typy words mode" width="720"/>
 </div>
 
-> [!WARNING]  
-> When the terminal is too small it can lead to strange behavior.
+<br/>
+
+> [!WARNING]
+> When the terminal is too small it can lead to strange behavior. Give it some room.
 
 ## Table of contents
 - [Overview](#overview)
+- [Modes](#modes)
 - [Installation](#installation)
 - [Usage](#usage)
 - [Keybindings](#keybindings)
@@ -25,22 +37,48 @@
 - [Uninstall](#uninstall)
 
 ## Overview
-![Description of the GIF](./docs/assets/demo.gif)
-
-I wanted a simple typing game to improve my typing speed and accuracy. I really like using
-[monkeytype](https://monkeytype.com/), so I built something similar for the terminal. Typy is a
-terminal typing test built with [ratatui](https://ratatui.rs/): it shows a stream of random words,
-tracks your speed and accuracy, and plots your words-per-minute over the run.
 
-The app is fully interactive:
+I wanted a simple typing game to improve my speed and accuracy. I'm a fan of
+[monkeytype](https://monkeytype.com/), so I built something similar for the terminal. Typy throws a
+stream of random words at you (or a real code snippet), keeps track of your speed and accuracy, and
+draws a little graph of your WPM at the end.
+
+Later on I added the code mode for a more selfish reason: I was learning a new keyboard layout and
+switching to a Corne keyboard, and typing prose gets you comfortable but it doesn't really
+prepare you for code. All the brackets, symbols and indentation are exactly the parts that trip you
+up on a new layout, so being able to drill on actual snippets made the transition a lot less painful.
+If you're in the same boat, that's what code mode is for.
+
+You don't have to remember any flags, run `typy` and everything (mode, theme, language, modifiers)
+lives on the settings screen.
+
+## Modes
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>Words</b><br/>
+      Random words in whatever language you pick. Turn on punctuation, numbers or uppercase when you
+      want it a bit harder.
+    </td>
+    <td width="50%" valign="top">
+      <b>Code</b><br/>
+      Real code snippets from open-source projects, highlighted with tree-sitter. Each one links back
+      to where it came from. Great for getting used to symbols and indentation on a new layout or
+      keyboard.
+    </td>
+  </tr>
+  <tr>
+    <td><img src="./docs/assets/texting.png" alt="Words mode" width="100%"/></td>
+    <td><img src="./docs/assets/coding.png" alt="Code mode" width="100%"/></td>
+  </tr>
+</table>
 
-- a **home screen** to start a test,
-- a **settings page** (theme, cursor, language, mode, time) with dropdown menus,
-- a **results screen** with WPM / accuracy and a graph,
-- a **stats page** with your recent games and averages.
-
-It also supports different modes (`uppercase`, `punctuation`), multiple languages, and themeable
-colors.
+<div align="center">
+  <br/>
+  <b>All of it is adjustable live from the settings screen</b><br/><br/>
+  <img src="./docs/assets/settings.png" alt="Settings screen" width="640"/>
+</div>
 
 ## Installation
 To install Typy, you can use the [Cargo] package manager:
@@ -89,17 +127,21 @@ nix run github:Pazl27/typy-cli
 
 ## Usage
 Run `typy` with no arguments to open the interactive app. You start on the home screen, from where
-you can begin a test, open the settings, or view your stats.
+you can begin a test, open the settings (`s`), or view your stats (`p`).
 
 ```bash
 typy
 ```
 
-If you pass a game option (`-t` or `-m`), Typy skips the home screen, runs a single test right away,
-shows the results, and exits when you press a key — handy for a quick run:
+If you pass a game option, Typy skips the home screen, runs one test straight away, shows the
+results, and exits when you press a key. Handy when you just want a quick run:
 
 ```bash
-typy -t 60 -m punctuation
+# a 60s words test with punctuation and numbers
+typy -m text -t 60 -x punctuation numbers
+
+# type a random Rust snippet
+typy -m code -l rust
 ```
 
 ## Keybindings
@@ -117,7 +159,7 @@ typy -t 60 -m punctuation
 
 | Key            | Action                                    |
 | -------------- | ----------------------------------------- |
-| letters        | type the word                             |
+| letters        | type the word / character                 |
 | `Space`        | jump to the start of the next word        |
 | `Backspace`    | delete the last character                 |
 | `Esc`          | cancel (back to home, or quit in quick run) |
@@ -136,12 +178,19 @@ typy -t 60 -m punctuation
 ## Flags
 The `typy` application supports the following flags:
 
-- `-t, --time <SECONDS>`: Duration of the test in seconds. Runs a single test immediately and exits.
-  - e.g., `typy -t 60` runs a 60 second test.
+- `-m, --mode <MODE>`: What to type — `text` (words) or `code`. Default: `text`.
+  - e.g., `typy -m code` types a random code snippet.
 
-- `-m, --mode <MODE>...`: Mode(s) to play. Runs a single test immediately.
-  - possible modes are `normal`, `uppercase` and `punctuation`.
-  - e.g., `typy -m uppercase punctuation`.
+- `-l, --language <LANG>`: Language to use (works for both modes).
+  - Text: `english`, `german`, ... (see [Language](#language)).
+  - Code: `rust`, `python`, `go`, `c`, `cpp`, `javascript`, or `any`.
+
+- `-x, --modifiers <MOD>...`: Extra text options (text mode only): `punctuation`, `numbers`,
+  `uppercase`. Combine freely.
+  - e.g., `typy -x punctuation numbers`.
+
+- `-t, --time <SECONDS>`: Test duration in seconds (text mode). Runs a single test immediately.
+  - e.g., `typy -t 60` runs a 60 second test.
 
 - `-s, --stats`: Show statistics for your past games.
 
@@ -159,9 +208,11 @@ or open it with `typy -c`. Everything below can also be changed live from the in
 
 theme = "Catppuccin Mocha"   # name of a built-in or custom theme (see Themes)
 cursor = "block"             # caret style (see Cursor)
+content = "words"            # "words" | "code" — what to type
+code_language = "any"        # code mode language: any | rust | python | go | c | cpp | javascript
 
 [modes]
-default_mode = "normal"      # "normal" | "uppercase" | "punctuation", or a combination e.g. "uppercase, punctuation"
+default_mode = "normal"      # "normal" | "uppercase" | "punctuation" | "numbers", or a combination e.g. "punctuation, numbers"
 uppercase_chance = "0.3"     # 0.0–1.0, clamped
 punctuation_chance = "0.5"   # 0.0–1.0, clamped
 
@@ -230,15 +281,23 @@ Possible values: `block`, `underline`, `bar`, and their blinking variants `blink
 `blinking underline`, `blinking bar`.
 
 ## Stats
-Your results are saved to `~/.local/share/typy/scores.json`, which keeps your last 10 games plus the
-running averages for WPM, RAW and accuracy.
+When you finish a test you get a results screen with your WPM, accuracy, and RAW numbers, plus a
+per-second graph of your run:
 
-You can view them in two ways:
+<div align="center">
+  <img src="./docs/assets/performance.png" alt="Results graph" width="680"/>
+</div>
+
+Your results are saved to `~/.local/share/typy/scores.json`, which keeps your last 10 games plus the
+running averages for WPM, RAW and accuracy. It also remembers your best WPM for each test duration,
+so you've always got a highscore to chase. You can revisit all of it any time:
 
 - In the app: press `p` on the home screen.
 - From the terminal: `typy -s`.
 
-![Stats](./docs/assets/snapshot_2025-02-24_00-28-16.png)
+<div align="center">
+  <img src="./docs/assets/stats.png" alt="Stats screen" width="640"/>
+</div>
 
 Press `Esc` or `q` to close the view.
 
@@ -257,14 +316,17 @@ it isn't there, it **downloads that one file** from GitHub
 (`raw.githubusercontent.com/Pazl27/typy-cli/.../resources/lang/<language>.txt`) and saves it locally.
 From then on it's read from disk and no network access is needed.
 
-What this means in practice:
+Code snippets work the same way: the snippet dataset is downloaded once from GitHub and then cached
+under `~/.local/share/typy/code/`.
+
+So, a few things to keep in mind:
 
-- The **first run needs an internet connection** (to fetch at least `english`). If GitHub is
-  unreachable, starting a test will fail with a download error.
-- Only the language you actually use is downloaded, not all of them.
-- Downloads always come from the `master` branch, regardless of the installed version/tag.
-- **Themes** are the exception — they are compiled into the binary and are always available offline.
-- The **Nix** package bundles `english.txt` and installs it on first launch, so Nix users work
+- The first run needs an internet connection (to fetch at least `english`, or the code dataset). If
+  GitHub is unreachable, starting a test fails with a download error.
+- Only the language you actually use gets downloaded, not all of them.
+- Downloads always come from the `master` branch, no matter which version/tag you installed.
+- Themes are the exception. They're compiled into the binary, so they always work offline.
+- The Nix package bundles `english.txt` and installs it on first launch, so Nix users are fine
   offline out of the box.
 
 To use Typy fully offline (or to pre-seed languages), copy the files yourself:
@@ -297,3 +359,4 @@ dropdown. Pull requests adding new languages to the repository are welcome.
 ```bash
 cargo uninstall typy
 ```
+</content>