hd-garden 0.9.1 → 0.9.3

package/app/bookshelf/[bookId]/page.tsx

@@ -0,0 +1,55 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { bookshelf } from "@garden/bookshelf";
+import { BookHub } from "../../components/bookshelf/BookHub";
+import { pageAlternates } from "../../lib/page-alternates";
+import { isStaticPlaceholder, STATIC_PLACEHOLDER, staticParams } from "../../../ui/garden/static-params.mjs";
+import type { BookshelfBook } from "../../components/bookshelf/types";
+
+function hubBooks(): { shelfTitle: string; book: BookshelfBook }[] {
+  if (!bookshelf) return [];
+  const found: { shelfTitle: string; book: BookshelfBook }[] = [];
+  for (const row of bookshelf.catalog) {
+    for (const book of row.books) {
+      if ((book.posts?.length ?? 0) > 1) found.push({ shelfTitle: bookshelf.title, book });
+    }
+  }
+  return found;
+}
+
+export function generateStaticParams() {
+  return staticParams(
+    hubBooks().map(({ book }) => ({ bookId: book.id })),
+    { bookId: STATIC_PLACEHOLDER },
+  );
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ bookId: string }>;
+}): Promise<Metadata> {
+  const { bookId } = await params;
+  const found = hubBooks().find((item) => item.book.id === bookId);
+  if (!found) return {};
+  return {
+    title: found.book.title,
+    description: found.book.posts?.find((post) => post.summary)?.summary,
+    alternates: pageAlternates(`/bookshelf/${found.book.id}`),
+  };
+}
+
+/** `/bookshelf/<id>` — one multi-note volume. Single-note books stay on the shelf. */
+export default async function BookHubPage({
+  params,
+}: {
+  params: Promise<{ bookId: string }>;
+}) {
+  const { bookId } = await params;
+  const found = hubBooks().find((item) => item.book.id === bookId);
+  if (!found) {
+    if (isStaticPlaceholder(bookId)) return null;
+    notFound();
+  }
+  return <BookHub shelfTitle={found.shelfTitle} book={found.book} />;
+}

package/app/bookshelf/load.mjs

