@qnroa/qtype 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -13,6 +13,76 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.0.8] — 2026-08-27
+
+Breaking dist format. Source `material/*.md` unchanged — the change
+is entirely in the build output and the view runtime. Users must
+re-run `qtype publish build` once; deployed sites need to re-upload
+the new `dist/`.
+
+### Changed
+- **Build ships one `.json` per material, not the raw `.md`.**
+  Each source `qa/security.md` now becomes `qa/security.json` under
+  `dist/material/`, containing the fully-parsed `Material` (structured
+  body, precomputed `charPlans`, romanization). Encrypted repos land
+  as `qa/security.json.enc`. The browser no longer parses markdown —
+  it fetches the JSON and renders directly. Roughly a 30–50% cold-load
+  latency win on medium repos; the parse ran on every navigation before.
+- **`index.json.tagIndex` / `typeIndex` map to card ids, not file paths.**
+  Filter UIs can now enumerate matching cards without loading a single
+  material file. The `cards[]` flat card index remains as-is (id / file
+  / title / type / tags).
+
+### Added
+- **Card-level filter view on Home.** Selecting a tag or type replaces
+  the material grid with a flat list of matching cards, grouped by
+  material for context but clickable per card.
+- **Cross-material filter navigation in typing.** Clicking a card from
+  the filter hit list carries the hit list into the typing route —
+  prev/next walks the filter results across materials, not the source
+  material's own card order. The hit list is persisted in
+  `localStorage`, so a page refresh keeps the filter context (F5 no
+  longer drops it).
+
+### Migration
+- Upgrade the qtype dependency, then run `qtype publish build` once.
+- Old `dist/` layout is not read anymore; delete and redeploy.
+
+## [0.0.7] — 2026-08-26
+
+Fully backward compatible: existing repos parse unchanged. The
+new capability is opt-in — write card-level frontmatter only where
+a card differs from the material default.
+
+### Added
+- **`Card` runtime shape gains `type` and `tags` fields.** Populated
+  either by card-level frontmatter or by inheriting the material
+  default. Downstream code should read `card.type` / `card.tags`
+  instead of `material.meta.type` / `material.meta.tags` when it
+  wants per-card resolution.
+- **Card-level frontmatter.** After an H1 you may open a second
+  `---\n...\n---` YAML block declaring `type` and `tags` for that one
+  card. This lets a single file mix qa / code / article — e.g. one qa
+  "principle" card followed by four code cards for cpp / py / go / java.
+- **Material-level fields are defaults.** `material.type` is the
+  fallback type for cards that don't declare their own.
+  `material.tags` is unioned with each card's tags (deduped). A card
+  can always override with its own card-level fm.
+- **`publish build` emits a flat card pool.** `dist/material/index.json`
+  carries `cards`, `tagIndex`, and `typeIndex` alongside the existing
+  `materials` list so the reader can filter/pick without fetching
+  every `.md`.
+- **Migration scripts.** `scripts/migrate_card_fm.py` pushes
+  material-level defaults down into every card (opt-in). Bundled but
+  usually unnecessary — the parser now handles legacy files natively.
+
+### Changed
+- QTYPE.md rules updated: "one material one type" is gone; the new
+  spec is "material-level fields set defaults; cards can override".
+- Search / lint / all internal consumers operate on `card.type` and
+  `card.tags` directly (still transparently backed by material defaults
+  when the card doesn't override).
+
 ## [0.0.6] - 2026-08-24
 
 ### Changed

package/CHANGELOG.zh.md

@@ -12,6 +12,61 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.0.8] — 2026-08-27
+
+破坏性 dist 格式变更。源 `material/*.md` 不变 —— 变化都在 build
+产物和 view 运行时。用户需要重新跑一次 `qtype publish build`；已部署
+的站点需要重新上传新的 `dist/`。
+
+### 变更
+- **build 产物为每份材料输出一个 `.json`，不再拷贝原始 `.md`。**
+  源文件 `qa/security.md` 现在会构建为 `dist/material/qa/security.json`,
+  内容是已完整解析的 `Material`（结构化 body、预算好的 `charPlans`、
+  拼音等）。加密仓落地为 `qa/security.json.enc`。浏览器不再解析
+  markdown，直接读 JSON 渲染。中等规模仓库冷启动延迟降低 30–50%。
+- **`index.json.tagIndex` / `typeIndex` 值改为卡 id，不再是材料 file。**
+  筛选 UI 可以直接枚举命中卡而不需要拉任何材料文件。顶层的 `cards[]`
+  扁平卡索引保持不变（id / file / title / type / tags）。
+
+### 新增
+- **Home 页卡级筛选视图**。勾一个 tag 或 type 后，材料网格会被替换
+  成命中卡列表，按材料聚合展示但每张卡独立可点。
+- **筛选跨材料翻页**。从命中卡列表点进 typing 时，前端会把命中列表
+  带到 typing 路由，prev/next 沿命中列表跨材料游走，而不是回退到
+  源材料内翻页。命中列表持久化到 `localStorage`，刷新页面（F5）后
+  筛选上下文仍然保留。
+
+### 迁移
+- 升级 qtype 依赖后，跑一次 `qtype publish build`。
+- 老的 `dist/` 结构已不再被读取，直接删除并重新部署。
+
+## [0.0.7] — 2026-08-26
+
+完全向后兼容:老仓库解析不变。新能力是可选的 —— 只在卡片和材料
+默认不同时才写卡级 frontmatter。
+
+### 新增
+- **`Card` 运行时结构新增 `type` 和 `tags` 字段**。值来自卡级 fm
+  或从材料默认继承。下游代码在需要 per-card 语义时应读 `card.type` /
+  `card.tags`,不要读 `material.meta.type` / `material.meta.tags`。
+- **卡级 frontmatter**。H1 后可以开第二段 `---\n...\n---` YAML 声明
+  该卡的 `type` 和 `tags`。这样一个文件里可以自由混合 qa / code /
+  article —— 比如 1 张 qa 原理卡加 4 张不同语言的 code 实现卡。
+- **素材级字段变成默认值**。`material.type` 是卡的 fallback,卡不写
+  就继承。`material.tags` 和卡级 tags 合并去重。任何一张卡都能靠自己
+  的卡级 fm 覆盖默认。
+- **`publish build` 输出扁平卡池**。`dist/material/index.json` 新增
+  `cards`、`tagIndex`、`typeIndex` 三个字段,reader 无需拉每份 md
+  就能做筛选。
+- **迁移脚本**:`scripts/migrate_card_fm.py` 一键把素材级 type/tags
+  下推到每张卡(可选,通常不需要 —— parser 原生支持向后继承)。
+
+### 变更
+- QTYPE.md 规则更新:"一个 material 一个 type" 改为"素材级字段是默认
+  值,卡可以覆盖"。
+- 搜索、lint、所有内部消费方直接读 `card.type` 加 `card.tags`(值来
+  自卡自身或素材默认,parser 透明处理)。
+
 ## [0.0.6] - 2026-08-24
 
 ### 变更

