tosijs-ui 1.16.8 → 1.16.10

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # 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
+programming in the page. Single-sourcing for books (#217): one corpus, several outputs,
+nothing kept in sync by hand. And live examples that open with their code showing and a
+console that speaks the example's language (#216). Additive, with one behaviour change to
+know about: in a `tjs` or `ts` example, or one in a registered dialect, a line typed at the
+console is now evaluated in that language and not as JavaScript. `dist/iife.js` grows by
+0.7 kB gzip.
+
+### The book opens on the project, not on "Adopting the doc system"
+
+Both pages are pinned to the top, and the adopting page had an `order` where the README had
+none, so it sorted first: the ePub's opening chapter, and the first entry in the site nav, was
+a page about adopting the doc system. The README now leads both.
+
+### One source, several outputs (#217)
+
+- **Per-volume placement.** A page can sit in a different place in each book:
+  `{"placement": {"language": {"parent": "for-programmers", "order": 20}}}` in its metadata.
+  Each entry may set `parent`, `order`, `pin` and `title`, and naming a volume also binds the
+  page into it. The site nav is unaffected.
+- **Text insets.** `<!--{ "inset": "install.md#with-bun" }-->` includes another document, or
+  one heading's section of it, in the page. A fragment (a markdown file whose name starts
+  with `_`, in a directory the docs are extracted from) can be inset without being a page, and is the only kind of
+  file an inset reads. Resolved at extraction, so the site, the ePubs, `llms.txt` and the markdown copies
+  all get the assembled text, and an inset passage's live examples and tests run where it is
+  inset.
+- **Conditional text.** `<!--{ "only": "book" | "site" }--> … <!--{ "end": "only" }-->`
+  conditional text, for wording that belongs to one output, such as "next chapter" against
+  "next page". Books read `bookText`, everything else reads `text`; both are in the published
+  `docs.json`, so this chooses wording and does not hide anything.
+- **Each is guarded.** An inset that resolves nowhere, an include cycle, a missing heading, a
+  file that is not a fragment, an unbalanced `only`, a directive inside a list, quote or
+  paragraph, and a placement under a parent that is not in the volume all fail the build.
+- **Print is not a volume.** The in-app Print output takes the book wording but stays the
+  whole site in site order; `placement` arranges ePub volumes.
+- New from `tosijs-ui/site`, for a consumer that builds its corpus some other way:
+  `assembleCorpus`, `resolveInsets`, `splitConditions`, `SingleSourceError`, `placeInBook`,
+  `bookTextOf`, and the `BookPlacement` type.
+- Saving an edited live example back to source is refused on a page whose source uses an
+  inset or conditional text, where the example's position on the page no longer identifies a
+  block in that file. No existing page is affected: it applies only to a page that uses one
+  of the new directives.
+
+### Examples that open with their code showing, and a console in their language (#216)
+
+- **A fence picks the view an example opens in.** `{"view": "code"}` in the source block's
+  fence options opens the editor beside the preview, in the page and not full-screen;
+  `{"view": "console"}` puts the console where the preview would be, beside the code, for
+  examples whose point is a value. The editor is built as the example nears the viewport. In
+  a narrow column the panes stack. `example.showInline('code' | 'console')` does the same
+  from code.
+- **The console evaluates in the example's dialect.** A line goes through the same transform
+  as the example's code, with the same fence options, so `x == '5'` in a `tjs` example is
+  TJS's `==`. A line the dialect rejects shows the dialect's error and is not retried as
+  JavaScript. Plain `js` examples and `run` dialects are unchanged. A registered dialect's
+  `transform` now also receives console lines, marked with `options.repl === true`.
+- **Known limit of the above with tjs.** tjs puts setup statements in front of the line it
+  translates, so an expression shows its value, but a line that is only a declaration shows a
+  leftover value where a browser console shows `undefined`, and a line needing both that
+  setup and `await` shows `undefined`. Fixing it needs the setup to be separable, which is
+  asked of tjs-lang.
+- The generated JavaScript tjs-lang asked to see already exists as the read-only **JS** tab of
+  a `tjs` or `ts` example, and the inline views make it reachable in the page. Showing the
+  JavaScript for a single console line is not in this release: a transform's output for one
+  line is mostly its runtime prelude, and there is no general way to separate the two.
+
 ## 1.16.8
 
 A patch for honest results. The doc-test lane can no longer pass over pages that never

