for-humanity 0.5.0 → 0.7.0

package/src/constant/font.ts

@@ -4,25 +4,15 @@
  */
 
 /**
- * 본문 글꼴 CSS · 패키지 기준 경로 · dynamic subset 92개
+ * 본문·코드 글꼴 CSS · 패키지 기준 경로 · Regular·SemiBold 두 파일
  */
-export const font_sans_css = "src/asset/font/pretendard/pretendardvariable-dynamic-subset.css";
-
-/**
- * 코드 글꼴 CSS · 라틴 subset · 한글은 본문 글꼴
- */
-export const font_mono_css = "src/asset/font/jetbrains-mono/jetbrains-mono.css";
+export const font_mono_css = "src/asset/font/monoplex-kr/monoplex-kr.css";
 
 /**
  * 사이트 이름 글꼴 CSS · Architects Daughter Regular · 라틴 subset
  */
 export const font_brand_css = "src/asset/font/architects-daughter/architects-daughter.css";
 
-/**
- * 탐색·라틴 문자에 필요한 본문 조각 · 92개 전체 선요청 방지
- */
-export const font_sans_preload_file = "PretendardVariable.subset.91.woff2";
-
 /**
  * 늦게 받은 글꼴로 이미 보이는 대체 글꼴을 교체하지 않는 표시 정책
  */

package/src/entry/browser/browser.tsx

