for-humanity 0.4.3 → 0.5.0

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);
+    }
+}

package/src/{app.tsx → entry/cli/_function/create-app.tsx}

@@ -1,7 +1,7 @@
 import {Hono} from "hono";
+import {html} from "hono/html";
+import type {Child} from "hono/jsx";
 import {ssgParams} from "hono/ssg";
-import type {ReactElement} from "react";
-import {renderToStaticMarkup} from "react-dom/server";
 import {PgDoc} from "@/page/doc/pg-doc";
 import {PgHome} from "@/page/home/pg-home";
 import type {Doc} from "@/type/doc";
@@ -28,16 +28,16 @@ export interface AppOptions {
 }
 
 /**
- * React 서버 렌더링 · 브라우저 React 번들 없음
+ * Hono JSX 페이지에 HTML 문서 선언 추가 · 서버와 정적 출력에서 같은 렌더러 사용
  */
-const toHtml = (page: ReactElement) => {
-    return `<!DOCTYPE html>${renderToStaticMarkup(page)}`;
+const toHtml = (page: Child) => {
+    return html`<!DOCTYPE html>${page}`;
 };
 
 /**
  * 첫 화면 / · 문서 /:slug{.+}/ · 하위 폴더 id 지원
  * 자원 wildcard와 정규식 매개변수 혼합 시 TrieRouter fallback으로 중첩 경로 불일치
- * 자원·SSE는 dev.ts의 별도 앱 소유
+ * 자원·SSE는 createDevApp의 별도 앱 소유
  */
 export const createApp = (options: AppOptions) => {
     const app = new Hono();

package/src/{content → entry/cli/_function/create-processor}/create-processor.ts

@@ -19,9 +19,9 @@ import {remarkParts} from "@/component/widget/prose/_function/remark-parts";
 import {remarkStatus} from "@/component/widget/prose/_function/remark-status";
 import {remarkSwatch} from "@/component/widget/prose/_function/remark-swatch";
 import {remarkUnknownDirectives} from "@/component/widget/prose/_function/remark-unknown-directives";
-import {rehypeAssets} from "@/content/rehype-assets";
-import {rehypeHeadingIds} from "@/content/rehype-heading-ids";
-import {remarkReport} from "@/content/remark-report";
+import {rehypeAssets} from "@/entry/cli/_function/create-processor/_rehype-assets";
+import {rehypeHeadingIds} from "@/entry/cli/_function/create-processor/_rehype-heading-ids";
+import {remarkReport} from "@/entry/cli/_function/create-processor/_remark-report";
 import type {SiteConfig} from "@/type/site-config";
 
 /**

package/src/{content → entry/cli/_function}/read-docs.ts

@@ -11,7 +11,7 @@ import {
     copy_error_doc_parent_missing,
     copy_error_frontmatter,
 } from "@/constant/copy";
-import type {Processor} from "@/content/create-processor";
+import type {Processor} from "@/entry/cli/_function/create-processor/create-processor";
 import type {Doc} from "@/type/doc";
 import {docDataSchema} from "@/type/doc-data";
 import type {DocFileData} from "@/type/doc-file-data";

package/src/{content → entry/cli/_function}/read-home.ts

@@ -2,7 +2,7 @@ import {readdir, readFile} from "node:fs/promises";
 import {join} from "node:path";
 import {VFile} from "vfile";
 import {copy_error_home_clash} from "@/constant/copy";
-import type {Processor} from "@/content/create-processor";
+import type {Processor} from "@/entry/cli/_function/create-processor/create-processor";
 import type {DocContent} from "@/type/doc-content";
 import type {DocFileData} from "@/type/doc-file-data";
 

package/src/{content/read-docs.test.ts → entry/cli/cli.test.ts}

@@ -3,28 +3,87 @@ import {mkdir, mkdtemp, rm, symlink, writeFile} from "node:fs/promises";
 import {tmpdir} from "node:os";
 import {join} from "node:path";
 import {test} from "node:test";
-import {renderToStaticMarkup} from "react-dom/server";
-import {createApp} from "@/app";
-import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
-import {asset_client_path, asset_style_path} from "@/constant/asset";
-import {createProcessor} from "@/content/create-processor";
-import {readDocs} from "@/content/read-docs";
-import {readHome} from "@/content/read-home";
-import {toDocGroups} from "@/content/to-doc-groups/to-doc-groups";
+import {navigationDataSchema} from "@/component/widget/navigation/_constant/navigation-data-schema";
+import {toDocGroups} from "@/component/widget/navigation/_function/to-doc-groups/to-doc-groups";
+import {toNavigationData} from "@/component/widget/navigation/_function/to-navigation-data/to-navigation-data";
+import {toNavigationJson} from "@/component/widget/navigation/_function/to-navigation-json";
+import {WgNavigation} from "@/component/widget/navigation/wg-navigation";
+import {asset_style_path} from "@/constant/asset";
+import {createApp} from "@/entry/cli/_function/create-app";
+import {createProcessor} from "@/entry/cli/_function/create-processor/create-processor";
+import {readDocs} from "@/entry/cli/_function/read-docs";
+import {readHome} from "@/entry/cli/_function/read-home";
 import {docDataSchema} from "@/type/doc-data";
 import {siteConfigSchema} from "@/type/site-config";
 
+/**
+ * 브라우저와 같은 공개 탐색 컴포넌트에서 문서 목록만 확인
+ */
+const toNavigationHtml = (options: Parameters<typeof toNavigationData>[0]) => {
+    const markup = WgNavigation({data: toNavigationData(options)}).toString();
+    const navigation = markup.match(/<nav[^>]*class="wg_navigationNav__root"[\s\S]*?<\/nav>/)?.[0];
+    assert.ok(navigation);
+    return navigation;
+};
+
+test("navigation payload excludes document bodies and safely embeds authored labels", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-navigation-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    const title = "</script><script>window.injected=true</script>\u2028\u2029";
+    const site = siteConfigSchema.parse({title});
+    await writeFile(join(root, "guide.md"), "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\nPrivate body marker.\n");
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const data = toNavigationData({site, docs, current: "guide"});
+    const json = toNavigationJson(data);
+
+    assert.equal(data.title, title);
+    assert.equal(data.groups[0].docs[0].active, true);
+    assert.doesNotMatch(json, /Private body marker|<|\u2028|\u2029/);
+    assert.deepEqual(JSON.parse(json), data);
+    assert.deepEqual(navigationDataSchema.parse(JSON.parse(json)), data);
+});
+
 test("page resource URLs use the supplied content fingerprints instead of fixed cache keys", async () => {
     const site = siteConfigSchema.parse({});
-    const assets = {fontCss: "", preload: [], reload: false, stylePath: "/_fh/style.abc123.css", clientPath: "/_fh/client.def456.js"};
+    const assets = {fontCss: "", preload: [], reload: false, browserScript: "", stylePath: "/_fh/style.abc123.css"};
     const app = createApp({site, store: {docs: []}, assets});
     const html = await (await app.request("/")).text();
 
     assert.match(html, /rel="stylesheet" href="\/_fh\/style\.abc123\.css"/);
-    assert.match(html, /type="module" src="\/_fh\/client\.def456\.js"/);
+    assert.doesNotMatch(html, /<script\b[^>]*\bsrc=/, "browser behavior must share one inline JSX entry");
     assert.doesNotMatch(html, /(?:href|src)="\/_fh\/(?:style\.css|client\.js)"/);
 });
 
+test("navigation initialization runs after its DOM and before the document body", async () => {
+    const site = siteConfigSchema.parse({});
+    const browserScript = "window.navigationFixture = true;";
+    const assets = {fontCss: "", preload: [], reload: false, stylePath: asset_style_path, browserScript};
+    const html = await (await createApp({site, store: {docs: []}, assets}).request("/")).text();
+    const initialization = html.indexOf(`<script>${browserScript}</script>`);
+
+    assert.doesNotMatch(html, /\sref="|\sonClick="/, "server HTML must not serialize browser refs or handlers");
+    assert.ok(initialization > html.indexOf("fh-navigation-data"), "authored payload must be available before mounting");
+    assert.ok(initialization > html.indexOf("data-navigation-drawer"), "navigation controls must exist before initialization");
+    assert.ok(initialization > html.indexOf("data-cursor-face"), "the JSX browser owner must also contain its cursor");
+    assert.ok(initialization < html.indexOf('<main class="wg_shell__main">'), "navigation must be ready before the main content is parsed");
+});
+
+test("the page outline belongs only to the right rail rather than mobile navigation", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-outline-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await writeFile(join(root, "README.md"), "# Home\n\n## Read here\n\n### More context\n\nText.\n");
+    const site = siteConfigSchema.parse({});
+    const home = await readHome({root, processor: createProcessor({site, root})});
+    const assets = {fontCss: "", preload: [], reload: false, browserScript: "", stylePath: asset_style_path};
+    const html = await (await createApp({site, store: {docs: [], home}, assets}).request("/")).text();
+    const rail = html.match(/<aside\b[^>]*data-navigation-rail=""[^>]*>([\s\S]*?)<\/aside>/)?.[1];
+
+    assert.ok(rail, "the right rail must exist");
+    assert.ok(rail.includes('data-navigation-scroll="outline"'), "the right rail must own the outline scroll area");
+    assert.match(rail, /Read here/);
+    assert.equal([...html.matchAll(/data-navigation-scroll="outline"/g)].length, 1);
+});
+
 test("documents with the same initial retain distinct URLs", async (t) => {
     const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
     const site = siteConfigSchema.parse({});
@@ -66,7 +125,7 @@ test("navigation shows every document group in reading order without document ic
     ]);
 
     const docs = await readDocs({root, processor: createProcessor({site, root})});
-    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "writing"}));
+    const html = toNavigationHtml({site, docs, current: "writing"});
     const groups = [...html.matchAll(/<section\b[^>]*aria-label="([^"]+)"/g)];
 
     assert.deepEqual(
@@ -74,7 +133,7 @@ test("navigation shows every document group in reading order without document ic
         ["Getting started", "Guide"],
     );
     assert.doesNotMatch(html, /<details\b/);
-    assert.doesNotMatch(html, /wg_shellNav__docIcon/);
+    assert.doesNotMatch(html, /wg_navigationNav__docIcon/);
     assert.doesNotMatch(html, /href="\/"/);
     assert.doesNotMatch(html, />Documents<|>Overview</);
     assert.ok(html.indexOf('href="/writing/"') < html.indexOf('href="/parts/"'));
@@ -147,15 +206,15 @@ test("nested groups follow metadata paths and keep sibling branches and document
     assert.equal(groups[1].groups[0].groups[0].groups[0].groups[0].name, "Drafts");
     assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
 
-    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "authoring"}));
+    const html = toNavigationHtml({site, docs, current: "authoring"});
 
     assert.match(html, /href="\/authoring\/"[^>]*aria-current="page"/);
