for-humanity 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.4.4 — 2026-10-04
+
+- Keep the document list and page outline in separate native scroll areas, so a shorter outline cannot clamp the document list position.
+- Restore desktop document navigation before its first paint and avoid reinserting the same navigation DOM during startup.
+- Indicate remaining navigation content with conditional top and bottom fades, keeping native scrollbars in forced colors and without JavaScript.
+- Connect the active outline branch through its parent while highlighting only the exact current heading.
+
 ## 0.4.3 — 2026-10-04
 
 - Use standard native navigation scrollbars in forced-color mode so browser color adjustment cannot hide custom thumbs against the background.

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.3
+pnpm add -D --save-exact for-humanity@0.4.4
 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.3` 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.4` 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.3` 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.4` 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

@@ -448,9 +448,6 @@
 
 /* src/component/widget/shell/_wg-shell-toc.css */
 .wg_shellToc__root {
-  margin-top: var(--app-space-group);
-  padding-top: var(--app-space-group);
-  border-top: 1px solid var(--app-color-border-soft);
   font-size: var(--app-font-size-dense);
   line-height: var(--app-line-height-tight);
 }
@@ -565,6 +562,9 @@
   &::after {
     border-left-color: var(--app-color-text-strong);
   }
+  & > .wg_shellToc__link::before {
+    border-top-color: var(--app-color-text-strong);
+  }
 }
 .wg_shellToc__sub {
   margin: var(--app-space-tree-row) 0 4px var(--app-space-tree-indent);
@@ -754,6 +754,7 @@
   --app-size-mobile-header: 56px;
   --app-size-menu-button: 44px;
   --app-size-drawer: 320px;
+  --app-size-navigation-fade: 28px;
   --app-space-anchor: 80px;
   --app-radius-pill: 0;
   --app-radius-card: 0;
@@ -884,34 +885,64 @@
   top: 0;
   align-self: start;
   min-width: 0;
-  min-height: 100vh;
-  max-height: 100vh;
+  height: 100dvh;
   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 {
+  display: flex;
+  flex-direction: column;
+  height: calc(100dvh - var(--app-size-brand));
   min-width: 0;
+  min-height: 0;
+}
+.wg_shell__documents {
+  flex: none;
+  max-height: 60%;
+}
+.wg_shell__outline {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  margin-top: var(--app-space-group);
+  padding-top: var(--app-space-group);
+  border-top: 1px solid var(--app-color-border-soft);
+  &:has(.wg_shell__headings:empty) {
+    display: none;
+  }
+}
+.wg_shell__headings {
+  min-height: 0;
+}
+.wg_shell__scroll {
+  overflow-y: auto;
+  overscroll-behavior-y: contain;
+  scroll-padding-block: var(--app-size-navigation-fade);
+}
+.wg_shell__scroll--ready {
+  scrollbar-width: none;
+}
+.wg_shell__scroll--above {
+  mask-image:
+    linear-gradient(
+      to bottom,
+      transparent,
+      #000 var(--app-size-navigation-fade));
+}
+.wg_shell__scroll--below {
+  mask-image:
+    linear-gradient(
+      to bottom,
+      #000 calc(100% - var(--app-size-navigation-fade)),
+      transparent);
+}
+.wg_shell__scroll--above.wg_shell__scroll--below {
+  mask-image:
+    linear-gradient(
+      to bottom,
+      transparent,
+      #000 var(--app-size-navigation-fade),
+      #000 calc(100% - var(--app-size-navigation-fade)),
+      transparent);
 }
 .wg_shell__main {
   grid-area: main;
@@ -934,35 +965,12 @@
   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);
-  }
+  overflow: hidden;
   &::backdrop {
     background: var(--app-color-backdrop);
   }
 }
 .wg_shell__drawerHeader {
-  position: sticky;
-  top: 0;
-  z-index: var(--app-z-index-sticky);
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -999,6 +1007,10 @@
 }
 .wg_shell__drawerContent {
   min-width: 0;
+  height: calc(100% - var(--app-size-mobile-header) - var(--app-space-block));
+  & > .wg_shell__navigation {
+    height: 100%;
+  }
 }
 .wg_shell__cursorFace {
   position: fixed;
@@ -1013,42 +1025,11 @@
 .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 {
+  .wg_shell__scroll {
+    mask-image: none;
     scrollbar-width: thin;
     scrollbar-color: auto;
-    &:hover {
-      scrollbar-color: auto;
-    }
-    &:focus-within {
-      scrollbar-color: auto;
-    }
-  }
-  .wg_shell__drawer {
-    scrollbar-width: thin;
-    scrollbar-color: auto;
-    &:hover {
-      scrollbar-color: auto;
-    }
-    &:focus-within {
-      scrollbar-color: auto;
-    }
   }
 }
 @media (width < 1024px) {
@@ -1058,13 +1039,17 @@
   }
   .wg_shell__sidebar {
     position: static;
-    min-height: 0;
-    max-height: none;
-    overflow-y: visible;
+    height: auto;
     margin-block-end: var(--app-space-block);
     margin-inline-end: 0;
     border-bottom: 1px solid var(--app-color-border-layout);
   }
+  .wg_shell__sidebar > .wg_shell__navigation {
+    height: auto;
+    & > .wg_shell__documents {
+      max-height: none;
+    }
+  }
   .wg_shell__sidebar--navigationReady {
     position: sticky;
     top: 0;

package/dist/cli.js

@@ -33,6 +33,68 @@ var WgProse = (props) => {
 // src/component/widget/shell/wg-shell.tsx
 import clsx5 from "clsx";
 
+// src/component/widget/shell/_constant/navigation.ts
+var navigation_mobile_query = "(width < 1024px)";
+var navigation_scroll_storage_key = "for-humanity:navigation-scroll";
+
+// src/component/widget/shell/_function/bind-navigation-overflow.ts
+var bindNavigationOverflow = () => {
+  const ports = [...document.querySelectorAll("[data-navigation-scroll]")];
+  const frame = { id: 0 };
+  const edgeTolerance = 1;
+  const updateOverflow = () => {
+    frame.id = 0;
+    for (const port of ports) {
+      port.classList.add("wg_shell__scroll--ready");
+      port.classList.toggle("wg_shell__scroll--above", port.scrollTop > edgeTolerance);
+      port.classList.toggle("wg_shell__scroll--below", port.scrollHeight - port.clientHeight - port.scrollTop > edgeTolerance);
+    }
+  };
+  const scheduleOverflow = () => {
+    if (frame.id === 0) {
+      frame.id = requestAnimationFrame(updateOverflow);
+    }
+  };
+  const observer = new ResizeObserver(scheduleOverflow);
+  for (const port of ports) {
+    port.addEventListener("scroll", scheduleOverflow, { passive: true });
+    observer.observe(port);
+    if (port.firstElementChild) {
+      observer.observe(port.firstElementChild);
+    }
+  }
+  addEventListener("pageshow", scheduleOverflow);
+  updateOverflow();
+};
+
+// src/component/widget/shell/_function/restore-navigation-scroll.ts
+var restoreNavigationScroll = (storageKey) => {
+  const navigation = document.querySelector("[data-navigation]");
+  const documents = document.querySelector('[data-navigation-scroll="documents"]');
+  const outline = document.querySelector('[data-navigation-scroll="outline"]');
+  if (!navigation || !documents || !outline) {
+    return;
+  }
+  try {
+    const value = sessionStorage.getItem(storageKey);
+    if (value === null) {
+      return;
+    }
+    const stored = JSON.parse(value);
+    const signature = [...navigation.querySelectorAll(".wg_shellNav__root a[href]")].map((link) => `${link.pathname}:${link.textContent}`).join("\n");
+    if (typeof stored !== "object" || stored === null || !("navigation" in stored) || stored.navigation !== signature) {
+      return;
+    }
+    if ("documents" in stored && typeof stored.documents === "number" && Number.isFinite(stored.documents) && stored.documents >= 0) {
+      documents.scrollTop = stored.documents;
+    }
+    if ("pathname" in stored && stored.pathname === location.pathname && "outline" in stored && typeof stored.outline === "number" && Number.isFinite(stored.outline) && stored.outline >= 0) {
+      outline.scrollTop = stored.outline;
+    }
+  } catch {
+  }
+};
+
 // src/component/widget/shell/_function/to-toc-groups.ts
 import { takeWhile } from "es-toolkit/array";
 
@@ -263,6 +325,7 @@ var asset_media_extensions = /* @__PURE__ */ new Set([".svg", ".png", ".jpg", ".
 // src/component/widget/shell/wg-shell.tsx
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 var reloadScript = `new EventSource(${JSON.stringify(asset_reload_path)}).onmessage=function(){location.reload()}`;
+var navigationScript = `(${bindNavigationOverflow.toString()})();if(!matchMedia(${JSON.stringify(navigation_mobile_query)}).matches){(${restoreNavigationScroll.toString()})(${JSON.stringify(`${navigation_scroll_storage_key}:desktop`)})}`;
 var WgShell = (props) => {
   const tocGroups = props.outline === void 0 ? [] : toTocGroups(props.outline);
   return /* @__PURE__ */ jsxs5("html", { lang: "ko", children: [
@@ -296,10 +359,11 @@ var WgShell = (props) => {
           )
         ] }),
         /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__navigation"), "data-navigation": "", children: [
-          /* @__PURE__ */ jsx5(WgShellNav, { site: props.site, docs: props.docs, current: props.current }),
-          tocGroups.length > 0 && /* @__PURE__ */ jsx5(WgShellToc, { groups: tocGroups })
+          /* @__PURE__ */ jsx5("div", { className: clsx5("wg_shell__documents", "wg_shell__scroll"), "data-navigation-scroll": "documents", children: /* @__PURE__ */ jsx5(WgShellNav, { site: props.site, docs: props.docs, current: props.current }) }),
+          /* @__PURE__ */ jsx5("div", { className: clsx5("wg_shell__outline"), children: /* @__PURE__ */ jsx5("div", { className: clsx5("wg_shell__headings", "wg_shell__scroll"), "data-navigation-scroll": "outline", children: tocGroups.length > 0 && /* @__PURE__ */ jsx5(WgShellToc, { groups: tocGroups }) }) })
         ] })
       ] }),
