hd-garden 0.9.1 → 0.9.3

package/app/components/bookshelf/engine.ts

@@ -312,6 +312,30 @@ export function mountBookshelf(root, options = {}) {
     return Math.max(96, Math.round(w * (nat.h / nat.w)));
   }
 
+  // Real jacket on the expanded spine. CSS background-image is stripped by
+  // `.spine[class*="img-"] { background-image: none !important }` and by the
+  // collapse rule, which left bk-* (#513688) as a solid pad at extract start.
+  function mountSeatCover(el, book) {
+    if (!el || !book || !book.cover || book.filler) return;
+    el.style.backgroundColor = "transparent";
+    let art = el.querySelector(":scope > .cover-art");
+    if (!art) {
+      art = document.createElement("img");
+      art.className = "cover-art";
+      art.alt = "";
+      art.draggable = false;
+      el.appendChild(art);
+    }
+    const src = coverSrc(book);
+    if (art.getAttribute("src") !== src) art.src = src;
+  }
+
+  function clearSeatCover(el) {
+    if (!el || !el.classList.contains("spine")) return;
+    el.querySelectorAll(":scope > .cover-art").forEach((node) => node.remove());
+    try { el.style.removeProperty("background-color"); } catch (_) {}
+  }
+
   function applyFaceSize(el, book, { expanded = false } = {}) {
     if (!el || !book) return;
     const faceH = bookFaceHeight(book);
@@ -580,6 +604,7 @@ export function mountBookshelf(root, options = {}) {
   function restoreRestingSpine(el, bookId) {
     if (!el) return;
     el.classList.remove("is-expanded", "is-collapsing");
+    clearSeatCover(el);
     const found = bookById(bookId);
     if (found && found.book.cover && !found.book.filler) {
       applyFaceSize(el, found.book, { expanded: false });
@@ -621,6 +646,7 @@ export function mountBookshelf(root, options = {}) {
       el.classList.remove("is-collapsing");
       el.classList.add("is-expanded");
       applyFaceSize(el, found.book, { expanded: true });
+      mountSeatCover(el, found.book);
     }
   }
 
@@ -651,18 +677,31 @@ export function mountBookshelf(root, options = {}) {
     collapseToken += 1;
   }
 
+  // Multi-note books leave the shelf for /bookshelf/<id>. No extract flyer.
+  function leaveForHub(book) {
+    const posts = book && Array.isArray(book.posts) ? book.posts : [];
+    const href = book && typeof book.hub === "string" ? book.hub : "";
+    if (posts.length < 2 || !href) return false;
+    const y = scrollLock ? scrollLock.y : readScroll().y;
+    try { sessionStorage.setItem("garden-bookshelf-scroll", String(y)); } catch (_) {}
+    window.location.assign(href);
+    return true;
+  }
+
   async function onCoverClick(id, el) {
     if (busy) return;
     const found = bookById(id);
     if (!found || found.book.filler) return;
+    if (leaveForHub(found.book)) return;
     await openBookFlow(found.book, found.cat, el, { fromExpanded: false, asSpine: false });
   }
 
   async function onSpineClick(id, el, ev) {
     if (busy) return;
     const found = bookById(id);
-    if (!found) return;
-    if (found.book.filler || !found.book.cover) return;
+    if (!found || found.book.filler) return;
+    if (leaveForHub(found.book)) return;
+    if (!found.book.cover) return;
 
     const isTouch = ev && (ev.pointerType === "touch" || ("ontouchstart" in window && window.matchMedia("(hover: none)").matches));
 
@@ -686,7 +725,20 @@ export function mountBookshelf(root, options = {}) {
     $("#noteTitle").textContent = book.title;
     $("#noteAuthor").textContent = book.author || "";
     const coverEl = $("#noteCover");
-    coverEl.className = `note-cover ${bkClass(book)} ${coverClass(book)}`;
+    // Intrinsic <img>, not the .img-* background. That background is
+    // background-size:cover inside a fixed 2:3 frame and clips landscape art.
+    coverEl.className = "note-cover";
+    coverEl.style.backgroundImage = "none";
+    coverEl.style.backgroundColor = "transparent";
+    coverEl.replaceChildren();
+    if (book.cover) {
+      const img = document.createElement("img");
+      img.className = "note-cover-img";
+      img.alt = "";
+      img.draggable = false;
+      img.src = coverSrc(book);
+      coverEl.appendChild(img);
+    }
     const note = NOTES[book.note];
     const read = $("#noteRead");
     if (read) {
@@ -969,6 +1021,42 @@ export function mountBookshelf(root, options = {}) {
     return { offset, ...pathPose(transform) };
   }
 
+  // Close samples. T0 still carries the separate sx/sy height pin.
+  // The old first stop was Tp3 (only 25% of the way home) at 0.28, so the
+  // book was still nearly full-size for the first ~1s and read as overlap.
+  function returnMoveKeys(Tfull, Tp1, T0) {
+    return [
+      pathKey(0, Tfull),
+      pathKey(0.12, lerpTS(Tfull, T0, 0.35)),
+      pathKey(0.32, lerpTS(Tfull, T0, 0.62)),
+      pathKey(0.52, Tp1),
+      pathKey(0.74, T0),
+      pathKey(0.88, T0),
+      pathKey(1, T0),
+    ];
+  }
+
+  // Note stays out until the flyer leaves, then a short handoff.
+  // Rising from 0.65 while the flyer stayed solid until 0.90 was the double exposure.
+  function noteInKeys() {
+    return [
+      { offset: 0, opacity: 0 },
+      { offset: 0.82, opacity: 0 },
+      { offset: 0.90, opacity: 1 },
+      { offset: 1, opacity: 1 },
+    ];
+  }
+
+  // Article is gone by ~0.12 (230ms). Shrink has already started on frame 0.
+  function noteOutKeys() {
+    return [
+      { offset: 0, opacity: 1 },
+      { offset: 0.05, opacity: 0.35 },
+      { offset: 0.12, opacity: 0 },
+      { offset: 1, opacity: 0 },
+    ];
+  }
+
   // ux14 geometric core: ONE diagonal arc slot-center ↔ screen-center.
   // X, Y, AND scale on the SAME beat — ban L-path (lift-only then slide-only).
   // Transforms are lerpTS(T0→Tfull) samples so WAAPI stays collinear in tx/ty/s.
@@ -1279,6 +1367,7 @@ export function mountBookshelf(root, options = {}) {
       "is-expanded",
       "is-collapsing"
     );
+    clearSeatCover(el);
     // Explicit removeProperty — kills commitStyles leftovers like opacity:0 / transform
     [
       "width",
@@ -1324,6 +1413,9 @@ export function mountBookshelf(root, options = {}) {
 
     const board = document.createElement("div");
     board.className = "flyer-board";
+    // ux27: never a solid shell behind the jacket. CSS also forces this off.
+    board.style.opacity = "0";
+    board.style.visibility = "hidden";
 
     const left = document.createElement("div");
     left.className = "flyer-leaf flyer-leaf-left";
@@ -1401,7 +1493,6 @@ export function mountBookshelf(root, options = {}) {
       left.style.transform = "rotateY(180deg)";
       right.style.transform = "rotateY(0deg)";
       right.style.opacity = "0";
-      board.style.opacity = "0";
       leftThick.style.opacity = "0";
       rightThick.style.opacity = "0";
       bookEl.style.transform = "rotateX(8deg) translate3d(0,0,0)";
@@ -1475,13 +1566,9 @@ export function mountBookshelf(root, options = {}) {
     noteView.classList.add("is-preparing");
     noteView.classList.remove("is-open");
     noteView.style.opacity = "0";
-    const coverEl = $("#noteCover");
-    const bg = coverEl && getComputedStyle(coverEl).backgroundImage;
-    const m = bg && bg.match(/url\(["']?([^"')]+)["']?\)/);
-    if (m) {
+    const img = $("#noteCover") && $("#noteCover").querySelector(".note-cover-img");
+    if (img && !coverImgReady(img)) {
       try {
-        const img = new Image();
-        img.src = m[1];
         const DECODE_MS = 400;
         const decodeOrLoad = img.decode
           ? img.decode()
@@ -1528,6 +1615,7 @@ export function mountBookshelf(root, options = {}) {
     busy = true;
     const myFlow = ++flowSeq;
     document.body.classList.add("is-busy");
+    root.classList.remove("is-return");
     openBook = { book, cat, asSpine, fromExpanded: !!fromExpanded, openSeatRect: null };
     openFromExpanded = !!fromExpanded;
 
@@ -1568,6 +1656,11 @@ export function mountBookshelf(root, options = {}) {
     sourceEl.style.transition = "none";
     sourceEl.style.transform = "none"; // kill :hover translateY / is-expanded lift
     sourceEl.classList.add("is-extracting"); // CSS: suppress :hover transform while extracting
+    // Keep the real jacket on the seat until the flyer exists. Dropping
+    // is-expanded used to reveal the bk-* fill for the frames before the flyer.
+    if (sourceEl.classList.contains("spine") && book && book.cover) {
+      mountSeatCover(sourceEl, book);
+    }
     if (fromExpanded) {
       sourceEl.classList.remove("is-expanded", "is-collapsing");
       // Drop the expanded cover's width. Do NOT drop a resting spine's height:
@@ -1722,14 +1815,14 @@ export function mountBookshelf(root, options = {}) {
             { offset: 0, opacity: 0 },
             { offset: 0.14, opacity: 0 },
             { offset: 0.22, opacity: 1 },
-            { offset: 0.90, opacity: 1 },
-            { offset: 0.96, opacity: 0.35 },
+            { offset: 0.82, opacity: 1 },
+            { offset: 0.90, opacity: 0 },
             { offset: 1.0, opacity: 0 },
           ]
         : [
             { offset: 0, opacity: 1 },
-            { offset: 0.90, opacity: 1 },
-            { offset: 0.96, opacity: 0.35 },
+            { offset: 0.82, opacity: 1 },
+            { offset: 0.90, opacity: 0 },
             { offset: 1.0, opacity: 0 },
           ],
       opts
@@ -1755,6 +1848,7 @@ export function mountBookshelf(root, options = {}) {
     const aExtractCoverIn = null;
 
     // Pose fade on SAME layer while diagonal continues — ban origin-swapping phase.
+    // Board stays out: fading it in painted a wide shell behind the cover by ~1350ms.
     const closedFaceKf = [
       { offset: 0, opacity: 0 },
       { offset: 0.28, opacity: 0 },
@@ -1762,7 +1856,11 @@ export function mountBookshelf(root, options = {}) {
       { offset: 0.52, opacity: 1 },
       { offset: 1.0, opacity: 1 },
     ];
-    const aBoard = dual._board ? dual._board.animate(closedFaceKf, opts) : null;
+    if (dual._board) {
+      dual._board.style.opacity = "0";
+      dual._board.style.visibility = "hidden";
+    }
+    const aBoard = null;
     const aRightFace = dual._right.animate(
       [
         { offset: 0, opacity: 0, transform: "rotateY(0deg)" },
@@ -1803,20 +1901,9 @@ export function mountBookshelf(root, options = {}) {
         )
       : null;
 
-    // §12: note main rise offset 0.70–0.92 (≥1.80s clear). FORBIDDEN: ≥0.95 at 0.34.
-    const aNote = noteView.animate(
-      [
-        { offset: 0, opacity: 0 },
-        { offset: 0.65, opacity: 0 },
-        { offset: 0.70, opacity: 0.15 },
-        { offset: 0.78, opacity: 0.55 },
-        { offset: 0.85, opacity: 0.90 },
-        { offset: 0.90, opacity: 0.99 },
-        { offset: 0.92, opacity: 1 },
-        { offset: 1.0, opacity: 1 },
-      ],
-      opts
-    );
+    // Note stays at 0 while the flyer owns the flight, then hands off by unlock (0.90).
+    // FORBIDDEN: note body readable while the flyer is still solid (double exposure).
+    const aNote = noteView.animate(noteInKeys(), opts);
 
     const aBack = openBackdrop
       ? openBackdrop.animate(
@@ -1961,6 +2048,9 @@ export function mountBookshelf(root, options = {}) {
     // Clock first. Shelf measure, freeze, and rAF used to run before this and
     // the 0.12 Tfull keyframe then held 672×504 for ~240ms. Stash from open is
     // enough to start the return; height pin is already in those samples.
+    // is-return puts the stage above the note so the shrink is not hidden
+    // under an opaque article (that read as ~1s of overlap, then a jump).
+    root.classList.add("is-return");
     const closeMotion = { duration: CLOSE_MS, easing: "linear", fill: "forwards" };
     const closeOpts = { duration: CLOSE_MS, easing: "linear", fill: "forwards" };
     const stashEarly = openBook.pathTs;
@@ -1982,29 +2072,21 @@ export function mountBookshelf(root, options = {}) {
       heldEarly.style.visibility = "visible";
       heldEarly.style.zIndex = "70";
       heldEarly.style.opacity = "1";
+      if (heldEarly._board) {
+        heldEarly._board.style.opacity = "0";
+        heldEarly._board.style.visibility = "hidden";
+      }
       promote(heldEarly);
       earlyMove = heldEarly.animate(
-        [
-          pathKey(0, stashEarly.Tfull),
-          pathKey(0.28, stashEarly.Tp3),
-          pathKey(0.44, stashEarly.Tp2),
-          pathKey(0.60, stashEarly.Tp1),
-          pathKey(0.78, stashEarly.T0),
-          pathKey(0.90, stashEarly.T0),
-          pathKey(1, stashEarly.T0),
-        ],
+        returnMoveKeys(stashEarly.Tfull, stashEarly.Tp1, stashEarly.T0),
         closeMotion
       );
-      earlyNote = noteView.animate(
-        [
-          { offset: 0, opacity: 1 },
-          { offset: 0.06, opacity: 0.85 },
-          { offset: 0.12, opacity: 0.45 },
-          { offset: 0.22, opacity: 0 },
-          { offset: 1.0, opacity: 0 },
-        ],
-        closeOpts
-      );
+      earlyNote = noteView.animate(noteOutKeys(), closeOpts);
+      // Backup if the fade is dropped: the article must not still be up after ~230ms.
+      wait(Math.round(CLOSE_MS * 0.12)).then(() => {
+        if (myFlow !== flowSeq || !noteView) return;
+        noteView.style.opacity = "0";
+      });
       if (heldEarly._left) {
         earlyLeft = heldEarly._left.animate(
           [
@@ -2058,6 +2140,7 @@ export function mountBookshelf(root, options = {}) {
       try { earlyNote && earlyNote.cancel(); } catch (_) {}
       try { earlyLeft && earlyLeft.cancel(); } catch (_) {}
       try { earlyRight && earlyRight.cancel(); } catch (_) {}
+      root.classList.remove("is-return");
       noteView.classList.remove("is-open", "is-preparing");
       noteView.hidden = true;
       noteView.style.opacity = "";
@@ -2081,7 +2164,10 @@ export function mountBookshelf(root, options = {}) {
     ].forEach((p) => {
       try { slot.style.removeProperty(p); } catch (_) {}
     });
-    slot.classList.remove("is-collapsing", "is-placeholder", "is-expanded");
+    slot.classList.remove("is-collapsing", "is-expanded");
+    // Keep the seat empty until handover. Dropping is-placeholder here let the
+    // bk-* fill paint a solid rectangle under the returning cover.
+    slot.classList.add("is-placeholder");
     expandedId = null;
     // Spines: re-pin the resting face BEFORE reading the seat. A cleared inline
     // height is the shorter size-class box, and put-back would keep it.
@@ -2116,13 +2202,13 @@ export function mountBookshelf(root, options = {}) {
     });
     shelfView.classList.add("is-frozen");
 
-    // ux13: prepare shelf+flyer UNDER opaque note — ban route hard-cut then mid-air resume.
-    // Keep note is-open + opacity 1 until reverse clock starts.
+    // Note stays in the tree so its fade can finish, but must not cover the flyer.
+    // is-return (set before the clock) owns stacking. Do not pin z-index 75.
     noteView.classList.add("is-open");
     noteView.classList.remove("is-preparing");
     noteView.hidden = false;
-    noteView.style.opacity = "1";
-    noteView.style.zIndex = "75";
+    if (!earlyNote) noteView.style.opacity = "1";
+    noteView.style.zIndex = "";
 
     unparkShelf();
     shelfView.style.opacity = "1";
@@ -2217,7 +2303,10 @@ export function mountBookshelf(root, options = {}) {
       flyer._right.style.transform = "rotateY(-8deg)";
       flyer._right.style.opacity = "1";
     }
-    if (flyer._board) flyer._board.style.opacity = "1";
+    if (flyer._board) {
+      flyer._board.style.opacity = "0";
+      flyer._board.style.visibility = "hidden";
+    }
     if (flyer._leftThick) flyer._leftThick.style.opacity = "1";
     if (flyer._rightThick) flyer._rightThick.style.opacity = "1";
     if (flyer._gutter) flyer._gutter.style.opacity = "1";
@@ -2280,29 +2369,13 @@ export function mountBookshelf(root, options = {}) {
 
     resetVeil();
 
-    // ux13: note fades ON the book layer while reverse shrink starts — ban instant note unmount.
-    const aNoteOut = earlyNote || noteView.animate(
-      [
-        { offset: 0, opacity: 1 },
-        { offset: 0.06, opacity: 0.85 },
-        { offset: 0.12, opacity: 0.45 },
-        { offset: 0.22, opacity: 0 },
-        { offset: 1.0, opacity: 0 },
-      ],
-      closeOpts
-    );
+    // Note fades out in the first ~230ms. Shrink already started on frame 0.
+    const aNoteOut = earlyNote || noteView.animate(noteOutKeys(), closeOpts);
 
-    // Shrink starts at offset 0. The old 0.12 Tfull key was ~228ms parked at 672×504.
+    // Shrink starts at offset 0 and is already well under way by ~400ms.
+    // A first stop on Tp3 (25% home) at 0.28 left the book looking full for ~1s.
     const aFlyerMove = earlyMove || flyer.animate(
-      [
-        pathKey(0, Tfull),
-        pathKey(0.28, Tp3),
-        pathKey(0.44, Tp2),
-        pathKey(0.60, Tp1),
-        pathKey(0.78, T0),
-        pathKey(0.90, T0),
-        pathKey(1, T0),
-      ],
+      returnMoveKeys(Tfull, Tp1, T0),
       closeMotion
     );
     // Reverse hinge on SAME layer while shrink (open was 0.32→0.68 hinge).
@@ -2336,7 +2409,7 @@ export function mountBookshelf(root, options = {}) {
       { offset: 0.28, opacity: 0 },
       { offset: 1.0, opacity: 0 },
     ];
-    const aBoardClose = flyer._board ? flyer._board.animate(closedFaceOut, closeOpts) : null;
+    const aBoardClose = null;
     const aThickLClose = flyer._leftThick ? flyer._leftThick.animate(closedFaceOut, closeOpts) : null;
     const aThickRClose = flyer._rightThick ? flyer._rightThick.animate(closedFaceOut, closeOpts) : null;
     const aGutterClose = flyer._gutter
@@ -2377,9 +2450,11 @@ export function mountBookshelf(root, options = {}) {
     const aFlyerFade = flyer.animate(
       targetMode === "spines"
         ? [
+            // Stay through the shrink. Cutting at 0.58 dropped a still-large
+            // cover and made the first ~1.1s look like overlap, then a pop.
             { offset: 0, opacity: 1 },
-            { offset: 0.50, opacity: 1 },
-            { offset: 0.58, opacity: 0 },
+            { offset: 0.68, opacity: 1 },
+            { offset: 0.80, opacity: 0 },
             { offset: 1.0, opacity: 0 },
           ]
         : [
@@ -2411,10 +2486,10 @@ export function mountBookshelf(root, options = {}) {
       ? spineSlotClose.animate(
           [
             { offset: 0, transform: outClose, opacity: 0 },
-            { offset: 0.50, transform: outClose, opacity: 0 },
-            { offset: 0.58, transform: outClose, opacity: 1 },
-            { offset: 0.78, transform: "translate3d(0px, 0px, 0)", opacity: 1 },
-            { offset: 0.90, transform: "translate3d(0px, 0px, 0)", opacity: 1 },
+            { offset: 0.66, transform: outClose, opacity: 0 },
+            { offset: 0.74, transform: outClose, opacity: 1 },
+            { offset: 0.86, transform: "translate3d(0px, 0px, 0)", opacity: 1 },
+            { offset: 0.94, transform: "translate3d(0px, 0px, 0)", opacity: 1 },
             { offset: 1.0, transform: "translate3d(0px, 0px, 0)", opacity: 0 },
           ],
           closeMotion
@@ -2429,8 +2504,8 @@ export function mountBookshelf(root, options = {}) {
           targetMode === "spines"
             ? [
                 { offset: 0, opacity: 1 },
-                { offset: 0.50, opacity: 1 },
-                { offset: 0.58, opacity: 0 },
+                { offset: 0.68, opacity: 1 },
+                { offset: 0.80, opacity: 0 },
                 { offset: 1, opacity: 0 },
               ]
             : [
@@ -2452,6 +2527,13 @@ export function mountBookshelf(root, options = {}) {
       slot.style.backgroundColor = "";
     }
 
+    // Seat may show its real face only as the flyer hands off. Until then the
+    // placeholder ban (transparent, invisible) blocks the solid bk plate.
+    wait(Math.round(CLOSE_MS * Math.max(0, slotInAt - 0.02))).then(() => {
+      if (myFlow !== flowSeq || !slot.isConnected) return;
+      slot.classList.remove("is-placeholder");
+    });
+
     const aSlotIn = slot.animate(
       [
         { offset: 0, opacity: 0 },
@@ -2510,6 +2592,7 @@ export function mountBookshelf(root, options = {}) {
       flyer.style.opacity = "0";
       slot.style.opacity = "1";
       slot.style.transform = "none";
+      root.classList.remove("is-return");
       noteView.classList.remove("is-open", "is-preparing");
       noteView.hidden = true;
       noteView.style.opacity = "";

package/app/components/bookshelf/index.ts

@@ -4,9 +4,12 @@ export { Bookshelf } from "./Bookshelf";
 export { mountBookshelf } from "./engine";
 export type {
   BookshelfBook,
+  BookshelfBookPost,
   BookshelfFiller,
   BookshelfNote,
+  BookshelfNoteKind,
   BookshelfProps,
   BookshelfShelf,
   BookshelfSize,
+  BookshelfSource,
 } from "./types";

package/app/components/bookshelf/schema.mjs

@@ -7,6 +7,7 @@ export class BookshelfConfigError extends Error {
 }
 
 const SIZES = new Set(["thin", "s-short", "s-mid", "s-tall"]);
+const NOTE_KINDS = new Set(["overview", "excerpt"]);
 
 function record(value, code, message) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new BookshelfConfigError(code, message);
@@ -31,6 +32,71 @@ function parseSize(value, where) {
   throw new BookshelfConfigError("size", `${where} 的 size 只能是 thin、s-short、s-mid 或 s-tall。`);
 }
 
+/** Same path identity as the shelf loader: drop content/posts and .md. */
+function postKey(value) {
+  return value.trim().replaceAll("\\", "/").replace(/^(?:content\/)?posts\//u, "").replace(/\.md$/u, "");
+}
+
+function parsePostEntry(item, where, index) {
+  if (typeof item === "string") {
+    const path = optionalString(item);
+    if (!path) throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 必须是路径。`);
+    return { path };
+  }
+  const entry = record(item, "posts", `${where} 的 posts[${index}] 必须是路径或映射。`);
+  const path = optionalString(entry.path);
+  if (!path) throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 需要 path。`);
+  const kind = optionalString(entry.kind);
+  if (kind && !NOTE_KINDS.has(kind)) {
+    throw new BookshelfConfigError("posts", `${where} 的 posts[${index}] 的 kind 只能是 overview 或 excerpt。`);
+  }
+  return kind ? { path, kind } : { path };
+}
+
+/**
+ * `post` is shorthand for one note. `posts` is the list.
+ * When `posts` is set it is the list, and `post` may only repeat the first path.
+ */
+function parsePostList(book, where) {
+  const single = optionalString(book.post);
+  if (book.posts == null) {
+    return single ? { post: single, posts: [{ path: single }] } : { post: undefined, posts: undefined };
+  }
+  if (!Array.isArray(book.posts)) {
+    throw new BookshelfConfigError("posts", `${where} 的 posts 必须是路径数组。`);
+  }
+  const posts = book.posts.map((item, index) => parsePostEntry(item, where, index));
+  if (posts.length === 0) throw new BookshelfConfigError("posts", `${where} 的 posts 不能为空。`);
+  const seenPaths = new Set();
+  for (const entry of posts) {
+    const key = postKey(entry.path);
+    if (seenPaths.has(key)) throw new BookshelfConfigError("posts", `${where} 的 posts 重复引用「${entry.path}」。`);
+    seenPaths.add(key);
+  }
+  if (single && postKey(single) !== postKey(posts[0].path)) {
+    throw new BookshelfConfigError("posts", `${where} 的 post 与 posts 的第一篇不是同一路径。多篇笔记只写 posts。`);
+  }
+  return { post: posts[0].path, posts };
+}
+
+function parseSources(value, where) {
+  if (value == null) return undefined;
+  if (!Array.isArray(value)) throw new BookshelfConfigError("sources", `${where} 的 sources 必须是数组。`);
+  if (value.length === 0) return undefined;
+  return value.map((item, index) => {
+    const source = record(item, "sources", `${where} 的 sources[${index}] 必须是映射。`);
+    const label = optionalString(source.label);
+    const href = optionalString(source.href);
+    if (!label || !href) {
+      throw new BookshelfConfigError("sources", `${where} 的 sources[${index}] 需要 label 和 href。`);
+    }
+    if (!/^(?:https?:\/\/|\/\/|\/(?!\/))/iu.test(href)) {
+      throw new BookshelfConfigError("sources", `${where} 的 sources[${index}] 只接受 http(s) 或以 / 开头的地址。`);
+    }
+    return { label, href };
+  });
+}
+
 function parseBook(value, where, seen) {
   const book = record(value, "book", `${where} 必须是映射。`);
   const id = optionalString(book.id);
@@ -38,6 +104,7 @@ function parseBook(value, where, seen) {
   if (!id || !title) throw new BookshelfConfigError("book", `${where} 需要 id 和 title。`);
   if (seen.has(id)) throw new BookshelfConfigError("duplicate-id", `${where} 的 id「${id}」重复。`);
   seen.add(id);
+  const notes = parsePostList(book, where);
   return {
     id,
     title,
@@ -47,7 +114,9 @@ function parseBook(value, where, seen) {
     cover: optionalString(book.cover),
     color: optionalString(book.color),
     filler: parseFiller(book.filler, where),
-    post: optionalString(book.post),
+    post: notes.post,
+    posts: notes.posts,
+    sources: parseSources(book.sources, where),
     note: typeof book.note === "string" && book.note.trim() ? book.note.trim() : undefined,
   };
 }

package/app/components/bookshelf/schema.ts

@@ -11,7 +11,9 @@ export type BookshelfConfigCode =
   | "size"
   | "filler"
   | "cover"
-  | "post";
+  | "post"
+  | "posts"
+  | "sources";
 
 export interface BookshelfConfigError extends Error {
   readonly code: BookshelfConfigCode;
@@ -23,18 +25,54 @@ export const BookshelfConfigError = ConfigError as unknown as new (
   message: string,
 ) => BookshelfConfigError;
 
+/** `overview` is the reading note (总览). `excerpt` is the quotation note (摘抄). */
+export type BookshelfNoteKind = "overview" | "excerpt";
+
+/** One note bound to a volume. A string in yaml is shorthand for `{ path }`. */
+export type BookshelfFilePost = {
+  /** Path under `content/posts/`, without `.md`. */
+  path: string;
+  kind?: BookshelfNoteKind;
+};
+
+/** Outbound source on the book card. Rendered as a quiet chip, not a button. */
+export type BookshelfFileSource = {
+  label: string;
+  href: string;
+};
+
 /**
- * One volume in `content/bookshelf.yaml`.
+ * One volume in `content/bookshelf.yaml`. One yaml entry is one spine.
+ *
+ * Covers stay on two paths:
+ * - yaml `cover` is the book jacket (Douban). It is the only image for the
+ *   shelf face, the open/close flyer, and the book-hub card.
+ * - a post's front matter `cover` is that note's hero on the article page.
+ *   Never copy a note hero into the jacket slot.
+ * - omit yaml `cover` and the jacket falls back to the first note's cover.
  *
- * Site contract (what a blog drops in to replace the package demo):
- * - `post` is a path under `content/posts/`, without `.md`. The shelf renders that
- *   post as the open-book note (front matter `description` is the short summary).
- * - `cover` is either a full URL (`https://…`, `//…`, or a site path starting
- *   with `/`) or a file name. A file name is published at `/media/covers/<file>`,
- *   the same URL `content/covers/` gets when a post's `cover` names that file.
- *   Omit `cover` to reuse the post's own cover.
+ * Notes:
+ * - `post: path` is shorthand for `posts: [path]`.
+ * - `posts` is the note list, in order. `kind: overview | excerpt` labels the
+ *   hub card 总览 or 摘抄. A bare string is a path with no kind.
+ * - when `posts` is set, `post` is optional. If both are set, `post` must be
+ *   the same path as `posts[0]`. Otherwise the shelf is rejected.
+ * - one note: the shelf opens that note as it does today (extract flyer, note,
+ *   return flyer). There is no book hub.
+ * - two or more notes: a spine click leaves the shelf for `/bookshelf/<id>`
+ *   (本书). It does not open `posts[0]` and it does not play the flyer.
+ *   The hub card is the locked book-multi layout: the jacket slot is 148px
+ *   wide, the image fills that width, and the height follows the file's ratio.
+ *   There is no plate behind the jacket. A Douban scan's white border is
+ *   cropped in the jacket file before it is committed; the build copies that
+ *   file into `/media/covers/` unchanged.
+ *   「我的笔记」 lists the notes. A note card is an ordinary link to that
+ *   article; article ↔ list does not play the flyer. The flyer runs only when
+ *   a single-note book is extracted from the shelf and put back.
+ * - `sources` are optional `{ label, href }` chips. The hub shows 豆瓣 and PDF
+ *   only. The PDF chip carries the caption 「（仅分享，侵权删）」. No chapter list.
+ * - `note` is Markdown used only when the book has no posts.
  * - `color` (`#rgb` or `#rrggbb`) is the spine cloth and the open-page palette.
- * - `note` is Markdown used only when `post` is absent.
  */
 export type BookshelfFileBook = {
   id: string;
@@ -42,10 +80,14 @@ export type BookshelfFileBook = {
   author?: string;
   spine?: string;
   size?: BookshelfSize;
+  /** Book jacket. File name under `content/covers/`, or a full URL. */
   cover?: string;
   color?: string;
   filler?: BookshelfFiller;
+  /** Shorthand for a single note. Equal to `posts[0].path` after parsing. */
   post?: string;
+  posts?: BookshelfFilePost[];
+  sources?: BookshelfFileSource[];
   note?: string;
 };