npm - @qnroa/qtype - Versions diffs - 0.0.3 → 0.0.5 - Mend

@qnroa/qtype 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/CHANGELOG.md +61 -0
package/CHANGELOG.zh.md +51 -0
package/dist/cli/commands/publish/build/action.js +49 -0
package/dist/cli/commands/publish/build/mermaidPrerender.js +30 -8
package/dist/view/assets/{index-CRh4USfC.js → index-1XXyxiQO.js} +28 -28
package/dist/view/assets/{index-ByMJp0a5.js → index-DIBSxFYl.js} +2 -2
package/dist/view/assets/{index-JNx7Ohoj.js → index-DgHvnMV9.js} +1 -1
package/dist/view/index.html +2 -2
package/docs/en/settings.md +2 -2
package/docs/zh/settings.md +2 -2
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -13,6 +13,67 @@ can land in any minor bump (`0.x.0`).
 ## [Unreleased]
+## [0.0.5] - 2026-08-22
+### Fixed
+- **Mermaid pre-render no longer fails under `npx` / hosted CI.**
+  `mermaidPrerender.init()` now uses `createRequire(import.meta.url).resolve('mermaid/…')`
+  to locate the mermaid ESM, so Node's own module resolver walks the
+  actual `node_modules` chain regardless of where qtype was installed
+  — user repo, npx cache, Cloudflare Pages build root, monorepo hoist.
+  The previous two hard-coded lookup paths remain as fallbacks but
+  are no longer the primary strategy. This fixes the
+  `mermaid ESM not found in node_modules` error on Cloudflare Pages
+  when a deck actually contains ` ```mermaid ` code blocks.
+- **`publish build` now copies `material/assets/**`** into
+  `dist/material/assets/` verbatim. Previously the CLI only walked
+  `.md` files, so any image the cards referenced via
+  `![](/material/assets/…)` returned 404 on the deployed site.
+## [0.0.4] - 2026-08-22
+### Added
+- **Site name in browser tab + header** — `qtype publish build` now
+  writes the site's name into `dist/index.html` (both the `<title>`
+  and a `data-qtype-repo-name` attribute on `<html>`). The view reads
+  it via `readBootConfig()` so the Header brand label reflects the
+  actual deck instead of a hardcoded "qtype". Precedence:
+  `repo.name` in `.qtype/config.json` wins, otherwise the repo
+  directory basename.
+- **HUD is present from t=0** — the pause / hint / keyboard toggles
+  are now reachable the moment the typing page mounts, not after the
+  first keystroke. `useHudBridge` derives an initial `TypingState` +
+  `TypingMetrics` from the engine on mount; arena's `onStateChange`
+  push still overrides once real events fire.
+### Changed
+- **Default sound settings** — `qtype.keySoundEnabled` and
+  `qtype.errorSoundEnabled` now default to `true` for new users. Both
+  were `false` before; existing users' saved preferences are
+  untouched.
+- **Default AFK threshold** raised from 15 s to 60 s so a short pause
+  to think doesn't cost the flow. Also clarified the settings
+  description (mouse hover without movement counts as AFK; tab hidden
+  / window blur pauses immediately).
+### Fixed
+- **`typing.$file.tsx` no longer synthesises HUD placeholder state**
+  in-line — the fix lives in `useHudBridge` where it belongs. Removes
+  the risk of the placeholder drifting from arena's real derivation.
+- **`deriveAesKey` returns an extractable AES key** so the view can
+  cache the derived bytes in sessionStorage — a same-tab reload no
+  longer re-prompts for the password. Regression test added under
+  `__tests__/core/encrypt.test.ts`.
+- **Docs link cleanup** — all internal `.md` links in the npm-shipped
+  files now go through `https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=...`
+  URLs so users on npm can click through even when the source repo
+  is private. Removed dead links to `CONTRIBUTING.md` /
+  `architecture.md` / `TODO.md` since those aren't shipped.
 ## [0.0.1] - 2026-08-16
 Initial development release. Everything below is the baseline shipped

package/CHANGELOG.zh.md CHANGED Viewed

@@ -12,6 +12,57 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 ## [Unreleased]
+## [0.0.5] - 2026-08-22
+### 修复
+- **Mermaid 预渲染在 `npx` / 托管 CI 环境不再失败**。
+  `mermaidPrerender.init()` 改用
+  `createRequire(import.meta.url).resolve('mermaid/…')`,让 Node
+  自己顺着 `node_modules` 链找 mermaid,不管 qtype 是装到用户仓库、
+  npx 缓存、Cloudflare Pages build root 还是 monorepo hoist 都能
+  找到。之前的两条硬编码查找路径保留作为兜底,但不再是主要策略。
+  修复了 deck 里真的有 ` ```mermaid ` 代码块时,Cloudflare Pages 上
+  `mermaid ESM not found in node_modules` 报错。
+- **`publish build` 现在会把 `material/assets/**`** 原样拷进
+  `dist/material/assets/`。之前 CLI 只遍历 `.md` 文件,导致卡片
+  引用的 `![](/material/assets/…)` 图片在部署后 404。
+## [0.0.4] - 2026-08-22
+### 新增
+- **浏览器 tab 标题 + 左上角显示站点名** —— `qtype publish build`
+  会把站点名写进 `dist/index.html`(同时改 `<title>` 和 `<html>` 上的
+  `data-qtype-repo-name` 属性)。view 通过 `readBootConfig()` 读它,
+  Header 的品牌位显示当前 deck 名而不是硬编码的 "qtype"。取值优先级:
+  `.qtype/config.json` 里的 `repo.name` > 仓库目录名。
+- **HUD 一进打字页就显示** —— 暂停 / 提示 / 键盘切换按钮从打字页
+  挂载起就可用,不再需要等用户敲第一下。`useHudBridge` 在 mount 时
+  就从 engine 派生初始 `TypingState` + `TypingMetrics`;arena 的
+  `onStateChange` 推送开始后无缝覆盖。
+### 变更
+- **默认打开按键音和错误音** —— `qtype.keySoundEnabled` 和
+  `qtype.errorSoundEnabled` 对新用户默认改为 `true`(之前都是
+  `false`)。已有用户的设置不受影响。
+- **AFK 默认阈值** 从 15 秒调到 60 秒,给思考一点空间。同时把设置
+  说明写清楚:鼠标悬停不动也算 AFK;切 tab 或窗口失焦会立即暂停。
+### 修复
+- **`typing.$file.tsx` 不再手写 HUD 初始状态** —— 修复搬到该在的
+  `useHudBridge`。避免手写值和 arena 真实派生逻辑漂移。
+- **`deriveAesKey` 返回可导出的 AES 密钥**,view 端才能把派生结果
+  存进 sessionStorage —— 同 tab 刷新不再重问密码。回归测试见
+  `__tests__/core/encrypt.test.ts`。
+- **文档链接整改** —— npm 发布的文件里所有内部 `.md` 链接都改成
+  `https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=...`
+  形式的 npm 链接,私仓状态下 npm 用户点了也能看到内容。删掉了指向
+  `CONTRIBUTING.md` / `architecture.md` / `TODO.md` 这些不发布文件
+  的死链。
 ## [0.0.1] - 2026-08-16
 首个开发版。以下是这个版本的基线内容。

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

@@ -42,6 +42,10 @@ 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 file of walkMaterial(cwd)) {
         const body = readMaterial(file);
@@ -64,6 +68,11 @@ 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
@@ -107,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) {
@@ -186,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)

package/dist/cli/commands/publish/build/mermaidPrerender.js CHANGED Viewed

@@ -38,15 +38,37 @@ export class MermaidRenderer {
     pageDark = null;
     pageLight = null;
     async init() {
-        const candidates = [
-            path.resolve(__dirname, '..', '..', '..', '..', '..', 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
-            path.resolve(process.cwd(), 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
-        ];
+        // Ask Node's own module resolver where mermaid actually lives. It
+        // walks the `node_modules` chain from this file up, so it works
+        // regardless of where the caller installed qtype:
+        //
+        //   * user repo with `npm install @qnroa/qtype`      → resolves in
+        //                                                     `<user>/node_modules/mermaid`
+        //   * `npx @qnroa/qtype` on any host (Cloudflare,     → resolves in
+        //     Vercel, GitHub Pages) that hoists deps into      the npx cache
+        //     an npx cache
+        //   * monorepo with hoisted deps                     → resolves in
+        //                                                     the hoisted root
+        //
+        // The two hard-coded fallbacks below only fire if Node's resolver
+        // fails entirely (older Node, exotic packaging), which shouldn't
+        // happen in any supported deployment.
         let mermaidEsm = null;
-        for (const c of candidates) {
-            if (fs.existsSync(c)) {
-                mermaidEsm = c;
-                break;
+        try {
+            const { createRequire } = await import('node:module');
+            const req = createRequire(import.meta.url);
+            mermaidEsm = req.resolve('mermaid/dist/mermaid.esm.min.mjs');
+        }
+        catch {
+            const candidates = [
+                path.resolve(__dirname, '..', '..', '..', '..', '..', 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
+                path.resolve(process.cwd(), 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
+            ];
+            for (const c of candidates) {
+                if (fs.existsSync(c)) {
+                    mermaidEsm = c;
+                    break;
+                }
             }
         }
         if (!mermaidEsm) {