@qnroa/qtype 0.0.1 → 0.0.3

package/docs/zh/material-types.md

@@ -0,0 +1,769 @@
+# 资料类型详解
+
+qtype 支持 6 种资料类型 —— `word` / `sentence` / `article` / `snippet` / `qa` / `code`。每种类型有自己的 Markdown 结构、解析规则、渲染器和交互布局。本文档从**文件格式** → **解析器行为** → **UI 布局** → **交互细节**四个层面逐一讲清楚。
+
+---
+
+## 目录
+
+- [公共约定](#公共约定)
+- [word — 单词卡](#word--单词卡)
+- [sentence — 句子卡](#sentence--句子卡)
+- [article — 篇章 (长篇)](#article--篇章-长篇)
+- [snippet — 短章 (诗句/格言)](#snippet--短章-诗句格言)
+- [qa — 问答](#qa--问答)
+- [code — 代码题](#code--代码题)
+- [调度与兜底](#调度与兜底)
+
+---
+
+## 公共约定
+
+### 标题(H1)显示规则
+
+所有类型的卡片都以 H1 作为 title 显示在卡片顶部。统一处理:
+
+- **word / sentence**:H1 本身就是打字目标,居中大字号
+- **snippet**:H1 是作品名,小字居中,muted 色
+- **article / qa / code**:H1 是章节名/题目名,居中,**最多显示 2 行**,超出用省略号,鼠标 hover 显示完整标题(浏览器原生 `title` tooltip)
+
+### 文件顶部 frontmatter
+
+每个 `.md` 文件顶部有 YAML frontmatter,声明整个文件属于哪种类型：
+
+```yaml
+---
+type: word          # 5 种之一,决定整个文件的卡片形状
+title: 高频词 500     # 可选,资料展示名
+tags: [english, cet4]
+created: 2026-01-15
+updated: 2026-08-20
+---
+```
+
+- **`type` 决定整个文件**:一个 `.md` 只允许一种 type,所有卡片形状相同
+- **缺 `type` 时默认按 `article` 解析**(向后兼容旧文件)
+- 未知的 `type` 值(比如 `type: 自定义`)也会 fallback 到 `article` 解析
+
+### 卡片切分
+
+frontmatter 之后的正文按 **H1**(`# ...`)切分卡片:
+
+- 每个 H1 起一张新卡
+- H1 之前的散文/说明会被**丢弃**(材料级别的前言,渲染器看不到)
+- 每个 chunk 包含它自己的 H1 行 + 之后所有行,直到下一个 H1 或文件结尾
+
+### 打字文本的规范化
+
+不管什么类型,最终作为"打字目标"的字符串会走 `validateTypingText`:
+
+- 智能引号 `“ ” ‘ ’` → 直引号 `" '`
+- 破折号 `— –` → 常规连字符 `-`
+- Emoji / 零宽字符被剥离
+- 无法映射到键盘的字符会收进 `unknownChars`,UI 会在卡片上方红字提示"该卡不可玩"
+
+### 每张卡的通用字段(runtime)
+
+解析完的 `Card` 对象都有:
+
+```ts
+{
+  id: string         // 形如 "path/to/file.md#3"
+  title: string      // 显示用的标题(不一定是打字目标)
+  answer: string     // 实际打字目标(已规范化)
+  charPlans: CharPlan[]  // 每字符的按键计划(用于键盘可视化)
+  unknownChars: string[] // 打不出来的字符,非空则卡片不可玩
+  // ↓ 特定类型才有:
+  phonetic?: string  // word / sentence 的音标
+  gloss?: string     // word / sentence 的释义
+  image?: string     // word / sentence 的单张配图 markdown
+  question?: string  // article / qa / code 的题干原文
+}
+```
+
+### 富渲染(展示侧,不参与打字)
+
+**非打字的展示位置**(题干 `## Q`、article/snippet 正文、word/sentence 的 gloss)会经过一个轻量 markdown 渲染器,支持以下富内容:
+
+| 特性 | 语法 | 说明 |
+|---|---|---|
+| **粗体 / 斜体 / 行内代码** | `**text**` / `*text*` / `` `code` `` | 标准 markdown |
+| **代码块** | ` ```lang ` fence | `code` 类型的答案侧走另一条路径(参见 code 类型章节);其他位置只做等宽渲染 |
+| **Mermaid 流程图** | ` ```mermaid ` fence | `publish build` 时**预渲染成 SVG**(dark + light 两版),浏览器只查表换 SVG,零 runtime 开销 |
+| **数学公式(LaTeX)** | 行内 `$...$`,块级 `$$...$$` | 用 **KaTeX** 懒加载渲染(~280KB),仅在有公式的页面加载。可在设置里关闭 |
+
+**只在展示侧渲染,不参与打字**。用户看到的是漂亮的公式或流程图,敲的还是键盘能打得出来的字符。举例:
+
+```md
+---
+type: qa
+---
+
+# 高斯积分
+
+## Q
+求下面这个积分的值:
+
+$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = ?$$
+
+## A
+sqrt(pi)
+```
+
+题干里的 `$$...$$` 用 KaTeX 渲染成一行漂亮公式;`## A` 里 `sqrt(pi)` 就是键盘能打的普通字符,这是用户实际要敲的内容。
+
+### 通用交互(所有类型共享)
+
+所有卡片核心都是 `<TypingArena>`,行为一致:
+
+- 键入正确字符 → 光标前进,该字符标绿
+- 键入错误字符 → 该字符标红,光标不前进(除非开了 `ignorePunctuation` 之类的规则)
+- Backspace 回退(除非 `allowBackspace: false`)
+- 打完最后一个字符 → 触发 `onFinish` → 路由决定是否 gate 通过,过则进下一张
+- **暂停**由 4 个显式触发点控制:HUD ⏸ / Alt+Space / AFK 达阈值 / 窗口失焦或切 tab
+- 暂停时 arena 覆盖一层遮罩,提示当前快捷键
+
+---
+
+## word — 单词卡
+
+### 用途
+
+单词记忆,类似 qwerty-learner 的核心场景。适合背四六级、雅思、编程英语词汇。
+
+### Markdown 格式
+
+```md
+---
+type: word
+title: 常用单词
+tags: [english]
+---
+
+# apple
+## /ˈæp.əl/
+### 苹果
+#### ![](https://example.com/apple.jpg)
+
+# abandon
+## /əˈbæn.dən/
+### 抛弃; 放弃
+
+# code
+## /koʊd/
+### 代码
+```
+
+**H 层级映射**：
+
+| Heading | 含义 | 是否可选 |
+|---|---|---|
+| `# 目标词` | H1 就是要打的单词本身 | 必需 |
+| `## 音标/拼音` | 中文可用拼音,如 `## dài mǎ` | 可选 |
+| `### 释义` | 中英释义,单行 | 可选 |
+| `#### ![](url)` | 单张配图,只识别第一张 | 可选 |
+
+**注意**:所有 H2/H3/H4 只取**同一行**内容,多行会被忽略。
+
+### 解析器行为(`buildAnnotatedCard`)
+
+1. 提取 H1 文本 → `title = answer`(同一个字符串既是显示标题,也是打字目标)
+2. 用 regex `^##\s+(.*)$` 从 body 里抽首个 H2 → `phonetic`
+3. 同样抽 H3 → `gloss`,H4 → `image`(保留原始 markdown 如 `![alt](url)`)
+4. `charPlans` 按 `answer` 生成
+5. answer 空字符串或全是不可打字符 → 该卡片被丢弃,不进 material.cards
+
+### UI 布局(`WordCard.tsx`)
+
+```
+      ┌────────────────────────────────────┐
+      │                                    │
+      │           apple  🔊                │  ← 目标词大字(3rem, weight 500,
+      │          ↑ 居中     ↑ 绝对定位       │    letter-spacing 0.05em)
+      │                                    │
+      │          /ˈæp.əl/                  │  ← 音标(等宽字体,muted 颜色)
+      │           苹果                       │  ← 释义
+      │         ┌──────┐                   │
+      │         │ img  │                   │  ← 配图(max-width 320px)
+      │         └──────┘                   │
+      │                                    │
+      └────────────────────────────────────┘
+```
+
+**关键 CSS 技巧**:发音按钮**不参与 flex 布局**,而是 `position: absolute; left: 100%; top: 50%; translateY(-50%); margin-left: 8px`。这样目标词无论多长,都保持整体居中,按钮悬浮在词的右侧 —— 与 qwerty-learner 同源。
+
+### 交互细节
+
+- **自动朗读**:切换到新卡片且 `paused=false` 时,调用 `speak()` 播放 `card.answer`。有 `spokenForRef` 去重,同一张卡不会重复朗读
+- **朗读次数**:受 `autoSpeakRepeat` 控制(1/2/3),内部通过 `.ended` 事件链式重播
+- **朗读音量/语速**:受 `ttsVolume` / `ttsRate` 控制
+- **音标/释义可见性**:`showPhonetic` / `showGloss` 两个开关,可在 HUD More 菜单里切换,也可在设置页里改默认值
+- **发音钮**:点击也能手动朗读,与 auto-speak 用同一个 provider(网易/Google/浏览器)
+
+> **朗读与音标解耦**:朗读只依赖 `card.answer` 和 TTS provider。**卡片没有音标 (H2 缺省) 也照样有发音按钮和自动朗读** —— 音标是给眼睛看的辅助信息,朗读是给耳朵听的独立通道,两者互不依赖。
+
+### 邻卡预览(NeighborPreview)
+
+左右两侧显示上一张/下一张卡片时:
+
+- **title**:目标词(`card.answer`)
+- **subtitle**:释义(`card.gloss`,可选)
+- 不显示音标(单词卡的音标属于当前卡片视图,不打扰预览)
+- 不显示配图(预览要小要一眼看到,图太占地方)
+
+---
+
+## sentence — 句子卡
+
+### 用途
+
+整句练习,适合背例句、口语句型、TOEFL/IELTS 常用句、日语例文。
+
+### Markdown 格式
+
+结构与 word **完全相同**,只是 H1 通常更长:
+
+```md
+---
+type: sentence
+title: 日常表达
+---
+
+# I'm going home.
+## /aɪm ˈɡoʊ.ɪŋ hoʊm/
+### 我要回家了。
+
+# The quick brown fox jumps over the lazy dog.
+## /ðə kwɪk braʊn fɑks dʒʌmps ˈoʊvɚ ðə ˈleɪ.zi dɔɡ/
+### 敏捷的棕狐狸跳过懒狗。
+```
+
+### 解析器行为
+
+**与 word 共用 `buildAnnotatedCard`**,一样的字段结构。区别只在渲染。
+
+### UI 布局(`SentenceCard.tsx`)
+
+```
+   ┌───────────────────────────────────────────────────┐
+   │                                                   │
+   │           I'm going home.  🔊                     │  ← 目标句(1.6rem, line-height 1.6)
+   │           ↑ 整体水平居中,发音钮悬浮右侧              │    text-align: center
+   │                                                   │
+   │           /aɪm ˈɡoʊ.ɪŋ hoʊm/                     │  ← 音标(0.95rem, muted)
+   │             我要回家了。                            │  ← 翻译
+   │           ┌────────────┐                          │
+   │           │   image    │                          │  ← 配图(max-width 400px)
+   │           └────────────┘                          │
+   └───────────────────────────────────────────────────┘
+```
+
+**与 word 的差别**:
+
+- 字号更小(1.6rem vs 3rem),因为句子多字符
+- max-width 更宽(900px vs 720px)
+- 图片更大(400px vs 320px)
+- 发音钮同款绝对定位
+- **arena 里的文字 `text-align: center`**(word 只有一个词天然居中,不需要;sentence 多字符必须显式居中,否则会靠左)
+
+> **朗读与音标解耦**:与 word 相同,朗读只看 `card.answer`。**没有音标的句子照样能听发音** —— 尤其是外语听写练习场景,音标很少给出,但朗读必须有。
+
+### 邻卡预览(NeighborPreview)
+
+- **title**:整句(`card.answer`)
+- **subtitle**:翻译(`card.gloss`,可选)
+- 不显示音标 / 图片
+
+---
+
+## article — 篇章 (长篇)
+
+### 用途
+
+段落/文章练习,适合打新闻、散文、书摘、多段说明文。
+
+### Markdown 格式
+
+```md
+---
+type: article
+title: 精读段落
+---
+
+# Autumn Morning
+
+The mist hung low over the valley, softening every edge.
+Somewhere below, a river murmured its ancient tune.
+Yellow leaves drifted down without a sound.
+
+![秋日晨景](https://example.com/autumn.jpg)
+
+# Winter Silence
+
+Snow had erased the road overnight...
+```
+
+**层级映射**:
+
+| Heading / 内容 | 含义 |
+|---|---|
+| `# 章节标题` | 只是显示标题,**不参与打字** |
+| H1 下的所有正文 | 全部作为打字目标(图片会被剥离) |
+| 正文里的图片 | 保留在 `card.question`,渲染在 arena 上方作为视觉辅助 |
+
+### 解析器行为(`buildArticleCard`)
+
+1. `title` = H1 文本
+2. 从 H1 下的 body 里**去掉所有 `![alt](url)` 图片语法** → 得到 `rawTarget`
+3. 规范化(智能引号、破折号、剥离 emoji) → `answer`(打字目标)
+4. `question` = **原始未处理的 body**(含图片语法),这样渲染器可以只挑出图片显示,不重复渲染文字
+
+### UI 布局(`ArticleCard.tsx`)
+
+```
+┌────────────────────────────────────────────────┐
+│               Autumn Morning                   │  ← 标题(1.3rem, 600, 居中)
+│                                                │
+│  [autumn.jpg]                ← 只显示图片        │
+│                                                │
+│  ┌──────────────────────────────────────────┐  │
+│  │ The mist hung low over the valley,        │  │
+│  │ softening every edge. Somewhere below,    │  │  ← arena
+│  │ a river murmured its ancient tune.        │  │    (1.15rem, line-height 1.7, 靠左)
+│  │ Yellow leaves drifted down without a...   │  │
+│  └──────────────────────────────────────────┘  │
+└────────────────────────────────────────────────┘
+```
+
+**标题居中 + 正文靠左**是主流文档排版(书籍 / 论文 / Wikipedia / Medium)。
+
+**渲染细节**:
+
+- 用了自定义 `imageOnly()` 函数,把 body 里非图片的行全部丢弃,只留 `![](url)` 那些行
+- 这样图片在文字上方 render,而**同样的文字不会被渲染两次**(一次作 md,一次作打字目标)
+- container 是 `flex-column` + `overflow-y: auto`,长文能滚动
+- arena 里的文字用 `white-space` 默认(不会 pre-wrap,段落之间的空行会折叠)
+
+### 交互细节
+
+- **无自动朗读**(段落太长,朗读体验差)
+- **无音标/释义**(不适用)
+- **发音钮**?没有 —— 长段落不需要,如果想听某句话可以复制到别处
+- 段落之间用**空行**分隔(md 标准),打字时空行会体现为 arena 里的换行
+
+### 是否居中?
+
+**不居中,靠左**。这是刻意的设计:
+
+- 段落文字居中反而破坏阅读流(主流打字应用 monkeytype / typing.io / typeracer 全部靠左)
+- 阅读长文本时,人眼靠"稳定的左边界"来快速定位下一行
+- CSS 上 `.qt-article` 是 `flex-direction: column` + 无 `align-items`,arena 撑满宽度,文字自然靠左
+
+### 邻卡预览
+
+- **title**:章节标题(`card.title`)
+- **无 subtitle**
+- 不预览正文(太长)
+
+### article vs snippet:怎么选?
+
+同样的 md 结构可以用 `article` 或 `snippet`。判断标准就一句话:
+
+- 内容像**文章** → `article`(小说段、新闻、说明文、书摘、多段散文)
+- 内容像**作品** → `snippet`(古诗、词、俳句、格言、slogan、菜单、清单、对联)
+
+技术上两者**解析完全相同**(共用 `buildArticleCard`),差别只在渲染器 —— `article` 靠左阅读,`snippet` 居中呈现。参见下一节。
+
+---
+
+## snippet — 短章 (诗句/格言)
+
+### 用途
+
+古诗词、俳句、格言警句、slogan、清单、对联、菜单 —— 任何**短小、有节奏、值得视觉性呈现**的文本。
+
+`article` 和 `snippet` 数据结构完全一样,分开只为渲染时对齐方式不同:`article` 靠左适合阅读长文,`snippet` 居中适合视觉呈现短文。
+
+### Markdown 格式
+
+```md
+---
+type: snippet
+title: 唐诗三百首
+tags: [poetry, tang]
+---
+
+# 静夜思
+
+床前明月光,
+疑是地上霜。
+举头望明月,
+低头思故乡。
+
+# 春晓
+
+春眠不觉晓,
+处处闻啼鸟。
+夜来风雨声,
+花落知多少。
+```
+
+**层级映射**:与 `article` **完全相同** ——
+
+| Heading / 内容 | 含义 |
+|---|---|
+| `# 章节/作品标题` | 显示标题,**不参与打字** |
+| H1 下的所有正文 | 全部作为打字目标(图片剥离) |
+
+### 解析器行为
+
+**沿用 `buildArticleCard`**,与 article 完全一样的字段结构。切分类型只影响渲染。
+
+### UI 布局(`SnippetCard.tsx`)
+
+```
+   ┌────────────────────────────────────────────┐
+   │                                            │
+   │                                            │
+   │              静夜思                          │  ← 标题(1.15rem, muted)
+   │            ↑ 居中                           │    letter-spacing 0.05em
+   │                                            │
+   │            床前明月光,                       │
+   │            疑是地上霜。                       │  ← arena(1.4rem, line-height 2)
+   │            举头望明月,                       │    text-align: center
+   │            低头思故乡。                       │
+   │                                            │
+   │                                            │
+   └────────────────────────────────────────────┘
+```
+
+**关键 CSS 差异(对比 article)**:
+
+| 维度 | article | snippet |
+|---|---|---|
+| container | `flex-column` 从上排,无居中 | `align-items: center; justify-content: center` 整体上下水平都居中 |
+| 标题 | 1.3rem, 深色, 靠左 | 1.15rem, muted, 居中, 字母间距略宽 |
+| arena 文字对齐 | 默认(靠左) | `text-align: center` |
+| 字号 | 1.15rem | 1.4rem (略大,配合诗歌节奏) |
+| 行距 | 1.7 | 2.0 (更宽,格律感) |
+
+### 交互细节
+
+- 无自动朗读、无音标、无发音钮(承袭 article)
+- 每行结尾的**标点必须打**(`,` `。` `;` 等)—— 打字目标里保留了这些字符
+- **换行**要打回车吗?不用 —— 打字目标里换行是文本的一部分,arena 会在光标碰到换行时自动前进,不需要按 Enter
+- 空行(诗节之间)同理,arena 自动跳过
+
+### 是否居中?
+
+**必须居中**。这是 snippet 存在的**唯一理由** —— 如果不需要居中,就该用 article。
+
+### 邻卡预览
+
+- **title**:作品标题(`card.title`,如"静夜思")
+- **无 subtitle**
+- 不预览正文
+
+---
+
+## qa — 问答
+
+### 用途
+
+题目 + 解答的形式,适合面试题、知识点问答、外语听力 dictation。
+
+### Markdown 格式
+
+```md
+---
+type: qa
+title: 常见面试题
+---
+
+# 什么是闭包?
+
+## Q
+请解释 JavaScript 中的闭包,以及它的常见应用场景。
+
+## A
+闭包是指有权访问另一个函数作用域中变量的函数。
+常见用途:
+- 数据私有化
+- 函数柯里化
+- 回调函数保持状态
+
+# HTTP 和 HTTPS 的区别
+
+## Q
+从**协议层面**说说 HTTP 和 HTTPS 的区别。
+
+参考图:
+![握手示意](https://example.com/tls.png)
+
+## A
+HTTPS 在 HTTP 之上加了 TLS/SSL 加密层...
+```
+
+**层级映射**:
+
+| 部分 | 含义 |
+|---|---|
+| `# 卡片标题` | 显示标题,不参与打字 |
+| `## Q` 之后到 `## A` 之前 | 题干,支持任意 markdown(列表、图片、代码块、粗体等) |
+| `## A` 之后到卡片结尾 | 打字目标(**图片被剥离**,其他 markdown 语法**保留原文**) |
+
+### 解析器行为(`buildQACard`)
+
+1. 用 regex `##\s*Q\b\s*\n([\s\S]*?)(?=\n##\s*A\b|$)` 抓 Q 块
+2. 用 regex `##\s*A\b\s*\n([\s\S]*)$` 抓 A 块
+3. **A 块必须存在**,否则该卡片被丢弃(returns null)
+4. Q 块可选,不存在则 `question = ''`
+5. A 块的原始文本 → `extractTypingText` → 剥离图片语法 + 剥离 fenced code 的 ``` 边界(留下代码内容)
+6. 规范化 → `answer`
+
+**注意**:A 里如果有 ``` fenced code,**只剥离前后的 ``` 标记**,里面的代码保留(因为要打)。这也是 code 类型能沿用这套解析器的原因。
+
+### UI 布局(`QaCard.tsx`)
+
+```
+┌────────────────────────────────────────────────┐
+│                什么是闭包?                       │  ← 标题(1.3rem, 600, 居中)
+│                                                │
+│  请解释 JavaScript 中的闭包,以及它的常见应用场景。 │  ← Q(muted, 0.95rem)
+│                                                │  ← 用 MdRenderer 完整渲染
+│                                                │    (列表/图片/代码都会显示)
+│  ┌──────────────────────────────────────────┐  │
+│  │ 闭包是指有权访问另一个函数作用域中变量的...     │  │
+│  │ 常见用途:                                    │  ← arena(1.1rem, line-height 1.7, 靠左)
+│  │ - 数据私有化                                 │  │    A 的**原始文本**(含 markdown 语法)
+│  │ - 函数柯里化                                 │  │
+│  │ - 回调函数保持状态                            │  │
+│  └──────────────────────────────────────────┘  │
+└────────────────────────────────────────────────┘
+```
+
+**关键点**:
+
+- **Q 是"给人看的"**,所以用 `<MdRenderer>` 完整渲染:粗体变粗体,列表变项目符号,图片显示,代码块高亮
+- **A 是"给人打的"**,arena 里的是**原始 md 文本**。用户会把 `- ` `**` 反引号等符号一字一字打出来
+- 这不是 bug —— 是设计目标:让用户练打那些平时打不好的符号
+- container `flex-column` + `overflow-y: auto`,题干长了能滚
+
+### 交互细节
+
+- **无自动朗读**(问答场景不朗读)
+- **无音标/释义/图片专门渲染**(图片直接在 Q 里显示)
+- 打字目标里的换行、缩进、特殊符号都要**逐字符打准**
+
+### 邻卡预览
+
+- **title**:卡片标题(`card.title`,也就是 H1)
+- **无 subtitle**
+- 不预览 Q(问答的 Q 通常包含 md 格式,预览里不好看,而且 preview 应该"扫一眼",不该读完整段问题)
+
+---
+
+## code — 代码题
+
+### 用途
+
+编程题练习,LeetCode / 常见算法题 / API 用法 / 语法背诵。
+
+### Markdown 格式
+
+**结构与 qa 完全一致**(共用 `buildQACard`),但约定 A 里放 fenced code block:
+
+````md
+---
+type: code
+title: 常见算法
+tags: [algorithm, javascript]
+---
+
+# Two Sum
+
+## Q
+给一个数组 `nums` 和一个目标值 `target`,返回两个下标使得两数之和等于 target。
+
+**约束**:同一元素不能用两次,答案唯一。
+
+## A
+```ts
+function twoSum(nums: number[], target: number): number[] {
+  const map = new Map<number, number>()
+  for (let i = 0; i < nums.length; i++) {
+    const rest = target - nums[i]
+    if (map.has(rest)) return [map.get(rest)!, i]
+    map.set(nums[i], i)
+  }
+  return []
+}
+```
+
+# Reverse Linked List
+
+## Q
+反转一个单链表,返回新头结点。
+
+## A
+```python
+def reverse(head):
+    prev = None
+    while head:
+        next_node = head.next
+        head.next = prev
+        prev = head
+        head = next_node
+    return prev
+```
+````
+
+### 解析器行为
+
+**沿用 `buildQACard`**,与 qa 完全相同。差别只在渲染端:
+
+- `card.answer` = **代码本身**(``` 边界已剥离,代码内容原封不动)
+- `card.question` = Q 块的完整 markdown
+
+### 语言识别(`CodeCard.tsx`)
+
+语言用于 Shiki 语法高亮(**不显示在 UI 上**),识别顺序:
+
+1. 首先在 `card.question` 里搜 `` ```lang `` fence 标签(比如 `` ```ts ``、`` ```python ``)—— 找到就用它
+2. 找不到就从文件路径猜(`typescript.md` → typescript,`python.md` → python,含 `cpp/c++` → cpp,等等)
+3. 都不中就默认 `javascript`
+
+> **不显示语言 tag 的原因**:作者已经把语言写进了 material 的 frontmatter `tags`(如 `tags: [algorithm, typescript]`),资料列表页会展示。卡片视图再显示一次是冗余,而且抢标题的视觉焦点。语言只用于代码染色,靠 Shiki 输出的颜色自然就知道是啥语言。
+
+### 语法高亮
+
+用 [Shiki](https://shiki.style/) 做 tokenize:
+
+1. `useShiki(lang)` 懒加载对应语言的语法包
+2. 主题跟随全局:`data-theme` 含 `latte` → `github-light`,否则 `github-dark`
+3. `codeToTokens` 遍历返回的 token,把每个字符对应的**颜色**塞进 `charColors: (string | null)[]`
+4. `TypingArena` 接受 `charColors` 参数,给未打字符添加 `color: <shiki color>` 的行内 style
+5. 打对/打错的 CSS 类通过 specificity 覆盖 shiki 颜色 —— 打对了变绿,打错了变红
+
+### UI 布局
+
+```
+┌────────────────────────────────────────────────────────┐
+│                    Two Sum                             │  ← 标题(1.15rem, 600, 居中, ≤ 2 行)
+│                                                        │
+│  给一个数组 nums 和一个目标值 target,返回两个下标使得...    │  ← Q(muted, 完整 md 渲染)
+│                                                        │    max-height 30vh,超出滚动
+│                                                        │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │ function twoSum(nums: number[], ...) {           │  │
+│  │   const map = new Map<number, number>()          │  │  ← arena
+│  │   for (let i = 0; i < nums.length; i++) {        │  │    等宽字体
+│  │     ...                                          │  │    white-space: pre-wrap
+│  │   }                                              │  │    text-align: left
+│  │ }                                                │  │    带 shiki 颜色
+│  └──────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────┘
+```
+
+**关键 CSS 差异**:
+
+- 整体 `font-family: var(--font-mono)` 等宽
+- arena 的文字 `white-space: pre-wrap`(保留代码里的换行和空格)+ `text-align: left`(代码永远靠左)
+- Q 区域 `max-height: 30vh` + `overflow-y: auto`,长题干不会挤掉代码
+- **不显示语言 tag** —— 语言(`ts` / `python`)约定作者写进 material 的 `tags` 里,在资料列表页展示;卡片视图内只保留 Shiki 高亮效果,不重复显示语言标签
+
+### 交互细节
+
+- **无自动朗读**
+- **必须打准所有缩进、括号、分号、大小写** —— 代码打字的核心训练目标
+- Tab 键行为受 `tabBehavior` 设置控制:`input`(推荐,把 Tab 当字符打入)/ `reset`(重打当前卡)/ `disabled`
+- 打字时**语法高亮实时保留**(打对的字变绿,但底色仍是 shiki 的颜色)
+- **`code` 是懒加载的**:整个 CodeCard 组件通过 `React.lazy` 引入,Shiki 依赖大约 1MB,不打代码就不下
+
+### 邻卡预览
+
+- **title**:题目名(`card.title`)
+- **无 subtitle**
+- 不预览代码本身(占地方,而且预览里没高亮反而看着乱)
+
+---
+
+## 调度与兜底
+
+### 分发路由(`CardView.tsx`)
+
+```tsx
+switch (material.meta.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} />
+}
+```
+
+- `code` 用 `<Suspense>` 包裹,fallback 是 `<QaCard>` —— Shiki 还没加载好之前先按普通 qa 显示,加载完自动切
+- 未知 type / frontmatter 里 type 是自定义字符串时 → `<CardBase>` 兜底:只显示 `question` + arena
+
+### CardBase 兜底渲染器
+
+极简结构:如果有 `question` 就显示它(纯文本),下面接 arena。没什么样式,防止全空。
+
+```tsx
+<div className="qt-cardbase">
+  {card.question && <div className="qt-cardbase__prompt">{card.question}</div>}
+  <div className="qt-cardbase__arena">
+    <TypingArena key={card.id} {...arenaProps(props)} />
+  </div>
+</div>
+```
+
+### arenaProps 转发
+
+所有 5 个渲染器都用 `arenaProps(props)` 把公共字段转发给 `<TypingArena>`:
+
+- `target` = `card.answer`(打字目标)
+- `charPlans` = `card.charPlans`(键盘可视化)
+- `hint` / `readOnly` / `targetWpm` / `tabBehavior` / `retryOnFail` / `completionMode` / `maxRetries`
+- `paused` + `onAutoPause` / `onFinish` / `onSkip` / `onStateChange` 回调
+
+这样各渲染器专心搞外围壳,不用重复写 arena 的接线。
+
+---
+
+## 一张对照表
+
+| type | Markdown 结构 | 打字目标 | 显示辅助 | 朗读 | 图片 | 语法高亮 | 文字居中 | 邻卡预览 |
+|---|---|---|---|---|---|---|---|---|
+| **word** | H1/H2/H3/H4 | H1 单词本身 | 音标(H2)+ 释义(H3)| ✅ 自动+手动 | H4 单张 | ✗ | ✅ | 单词 + 释义 |
+| **sentence** | H1/H2/H3/H4 | H1 整句 | 音标(H2)+ 翻译(H3)| ✅ 自动+手动 | H4 单张 | ✗ | ✅ | 整句 + 翻译 |
+| **article** | H1 + 段落 | H1 下的正文 | 只保留正文中的图片 | ✗ | 保留 | ✗ | 标题居中 / 正文靠左 | 章节标题 |
+| **snippet** | H1 + 短文 | H1 下的正文 | 只保留正文中的图片 | ✗ | 保留 | ✗ | 全部居中 | 作品标题 |
+| **qa** | H1 + ## Q + ## A | ## A 原文 | ## Q 完整 md 渲染 | ✗ | Q 里显示 | ✗ | 标题居中 / 正文靠左 | 卡片标题 |
+| **code** | H1 + ## Q + ## A(fenced) | ## A 里的代码 | ## Q 完整 md 渲染 | ✗ | Q 里显示 | ✅ Shiki (不显 lang tag) | 标题居中 / 正文靠左 | 题目名 |
+
+---
+
+## 常见问题
+
+**Q1: 我能不能在一个文件里混两种 type?**
+不能。`type` 是 material 级别,决定整个文件的解析规则。想混就拆两个文件。
+
+**Q2: word/sentence 的 H2 能不能多行?**
+不能。regex 只匹配 `^##\s+(.*)$` 单行,后续行会被忽略。
+
+**Q3: article 里我想让用户练打图片链接怎么办?**
+不行。图片语法(`![](url)`)在解析阶段被无条件剥离。把它写在 fenced code 里也不行 —— article 没有 fence 剥离逻辑,那就成了普通字面量。要么改用 qa,把图片链接放 A 里。
+
+**Q4: qa 的 A 我在开头写了列表 `-`,是不是也要打这个 `-`?**
+对,`-` 也要打。qa 的 A 保留全部 markdown 语法原文,包括 `- ` `**` `##` ``` ` `` 等。这是设计目标。
+
+**Q5: code 的 fence 语言标签写错了会怎样?**
+Shiki 找不到该语言就 fallback 到"无高亮"(charColors 全 null),arena 用默认文本色渲染,打字功能正常。不会崩。