@qnroa/qtype 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -13,6 +13,93 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [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
+and cleans up how "ignore punctuation" behaves. The invisible editor
+is now a `<input>` instead of a contenteditable div, matching the
+pattern every mainstream Chinese typing site uses; character capture
+reads `el.value` on the `input` event, so IME commits arrive as the
+final glyph — no more races between keydown and beforeinput.
+
+### Added
+- **Miss-slot display setting** (Appearance → Miss display). Default
+  keeps the target glyph visible in red (matches Monkeytype / keybr
+  / ohMyType / ptype conventions — user sees *what should have been
+  there*). Flip to "Typed" to render the user's actual keystroke in
+  red at the miss slot instead — useful when reviewing exactly what
+  went wrong.
+
+### Changed
+- **Editor element is now a hidden `<input>`, not `<div
+  contentEditable>`.** IME commits and macOS smart-punctuation
+  substitutions land in `el.value` as the final glyph, which the
+  `input` event reads and emits to the engine. Composition (pinyin
+  preedit) is gated on the event's own `isComposing` /
+  `inputType === 'insertCompositionText'` signals rather than the
+  hook's state machine, so browsers that fire `input` before
+  `compositionstart` can't leak preedit letters through as
+  characters.
+- **`Ignore punctuation` now rewrites punctuation to space at engine
+  construction.** Previously the engine fast-forwarded through
+  punctuation slots inside `onKeyDown`, which left the arena still
+  showing punctuation and the on-screen keyboard still hinting the
+  punctuation key. Now every punctuation codepoint in the target
+  becomes a regular space up-front — the arena, the keyboard hint
+  and the engine all see the same target sequence, no divergence.
+  Toggling the setting mid-card rebuilds the engine via the
+  `useTypingEngine` memo.
+
+### Fixed
+- **Chinese full-width punctuation shown as ASCII.** The old
+  keydown-based capture path picked up whichever of `keydown.key` /
+  `beforeinput.data` fired first and could substitute a half-width
+  glyph. Moving to `<input>` + `input` event and always rendering
+  the target glyph (default) puts an end to this class of bug.
+- **Dead `softInsertText` handler removed** from `INPUT_TYPE_HANDLERS`
+  and the `handleBeforeInput` fast-path; character emission has a
+  single owner now (the `input` event).
+
 ## [0.2.2] — 2026-09-01
 
 A responsive footer, a convention-based way to swap the site logo

package/CHANGELOG.zh.md

@@ -12,6 +12,74 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [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
+
+修复打字界面在中文输入法下的一系列老问题,并把"忽略标点"的行为
+理顺。隐藏的输入编辑器从 contenteditable 换成 `<input>`,和主流
+中文打字站的做法一致;字符捕获改为在 `input` 事件里读 `el.value`,
+IME 提交后的最终字符直接进引擎 —— 不再有 keydown 和 beforeinput
+的竞态。
+
+### 新增
+- **错误显示设置**(外观 → 错误显示)。默认保持目标字符可见(红色),
+  和 Monkeytype / keybr / ohMyType / ptype 一致 —— 用户看到的是
+  "本来应该是什么"。切到"实际输入"则在错误位置显示用户实际敲入
+  的字符(仍然红色),方便复盘到底敲错在哪。
+
+### 变更
+- **编辑器元素从 `<div contentEditable>` 改为隐藏 `<input>`。** IME
+  提交和 macOS 智能标点替换都会把最终字符写进 `el.value`,由
+  `input` 事件读到再喂给引擎。组词状态(拼音预输入)靠事件自身的
+  `isComposing` / `inputType === 'insertCompositionText'` 判断,
+  不再依赖 hook 状态机的时序;这样即便浏览器先 `input` 后
+  `compositionstart`,预输入的拼音字母也不会以字符形式泄漏出去。
+- **`忽略标点` 改为在引擎构造时把标点重写成空格。** 之前是引擎在
+  `onKeyDown` 里 fast-forward 跳过标点位置,但界面上标点还在显示,
+  键盘还在提示打标点键。现在所有标点 codepoint 上来就变空格 ——
+  arena、键盘提示、引擎看到的目标序列完全一致,不会跑偏。中途切换
+  设置时通过 `useTypingEngine` 的 memo 重建引擎。
+
+### 修复
+- **中文全角标点显示成 ASCII。** 老的 keydown 捕获路径会挑
+  `keydown.key` 或 `beforeinput.data` 里先来的那个,可能替换成半角。
+  改用 `<input>` + `input` 事件、并默认在打错位置显示目标字符,
+  这类问题一次性解决。
+- **删除死代码 `softInsertText`。** `INPUT_TYPE_HANDLERS` 和
+  `handleBeforeInput` 里的 `insertText` 特殊分支一起删掉,字符发射
+  只由 `input` 事件负责。
+
 ## [0.2.2] — 2026-09-01
 
 响应式页脚,约定式自定义 logo 和 favicon(不用改代码),以及把 view

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

@@ -31,10 +31,28 @@ export class TypingInput {
     #position;
     #listeners = new Set();
     constructor(text, settings) {
-        this.#target = text;
-        this.#targetCodepoints = Array.from(text, (ch) => ch.codePointAt(0) ?? 0);
-        this.#length = this.#targetCodepoints.length;
         this.settings = { ...defaultTypingSettings, ...settings };
+        // ignorePunctuation replaces every punctuation codepoint with a
+        // regular space in the target sequence. The engine, the arena
+        // renderer, and the keyboard hint all just see a space — no
+        // fast-forward machinery, no special-case display, no divergence
+        // between what the user sees and what they need to type.
+        const raw = Array.from(text, (ch) => ch.codePointAt(0) ?? 0);
+        this.#targetCodepoints = this.settings.ignorePunctuation
+            ? raw.map((cp) => (isPunctuation(cp) ? 0x20 : cp))
+            : raw;
+        // The effective target string: rewritten if ignorePunctuation is
+        // on, else identical to `text`. Anything that consumes
+        // `engine.target` (keyboard-hint plans, mini-arena mirrors, etc.)
+        // sees exactly the sequence the engine expects the user to type.
+        // We avoid `String.fromCodePoint(...arr)` here — spreading a large
+        // codepoint array can blow the JS engine's argument-count ceiling
+        // on unusually long targets. Building char-by-char is O(n) with no
+        // fixed upper bound.
+        this.#target = this.settings.ignorePunctuation
+            ? this.#targetCodepoints.map((cp) => String.fromCodePoint(cp)).join('')
+            : text;
+        this.#length = this.#targetCodepoints.length;
         this.#chars = this.#buildInitialChars();
         this.#position = 0;
     }
@@ -60,20 +78,7 @@ export class TypingInput {
         if (this.#position >= this.#length) {
             return Feedback.Correct;
         }
-        let expected = this.#targetCodepoints[this.#position];
-        // ignorePunctuation: fast-forward through any punctuation slots
-        // before matching the user's keystroke against the next
-        // typable character. Uses a broad Unicode range so it works
-        // for both ASCII and CJK punctuation.
-        if (this.settings.ignorePunctuation) {
-            while (this.#position < this.#length &&
-                isPunctuation(this.#targetCodepoints[this.#position])) {
-                this.#autoAdvance(timestamp);
-            }
-            if (this.#position >= this.#length)
-                return Feedback.Correct;
-            expected = this.#targetCodepoints[this.#position];
-        }
+        const expected = this.#targetCodepoints[this.#position];
         // Normalize both sides through the same equivalence table so
         // fullwidth/half-width / smart-quote / CJK-punctuation variants
         // don't cause false misses. Display remains untouched.
@@ -195,28 +200,6 @@ export class TypingInput {
         for (const l of this.#listeners)
             l();
     }
-    /**
-     * Mark the current slot as auto-advanced Hit (used by
-     * `ignorePunctuation`). Records the timestamp so stats include the
-     * auto-advance in `startedAt` timing, but doesn't count it toward
-     * user keystroke totals (still shows as Hit — the punctuation was
-     * "correctly typed" via the auto-advance rule).
-     */
-    #autoAdvance(timestamp) {
-        if (this.#position >= this.#length)
-            return;
-        const expected = this.#targetCodepoints[this.#position];
-        const next = this.#chars.slice();
-        const prev = next[this.#position];
-        next[this.#position] = {
-            target: expected,
-            typed: expected,
-            attrs: (prev.attrs & ~(CharAttr.Miss | CharAttr.Cursor)) | CharAttr.Hit,
-            timestamp,
-        };
-        this.#chars = next;
-        this.#position++;
-    }
 }
 /**
  * ASCII case-insensitive comparison. Non-ASCII (CJK, accented Latin,
@@ -233,35 +216,56 @@ 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.
  */
 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;
+    }
 }