-    assert.match(html, /Atlas<\/span><ul\b/);
-    assert.match(html, /Research<\/span><ul\b/);
+    assert.match(html, /Atlas<\/span><button\b[^>]*aria-expanded="true"[^>]*>−<\/button><ul\b/);
+    assert.match(html, /Research<\/span><button\b[^>]*aria-expanded="true"[^>]*>−<\/button><ul\b/);
     assert.equal([...html.matchAll(/href="\/authoring\/"/g)].length, 1);
     assert.equal([...html.matchAll(/>Research<\/span>/g)].length, 2);
-    assert.equal([...html.matchAll(/wg_shellNavList__item--current/g)].length, 3);
-    assert.doesNotMatch(renderToStaticMarkup(WgShellNav({site, docs})), /aria-current="page"|wg_shellNavList__item--current/);
+    assert.equal([...html.matchAll(/wg_navigationNavList__item--current/g)].length, 3);
+    assert.doesNotMatch(toNavigationHtml({site, docs}), /aria-current="page"|wg_navigationNavList__item--current/);
     assert.ok(html.indexOf('href="/parts/"') < html.indexOf('href="/authoring/"'));
     assert.doesNotMatch(html, /<details\b/);
 });
@@ -205,20 +264,24 @@ test("parent documents contain ordered descendants with independent URLs and one
     assert.deepEqual(docs.find((doc) => doc.id === "details")?.ancestors, ["settings", "guide/site"]);
     assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
 
-    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "details"}));
-    assert.match(html, /href="\/settings\/"[^>]*>Settings<\/a><ul\b[^>]*aria-label="Settings"/);
-    assert.match(html, /href="\/guide\/site\/"[^>]*>Site<\/a><ul\b[^>]*aria-label="Site"/);
+    const html = toNavigationHtml({site, docs, current: "details"});
+    assert.match(html, /href="\/settings\/"[^>]*>Settings<\/a><button\b[^>]*aria-label="Collapse Settings"[^>]*>−<\/button><ul\b[^>]*aria-label="Settings"/);
+    assert.match(html, /href="\/guide\/site\/"[^>]*>Site<\/a><button\b[^>]*aria-label="Collapse Site"[^>]*>−<\/button><ul\b[^>]*aria-label="Site"/);
     assert.match(html, /href="\/details\/"[^>]*aria-current="page"/);
     assert.equal([...html.matchAll(/aria-current="page"/g)].length, 1);
