@qnroa/qtype 0.0.9 → 0.1.0

package/CHANGELOG.md

@@ -13,6 +13,121 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.1.0] — 2026-08-27
+
+Breaking dist format. Source `material/*.md` unchanged — the source
+grammar and semantics are preserved end-to-end. Users must re-run
+`qtype publish build` once; deployed sites need to re-upload the new
+`dist/`.
+
+### Fixed
+- **`splitByH1` now respects fenced code blocks.** A `# ...` line
+  inside a ``` ``` fence is no longer mistaken for a new card. This
+  was silently slicing materials with hash-comment code samples (e.g.
+  a regex primer's Python snippets) into dozens of bogus cards whose
+  indices leaked downstream through the `<file>#<idx>` id scheme.
+- **`promptPassword` recognises Ctrl-C (`\x03`) and DEL (`\x7f`).**
+  Both control characters had been silently dropped from the source
+  during an earlier copy-paste, leaving password entry unable to
+  abort on Ctrl-C or backspace correctly on modern terminals.
+- **HUD "back to library" preserves the selected tag filter.** The
+  purge effect in `useLibraryFilters` used to run against the initial
+  `availableTags: []` from a still-loading manifest and nuke every
+  persisted tag before the corpus arrived. Now waits until the corpus
+  is known.
+- **Filter-list navigation walks the filter, not the source material.**
+  `useFilterFlow` no longer depends on the async manifest — the
+  neighbour `(file, idx)` is carried inside each hit entry, so
+  `next()` / `prev()` work from the moment localStorage settles.
+- **Grid ↔ list view toggle is orthogonal to filtering.** Prior
+  versions forced list layout whenever a tag/type filter was active,
+  ignoring the user's chosen mode. Now grid stays grid, list stays
+  list — the filter changes *what* is listed (materials vs. matching
+  cards), not *how*.
+- **F5 keeps the filter hit list.** The hit list moved from a
+  module-level variable to `localStorage`, so refreshing the typing
+  page no longer degrades to intra-material navigation.
+
+### Changed (breaking)
+- **`Card.id` is a 12-hex-char content hash instead of
+  `<file>#<idx>`.** Reordering cards inside a material no longer
+  invalidates every downstream reference (bookmarks, filter picks,
+  CDN cache keys). Position information is preserved as first-class
+  fields on the card: `Card.materialFile` + `Card.indexInMaterial`.
+- **`Card` gains required fields `materialFile` and `indexInMaterial`.**
+  Downstream consumers that need location info should read these
+  instead of parsing `id`.
+- **`dist/material/mermaid.json` is gone.** Mermaid SVGs are now
+  sharded per material: `qa/security.md` gets
+  `dist/material/qa/security.mermaid.json`. Encrypted repos land as
+  `<file>.mermaid.json.enc`. The browser only fetches the shard for
+  the material it's rendering, not the union of every diagram in the
+  repo.
+- **Build ships one JSON per material, not the raw `.md`.** Source
+  `qa/security.md` now becomes `qa/security.json` under
+  `dist/material/`, containing the fully-parsed `Material`
+  (structured body, precomputed romanization). Encrypted repos land
+  as `qa/security.json.enc`. The browser no longer parses markdown —
+  it fetches the JSON and renders directly. (Introduced in 0.0.8; the
+  full breaking history is kept here for the 0.1.0 upgrade guide.)
+- **`index.json.tagIndex` / `typeIndex` map to card ids
+  (content-hash), not file paths.** Filter UIs can enumerate matching
+  cards without loading any material file. (Introduced in 0.0.8.)
+
+### Added
+- **`computeCardId(input)`** exported from `@qnroa/qtype/core` for
+  external tooling that wants to compute the same stable id qtype
+  uses.
+- **Card-level filter view on Home.** Selecting a tag or type
+  replaces the material grid with matching cards, laid out per the
+  current grid/list mode. (Introduced in 0.0.8, generalised to
+  grid + list in 0.0.9.)
+- **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. (Introduced in 0.0.8;
+  refactored to hit-entry rows carrying `(id, file, idx)` in 0.1.0.)
+- **`EntryCard` / `EntryRow` base components + `CardHitCard` /
+  `CardHitRow` specialisations.** Materials and card hits share one
+  shell (click / keyboard / selection / done stamp) so visual
+  behaviour is consistent regardless of what's being listed.
+  (Introduced in 0.0.9.)
+- **Lint warning `card.unknownType`.** Cards whose `type` isn't one
+  of the six built-ins (word / sentence / article / snippet / qa /
+  code) now surface a warning — 90% of the time it's a typo that
+  would otherwise render silently wrong.
+- **`qtype init --force` skips sample material seeds on repos with
+  real content.** Established repos no longer accumulate 6 unwanted
+  starter `.md` files (plus their asset SVGs) on every re-sync.
+
+### Migration
+- Upgrade the qtype dependency, then run `qtype publish build` once.
+- The old `dist/` layout is not read anymore; delete the deployed
+  copy and upload the fresh build.
+- User progress (`qtype.done`, `qtype.doneCards`) is stored under
+  `(file, indexInMaterial)` and still works — the new `id` is a
+  parallel identity for filter / bookmark purposes.
+
+## [0.0.10] — 2026-08-27
+
+Bug-fix release. Two regressions from the 0.0.8 filter feature —
+both view-only, no dist change.
+
+### Fixed
+- **Filter-list navigation now actually walks the filter, not the
+  source material.** `useFilterFlow` depended on the manifest's flat
+  card index to resolve neighbour (file, idx), but that index arrives
+  async — until it landed, `next()` / `prev()` returned `null` and
+  the typing route silently fell back to intra-material navigation.
+  The hook now parses `(file, idx)` directly out of the card id
+  (`<file>#<idx>`), so it works from the moment localStorage settles.
+- **Selected tags survive HUD "back to library".** The purge effect
+  in `useLibraryFilters` ran on the initial `availableTags: []` from
+  a still-loading manifest and nuked every persisted tag before the
+  corpus arrived. The purge now waits until the corpus is known
+  (new `corpusReady` param, defaults to `true` for backward
+  compatibility).
+
 ## [0.0.9] — 2026-08-27
 
 View-only. No dist change, no need to rebuild — refreshing the page

package/CHANGELOG.zh.md

@@ -12,6 +12,91 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.1.0] — 2026-08-27
+
+破坏性 dist 格式变更。源 `material/*.md` 未变 —— 语法和语义端到端
+保持一致。用户需要重新跑一次 `qtype publish build`；已部署的站点
+需要重新上传新的 `dist/`。
+
+### 修复
+- **`splitByH1` 识别代码块**。fenced code block 里以 `# ...` 开头的
+  行不再被误认为新卡。之前会把带 hash 注释的代码示例（比如 regex
+  教程里的 Python 片段）切成几十个假卡片，让 `<file>#<idx>` 的 id
+  索引跳跃。
+- **`promptPassword` 识别 Ctrl-C (`\x03`) 和 DEL (`\x7f`)**。两个
+  控制字符早期从 qrism 复制过来时被吃掉了，导致输密码时 Ctrl-C 无
+  法中断，现代终端的 Backspace 也无效。
+- **HUD"返回上级"后 tag 筛选保留**。`useLibraryFilters` 的 purge
+  effect 之前会在 manifest 还没加载完（`availableTags = []`）的初
+  始态跑，把持久化的所有 tag 都清掉。现在等 corpus 就绪再跑。
+- **筛选后翻页真的走筛选，不是走材料内**。`useFilterFlow` 不再依
+  赖异步 manifest —— 每条命中记录本身携带 `(file, idx)`,
+  `next()` / `prev()` 从 localStorage 就绪起就能工作。
+- **grid ↔ list 视图和筛选正交**。之前只要勾了 tag/type,不管用户
+  当前选的是 grid 还是 list,都强制变 list。现在 grid 保持 grid,
+  list 保持 list,筛选只决定"列的是什么"（材料还是命中卡）。
+- **F5 保留筛选命中列表**。hitList 从 module 级内存变量迁到
+  localStorage,刷新 typing 页不再回落到材料内翻页。
+
+### 变更（破坏性）
+- **`Card.id` 是 12 位内容 hash,不再是 `<file>#<idx>`**。材料内重排
+  卡片不再让下游引用（书签、筛选选中、CDN 缓存 key）全部失效。位置
+  信息作为 Card 的一等字段保留：`Card.materialFile` 和
+  `Card.indexInMaterial`。
+- **`Card` 新增必填字段 `materialFile` 和 `indexInMaterial`**。需要
+  位置信息的下游消费者应该读这两个字段而不是解析 `id`。
+- **`dist/material/mermaid.json` 消失**。Mermaid SVG 按材料分片：
+  `qa/security.md` 对应 `dist/material/qa/security.mermaid.json`。
+  加密仓库落到 `<file>.mermaid.json.enc`。浏览器只 fetch 当前材料
+  的 shard,不再下载全站图的并集。
+- **build 产物为每份材料一个 JSON,不再拷贝 `.md`**。源文件
+  `qa/security.md` 现在会构建为 `dist/material/qa/security.json`,
+  内容是已完整解析的 `Material`。加密仓库落地为
+  `qa/security.json.enc`。浏览器不再解析 markdown。（0.0.8 引入,
+  0.1.0 升级指南里保留完整破坏性历史。）
+- **`index.json.tagIndex` / `typeIndex` 值改为卡 id（内容 hash）,
+  不再是材料 file**。（0.0.8 引入。）
+
+### 新增
+- **`computeCardId(input)`** 从 `@qnroa/qtype/core` 导出,给外部
+  工具用来算和 qtype 一致的稳定 id。
+- **Home 卡级筛选视图**。勾一个 tag 或 type 后,材料网格被替换成
+  命中卡列表,按当前 grid/list 模式展示。（0.0.8 引入,0.0.9 泛化
+  为 grid + list。）
+- **筛选跨材料翻页**。从命中卡列表点进 typing 时,前端把命中列表
+  带到 typing 路由,prev/next 沿命中列表跨材料游走。（0.0.8 引入,
+  0.1.0 重构成每条记录带 `(id, file, idx)`。）
+- **`EntryCard` / `EntryRow` 基类 + `CardHitCard` / `CardHitRow`
+  特化**。材料和命中卡共享一套 shell（点击 / 键盘 / 选中 /
+  done stamp）,视觉行为一致。（0.0.9 引入。）
+- **lint 加 `card.unknownType` 警告**。`type` 不是内置 6 种（word /
+  sentence / article / snippet / qa / code）时报警 —— 90% 都是手
+  滑,不然会静默走 article 兜底渲染。
+- **`qtype init --force` 已有真实内容的 repo 跳过 sample seed**。
+  成熟 repo 每次同步不再累积 6 个 starter md（含 asset SVG）噪音。
+
+### 迁移
+- 升级 qtype 依赖后,跑一次 `qtype publish build`。
+- 老 `dist/` 结构已不再被读取,直接删除并重新部署。
+- 用户进度（`qtype.done` / `qtype.doneCards`）按 `(file,
+  indexInMaterial)` 存,继续可用 —— 新的 `id` 是给筛选 / 书签用的
+  并列身份,不替代它。
+
+## [0.0.10] — 2026-08-27
+
+Bug 修复。两个从 0.0.8 筛选功能引入的回归 —— 都是 view 层,dist 未变。
+
+### 修复
+- **筛选后翻页现在真的走筛选,不是走材料内**。`useFilterFlow` 之前
+  依赖 manifest 的扁平卡索引来解析下一张的 `(file, idx)`,但该索引
+  是异步加载的 —— 在它到达之前,`next()` / `prev()` 返回 `null`,
+  typing 页静默回退到材料内翻页。现在改成直接从 cardId (`<file>#<idx>`)
+  自解析 `(file, idx)`,localStorage 一就位就能用。
+- **HUD"返回上级"后 tag 筛选保留**。`useLibraryFilters` 的 purge
+  effect 会在 manifest 还没加载完(此时 `availableTags` 是 `[]`)
+  的初始态就跑,把持久化的所有 tag 都清掉。现在 purge 会等到 corpus
+  就绪才跑(新的 `corpusReady` 参数,默认 `true` 保持向后兼容)。
+
 ## [0.0.9] — 2026-08-27
 
 只改 view,dist 未变,老部署刷新页面即可,无需重跑 build。

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