package/README.md

@@ -1,6 +1,6 @@
 # tosijs-ui
 
-<!--{ "pin": "top", "layout": "full-width", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
+<!--{ "pin": "top", "order": 0, "layout": "full-width", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
 
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 

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

@@ -3,11 +3,13 @@ export interface BookDoc {
     filename: string;
     title: string;
     text: string;
+    /** the book's variant, where conditional text made it differ from the site's */
+    bookText?: string;
     parent?: string;
     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. */
@@ -16,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

@@ -9,6 +9,7 @@ force-wrapped code listings, not executed.
 import { renderDocMarkdown } from './render.js';
 import { buildSlugMap } from './routing.js';
 import { buildNavTree } from './nav-tree.js';
+import { bookTextOf } from './book-target.js';
 // Clean book typography; force-wraps code so listings never overflow a page.
 export const DEFAULT_BOOK_CSS = `/* doc-system book stylesheet */
 html { font-size: 100%; }
@@ -107,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; }
@@ -118,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()
@@ -149,7 +152,7 @@ export function buildBookHtml(docs, opts) {
     const roots = buildNavTree(visible, slugMap);
     const css = opts.css ?? `${DEFAULT_BOOK_CSS}\n${PRINT_CSS}`;
     const chapters = flatten(roots)
-        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(node.doc.text))}\n</section>`)
+        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)))}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>
 <html lang="${opts.lang ?? 'en'}">
@@ -159,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/book-target.d.ts

@@ -14,6 +14,16 @@ export interface BookTargetDoc {
     /** one book, several books, or `'none'` */
     book?: string | string[];
     hidden?: boolean;
+    /** where this doc sits in a particular volume, keyed by `book` name */
+    placement?: Record<string, BookPlacement>;
+}
+export interface BookPlacement {
+    /** parent within this volume; `''` puts the doc at the top level */
+    parent?: string;
+    order?: number;
+    pin?: 'top' | 'bottom';
+    /** chapter title in this volume */
+    title?: string;
 }
 type SlugMap = Record<string, string>;
 /**
@@ -29,6 +39,15 @@ export declare function chain<T extends BookTargetDoc>(doc: T, docs: T[], slugMa
  * another, or bind into several (`["default", "appendices"]`).
  */
 export declare function resolveBooks<T extends BookTargetDoc>(doc: T, docs: T[], slugMap?: SlugMap): string[];
+/**
+ * The docs of one volume, arranged for it: each doc's `placement` for this book overlaid on
+ * its site `parent` / `order` / `pin` / `title`. Returns shallow copies; the site's
+ * arrangement is untouched.
+ */
+export declare function placeInBook<T extends BookTargetDoc & {
+    order?: number;
+    pin?: 'top' | 'bottom';
+}>(docs: T[], book: string): T[];
 /**
  * Hidden here or anywhere above.
  *
@@ -48,4 +67,9 @@ export declare function withoutHidden<T extends BookTargetDoc>(docs: T[], slugMa
 export declare function partitionByBook<T extends BookTargetDoc>(docs: T[], slugMap?: SlugMap): Map<string, T[]>;
 /** Named books only, in stable order — the extra volumes beside the default one. */
 export declare function namedBooks<T extends BookTargetDoc>(docs: T[], slugMap?: SlugMap): string[];
+export declare const bookTextOf: (doc: {
+    text: string;
+    bookText?: string;
+}) => string;
+export declare const mayHaveSingleSourceDirective: (text: string) => boolean;
 export {};

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

@@ -29,6 +29,11 @@ export const NO_BOOK = 'none';
  * `book: ["default", "field-guide"]` binds the doc into both.
  */
 export const DEFAULT_BOOK_NAME = 'default';
