@qnroa/qtype 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -13,6 +13,72 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.0.9] — 2026-08-27
+
+View-only. No dist change, no need to rebuild — refreshing the page
+on an existing deployment is enough.
+
+### Changed
+- **Grid ↔ list view toggle is now the outermost switch, orthogonal
+  to filtering.** Previously any active tag/type filter forced the
+  home page into a list layout, ignoring the user's chosen view
+  mode. Now grid stays grid, list stays list — the filter changes
+  *what* is listed (materials vs. matching cards), not *how*.
+
+### Added
+- **`CardHitCard`** — grid tile for a card hit, sibling of
+  `MaterialCard`. Kept alongside the existing `CardHitRow` so the
+  new 2×2 (grid/list × material/card) matrix has one component per
+  cell.
+- **`EntryCard` / `EntryRow` base components.** The reusable shell
+  (click / keyboard routing, selection checkbox, done stamp,
+  hover / focus states, header + actions slots) is now factored
+  out so specializations only own their body content. Same
+  `.qt-deckcard*` / `.qt-deckrow*` selectors, no visual change.
+- **`RowTags` helper.** The responsive tag-chip truncation logic
+  from `MaterialRow` moved into a shared component and is now used
+  by `CardHitRow` too.
+
+### Internal
+- No public API changes to `MaterialRepository` or build outputs.
+- Card-level filter view now shows a `done` stamp per card
+  (backed by `useDoneState.isCardDone`).
+
+## [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

package/CHANGELOG.zh.md

@@ -12,6 +12,60 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.0.9] — 2026-08-27
+
+只改 view,dist 未变,老部署刷新页面即可,无需重跑 build。
+
+### 变更
+- **grid ↔ list 视图切换现在是最外层开关,和筛选正交**。之前只要
+  勾了 tag/type,不管用户当前选的是 grid 还是 list,都强制变成 list;
+  现在 grid 保持 grid,list 保持 list,筛选只决定"列的是什么"
+  (材料还是命中卡),不决定"怎么呈现"。
+
+### 新增
+- **`CardHitCard`** — 命中卡的 grid 版本,和 `MaterialCard` 是兄弟。
+  与已有的 `CardHitRow` 一起,凑齐新的 2×2 (grid/list × 材料/卡)
+  组合,每格一个组件。
+- **`EntryCard` / `EntryRow` 基类**。可复用的容器逻辑(点击/键盘
+  路由、选中框、done stamp、hover/focus 态、header + actions 槽)
+  抽成基类,特化组件只负责自己的 body。`.qt-deckcard*` / `.qt-deckrow*`
+  样式选择器不变,视觉零变化。
+- **`RowTags` helper**。之前写死在 `MaterialRow` 里的响应式 tag
+  chip 截断逻辑抽成独立组件,现在 `CardHitRow` 也能复用。
+
+### 内部
+- `MaterialRepository` 公共接口和 build 产物未变。
+- 命中卡列表 grid/list 都开始显示卡级 done stamp
+ (由 `useDoneState.isCardDone` 提供)。
+
+## [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
 
 完全向后兼容:老仓库解析不变。新能力是可选的 —— 只在卡片和材料

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';
@@ -77,23 +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,
-            cardCount: m.cardCount,
+            cardCount: parsed.cards.length,
         });
     }
     // Mermaid SVG map + CSS: the view fetches these alongside index.json and
