@qnroa/qtype 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -13,6 +13,90 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-09-14
+
+Second pass on card-lifecycle correctness plus a code-typing quality-
+of-life feature. The completion pill no longer overlaps card content,
+navigating between done and not-done cards no longer poisons the
+fresh card with a "already done" paint, and code cards can skip
+leading indentation the way typing.io does.
+
+### Added
+- **Auto-skip indent** (Typing rules → Auto-skip indent). Every line's
+  leading spaces / tabs are pre-hit for the user — the cursor jumps to
+  the first real character on each line, so code cards no longer force
+  you to type ten spaces before every statement. On by default; toggle
+  in Settings or via the HUD ⋮ menu. Same behaviour typing.io ships as
+  its default and defended publicly against "just make me type it"
+  arguments in early user feedback. Blank lines (pure-whitespace lines)
+  are not skipped — the user still hits Enter for them.
+
+### Fixed
+- **Completion pill overlapping card content.** The "press Enter to
+  continue" hint used to sit under the HUD as an absolute-positioned
+  pill; on code / article cards where the prompt sits right below the
+  HUD, it landed on top of the first line of content. The hint now
+  lives in a fixed-height notification strip between the stage and the
+  keyboard — same pattern Anki / Duolingo use — so it never overlays
+  content and layout doesn't shift when it appears or leaves.
+- **Wrong card shown as "already done" after rewind then advance.**
+  Sequence: finish card 1 → auto-advance to card 2 → rewind to card 1
+  (correctly rendered as done) → advance back to card 2, which was
+  now painted green even though the user had never typed it. Root
+  cause: the route's `useEffect` for `markAllHit()` ran after `cardId`
+  changed but before the state machine's `CARD_ENTER` effect settled
+  the new `kind`, so a stale `completed` from the previous card
+  painted the fresh engine. The effect now cross-checks the
+  authoritative `cardDone` (from `useDoneState`) before calling
+  `markAllHit()`.
+- **Auto-advance timer not scheduling after `manual → auto` mid-pass.**
+  If the user switched advance mode from manual to auto while sitting
+  in a `passed{awaitingAdvance}` state, the 700ms timer that fires
+  `STAMP_TIMEOUT` never scheduled — the effect that owns it had no
+  `advanceMode` dep and its `prev !== 'passed'` gate blocked re-entry.
+  The gate is now `stampTimerRef.current === null` (idempotent), and
+  `advanceMode` is a proper dep.
+
+## [0.2.4] — 2026-09-08
+
+Bug-fix + refactor pass around the ignore-punctuation setting and the
+plumbing that surfaces settings in the command palette and HUD menu.
+
+### Fixed
+- **Ignore-punctuation used to eat operators.** `+`, `-`, `*`, `/`,
+  `=`, `<`, `>`, `(`, `)` and other code / math symbols were treated
+  as punctuation, so turning the setting on rewrote whole code
+  passages into runs of blanks. The punctuation set is now the same
+  9 ASCII marks keybr / ptype / Monkeytype recognise
+  (`. , ! ? ; : ' " -` — sentence and clause marks only) plus the
+  corresponding CJK sentence marks, smart quotes, and Chinese book /
+  corner-bracket pairs. Operators and brackets pass through
+  unchanged.
+- **Arena stale-render after toggling ignore-punctuation.** Switching
+  the setting mid-card left the arena rendered against the previous
+  engine's target for a tick, so punctuation slots appeared to
+  linger until the next event. The arena is now keyed on
+  `${card.id}::${engine.target}`, forcing a full remount whenever
+  the engine's effective target changes — no stale
+  `useSyncExternalStore` subscription, no leftover DOM.
+
+### Changed
+- **HUD ⋮ menu is now registry-driven.** Every settings entry that
+  opts in via `hud: { icon, order? }` shows up as a quick toggle
+  during typing. `hint`, `ignoreCase`, `ignorePunctuation`,
+  `allowBackspace`, `showKeyboard`, `showHands` land in the menu by
+  default; `showPhonetic`, `showGloss`, `autoSpeak` show up on word
+  / sentence cards. Adding a new HUD toggle is now one registry
+  line.
+- **Command palette lists every setting.** The palette walks the
+  settings registry and emits a `setting.<id>` command per entry —
+  bool settings toggle inline; enum / number / action settings open
+  the settings dialog scrolled to the row. No more manually adding
+  palette entries for each new setting.
+- **`useHint()` extracted.** Three call sites were inlining the
+  same `usePersistedState<HintMode>('settings', 'hint', ...)` block;
+  they all use the shared hook now.
+
 ## [0.2.3] — 2026-09-07
 
 Fixes long-standing bugs around Chinese IME input on the typing arena

