for-humanity 0.2.1 → 0.4.0

package/src/component/widget/shell/_wg-shell-nav-list.css

@@ -13,8 +13,30 @@
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
+    overflow-wrap: anywhere;
+
+    &::before {
+        position: absolute;
+        top: calc(0.5lh + var(--app-space-tree-row));
+        left: 0;
+        width: var(--app-space-tree-indent);
+        border-top: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+}
+
+.wg_shellNavList__link {
+    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
+    position: relative;
+    display: block;
+    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+    color: var(--app-color-link);
+    font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
+    text-decoration: none;
     overflow-wrap: anywhere;
 
     &::before {
@@ -26,6 +48,33 @@
         content: "";
         pointer-events: none;
     }
+
+    &:where(:hover) {
+        text-decoration: underline;
+    }
+
+    &:where(:hover)::before {
+        border-top-color: currentcolor;
+    }
+
+    /* hover와 같은 밑줄·가지선으로 키보드 위치 표시 */
+    &:where(:focus-visible) {
+        outline: none;
+        text-decoration: underline;
+    }
+
+    &:where(:focus-visible)::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellNavList__link--active {
+    color: var(--app-color-link);
+    font-weight: var(--app-font-weight-active);
+
+    &::before {
+        border-top-color: currentcolor;
+    }
 }
 
 .wg_shellNavList__item {
@@ -62,20 +111,20 @@
     }
 
     &:where(:hover)::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     &:where(:has(:focus-visible))::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
     &:where(:has(~ .wg_shellNavList__item:hover))::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     & > .wg_shellNavList__root {
@@ -84,75 +133,39 @@
 
     /* 하위 문서를 탐색할 때 조상 묶음의 가지도 함께 연결 */
     &:where(:hover) > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
+        border-top-color: var(--app-color-link);
     }
 
     &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
+        border-top-color: var(--app-color-link);
+    }
+
+    /* 자식 문서를 탐색할 때 클릭 가능한 부모 문서의 가지도 연결 */
+    &:where(:hover) > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
+    }
+
+    &:where(:has(:focus-visible)) > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
     }
 }
 
 .wg_shellNavList__item--trail {
     &::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 }
 
 .wg_shellNavList__item--current {
     &::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     & > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
-    }
-}
-
-.wg_shellNavList__link {
-    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
-    position: relative;
-    display: block;
-    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text);
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-    text-decoration: none;
-    overflow-wrap: anywhere;
-
-    &::before {
-        position: absolute;
-        top: calc(0.5lh + var(--app-space-tree-row));
-        left: 0;
-        width: var(--app-space-tree-indent);
-        border-top: 1px solid var(--app-color-border-soft);
-        content: "";
-        pointer-events: none;
+        border-top-color: var(--app-color-link);
     }
 
-    &:where(:hover) {
-        text-decoration: underline;
-    }
-
-    &:where(:hover)::before {
-        border-top-color: currentcolor;
-    }
-
-    /* hover와 같은 밑줄·가지선으로 키보드 위치 표시 */
-    &:where(:focus-visible) {
-        outline: none;
-        text-decoration: underline;
-    }
-
-    &:where(:focus-visible)::before {
-        border-top-color: currentcolor;
-    }
-}
-
-.wg_shellNavList__link--active {
-    color: var(--app-color-text-strong);
-    font-weight: var(--app-font-weight-active);
-
-    &::before {
-        border-top-color: currentcolor;
+    & > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
     }
 }

package/src/component/widget/shell/_wg-shell-nav-list.tsx