@@ -11,6 +11,17 @@ import { ensureQtypeRepo } from '../../../utils/repoGuard.js';
 import { t } from '../../../i18n/index.js';
 import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
 import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
+/** The six built-in card types the parser and renderers understand. A
+ *  card with any other `type` falls through to article-style rendering —
+ *  legal (custom user types are allowed) but often a typo. */
+const BUILT_IN_TYPES = new Set([
+    'word',
+    'sentence',
+    'article',
+    'snippet',
+    'qa',
+    'code',
+]);
 const TITLE_RE = /^title:\s*(.+)$/m;
 const HEADING_RE = /^#\s+.+$/m;
 export async function contentLintAction(opts = {}) {
@@ -60,10 +71,28 @@ export async function contentLintAction(opts = {}) {
                     }),
                 });
             }
+            // Warn (not error) when card.type isn't one of the six built-ins.
+            // Custom types are legal per QTYPE spec — the parser accepts them
+            // and the renderer falls back to article shape — but nine times
+            // out of ten it's a typo (`qaa` for `qa`, `articel` for `article`)
+            // that would otherwise render silently wrong.
+            if (c.type && !BUILT_IN_TYPES.has(c.type)) {
+                issues.push({
+                    code: 'card.unknownType',
+                    path: rel,
+                    card: i + 1,
+                    message: t('content.lint.issue.unknownType', {
+                        path: rel,
+                        card: i + 1,
+                        type: c.type,
+                    }),
+                });
+            }
         });
     }