package/CHANGELOG.zh.md

@@ -12,6 +12,72 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-09-14
+
+围绕卡片生命周期的正确性又做了一轮修复,并加入一个代码打字的
+体验改进。完成提示条不再压卡片内容;在"已完成"和"未打"卡片
+之间来回切,新卡不再被误标为"已完成";代码卡按 typing.io 的做法
+自动跳过缩进。
+
+### 新增
+- **自动跳过缩进**(打字规则 → 自动跳过缩进)。每行开头的空格 / Tab
+  由系统自动填入,光标直接落在第一个真字符上 —— 代码卡不再逼你
+  每句前先敲十个空格。默认开启,可在设置或 HUD ⋮ 菜单里切换。
+  typing.io 默认就是这个行为,作者曾公开对"就让用户自己打空格吧"
+  这种意见做过反驳。纯空白行(只有空格 + 换行)不自动跳过,用户
+  仍需手动敲回车。
+
+### 修复
+- **完成提示条压卡片内容。** "按 Enter 继续"提示原来是挂在 HUD
+  下方的绝对定位气泡,在代码 / 文章类卡片(内容紧贴 HUD 下方)
+  时会盖住第一行内容。现在提示条改成打字区和键盘之间的**固定
+  高度通知条**,和 Anki / Duolingo 一样 —— 不遮内容,布局也不会
+  在提示出现 / 消失时跳动。
+- **回退再前进后新卡被误显示为"已完成"。** 场景:打完卡片 1 →
+  自动到卡片 2 → 退回卡片 1(正确显示为完成)→ 再前进到卡片 2,
+  卡片 2 被涂满绿色,尽管从没打过。根因:route 里的
+  `markAllHit()` useEffect 在 `cardId` 变化后先跑,状态机
+  `CARD_ENTER` effect 后跑,`kind` 仍是旧的 `completed`,把新引擎
+  也涂绿了。现在这个 effect 会**同时校验** `useDoneState` 里真实
+  的 `cardDone`,不再单信任 stale `kind`。
+- **`manual → auto` 中途切换后自动前进 timer 不触发。** 用户在
+  `passed{awaitingAdvance}` 里把前进模式从 manual 切到 auto,原本
+  700ms 定时器不启动 —— effect 的 deps 里没有 `advanceMode`,而且
+  `prev !== 'passed'` 的守卫挡住了二次进入。改成幂等守卫
+  (`stampTimerRef.current === null`)并把 `advanceMode` 加入 deps。
+
+## [0.2.4] — 2026-09-08
+
+围绕"忽略标点"设置和"命令面板 / HUD 菜单如何呈现设置"两件事,
+做了一轮修复和小重构。
+
+### 修复
+- **忽略标点误伤运算符。** 之前 `+ - * / = < > ( )` 等代码 / 数学
+  符号都被当成标点,一开设置就把整段代码替换成空格。改成和
+  keybr / ptype / Monkeytype 一致的 9 个 ASCII 句读
+  (`. , ! ? ; : ' " -`),加上对应的中文句号 / 逗号 / 冒号 / 分号 /
+  问号 / 感叹号 / 顿号 + 中文引号 / 书名号 / 角括号。运算符和括号
+  一律不动。
+- **切换忽略标点后 arena 一瞬间残留旧渲染。** 卡片打字中途切设置,
+  引擎重建了但 arena 的 fiber 被复用,`useSyncExternalStore`
+  订阅还挂在旧 engine 上,标点位置视觉错乱,得刷新才好。arena
+  的 React key 改成 `${card.id}::${engine.target}`,engine 目标
+  一变就整棵重挂,零残留。
+
+### 变更
+- **HUD ⋮ 菜单改为注册表驱动。** 设置条目里加 `hud: { icon, order? }`
+  就自动出现在打字时的快捷菜单。默认加入的:显示提示、忽略大小写、
+  忽略标点、允许退格、显示键盘、显示手位;word / sentence 卡片
+  额外多显示音标 / 释义 / 自动朗读。加一个 HUD 快捷开关现在只需
+  改注册表一行。
+- **命令面板列出所有设置。** 面板遍历设置注册表,给每个条目生成一条
+  `setting.<id>` 命令。bool 类型直接就地翻转;枚举 / 数字 / action
+  打开设置对话框并高亮那一行。新增设置不再需要单独往命令面板加
+  条目。
+- **抽出 `useHint()` hook。** 之前 3 个地方内联同样的
+  `usePersistedState<HintMode>('settings', 'hint', ...)`,现在统一用
+  这个 hook。
+
 ## [0.2.3] — 2026-09-07
 
 修复打字界面在中文输入法下的一系列老问题,并把"忽略标点"的行为

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