-    assert.equal([...html.matchAll(/wg_shellNavList__link--active/g)].length, 1);
-    assert.equal([...html.matchAll(/wg_shellNavList__item--current/g)].length, 5);
+    assert.equal([...html.matchAll(/wg_navigationNavList__link--active/g)].length, 1);
+    assert.equal([...html.matchAll(/wg_navigationNavList__item--current/g)].length, 5);
     for (const doc of docs) {
         assert.equal(html.split(`href="/${doc.id}/"`).length - 1, 1);
     }
     assert.ok(html.indexOf('href="/themes/"') < html.indexOf('href="/guide/site/"'));
-    assert.doesNotMatch(renderToStaticMarkup(WgShellNav({site, docs})), /aria-current="page"|wg_shellNavList__item--current/);
+    assert.doesNotMatch(toNavigationHtml({site, docs}), /aria-current="page"|wg_navigationNavList__item--current/);
 
-    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    const app = createApp({
+        site,
+        store: {docs},
+        assets: {stylePath: asset_style_path, browserScript: "", fontCss: "", preload: [], reload: false},
+    });
     for (const doc of docs) {
         assert.equal((await app.request(`/${doc.id}/`)).status, 200);
     }
@@ -340,7 +403,11 @@ test("a plain root README renders at home and relative home links resolve from n
     ]);
 
     const [docs, home] = await Promise.all([readDocs({root, processor}), readHome({root, processor})]);
