hd-garden 0.9.0 → 0.9.1

package/app/bookshelf/load.mjs

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+import { gardenSiteRoot } from "../../scripts/garden-paths.mjs";
+import { bookshelfMountFromFile, normalizeBookshelfPostPath } from "../components/bookshelf/catalog.mjs";
+import { BookshelfConfigError, parseBookshelfConfig } from "../components/bookshelf/schema.mjs";
+
+export function bookshelfConfigPath(root = gardenSiteRoot()) {
+  return path.join(root, "content", "bookshelf.yaml");
+}
+
+/**
+ * The site shelf, or null when `content/bookshelf.yaml` is absent.
+ * Absent means the package demo (click-test only). A file here is the live shelf:
+ * each book's `post` is read from `content/posts` and turned into note HTML.
+ * `preparedPosts`, when passed, are the sync pipeline's posts (rewritten asset
+ * URLs). Otherwise the markdown files are read directly.
+ * Throws `BookshelfConfigError` when the file, a cover, or a post path is broken.
+ */
+export function loadBookshelf(root = gardenSiteRoot(), preparedPosts) {
+  const file = bookshelfConfigPath(root);
+  if (!fs.existsSync(file)) return null;
+  let parsed;
+  try {
+    parsed = parseYaml(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "无法解析";
+    throw new BookshelfConfigError("invalid-root", `content/bookshelf.yaml 无法解析：${detail}`);
+  }
+  const config = parseBookshelfConfig(parsed);
+  const sources = preparedPosts
+    ? preparedPosts.map((post) => ({
+      path: post.path,
+      title: post.title,
+      description: post.description,
+      cover: post.cover,
+      content: post.content,
+    }))
+    : readReferencedPosts(root, config);
+  return bookshelfMountFromFile(config, sources);
+}
+
+function readReferencedPosts(root, config) {
+  const seen = new Set();
+  const posts = [];
+  for (const shelf of config.shelves) {
+    for (const book of shelf.books) {
+      if (!book.post) continue;
+      const relative = normalizeBookshelfPostPath(book.post);
+      if (seen.has(relative)) continue;
+      seen.add(relative);
+      posts.push(readPost(root, relative));
+    }
+  }
+  return posts;
+}
+
+function readPost(root, postPath) {
+  const relative = normalizeBookshelfPostPath(postPath);
+  const postsRoot = path.resolve(root, "content", "posts");
+  const file = `${path.resolve(postsRoot, ...relative.split("/"))}.md`;
+  if (!file.startsWith(`${postsRoot}${path.sep}`)) {
+    throw new BookshelfConfigError("post", `post「${postPath}」必须是 content/posts 下的路径，不带 .md。`);
+  }
+  if (!fs.existsSync(file)) {
+    throw new BookshelfConfigError("post", `content/bookshelf.yaml 引用的博文 ${relative} 不存在。`);
+  }
+  let parsed;
+  try {
+    parsed = matter(fs.readFileSync(file, "utf8"), {
+      engines: {
+        yaml: {
+          parse: (input) => parseYaml(input) ?? {},
+        },
+      },
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "无法解析";
+    throw new BookshelfConfigError("post", `博文 ${relative} 无法解析：${detail}`);
+  }
+  const data = parsed.data && typeof parsed.data === "object" ? parsed.data : {};
+  return {
+    path: relative,
+    title: optionalString(data.title),
+    description: optionalString(data.description),
+    cover: optionalString(data.cover),
+    content: parsed.content,
+  };
+}
+
+function optionalString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}

package/app/bookshelf/load.ts

@@ -1,23 +1,16 @@
-import fs from "node:fs";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { gardenSiteRoot } from "../../scripts/garden-paths.mjs";
-import { BookshelfConfigError, parseBookshelfConfig, type BookshelfFile } from "../components/bookshelf/schema";
+import type { BookshelfMount } from "../components/bookshelf/catalog";
+import { bookshelfConfigPath as configPath, loadBookshelf as readShelf } from "./load.mjs";
 
-export function bookshelfConfigPath(root = gardenSiteRoot()) {
-  return path.join(root, "content", "bookshelf.yaml");
+export type { BookshelfMount };
+
+export function bookshelfConfigPath(root?: string) {
+  return configPath(root) as string;
 }
 
-/** Site shelf, or null when the site has no `content/bookshelf.yaml`. */
-export function loadBookshelf(): BookshelfFile | null {
-  const file = bookshelfConfigPath();
-  if (!fs.existsSync(file)) return null;
-  let parsed: unknown;
-  try {
-    parsed = parseYaml(fs.readFileSync(file, "utf8"));
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : "无法解析";
-    throw new BookshelfConfigError("invalid-root", `content/bookshelf.yaml 无法解析：${detail}`);
-  }
-  return parseBookshelfConfig(parsed);
+/**
+ * The site shelf, or null when `content/bookshelf.yaml` is absent.
+ * Absent means the package demo. See `load.mjs` for the file contract.
+ */
+export function loadBookshelf(root?: string): BookshelfMount | null {
+  return readShelf(root) as BookshelfMount | null;
 }

package/app/bookshelf/page.tsx

@@ -1,19 +1,52 @@
 import type { Metadata } from "next";
+import { bookshelf } from "@garden/bookshelf";
 import { Bookshelf } from "../components/bookshelf";
 import { siteLang } from "../lib/i18n";
-
-const preview = siteLang === "zh";
-
-export const metadata: Metadata = preview
-  ? { title: { absolute: "花园 · 读书笔记" }, robots: { index: false, follow: false } }
-  : { title: "Bookshelf", robots: { index: false, follow: false } };
+import { pageAlternates } from "../lib/page-alternates";
+import { siteConfig } from "../site.config";
 
 /**
- * Click-test route for the approved shelf.
- * States: ?mode=covers (A), default spines (B), hover one spine (C). ?debug=1 shows the demo's mode buttons.
- * English sites skip the Chinese demo markup so a locale=en build stays free of CJK.
+ * `/bookshelf` contract:
+ * - `content/bookshelf.yaml` present → that shelf, with each `post` rendered
+ *   into `notes`, inside the site header. Indexed like the other pages.
+ * - file absent → package demo (Chinese click-test only, noindex, no site chrome).
+ *   English builds skip the demo so a locale=en site stays free of that markup.
  */
+export async function generateMetadata(): Promise<Metadata> {
+  const shelf = bookshelf;
+  if (shelf) {
+    return {
+      title: shelf.title,
+      description: shelf.description,
+      alternates: pageAlternates("/bookshelf"),
+    };
+  }
+  if (siteLang === "zh") {
+    return { title: { absolute: "花园 · 读书笔记" }, robots: { index: false, follow: false } };
+  }
+  return { title: "Bookshelf", robots: { index: false, follow: false } };
+}
+
 export default function BookshelfPage() {
-  if (!preview) return null;
+  const shelf = bookshelf;
+  if (shelf) {
+    return (
+      <main className="sh-main bookshelf-page" id="content">
+        <header className="sh-head">
+          {shelf.eyebrow ? <p className="sh-kicker">{shelf.eyebrow}</p> : null}
+          <h1 id="sh-title">{shelf.title}</h1>
+          {shelf.description ? <p className="sh-deck">{shelf.description}</p> : null}
+        </header>
+        <Bookshelf
+          embedded
+          catalog={shelf.catalog}
+          notes={shelf.notes}
+          title={shelf.title}
+          eyebrow={shelf.eyebrow ?? siteConfig.name}
+        />
+      </main>
+    );
+  }
+  if (siteLang !== "zh") return null;
   return <Bookshelf />;
 }

package/app/components/SiteChrome.tsx

@@ -5,7 +5,14 @@ import { inAppPath, isHandbookPath, routeLang, ui } from "../lib/i18n";
 import { SiteFooter } from "./SiteFooter";
 import { SiteHeader } from "./SiteHeader";
 
-export function SiteChrome({ children }: { children: React.ReactNode }) {
+export function SiteChrome({
+  children,
+  bookshelfSite = false,
+}: {
+  children: React.ReactNode;
+  /** True when the site has content/bookshelf.yaml. The package demo stays chrome-less. */
+  bookshelfSite?: boolean;
+}) {
   const pathname = usePathname();
   const lang = routeLang(pathname);
   // The skip link follows the route language too (/garden/en/ is English).
@@ -14,18 +21,19 @@ export function SiteChrome({ children }: { children: React.ReactNode }) {
       {ui(lang).skipToContent}
     </a>
   );
-  // The shelf preview is the approved demo viewport, not a page inside the site header.
-  // Static export serves /bookshelf/ ; an exact "/bookshelf" check leaves the chrome on.
+  // The package demo (no content/bookshelf.yaml) is the approved chrome-less viewport.
+  // A site shelf is a normal page, so it keeps the header and footer.
+  // Static export serves /bookshelf/ ; an exact "/bookshelf" check would miss it.
   const path = inAppPath(pathname);
-  const shelfPreview = path === "/bookshelf" || path.startsWith("/bookshelf/");
-  if (path.startsWith("/admin") || shelfPreview) {
+  const shelfDemo = !bookshelfSite && (path === "/bookshelf" || path.startsWith("/bookshelf/"));
+  if (path.startsWith("/admin") || shelfDemo) {
     return <>{skip}{children}</>;
   }
 
   return (
     <>
       {skip}
-      <SiteHeader />
+      <SiteHeader shelf={bookshelfSite} />
       <div id="main-content">{children}</div>
       <SiteFooter docs={isHandbookPath(pathname)} lang={lang} />
     </>

package/app/components/SiteHeader.tsx

@@ -16,7 +16,7 @@ import { brand, searchFull, searchIndexUrl } from "@garden/site-config";
 import { createSearch } from "../../ui/garden/search-match.mjs";
 import { cropMatchedText, highlightParts } from "../../ui/garden/search-preview.mjs";
 import { resolveDark, themeSwitchProps } from "../../ui/garden/theme.mjs";
-import { SITE_NAV, isCurrentNav } from "../../ui/garden/site-nav.mjs";
+import { siteNav, isCurrentNav } from "../../ui/garden/site-nav.mjs";
 import { isHandbookPath, routeLang, ui } from "../lib/i18n";
 import { HandbookLangSwitch } from "./HandbookLangSwitch";
 import { createIdbStore, loadFullIndex, saveDataOn, whenIdleAfterLoad } from "../../ui/garden/search-full.mjs";
@@ -89,7 +89,6 @@ function loadSearchEngine() {
   return engineLoad;
 }
 
-const nav = SITE_NAV.map((item) => ({ ...item, key: item.href, href: siteHref(item.href) }));
 
 function rangesFor(
   matches: readonly SearchMatch[] | undefined,
@@ -140,7 +139,8 @@ function searchPreview(
   return { prefix: "", text: item.description, suffix: "", ranges: [] };
 }
 
-export function SiteHeader() {
+export function SiteHeader({ shelf = false }: { shelf?: boolean }) {
+  const nav = siteNav({ shelf }).map((item) => ({ ...item, key: item.href, href: siteHref(item.href) }));
   const pathname = usePathname() || "/";
   const t = ui(routeLang(pathname));
   const [menuOpen, setMenuOpen] = useState(false);

package/app/components/bookshelf/Bookshelf.tsx

@@ -1,16 +1,53 @@
 "use client";
 
 import { useLayoutEffect, useRef } from "react";
+import { siteHref } from "../../lib/site-href";
 import { mountBookshelf } from "./engine";
-import type { BookshelfProps } from "./types";
+import type { BookshelfProps, BookshelfShelf } from "./types";
 import "./bookshelf.css";
 
-const SHELL = `
+const SHELF_SCROLL_KEY = "garden-bookshelf-scroll";
+
+function withNoteLinks(catalog: BookshelfShelf[] | undefined) {
+  if (!catalog) return catalog;
+  return catalog.map((row) => ({
+    ...row,
+    books: row.books.map((book) =>
+      book.post ? { ...book, href: siteHref(`/blog/${book.post}`) } : book,
+    ),
+  }));
+}
+
+function readSavedScroll() {
+  try {
+    const raw = sessionStorage.getItem(SHELF_SCROLL_KEY);
+    if (raw == null) return null;
+    sessionStorage.removeItem(SHELF_SCROLL_KEY);
+    const y = Number(raw);
+    return Number.isFinite(y) ? y : null;
+  } catch {
+    return null;
+  }
+}
+
+const DEMO_BRAND = "花园 · 读书笔记";
+const DEMO_TITLE = "读书笔记";
+
+function escapeHtml(value: string) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function shelfShell(brand: string, title: string) {
+  return `
     <div class="shelf-view" id="shelfView">
       <div class="page">
         <header class="top">
-          <div class="brand">花园 · 读书笔记</div>
-          <h1>读书笔记</h1>
+          <div class="brand">${escapeHtml(brand)}</div>
+          <h1>${escapeHtml(title)}</h1>
           <p class="lede is-debug" id="lede" hidden>调试说明：页级疏密；悬停/点按展一本；再点进笔记。</p>
           <div class="qa-bar is-debug" id="qaBar" role="group" aria-label="演示控制" hidden>
             <span class="qa-label">页级态</span>
@@ -37,6 +74,7 @@ const SHELL = `
             <p class="note-cat" id="noteCat"></p>
             <h1 id="noteTitle"></h1>
             <p class="note-author" id="noteAuthor"></p>
+            <a class="note-read" id="noteRead" hidden>阅读全文</a>
           </div>
         </div>
         <div class="note-body" id="noteBody"></div>
@@ -49,14 +87,31 @@ const SHELL = `
     </div>
     <div class="stage" id="stage" aria-hidden="true"></div>
 `;
+}
 
-/** Approved bookshelf. Pass `catalog` and `notes` to mount another shelf on the same motion. */
-export function Bookshelf({ catalog, notes }: BookshelfProps) {
+/** Approved bookshelf. Pass `catalog` and `notes` for a site shelf; omit them for the package demo. */
+export function Bookshelf({ catalog, notes, title, eyebrow, embedded = false }: BookshelfProps) {
   const ref = useRef<HTMLDivElement>(null);
   useLayoutEffect(() => {
     const root = ref.current;
     if (!root) return;
-    return mountBookshelf(root, { catalog, notes });
-  }, [catalog, notes]);
-  return <div className="bookshelf-demo" ref={ref} dangerouslySetInnerHTML={{ __html: SHELL }} />;
+    const saved = embedded ? readSavedScroll() : null;
+    const applyScroll = () => {
+      if (saved != null) window.scrollTo(0, saved);
+    };
+    applyScroll();
+    const unmount = mountBookshelf(root, { catalog: withNoteLinks(catalog), notes });
+    const frame = window.requestAnimationFrame(applyScroll);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      unmount?.();
+    };
+  }, [catalog, notes, title, eyebrow, embedded]);
+  return (
+    <div
+      className={embedded ? "bookshelf-demo is-site" : "bookshelf-demo"}
+      ref={ref}
+      dangerouslySetInnerHTML={{ __html: shelfShell(eyebrow || DEMO_BRAND, title || DEMO_TITLE) }}
+    />
+  );
 }

package/app/components/bookshelf/bookshelf.css

@@ -6,7 +6,10 @@
 .bookshelf-demo .cover.is-extracting:hover,
 .bookshelf-demo .spine.is-extracting,
 .bookshelf-demo .spine.is-extracting:hover,
-.bookshelf-demo .spine.is-extracting.is-expanded {
+.bookshelf-demo .spine.is-extracting.is-expanded,
+.bookshelf-demo .spine.is-seat,
+.bookshelf-demo .spine.is-seat:hover,
+.bookshelf-demo .spine.is-seat:focus-visible {
   transform: none !important;
   box-shadow: none !important;
   transition: none !important;
@@ -674,7 +677,7 @@
   contain: layout style;
 }
 .bookshelf-demo .flyer.is-ready {
-  will-change: transform, opacity;
+  will-change: translate, scale, opacity;
 }
 
 /* Soft oval foot shadow — no filter:blur (blur+anim = jitter) */
@@ -1165,3 +1168,121 @@
 
 /* Reading path: hide demo/QA chrome unless ?debug=1 */
 body:not(.debug-on) .bookshelf-demo .is-debug { display: none !important; }
+
+/* Site shelf: same column, type, and header as the blog. Motion rules above stay. */
+.bookshelf-page.sh-main {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+.bookshelf-page .sh-head {
+  width: 100%;
+  max-width: var(--col);
+  margin-inline: auto;
+}
+.bookshelf-page .sh-kicker {
+  margin: 0 0 12px;
+  font-size: var(--fs-meta);
+  letter-spacing: 0.08em;
+  color: var(--muted);
+}
+.bookshelf-demo.is-site {
+  --site-sans: -apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Segoe UI", system-ui, sans-serif;
+  width: 100%;
+  max-width: var(--col);
+  margin-inline: auto;
+  background: transparent;
+  min-height: 0;
+  color: inherit;
+  font-family: var(--site-sans);
+  font-size: inherit;
+  line-height: inherit;
+}
+.bookshelf-demo.is-site .page {
+  width: 100%;
+  max-width: none;
+  margin: 0;
+  padding: 0 0 8px;
+}
+.bookshelf-demo.is-site .top { display: none; }
+.bookshelf-page .sh-head h1,
+.bookshelf-page .sh-deck,
+.bookshelf-page .sh-kicker,
+body:has(.bookshelf-demo.is-site) .sh-header,
+body:has(.bookshelf-demo.is-site) .sh-footer {
+  font-family: -apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Segoe UI", system-ui, sans-serif;
+}
+body:has(.bookshelf-demo.is-site) .sh-header .sh-word {
+  font-family: "Songti SC", "STSong", "Source Serif 4", Georgia, serif;
+}
+/* Overlays stay under the sticky header so open/close does not cover it. */
+.bookshelf-demo.is-site .open-backdrop {
+  top: var(--hdr);
+  z-index: 30;
+  background: var(--paper);
+}
+.bookshelf-demo.is-site .stage { z-index: 32; }
+.bookshelf-demo.is-site .note-view {
+  top: var(--hdr);
+  background: var(--paper);
+  color: var(--text);
+}
+.bookshelf-demo.is-site .note-view.is-preparing,
+.bookshelf-demo.is-site .note-view.is-open { z-index: 34; }
+.bookshelf-demo.is-site .open-veil { z-index: 36; }
+.bookshelf-demo.is-site .note {
+  width: min(100%, var(--col));
+  margin: 0 auto;
+  padding: 28px 0 80px;
+}
+.bookshelf-demo.is-site .back-btn,
+.bookshelf-demo.is-site .note-hero,
+.bookshelf-demo.is-site .note-body,
+.bookshelf-demo.is-site .note-read {
+  max-width: none;
+  font-family: var(--site-sans);
+}
+.bookshelf-demo.is-site .note-body {
+  font-size: var(--fs-body);
+  line-height: 1.75;
+  color: var(--text);
+}
+.bookshelf-demo.is-site .note-body h2 {
+  font-family: inherit;
+  font-size: var(--fs-h2);
+  font-weight: 700;
+  line-height: 1.3;
+  color: var(--ink);
+}
+.bookshelf-demo.is-site .note-meta h1 {
+  font-family: inherit;
+  font-weight: 700;
+  font-size: var(--fs-display);
+  line-height: 1.2;
+  color: var(--ink);
+}
+.bookshelf-demo .flyer-page-more {
+  pointer-events: auto;
+  align-self: flex-start;
+  margin-top: 8px;
+  font-family: system-ui, sans-serif;
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  color: var(--ink, #2a261e);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+.bookshelf-demo .note-read {
+  display: inline-block;
+  margin: 12px 0 0;
+  font-size: 14px;
+  color: var(--ink);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.bookshelf-demo .note-read[hidden] { display: none; }
+.bookshelf-demo.is-site .note-read { color: var(--blue); }
+@media (max-width: 820px) {
+  .bookshelf-demo.is-site .note { padding: 16px 20px 64px; }
+}

package/app/components/bookshelf/catalog.mjs

@@ -0,0 +1,116 @@
+import { marked } from "marked";
+import { BookshelfConfigError } from "./schema.mjs";
+
+/**
+ * Site shelf for `<Bookshelf catalog notes />`.
+ * Built only from `content/bookshelf.yaml` and the posts it names.
+ * The package demo is a separate path: this module never reads it.
+ *
+ * `post` is a `content/posts` path without `.md`. Its front matter description
+ * leads the note HTML so the open book's right page is that summary.
+ * A cover file name is published at `/media/covers/<file>` (same stem cleanup
+ * as content sync). A full URL or a path starting with `/` is kept.
+ */
+
+const WIDGET_FENCE = /```(?:garden|ui-error|ui|intent|widget)(?:[ \t]+[^\n]*)?\r?\n[\s\S]*?```/gu;
+
+export function resolveBookshelfCover(cover, where = "cover") {
+  if (!cover?.trim()) return undefined;
+  const value = cover.trim();
+  if (/^(?:[a-z][a-z0-9+.-]*:)?\/\//iu.test(value) || value.startsWith("/") || value.startsWith("data:")) {
+    return value;
+  }
+  let relative = value.replace(/^\.\//u, "");
+  if (relative.startsWith("covers/")) relative = relative.slice("covers/".length);
+  const parts = relative.split("/");
+  if (!relative || parts.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new BookshelfConfigError("cover", `${where} 的 cover 必须是文件名或完整 URL。`);
+  }
+  return `/media/covers/${parts.map(publishCoverSegment).join("/")}`;
+}
+
+/** `content/posts` path, without `.md`. Rejects anything that leaves that directory. */
+export function normalizeBookshelfPostPath(value) {
+  const relative = value
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(/^(?:content\/)?posts\//u, "")
+    .replace(/\.md$/u, "");
+  if (
+    !relative
+    || relative.startsWith("/")
+    || relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new BookshelfConfigError("post", `post「${value}」必须是 content/posts 下的路径，不带 .md。`);
+  }
+  return relative;
+}
+
+export function bookshelfMountFromFile(file, posts) {
+  const byPath = new Map(posts.map((post) => [normalizeBookshelfPostPath(post.path), post]));
+  const notes = {};
+  const catalog = file.shelves.map((shelf) => ({
+    id: shelf.id,
+    name: shelf.name,
+    books: shelf.books.map((book) => toCatalogBook(book, byPath, notes)),
+  }));
+  return {
+    title: file.title,
+    description: file.description,
+    eyebrow: file.eyebrow,
+    catalog,
+    notes,
+  };
+}
+
+function toCatalogBook(book, byPath, notes) {
+  const post = book.post ? byPath.get(normalizeBookshelfPostPath(book.post)) : undefined;
+  if (book.post && !post) {
+    throw new BookshelfConfigError("post", `书架引用的博文 ${book.post} 没有读到。`);
+  }
+  const cover = resolveBookshelfCover(book.cover, book.id) ?? (post ? resolveBookshelfCover(post.cover, book.id) : undefined);
+  const body = post
+    ? renderNoteHtml(post.content, post.description)
+    : book.note
+      ? renderNoteHtml(book.note)
+      : "";
+  const note = body ? book.id : null;
+  if (note) notes[book.id] = { title: book.title, body, summary: post?.description };
+  return {
+    id: book.id,
+    title: book.title,
+    author: book.author ?? "",
+    spine: book.spine ?? book.title,
+    size: book.size ?? (book.filler ? "thin" : "s-mid"),
+    cover: cover ?? false,
+    color: book.color,
+    filler: book.filler,
+    post: book.post ? normalizeBookshelfPostPath(book.post) : undefined,
+    note,
+  };
+}
+
+function renderNoteHtml(markdown, description) {
+  const prose = markdown.replace(WIDGET_FENCE, "\n").trim();
+  const parsed = prose ? marked.parse(prose, { async: false }).trim() : "";
+  const summary = description?.trim();
+  if (!summary || prose.includes(summary)) return parsed;
+  return `<p>${escapeHtml(summary)}</p>${parsed ? `\n${parsed}` : ""}`;
+}
+
+function publishCoverSegment(segment, index, all) {
+  const isFile = index === all.length - 1;
+  if (!isFile) return encodeURIComponent(segment.replace(/[^\w\u3400-\u9fff.-]+/gu, "-"));
+  const dot = segment.lastIndexOf(".");
+  const ext = dot >= 0 ? segment.slice(dot).toLowerCase() : "";
+  const stem = dot >= 0 ? segment.slice(0, dot) : segment;
+  return encodeURIComponent(`${stem.replace(/[^\w\u3400-\u9fff.-]+/gu, "-")}${ext}`);
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/app/components/bookshelf/catalog.ts

@@ -0,0 +1,23 @@
+import type { BookshelfNote, BookshelfShelf } from "./types";
+
+/**
+ * Site shelf ready for `<Bookshelf catalog notes />`.
+ * The runtime lives in `catalog.mjs` (node tests and the page share it).
+ * The package demo is not an input.
+ */
+export type BookshelfMount = {
+  title: string;
+  description?: string;
+  eyebrow?: string;
+  catalog: BookshelfShelf[];
+  notes: Record<string, BookshelfNote>;
+};
+
+/** A post the shelf can turn into a note. `path` is relative to `content/posts`, without `.md`. */
+export type BookshelfPostSource = {
+  path: string;
+  title?: string;
+  description?: string;
+  cover?: string;
+  content: string;
+};