for-humanity 0.4.4 → 0.6.0

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,18 @@ 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 {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";
@@ -86,10 +88,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,
@@ -97,12 +98,16 @@ const main = async () => {
     ]);
     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, 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") {
@@ -115,12 +120,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;
     }
@@ -128,7 +141,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}/`));
 
     /**
      * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
@@ -140,7 +153,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/_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";

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

@@ -0,0 +1,42 @@
+import type {NavigationPosition, NavigationScrollState} from "@/store/navigation/navigation-state";
+
+/**
+ * 알 수 없는 저장 형태·음수·무한 좌표 제외 · 초기 HTML과 Zustand에 같은 검증 적용
+ */
+export const toNavigationScrollState = (value: unknown): NavigationScrollState => {
+    /**
+     * 한 배치의 완전한 좌표만 복원 대상으로 수용
+     */
+    const toPosition = (position: unknown): NavigationPosition | undefined => {
+        if (
+            typeof position !== "object" ||
+            position === null ||
+            !("navigation" in position) ||
+            typeof position.navigation !== "string" ||
+            !("pathname" in position) ||
+            typeof position.pathname !== "string" ||
+            !("documents" in position) ||
+            typeof position.documents !== "number" ||
+            !Number.isFinite(position.documents) ||
+            position.documents < 0 ||
+            !("outline" in position) ||
+            typeof position.outline !== "number" ||
+            !Number.isFinite(position.outline) ||
+            position.outline < 0
+        ) {
+            return;
+        }
+        return {navigation: position.navigation, pathname: position.pathname, documents: position.documents, outline: position.outline};
+    };
+
+    if (typeof value !== "object" || value === null || !("positions" in value) || typeof value.positions !== "object" || value.positions === null) {
+        return {positions: {}};
+    }
+
+    const positions = {
+        wide: toPosition("wide" in value.positions ? value.positions.wide : undefined),
+        desktop: toPosition("desktop" in value.positions ? value.positions.desktop : undefined),
+        drawer: toPosition("drawer" in value.positions ? value.positions.drawer : undefined),
+    };
+    return {positions: Object.fromEntries(Object.entries(positions).filter((entry) => entry[1] !== undefined))};
+};

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/src/type/site-config.ts

@@ -1,5 +1,5 @@
 import {z} from "zod";
-import {copy_error_navigation_clash, copy_site_title_default} from "@/constant/copy";
+import {copy_error_navigation_clash, copy_error_site_url, copy_site_title_default} from "@/constant/copy";
 import {site_navigation_default} from "@/constant/site";
 import {status_default_phrases, status_kind} from "@/constant/status";
 import {groupPathSchema} from "@/type/group-path";
@@ -17,6 +17,15 @@ export const siteConfigSchema = z.object({
      * HTML 설명 메타데이터 · 선택
      */
     description: z.string().optional(),
+    /**
+     * 공개 사이트 루트 URL · 지정할 때만 robots.txt와 sitemap.xml 생성
+     */
+    url: z
+        .url({protocol: /^https?$/})
+        .transform((value) => new URL(value))
+        .refine((value) => value.username === "" && value.password === "" && value.pathname === "/" && value.search === "" && value.hash === "", copy_error_site_url)
+        .transform((value) => value.origin)
+        .optional(),
     /**
      * 탐색 묶음 경로의 읽는 순서 · 미지정 형제 묶음은 뒤에서 이름순
      */

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