@qnroa/qtype 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -13,6 +13,124 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-09-01
+
+Discoverability pass for `qtype config`. Users no longer have to grep
+the source (or the wiki) to find out what keys they can set.
+
+### Added
+- **`qtype config --help` now lists every configurable key** at the
+  bottom of the help output — one line per key with its default, scope,
+  description, and enum options where applicable. Same source of truth
+  as the actual schema, so it stays honest.
+- **`qtype config list --all`** — verbose per-key view: current value
+  (or default if unset), source (which file / default), scope, and
+  enum options. Complements `list` (only shows keys the user has
+  actually set).
+- **`SchemaEntry.description` + `SchemaEntry.options`** fields, both
+  optional. Populated for every currently-registered key so the two
+  new help surfaces have something to show.
+- **`CommandModule.afterHelp`** hook — commands can append reference
+  material after the standard help sections. `config` uses it; other
+  commands can add their own without touching the registry.
+
+### Changed
+- Cleaned up in-line doc comments in the schema files (they've been
+  moved into the `description` field where possible, so they're
+  reachable at runtime).
+
+## [0.2.0] — 2026-08-31
+
+Substantial rework of the typing page. The screen-flow is now a real
+finite state machine (xstate), the ad-hoc `paused / stampKind /
+awaitingAdvance / finished / isReview` booleans are gone, and every
+screen state's UI is derived from one place rather than pieced together
+by view code. Behaviour visible to the user shifts in a few spots —
+see below.
+
+### Added
+- **Session persistence for done state.** Marking a card done writes
+  to the persistent kv (`useDoneState`), so the completion streak
+  survives page reloads and shows up on Home right next to the
+  material title as `3 / 12`. Openng a material now lands on the
+  first card the user hasn't finished, not always card 1.
+- **Completed-card review mode.** Coming back to a card you've already
+  finished shows the answer painted in green (via `engine.markAllHit`)
+  with the HUD still available; pressing ▶ / Alt+Space wipes the done
+  flag and lets you retype from scratch.
+- **Card-jump list panel.** The quick-input's card submode now lists
+  every card in the queue with its title, done state, and a "current"
+  marker. Type text to filter by title, digits to jump by number.
+- **After-pass advance mode.** New setting `advanceMode` — the default
+  is now **Confirm** (stay on the finished card until the user hits
+  the confirm key) rather than auto-advance after 700ms. Users who
+  prefer the old behaviour can flip it back to Auto in settings.
+- **Confirm key setting.** Choose Enter or Space as the "next" key.
+  The chosen key is highlighted on the on-screen keyboard during the
+  confirmation window so mobile users can see where to tap.
+- **Global keyboard channel.** Typing keeps working after clicks that
+  move focus out of the arena — a window-level `keydown` listener
+  forwards keystrokes to the engine so users don't have to click back
+  into the (invisible) editor after every misplaced tap.
+- **Mobile virtual keyboard inset.** The layout reserves space at the
+  bottom equal to the soft-keyboard height (`visualViewport` API), so
+  the answer text no longer disappears under the keyboard on iOS /
+  Android.
+- **Region-aware TTS default.** New `auto` TTS provider picks Youdao
+  for `zh-*` browsers and Google elsewhere, with the "browser" engine
+  as fallback. Explicit picks still take precedence.
+- **`?path=` search param on the typing route.** The HUD "back to
+  library" button returns to the exact folder the user came from
+  instead of the library root.
+
+### Changed
+- **Typing page UI reimplemented as an xstate machine** (`idle` /
+  `typing` / `paused` / `passed` / `completed` / `finished`), replacing
+  five ad-hoc `useState` booleans. Every screen state's mask / stamp /
+  pill / keyboard-hint / HUD-play-icon is derived from one `derived`
+  struct rather than assembled by the view. Fixes a class of races
+  where two effects would fight over the same visual (e.g. the pass
+  stamp being covered by the pause mask because a review-restore
+  effect fired half a frame too early).
+- **`useTypingEngine` is now keyed on card id, not answer text.** Two
+  cards whose answers happened to be identical used to share one
+  engine, leaking cursor / hit-miss marks between them. Every card
+  now gets a fresh engine on entry.
+- **First character of each card is now highlighted on the on-screen
+  keyboard.** `useHudBridge` derives the first keystroke from the
+  engine at mount instead of waiting for the arena to push one.
+- **Backspaced characters render as untyped.** The engine still tags
+  them as `Recover` for downstream logic, but the dotted underline
+  UI decoration is removed — visually the slot goes back to "pending".
+- **HUD ▶ / Alt+Space in `completed` state means "restart this card"**,
+  not "start typing". It clears the done marker + resets the engine +
+  moves the machine to typing.
+- **Paused → next card lands in idle, not typing.** Advancing while
+  paused now shows the pause mask on the new card so the user still
+  has to explicitly start.
+- **Backspace / stamp / advance cleanup are co-located with the user
+  action that triggers them**, not smuggled through state-transition
+  effects that could fire on incidental transitions (e.g. advancing
+  to an un-done card would previously have clobbered the destination's
+  done state).
+
+### Removed
+- **`sessionPassed` snapshot store.** Reviewing a passed card no
+  longer replays the exact keystroke-by-keystroke record from
+  sessionStorage — a static "all hit" view is used instead. That
+  removed a whole storage layer and closed the quota concern for
+  users with thousands of cards.
+- **`TypingInput.snapshot` / `restore`** (and the `TypingInputSnapshot`
+  type). Superseded by `markAllHit`.
+
+### Fixed
+- **Focus loss no longer stops typing.** Clicking HUD buttons or
+  outside the arena used to silently drop keystrokes; the global
+  keydown fallback catches them now.
+- **Mobile answer text no longer covered by the soft keyboard.**
+- **HUD "back" button returns to origin folder** (see `?path=`
+  above), instead of always the library root.
+
 ## [0.1.4] — 2026-08-29
 
 Two small UX changes: a tappable resume overlay and a completion