+      /* @__PURE__ */ jsx5("script", { dangerouslySetInnerHTML: { __html: navigationScript } }),
       /* @__PURE__ */ jsx5("main", { className: clsx5("wg_shell__main"), children: props.children }),
       /* @__PURE__ */ jsxs5("dialog", { className: clsx5("wg_shell__drawer"), id: "fh-navigation-drawer", "aria-labelledby": "fh-navigation-title", "data-navigation-drawer": "", children: [
         /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__drawerHeader"), children: [
@@ -1018,8 +1082,8 @@ var rehypeAssets = (options) => (tree, file) => {
       return;
     }
     const target = resolve2(dirname2(file.path), path);
-    const location = relative2(options.root, target);
-    if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+    const location2 = relative2(options.root, target);
+    if (location2 === ".." || location2.startsWith(`..${sep}`) || isAbsolute(location2)) {
       file.fail(`${copy_error_asset}: \uBB38\uC11C \uD3F4\uB354 \uBC16 \xB7 ${url}`, node);
     }
     if (!existsSync2(target)) {

package/dist/client.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.4.3",
+    "version": "0.4.4",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",

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

@@ -107,7 +107,10 @@ export const bindMobileNavigation = () => {
 
         if (mobile.matches) {
             openButton.classList.add("wg_shell__menuToggle--visible");
-            content.append(navigation);
+
+            if (navigation.parentElement !== content) {
+                content.append(navigation);
+            }
 
             if (focused instanceof HTMLElement && navigation.contains(focused)) {
                 openButton.focus({preventScroll: true});
@@ -117,7 +120,11 @@ export const bindMobileNavigation = () => {
         }
 
         closeNavigation();
-        sidebar.append(navigation);
+
+        // 첫 desktop 연결에서 같은 DOM을 재삽입하면 내부 스크롤이 0으로 초기화됨
+        if (navigation.parentElement !== sidebar) {
+            sidebar.append(navigation);
+        }
 
         if (focused instanceof HTMLElement && navigation.contains(focused)) {
             focused.focus({preventScroll: true});

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

@@ -0,0 +1,47 @@
+/**
+ * 실제 남은 내용이 있는 위·아래 끝만 흐림 표시 · 스크롤·글꼴·화면 크기 추적
+ * HTML 직후 직렬화해 실행하므로 import나 바깥 변수 없이 브라우저 DOM만 사용
+ * 관찰자는 문서 수명 동안 유지 · BFCache 복귀에서도 같은 탐색 DOM 추적
+ */
+export const bindNavigationOverflow = () => {
+    const ports = [...document.querySelectorAll<HTMLElement>("[data-navigation-scroll]")];
+    const frame = {id: 0};
+    // 소수 픽셀 반올림으로 끝에서 흐림이 남는 것을 방지
+    const edgeTolerance = 1;
+
+    /**
+     * 콘텐츠가 잘리는 끝만 표시 · 네이티브 스크롤은 그대로 사용
+     */
+    const updateOverflow = () => {
+        frame.id = 0;
+
+        for (const port of ports) {
+            port.classList.add("wg_shell__scroll--ready");
+            port.classList.toggle("wg_shell__scroll--above", port.scrollTop > edgeTolerance);
+            port.classList.toggle("wg_shell__scroll--below", port.scrollHeight - port.clientHeight - port.scrollTop > edgeTolerance);
+        }
+    };
+
+    /**
+     * 연속 스크롤과 크기 변경은 프레임당 한 번만 반영
+     */
+    const scheduleOverflow = () => {
+        if (frame.id === 0) {
+            frame.id = requestAnimationFrame(updateOverflow);
+        }
+    };
+
+    const observer = new ResizeObserver(scheduleOverflow);
+
+    for (const port of ports) {
+        port.addEventListener("scroll", scheduleOverflow, {passive: true});
+        observer.observe(port);
+
+        if (port.firstElementChild) {
+            observer.observe(port.firstElementChild);
+        }
+    }
+
+    addEventListener("pageshow", scheduleOverflow);
+    updateOverflow();
+};

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

@@ -1,123 +1,84 @@
 import {navigation_mobile_query, navigation_scroll_storage_key} from "@/component/widget/shell/_constant/navigation";
+import {restoreNavigationScroll} from "@/component/widget/shell/_function/restore-navigation-scroll";
 
 /**
- * 문서 이동·새로고침에서 공유 탐색의 위치 유지 · 본문 스크롤과 독립
- * 저장소 실패는 기본 탐색 유지, 문서 목록 변경은 이전 위치를 사용하지 않음
+ * 문서 목록과 페이지 목차의 위치를 따로 저장 · TOC 길이가 목록 위치를 바꾸지 않음
+ * 첫 데스크톱 복원은 HTML에서 완료 · 늦은 module 실행에서 다시 이동하지 않음
  */
 export const bindNavigationScroll = () => {
     const navigation = document.querySelector<HTMLElement>("[data-navigation]");
-    const sidebar = document.querySelector<HTMLElement>(".wg_shell__sidebar");
+    const documents = document.querySelector<HTMLElement>('[data-navigation-scroll="documents"]');
+    const outline = document.querySelector<HTMLElement>('[data-navigation-scroll="outline"]');
     const dialog = document.querySelector<HTMLDialogElement>("[data-navigation-drawer]");
     const openButton = document.querySelector<HTMLButtonElement>("[data-navigation-open]");
 
-    if (!navigation || !sidebar || !dialog || !openButton) {
+    if (!navigation || !documents || !outline || !dialog || !openButton) {
         return;
     }
 
     const mobile = matchMedia(navigation_mobile_query);
     const layout = {mobile: mobile.matches};
-    // 목차와 현재 상태는 페이지마다 바뀜 · 공통 문서 링크의 순서로 저장 위치의 유효성 판단
+    const ports = [documents, outline];
+    const positions = new Map<string, Map<HTMLElement, number>>();
     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);
+    /**
+     * 숨김·닫기보다 먼저 마지막 위치 보존 · 저장소 차단 시에도 드로어 재열기 유지
+     */
+    const saveScroll = () => {
+        if (layout.mobile !== mobile.matches || (mobile.matches && !dialog.open)) {
+            return;
+        }
 
-            if (value !== null) {
-                const stored: unknown = JSON.parse(value);
+        const key = `${navigation_scroll_storage_key}:${mobile.matches ? "drawer" : "desktop"}`;
+        positions.set(key, new Map(ports.map((port) => [port, port.scrollTop])));
 
-                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);
-                }
-            }
+        try {
+            sessionStorage.setItem(key, JSON.stringify({navigation: signature, pathname: location.pathname, documents: documents.scrollTop, outline: outline.scrollTop}));
         } catch {
-            // 차단되거나 손상된 저장소는 복원만 생략 · 스크롤과 기본 링크 이동 유지
+            // 현재 페이지 안의 위치는 메모리에 유지 · 저장 실패가 링크 이동을 막지 않음
         }
-
-        for (const type of ["wheel", "touchstart", "pointerdown", "keydown"]) {
-            port.addEventListener(type, () => userInput.abort(), {once: true, passive: true});
-        }
-    }
-    const initialPositions = new Map(positions);
+    };
 
     /**
-     * 네이티브 스크롤 범위로 복원 · 닫힌 드로어의 0 좌표는 복원하지 않음
+     * 열기·반응형 DOM 이동 완료 후 화면별 위치 복원
      */
     const restoreScroll = () => {
         layout.mobile = mobile.matches;
-        const port = mobile.matches ? dialog : sidebar;
-        const top = positions.get(port);
 
-        if (top === undefined || (mobile.matches && !dialog.open)) {
+        if (mobile.matches && !dialog.open) {
             return;
         }
 
-        port.scrollTop = top;
-    };
+        const key = `${navigation_scroll_storage_key}:${mobile.matches ? "drawer" : "desktop"}`;
+        const saved = positions.get(key);
 
-    /**
-     * 드로어 닫기 이전 클릭·현재 스크롤·페이지 이탈에서 마지막 탐색 위치 저장
-     */
-    const saveScroll = (event: Event) => {
-        const port = mobile.matches ? dialog : sidebar;
-        const key = storageKeys.get(port);
+        if (saved === undefined) {
+            restoreNavigationScroll(key);
+        } else {
+            for (const port of ports) {
+                const top = saved.get(port);
 
-        // 반응형 전환의 숨김·닫기 스크롤은 사용자 위치가 아님 · 활성 포트만 저장
-        if (layout.mobile !== mobile.matches || (event.type === "scroll" && event.currentTarget !== port) || key === undefined || (mobile.matches && !dialog.open)) {
-            return;
+                if (top !== undefined) {
+                    port.scrollTop = top;
+                }
+            }
         }
 
-        positions.set(port, port.scrollTop);
-
-        try {
-            sessionStorage.setItem(key, JSON.stringify({navigation: signature, top: port.scrollTop}));
-        } catch {
-            // 저장 실패도 같은 페이지의 드로어 재열기와 반응형 위치 복원은 유지
-        }
+        saveScroll();
     };
 
-    /**
-     * 글꼴로 탐색 높이가 달라진 경우 한 번만 재보정 · 사용자 입력이 먼저면 유지
-     */
-    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;
-            }
-        }
-    };
+    for (const port of ports) {
+        port.addEventListener("scroll", saveScroll, {passive: true});
+    }
 
-    sidebar.addEventListener("scroll", saveScroll, {passive: true});
-    dialog.addEventListener("scroll", saveScroll, {passive: true});
+    // 캡처 단계에서 모바일의 기본 닫기보다 먼저 저장
     navigation.addEventListener("click", saveScroll, {capture: true});
+    dialog.addEventListener("cancel", saveScroll);
+    dialog.querySelector("[data-navigation-close]")?.addEventListener("click", saveScroll, {capture: true});
+    dialog.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});
-    }
+    saveScroll();
 };

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

@@ -0,0 +1,47 @@
+/**
+ * 탐색 HTML 직후와 드로어 열기에서 저장 위치 복원 · 첫 paint 전 실행
+ * HTML에 함수 본문을 직렬화하므로 import나 바깥 변수 없이 브라우저 DOM만 사용
+ * @param storageKey 탭·화면 모드별 저장 키
+ */
+export const restoreNavigationScroll = (storageKey: string) => {
+    const navigation = document.querySelector<HTMLElement>("[data-navigation]");
+    const documents = document.querySelector<HTMLElement>('[data-navigation-scroll="documents"]');
+    const outline = document.querySelector<HTMLElement>('[data-navigation-scroll="outline"]');
+
+    if (!navigation || !documents || !outline) {
+        return;
+    }
+
+    try {
+        const value = sessionStorage.getItem(storageKey);
+
+        if (value === null) {
+            return;
+        }
+
+        const stored: unknown = JSON.parse(value);
+        const signature = [...navigation.querySelectorAll<HTMLAnchorElement>(".wg_shellNav__root a[href]")].map((link) => `${link.pathname}:${link.textContent}`).join("\n");
+
+        if (typeof stored !== "object" || stored === null || !("navigation" in stored) || stored.navigation !== signature) {
+            return;
+        }
+
+        if ("documents" in stored && typeof stored.documents === "number" && Number.isFinite(stored.documents) && stored.documents >= 0) {
+            documents.scrollTop = stored.documents;
+        }
+
+        // 문서 목록은 공통 위치 · 목차는 같은 페이지에 다시 들어왔을 때만 복원
+        if (
+            "pathname" in stored &&
+            stored.pathname === location.pathname &&
+            "outline" in stored &&
+            typeof stored.outline === "number" &&
+            Number.isFinite(stored.outline) &&
+            stored.outline >= 0
+        ) {
+            outline.scrollTop = stored.outline;
+        }
+    } catch {
+        // 차단·손상된 저장소는 복원만 생략 · 기본 링크와 스크롤 유지
+    }
+};

package/src/component/widget/shell/_wg-shell-toc.css

@@ -2,9 +2,6 @@
  * 문서 탐색 아래 목차 · 회색 제목·묶음과 본문 글색의 이동 대상 구분
  */
 .wg_shellToc__root {
-    margin-top: var(--app-space-group);
-    padding-top: var(--app-space-group);
-    border-top: 1px solid var(--app-color-border-soft);
     font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
 }
@@ -150,6 +147,11 @@
     &::after {
         border-left-color: var(--app-color-text-strong);
     }
+
+    /* 현재 소제목의 상위 절은 글 강조 없이 경로의 가로 가지 연결 */
+    & > .wg_shellToc__link::before {
+        border-top-color: var(--app-color-text-strong);
+    }
 }
 
 .wg_shellToc__sub {

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

@@ -27,7 +27,7 @@
 .wg_shell__brandRow {
     display: flex;
 
-    /* 공유 사이드바의 스크롤 기준 · 목록과 목차 위에서 이름 고정 */
+    /* 두 스크롤 영역 바깥 · 목록과 목차 위에서 이름 고정 */
     position: sticky;
     top: 0;
     z-index: var(--app-z-index-sticky);
@@ -103,50 +103,69 @@
     display: flex;
 }
 
+/* sticky 틀 안에서 문서 목록과 목차의 스크롤 높이를 독립 유지 */
 .wg_shell__sidebar {
     grid-area: nav;
-
-    /* 뷰포트 sticky · 문서 탐색과 목차는 이 컨테이너에서 함께 스크롤 */
     position: sticky;
     top: 0;
     align-self: start;
     min-width: 0;
-    min-height: 100vh;
-    max-height: 100vh;
+    height: 100dvh;
     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);
+.wg_shell__navigation {
+    display: flex;
+    flex-direction: column;
+    height: calc(100dvh - var(--app-size-brand));
+    min-width: 0;
+    min-height: 0;
+}
 
-    &::-webkit-scrollbar {
-        width: 3px;
-    }
+.wg_shell__documents {
+    /* TOC 길이가 바뀌어도 공통 목록의 스크롤 범위는 동일 */
+    flex: none;
+    max-height: 60%;
+}
 
-    &::-webkit-scrollbar-track {
-        background: transparent;
+.wg_shell__outline {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    margin-top: var(--app-space-group);
+    padding-top: var(--app-space-group);
+    border-top: 1px solid var(--app-color-border-soft);
+
+    &:has(.wg_shell__headings:empty) {
+        display: none;
     }
+}
 
-    &::-webkit-scrollbar-thumb {
-        border-radius: 3px;
-        background: transparent;
-    }
+.wg_shell__headings {
+    min-height: 0;
+}
 
-    &:hover::-webkit-scrollbar-thumb {
-        background: var(--app-color-border-soft);
-    }
+.wg_shell__scroll {
+    overflow-y: auto;
+    overscroll-behavior-y: contain;
+    scroll-padding-block: var(--app-size-navigation-fade);
+}
 
-    &:focus-within::-webkit-scrollbar-thumb {
-        background: var(--app-color-border-soft);
-    }
+.wg_shell__scroll--ready {
+    /* 흐림으로 넘침을 알릴 때만 손잡이 숨김 · JS 없으면 네이티브 손잡이 유지 */
+    scrollbar-width: none;
 }
 
-.wg_shell__navigation {
-    min-width: 0;
+.wg_shell__scroll--above {
+    mask-image: linear-gradient(to bottom, transparent, #000 var(--app-size-navigation-fade));
+}
+
+.wg_shell__scroll--below {
+    mask-image: linear-gradient(to bottom, #000 calc(100% - var(--app-size-navigation-fade)), transparent);
+}
+
+.wg_shell__scroll--above.wg_shell__scroll--below {
+    mask-image: linear-gradient(to bottom, transparent, #000 var(--app-size-navigation-fade), #000 calc(100% - var(--app-size-navigation-fade)), transparent);
 }
 
 .wg_shell__main {
@@ -174,32 +193,7 @@
     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);
-    }
+    overflow: hidden;
 
     &::backdrop {
         background: var(--app-color-backdrop);
@@ -207,10 +201,7 @@
 }
 
 .wg_shell__drawerHeader {
-    /* 스크롤하는 drawer 안에서 닫기 버튼 유지 */
-    position: sticky;
-    top: 0;
-    z-index: var(--app-z-index-sticky);
+    /* 두 스크롤 영역 바깥에서 닫기 버튼 유지 */
     display: flex;
     align-items: center;
     justify-content: space-between;
@@ -252,6 +243,11 @@
 
 .wg_shell__drawerContent {
     min-width: 0;
+    height: calc(100% - var(--app-size-mobile-header) - var(--app-space-block));
+
+    & > .wg_shell__navigation {
+        height: 100%;
+    }
 }
 
 .wg_shell__cursorFace {
@@ -270,54 +266,12 @@
     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 {
-        /* non-auto 표준 폭은 WebKit 전용 스타일을 비활성화해 네이티브 색상 유지 */
+    .wg_shell__scroll {
+        mask-image: none;
         scrollbar-width: thin;
         scrollbar-color: auto;
-
-        &:hover {
-            scrollbar-color: auto;
-        }
-
-        &:focus-within {
-            scrollbar-color: auto;
-        }
-    }
-
-    .wg_shell__drawer {
-        scrollbar-width: thin;
-        scrollbar-color: auto;
-
-        &:hover {
-            scrollbar-color: auto;
-        }
-
-        &:focus-within {
-            scrollbar-color: auto;
-        }
     }
 }
 
@@ -332,14 +286,20 @@
 
     .wg_shell__sidebar {
         position: static;
-        min-height: 0;
-        max-height: none;
-        overflow-y: visible;
+        height: auto;
         margin-block-end: var(--app-space-block);
         margin-inline-end: 0;
         border-bottom: 1px solid var(--app-color-border-layout);
     }
 
+    .wg_shell__sidebar > .wg_shell__navigation {
+        height: auto;
+
+        & > .wg_shell__documents {
+            max-height: none;
+        }
+    }
+
     .wg_shell__sidebar--navigationReady {
         /* 본문을 스크롤해도 메뉴 진입 유지 · 스크립트 없는 긴 목록에는 적용하지 않음 */
         position: sticky;

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

@@ -1,5 +1,8 @@
 import clsx from "clsx";
 import type {ReactNode} from "react";
+import {navigation_mobile_query, navigation_scroll_storage_key} from "@/component/widget/shell/_constant/navigation";
+import {bindNavigationOverflow} from "@/component/widget/shell/_function/bind-navigation-overflow";
+import {restoreNavigationScroll} from "@/component/widget/shell/_function/restore-navigation-scroll";
 import {toTocGroups} from "@/component/widget/shell/_function/to-toc-groups";
 import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
 import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
@@ -18,6 +21,12 @@ import "./wg-shell.css";
  */
 const reloadScript = `new EventSource(${JSON.stringify(asset_reload_path)}).onmessage=function(){location.reload()}`;
 
+/**
+ * 탐색 DOM 직후 동기 실행 · 큰 본문과 module 다운로드를 기다리지 않고 첫 위치·흐림 적용
+ * 손잡이 숨김으로 달라지는 목록 폭을 먼저 확정한 뒤 좌표 복원
+ */
+const navigationScript = `(${bindNavigationOverflow.toString()})();if(!matchMedia(${JSON.stringify(navigation_mobile_query)}).matches){(${restoreNavigationScroll.toString()})(${JSON.stringify(`${navigation_scroll_storage_key}:desktop`)})}`;
+
 /**
  * 공통 HTML 틀의 입력 · 문서 탐색·현재 목차·본문
  */
@@ -112,10 +121,23 @@ export const WgShell = (props: WgShellProps) => {
                      * 같은 탐색 DOM을 모바일 대화상자로 이동 · 스크립트 없이도 기본 목록 제공
                      */}
                     <div className={clsx("wg_shell__navigation")} data-navigation="">
-                        <WgShellNav site={props.site} docs={props.docs} current={props.current} />
-                        {tocGroups.length > 0 && <WgShellToc groups={tocGroups} />}
+                        {/**
+                         * 모든 페이지에서 같은 높이의 문서 탐색 · 목차 길이와 스크롤 분리
+                         */}
+                        <div className={clsx("wg_shell__documents", "wg_shell__scroll")} data-navigation-scroll="documents">
+                            <WgShellNav site={props.site} docs={props.docs} current={props.current} />
+                        </div>
+                        {/**
+                         * 문서 목록 아래 현재 페이지 목차 · 남은 뷰포트 안에서 독립 스크롤
+                         */}
+                        <div className={clsx("wg_shell__outline")}>
+                            <div className={clsx("wg_shell__headings", "wg_shell__scroll")} data-navigation-scroll="outline">
+                                {tocGroups.length > 0 && <WgShellToc groups={tocGroups} />}
+                            </div>
+                        </div>
                     </div>
                 </div>
+                <script dangerouslySetInnerHTML={{__html: navigationScript}} />
                 <main className={clsx("wg_shell__main")}>{props.children}</main>
                 {/**
                  * 브라우저의 모달 포커스·Escape 처리 · 목록은 한 번만 렌더링

package/src/style/token.css

@@ -109,6 +109,7 @@
     --app-size-mobile-header: 56px;
     --app-size-menu-button: 44px;
     --app-size-drawer: 320px;
+    --app-size-navigation-fade: 28px;
 
     /* 화면 위쪽 제목 여백 · hash 도착점과 목차 읽는 선의 공통 기준 */
     --app-space-anchor: 80px;