for-humanity 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.4.1 — 2026-10-04
+
+- Coalesce consecutive document and asset saves and serialize dev refreshes so bulk AI edits cannot start overlapping full-site renders and exhaust memory.
+- Continue queued and later edits after failed processing, and apply only the latest valid generation.
+
+## 0.4.0 — 2026-10-04
+
+- Copy explicitly referenced local images and supported attachments to fingerprinted asset URLs, resolving paths relative to their Markdown files in both build and dev.
+- Support reference-style images and raw HTML image sources, preserve query/hash suffixes, and reject missing files, unsupported local image formats and paths or symlinks outside the document root.
+- Reload referenced image and attachment changes in dev while retaining the previous valid document and resource map after failed processing.
+- Mark only the current table-of-contents anchor as active, with `aria-current="location"`, while retaining the tree path through its ancestors.
+- Add image documentation, purpose-based authoring guidance and fictional design and research examples.
+- Keep legacy `type: document` and `type: blueprint` inputs compatible, recommend omitting `type`, and focus the roadmap on reusable visualization and theme modules rather than a dedicated Blueprint renderer.
+
 ## 0.3.0 — 2026-10-04
 
 - Support nested document pages with optional `parent` IDs, preserving existing groups and document URLs.

package/README.md

@@ -33,7 +33,7 @@ Write Markdown. Keep the context. Share a static site.
 Node.js 22 or later and pnpm. Install the CLI in your document project:
 
 ```sh
-pnpm add -D --save-exact for-humanity@0.3.0
+pnpm add -D --save-exact for-humanity@0.4.1
 mkdir docs
 ```
 
@@ -52,7 +52,7 @@ pnpm exec for-humanity preview docs
 
 If your Markdown files are in the project root, use `.` instead of `docs`. The root `README.md` becomes the home page; root `AGENTS.md` and `CLAUDE.md` stay out of the site.
 
-Version `0.3.0` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
+Version `0.4.1` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
 Cloudflare Pages can host the generated site. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) for the build settings.
 
 ### Develop the kit
@@ -74,7 +74,7 @@ pnpm preview    # Preview the static site
 pnpm build:pages # Add Cloudflare Pages headers and a 404 page
 ```
 
-Changes pushed to `main` update the documentation site. A stable version tag such as `v0.3.0` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
+Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.1` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
 The npm README updates with each package release. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md#packaging-and-release) for the release steps.
 
 ## Make it yours
