@qnroa/qtype 0.0.1 → 0.0.3

package/docs/en/material-types.md

@@ -0,0 +1,241 @@
+# Material Types
+
+qtype supports six material types — `word`, `sentence`, `article`,
+`snippet`, `qa`, and `code`. Each has its own Markdown structure,
+parser rule, renderer, and interaction. This doc covers all four
+layers: **file format → parser behaviour → UI layout → interaction**.
+See `docs/zh/material-types.md` for the full Chinese reference; this
+English version summarizes the same rules.
+
+---
+
+## Common conventions
+
+### Frontmatter
+
+Every `.md` file starts with YAML frontmatter declaring the type for
+the entire file:
+
+```yaml
+---
+type: word          # one of the six types; controls how cards parse
+title: My deck      # display name, optional
+tags: [english, cet4]
+created: 2026-01-15
+updated: 2026-08-20
+---
+```
+
+- `type` decides the parse rule for every card in the file — a file
+  holds exactly one type
+- Missing `type` falls back to `article` (backward-compat with early
+  files)
+- Unknown `type` values fall back to `article` parsing and use the
+  `CardBase` renderer
+
+### Card boundary
+
+After frontmatter, the body is split into cards by **H1** (`#`):
+
+- Each H1 starts a new card
+- Prose above the first H1 is dropped
+- A chunk includes its own H1 line plus everything up to the next
+  H1 or EOF
+
+### Typing text normalisation
+
+Every "typing target" runs through `validateTypingText`:
+
+- Smart quotes → straight (`“” → ""`, `‘’ → ''`)
+- Em-dash / en-dash → hyphen
+- Emoji + zero-width chars stripped
+- Untypable codepoints collected in `card.unknownChars` → UI flags
+  the card as unplayable
+
+### Runtime `Card` shape
+
+```ts
+{
+  id: string          // "path/to/file.md#3"
+  title: string       // display heading
+  answer: string      // typing target (normalized)
+  charPlans: CharPlan[]
+  unknownChars: string[]
+  phonetic?, gloss?, image?  // word/sentence only
+  question?           // article/snippet/qa/code
+  romanization?, glyphMap?, romanizationAccepted?  // CJK cards
+}
+```
+
+For CJK cards the parser attaches pinyin (`romanization`) plus a
+`glyphMap` (roman-index → Han-index) and a per-position `accepted`
+set that handles heteronyms and rare-character wildcards. Used by
+the pinyin channel (`features/typing/pinyin`) to score the user's
+keystrokes against Hanzi answers without requiring an IME.
+
+### Rich rendering (display side only, not typed)
+
+Non-typed display slots (`## Q` prompts, article/snippet bodies,
+word/sentence gloss) run through a light Markdown renderer that
+supports:
+
+| Feature | Syntax | Notes |
+|---|---|---|
+| **Bold / italic / inline code** | `**text**` / `*text*` / `` `code` `` | Standard Markdown |
+| **Code blocks** | ` ```lang ` fence | The `code` type's answer side uses a separate Shiki path (see the code section); other positions render monospaced only |
+| **Mermaid diagrams** | ` ```mermaid ` fence | `publish build` **pre-renders to SVG** (dark + light pair); the browser just looks up and swaps — zero runtime cost |
+| **Math (LaTeX)** | inline `$...$`, block `$$...$$` | Rendered via **KaTeX**, lazy-loaded (~280KB) only when a page contains math. Can be toggled off in settings |
+
+**Everything above renders only on the display side and never
+participates in typing.** The user sees pretty formulas or diagrams
+and still types plain keyboard characters. Example:
+
+```md
+---
+type: qa
+---
+
+# Gaussian integral
+
+## Q
+Evaluate the following integral:
+
+$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = ?$$
+
+## A
+sqrt(pi)
+```
+
+The prompt renders the equation via KaTeX; `sqrt(pi)` in `## A` is
+plain ASCII the user actually types.
+
+### Universal interaction
+
+All cards render into `<TypingArena>` inside a `<CardShell>`. Shared
+behaviours:
+
+- Correct keystroke → green + advance; wrong → red (`ignorePunctuation`
+  and `ignoreCase` are opt-in relaxations)
+- Backspace pops the top char, no cross-line restriction (stack model)
+- Enter dispatches a `\n` to the engine like any other char; whether
+  it triggers a real line break comes from `target`, not user input
+- Pause is explicit: HUD ⏸ / Alt+Space / AFK / tab hidden / window blur
+- On CJK cards the pinyin channel highlights the keyboard for the
+  expected pinyin letter and colours wrong letters red in the preedit
+  bubble
+
+---
+
+## Six types at a glance
+
+| type | Body target | Extras | Auto-speak | Rendered |
+|---|---|---|---|---|
+| **word** | H1 word itself | H2 phonetic, H3 gloss, H4 image | yes | centered, big glyph |
+| **sentence** | H1 sentence | H2 phonetic, H3 translation, H4 image | yes | centered |
+| **article** | H1 body prose | inline images | no | flow (top-aligned) |
+| **snippet** | H1 body (short) | inline images | no | centered "poster" |
+| **qa** | `## A` block | `## Q` block | no | flow |
+| **code** | `## A` fenced code | `## Q` block | no | flow, Shiki (opt-in) |
+
+### word / sentence
+
+```md
+# apple
+## /ˈæp.əl/
+### the fruit
+#### ![](https://…/apple.jpg)
+```
+
+Layout: target word/sentence big and centered; a floating speak button
+sits absolute to its right so the target stays optically centered.
+Auto-speak fires once per card when unpaused (deduped by `card.id`).
+
+### article
+
+```md
+# Autumn Morning
+
+The mist hung low over the valley…
+```
+
+Long-form prose. Images in the body are extracted and rendered above
+the arena (source-mode) but stripped from the typing text (the arena
+itself types only characters). Title is centered; body left-aligned
+(standard document typography).
+
+### snippet
+
+Same shape as `article` but rendered **vertically centered with
+centered text** — for poems, aphorisms, slogans, or any short
+composition where visual balance beats reading flow.
+
+### qa
+
+```md
+# What is a closure?
+
+## Q
+Explain JavaScript closures with an example.
+
+## A
+A closure is a function bundled with its lexical scope…
+```
+
+`## Q` renders through `<MdRenderer>` (full markdown — lists, code
+blocks, images all display). `## A` is the typing target as **raw
+markdown text**: users type the `-`, `**`, backticks, etc. verbatim.
+
+### code
+
+Same shape as `qa` but the `## A` block is expected to hold a fenced
+code fence. The parser strips the ``` markers, keeping the code body
+as the typing target. Language is detected from the fence tag or the
+filename, and Shiki syntax highlighting is applied when
+`qtype.codeSyntaxHighlight` is on (off by default — pending/hit/miss
+colours suffice for muscle-memory training and disabling avoids the
+~1MB Shiki bundle).
+
+---
+
+## Dispatch
+
+`CardView` switches on `material.meta.type`:
+
+```tsx
+switch (type) {
+  case 'word':     return <WordCard {...props} />
+  case 'sentence': return <SentenceCard {...props} />
+  case 'article':  return <ArticleCard {...props} />
+  case 'snippet':  return <SnippetCard {...props} />
+  case 'qa':       return <QaCard {...props} />
+  case 'code':
+    return (
+      <Suspense fallback={<QaCard {...props} />}>
+        <CodeCard {...props} />
+      </Suspense>
+    )
+  default:         return <CardBase {...props} />
+}
+```
+
+`CodeCard` is lazy-loaded via `React.lazy` because Shiki is heavy.
+Unknown types fall back to `CardBase` (bare `<TypingArena>`).
+
+---
+
+## FAQ
+
+**Can I mix types in one file?** No — `type` is material-level.
+
+**Can `word` H2 span multiple lines?** No — regex only matches one
+line; extra lines are ignored.
+
+**In `article`, why can't I type images?** Image markdown is stripped
+from the typing target. If you need users to type image references,
+use `qa` and put them in `## A`.
+
+**In `qa`, do users type the `- ` and `**` too?** Yes — the answer
+is preserved as raw markdown so users practise those symbols.
+
+**What if `code` has an unknown fence language?** Shiki silently
+falls back to plain text; typing still works normally.