-    const app = createApp({site, store: {docs, home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    const app = createApp({
+        site,
+        store: {docs, home},
+        assets: {stylePath: asset_style_path, browserScript: "", fontCss: "", preload: [], reload: false},
+    });
     const response = await app.request("/");
     const html = await response.text();
 
@@ -356,7 +423,7 @@ test("a plain root README renders at home and relative home links resolve from n
     assert.match(html, /href="\/guide\/setup\/"/);
     assert.match(html, /href="#start" data-toc-link/);
     assert.match(html, /class="shiki/);
-    assert.match(html, /wg_shell__brand" href="\/" aria-current="page"/);
+    assert.match(html, /wg_navigation__brand" href="\/" aria-current="page"/);
     assert.equal([...html.matchAll(/href="\/"/g)].length, 1);
     assert.match(docs[0].html, /href="\/#start"/);
     assert.doesNotMatch(html, /wg_prose__eyebrow|pg_home__card/);
@@ -369,7 +436,11 @@ test("a missing README provides a creation hint without generated overview cards
 
     t.after(() => rm(root, {recursive: true, force: true}));
     const home = await readHome({root, processor: createProcessor({site, root})});
-    const app = createApp({site, store: {docs: [], home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    const app = createApp({
+        site,
+        store: {docs: [], home},
+        assets: {stylePath: asset_style_path, browserScript: "", fontCss: "", preload: [], reload: false},
+    });
     const html = await (await app.request("/")).text();
 
     assert.equal(home, undefined);
@@ -448,7 +519,11 @@ test("headings and contents preserve authored text without automatic numbering",
     );
 
     const docs = await readDocs({root, processor: createProcessor({site, root})});
-    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    const app = createApp({
+        site,
+        store: {docs},
+        assets: {stylePath: asset_style_path, browserScript: "", fontCss: "", preload: [], reload: false},
+    });
     const html = await (await app.request("/guide/")).text();
 
     assert.match(html, /<h2[^>]*id="overview"[^>]*><span class="wg_prose__headingText">Overview<\/span><\/h2>/);
@@ -457,8 +532,8 @@ test("headings and contents preserve authored text without automatic numbering",
     assert.match(html, /href="#01-keep-this-number"[^>]*>01\. Keep this number<\/a>/);
     assert.match(html, /href="#nested-heading"[^>]*>Nested heading<\/a>/);
     assert.match(html, /href="#overview-1"[^>]*>Overview<\/a>/);
-    assert.match(html, /wg_shellToc__group">Setup<\/div>/);
-    assert.doesNotMatch(html, /wg_prose__num|wg_shellToc__mark/);
+    assert.match(html, /wg_navigationToc__group">Setup<\/div>/);
+    assert.doesNotMatch(html, /wg_prose__num|wg_navigationToc__mark/);
 });
 
 test("local Markdown and raw HTML images share fingerprinted assets with attachments", async (t) => {

package/src/{cli.ts → entry/cli/cli.ts}

@@ -5,7 +5,7 @@
  */
 
 import {EventEmitter} from "node:events";
-import {existsSync, watch} from "node:fs";
+import {existsSync, readFileSync, watch} from "node:fs";
 import {copyFile, mkdir, rm, writeFile} from "node:fs/promises";
 import {basename, dirname, extname, join, relative, resolve, sep} from "node:path";
 import {fileURLToPath, pathToFileURL} from "node:url";
@@ -14,16 +14,16 @@ import {serveStatic} from "@hono/node-server/serve-static";
 import {debounce} from "es-toolkit";
 import {Hono} from "hono";
 import {toSSG} from "hono/ssg";
-import {createApp} from "@/app";
-import {asset_client_path, asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
-import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port, cli_reload_delay_ms} from "@/constant/cli";
+import {asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
 import {copy_error_config, copy_error_font_preload, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
 import {font_brand_css, font_cache_control, font_mono_css, font_sans_css, font_sans_preload_file} from "@/constant/font";
 import {site_config_absent} from "@/constant/site";
-import {createProcessor} from "@/content/create-processor";
-import {readDocs} from "@/content/read-docs";
-import {readHome} from "@/content/read-home";
-import {createDevApp} from "@/dev";
+import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port, cli_reload_delay_ms} from "@/entry/cli/_constant/cli";
+import {createApp} from "@/entry/cli/_function/create-app";
+import {createDevApp} from "@/entry/cli/_function/create-dev-app";
+import {createProcessor} from "@/entry/cli/_function/create-processor/create-processor";
+import {readDocs} from "@/entry/cli/_function/read-docs";
+import {readHome} from "@/entry/cli/_function/read-home";
 import {siteConfigSchema} from "@/type/site-config";
 import {toChangeQueue} from "@/util/async/to-change-queue";
 import {toErrorMessage} from "@/util/error/to-error-message";
@@ -86,10 +86,9 @@ const main = async () => {
 
     const fontCss = [sans.css, mono.css, brand.css].join("\n");
     const stylePath = toAssetPath({path: asset_style_path, file: join(kitRoot, "dist/cli.css")});
-    const clientPath = toAssetPath({path: asset_client_path, file: join(kitRoot, "dist/client.js")});
+    const browserScript = readFileSync(join(kitRoot, "dist/browser.js"), "utf8");
     const kitFiles = new Map([
         [stylePath, join(kitRoot, "dist/cli.css")],
-        [clientPath, join(kitRoot, "dist/client.js")],
         [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")],
         ...sans.files,
         ...mono.files,
@@ -102,7 +101,7 @@ const main = async () => {
     const app = createApp({
         site: siteConfig,
         store,
-        assets: {stylePath, clientPath, fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev"},
+        assets: {stylePath, browserScript, fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev"},
     });
 
     if (command === "build") {

package/src/store/navigation/_constant/tree.ts

@@ -0,0 +1,6 @@
+import type {NavigationTreeState} from "@/store/navigation/navigation-state";
+
+/**
+ * 서버에서 사용자 저장소 없이 모든 가지를 펼치는 고정 스냅샷
+ */
+export const tree_server_state: NavigationTreeState = {collapsed: {}};

package/src/store/navigation/create-navigation-stores.test.ts

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import {test} from "node:test";
+import {createNavigationStores} from "@/store/navigation/create-navigation-stores";
+import {navigation_scroll_storage_key, navigation_tree_storage_key} from "@/store/navigation/navigation-storage";
+
+const fixture = () => {
+    const local = new Map<string, string>();
+    const session = new Map<string, string>();
+    const storage = (values: Map<string, string>) => ({
+        getItem: (key: string) => {
+            const value = values.get(key);
+            return value === undefined ? null : value;
+        },
+        setItem: (key: string, value: string) => {
+            values.set(key, value);
+        },
+        removeItem: (key: string) => {
+            values.delete(key);
+        },
+    });
+    return {local, session, options: {local: () => storage(local), session: () => storage(session)}};
+};
+
+test("starts with every branch expanded and persists explicit choices across pages", () => {
+    const setup = fixture();
+    const stores = createNavigationStores(setup.options);
+    assert.deepEqual(stores.tree.getState(), {collapsed: {}});
+    stores.tree.setState({collapsed: {'group:["Projects"]': true, "outline:one:heading:setup": false}});
+    assert.deepEqual(createNavigationStores(setup.options).tree.getState(), stores.tree.getState());
+    assert.equal(setup.session.has(navigation_tree_storage_key), false);
+});
+
+test("retains independent wide, desktop and drawer scroll positions within a tab", () => {
+    const setup = fixture();
+    const stores = createNavigationStores(setup.options);
+    stores.scroll.setState({
+        positions: {
+            wide: {navigation: "docs", pathname: "/one/", documents: 450, outline: 300},
+            desktop: {navigation: "docs", pathname: "/two/", documents: 750, outline: 100},
+            drawer: {navigation: "docs", pathname: "/one/", documents: 200, outline: 800},
+        },
+    });
+    assert.deepEqual(createNavigationStores(setup.options).scroll.getState(), stores.scroll.getState());
+    assert.equal(setup.local.has(navigation_scroll_storage_key), false);
+});
+
+test("rejects malformed and unknown-version persistence without losing defaults", () => {
+    for (const value of ["{", "null", '{"state":null,"version":1}', '{"state":{"collapsed":{"group:a":true}},"version":999}']) {
+        const setup = fixture();
+        setup.local.set(navigation_tree_storage_key, value);
+        setup.session.set(navigation_scroll_storage_key, value);
+        const stores = createNavigationStores(setup.options);
+        assert.deepEqual(stores.tree.getState(), {collapsed: {}});
+        assert.deepEqual(stores.scroll.getState(), {positions: {}});
+    }
+});
+
+test("narrows persisted branch flags and rejects invalid scroll coordinates", () => {
+    const setup = fixture();
+    setup.local.set(navigation_tree_storage_key, JSON.stringify({version: 1, state: {collapsed: {good: true, bad: "true"}, unexpected: true}}));
+    setup.session.set(
+        navigation_scroll_storage_key,
+        JSON.stringify({
+            version: 1,
+            state: {
+                positions: {
+                    desktop: {navigation: "docs", pathname: "/one/", documents: -1, outline: 0},
+                    wide: {navigation: "docs", pathname: "/one/", documents: 100, outline: 20},
+                    drawer: {navigation: "docs", pathname: "/one/", documents: 100, outline: "20"},
+                },
+            },
+        }),
+    );
+    const stores = createNavigationStores(setup.options);
+    assert.deepEqual(stores.tree.getState(), {collapsed: {good: true}});
+    assert.deepEqual(stores.scroll.getState().positions.wide, {navigation: "docs", pathname: "/one/", documents: 100, outline: 20});
+    assert.equal(stores.scroll.getState().positions.desktop, undefined);
+    assert.equal(stores.scroll.getState().positions.drawer, undefined);
+});
+
+test("keeps in-memory interaction working when storage reads and writes are blocked", () => {
+    const blocked = () => {
+        throw new Error("Storage blocked");
+    };
+    const stores = createNavigationStores({local: blocked, session: blocked});
+    stores.tree.setState({collapsed: {"document:one": true}});
+    stores.tree.persist.rehydrate();
+    assert.equal(stores.tree.getState().collapsed["document:one"], true);
+    stores.scroll.setState({positions: {desktop: {navigation: "docs", pathname: "/", documents: 100, outline: 200}}});
+    stores.scroll.persist.rehydrate();
+    assert.equal(stores.scroll.getState().positions.desktop?.documents, 100);
+});

package/src/store/navigation/create-navigation-stores.ts

@@ -0,0 +1,73 @@
+import {createJSONStorage, persist, type StateStorage} from "zustand/middleware";
+import {createStore} from "zustand/vanilla";
+import type {NavigationScrollState, NavigationTreeState} from "@/store/navigation/navigation-state";
+import {navigation_scroll_storage_key, navigation_storage_version, navigation_tree_storage_key} from "@/store/navigation/navigation-storage";
+import {toNavigationScrollState} from "@/store/navigation/to-navigation-scroll-state";
+import {toNavigationTreeState} from "@/store/navigation/to-navigation-tree-state";
+
+/**
+ * 브라우저 저장소를 늦게 읽는 경계 · 차단 환경과 테스트의 메모리 저장소 지원
+ */
+interface NavigationStorage {
+    /**
+     * 브라우저 재실행 후에도 유지할 접힘 선택
+     */
+    local: () => StateStorage;
+    /**
+     * 같은 탭 안에서만 복원할 스크롤 위치
+     */
+    session: () => StateStorage;
+}
+
+/**
+ * 브라우저 탐색의 vanilla 스토어 생성기 · Hono Hook이 아닌 생성기이므로 use- 접두사를 붙이지 않음
+ * 서버 요청은 이 생성기를 실행하지 않으며 저장 실패 시 메모리 상태 유지
+ */
+export const createNavigationStores = (options: NavigationStorage) => {
+    /**
+     * 저장소 접근이 막혀도 persist 갱신이 버튼·스크롤 동작을 중단하지 않도록 격리
+     */
+    const toSafeStorage = (getStorage: NavigationStorage["local"]): StateStorage => {
+        return {
+            getItem: (key) => {
+                // persist의 읽기 오류 경로로 보내 기존 메모리 상태를 유지 · null은 실제 저장소 초기화에만 사용
+                return getStorage().getItem(key);
+            },
+            setItem: (key, value) => {
+                try {
+                    return getStorage().setItem(key, value);
+                } catch {
+                    /* 저장 실패 시에도 스토어의 메모리 상태는 유지 */
+                }
+            },
+            removeItem: (key) => {
+                try {
+                    return getStorage().removeItem(key);
+                } catch {
+                    /* 저장소 차단이 탐색을 막지 않음 */
+                }
+            },
+        };
+    };
+
+    return {
+        tree: createStore<NavigationTreeState>()(
+            persist(() => ({collapsed: {}}), {
+                name: navigation_tree_storage_key,
+                version: navigation_storage_version,
+                storage: createJSONStorage(() => toSafeStorage(options.local)),
+                merge: (persisted) => toNavigationTreeState(persisted),
+                migrate: () => ({collapsed: {}}),
+            }),
+        ),
+        scroll: createStore<NavigationScrollState>()(
+            persist(() => ({positions: {}}), {
+                name: navigation_scroll_storage_key,
+                version: navigation_storage_version,
+                storage: createJSONStorage(() => toSafeStorage(options.session)),
+                merge: (persisted) => toNavigationScrollState(persisted),
+                migrate: () => ({positions: {}}),
+            }),
+        ),
+    };
+};

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

@@ -0,0 +1,46 @@
+/**
+ * 스크롤 영역의 배치 · 넓은 3열, 좁은 2열, 모바일 모달
+ */
+export type NavigationLayout = "wide" | "desktop" | "drawer";
+
+/**
+ * 사용자가 명시적으로 바꾼 가지 선택 · 없는 키는 펼침
+ */
+export interface NavigationTreeState {
+    /**
+     * 문서 ID·그룹 전체 경로·페이지별 heading으로 구분한 접힘 상태
+     */
+    collapsed: Record<string, boolean>;
+}
+
+/**
+ * 한 화면 배치의 마지막 탐색 위치 · 목록 변경과 다른 페이지의 목차는 재사용하지 않음
+ */
+export interface NavigationPosition {
+    /**
+     * 현재 사이트의 공통 문서 URL·제목 목록
+     */
+    navigation: string;
+    /**
+     * 목차가 속한 페이지
+     */
+    pathname: string;
+    /**
+     * 공통 문서 목록의 세로 위치
+     */
+    documents: number;
+    /**
+     * 현재 페이지 목차의 세로 위치
+     */
+    outline: number;
+}
+
+/**
+ * 같은 탭 안에서 유지하는 배치별 탐색 위치
+ */
+export interface NavigationScrollState {
+    /**
+     * 아직 열지 않은 배치의 위치는 저장하지 않음
+     */
+    positions: Partial<Record<NavigationLayout, NavigationPosition>>;
+}

package/src/store/navigation/navigation-storage.ts

@@ -0,0 +1,14 @@
+/**
+ * 문서·현재 페이지 목차의 접힘 선택 · 기본은 전체 펼침
+ */
+export const navigation_tree_storage_key = "for-humanity:navigation-tree";
+
+/**
+ * 저장 형태가 바뀌면 기존 자료를 기본 상태로 돌리는 persist 버전
+ */
+export const navigation_storage_version = 1;
+
+/**
+ * 같은 탭에서 문서 이동 후 탐색 위치 복원 · 데스크톱과 드로어는 별도 저장
+ */
+export const navigation_scroll_storage_key = "for-humanity:navigation-scroll";