@qnroa/qtype 0.0.2 → 0.0.4

package/dist/cli/commands/repo/new/action.js

@@ -62,11 +62,30 @@ export async function repoNewAction(opts) {
         fs.writeFileSync(path.join(repoDir, fileName), readTemplate(templatesDir, fileName, vars));
         console.log(`  + ${fileName}`);
     }
-    // 4. Seed material/example.md and empty .gitkeep so the directory exists
-    //    but stays trivially prunable if the user wipes the seed.
+    // 4. Seed one starter per material type + .gitkeep so the directory
+    //    exists but stays trivially prunable if the user wipes the seed.
+    //    Each starter is a valid `qtype check`-clean deck the user can
+    //    copy, rename, and edit. Their image assets ship alongside so the
+    //    demos render out of the box.
     fs.mkdirSync(path.join(repoDir, 'material'), { recursive: true });
-    fs.writeFileSync(path.join(repoDir, 'material', 'example.md'), readTemplate(templatesDir, path.join('material', 'example.md'), vars));
-    console.log(`  + material/example.md`);
+    const starters = [
+        ['word', 'apple.svg'],
+        ['sentence', 'pangram.svg'],
+        ['article', 'sunrise.svg'],
+        ['snippet', 'moon.svg'],
+        ['qa', 'login-flow.svg'],
+        ['code', 'tree.svg'],
+    ];
+    for (const [type, asset] of starters) {
+        const mdRel = path.join('material', `${type}.md`);
+        fs.writeFileSync(path.join(repoDir, mdRel), readTemplate(templatesDir, mdRel, vars));
+        console.log(`  + ${mdRel}`);
+        const assetRel = path.join('material', 'assets', type, asset);
+        const assetDir = path.dirname(path.join(repoDir, assetRel));
+        fs.mkdirSync(assetDir, { recursive: true });
+        fs.writeFileSync(path.join(repoDir, assetRel), readTemplate(templatesDir, assetRel, vars));
+        console.log(`  + ${assetRel}`);
+    }
     fs.writeFileSync(path.join(repoDir, 'material', '.gitkeep'), '');
     console.log(`  + material/.gitkeep`);
     // 5. Write .qtype/config.json with the repo language.

package/dist/cli/commands/repo/new/i18n.js