-    // `emptyTitle` is treated as a warning (informational). Anything else is an error.
-    const errorIssues = issues.filter((i) => i.code !== 'material.emptyTitle');
+    // Informational warnings — reported but don't fail the check.
+    const WARN_CODES = new Set(['material.emptyTitle', 'card.unknownType']);
+    const errorIssues = issues.filter((i) => !WARN_CODES.has(i.code));
     const result = {
         ok: errorIssues.length === 0,
         stats: { materials: materialCount, cards: cardTotal },
@@ -85,7 +114,7 @@ export async function contentLintAction(opts = {}) {
                 console.error(`    ${t('content.lint.msg.andMore', { count: errorIssues.length - 30 })}`);
             }
         }
-        const warnIssues = issues.filter((i) => i.code === 'material.emptyTitle');
+        const warnIssues = issues.filter((i) => WARN_CODES.has(i.code));
         for (const w of warnIssues)
             warn(w.message);
         if (result.ok)

package/dist/cli/commands/content/lint/i18n.js

@@ -13,6 +13,7 @@ export const messages = {
         'content.lint.issue.noCards': '{path}: 未识别到任何 Q/A 卡片',
         'content.lint.issue.unknownChars': '{path}#{card}: 含无法练习的字符 → {chars}',
         'content.lint.issue.emptyTitle': '{path}: frontmatter 缺少 title',
+        'content.lint.issue.unknownType': '{path}#{card}: type={type} 不是内置 6 种（word/sentence/article/snippet/qa/code），将走 article 兜底渲染',
     },
     'en-US': {
         'content.lint.summary': 'Material format lint',
@@ -28,5 +29,6 @@ export const messages = {
         'content.lint.issue.noCards': '{path}: no Q/A cards parsed',
         'content.lint.issue.unknownChars': '{path}#{card}: non-typable chars → {chars}',
         'content.lint.issue.emptyTitle': '{path}: frontmatter missing title',
+        'content.lint.issue.unknownType': '{path}#{card}: type={type} is not one of the six built-ins (word/sentence/article/snippet/qa/code) — will fall back to article rendering',
     },
 };

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

