@qnroa/qtype 0.0.2 → 0.0.4

package/dist/core/schemas/both.js

@@ -0,0 +1,52 @@
+/**
+ * "both" schema: user can set a global default and any single repo
+ * can override it. Registered on BOTH kv stores. Read precedence at
+ * runtime: repo > user > schema default.
+ */
+import { enumValidator, boolValidator, positiveIntValidator, } from '../../store/index.js';
+export const bothSchema = {
+    // Repo language. Drives:
+    //   • which template locale (examples/zh vs examples/en) new repos are
+    //     scaffolded from
+    //   • the web UI language — the reader is locked to repo.lang so the UI
+    //     matches the material's own language
+    //
+    // Values are BCP 47 codes (`zh-CN` / `en-US`); the short forms `zh` /
+    // `en` are accepted for backwards compatibility with older `.qtype/
+    // config.json` files and normalised at read time.
+    'repo.lang': {
+        validator: enumValidator(['zh-CN', 'en-US', 'zh', 'en']),
+        default: 'en-US',
+    },
+    'typing.theme': {
+        validator: enumValidator(['mocha', 'latte']),
+        default: 'mocha',
+    },
+    'typing.targetWpm': {
+        validator: positiveIntValidator(),
+    },
+    'typing.tabBehavior': {
+        validator: enumValidator(['reset', 'input', 'disabled']),
+        default: 'reset',
+    },
+    'typing.hint': {
+        validator: enumValidator(['none', 'ghost']),
+        default: 'none',
+    },
+    'typing.showKeyboard': {
+        validator: boolValidator(),
+        default: true,
+    },
+    'typing.showHands': {
+        validator: boolValidator(),
+        default: true,
+    },
+    // Mermaid pre-render mode. `prerender` (default) uses puppeteer at build
+    // time to bake SVGs into dist/material/mermaid.json; `client` ships raw
+    // ```mermaid fences and lets the browser render them; `off` treats mermaid
+    // as plain code blocks.
+    'publish.mermaid': {
+        validator: enumValidator(['prerender', 'client', 'off']),
+        default: 'prerender',
+    },
+};

package/dist/core/schemas/index.js

@@ -0,0 +1,3 @@
+export { userOnlySchema } from './user.js';
+export { repoOnlySchema } from './repo.js';
+export { bothSchema } from './both.js';

package/dist/core/schemas/repo.js

@@ -0,0 +1,55 @@
+/**
+ * repo-only config schema: keys tied to a specific repo, never
+ * useful as a user-wide default. Registered on the repo KV only.
+ */
+import { enumValidator, nonEmptyStringValidator, boolValidator, } from '../../store/index.js';
+export const repoOnlySchema = {
+    'repo.name': {
+        validator: nonEmptyStringValidator(),
+    },
+    // ── Password protection for `publish build` ─────────────
+    // On/off toggle. When true, `publish build` reads the other three fields
+    // and encrypts every material/*.md before writing to dist.
+    'publish.password.enabled': {
+        validator: boolValidator(),
+        default: false,
+    },
+    // Argon2id PHC-style hash of the plaintext password, used to verify the
+    // password entered at build time. NOT the AES key — that's derived
+    // separately via `publish.password.aesSalt`. Empty string when protection
+    // is off; shape enforced by `publish password set` writing a well-formed
+    // PHC string.
+    'publish.password.hash': {
+        validator: (v) => typeof v === 'string'
+            ? null
+            : { code: 'err.schema.nonEmptyString', fallback: 'must be a string' },
+        default: '',
+    },
+    // Base64 salt used with argon2id (password → AES-256 key). Rotated only
+    // when the user calls `publish password set` — stable across rebuilds so
+    // the same password unlocks previously published sites.
+    'publish.password.aesSalt': {
+        validator: (v) => typeof v === 'string'
+            ? null
+            : { code: 'err.schema.nonEmptyString', fallback: 'must be a string' },
+        default: '',
+    },
+    // What to encrypt. `all` covers material/ + any future encrypted assets;
+    // `material-only` limits encryption to material/*.md (same behavior in
+    // v0 since qtype has no other content streams).
+    'publish.password.scope': {
+        validator: enumValidator(['all', 'material-only', 'selected']),
+        default: 'all',
+    },
+    // When scope='selected', the list of file names (relative to material/)
+    // to encrypt. Ignored otherwise.
+    'publish.password.selected': {
+        validator: (v) => Array.isArray(v) && v.every((x) => typeof x === 'string')
+            ? null
+            : {
+                code: 'err.schema.nonEmptyString',
+                fallback: 'must be an array of strings',
+            },
+        default: [],
+    },
+};

