skill-family-doc-render 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+## 0.6.1 - 2026-10-12
+
+### 变更
+
+- 按本仓联合发布合同，`skill-family-doc-render` 与 `skill-family-docs`、公开站点对齐为 0.6.1。渲染器的公开 API、命令行参数、输入合同、模板和业务实现均未改变，运行依赖仍精确锁定原版本。Foundation 0.22.0 钉扎不变。
+
+### 说明
+
+- 本地源包版本为 0.6.1 候选，不代表已经正式发布。安装或使用 `npx` 前，先在官方 npm 确认 `skill-family-doc-render@0.6.1` 可用。已发布的 0.6.0 保留，不覆盖该版本。
+
+## 0.6.0 - 2026-10-11
+
+### 变更
+
+- 与 `skill-family-docs` 和公开站点的 0.6.0 联合发布对齐版本。
+- `editorial` 模板调整阅读与交互样式，包内单测同步。
+
+### 说明
+
+- 安装或 `npx` 前，先在官方 npm 确认 `skill-family-doc-render@0.6.0` 可用。本源版本不等于已发布或可安装版本。
+
 ## 0.5.0 - 2026-09-28
 
 ### 新增

package/README.md

@@ -16,20 +16,20 @@ publication APIs. A failure before commit removes staging and leaves the existin
 untouched. After commit, or when publication is indeterminate, staging or displaced data may
 remain for diagnosis; the renderer does not guess or roll back.
 
-> **Version boundary:** this source tree is version `0.5.0`. That is the local version and the
+> **Version boundary:** this source tree is version `0.6.1`. That is the local version and the
 > intended joint target for the renderer, documentation plugin, and public site. Confirm this
 > exact version in the official npm registry before `npm install` or `npx`. Published `0.4.5`
 > preserves the `markdown-v1`, `editorial`, and `--check-project` behavior introduced in 0.4.0
-> and has no `--conclusion-output` or `--read-proof`. Those two commands belong to this 0.5.0
+> and has no `--conclusion-output` or `--read-proof`. Those two commands belong to this 0.6.1
 > CLI. The examples give the command shape for that version. They leave publication, Skill
-> Family Hub registration, and new host-reply acceptance to the official records for `0.5.0`.
+> Family Hub registration, and new host-reply acceptance to the official records for `0.6.1`.
 
 ## Install
 