@@ -19,8 +19,12 @@ export interface WgShellNavListProps {
 }
 
 export const WgShellNavList = (props: WgShellNavListProps) => {
+    const currentAncestors = new Set(props.currentDoc?.ancestors);
     const entries = [
-        ...props.group.docs.map((doc) => ({kind: "document" as const, key: `doc:${doc.id}`, doc, current: doc.id === props.currentDoc?.id})),
+        ...props.group.docs.map((doc) => {
+            const active = doc.id === props.currentDoc?.id;
+            return {kind: "document" as const, key: `doc:${doc.id}`, doc, active, current: active || currentAncestors.has(doc.id)};
+        }),
         ...props.group.groups.map((group) => ({
             kind: "group" as const,
             key: `group:${JSON.stringify(group.path)}`,
@@ -44,17 +48,28 @@ export const WgShellNavList = (props: WgShellNavListProps) => {
                     key={entry.key}
                 >
                     {/**
-                     * 독립 문서 · 키보드 포커스와 현재 페이지 표시는 링크가 담당
+                     * 문서 링크 · 부모도 독립 페이지, 현재 한 문서에만 페이지 상태 부여
                      */}
                     {entry.kind === "document" && (
-                        <a
-                            className={clsx("wg_shellNavList__link", {"wg_shellNavList__link--active": entry.current})}
-                            href={`/${entry.doc.id}/`}
-                            title={entry.doc.data.label}
-                            aria-current={entry.current ? "page" : undefined}
-                        >
-                            {entry.doc.data.name}
-                        </a>
+                        <Fragment>
+                            <a
+                                className={clsx("wg_shellNavList__link", {"wg_shellNavList__link--active": entry.active})}
+                                href={`/${entry.doc.id}/`}
+                                title={entry.doc.data.label}
+                                aria-current={entry.active ? "page" : undefined}
+                            >
+                                {entry.doc.data.name}
+                            </a>
+                            {/**
+                             * 하위 문서 · 부모 아래에서도 기존 목록의 들여쓰기와 키보드 이동 유지
+                             */}
+                            {entry.doc.children !== undefined && (
+                                <WgShellNavList
+                                    group={{name: entry.doc.data.name, path: entry.doc.data.group, docs: entry.doc.children, groups: []}}
+                                    currentDoc={props.currentDoc}
+                                />
+                            )}
+                        </Fragment>
                     )}
                     {/**
                      * 하위 묶음 · 같은 목록을 재귀로 이어 깊이에 따라 들여쓰기

package/src/component/widget/shell/_wg-shell-nav.css

@@ -1,5 +1,5 @@
 /*
- * 읽는 순서의 문서 목록 · 중립색 1px 트리
+ * 읽는 순서의 문서 목록 · 작은 회색 묶음과 링크색 문서
  */
 .wg_shellNav__root {
     font-size: var(--app-font-size-dense);
@@ -15,6 +15,7 @@
 .wg_shellNav__group {
     margin: 0 0 4px;
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
     text-box: trim-start cap alphabetic;
 }

package/src/component/widget/shell/_wg-shell-toc.css

@@ -1,5 +1,5 @@
 /*
- * 문서 탐색 아래 목차 · 작성한 제목과 계층을 유지하는 중립색 트리
+ * 문서 탐색 아래 목차 · 회색 제목·묶음과 본문 글색의 이동 대상 구분
  */
 .wg_shellToc__root {
     margin-top: var(--app-space-group);
@@ -13,14 +13,15 @@
     margin-bottom: var(--app-space-inline);
     color: var(--app-color-text-muted);
     font-size: var(--app-font-size-label);
-    font-weight: var(--app-font-weight-mark);
+    font-weight: var(--app-font-weight-strong);
     letter-spacing: var(--app-letter-spacing-label);
 }
 
 .wg_shellToc__group {
     margin: var(--app-space-stack) 0 4px;
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
 }
 
 .wg_shellToc__list {
@@ -34,7 +35,7 @@
     position: relative;
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text-muted);
+    color: var(--app-color-text);
     font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
     text-decoration: none;
@@ -222,7 +223,7 @@
     position: relative;
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text-muted);
+    color: var(--app-color-text);
     font-size: var(--app-font-size-detail);
     line-height: var(--app-line-height-tight);
     text-decoration: none;

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/copy.ts

@@ -35,7 +35,7 @@ export const copy_home_missing = "문서 폴더에 README.md를 추가하면 이
 /**
  * 현재 문서 목차 라벨
  */
-export const copy_nav_toc_label = "Contents";
+export const copy_nav_toc_label = "On this page";
 
 /**
  * 대소문자만 다른 README 중복 오류
@@ -82,6 +82,21 @@ export const copy_error_doc_id = "문서 id에 사용할 수 없는 경로";
  */
 export const copy_error_doc_id_clash = "문서 id가 겹친다";
 
+/**
+ * 누락되거나 홈을 가리키는 부모 문서 참조
+ */
+export const copy_error_doc_parent_missing = "부모 문서가 없다";
+
+/**
+ * 자기 참조 또는 순환하는 문서 부모 경로
+ */
+export const copy_error_doc_parent_cycle = "문서 parent가 순환한다";
+
+/**
+ * 분류 경로가 다른 문서 사이의 부모 참조
+ */
+export const copy_error_doc_parent_group = "부모 문서와 group이 다르다";
+
 /**
  * 흐름도 렌더링 실패
  */
@@ -106,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";
@@ -160,6 +160,133 @@ test("nested groups follow metadata paths and keep sibling branches and document
     assert.doesNotMatch(html, /<details\b/);
 });
 
+test("parent is an optional nonempty document ID", () => {
+    const data = {name: "Child", label: "Child", group: "Guide"};
+
+    assert.equal(docDataSchema.parse(data).parent, undefined);
+    assert.equal(docDataSchema.parse({...data, parent: " guide/settings "}).parent, "guide/settings");
+    for (const parent of ["", " ", null, 1, [], ["guide"]]) {
+        assert.equal(docDataSchema.safeParse({...data, parent}).success, false);
+    }
+});
+
+test("parent documents contain ordered descendants with independent URLs and one current page", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({navigation: [["Projects", "Atlas", "Guide"]]});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await Promise.all([
+        writeFile(join(root, "settings.md"), "---\nname: Settings\nlabel: Settings\ngroup: [Projects, Atlas, Guide]\norder: 10\n---\n\nSettings introduction.\n"),
+        writeFile(join(root, "guide/site.md"), "---\nname: Site\nlabel: Site\ngroup: [Projects, Atlas, Guide]\nparent: settings\norder: 20\n---\n\nSite introduction.\n"),
+        writeFile(join(root, "themes.md"), "---\nname: Themes\nlabel: Themes\ngroup: [Projects, Atlas, Guide]\nparent: settings\norder: 10\n---\n\nThemes introduction.\n"),
+        writeFile(join(root, "details.md"), "---\nname: Details\nlabel: Details\ngroup: [Projects, Atlas, Guide]\nparent: guide/site\n---\n\nDeep child.\n"),
+        writeFile(join(root, "writing.md"), "---\nname: Writing\nlabel: Writing\ngroup: [Projects, Atlas, Guide]\norder: 20\n---\n\nIndependent guide.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const groups = toDocGroups({docs, navigation: site.navigation});
+    const guide = groups[0].groups[0].groups[0];
+
+    assert.deepEqual(
+        guide.docs.map((doc) => doc.id),
+        ["settings", "writing"],
+    );
+    assert.ok(guide.docs[0].children);
+    assert.deepEqual(
+        guide.docs[0].children.map((doc) => doc.id),
+        ["themes", "guide/site"],
+    );
+    assert.ok(guide.docs[0].children[1].children);
+    assert.deepEqual(
+        guide.docs[0].children[1].children.map((doc) => doc.id),
+        ["details"],
+    );
+    assert.deepEqual(docs.find((doc) => doc.id === "details")?.ancestors, ["settings", "guide/site"]);
+    assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
+
+    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "details"}));
+    assert.match(html, /href="\/settings\/"[^>]*>Settings<\/a><ul\b[^>]*aria-label="Settings"/);
+    assert.match(html, /href="\/guide\/site\/"[^>]*>Site<\/a><ul\b[^>]*aria-label="Site"/);
+    assert.match(html, /href="\/details\/"[^>]*aria-current="page"/);
+    assert.equal([...html.matchAll(/aria-current="page"/g)].length, 1);
+    assert.equal([...html.matchAll(/wg_shellNavList__link--active/g)].length, 1);
+    assert.equal([...html.matchAll(/wg_shellNavList__item--current/g)].length, 5);
+    for (const doc of docs) {
+        assert.equal(html.split(`href="/${doc.id}/"`).length - 1, 1);
+    }
+    assert.ok(html.indexOf('href="/themes/"') < html.indexOf('href="/guide/site/"'));
+    assert.doesNotMatch(renderToStaticMarkup(WgShellNav({site, docs})), /aria-current="page"|wg_shellNavList__item--current/);
+
+    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    for (const doc of docs) {
+        assert.equal((await app.request(`/${doc.id}/`)).status, 200);
+    }
+});
+
+test("relative parent IDs work with both the whole collection and a project document root", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await mkdir(join(root, "project/research"), {recursive: true});
+    await mkdir(join(root, "project/guide"));
+    await Promise.all([
+        writeFile(join(root, "project/research/README.md"), "---\nname: Research\nlabel: Research\ngroup: Guide\n---\n\nResearch introduction.\n"),
+        writeFile(join(root, "project/research/parts.md"), "---\nname: Parts\nlabel: Parts\ngroup: Guide\nparent: ./readme\n---\n\nText.\n"),
+        writeFile(join(root, "project/guide/authoring.md"), "---\nname: Authoring\nlabel: Authoring\ngroup: Guide\nparent: ../research/readme\n---\n\nText.\n"),
+    ]);
+    for (const scope of [root, join(root, "project")]) {
+        const docs = await readDocs({root: scope, processor: createProcessor({site, root: scope})});
+        const parentId = scope === root ? "project/research/readme" : "research/readme";
+        const groups = toDocGroups({docs, navigation: site.navigation});
+        assert.deepEqual(
+            groups[0].docs.map((doc) => doc.id),
+            [parentId],
+        );
+        assert.ok(groups[0].docs[0].children);
+        assert.equal(groups[0].docs[0].children.length, 2);
+        assert.ok(groups[0].docs[0].children.every((doc) => doc.data.parent === parentId));
+        assert.ok(groups[0].docs[0].children.every((doc) => doc.ancestors.length === 1 && doc.ancestors[0] === parentId));
+    }
+});
+
+test("missing and home document parents fail when loading documents", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "README.md"), "# Home\n");
+    for (const parent of ["missing", "readme", "guide.md", "/guide/"]) {
+        await writeFile(join(root, "child.md"), `---\nname: Child\nlabel: Child\ngroup: Guide\nparent: ${parent}\n---\n\nText.\n`);
+        await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /부모 문서가 없다: child/);
+    }
+});
+
+test("self references and cycles fail when loading documents", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "first.md"), "---\nname: First\nlabel: First\ngroup: Guide\nparent: first\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /문서 parent가 순환한다/);
+
+    await writeFile(join(root, "first.md"), "---\nname: First\nlabel: First\ngroup: Guide\nparent: second\n---\n\nText.\n");
+    await writeFile(join(root, "second.md"), "---\nname: Second\nlabel: Second\ngroup: Guide\nparent: third\n---\n\nText.\n");
+    await writeFile(join(root, "third.md"), "---\nname: Third\nlabel: Third\ngroup: Guide\nparent: first\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /문서 parent가 순환한다/);
+});
+
+test("parent and child must use the same complete group path", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "parent.md"), "---\nname: Parent\nlabel: Parent\ngroup: [Projects, Atlas, Research]\n---\n\nText.\n");
+    await writeFile(join(root, "child.md"), "---\nname: Child\nlabel: Child\ngroup: [Projects, Beacon, Research]\nparent: parent\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /부모 문서와 group이 다르다: child/);
+});
+
 test("frontmatter supports BOM, CRLF and a closing fence at EOF", async (t) => {
     const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
     const site = siteConfigSchema.parse({});
@@ -289,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"),
         ),
@@ -306,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"/);
 });
 
@@ -333,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})}), /문서 폴더 밖/);
+});