@qnroa/qtype 0.0.9 → 0.1.1

package/dist/core/cardId.js

@@ -0,0 +1,101 @@
+/**
+ * Content-derived card id.
+ *
+ * Historically qtype used `<file>#<indexInMaterial>` as the card id. That
+ * value doubled as a stable "identity" (for done tracking, filter hit
+ * lists, deep links) while also being the physical position pointer —
+ * so any time the author inserted / removed / reordered a card, every
+ * downstream id in that material shifted, silently invalidating every
+ * saved reference.
+ *
+ * The new id is a SHA-256 prefix over the card's content-defining
+ * fields:
+ *
+ *   materialFile + '\n' + title + '\n' + answer + '\n' + question
+ *
+ * — trimmed to 12 hex chars (48 bits, ~2^24 birthday collision boundary,
+ * plenty for a single repo). This makes the id:
+ *   • Reorder-safe (position doesn't feed the hash).
+ *   • Human-copy-friendly (short enough to paste in URLs).
+ *   • Content-change-sensitive (a real edit produces a new id, which is
+ *     the honest behaviour — the reader treats the pre-edit and post-edit
+ *     forms as distinct cards).
+ *
+ * We ship a small sync SHA-256 rather than pulling in `crypto.subtle`
+ * (async, needs to be awaited at parse time) — the payload is tiny and
+ * the parser stays synchronous.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+const HEX = '0123456789abcdef';
+function toHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        out += HEX[b >>> 4] + HEX[b & 0x0f];
+    }
+    return out;
+}
+/** Content hash prefix length in hex chars. 12 hex = 48 bits. */
+export const CARD_ID_LEN = 12;
+export function computeCardId(input) {
+    const src = [
+        input.materialFile,
+        input.title,
+        input.answer,
+        input.question ?? '',
+    ].join('\n');
+    const bytes = sha256(new TextEncoder().encode(src));
+    return toHex(bytes).slice(0, CARD_ID_LEN);
+}
+// ─── URL slug encoding ────────────────────────────────────────────
+//
+// URL shape:
+//   /typing/<material-path>/<idx>-<cardId>
+//
+//   /typing/qa/algorithms/25-f849bcc10faf
+//   /typing/code/algo/array/cpp/3-abc123def456
+//
+// The material path echoes the source `material/*.md` tree with the
+// `.md` extension stripped. `idx` is the card's 0-based position in
+// its material; `cardId` is a 12-hex content hash used as a
+// verification code — if the URL's `idx` no longer points at the
+// card whose content produced `cardId`, the typing route quietly
+// redirects to the current position.
+//
+// Splitting on the LAST dash is deliberate: material names may
+// legitimately contain dashes (`en/idioms-day1`), so a "split on
+// any dash" scheme would misinterpret them. Idx + cardId sit at the
+// end; the material path is whatever comes before the last `/`.
+/**
+ * Build the `/typing/...` splat portion (i.e. everything after
+ * `/typing/`). Does NOT `.md`-strip or url-encode — callers pass
+ * `materialFile` without the extension.
+ */
+export function formatCardSlug(materialFile, indexInMaterial, cardId) {
+    const stem = materialFile.replace(/\.md$/, '');
+    return `${stem}/${indexInMaterial}-${cardId}`;
+}
+export function parseCardSlug(slug) {
+    const lastSlash = slug.lastIndexOf('/');
+    if (lastSlash < 0)
+        return null;
+    const stem = slug.slice(0, lastSlash);
+    const tail = slug.slice(lastSlash + 1);
+    const lastDash = tail.lastIndexOf('-');
+    if (lastDash < 0)
+        return null;
+    const idxStr = tail.slice(0, lastDash);
+    const cardId = tail.slice(lastDash + 1);
+    const idx = parseInt(idxStr, 10);
+    if (!Number.isFinite(idx) || idx < 0)
+        return null;
+    if (!/^[0-9a-f]{12}$/.test(cardId))
+        return null;
+    if (!stem)
+        return null;
+    return {
+        materialFile: `${stem}.md`,
+        indexInMaterial: idx,
+        cardId,
+    };
+}

package/dist/core/index.js

@@ -7,3 +7,4 @@ export * from './typing/index.js';
 export { charToKeystrokes, textToCharPlans } from './keystroke/index.js';
 export { normalizeText, validateTypingText } from './keystroke/textNormalize.js';
 export * from './encrypt.js';
+export { computeCardId, CARD_ID_LEN, formatCardSlug, parseCardSlug, } from './cardId.js';