@@ -109,7 +109,7 @@ The contract, code or reasoning behind the visible result.
 :::
 ```
 
-[Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) pairs source examples with their rendered results. The [Blueprint sample](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) uses a fictional reading-list app to show a screen flow, decisions, open questions and illustrative API contracts.
+[Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) pairs source examples with their rendered results. The [Design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) uses a fictional reading-list app to show a screen flow, decisions, open questions and illustrative API contracts.
 
 ## Documentation
 
@@ -119,7 +119,7 @@ The contract, code or reasoning behind the visible result.
 | Guide | [Writing](https://github.com/minu-ha/for-humanity/blob/main/templates/document/writing.md) · [Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) · [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) |
 | Reference | [API](https://github.com/minu-ha/for-humanity/blob/main/templates/document/api.md) |
 | Releases | [Official releases](https://github.com/minu-ha/for-humanity/blob/main/templates/document/releases.md) · [Changelog](https://github.com/minu-ha/for-humanity/blob/main/templates/document/changelog.md) |
-| Examples | [Fictional Blueprint](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) |
+| Examples | [Fictional design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) |
 | Development | [Architecture](https://github.com/minu-ha/for-humanity/blob/main/templates/document/architecture.md) · [Design](https://github.com/minu-ha/for-humanity/blob/main/templates/document/design.md) · [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md) · [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) |
 
 ## License

package/dist/cli.js

@@ -2,12 +2,13 @@
 
 // src/cli.ts
 import { EventEmitter } from "node:events";
-import { existsSync as existsSync2, watch } from "node:fs";
+import { existsSync as existsSync3, watch } from "node:fs";
 import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
-import { basename as basename2, dirname as dirname3, join as join4, relative as relative3, resolve as resolve2 } from "node:path";
+import { basename as basename2, dirname as dirname4, extname as extname4, join as join4, relative as relative4, resolve as resolve3, sep as sep3 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { debounce } from "es-toolkit";
 import { Hono as Hono3 } from "hono";
 import { toSSG } from "hono/ssg";
 
@@ -149,6 +150,7 @@ var copy_error_unknown_directive = "\uBAA8\uB974\uB294 \uBD80\uD488\uC774\uB2E4"
 var copy_error_directive_syntax = "\uBD80\uD488 \uBB38\uBC95\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
 var copy_warn_broken_link = "\uC5C6\uB294 \uBB38\uC11C\uB85C \uAC74 \uB9C1\uD06C\uB2E4";
 var copy_warn_unknown_status = "\uC124\uC815\uC5D0 \uC5C6\uB294 \uC0C1\uD0DC \uBB38\uAD6C\uB2E4";
+var copy_error_asset = "\uC790\uC6D0\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
 
 // src/constant/locale.ts
 var locale_doc_name = "en";
@@ -242,9 +244,21 @@ var asset_content_types = {
   ".css": "text/css; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
   ".woff2": "font/woff2",
-  ".svg": "image/svg+xml"
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".pdf": "application/pdf",
+  ".csv": "text/csv; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".zip": "application/zip"
 };
 var asset_content_type_default = "application/octet-stream";
+var asset_media_dir = `/${asset_dir}/media`;
+var asset_media_extensions = /* @__PURE__ */ new Set([".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".pdf", ".csv", ".txt", ".zip"]);
 
 // src/component/widget/shell/wg-shell.tsx
 import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
@@ -336,6 +350,7 @@ var cli_default_command = "dev";
 var cli_default_docs_dir = ".";
 var cli_config_file_name = "for-humanity.config.mjs";
 var cli_dev_port = 4321;
+var cli_reload_delay_ms = 150;
 
 // src/constant/font.ts
 var font_sans_css = "src/asset/font/pretendard/pretendardvariable-dynamic-subset.css";
@@ -968,14 +983,67 @@ var remarkUnknownDirectives = () => (tree, file) => {
   });
 };
 
+// src/content/rehype-assets.ts
+import { existsSync as existsSync2, realpathSync, statSync } from "node:fs";
+import { dirname as dirname2, extname, isAbsolute, relative as relative2, resolve as resolve2, sep } from "node:path";
+import { visit as visit7 } from "unist-util-visit";
+
+// src/util/file/to-asset-path.ts
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { posix as posix2 } from "node:path";
+var toAssetPath = (options) => {
+  const extension = posix2.extname(options.path);
+  return `${posix2.dirname(options.path)}/${posix2.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+};
+
+// src/content/rehype-assets.ts
+var rehypeAssets = (options) => (tree, file) => {
+  visit7(tree, "element", (node) => {
+    const property = node.tagName === "img" ? "src" : "href";
+    const url = node.properties[property];
+    if (node.tagName !== "img" && node.tagName !== "a" || typeof url !== "string" || /^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(url)) {
+      return;
+    }
+    const match = /^([^?#]+)([?#].*)?$/.exec(url);
+    if (match === null) {
+      return;
+    }
+    const path = decodeURIComponent(match[1]);
+    const extension = extname(path).toLowerCase();
+    if (!asset_media_extensions.has(extension)) {
+      if (node.tagName === "img") {
+        file.fail(`${copy_error_asset}: \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uB294 \uC774\uBBF8\uC9C0 \uD615\uC2DD \xB7 ${url}`, node);
+      }
+      return;
+    }
+    const target = resolve2(dirname2(file.path), path);
+    const location = relative2(options.root, target);
+    if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+      file.fail(`${copy_error_asset}: \uBB38\uC11C \uD3F4\uB354 \uBC16 \xB7 ${url}`, node);
+    }
+    if (!existsSync2(target)) {
+      file.fail(`${copy_error_asset}: \uD30C\uC77C\uC774 \uC5C6\uB2E4 \xB7 ${url}`, node);
+    }
+    const actual = realpathSync(target);
+    const actualLocation = relative2(realpathSync(options.root), actual);
+    if (actualLocation === ".." || actualLocation.startsWith(`..${sep}`) || isAbsolute(actualLocation) || !statSync(actual).isFile()) {
+      file.fail(`${copy_error_asset}: \uBB38\uC11C \uD3F4\uB354 \uBC16\uC774\uAC70\uB098 \uC77C\uBC18 \uD30C\uC77C\uC774 \uC544\uB2C8\uB2E4 \xB7 ${url}`, node);
+    }
+    const assetUrl = toAssetPath({ path: `${asset_media_dir}/asset${extension}`, file: actual });
+    options.files.set(assetUrl, actual);
+    node.properties[property] = match[2] === void 0 ? assetUrl : `${assetUrl}${match[2]}`;
+  });
+};
+
 // src/content/rehype-heading-ids.ts
 import Slugger from "github-slugger";
 import { toString as toPlainText3 } from "hast-util-to-string";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 var rehypeHeadingIds = () => (tree, file) => {
   const slugger = new Slugger();
   const headings = [];
-  visit7(tree, "element", (node) => {
+  visit8(tree, "element", (node) => {
     const depth = /^h([1-6])$/.exec(node.tagName)?.[1];
     if (depth === void 0) {
       return;
@@ -991,9 +1059,9 @@ var rehypeHeadingIds = () => (tree, file) => {
 };
 
 // src/content/remark-report.ts
-import { relative as relative2 } from "node:path";
+import { relative as relative3 } from "node:path";
 var remarkReport = (options) => (_tree, file) => {
-  const path = relative2(options.root, file.path);
+  const path = relative3(options.root, file.path);
   for (const message of file.messages) {
     console.warn(`${message.line === void 0 ? path : `${path}:${message.line}`} ${message.reason}`);
   }
@@ -1001,12 +1069,12 @@ var remarkReport = (options) => (_tree, file) => {
 
 // src/content/create-processor.ts
 var createProcessor = (options) => {
-  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeStringify, { allowDangerousHtml: true });
+  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeAssets, { root: options.root, files: options.files ?? /* @__PURE__ */ new Map() }).use(rehypeStringify, { allowDangerousHtml: true });
 };
 
 // src/content/read-docs.ts
 import { readdir, readFile } from "node:fs/promises";
-import { join, posix as posix2, sep } from "node:path";
+import { join, posix as posix3, sep as sep2 } from "node:path";
 import { VFile } from "vfile";
 import { parse as parseYaml } from "yaml";
 
@@ -1035,7 +1103,7 @@ var docDataSchema = z2.object({
    */
   label: z2.string(),
   /**
-   * 문서 종류 · blueprint 전용 표현 미구현
+   * 기존 type 값 호환 · 생략 권장, 렌더링 차이 없음
    */
   type: z2.enum(doc_type).default(doc_type.document),
   /**
@@ -1055,11 +1123,11 @@ var docDataSchema = z2.object({
 // src/content/read-docs.ts
 var readDocs = async (options) => {
   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}`)
+    (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep2).includes("node_modules") && !path.startsWith(`dist${sep2}`)
   );
   const docs = await Promise.all(
     paths.map(async (path) => {
-      const id = path.replace(/\.mdx?$/i, "").split(sep).join("/").toLowerCase();
+      const id = path.replace(/\.mdx?$/i, "").split(sep2).join("/").toLowerCase();
       const segments = id.split("/");
       if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment === "index.html") || /[#?%*:\\]/.test(id) || /[\p{Cc}]/u.test(id) || segments[0] === asset_dir || segments[0] === asset_favicon_path.slice(1)) {
         throw new Error(`${copy_error_doc_id}: ${path}`);
@@ -1074,7 +1142,7 @@ var readDocs = async (options) => {
       }
       const data = {
         ...parsed.data,
-        parent: parsed.data.parent !== void 0 && /^\.\.?\//.test(parsed.data.parent) ? posix2.join(posix2.dirname(id), parsed.data.parent) : parsed.data.parent
+        parent: parsed.data.parent !== void 0 && /^\.\.?\//.test(parsed.data.parent) ? posix3.join(posix3.dirname(id), parsed.data.parent) : parsed.data.parent
       };
       const fh = { frontmatter: data, headings: [], sections: [] };
       file.data.fh = fh;
@@ -1135,7 +1203,7 @@ var readHome = async (options) => {
 
 // src/dev.ts
 import { readFile as readFile3 } from "node:fs/promises";
-import { extname } from "node:path";
+import { extname as extname2 } from "node:path";
 import { Hono as Hono2 } from "hono";
 import { streamSSE } from "hono/streaming";
 var createDevApp = (options) => {
@@ -1145,8 +1213,8 @@ var createDevApp = (options) => {
     if (file === void 0) {
       return c.notFound();
     }
-    c.header("content-type", asset_content_types[extname(file)] ?? asset_content_type_default);
-    if (extname(file) === ".woff2") {
+    c.header("content-type", asset_content_types[extname2(file).toLowerCase()] ?? asset_content_type_default);
+    if (extname2(file) === ".woff2") {
       c.header("Cache-Control", font_cache_control);
     }
     return c.body(await readFile3(file));
@@ -1222,6 +1290,32 @@ var siteConfigSchema = z3.object({
   ).default(status_default_phrases)
 });
 
+// src/util/async/to-change-queue.ts
+var toChangeQueue = (options) => {
+  const state = { requested: 0, completed: 0, running: false };
+  return async () => {
+    state.requested += 1;
+    if (state.running) {
+      return;
+    }
+    state.running = true;
+    try {
+      while (state.completed !== state.requested) {
+        const requested = state.requested;
+        try {
+          await options.run();
+        } catch (error) {
+          options.onError(error);
+        } finally {
+          state.completed = requested;
+        }
+      }
+    } finally {
+      state.running = false;
+    }
+  };
+};
+
 // src/util/error/to-error-message.ts
 var toErrorMessage = (error) => {
   if (error instanceof Error && "file" in error && typeof error.file === "string" && "line" in error && typeof error.line === "number") {
@@ -1230,25 +1324,16 @@ var toErrorMessage = (error) => {
   return error instanceof Error ? error.message : String(error);
 };
 
-// src/util/file/to-asset-path.ts
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { posix as posix3 } from "node:path";
-var toAssetPath = (options) => {
-  const extension = posix3.extname(options.path);
-  return `${posix3.dirname(options.path)}/${posix3.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
-};
-
 // src/util/font/to-font-css.ts
 import { createHash as createHash2 } from "node:crypto";
 import { readFileSync as readFileSync2 } from "node:fs";
-import { basename, dirname as dirname2, extname as extname2, join as join3 } from "node:path";
+import { basename, dirname as dirname3, extname as extname3, join as join3 } from "node:path";
 var toFontCss = (options) => {
   const files = /* @__PURE__ */ new Map();
   const css = [...readFileSync2(options.css, "utf8").matchAll(/@font-face\s*\{[^}]*\}/g)].map(
     (match) => match[0].replace(/font-display:\s*[^;]+;/g, `font-display: ${font_display_strategy};`).replace(/url\(([^)]+)\)/g, (_match, relativeUrl) => {
-      const file = join3(dirname2(options.css), relativeUrl);
-      const extension = extname2(file);
+      const file = join3(dirname3(options.css), relativeUrl);
+      const extension = extname3(file);
       const hash = createHash2("sha256").update(readFileSync2(file)).digest("hex").slice(0, font_hash_length);
       const url = `${options.fontDir}/${basename(file, extension)}.${hash}${extension}`;
       files.set(url, file);
@@ -1266,14 +1351,14 @@ var main = async () => {
     throw new Error(`${copy_error_unknown_command}: ${command} (${commands.join(", ")})`);
   }
   const kitRoot = fileURLToPath(new URL("../", import.meta.url));
-  const docsRoot = resolve2(docsDir);
+  const docsRoot = resolve3(docsDir);
   const outDir = join4(docsRoot, "dist");
   if (command === "preview") {
     const app2 = new Hono3();
     app2.use(
       "/*",
       serveStatic({
-        root: relative3(process.cwd(), outDir),
+        root: relative4(process.cwd(), outDir),
         onFound: (_path, c) => {
           if (c.req.path.startsWith(`${asset_font_dir}/`)) {
             c.header("Cache-Control", font_cache_control);
@@ -1285,7 +1370,7 @@ var main = async () => {
     return;
   }
   const configFile = join4(docsRoot, cli_config_file_name);
-  const parsedConfig = siteConfigSchema.safeParse(existsSync2(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
+  const parsedConfig = siteConfigSchema.safeParse(existsSync3(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
   if (!parsedConfig.success) {
     throw new Error(`${copy_error_config}: ${parsedConfig.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
   }
@@ -1300,7 +1385,7 @@ var main = async () => {
   const fontCss = [sans.css, mono.css, brand.css].join("\n");
   const stylePath = toAssetPath({ path: asset_style_path, file: join4(kitRoot, "dist/cli.css") });
   const clientPath = toAssetPath({ path: asset_client_path, file: join4(kitRoot, "dist/client.js") });
-  const files = new Map([
+  const kitFiles = new Map([
     [stylePath, join4(kitRoot, "dist/cli.css")],
     [clientPath, join4(kitRoot, "dist/client.js")],
     [asset_favicon_path, join4(kitRoot, "src/asset/favicon.svg")],
@@ -1308,7 +1393,8 @@ var main = async () => {
     ...mono.files,
     ...brand.files
   ]);
-  const processor = createProcessor({ site: siteConfig, root: docsRoot });
+  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 store = { docs, home };
   const app = createApp({
@@ -1323,31 +1409,46 @@ var main = async () => {
       throw result.error;
     }
     for (const [url, file] of files) {
-      await mkdir(dirname3(join4(outDir, url)), { recursive: true });
+      await mkdir(dirname4(join4(outDir, url)), { recursive: true });
       await copyFile(file, join4(outDir, url));
     }
-    console.log(`${result.files.length} pages, ${files.size} assets \u2192 ${relative3(process.cwd(), outDir)}`);
+    console.log(`${result.files.length} pages, ${files.size} assets \u2192 ${relative4(process.cwd(), outDir)}`);
     return;
   }
   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}/`));
-  const handleDocsChange = async (_event, filename) => {
-    if (filename !== null && !/\.mdx?$/i.test(filename)) {
-      return;
-    }
-    const currentGeneration = ++generation;
-    try {
-      const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor }), readHome({ root: docsRoot, processor })]);
-      if (currentGeneration !== generation) {
+  const reloadDocs = debounce(
+    toChangeQueue({
+      run: async () => {
+        const currentGeneration = generation;
+        const nextFiles = new Map(kitFiles);
+        const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
+        const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
+        if (currentGeneration !== generation) {
+          return;
+        }
+        files.clear();
+        for (const entry of nextFiles) {
+          files.set(...entry);
+        }
+        store.docs = docs2;
+        store.home = home2;
+        reload.emit("change");
+      },
+      onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`)
+    }),
+    cli_reload_delay_ms
+  );
+  const handleDocsChange = (_event, filename) => {
+    if (filename !== null) {
+      const segments = filename.split(sep3);
+      if (segments.includes("dist") || segments.includes("node_modules") || !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname4(filename).toLowerCase())) {
         return;
       }
-      store.docs = docs2;
-      store.home = home2;
-      reload.emit("change");
-    } catch (error) {
-      console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
     }
+    generation += 1;
+    reloadDocs();
   };
   watch(docsRoot, { recursive: true }, handleDocsChange);
 };

package/dist/client.js

@@ -1,5 +1,5 @@
-var L="fh-cursor-face";var S="(width < 1024px)";var p=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var m=e=>{let t=p(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var k=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),r=document.querySelector("[data-navigation-open]"),u=document.querySelector("[data-navigation-close]"),d=e?.parentElement;if(!e||!t||!n||!r||!u||!d)return;let s=matchMedia(S),l=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),r.setAttribute("aria-expanded","false"))},h=()=>{t.close(),l()},a=()=>{!s.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),r.setAttribute("aria-expanded","true"))},c=o=>{let i=t.getBoundingClientRect();o.target===t&&(o.clientX<i.left||o.clientX>i.right||o.clientY<i.top||o.clientY>i.bottom)&&h()},q=o=>{if(!t.open||o.defaultPrevented||o.button!==0||o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||!(o.target instanceof Element))return;let i=o.target.closest("a[href]");if(!(!(i instanceof HTMLAnchorElement)||i.target!==""&&i.target!=="_self"||i.hasAttribute("download"))&&(h(),i.origin===location.origin&&i.pathname===location.pathname&&i.search===location.search&&i.hash)){let T=m(i.hash);T&&(T.tabIndex=-1,T.focus({preventScroll:!0}))}},H=()=>{let o=document.activeElement;if(s.matches){r.classList.add("wg_shell__menuToggle--visible"),n.append(e),o instanceof HTMLElement&&e.contains(o)&&r.focus({preventScroll:!0});return}h(),d.append(e),o instanceof HTMLElement&&e.contains(o)?o.focus({preventScroll:!0}):(o===r||o instanceof HTMLElement&&t.contains(o))&&d.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),r.classList.remove("wg_shell__menuToggle--visible")};r.addEventListener("click",a),u.addEventListener("click",h),t.addEventListener("close",l),t.addEventListener("click",c),e.addEventListener("click",q),s.addEventListener("change",H),H(),d.classList.add("wg_shell__sidebar--navigationReady")};k();var g=document.querySelector("[data-cursor-face]");if(g){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,g.classList.remove("wg_shell__cursorFace--visible")},r=()=>{e.matches||n()},u=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,g.style.transform=`translate3d(
+var L="fh-cursor-face";var k="(width < 1024px)";var p=e=>{if(!e)return null;try{return document.getElementById(decodeURIComponent(e.slice(1)))}catch(t){if(t instanceof URIError)return null;throw t}};var m=e=>{let t=p(e);for(let n=t?.closest("details");n;n=n.parentElement?.closest("details"))n.open=!0;return t};var S=()=>{let e=document.querySelector("[data-navigation]"),t=document.querySelector("[data-navigation-drawer]"),n=document.querySelector("[data-navigation-content]"),i=document.querySelector("[data-navigation-open]"),d=document.querySelector("[data-navigation-close]"),c=e?.parentElement;if(!e||!t||!n||!i||!d||!c)return;let l=matchMedia(k),a=()=>{t.open||(document.body.classList.remove("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","false"))},u=()=>{t.close(),a()},h=()=>{!l.matches||t.open||(t.showModal(),document.body.classList.add("wg_shell__root--drawerOpen"),i.setAttribute("aria-expanded","true"))},r=o=>{let s=t.getBoundingClientRect();o.target===t&&(o.clientX<s.left||o.clientX>s.right||o.clientY<s.top||o.clientY>s.bottom)&&u()},q=o=>{if(!t.open||o.defaultPrevented||o.button!==0||o.metaKey||o.ctrlKey||o.shiftKey||o.altKey||!(o.target instanceof Element))return;let s=o.target.closest("a[href]");if(!(!(s instanceof HTMLAnchorElement)||s.target!==""&&s.target!=="_self"||s.hasAttribute("download"))&&(u(),s.origin===location.origin&&s.pathname===location.pathname&&s.search===location.search&&s.hash)){let T=m(s.hash);T&&(T.tabIndex=-1,T.focus({preventScroll:!0}))}},H=()=>{let o=document.activeElement;if(l.matches){i.classList.add("wg_shell__menuToggle--visible"),n.append(e),o instanceof HTMLElement&&e.contains(o)&&i.focus({preventScroll:!0});return}u(),c.append(e),o instanceof HTMLElement&&e.contains(o)?o.focus({preventScroll:!0}):(o===i||o instanceof HTMLElement&&t.contains(o))&&c.querySelector(".wg_shell__brand")?.focus({preventScroll:!0}),i.classList.remove("wg_shell__menuToggle--visible")};i.addEventListener("click",h),d.addEventListener("click",u),t.addEventListener("close",a),t.addEventListener("click",r),e.addEventListener("click",q),l.addEventListener("change",H),H(),c.classList.add("wg_shell__sidebar--navigationReady")};S();var g=document.querySelector("[data-cursor-face]");if(g){let e=matchMedia("(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)"),t={x:0,y:0,frame:0},n=()=>{cancelAnimationFrame(t.frame),t.frame=0,g.classList.remove("wg_shell__cursorFace--visible")},i=()=>{e.matches||n()},d=()=>{t.frame===0&&(t.frame=requestAnimationFrame(()=>{t.frame=0,g.style.transform=`translate3d(
                 ${Math.max(0,Math.min(t.x+16,document.documentElement.clientWidth-g.width-16))}px,
                 ${Math.max(0,Math.min(t.y+16,document.documentElement.clientHeight-g.height-16))}px,
                 0
-            )`,g.classList.add("wg_shell__cursorFace--visible")}))},d=a=>{if(!(e.matches&&a.pointerType==="mouse")){n();return}t.x=a.clientX,t.y=a.clientY,u()},s=()=>{g.classList.contains("wg_shell__cursorFace--visible")&&u()},l=()=>{if(g.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(L,JSON.stringify({x:t.x,y:t.y}))}catch{}},h=()=>{try{let a=sessionStorage.getItem(L);if(sessionStorage.removeItem(L),a!==null&&e.matches){let c=JSON.parse(a);typeof c=="object"&&c!==null&&"x"in c&&"y"in c&&typeof c.x=="number"&&typeof c.y=="number"&&Number.isFinite(c.x)&&Number.isFinite(c.y)&&(t.x=c.x,t.y=c.y,u())}}catch{}};h(),document.addEventListener("pointermove",d,{passive:!0}),document.addEventListener("pointerdown",d,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",s),addEventListener("pagehide",l),addEventListener("pageshow",h),e.addEventListener("change",r)}var v=m(location.hash),_=null,b=0,f=null,x=()=>{clearTimeout(b),f?.abort(),f=null,_?.classList.remove("wg_prose__headingText--highlighted"),_=null},M=e=>{x(),_=e===null?null:e.querySelector(".wg_prose__headingText"),_!==null&&(_.classList.add("wg_prose__headingText--highlighted"),b=window.setTimeout(x,3e3),f=new AbortController,document.addEventListener("scrollend",B,{signal:f.signal}))},B=e=>{e.target===document&&(clearTimeout(b),f?.abort(),f=null,b=window.setTimeout(x,3e3))},N=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=m(e.currentTarget.hash);e.currentTarget.hash===location.hash&&M(t)}},K=()=>{let e=m(location.hash);e?.scrollIntoView(),M(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",N);addEventListener("hashchange",K);var y=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=p(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(r=>{let u=p(r.hash),d=r.parentElement;return u&&d?[{heading:u,link:r,item:d}]:[]})}]}),w=y.at(0);if(w){let e=()=>{let t=Number.parseFloat(getComputedStyle(w.heading).scrollMarginTop)+1,n=y.findLast(s=>s.heading.checkVisibility()&&s.heading.getBoundingClientRect().top<=t)??w,r=n.subs.findLast(s=>s.heading.checkVisibility()&&s.heading.getBoundingClientRect().top<=t),u=y.indexOf(n),d=r===void 0?-1:n.subs.indexOf(r);for(let[s,l]of y.entries()){l.link.classList.toggle("wg_shellToc__link--active",l===n),l.item.classList.toggle("wg_shellToc__item--trail",l.list===n.list&&s<u),l.item.classList.toggle("wg_shellToc__item--current",l===n);for(let[h,a]of l.subs.entries())a.link.classList.toggle("wg_shellToc__subLink--active",a===r),a.item.classList.toggle("wg_shellToc__subItem--trail",l===n&&h<d),a.item.classList.toggle("wg_shellToc__subItem--current",a===r)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var I=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>I.abort(),{once:!0,passive:!0});var A=async()=>{await document.fonts.ready,v&&!I.signal.aborted&&(v.scrollIntoView({behavior:"instant"}),M(v)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?A():addEventListener("load",A,{once:!0});
+            )`,g.classList.add("wg_shell__cursorFace--visible")}))},c=h=>{if(!(e.matches&&h.pointerType==="mouse")){n();return}t.x=h.clientX,t.y=h.clientY,d()},l=()=>{g.classList.contains("wg_shell__cursorFace--visible")&&d()},a=()=>{if(g.classList.contains("wg_shell__cursorFace--visible"))try{sessionStorage.setItem(L,JSON.stringify({x:t.x,y:t.y}))}catch{}},u=()=>{try{let h=sessionStorage.getItem(L);if(sessionStorage.removeItem(L),h!==null&&e.matches){let r=JSON.parse(h);typeof r=="object"&&r!==null&&"x"in r&&"y"in r&&typeof r.x=="number"&&typeof r.y=="number"&&Number.isFinite(r.x)&&Number.isFinite(r.y)&&(t.x=r.x,t.y=r.y,d())}}catch{}};u(),document.addEventListener("pointermove",c,{passive:!0}),document.addEventListener("pointerdown",c,{passive:!0}),document.documentElement.addEventListener("pointerleave",n),addEventListener("blur",n),addEventListener("resize",l),addEventListener("pagehide",a),addEventListener("pageshow",u),e.addEventListener("change",i)}var v=m(location.hash),_=null,y=0,f=null,x=()=>{clearTimeout(y),f?.abort(),f=null,_?.classList.remove("wg_prose__headingText--highlighted"),_=null},M=e=>{x(),_=e===null?null:e.querySelector(".wg_prose__headingText"),_!==null&&(_.classList.add("wg_prose__headingText--highlighted"),y=window.setTimeout(x,3e3),f=new AbortController,document.addEventListener("scrollend",B,{signal:f.signal}))},B=e=>{e.target===document&&(clearTimeout(y),f?.abort(),f=null,y=window.setTimeout(x,3e3))},N=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=m(e.currentTarget.hash);e.currentTarget.hash===location.hash&&M(t)}},K=()=>{let e=m(location.hash);e?.scrollIntoView(),M(e)};for(let e of document.querySelectorAll("a[href]"))e.addEventListener("click",N);addEventListener("hashchange",K);var E=[...document.querySelectorAll("[data-toc-link]")].flatMap(e=>{let t=p(e.hash),n=e.parentElement;return!t||!n?[]:[{heading:t,link:e,item:n,list:n.parentElement,subs:[...n.querySelectorAll("[data-toc-sub-link]")].flatMap(i=>{let d=p(i.hash),c=i.parentElement;return d&&c?[{heading:d,link:i,item:c}]:[]})}]}),w=E.at(0);if(w){let e=()=>{let t=Number.parseFloat(getComputedStyle(w.heading).scrollMarginTop)+1,n=E.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t)??w,i=n.subs.findLast(l=>l.heading.checkVisibility()&&l.heading.getBoundingClientRect().top<=t),d=E.indexOf(n),c=i===void 0?-1:n.subs.indexOf(i);for(let[l,a]of E.entries()){let u=a===n&&i===void 0;a.link.classList.toggle("wg_shellToc__link--active",u),u?a.link.setAttribute("aria-current","location"):a.link.removeAttribute("aria-current"),a.item.classList.toggle("wg_shellToc__item--trail",a.list===n.list&&l<d),a.item.classList.toggle("wg_shellToc__item--current",a===n);for(let[h,r]of a.subs.entries())r.link.classList.toggle("wg_shellToc__subLink--active",r===i),r===i?r.link.setAttribute("aria-current","location"):r.link.removeAttribute("aria-current"),r.item.classList.toggle("wg_shellToc__subItem--trail",a===n&&h<c),r.item.classList.toggle("wg_shellToc__subItem--current",r===i)}};addEventListener("scroll",e,{passive:!0}),addEventListener("resize",e),addEventListener("toggle",e,!0),e()}var I=new AbortController;for(let e of["wheel","touchmove","keydown","mousedown"])addEventListener(e,()=>I.abort(),{once:!0,passive:!0});var A=async()=>{await document.fonts.ready,v&&!I.signal.aborted&&(v.scrollIntoView({behavior:"instant"}),M(v)),document.documentElement.style.removeProperty("scroll-behavior")};document.readyState==="complete"?A():addEventListener("load",A,{once:!0});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.3.0",
+    "version": "0.4.1",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",
@@ -41,7 +41,7 @@
         "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build templates/document",
         "build:pages": "pnpm build && node util/prepare-pages.mjs",
         "preview": "node dist/cli.js preview templates/document",
-        "test": "esbuild src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
+        "test": "esbuild src/util/async/to-change-queue.test.ts src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/util/async/*.test.mjs node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
         "lint": "biome check && stylelint \"src/**/*.css\"",
         "lint:fix": "biome check --write && stylelint \"src/**/*.css\" --fix",
         "typecheck": "tsc --noEmit",

package/src/cli.ts

@@ -7,15 +7,16 @@
 import {EventEmitter} from "node:events";
 import {existsSync, watch} from "node:fs";
 import {copyFile, mkdir, rm, writeFile} from "node:fs/promises";
-import {basename, dirname, join, relative, resolve} from "node:path";
+import {basename, 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";
+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_style_path} from "@/constant/asset";
-import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port} from "@/constant/cli";
+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 {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";
@@ -24,6 +25,7 @@ import {readDocs} from "@/content/read-docs";
 import {readHome} from "@/content/read-home";
 import {createDevApp} from "@/dev";
 import {siteConfigSchema} from "@/type/site-config";
+import {toChangeQueue} from "@/util/async/to-change-queue";
 import {toErrorMessage} from "@/util/error/to-error-message";
 import {toAssetPath} from "@/util/file/to-asset-path";
 import {toFontCss} from "@/util/font/to-font-css";
@@ -85,7 +87,7 @@ 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 files = new Map([
+    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")],
@@ -93,7 +95,8 @@ const main = async () => {
         ...mono.files,
         ...brand.files,
     ]);
-    const processor = createProcessor({site: siteConfig, root: docsRoot});
+    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 store = {docs, home};
     const app = createApp({
@@ -128,30 +131,46 @@ const main = async () => {
     serve({fetch: createDevApp({pages: app, files, reload}).fetch, port: cli_dev_port}, (info) => console.log(`http://localhost:${info.port}/`));
 
     /**
-     * Markdown 변경 시 전체 재처리와 새로고침
-     * 재처리 실패 시 직전 정상 문서 유지
+     * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
+     * 문서 수가 많아도 파일 이벤트마다 전체 렌더링이 동시에 쌓이지 않음
      */
-    const handleDocsChange = async (_event: string, filename: string | null) => {
-        if (filename !== null && !/\.mdx?$/i.test(filename)) {
-            return;
-        }
-
-        const currentGeneration = ++generation;
-
-        try {
-            const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor}), readHome({root: docsRoot, processor})]);
+    const reloadDocs = debounce(
+        toChangeQueue({
+            run: 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})]);
+
+                if (currentGeneration !== generation) {
+                    return;
+                }
+
+                files.clear();
+                for (const entry of nextFiles) {
+                    files.set(...entry);
+                }
+                store.docs = docs;
+                store.home = home;
+                reload.emit("change");
+            },
+            onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`),
+        }),
+        cli_reload_delay_ms,
+    );
 
-            // 최신 변경의 처리 결과만 반영
-            if (currentGeneration !== generation) {
+    /**
+     * 입력 변경 감지 · 출력·설치 폴더 제외 · 누락 자원 추가도 다시 확인
+     */
+    const handleDocsChange = (_event: string, filename: string | null) => {
+        if (filename !== null) {
+            const segments = filename.split(sep);
+            if (segments.includes("dist") || segments.includes("node_modules") || (!/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))) {
                 return;
             }
-
-            store.docs = docs;
-            store.home = home;
-            reload.emit("change");
-        } catch (error) {
-            console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
         }
+        generation += 1;
+        reloadDocs();
     };
 
     watch(docsRoot, {recursive: true}, handleDocsChange);

package/src/client.ts

@@ -275,12 +275,23 @@ if (firstSection) {
         const currentSubIndex = sub === undefined ? -1 : current.subs.indexOf(sub);
 
         for (const [index, section] of tocSections.entries()) {
-            section.link.classList.toggle("wg_shellToc__link--active", section === current);
+            const active = section === current && sub === undefined;
+            section.link.classList.toggle("wg_shellToc__link--active", active);
+            if (active) {
+                section.link.setAttribute("aria-current", "location");
+            } else {
+                section.link.removeAttribute("aria-current");
+            }
             section.item.classList.toggle("wg_shellToc__item--trail", section.list === current.list && index < currentIndex);
             section.item.classList.toggle("wg_shellToc__item--current", section === current);
 
             for (const [subIndex, item] of section.subs.entries()) {
                 item.link.classList.toggle("wg_shellToc__subLink--active", item === sub);
+                if (item === sub) {
+                    item.link.setAttribute("aria-current", "location");
+                } else {
+                    item.link.removeAttribute("aria-current");
+                }
                 item.item.classList.toggle("wg_shellToc__subItem--trail", section === current && subIndex < currentSubIndex);
                 item.item.classList.toggle("wg_shellToc__subItem--current", item === sub);
             }

package/src/constant/asset.ts

@@ -40,9 +40,29 @@ export const asset_content_types: Record<string, string> = {
     ".js": "text/javascript; charset=utf-8",
     ".woff2": "font/woff2",
     ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".zip": "application/zip",
 };
 
 /**
  * 미등록 확장자의 content-type
  */
 export const asset_content_type_default = "application/octet-stream";
+
+/**
+ * 문서에서 참조한 그림·첨부 자원의 예약 경로
+ */
+export const asset_media_dir = `/${asset_dir}/media`;
+
+/**
+ * 명시적 로컬 참조로 배포할 수 있는 파일 형식 · 실행 파일·소스·설정 제외
+ */
+export const asset_media_extensions = new Set([".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".pdf", ".csv", ".txt", ".zip"]);

package/src/constant/cli.ts

@@ -17,3 +17,8 @@ export const cli_config_file_name = "for-humanity.config.mjs";
  * dev·preview 공통 포트
  */
 export const cli_dev_port = 4321;
+
+/**
+ * 연속 저장을 하나의 문서 갱신으로 합치는 대기 시간 · ms
+ */
+export const cli_reload_delay_ms = 150;

package/src/constant/copy.ts

@@ -121,3 +121,8 @@ export const copy_warn_broken_link = "없는 문서로 건 링크다";
  * 미등록 날짜 상태 문구 경고
  */
 export const copy_warn_unknown_status = "설정에 없는 상태 문구다";
+
+/**
+ * 문서에서 참조한 로컬 자원의 경로·형식 오류
+ */
+export const copy_error_asset = "자원이 올바르지 않다";

package/src/constant/doc.ts

@@ -1,6 +1,6 @@
 /**
- * 문서 종류 · document 글 정리, blueprint 화면 설계
- * blueprint 전용 표현 미구현
+ * 기존 frontmatter type의 호환 값 · 모두 같은 Markdown 렌더링
+ * 새 문서는 type 생략 권장
  */
 export const doc_type = {
     document: "document",

package/src/content/create-processor.ts

@@ -19,6 +19,7 @@ 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 type {SiteConfig} from "@/type/site-config";
@@ -28,7 +29,7 @@ import type {SiteConfig} from "@/type/site-config";
  * 플러그인 HTML 조각은 마지막 rehype-raw에서 해석
  * Shiki inline style: token.css의 --app-code-* 참조
  */
-export const createProcessor = (options: {site: SiteConfig; root: string}) => {
+export const createProcessor = (options: {site: SiteConfig; root: string; files?: Map<string, string>}) => {
     return unified()
         .use(remarkParse)
         .use(remarkFrontmatter, ["yaml"])
@@ -50,6 +51,7 @@ export const createProcessor = (options: {site: SiteConfig; root: string}) => {
         .use(rehypeSections)
         .use(rehypeTables)
         .use(rehypeRaw)
+        .use(rehypeAssets, {root: options.root, files: options.files ?? new Map<string, string>()})
         .use(rehypeStringify, {allowDangerousHtml: true});
 };
 

package/src/content/read-docs.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import {mkdir, mkdtemp, rm, writeFile} from "node:fs/promises";
+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";
@@ -416,7 +416,7 @@ test("relative Markdown links preserve query strings and fragments", async (t) =
                 "[Fragment](../api.mdx#details?literal=yes)",
                 "[External](https://example.com/api.md?mode=compact#details)",
                 "[Absolute](/api.md?mode=compact#details)",
-                "[Asset](diagram.svg?version=2#label)",
+                "[Asset](/diagram.svg?version=2#label)",
                 "[Local](#details?literal=yes)",
             ].join("\n\n"),
         ),
@@ -433,7 +433,7 @@ test("relative Markdown links preserve query strings and fragments", async (t) =
     assert.match(setup.html, /href="\/api\/#details\?literal=yes"/);
     assert.match(setup.html, /href="https:\/\/example\.com\/api\.md\?mode=compact#details"/);
     assert.match(setup.html, /href="\/api\.md\?mode=compact#details"/);
-    assert.match(setup.html, /href="diagram\.svg\?version=2#label"/);
+    assert.match(setup.html, /href="\/diagram\.svg\?version=2#label"/);
     assert.match(setup.html, /href="#details\?literal=yes"/);
 });
 
@@ -460,3 +460,53 @@ test("headings and contents preserve authored text without automatic numbering",
     assert.match(html, /wg_shellToc__group">Setup<\/div>/);
     assert.doesNotMatch(html, /wg_prose__num|wg_shellToc__mark/);
 });
+
+test("local Markdown and raw HTML images share fingerprinted assets with attachments", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-media-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await mkdir(join(root, "img"));
+    await writeFile(join(root, "img", "sample.svg"), '<svg xmlns="http://www.w3.org/2000/svg"/>');
+    await writeFile(join(root, "guide", "report.csv"), "name,value\nsample,1\n");
+    await writeFile(
+        join(root, "guide", "page.md"),
+        '---\nname: Media\nlabel: Media\ngroup: Guide\n---\n\n![Image](../img/sample.svg)\n\n![Reference][shot]\n\n[shot]: ../img/sample.svg\n\n<img src="../img/sample.svg" alt="Raw" />\n\n[Download](report.csv?download=1#rows)\n\n![External](https://example.com/image.png)\n',
+    );
+    const files = new Map<string, string>();
+    const docs = await readDocs({root, processor: createProcessor({site: siteConfigSchema.parse({}), root, files})});
+    assert.equal(files.size, 2);
+    assert.equal(docs[0].html.match(/src="\/_fh\/media\/asset\.[a-f0-9]+\.svg"/g)?.length, 3);
+    assert.match(docs[0].html, /href="\/_fh\/media\/asset\.[a-f0-9]+\.csv\?download=1#rows"/);
+    assert.match(docs[0].html, /src="https:\/\/example.com\/image.png"/);
+});
+
+test("missing local images and paths outside the document root fail instead of producing broken output", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-media-"));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await writeFile(join(root, "page.md"), "---\nname: Media\nlabel: Media\ngroup: Guide\n---\n\n![Missing](missing.png)\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site: siteConfigSchema.parse({}), root})}), /자원/);
+    await writeFile(join(root, "page.md"), "---\nname: Media\nlabel: Media\ngroup: Guide\n---\n\n![Outside](../outside.png)\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site: siteConfigSchema.parse({}), root})}), /문서 폴더 밖/);
+});
+
+test("home images use the chosen root and symlink escapes cannot publish outside files", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-media-"));
+    const outside = await mkdtemp(join(tmpdir(), "for-humanity-outside-"));
+    t.after(() => Promise.all([rm(root, {recursive: true, force: true}), rm(outside, {recursive: true, force: true})]));
+    await writeFile(join(root, "local image.png"), "first");
+    await writeFile(join(root, "README.md"), "# Home\n\n![Home](local%20image.png)\n");
+    const files = new Map<string, string>();
+    const site = siteConfigSchema.parse({});
+    const home = await readHome({root, processor: createProcessor({site, root, files})});
+    assert.equal(files.size, 1);
+    const before = [...files.keys()][0];
+    assert.ok(home?.html.includes(before));
+    await writeFile(join(root, "local image.png"), "changed");
+    const updated = new Map<string, string>();
+    await readHome({root, processor: createProcessor({site, root, files: updated})});
+    assert.notEqual([...updated.keys()][0], before);
+    await writeFile(join(outside, "private.png"), "private");
+    await symlink(join(outside, "private.png"), join(root, "linked.png"));
+    await writeFile(join(root, "README.md"), "# Home\n\n![Private](linked.png)\n");
+    await assert.rejects(readHome({root, processor: createProcessor({site, root})}), /문서 폴더 밖/);
+});

package/src/content/rehype-assets.ts

@@ -0,0 +1,70 @@
+import {existsSync, realpathSync, statSync} from "node:fs";
+import {dirname, extname, isAbsolute, relative, resolve, sep} from "node:path";
+import type {Root} from "hast";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {asset_media_dir, asset_media_extensions} from "@/constant/asset";
+import {copy_error_asset} from "@/constant/copy";
+import {toAssetPath} from "@/util/file/to-asset-path";
+
+/**
+ * 명시적으로 참조한 로컬 이미지·첨부의 수집 계약
+ */
+export interface AssetOptions {
+    /**
+     * 자원을 읽을 수 있는 문서 루트
+     */
+    root: string;
+    /**
+     * dev 응답과 정적 복사에서 공유할 URL → 파일 목록
+     */
+    files: Map<string, string>;
+}
+
+/**
+ * 파일 위치 기준 이미지·첨부 → 내용 지문 URL · 원시 HTML도 같은 규칙
+ * 없는 파일, 폴더 밖 경로와 symlink, 지원하지 않는 이미지 형식은 빌드 실패
+ * 절대 URL·외부 URL은 작성자가 제공하며 수집하지 않음
+ */
+export const rehypeAssets = (options: AssetOptions) => (tree: Root, file: VFile) => {
+    visit(tree, "element", (node) => {
+        const property = node.tagName === "img" ? "src" : "href";
+        const url = node.properties[property];
+
+        if ((node.tagName !== "img" && node.tagName !== "a") || typeof url !== "string" || /^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(url)) {
+            return;
+        }
+
+        const match = /^([^?#]+)([?#].*)?$/.exec(url);
+        if (match === null) {
+            return;
+        }
+
+        const path = decodeURIComponent(match[1]);
+        const extension = extname(path).toLowerCase();
+        if (!asset_media_extensions.has(extension)) {
+            if (node.tagName === "img") {
+                file.fail(`${copy_error_asset}: 지원하지 않는 이미지 형식 · ${url}`, node);
+            }
+            return;
+        }
+
+        const target = resolve(dirname(file.path), path);
+        const location = relative(options.root, target);
+        if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+            file.fail(`${copy_error_asset}: 문서 폴더 밖 · ${url}`, node);
+        }
+        if (!existsSync(target)) {
+            file.fail(`${copy_error_asset}: 파일이 없다 · ${url}`, node);
+        }
+        const actual = realpathSync(target);
+        const actualLocation = relative(realpathSync(options.root), actual);
+        if (actualLocation === ".." || actualLocation.startsWith(`..${sep}`) || isAbsolute(actualLocation) || !statSync(actual).isFile()) {
+            file.fail(`${copy_error_asset}: 문서 폴더 밖이거나 일반 파일이 아니다 · ${url}`, node);
+        }
+
+        const assetUrl = toAssetPath({path: `${asset_media_dir}/asset${extension}`, file: actual});
+        options.files.set(assetUrl, actual);
+        node.properties[property] = match[2] === undefined ? assetUrl : `${assetUrl}${match[2]}`;
+    });
+};

package/src/dev.ts

@@ -41,7 +41,7 @@ export const createDevApp = (options: DevOptions) => {
             return c.notFound();
         }
 
-        c.header("content-type", asset_content_types[extname(file)] ?? asset_content_type_default);
+        c.header("content-type", asset_content_types[extname(file).toLowerCase()] ?? asset_content_type_default);
 
         if (extname(file) === ".woff2") {
             c.header("Cache-Control", font_cache_control);

package/src/type/doc-data.ts

@@ -15,7 +15,7 @@ export const docDataSchema = z.object({
      */
     label: z.string(),
     /**
-     * 문서 종류 · blueprint 전용 표현 미구현
+     * 기존 type 값 호환 · 생략 권장, 렌더링 차이 없음
      */
     type: z.enum(doc_type).default(doc_type.document),
     /**

package/src/util/async/to-change-queue.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import {test} from "node:test";
+import {toChangeQueue} from "@/util/async/to-change-queue";
+
+test("coalesces changes during an active render and never overlaps work", async () => {
+    const gate = Promise.withResolvers<void>();
+    const renders: number[] = [];
+    const errors: unknown[] = [];
+    let version = 1;
+    let running = 0;
+    const queue = toChangeQueue({
+        run: async () => {
+            running += 1;
+            assert.equal(running, 1);
+            const current = version;
+            if (current === 1) await gate.promise;
+            renders.push(current);
+            running -= 1;
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    for (const next of [2, 3, 4, 5]) {
+        version = next;
+        await queue();
+    }
+    gate.resolve();
+    await first;
+    assert.deepEqual(renders, [1, 5]);
+    assert.deepEqual(errors, []);
+});
+
+test("a failed render does not lose a queued recovery or block later edits", async () => {
+    const gate = Promise.withResolvers<void>();
+    const errors: unknown[] = [];
+    const renders: number[] = [];
+    let version = 1;
+    const queue = toChangeQueue({
+        run: async () => {
+            const current = version;
+            if (current === 1) {
+                await gate.promise;
+                throw new Error("Invalid source");
+            }
+            renders.push(current);
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    version = 2;
+    await queue();
+    gate.resolve();
+    await first;
+    version = 3;
+    await queue();
+    assert.deepEqual(renders, [2, 3]);
+    assert.equal(errors.length, 1);
+});

package/src/util/async/to-change-queue.ts

@@ -0,0 +1,43 @@
+/**
+ * 변경 재처리의 실행과 오류 보고 계약
+ */
+export interface ChangeQueueOptions {
+    /**
+     * 한 번의 최신 입력 처리 · 이전 실행이 끝난 뒤 호출
+     */
+    run: () => Promise<void>;
+    /**
+     * 실패 보고 · 대기 중인 변경과 다음 실행은 유지
+     */
+    onError: (error: unknown) => void;
+}
+
+/**
+ * 동시에 하나만 실행하는 변경 요청 함수 · 실행 중 요청은 다음 한 번으로 합침
+ * 활성 실행의 반환 Promise는 대기 요청까지 끝나면 완료, 중첩 요청은 즉시 반환
+ */
+export const toChangeQueue = (options: ChangeQueueOptions) => {
+    const state = {requested: 0, completed: 0, running: false};
+
+    return async () => {
+        state.requested += 1;
+        if (state.running) {
+            return;
+        }
+        state.running = true;
+        try {
+            while (state.completed !== state.requested) {
+                const requested = state.requested;
+                try {
+                    await options.run();
+                } catch (error) {
+                    options.onError(error);
+                } finally {
+                    state.completed = requested;
+                }
+            }
+        } finally {
+            state.running = false;
+        }
+    };
+};