package/CHANGELOG.zh.md

@@ -12,6 +12,95 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-09-01
+
+`qtype config` 的可发现性升级。用户不再需要翻源码或 wiki 才知道能设
+置哪些 key。
+
+### 新增
+- **`qtype config --help` 现在会在底部列出所有可配置的 key**,一行一个,
+  含默认值、作用域、描述、枚举选项(如果有)。数据源就是 schema 本身,
+  不会脱节。
+- **`qtype config list --all`** —— 详版:每个 key 显示当前值(或未设置
+  时的默认)、来源(哪个文件 / 默认)、作用域、枚举选项。和 `list`(只
+  显示用户设过的)互补。
+- **`SchemaEntry.description` + `SchemaEntry.options`** 两个可选字段。
+  现在每个已注册 key 都填了,给上面两个新的 help 出口提供内容。
+- **`CommandModule.afterHelp` 钩子** —— 命令可以在标准 help 段落后追加
+  参考内容。`config` 用它,其它命令想加也行,不用改 registry。
+
+### 变更
+- 清理了 schema 文件里的行内文档注释(能放进 `description` 的都挪进
+  去了,这样运行时就能读到)。
+
+## [0.2.0] — 2026-08-31
+
+打字页面的整体架构重写。屏幕流程改成了真正的有限状态机（xstate），
+之前散在各处的 `paused / stampKind / awaitingAdvance / finished /
+isReview` 布尔位全部替换成一个状态机，每种状态下的 UI 都从一个统一
+的派生里读，而不是各处自己拼。用户可感知的行为变化见下面。
+
+### 新增
+- **完成状态持久化。** 通过卡片会写到本地存储（`useDoneState`），
+  刷新页面 / 重启浏览器都保留，Home 里的材料卡上会显示 `3 / 12`
+  完成进度。打开材料时会跳到第一张未完成的卡，不再永远从第一张开始。
+- **已完成卡片的回看模式。** 切回已通过的卡时，答案会整体显示为绿色
+  （`engine.markAllHit`），HUD 仍可用；按 ▶ / Alt+Space 会清掉这张
+  卡的完成标记并重置引擎，回到从头开始的可打状态。
+- **卡片跳转列表面板。** 命令面板的卡片跳转模式现在会列出 queue 中
+  每一张卡的标题、完成状态和当前位置。输入文本按标题模糊过滤，输入
+  数字按序号直接跳转。
+- **通过后推进模式。** 新增设置 `advanceMode`，默认改为 **确认**（打
+  完卡等待用户按确认键才进入下一张），不再是原本的 700ms 自动跳。
+  想要旧行为的用户可以在设置里切回自动。
+- **确认键设置。** 可选 Enter 或 Space 作为「进入下一张」的键。选中
+  的键在等待确认时会在虚拟键盘上高亮，方便移动端用户看到点哪。
+- **全局键盘通道。** 点击了 HUD 按钮 / 卡片之外的区域之后依然可以继续
+  打字 —— 一个 window 级别的 keydown 监听会兜底转发到引擎，用户不用
+  再回点隐形编辑器。
+- **移动端虚拟键盘避让。** 布局底部会预留和虚拟键盘等高的空间
+  （`visualViewport` API），答题区不再被系统键盘挡住。
+- **区域感知的 TTS 默认值。** 新增 `auto` 语音源，浏览器语言 `zh-*`
+  用有道，其他用 Google，都失败降级到浏览器自带。用户手动选的会覆盖。
+- **typing route 支持 `?path=` search 参数。** HUD 上的「返回」按钮
+  会回到用户进入该材料前所在的文件夹，而不是永远回到根目录。
+
+### 变更
+- **打字页 UI 用 xstate 状态机重写**（`idle` / `typing` / `paused` /
+  `passed` / `completed` / `finished` 六态），替换了原本的 5 个散乱
+  `useState` 布尔。所有状态的遮罩 / 笑脸 / pill / 键盘高亮 / HUD 播
+  放按钮图标都从一个 `derived` 结构派生。修复了一类由两个副作用抢
+  同一个视觉状态引起的 bug（比如笑脸被 review restore 副作用早触发
+  盖住）。
+- **`useTypingEngine` 现在按 cardId 缓存，不再按答案文本。** 之前两
+  张答案文字相同的卡会共用一个引擎，光标 / 对错标记会串。现在每张
+  卡进入时都是一个干净的新引擎。
+- **每张卡的第一个字符现在会在键盘上高亮。** `useHudBridge` 在挂载
+  时就从引擎派生出第一个 keystroke，不再等 arena push。
+- **删除的字符按待打字状态渲染。** 引擎仍然会打 `Recover` 标记（下
+  游还在用），但视觉上不再显示原本的点状下划线。
+- **completed 状态下按 ▶ / Alt+Space 表示「重打这张卡」**，不是「开始
+  打字」。会清完成标记 + 重置引擎 + 转到 typing。
+- **暂停状态下切下一张会到 idle,不到 typing。** 新卡进去仍显示暂停
+  遮罩,等用户主动开始。
+- **Backspace / stamp / advance 的清理逻辑放到触发它们的用户动作里**,
+  不再依赖状态过渡副作用。避免了「切到未通过的卡时误清目标卡完成状
+  态」这类 bug。
+
+### 删除
+- **`sessionPassed` 快照存储。** 回看已通过的卡不再从 sessionStorage
+  回放当时逐键的完整状态,直接使用「全绿」静态视图。移除了一整层存
+  储,消除了对几千张卡容量上限的顾虑。
+- **`TypingInput.snapshot` / `restore` 方法**(以及 `TypingInputSnapshot`
+  类型)。被 `markAllHit` 取代。
+
+### 修复
+- **焦点丢失不再停止打字。** 点击 HUD 按钮 / 卡片之外会让隐形编辑器
+  失焦,原来会静默吞掉按键。现在有全局 keydown 兜底。
+- **移动端答题区不再被虚拟键盘遮挡。**
+- **HUD「返回」按钮回到进入时的目录**(见上面 `?path=`),不再永远回
+  到根目录。
+
 ## [0.1.4] — 2026-08-29
 
 两个小 UX 改动：暂停遮罩可以点击继续，卡片打完时会有一个短暂的