+const placementKey = (book) => book === DEFAULT_BOOK ? DEFAULT_BOOK_NAME : book;
+/** Volumes a doc's `placement` names, as book keys. */
+function placedBooks(doc) {
+    return Object.keys(doc.placement ?? {}).map((k) => k.trim().toLowerCase() === DEFAULT_BOOK_NAME ? DEFAULT_BOOK : k.trim());
+}
 /**
  * The doc itself, then each ancestor nearest-first. Stops at an unresolvable parent and
  * at a cycle, so a self-parented doc yields just itself rather than hanging.
@@ -86,14 +91,51 @@ function normalizeDeclaration(value) {
  * another, or bind into several (`["default", "appendices"]`).
  */
 export function resolveBooks(doc, docs, slugMap = {}) {
+    const placed = placedBooks(doc);
+    const withPlaced = (books) => [
+        ...books,
+        ...placed.filter((b) => !books.includes(b)),
+    ];
     for (const d of chain(doc, docs, slugMap)) {
         if (d.book === undefined)
             continue;
         const declared = normalizeDeclaration(d.book);
-        if (declared !== null)
-            return declared;
+        /*
+        An explicit `none` on the doc ITSELF still wins over its own placement: withholding is
+        the conservative reading of a contradiction, as it is for `["default", "none"]`. An
+        inherited `none` does not, or a chapter could never be placed into a book from a section
+        that is otherwise site-only.
+        */
+        if (declared !== null) {
+            if (!declared.length && d === doc)
+                return [];
+            return withPlaced(declared);
+        }
     }
-    return [DEFAULT_BOOK];
+    return withPlaced([DEFAULT_BOOK]);
+}
+/**
+ * The docs of one volume, arranged for it: each doc's `placement` for this book overlaid on
+ * its site `parent` / `order` / `pin` / `title`. Returns shallow copies; the site's
+ * arrangement is untouched.
+ */
+export function placeInBook(docs, book) {
+    const key = placementKey(book);
+    return docs.map((doc) => {
+        const entry = Object.entries(doc.placement ?? {}).find(([k]) => k.trim() === key ||
+            (book === DEFAULT_BOOK && k.trim().toLowerCase() === DEFAULT_BOOK_NAME));
+        if (!entry)
+            return doc;
+        // Only what a placement is documented to set: an entry is author-written JSON, and
+        // copying whatever it holds would let `"hidden": false` or `"text"` through.
+        const out = { ...doc };
+        for (const field of ['parent', 'order', 'pin', 'title']) {
+            const value = entry[1][field];
+            if (value !== undefined)
+                out[field] = value;
+        }
+        return out;
+    });
 }
 /**
  * Hidden here or anywhere above.
@@ -134,3 +176,20 @@ export function namedBooks(docs, slugMap = {}) {
         .filter((k) => k !== DEFAULT_BOOK)
         .sort();
 }
+/*
+The text a book binds for this doc.
+
+`bookText` exists only where conditional text made the book differ from the site
+(`site/single-source.ts`). Every book output asks here, so there are exactly two readers to
+get right (the ePub and print) and every other consumer keeps reading `text`.
+*/
+export const bookTextOf = (doc) => doc.bookText ?? doc.text;
+/*
+Might this source use an inset or conditional text?
+
+Deliberately loose: it also matches a directive that is only being SHOWN in a code fence.
+Its two callers want exactly that bias. The build uses it to skip docs that certainly have
+none before asking the parser, and the example editor uses it to refuse a save, where a
+false positive costs a refusal and a false negative writes an edit into the wrong block.
+*/
+export const mayHaveSingleSourceDirective = (text) => /<!--\s*\{[^\n]*"(inset|only|end)"\s*:/.test(text);

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/docs.d.ts

@@ -1,3 +1,4 @@
+import { type BookPlacement } from '../book-target.js';
 export interface Doc {
     text: string;
     title: string;
@@ -32,6 +33,18 @@ export interface Doc {
      * individual chapter can still divert, join several volumes, or opt out.
      */
     book?: string | string[];
+    /**
+     * Where this doc sits in a particular volume, when that differs from the site:
+     * `{ "language": { "parent": "for-programmers", "order": 20 } }`. Keyed by `book` name
+     * (`"default"` for the main volume); each entry may set `parent`, `order`, `pin` and
+     * `title`. Naming a volume here also binds the doc into it. The site nav is unaffected.
+     */
+    placement?: Record<string, BookPlacement>;
+    /**
+     * The text a book binds, set by the build only where `{"only": …}` conditional text made
+     * it differ from `text` (which is always what the site shows). Never author this.
+     */
+    bookText?: string;
     /**
      * Opt this page out of the reading column.
      *

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

@@ -99,6 +99,7 @@ import { truncationWarnings, formatTruncationWarnings, } from './truncated-doc.j
 import { pinnedSort } from '../nav-tree.js';
 import { buildSlugMap } from '../routing.js';
 import { withoutHidden } from '../book-target.js';
+import { assembleCorpus, isSingleSourceDirective } from './single-source.js';
 /**
  * Directories a doc site should not publish, excluded by default (tosijs-ui#153).
  *
@@ -234,7 +235,14 @@ function metadata(content, filePath) {
     And it must START A LINE. A metadata block is a standalone directive, so an inline mention
     in a sentence is prose — exactly the rule `/*#` doc blocks already follow.
     */
-    const source = scannable.match(/^[ \t]*<!--(\{.*\})-->|^[ \t]*\/\*(\{.*\})\*\//m);
+    /*
+    The first such block that is not a single-sourcing directive. An inset or an `only` is
+    spelled the same way, and a doc that opens with one and has no metadata of its own was
+    otherwise published carrying `inset` as a metadata field.
+    */
+    const source = [
+        ...scannable.matchAll(/^[ \t]*<!--(\{.*\})-->|^[ \t]*\/\*(\{.*\})\*\//gm),
+    ].find((m) => !isSingleSourceDirective(m[1] || m[2]));
     let data = {};
     if (source) {
         try {
@@ -297,7 +305,9 @@ function hasDocBlock(filePath) {
         return false; // unreadable is not our business here
     }
 }
-function findMarkdownFiles(paths, ignore, defaultIgnores = new Set()) {
+function findMarkdownFiles(paths, ignore, defaultIgnores = new Set(), 
+/** filled with the real path of every directory actually walked (see `assembleCorpus`) */
+walked) {
     const markdownFiles = [];
     const truncationFound = [];
     const withheld = [];
@@ -366,6 +376,12 @@ function findMarkdownFiles(paths, ignore, defaultIgnores = new Set()) {
             }
             return;
         }
+        try {
+            walked?.add(fs.realpathSync(dir));
+        }
+        catch {
+            // unreadable: nothing in it is scraped, so nothing in it is a fragment either
+        }
         files.forEach((file) => {
             // Skip scaffolding / working files (Jekyll-style `_`-prefix): a
             // `_template.md` or `_drafting-log.md` shouldn't leak into the corpus or
@@ -498,7 +514,8 @@ function findMarkdownFiles(paths, ignore, defaultIgnores = new Set()) {
 }
 export function extractDocs(options) {
     const { paths, ignore = ['node_modules', 'dist', 'build'], output } = options;
-    const found = findMarkdownFiles(paths, ignore, new Set(DEFAULT_DOC_IGNORES));
+    const walked = new Set();
+    const found = findMarkdownFiles(paths, ignore, new Set(DEFAULT_DOC_IGNORES), walked);
     /*
     Drop hidden docs HERE, before anything else sees them.
   
@@ -513,6 +530,21 @@ export function extractDocs(options) {
     rest of the pipeline is concerned. Descendants of a hidden doc go with it.
     */
     const docs = withoutHidden(found, buildSlugMap(found));
+    /*
+    Insets and conditional text are resolved HERE, for the same reason hidden docs are dropped
+    here: the corpus is the thing that ships, so anything assembled later is assembled by each
+    consumer separately. After the hidden filter, so a withheld doc cannot be published by
+    insetting it; a fragment that should not be a page is a `_`-prefixed file instead, and that
+    is the only kind of file an inset will read (see `fragmentPath`).
+    */
+    /*
+    A fragment may be read from a directory this extraction WALKED, and nowhere else. Not a
+    list of roots with the ignore rule applied again: the re-review found that second copy
+    disagreeing with the first within the hour (a file doc path such as `README.md` made the
+    whole project a root, and a path-form ignore was not honoured). The walk already decided
+    which directories are published, so ask it.
+    */
+    assembleCorpus(docs, { fragmentDirs: walked });
     if (output) {
         saveDocsJSON(docs, output);
     }

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;