tosijs-ui 1.16.9 → 1.16.10

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.16.10
+
+Print now opens with the book cover.
+
+- **Print as PDF has a cover.** The first page is the default volume's cover: your
+  `epub.cover` image, or the one generated from the title and `coverIcon`. The title page and
+  contents follow it. Print checks the image loads before using it, so a site without `epub`,
+  a build that wrote no cover, or a corpus with no default volume prints as it did before.
+  `epub: { printCover: false }` leaves the cover out of Print and keeps it in the ePub.
+- **The cover is a file you can link.** Each ePub build writes its cover beside the book
+  (`my-project-cover.png`; an explicit cover keeps its own type), and `/epub-volumes.json`
+  gains `coverFilename` and `coverUrl` for every volume whose cover the build wrote. A volume
+  without a cover has neither field.
+- A WebP or SVG `epub.cover` is now declared with its own media type in the ePub; it was
+  labelled `image/png`.
+- `attachCovers`, `printCoverManifestUrl` and `VOLUME_MANIFEST` are exported from
+  `tosijs-ui/site` for a build that does not go through `buildSite`.
+- A configured `epub.cover` that does not exist now prints a warning; the build still
+  generates a cover in its place, as before.
+
 ## 1.16.9
 
 Two sets of asks from tjs-lang for *The TJS Programming Language*, a book that teaches

package/dist/doc-system/book-html.d.ts