@@ -13,7 +13,8 @@ export function bookshelfConfigPath(root = gardenSiteRoot()) {
 /**
  * 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.
+ * each book's `post` or `posts` is read from `content/posts`. One note becomes
+ * the open-book HTML. Several notes stay on the book for `/bookshelf/<id>`.
  * `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.
@@ -35,22 +36,33 @@ export function loadBookshelf(root = gardenSiteRoot(), preparedPosts) {
       title: post.title,
       description: post.description,
       cover: post.cover,
+      date: typeof post.date === "string" ? post.date : undefined,
       content: post.content,
     }))
     : readReferencedPosts(root, config);
   return bookshelfMountFromFile(config, sources);
 }
 
+function referencedPostPaths(book) {
+  if (Array.isArray(book.posts) && book.posts.length > 0) {
+    return book.posts
+      .map((entry) => (typeof entry === "string" ? entry : entry?.path))
+      .filter((path) => typeof path === "string" && path.trim());
+  }
+  return book.post ? [book.post] : [];
+}
+
 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));
+      for (const entry of referencedPostPaths(book)) {
+        const relative = normalizeBookshelfPostPath(entry);
+        if (seen.has(relative)) continue;
+        seen.add(relative);
+        posts.push(readPost(root, relative));
+      }
     }
   }
   return posts;
@@ -85,6 +97,7 @@ function readPost(root, postPath) {
     title: optionalString(data.title),
     description: optionalString(data.description),
     cover: optionalString(data.cover),
+    date: optionalDate(data.date),
     content: parsed.content,
   };
 }
@@ -94,3 +107,8 @@ function optionalString(value) {
   const trimmed = value.trim();
   return trimmed ? trimmed : undefined;
 }
+
+function optionalDate(value) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  return optionalString(value);
+}

package/app/components/bookshelf/BookHub.tsx

@@ -0,0 +1,142 @@
+import Link from "next/link";
+import { siteHref } from "../../lib/site-href";
+import { ui } from "../../lib/i18n";
+import type { BookshelfBook, BookshelfBookPost, BookshelfNoteKind, BookshelfSource } from "./types";
+
+function day(value: string) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value.slice(0, 10);
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+function kindLabel(kind: BookshelfNoteKind | undefined) {
+  const t = ui();
+  switch (kind) {
+    case "overview":
+      return t.bookHubOverview;
+    case "excerpt":
+      return t.bookHubExcerpt;
+    case undefined:
+      return "";
+    default: {
+      const unexpected: never = kind;
+      return unexpected;
+    }
+  }
+}
+
+function sourceHref(href: string) {
+  if (href.startsWith("/") && !href.startsWith("//")) return siteHref(href);
+  return href;
+}
+
+function isExternal(href: string) {
+  return /^(?:https?:)?\/\//iu.test(href);
+}
+
+/** Hub chips are Douban and PDF. The Chinese label is the zh shelf; English sites write Douban. */
+function isDoubanChip(label: string) {
+  return label === "豆瓣" || /^douban$/iu.test(label);
+}
+
+function hubSources(sources: readonly BookshelfSource[] | undefined) {
+  const list = sources ?? [];
+  const douban = list.filter((source) => isDoubanChip(source.label));
+  const pdf = list.filter((source) => /pdf/iu.test(source.label));
+  return [...douban, ...pdf];
+}
+
+function NoteCard({ entry }: { entry: BookshelfBookPost }) {
+  const t = ui();
+  const label = kindLabel(entry.kind);
+  const href = entry.href ?? siteHref(`/blog/${entry.path}`);
+  const when = entry.date ? day(entry.date) : "";
+  const count = entry.words ? t.wordCount(entry.words) : "";
+  return (
+    <Link className="book-hub-note" href={href}>
+      {label ? <p className="book-hub-note-label">{label}</p> : null}
+      <h3>{entry.title}</h3>
+      {entry.summary ? <p className="book-hub-note-sum">{entry.summary}</p> : null}
+      {when || count ? (
+        <p className="book-hub-note-meta">
+          {when}
+          {when && count ? " · " : null}
+          {count}
+        </p>
+      ) : null}
+    </Link>
+  );
+}
+
+function SourceChips({ sources }: { sources: readonly BookshelfSource[] }) {
+  const shown = hubSources(sources);
+  if (!shown.length) return null;
+  const t = ui();
+  return (
+    <div className="book-hub-sources">
+      {shown.map((source) => {
+        const href = sourceHref(source.href);
+        const external = isExternal(source.href);
+        const pdf = /pdf/iu.test(source.label);
+        return (
+          <span className="book-hub-source" key={`${source.label}\u0000${source.href}`}>
+            <a
+              className="book-hub-chip"
+              href={href}
+              {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+            >
+              {source.label}
+              <span className="ext" aria-hidden="true">↗</span>
+            </a>
+            {pdf ? <span className="book-hub-source-note">{t.bookHubPdfNote}</span> : null}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+/** Book hub (本书). Multi-note volumes land here; a note card is a plain article link. */
+export function BookHub({ shelfTitle, book }: { shelfTitle: string; book: BookshelfBook }) {
+  const t = ui();
+  const jacket = typeof book.cover === "string" ? book.cover : "";
+  const posts = book.posts ?? [];
+  return (
+    <main className="sh-main book-hub" id="content">
+      <p className="book-hub-crumb">
+        <Link href={siteHref("/columns")}>{t.homeColumns}</Link>
+        <span aria-hidden="true"> · </span>
+        <Link href={siteHref("/bookshelf")}>{shelfTitle}</Link>
+        <span aria-hidden="true"> · </span>
+        <span aria-current="page">{t.bookHubCurrent}</span>
+      </p>
+
+      <section className="book-hub-card" aria-labelledby="book-hub-title">
+        {jacket ? (
+          <div className="book-hub-cover">
+            <img src={jacket} alt={t.coverLabel(book.title)} width={148} />
+          </div>
+        ) : null}
+        <div className="book-hub-meta">
+          <h1 id="book-hub-title">{book.title}</h1>
+          {book.author ? <p className="book-hub-author">{book.author}</p> : null}
+          <SourceChips sources={book.sources ?? []} />
+        </div>
+      </section>
+
+      <h2 className="book-hub-notes-head">{t.bookHubNotes}</h2>
+      <ul className="book-hub-notes">
+        {posts.map((entry) => (
+          <li key={entry.path}>
+            <NoteCard entry={entry} />
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/app/components/bookshelf/Bookshelf.tsx

@@ -12,9 +12,20 @@ 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,
-    ),
+    books: row.books.map((book) => {
+      const posts = book.posts?.map((entry) => ({
+        ...entry,
+        href: siteHref(`/blog/${entry.path}`),
+      }));
+      const hub = book.hub ? siteHref(book.hub) : undefined;
+      if (!book.post && !posts?.length && !hub) return book;
+      return {
+        ...book,
+        ...(book.post ? { href: siteHref(`/blog/${book.post}`) } : {}),
+        ...(posts?.length ? { posts } : {}),
+        ...(hub ? { hub } : {}),
+      };
+    }),
   }));
 }
 

package/app/components/bookshelf/bookshelf.css

@@ -235,18 +235,22 @@
     z-index: 2;
   }
 }
-.bookshelf-demo .cover.is-placeholder {
-  /* ux13+ux24: invisible seat — no gray/wood/bk plate while flyer is out */
+.bookshelf-demo .cover.is-placeholder,
+.bookshelf-demo .spine.is-placeholder {
+  /* Empty seat while the flyer owns the motion: shelf surface only.
+     A bk-* fill here is the gray/lavender plate behind the real cover. */
   opacity: 0 !important;
   visibility: hidden !important;
   background-color: transparent !important;
   background-image: none !important;
-  filter: none;
+  filter: none !important;
   pointer-events: none;
-  box-shadow: none;
+  box-shadow: none !important;
+  color: transparent !important;
   transform: none !important;
 }
-.bookshelf-demo .cover.is-placeholder > .cover-art {
+.bookshelf-demo .cover.is-placeholder > .cover-art,
+.bookshelf-demo .spine.is-placeholder > .cover-art {
   visibility: hidden !important;
   opacity: 0 !important;
 }
@@ -342,15 +346,7 @@
     z-index: 2;
   }
 }
-.bookshelf-demo .spine.is-placeholder {
-  /* ux13: invisible seat — ban gray ghost plate */
-  opacity: 0;
-  filter: none;
-  pointer-events: none;
-  box-shadow: none;
-  transform: none !important;
-}
-.bookshelf-demo .spine.is-placeholder span { opacity: 0; }
+.bookshelf-demo .spine.is-placeholder span { opacity: 0 !important; visibility: hidden !important; }
 .bookshelf-demo .cover.is-placeholder.is-landing,
 .bookshelf-demo .spine.is-placeholder.is-landing {
   opacity: 0;
@@ -359,6 +355,25 @@
 
 /* Mode C: temporary expand on spine wall */
 /* resting spines: solid hue only; cover image only when expanded */
+/* Expanded / extracting face must not fall back to bk-* (#513688 etc.).
+   The jacket is .cover-art. A missing image stays cream shelf, not a shell pad. */
+.bookshelf-demo .spine.is-expanded,
+.bookshelf-demo .spine.is-extracting {
+  background-color: transparent !important;
+}
+.bookshelf-demo .spine.is-expanded > .cover-art,
+.bookshelf-demo .spine.is-extracting > .cover-art {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  object-position: center top;
+  display: block;
+  pointer-events: none;
+  z-index: 1;
+  border-radius: inherit;
+}
 .bookshelf-demo .spine[class*="img-"] {
   background-image: none !important;
 }
@@ -559,15 +574,32 @@
   align-items: flex-start;
   margin-bottom: 36px;
 }
+.bookshelf-demo .note-meta {
+  min-width: 0;
+  flex: 1 1 auto;
+}
+/* Settled note header: size the box to the picture. A fixed 2:3 frame with
+   background-size:cover center-crops landscape heroes (Obsidian → "sid"). */
 .bookshelf-demo .note-cover {
-  width: 120px;
-  height: 180px;
-  flex-shrink: 0;
+  width: max-content;
+  max-width: min(420px, 46%);
+  height: auto;
+  flex: 0 0 auto;
   border-radius: 2px 3px 0 0;
-  background-size: cover;
-  background-position: center top;
-  background-color: #2a2a2a;
+  background-color: transparent;
+  background-image: none;
   box-shadow: 0 8px 20px rgba(40,30,20,0.12);
+  line-height: 0;
+}
+.bookshelf-demo .note-cover-img {
+  display: block;
+  width: auto;
+  height: auto;
+  max-width: 100%;
+  max-height: 180px;
+  object-fit: contain;
+  object-position: center;
+  border-radius: inherit;
 }
 .bookshelf-demo .note-cat {
   margin: 0 0 8px;
@@ -713,21 +745,16 @@
   backface-visibility: hidden;
 }
 
-/* Thin cover board peeking under page block (thickness cue) */
+/* ux27 plate ban: this used to be a full-spread shell (fallback #6a7a98 / #5a6a88,
+   and shell-hi of dark covers reads the same gray-lavender). It sat wider than
+   the jacket during lift and put-back. Fore-edge stays on .flyer-thickness. */
 .bookshelf-demo .flyer-board {
-  position: absolute;
-  inset: -2% -1.2% -3.5% -1.2%;
-  border-radius: 3px 4px 2px 2px;
-  /* ux26: shell = this book's cover dominant (via --shell); ban site-wide brown */
-  background: linear-gradient(
-    180deg,
-    var(--shell-hi, #6a7a98) 0%,
-    var(--shell, #5a6a88) 55%,
-    var(--shell-lo, #3a4a68) 100%
-  );
-  box-shadow: 0 1px 0 rgba(255,255,255,0.06) inset;
-  transform: translateZ(-8px);
-  z-index: 0;
+  display: none !important;
+  background: none !important;
+  background-color: transparent !important;
+  box-shadow: none !important;
+  opacity: 0 !important;
+  visibility: hidden !important;
 }
 
 .bookshelf-demo .flyer-leaf {
@@ -759,7 +786,7 @@
 /* Cover on BACK of left leaf — camera-facing when leaf folded (180°) */
 .bookshelf-demo .flyer-face-cover {
   transform: rotateY(180deg);
-  background-color: transparent; /* ux24: no preset wood plate */
+  background-color: transparent !important; /* ux24/ux27: bk-* must not fill behind the img */
   /* No background-image here — .img-* / inline applyCoverImage owns the photo.
      Gradients-only used to override img classes → flat brown/gray close flash. */
   box-shadow:
@@ -782,17 +809,18 @@
 }
 .bookshelf-demo .flyer-spine-label { pointer-events: none; }
 
-/* ux15 plate kept inert; ux16 uses full-height .flyer-spine-slot instead */
+/* ux15 plate kept inert; ux16 uses full-height .flyer-spine-slot instead.
+   Never paint the lavender shell fallback if a leftover plate node is mounted. */
 .bookshelf-demo .flyer-spine-land-plate {
   position: absolute;
   inset: 0;
   pointer-events: none;
   border-radius: inherit;
   z-index: 1;
-  display: none;
-}
-.bookshelf-demo .flyer-spine-land-plate:not([class*="bk-"]) {
-  background: linear-gradient(180deg, var(--shell-hi, #6a7a98) 0%, var(--shell, #5a6a88) 100%);
+  display: none !important;
+  background: none !important;
+  background-color: transparent !important;
+  opacity: 0 !important;
 }
 
 /* ux16: exact homeRect standing spine — full height, spine width, slides out/in */
@@ -1002,6 +1030,18 @@
   overflow: auto;
 }
 
+/* Close: flyer owns the motion. The note used to stay at z-index 75, so the
+   article sat on top of the return for the whole fade and the shrink was hidden. */
+.bookshelf-demo.is-return .stage { z-index: 80; }
+.bookshelf-demo.is-return .note-view,
+.bookshelf-demo.is-return .note-view.is-preparing,
+.bookshelf-demo.is-return .note-view.is-open { z-index: 60; }
+.bookshelf-demo.is-site.is-return .stage { z-index: 36; }
+.bookshelf-demo.is-site.is-return .open-backdrop { z-index: 30; }
+.bookshelf-demo.is-site.is-return .note-view,
+.bookshelf-demo.is-site.is-return .note-view.is-preparing,
+.bookshelf-demo.is-site.is-return .note-view.is-open { z-index: 31; }
+
 .bookshelf-demo .shelf-view.is-dim {
   /* Backdrop covers shelf — dim is unused during open; keep inert */
   opacity: 1;
@@ -1059,7 +1099,7 @@
   inset: 0;
   border-radius: inherit;
   overflow: hidden;
-  background-color: transparent; /* ux24: no preset wood plate */
+  background-color: transparent !important; /* ux24/ux27: no solid shell behind the img */
   background-size: cover;
   background-position: center top;
   background-repeat: no-repeat;
@@ -1162,7 +1202,13 @@
   .bookshelf-demo .spine.is-expanded.is-collapsing.s-mid { width: 24px; height: 134px; }
   .bookshelf-demo .spine.is-expanded.is-collapsing.s-short { width: 20px; height: 120px; }
   .bookshelf-demo .note-hero { flex-direction: column; gap: 16px; }
-  .bookshelf-demo .note-cover { width: 100px; height: 150px; }
+  .bookshelf-demo .note-cover { width: max-content; max-width: 100%; }
+  .bookshelf-demo .note-cover-img {
+    width: auto;
+    max-width: 100%;
+    max-height: 180px;
+    height: auto;
+  }
   .bookshelf-demo .qa-hint { width: 100%; margin-left: 0; margin-top: 4px; }
 }
 

package/app/components/bookshelf/catalog.mjs

@@ -1,4 +1,5 @@
 import { marked } from "marked";
+import { searchableText } from "../../../ui/garden/search-index.mjs";
 import { BookshelfConfigError } from "./schema.mjs";
 
 /**
@@ -6,10 +7,13 @@ import { BookshelfConfigError } from "./schema.mjs";
  * 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.
+ * `post` is shorthand for one note. `posts` is the list. A single note still
+ * becomes the open-book body. Two or more notes do not: the book carries `hub`
+ * (`/bookshelf/<id>`) and the shelf navigates there instead of opening `posts[0]`.
+ *
+ * The jacket is yaml `cover` only. A post cover is that note's hero and is
+ * copied onto the book only when yaml `cover` is omitted, and then only from
+ * the first note. A file name is published at `/media/covers/<file>`.
  */
 
 const WIDGET_FENCE = /```(?:garden|ui-error|ui|intent|widget)(?:[ \t]+[^\n]*)?\r?\n[\s\S]*?```/gu;
@@ -29,6 +33,14 @@ export function resolveBookshelfCover(cover, where = "cover") {
   return `/media/covers/${parts.map(publishCoverSegment).join("/")}`;
 }
 
+/** Book hub for a multi-note volume. One path segment, the book id. */
+export function bookshelfHubPath(id) {
+  if (typeof id !== "string" || !id || /[\\/]/.test(id) || id === "." || id === "..") {
+    throw new BookshelfConfigError("book", `本书页的 id「${id ?? ""}」必须是单一路径段。`);
+  }
+  return `/bookshelf/${encodeURIComponent(id)}`;
+}
+
 /** `content/posts` path, without `.md`. Rejects anything that leaves that directory. */
 export function normalizeBookshelfPostPath(value) {
   const relative = value
@@ -63,19 +75,64 @@ export function bookshelfMountFromFile(file, posts) {
   };
 }
 
-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} 没有读到。`);
+function bookPostRefs(book) {
+  if (Array.isArray(book.posts) && book.posts.length > 0) {
+    return book.posts.map((entry) => (
+      typeof entry === "string" ? { path: entry } : { path: entry?.path, kind: entry?.kind }
+    ));
   }
-  const cover = resolveBookshelfCover(book.cover, book.id) ?? (post ? resolveBookshelfCover(post.cover, book.id) : undefined);
-  const body = post
-    ? renderNoteHtml(post.content, post.description)
-    : book.note
+  if (typeof book.post === "string" && book.post.trim()) return [{ path: book.post.trim() }];
+  return [];
+}
+
+/** Same count the article page prints (`estimateWordCount`). */
+function noteWordCount(markdown) {
+  const text = searchableText(markdown ?? "");
+  const han = text.match(/[\u3400-\u9fff]/gu)?.length ?? 0;
+  const other = text.replace(/[\u3400-\u9fff]/gu, " ").match(/[\p{L}\p{N}]+/gu)?.length ?? 0;
+  return han + other;
+}
+
+/** Jacket: yaml cover when set. Otherwise the first note's cover, never a later note's. */
+function jacketFor(book, primary) {
+  if (book.cover) return resolveBookshelfCover(book.cover, book.id);
+  if (primary?.cover) return resolveBookshelfCover(primary.cover, book.id);
+  return undefined;
+}
+
+function toCatalogBook(book, byPath, notes) {
+  const refs = bookPostRefs(book);
+  const paths = refs.map((ref) => normalizeBookshelfPostPath(ref.path));
+  const sources = paths.map((relative, index) => {
+    const post = byPath.get(relative);
+    if (!post) throw new BookshelfConfigError("post", `书架引用的博文 ${refs[index].path} 没有读到。`);
+    return post;
+  });
+  const primary = sources[0];
+  const multi = sources.length > 1;
+  const cover = jacketFor(book, primary);
+  // A multi-note book opens on the hub. Its note bodies stay on the article pages.
+  const body = !multi && primary
+    ? renderNoteHtml(primary.content, primary.description)
+    : !multi && book.note
       ? renderNoteHtml(book.note)
       : "";
   const note = body ? book.id : null;
-  if (note) notes[book.id] = { title: book.title, body, summary: post?.description };
+  if (note) notes[book.id] = { title: book.title, body, summary: primary?.description };
+  const posts = sources.map((source, index) => {
+    const words = noteWordCount(source.content);
+    const title = (typeof source.title === "string" && source.title.trim()) || (index === 0 ? book.title : paths[index]);
+    const summary = typeof source.description === "string" ? source.description.trim() : "";
+    const date = typeof source.date === "string" ? source.date.trim() : "";
+    return {
+      path: paths[index],
+      title,
+      ...(refs[index].kind ? { kind: refs[index].kind } : {}),
+      ...(summary ? { summary } : {}),
+      ...(date ? { date } : {}),
+      ...(words > 0 ? { words } : {}),
+    };
+  });
   return {
     id: book.id,
     title: book.title,
@@ -85,7 +142,10 @@ function toCatalogBook(book, byPath, notes) {
     cover: cover ?? false,
     color: book.color,
     filler: book.filler,
-    post: book.post ? normalizeBookshelfPostPath(book.post) : undefined,
+    post: !multi && paths[0] ? paths[0] : undefined,
+    posts: posts.length ? posts : undefined,
+    hub: multi ? bookshelfHubPath(book.id) : undefined,
+    sources: Array.isArray(book.sources) && book.sources.length ? book.sources : undefined,
     note,
   };
 }

package/app/components/bookshelf/catalog.ts

@@ -4,6 +4,10 @@ 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.
+ *
+ * A book's `cover` is the jacket. A post's `cover` on `BookshelfPostSource` is
+ * that note's hero and is used as the jacket only when the yaml book omits
+ * `cover`. Multi-note books set `hub` (`/bookshelf/<id>`) and do not fill `notes`.
  */
 export type BookshelfMount = {
   title: string;