@qnroa/qtype 0.0.8 → 0.1.0

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/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/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 */
+        }
+    }
+}