@@ -16,7 +16,7 @@ export const messages = {
         'repo.new.msg.done': '仓库已建好：{path}',
         'repo.new.msg.nextSteps': '下一步：',
         'repo.new.msg.next.cd': 'cd {name}',
-        'repo.new.msg.next.edit': 'vim material/example.md    # 或添加新的 material/*.md',
+        'repo.new.msg.next.edit': 'ls material/               # 6 种类型的入门模板，改哪个都行',
         'repo.new.msg.next.commit': 'git add -A && git commit  # 首次提交',
         'repo.new.msg.next.gitHint': 'git init                  # 如需版本控制，也可以 qtype repo new --git',
         'repo.new.tpl.defaultDescription': '资料库',
@@ -38,7 +38,7 @@ export const messages = {
         'repo.new.msg.done': 'Repo created: {path}',
         'repo.new.msg.nextSteps': 'Next steps:',
         'repo.new.msg.next.cd': 'cd {name}',
-        'repo.new.msg.next.edit': 'vim material/example.md    # or add new material/*.md',
+        'repo.new.msg.next.edit': 'ls material/               # 6 starter templates, edit any of them',
         'repo.new.msg.next.commit': 'git add -A && git commit  # initial commit',
         'repo.new.msg.next.gitHint': 'git init                  # or re-run with qtype repo new --git',
         'repo.new.tpl.defaultDescription': 'material library',

package/dist/cli/commands/repo/sync/action.js

@@ -16,12 +16,32 @@ function buildSyncPlan() {
         { kind: 'file', target: 'TODO.md', source: 'TODO.md', managed: false },
         { kind: 'file', target: 'index.md', source: 'index.md', managed: false },
         { kind: 'file', target: 'log.md', source: 'log.md', managed: false },
-        {
+        // Starter cards — one per material type. Users copy the one that
+        // matches what they're writing, rename it, edit content, and are
+        // off to the races. Every file is a valid `qtype check`-clean deck
+        // out of the box (the smoke test asserts this).
+        ...['word', 'sentence', 'article', 'snippet', 'qa', 'code'].map((type) => ({
             kind: 'file',
-            target: 'material/example.md',
-            source: path.join('material', 'example.md'),
+            target: `material/${type}.md`,
+            source: path.join('material', `${type}.md`),
             managed: false,
-        },
+        })),
+        // Starter card image assets — SVGs referenced by the starters.
+        // `currentColor`-stroked so they inherit the site's text color and
+        // adapt to dark/light theme without extra work.
+        ...[
+            ['word', 'apple.svg'],
+            ['sentence', 'pangram.svg'],
+            ['article', 'sunrise.svg'],
+            ['snippet', 'moon.svg'],
+            ['qa', 'login-flow.svg'],
+            ['code', 'tree.svg'],
+        ].map(([type, name]) => ({
+            kind: 'file',
+            target: `material/assets/${type}/${name}`,
+            source: path.join('material', 'assets', type, name),
+            managed: false,
+        })),
         // ── Skeleton (create-only, never touched) ───────
         { kind: 'dir', target: '.qtype', managed: false },
         { kind: 'dir', target: 'material', managed: false },

package/dist/cli/commands/repo/templates.js

@@ -9,7 +9,8 @@ import { fileURLToPath } from 'node:url';
  *   ├── en/
  *   │   ├── QTYPE.md  README.md  TODO.md  index.md  log.md
  *   │   └── material/
- *   │       └── example.md
+ *   │       ├── word.md      article.md   qa.md
+ *   │       └── sentence.md  snippet.md   code.md
  *   └── zh/
  *       └── (same files)
  *

package/dist/cli/utils/material.js

@@ -0,0 +1,49 @@
+/**
+ * Shared helpers for walking a qtype repo's material/ directory.
+ *
+ * Every CLI command that reads material files (publish build, content
+ * lint / validate / search, check) goes through here so:
+ *   - The "recursively descend into subfolders" behavior is a single
+ *     implementation (used to be duplicated with different depths).
+ *   - Only `.md` files are yielded (any accidental `.DS_Store`, images,
+ *     etc. are skipped).
+ *   - Paths are always returned with forward slashes so downstream
+ *     JSON manifests and URL building agree even on Windows.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Directory name under a qtype repo root that holds the deck files. */
+export const MATERIAL_DIR = 'material';
+/**
+ * Yield every `.md` file under `<repoRoot>/material/`, recursively.
+ * Returns an empty array when the directory doesn't exist — callers
+ * that treat a missing dir as fatal should check that separately.
+ */
+export function walkMaterial(repoRoot) {
+    const root = path.join(repoRoot, MATERIAL_DIR);
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    const walk = (subdir) => {
+        const dir = path.join(root, subdir);
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const rel = subdir ? `${subdir}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(rel);
+                continue;
+            }
+            if (!entry.name.endsWith('.md'))
+                continue;
+            out.push({ rel, abs: path.join(root, rel) });
+        }
+    };
+    walk('');
+    return out;
+}
+/**
+ * Read a material file. Small wrapper for consistency across commands
+ * that all want utf-8 text.
+ */
+export function readMaterial(file) {
+    return fs.readFileSync(file.abs, 'utf8');
+}

package/dist/core/encrypt.js

@@ -24,6 +24,23 @@
  * path stays clean (plaintext → argon2id → raw bytes → AES key).
  */
 import { argon2id } from '@noble/hashes/argon2.js';
+// argon2id parameters — tuned 2026-08 against @noble/hashes on a mid-range
+// laptop. Target: ≥500ms per derivation so the offline brute-force cost
+// stays material without making the interactive login feel sluggish.
+//
+// Benchmark (M-series, `argon2id(pw, 16-byte salt, { dkLen: 32 })`, median
+// of 3 warm runs):
+//   32 MiB / t=2  →  ~223ms  ✗ below target
+//   32 MiB / t=3  →  ~327ms  ✗ below target
+//   64 MiB / t=2  →  ~445ms  ✗ just under target
+//   64 MiB / t=3  →  ~669ms  ✓ current — comfortable margin above 500ms
+//   96 MiB / t=3  →  ~949ms  ✗ ~1s login lag on modest hardware
+//   128 MiB / t=3 →  ~1272ms ✗ same
+//
+// Threat model recap: static-site content decrypts client-side, so an
+// attacker with the bundle can brute force offline unbounded. Higher
+// costs only linearly slow that attack. Sub-second is the plateau
+// beyond which UX pain outweighs security gain for this class of app.
 export const ARGON2_MEMORY = 64 * 1024;
 export const ARGON2_TIME = 3;
 export const ARGON2_PARALLEL = 1;
@@ -78,7 +95,13 @@ export async function deriveAesKey(password, saltB64, params = DEFAULT_ARGON2_PA
         p: params.p,
         dkLen: AES_KEY_LEN,
     });
-    return globalThis.crypto.subtle.importKey('raw', toBufferSource(raw), { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+    // `extractable: true` so the view layer can `exportKey('raw', …)` and
+    // stash the bytes in sessionStorage — that's what lets a page reload
+    // skip the argon2 re-derivation. On a static-site threat model this
+    // grants nothing new: whoever controls the tab already sees every
+    // AES.decrypt() plaintext, so making the CryptoKey itself extractable
+    // adds no attacker capability.
+    return globalThis.crypto.subtle.importKey('raw', toBufferSource(raw), { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
 }
 // Bridge helper: WebCrypto's DOM BufferSource type demands
 // Uint8Array<ArrayBuffer>, while noble/hashes returns Uint8Array<ArrayBufferLike>

package/dist/core/index.js

@@ -6,3 +6,4 @@ export * from './typing/index.js';
 // without a duplicate export conflict.
 export { charToKeystrokes, textToCharPlans } from './keystroke/index.js';
 export { normalizeText, validateTypingText } from './keystroke/textNormalize.js';
+export * from './encrypt.js';

package/dist/core/parser/frontmatter.js

@@ -1,46 +1,43 @@
 const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
-export function parseFrontmatter(block) {
+/**
+ * Material-level frontmatter (top of the file, before the first `#`).
+ *
+ *   ---
+ *   title: <标题>
+ *   type: word | sentence | article | qa | code
+ *   tags: [<t1>, <t2>]
+ *   created: YYYY-MM-DD
+ *   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).
+ */
+export function parseMaterialFrontmatter(source) {
     const meta = { tags: [] };
-    const match = block.match(FM_RE);
+    const match = source.match(FM_RE);
     if (!match)
-        return { meta, rest: block };
+        return { meta, rest: source };
     const body = match[1];
-    const rest = block.slice(match[0].length);
+    const fields = {};
     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;
-        }
+        fields[kv[1]] = kv[2].trim();
     }
-    return { meta, rest };
+    if (fields.title)
+        meta.title = fields.title;
+    if (fields.type)
+        meta.type = fields.type;
+    if (fields.tags)
+        meta.tags = parseTagList(fields.tags);
+    if (fields.created)
+        meta.created = fields.created;
+    if (fields.updated)
+        meta.updated = fields.updated;
+    return { meta, rest: source.slice(match[0].length) };
 }
 function parseTagList(value) {
     const trimmed = value.trim();
@@ -56,3 +53,11 @@ function parseTagList(value) {
         .map((s) => s.trim())
         .filter(Boolean);
 }
+/**
+ * Kept for backwards compatibility of the barrel export. Card-level
+ * frontmatter is no longer used; this always returns empty meta and
+ * the original block unchanged.
+ */
+export function parseFrontmatter(block) {
+    return { meta: { tags: [] }, rest: block };
+}

package/dist/core/parser/parseMaterial.js

@@ -1,42 +1,192 @@
-import { parseFrontmatter } from './frontmatter.js';
+import { parseMaterialFrontmatter } from './frontmatter.js';
 import { textToCharPlans } from '../keystroke/index.js';
 import { validateTypingText } from '../keystroke/textNormalize.js';
-const CARD_SEPARATOR = /\n\n---\n\n/;
+import { containsCJK, romanize } from '../romanization/index.js';
 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 { meta: materialMeta, rest } = parseMaterialFrontmatter(normalized);
+    const materialType = materialMeta.type ?? 'article';
+    const rawCards = splitByH1(rest);
     const cards = [];
-    for (let i = 0; i < blocks.length; i++) {
-        const card = parseCard(blocks[i], filePath, i);
+    for (let i = 0; i < rawCards.length; i++) {
+        const card = parseCard(rawCards[i], materialType, filePath, i);
         if (card)
-            cards.push(card);
+            cards.push(attachRomanization(card));
     }
-    return { filePath, cards };
+    return { filePath, meta: materialMeta, 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)
+/**
+ * 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).
+ */
+function splitByH1(body) {
+    const lines = body.split('\n');
+    const chunks = [];
+    let current = null;
+    for (const line of lines) {
+        if (/^#\s+/.test(line)) {
+            if (current)
+                chunks.push(current.join('\n').trim());
+            current = [line];
+        }
+        else if (current) {
+            current.push(line);
+        }
+        // Lines before the first H1 are ignored (material-level prose).
+    }
+    if (current)
+        chunks.push(current.join('\n').trim());
+    return chunks.filter(Boolean);
+}
+/**
+ * If the card's `answer` contains any Han character, attach a
+ * romanization (pinyin) so the typing engine has a keyboard-typable
+ * target. Non-CJK cards get nothing (fields stay undefined).
+ */
+function attachRomanization(card) {
+    if (!containsCJK(card.answer))
+        return card;
+    const rom = romanize(card.answer);
+    if (!rom.text)
+        return card;
+    return {
+        ...card,
+        romanization: rom.text,
+        glyphMap: rom.glyphMap,
+        romanizationAccepted: rom.accepted,
+    };
+}
+function parseCard(chunk, materialType, filePath, index) {
+    const lines = chunk.split('\n');
+    const h1Line = lines[0];
+    const titleMatch = h1Line.match(/^#\s+(.*)$/);
+    if (!titleMatch)
+        return null;
+    const title = titleMatch[1].trim();
+    if (!title)
         return null;
-    const question = qMatch[1].trim();
+    const body = lines.slice(1).join('\n').trim();
+    switch (materialType) {
+        case 'word':
+        case 'sentence':
+            return buildAnnotatedCard(title, body, filePath, index);
+        case 'qa':
+        case 'code':
+            return buildQACard(title, body, filePath, index);
+        case 'article':
+        case 'snippet':
+        default:
+            return buildArticleCard(title, body, filePath, index);
+    }
+}
+/**
+ * word / sentence: H1 is the typing target. H2/H3/H4 are optional
+ * single-line annotation slots.
+ */
+function buildAnnotatedCard(title, body, filePath, index) {
+    const validated = validateTypingText(title);
+    const answer = validated.text;
+    if (!answer)
+        return null;
+    const h2 = extractHeadingContent(body, 2);
+    const h3 = extractHeadingContent(body, 3);
+    const h4 = extractHeadingContent(body, 4);
+    const charPlans = textToCharPlans(answer);
+    return {
+        id: `${filePath}#${index}`,
+        title: answer,
+        answer,
+        phonetic: h2 || undefined,
+        gloss: h3 || undefined,
+        image: h4 || undefined,
+        charPlans,
+        unknownChars: validated.unknowns,
+    };
+}
+/**
+ * article: H1 is the section heading; the entire body under H1 is
+ * the typing target. Images and other non-text markdown are stripped
+ * from the typing text but preserved in `question` so the renderer
+ * can show them alongside the arena.
+ */
+function buildArticleCard(title, body, filePath, index) {
+    const rawTarget = stripImages(body).trim();
+    if (!rawTarget)
+        return null;
+    const validated = validateTypingText(rawTarget);
+    const answer = validated.text;
+    if (!answer)
+        return null;
+    const charPlans = textToCharPlans(answer);
+    return {
+        id: `${filePath}#${index}`,
+        title,
+        answer,
+        // `question` carries the raw body so images render in the card
+        // shell alongside the arena. The arena itself gets `answer`, which
+        // is the images-stripped normalized text.
+        question: body,
+        charPlans,
+        unknownChars: validated.unknowns,
+    };
+}
+/**
+ * qa / code: H1 is the card heading; `## Q` marks the prompt; `## A`
+ * marks the answer (typing target). Both sub-sections are captured as
+ * raw markdown; the answer is stripped of image markdown for typing.
+ */
+function buildQACard(title, body, filePath, index) {
+    const qaMatch = body.match(/##\s*Q\b\s*\n([\s\S]*?)(?=\n##\s*A\b|$)/);
+    const aMatch = body.match(/##\s*A\b\s*\n([\s\S]*)$/);
+    if (!aMatch)
+        return null;
+    const question = qaMatch ? qaMatch[1].trim() : '';
     const rawAnswer = aMatch[1].trim();
-    if (!question || !rawAnswer)
+    const targetText = extractTypingText(rawAnswer);
+    if (!targetText)
         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);
+    const validated = validateTypingText(targetText);
+    const answer = validated.text;
+    if (!answer)
+        return null;
+    const charPlans = textToCharPlans(answer);
     return {
         id: `${filePath}#${index}`,
+        title,
+        answer,
         question,
-        answer: validated.text,
-        meta,
         charPlans,
         unknownChars: validated.unknowns,
     };
 }
+/**
+ * Get the inline text of the first H2/H3/H4 in a block, `null` if
+ * absent. Only same-line content is returned — H4 for word cards is
+ * expected to be a single `![](url)` on the heading line.
+ */
+function extractHeadingContent(body, level) {
+    const hashes = '#'.repeat(level);
+    const re = new RegExp(`^${hashes}\\s+(.*)$`, 'm');
+    const m = body.match(re);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Strip markdown images so the typing target contains only characters
+ * the user can actually type. Fenced code fences themselves are
+ * removed (backticks aren't typed), but their contents are kept.
+ */
+function extractTypingText(md) {
+    return stripFencedCodeMarkers(stripImages(md)).trim();
+}
+function stripImages(md) {
+    return md.replace(/!\[[^\]]*\]\([^)]*\)/g, '');
+}
+/**
+ * Remove the ``` fences around fenced code blocks so the code body
+ * itself becomes the typing target. The optional language tag on the
+ * opening fence is also dropped.
+ */
+function stripFencedCodeMarkers(md) {
+    return md.replace(/```[^\n]*\n?/g, '').replace(/```\s*$/g, '');
+}

package/dist/core/romanization/index.js

@@ -0,0 +1,152 @@
+/**
+ * romanization — turn CJK text into a keyboard-typable roman-alphabet
+ * form so users can practice against the actual key sequence (pinyin),
+ * not the composed glyph they can only produce via an IME.
+ *
+ * Currently supports Chinese via `pinyin-pro`. The field name and API
+ * are neutral so we can plug in romaji / hangul romanization later
+ * behind the same abstraction.
+ *
+ * Output:
+ *   text        — the roman string (typing target)
+ *   glyphMap[i] — index into the original text that romanChar `i`
+ *                 belongs to. Non-CJK chars are 1:1 self-mapped;
+ *                 each CJK char's pinyin syllable + a trailing space
+ *                 all map back to that single CJK char.
+ *
+ * Punctuation:
+ *   Full-width CJK punctuation (`，` `。` `；` etc.) is folded to its
+ *   ASCII equivalent (`,` `.` `;`) so the user can actually type it
+ *   without switching to a CJK IME.
+ */
+import { pinyin } from 'pinyin-pro';
+/** True if the string contains any CJK Han character. */
+const HAN_RE = /\p{Script=Han}/u;
+export function containsCJK(s) {
+    return HAN_RE.test(s);
+}
+/** Full-width CJK punctuation → ASCII fold table. */
+const PUNCT_FOLD = {
+    '，': ',',
+    '。': '.',
+    '；': ';',
+    '：': ':',
+    '？': '?',
+    '！': '!',
+    '、': ',',
+    '（': '(',
+    '）': ')',
+    '「': '"',
+    '」': '"',
+    '『': '"',
+    '』': '"',
+    '“': '"',
+    '”': '"',
+    '‘': "'",
+    '’': "'",
+    '《': '<',
+    '》': '>',
+    '·': '.',
+    '—': '-',
+    '…': '.',
+    '～': '~',
+};
+function foldPunct(ch) {
+    return PUNCT_FOLD[ch] ?? ch;
+}
+/**
+ * Build the romanization + glyph map for a piece of mixed CJK/ASCII
+ * text. Multi-reading Hanzi get their alternate pinyins folded into
+ * `accepted[i]` so any valid reading types-through cleanly.
+ */
+export function romanize(text) {
+    const chars = Array.from(text);
+    const out = [];
+    const map = [];
+    const accepted = [];
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (HAN_RE.test(ch)) {
+            // Default reading — drives the visible text and the syllable
+            // length. Multi-reading Hanzi additionally contribute their
+            // letters into `accepted` at aligned positions.
+            const defaultSyl = pinyin(ch, {
+                toneType: 'none',
+                type: 'string',
+                v: true,
+            });
+            let readings;
+            if (!defaultSyl || defaultSyl === ch) {
+                // pinyin-pro has no entry for this glyph. Emit a single '?'
+                // placeholder so downstream indexing stays aligned; consumers
+                // can accept any letter here (rare chars are effectively
+                // free-pass).
+                readings = ['?'];
+            }
+            else {
+                const multi = pinyin(ch, {
+                    toneType: 'none',
+                    type: 'string',
+                    v: true,
+                    multiple: true,
+                });
+                // Some pinyin-pro versions return the multi-reading string
+                // as space-separated syllables. Split and dedupe. Always keep
+                // defaultSyl first so `text` uses it.
+                const parts = typeof multi === 'string'
+                    ? multi.split(' ').map((s) => s.trim()).filter(Boolean)
+                    : [defaultSyl];
+                readings = Array.from(new Set([defaultSyl, ...parts]));
+            }
+            const primary = readings[0];
+            for (let k = 0; k < primary.length; k++) {
+                const c = primary[k];
+                out.push(c);
+                map.push(i);
+                // Union of the k-th letter of every reading whose length > k.
+                const set = new Set();
+                if (primary === '?') {
+                    // Rare-char slot: accept ANY letter (represented by empty
+                    // set treated as wildcard by consumers).
+                    set.add('*');
+                }
+                else {
+                    for (const r of readings) {
+                        if (k < r.length)
+                            set.add(r[k]);
+                    }
+                }
+                accepted.push(set);
+            }
+            // Separator space between syllables.
+            out.push(' ');
+            map.push(i);
+            accepted.push(new Set([' ']));
+        }
+        else {
+            const folded = foldPunct(ch);
+            out.push(folded);
+            map.push(i);
+            accepted.push(new Set([folded]));
+        }
+    }
+    // Trim trailing separator.
+    while (out.length > 0 &&
+        out[out.length - 1] === ' ' &&
+        map[map.length - 1] === chars.length - 1) {
+        out.pop();
+        map.pop();
+        accepted.pop();
+    }
+    return { text: out.join(''), glyphMap: map, accepted };
+}
+/**
+ * Check if `ch` is acceptable at position `i` in a romanization.
+ * Handles the wildcard '*' used for rare-char placeholders.
+ */
+export function isAccepted(accepted, i, ch) {
+    const set = accepted[i];
+    if (!set)
+        return false;
+    return set.has('*') || set.has(ch);
+}