package/dist/core/keystroke/textNormalize.js

@@ -1,15 +1,18 @@
 // Import-time text sanitization + validation.
-// Goal: guarantee that every character surviving normalization has a valid
-// keystroke plan, so runtime never has to skip or bail on unknown chars.
+//
+// This layer used to rewrite user-visible characters (smart quotes to
+// straight, fullwidth space to half, em-dash to double hyphen, etc.) at
+// import time — which meant the *displayed* text no longer matched what
+// the author wrote. That's the wrong layer: display should be honest
+// about the source; runtime equivalence for typing lives in
+// `typing/engine/normalize.ts` and only affects comparison.
+//
+// So the rewrite table is empty. We still strip characters that are
+// truly untypable (control chars, zero-width, emoji), because those
+// have no keyboard input at all.
 import { charToKeystrokes } from './index.js';
-// Character rewrites: smart quotes, unusual dashes, etc.
-const REWRITE = {
-    '—': '——', // em-dash → double hyphen (matches keystroke plan for 中文 —)
-    '–': '-', // en-dash → hyphen
-    '…': '……', // horizontal ellipsis → double per convention (chineseMap uses ……)
-    ' ': ' ', // non-breaking space → regular space
-    '　': ' ', // ideographic space → regular space
-};
+// Rewrites are intentionally empty. See file-level comment.
+const REWRITE = {};
 // Ranges of code points to strip entirely (they can't be typed).
 const STRIP_RANGES = [
     [0x0000, 0x0008], // C0 controls before \t

package/dist/core/parser/frontmatter.js

@@ -10,9 +10,8 @@ const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
  *   updated: YYYY-MM-DD
  *   ---
  *
- * Card-level frontmatter no longer exists — everything a card carries
- * is expressed by its markdown structure (see parseMaterial for the
- * per-type rules).
+ * `type` and `tags` here are *defaults* — cards can override via
+ * their own `parseCardFrontmatter` block (see above).
  */
 export function parseMaterialFrontmatter(source) {
     const meta = {};

package/dist/core/parser/parseMaterial.js

@@ -1,3 +1,4 @@
+import { computeCardId } from '../cardId.js';
 import { parseMaterialFrontmatter, parseCardFrontmatter } from './frontmatter.js';
 import { textToCharPlans } from '../keystroke/index.js';
 import { validateTypingText } from '../keystroke/textNormalize.js';
@@ -20,13 +21,31 @@ export function parseMaterial(source, filePath = 'inline') {
  * Split the material body (after frontmatter) into per-card chunks,
  * one per H1. Each chunk starts with its `# heading` line and includes
  * everything up to the next H1 (or end-of-file).
+ *
+ * H1 detection is fence-aware — lines that look like `# ...` while
+ * inside a ``` ``` fenced code block are treated as body content (a
+ * shell / Python / Ruby comment), not as a new card. Without this,
+ * material files that embed code with hash comments (e.g. a regex
+ * primer's Python examples) get sliced into dozens of bogus cards
+ * whose ids leak downstream through the `<file>#<idx>` scheme.
  */
 function splitByH1(body) {
     const lines = body.split('\n');
     const chunks = [];
     let current = null;
+    let inFence = false;
     for (const line of lines) {
-        if (/^#\s+/.test(line)) {
+        // Toggle fence state on any line starting with ``` — matches the
+        // opening (with an optional language tag) and the closing (bare)
+        // form. Fence lines themselves count as body if we're already
+        // tracking a card.
+        if (/^```/.test(line)) {
+            inFence = !inFence;
+            if (current)
+                current.push(line);
+            continue;
+        }
+        if (!inFence && /^#\s+/.test(line)) {
             if (current)
                 chunks.push(current.join('\n').trim());
             current = [line];
@@ -97,6 +116,12 @@ function parseCard(chunk, defaultType, defaultTags, filePath, index) {
         return null;
     card.type = cardType;
     card.tags = tags;
+    card.id = computeCardId({
+        materialFile: filePath,
+        title: card.title,
+        answer: card.answer,
+        question: card.question,
+    });
     return card;
 }
 function dedupe(tags) {
@@ -126,7 +151,9 @@ function buildAnnotatedCard(title, body, filePath, index) {
     const h4 = extractHeadingContent(body, 4);
     const charPlans = textToCharPlans(answer);
     return {
-        id: `${filePath}#${index}`,
+        id: '', // filled in by parseCard after content is finalised
+        materialFile: filePath,
+        indexInMaterial: index,
         title: answer,
         answer,
         phonetic: h2 || undefined,
@@ -154,7 +181,9 @@ function buildArticleCard(title, body, filePath, index) {
         return null;
     const charPlans = textToCharPlans(answer);
     return {
-        id: `${filePath}#${index}`,
+        id: '', // filled in by parseCard after content is finalised
+        materialFile: filePath,
+        indexInMaterial: index,
         title,
         answer,
         // `question` carries the raw body so images render in the card
@@ -188,7 +217,9 @@ function buildQACard(title, body, filePath, index) {
         return null;
     const charPlans = textToCharPlans(answer);
     return {
-        id: `${filePath}#${index}`,
+        id: '', // filled in by parseCard after content is finalised
+        materialFile: filePath,
+        indexInMaterial: index,
         title,
         answer,
         question,

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

@@ -19,6 +19,7 @@
  */
 import { CharAttr } from './chars.js';
 import { Feedback } from './feedback.js';
+import { normalizeForCompare } from './normalize.js';
 import { defaultTypingSettings, } from './settings.js';
 import { computeStats } from './stats.js';
 export class TypingInput {
@@ -73,9 +74,14 @@ export class TypingInput {
                 return Feedback.Correct;
             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.
+        const nCp = normalizeForCompare(codePoint);
+        const nExp = normalizeForCompare(expected);
         const isHit = this.settings.ignoreCase
-            ? sameLetter(codePoint, expected)
-            : codePoint === expected;
+            ? sameLetter(nCp, nExp)
+            : nCp === nExp;
         // Clone the array so subscribers see a new reference. Only the touched
         // Char is a new object — the rest are shared.
         const next = this.#chars.slice();

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

@@ -0,0 +1,87 @@
+/**
+ * Runtime input normalization for typing comparison.
+ *
+ * The engine used to compare `codePoint === expected` strictly, which broke
+ * for equivalent-but-different characters that the OS/IME hands out
+ * depending on state:
+ *
+ *   - Fullwidth space U+3000 vs regular space U+0020 (Chinese IME)
+ *   - Non-breaking space U+00A0 vs U+0020
+ *   - Smart quotes U+201C/U+201D/U+2018/U+2019 vs straight quotes
+ *   - Fullwidth CJK punctuation (U+FF0C etc.) vs ASCII punctuation
+ *   - En-dash U+2013 vs hyphen U+002D
+ *   - Horizontal ellipsis U+2026 vs three dots
+ *
+ * These are all pairs where the two forms carry the same *intent* — the
+ * user is trying to type the character they see, and shouldn't be
+ * penalised because their input method emitted a different codepoint.
+ *
+ * The rule: normalize BOTH the user's keystroke and the expected
+ * character through the same table, then compare. Display is untouched.
+ *
+ * Character classes we do NOT normalize:
+ *   - Fullwidth Latin letters (U+FF21..U+FF3A / U+FF41..U+FF5A) — if a
+ *     card contains "Ａ" that's the author's explicit intent; ignoreCase
+ *     handles the ASCII case elsewhere.
+ *   - Fullwidth digits (U+FF10..U+FF19) — same reasoning.
+ *   - Curly braces / angles that carry semantic meaning in Chinese text.
+ */
+/** Char → equivalent char used for typing comparison. */
+const EQUIV = {
+    // ─── Spaces ───────────────────────────────────────────
+    0x3000: 0x0020, // U+3000 IDEOGRAPHIC SPACE
+    0x00A0: 0x0020, // U+00A0 NO-BREAK SPACE
+    // ─── Quotes ────────────────────────────────────────────
+    0x201C: 0x0022, // U+201C LEFT DOUBLE QUOTATION MARK
+    0x201D: 0x0022, // U+201D RIGHT DOUBLE QUOTATION MARK
+    0x201E: 0x0022, // U+201E DOUBLE LOW-9
+    0x2033: 0x0022, // U+2033 DOUBLE PRIME
+    0x2018: 0x0027, // U+2018 LEFT SINGLE QUOTATION MARK
+    0x2019: 0x0027, // U+2019 RIGHT SINGLE QUOTATION MARK
+    0x2032: 0x0027, // U+2032 PRIME
+    // ─── Dashes ────────────────────────────────────────────
+    0x2013: 0x002D, // U+2013 EN DASH
+    0x2014: 0x002D, // U+2014 EM DASH  (kept: single "-" match; author's "——"
+    //                             double-hyphen convention still works because
+    //                             it's already two ASCII "-" in storage)
+    0x2212: 0x002D, // U+2212 MINUS SIGN
+    0xFF0D: 0x002D, // U+FF0D FULLWIDTH HYPHEN-MINUS
+    // ─── CJK punctuation → ASCII ───────────────────────────
+    0xFF0C: 0x002C, // ，
+    0x3002: 0x002E, // 。 (map to `.`; author writing 句号 the user types `.`)
+    0xFF1F: 0x003F, // ？
+    0xFF01: 0x0021, // ！
+    0xFF1A: 0x003A, // ：
+    0xFF1B: 0x003B, // ；
+    0xFF08: 0x0028, // （
+    0xFF09: 0x0029, // ）
+    0x3010: 0x005B, // 【
+    0x3011: 0x005D, // 】
+    0x300A: 0x003C, // 《
+    0x300B: 0x003E, // 》
+    0xFF0F: 0x002F, // ／
+    0xFF0B: 0x002B, // ＋
+    0xFF1D: 0x003D, // ＝
+    0xFF5E: 0x007E, // ～
+    0xFF03: 0x0023, // ＃
+    0xFF04: 0x0024, // ＄
+    0xFF05: 0x0025, // ％
+    0xFF06: 0x0026, // ＆
+    0xFF0A: 0x002A, // ＊
+    0xFF20: 0x0040, // ＠
+    0xFF3B: 0x005B, // ［
+    0xFF3D: 0x005D, // ］
+    0xFF5B: 0x007B, // ｛
+    0xFF5D: 0x007D, // ｝
+    // ─── Middle dot / interpunct ───────────────────────────
+    0x00B7: 0x00B7, // U+00B7 keep (rendered as ·)
+    0x2027: 0x00B7, // U+2027 HYPHENATION POINT
+    0x30FB: 0x00B7, // U+30FB KATAKANA MIDDLE DOT
+    // ─── Ellipsis ──────────────────────────────────────────
+    0x2026: 0x002E, // U+2026 HORIZONTAL ELLIPSIS -> "."  (matched char-by-char
+    //                                     if the card stores "..." literally)
+};
+/** Return the canonical form of `codePoint` for typing comparison. */
+export function normalizeForCompare(codePoint) {
+    return EQUIV[codePoint] ?? codePoint;
+}

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

@@ -1,7 +1,5 @@
 export const defaultTypingSettings = {
     stopOnError: false,
-    forgiveErrors: false,
-    spaceSkipsWords: false,
     ignoreCase: false,
     ignorePunctuation: false,
     allowBackspace: true,

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

@@ -1,3 +1,4 @@
+import { round } from '../round.js';
 import { CharAttr, hasAttr } from './chars.js';
 const MS_PER_MINUTE = 60_000;
 export function computeStats(chars, position, completed, now) {
@@ -39,7 +40,3 @@ export function computeStats(chars, position, completed, now) {
         finishedAt,
     };
 }
-function round(n, digits = 2) {
-    const p = 10 ** digits;
-    return Math.round(n * p) / p;
-}

package/dist/core/typing/metrics.js

@@ -1,3 +1,4 @@
+import { round } from './round.js';
 const MS_PER_MINUTE = 60_000;
 export function computeMetrics(s, now = Date.now()) {
     const startedAt = s.startedAt ?? now;
@@ -14,7 +15,3 @@ export function computeMetrics(s, now = Date.now()) {
         elapsedMs,
     };
 }
-function round(n, digits = 2) {
-    const p = 10 ** digits;
-    return Math.round(n * p) / p;
-}

package/dist/core/typing/round.js

@@ -0,0 +1,12 @@
+/**
+ * Fixed-precision round used by the typing metrics + stats modules.
+ *
+ * Lives in its own file only because two consumers (metrics.ts /
+ * engine/stats.ts) both need it — inlining it in either place forces
+ * the other to keep a byte-identical copy, which drifted once and
+ * would drift again.
+ */
+export function round(n, digits = 2) {
+    const p = 10 ** digits;
+    return Math.round(n * p) / p;
+}

package/dist/store/index.js

@@ -41,4 +41,5 @@ export { KvStore, parseKey, getAt, setAt, unsetAt, flatten, } from './kv.js';
 export { enumValidator, nonEmptyStringValidator, boolValidator, positiveIntValidator, absolutePathValidator, predicateValidator, } from './validators.js';
 export { JsonStorage } from './storage/json.js';
 export { BrowserStorage } from './storage/browser.js';
+export { SessionStorage } from './storage/session.js';
 export { MemoryStorage } from './storage/memory.js';

package/dist/store/storage/browser.js

@@ -58,4 +58,53 @@ export class BrowserStorage {
             throw new KvError('err.kv.storage.writeFailed', { origin: this.origin, reason: e.message }, `${this.origin}: write failed — ${e.message}`);
         }
     }
+    // ─── Synchronous variants ───────────────────────────────
+    //
+    // Under the hood `localStorage` is entirely synchronous. The async
+    // signatures above exist to satisfy the shared `Storage` interface
+    // (JsonStorage / MemoryStorage), but the browser side does not need
+    // to pay the cost of a microtask for every read.
+    //
+    // React rendering cannot `await`, so the view layer (`view/state/kv`)
+    // needs to read a value at render time. Rather than have it drop
+    // through to `localStorage.getItem` directly and duplicate all the
+    // parse / validate logic below, expose sync counterparts here.
+    //
+    // Semantics match the async versions except that parse / write
+    // failures on the sync path throw plain `Error` instead of `KvError`
+    // — the view layer wants "no data / broken data" to fall back to
+    // defaults silently, which matches the existing `readBlob` behaviour.
+    /** Synchronous read. Returns `{}` on missing / unavailable /
+     *  malformed data — never throws. */
+    readSync() {
+        const ls = getLocalStorage();
+        if (!ls)
+            return {};
+        const raw = ls.getItem(this.storageKey);
+        if (!raw)
+            return {};
+        try {
+            const data = JSON.parse(raw);
+            if (data && typeof data === 'object' && !Array.isArray(data)) {
+                return data;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return {};
+    }
+    /** Synchronous write. Silently drops quota-exceeded / private-mode
+     *  failures — the view layer treats storage as best-effort. */
+    writeSync(data) {
+        const ls = getLocalStorage();
+        if (!ls)
+            return;
+        try {
+            ls.setItem(this.storageKey, JSON.stringify(data));
+        }
+        catch {
+            /* ignore quota / private mode */
+        }
+    }
 }

package/dist/store/storage/session.js

@@ -0,0 +1,92 @@
+import { KvError } from '../types.js';
+function getSessionStorage() {
+    try {
+        const ss = globalThis
+            .sessionStorage;
+        return ss ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export class SessionStorage {
+    scope;
+    storageKey;
+    constructor(scope, storageKey = `qtype.${scope}`) {
+        this.scope = scope;
+        this.storageKey = storageKey;
+    }
+    get origin() {
+        return `sessionStorage:${this.storageKey}`;
+    }
+    async available() {
+        return getSessionStorage() !== null;
+    }
+    async read() {
+        const ss = getSessionStorage();
+        if (!ss)
+            return {};
+        const raw = ss.getItem(this.storageKey);
+        if (!raw)
+            return {};
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new KvError('err.kv.storage.parseFailed', { origin: this.origin, reason: e.message }, `${this.origin}: JSON parse error — ${e.message}`);
+        }
+        if (data == null)
+            return {};
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            throw new KvError('err.kv.storage.parseFailed', {
+                origin: this.origin,
+                reason: `root must be a JSON object, got ${Array.isArray(data) ? 'array' : typeof data}`,
+            }, `${this.origin}: root must be a JSON object`);
+        }
+        return data;
+    }
+    async write(data) {
+        const ss = getSessionStorage();
+        if (!ss) {
+            throw new KvError('err.kv.storage.unavailable', { scope: this.scope, origin: this.origin }, `${this.origin}: sessionStorage not available`);
+        }
+        try {
+            ss.setItem(this.storageKey, JSON.stringify(data));
+        }
+        catch (e) {
+            throw new KvError('err.kv.storage.writeFailed', { origin: this.origin, reason: e.message }, `${this.origin}: write failed — ${e.message}`);
+        }
+    }
+    /** Synchronous read. Returns `{}` on missing / malformed data. */
+    readSync() {
+        const ss = getSessionStorage();
+        if (!ss)
+            return {};
+        const raw = ss.getItem(this.storageKey);
+        if (!raw)
+            return {};
+        try {
+            const data = JSON.parse(raw);
+            if (data && typeof data === 'object' && !Array.isArray(data)) {
+                return data;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return {};
+    }
+    /** Synchronous write. Silently drops quota / private-mode errors. */
+    writeSync(data) {
+        const ss = getSessionStorage();
+        if (!ss)
+            return;
+        try {
+            ss.setItem(this.storageKey, JSON.stringify(data));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}