tosijs-ui 1.16.9 → 1.16.11

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.16.11
+
+In-page links work, teaching examples show their test result, and "Download ePub" stops
+offering a book that was never built. `dist/iife.js` grows by 1.2 kB gzip.
+
+- **Headings have ids.** Every heading rendered from markdown now carries an `id`, so
+  `[text](#that-heading)` and `/page/#that-heading` go somewhere. Before this they were
+  links that did nothing, with no error anywhere. The id is the GitHub slug of the heading
+  text, with `-1`, `-2` for a repeat on the same page. Arriving at a heading scrolls it to
+  the top of the page.
+- **The build warns about an in-page link that matches nothing** on its page, naming the
+  page and the anchor. Under `strict: true` it fails the build.
+- **An inset's `#anchor` is matched as the heading's id**, the one the page carries:
+  `install.md#whats-new` now matches "What's new", and `#usage-1` names the second "Usage".
+  The 1.16.9 spelling still matches (`#what-s-new`).
+- **Inline views show the test result** (#219). An example opened with `{"view": "code"}` or
+  `{"view": "console"}` has one line under its preview: the count when its tests pass, the
+  first failure in red when they do not. It covers the `test` block and a `tjs` example's
+  inline tests, and clicking it opens the tab with the detail.
+- **An example in an inline view always runs its tests**, whatever the page's tests switch says (it is off
+  by default away from localhost). A `tjs` example with inline tests therefore transpiles in
+  the page when it is in an inline view on a deployed site, where it used to run from the
+  copy the build transpiled. Examples without a `view` option are unchanged.
+- **Inline views hide empty tabs.** `html`, `css` and `DOM tests` appear only when the
+  example has that block. The full-screen code view still shows them all.
+- **A long section title keeps its arrow.** In the sidebar, a section title that wraps no
+  longer leaves the disclosure triangle alone on a line above it.
+- **"Download ePub" follows the build** (#218). The settings menu links to the ePub at the
+  URL the build wrote, shows a submenu for a site with several volumes, and has no entry on
+  a site that builds none. It used to appear on every site and 404 on those. A hand-written
+  `<tosi-doc-system config>` without the new `ebooks` key keeps the old derived link.
+
+## 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-browser.js

@@ -978,9 +978,16 @@ export function createDocBrowser(options) {
     const scrollToHashExample = () => {
         if (memoryRouting)
             return;
-        const hash = location.hash.replace(/^#/, '');
+        let hash = location.hash.replace(/^#/, '');
         if (!hash)
             return;
+        try {
+            // A heading id can hold non-ASCII letters, which arrive percent-encoded.
+            hash = decodeURIComponent(hash);
+        }
+        catch {
+            // a stray % — look it up as written
+        }
         requestAnimationFrame(() => {
             let el = null;
             try {
@@ -991,6 +998,12 @@ export function createDocBrowser(options) {
             }
             if (!el)
                 return;
+            // A heading (they have ids as of 1.16.11) goes to the top, where a reader expects a
+            // section to start; an example is centred and flashed.
+            if (/^H[1-6]$/.test(el.tagName)) {
+                el.scrollIntoView({ block: 'start' });
+                return;
+            }
             el.scrollIntoView({ block: 'center', behavior: 'smooth' });
             el.classList.add('example-target');
             setTimeout(() => el && el.classList.remove('example-target'), 1600);

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-styles.js

@@ -632,6 +632,15 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'inline-block',
             // push the summary text in a bit less than a normal doc-link
             paddingLeft: 'calc(var(--spacing) * 0.5)',
+            /*
+            Room for the disclosure triangle on the same line (#219). An inline-block as wide as
+            its text does not fit beside the marker once the title is long, so the whole link
+            dropped to the next line and left the triangle alone on a row of its own, which reads
+            as an empty nav entry. Capped, it stays beside the triangle and wraps inside itself.
+            */
+            boxSizing: 'border-box',
+            maxWidth: 'calc(100% - 1.5em)',
+            verticalAlign: 'top',
         },
         // Declarative header link list — shown for no-JS, removed on hydration.
         '.doc-navbar': {

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

@@ -2,6 +2,23 @@ import { ElementCreator } from 'tosijs';
 import * as tosijsModule from 'tosijs';
 import { Doc } from '../doc-browser.js';
 import './css-var-editor.js';
+export interface Ebook {
+    title: string;
+    url: string;
+}
+/**
+ * The settings menu's "Download ePub" entry, or `null` for none.
+ *
+ * The item used to be unconditional and its URL derived from the project name, so a site
+ * that built no ePub (the default) shipped a menu item that 404s, and a multi-volume site
+ * or one with `basePath` or `epub.title` linked to a file nothing wrote (#218). The site
+ * build now bakes the list of volumes it makes into the page config:
+ *
+ *   - a list   → one item (or, for several volumes, a submenu), at the build's own URLs
+ *   - `[]`     → the site makes no ePub: no item
+ *   - no key   → a hand-written `config` that predates this: the old derived link, unchanged
+ */
+export declare function epubMenuItem(ebooks: Ebook[] | undefined, legacyUrl: string): Record<string, unknown> | null;
 export declare const CORPUS_ATTEMPTS = 3;
 export declare function fetchCorpus(url: string): Promise<Doc[]>;
 declare const TosiDocSystem_base: tosijsModule.WithAttributes<{

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';
@@ -71,6 +71,48 @@ import { i18n, setLocale, initLocalization } from '../localize.js';
 // tweaker under an example. Part of the doc-system, NOT re-exported from tosijs-ui.
 import './css-var-editor.js';
 const { button, div } = elements;
+const download = (url) => () => {
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = '';
+    link.click();
+};
+/**
+ * The settings menu's "Download ePub" entry, or `null` for none.
+ *
+ * The item used to be unconditional and its URL derived from the project name, so a site
+ * that built no ePub (the default) shipped a menu item that 404s, and a multi-volume site
+ * or one with `basePath` or `epub.title` linked to a file nothing wrote (#218). The site
+ * build now bakes the list of volumes it makes into the page config:
+ *
+ *   - a list   → one item (or, for several volumes, a submenu), at the build's own URLs
+ *   - `[]`     → the site makes no ePub: no item
+ *   - no key   → a hand-written `config` that predates this: the old derived link, unchanged
+ */
+export function epubMenuItem(ebooks, legacyUrl) {
+    if (!Array.isArray(ebooks))
+        return {
+            caption: 'Download ePub',
+            icon: 'book',
+            action: download(legacyUrl),
+        };
+    if (ebooks.length === 0)
+        return null;
+    if (ebooks.length === 1)
+        return {
+            caption: 'Download ePub',
+            icon: 'book',
+            action: download(ebooks[0].url),
+        };
+    return {
+        caption: 'Download ePub',
+        icon: 'book',
+        menuItems: ebooks.map((book) => ({
+            caption: book.title,
+            action: download(book.url),
+        })),
+    };
+}
 const PREFS_KEY = 'tosi-doc-system-prefs';
 /*
 Fetch the corpus, retrying a TRANSIENT failure — without becoming the reason it stays down.
@@ -288,8 +330,13 @@ export class TosiDocSystem extends withAttributes({
                 const menuItems = [];
                 // Print / ePub of the whole corpus, before a separator + the prefs.
                 let projectName = '';
+                let bookVolumes;
+                let ebooks;
                 try {
-                    projectName = JSON.parse(this.config || '{}').projectName || '';
+                    const parsed = JSON.parse(this.config || '{}');
+                    projectName = parsed.projectName || '';
+                    bookVolumes = parsed.bookVolumes || undefined;
+                    ebooks = parsed.ebooks;
                 }
                 catch {
                     // ignore — fall through to document.title
@@ -298,12 +345,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 +370,7 @@ export class TosiDocSystem extends withAttributes({
                         */
                         win.document.write(buildBookHtml(this.corpus, {
                             title: bookTitle,
+                            cover: bookCover,
                             autoPrint: false,
                         }));
                         win.document.close();
@@ -337,16 +389,9 @@ export class TosiDocSystem extends withAttributes({
                         void printWhenReady(win, () => highlightBlocks(win.document, { policy: 'none' }));
                     },
                 });
-                menuItems.push({
-                    caption: 'Download ePub',
-                    icon: 'book',
-                    action: () => {
-                        const link = document.createElement('a');
-                        link.href = `/${slugify(bookTitle)}.epub`;
-                        link.download = '';
-                        link.click();
-                    },
-                });
+                const epubItem = epubMenuItem(ebooks, `/${slugify(bookTitle)}.epub`);
+                if (epubItem)
+                    menuItems.push(epubItem);
                 menuItems.push(null);
                 const localeOptions = i18n.localeOptions.value || [];
                 if (localeOptions.length > 1) {

package/dist/doc-system/heading-id.d.ts

@@ -0,0 +1,21 @@
+/** The text a reader sees in a heading: marked's inline tokens with the markup dropped. */
+export declare function headingText(token: any): string;
+/** GitHub-flavoured slug of some heading text. May be empty (a heading of punctuation). */
+export declare function slugOfHeadingText(text: string): string;
+/** The slug of a marked heading token, before any `-1` de-duplication. */
+export declare const headingSlug: (token: any) => string;
+/**
+ * Hands out ids for one page, suffixing a repeat the way GitHub does.
+ *
+ * It knows about headings and nothing else. In particular it does NOT keep headings out of
+ * `example-N`, the ids live examples get in the browser: a reservation here was tried for
+ * 1.16.11 and made `next('example')` loop forever on its second call, because every suffix
+ * of `example` is `example-N`. A heading "Example 2" is `example-2`, as on GitHub. On a page
+ * that also has a second live example the two share that id, and a link reaches whichever
+ * comes first in the document (a known overlap, not checked by the build).
+ */
+export declare class HeadingIds {
+    private seen;
+    /** The id for the next heading with this slug, or '' when the slug is empty. */
+    next(slug: string): string;
+}

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

@@ -0,0 +1,62 @@
+/*
+THE rule for a heading's id, build and client alike.
+
+Headings rendered with no `id`, so `[text](#some-heading)` was a live-looking link that did
+nothing, with no error anywhere (board #3178). The slug is the GitHub-flavoured one, because
+that is what an author writing an in-page link expects and what the same file gets when it is
+read on GitHub: lowercase, every character that is not a letter, a number, a space, `-` or
+`_` dropped, spaces to `-`. A repeat on one page gets `-1`, `-2`, ….
+
+The renderer stamps ids with it and an inset's `#anchor` (single-source.ts) is matched with
+it. Do not write a second copy: an anchor that the build accepts and the page does not carry
+is exactly the silent failure this exists to end.
+*/
+/** The text a reader sees in a heading: marked's inline tokens with the markup dropped. */
+export function headingText(token) {
+    if (Array.isArray(token.tokens) && token.type !== 'codespan')
+        return token.tokens.map(headingText).join('');
+    if (token.type === 'html')
+        return '';
+    if (token.type === 'br')
+        return ' ';
+    return String(token.text ?? '');
+}
+/** GitHub-flavoured slug of some heading text. May be empty (a heading of punctuation). */
+export function slugOfHeadingText(text) {
+    return text
+        .replace(/&(?:#\d+|#x[\da-f]+|[a-z][a-z\d]*);/gi, '') // an entity is not its name
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+/** The slug of a marked heading token, before any `-1` de-duplication. */
+export const headingSlug = (token) => slugOfHeadingText(headingText(token));
+/**
+ * Hands out ids for one page, suffixing a repeat the way GitHub does.
+ *
+ * It knows about headings and nothing else. In particular it does NOT keep headings out of
+ * `example-N`, the ids live examples get in the browser: a reservation here was tried for
+ * 1.16.11 and made `next('example')` loop forever on its second call, because every suffix
+ * of `example` is `example-N`. A heading "Example 2" is `example-2`, as on GitHub. On a page
+ * that also has a second live example the two share that id, and a link reaches whichever
+ * comes first in the document (a known overlap, not checked by the build).
+ */
+export class HeadingIds {
+    seen = new Map();
+    /** The id for the next heading with this slug, or '' when the slug is empty. */
+    next(slug) {
+        if (!slug)
+            return '';
+        let id = slug;
+        // A suffixed id can itself collide with an earlier literal heading ("Usage 1"). Each
+        // pass raises the counter, and `seen` is finite, so this ends.
+        while (this.seen.has(id)) {
+            const n = (this.seen.get(slug) ?? 0) + 1;
+            this.seen.set(slug, n);
+            id = `${slug}-${n}`;
+        }
+        this.seen.set(id, this.seen.get(id) ?? 0);
+        return id;
+    }
+}

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/render.js

@@ -10,11 +10,20 @@ give that example a stable anchor — see the docMarked renderer below.
 */
 import { Marked, Renderer } from 'marked';
 import { parseFenceInfo } from './example-policy.js';
+import { HeadingIds, headingSlug } from './heading-id.js';
 const baseRenderer = new Renderer();
 let currentBakes;
+// Per-parse, reset in `preprocess` below (same pattern as the footnote state).
+let headingIds = new HeadingIds();
 const docMarked = new Marked();
 docMarked.use({
     renderer: {
+        // Every heading gets an id, so `[text](#that-heading)` resolves — see heading-id.ts.
+        heading(token) {
+            const id = headingIds.next(headingSlug(token));
+            const inner = this.parser.parseInline(token.tokens);
+            return `<h${token.depth}${id ? ` id="${escapeAttr(id)}"` : ''}>${inner}</h${token.depth}>\n`;
+        },
         code(token) {
             // Fence info grammar: `<lang>` optionally with a `:<mode>` and/or `#<id>` in
             // EITHER order — `js`, `css#anchor`, `js:iframe`, `ts:ide#demo`, `ts#demo:ide`.
@@ -84,6 +93,7 @@ docMarked.use({
         preprocess(markdown) {
             footnoteDefs = new Map();
             footnoteOrder = [];
+            headingIds = new HeadingIds();
             return markdown;
         },
         postprocess(html) {

package/dist/doc-system/site/build-warnings.d.ts

@@ -21,3 +21,4 @@ export declare function misconfigured(strict: boolean | undefined, message: stri
 export declare function liveFenceLanguages(docs: Array<{
     text?: string;
 }>, policy?: ExamplePolicy): Set<string>;
+export declare function deadInPageAnchors(html: string): string[];

package/dist/doc-system/site/build-warnings.js

@@ -43,3 +43,64 @@ export function liveFenceLanguages(docs, policy = 'auto') {
     }
     return langs;
 }
+const unescapeAttr = (s) => s
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+/**
+ * The in-page links (`href="#…"`) in a RENDERED page that point at no id on it.
+ *
+ * A dead in-page anchor is the one broken link a reader cannot tell from a working one: it
+ * is styled as a link, it does nothing, and nothing reports it (board #3178). Asked of the
+ * rendered HTML and not of the markdown, so the ids are the ones the page really carries
+ * (`renderDocMarkdown`, THE renderer) and no second copy of the heading-id rule exists here.
+ *
+ * Not reported, because they are not in-page anchors or resolve only in the browser:
+ * `#/route` and `#!…` (hash routers), a bare `#`, `#top`, and `#example-N` (live examples
+ * are numbered when the page hydrates). A fence's own `#id` is on the rendered page and is
+ * checked like any other id.
+ *
+ * Tags are read with their attributes in any order and any quoting. What it cannot see is
+ * an id that only exists once a script has run; such a link is reported.
+ */
+// One HTML start tag, attributes and all. Quoted values may hold `>`, which is why this is
+// not `<[^>]*>`.
+const START_TAG = /<([a-z][a-z0-9-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*\/?>/gi;
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+export function deadInPageAnchors(html) {
+    const ids = new Set();
+    const links = [];
+    for (const tag of html.matchAll(START_TAG)) {
+        const name = tag[1].toLowerCase();
+        for (const attr of tag[2].matchAll(ATTRIBUTE)) {
+            const key = attr[1].toLowerCase();
+            const value = unescapeAttr(attr[2] ?? attr[3] ?? attr[4] ?? '');
+            if (key === 'id' || key === 'data-example-id')
+                ids.add(value);
+            // `name` is an anchor target on <a> only; on a form field it is a field name.
+            else if (key === 'name' && name === 'a')
+                ids.add(value);
+            else if (key === 'href' && name === 'a' && value.startsWith('#'))
+                links.push(value.slice(1));
+        }
+    }
+    const dead = new Set();
+    for (let target of links) {
+        try {
+            target = decodeURIComponent(target);
+        }
+        catch {
+            // a stray % — compare it as written
+        }
+        if (!target ||
+            target === 'top' ||
+            /^[/!]/.test(target) ||
+            /^example-\d+$/.test(target) ||
+            ids.has(target))
+            continue;
+        dead.add(target);
+    }
+    return [...dead];
+}

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;