package/dist/cli/commands/config/action.js

@@ -178,6 +178,12 @@ export async function configUnsetAction(key, opts) {
 /** `qtype config list [--global|--local] [--show-origin]` */
 export async function configListAction(opts) {
     const scope = pickScope(opts);
+    // --all: enumerate every schema-known key, filling in defaults for
+    // ones the user hasn't set. Useful for discovering what can be
+    // configured.
+    if (opts.all) {
+        return listAllKnown(scope);
+    }
     const userEntries = scope === 'repo' ? [] : await userKv.list();
     const repoEntries = scope === 'user' ? [] : (await repoKv.available()) ? await repoKv.list() : [];
     const rows = [];
@@ -220,6 +226,68 @@ export async function configListAction(opts) {
 // ═══════════════════════════════════════════════════════════════
 // helpers
 // ═══════════════════════════════════════════════════════════════
+/**
+ * List every key known to the schema in the given scope (all if scope
+ * is undefined). For each key: current value + source, or default +
+ * `(default)` marker if unset, plus type / options / description.
+ */
+async function listAllKnown(scope) {
+    const rows = [];
+    const seen = new Set();
+    if (scope !== 'repo') {
+        for (const k of userKv.knownKeys()) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            rows.push({ key: k, kv: userKv, scope: 'user' });
+        }
+    }
+    if (scope !== 'user') {
+        for (const k of repoKv.knownKeys()) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            rows.push({ key: k, kv: repoKv, scope: 'repo' });
+        }
+    }
+    rows.sort((a, b) => a.key.localeCompare(b.key));
+    const repoAvailable = scope === 'user' ? false : await repoKv.available();
+    for (const r of rows) {
+        const entry = r.kv.getSchema(r.key);
+        // Prefer the stored value (from user or repo scope); fall back to
+        // the schema default. `get` returns default when unset, so guard
+        // with `has` first to know whether the value is user-set.
+        let currentDisplay = '';
+        let sourceLabel = '';
+        const canRead = r.scope === 'user' || repoAvailable;
+        if (canRead && (await r.kv.has(r.key))) {
+            const raw = await r.kv.get(r.key);
+            currentDisplay = formatValue(raw);
+            sourceLabel = `${r.scope}:${r.kv.origin}`;
+        }
+        else {
+            currentDisplay = formatValue(entry.default);
+            sourceLabel = 'default';
+        }
+        const parts = [`${r.key}=${currentDisplay}`];
+        if (entry.description)
+            parts.push(dim(entry.description));
+        console.log(parts.join('  '));
+        const meta = [];
+        if (entry.options && entry.options.length > 0) {
+            meta.push(`options: ${entry.options.join(' | ')}`);
+        }
+        if (entry.default !== undefined && sourceLabel === 'default') {
+            // already shown as current; keep meta uncluttered
+        }
+        else if (entry.default !== undefined) {
+            meta.push(`default: ${formatValue(entry.default)}`);
+        }
+        meta.push(`scope: ${r.scope}`);
+        meta.push(`source: ${sourceLabel}`);
+        console.log('  ' + dim(meta.join('  ·  ')));
+    }
+}
 /** Format a value as a single-line string. Objects / arrays use JSON. */
 function formatValue(v) {
     if (v == null)

package/dist/cli/commands/config/i18n.js

@@ -7,8 +7,10 @@ export const messages = {
         'config.opt.global': '操作 user 层（~/.config/qtype/config.json）',
         'config.opt.local': '操作 repo 层（<repo>/.qtype/config.json）',
         'config.opt.showOrigin': '显示配置项来源（文件路径 / 哪一层）',
+        'config.opt.all': '列出所有可配置项（含 schema 里未设置的默认值）',
         'config.example.setLang': '设置 CLI 语言',
         'config.example.list': '列出所有生效配置',
+        'config.list.example.all': '列出所有可配置项及默认值',
         'config.get.summary': '读配置',
         'config.get.description': '读取指定 key 的值（默认合并两层；key 不存在 exit 1）',
         'config.get.example.basic': '读 CLI 语言偏好',
@@ -29,6 +31,8 @@ export const messages = {
         'config.list.example.global': '只看 user 层',
         'config.list.msg.empty': '配置为空',
         'config.list.msg.emptyScoped': '配置为空 ({scope})',
+        'config.help.keysHeader': '可配置项:',
+        'config.help.keysFooter': '用 `qtype config set <key> <value>` 修改；`qtype config list --all` 查看完整状态。',
     },
     'en-US': {
         'config.summary': 'Manage config',
@@ -38,8 +42,10 @@ export const messages = {
         'config.opt.global': 'Operate on user scope (~/.config/qtype/config.json)',
         'config.opt.local': 'Operate on repo scope (<repo>/.qtype/config.json)',
         'config.opt.showOrigin': 'Show where each entry comes from (file path and scope)',
+        'config.opt.all': 'List every configurable key, including schema defaults for unset keys',
         'config.example.setLang': 'Set CLI language',
         'config.example.list': 'List all effective config',
+        'config.list.example.all': 'List every configurable key with defaults',
         'config.get.summary': 'Get value',
         'config.get.description': 'Get value for a key (merged by default; exit 1 if key not set)',
         'config.get.example.basic': 'Read CLI language preference',
@@ -60,5 +66,7 @@ export const messages = {
         'config.list.example.global': 'Only user scope',
         'config.list.msg.empty': 'Config is empty',
         'config.list.msg.emptyScoped': 'Config is empty ({scope})',
+        'config.help.keysHeader': 'Available keys:',
+        'config.help.keysFooter': 'Use `qtype config set <key> <value>` to change one; `qtype config list --all` to see the full state.',
     },
 };

package/dist/cli/commands/config/index.js

@@ -1,5 +1,7 @@
 import { t } from '../../i18n/index.js';
 import { messages } from './i18n.js';
+import { userKv, repoKv } from '../../bootstrap.js';
+import { bold, dim } from '../../utils/output.js';
 import { configGetAction, configSetAction, configUnsetAction, configListAction, } from './action.js';
 /** Shared --global / --local / --show-origin options. */
 const scopeOptions = [
@@ -52,13 +54,59 @@ const listCmd = {
     options: [
         ...scopeOptions,
         { flags: '--show-origin', describe: () => t('config.opt.showOrigin') },
+        { flags: '--all', describe: () => t('config.opt.all') },
     ],
     examples: () => [
         { command: 'qtype config list', describe: () => t('config.list.example.merged') },
         { command: 'qtype config list --global', describe: () => t('config.list.example.global') },
+        { command: 'qtype config list --all', describe: () => t('config.list.example.all') },
     ],
     action: async (opts) => configListAction(opts),
 };
+/**
+ * Render every configurable key (from both user and repo schemas)
+ * as a `key = <default>  — description` list. Used by `qtype
+ * config --help` so users can discover what can be tuned without
+ * hunting through docs.
+ */
+function renderAvailableKeys() {
+    const rows = [];
+    const seen = new Set();
+    for (const k of userKv.knownKeys()) {
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        const e = userKv.getSchema(k);
+        rows.push({ key: k, scope: 'user', default: e.default, description: e.description, options: e.options });
+    }
+    for (const k of repoKv.knownKeys()) {
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        const e = repoKv.getSchema(k);
+        rows.push({ key: k, scope: 'repo', default: e.default, description: e.description, options: e.options });
+    }
+    rows.sort((a, b) => a.key.localeCompare(b.key));
+    const fmtDefault = (v) => {
+        if (v === undefined)
+            return '(no default)';
+        if (typeof v === 'string')
+            return v || '""';
+        return JSON.stringify(v);
+    };
+    const lines = [bold(t('config.help.keysHeader'))];
+    for (const r of rows) {
+        lines.push(`  ${r.key}  ${dim('=')}  ${fmtDefault(r.default)}  ${dim(`(${r.scope})`)}`);
+        if (r.description)
+            lines.push(`      ${dim(r.description)}`);
+        if (r.options && r.options.length > 0) {
+            lines.push(`      ${dim(`options: ${r.options.join(' | ')}`)}`);
+        }
+    }
+    lines.push('');
+    lines.push(dim(t('config.help.keysFooter')));
+    return lines.join('\n');
+}
 export const configCmd = {
     name: 'config',
     messages,
@@ -67,6 +115,8 @@ export const configCmd = {
     examples: () => [
         { command: 'qtype config set cli.lang zh', describe: () => t('config.example.setLang') },
         { command: 'qtype config list', describe: () => t('config.example.list') },
+        { command: 'qtype config list --all', describe: () => t('config.list.example.all') },
     ],
+    afterHelp: () => renderAvailableKeys(),
     subcommands: [getCmd, setCmd, unsetCmd, listCmd],
 };

package/dist/cli/registry/help.js

@@ -66,6 +66,12 @@ export function applyHelpMetadata(cmd, mod) {
     if (mod.seeAlso && mod.seeAlso.length > 0) {
         cmd.addHelpText('after', renderSeeAlso(mod.seeAlso));
     }
+    // Free-form afterHelp — printed last, useful for reference lists.
+    if (mod.afterHelp) {
+        const extra = mod.afterHelp();
+        if (extra && extra.trim())
+            cmd.addHelpText('after', '\n' + extra);
+    }
     // Aliases
     if (mod.aliases && mod.aliases.length > 0) {
         for (const alias of mod.aliases)

package/dist/core/schemas/both.js

@@ -5,48 +5,50 @@
  */
 import { enumValidator, boolValidator, positiveIntValidator, } from '../../store/index.js';
 export const bothSchema = {
-    // Repo language. Drives:
-    //   • which template locale (examples/zh vs examples/en) new repos are
-    //     scaffolded from
-    //   • the web UI language — the reader is locked to repo.lang so the UI
-    //     matches the material's own language
-    //
-    // Values are BCP 47 codes (`zh-CN` / `en-US`); the short forms `zh` /
-    // `en` are accepted for backwards compatibility with older `.qtype/
-    // config.json` files and normalised at read time.
     'repo.lang': {
         validator: enumValidator(['zh-CN', 'en-US', 'zh', 'en']),
         default: 'en-US',
+        description: 'Repo (and its published web UI) language.',
+        options: ['zh-CN', 'en-US'],
     },
     'typing.theme': {
         validator: enumValidator(['mocha', 'latte']),
         default: 'mocha',
+        description: 'Web reader theme.',
+        options: ['mocha', 'latte'],
     },
     'typing.targetWpm': {
         validator: positiveIntValidator(),
+        description: 'Ghost-pacer target speed in WPM. 0 = disabled.',
     },
     'typing.tabBehavior': {
         validator: enumValidator(['reset', 'input', 'disabled']),
         default: 'reset',
+        description: 'What pressing Tab in the arena does.',
+        options: ['reset', 'input', 'disabled'],
     },
     'typing.hint': {
         validator: enumValidator(['none', 'ghost']),
         default: 'none',
+        description: 'Whether to render a faint ghost hint under the caret.',
+        options: ['none', 'ghost'],
     },
     'typing.showKeyboard': {
         validator: boolValidator(),
         default: true,
+        description: 'Show the on-screen keyboard beneath the arena.',
+        options: ['true', 'false'],
     },
     'typing.showHands': {
         validator: boolValidator(),
         default: true,
+        description: 'Show the hand overlay on the on-screen keyboard.',
+        options: ['true', 'false'],
     },
-    // Mermaid pre-render mode. `prerender` (default) uses puppeteer at build
-    // time to bake SVGs into dist/material/mermaid.json; `client` ships raw
-    // ```mermaid fences and lets the browser render them; `off` treats mermaid
-    // as plain code blocks.
     'publish.mermaid': {
         validator: enumValidator(['prerender', 'client', 'off']),
         default: 'prerender',
+        description: 'Mermaid diagram handling at `publish build` time.',
+        options: ['prerender', 'client', 'off'],
     },
 };

package/dist/core/schemas/repo.js

@@ -6,43 +6,35 @@ import { enumValidator, nonEmptyStringValidator, boolValidator, } from '../../st
 export const repoOnlySchema = {
     'repo.name': {
         validator: nonEmptyStringValidator(),
+        description: 'Repo display name (folder title, package.json name).',
     },
     // ── Password protection for `publish build` ─────────────
-    // On/off toggle. When true, `publish build` reads the other three fields
-    // and encrypts every material/*.md before writing to dist.
     'publish.password.enabled': {
         validator: boolValidator(),
         default: false,
+        description: 'Encrypt materials at `publish build` time.',
+        options: ['true', 'false'],
     },
-    // Argon2id PHC-style hash of the plaintext password, used to verify the
-    // password entered at build time. NOT the AES key — that's derived
-    // separately via `publish.password.aesSalt`. Empty string when protection
-    // is off; shape enforced by `publish password set` writing a well-formed
-    // PHC string.
     'publish.password.hash': {
         validator: (v) => typeof v === 'string'
             ? null
             : { code: 'err.schema.nonEmptyString', fallback: 'must be a string' },
         default: '',
+        description: 'Argon2id PHC hash of the publish password (managed by `qtype publish password`).',
     },
-    // Base64 salt used with argon2id (password → AES-256 key). Rotated only
-    // when the user calls `publish password set` — stable across rebuilds so
-    // the same password unlocks previously published sites.
     'publish.password.aesSalt': {
         validator: (v) => typeof v === 'string'
             ? null
             : { code: 'err.schema.nonEmptyString', fallback: 'must be a string' },
         default: '',
+        description: 'Base64 salt used to derive the AES key (managed by `qtype publish password`).',
     },
-    // What to encrypt. `all` covers material/ + any future encrypted assets;
-    // `material-only` limits encryption to material/*.md (same behavior in
-    // v0 since qtype has no other content streams).
     'publish.password.scope': {
         validator: enumValidator(['all', 'material-only', 'selected']),
         default: 'all',
+        description: 'What to encrypt when password protection is on.',
+        options: ['all', 'material-only', 'selected'],
     },
-    // When scope='selected', the list of file names (relative to material/)
-    // to encrypt. Ignored otherwise.
     'publish.password.selected': {
         validator: (v) => Array.isArray(v) && v.every((x) => typeof x === 'string')
             ? null
@@ -51,5 +43,6 @@ export const repoOnlySchema = {
                 fallback: 'must be an array of strings',
             },
         default: [],
+        description: 'File names to encrypt when scope is `selected` (JSON array).',
     },
 };

package/dist/core/schemas/user.js

@@ -11,9 +11,13 @@ export const userOnlySchema = {
     'cli.lang': {
         validator: enumValidator(['zh-CN', 'en-US', 'zh', 'en']),
         default: 'en-US',
+        description: 'CLI display language.',
+        options: ['zh-CN', 'en-US'],
     },
     'cli.color': {
         validator: enumValidator(['always', 'never', 'auto']),
         default: 'auto',
+        description: 'Color output policy for CLI messages.',
+        options: ['always', 'never', 'auto'],
     },
 };

package/dist/core/typing/engine/TypingInput.js

@@ -140,6 +140,24 @@ export class TypingInput {
         this.#position = 0;
         this.#notify();
     }
+    /**
+     * Mark every character as Hit — used by the route's `completed`
+     * state (a card the user finished earlier) so downstream renderers
+     * paint the whole answer in green without needing a full snapshot
+     * of the original keystroke stream. Purely cosmetic: stats derived
+     * from timestamps stay zero.
+     */
+    markAllHit() {
+        const next = this.#chars.map((c) => ({
+            target: c.target,
+            typed: c.target,
+            attrs: (c.attrs & ~(CharAttr.Miss | CharAttr.Cursor)) | CharAttr.Hit,
+            timestamp: 0,
+        }));
+        this.#chars = next;
+        this.#position = this.#length;
+        this.#notify();
+    }
     get position() {
         return this.#position;
     }