for-humanity 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.4.2 — 2026-10-04
+
+- Preserve sidebar and mobile drawer scroll positions across document navigation and reloads within a tab, independently of the main content.
+- Show thin native navigation scrollbar thumbs on hover or keyboard focus, with a transparent track, Firefox thin fallback and system colors in forced-color environments.
+- Explain when related sections belong in one page's headings and when a separate child document is appropriate.
+
+## 0.4.1 — 2026-10-04
+
+- Coalesce consecutive document and asset saves and serialize dev refreshes so bulk AI edits cannot start overlapping full-site renders and exhaust memory.
+- Continue queued and later edits after failed processing, and apply only the latest valid generation.
+
 ## 0.4.0 — 2026-10-04
 
 - Copy explicitly referenced local images and supported attachments to fingerprinted asset URLs, resolving paths relative to their Markdown files in both build and dev.

package/README.md

@@ -33,7 +33,7 @@ Write Markdown. Keep the context. Share a static site.
 Node.js 22 or later and pnpm. Install the CLI in your document project:
 
 ```sh
-pnpm add -D --save-exact for-humanity@0.4.0
+pnpm add -D --save-exact for-humanity@0.4.2
 mkdir docs
 ```
 
@@ -52,7 +52,7 @@ pnpm exec for-humanity preview docs
 
 If your Markdown files are in the project root, use `.` instead of `docs`. The root `README.md` becomes the home page; root `AGENTS.md` and `CLAUDE.md` stay out of the site.
 
-Version `0.4.0` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
+Version `0.4.2` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
 Cloudflare Pages can host the generated site. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) for the build settings.
 
 ### Develop the kit
@@ -74,7 +74,7 @@ pnpm preview    # Preview the static site
 pnpm build:pages # Add Cloudflare Pages headers and a 404 page
 ```
 
-Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.0` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
+Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.2` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
 The npm README updates with each package release. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md#packaging-and-release) for the release steps.
 
 ## Make it yours

package/dist/cli.css

@@ -888,7 +888,27 @@
   max-height: 100vh;
   margin-inline-end: var(--app-space-sidebar-gap);
   overflow-y: auto;
+  overscroll-behavior-y: contain;
+  scrollbar-gutter: stable;
+  scrollbar-width: auto;
+  scrollbar-color: auto;
   scroll-padding-block: var(--app-size-brand) var(--app-space-block);
+  &::-webkit-scrollbar {
+    width: 3px;
+  }
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  &::-webkit-scrollbar-thumb {
+    border-radius: 3px;
+    background: transparent;
+  }
+  &:hover::-webkit-scrollbar-thumb {
+    background: var(--app-color-border-soft);
+  }
+  &:focus-within::-webkit-scrollbar-thumb {
+    background: var(--app-color-border-soft);
+  }
 }
 .wg_shell__navigation {
   min-width: 0;
@@ -914,8 +934,27 @@
   border-right: 1px solid var(--app-color-border-layout);
   background: var(--app-color-ground);
   color: var(--app-color-text);
+  scrollbar-gutter: stable;
+  scrollbar-width: auto;
+  scrollbar-color: auto;
   overscroll-behavior: contain;
   scroll-padding-block: var(--app-size-mobile-header) var(--app-space-group);
+  &::-webkit-scrollbar {
+    width: 3px;
+  }
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  &::-webkit-scrollbar-thumb {
+    border-radius: 3px;
+    background: transparent;
+  }
+  &:hover::-webkit-scrollbar-thumb {
+    background: var(--app-color-border-soft);
+  }
+  &:focus-within::-webkit-scrollbar-thumb {
+    background: var(--app-color-border-soft);
+  }
   &::backdrop {
     background: var(--app-color-backdrop);
   }
@@ -974,6 +1013,36 @@
 .wg_shell__cursorFace--visible {
   visibility: visible;
 }
+@supports not selector(::-webkit-scrollbar) {
+  .wg_shell__sidebar {
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+    &:hover {
+      scrollbar-color: var(--app-color-border-soft) transparent;
+    }
+    &:focus-within {
+      scrollbar-color: var(--app-color-border-soft) transparent;
+    }
+  }
+  .wg_shell__drawer {
+    scrollbar-width: thin;
+    scrollbar-color: var(--app-color-border-soft) transparent;
+  }
+}
+@media (forced-colors: active) {
+  .wg_shell__sidebar {
+    scrollbar-width: auto;
+    scrollbar-color: auto;
+    &::-webkit-scrollbar-thumb {
+      background: CanvasText;
+    }
+  }
+  .wg_shell__drawer {
+    &::-webkit-scrollbar-thumb {
+      background: CanvasText;
+    }
+  }
+}
 @media (width < 1024px) {
   .wg_shell__root {
     max-width: calc(var(--app-size-main) + var(--app-space-gutter) * 2);

package/dist/cli.js

@@ -8,6 +8,7 @@ import { basename as basename2, dirname as dirname4, extname as extname4, join a
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { debounce } from "es-toolkit";
 import { Hono as Hono3 } from "hono";
 import { toSSG } from "hono/ssg";
 
@@ -349,6 +350,7 @@ var cli_default_command = "dev";
 var cli_default_docs_dir = ".";
 var cli_config_file_name = "for-humanity.config.mjs";
 var cli_dev_port = 4321;
+var cli_reload_delay_ms = 150;
 
 // src/constant/font.ts
 var font_sans_css = "src/asset/font/pretendard/pretendardvariable-dynamic-subset.css";
@@ -1288,6 +1290,32 @@ var siteConfigSchema = z3.object({
   ).default(status_default_phrases)
 });
 
+// src/util/async/to-change-queue.ts
+var toChangeQueue = (options) => {
+  const state = { requested: 0, completed: 0, running: false };
+  return async () => {
+    state.requested += 1;
+    if (state.running) {
+      return;
+    }
+    state.running = true;
+    try {
+      while (state.completed !== state.requested) {
+        const requested = state.requested;
+        try {
+          await options.run();
+        } catch (error) {
+          options.onError(error);
+        } finally {
+          state.completed = requested;
+        }
+      }
+    } finally {
+      state.running = false;
+    }
+  };
+};
+
 // src/util/error/to-error-message.ts
 var toErrorMessage = (error) => {
   if (error instanceof Error && "file" in error && typeof error.file === "string" && "line" in error && typeof error.line === "number") {
@@ -1390,31 +1418,37 @@ var main = async () => {
   const reload = new EventEmitter();
   let generation = 0;
   serve({ fetch: createDevApp({ pages: app, files, reload }).fetch, port: cli_dev_port }, (info) => console.log(`http://localhost:${info.port}/`));