@@ -13,7 +13,7 @@ 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});
+        const stores = createNavigationStores({session: () => sessionStorage});
         createRoot(root).render(<WgShellControls data={data} stores={stores} reload={root.hasAttribute("data-shell-reload")} />);
     } catch (error) {
         // 초기화 오류에서도 서버의 링크·본문과 네이티브 스크롤 유지

package/src/entry/cli/_constant/crawling.ts

@@ -0,0 +1,14 @@
+/**
+ * 크롤러 안내 파일의 사이트 루트 경로
+ */
+export const crawling_robots_path = "/robots.txt";
+
+/**
+ * 공개 페이지 목록의 사이트 루트 경로
+ */
+export const crawling_sitemap_path = "/sitemap.xml";
+
+/**
+ * 공개 크롤러 파일과 정적 출력이 충돌하는 문서의 첫 경로 조각
+ */
+export const crawling_reserved_roots = [crawling_robots_path.slice(1), crawling_sitemap_path.slice(1)];

package/src/entry/cli/_function/create-dev-app.ts

@@ -5,6 +5,7 @@ import {type Context, Hono} from "hono";
 import {streamSSE} from "hono/streaming";
 import {asset_content_type_default, asset_content_types, asset_dir, asset_favicon_path, asset_reload_path} from "@/constant/asset";
 import {font_cache_control} from "@/constant/font";
+import {crawling_robots_path, crawling_sitemap_path} from "@/entry/cli/_constant/crawling";
 
 /**
  * 개발 서버 입력 계약
@@ -14,6 +15,10 @@ export interface DevOptions {
      * 정적 자원 외 요청을 처리할 페이지 앱
      */
     pages: Hono;
+    /**
+     * 공개 URL을 설정한 프로젝트의 크롤러 파일 앱
+     */
+    crawling?: Hono;
     /**
      * 자원 URL → 파일 경로 · 정적 빌드와 동일 목록
      */
@@ -25,7 +30,7 @@ export interface DevOptions {
 }
 
 /**
- * 개발 전용 자원·SSE 라우트 · 나머지 요청은 페이지 앱에 위임
+ * 개발 전용 자원·SSE와 선택적 크롤러 응답 · 나머지 요청은 페이지 앱에 위임
  * 정적 빌드의 페이지 라우트와 분리
  */
 export const createDevApp = (options: DevOptions) => {
@@ -73,6 +78,9 @@ export const createDevApp = (options: DevOptions) => {
     );
     app.get(`/${asset_dir}/*`, handleAsset);
     app.get(asset_favicon_path, handleAsset);
+    if (options.crawling !== undefined) {
+        app.on("GET", [crawling_robots_path, crawling_sitemap_path], (c) => options.crawling?.fetch(c.req.raw, c.env) ?? c.notFound());
+    }
     app.all("/*", (c) => options.pages.fetch(c.req.raw, c.env));
 
     return app;

package/src/entry/cli/_function/read-docs.ts

@@ -16,12 +16,30 @@ import type {Doc} from "@/type/doc";
 import {docDataSchema} from "@/type/doc-data";
 import type {DocFileData} from "@/type/doc-file-data";
 
+/**
+ * 문서 폴더를 읽고 명령별 출력 경로와 함께 검증하는 입력
+ */
+export interface ReadDocsParams {
+    /**
+     * CLI에 넘긴 문서 폴더의 절대 경로
+     */
+    root: string;
+    /**
+     * 설정·자원 목록을 연결한 Markdown 처리기
+     */
+    processor: Processor;
+    /**
+     * 명령이 생성할 파일과 충돌하는 첫 경로 조각 · 생략 시 추가 예약 없음
+     */
+    reserved?: readonly string[];
+}
+
 /**
  * Markdown 수집과 렌더링 · 루트 README는 홈, AGENTS·CLAUDE는 작성 지침으로 분리
  * 문서 목록에서 루트 안내 파일·node_modules·dist 제외
  * 머리말·문서 식별자 중복·플러그인 오류 시 실패
  */
-export const readDocs = async (options: {root: string; processor: Processor}): Promise<Doc[]> => {
+export const readDocs = async (options: ReadDocsParams): Promise<Doc[]> => {
     const paths = (await readdir(options.root, {recursive: true})).filter(
         (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep).includes("node_modules") && !path.startsWith(`dist${sep}`),
     );
@@ -39,6 +57,7 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
                 segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment === "index.html") ||
                 /[#?%*:\\]/.test(id) ||
                 /[\p{Cc}]/u.test(id) ||
+                options.reserved?.includes(segments[0]) === true ||
                 segments[0] === asset_dir ||
                 segments[0] === asset_favicon_path.slice(1)
             ) {

package/src/entry/cli/_function/to-crawling-app.ts

@@ -0,0 +1,42 @@
+import {Hono} from "hono";
+import {html} from "hono/html";
+import {crawling_robots_path, crawling_sitemap_path} from "@/entry/cli/_constant/crawling";
+import type {AppOptions} from "@/entry/cli/_function/create-app";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * URL을 명시한 공개 프로젝트의 크롤러 응답 입력
+ */
+export interface CrawlingParams {
+    /**
+     * 설정 검증에서 루트 origin으로 정규화한 공개 HTTP(S) URL
+     */
+    url: NonNullable<SiteConfig["url"]>;
+    /**
+     * dev 파일 변경 시 교체되는 현재 문서 목록 · 본문은 사이트맵에 포함하지 않음
+     */
+    store: AppOptions["store"];
+}
+
+/**
+ * dev와 정적 빌드에서 같은 크롤러 파일 생성 · 정책·수정 시각은 추정하지 않음
+ */
+export const toCrawlingApp = (params: CrawlingParams) => {
+    const app = new Hono();
+
+    app.get(crawling_robots_path, (c) => c.text(`User-agent: *\nAllow: /\n\nSitemap: ${params.url}${crawling_sitemap_path}\n`));
+    app.get(
+        crawling_sitemap_path,
+        (_c) =>
+            new Response(
+                html`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<url><loc>${params.url}/</loc></url>
+${params.store.docs.map((doc) => html`<url><loc>${params.url}/${doc.id.split("/").map(encodeURIComponent).join("/")}/</loc></url>`)}
+</urlset>`.toString(),
+                {headers: {"Content-Type": "application/xml; charset=utf-8"}},
+            ),
+    );
+
+    return app;
+};

package/src/entry/cli/cli.test.ts

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
-import {mkdir, mkdtemp, rm, symlink, writeFile} from "node:fs/promises";
+import {EventEmitter} from "node:events";
+import {mkdir, mkdtemp, readFile, rm, symlink, writeFile} from "node:fs/promises";
 import {tmpdir} from "node:os";
 import {join} from "node:path";
 import {test} from "node:test";
+import {toSSG} from "hono/ssg";
 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";
@@ -10,9 +12,11 @@ import {toNavigationJson} from "@/component/widget/navigation/_function/to-navig
 import {WgNavigation} from "@/component/widget/navigation/wg-navigation";
 import {asset_style_path} from "@/constant/asset";
 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 {toCrawlingApp} from "@/entry/cli/_function/to-crawling-app";
 import {docDataSchema} from "@/type/doc-data";
 import {siteConfigSchema} from "@/type/site-config";
 
@@ -54,6 +58,107 @@ test("page resource URLs use the supplied content fingerprints instead of fixed
     assert.doesNotMatch(html, /(?:href|src)="\/_fh\/(?:style\.css|client\.js)"/);
 });
 
+test("public site URL is opt-in and normalizes an HTTP(S) root URL", () => {
+    assert.deepEqual(siteConfigSchema.parse({url: "https://docs.example.org/"}), {...siteConfigSchema.parse({}), url: "https://docs.example.org"});
+    assert.deepEqual(siteConfigSchema.parse({url: "http://localhost:4321"}), {...siteConfigSchema.parse({}), url: "http://localhost:4321"});
+    assert.equal("url" in siteConfigSchema.parse({}), false);
+});
+
+test("public site URL rejects unsupported protocols, credentials and non-root URLs", () => {
+    for (const url of [
+        "",
+        "/",
+        "file:///docs",
+        "ftp://docs.example.org",
+        "https://user:password@docs.example.org",
+        "https://docs.example.org/docs/",
+        "https://docs.example.org/?q=guide",
+        "https://docs.example.org/#guide",
+    ]) {
+        assert.equal(siteConfigSchema.safeParse({url}).success, false, url);
+    }
+});
+
+test("crawler files are absent when the public site URL is omitted", async () => {
+    const site = siteConfigSchema.parse({});
+    const assets = {fontCss: "", preload: [], reload: false, browserScript: "", stylePath: asset_style_path};
+    const app = createDevApp({pages: createApp({site, store: {docs: []}, assets}), files: new Map(), reload: new EventEmitter()});
+
+    assert.equal((await app.request("/robots.txt")).status, 404);
+    assert.equal((await app.request("/sitemap.xml")).status, 404);
+});
+
+test("crawler files list home and encoded nested document URLs with the current document store", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-crawling-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await writeFile(join(root, "guide.md"), "---\nname: Start\nlabel: Start\ngroup: Guide\n---\n\nStart here.\n");
+    await writeFile(join(root, "guide/한국어 & tools.md"), "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\nText.\n");
+    const site = siteConfigSchema.parse({url: "https://docs.example.org/"});
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const store = {docs};
+    const assets = {fontCss: "", preload: [], reload: false, browserScript: "", stylePath: asset_style_path};
+    assert.ok(site.url);
+    const app = createDevApp({pages: createApp({site, store, assets}), crawling: toCrawlingApp({url: site.url, store}), files: new Map(), reload: new EventEmitter()});
+    const robots = await app.request("/robots.txt");
+    const sitemap = await app.request("/sitemap.xml");
+
+    assert.equal((await app.request("/guide/")).status, 200, "crawler routes must preserve ordinary document routes");
+    assert.equal((await app.request(`/guide/${encodeURIComponent("한국어 & tools")}/`)).status, 200, "crawler routes must preserve nested document routes");
+    assert.equal(robots.status, 200);
+    assert.match(String(robots.headers.get("content-type")), /^text\/plain/);
+    assert.equal(await robots.text(), "User-agent: *\nAllow: /\n\nSitemap: https://docs.example.org/sitemap.xml\n");
+    assert.equal(sitemap.status, 200);
+    assert.match(String(sitemap.headers.get("content-type")), /^application\/xml/);
+    const xml = await sitemap.text();
+    assert.match(xml, /^<\?xml version="1\.0" encoding="UTF-8"\?>/);
+    assert.match(xml, /<urlset xmlns="http:\/\/www\.sitemaps\.org\/schemas\/sitemap\/0\.9">/);
+    assert.match(xml, /<loc>https:\/\/docs\.example\.org\/<\/loc>/);
+    assert.ok(xml.includes(`<loc>https://docs.example.org/guide/${encodeURIComponent("한국어 & tools")}/</loc>`));
+    assert.equal([...xml.matchAll(/<loc>/g)].length, 3);
+    assert.doesNotMatch(xml, /<lastmod>|<changefreq>|<priority>|robots\.txt|sitemap\.xml|_fh|#read/);
+
+    store.docs = [];
+    assert.equal([...(await (await app.request("/sitemap.xml")).text()).matchAll(/<loc>/g)].length, 1);
+});
+
+test("SSG writes crawler files and preserves ordinary and nested document pages", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-crawling-build-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await writeFile(join(root, "guide.md"), "---\nname: Start\nlabel: Start\ngroup: Guide\n---\n\nStart here.\n");
+    await writeFile(join(root, "guide/details.md"), "---\nname: Details\nlabel: Details\ngroup: Guide\n---\n\nNested details.\n");
+    const site = siteConfigSchema.parse({url: "https://docs.example.org"});
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const assets = {fontCss: "", preload: [], reload: false, browserScript: "", stylePath: asset_style_path};
+    const app = createApp({site, store: {docs}, assets});
+    const result = await toSSG(app, {writeFile, mkdir}, {dir: root});
+    assert.ok(site.url);
+    const crawlerResult = await toSSG(toCrawlingApp({url: site.url, store: {docs}}), {writeFile, mkdir}, {dir: root});
+
+    assert.equal(result.success, true);
+    assert.equal(crawlerResult.success, true);
+    assert.equal(result.files.length + crawlerResult.files.length, 5, "home, both documents and both crawler files must be emitted");
+    assert.match(await readFile(join(root, "guide/index.html"), "utf8"), /Start here\./);
+    assert.match(await readFile(join(root, "guide/details/index.html"), "utf8"), /Nested details\./);
+    assert.match(await readFile(join(root, "robots.txt"), "utf8"), /Sitemap: https:\/\/docs\.example\.org\/sitemap\.xml/);
+    assert.match(await readFile(join(root, "sitemap.xml"), "utf8"), /<loc>https:\/\/docs\.example\.org\/<\/loc>/);
+});
+
+test("crawler filenames reject conflicting document roots only when reserved", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-crawling-paths-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "sitemap.xml"));
+    await writeFile(join(root, "Robots.txt.md"), "---\nname: Robots\nlabel: Robots\ngroup: Guide\n---\n\nText.\n");
+    await writeFile(join(root, "sitemap.xml/guide.md"), "---\nname: Sitemap\nlabel: Sitemap\ngroup: Guide\n---\n\nText.\n");
+    const site = siteConfigSchema.parse({});
+    const processor = createProcessor({site, root});
+    const params = {root, processor, reserved: ["robots.txt", "sitemap.xml"]};
+
+    await assert.rejects(readDocs(params), /문서 id에 사용할 수 없는 경로/);
+    assert.equal((await readDocs({root, processor})).length, 2);
+});
+
 test("navigation initialization runs after its DOM and before the document body", async () => {
     const site = siteConfigSchema.parse({});
     const browserScript = "window.navigationFixture = true;";
@@ -209,12 +314,11 @@ test("nested groups follow metadata paths and keep sibling branches and document
     const html = toNavigationHtml({site, docs, current: "authoring"});
 
     assert.match(html, /href="\/authoring\/"[^>]*aria-current="page"/);
-    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.match(html, /Atlas<\/span><ul\b/);
+    assert.match(html, /Research<\/span><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_navigationNavList__item--current/g)].length, 3);
-    assert.doesNotMatch(toNavigationHtml({site, docs}), /aria-current="page"|wg_navigationNavList__item--current/);
+    assert.doesNotMatch(toNavigationHtml({site, docs}), /aria-current="page"/);
     assert.ok(html.indexOf('href="/parts/"') < html.indexOf('href="/authoring/"'));
     assert.doesNotMatch(html, /<details\b/);
 });
