for-humanity 0.4.4 → 0.5.0

package/src/store/navigation/to-navigation-tree-state.ts

@@ -0,0 +1,19 @@
+import type {NavigationTreeState} from "@/store/navigation/navigation-state";
+
+/**
+ * persist 저장 자료에서 boolean 접힘 선택만 수용
+ */
+export const toNavigationTreeState = (value: unknown): NavigationTreeState => {
+    if (
+        typeof value !== "object" ||
+        value === null ||
+        !("collapsed" in value) ||
+        typeof value.collapsed !== "object" ||
+        value.collapsed === null ||
+        Array.isArray(value.collapsed)
+    ) {
+        return {collapsed: {}};
+    }
+
+    return {collapsed: Object.fromEntries(Object.entries(value.collapsed).filter((entry) => typeof entry[1] === "boolean"))};
+};

package/src/store/navigation/use-navigation-tree-store.ts

@@ -0,0 +1,12 @@
+import {useSyncExternalStore} from "hono/jsx";
+import {tree_server_state} from "@/store/navigation/_constant/tree";
+import type {createNavigationStores} from "@/store/navigation/create-navigation-stores";
+
+/**
+ * Hono 컴포넌트의 persist 구독 · 브라우저 최초 렌더도 저장된 값을 즉시 소비
+ */
+export const useNavigationTreeStore = (tree?: ReturnType<typeof createNavigationStores>["tree"]) => {
+    const subscribe = tree === undefined ? () => () => {} : tree.subscribe;
+    const getSnapshot = tree === undefined ? () => tree_server_state : tree.getState;
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};

package/src/style/token.css