@@ -9,7 +9,7 @@ export interface BookDoc {
     hidden?: boolean;
 }
 export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/*\nPrism token colours for the book \u2014 a LIGHT palette, deliberately distinct from the site's.\n\nThe site has TWO palettes, one per mode. A book has one background and it is light: the\npre rule above is #f6f8fa, an ePub reader may impose white or sepia, and paper is paper.\nReusing the site palette here would be light-on-light \u2014 invisible body text dressed as syntax\nhighlighting, which is the exact failure a nested diff hit in tosijs-ui#143.\n\nContrast-checked against #f6f8fa; the comment green is the weakest at ~4.6:1, still above\nWCAG AA for body text. Colours are literal rather than custom properties because this\nstylesheet ships inside an ePub, where custom properties are not reliably supported.\n\nNO BACKTICKS in this comment: it lives inside a JS template literal, so one would end the\nstring and drop the rest of the stylesheet into code. (It did. Same shape as a block comment\nending a doc comment early \u2014 punctuation that means something to the container.)\n*/\n.token.comment, .token.prolog, .token.cdata { color: #5c6f5c; font-style: italic; }\n.token.punctuation { color: #666; }\n.token.string, .token.char, .token.attr-value, .token.regex { color: #a03030; }\n.token.number, .token.boolean, .token.constant { color: #0b7285; }\n.token.keyword, .token.important, .token.atrule { color: #0a5bb5; }\n.token.function, .token.class-name { color: #7a4b00; }\n.token.operator, .token.entity, .token.url { color: #444; }\n.token.tag, .token.selector, .token.builtin { color: #0a6b52; }\n.token.attr-name, .token.property { color: #2a5db0; }\n.token.deleted { color: #b02020; }\n.token.inserted { color: #2a6b2a; }\n.token.bold { font-weight: bold; }\n.token.italic { font-style: italic; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
-export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
+export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-cover { display: block; margin: 0 auto; max-width: 100%; max-height: 100vh; page-break-after: always; break-inside: avoid; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
 export declare function escapeHtml(s: string): string;
 export declare function slugify(s: string): string;
 /** Drop the `<!--{ … }-->` metadata directives the extractor leaves in the text. */
@@ -18,6 +18,12 @@ export declare function stripDocMeta(text: string): string;
 export declare function flatten<T extends NavDoc>(nodes: NavNode<T>[]): NavNode<T>[];
 export interface BookHtmlOptions {
     title: string;
+    /**
+     * URL of a cover image, printed as the first page. The caller is responsible for it
+     * loading (`resolveBookCover` checks before passing it): a broken image here is a blank
+     * first page.
+     */
+    cover?: string;
     /** full stylesheet (defaults to DEFAULT_BOOK_CSS + PRINT_CSS) */
     css?: string;
     lang?: string;

package/dist/doc-system/book-html.js

@@ -108,6 +108,7 @@ a.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }
 // Print-only layout: page margins, a chapter per page, an avoid-break TOC.
 export const PRINT_CSS = `
 @page { margin: 18mm 16mm; }
+.book-cover { display: block; margin: 0 auto; max-width: 100%; max-height: 100vh; page-break-after: always; break-inside: avoid; }
 .book-title { text-align: center; margin: 30vh 0 1em; }
 .book-toc { page-break-after: always; }
 .book-toc h2 { page-break-before: avoid; }
@@ -119,6 +120,7 @@ export const PRINT_CSS = `
 export function escapeHtml(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
+const escapeAttr = (s) => escapeHtml(s).replace(/"/g, '&quot;');
 export function slugify(s) {
     return s
         .toLowerCase()
@@ -160,6 +162,9 @@ export function buildBookHtml(docs, opts) {
 <style>${css}</style>
 </head>
 <body>
+${opts.cover
+        ? `<img class="book-cover" src="${escapeAttr(opts.cover)}" alt="${escapeAttr(opts.title)} cover"/>`
+        : ''}
 <h1 class="book-title">${escapeHtml(opts.title)}</h1>
 <nav class="book-toc"><h2>Contents</h2><ol>${tocHtml(roots)}</ol></nav>
 ${chapters}

package/dist/doc-system/doc-system.js

@@ -62,7 +62,7 @@ import { createDocBrowser, } from '../doc-browser.js';
 import { buildSlugMap, legacyQueryPath } from './routing.js';
 import { buildBookHtml, slugify } from './book-html.js';
 import { highlightBlocks } from './highlight.js';
-import { printWhenReady } from './print-window.js';
+import { printWhenReady, resolveBookCover } from './print-window.js';
 import { docSystemStyleSpec } from './doc-system-styles.js';
 import { icons } from '../icons.js';
 import { popMenu } from '../menu.js';
@@ -288,8 +288,11 @@ export class TosiDocSystem extends withAttributes({
                 const menuItems = [];
                 // Print / ePub of the whole corpus, before a separator + the prefs.
                 let projectName = '';
+                let bookVolumes;
                 try {
-                    projectName = JSON.parse(this.config || '{}').projectName || '';
+                    const parsed = JSON.parse(this.config || '{}');
+                    projectName = parsed.projectName || '';
+                    bookVolumes = parsed.bookVolumes || undefined;
                 }
                 catch {
                     // ignore — fall through to document.title
@@ -298,12 +301,16 @@ export class TosiDocSystem extends withAttributes({
                 menuItems.push({
                     caption: 'Print as PDF',
                     icon: 'printer',
-                    action: () => {
+                    action: async () => {
+                        // Opened synchronously, inside the click, or a popup blocker refuses it.
                         const win = window.open('', '_blank');
                         if (!win) {
                             window.alert('Allow pop-ups to print the documentation as a book.');
                             return;
                         }
+                        // Checked before the book is written: a cover only if the build wrote one
+                        // and it loads. See `resolveBookCover`.
+                        const bookCover = await resolveBookCover(bookVolumes);
                         win.document.open();
                         /*
                         `autoPrint: false` — highlight BEFORE printing (review major M1).
@@ -319,6 +326,7 @@ export class TosiDocSystem extends withAttributes({
                         */
                         win.document.write(buildBookHtml(this.corpus, {
                             title: bookTitle,
+                            cover: bookCover,
                             autoPrint: false,
                         }));
                         win.document.close();

package/dist/doc-system/print-window.d.ts

@@ -28,3 +28,31 @@ export interface PrintWhenReadyOptions {
  * document.
  */
 export declare function printWhenReady(win: PrintableWindow, highlight: () => Promise<unknown>, opts?: PrintWhenReadyOptions): Promise<void>;
+export interface ResolveBookCoverOptions {
+    /** Injected for tests. */
+    fetchFn?: (url: string) => Promise<{
+        ok: boolean;
+        json: () => Promise<unknown>;
+    }>;
+    /** Resolves when the image at `url` loads, rejects when it does not. Injected for tests. */
+    loadImage?: (url: string) => Promise<unknown>;
+    /**
+     * How long the whole lookup may take before Print goes ahead without a cover. The files
+     * are small and same-origin, so this only bites on a stalled connection.
+     */
+    timeoutMs?: number;
+}
+/**
+ * The cover Print should open with, or `undefined` for none.
+ *
+ * Reads the default volume's `coverUrl` from the volume manifest the site build wrote, then
+ * loads the image before answering. Both steps are checks on purpose: the manifest lists a
+ * cover only when the build wrote one, and loading it here means the printed book never
+ * starts with a broken image and a page break — without an inline `onerror`, which a
+ * Content-Security-Policy would block in the popup.
+ *
+ * Any failure means no cover, and so does taking too long: the popup is already open and
+ * blank while this runs, and a request that never settles must not leave it that way. Print
+ * must still happen.
+ */
+export declare function resolveBookCover(manifestUrl: string | undefined, opts?: ResolveBookCoverOptions): Promise<string | undefined>;

package/dist/doc-system/print-window.js

@@ -14,6 +14,7 @@ The two changes, so the shape is not rediscovered:
 Both failure modes are silent in the worst way: a print dialog that opens over a half-rendered
 page, or one that never opens at all. Neither throws, and you only find out by printing.
 */
+import { DEFAULT_BOOK } from './book-target.js';
 /**
  * Highlight, then print — after the window has actually loaded.
  *
@@ -48,3 +49,47 @@ export function printWhenReady(win, highlight, opts = {}) {
             win.addEventListener('load', go, { once: true });
     });
 }
+const loadImageInPage = (url) => new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = resolve;
+    img.onerror = reject;
+    img.src = url;
+});
+/**
+ * The cover Print should open with, or `undefined` for none.
+ *
+ * Reads the default volume's `coverUrl` from the volume manifest the site build wrote, then
+ * loads the image before answering. Both steps are checks on purpose: the manifest lists a
+ * cover only when the build wrote one, and loading it here means the printed book never
+ * starts with a broken image and a page break — without an inline `onerror`, which a
+ * Content-Security-Policy would block in the popup.
+ *
+ * Any failure means no cover, and so does taking too long: the popup is already open and
+ * blank while this runs, and a request that never settles must not leave it that way. Print
+ * must still happen.
+ */
+export function resolveBookCover(manifestUrl, opts = {}) {
+    if (!manifestUrl)
+        return Promise.resolve(undefined);
+    const { fetchFn = fetch, loadImage = loadImageInPage, timeoutMs = 3000, } = opts;
+    const lookup = async () => {
+        try {
+            const response = await fetchFn(manifestUrl);
+            if (!response.ok)
+                return undefined;
+            const volumes = (await response.json());
+            const cover = volumes.find((v) => v.book === DEFAULT_BOOK)?.coverUrl;
+            if (!cover)
+                return undefined;
+            await loadImage(cover);
+            return cover;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return Promise.race([
+        lookup(),
+        new Promise((resolve) => setTimeout(() => resolve(undefined), timeoutMs)),
+    ]);
+}

package/dist/doc-system/site/epub-volumes.d.ts

@@ -1,3 +1,5 @@
+/** Where the volume manifest is served. */
+export declare const VOLUME_MANIFEST = "epub-volumes.json";
 export interface EpubVolume {
     /** the `book` value, or '' for the default volume */
     book: string;
@@ -7,13 +9,38 @@ export interface EpubVolume {
     filename: string;
     /** served URL, honouring basePath */
     url: string;
+    /**
+     * The cover image the build wrote beside the ePub, e.g. `my-project-cover.png`. Present
+     * only in the manifest, and only when that file exists: it is read back from the output
+     * dir after the ePubs are built (`attachCovers`), never predicted.
+     */
+    coverFilename?: string;
+    /** served URL of that cover, honouring basePath — Print uses it as its first page */
+    coverUrl?: string;
 }
+/**
+ * The image types a cover may be, by extension. One table: the ePub build labels its cover
+ * from it and `attachCovers` recognises a cover file by it.
+ */
+export declare const COVER_MEDIA_TYPES: Record<string, string>;
+/** The name `buildEpub` gives a cover written beside `<stem>.epub`, minus its extension. */
+export declare const coverStem: (epubFilename: string) => string;
+/**
+ * Add `coverFilename`/`coverUrl` to each volume whose cover is among `files` (a listing of
+ * the output dir, taken AFTER the ePubs were built).
+ *
+ * Read back and not derived, because only the ePub build knows what it wrote: an explicit
+ * cover keeps its own type, a missing one falls back to a generated PNG, and a build without
+ * `@resvg/resvg-js` writes none. A predicted name was wrong in each of those cases.
+ */
+export declare function attachCovers(volumes: EpubVolume[], files: string[], basePath?: string): EpubVolume[];
 export interface VolumeNamingConfig {
     name?: string;
     basePath?: string;
     epub?: boolean | {
         title?: string;
         volumeTitles?: Record<string, string>;
+        printCover?: boolean;
     };
 }
 /**
@@ -47,3 +74,8 @@ export declare const EPUB_DOWNLOADS_MARKER: RegExp;
  * comment.
  */
 export declare function renderEpubDownloads(text: string, volumes: EpubVolume[]): string;
+/**
+ * The manifest URL a page should hand to Print so it can open with the cover, or
+ * `undefined` when it should not: no ePub is built, or `epub.printCover` is `false`.
+ */
+export declare function printCoverManifestUrl(config: VolumeNamingConfig): string | undefined;

package/dist/doc-system/site/epub-volumes.js

@@ -25,6 +25,43 @@ function slugify(text) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
 }
+/** Where the volume manifest is served. */
+export const VOLUME_MANIFEST = 'epub-volumes.json';
+/**
+ * The image types a cover may be, by extension. One table: the ePub build labels its cover
+ * from it and `attachCovers` recognises a cover file by it.
+ */
+export const COVER_MEDIA_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+};
+/** The name `buildEpub` gives a cover written beside `<stem>.epub`, minus its extension. */
+export const coverStem = (epubFilename) => `${epubFilename.replace(/\.epub$/, '')}-cover`;
+/**
+ * Add `coverFilename`/`coverUrl` to each volume whose cover is among `files` (a listing of
+ * the output dir, taken AFTER the ePubs were built).
+ *
+ * Read back and not derived, because only the ePub build knows what it wrote: an explicit
+ * cover keeps its own type, a missing one falls back to a generated PNG, and a build without
+ * `@resvg/resvg-js` writes none. A predicted name was wrong in each of those cases.
+ */
+export function attachCovers(volumes, files, basePath = '/') {
+    const base = basePath.replace(/\/+$/, '');
+    return volumes.map((volume) => {
+        const stem = coverStem(volume.filename);
+        // An image, by extension: a volume named "cover" writes `<stem>-cover.epub`, which is
+        // another volume's book and not this one's cover.
+        const coverFilename = files.find((f) => f.startsWith(`${stem}.`) &&
+            f.slice(stem.length).toLowerCase() in COVER_MEDIA_TYPES);
+        return coverFilename
+            ? { ...volume, coverFilename, coverUrl: `${base}/${coverFilename}` }
+            : volume;
+    });
+}
 /**
  * The identity of one volume. `bookTarget` undefined means the default volume.
  *
@@ -91,3 +128,14 @@ export function renderEpubDownloads(text, volumes) {
         .join('\n');
     return text.replace(EPUB_DOWNLOADS_MARKER, list);
 }
+/**
+ * The manifest URL a page should hand to Print so it can open with the cover, or
+ * `undefined` when it should not: no ePub is built, or `epub.printCover` is `false`.
+ */
+export function printCoverManifestUrl(config) {
+    if (!config.epub)
+        return undefined;
+    if (typeof config.epub === 'object' && config.epub.printCover === false)
+        return undefined;
+    return `${(config.basePath ?? '/').replace(/\/+$/, '')}/${VOLUME_MANIFEST}`;
+}

package/dist/doc-system/site/epub.d.ts

@@ -54,6 +54,11 @@ export interface BuildEpubOptions {
     coverIcon?: string;
     /** background color for the generated cover, default '#1f2933' */
     coverColor?: string;
+    /**
+     * `false` keeps the cover out of Print as PDF, which otherwise opens with the default
+     * volume's cover. The ePub's own cover is unaffected.
+     */
+    printCover?: boolean;
 }
 export declare function escapeXml(s: string): string;
 /**

package/dist/doc-system/site/epub.js

@@ -21,7 +21,7 @@ import { highlightHtml } from '../highlight.js';
 import { buildSlugMap, pathForSlug, resolveParent, slugForPath, withBase, } from '../routing.js';
 import { buildNavTree } from '../nav-tree.js';
 import { partitionByBook, placeInBook, bookTextOf, DEFAULT_BOOK, } from '../book-target.js';
-import { epubVolumeIdentity } from './epub-volumes.js';
+import { COVER_MEDIA_TYPES, coverStem, epubVolumeIdentity, } from './epub-volumes.js';
 import { isLiveFence, languageOfClass } from '../example-policy.js';
 import { DEFAULT_BOOK_CSS, stripDocMeta, flatten, slugify, } from '../book-html.js';
 import { selectBookDocs } from '../book-manifest.js';
@@ -513,13 +513,12 @@ function loadSvgGlyph(absPath) {
  * if neither is available.
  */
 async function makeCover(config, opts, meta) {
+    if (opts.cover && !fs.existsSync(opts.cover)) {
+        console.warn(`epub: cover "${opts.cover}" not found — generating one from the title instead.`);
+    }
     if (opts.cover && fs.existsSync(opts.cover)) {
         const ext = path.extname(opts.cover).toLowerCase();
-        const mediaType = ext === '.jpg' || ext === '.jpeg'
-            ? 'image/jpeg'
-            : ext === '.gif'
-                ? 'image/gif'
-                : 'image/png';
+        const mediaType = COVER_MEDIA_TYPES[ext] ?? 'image/png';
         return {
             file: `cover${ext || '.png'}`,
             mediaType,
@@ -786,6 +785,13 @@ export async function buildEpub(config, opts = {}) {
         // on disk all derive from one function. A link cannot point at a name nothing wrote.
         path.join(outDir, epubVolumeIdentity({ name: baseTitle, epub: { title: baseTitle } }, opts.bookTarget).filename));
     await zipEpub(buildDir, output);
+    // The same cover, as a plain file beside the ePub, so Print can open with it. The site
+    // build reads the name back from the output dir (`attachCovers`); nothing predicts it.
+    const coverPath = cover
+        ? path.join(path.dirname(output), coverStem(path.basename(output)) + path.extname(cover.file))
+        : null;
+    if (cover && coverPath)
+        fs.writeFileSync(coverPath, cover.data);
     fs.rmSync(buildDir, { recursive: true, force: true });
     // Release the parser window: an unclosed happy-dom Window holds its whole
     // document (every chapter parsed) plus its timers. Hygiene, not a proven win —
@@ -793,6 +799,7 @@ export async function buildEpub(config, opts = {}) {
     // is still retained. buildEpub now runs in a child process (see orchestrator),
     // which is what actually bounds it.
     win?.close?.();
-    console.log(`epub: ${output} (${chapters.length} chapters)`);
+    console.log(`epub: ${output} (${chapters.length} chapters)` +
+        (coverPath ? `, cover ${path.basename(coverPath)}` : ''));
     return output;
 }

package/dist/doc-system/site/generate-site.d.ts

@@ -15,6 +15,11 @@ export interface GenerateSiteConfig {
     /** directory to write pages into (the served web root, e.g. ./docs) */
     outputDir: string;
     projectName?: string;
+    /**
+     * URL of the volume manifest (`/epub-volumes.json`). Print reads the default volume's
+     * cover from it; omitted when the site has no ePub or opted out with `printCover: false`.
+     */
+    bookVolumes?: string;
     /** site-level description, used as a fallback when a doc has none */
     description?: string;
     /** <html lang>, default 'en' */

package/dist/doc-system/site/generate-site.js

@@ -303,6 +303,7 @@ export async function generateSite(config) {
         projectName: config.projectName,
         projectLinks: config.projectLinks,
         logo: config.logo,
+        bookVolumes: config.bookVolumes,
     }));
     // The theme stylesheet (config.stylesUrl) is written separately by
     // ./generate-css.ts; pages here just <link> to it.

package/dist/doc-system/site/index.d.ts

@@ -21,7 +21,7 @@ export type { BookManifest } from '../book-manifest.js';
 export { placeInBook, bookTextOf } from '../book-target.js';
 export type { BookPlacement } from '../book-target.js';
 export { assembleCorpus, resolveInsets, splitConditions, SingleSourceError, } from './single-source.js';
-export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, type EpubVolume, } from './epub-volumes.js';
+export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, attachCovers, printCoverManifestUrl, VOLUME_MANIFEST, type EpubVolume, } from './epub-volumes.js';
 export { currentHolder, describeHolder, lockPathFor, lockDecision, isProcessAlive, } from './build-lock.js';
 export type { LockHolder, LockDecision } from './build-lock.js';
 export { registerGrammar, registeredGrammars, highlightHtml, highlightBlocks, grammarFor, } from '../highlight.js';

package/dist/doc-system/site/index.js

@@ -22,7 +22,7 @@ export { placeInBook, bookTextOf } from '../book-target.js';
 // Insets and conditional text (#217): `extractDocs` applies these; exported for a consumer
 // that builds its corpus some other way.
 export { assembleCorpus, resolveInsets, splitConditions, SingleSourceError, } from './single-source.js';
-export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, } from './epub-volumes.js';
+export { listEpubVolumes, epubVolumeIdentity, renderEpubDownloads, attachCovers, printCoverManifestUrl, VOLUME_MANIFEST, } from './epub-volumes.js';
 /*
 Reading the build lock is part of the PUBLIC surface, not an internal detail (#117).
 

package/dist/doc-system/site/orchestrator.js

@@ -28,7 +28,7 @@ function registerSiteDialects(config) {
     }
 }
 import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
-import { listEpubVolumes, renderEpubDownloads } from './epub-volumes.js';
+import { attachCovers, listEpubVolumes, printCoverManifestUrl, VOLUME_MANIFEST, renderEpubDownloads, } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
 import { computeAssetStamp, missingStampInputWarning } from './asset-stamp.js';
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, } from 'fs';
@@ -656,7 +656,7 @@ export async function buildSite(config, opts = {}) {
                     await Bun.write(DOCS_JSON, JSON.stringify(corpus, null, 2));
                 // A stable, machine-readable list so a consumer can link the books without
                 // re-deriving the filename — the "documented helper" half of #46.
-                await Bun.write(`${PUBLIC}/epub-volumes.json`, JSON.stringify(volumes, null, 2));
+                await Bun.write(`${PUBLIC}/${VOLUME_MANIFEST}`, JSON.stringify(volumes, null, 2));
             };
             // Auto-create missing section docs + regenerate their TOC blocks, then
             // re-extract so the corpus reflects the on-disk changes.
@@ -1479,6 +1479,7 @@ export async function buildSite(config, opts = {}) {
                 docs,
                 outputDir: PUBLIC,
                 projectName: config.name,
+                bookVolumes: printCoverManifestUrl(config),
                 description: config.description,
                 baseUrl: config.baseUrl,
                 lang: config.lang,
@@ -1600,6 +1601,12 @@ export async function buildSite(config, opts = {}) {
                         bookTarget,
                     });
                 }
+                // Now the covers exist (or do not), say so in the manifest: a `coverUrl` there
+                // names a file this build wrote. Print reads the default volume's from here.
+                const manifest = `${PUBLIC}/${VOLUME_MANIFEST}`;
+                if (existsSync(manifest)) {
+                    await Bun.write(manifest, JSON.stringify(attachCovers(JSON.parse(await Bun.file(manifest).text()), readdirSync(PUBLIC), config.basePath), null, 2));
+                }
             }
             console.timeEnd('build');
             // A failed library typecheck (above) marks the whole build failed so a one-shot

package/dist/doc-system/site/site-config.d.ts

@@ -321,6 +321,11 @@ export interface SiteConfig {
         coverIcon?: string;
         /** background color for the generated cover, default '#1f2933' */
         coverColor?: string;
+        /**
+         * `false` keeps the cover out of Print as PDF, which otherwise opens with the
+         * default volume's cover. The ePub's own cover is unaffected.
+         */
+        printCover?: boolean;
     };
     /**
      * Curate the book artifact (ePub, and later print) as a subset / reordering of