@qnroa/qtype 0.0.2 → 0.0.4

package/dist/cli/commands/check/index.js

@@ -1,20 +1,21 @@
 import { t } from '../../i18n/index.js';
-import { messages } from './i18n.js';
-import { checkAction } from './action.js';
+import { messages as lintMessages } from '../content/lint/i18n.js';
+import { contentLintAction } from '../content/lint/action.js';
 export const checkCmd = {
     name: 'check',
-    messages,
-    summary: () => t('check.summary'),
-    describe: () => t('check.description'),
+    messages: lintMessages,
+    summary: () => t('content.lint.summary'),
+    describe: () => t('content.lint.description'),
     options: [
-        { flags: '--repo <path>', describe: () => t('check.opt.repo') },
+        { flags: '--repo <path>', describe: () => t('content.lint.arg.path') },
+        { flags: '--json', describe: () => t('content.lint.opt.json') },
     ],
     examples: () => [
-        { command: 'qtype check', describe: () => t('check.example.basic') },
-        { command: 'qtype check --repo ./my-material', describe: () => t('check.example.repo') },
+        { command: 'qtype check', describe: () => t('content.lint.example.basic') },
+        { command: 'qtype check --json', describe: () => t('content.lint.example.json') },
     ],
-    seeAlso: ['publish build', 'content lint'],
+    seeAlso: ['content lint', 'content validate', 'publish build'],
     action: async (opts) => {
-        await checkAction({ repo: opts.repo });
+        await contentLintAction({ path: opts.repo, json: opts.json });
     },
 };

package/dist/cli/commands/config/action.js

@@ -1,6 +1,6 @@
 import { KvError } from '../../../store/index.js';
 import { userKv, repoKv } from '../../bootstrap.js';