-After confirming `skill-family-doc-render@0.5.0` in the official npm registry, install that exact version:
+After confirming `skill-family-doc-render@0.6.1` in the official npm registry, install that exact version:
 
 ```sh
-npm install --save-exact skill-family-doc-render@0.5.0
+npm install --save-exact skill-family-doc-render@0.6.1
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
@@ -39,41 +39,41 @@ This checkout currently pins exact runtime dependencies on `marked@18.0.11`,
 Markdown lexer; the renderer applies its own restricted-format validation before passing semantic
 content to the template. The workspace profile check separately uses
 `skill-family-engineering-kit@0.22.0`. These pins describe the local source and installed
-packages; they do not republish `0.5.0`.
+packages; they do not republish `0.6.0`.
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
 must re-render their baseline before using `--check`. See the changelog for the full migration
 notes.
 
 ## CLI
 
-Use the exact 0.5.0 CLI for rendering, checks, coverage maintenance, the Git index assertion, and the proof commands. Confirm `skill-family-doc-render@0.5.0` in the official npm registry before running them. Published 0.4.5 can run the commands that omit `--conclusion-output` and `--read-proof`.
+Use the exact 0.6.1 CLI for rendering, checks, coverage maintenance, the Git index assertion, and the proof commands. Confirm `skill-family-doc-render@0.6.1` in the official npm registry before running them. Published 0.4.5 can run the commands that omit `--conclusion-output` and `--read-proof`.
 
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.5.0
+npx skill-family-doc-render@0.6.1
 
 # drift check only: compare in-memory render against the on-disk site-baseline.json, write nothing
-npx skill-family-doc-render@0.5.0 --check
+npx skill-family-doc-render@0.6.1 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.5.0 --repo <name>
+npx skill-family-doc-render@0.6.1 --repo <name>
 
 # assert every rendered file is tracked in the Git index, then render
-npx skill-family-doc-render@0.5.0 --assert-git
+npx skill-family-doc-render@0.6.1 --assert-git
 
 # run both the drift and Git index tracking checks without writing
-npx skill-family-doc-render@0.5.0 --check --assert-git
+npx skill-family-doc-render@0.6.1 --check --assert-git
 
 # inspect or refresh the reviewed product-input snapshot
-npx skill-family-doc-render@0.5.0 --status --repo <name>
-npx skill-family-doc-render@0.5.0 --refresh-coverage --repo <name>
-npx skill-family-doc-render@0.5.0 --check-project --repo <name>
+npx skill-family-doc-render@0.6.1 --status --repo <name>
+npx skill-family-doc-render@0.6.1 --refresh-coverage --repo <name>
+npx skill-family-doc-render@0.6.1 --check-project --repo <name>
 
 # after the mechanical check, exclusive-create one proof; do not overwrite
-npx skill-family-doc-render@0.5.0 --check-project --repo <name> --conclusion-output /absolute/path/conclusion.json
+npx skill-family-doc-render@0.6.1 --check-project --repo <name> --conclusion-output /absolute/path/conclusion.json
 
 # read one existing proof from any working directory; write nothing
-npx skill-family-doc-render@0.5.0 --read-proof --proof-root /absolute/proof-root --proof relative/conclusion.json
+npx skill-family-doc-render@0.6.1 --read-proof --proof-root /absolute/proof-root --proof relative/conclusion.json
 ```
 
 `--check-project` still requires the current directory to own `public-release.json`.
@@ -104,7 +104,7 @@ Same-version `DOCS_CLEAR` maps to `pass` only when `completion` is `complete`;
 That status keeps the proof's recorded non-pass. A missing file, damaged JSON, a different
 provider, or an unknown same-version domain code is `unavailable` (exit `2`). Earlier
 local-candidate runs exercised proof output and proof reading; those runs keep their original
-scene limits. Publication, Hub registration, and new host replies for `0.5.0` stay with the
+scene limits. Publication, Hub registration, and new host replies for `0.6.1` stay with the
 official records. These proof commands consume the Foundation
 `professional-conclusion` contract from `skill-family-contracts@0.22.0`. Refreshing a proof
 means running `--check-project` again to a new output path. Remediation, site creation, and
@@ -318,7 +318,7 @@ Foundation packages below, it uses exact `marked@18.0.11` for Markdown tokenizat
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** run `npx skill-family-doc-render@0.5.0 --check-project --repo <name>` after
+> **Start here:** run `npx skill-family-doc-render@0.6.1 --check-project --repo <name>` after
 > confirming that exact version in the official registry. From a local checkout, stay in the
 > directory that owns `public-release.json` and call
 > `node /absolute/path/to/skill-family-doc-render/bin/skill-family-doc-render.mjs --check-project --repo <name>`,
