for-humanity 0.4.4 → 0.5.0

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

@@ -1,12 +1,15 @@
 /*
- * 넓은 화면은 본문 중앙 정렬 · 폭이 줄면 오른쪽 여백부터 축소
+ * 넓은 화면은 같은 폭의 양쪽 탐색 · 좁은 화면은 문서 탐색만 표시
  */
 .wg_shell__root {
     display: grid;
     max-width: var(--app-size-page);
     margin: 0 auto;
     padding: 0 var(--app-space-gutter);
-    grid-template: "nav main ." 1fr / calc(var(--app-size-sidebar) + var(--app-space-sidebar-gap)) minmax(0, var(--app-size-main)) minmax(0, 1fr);
+    grid-template: "nav main outline" 1fr / calc(var(--app-size-sidebar) + var(--app-space-sidebar-gap)) minmax(0, var(--app-size-main)) calc(
+            var(--app-size-sidebar) +
+            var(--app-space-sidebar-gap)
+        );
     background: var(--app-color-ground);
     color: var(--app-color-text);
     font-family: var(--app-font-sans);
@@ -24,148 +27,9 @@
     overflow: hidden;
 }
 
-.wg_shell__brandRow {
-    display: flex;
-
-    /* 두 스크롤 영역 바깥 · 목록과 목차 위에서 이름 고정 */
-    position: sticky;
-    top: 0;
-    z-index: var(--app-z-index-sticky);
-    align-self: start;
-    min-width: 0;
-    height: var(--app-size-brand);
-    padding-block: var(--app-space-page-top) var(--app-space-group);
-    background: var(--app-color-ground);
-    gap: var(--app-space-inline);
-    align-items: start;
-}
-
-.wg_shell__brand {
-    display: block;
-    flex: 1;
-    min-width: 0;
-    overflow: hidden;
-    color: var(--app-color-text-strong);
-    font-family: var(--app-font-brand);
-    font-size: var(--app-font-size-title);
-    font-weight: var(--app-font-weight-mark);
-    line-height: var(--app-line-height-title);
-    letter-spacing: var(--app-letter-spacing-brand);
-    text-decoration: none;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-
-    &:hover {
-        text-decoration: underline;
-    }
-
-    &:focus-visible {
-        /* 브랜드도 hover와 같은 밑줄로 키보드 위치 표시 */
-        outline: none;
-        text-decoration: underline;
-    }
-}
-
-.wg_shell__menuIcon {
-    width: 20px;
-    height: 20px;
-    fill: none;
-    stroke: currentcolor;
-    stroke-linecap: round;
-    stroke-width: 1.5;
-}
-
-.wg_shell__menuToggle {
-    display: none;
-    align-items: center;
-    justify-content: center;
-    flex: none;
-    width: var(--app-size-menu-button);
-    height: var(--app-size-menu-button);
-    padding: 0;
-    border: 0;
-    border-radius: var(--app-radius-box);
-    background: transparent;
-    color: var(--app-color-text-strong);
-    cursor: pointer;
-
-    &:hover {
-        background: var(--app-color-accent-soft);
-    }
-
-    &:focus-visible {
-        outline: var(--app-outline-focus);
-        outline-offset: var(--app-outline-focus-offset);
-    }
-}
-
-.wg_shell__menuToggle--visible {
-    display: flex;
-}
-
-/* sticky 틀 안에서 문서 목록과 목차의 스크롤 높이를 독립 유지 */
-.wg_shell__sidebar {
-    grid-area: nav;
-    position: sticky;
-    top: 0;
-    align-self: start;
-    min-width: 0;
-    height: 100dvh;
-    margin-inline-end: var(--app-space-sidebar-gap);
-}
-
-.wg_shell__navigation {
-    display: flex;
-    flex-direction: column;
-    height: calc(100dvh - var(--app-size-brand));
-    min-width: 0;
-    min-height: 0;
-}
-
-.wg_shell__documents {
-    /* TOC 길이가 바뀌어도 공통 목록의 스크롤 범위는 동일 */
-    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 {
-    /* 흐림으로 넘침을 알릴 때만 손잡이 숨김 · JS 없으면 네이티브 손잡이 유지 */
-    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__browserRoot {
+    /* 브라우저 셸의 마운트 경계 · 자식은 body의 기존 grid에 참여 */
+    display: contents;
 }
 
 .wg_shell__main {
@@ -179,103 +43,14 @@
     padding-inline: var(--app-space-column);
 }
 
-.wg_shell__drawer {
-    /* 네이티브 모달의 top layer · 뷰포트 왼쪽에 고정 */
-    position: fixed;
-    inset: 0 auto 0 0;
-    width: min(var(--app-size-drawer), calc(100% - var(--app-space-gutter) * 2));
-    max-width: none;
-    height: 100dvh;
-    max-height: 100dvh;
-    margin: 0;
-    padding: 0 var(--app-space-gutter) var(--app-space-group);
-    border: 0;
-    border-right: 1px solid var(--app-color-border-layout);
-    background: var(--app-color-ground);
-    color: var(--app-color-text);
-    overflow: hidden;
-
-    &::backdrop {
-        background: var(--app-color-backdrop);
-    }
-}
-
-.wg_shell__drawerHeader {
-    /* 두 스크롤 영역 바깥에서 닫기 버튼 유지 */
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: var(--app-space-inline);
-    min-height: var(--app-size-mobile-header);
-    margin-bottom: var(--app-space-block);
-    background: var(--app-color-ground);
-}
-
-.wg_shell__drawerTitle {
-    margin: 0;
-    font-size: var(--app-font-size-part);
-    font-weight: var(--app-font-weight-strong);
-}
-
-.wg_shell__drawerClose {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    flex: none;
-    width: var(--app-size-menu-button);
-    height: var(--app-size-menu-button);
-    padding: 0;
-    border: 0;
-    border-radius: var(--app-radius-box);
-    background: transparent;
-    color: var(--app-color-text-strong);
-    cursor: pointer;
-
-    &:hover {
-        background: var(--app-color-accent-soft);
-    }
-
-    &:focus-visible {
-        outline: var(--app-outline-focus);
-        outline-offset: var(--app-outline-focus-offset);
-    }
-}
-
-.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;
-    top: 0;
-    left: 0;
-    z-index: var(--app-z-index-popper);
-    visibility: hidden;
-    pointer-events: none;
-    user-select: none;
-    image-rendering: pixelated;
-}
-
-.wg_shell__cursorFace--visible {
-    visibility: visible;
-}
-
-/* 강제 색상 환경은 흐림 대신 시스템 손잡이로 넘침 표시 */
-@media (forced-colors: active) {
-    .wg_shell__scroll {
-        mask-image: none;
-        scrollbar-width: thin;
-        scrollbar-color: auto;
+/* 오른쪽 목차를 숨기는 화면에서 본문과 문서 목록의 간격 유지 */
+@media (width < 1536px) {
+    .wg_shell__root {
+        grid-template: "nav main ." 1fr / calc(var(--app-size-sidebar) + var(--app-space-sidebar-gap)) minmax(0, var(--app-size-main)) minmax(0, 1fr);
     }
 }
 
-/* 좁은 화면 · 상단 브랜드와 메뉴 버튼 · 탐색 목록은 네이티브 모달 */
+/* 모바일의 브랜드·본문은 한 열 배치 */
 @media (width < 1024px) {
     .wg_shell__root {
         max-width: calc(var(--app-size-main) + var(--app-space-gutter) * 2);
@@ -284,37 +59,6 @@
             "main" 1fr / minmax(0, 1fr);
     }
 
-    .wg_shell__sidebar {
-        position: static;
-        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;
-        z-index: var(--app-z-index-sticky);
-        background: var(--app-color-ground);
-    }
-
-    .wg_shell__brandRow {
-        position: static;
-        height: var(--app-size-mobile-header);
-        padding-block: 0;
-        align-items: center;
-    }
-
     .wg_shell__main {
         padding-block-start: var(--app-space-page-top);
         padding-inline: 0;

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

@@ -1,32 +1,17 @@
 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";
-import {WgShellToc} from "@/component/widget/shell/_wg-shell-toc";
-import {asset_favicon_path, asset_reload_path} from "@/constant/asset";
-import {copy_nav_close, copy_nav_open, copy_nav_title} from "@/constant/copy";
+import type {Child} from "hono/jsx";
+import {toNavigationData} from "@/component/widget/navigation/_function/to-navigation-data/to-navigation-data";
+import {toNavigationJson} from "@/component/widget/navigation/_function/to-navigation-json";
+import {WgShellControls} from "@/component/widget/shell-controls/wg-shell-controls";
+import {asset_favicon_path} from "@/constant/asset";
 import type {Doc} from "@/type/doc";
+import type {DocOutline} from "@/type/doc-outline";
 import type {SiteAssets} from "@/type/site-assets";
 import type {SiteConfig} from "@/type/site-config";
 import "@/style/base.css";
 import "@/style/token.css";
 import "./wg-shell.css";
 
-/**
- * dev 문서 변경 시 SSE 새로고침
- */
-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 틀의 입력 · 문서 탐색·현재 목차·본문
  */
@@ -58,16 +43,16 @@ export interface WgShellProps {
     /**
      * 현재 페이지 본문
      */
-    children: ReactNode;
+    children: Child;
 }
 
 export const WgShell = (props: WgShellProps) => {
-    const tocGroups = props.outline === undefined ? [] : toTocGroups(props.outline);
+    const navigationData = toNavigationData({site: props.site, docs: props.docs, current: props.current, outline: props.outline});
 
     return (
         <html lang="ko">
             {/**
-             * 공통 자원 · 초기 smooth scroll은 client.ts의 hash 위치 보정 후 복원
+             * 공통 자원 · 브라우저 동작은 WgShellControls의 생명주기에서 연결
              */}
             <head>
                 <meta charSet="utf-8" />
@@ -79,90 +64,24 @@ export const WgShell = (props: WgShellProps) => {
                 {props.assets.preload.map((href) => (
                     <link key={href} rel="preload" href={href} as="font" type="font/woff2" crossOrigin="" />
                 ))}
-                <script dangerouslySetInnerHTML={{__html: 'document.documentElement.style.scrollBehavior="auto"'}} />
                 <link rel="stylesheet" href={props.assets.stylePath} />
-                {props.assets.reload && <script dangerouslySetInnerHTML={{__html: reloadScript}} />}
             </head>
             {/**
              * 문서 탐색·현재 목차·본문 · 브라우저 동작 연결
              */}
             <body className={clsx("wg_shell__root")}>
                 {/**
-                 * 데스크톱의 공유 사이드바 · 모바일에서는 브랜드와 메뉴 버튼
+                 * 서버·브라우저의 공통 셸 조립 · 본문 HTML은 마운트 범위에서 제외
                  */}
-                <div className={clsx("wg_shell__sidebar")}>
-                    {/**
-                     * 브랜드와 모바일 메뉴 진입 · 버튼은 동작 연결 후 표시
-                     */}
-                    <div className={clsx("wg_shell__brandRow")}>
-                        {/**
-                         * 어느 문서에서도 README 홈으로 이동
-                         */}
-                        <a className={clsx("wg_shell__brand")} href="/" aria-current={props.current === undefined ? "page" : undefined}>
-                            {props.site.title}
-                        </a>
-                        {/**
-                         * 접힌 모바일 탐색의 진입점과 열림 상태 전달
-                         */}
-                        <button
-                            className={clsx("wg_shell__menuToggle")}
-                            type="button"
-                            aria-label={copy_nav_open}
-                            aria-controls="fh-navigation-drawer"
-                            aria-expanded="false"
-                            data-navigation-open=""
-                        >
-                            <svg className={clsx("wg_shell__menuIcon")} viewBox="0 0 24 24" aria-hidden="true" focusable="false">
-                                <path d="M4 6h16M4 12h16M4 18h16" />
-                            </svg>
-                        </button>
-                    </div>
-                    {/**
-                     * 같은 탐색 DOM을 모바일 대화상자로 이동 · 스크립트 없이도 기본 목록 제공
-                     */}
-                    <div className={clsx("wg_shell__navigation")} data-navigation="">
-                        {/**
-                         * 모든 페이지에서 같은 높이의 문서 탐색 · 목차 길이와 스크롤 분리
-                         */}
-                        <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 className={clsx("wg_shell__browserRoot")} data-shell-browser-root="" data-shell-reload={props.assets.reload ? "" : undefined}>
+                    <WgShellControls data={navigationData} reload={props.assets.reload} />
                 </div>
-                <script dangerouslySetInnerHTML={{__html: navigationScript}} />
-                <main className={clsx("wg_shell__main")}>{props.children}</main>
                 {/**
-                 * 브라우저의 모달 포커스·Escape 처리 · 목록은 한 번만 렌더링
+                 * 최소 탐색 자료와 단일 JSX 번들 · 본문 전 상태·스크롤 복원
                  */}
-                <dialog className={clsx("wg_shell__drawer")} id="fh-navigation-drawer" aria-labelledby="fh-navigation-title" data-navigation-drawer="">
-                    <div className={clsx("wg_shell__drawerHeader")}>
-                        {/**
-                         * 대화상자의 접근 가능한 이름
-                         */}
-                        <h2 className={clsx("wg_shell__drawerTitle")} id="fh-navigation-title">
-                            {copy_nav_title}
-                        </h2>
-                        {/**
-                         * 목록을 스크롤해도 보이는 닫기 동작
-                         */}
-                        <button className={clsx("wg_shell__drawerClose")} type="button" aria-label={copy_nav_close} data-navigation-close="">
-                            <svg className={clsx("wg_shell__menuIcon")} viewBox="0 0 24 24" aria-hidden="true" focusable="false">
-                                <path d="m6 6 12 12M18 6 6 18" />
-                            </svg>
-                        </button>
-                    </div>
-                    <div className={clsx("wg_shell__drawerContent")} data-navigation-content="" />
-                </dialog>
-                <img className={clsx("wg_shell__cursorFace")} src={asset_favicon_path} width="24" height="24" alt="" aria-hidden="true" draggable={false} data-cursor-face="" />
-                <script type="module" src={props.assets.clientPath} />
+                <script type="application/json" id="fh-navigation-data" dangerouslySetInnerHTML={{__html: toNavigationJson(navigationData)}} />
+                <script dangerouslySetInnerHTML={{__html: props.assets.browserScript}} />
+                <main className={clsx("wg_shell__main")}>{props.children}</main>
             </body>
         </html>
     );

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

@@ -0,0 +1,4 @@
+.wg_shellControls__navigation {
+    /* Hono 갱신의 DOM 경계 · 탐색 자식은 기존 body grid에 참여 */
+    display: contents;
+}

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

@@ -0,0 +1,170 @@
+import clsx from "clsx";
+import {Fragment, useEffect, useLayoutEffect, useRef} from "hono/jsx";
+import {WgCursorFace} from "@/component/widget/cursor-face/wg-cursor-face";
+import {WgNavigation, type WgNavigationProps} from "@/component/widget/navigation/wg-navigation";
+import {heading_highlight_hold_ms} from "@/component/widget/prose/_constant/heading-highlight";
+import {asset_reload_path} from "@/constant/asset";
+import {revealHashTarget} from "@/util/dom/reveal-hash-target";
+import "./wg-shell-controls.css";
+
+/**
+ * 셸의 서버·브라우저 공통 입력 · 탐색 계약을 그대로 사용하고 dev 갱신만 추가
+ */
+export interface WgShellControlsProps extends WgNavigationProps {
+    /**
+     * 문서 변경 알림에 따른 dev 새로고침 활성화
+     */
+    reload: boolean;
+}
+
+export const WgShellControls = (props: WgShellControlsProps) => {
+    const headingRef = useRef<HTMLElement | null>(null);
+    const timerRef = useRef(0);
+    const arrivalRef = useRef<AbortController | null>(null);
+    const lifetimeRef = useRef<AbortController | null>(null);
+    const userScrollRef = useRef<AbortController | null>(null);
+
+    /**
+     * 다음 앵커 이동과 해제에서 이전 강조·도착 감시·타이머를 함께 정리
+     */
+    const clearHeadingHighlight = () => {
+        clearTimeout(timerRef.current);
+        timerRef.current = 0;
+        arrivalRef.current?.abort();
+        arrivalRef.current = null;
+        headingRef.current?.classList.remove("wg_prose__headingText--highlighted");
+        headingRef.current = null;
+    };
+
+    /**
+     * 본문 스크롤 도착 후 3초 확보 · 사이드바 자체의 scrollend는 제외
+     */
+    const handleHighlightArrival = (event: Event) => {
+        if (event.target !== document) return;
+        clearTimeout(timerRef.current);
+        arrivalRef.current?.abort();
+        arrivalRef.current = null;
+        timerRef.current = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
+    };
+
+    /**
+     * 도착 제목만 강조 · 같은 hash 재클릭도 유지 시간 재시작
+     */
+    const highlightHeading = (target: HTMLElement | null) => {
+        clearHeadingHighlight();
+        headingRef.current = target === null ? null : target.querySelector<HTMLElement>(".wg_prose__headingText");
+        if (headingRef.current === null) return;
+        headingRef.current.classList.add("wg_prose__headingText--highlighted");
+        timerRef.current = window.setTimeout(clearHeadingHighlight, heading_highlight_hold_ms);
+        arrivalRef.current = new AbortController();
+        document.addEventListener("scrollend", handleHighlightArrival, {signal: arrivalRef.current.signal});
+    };
+
+    /**
+     * 탐색 DOM이 다시 만들어져도 같은 hash의 접힌 Details 공개를 유지
+     */
+    const handleHashClick = (event: MouseEvent) => {
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+        const link = event.target instanceof Element ? event.target.closest("a[href]") : null;
+        if (
+            link instanceof HTMLAnchorElement &&
+            (link.target === "" || link.target === "_self") &&
+            !link.hasAttribute("download") &&
+            link.origin === location.origin &&
+            link.pathname === location.pathname &&
+            link.search === location.search &&
+            link.hash
+        ) {
+            const target = revealHashTarget(link.hash);
+            if (link.hash === location.hash) highlightHeading(target);
+        }
+    };
+
+    /**
+     * hash 변경 시 접힌 대상을 공개하고 네이티브 스크롤·강조 적용
+     */
+    const handleHashChange = () => {
+        const target = revealHashTarget(location.hash);
+        target?.scrollIntoView();
+        highlightHeading(target);
+    };
+
+    const handleUserScroll = () => {
+        userScrollRef.current?.abort();
+    };
+
+    /**
+     * 초기 폰트 로드 후 앵커 보정 · 해제된 인스턴스와 사용자 이동에 개입하지 않음
+     */
+    const handlePageLoad = async () => {
+        const lifetime = lifetimeRef.current;
+        const hash = location.hash;
+        const target = revealHashTarget(hash);
+        await document.fonts.ready;
+        if (lifetime === null || lifetime.signal.aborted) return;
+        if (target !== null && !userScrollRef.current?.signal.aborted && hash === location.hash) {
+            target.scrollIntoView({behavior: "instant"});
+            highlightHeading(target);
+        }
+        document.documentElement.style.removeProperty("scroll-behavior");
+    };
+
+    /**
+     * 셸은 본문 앞에서 마운트 · 본문 파싱 이후에만 초기 접힘 대상 조회
+     */
+    const handleBodyReady = () => {
+        revealHashTarget(location.hash);
+        if (document.readyState === "complete") void handlePageLoad();
+    };
+
+    /**
+     * 본문 이벤트의 설치·정리는 셸이 소유 · SSR에서는 DOM에 접근하지 않음
+     */
+    useLayoutEffect(() => {
+        const lifetime = new AbortController();
+        lifetimeRef.current = lifetime;
+        userScrollRef.current = new AbortController();
+        document.documentElement.style.scrollBehavior = "auto";
+        document.addEventListener("click", handleHashClick, {signal: lifetime.signal});
+        addEventListener("hashchange", handleHashChange, {signal: lifetime.signal});
+        addEventListener("load", handlePageLoad, {once: true, signal: lifetime.signal});
+        for (const type of ["wheel", "touchmove", "keydown", "mousedown"]) {
+            addEventListener(type, handleUserScroll, {once: true, passive: true, signal: lifetime.signal});
+        }
+        if (document.readyState === "loading") {
+            document.addEventListener("DOMContentLoaded", handleBodyReady, {once: true, signal: lifetime.signal});
+        } else {
+            handleBodyReady();
+        }
+        return () => {
+            lifetime.abort();
+            lifetimeRef.current = null;
+            userScrollRef.current?.abort();
+            userScrollRef.current = null;
+            clearHeadingHighlight();
+            document.documentElement.style.removeProperty("scroll-behavior");
+        };
+    }, []);
+
+    /**
+     * dev 새로고침 연결도 브라우저 셸의 수명에 맞춰 닫음
+     */
+    useEffect(() => {
+        if (!props.reload || lifetimeRef.current === null) return;
+        const source = new EventSource(asset_reload_path);
+        source.onmessage = () => location.reload();
+        return () => source.close();
+    }, [props.reload]);
+
+    return (
+        <Fragment>
+            {/**
+             * 별도 DOM 경계로 탐색 갱신이 커서 형제 사이에서 dialog를 재삽입하지 않게 함
+             */}
+            <div className={clsx("wg_shellControls__navigation")}>
+                <WgNavigation data={props.data} stores={props.stores} />
+            </div>
+            <WgCursorFace ready={props.stores !== undefined} />
+        </Fragment>
+    );
+};

package/src/constant/asset.ts

@@ -12,11 +12,6 @@ export const asset_dir = "_fh";
  */
 export const asset_style_path = `/${asset_dir}/style.css`;
 
-/**
- * 내용 지문을 붙일 테마·목차·hash 보정 스크립트의 기본 URL
- */
-export const asset_client_path = `/${asset_dir}/client.js`;
-
 /**
  * 자체 호스팅 글꼴 폴더
  */

package/src/entry/browser/browser.tsx

@@ -0,0 +1,22 @@
+/*
+ * 브라우저 진입 · 서버 자료 검증과 저장소 생성 후 공통 셸 컨트롤을 한 번 마운트
+ */
+import {createRoot} from "hono/jsx/dom/client";
+import {navigationDataSchema} from "@/component/widget/navigation/_constant/navigation-data-schema";
+import {WgShellControls} from "@/component/widget/shell-controls/wg-shell-controls";
+import {createNavigationStores} from "@/store/navigation/create-navigation-stores";
+
+const root = document.querySelector<HTMLElement>("[data-shell-browser-root]");
+const payload = document.getElementById("fh-navigation-data");
+
+if (root !== null && payload !== null) {
+    try {
+        const value: unknown = JSON.parse(payload.textContent);
+        const data = navigationDataSchema.parse(value);
+        const stores = createNavigationStores({local: () => localStorage, session: () => sessionStorage});
+        createRoot(root).render(<WgShellControls data={data} stores={stores} reload={root.hasAttribute("data-shell-reload")} />);
+    } catch (error) {
+        // 초기화 오류에서도 서버의 링크·본문과 네이티브 스크롤 유지
+        console.error("for-humanity browser initialization failed", error);
+    }
+}