@@ -67,9 +67,11 @@ export async function publishBuildAction(opts = {}) {
         const cardCount = countH1(body);
         materials.push({ name: file.rel, body, title, cardCount });
     }
-    // Mermaid pre-render — scan all bodies, produce svg + css maps.
+    // Mermaid pre-render — scan all bodies, produce per-file svg maps
+    // + a shared css blob. Sharded per material so the browser only
+    // downloads the diagrams referenced by the material it's opening.
     const mermaid = mermaidMode === 'prerender'
-        ? await prerenderMermaid(materials.map((m) => m.body))
+        ? await prerenderMermaid(materials.map((m) => ({ file: m.name, body: m.body })))
         : emptyMermaidPass();
     if (mermaidMode !== 'prerender') {
         info(t('publish.build.msg.mermaidSkip', { mode: mermaidMode }));
@@ -133,16 +135,28 @@ export async function publishBuildAction(opts = {}) {
             cardCount: parsed.cards.length,
         });
     }
-    // Mermaid SVG map + CSS: the view fetches these alongside index.json and
-    // looks up each fence by its trimmed source when rendering material bodies.
+    // Mermaid SVG shards — one per material that has diagrams. The view
+    // fetches `<file>.mermaid.json` next to `<file>.json` on demand.
+    // Prior versions shipped a single top-level `mermaid.json` covering
+    // every diagram in the repo; that forced every reader to download
+    // the union even when they opened one material.
     if (mermaid.count > 0) {
-        const mermaidJson = mermaidMode === 'prerender' ? mermaid.svgs : {};
-        if (encryptCtx) {
-            const blob = await encryptString(encryptCtx.key, JSON.stringify(mermaidJson));
-            fs.writeFileSync(path.join(targetMaterial, 'mermaid.json.enc'), JSON.stringify(blob));
-        }
-        else {
-            fs.writeFileSync(path.join(targetMaterial, 'mermaid.json'), JSON.stringify(mermaidJson));
+        for (const [file, svgs] of mermaid.perFile) {
+            if (Object.keys(svgs).length === 0)
+                continue;
+            const jsonRel = file.replace(/\.md$/, '.mermaid.json');
+            const outPath = encryptCtx
+                ? path.join(targetMaterial, `${jsonRel}.enc`)
+                : path.join(targetMaterial, jsonRel);
+            fs.mkdirSync(path.dirname(outPath), { recursive: true });
+            const payload = JSON.stringify(svgs);
+            if (encryptCtx) {
+                const blob = await encryptString(encryptCtx.key, payload);
+                fs.writeFileSync(outPath, JSON.stringify(blob));
+            }
+            else {
+                fs.writeFileSync(outPath, payload);
+            }
         }
         if (mermaid.css) {
             fs.writeFileSync(path.join(targetMaterial, 'mermaid.css'), mermaid.css);
@@ -177,6 +191,7 @@ export async function publishBuildAction(opts = {}) {
                 title: card.title,
                 type: card.type,
                 tags: card.tags,
+                indexInMaterial: card.indexInMaterial,
             });
             for (const tag of card.tags) {
                 if (!tagIndex[tag])

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

@@ -43,20 +43,30 @@ function extractSources(md) {
 }
 /** Empty result — used when no diagrams found or mermaid pass disabled. */
 export function emptyMermaidPass() {
-    return { svgs: {}, css: '', count: 0, errored: 0 };
+    return { perFile: new Map(), css: '', count: 0, errored: 0 };
 }
 /**
- * Scan all provided material bodies for ```mermaid fences and pre-render
- * each unique diagram twice (dark + light). Returns a lookup map + the
- * associated CSS. Returns an empty result when no diagrams are found.
+ * Scan every provided material body for ```mermaid fences and pre-render
+ * each unique diagram twice (dark + light). Rendering is deduped
+ * globally (a diagram appearing in three materials is drawn once);
+ * emission is per-material (the same SVG bytes may be copied into
+ * three per-file maps). Returns an empty result when no diagrams are
+ * found.
  */
-export async function prerenderMermaid(materialBodies) {
+export async function prerenderMermaid(inputs) {
+    // Collect (file, key) → source. `uniqueSources` dedupes for the
+    // renderer; `perFileSources` remembers which files each diagram
+    // belongs to so we can copy the SVG into every shard that needs it.
     const uniqueSources = new Map();
-    for (const body of materialBodies) {
+    const perFileSources = new Map();
+    for (const { file, body } of inputs) {
         for (const src of extractSources(body)) {
             const key = mermaidSvgKey(src);
             if (!uniqueSources.has(key))
                 uniqueSources.set(key, src);
+            const set = perFileSources.get(file) ?? new Set();
+            set.add(key);
+            perFileSources.set(file, set);
         }
     }
     if (uniqueSources.size === 0)
@@ -64,7 +74,7 @@ export async function prerenderMermaid(materialBodies) {
     info(t('publish.build.msg.mermaidStart', { count: uniqueSources.size }));
     const renderer = new MermaidRenderer();
     await renderer.init();
-    const svgs = {};
+    const renderedByKey = {};
     const cssChunks = [];
     let errored = 0;
     try {
@@ -72,7 +82,7 @@ export async function prerenderMermaid(materialBodies) {
             const r = await renderer.render(source);
             if (r.errored)
                 errored++;
-            svgs[key] = { dark: r.svgDark, light: r.svgLight };
+            renderedByKey[key] = { dark: r.svgDark, light: r.svgLight };
             if (r.cssDark)
                 cssChunks.push(r.cssDark);
             if (r.cssLight)
@@ -82,10 +92,20 @@ export async function prerenderMermaid(materialBodies) {
     finally {
         await renderer.close();
     }
+    const perFile = new Map();
+    for (const [file, keys] of perFileSources) {
+        const map = {};
+        for (const k of keys) {
+            const svg = renderedByKey[k];
+            if (svg)
+                map[k] = svg;
+        }
+        perFile.set(file, map);
+    }
     if (errored > 0)
         warn(t('publish.build.msg.mermaidErrored', { count: errored }));
     return {
-        svgs,
+        perFile,
         css: cssChunks.join('\n'),
         count: uniqueSources.size,
         errored,

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

@@ -74,7 +74,7 @@ export async function repoSyncAction(opts) {
         description: t('repo.sync.tpl.defaultDescription'),
         date: today,
     };
-    const plan = buildSyncPlan();
+    const plan = filterOutSampleSeedsIfUserContent(root, buildSyncPlan());
     const toCreate = [];
     const toOverwrite = [];
     const skipped = [];
@@ -220,3 +220,64 @@ function writeItem(root, item, templatesDir, vars) {
         fs.writeFileSync(fullPath, '');
     }
 }
+/**
+ * Six sample material files (`material/<type>.md` + their `assets/<type>/*.svg`
+ * companions) exist to bootstrap a brand-new repo — every card type gets a
+ * copy-and-edit starter. On an established repo (`qtype init --force` after
+ * writing real content), re-seeding them is pure noise: the user has to
+ * manually delete six files every time they run sync.
+ *
+ * Detection heuristic: if `material/` already holds any `.md` whose base
+ * name is not one of the six sample types, the user has real content.
+ * Skip both the starter `.md` seeds and their asset seeds; keep everything
+ * else in the plan.
+ *
+ * The first-time init flow is unaffected — an empty (or missing) `material/`
+ * still gets the full sample seed.
+ */
+const SAMPLE_TYPES = new Set(['word', 'sentence', 'article', 'snippet', 'qa', 'code']);
+function isSampleSeed(target) {
+    // `material/<type>.md` or `material/assets/<type>/*.svg`
+    const md = /^material\/([^/]+)\.md$/.exec(target);
+    if (md && SAMPLE_TYPES.has(md[1]))
+        return true;
+    const asset = /^material\/assets\/([^/]+)\//.exec(target);
+    if (asset && SAMPLE_TYPES.has(asset[1]))
+        return true;
+    return false;
+}
+function hasUserContent(materialDir) {
+    if (!fs.existsSync(materialDir))
+        return false;
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === 'assets' && entry.isDirectory())
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (walk(full))
+                    return true;
+                continue;
+            }
+            if (!entry.name.endsWith('.md'))
+                continue;
+            // A sample seed at the top level (`material/qa.md`) doesn't count.
+            // Anything else — deeper paths or top-level files with non-sample
+            // names — is user-authored content.
+            const rel = path.relative(materialDir, full);
+            const topLevel = rel.split(path.sep).length === 1;
+            const base = entry.name.replace(/\.md$/, '');
+            if (topLevel && SAMPLE_TYPES.has(base))
+                continue;
+            return true;
+        }
+        return false;
+    };
+    return walk(materialDir);
+}
+function filterOutSampleSeedsIfUserContent(root, plan) {
+    const materialDir = path.join(root, 'material');
+    if (!hasUserContent(materialDir))
+        return plan;
+    return plan.filter((item) => !isSampleSeed(item.target));
+}

package/dist/cli/utils/prompt.js

@@ -46,8 +46,10 @@ export function promptPassword(prompt) {
         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 === '') {
+                // the byte fall into the password buffer. Escape sequence used
+                // instead of the literal 0x03 byte so a stray copy-paste through a
+                // terminal / chat app can't silently drop the control character.
+                if (ch === '\x03') {
                     if (isTty && typeof stdin.setRawMode === 'function')
                         stdin.setRawMode(false);
                     stdin.pause();
@@ -60,7 +62,9 @@ export function promptPassword(prompt) {
                     finish(data);
                     return;
                 }
-                if (ch === '' || ch === '\b') {
+                // Backspace: modern macOS/Linux terminals send DEL (0x7f); older
+                // ones and some Windows shells send BS (0x08). Handle both.
+                if (ch === '\x7f' || ch === '\b') {
                     data = data.slice(0, -1);
                     continue;
                 }

package/dist/core/cardId.js

@@ -0,0 +1,101 @@
+/**
+ * Content-derived card id.
+ *
+ * Historically qtype used `<file>#<indexInMaterial>` as the card id. That
+ * value doubled as a stable "identity" (for done tracking, filter hit
+ * lists, deep links) while also being the physical position pointer —
+ * so any time the author inserted / removed / reordered a card, every
+ * downstream id in that material shifted, silently invalidating every
+ * saved reference.
+ *
+ * The new id is a SHA-256 prefix over the card's content-defining
+ * fields:
+ *
+ *   materialFile + '\n' + title + '\n' + answer + '\n' + question
+ *
+ * — trimmed to 12 hex chars (48 bits, ~2^24 birthday collision boundary,
+ * plenty for a single repo). This makes the id:
+ *   • Reorder-safe (position doesn't feed the hash).
+ *   • Human-copy-friendly (short enough to paste in URLs).
+ *   • Content-change-sensitive (a real edit produces a new id, which is
+ *     the honest behaviour — the reader treats the pre-edit and post-edit
+ *     forms as distinct cards).
+ *
+ * We ship a small sync SHA-256 rather than pulling in `crypto.subtle`
+ * (async, needs to be awaited at parse time) — the payload is tiny and
+ * the parser stays synchronous.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+const HEX = '0123456789abcdef';
+function toHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        out += HEX[b >>> 4] + HEX[b & 0x0f];
+    }
+    return out;
+}
+/** Content hash prefix length in hex chars. 12 hex = 48 bits. */
+export const CARD_ID_LEN = 12;
+export function computeCardId(input) {
+    const src = [
+        input.materialFile,
+        input.title,
+        input.answer,
+        input.question ?? '',
+    ].join('\n');
+    const bytes = sha256(new TextEncoder().encode(src));
+    return toHex(bytes).slice(0, CARD_ID_LEN);
+}
+// ─── URL slug encoding ────────────────────────────────────────────
+//
+// URL shape:
+//   /typing/<material-path>/<idx>-<cardId>
+//
+//   /typing/qa/algorithms/25-f849bcc10faf
+//   /typing/code/algo/array/cpp/3-abc123def456
+//
+// The material path echoes the source `material/*.md` tree with the
+// `.md` extension stripped. `idx` is the card's 0-based position in
+// its material; `cardId` is a 12-hex content hash used as a
+// verification code — if the URL's `idx` no longer points at the
+// card whose content produced `cardId`, the typing route quietly
+// redirects to the current position.
+//
+// Splitting on the LAST dash is deliberate: material names may
+// legitimately contain dashes (`en/idioms-day1`), so a "split on
+// any dash" scheme would misinterpret them. Idx + cardId sit at the
+// end; the material path is whatever comes before the last `/`.
+/**
+ * Build the `/typing/...` splat portion (i.e. everything after
+ * `/typing/`). Does NOT `.md`-strip or url-encode — callers pass
+ * `materialFile` without the extension.
+ */
+export function formatCardSlug(materialFile, indexInMaterial, cardId) {
+    const stem = materialFile.replace(/\.md$/, '');
+    return `${stem}/${indexInMaterial}-${cardId}`;
+}
+export function parseCardSlug(slug) {
+    const lastSlash = slug.lastIndexOf('/');
+    if (lastSlash < 0)
+        return null;
+    const stem = slug.slice(0, lastSlash);
+    const tail = slug.slice(lastSlash + 1);
+    const lastDash = tail.lastIndexOf('-');
+    if (lastDash < 0)
+        return null;
+    const idxStr = tail.slice(0, lastDash);
+    const cardId = tail.slice(lastDash + 1);
+    const idx = parseInt(idxStr, 10);
+    if (!Number.isFinite(idx) || idx < 0)
+        return null;
+    if (!/^[0-9a-f]{12}$/.test(cardId))
+        return null;
+    if (!stem)
+        return null;
+    return {
+        materialFile: `${stem}.md`,
+        indexInMaterial: idx,
+        cardId,
+    };
+}

package/dist/core/index.js

@@ -7,3 +7,4 @@ export * from './typing/index.js';
 export { charToKeystrokes, textToCharPlans } from './keystroke/index.js';
 export { normalizeText, validateTypingText } from './keystroke/textNormalize.js';
 export * from './encrypt.js';
+export { computeCardId, CARD_ID_LEN, formatCardSlug, parseCardSlug, } from './cardId.js';

package/dist/core/parser/frontmatter.js

@@ -10,9 +10,8 @@ const FM_RE = /^---\n([\s\S]*?)\n---\n?/;
  *   updated: YYYY-MM-DD
  *   ---
  *
- * Card-level frontmatter no longer exists — everything a card carries
- * is expressed by its markdown structure (see parseMaterial for the
- * per-type rules).
+ * `type` and `tags` here are *defaults* — cards can override via
+ * their own `parseCardFrontmatter` block (see above).
  */
 export function parseMaterialFrontmatter(source) {
     const meta = {};