-import { info, success, dim, error } from '../../utils/output.js';
+import { info, success, dim, error, fatal } from '../../utils/output.js';
 import { t } from '../../i18n/index.js';
 /** --global / --local are mutually exclusive; returns the explicitly-specified scope (neither given → undefined). */
 function pickScope(opts) {
@@ -61,8 +61,7 @@ export async function configGetAction(key, opts) {
         if (!has) {
             const def = kv.getSchema(key)?.default;
             if (def === undefined) {
-                error(t('config.get.msg.notSetScoped', { key, scope }));
-                process.exit(1);
+                fatal(t('config.get.msg.notSetScoped', { key, scope }));
             }
             console.log(formatValue(def));
             return;
@@ -85,8 +84,7 @@ export async function configGetAction(key, opts) {
     // Fall back to default: repo schema first, then user
     const def = repoKv.getSchema(key)?.default ?? userKv.getSchema(key)?.default;
     if (def === undefined) {
-        error(t('config.get.msg.notSet', { key }));
-        process.exit(1);
+        fatal(t('config.get.msg.notSet', { key }));
     }
     console.log(formatValue(def));
 }
@@ -95,8 +93,7 @@ async function showOrigin(key, scope) {
     const inUser = await userKv.has(key);
     if (scope === 'user') {
         if (!inUser) {
-            error(t('config.get.msg.notSetScoped', { key, scope: 'user' }));
-            process.exit(1);
+            fatal(t('config.get.msg.notSetScoped', { key, scope: 'user' }));
         }
         console.log(formatValue(await userKv.get(key)));
         console.error(`  ${dim('from:')} ${userKv.origin} (user)`);
@@ -104,8 +101,7 @@ async function showOrigin(key, scope) {
     }
     if (scope === 'repo') {
         if (!inRepo) {
-            error(t('config.get.msg.notSetScoped', { key, scope: 'repo' }));
-            process.exit(1);
+            fatal(t('config.get.msg.notSetScoped', { key, scope: 'repo' }));
         }
         console.log(formatValue(await repoKv.get(key)));
         console.error(`  ${dim('from:')} ${repoKv.origin} (repo)`);

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

@@ -6,67 +6,61 @@
  *   - Each file parses to at least one Q/A card (error)
  *   - No card contains characters unmapped in the keystroke plan (error)
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, success, error, warn } from '../../../utils/output.js';
 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';
 const TITLE_RE = /^title:\s*(.+)$/m;
 const HEADING_RE = /^#\s+.+$/m;
 export async function contentLintAction(opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     if (!opts.json)
         info(t('content.lint.msg.scanning', { path: root }));
     const issues = [];
     let cardTotal = 0;
     let materialCount = 0;
-    if (fs.existsSync(materialDir)) {
-        for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
-                continue;
-            materialCount++;
-            const rel = path.posix.join('material', name);
-            const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
-            // File-level title (soft): warn if neither frontmatter title nor
-            // a top-level heading is present — the browser view has nothing to
-            // show as the material's name.
-            const head = src.slice(0, 2048);
-            if (!TITLE_RE.test(head) && !HEADING_RE.test(head)) {
-                issues.push({
-                    code: 'material.emptyTitle',
-                    path: rel,
-                    message: t('content.lint.issue.emptyTitle', { path: rel }),
-                });
-            }
-            const material = parseMaterial(src, rel);
-            cardTotal += material.cards.length;
-            if (material.cards.length === 0) {
+    for (const file of walkMaterial(root)) {
+        materialCount++;
+        const rel = `${MATERIAL_DIR}/${file.rel}`;
+        const src = readMaterial(file);
+        // File-level title (soft): warn if neither frontmatter title nor
+        // a top-level heading is present — the browser view has nothing to
+        // show as the material's name.
+        const head = src.slice(0, 2048);
+        if (!TITLE_RE.test(head) && !HEADING_RE.test(head)) {
+            issues.push({
+                code: 'material.emptyTitle',
+                path: rel,
+                message: t('content.lint.issue.emptyTitle', { path: rel }),
+            });
+        }
+        const material = parseMaterial(src, rel);
+        cardTotal += material.cards.length;
+        if (material.cards.length === 0) {
+            issues.push({
+                code: 'material.noCards',
+                path: rel,
+                message: t('content.lint.issue.noCards', { path: rel }),
+            });
+            continue;
+        }
+        material.cards.forEach((c, i) => {
+            if (c.unknownChars.length > 0) {
+                const chars = [...new Set(c.unknownChars)];
                 issues.push({
-                    code: 'material.noCards',
+                    code: 'material.unknownChars',
                     path: rel,
-                    message: t('content.lint.issue.noCards', { path: rel }),
-                });
-                continue;
-            }
-            material.cards.forEach((c, i) => {
-                if (c.unknownChars.length > 0) {
-                    const chars = [...new Set(c.unknownChars)];
-                    issues.push({
-                        code: 'material.unknownChars',
+                    card: i + 1,
+                    chars,
+                    message: t('content.lint.issue.unknownChars', {
                         path: rel,
                         card: i + 1,
-                        chars,
-                        message: t('content.lint.issue.unknownChars', {
-                            path: rel,
-                            card: i + 1,
-                            chars: chars.join(' '),
-                        }),
-                    });
-                }
-            });
-        }
+                        chars: chars.join(' '),
+                    }),
+                });
+            }
+        });
     }
     // `emptyTitle` is treated as a warning (informational). Anything else is an error.
     const errorIssues = issues.filter((i) => i.code !== 'material.emptyTitle');

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

@@ -1,56 +1,66 @@
 /**
  * `qtype content search <query>` action — grep-style search over material/*.md.
  *
- * Simple case-insensitive substring match on card questions + answers. Not
- * ranked — just returns first-N hits so a user can pipe grep-style output
- * into vim/less. Deliberately dumb: fits the "types of cards, not a knowledge
- * graph" scope of qtype.
+ * Simple case-insensitive substring match on card questions + answers,
+ * with optional tag / type / limit filters and a --json output mode for
+ * scripting. Not ranked — just returns first-N hits, insertion order.
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, dim } from '../../../utils/output.js';
 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';
 export async function contentSearchAction(query, opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     const limit = opts.limit ?? 20;
+    const tagFilter = opts.tag?.map((t) => t.toLowerCase()) ?? [];
+    const typeFilter = opts.type?.map((t) => t.toLowerCase()) ?? [];
     const q = query.toLowerCase();
     const hits = [];
-    if (fs.existsSync(materialDir)) {
-        outer: for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
+    outer: for (const file of walkMaterial(root)) {
+        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 question = card.question ?? card.title;
+            const qLc = question.toLowerCase();
+            const aLc = card.answer.toLowerCase();
+            if (!qLc.includes(q) && !aLc.includes(q))
                 continue;
-            const rel = path.posix.join('material', name);
-            const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
-            const material = parseMaterial(src, rel);
-            material.cards.forEach((card, i) => {
-                const qLc = card.question.toLowerCase();
-                const aLc = card.answer.toLowerCase();
-                if (!qLc.includes(q) && !aLc.includes(q))
-                    return;
-                const snippetSrc = qLc.includes(q) ? card.question : card.answer;
-                const idx = snippetSrc.toLowerCase().indexOf(q);
-                const start = Math.max(0, idx - 20);
-                const end = Math.min(snippetSrc.length, idx + q.length + 40);
-                const snippet = (start > 0 ? '…' : '') +
-                    snippetSrc.slice(start, end).replace(/\n+/g, ' ') +
-                    (end < snippetSrc.length ? '…' : '');
-                hits.push({
-                    file: rel,
-                    card: i + 1,
-                    question: card.question,
-                    answer: card.answer,
-                    snippet,
-                });
-                if (hits.length >= limit)
-                    return;
+            const snippetSrc = qLc.includes(q) ? question : card.answer;
+            const idx = snippetSrc.toLowerCase().indexOf(q);
+            const start = Math.max(0, idx - 20);
+            const end = Math.min(snippetSrc.length, idx + q.length + 40);
+            const snippet = (start > 0 ? '…' : '') +
+                snippetSrc.slice(start, end).replace(/\n+/g, ' ') +
+                (end < snippetSrc.length ? '…' : '');
+            hits.push({
+                file: rel,
+                card: i + 1,
+                title: card.title,
+                question,
+                answer: card.answer,
+                snippet,
+                type: material.meta.type,
+                tags: material.meta.tags ?? [],
             });
             if (hits.length >= limit)
                 break outer;
         }
     }
+    if (opts.json) {
+        console.log(JSON.stringify({ query, count: hits.length, hits }, null, 2));
+        return;
+    }
     if (hits.length === 0) {
         info(t('content.search.msg.noResults'));
         return;

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

@@ -5,6 +5,9 @@ export const messages = {
         'content.search.arg.query': '搜索关键词',
         'content.search.arg.path': '仓库路径（默认当前目录）',
         'content.search.opt.limit': '最多返回结果数（默认 20）',
+        'content.search.opt.tag': '按 tag 过滤 material（可多次；需全部匹配）',
+        'content.search.opt.type': '按 material 类型过滤（可多次指定）',
+        'content.search.opt.json': '以 JSON 输出结果，便于脚本处理',
         'content.search.msg.noResults': '没有找到匹配的结果',
         'content.search.msg.results': '找到 {count} 个结果',
     },
@@ -14,6 +17,9 @@ export const messages = {
         'content.search.arg.query': 'Search query',
         'content.search.arg.path': 'Repo path (default: current directory)',
         'content.search.opt.limit': 'Max results (default: 20)',
+        'content.search.opt.tag': 'Filter by tag (repeatable; all must match)',
+        'content.search.opt.type': 'Filter by material type (repeatable)',
+        'content.search.opt.json': 'Emit results as JSON for scripting',
         'content.search.msg.noResults': 'No results found',
         'content.search.msg.results': 'Found {count} results',
     },

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

@@ -17,8 +17,26 @@ export const contentSearchCmd = {
             parser: (v) => parseInt(v, 10),
             defaultValue: 20,
         },
+        {
+            flags: '--tag <tag...>',
+            describe: () => t('content.search.opt.tag'),
+        },
+        {
+            flags: '--type <type...>',
+            describe: () => t('content.search.opt.type'),
+        },
+        {
+            flags: '--json',
+            describe: () => t('content.search.opt.json'),
+        },
     ],
     action: async (query, pathArg, opts) => {
-        await contentSearchAction(query, { path: pathArg, limit: opts.limit });
+        await contentSearchAction(query, {
+            path: pathArg,
+            limit: opts.limit,
+            tag: opts.tag,
+            type: opts.type,
+            json: opts.json,
+        });
     },
 };

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

@@ -11,49 +11,47 @@
  *   - Tag consistency: warns when the same tag is used with different
  *     casing (`react` vs `React`)
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, success, error, warn } from '../../../utils/output.js';
 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';
 export async function contentValidateAction(opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     if (!opts.json)
         info(t('content.validate.msg.validating', { path: root }));
     const errors = [];
     const warnings = [];
     let cardTotal = 0;
-    const files = [];
+    const materials = walkMaterial(root);
     // ── Filename uniqueness (case-insensitive) ──────────────
-    if (fs.existsSync(materialDir)) {
+    // Compares by the full relative path — a file at en/a.md and one
+    // at zh/a.md are NOT a collision (different folders), whereas
+    // a.md and A.md at the same level are.
+    {
         const seen = new Map();
-        for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
-                continue;
-            files.push(name);
-            const key = name.toLowerCase();
+        for (const file of materials) {
+            const key = file.rel.toLowerCase();
             const prior = seen.get(key);
-            if (prior && prior !== name) {
+            if (prior && prior !== file.rel) {
                 errors.push({
                     code: 'duplicate.file',
-                    path: name,
-                    message: t('content.validate.err.duplicateFile', { file: name }),
+                    path: file.rel,
+                    message: t('content.validate.err.duplicateFile', { file: file.rel }),
                     extra: { collidesWith: prior },
                 });
             }
             else {
-                seen.set(key, name);
+                seen.set(key, file.rel);
             }
         }
     }
     // ── Parse every material, then run cross-file checks ────
     const questionIndex = new Map(); // normalized Q → "path#card"
     const tagVariants = new Map(); // lower → { original casings }
-    for (const name of files) {
-        const rel = path.posix.join('material', name);
-        const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
+    for (const file of materials) {
+        const rel = `${MATERIAL_DIR}/${file.rel}`;
+        const src = readMaterial(file);
         const material = parseMaterial(src, rel);
         cardTotal += material.cards.length;
         material.cards.forEach((card, i) => {
@@ -72,8 +70,9 @@ export async function contentValidateAction(opts = {}) {
                     extra: { chars },
                 });
             }
-            // Duplicate card questions across the corpus.
-            const key = card.question.trim().toLowerCase();
+            // Duplicate card titles across the corpus (title stands in as the
+            // card identity — the H1 text uniquely names each card).
+            const key = card.title.trim().toLowerCase();
             if (key.length > 0) {
                 const prior = questionIndex.get(key);
                 const here = `${rel}#${cardIdx}`;
@@ -93,14 +92,16 @@ export async function contentValidateAction(opts = {}) {
                     questionIndex.set(key, here);
                 }
             }
-            // Tag casing consistency.
-            for (const tag of card.meta.tags) {
-                const lower = tag.toLowerCase();
-                const set = tagVariants.get(lower) ?? new Set();
-                set.add(tag);
-                tagVariants.set(lower, set);
-            }
+            // Card-level tag consistency was removed with the frontmatter
+            // simplification — only material-level tags exist now, handled below.
         });
+        // 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) {
@@ -116,7 +117,7 @@ export async function contentValidateAction(opts = {}) {
     }
     const result = {
         ok: errors.length === 0,
-        stats: { materials: files.length, cards: cardTotal, warnings: warnings.length },
+        stats: { materials: materials.length, cards: cardTotal, warnings: warnings.length },
         errors,
         warnings,
     };

package/dist/cli/commands/index.js

@@ -4,7 +4,6 @@ import { publishCmd } from './publish/index.js';
 import { checkCmd } from './check/index.js';
 import { contentCmd } from './content/index.js';
 import { configCmd } from './config/index.js';
-import { pluginCmd } from './plugin/index.js';
 import { packCmd } from './pack/index.js';
 export const allCommands = [
     initCmd,
@@ -13,7 +12,6 @@ export const allCommands = [
     checkCmd,
     contentCmd,
     packCmd,
-    pluginCmd,
     configCmd,
 ];
-export { initCmd, repoCmd, publishCmd, checkCmd, contentCmd, packCmd, pluginCmd, configCmd, };
+export { initCmd, repoCmd, publishCmd, checkCmd, contentCmd, packCmd, configCmd, };

package/dist/cli/commands/pack/index.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { t } from '../../i18n/index.js';
 import { error, info, success } from '../../utils/output.js';
+import { MATERIAL_DIR } from '../../utils/material.js';
 import { messages } from './i18n.js';
 const IGNORE = new Set(['dist', 'node_modules', '.git']);
 export const packCmd = {
@@ -21,7 +22,7 @@ export const packCmd = {
     ],
     action: async (opts) => {
         const cwd = process.cwd();
-        if (!fs.existsSync(path.join(cwd, 'material'))) {
+        if (!fs.existsSync(path.join(cwd, MATERIAL_DIR))) {
             error(t('pack.err.noMaterial'));
             process.exitCode = 1;
             return;

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

@@ -20,11 +20,13 @@ 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 { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function publishBuildAction(opts = {}) {
     const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
     const outDir = path.resolve(cwd, opts.out ?? 'dist');
     const viewBundle = resolveBundle('dist/view');
-    const materialDir = path.join(cwd, 'material');
+    const materialDir = path.join(cwd, MATERIAL_DIR);
     info(t('publish.build.msg.parsing', { path: cwd }));
     if (!fs.existsSync(viewBundle) ||
         !fs.existsSync(path.join(viewBundle, 'index.html'))) {
@@ -40,13 +42,20 @@ export async function publishBuildAction(opts = {}) {
     const encryptCtx = await resolveEncryptCtx(cwd);
     const mermaidMode = await resolveMermaidMode(cwd);
     const repoLang = await resolveRepoLang(cwd);
+    // Wiki display name: repo.name from config wins over the directory
+    // basename, so users can `qtype config set repo.name "..."` to
+    // override how the site labels itself in the browser tab.
+    const name = await resolveRepoName(cwd);
     const materials = [];
-    for (const name of fs.readdirSync(materialDir)) {
-        if (!name.endsWith('.md'))
-            continue;
-        const body = fs.readFileSync(path.join(materialDir, name), 'utf8');
-        const title = readTitle(body) ?? name.replace(/\.md$/, '');
-        materials.push({ name, body, title });
+    for (const file of walkMaterial(cwd)) {
+        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 });
     }
     // Mermaid pre-render — scan all bodies, produce svg + css maps.
     const mermaid = mermaidMode === 'prerender'
@@ -59,23 +68,38 @@ export async function publishBuildAction(opts = {}) {
     fs.rmSync(outDir, { recursive: true, force: true });
     fs.mkdirSync(outDir, { recursive: true });
     copyDir(viewBundle, outDir);
+    // Rewrite dist/index.html to carry the site's name — both in the
+    // <title> (browser tab) and as a `data-qtype-repo-name` attribute on
+    // <html> (read by the view's `readBootConfig()` for the header
+    // brand label and anywhere else the repo name is shown).
+    rewriteIndexHtml(path.join(outDir, 'index.html'), name);
     // Defensive: clear any stale material/ that might have snuck into the
     // view bundle. Since dev-seed content lives at repo root's examples/
     // (served only by the vite dev middleware, not the bundle), this is a
     // no-op today — kept in case a future build tool ships anything here.
-    const targetMaterial = path.join(outDir, 'material');
+    const targetMaterial = path.join(outDir, MATERIAL_DIR);
     fs.rmSync(targetMaterial, { recursive: true, force: true });
     fs.mkdirSync(targetMaterial, { recursive: true });
     const entries = [];
     for (const m of materials) {
+        const outPath = encryptCtx
+            ? path.join(targetMaterial, `${m.name}.enc.json`)
+            : path.join(targetMaterial, m.name);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
         if (encryptCtx) {
             const blob = await encryptString(encryptCtx.key, m.body);
-            fs.writeFileSync(path.join(targetMaterial, `${m.name}.enc.json`), JSON.stringify(blob));
+            fs.writeFileSync(outPath, JSON.stringify(blob));
         }
         else {
-            fs.writeFileSync(path.join(targetMaterial, m.name), m.body);
+            fs.writeFileSync(outPath, m.body);
         }
-        entries.push({ file: m.name, title: m.title });
+        entries.push({
+            file: m.name,
+            title: m.title,
+            type: m.type,
+            tags: m.tags,
+            cardCount: m.cardCount,
+        });
     }
     // Mermaid SVG map + CSS: the view fetches these alongside index.json and
     // looks up each fence by its trimmed source when rendering material bodies.
@@ -92,6 +116,14 @@ export async function publishBuildAction(opts = {}) {
             fs.writeFileSync(path.join(targetMaterial, 'mermaid.css'), mermaid.css);
         }
     }
+    // Copy `material/assets/**` verbatim (images referenced by cards
+    // via `![](/material/assets/…)` need to actually resolve at the
+    // deployed URL). Assets are NOT encrypted — they're image bytes,
+    // and the encryption pass only wraps `.md` content anyway.
+    const srcAssets = path.join(cwd, MATERIAL_DIR, 'assets');
+    if (fs.existsSync(srcAssets)) {
+        copyDir(srcAssets, path.join(targetMaterial, 'assets'));
+    }
     // Manifest: lists materials + optional encryption envelope + mermaid mode.
     const manifest = { materials: entries };
     if (encryptCtx) {
@@ -171,6 +203,38 @@ async function resolveRepoLang(cwd) {
         return 'zh-CN';
     return 'en-US';
 }
+/**
+ * Repo display name: `repo.name` from `.qtype/config.json` wins over
+ * the directory basename, so users can override without renaming the
+ * folder. Same rule as qrism's `loadPublishConfig`.
+ */
+async function resolveRepoName(cwd) {
+    const kv = createRepoKv(cwd);
+    if (await kv.available()) {
+        const v = await kv.get('repo.name');
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return path.basename(cwd);
+}
+function rewriteIndexHtml(indexPath, name) {
+    if (!fs.existsSync(indexPath))
+        return;
+    const html = fs.readFileSync(indexPath, 'utf8');
+    const escaped = name
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    const withTitle = html.replace(/<title>[^<]*<\/title>/, `<title>${escaped}</title>`);
+    // Add or replace data-qtype-repo-name on the root <html> tag.
+    // Two branches so a re-run cleanly overwrites an existing attribute.
+    const rewritten = /<html\b[^>]*\bdata-qtype-repo-name=/.test(withTitle)
+        ? withTitle.replace(/(<html\b[^>]*\bdata-qtype-repo-name=)"[^"]*"/, `$1"${escaped}"`)
+        : withTitle.replace(/<html\b/, `<html data-qtype-repo-name="${escaped}"`);
+    if (rewritten !== html)
+        fs.writeFileSync(indexPath, rewritten);
+}
 async function obtainPassword() {
     const envPwd = process.env.QTYPE_PUBLISH_PASSWORD;
     if (envPwd)
@@ -196,6 +260,19 @@ function readTitle(source) {
     const m = head.match(/^title:\s*(.+)$/m);
     return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
 }
+/**
+ * Cheap card-count estimator — counts top-level `#` H1 lines in the
+ * body. Enough for the library's "N cards" chip without full markdown
+ * parse. Matches the parser's `splitByH1` semantics.
+ */
+function countH1(source) {
+    let n = 0;
+    for (const line of source.split('\n')) {
+        if (/^#\s+/.test(line))
+            n++;
+    }
+    return n;
+}
 function countCards(materialDir) {
     let n = 0;
     for (const name of fs.readdirSync(materialDir)) {