@qnroa/qtype 0.0.2 → 0.0.4

package/docs/zh/settings.md

@@ -0,0 +1,120 @@
+# Settings 参考
+
+English: [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/settings.md)
+
+qtype 有**两套设置**,分开管:
+
+1. **仓库/命令级配置** —— 走 `qtype config`,存在 `~/.config/qtype/config.json`(user 层)+ `<repo>/.qtype/config.json`(repo 层)。见 [cli-reference.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/cli-reference.md#qtype-config-get--set--unset--list)
+2. **浏览器/阅读器界面设置** —— 用户在 view 里点齿轮打开的设置对话框,存在浏览器 kv(`qtype.config.user` blob)。这是本文档的内容
+
+阅读器界面设置**只影响本浏览器**,不进 `qtype config`,不进 git,也不影响 CLI。想同步到别的机器可以走浏览器同步 / 手动导出。
+
+---
+
+## Appearance(外观)
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `qtype.themeMode` | `auto` / `mocha` / `latte` | `auto` | 主题(dark / light / 跟系统) |
+| `qtype.uiLang` | `auto` / `zh-CN` / `en-US` | `auto` | 界面语言 |
+| `qtype.typingFontSize` | `s` / `m` / `l` | `m` | 打字区字体大小 |
+| `qtype.letterSpacing` | `tight` / `normal` / `wide` | `normal` | 字符间距 |
+| `qtype.spaceGlyph` | `dot` / `dash` / `blank` | `dash` | 打字目标里的空格显示成什么 |
+| `qtype.breakWord` | boolean | true | 单词过长时是否内部断行 |
+
+---
+
+## Typing rules(打字规则)
+
+详细语义见 [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/typing-rules.md)。
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `qtype.hint` | `off` / `ghost` | `off` | 是否显示 ghost 目标提示 |
+| `qtype.ignoreCase` | boolean | false | 大小写不敏感对比 |
+| `qtype.ignorePunctuation` | boolean | false | 忽略标点差异(智能引号 / 全半角) |
+| `qtype.allowBackspace` | boolean | true | 允许 Backspace 撤销 |
+| `qtype.tabBehavior` | `reset` / `input` | `reset` | Tab 键:重置本卡 / 当空格输入 |
+| `qtype.tabWidth` | `2` / `4` | `4` | tabBehavior=input 时一个 Tab 展开几个空格 |
+| `qtype.completionMode` | `through` / `perfect` / `lenient` | `through` | 完成一张卡的门槛(见 typing-rules.md) |
+| `qtype.retryOnFail` | `off` / `auto` / `immediate` | `off` | 失败自动重试策略 |
+| `qtype.maxRetries` | 0-20 | 5 | 自动重试上限,0 = 无限 |
+| `qtype.maxWrongRate` | 0-100 | 0 | 错误率阈值(%),超过就锁字。0 = 关闭 |
+| `qtype.targetWpm` | 0-500 | 0 | 目标 WPM(带阴影光标做节拍器)。0 = 关闭 |
+
+---
+
+## Audio(音效)
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `qtype.keySoundEnabled` | boolean | true | 按键点击音 |
+| `qtype.keySoundVolume` | 0-100 | 40 | 按键音音量 |
+| `qtype.errorSoundEnabled` | boolean | true | 错误提示音 |
+| `qtype.errorSoundVolume` | 0-100 | 60 | 错误音音量 |
+| `qtype.completeSoundEnabled` | boolean | true | 完成整个 material 时的音效 |
+| `qtype.autoSpeak` | boolean | true | word / sentence 卡切卡时自动朗读 |
+| `qtype.autoSpeakRepeat` | 1-5 | 1 | 自动朗读重复次数 |
+| `qtype.ttsProvider` | `browser` / `youdao` / `google` | `browser` | TTS 提供方 |
+| `qtype.ttsVolume` | 0-100 | 100 | 朗读音量 |
+| `qtype.ttsRate` | 50-200 | 100 | 朗读语速(%) |
+
+---
+
+## Interface(界面)
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `qtype.showKeyboard` | boolean | true | 显示屏幕键盘 |
+| `qtype.showHands` | boolean | true | 屏幕键盘上叠加双手指法 |
+| `qtype.keyboardSize` | `s` / `m` / `l` | `m` | 屏幕键盘大小 |
+| `qtype.autoHideCursor` | boolean | true | 3 秒无鼠标移动自动隐藏鼠标 |
+| `qtype.showNeighborPreview` | boolean | true | 左右显示前后卡预览 |
+| `qtype.showPhonetic` | boolean | true | word / sentence 卡默认显示音标 |
+| `qtype.showGloss` | boolean | true | word / sentence 卡默认显示释义 |
+| `qtype.showResultPopup` | boolean | true | 完成后弹窗显示 WPM / 准确率 |
+| `qtype.speedUnit` | `wpm` / `cpm` | `wpm` | 速度单位:词 / 字符每分钟 |
+| `qtype.afkSeconds` | 5-300 | 60 | 多少秒无输入自动暂停(见 [typing-rules](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/typing-rules.md#afk-自动暂停)) |
+| `qtype.minAccuracy` | 0-100 | 0 | 准确率低于此值时提示,0 = 关闭 |
+| `qtype.codeSyntaxHighlight` | boolean | false | code 卡启用 Shiki 语法高亮(默认关,~1MB bundle) |
+| `qtype.mathRenderer` | boolean | true | 用 KaTeX 渲染 `$...$` / `$$...$$` 数学公式(懒加载 ~280KB) |
+
+---
+
+## Side stores(独立存储的数据)
+
+有几类数据不走上面的单 blob,单独存:
+
+| 键 | 内容 | 说明 |
+|---|---|---|
+| `qtype.doneState` | `Record<file, Record<idx, CardStats[]>>` | 每张卡的历次 WPM / 准确率 —— 首页 sparkline 数据源 |
+| `qtype.handOffsets` | 键盘校准 | 按键位置相对默认布局的偏移 |
+| `qtype.keybindings` | 快捷键重绑 | 见 [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/shortcuts.md) |
+
+这三个都由 v2 kv migration 收编到统一 blob 里,内部还是独立的子 map,
+但从 UI 视角看是**唯一 blob** —— `handOffsets` / `keybindings` 也会跟着
+theme / hint 一起进导入导出。
+
+---
+
+## 导入 / 导出
+
+Settings 面板的**「数据」**标签页有导入 / 导出按钮:
+
+- 导出 → `qtype-settings.json`,包含上面全部设置 + 三类 side store
+- 导入 → 覆盖当前值,进 kv 前会经过 schema 校验
+
+**导入不会合并**,是完整覆盖。如果只想改一两个值,直接用 UI 或代码里
+`kvSet('key', value)`。
+
+---
+
+## 让 CLI 感知界面设置?
+
+**不能**。上面这些设置**只在浏览器里存在**,CLI 读不到 —— 分工是:
+
+- 谁写卡片 / 谁 publish → CLI 层设置(`qtype config`,进 git)
+- 谁在浏览器里练 → 界面层设置(浏览器 kv,per-device)
+
+比如你想让全 team 用一样的默认字体大小 —— 现在**做不到**。这是有意的
+设计:CLI 层是「作品的一部分」,界面层是「每个人自己的阅读偏好」。

package/docs/zh/shortcuts.md

@@ -0,0 +1,83 @@
+# 快捷键
+
+English: [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/shortcuts.md)
+
+阅读器里的键盘快捷键。这份是**出厂默认**;每一项都可以在 Settings →
+Shortcuts 里重绑,重绑的值存在浏览器 kv 里(不进 git,per-device)。
+
+## 全局(任何页面)
+
+| 动作 | mac | Windows / Linux | 说明 |
+|---|---|---|---|
+| 打开命令面板 | `Cmd+K` | `Ctrl+K` | ⌘K 风格的 launcher,可以搜任何动作 / material |
+| 命令面板(纯命令) | `Cmd+Shift+P` | `Ctrl+Shift+P` | 只筛动作,不带 material |
+
+## 打字页(typing route)
+
+### HUD(顶部状态栏)
+
+| 动作 | mac | Windows / Linux | 说明 |
+|---|---|---|---|
+| 暂停 / 继续 | `Alt+Space` | `Alt+Space` | 也可以点 HUD 上的 ⏸ 按钮 |
+| 切换 ghost 提示 | `Alt+H` | `Alt+Shift+H` | 在打字目标下方显示褪色目标提示 |
+| 切换屏幕键盘 | `Alt+K` | `Alt+K` | 屏幕键盘可见性 |
+| 切换手部指法 | `Alt+J` | `Alt+J` | 屏幕键盘上叠加双手指法 |
+| 返回首页 | `Alt+R` | `Alt+R` | 退出当前 material |
+
+### 卡片导航
+
+| 动作 | mac | Windows / Linux | 说明 |
+|---|---|---|---|
+| 上一张卡 | `Alt+Shift+←` | `Alt+Shift+←` | 卡组内往前跳 |
+| 下一张卡 | `Alt+Shift+→` | `Alt+Shift+→` | 卡组内往后跳 |
+
+### 仅命令面板(无默认按键)
+
+以下动作**没有出厂快捷键**,只能在命令面板里搜到用:
+
+- **跳到卡片 N** —— `card.jump`,输入卡号跳过去
+- **换主题** —— `pick.theme`
+- **切换 hint 模式** —— `hint.toggle`
+- **打开设置** —— `settings.open`
+- **搜索 material** —— `search.materials`
+- **切网格视图 / 列表视图** —— `view.grid` / `view.list`(仅首页)
+- **重新加载当前 material** —— `material.reload`
+- **随机跳到一张 material** —— `material.random`
+- **清空所有完成记录** —— `done.clearAll`
+- **重置筛选器** —— `filter.reset`
+
+想给它们绑快捷键,在 Settings → Shortcuts 里点对应行 → 按新的键组合。
+
+## 打字时的键(不算「快捷键」,是引擎行为)
+
+这些是打字过程本身的按键处理,不算可重绑的动作:
+
+| 键 | 行为 |
+|---|---|
+| 字母 / 数字 / 标点 / 空格 | 打对 → 光标前进 + 变绿;打错 → 变红,光标不动 |
+| `Backspace` | 撤销一个字符(除非 `allowBackspace: false`,见 [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/typing-rules.md)) |
+| `Enter` | 打进「换行」目标字符(不是提交) |
+| `Tab` | 按 `tabBehavior` 设置:重置本卡 / 输入 2 或 4 个空格 |
+| `Escape` | 让打字区失焦(不暂停) |
+| `←` `→` `↑` `↓` `Home` `End` | **被忽略**(打字工具不需要移动光标) |
+
+## 重绑
+
+**Settings → Shortcuts**:
+- 每一行显示动作名 + 当前绑定
+- 点行 → 按新键组合(录制模式)
+- Escape 取消录制,Delete 清空绑定
+- 冲突检测:两个动作绑同一键会警告
+- 「重置默认」按钮恢复所有出厂值
+
+**重绑存在哪**:浏览器 kv `qtype.keybindings`,由 v2 migration 收进
+主 blob,导入 / 导出会跟着走(见 [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/settings.md))。
+
+## 平台差异
+
+**Mac** 和 **Windows / Linux** 分开定义。你会看到大部分动作两平台一样
+(纯 Alt 组合无 OS 冲突),但少数用了 `Cmd` vs `Ctrl` —— 用户在 mac 上
+习惯 Cmd,在 Windows 上习惯 Ctrl。
+
+检测平台是**运行时判断**(`navigator.platform` / `userAgent`),不是构建时。
+所以一个 dist 部署到跨平台的用户都能用。

package/docs/zh/typing-rules.md

@@ -0,0 +1,191 @@
+# 打字规则
+
+English: [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/typing-rules.md)
+
+qtype 有一堆可调的打字规则,决定「打对 / 打错 / 什么时候算完成 / 什么时候
+自动重试」。所有规则都在 Settings 里能改;开关一览见 [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/settings.md)。
+
+本文档讲清每个规则的**语义 + 常见组合**。
+
+---
+
+## 输入判定
+
+### `ignoreCase`(默认 off)
+
+**开启**:输入 `a` 也能匹配目标 `A`;英文卡里按 Shift 按错也不算错。
+
+**关闭**:大小写必须完全一致。
+
+**什么时候开**:早期练指法、不用记 Shift 位置。**关掉**:练英文段落、
+要保持严谨。
+
+### `ignorePunctuation`(默认 off)
+
+**开启**:引擎在打字时**跳过标点**——目标里出现 `.` `,` `!` `?` `。` `,`
+等自动向前推进,不需要用户敲。
+
+**关闭**:标点也要打对。
+
+**什么时候开**:练英文文章、只关心单词部分,不想打 `,` 打错。**关掉**:
+练精确抄写(法律文书 / 诗词 / 代码)。
+
+### `allowBackspace`(默认 on)
+
+**开启**:Backspace 撤销一个字符,可以退回改错。
+
+**关闭**:Backspace 无效,打错就得往前走(用 `retryOnFail` / `maxWrongRate` 补救)。
+
+**什么时候关**:模拟考试严格模式、让用户敲完整句不能反悔。
+
+---
+
+## 输入限制
+
+### `maxWrongRate`(默认 0 = 关闭,范围 0-100)
+
+上限错误率(%)。**超过**这个值时:
+- 引擎自动 undo 用户最后一个错字
+- HUD 出错误 toast(「错误率超过 X%」)
+
+例:`maxWrongRate: 5` → 累计错误率 > 5% 时,打错就自动回退,强迫用户
+放慢速度。
+
+**什么时候开**:想练准确率而非速度。**留 0**:允许边打边错、只要最终
+过完就行。
+
+### `retryOnFail`(默认 `off`)
+
+「打完这一张但没达到 `completionMode` 门槛」时的自动重试策略。
+
+- **`off`** —— 不自动重试。用户手动 `Alt+R` 才回到卡首
+- **`auto`** —— 完成 + 门槛未过 → arena 抖一下(shake)+ 从头开始
+- **`immediate`** —— 更严格:**打错任何一个字**就立刻重来(不等完成)
+
+**maxRetries**(0-20,默认 5):自动重试上限。超过就调 `onSkip` 让路由决定
+(通常直接进下一张)。0 = 无限重试。
+
+**组合示例**:
+- `retryOnFail: auto` + `completionMode: perfect` → 每卡必须零错才能过,
+  否则从头
+- `retryOnFail: immediate` + `maxRetries: 3` → 3 次立即重试失败就跳过
+
+---
+
+## 完成判定
+
+### `completionMode`(默认 `through`)
+
+「一张卡打完时,算不算 done?」
+
+- **`through`** —— 只要敲到最后一个字就算完成(默认,最宽松)
+- **`lenient`** —— 错误率 ≤ 5% 才算完成
+- **`perfect`** —— 零错才算完成
+
+**「不算完成」**发生什么:取决于 `retryOnFail`:
+- `off` → 卡显示为「结束但未完成」,用户可以手动继续下一张
+- `auto` → 从头开始
+- `immediate` → 严格模式下,一般在打错时就已经自动重来了,不会走到这
+
+**组合**:completionMode 和 retryOnFail 是**独立**的两个开关:
+- completionMode 决定「什么叫完成」
+- retryOnFail 决定「没完成时怎么办」
+
+---
+
+## Tab 键行为
+
+### `tabBehavior`(默认 `reset`)
+
+- **`reset`** —— 按 Tab 重置整张卡(打字工具常见约定)
+- **`input`** —— Tab 作为输入,展开成 `tabWidth` 个空格(练代码常用)
+
+### `tabWidth`(2 或 4,默认 4)
+
+`tabBehavior: input` 时,一个 Tab 键 = 几个空格。
+
+**练 Python 通常用 `4`,练 Go 或 shell 用 `2`**。代码卡里的目标应该用一致的
+缩进方式(全是空格或全是 tab 对齐)——qtype 只处理输入,不改目标。
+
+---
+
+## 目标速度提示
+
+### `targetWpm`(默认 0 = 关闭,范围 0-500)
+
+打开后,arena 里显示一个**影子光标**,按目标速度前进。你的实际光标追上
+或落后于它,肉眼就能判断快慢。
+
+例:`targetWpm: 40` → 影子按 40 WPM 匀速前进,你要追上它 = 达到 40 WPM。
+
+设 0 关闭。开着不影响打字判定,只是节拍器。
+
+---
+
+## AFK 自动暂停
+
+### `afkSeconds`(默认 60,范围 5-300)
+
+多长时间没「活动」就自动暂停。
+
+**「活动」= keydown / mousemove / wheel / touchstart / touchmove**。**鼠标
+悬停不动也算 AFK**(不算移动)。切 tab 或窗口失焦会**立刻**暂停,不等
+AFK 超时。
+
+暂停后 arena 变灰,不接受输入,需要 `Alt+Space` 或 HUD 上的 ▶ 恢复。
+
+**为什么默认 60**:留出思考的时间。想要严格计时,调到 15 或 30。
+
+---
+
+## 组合方案参考
+
+### 「刚入门,佛系练」
+```
+ignoreCase: on
+ignorePunctuation: on
+allowBackspace: on
+completionMode: through
+retryOnFail: off
+maxWrongRate: 0
+```
+不管对错,打完就下一张,慢慢积累速度。
+
+### 「日常练打字」(推荐默认)
+```
+ignoreCase: off
+ignorePunctuation: off
+allowBackspace: on
+completionMode: through
+retryOnFail: auto
+maxRetries: 3
+maxWrongRate: 0
+```
+错了能改,过多重来 3 次跳过。
+
+### 「模拟考试严格模式」
+```
+ignoreCase: off
+ignorePunctuation: off
+allowBackspace: off
+completionMode: perfect
+retryOnFail: immediate
+maxRetries: 0
+```
+打错立刻重来,不允许改,零错才过。
+
+### 「快速刷完不 grind」
+```
+ignoreCase: on
+ignorePunctuation: on
+completionMode: through
+retryOnFail: off
+```
+所有卡走一遍,记录 WPM,不磨完美主义。
+
+---
+
+## 相关文档
+
+- 每个规则的开关位置:[settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/settings.md)
+- 快捷键(暂停 / 上一张 / 下一张):[shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/shortcuts.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qnroa/qtype",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Turn Markdown notes into typing practice — CLI + review + static-site publisher",
   "keywords": [
     "typing",
@@ -11,8 +11,7 @@
     "static-site-generator",
     "spaced-repetition",
     "chinese-typing",
-    "pinyin",
-    "qrism"
+    "pinyin"
   ],
   "license": "Apache-2.0",
   "author": "Qnroa",
@@ -35,12 +34,7 @@
     "LICENSE",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
-    "!docs/**/release.md",
-    "!docs/**/cli-internals.md",
-    "!docs/**/architecture.md",
-    "!docs/**/core-architecture.md",
-    "!docs/**/cli-architecture.md",
-    "!docs/**/view-architecture.md"
+    "!docs/**/architecture.md"
   ],
   "exports": {
     "./core": "./dist/core/index.js",
@@ -62,10 +56,18 @@
   },
   "dependencies": {
     "@noble/hashes": "^2.2.0",
+    "@radix-ui/react-popover": "^1.1.23",
+    "@radix-ui/react-tooltip": "^1.2.16",
+    "@types/howler": "^2.2.13",
+    "cmdk": "^1.1.1",
     "commander": "^15.0.0",
+    "howler": "^2.2.4",
+    "katex": "^0.16.47",
+    "lucide-react": "^1.33.0",
     "mermaid": "^11.15.0",
-    "pinyin-pro": "^3.29.1",
-    "puppeteer": "^25.4.0"
+    "pinyin-pro": "^3.29.3",
+    "puppeteer": "^25.4.0",
+    "shiki": "^4.4.3"
   },
   "devDependencies": {
     "@radix-ui/react-dialog": "^1.1.23",