@@ -1,7 +1,7 @@
 /*
  * 공통 토큰의 단일 출처 · --app-종류-쓰임
  * 사용 기준: templates/document/design.md · 테마 분기는 color-scheme에 한정
- * 폭 기준 1024px·640px · 공유 사이드바와 본문 배치
+ * 폭 기준 1536px·1024px·640px · 양쪽 탐색과 본문 배치
  */
 
 :root {
@@ -102,7 +102,7 @@
     --app-space-gutter: 28px;
     --app-space-column: 32px;
     --app-space-sidebar-gap: 32px;
-    --app-size-sidebar: 200px;
+    --app-size-sidebar: 240px;
     --app-size-main: 900px;
     --app-size-page: calc(var(--app-size-main) + (var(--app-size-sidebar) + var(--app-space-sidebar-gap) + var(--app-space-gutter)) * 2);
     --app-size-brand: calc(var(--app-font-size-title) * var(--app-line-height-title) + var(--app-space-page-top) + var(--app-space-group));
@@ -110,6 +110,7 @@
     --app-size-menu-button: 44px;
     --app-size-drawer: 320px;
     --app-size-navigation-fade: 28px;
+    --app-size-tree-toggle: 24px;
 
     /* 화면 위쪽 제목 여백 · hash 도착점과 목차 읽는 선의 공통 기준 */
     --app-space-anchor: 80px;

package/src/type/doc-content.ts

@@ -1,4 +1,4 @@
-import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
+import type {DocOutline} from "@/type/doc-outline";
 
 /**
  * README 홈과 일반 문서가 공유하는 렌더링 결과

package/src/type/doc-file-data.ts

@@ -1,6 +1,6 @@
-import type {DocSection} from "@/component/widget/prose/_type/doc-section";
 import type {DocData} from "@/type/doc-data";
 import type {DocHeading} from "@/type/doc-heading";
+import type {DocSection} from "@/type/doc-section";
 
 /**
  * 문서 처리 중간 계약 · read-docs의 머리말과 rehype의 제목·절 정보

package/src/{component/widget/shell/_type → type}/doc-outline.ts

@@ -1,5 +1,5 @@
-import type {DocSection} from "@/component/widget/prose/_type/doc-section";
 import type {DocHeading} from "@/type/doc-heading";
+import type {DocSection} from "@/type/doc-section";
 
 /**
  * 문서 렌더링 결과의 목차 입력

package/src/type/site-assets.ts

@@ -7,9 +7,9 @@ export interface SiteAssets {
      */
     stylePath: string;
     /**
-     * 내용 지문으로 구분한 브라우저 스크립트 URL
+     * 셸 DOM 뒤에서 동기 실행할 단일 Hono JSX 브라우저 번들
      */
-    clientPath: string;
+    browserScript: string;
     /**
      * 내장 @font-face · head의 style 내용
      */

package/dist/client.js

@@ -1,7 +0,0 @@
-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
-            )`,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/src/client.ts

@@ -1,335 +0,0 @@
-/*
- * 브라우저 동작 · 모바일 탐색, 커서 장식, 읽는 절, hash 위치 보정
- * 서버 HTML의 data-* 연결 · React hydration 없음
- */
-
-import {heading_highlight_hold_ms} from "@/component/widget/prose/_constant/heading-highlight";
-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]");
-
-if (cursorFace) {
-    const cursorMedia = matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)");
-    const position = {x: 0, y: 0, frame: 0};
-
-    /**
-     * 터치 전환과 화면 이탈 시 예약된 이동도 취소해 장식이 다시 나타나지 않게 함
-     */
-    const handleCursorHide = () => {
-        cancelAnimationFrame(position.frame);
-        position.frame = 0;
-        cursorFace.classList.remove("wg_shell__cursorFace--visible");
-    };
-
-    /**
-     * 비활성 전환에서만 숨김 · 활성화 알림이 새 마우스 이동을 취소하지 않도록 함
-     */
-    const handleCursorMediaChange = () => {
-        if (!cursorMedia.matches) {
-            handleCursorHide();
-        }
-    };
-
-    /**
-     * 이동·화면 크기 변경·문서 진입에 같은 위치 계산 적용 · 화면 갱신마다 한 번만 반영
-     */
-    const renderCursorFace = () => {
-        if (position.frame !== 0) {
-            return;
-        }
-
-        position.frame = requestAnimationFrame(() => {
-            position.frame = 0;
-
-            // 포인터 좌표는 실행 중에만 결정 · transform으로 문서 재배치 방지
-            cursorFace.style.transform = `translate3d(
-                ${Math.max(0, Math.min(position.x + cursor_face_offset_px, document.documentElement.clientWidth - cursorFace.width - cursor_face_offset_px))}px,
-                ${Math.max(0, Math.min(position.y + cursor_face_offset_px, document.documentElement.clientHeight - cursorFace.height - cursor_face_offset_px))}px,
-                0
-            )`;
-            cursorFace.classList.add("wg_shell__cursorFace--visible");
-        });
-    };
-
-    /**
-     * 누른 상태도 마우스 입력으로 처리 · 클릭·텍스트 선택 중에도 얼굴 유지
-     */
-    const handleDocumentPointer = (event: PointerEvent) => {
-        const isMouse = cursorMedia.matches && event.pointerType === "mouse";
-
-        if (!isMouse) {
-            handleCursorHide();
-
-            return;
-        }
-
-        position.x = event.clientX;
-        position.y = event.clientY;
-        renderCursorFace();
-    };
-
-    /**
-     * 이미 보이는 얼굴을 새 화면 크기에 맞춰 이동 · 추가 마우스 이동 불필요
-     */
-    const handleCursorResize = () => {
-        if (cursorFace.classList.contains("wg_shell__cursorFace--visible")) {
-            renderCursorFace();
-        }
-    };
-
-    /**
-     * 전체 페이지 이동에서도 마지막 좌표 유지 · 저장 실패는 기본 마우스 동작에 영향 없음
-     */
-    const handlePageHide = () => {
-        if (!cursorFace.classList.contains("wg_shell__cursorFace--visible")) {
-            return;
-        }
-
-        try {
-            sessionStorage.setItem(cursor_face_storage_key, JSON.stringify({x: position.x, y: position.y}));
-        } catch {
-            // 저장소가 막힌 환경에서도 클릭·선택과 현재 페이지의 장식 유지
-        }
-    };
-
-    /**
-     * 첫 진입과 BFCache 복귀에서 좌표를 한 번 소비 · 이전 문서의 위치가 남지 않도록 삭제
-     */
-    const handlePageShow = () => {
-        try {
-            const stored = sessionStorage.getItem(cursor_face_storage_key);
-
-            sessionStorage.removeItem(cursor_face_storage_key);
-
-            if (stored !== null && cursorMedia.matches) {
-                const point: unknown = JSON.parse(stored);
-                // 속성 타입의 좁히기를 유지하도록 저장소 검증과 사용을 같은 분기에 둠
-                if (
-                    typeof point === "object" &&
-                    point !== null &&
-                    "x" in point &&
-                    "y" in point &&
-                    typeof point.x === "number" &&
-                    typeof point.y === "number" &&
-                    Number.isFinite(point.x) &&
-                    Number.isFinite(point.y)
-                ) {
-                    position.x = point.x;
-                    position.y = point.y;
-                    renderCursorFace();
-                }
-            }
-        } catch {
-            // 저장 실패나 잘못된 좌표는 무시하고 다음 실제 마우스 입력에서 표시
-        }
-    };
-
-    handlePageShow();
-
-    document.addEventListener("pointermove", handleDocumentPointer, {passive: true});
-    document.addEventListener("pointerdown", handleDocumentPointer, {passive: true});
-    document.documentElement.addEventListener("pointerleave", handleCursorHide);
-    addEventListener("blur", handleCursorHide);
-    addEventListener("resize", handleCursorResize);
-    addEventListener("pagehide", handlePageHide);
-    addEventListener("pageshow", handlePageShow);
-    cursorMedia.addEventListener("change", handleCursorMediaChange);
-}
-
-const hashTarget = revealHashTarget(location.hash);
-
-// 값 조립이 아닌 현재 강조의 수명 상태 · 새 이동은 이전 타이머를 취소
-let highlightedHeading: HTMLElement | null = null;
-let highlightTimer = 0;
-let highlightScroll: AbortController | null = null;
-
-/**
- * 강조 해제와 도착 감시 정리 · 다음 앵커의 오래된 타이머 개입 방지
- */
-const clearHeadingHighlight = () => {
-    clearTimeout(highlightTimer);
-    highlightScroll?.abort();
-    highlightScroll = null;
-    highlightedHeading?.classList.remove("wg_prose__headingText--highlighted");
-    highlightedHeading = null;
-};
-
-/**
- * 도착한 제목만 잠시 강조 · 같은 대상 재클릭도 유지 시간 재시작
- */
-const highlightHeading = (target: HTMLElement | null) => {
-    clearHeadingHighlight();
-    highlightedHeading = target === null ? null : target.querySelector<HTMLElement>(".wg_prose__headingText");
-
-    if (highlightedHeading === null) {
-        return;
-    }
-
-    highlightedHeading.classList.add("wg_prose__headingText--highlighted");
-    highlightTimer = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
-    highlightScroll = new AbortController();
-
-    // 부드러운 스크롤이 끝난 뒤에도 3초 확보 · 움직이지 않거나 scrollend가 없으면 위 타이머 사용
-    document.addEventListener("scrollend", handleHighlightArrival, {signal: highlightScroll.signal});
-};
-
-/**
- * 본문 스크롤의 첫 도착에서 유지 시간 갱신 · 사이드바 스크롤은 제외
- */
-const handleHighlightArrival = (event: Event) => {
-    if (event.target !== document) {
-        return;
-    }
-
-    clearTimeout(highlightTimer);
-    highlightScroll?.abort();
-    highlightScroll = null;
-    highlightTimer = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
-};
-
-/**
- * 같은 hash를 다시 눌러도 접힌 대상 공개 · 기본 링크 이동 유지
- */
-const handleHashClick = (event: MouseEvent) => {
-    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-        return;
-    }
-
-    if (
-        event.currentTarget instanceof HTMLAnchorElement &&
-        (event.currentTarget.target === "" || event.currentTarget.target === "_self") &&
-        !event.currentTarget.hasAttribute("download") &&
-        event.currentTarget.origin === location.origin &&
-        event.currentTarget.pathname === location.pathname &&
-        event.currentTarget.search === location.search &&
-        event.currentTarget.hash
-    ) {
-        const target = revealHashTarget(event.currentTarget.hash);
-
-        if (event.currentTarget.hash === location.hash) {
-            highlightHeading(target);
-        }
-    }
-};
-
-/**
- * hash 변경의 숨은 대상 공개와 위치 보정
- */
-const handleHashChange = () => {
-    const target = revealHashTarget(location.hash);
-
-    target?.scrollIntoView();
-    highlightHeading(target);
-};
-
-for (const link of document.querySelectorAll<HTMLAnchorElement>("a[href]")) {
-    link.addEventListener("click", handleHashClick);
-}
-
-addEventListener("hashchange", handleHashChange);
-
-// 목차 링크와 실제 제목 연결
-const tocSections = [...document.querySelectorAll<HTMLAnchorElement>("[data-toc-link]")].flatMap((link) => {
-    const heading = findHashTarget(link.hash);
-    const item = link.parentElement;
-
-    if (!heading || !item) {
-        return [];
-    }
-
-    return [
-        {
-            heading,
-            link,
-            item,
-            list: item.parentElement,
-            subs: [...item.querySelectorAll<HTMLAnchorElement>("[data-toc-sub-link]")].flatMap((sub) => {
-                const subHeading = findHashTarget(sub.hash);
-                const subItem = sub.parentElement;
-
-                return subHeading && subItem ? [{heading: subHeading, link: sub, item: subItem}] : [];
-            }),
-        },
-    ];
-});
-const firstSection = tocSections.at(0);
-
-if (firstSection) {
-    /**
-     * 읽는 선 기준 절·소제목 표시
-     * 기준: 제목의 scroll-margin-top + reading_line_slack_px
-     */
-    const markActive = () => {
-        // scroll-margin-top 계산값: CSS px
-        const line = Number.parseFloat(getComputedStyle(firstSection.heading).scrollMarginTop) + reading_line_slack_px;
-        // 접힌 Details 안 제목은 좌표가 남아도 현재 위치에서 제외
-        const current = tocSections.findLast((section) => section.heading.checkVisibility() && section.heading.getBoundingClientRect().top <= line) ?? firstSection;
-        const sub = current.subs.findLast((item) => item.heading.checkVisibility() && item.heading.getBoundingClientRect().top <= line);
-        const currentIndex = tocSections.indexOf(current);
-        const currentSubIndex = sub === undefined ? -1 : current.subs.indexOf(sub);
-
-        for (const [index, section] of tocSections.entries()) {
-            const active = section === current && sub === undefined;
-            section.link.classList.toggle("wg_shellToc__link--active", active);
-            if (active) {
-                section.link.setAttribute("aria-current", "location");
-            } else {
-                section.link.removeAttribute("aria-current");
-            }
-            section.item.classList.toggle("wg_shellToc__item--trail", section.list === current.list && index < currentIndex);
-            section.item.classList.toggle("wg_shellToc__item--current", section === current);
-
-            for (const [subIndex, item] of section.subs.entries()) {
-                item.link.classList.toggle("wg_shellToc__subLink--active", item === sub);
-                if (item === sub) {
-                    item.link.setAttribute("aria-current", "location");
-                } else {
-                    item.link.removeAttribute("aria-current");
-                }
-                item.item.classList.toggle("wg_shellToc__subItem--trail", section === current && subIndex < currentSubIndex);
-                item.item.classList.toggle("wg_shellToc__subItem--current", item === sub);
-            }
-        }
-    };
-
-    addEventListener("scroll", markActive, {passive: true});
-    addEventListener("resize", markActive);
-    addEventListener("toggle", markActive, true);
-    markActive();
-}
-
-const userScroll = new AbortController();
-
-for (const type of ["wheel", "touchmove", "keydown", "mousedown"]) {
-    addEventListener(type, () => userScroll.abort(), {once: true, passive: true});
-}
-
-/**
- * 글꼴 로드 후 hash 위치 보정 · 사용자 입력 시 자동 이동 취소
- * 초기 smooth scroll과 보정의 충돌 방지 · 보정 후 CSS 동작 복원
- */
-const settleHashScroll = async () => {
-    await document.fonts.ready;
-
-    if (hashTarget && !userScroll.signal.aborted) {
-        hashTarget.scrollIntoView({behavior: "instant"});
-        highlightHeading(hashTarget);
-    }
-
-    document.documentElement.style.removeProperty("scroll-behavior");
-};
-
-// 글꼴 요청 완료 시점 보장 · load 후 fonts.ready
-if (document.readyState === "complete") {
-    settleHashScroll();
-} else {
-    addEventListener("load", settleHashScroll, {once: true});
-}

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

@@ -1,9 +0,0 @@
-/**
- * 모바일 탐색 전환 · 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-mobile-navigation.ts

@@ -1,147 +0,0 @@
-import {navigation_mobile_query} from "@/component/widget/shell/_constant/navigation";
-import {revealHashTarget} from "@/util/dom/reveal-hash-target";
-
-/**
- * 같은 문서 탐색을 데스크톱 사이드바와 모바일 모달 사이에서 이동
- * 닫기·크기 변경에서 스크롤과 포커스 복원 · 초기화 실패 시 기본 목록 유지
- */
-export const bindMobileNavigation = () => {
-    const navigation = document.querySelector<HTMLElement>("[data-navigation]");
-    const dialog = document.querySelector<HTMLDialogElement>("[data-navigation-drawer]");
-    const content = document.querySelector<HTMLElement>("[data-navigation-content]");
-    const openButton = document.querySelector<HTMLButtonElement>("[data-navigation-open]");
-    const closeButton = document.querySelector<HTMLButtonElement>("[data-navigation-close]");
-    const sidebar = navigation?.parentElement;
-
-    if (!navigation || !dialog || !content || !openButton || !closeButton || !sidebar) {
-        return;
-    }
-
-    const mobile = matchMedia(navigation_mobile_query);
-
-    /**
-     * Escape 등 네이티브 닫기에서도 배경 스크롤과 버튼의 상태 복원
-     */
-    const handleClose = () => {
-        // 닫기 직후 다시 연 모달에 이전 close 이벤트가 개입하지 않도록 함
-        if (dialog.open) {
-            return;
-        }
-
-        document.body.classList.remove("wg_shell__root--drawerOpen");
-        openButton.setAttribute("aria-expanded", "false");
-    };
-
-    /**
-     * 기본 링크 이동보다 먼저 잠금 해제 · 네이티브 close가 열기 버튼으로 포커스 복원
-     */
-    const closeNavigation = () => {
-        dialog.close();
-        handleClose();
-    };
-
-    /**
-     * 네이티브 모달로 외부 포커스 차단 · 모바일에서만 열기
-     */
-    const handleOpen = () => {
-        if (!mobile.matches || dialog.open) {
-            return;
-        }
-
-        dialog.showModal();
-        document.body.classList.add("wg_shell__root--drawerOpen");
-        openButton.setAttribute("aria-expanded", "true");
-    };
-
-    /**
-     * 대화상자 바깥 배경 클릭만 닫기 · 내부의 빈 공간은 유지
-     */
-    const handleBackdropClick = (event: MouseEvent) => {
-        const bounds = dialog.getBoundingClientRect();
-
-        if (event.target === dialog && (event.clientX < bounds.left || event.clientX > bounds.right || event.clientY < bounds.top || event.clientY > bounds.bottom)) {
-            closeNavigation();
-        }
-    };
-
-    /**
-     * 링크의 기본 이동은 유지 · 목차는 닫은 뒤 실제 제목에 키보드 위치 전달
-     */
-    const handleNavigationClick = (event: MouseEvent) => {
-        if (
-            !dialog.open ||
-            event.defaultPrevented ||
-            event.button !== 0 ||
-            event.metaKey ||
-            event.ctrlKey ||
-            event.shiftKey ||
-            event.altKey ||
-            !(event.target instanceof Element)
-        ) {
-            return;
-        }
-
-        const link = event.target.closest("a[href]");
-
-        if (!(link instanceof HTMLAnchorElement) || (link.target !== "" && link.target !== "_self") || link.hasAttribute("download")) {
-            return;
-        }
-
-        closeNavigation();
-
-        if (link.origin === location.origin && link.pathname === location.pathname && link.search === location.search && link.hash) {
-            const target = revealHashTarget(link.hash);
-
-            if (target) {
-                target.tabIndex = -1;
-                target.focus({preventScroll: true});
-            }
-        }
-    };
-
-    /**
-     * 반응형 전환에도 목록 중복 없음 · 열린 모달을 데스크톱으로 가져가기 전에 닫기
-     */
-    const handleLayoutChange = () => {
-        const focused = document.activeElement;
-
-        if (mobile.matches) {
-            openButton.classList.add("wg_shell__menuToggle--visible");
-
-            if (navigation.parentElement !== content) {
-                content.append(navigation);
-            }
-
-            if (focused instanceof HTMLElement && navigation.contains(focused)) {
-                openButton.focus({preventScroll: true});
-            }
-
-            return;
-        }
-
-        closeNavigation();
-
-        // 첫 desktop 연결에서 같은 DOM을 재삽입하면 내부 스크롤이 0으로 초기화됨
-        if (navigation.parentElement !== sidebar) {
-            sidebar.append(navigation);
-        }
-
-        if (focused instanceof HTMLElement && navigation.contains(focused)) {
-            focused.focus({preventScroll: true});
-        } else if (focused === openButton || (focused instanceof HTMLElement && dialog.contains(focused))) {
-            sidebar.querySelector<HTMLAnchorElement>(".wg_shell__brand")?.focus({preventScroll: true});
-        }
-
-        // CSS의 폭 조건이 먼저 버튼을 숨겨 포커스가 사라지지 않도록 복원 후 숨김
-        openButton.classList.remove("wg_shell__menuToggle--visible");
-    };
-
-    openButton.addEventListener("click", handleOpen);
-    closeButton.addEventListener("click", closeNavigation);
-    dialog.addEventListener("close", handleClose);
-    dialog.addEventListener("click", handleBackdropClick);
-    navigation.addEventListener("click", handleNavigationClick);
-    mobile.addEventListener("change", handleLayoutChange);
-    handleLayoutChange();
-    sidebar.classList.add("wg_shell__sidebar--navigationReady");
-};

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

@@ -1,47 +0,0 @@
-/**
- * 실제 남은 내용이 있는 위·아래 끝만 흐림 표시 · 스크롤·글꼴·화면 크기 추적
- * 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();
-};