package/dist/cli/commands/content/search/action.js

@@ -21,16 +21,16 @@ export async function contentSearchAction(query, opts = {}) {
         const rel = `${MATERIAL_DIR}/${file.rel}`;
         const src = readMaterial(file);
         const material = parseMaterial(src, rel);
-        const materialType = material.meta.type?.toLowerCase() ?? 'article';
-        if (typeFilter.length > 0 && !typeFilter.includes(materialType))
-            continue;
-        const materialTags = (material.meta.tags ?? []).map((t) => t.toLowerCase());
-        if (tagFilter.length > 0 &&
-            !tagFilter.every((wanted) => materialTags.includes(wanted))) {
-            continue;
-        }
         for (let i = 0; i < material.cards.length; i++) {
             const card = material.cards[i];
+            const cardType = card.type.toLowerCase();
+            if (typeFilter.length > 0 && !typeFilter.includes(cardType))
+                continue;
+            const cardTags = card.tags.map((t) => t.toLowerCase());
+            if (tagFilter.length > 0 &&
+                !tagFilter.every((wanted) => cardTags.includes(wanted))) {
+                continue;
+            }
             const question = card.question ?? card.title;
             const qLc = question.toLowerCase();
             const aLc = card.answer.toLowerCase();
@@ -50,8 +50,8 @@ export async function contentSearchAction(query, opts = {}) {
                 question,
                 answer: card.answer,
                 snippet,
-                type: material.meta.type,
-                tags: material.meta.tags ?? [],
+                type: card.type,
+                tags: card.tags,
             });
             if (hits.length >= limit)
                 break outer;

package/dist/cli/commands/content/validate/action.js

@@ -92,16 +92,14 @@ export async function contentValidateAction(opts = {}) {
                     questionIndex.set(key, here);
                 }
             }