@@ -26,6 +26,10 @@ export class TypingInput {
     #target;
     #targetCodepoints;
     #length;
+    /** Per-slot flag: this slot is a leading-indent whitespace that the
+     *  engine will auto-hit under `autoSkipIndent`. Computed once at
+     *  construction from the target's line structure. */
+    #skipMask;
     settings;
     #chars;
     #position;
@@ -53,8 +57,17 @@ export class TypingInput {
             ? this.#targetCodepoints.map((cp) => String.fromCodePoint(cp)).join('')
             : text;
         this.#length = this.#targetCodepoints.length;
+        this.#skipMask = this.settings.autoSkipIndent
+            ? buildIndentSkipMask(this.#targetCodepoints)
+            : new Array(this.#length).fill(false);
         this.#chars = this.#buildInitialChars();
         this.#position = 0;
+        // If the target starts with indent whitespace, auto-advance past
+        // it before the user's first keystroke so the initial cursor is
+        // on the first "real" character. Subsequent lines are handled in
+        // `onKeyDown` after a newline hit lands the cursor on the next
+        // line's leading whitespace.
+        this.#autoAdvanceSkipped(0);
     }
     #buildInitialChars() {
         const chars = new Array(this.#length);
@@ -103,6 +116,12 @@ export class TypingInput {
         this.#chars = next;
         if (isHit || !this.settings.stopOnError) {
             this.#position++;
+            // After advancing, if the new position is an auto-skip indent
+            // whitespace (typical case: user just hit newline, cursor sits
+            // on the next line's leading spaces / tabs), fast-forward
+            // through those slots so the user's next keystroke lands on
+            // real code.
+            this.#autoAdvanceSkipped(timestamp);
         }
         this.#notify();
         if (recovered)
@@ -122,7 +141,13 @@ export class TypingInput {
             // Signal that the user is trying to rewind past start.
             return Feedback.Restart;
         }
-        this.#position--;
+        // Skip back over any auto-hit indent whitespace so the user
+        // doesn't "rewind" into invisible-to-them spaces. Land on the
+        // most recent user-touched slot.
+        let target = this.#position - 1;
+        while (target > 0 && this.#skipMask[target])
+            target--;
+        this.#position = target;
         const next = this.#chars.slice();
         const prev = next[this.#position];
         // Clear Hit/Miss (this slot is now pending again) but remember it
@@ -143,8 +168,35 @@ export class TypingInput {
     reset() {
         this.#chars = this.#buildInitialChars();
         this.#position = 0;
+        this.#autoAdvanceSkipped(0);
         this.#notify();
     }
+    /**
+     * Walk `#position` past every consecutive auto-skip indent slot,
+     * marking each as an auto-hit so the arena renders them green.
+     * `timestamp` is stamped onto the skipped chars for consistency
+     * with real hits; downstream stats ignore auto-hit timestamps for
+     * WPM computation since they weren't user keystrokes.
+     */
+    #autoAdvanceSkipped(timestamp) {
+        if (!this.settings.autoSkipIndent)
+            return;
+        while (this.#position < this.#length &&
+            this.#skipMask[this.#position]) {
+            const idx = this.#position;
+            const expected = this.#targetCodepoints[idx];
+            const next = this.#chars.slice();
+            const prev = next[idx];
+            next[idx] = {
+                target: expected,
+                typed: expected,
+                attrs: (prev.attrs & ~(CharAttr.Miss | CharAttr.Cursor)) | CharAttr.Hit,
+                timestamp,
+            };
+            this.#chars = next;
+            this.#position++;
+        }
+    }
     /**
      * Mark every character as Hit — used by the route's `completed`
      * state (a card the user finished earlier) so downstream renderers
@@ -216,35 +268,100 @@ function sameLetter(a, b) {
     return false;
 }
 /**
- * Rough Unicode punctuation test — ASCII punctuation + CJK
- * fullwidth range + common typographic marks. Kept explicit
- * (no `\p{P}` regex) so the check is fast and predictable.
+ * Sentence / clause punctuation, per keybr + ptype + Monkeytype
+ * conventions. Explicitly excludes math operators (`+ - * / = < >`),
+ * brackets (`( ) [ ] { }`), and code-symbol characters (`_ | \ @ # $
+ * % & ^ ~ \``) — those show up in real prose and code and should be
+ * typed as-is, not silently rewritten to space.
+ *
+ * Uses an inline set of codepoints instead of `\p{P}` — the Unicode
+ * punctuation category also matches math / brackets / dashes we want
+ * to leave alone, which is exactly why every mainstream typing app
+ * hard-codes its own list.
+ */
+/**
+ * Mark every codepoint that is leading whitespace on its line — a run
+ * of ASCII space (0x20) or tab (0x09) at line-start, up to (but not
+ * including) the first non-whitespace character on that line. Blank
+ * lines (nothing but whitespace between two newlines) are not
+ * flagged — the user still hits Enter for them, and there is no
+ * "indent" to skip.
  */
+function buildIndentSkipMask(cps) {
+    const mask = new Array(cps.length).fill(false);
+    let atLineStart = true;
+    for (let i = 0; i < cps.length; i++) {
+        const cp = cps[i];
+        if (cp === 0x0a) {
+            atLineStart = true;
+            continue;
+        }
+        if (atLineStart && (cp === 0x20 || cp === 0x09)) {
+            mask[i] = true;
+            continue;
+        }
+        atLineStart = false;
+    }
+    // Blank lines: a run of whitespace immediately followed by a
+    // newline is not "indentation" — un-flag it so the user still has
+    // to hit Enter (or space, if the line is really pure spaces) to
+    // pass. Walk each flagged run and check whether it ends at a
+    // newline before any non-whitespace.
+    for (let i = 0; i < mask.length; i++) {
+        if (!mask[i])
+            continue;
+        let j = i;
+        while (j < mask.length && mask[j])
+            j++;
+        // j is the first non-mask index after the run. If cps[j] is a
+        // newline or end-of-input, this run isn't indent — clear it.
+        if (j >= cps.length || cps[j] === 0x0a) {
+            for (let k = i; k < j; k++)
+                mask[k] = false;
+        }
+        i = j - 1;
+    }
+    return mask;
+}
 function isPunctuation(cp) {
-    // ASCII punctuation:  ! " # $ % & ' ( ) * + , - . /   : ; < = > ? @
-    // [ \ ] ^ _ `   { | } ~
-    if (cp >= 0x21 && cp <= 0x2f)
-        return true;
-    if (cp >= 0x3a && cp <= 0x40)
-        return true;
-    if (cp >= 0x5b && cp <= 0x60)
-        return true;
-    if (cp >= 0x7b && cp <= 0x7e)
-        return true;
-    // CJK Symbols and Punctuation
-    if (cp >= 0x3000 && cp <= 0x303f)
-        return true;
-    // Fullwidth ASCII forms (includes fullwidth punctuation)
-    if (cp >= 0xff01 && cp <= 0xff0f)
-        return true;
-    if (cp >= 0xff1a && cp <= 0xff20)
-        return true;
-    if (cp >= 0xff3b && cp <= 0xff40)
-        return true;
-    if (cp >= 0xff5b && cp <= 0xff65)
-        return true;
-    // General Punctuation block
-    if (cp >= 0x2000 && cp <= 0x206f)
-        return true;
-    return false;
+    switch (cp) {
+        // ASCII sentence / clause marks.  .  ,  !  ?  ;  :  '  "
+        case 0x2e:
+        case 0x2c:
+        case 0x21:
+        case 0x3f:
+        case 0x3b:
+        case 0x3a:
+        case 0x27:
+        case 0x22:
+        // CJK sentence marks:  。  、
+        case 0x3001:
+        case 0x3002:
+        // Fullwidth forms:  ！  ？  ，  ：  ；  ＇  ＂
+        case 0xff01:
+        case 0xff1f:
+        case 0xff0c:
+        case 0xff1a:
+        case 0xff1b:
+        case 0xff07:
+        case 0xff02:
+        // Smart quotes:  " "  ' '
+        case 0x201c:
+        case 0x201d:
+        case 0x2018:
+        case 0x2019:
+        // Book title marks:  《 》  〈 〉
+        case 0x300a:
+        case 0x300b:
+        case 0x3008:
+        case 0x3009:
+        // CJK corner brackets:  「 」  『 』
+        case 0x300c:
+        case 0x300d:
+        case 0x300e:
+        case 0x300f:
+            return true;
+        default:
+            return false;
+    }
 }

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

@@ -3,4 +3,5 @@ export const defaultTypingSettings = {
     ignoreCase: false,
     ignorePunctuation: false,
     allowBackspace: true,
+    autoSkipIndent: false,
 };