@@ -346,6 +346,6 @@ Apache-2.0
 Display help and run a read-only project check:
 
 ```sh
-npx skill-family-doc-render@0.5.0 --help
-npx skill-family-doc-render@0.5.0 --check-project --repo <name>
+npx skill-family-doc-render@0.6.1 --help
+npx skill-family-doc-render@0.6.1 --check-project --repo <name>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",

package/templates/editorial/assets/site.js

@@ -99,12 +99,49 @@
   let activeDialog;
   // Release synchronously before following links or switching dialogs. The queued
   // native close event must never restore an old position over a destination.
+  function captureViewport() {
+    return { left: window.scrollX, top: window.scrollY };
+  }
+  // Sticky header controls sit in document flow at y=0. Pointerdown/keydown must
+  // record the viewport before focus scrolls that in-flow box into view.
+  function bindOpener(button) {
+    let viewport = null;
+    const remember = () => { viewport = captureViewport(); };
+    button.addEventListener('pointerdown', remember);
+    button.addEventListener('touchstart', remember, { passive: true });
+    button.addEventListener('keydown', event => {
+      if (event.key === 'Enter' || event.key === ' ') remember();
+    });
+    button.addEventListener('mousedown', event => {
+      remember();
+      event.preventDefault();
+    });
+    return () => {
+      const value = viewport ?? captureViewport();
+      viewport = null;
+      return value;
+    };
+  }
+  function restoreScroll(state) {
+    const html = document.documentElement;
+    const previous = html.style.scrollBehavior;
+    html.style.scrollBehavior = 'auto';
+    const apply = () => window.scrollTo({ left: state.left, top: state.top, behavior: 'auto' });
+    apply();
+    requestAnimationFrame(() => {
+      apply();
+      requestAnimationFrame(apply);
+    });
+    setTimeout(apply, 0);
+    html.style.scrollBehavior = previous;
+  }
   function releaseDialog(state, returnFocus = true) {
     if (activeDialog !== state) return;
     activeDialog = null;
+    document.documentElement.classList.remove('modal-open');
     document.body.classList.remove('modal-open');
     document.body.style.removeProperty('top');
-    window.scrollTo({ left: state.left, top: state.top, behavior: 'instant' });
+    restoreScroll(state);
     if (returnFocus && state.invoker?.isConnected) state.invoker.focus({ preventScroll: true });
   }
   function closeDialog(dialog, returnFocus = true) {
@@ -112,11 +149,17 @@
     dialog.close();
     if (state?.dialog === dialog) releaseDialog(state, returnFocus);
   }
-  function showDialog(dialog, invoker) {
+  function showDialog(dialog, invoker, viewport) {
     if (activeDialog) closeDialog(activeDialog.dialog);
-    const state = { dialog, invoker, left: window.scrollX, top: window.scrollY };
+    const state = {
+      dialog,
+      invoker,
+      left: viewport?.left ?? window.scrollX,
+      top: viewport?.top ?? window.scrollY,
+    };
     activeDialog = state;
     document.body.style.top = `${-state.top}px`;
+    document.documentElement.classList.add('modal-open');
     document.body.classList.add('modal-open');
     try { dialog.showModal(); } catch (error) { releaseDialog(state); throw error; }
   }
@@ -130,7 +173,8 @@
       if (event.clientX < rect.left || event.clientX > rect.right || event.clientY < rect.top || event.clientY > rect.bottom) closeDialog(dialog);
     });
   }
-  get('menu-toggle').addEventListener('click', () => showDialog(menu, get('menu-toggle')));
+  const menuViewport = bindOpener(get('menu-toggle'));
+  get('menu-toggle').addEventListener('click', () => showDialog(menu, get('menu-toggle'), menuViewport()));
   get('close-menu').addEventListener('click', () => closeDialog(menu));
   menu.addEventListener('click', event => {
     if (event.target.closest('a')) closeDialog(menu, false);
@@ -189,14 +233,15 @@
     setActiveResult(0, false);
     results.scrollTop = 0;
   }
-  function openSearch(invoker) {
+  const searchViewport = bindOpener(searchToggle);
+  function openSearch(invoker, viewport) {
     if (invoker?.closest('dialog')) invoker = searchToggle;
     input.value = '';
     updateSearch();
-    showDialog(searchDialog, invoker);
+    showDialog(searchDialog, invoker, viewport);
     input.focus({ preventScroll: true });
   }
-  searchToggle.addEventListener('click', () => openSearch(searchToggle));
+  searchToggle.addEventListener('click', () => openSearch(searchToggle, searchViewport()));
   get('close-search').addEventListener('click', () => closeDialog(searchDialog));
   input.addEventListener('input', updateSearch);
   input.addEventListener('keydown', event => {

package/templates/editorial/assets/style.css

@@ -6,7 +6,7 @@
   --surface: #fff;
   --ink: #26392f;
   --text: #3d4b43;
-  --muted: #657168;
+  --muted: #5f6c62; /* muted on tint must stay ≥4.5:1; #657168 was 4.394 */
   --line: #dce3d9;
   --green: #2f634c;
   --tint: #e9f0e7;
@@ -122,8 +122,10 @@ main:focus:not(:focus-visible) { outline: none; }
 .breadcrumb { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 12px; color: var(--muted); font-size: 11px; margin: 0 auto 35px; max-width: 740px; }
 .breadcrumb > span:last-child { color: var(--text); }
 article { max-width: 740px; margin: 0 auto; }
-.intro { font-size: 15px; line-height: 1.9; color: var(--muted); margin-bottom: 20px; max-width: 44em; }
+article.page-home { overflow-x: clip; }
+.intro { font-size: 16px; line-height: 1.8; color: var(--muted); margin-bottom: 20px; max-width: 44em; }
 .page-heading { margin-bottom: 30px; }
+.page-heading .text-action { display: inline-flex; margin: -6px 0 14px; }
 .content-list { margin: 20px 0; padding-left: 1.5em; }
 .content-list li { padding-left: .3em; margin: 12px 0; }
 .heading-link { font-size: .7em; text-decoration: none; font-weight: 400; padding: 4px; opacity: .65; }
@@ -142,9 +144,9 @@ article { max-width: 740px; margin: 0 auto; }
 .article-footer a { text-decoration: none; white-space: nowrap; }
 
 /* Home page uses the same manifest-driven task sequence as the pager. */
-.home-hero { display: grid; grid-template-columns: minmax(0,1fr) 180px; align-items: center; gap: 25px; }
+.home-hero { display: grid; grid-template-columns: minmax(0,1fr) 180px; align-items: center; gap: 25px; overflow: hidden; }
 .home-hero h1 { font-size: 38px; }
-.home-hero .intro { font-size: 14px; }
+.home-hero .intro { font-size: 16px; }
 .hero-actions { display: flex; align-items: center; gap: 22px; flex-wrap: wrap; margin: 24px 0 12px; }
 .hero-actions:empty { display: none; }
 .button { display: inline-flex; align-items: center; justify-content: space-between; gap: 28px; text-decoration: none; border-radius: 7px; padding: 10px 14px 10px 18px; font-size: 13px; font-weight: 500; transition: transform 160ms var(--ease), background 160ms var(--ease); }
@@ -172,8 +174,8 @@ article { max-width: 740px; margin: 0 auto; }
 .route-list > a:first-child { border-top: 0; }
 .route-list > a:hover { background: var(--tint); padding-left: 10px; padding-right: 10px; }
 .route-number { font-size: 11px; color: var(--muted); align-self: flex-start; padding-top: 4px; flex: none; }
-.route-list h3 { font-size: 14px; margin: 0 0 3px; }
-.route-list p { font-size: 12px; color: var(--muted); margin: 0; line-height: 1.8; }
+.route-list h3 { font-size: 16px; margin: 0 0 3px; }
+.route-list p { font-size: 16px; color: var(--muted); margin: 0; line-height: 1.8; }
 .route-arrow { margin-left: auto; font-size: 18px; font-weight: 400; color: var(--green); flex: none; }
 
 /* Semantic blocks; no project-provided layout classes. */
@@ -208,7 +210,7 @@ td code { white-space: nowrap; }
 dialog { background: var(--surface); color: var(--text); border: 1px solid var(--line); border-radius: 12px; padding: 0; box-shadow: var(--shadow); }
 dialog:not([open]) { display: none; }
 dialog::backdrop { background: #162c2455; backdrop-filter: blur(3px); }
-html:has(dialog[open]) { overflow: hidden; }
+html.modal-open { overflow: hidden; }
 body.modal-open { position: fixed; left: 0; right: 0; width: 100%; }
 #editorial-search-dialog { width: min(600px,calc(100vw - 28px)); max-height: 75dvh; margin: 12dvh auto auto; }
 #editorial-search-dialog[open] { display: flex; flex-direction: column; }
@@ -238,7 +240,6 @@ body.modal-open { position: fixed; left: 0; right: 0; width: 100%; }
   .sidebar { padding-left: 32px; }
   .home-hero { grid-template-columns: minmax(0,1fr) 200px; gap: 35px; }
   .home-hero h1 { font-size: 42px; }
-  .home-hero .intro { font-size: 15px; }
 }
 @media (max-width: 1199px) {
   .layout { grid-template-columns: 210px minmax(0,1fr); }
@@ -269,7 +270,6 @@ body.modal-open { position: fixed; left: 0; right: 0; width: 100%; }
   .home-hero { grid-template-columns: minmax(0,1fr) 155px; gap: 20px; }
   .home-hero h1 { font-size: 34px; }
   h1 { font-size: 31px; }
-  .intro { font-size: 14px; }
   .hero-actions { gap: 17px; }
   .page-heading { margin-bottom: 24px; }
   .article-footer { margin-top: 42px; }
@@ -278,14 +278,11 @@ body.modal-open { position: fixed; left: 0; right: 0; width: 100%; }
   .home-hero { display: block; }
   .source-illustration { display: none; }
   .home-hero h1 { font-size: 34px; line-height: 1.42; }
-  .home-hero .intro { font-size: 14px; }
   .hero-actions { gap: 18px; margin-top: 22px; }
   h1 { font-size: 29px; letter-spacing: -.04em; }
   h2 { font-size: 21px; }
   .start-section { padding-top: 23px; margin-top: 30px; }
   .route-list > a { padding: 18px 0; gap: 12px; }
-  .route-list h3 { font-size: 14px; }
-  .route-list p { font-size: 12px; }
   .route-arrow { font-size: 16px; }
   .route-number { font-size: 10px; }
   .callout { padding: 14px; gap: 10px; font-size: 12px; }
@@ -313,7 +310,7 @@ body.modal-open { position: fixed; left: 0; right: 0; width: 100%; }
   }
   .site-header, .sidebar, .page-outline, .copy-button, .heading-copy, .heading-link,
   .page-pager, .article-footer, .toast, dialog, .skip-link, .mobile-fallback { display: none !important; }
-  html:has(dialog[open]) { overflow: visible; }
+  html.modal-open { overflow: visible; }
   body.modal-open { position: static; top: auto !important; }
   .layout { display: block; }
   main { padding: 0; }

package/templates/editorial/index.mjs

@@ -201,11 +201,13 @@ function tutorial(model, page) {
   return `<nav class="page-pager" aria-label="教程翻页">${previous ? `<a class="pager-previous" href="${pageHref(previous)}" rel="prev"><span>上一步</span><strong>← ${escape(label(previous))}</strong></a>` : ''}${next ? `<a class="pager-next" href="${pageHref(next)}" rel="next"><span>下一步</span><strong>${escape(label(next))} →</strong></a>` : ''}</nav>`;
 }
 function hero(model, page) {
-  const title = `<h1>${escape(page.title)}</h1><p class="intro">${renderInline(page.blocks[0].content)}</p>`;
+  const intro = `<p class="intro">${renderInline(page.blocks[0].content)}</p>`;
   if (page.kind !== 'home') {
     const promptIndex = page.kind === 'task' ? page.blocks.findIndex(block => block.type === 'code' && block.language === 'prompt') : -1;
-    return `<div class="page-heading">${title}${promptIndex >= 0 ? `<a class="text-action" href="#editorial-code-${promptIndex}">查看操作提示词 <span aria-hidden="true">↓</span></a>` : ''}</div>`;
+    const jump = promptIndex >= 0 ? `<a class="text-action" href="#editorial-code-${promptIndex}">查看操作提示词 <span aria-hidden="true">↓</span></a>` : '';
+    return `<div class="page-heading"><h1>${escape(page.title)}</h1>${jump}${intro}</div>`;
   }
+  const title = `<h1>${escape(page.title)}</h1>${intro}`;
   const tasks = model.pages.filter(item => item.inPager);
   const first = tasks[0];
   const maintenance = tasks.find(item => item.role === 'maintenance' && item !== first);