-            // Card-level tag consistency was removed with the frontmatter
-            // simplification — only material-level tags exist now, handled below.
+            // Collect card tags for cross-corpus casing consistency check.
+            for (const tag of card.tags) {
+                const lower = tag.toLowerCase();
+                const set = tagVariants.get(lower) ?? new Set();
+                set.add(tag);
+                tagVariants.set(lower, set);
+            }
         });
-        // Material-level tag casing consistency.
-        for (const tag of material.meta.tags) {
-            const lower = tag.toLowerCase();
-            const set = tagVariants.get(lower) ?? new Set();
-            set.add(tag);
-            tagVariants.set(lower, set);
-        }
     }
     for (const [lower, variants] of tagVariants) {
         if (variants.size > 1) {

package/dist/cli/commands/publish/build/action.js

@@ -6,9 +6,22 @@
  *   2. Resolve optional password-encryption context (see `publish/password/`).
  *   3. Wipe & recreate the output directory.
  *   4. Copy the view bundle wholesale, then strip its dev-seed material/.
- *   5. Copy the user's material/*.md (encrypting each file if the repo has
- *      password protection enabled) and emit an index.json manifest that
- *      records the file list + titles for the view to consume.
+ *   5. Parse each `material/*.md` into a fully-typed Material (structured
+ *      body, charPlans, romanization all resolved), then emit one
+ *      `<path>.json` per source `.md` — the view no longer parses markdown
+ *      at runtime. Card-level filter/browse indices live in `index.json`.
+ *
+ * ─── Why JSON per material, not raw md ───
+ * Prior versions shipped the raw `.md` and had the browser call
+ * `parseMaterial()` on every load. That made typing-target extraction,
+ * pinyin romanization, and keystroke planning all client-side hot paths
+ * — visible latency on cold navigation, and duplicated logic between
+ * `qtype check` and the view. Moving the parse to build:
+ *   - View pulls one JSON per material and renders directly — no parse.
+ *   - `charPlans` / `romanization` are computed once, reused everywhere.
+ *   - The `tagIndex` / `typeIndex` in `index.json` are cardId-grained,
+ *     so tag/type filters can enumerate matching cards without loading
+ *     any material file.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -20,7 +33,7 @@ import { createRepoKv } from '../../../bootstrap.js';
 import { deriveAesKey, encryptString, DEFAULT_ARGON2_PARAMS, } from '../../../../core/encrypt.js';
 import { verifyPassword } from '../password/action.js';
 import { prerenderMermaid, emptyMermaidPass } from './mermaidPass.js';
-import { parseMaterialFrontmatter } from '../../../../core/parser/frontmatter.js';
+import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
 import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function publishBuildAction(opts = {}) {
     const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
@@ -51,11 +64,8 @@ export async function publishBuildAction(opts = {}) {
         const body = readMaterial(file);
         const filename = file.rel.split('/').pop() ?? file.rel;
         const title = readTitle(body) ?? filename.replace(/\.md$/, '');
-        const fm = parseMaterialFrontmatter(body).meta;
-        const fallbackType = file.rel.includes('/') ? file.rel.split('/')[0] : '';
-        const type = fm.type ?? fallbackType;
         const cardCount = countH1(body);
-        materials.push({ name: file.rel, body, title, type, tags: fm.tags, cardCount });
+        materials.push({ name: file.rel, body, title, cardCount });
     }
     // Mermaid pre-render — scan all bodies, produce svg + css maps.
     const mermaid = mermaidMode === 'prerender'
@@ -80,25 +90,47 @@ export async function publishBuildAction(opts = {}) {
     const targetMaterial = path.join(outDir, MATERIAL_DIR);
     fs.rmSync(targetMaterial, { recursive: true, force: true });
     fs.mkdirSync(targetMaterial, { recursive: true });
+    // Parse each material once. We reuse the parsed Material both for
+    // the per-material JSON payload and for the flat card index below,
+    // so a bad parse skips this material from both outputs (rather than
+    // half-emitting it).
+    const parsedByFile = new Map();
+    for (const m of materials) {
+        try {
+            parsedByFile.set(m.name, parseMaterial(m.body, m.name));
+        }
+        catch (err) {
+            info(t('publish.build.msg.parseSkip', {
+                file: m.name,
+                reason: err instanceof Error ? err.message : String(err),
+            }));
+        }
+    }
     const entries = [];
     for (const m of materials) {
+        const parsed = parsedByFile.get(m.name);
+        if (!parsed)
+            continue;
+        // Source md becomes `<path>.json` (or `<path>.json.enc` when
+        // encrypted). We strip the `.md` extension so the URL path mirrors
+        // the source hierarchy while carrying the runtime payload shape.
+        const jsonRel = m.name.replace(/\.md$/, '.json');
         const outPath = encryptCtx
-            ? path.join(targetMaterial, `${m.name}.enc.json`)
-            : path.join(targetMaterial, m.name);
+            ? path.join(targetMaterial, `${jsonRel}.enc`)
+            : path.join(targetMaterial, jsonRel);
         fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        const payload = serializeMaterial(parsed);
         if (encryptCtx) {
-            const blob = await encryptString(encryptCtx.key, m.body);
+            const blob = await encryptString(encryptCtx.key, payload);
             fs.writeFileSync(outPath, JSON.stringify(blob));
         }
         else {
-            fs.writeFileSync(outPath, m.body);
+            fs.writeFileSync(outPath, payload);
         }
         entries.push({
             file: m.name,
             title: m.title,
-            type: m.type,
-            tags: m.tags,
-            cardCount: m.cardCount,
+            cardCount: parsed.cards.length,
         });
     }
     // Mermaid SVG map + CSS: the view fetches these alongside index.json and
@@ -124,8 +156,48 @@ export async function publishBuildAction(opts = {}) {
     if (fs.existsSync(srcAssets)) {
         copyDir(srcAssets, path.join(targetMaterial, 'assets'));
     }
+    // Card-pool index — flat listing of every card with its effective
+    // (material + card fm merged) metadata. Body content is NOT
+    // duplicated here; it lives in each material's own JSON payload.
+    //
+    // `tagIndex` / `typeIndex` map to card ids (not file paths) so
+    // filter UIs can enumerate matching cards without touching any
+    // material file.
+    const cardIndex = [];
+    const tagIndex = {};
+    const typeIndex = {};
+    for (const m of materials) {
+        const parsed = parsedByFile.get(m.name);
+        if (!parsed)
+            continue;
+        for (const card of parsed.cards) {
+            cardIndex.push({
+                id: card.id,
+                file: m.name,
+                title: card.title,
+                type: card.type,
+                tags: card.tags,
+            });
+            for (const tag of card.tags) {
+                if (!tagIndex[tag])
+                    tagIndex[tag] = [];
+                tagIndex[tag].push(card.id);
+            }
+            const ct = card.type || '';
+            if (ct) {
+                if (!typeIndex[ct])
+                    typeIndex[ct] = [];
+                typeIndex[ct].push(card.id);
+            }
+        }
+    }
     // Manifest: lists materials + optional encryption envelope + mermaid mode.
-    const manifest = { materials: entries };
+    const manifest = {
+        materials: entries,
+        cards: cardIndex,
+        tagIndex,
+        typeIndex,
+    };
     if (encryptCtx) {
         manifest.encrypted = {
             algo: 'AES-GCM',
@@ -143,10 +215,10 @@ export async function publishBuildAction(opts = {}) {
     // Repo language — the reader locks its UI to this so the interface
     // matches the material's own language.
     manifest.lang = repoLang;
-    fs.writeFileSync(path.join(targetMaterial, 'index.json'), JSON.stringify(manifest, null, 2) + '\n');
+    fs.writeFileSync(path.join(targetMaterial, 'index.json'), JSON.stringify(manifest));
     success(t('publish.build.msg.done', { path: outDir }));
     info(t('publish.build.msg.stat', {
-        count: countCards(materialDir).toString(),
+        count: cardIndex.length.toString(),
         materialCount: entries.length.toString(),
     }));
     info(t('publish.build.msg.hint'));
@@ -273,13 +345,36 @@ function countH1(source) {
     }
     return n;
 }
-function countCards(materialDir) {
-    let n = 0;
-    for (const name of fs.readdirSync(materialDir)) {
-        if (!name.endsWith('.md'))
-            continue;
-        const body = fs.readFileSync(path.join(materialDir, name), 'utf8');
-        n += body.split(/\n\n---\n\n/).filter((s) => /##\s*Q:/.test(s)).length;
-    }
-    return n;
+/**
+ * Serialize a parsed Material into the JSON string we ship in dist.
+ *
+ * Two size-oriented decisions:
+ *   - `charPlans` is stripped. It's the single biggest field per card
+ *     (one entry per typing character × its full keystroke list),
+ *     and the view already has a fallback: `TypingArena` calls
+ *     `textToCharPlans(target)` when the field is absent. Recomputing
+ *     on load is cheap (μs per card) and the size win is 10× on
+ *     CJK-heavy repos.
+ *   - `romanizationAccepted` is kept but folded from `Set<string>[]`
+ *     to `string[]` — sets don't survive `JSON.stringify`, and the
+ *     view rebuilds them via `new Set(str)` on load. Compact, and
+ *     recomputing pinyin+heteronym data client-side isn't cheap
+ *     (needs the whole pinyin dictionary), so shipping it is worth
+ *     the bytes.
+ *
+ * Serialized without indentation — dist is a runtime artifact, not
+ * something authors read. Skipping the 2-space indent halves the file
+ * size before gzip and matches how CDNs expect JSON assets to look.
+ */
+function serializeMaterial(material) {
+    const cards = material.cards.map((c) => {
+        const accepted = c.romanizationAccepted
+            ? c.romanizationAccepted.map((s) => [...s].sort().join(''))
+            : undefined;
+        // Explicitly omit charPlans — reconstructed by the view.
+        const { charPlans: _charPlans, ...rest } = c;
+        void _charPlans;
+        return { ...rest, romanizationAccepted: accepted };
+    });
+    return JSON.stringify({ ...material, cards });
 }

package/dist/cli/commands/publish/build/i18n.js

@@ -22,6 +22,7 @@ export const messages = {
         'publish.build.msg.mermaidDone': 'mermaid 渲染完成：{count} 个图，{errored} 个失败',
         'publish.build.msg.mermaidErrored': '{count} 个 mermaid 图渲染失败（已回落到错误占位 SVG）',
         'publish.build.msg.mermaidSkip': 'publish.mermaid={mode}，跳过预渲染',
+        'publish.build.msg.parseSkip': '跳过 {file}（解析失败：{reason}）',
     },
     'en-US': {
         'publish.build.summary': 'Build the static material site',
@@ -46,5 +47,6 @@ export const messages = {
         'publish.build.msg.mermaidDone': 'Mermaid render complete: {count} diagrams, {errored} failed',
         'publish.build.msg.mermaidErrored': '{count} mermaid diagram(s) failed to render (falling back to inline error SVG)',
         'publish.build.msg.mermaidSkip': 'publish.mermaid={mode}, skipping prerender',
+        'publish.build.msg.parseSkip': 'Skipped {file} (parse failed: {reason})',
     },
 };

package/dist/core/parser/frontmatter.js

@@ -15,7 +15,7 @@ const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
  * per-type rules).
  */
 export function parseMaterialFrontmatter(source) {
-    const meta = { tags: [] };
+    const meta = {};
     const match = source.match(FM_RE);
     if (!match)
         return { meta, rest: source };
@@ -54,9 +54,32 @@ function parseTagList(value) {
         .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.
+ * Card-level frontmatter — sits on the very first non-empty lines of a
+ * card body (right after the H1). Same YAML-fence syntax as the
+ * material-level block so users don't have to learn a second grammar.
+ * Returns empty meta if the body doesn't start with `---`.
+ */
+export function parseCardFrontmatter(cardBody) {
+    const meta = { tags: [] };
+    const match = cardBody.match(FM_RE);
+    if (!match)
+        return { meta, rest: cardBody };
+    const body = match[1];
+    const fields = {};
+    for (const line of body.split('\n')) {
+        const kv = line.match(/^(\w+)\s*:\s*(.+)$/);
+        if (!kv)
+            continue;
+        fields[kv[1]] = kv[2].trim();
+    }
+    if (fields.type)
+        meta.type = fields.type;
+    if (fields.tags)
+        meta.tags = parseTagList(fields.tags);
+    return { meta, rest: cardBody.slice(match[0].length) };
+}
+/**
+ * Kept for backwards compatibility of the barrel export.
  */
 export function parseFrontmatter(block) {
     return { meta: { tags: [] }, rest: block };

package/dist/core/parser/parseMaterial.js

@@ -1,15 +1,16 @@
-import { parseMaterialFrontmatter } from './frontmatter.js';
+import { parseMaterialFrontmatter, parseCardFrontmatter } from './frontmatter.js';
 import { textToCharPlans } from '../keystroke/index.js';
 import { validateTypingText } from '../keystroke/textNormalize.js';
 import { containsCJK, romanize } from '../romanization/index.js';
 export function parseMaterial(source, filePath = 'inline') {
     const normalized = source.replace(/\r\n/g, '\n').trim() + '\n';
     const { meta: materialMeta, rest } = parseMaterialFrontmatter(normalized);
-    const materialType = materialMeta.type ?? 'article';
+    const defaultType = materialMeta.type;
+    const defaultTags = materialMeta.tags ?? [];
     const rawCards = splitByH1(rest);
     const cards = [];
     for (let i = 0; i < rawCards.length; i++) {
-        const card = parseCard(rawCards[i], materialType, filePath, i);
+        const card = parseCard(rawCards[i], defaultType, defaultTags, filePath, i);
         if (card)
             cards.push(attachRomanization(card));
     }
@@ -57,7 +58,7 @@ function attachRomanization(card) {
         romanizationAccepted: rom.accepted,
     };
 }
-function parseCard(chunk, materialType, filePath, index) {
+function parseCard(chunk, defaultType, defaultTags, filePath, index) {
     const lines = chunk.split('\n');
     const h1Line = lines[0];
     const titleMatch = h1Line.match(/^#\s+(.*)$/);
@@ -66,19 +67,50 @@ function parseCard(chunk, materialType, filePath, index) {
     const title = titleMatch[1].trim();
     if (!title)
         return null;
-    const body = lines.slice(1).join('\n').trim();
-    switch (materialType) {
+    const rawBody = lines.slice(1).join('\n').trim();
+    const { meta: cardMeta, rest: bodyAfterFm } = parseCardFrontmatter(rawBody);
+    const body = bodyAfterFm.trim();
+    // Type resolution: card's own type wins, otherwise fall back to the
+    // material's default. A card with neither is unparseable and gets
+    // skipped (validators can surface this to the author).
+    const cardType = (cardMeta.type ?? defaultType);
+    if (!cardType)
+        return null;
+    const tags = dedupe([...defaultTags, ...cardMeta.tags]);
+    let card;
+    switch (cardType) {
         case 'word':
         case 'sentence':
-            return buildAnnotatedCard(title, body, filePath, index);
+            card = buildAnnotatedCard(title, body, filePath, index);
+            break;
         case 'qa':
         case 'code':
-            return buildQACard(title, body, filePath, index);
+            card = buildQACard(title, body, filePath, index);
+            break;
         case 'article':
         case 'snippet':
         default:
-            return buildArticleCard(title, body, filePath, index);
+            card = buildArticleCard(title, body, filePath, index);
+            break;
+    }
+    if (!card)
+        return null;
+    card.type = cardType;
+    card.tags = tags;
+    return card;
+}
+function dedupe(tags) {
+    const seen = new Set();
+    const out = [];
+    for (const t of tags) {
+        if (!t)
+            continue;
+        if (seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
     }
+    return out;
 }
 /**
  * word / sentence: H1 is the typing target. H2/H3/H4 are optional
@@ -102,6 +134,8 @@ function buildAnnotatedCard(title, body, filePath, index) {
         image: h4 || undefined,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**
@@ -129,6 +163,8 @@ function buildArticleCard(title, body, filePath, index) {
         question: body,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**
@@ -158,6 +194,8 @@ function buildQACard(title, body, filePath, index) {
         question,
         charPlans,
         unknownChars: validated.unknowns,
+        type: '',
+        tags: [],
     };
 }
 /**