@@ -265,17 +369,16 @@ test("parent documents contain ordered descendants with independent URLs and one
     assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
 
     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="\/settings\/"[^>]*>Settings<\/a><ul\b[^>]*aria-label="Settings"/);
+    assert.match(html, /href="\/guide\/site\/"[^>]*>Site<\/a><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_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(toNavigationHtml({site, docs}), /aria-current="page"|wg_navigationNavList__item--current/);
+    assert.doesNotMatch(toNavigationHtml({site, docs}), /aria-current="page"/);
 
     const app = createApp({
         site,

package/src/entry/cli/cli.ts

@@ -7,7 +7,7 @@
 import {EventEmitter} from "node:events";
 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 {dirname, extname, join, relative, resolve, sep} from "node:path";
 import {fileURLToPath, pathToFileURL} from "node:url";
 import {serve} from "@hono/node-server";
 import {serveStatic} from "@hono/node-server/serve-static";
@@ -15,15 +15,17 @@ import {debounce} from "es-toolkit";
 import {Hono} from "hono";
 import {toSSG} from "hono/ssg";
 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 {copy_error_config, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
+import {font_brand_css, font_cache_control, font_mono_css} from "@/constant/font";
 import {site_config_absent} from "@/constant/site";
 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 {crawling_reserved_roots} from "@/entry/cli/_constant/crawling";
 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 {toCrawlingApp} from "@/entry/cli/_function/to-crawling-app";
 import {siteConfigSchema} from "@/type/site-config";
 import {toChangeQueue} from "@/util/async/to-change-queue";
 import {toErrorMessage} from "@/util/error/to-error-message";
@@ -75,33 +77,25 @@ const main = async () => {
 
     const siteConfig = parsedConfig.data;
     // 내장 @font-face와 파일 수집 · font-family는 token.css 소유
-    const sans = toFontCss({css: join(kitRoot, font_sans_css), fontDir: asset_font_dir});
     const mono = toFontCss({css: join(kitRoot, font_mono_css), fontDir: asset_font_dir});
     const brand = toFontCss({css: join(kitRoot, font_brand_css), fontDir: asset_font_dir});
-    const sansPreload = [...sans.files].find((entry) => basename(entry[1]) === font_sans_preload_file);
 
-    if (sansPreload === undefined) {
-        throw new Error(`${copy_error_font_preload}: ${font_sans_preload_file}`);
-    }
-
-    const fontCss = [sans.css, mono.css, brand.css].join("\n");
+    const fontCss = [mono.css, brand.css].join("\n");
     const stylePath = toAssetPath({path: asset_style_path, file: join(kitRoot, "dist/cli.css")});
     const browserScript = readFileSync(join(kitRoot, "dist/browser.js"), "utf8");
-    const kitFiles = new Map([
-        [stylePath, join(kitRoot, "dist/cli.css")],
-        [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")],
-        ...sans.files,
-        ...mono.files,
-        ...brand.files,
-    ]);
+    const kitFiles = new Map([[stylePath, join(kitRoot, "dist/cli.css")], [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")], ...mono.files, ...brand.files]);
     const files = new Map(kitFiles);
     const processor = createProcessor({site: siteConfig, root: docsRoot, files});
-    const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor}), readHome({root: docsRoot, processor})]);
+    const [docs, home] = await Promise.all([
+        readDocs({root: docsRoot, processor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
+        readHome({root: docsRoot, processor}),
+    ]);
     const store = {docs, home};
+    const crawling = siteConfig.url === undefined ? undefined : toCrawlingApp({url: siteConfig.url, store});
     const app = createApp({
         site: siteConfig,
         store,
-        assets: {stylePath, browserScript, fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev"},
+        assets: {stylePath, browserScript, fontCss, preload: [...brand.files.keys(), ...mono.files.keys()], reload: command === "dev"},
     });
 
     if (command === "build") {
@@ -114,12 +108,20 @@ const main = async () => {
             throw result.error;
         }
 
+        const crawlerResult = crawling === undefined ? undefined : await toSSG(crawling, {writeFile, mkdir}, {dir: outDir});
+
+        if (crawlerResult?.success === false) {
+            throw crawlerResult.error;
+        }
+
         for (const [url, file] of files) {
             await mkdir(dirname(join(outDir, url)), {recursive: true});
             await copyFile(file, join(outDir, url));
         }
 
-        console.log(`${result.files.length} pages, ${files.size} assets → ${relative(process.cwd(), outDir)}`);
+        console.log(
+            `${crawlerResult === undefined ? result.files.length : result.files.length + crawlerResult.files.length} files, ${files.size} assets → ${relative(process.cwd(), outDir)}`,
+        );
 
         return;
     }
@@ -127,7 +129,7 @@ const main = async () => {
     const reload = new EventEmitter();
     let generation = 0;
 
-    serve({fetch: createDevApp({pages: app, files, reload}).fetch, port: cli_dev_port}, (info) => console.log(`http://localhost:${info.port}/`));
+    serve({fetch: createDevApp({pages: app, crawling, files, reload}).fetch, port: cli_dev_port}, (info) => console.log(`http://localhost:${info.port}/`));
 
     /**
      * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
@@ -139,7 +141,10 @@ const main = async () => {
                 const currentGeneration = generation;
                 const nextFiles = new Map(kitFiles);
                 const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
-                const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
+                const [docs, home] = await Promise.all([
+                    readDocs({root: docsRoot, processor: nextProcessor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
+                    readHome({root: docsRoot, processor: nextProcessor}),
+                ]);
 
                 if (currentGeneration !== generation) {
                     return;

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

@@ -1,35 +1,25 @@
 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";
+import {navigation_scroll_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>) => ({
+    const storage = {
         getItem: (key: string) => {
-            const value = values.get(key);
+            const value = session.get(key);
             return value === undefined ? null : value;
         },
         setItem: (key: string, value: string) => {
-            values.set(key, value);
+            session.set(key, value);
         },
         removeItem: (key: string) => {
-            values.delete(key);
+            session.delete(key);
         },
-    });
-    return {local, session, options: {local: () => storage(local), session: () => storage(session)}};
+    };
+    return {session, options: {session: () => storage}};
 };
 
-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);
@@ -41,23 +31,19 @@ test("retains independent wide, desktop and drawer scroll positions within a tab
         },
     });
     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}']) {
+    for (const value of ["{", "null", '{"state":null,"version":1}', '{"state":{"positions":{}},"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", () => {
+test("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({
@@ -72,7 +58,6 @@ test("narrows persisted branch flags and rejects invalid scroll coordinates", ()
         }),
     );
     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);
@@ -82,10 +67,7 @@ test("keeps in-memory interaction working when storage reads and writes are bloc
     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);
+    const stores = createNavigationStores({session: blocked});
     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

@@ -1,18 +1,13 @@
 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 type {NavigationScrollState} from "@/store/navigation/navigation-state";
+import {navigation_scroll_storage_key, navigation_storage_version} 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;
     /**
      * 같은 탭 안에서만 복원할 스크롤 위치
      */
@@ -25,9 +20,9 @@ interface NavigationStorage {
  */
 export const createNavigationStores = (options: NavigationStorage) => {
     /**
-     * 저장소 접근이 막혀도 persist 갱신이 버튼·스크롤 동작을 중단하지 않도록 격리
+     * 저장소 접근이 막혀도 persist 갱신이 스크롤 동작을 중단하지 않도록 격리
      */
-    const toSafeStorage = (getStorage: NavigationStorage["local"]): StateStorage => {
+    const toSafeStorage = (getStorage: NavigationStorage["session"]): StateStorage => {
         return {
             getItem: (key) => {
                 // persist의 읽기 오류 경로로 보내 기존 메모리 상태를 유지 · null은 실제 저장소 초기화에만 사용
@@ -51,15 +46,6 @@ export const createNavigationStores = (options: NavigationStorage) => {
     };
 
     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,

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

@@ -3,16 +3,6 @@
  */
 export type NavigationLayout = "wide" | "desktop" | "drawer";
 
-/**
- * 사용자가 명시적으로 바꾼 가지 선택 · 없는 키는 펼침
- */
-export interface NavigationTreeState {
-    /**
-     * 문서 ID·그룹 전체 경로·페이지별 heading으로 구분한 접힘 상태
-     */
-    collapsed: Record<string, boolean>;
-}
-
 /**
  * 한 화면 배치의 마지막 탐색 위치 · 목록 변경과 다른 페이지의 목차는 재사용하지 않음
  */

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

@@ -1,8 +1,3 @@
-/**
- * 문서·현재 페이지 목차의 접힘 선택 · 기본은 전체 펼침
- */
-export const navigation_tree_storage_key = "for-humanity:navigation-tree";
-
 /**
  * 저장 형태가 바뀌면 기존 자료를 기본 상태로 돌리는 persist 버전
  */