package/docs/en/settings.md

@@ -0,0 +1,133 @@
+# Settings reference
+
+Chinese: [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/settings.md)
+
+qtype has **two independent settings stores**:
+
+1. **Repo/CLI config** — via `qtype config`, stored at
+   `~/.config/qtype/config.json` (user) + `<repo>/.qtype/config.json`
+   (repo). See [cli-reference.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/cli-reference.md#qtype-config-get--set--unset--list).
+2. **Reader UI settings** — everything the user opens the gear icon
+   to change, stored in the browser's kv store (`qtype.config.user`
+   blob). This document covers those.
+
+Reader settings **live in the browser only** — they don't hit
+`qtype config`, don't enter git, and don't affect the CLI. To sync to
+another machine, use browser sync or the manual import/export below.
+
+---
+
+## Appearance
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `qtype.themeMode` | `auto` / `mocha` / `latte` | `auto` | Theme (dark / light / follow system) |
+| `qtype.uiLang` | `auto` / `zh-CN` / `en-US` | `auto` | UI language |
+| `qtype.typingFontSize` | `s` / `m` / `l` | `m` | Arena font size |
+| `qtype.letterSpacing` | `tight` / `normal` / `wide` | `normal` | Letter spacing |
+| `qtype.spaceGlyph` | `dot` / `dash` / `blank` | `dash` | How the target's spaces are drawn |
+| `qtype.breakWord` | boolean | true | Break long words to fit the arena width |
+
+---
+
+## Typing rules
+
+Deeper semantics in [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/typing-rules.md).
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `qtype.hint` | `off` / `ghost` | `off` | Show ghost hint under the target |
+| `qtype.ignoreCase` | boolean | false | Case-insensitive comparison |
+| `qtype.ignorePunctuation` | boolean | false | Ignore punctuation variants (smart quotes / full-width) |
+| `qtype.allowBackspace` | boolean | true | Allow Backspace to undo |
+| `qtype.tabBehavior` | `reset` / `input` | `reset` | Tab: reset the card / expand to spaces |
+| `qtype.tabWidth` | `2` / `4` | `4` | Spaces per Tab when `tabBehavior=input` |
+| `qtype.completionMode` | `through` / `perfect` / `lenient` | `through` | Bar to count a card as done (see typing-rules) |
+| `qtype.retryOnFail` | `off` / `auto` / `immediate` | `off` | Auto-retry policy on failure |
+| `qtype.maxRetries` | 0-20 | 5 | Auto-retry cap; 0 = unlimited |
+| `qtype.maxWrongRate` | 0-100 | 0 | Error-rate threshold (%); above it locks; 0 = off |
+| `qtype.targetWpm` | 0-500 | 0 | Target WPM (shadow-cursor pacer); 0 = off |
+
+---
+
+## Audio
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `qtype.keySoundEnabled` | boolean | false | Key click sound |
+| `qtype.keySoundVolume` | 0-100 | 40 | Key sound volume |
+| `qtype.errorSoundEnabled` | boolean | false | Error sound |
+| `qtype.errorSoundVolume` | 0-100 | 60 | Error sound volume |
+| `qtype.completeSoundEnabled` | boolean | true | Sound when a material finishes |
+| `qtype.autoSpeak` | boolean | true | Auto-speak on word / sentence card switch |
+| `qtype.autoSpeakRepeat` | 1-5 | 1 | Auto-speak repeat count |
+| `qtype.ttsProvider` | `browser` / `youdao` / `google` | `browser` | TTS backend |
+| `qtype.ttsVolume` | 0-100 | 100 | Speech volume |
+| `qtype.ttsRate` | 50-200 | 100 | Speech rate (%) |
+
+---
+
+## Interface
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `qtype.showKeyboard` | boolean | true | Show on-screen keyboard |
+| `qtype.showHands` | boolean | true | Overlay finger-position hints on the keyboard |
+| `qtype.keyboardSize` | `s` / `m` / `l` | `m` | On-screen keyboard size |
+| `qtype.autoHideCursor` | boolean | true | Auto-hide cursor after 3s of no movement |
+| `qtype.showNeighborPreview` | boolean | true | Show prev / next card previews on the sides |
+| `qtype.showPhonetic` | boolean | true | Show phonetic line on word / sentence |
+| `qtype.showGloss` | boolean | true | Show gloss on word / sentence |
+| `qtype.showResultPopup` | boolean | true | Result popup on completion (WPM / accuracy) |
+| `qtype.speedUnit` | `wpm` / `cpm` | `wpm` | Speed unit — words vs characters per minute |
+| `qtype.afkSeconds` | 5-300 | 60 | Idle seconds → auto-pause (see [typing-rules](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/typing-rules.md#afk-auto-pause)) |
+| `qtype.minAccuracy` | 0-100 | 0 | Warn below this accuracy; 0 = off |
+| `qtype.codeSyntaxHighlight` | boolean | false | Shiki highlighting on `code` cards (off by default, ~1MB bundle) |
+| `qtype.mathRenderer` | boolean | true | Render `$...$` / `$$...$$` via KaTeX (lazy-loaded ~280KB) |
+
+---
+
+## Side stores
+
+A few large / structured pieces of state live alongside the main
+blob, still in the same kv layer:
+
+| Key | Content | Notes |
+|---|---|---|
+| `qtype.doneState` | `Record<file, Record<idx, CardStats[]>>` | Per-card WPM / accuracy history — powers the home sparkline |
+| `qtype.handOffsets` | Keyboard calibration | Offsets from the default layout |
+| `qtype.keybindings` | Shortcut rebindings | See [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/shortcuts.md) |
+
+The v2 kv migration folded these into the unified blob so they travel
+with import / export alongside theme / hint / etc.
+
+---
+
+## Import / export
+
+The **Data** tab in the Settings dialog has buttons to export /
+import:
+
+- Export → `qtype-settings.json` — every key above plus all three
+  side stores
+- Import → overwrites the current values; each key is schema-validated
+  before being written
+
+**Import is a full overwrite, not a merge.** To change just one or
+two values, use the UI or call `kvSet('key', value)` directly.
+
+---
+
+## Can the CLI read reader settings?
+
+**No.** The keys above **only exist in the browser** and the CLI has
+no access. The split is intentional:
+
+- Who writes cards / who publishes → CLI-layer config (`qtype config`,
+  lives in git)
+- Who types in the browser → reader-layer settings (browser kv,
+  per-device)
+
+If you want e.g. team-wide default font size, that's **not possible
+today**. Reader settings are "each reader's private preference"; CLI
+settings are "part of the artifact".

package/docs/en/shortcuts.md

@@ -0,0 +1,89 @@
+# Keyboard shortcuts
+
+Chinese: [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/shortcuts.md)
+
+Every shortcut in the reader. This is the **factory default**;
+everything can be rebound in Settings → Shortcuts. Rebindings live in
+browser kv (not in git, per-device).
+
+## Global (any page)
+
+| Action | mac | Windows / Linux | Notes |
+|---|---|---|---|
+| Open command palette | `Cmd+K` | `Ctrl+K` | ⌘K-style launcher — search any action / material |
+| Palette (commands only) | `Cmd+Shift+P` | `Ctrl+Shift+P` | Actions only, no materials |
+
+## Typing route
+
+### HUD (top status bar)
+
+| Action | mac | Windows / Linux | Notes |
+|---|---|---|---|
+| Pause / resume | `Alt+Space` | `Alt+Space` | Also the ⏸ button on the HUD |
+| Toggle ghost hint | `Alt+H` | `Alt+Shift+H` | Show a faded target under the arena |
+| Toggle on-screen keyboard | `Alt+K` | `Alt+K` | Keyboard visibility |
+| Toggle finger overlay | `Alt+J` | `Alt+J` | Hand positions on the keyboard |
+| Back to home | `Alt+R` | `Alt+R` | Leave the current material |
+
+### Card navigation
+
+| Action | mac | Windows / Linux | Notes |
+|---|---|---|---|
+| Previous card | `Alt+Shift+←` | `Alt+Shift+←` | Within the current deck |
+| Next card | `Alt+Shift+→` | `Alt+Shift+→` | Within the current deck |
+
+### Palette-only (no default binding)
+
+These have **no shipped shortcut** — access via the command palette:
+
+- **Jump to card N** — `card.jump`
+- **Pick theme** — `pick.theme`
+- **Toggle hint mode** — `hint.toggle`
+- **Open settings** — `settings.open`
+- **Search materials** — `search.materials`
+- **Grid / list view** — `view.grid` / `view.list` (home only)
+- **Reload current material** — `material.reload`
+- **Jump to a random material** — `material.random`
+- **Clear all done state** — `done.clearAll`
+- **Reset filters** — `filter.reset`
+
+Bind any of them in Settings → Shortcuts by clicking the row and
+pressing a key combo.
+
+## Typing keys (engine behaviour, not remappable)
+
+The arena's own key handling — not counted as "actions", not
+rebindable:
+
+| Key | Behaviour |
+|---|---|
+| Letters / digits / punctuation / space | Correct → cursor advances, char goes green; wrong → red, cursor holds |
+| `Backspace` | Undo one char (unless `allowBackspace: false`, see [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/typing-rules.md)) |
+| `Enter` | Types the newline target char (not "submit") |
+| `Tab` | Per `tabBehavior`: reset the card, or expand to 2 or 4 spaces |
+| `Escape` | Blur the arena (does not pause) |
+| `←` `→` `↑` `↓` `Home` `End` | **Ignored** — a typing tool doesn't need caret movement |
+
+## Rebinding
+
+**Settings → Shortcuts**:
+- Every action shows its label + current binding
+- Click a row → press a new combo (recording mode)
+- Escape cancels the recording, Delete clears the binding
+- Conflict detection: two actions on the same combo → warning
+- "Reset defaults" button restores factory bindings
+
+**Where the rebindings live**: `qtype.keybindings` in browser kv,
+folded into the main config blob by v2 migration; they travel with
+import / export (see [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/settings.md)).
+
+## Platform differences
+
+**Mac** and **Windows / Linux** have separate default tables. Most
+actions use plain `Alt` combos that don't clash on either OS; a few
+use `Cmd` (mac) vs `Ctrl` (Windows / Linux) to match native muscle
+memory.
+
+Platform detection is **runtime** (`navigator.platform` /
+`userAgent`), not build-time — one dist works for every visitor
+regardless of OS.

package/docs/en/typing-rules.md

@@ -0,0 +1,208 @@
+# Typing rules
+
+Chinese: [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/typing-rules.md)
+
+A bunch of knobs govern "what counts as a correct keystroke / when a
+card is done / when to auto-retry". Everything's toggleable in
+Settings; the full switch list is in [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/settings.md).
+
+This doc explains the **semantics** and gives some **preset combos**.
+
+---
+
+## Input matching
+
+### `ignoreCase` (default off)
+
+**On**: typing `a` matches target `A` — miss-shifts don't count as
+wrong.
+
+**Off**: case must match exactly.
+
+**Turn on** when learning positions and don't want to fight Shift.
+**Off** for prose typing where you want the rigour.
+
+### `ignorePunctuation` (default off)
+
+**On**: the engine **skips over punctuation slots** — the target's
+`.` `,` `!` `?` `。` `,` etc. auto-advance without a user keystroke.
+
+**Off**: punctuation must be typed too.
+
+**Turn on** when practising English prose and just care about the
+words. **Off** for exact transcription (legal text / poems / code).
+
+### `allowBackspace` (default on)
+
+**On**: Backspace undoes one char — mistakes are recoverable.
+
+**Off**: Backspace is inert; you carry the mistake forward and rely
+on `retryOnFail` / `maxWrongRate` to bail out.
+
+**Turn off** to simulate a strict-mode exam.
+
+---
+
+## Input limits
+
+### `maxWrongRate` (default 0 = off, range 0-100)
+
+Wrong-rate ceiling in percent. **Above** the limit, the engine:
+- auto-undoes the last wrong char
+- fires an error toast ("wrong rate exceeded X%")
+
+E.g. `maxWrongRate: 5` → accumulated wrong rate > 5% forces auto-undo
+on the next mistake, throttling you back.
+
+**Turn on** to train accuracy over speed. **Leave 0** to allow errors
+as long as you finish the pass.
+
+### `retryOnFail` (default `off`)
+
+Auto-retry policy when a pass finishes without meeting `completionMode`:
+
+- **`off`** — no auto-retry; user has to `Alt+R` manually
+- **`auto`** — pass finished + gate rejected → shake the arena + reset
+- **`immediate`** — stricter: **any single wrong char** triggers reset
+  (doesn't wait for the pass to finish)
+
+**maxRetries** (0-20, default 5): cap on auto-retries. Beyond that,
+`onSkip` fires (route usually advances to the next card). 0 =
+unlimited.
+
+**Sample combos**:
+- `retryOnFail: auto` + `completionMode: perfect` → every card must
+  be zero-error to pass, else reset from scratch
+- `retryOnFail: immediate` + `maxRetries: 3` → 3 instant resets, then
+  skip
+
+---
+
+## Completion
+
+### `completionMode` (default `through`)
+
+"When the last char is typed, does the card count as done?"
+
+- **`through`** — yes, as soon as you reach the end (default, most
+  lenient)
+- **`lenient`** — yes if wrong rate ≤ 5%
+- **`perfect`** — yes only when zero errors
+
+**"Not done" outcome** depends on `retryOnFail`:
+- `off` → card shows as "finished but not passed"; user can continue
+- `auto` → reset from scratch
+- `immediate` → strict mode; you rarely reach the end in this branch
+  (a wrong char already reset you)
+
+**Independence**: completionMode and retryOnFail are two separate
+knobs:
+- completionMode decides "what counts as done"
+- retryOnFail decides "what to do when not done"
+
+---
+
+## Tab key
+
+### `tabBehavior` (default `reset`)
+
+- **`reset`** — Tab resets the current card (typical typing-tool
+  convention)
+- **`input`** — Tab is real input, expands to `tabWidth` spaces (for
+  code)
+
+### `tabWidth` (2 or 4, default 4)
+
+When `tabBehavior: input`, one Tab = N spaces.
+
+**Python usually 4, Go / shell 2**. The target code in a `code` card
+should use one indent style consistently — qtype only shapes user
+input, it doesn't rewrite the target.
+
+---
+
+## Target-speed pacer
+
+### `targetWpm` (default 0 = off, range 0-500)
+
+Turn on to render a **shadow cursor** that advances at the target
+speed. Your actual cursor being ahead / behind tells you at a glance.
+
+E.g. `targetWpm: 40` → the shadow marches at 40 WPM; matching it
+means you're hitting 40.
+
+0 turns it off. Doesn't affect correctness judging — pure metronome.
+
+---
+
+## AFK auto-pause
+
+### `afkSeconds` (default 60, range 5-300)
+
+Seconds of no "activity" before auto-pausing.
+
+**Activity = keydown / mousemove / wheel / touchstart / touchmove.**
+Mouse hovering without moving **counts as AFK**. Switching tabs or
+losing window focus **pauses immediately** without waiting for the
+timeout.
+
+Once paused the arena greys out and refuses input; `Alt+Space` or
+the HUD ▶ resumes.
+
+**Why default 60**: gives room to think. Drop to 15 or 30 for strict
+timing.
+
+---
+
+## Preset combos
+
+### "Beginner — chill mode"
+```
+ignoreCase: on
+ignorePunctuation: on
+allowBackspace: on
+completionMode: through
+retryOnFail: off
+maxWrongRate: 0
+```
+Anything goes; finishing counts. Build speed over time.
+
+### "Daily practice" (recommended default)
+```
+ignoreCase: off
+ignorePunctuation: off
+allowBackspace: on
+completionMode: through
+retryOnFail: auto
+maxRetries: 3
+maxWrongRate: 0
+```
+Mistakes recoverable; on too many, retry up to 3 then skip.
+
+### "Exam-strict"
+```
+ignoreCase: off
+ignorePunctuation: off
+allowBackspace: off
+completionMode: perfect
+retryOnFail: immediate
+maxRetries: 0
+```
+Errors instantly reset; no backspace; zero-error required.
+
+### "Sweep-through, don't grind"
+```
+ignoreCase: on
+ignorePunctuation: on
+completionMode: through
+retryOnFail: off
+```
+Speed-run the deck once, record WPM, don't perfectionist your way
+in.
+
+---
+
+## Related
+
+- Where each knob lives in the UI: [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/settings.md)
+- Shortcuts (pause / prev / next): [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/shortcuts.md)