@@ -119,22 +156,20 @@ export async function publishBuildAction(opts = {}) {
     if (fs.existsSync(srcAssets)) {
         copyDir(srcAssets, path.join(targetMaterial, 'assets'));
     }
-    // Card-pool index — parse every material once so the view can
-    // filter across files by card-level type/tags without fetching each
-    // md. Cards keep their full effective (material + card fm merged)
-    // metadata; body content is NOT duplicated here (still fetched
-    // on-demand from the .md file).
+    // 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) {
-        let parsed;
-        try {
-            parsed = parseMaterial(m.body, m.name);
-        }
-        catch {
+        const parsed = parsedByFile.get(m.name);
+        if (!parsed)
             continue;
-        }
         for (const card of parsed.cards) {
             cardIndex.push({
                 id: card.id,
@@ -146,15 +181,13 @@ export async function publishBuildAction(opts = {}) {
             for (const tag of card.tags) {
                 if (!tagIndex[tag])
                     tagIndex[tag] = [];
-                if (!tagIndex[tag].includes(m.name))
-                    tagIndex[tag].push(m.name);
+                tagIndex[tag].push(card.id);
             }
-            const t = card.type || '';
-            if (t) {
-                if (!typeIndex[t])
-                    typeIndex[t] = [];
-                if (!typeIndex[t].includes(m.name))
-                    typeIndex[t].push(m.name);
+            const ct = card.type || '';
+            if (ct) {
+                if (!typeIndex[ct])
+                    typeIndex[ct] = [];
+                typeIndex[ct].push(card.id);
             }
         }
     }
@@ -182,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'));
@@ -312,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/view/assets/{index-DNcGZhd7.js → index-B29a4MHP.js}

@@ -1,3 +1,3 @@
-const __vite__mapDeps=(i,m=__vite__mapDeps,d=(m.f||(m.f=["assets/index-BM7BgXjn.js","assets/index-C1KzsLUa.js","assets/index-BLryk3W4.css"])))=>i.map(i=>d[i]);
-import{r as l,_ as h,u as g,j as f,C as p,M as m,T as y,a as w}from"./index-C1KzsLUa.js";let o=null,c=null;async function L(){return o||c||(c=h(()=>import("./index-BM7BgXjn.js"),__vite__mapDeps([0,1,2])).then(async e=>(o=await e.createHighlighter({themes:["github-dark","github-light"],langs:[]}),o)),c)}async function _(e,t){if(!e.getLoadedLanguages().includes(t))try{await e.loadLanguage(t)}catch{}}function x(e){const[t,n]=l.useState(o);return l.useEffect(()=>{if(!e)return;let r=!1;return(async()=>{const s=await L();await _(s,e),r||n(s)})(),()=>{r=!0}},[e]),t}const A=/```(\w+)/;function E(e){const t=e.toLowerCase();return t.includes("typescript")||t.endsWith(".ts")?"typescript":t.includes("python")||t.endsWith(".py")?"python":t.includes("cpp")||t.includes("c++")?"cpp":t.includes("java")&&!t.includes("script")?"java":t.includes("go")?"go":t.includes("rust")||t.endsWith(".rs")?"rust":t.includes("code-c")||t.endsWith(".c")?"c":"javascript"}function j(e,t){if(e){const n=e.match(A);if(n)return n[1]}return E(t)}function k(e,t,n,r){if(!r||!r.getLoadedLanguages().includes(t))return new Array(Array.from(e).length).fill(null);try{const s=r.codeToTokens(e,{lang:t,theme:n}),i=[];for(const u of s.tokens){for(const a of u)for(const d of a.content)i.push(a.color??null);i.push(null)}return!e.endsWith(`
+const __vite__mapDeps=(i,m=__vite__mapDeps,d=(m.f||(m.f=["assets/index-Due6dVBA.js","assets/index-D2236cNR.js","assets/index-DI1_zxwA.css"])))=>i.map(i=>d[i]);
+import{r as l,_ as h,u as g,j as f,C as p,M as m,T as y,a as w}from"./index-D2236cNR.js";let o=null,c=null;async function L(){return o||c||(c=h(()=>import("./index-Due6dVBA.js"),__vite__mapDeps([0,1,2])).then(async e=>(o=await e.createHighlighter({themes:["github-dark","github-light"],langs:[]}),o)),c)}async function _(e,t){if(!e.getLoadedLanguages().includes(t))try{await e.loadLanguage(t)}catch{}}function x(e){const[t,n]=l.useState(o);return l.useEffect(()=>{if(!e)return;let r=!1;return(async()=>{const s=await L();await _(s,e),r||n(s)})(),()=>{r=!0}},[e]),t}const A=/```(\w+)/;function E(e){const t=e.toLowerCase();return t.includes("typescript")||t.endsWith(".ts")?"typescript":t.includes("python")||t.endsWith(".py")?"python":t.includes("cpp")||t.includes("c++")?"cpp":t.includes("java")&&!t.includes("script")?"java":t.includes("go")?"go":t.includes("rust")||t.endsWith(".rs")?"rust":t.includes("code-c")||t.endsWith(".c")?"c":"javascript"}function j(e,t){if(e){const n=e.match(A);if(n)return n[1]}return E(t)}function k(e,t,n,r){if(!r||!r.getLoadedLanguages().includes(t))return new Array(Array.from(e).length).fill(null);try{const s=r.codeToTokens(e,{lang:t,theme:n}),i=[];for(const u of s.tokens){for(const a of u)for(const d of a.content)i.push(a.color??null);i.push(null)}return!e.endsWith(`
 `)&&i.length>Array.from(e).length&&i.pop(),i}catch{return new Array(Array.from(e).length).fill(null)}}function v(e){var d;const{material:t,card:n}=e,[r]=g(),s=l.useMemo(()=>r?j(n.question,t.filePath):"",[n.question,t.filePath,r]),i=typeof document<"u"&&((d=document.documentElement.getAttribute("data-theme"))!=null&&d.includes("latte"))?"github-light":"github-dark",u=x(r?s:""),a=l.useMemo(()=>r?k(n.answer,s,i,u):void 0,[n.answer,s,i,u,r]);return f.jsx(p,{type:"code",variant:"flow",slots:[{role:"title",content:n.title},n.question?{role:"question",content:f.jsx(m,{source:n.question})}:{role:"question",content:null},{role:"arena",content:f.jsx(y,{...w(e),charColors:a},n.id)}]})}export{v as CodeCard};