@qnroa/qtype 0.0.1

package/dist/cli/utils/prompt.js

@@ -0,0 +1,72 @@
+/**
+ * Minimal stdin prompt helpers for CLI commands.
+ *
+ * `promptLine` reads until the first newline with echo (visible input).
+ * `promptPassword` does the same with echo suppressed on TTYs — falls back
+ * to plain echo on non-TTY (e.g. piped stdin) since there's no terminal to
+ * mute anyway.
+ */
+export function promptLine(prompt) {
+    if (prompt)
+        process.stdout.write(prompt);
+    return new Promise((resolve) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        const onData = (chunk) => {
+            data += chunk;
+            const nl = data.indexOf('\n');
+            if (nl !== -1) {
+                process.stdin.off('data', onData);
+                resolve(data.slice(0, nl).trimEnd());
+            }
+        };
+        process.stdin.on('data', onData);
+    });
+}
+export function promptPassword(prompt) {
+    if (prompt)
+        process.stdout.write(prompt);
+    const stdin = process.stdin;
+    const isTty = stdin.isTTY === true;
+    if (isTty && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+    }
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    return new Promise((resolve, reject) => {
+        let data = '';
+        const finish = (value) => {
+            stdin.off('data', onData);
+            if (isTty && typeof stdin.setRawMode === 'function')
+                stdin.setRawMode(false);
+            stdin.pause();
+            process.stdout.write('\n');
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                // Ctrl-C in raw mode: abort with a clear error rather than letting
+                // the byte fall into the password buffer.
+                if (ch === '') {
+                    if (isTty && typeof stdin.setRawMode === 'function')
+                        stdin.setRawMode(false);
+                    stdin.pause();
+                    process.stdout.write('\n');
+                    stdin.off('data', onData);
+                    reject(new Error('aborted'));
+                    return;
+                }
+                if (ch === '\n' || ch === '\r') {
+                    finish(data);
+                    return;
+                }
+                if (ch === '' || ch === '\b') {
+                    data = data.slice(0, -1);
+                    continue;
+                }
+                data += ch;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}

package/dist/cli/utils/repoGuard.js

@@ -0,0 +1,41 @@
+/**
+ * Repo guard: ensure a path is a qtype repo before running the command.
+ *
+ * A qtype repo is identified by **the protocol file `QTYPE.md` (or any
+ * legacy `QTYPE.<lang>.md`) at the root**, plus the `material/` directory the
+ * spec mandates. Earlier versions checked for `.qtype/`, but that's
+ * PUBLISH-only configuration metadata — fresh repos created via
+ * `qtype repo new` don't have it until the user runs `publish init`,
+ * which made content lint/validate refuse to run on perfectly valid
+ * just-created repos. Anchoring on the protocol file matches the QTYPE
+ * spec's own definition of "what is a qtype repo".
+ *
+ * Commands that read/write repo content (publish build, content lint/validate,
+ * edit, etc.) should call this first — otherwise they happily succeed on
+ * arbitrary directories like /tmp, producing meaningless output and dist/
+ * directories scattered everywhere.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fatal } from './output.js';
+import { t } from '../i18n/index.js';
+const PROTOCOL_FILES = ['QTYPE.md', 'QTYPE.zh.md', 'QTYPE.en.md'];
+/**
+ * Throw via `fatal()` if `repoRoot` is not a qtype repo.
+ *
+ * Returns the absolute path on success.
+ */
+export function ensureQtypeRepo(repoRoot) {
+    const abs = path.resolve(repoRoot);
+    if (!fs.existsSync(abs)) {
+        fatal(t('err.path.notExists', { path: abs }));
+    }
+    // Either form of the protocol file marks a qtype repo. We check both
+    // the canonical `QTYPE.md` and the older language-suffixed names for
+    // backward compatibility with repos created before the rename.
+    const hasProtocol = PROTOCOL_FILES.some((f) => fs.existsSync(path.join(abs, f)));
+    if (!hasProtocol) {
+        fatal(t('err.notQtypeRepo', { path: abs }), t('hint.runRepoNew'));
+    }
+    return abs;
+}

package/dist/core/encrypt.js

@@ -0,0 +1,113 @@
+/**
+ * Password-based content encryption for the published static site.
+ *
+ * Threat model: prevent casual viewing by anyone who has the URL but not
+ * the password (Staticrypt-style). NOT a defence against a motivated
+ * attacker who downloads the site and brute-forces offline — since the
+ * ciphertext + KDF parameters travel to the browser together, that's
+ * unavoidable for a static site with no server component.
+ *
+ * Design:
+ *   - argon2id(password, aesSalt) → 32-byte AES-256 key.
+ *     Params fixed at 64 MiB / t=3 / p=1 (same as the interactive-login
+ *     profile used by `publish password set` for hash verification).
+ *   - AES-GCM with a fresh random 12-byte IV per ciphertext blob.
+ *     Auth tag (16 bytes) is appended to the ciphertext by SubtleCrypto,
+ *     so tampering fails decryption loudly.
+ *   - Runs identically under Node 20+ (`globalThis.crypto.subtle`) and in
+ *     the browser — one implementation, one code path.
+ *
+ * NB: the argon2 hash stored under `publish.password.hash` is used ONLY
+ * to verify "did the user type the right password?" before deriving the
+ * AES key. It does NOT participate in AES key derivation — that comes
+ * from a separately stored salt (`publish.password.aesSalt`) so the KDF
+ * path stays clean (plaintext → argon2id → raw bytes → AES key).
+ */
+import { argon2id } from '@noble/hashes/argon2.js';
+export const ARGON2_MEMORY = 64 * 1024;
+export const ARGON2_TIME = 3;
+export const ARGON2_PARALLEL = 1;
+export const AES_KEY_LEN = 32;
+export const AES_SALT_LEN = 16;
+export const AES_IV_LEN = 12;
+export const DEFAULT_ARGON2_PARAMS = {
+    m: ARGON2_MEMORY,
+    t: ARGON2_TIME,
+    p: ARGON2_PARALLEL,
+};
+function toB64(u8) {
+    let s = '';
+    for (let i = 0; i < u8.length; i++)
+        s += String.fromCharCode(u8[i]);
+    return typeof btoa === 'function'
+        ? btoa(s)
+        : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            globalThis.Buffer.from(u8).toString('base64');
+}
+function fromB64(s) {
+    if (typeof atob === 'function') {
+        const bin = atob(s);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Uint8Array(globalThis.Buffer.from(s, 'base64'));
+}
+/** Random bytes via WebCrypto (available in Node 20+ and every browser). */
+export function randomBytes(len) {
+    const out = new Uint8Array(len);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+}
+/** Fresh 16-byte salt for AES key derivation. */
+export function generateAesSalt() {
+    return toB64(randomBytes(AES_SALT_LEN));
+}
+/**
+ * Derive a 32-byte AES-256 key from (password, salt) using argon2id.
+ * Deterministic — same inputs always produce the same key, which lets
+ * `publish build` re-encrypt content on every run without a stored key file.
+ */
+export async function deriveAesKey(password, saltB64, params = DEFAULT_ARGON2_PARAMS) {
+    const salt = fromB64(saltB64);
+    const raw = argon2id(password, salt, {
+        t: params.t,
+        m: params.m,
+        p: params.p,
+        dkLen: AES_KEY_LEN,
+    });
+    return globalThis.crypto.subtle.importKey('raw', toBufferSource(raw), { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+// Bridge helper: WebCrypto's DOM BufferSource type demands
+// Uint8Array<ArrayBuffer>, while noble/hashes returns Uint8Array<ArrayBufferLike>
+// (which includes SharedArrayBuffer). Copying into a fresh ArrayBuffer-backed
+// view keeps the API surface clean and works identically in Node and browser.
+function toBufferSource(u8) {
+    const buf = new ArrayBuffer(u8.byteLength);
+    const view = new Uint8Array(buf);
+    view.set(u8);
+    return view;
+}
+/** Encrypt a UTF-8 string. Returns base64-encoded {ct, iv}. */
+export async function encryptString(key, plaintext) {
+    const iv = randomBytes(AES_IV_LEN);
+    const data = new TextEncoder().encode(plaintext);
+    const ctBuf = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv: toBufferSource(iv) }, key, toBufferSource(data));
+    return { ct: toB64(new Uint8Array(ctBuf)), iv: toB64(iv) };
+}
+/** Decrypt an EncryptedBlob back to its original UTF-8 string. */
+export async function decryptString(key, blob) {
+    const iv = fromB64(blob.iv);
+    const ct = fromB64(blob.ct);
+    const ptBuf = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: toBufferSource(iv) }, key, toBufferSource(ct));
+    return new TextDecoder().decode(ptBuf);
+}
+/** Type guard so runtime code can safely distinguish plaintext vs encrypted. */
+export function isEncryptedBlob(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v.ct === 'string' &&
+        typeof v.iv === 'string');
+}

package/dist/core/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './parser/index.js';
+export * from './typing/index.js';
+// Runtime helpers from keystroke module. Types (CharPlan / Keystroke) are
+// re-declared in types.ts so callers can import them from '@core/index'
+// without a duplicate export conflict.
+export { charToKeystrokes, textToCharPlans } from './keystroke/index.js';
+export { normalizeText, validateTypingText } from './keystroke/textNormalize.js';

package/dist/core/keystroke/asciiMap.js

@@ -0,0 +1,39 @@
+// Unshifted characters (single key press, no shift).
+const UNSHIFTED = {
+    // letters
+    a: 'a', b: 'b', c: 'c', d: 'd', e: 'e', f: 'f', g: 'g', h: 'h', i: 'i',
+    j: 'j', k: 'k', l: 'l', m: 'm', n: 'n', o: 'o', p: 'p', q: 'q', r: 'r',
+    s: 's', t: 't', u: 'u', v: 'v', w: 'w', x: 'x', y: 'y', z: 'z',
+    // digits
+    '0': '0', '1': '1', '2': '2', '3': '3', '4': '4',
+    '5': '5', '6': '6', '7': '7', '8': '8', '9': '9',
+    // punctuation on their base key
+    '`': '`', '-': '-', '=': '=',
+    '[': '[', ']': ']', '\\': '\\',
+    ';': ';', "'": "'",
+    ',': ',', '.': '.', '/': '/',
+    // whitespace
+    ' ': 'space',
+    '\n': 'enter',
+    '\t': 'tab',
+};
+// Shifted characters.
+const SHIFTED = {
+    // uppercase letters
+    A: 'a', B: 'b', C: 'c', D: 'd', E: 'e', F: 'f', G: 'g', H: 'h', I: 'i',
+    J: 'j', K: 'k', L: 'l', M: 'm', N: 'n', O: 'o', P: 'p', Q: 'q', R: 'r',
+    S: 's', T: 't', U: 'u', V: 'v', W: 'w', X: 'x', Y: 'y', Z: 'z',
+    // shifted punctuation
+    '~': '`', '!': '1', '@': '2', '#': '3', $: '4', '%': '5',
+    '^': '6', '&': '7', '*': '8', '(': '9', ')': '0', _: '-', '+': '=',
+    '{': '[', '}': ']', '|': '\\',
+    ':': ';', '"': "'",
+    '<': ',', '>': '.', '?': '/',
+};
+export function asciiToKeystrokes(ch) {
+    if (ch in UNSHIFTED)
+        return [{ key: UNSHIFTED[ch], imeMode: 'en' }];
+    if (ch in SHIFTED)
+        return [{ key: SHIFTED[ch], shift: true, imeMode: 'en' }];
+    return null;
+}

package/dist/core/keystroke/chineseMap.js

@@ -0,0 +1,32 @@
+// Chinese-character → pinyin → keystrokes (quanpin, space-commit).
+// Uses pinyin-pro to get the pinyin for a single CJK ideograph, then emits
+// one lowercase-letter keystroke per pinyin letter followed by a space to
+// commit the character.
+import { pinyin } from 'pinyin-pro';
+// Match ANY CJK Unified Ideograph (not just BMP block).
+// Covers CJK Unified Ideographs + Extension A + Compatibility Ideographs.
+export function isChineseChar(ch) {
+    const code = ch.codePointAt(0);
+    if (code === undefined)
+        return false;
+    return ((code >= 0x4e00 && code <= 0x9fff) || // CJK Unified
+        (code >= 0x3400 && code <= 0x4dbf) || // Extension A
+        (code >= 0xf900 && code <= 0xfaff) // Compatibility
+    );
+}
+// Returns null if pinyin lookup fails (unknown character).
+export function chineseCharToKeystrokes(ch) {
+    const py = pinyin(ch, {
+        toneType: 'none',
+        type: 'string',
+        v: true, // treat ü as v (typical IME input)
+    });
+    if (!py || !/^[a-z]+$/.test(py))
+        return null;
+    const keys = py.split('').map((c) => ({
+        key: c,
+        imeMode: 'zh',
+    }));
+    keys.push({ key: 'space', imeMode: 'zh' });
+    return keys;
+}

package/dist/core/keystroke/fullwidthMap.js

@@ -0,0 +1,41 @@
+const K = (key, shift) => ({
+    key,
+    ...(shift ? { shift: true } : {}),
+    imeMode: 'zh',
+});
+// key: single-char (or 2-char for ellipsis/dashes) source char in text.
+// value: keystroke sequence.
+const MAP = {
+    // Sentence punctuation
+    '，': [K(',')],
+    '。': [K('.')],
+    '！': [K('1', true)],
+    '？': [K('/', true)],
+    '：': [K(';', true)],
+    '；': [K(';')],
+    '、': [K('\\')], // Chinese ideographic comma via backslash in most IMEs
+    // Quotes (curly / fullwidth)
+    '“': [K("'", true)], // "
+    '”': [K("'", true)], // "
+    '‘': [K("'")], // '
+    '’': [K("'")], // '
+    // Brackets
+    '（': [K('9', true)],
+    '）': [K('0', true)],
+    '【': [K('[')],
+    '】': [K(']')],
+    '《': [K(',', true)],
+    '》': [K('.', true)],
+    '「': [K('[')], // some IMEs
+    '」': [K(']')],
+    // Dashes & ellipsis (single char even though rendered wide)
+    '—': [K('-', true), K('-', true)], // em-dash → often typed as ——
+    '…': [K('6', true), K('6', true)], // horizontal ellipsis → typed as ……
+    '·': [K('`')], // middle dot on backtick key in zh mode
+    // Currency & math (basic)
+    '￥': [K('4', true)], // fullwidth yuan
+};
+export function fullwidthToKeystrokes(ch) {
+    return MAP[ch] ?? null;
+}
+export const FULLWIDTH_CHARS = new Set(Object.keys(MAP));

package/dist/core/keystroke/index.js

@@ -0,0 +1,22 @@
+import { asciiToKeystrokes } from './asciiMap.js';
+import { fullwidthToKeystrokes } from './fullwidthMap.js';
+import { chineseCharToKeystrokes, isChineseChar } from './chineseMap.js';
+// Resolve one character (post-normalization) to its physical keystrokes.
+// Returns null if the character cannot be typed (should be caught by import
+// validation so users never encounter this at runtime).
+export function charToKeystrokes(ch) {
+    return (asciiToKeystrokes(ch) ??
+        fullwidthToKeystrokes(ch) ??
+        (isChineseChar(ch) ? chineseCharToKeystrokes(ch) : null));
+}
+// Expand a full string into a flat list of CharPlans.
+export function textToCharPlans(text) {
+    const plans = [];
+    for (const ch of text) {
+        // `for..of` iterates by code point, so surrogate pairs stay together.
+        const ks = charToKeystrokes(ch);
+        if (ks)
+            plans.push({ char: ch, keystrokes: ks });
+    }
+    return plans;
+}

package/dist/core/keystroke/textNormalize.js

@@ -0,0 +1,68 @@
+// 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.
+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
+};
+// Ranges of code points to strip entirely (they can't be typed).
+const STRIP_RANGES = [
+    [0x0000, 0x0008], // C0 controls before \t
+    [0x000B, 0x001F], // remaining C0 controls (\t=0x09, \n=0x0A kept)
+    [0x007F, 0x009F], // DEL + C1 controls
+    [0x200B, 0x200F], // zero-width, LTR/RTL marks
+    [0x202A, 0x202E], // bidi override marks
+    [0x2060, 0x2064], // word joiner + invisible ops
+    [0xFEFF, 0xFEFF], // BOM
+    [0x1F300, 0x1FAFF], // emoji: symbols & pictographs, transport, etc.
+    [0x1F600, 0x1F64F], // emoji: emoticons
+    [0x2600, 0x27BF], // misc symbols + dingbats
+    [0x1F900, 0x1F9FF], // supplemental symbols & pictographs
+];
+function shouldStrip(cp) {
+    for (const [lo, hi] of STRIP_RANGES)
+        if (cp >= lo && cp <= hi)
+            return true;
+    return false;
+}
+// Normalize text: rewrite smart chars and strip untypable ones.
+export function normalizeText(input) {
+    const removed = [];
+    let out = '';
+    for (const ch of input) {
+        // Rewrite first
+        if (ch in REWRITE) {
+            out += REWRITE[ch];
+            continue;
+        }
+        // Strip
+        const cp = ch.codePointAt(0) ?? 0;
+        if (shouldStrip(cp)) {
+            removed.push(ch);
+            continue;
+        }
+        out += ch;
+    }
+    return { text: out, removed };
+}
+// Validate a piece of text for typing: normalize, then check each remaining
+// character has a keystroke plan. `unknowns` lists any that don't.
+export function validateTypingText(input) {
+    const { text, removed } = normalizeText(input);
+    const unknowns = [];
+    for (const ch of text) {
+        if (!charToKeystrokes(ch))
+            unknowns.push(ch);
+    }
+    return {
+        text,
+        removed,
+        unknowns,
+        valid: unknowns.length === 0,
+    };
+}

package/dist/core/keystroke/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/parser/frontmatter.js

@@ -0,0 +1,58 @@
+const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
+export function parseFrontmatter(block) {
+    const meta = { tags: [] };
+    const match = block.match(FM_RE);
+    if (!match)
+        return { meta, rest: block };
+    const body = match[1];
+    const rest = block.slice(match[0].length);
+    for (const line of body.split('\n')) {
+        const kv = line.match(/^(\w+)\s*:\s*(.+)$/);
+        if (!kv)
+            continue;
+        const [, key, rawValue] = kv;
+        const value = rawValue.trim();
+        if (key === 'tags') {
+            meta.tags = parseTagList(value);
+        }
+        else if (key === 'difficulty') {
+            const n = Number(value);
+            if (!Number.isNaN(n))
+                meta.difficulty = n;
+        }
+        else if (key === 'hint') {
+            const v = value;
+            if (v === 'none' || v === 'ghost')
+                meta.hint = v;
+        }
+        else if (key === 'type') {
+            if (value === 'word' || value === 'sentence' || value === 'normal') {
+                meta.type = value;
+            }
+        }
+        else if (key === 'phonetic') {
+            meta.phonetic = value;
+        }
+        else if (key === 'gloss') {
+            meta.gloss = value;
+        }
+        else if (key === 'translation') {
+            meta.translation = value;
+        }
+    }
+    return { meta, rest };
+}
+function parseTagList(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return trimmed
+            .slice(1, -1)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    return trimmed
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}

package/dist/core/parser/index.js

@@ -0,0 +1,2 @@
+export * from './parseMaterial.js';
+export * from './frontmatter.js';

package/dist/core/parser/parseMaterial.js

@@ -0,0 +1,42 @@
+import { parseFrontmatter } from './frontmatter.js';
+import { textToCharPlans } from '../keystroke/index.js';
+import { validateTypingText } from '../keystroke/textNormalize.js';
+const CARD_SEPARATOR = /\n\n---\n\n/;
+export function parseMaterial(source, filePath = 'inline') {
+    const normalized = source.replace(/\r\n/g, '\n').trim() + '\n';
+    const blocks = normalized
+        .split(CARD_SEPARATOR)
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const cards = [];
+    for (let i = 0; i < blocks.length; i++) {
+        const card = parseCard(blocks[i], filePath, i);
+        if (card)
+            cards.push(card);
+    }
+    return { filePath, cards };
+}
+function parseCard(block, filePath, index) {
+    const { meta, rest } = parseFrontmatter(block);
+    const qMatch = rest.match(/^##\s*Q:?\s*([\s\S]*?)(?=\n##\s*A:?|$)/m);
+    const aMatch = rest.match(/\n##\s*A:?\s*([\s\S]*)$/m);
+    if (!qMatch || !aMatch)
+        return null;
+    const question = qMatch[1].trim();
+    const rawAnswer = aMatch[1].trim();
+    if (!question || !rawAnswer)
+        return null;
+    // Normalize the answer for typing: smart quotes/dashes rewritten, emoji &
+    // zero-width chars stripped. Compute the keystroke plan and list any chars
+    // that still don't have one so the UI can warn.
+    const validated = validateTypingText(rawAnswer);
+    const charPlans = textToCharPlans(validated.text);
+    return {
+        id: `${filePath}#${index}`,
+        question,
+        answer: validated.text,
+        meta,
+        charPlans,
+        unknownChars: validated.unknowns,
+    };
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/typing/engine.js

@@ -0,0 +1,112 @@
+export function createState(target) {
+    return {
+        target,
+        typed: '',
+        cursor: 0,
+        correctCount: 0,
+        wrongCount: 0,
+        startedAt: null,
+        finishedAt: null,
+        composing: false,
+    };
+}
+export function beginComposition(s, now = Date.now()) {
+    return {
+        ...s,
+        startedAt: s.startedAt ?? now,
+        composing: true,
+    };
+}
+export function endComposition(s, committed, now = Date.now()) {
+    const next = commitChars(s, committed, now);
+    return { ...next, composing: false };
+}
+export function typeChar(s, ch, now = Date.now()) {
+    if (s.composing)
+        return s;
+    return commitChars(s, ch, now);
+}
+export function backspace(s) {
+    if (s.composing || s.cursor === 0)
+        return s;
+    const removed = s.typed[s.cursor - 1];
+    const expected = s.target[s.cursor - 1];
+    const wasCorrect = removed === expected;
+    return {
+        ...s,
+        typed: s.typed.slice(0, -1),
+        cursor: s.cursor - 1,
+        correctCount: wasCorrect ? s.correctCount - 1 : s.correctCount,
+        wrongCount: wasCorrect ? s.wrongCount : s.wrongCount - 1,
+        finishedAt: null,
+    };
+}
+function commitChars(s, chunk, now) {
+    if (!chunk)
+        return s;
+    let { cursor, correctCount, wrongCount, typed } = s;
+    const startedAt = s.startedAt ?? now;
+    const chars = Array.from(chunk);
+    for (const ch of chars) {
+        const expected = s.target[cursor];
+        if (expected === undefined)
+            break;
+        if (ch === expected)
+            correctCount++;
+        else
+            wrongCount++;
+        typed += ch;
+        cursor++;
+    }
+    const finishedAt = cursor >= s.target.length ? now : null;
+    return {
+        ...s,
+        typed,
+        cursor,
+        correctCount,
+        wrongCount,
+        startedAt,
+        finishedAt,
+    };
+}
+export function charStatus(s, index) {
+    if (index < s.cursor) {
+        return s.typed[index] === s.target[index] ? 'correct' : 'wrong';
+    }
+    if (index === s.cursor)
+        return 'current';
+    return 'pending';
+}
+// Sync the state to a full "typed so far" string (read from the contenteditable
+// editor on every input event, dazidazi-style). Recomputes correct/wrong counts
+// from scratch based on positional character comparison, so the caller doesn't
+// need to track incremental changes.
+export function syncTyped(s, typed, now = Date.now()) {
+    const chars = Array.from(typed);
+    let correctCount = 0;
+    let wrongCount = 0;
+    for (let i = 0; i < chars.length; i++) {
+        const expected = s.target[i];
+        if (expected === undefined) {
+            // Overflow — extra characters past target length count as wrong.
+            wrongCount++;
+            continue;
+        }
+        if (chars[i] === expected)
+            correctCount++;
+        else
+            wrongCount++;
+    }
+    const cursor = chars.length;
+    const startedAt = s.startedAt ?? (typed.length > 0 ? now : null);
+    const finished = cursor >= s.target.length && correctCount === s.target.length;
+    return {
+        ...s,
+        typed,
+        cursor,
+        correctCount,
+        wrongCount,
+        startedAt,
+        finishedAt: finished ? (s.finishedAt ?? now) : null,
+    };
+}

package/dist/core/typing/index.js

@@ -0,0 +1,2 @@
+export * from './engine.js';
+export * from './metrics.js';