package/dist/core/schemas/user.js

@@ -0,0 +1,19 @@
+/**
+ * user-only config schema: keys that describe the person, not any
+ * particular repo. Registered on the user KV only. Kept in its own
+ * file so adding a new user preference is one focused edit.
+ */
+import { enumValidator } from '../../store/index.js';
+export const userOnlySchema = {
+    // CLI display language. Values are BCP 47 codes; the short forms
+    // `zh` / `en` are accepted for backwards compatibility with older
+    // config files and normalised at read time by the i18n layer.
+    'cli.lang': {
+        validator: enumValidator(['zh-CN', 'en-US', 'zh', 'en']),
+        default: 'en-US',
+    },
+    'cli.color': {
+        validator: enumValidator(['always', 'never', 'auto']),
+        default: 'auto',
+    },
+};

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

@@ -0,0 +1,243 @@
+/**
+ * TypingInput — qtype's typing state machine.
+ *
+ * Inspired by Keybr's `TextInput` but rewritten to fit qtype:
+ *   • Single event model (onKeyDown / onBackspace) — no Keybr-style
+ *     "garbage buffer" or word-skip. Every user keystroke maps to one
+ *     Char slot at `position`.
+ *   • Chars are pre-allocated with `attrs = 0`. Typing mutates only the
+ *     Char at `position`; backspace decrements position and marks the
+ *     reverted char with Recover.
+ *   • Per-Char `timestamp` records when that slot was resolved. Stats
+ *     use first/last non-zero timestamps.
+ *   • Subscribers get a stable Char[] reference between notifications;
+ *     a new array is emitted on every state transition so React can
+ *     compare cheaply.
+ *
+ * The class does NOT know about pinyin, IME composition, or DOM. Those
+ * live in the events layer above.
+ */
+import { CharAttr } from './chars.js';
+import { Feedback } from './feedback.js';
+import { defaultTypingSettings, } from './settings.js';
+import { computeStats } from './stats.js';
+export class TypingInput {
+    #target;
+    #targetCodepoints;
+    #length;
+    settings;
+    #chars;
+    #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 };
+        this.#chars = this.#buildInitialChars();
+        this.#position = 0;
+    }
+    #buildInitialChars() {
+        const chars = new Array(this.#length);
+        for (let i = 0; i < this.#length; i++) {
+            chars[i] = {
+                target: this.#targetCodepoints[i],
+                typed: null,
+                attrs: CharAttr.Normal,
+                timestamp: 0,
+            };
+        }
+        return chars;
+    }
+    /**
+     * User pressed a printable key. Returns feedback describing the result.
+     *
+     * Hit  → Char.attrs |= Hit, position advances.
+     * Miss → Char.attrs |= Miss, position advances unless stopOnError.
+     */
+    onKeyDown(codePoint, timestamp) {
+        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 isHit = this.settings.ignoreCase
+            ? sameLetter(codePoint, expected)
+            : codePoint === expected;
+        // 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();
+        const prev = next[this.#position];
+        const nextAttrs = (prev.attrs & ~(CharAttr.Hit | CharAttr.Miss | CharAttr.Cursor)) |
+            (isHit ? CharAttr.Hit : CharAttr.Miss);
+        const recovered = isHit && (prev.attrs & CharAttr.Miss) !== 0;
+        next[this.#position] = {
+            target: expected,
+            typed: codePoint,
+            attrs: recovered ? nextAttrs | CharAttr.Recover : nextAttrs,
+            timestamp,
+        };
+        this.#chars = next;
+        if (isHit || !this.settings.stopOnError) {
+            this.#position++;
+        }
+        this.#notify();
+        if (recovered)
+            return Feedback.Recover;
+        return isHit ? Feedback.Correct : Feedback.Incorrect;
+    }
+    /**
+     * User pressed Backspace. Rewinds one slot and flags the reverted
+     * Char as Recover so downstream UI can dim / rehighlight it.
+     */
+    onBackspace(_timestamp) {
+        if (!this.settings.allowBackspace) {
+            // Silently swallow — the "commit and move on" mode.
+            return Feedback.Correct;
+        }
+        if (this.#position === 0) {
+            // Signal that the user is trying to rewind past start.
+            return Feedback.Restart;
+        }
+        this.#position--;
+        const next = this.#chars.slice();
+        const prev = next[this.#position];
+        // Clear Hit/Miss (this slot is now pending again) but remember it
+        // was once touched so we can render a "recovered" ghost if desired.
+        // `typed` resets to null — pending slots are "no user input yet".
+        next[this.#position] = {
+            target: this.#targetCodepoints[this.#position],
+            typed: null,
+            attrs: (prev.attrs & ~(CharAttr.Hit | CharAttr.Miss | CharAttr.Cursor)) |
+                CharAttr.Recover,
+            timestamp: 0,
+        };
+        this.#chars = next;
+        this.#notify();
+        return Feedback.Recover;
+    }
+    /** Wipe all progress and re-initialize Char slots. */
+    reset() {
+        this.#chars = this.#buildInitialChars();
+        this.#position = 0;
+        this.#notify();
+    }
+    get position() {
+        return this.#position;
+    }
+    get chars() {
+        return this.#chars;
+    }
+    get target() {
+        return this.#target;
+    }
+    get length() {
+        return this.#length;
+    }
+    get completed() {
+        return this.#position >= this.#length;
+    }
+    /** Codepoint the engine expects next, or null when done. */
+    get nextChar() {
+        return this.#position < this.#length
+            ? this.#targetCodepoints[this.#position]
+            : null;
+    }
+    get stats() {
+        return computeStats(this.#chars, this.#position, this.completed, Date.now());
+    }
+    statsAt(now) {
+        return computeStats(this.#chars, this.#position, this.completed, now);
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    #notify() {
+        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,
+ * etc.) codepoints compare strictly.
+ */
+function sameLetter(a, b) {
+    if (a === b)
+        return true;
+    // ASCII A-Z (65-90) vs a-z (97-122)
+    if (a >= 65 && a <= 90 && b === a + 32)
+        return true;
+    if (a >= 97 && a <= 122 && b === a - 32)
+        return true;
+    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.
+ */
+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;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * qtype's per-character record. Inspired by Keybr's Attr bitmask + Char
+ * pair, but re-typed for qtype (mutable timestamp field, no cls, no
+ * StyledText spans — qtype renders characters uniformly).
+ *
+ * Each Char corresponds to exactly one target codepoint. The `attrs`
+ * bitmask carries the render state; `timestamp` is the wall-clock time
+ * (ms) the char was resolved, 0 if not yet.
+ *
+ * `target` and `typed` are separate so consumers never have to guess
+ * "which one does codePoint mean in this state?" —
+ *
+ *   • `target` — fixed at construction time. Always the character the
+ *     material asks for at this slot. Consumers use this for layout
+ *     decisions (is-newline / is-space) that depend on the material's
+ *     structure, not on user input.
+ *   • `typed`  — what the user actually typed. Equals `target` on
+ *     pending / hit / recovered slots; differs only when Miss is set.
+ *     Consumers use this for what to RENDER (the visible glyph).
+ */
+export const CharAttr = {
+    Normal: 0,
+    Hit: 1 << 0,
+    Miss: 1 << 1,
+    Cursor: 1 << 2,
+    Recover: 1 << 3,
+};
+export function hasAttr(attrs, flag) {
+    return (attrs & flag) !== 0;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Return value from TypingInput's public methods.
+ *
+ *   Correct   — typed the expected char.
+ *   Incorrect — typed something else.
+ *   Restart   — the input rewound past position 0 or was reset.
+ *   Recover   — user cleared a wrong char via backspace or re-typed
+ *               correctly after a miss.
+ */
+export const Feedback = {
+    Correct: 'correct',
+    Incorrect: 'incorrect',
+    Restart: 'restart',
+    Recover: 'recover',
+};

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

@@ -0,0 +1,5 @@
+export { TypingInput } from './TypingInput.js';
+export { CharAttr, hasAttr } from './chars.js';
+export { Feedback } from './feedback.js';
+export { defaultTypingSettings } from './settings.js';
+export { computeStats } from './stats.js';

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

@@ -0,0 +1,8 @@
+export const defaultTypingSettings = {
+    stopOnError: false,
+    forgiveErrors: false,
+    spaceSkipsWords: false,
+    ignoreCase: false,
+    ignorePunctuation: false,
+    allowBackspace: true,
+};

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

@@ -0,0 +1,45 @@
+import { CharAttr, hasAttr } from './chars.js';
+const MS_PER_MINUTE = 60_000;
+export function computeStats(chars, position, completed, now) {
+    let correctCount = 0;
+    let wrongCount = 0;
+    let firstTs = null;
+    let lastTs = null;
+    for (let i = 0; i < position; i++) {
+        const c = chars[i];
+        if (hasAttr(c.attrs, CharAttr.Hit))
+            correctCount++;
+        else if (hasAttr(c.attrs, CharAttr.Miss))
+            wrongCount++;
+        if (c.timestamp > 0) {
+            if (firstTs === null || c.timestamp < firstTs)
+                firstTs = c.timestamp;
+            if (lastTs === null || c.timestamp > lastTs)
+                lastTs = c.timestamp;
+        }
+    }
+    const startedAt = firstTs;
+    const finishedAt = completed ? lastTs : null;
+    const endedAt = finishedAt ?? (startedAt !== null ? now : null);
+    const elapsedMs = startedAt !== null && endedAt !== null
+        ? Math.max(1, endedAt - startedAt)
+        : 0;
+    const totalTyped = correctCount + wrongCount;
+    const accuracy = totalTyped === 0 ? 1 : correctCount / totalTyped;
+    const cpm = elapsedMs > 0 ? (correctCount / elapsedMs) * MS_PER_MINUTE : 0;
+    const wpm = cpm / 5;
+    return {
+        wpm: round(wpm),
+        cpm: round(cpm),
+        accuracy: round(accuracy, 4),
+        elapsedMs,
+        correctCount,
+        wrongCount,
+        startedAt,
+        finishedAt,
+    };
+}
+function round(n, digits = 2) {
+    const p = 10 ** digits;
+    return Math.round(n * p) / p;
+}

package/dist/core/typing/index.js

@@ -1,2 +1,10 @@
-export * from './engine.js';
+/**
+ * qtype's typing domain module.
+ *
+ * Everything here is platform-agnostic: no React, no DOM, no Node
+ * fs / process. CLI can drive the engine to analyze event logs; View
+ * subscribes to it for real-time UI updates; anyone else (future
+ * desktop shell, TUI, batch benchmark) can consume the same code.
+ */
+export * from './engine/index.js';
 export * from './metrics.js';