@qnroa/qtype 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -13,6 +13,50 @@ 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

package/CHANGELOG.zh.md

@@ -12,6 +12,40 @@ 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 菜单如何呈现设置"两件事,

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
@@ -227,6 +279,50 @@ function sameLetter(a, b) {
  * 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) {
     switch (cp) {
         // ASCII sentence / clause marks.  .  ,  !  ?  ;  :  '  "

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

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