-  const handleDocsChange = async (_event, filename) => {
+  const reloadDocs = debounce(
+    toChangeQueue({
+      run: async () => {
+        const currentGeneration = generation;
+        const nextFiles = new Map(kitFiles);
+        const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
+        const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
+        if (currentGeneration !== generation) {
+          return;
+        }
+        files.clear();
+        for (const entry of nextFiles) {
+          files.set(...entry);
+        }
+        store.docs = docs2;
+        store.home = home2;
+        reload.emit("change");
+      },
+      onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`)
+    }),
+    cli_reload_delay_ms
+  );
+  const handleDocsChange = (_event, filename) => {
     if (filename !== null) {
       const segments = filename.split(sep3);
       if (segments.includes("dist") || segments.includes("node_modules") || !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname4(filename).toLowerCase())) {
         return;
       }
     }
-    const currentGeneration = ++generation;
-    try {
-      const nextFiles = new Map(kitFiles);
-      const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
-      const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
-      if (currentGeneration !== generation) {
-        return;
-      }
-      files.clear();
-      for (const entry of nextFiles) {
-        files.set(...entry);
-      }
-      store.docs = docs2;
-      store.home = home2;
-      reload.emit("change");
-    } catch (error) {
-      console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
-    }
+    generation += 1;
+    reloadDocs();
   };
   watch(docsRoot, { recursive: true }, handleDocsChange);
 };

package/dist/client.js

@@ -1,5 +1,6 @@
-var L="fh-cursor-face";var k="(width < 1024px)";var p=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var m=e=>{let t=p(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var S=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),i=document.querySelector("[data-navigation-open]"),d=document.querySelector("[data-navigation-close]"),c=e?.parentElement;if(!e||!t||!n||!i||!d||!c)return;let l=matchMedia(k),a=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","false"))},u=()=>{t.close(),a()},h=()=>{!l.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","true"))},r=o=>{let s=t.getBoundingClientRect();o.target===t&&(o.clientX<s.left||o.clientX>s.right||o.clientY<s.top||o.clientY>s.bottom)&&u()},q=o=>{if(!t.open||o.defaultPrevented||o.button!==0||o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||!(o.target instanceof Element))return;let s=o.target.closest("a[href]");if(!(!(s instanceof HTMLAnchorElement)||s.target!==""&&s.target!=="_self"||s.hasAttribute("download"))&&(u(),s.origin===location.origin&&s.pathname===location.pathname&&s.search===location.search&&s.hash)){let T=m(s.hash);T&&(T.tabIndex=-1,T.focus({preventScroll:!0}))}},H=()=>{let o=document.activeElement;if(l.matches){i.classList.add("wg_shell__menuToggle--visible"),n.append(e),o instanceof HTMLElement&&e.contains(o)&&i.focus({preventScroll:!0});return}u(),c.append(e),o instanceof HTMLElement&&e.contains(o)?o.focus({preventScroll:!0}):(o===i||o instanceof HTMLElement&&t.contains(o))&&c.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),i.classList.remove("wg_shell__menuToggle--visible")};i.addEventListener("click",h),d.addEventListener("click",u),t.addEventListener("close",a),t.addEventListener("click",r),e.addEventListener("click",q),l.addEventListener("change",H),H(),c.classList.add("wg_shell__sidebar--navigationReady")};S();var g=document.querySelector("[data-cursor-face]");if(g){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,g.classList.remove("wg_shell__cursorFace--visible")},i=()=>{e.matches||n()},d=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,g.style.transform=`translate3d(
-                ${Math.max(0,Math.min(t.x+16,document.documentElement.clientWidth-g.width-16))}px,
-                ${Math.max(0,Math.min(t.y+16,document.documentElement.clientHeight-g.height-16))}px,
+var T="fh-cursor-face";var w="(width < 1024px)",x="for-humanity:navigation-scroll";var b=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var y=e=>{let t=b(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var I=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),a=document.querySelector("[data-navigation-open]"),s=document.querySelector("[data-navigation-close]"),u=e?.parentElement;if(!e||!t||!n||!a||!s||!u)return;let d=matchMedia(w),l=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),a.setAttribute("aria-expanded","false"))},m=()=>{t.close(),l()},g=()=>{!d.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),a.setAttribute("aria-expanded","true"))},i=r=>{let o=t.getBoundingClientRect();r.target===t&&(r.clientX<o.left||r.clientX>o.right||r.clientY<o.top||r.clientY>o.bottom)&&m()},L=r=>{if(!t.open||r.defaultPrevented||r.button!==0||r.metaKey||r.ctrlKey||r.shiftKey||r.altKey||!(r.target instanceof Element))return;let o=r.target.closest("a[href]");if(!(!(o instanceof HTMLAnchorElement)||o.target!==""&&o.target!=="_self"||o.hasAttribute("download"))&&(m(),o.origin===location.origin&&o.pathname===location.pathname&&o.search===location.search&&o.hash)){let c=y(o.hash);c&&(c.tabIndex=-1,c.focus({preventScroll:!0}))}},p=()=>{let r=document.activeElement;if(d.matches){a.classList.add("wg_shell__menuToggle--visible"),n.append(e),r instanceof HTMLElement&&e.contains(r)&&a.focus({preventScroll:!0});return}m(),u.append(e),r instanceof HTMLElement&&e.contains(r)?r.focus({preventScroll:!0}):(r===a||r instanceof HTMLElement&&t.contains(r))&&u.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),a.classList.remove("wg_shell__menuToggle--visible")};a.addEventListener("click",g),s.addEventListener("click",m),t.addEventListener("close",l),t.addEventListener("click",i),e.addEventListener("click",L),d.addEventListener("change",p),p(),u.classList.add("wg_shell__sidebar--navigationReady")};var N=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector(".wg_shell__sidebar"),n=document.querySelector("[data-navigation-drawer]"),a=document.querySelector("[data-navigation-open]");if(!e||!t||!n||!a)return;let s=matchMedia(w),u={mobile:s.matches},d=[...e.querySelectorAll(".wg_shellNav__root a[href]")].map(o=>`${o.pathname}:${o.textContent}`).join(`
+`),l=new Map,m=new Map([[t,`${x}:desktop`],[n,`${x}:drawer`]]),g=new AbortController;for(let[o,c]of m){try{let _=sessionStorage.getItem(c);if(_!==null){let h=JSON.parse(_);typeof h=="object"&&h!==null&&"navigation"in h&&h.navigation===d&&"top"in h&&typeof h.top=="number"&&Number.isFinite(h.top)&&h.top>=0&&l.set(o,h.top)}}catch{}for(let _ of["wheel","touchstart","pointerdown","keydown"])o.addEventListener(_,()=>g.abort(),{once:!0,passive:!0})}let i=new Map(l),L=()=>{u.mobile=s.matches;let o=s.matches?n:t,c=l.get(o);c===void 0||s.matches&&!n.open||(o.scrollTop=c)},p=o=>{let c=s.matches?n:t,_=m.get(c);if(!(u.mobile!==s.matches||o.type==="scroll"&&o.currentTarget!==c||_===void 0||s.matches&&!n.open)){l.set(c,c.scrollTop);try{sessionStorage.setItem(_,JSON.stringify({navigation:d,top:c.scrollTop}))}catch{}}},r=async()=>{if(await document.fonts.ready,!g.signal.aborted){let o=s.matches?n:t,c=i.get(o);c!==void 0&&(!s.matches||n.open)&&(o.scrollTop=c)}};t.addEventListener("scroll",p,{passive:!0}),n.addEventListener("scroll",p,{passive:!0}),e.addEventListener("click",p,{capture:!0}),a.addEventListener("click",L),s.addEventListener("change",L),addEventListener("pagehide",p),L(),document.readyState==="complete"?r():addEventListener("load",r,{once:!0})};I();N();var f=document.querySelector("[data-cursor-face]");if(f){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,f.classList.remove("wg_shell__cursorFace--visible")},a=()=>{e.matches||n()},s=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,f.style.transform=`translate3d(
+                ${Math.max(0,Math.min(t.x+16,document.documentElement.clientWidth-f.width-16))}px,
+                ${Math.max(0,Math.min(t.y+16,document.documentElement.clientHeight-f.height-16))}px,
                 0
-            )`,g.classList.add("wg_shell__cursorFace--visible")}))},c=h=>{if(!(e.matches&&h.pointerType==="mouse")){n();return}t.x=h.clientX,t.y=h.clientY,d()},l=()=>{g.classList.contains("wg_shell__cursorFace--visible")&&d()},a=()=>{if(g.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(L,JSON.stringify({x:t.x,y:t.y}))}catch{}},u=()=>{try{let h=sessionStorage.getItem(L);if(sessionStorage.removeItem(L),h!==null&&e.matches){let r=JSON.parse(h);typeof r=="object"&&r!==null&&"x"in r&&"y"in r&&typeof r.x=="number"&&typeof r.y=="number"&&Number.isFinite(r.x)&&Number.isFinite(r.y)&&(t.x=r.x,t.y=r.y,d())}}catch{}};u(),document.addEventListener("pointermove",c,{passive:!0}),document.addEventListener("pointerdown",c,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",l),addEventListener("pagehide",a),addEventListener("pageshow",u),e.addEventListener("change",i)}var v=m(location.hash),_=null,y=0,f=null,x=()=>{clearTimeout(y),f?.abort(),f=null,_?.classList.remove("wg_prose__headingText--highlighted"),_=null},M=e=>{x(),_=e===null?null:e.querySelector(".wg_prose__headingText"),_!==null&&(_.classList.add("wg_prose__headingText--highlighted"),y=window.setTimeout(x,3e3),f=new AbortController,document.addEventListener("scrollend",B,{signal:f.signal}))},B=e=>{e.target===document&&(clearTimeout(y),f?.abort(),f=null,y=window.setTimeout(x,3e3))},N=e=>{if(!(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)&&e.currentTarget instanceof HTMLAnchorElement&&(e.currentTarget.target===""||e.currentTarget.target==="_self")&&!e.currentTarget.hasAttribute("download")&&e.currentTarget.origin===location.origin&&e.currentTarget.pathname===location.pathname&&e.currentTarget.search===location.search&&e.currentTarget.hash){let t=m(e.currentTarget.hash);e.currentTarget.hash===location.hash&&M(t)}},K=()=>{let e=m(location.hash);e?.scrollIntoView(),M(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",N);addEventListener("hashchange",K);var E=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=p(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(i=>{let d=p(i.hash),c=i.parentElement;return d&&c?[{heading:d,link:i,item:c}]:[]})}]}),w=E.at(0);if(w){let e=()=>{let t=Number.parseFloat(getComputedStyle(w.heading).scrollMarginTop)+1,n=E.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t)??w,i=n.subs.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t),d=E.indexOf(n),c=i===void 0?-1:n.subs.indexOf(i);for(let[l,a]of E.entries()){let u=a===n&&i===void 0;a.link.classList.toggle("wg_shellToc__link--active",u),u?a.link.setAttribute("aria-current","location"):a.link.removeAttribute("aria-current"),a.item.classList.toggle("wg_shellToc__item--trail",a.list===n.list&&l<d),a.item.classList.toggle("wg_shellToc__item--current",a===n);for(let[h,r]of a.subs.entries())r.link.classList.toggle("wg_shellToc__subLink--active",r===i),r===i?r.link.setAttribute("aria-current","location"):r.link.removeAttribute("aria-current"),r.item.classList.toggle("wg_shellToc__subItem--trail",a===n&&h<c),r.item.classList.toggle("wg_shellToc__subItem--current",r===i)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var I=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>I.abort(),{once:!0,passive:!0});var A=async()=>{await document.fonts.ready,v&&!I.signal.aborted&&(v.scrollIntoView({behavior:"instant"}),M(v)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?A():addEventListener("load",A,{once:!0});
+            )`,f.classList.add("wg_shell__cursorFace--visible")}))},u=g=>{if(!(e.matches&&g.pointerType==="mouse")){n();return}t.x=g.clientX,t.y=g.clientY,s()},d=()=>{f.classList.contains("wg_shell__cursorFace--visible")&&s()},l=()=>{if(f.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(T,JSON.stringify({x:t.x,y:t.y}))}catch{}},m=()=>{try{let g=sessionStorage.getItem(T);if(sessionStorage.removeItem(T),g!==null&&e.matches){let i=JSON.parse(g);typeof i=="object"&&i!==null&&"x"in i&&"y"in i&&typeof i.x=="number"&&typeof i.y=="number"&&Number.isFinite(i.x)&&Number.isFinite(i.y)&&(t.x=i.x,t.y=i.y,s())}}catch{}};m(),document.addEventListener("pointermove",u,{passive:!0}),document.addEventListener("pointerdown",u,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",d),addEventListener("pagehide",l),addEventListener("pageshow",m),e.addEventListener("change",a)}var k=y(location.hash),E=null,S=0,v=null,C=()=>{clearTimeout(S),v?.abort(),v=null,E?.classList.remove("wg_prose__headingText--highlighted"),E=null},q=e=>{C(),E=e===null?null:e.querySelector(".wg_prose__headingText"),E!==null&&(E.classList.add("wg_prose__headingText--highlighted"),S=window.setTimeout(C,3e3),v=new AbortController,document.addEventListener("scrollend",P,{signal:v.signal}))},P=e=>{e.target===document&&(clearTimeout(S),v?.abort(),v=null,S=window.setTimeout(C,3e3))},R=e=>{if(!(e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)&&e.currentTarget instanceof HTMLAnchorElement&&(e.currentTarget.target===""||e.currentTarget.target==="_self")&&!e.currentTarget.hasAttribute("download")&&e.currentTarget.origin===location.origin&&e.currentTarget.pathname===location.pathname&&e.currentTarget.search===location.search&&e.currentTarget.hash){let t=y(e.currentTarget.hash);e.currentTarget.hash===location.hash&&q(t)}},$=()=>{let e=y(location.hash);e?.scrollIntoView(),q(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",R);addEventListener("hashchange",$);var H=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=b(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(a=>{let s=b(a.hash),u=a.parentElement;return s&&u?[{heading:s,link:a,item:u}]:[]})}]}),A=H.at(0);if(A){let e=()=>{let t=Number.parseFloat(getComputedStyle(A.heading).scrollMarginTop)+1,n=H.findLast(d=>d.heading.checkVisibility()&&d.heading.getBoundingClientRect().top<=t)??A,a=n.subs.findLast(d=>d.heading.checkVisibility()&&d.heading.getBoundingClientRect().top<=t),s=H.indexOf(n),u=a===void 0?-1:n.subs.indexOf(a);for(let[d,l]of H.entries()){let m=l===n&&a===void 0;l.link.classList.toggle("wg_shellToc__link--active",m),m?l.link.setAttribute("aria-current","location"):l.link.removeAttribute("aria-current"),l.item.classList.toggle("wg_shellToc__item--trail",l.list===n.list&&d<s),l.item.classList.toggle("wg_shellToc__item--current",l===n);for(let[g,i]of l.subs.entries())i.link.classList.toggle("wg_shellToc__subLink--active",i===a),i===a?i.link.setAttribute("aria-current","location"):i.link.removeAttribute("aria-current"),i.item.classList.toggle("wg_shellToc__subItem--trail",l===n&&g<u),i.item.classList.toggle("wg_shellToc__subItem--current",i===a)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var K=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>K.abort(),{once:!0,passive:!0});var F=async()=>{await document.fonts.ready,k&&!K.signal.aborted&&(k.scrollIntoView({behavior:"instant"}),q(k)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?F():addEventListener("load",F,{once:!0});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.4.0",
+    "version": "0.4.2",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",
@@ -41,7 +41,7 @@
         "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build templates/document",
         "build:pages": "pnpm build && node util/prepare-pages.mjs",
         "preview": "node dist/cli.js preview templates/document",
-        "test": "esbuild src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
+        "test": "esbuild src/util/async/to-change-queue.test.ts src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/util/async/*.test.mjs node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
         "lint": "biome check && stylelint \"src/**/*.css\"",
         "lint:fix": "biome check --write && stylelint \"src/**/*.css\" --fix",
         "typecheck": "tsc --noEmit",

package/src/cli.ts

@@ -11,11 +11,12 @@ import {basename, dirname, extname, join, relative, resolve, sep} from "node:pat
 import {fileURLToPath, pathToFileURL} from "node:url";
 import {serve} from "@hono/node-server";
 import {serveStatic} from "@hono/node-server/serve-static";
+import {debounce} from "es-toolkit";
 import {Hono} from "hono";
 import {toSSG} from "hono/ssg";
 import {createApp} from "@/app";
 import {asset_client_path, asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
-import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port} from "@/constant/cli";
+import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port, cli_reload_delay_ms} from "@/constant/cli";
 import {copy_error_config, copy_error_font_preload, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
 import {font_brand_css, font_cache_control, font_mono_css, font_sans_css, font_sans_preload_file} from "@/constant/font";
 import {site_config_absent} from "@/constant/site";
@@ -24,6 +25,7 @@ import {readDocs} from "@/content/read-docs";
 import {readHome} from "@/content/read-home";
 import {createDevApp} from "@/dev";
 import {siteConfigSchema} from "@/type/site-config";
+import {toChangeQueue} from "@/util/async/to-change-queue";
 import {toErrorMessage} from "@/util/error/to-error-message";
 import {toAssetPath} from "@/util/file/to-asset-path";
 import {toFontCss} from "@/util/font/to-font-css";
@@ -129,40 +131,46 @@ const main = async () => {
     serve({fetch: createDevApp({pages: app, files, reload}).fetch, port: cli_dev_port}, (info) => console.log(`http://localhost:${info.port}/`));
 
     /**
-     * Markdown 변경 시 전체 재처리와 새로고침
-     * 재처리 실패 시 직전 정상 문서 유지
+     * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
+     * 문서 수가 많아도 파일 이벤트마다 전체 렌더링이 동시에 쌓이지 않음
      */
-    const handleDocsChange = async (_event: string, filename: string | null) => {
+    const reloadDocs = debounce(
+        toChangeQueue({
+            run: async () => {
+                const currentGeneration = generation;
+                const nextFiles = new Map(kitFiles);
+                const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
+                const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
+
+                if (currentGeneration !== generation) {
+                    return;
+                }
+
+                files.clear();
+                for (const entry of nextFiles) {
+                    files.set(...entry);
+                }
+                store.docs = docs;
+                store.home = home;
+                reload.emit("change");
+            },
+            onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`),
+        }),
+        cli_reload_delay_ms,
+    );
+
+    /**
+     * 입력 변경 감지 · 출력·설치 폴더 제외 · 누락 자원 추가도 다시 확인
+     */
+    const handleDocsChange = (_event: string, filename: string | null) => {
         if (filename !== null) {
             const segments = filename.split(sep);
-            // 출력·설치 폴더는 제외 · 실패한 참조의 파일이 뒤늦게 생겨도 다시 처리
             if (segments.includes("dist") || segments.includes("node_modules") || (!/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))) {
                 return;
             }
         }
-
-        const currentGeneration = ++generation;
-
-        try {
-            const nextFiles = new Map(kitFiles);
-            const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
-            const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
-
-            // 최신 변경의 처리 결과만 반영
-            if (currentGeneration !== generation) {
-                return;
-            }
-
-            files.clear();
-            for (const entry of nextFiles) {
-                files.set(...entry);
-            }
-            store.docs = docs;
-            store.home = home;
-            reload.emit("change");
-        } catch (error) {
-            console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
-        }
+        generation += 1;
+        reloadDocs();
     };
 
     watch(docsRoot, {recursive: true}, handleDocsChange);

package/src/client.ts

@@ -7,10 +7,12 @@ import {heading_highlight_hold_ms} from "@/component/widget/prose/_constant/head
 import {cursor_face_offset_px, cursor_face_storage_key} from "@/component/widget/shell/_constant/cursor-face";
 import {reading_line_slack_px} from "@/component/widget/shell/_constant/reading-line";
 import {bindMobileNavigation} from "@/component/widget/shell/_function/bind-mobile-navigation";
+import {bindNavigationScroll} from "@/component/widget/shell/_function/bind-navigation-scroll";
 import {findHashTarget} from "@/util/dom/find-hash-target";
 import {revealHashTarget} from "@/util/dom/reveal-hash-target";
 
 bindMobileNavigation();
+bindNavigationScroll();
 
 const cursorFace = document.querySelector<HTMLImageElement>("[data-cursor-face]");
 

package/src/component/widget/shell/_constant/navigation.ts

@@ -2,3 +2,8 @@
  * 모바일 탐색 전환 · wg-shell.css의 폭 조건과 일치
  */
 export const navigation_mobile_query = "(width < 1024px)";
+
+/**
+ * 같은 탭에서 문서 이동 후 탐색 위치 복원 · 데스크톱과 드로어는 별도 저장
+ */
+export const navigation_scroll_storage_key = "for-humanity:navigation-scroll";

package/src/component/widget/shell/_function/bind-navigation-scroll.ts

@@ -0,0 +1,123 @@
+import {navigation_mobile_query, navigation_scroll_storage_key} from "@/component/widget/shell/_constant/navigation";
+
+/**
+ * 문서 이동·새로고침에서 공유 탐색의 위치 유지 · 본문 스크롤과 독립
+ * 저장소 실패는 기본 탐색 유지, 문서 목록 변경은 이전 위치를 사용하지 않음
+ */
+export const bindNavigationScroll = () => {
+    const navigation = document.querySelector<HTMLElement>("[data-navigation]");
+    const sidebar = document.querySelector<HTMLElement>(".wg_shell__sidebar");
+    const dialog = document.querySelector<HTMLDialogElement>("[data-navigation-drawer]");
+    const openButton = document.querySelector<HTMLButtonElement>("[data-navigation-open]");
+
+    if (!navigation || !sidebar || !dialog || !openButton) {
+        return;
+    }
+
+    const mobile = matchMedia(navigation_mobile_query);
+    const layout = {mobile: mobile.matches};
+    // 목차와 현재 상태는 페이지마다 바뀜 · 공통 문서 링크의 순서로 저장 위치의 유효성 판단
+    const signature = [...navigation.querySelectorAll<HTMLAnchorElement>(".wg_shellNav__root a[href]")].map((link) => `${link.pathname}:${link.textContent}`).join("\n");
+    const positions = new Map<HTMLElement, number>();
+    const storageKeys = new Map<HTMLElement, string>([
+        [sidebar, `${navigation_scroll_storage_key}:desktop`],
+        [dialog, `${navigation_scroll_storage_key}:drawer`],
+    ]);
+    const userInput = new AbortController();
+
+    for (const [port, key] of storageKeys) {
+        try {
+            const value = sessionStorage.getItem(key);
+
+            if (value !== null) {
+                const stored: unknown = JSON.parse(value);
+
+                if (
+                    typeof stored === "object" &&
+                    stored !== null &&
+                    "navigation" in stored &&
+                    stored.navigation === signature &&
+                    "top" in stored &&
+                    typeof stored.top === "number" &&
+                    Number.isFinite(stored.top) &&
+                    stored.top >= 0
+                ) {
+                    positions.set(port, stored.top);
+                }
+            }
+        } catch {
+            // 차단되거나 손상된 저장소는 복원만 생략 · 스크롤과 기본 링크 이동 유지
+        }
+
+        for (const type of ["wheel", "touchstart", "pointerdown", "keydown"]) {
+            port.addEventListener(type, () => userInput.abort(), {once: true, passive: true});
+        }
+    }
+    const initialPositions = new Map(positions);
+
+    /**
+     * 네이티브 스크롤 범위로 복원 · 닫힌 드로어의 0 좌표는 복원하지 않음
+     */
+    const restoreScroll = () => {
+        layout.mobile = mobile.matches;
+        const port = mobile.matches ? dialog : sidebar;
+        const top = positions.get(port);
+
+        if (top === undefined || (mobile.matches && !dialog.open)) {
+            return;
+        }
+
+        port.scrollTop = top;
+    };
+
+    /**
+     * 드로어 닫기 이전 클릭·현재 스크롤·페이지 이탈에서 마지막 탐색 위치 저장
+     */
+    const saveScroll = (event: Event) => {
+        const port = mobile.matches ? dialog : sidebar;
+        const key = storageKeys.get(port);
+
+        // 반응형 전환의 숨김·닫기 스크롤은 사용자 위치가 아님 · 활성 포트만 저장
+        if (layout.mobile !== mobile.matches || (event.type === "scroll" && event.currentTarget !== port) || key === undefined || (mobile.matches && !dialog.open)) {
+            return;
+        }
+
+        positions.set(port, port.scrollTop);
+
+        try {
+            sessionStorage.setItem(key, JSON.stringify({navigation: signature, top: port.scrollTop}));
+        } catch {
+            // 저장 실패도 같은 페이지의 드로어 재열기와 반응형 위치 복원은 유지
+        }
+    };
+
+    /**
+     * 글꼴로 탐색 높이가 달라진 경우 한 번만 재보정 · 사용자 입력이 먼저면 유지
+     */
+    const settleScroll = async () => {
+        await document.fonts.ready;
+
+        if (!userInput.signal.aborted) {
+            const port = mobile.matches ? dialog : sidebar;
+            const top = initialPositions.get(port);
+
+            if (top !== undefined && (!mobile.matches || dialog.open)) {
+                port.scrollTop = top;
+            }
+        }
+    };
+
+    sidebar.addEventListener("scroll", saveScroll, {passive: true});
+    dialog.addEventListener("scroll", saveScroll, {passive: true});
+    navigation.addEventListener("click", saveScroll, {capture: true});
+    openButton.addEventListener("click", restoreScroll);
+    mobile.addEventListener("change", restoreScroll);
+    addEventListener("pagehide", saveScroll);
+    restoreScroll();
+
+    if (document.readyState === "complete") {
+        settleScroll();
+    } else {
+        addEventListener("load", settleScroll, {once: true});
+    }
+};

package/src/component/widget/shell/wg-shell.css

@@ -115,7 +115,34 @@
     max-height: 100vh;
     margin-inline-end: var(--app-space-sidebar-gap);
     overflow-y: auto;
+    overscroll-behavior-y: contain;
+
+    /* 얇은 네이티브 손잡이 · 트랙 없이 기존 본문 간격 안쪽에 표시 */
+    scrollbar-gutter: stable;
+    scrollbar-width: auto;
+    scrollbar-color: auto;
     scroll-padding-block: var(--app-size-brand) var(--app-space-block);
+
+    &::-webkit-scrollbar {
+        width: 3px;
+    }
+
+    &::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    &::-webkit-scrollbar-thumb {
+        border-radius: 3px;
+        background: transparent;
+    }
+
+    &:hover::-webkit-scrollbar-thumb {
+        background: var(--app-color-border-soft);
+    }
+
+    &:focus-within::-webkit-scrollbar-thumb {
+        background: var(--app-color-border-soft);
+    }
 }
 
 .wg_shell__navigation {
@@ -147,9 +174,33 @@
     border-right: 1px solid var(--app-color-border-layout);
     background: var(--app-color-ground);
     color: var(--app-color-text);
+    scrollbar-gutter: stable;
+    scrollbar-width: auto;
+    scrollbar-color: auto;
     overscroll-behavior: contain;
     scroll-padding-block: var(--app-size-mobile-header) var(--app-space-group);
 
+    &::-webkit-scrollbar {
+        width: 3px;
+    }
+
+    &::-webkit-scrollbar-track {
+        background: transparent;
+    }
+
+    &::-webkit-scrollbar-thumb {
+        border-radius: 3px;
+        background: transparent;
+    }
+
+    &:hover::-webkit-scrollbar-thumb {
+        background: var(--app-color-border-soft);
+    }
+
+    &:focus-within::-webkit-scrollbar-thumb {
+        background: var(--app-color-border-soft);
+    }
+
     &::backdrop {
         background: var(--app-color-backdrop);
     }
@@ -219,6 +270,45 @@
     visibility: visible;
 }
 
+/* Firefox는 표준 thin 사용 · 손잡이 폭은 브라우저가 결정 */
+@supports not selector(::-webkit-scrollbar) {
+    .wg_shell__sidebar {
+        scrollbar-width: thin;
+        scrollbar-color: transparent transparent;
+
+        &:hover {
+            scrollbar-color: var(--app-color-border-soft) transparent;
+        }
+
+        &:focus-within {
+            scrollbar-color: var(--app-color-border-soft) transparent;
+        }
+    }
+
+    .wg_shell__drawer {
+        scrollbar-width: thin;
+        scrollbar-color: var(--app-color-border-soft) transparent;
+    }
+}
+
+/* 색상 강제 환경은 시스템 손잡이 유지 · 대비 설정을 덮어쓰지 않음 */
+@media (forced-colors: active) {
+    .wg_shell__sidebar {
+        scrollbar-width: auto;
+        scrollbar-color: auto;
+
+        &::-webkit-scrollbar-thumb {
+            background: CanvasText;
+        }
+    }
+
+    .wg_shell__drawer {
+        &::-webkit-scrollbar-thumb {
+            background: CanvasText;
+        }
+    }
+}
+
 /* 좁은 화면 · 상단 브랜드와 메뉴 버튼 · 탐색 목록은 네이티브 모달 */
 @media (width < 1024px) {
     .wg_shell__root {

package/src/constant/cli.ts

@@ -17,3 +17,8 @@ export const cli_config_file_name = "for-humanity.config.mjs";
  * dev·preview 공통 포트
  */
 export const cli_dev_port = 4321;
+
+/**
+ * 연속 저장을 하나의 문서 갱신으로 합치는 대기 시간 · ms
+ */
+export const cli_reload_delay_ms = 150;

package/src/util/async/to-change-queue.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import {test} from "node:test";
+import {toChangeQueue} from "@/util/async/to-change-queue";
+
+test("coalesces changes during an active render and never overlaps work", async () => {
+    const gate = Promise.withResolvers<void>();
+    const renders: number[] = [];
+    const errors: unknown[] = [];
+    let version = 1;
+    let running = 0;
+    const queue = toChangeQueue({
+        run: async () => {
+            running += 1;
+            assert.equal(running, 1);
+            const current = version;
+            if (current === 1) await gate.promise;
+            renders.push(current);
+            running -= 1;
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    for (const next of [2, 3, 4, 5]) {
+        version = next;
+        await queue();
+    }
+    gate.resolve();
+    await first;
+    assert.deepEqual(renders, [1, 5]);
+    assert.deepEqual(errors, []);
+});
+
+test("a failed render does not lose a queued recovery or block later edits", async () => {
+    const gate = Promise.withResolvers<void>();
+    const errors: unknown[] = [];
+    const renders: number[] = [];
+    let version = 1;
+    const queue = toChangeQueue({
+        run: async () => {
+            const current = version;
+            if (current === 1) {
+                await gate.promise;
+                throw new Error("Invalid source");
+            }
+            renders.push(current);
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    version = 2;
+    await queue();
+    gate.resolve();
+    await first;
+    version = 3;
+    await queue();
+    assert.deepEqual(renders, [2, 3]);
+    assert.equal(errors.length, 1);
+});

package/src/util/async/to-change-queue.ts

@@ -0,0 +1,43 @@
+/**
+ * 변경 재처리의 실행과 오류 보고 계약
+ */
+export interface ChangeQueueOptions {
+    /**
+     * 한 번의 최신 입력 처리 · 이전 실행이 끝난 뒤 호출
+     */
+    run: () => Promise<void>;
+    /**
+     * 실패 보고 · 대기 중인 변경과 다음 실행은 유지
+     */
+    onError: (error: unknown) => void;
+}
+
+/**
+ * 동시에 하나만 실행하는 변경 요청 함수 · 실행 중 요청은 다음 한 번으로 합침
+ * 활성 실행의 반환 Promise는 대기 요청까지 끝나면 완료, 중첩 요청은 즉시 반환
+ */
+export const toChangeQueue = (options: ChangeQueueOptions) => {
+    const state = {requested: 0, completed: 0, running: false};
+
+    return async () => {
+        state.requested += 1;
+        if (state.running) {
+            return;
+        }
+        state.running = true;
+        try {
+            while (state.completed !== state.requested) {
+                const requested = state.requested;
+                try {
+                    await options.run();
+                } catch (error) {
+                    options.onError(error);
+                } finally {
+                    state.completed = requested;
+                }
+            }
+        } finally {
+            state.running = false;
+        }
+    };
+};