tosijs-ui 1.16.36 → 1.16.38

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 1.16.38
+
+- **The ePub carries its images (#3519).** Every local image went into the book as a site path
+  that does not exist inside the zip, and no image file was copied, so every figure was a broken
+  image in every reader. It never showed in a library's book, whose images are remote README
+  badges; it made an illustrated book impossible. A local image is now copied into the ePub and
+  listed in its manifest once, however many chapters use it. A `/images/fig.jpg` path (with or
+  without `basePath`) is found in the built site, where your `staticDirs` are; a relative path is
+  resolved against the page's URL, as on the site. That covers `<img src>` and `srcset` in
+  markdown and raw HTML; `<picture><source>` and SVG `<image>` are not bound yet. Remote and
+  `data:` images are unchanged. One that is missing, outside the site, or not
+  JPEG/PNG/GIF/SVG/WebP is listed in a warning, and fails a `strict` build, including an image
+  only your host serves (a CDN rewrite, a proxied path): the page shows it, the book cannot.
+- **A book with images is bigger, and so is its rebuild.** The ePub now carries every figure,
+  and it is rebuilt on every dev-server rebuild; already-compressed images are stored, not
+  deflated again, so the cost is copying them. If you commit your output folder, the ePub in it
+  grows by the size of your images.
+
+## 1.16.37
+
+Doc-site test running, as a developer meets it. On a deployed site, tests still start off; the
+only difference there is how a passing run looks to a reader who turns them on.
+
+- **Safari no longer stalls the background test run.** The runner loads each page with tests in
+  a hidden frame, and parked that frame off-screen; WebKit gives an off-screen frame no
+  animation frames, tosijs renders on them, so every page waited out its 45-second deadline and
+  the header read "Running 0" for the whole run. The frame now sits inside the viewport, clipped
+  so nothing paints. The doc-test gate runs in WebKit for the first time, and passes.
+- **Over the tunnel, tests run as they do on localhost.** They started off there, and turned on
+  ran only the page on screen; the dev server now marks the pages it serves, so any page it
+  served starts with tests on and runs the whole site in the background. That is every visitor
+  to a dev server, on the LAN or through a tunnel link, with or without an edit session: a
+  preview link opened on a phone runs every page's tests in hidden frames. Turning tests off
+  from the header menu is remembered per browser. A deployed site has no mark and still
+  defaults to off.
+- **A pass no longer blanks the header's test widget.** It faded to nothing and left an empty
+  rectangle in the bar. It now turns grey and then translucent, all as a CSS filter over the
+  pass colour, and stays readable and clickable. Floating over a page with no header it still
+  fades out.
+
 ## 1.16.36
 
 One additive site option. Nothing changes for a site that does not set it.

package/dist/doc-browser.js

@@ -119,6 +119,7 @@ import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
 import { LAN_REFUSAL_ADVICE } from './live-example/source-access.js';
+import { servedForDevelopment } from './live-example/dev-served.js';
 /*
 Does this doc contain a REAL ` ```test ` block, as opposed to mentioning one?
 
@@ -186,6 +187,18 @@ const testIndicatorStyleSpec = {
         '70%': { opacity: '1', transform: 'scale(1.1)' },
         '100%': { opacity: '0', transform: 'scale(0.9)', pointerEvents: 'none' },
     },
+    /*
+    A pass in the header settles into a muted, monochrome badge rather than fading out. Faded,
+    it left an empty rectangle in the bar (the widget keeps its box), and the result was gone
+    for anyone who looked a moment late. Muted, it reads as "nothing to see" and stays a button.
+    All of it is a filter over the pass colour, never a new colour. Grey first, then faded: fading
+    while still green put a washed-out green on the header's colour.
+    */
+    '@keyframes test-settle': {
+        '0%, 40%': { filter: 'grayscale(0) opacity(1)' },
+        '55%': { filter: 'grayscale(1) opacity(1)' },
+        '100%': { filter: 'grayscale(1) opacity(0.55)' },
+    },
     // Hide when tests disabled
     'body:not(.tests-enabled) .doc-link::after, body:not(.tests-enabled) .test-widget': {
         display: 'none !important',
@@ -240,8 +253,19 @@ const testIndicatorStyleSpec = {
     '.test-widget.-passed': {
         _testBg: testColor.pass,
         _testFg: testTextColor.pass,
+        animation: 'test-settle 3s ease-out forwards',
+    },
+    // Floating over the page (no header), it still gets out of the way: there is no gap to leave.
+    '.test-widget.-floating.-passed': {
         animation: 'test-fade 3s ease-out forwards',
     },
+    '@media (prefers-reduced-motion: reduce)': {
+        '.test-widget.-passed': {
+            animation: 'none',
+            filter: 'grayscale(1) opacity(0.55)',
+        },
+        '.test-widget.-floating.-passed': { opacity: '0', pointerEvents: 'none' },
+    },
     '.test-widget.-failed': {
         _testBg: testColor.fail,
         _testFg: testTextColor.fail,
@@ -1762,7 +1786,7 @@ export function createDocBrowser(options) {
             else {
                 testWidget.classList.add('-passed');
                 testWidget.classList.remove('-failed');
-                testWidget.hidden = false; // Show briefly before fade
+                testWidget.hidden = false; // settles into a muted badge (see `.test-widget.-passed`)
             }
         }
         updateTestWidgetDisplay();
@@ -1938,9 +1962,15 @@ export function createDocBrowser(options) {
         const currentFilename = String(app.currentDoc.filename);
         /*
         Create a hidden iframe that loads the full page. Keep a real layout size — layout-dependent
-        example tests need one — but park it off-screen rather than rely on opacity:0 over the
-        visible page: Chromium (and haltija on top of it) still composites a 0-opacity layer at 0,0,
-        which flashes as the frame navigates page to page.
+        example tests need one — and hide it with a clip that leaves nothing to paint, not opacity:
+        Chromium (and haltija on top of it) still composites a 0-opacity layer at 0,0, which flashes
+        as the frame navigates page to page.
+    
+        INSIDE the viewport, though. It used to be parked at left:-10000px, and WebKit throttles a
+        frame outside the viewport: its animation frames never came, tosijs renders on animation
+        frames, so every page sat until its 45s deadline and Safari showed "Running 0" for the whole
+        run. That was the "WebKit's iframe runner never signals" of the e2e lane, and it reached
+        readers once the tunnel ran tests in the background.
     
         THE SIZE IS OVERRIDABLE, because 800x600 was the only width the inline tier had ever run at.
         A doc-system layout regression at phone width shipped in 1.12.3 and was found by a reader,
@@ -1959,7 +1989,7 @@ export function createDocBrowser(options) {
         const vpWidth = Number(vp?.width) > 0 ? Number(vp?.width) : 800;
         const vpHeight = Number(vp?.height) > 0 ? Number(vp?.height) : 600;
         const testFrame = document.createElement('iframe');
-        testFrame.style.cssText = `position: fixed; left: -10000px; top: 0; width: ${vpWidth}px; height: ${vpHeight}px; opacity: 0; pointer-events: none;`;
+        testFrame.style.cssText = `position: fixed; left: 0; top: 0; z-index: -1; clip-path: inset(100%); width: ${vpWidth}px; height: ${vpHeight}px; opacity: 0; pointer-events: none;`;
         document.body.appendChild(testFrame);
         // Listen for test results posted from the iframe
         const messageHandler = (event) => {
@@ -2032,11 +2062,12 @@ export function createDocBrowser(options) {
             void settleCurrentPage(currentFilename);
         }
     };
-    // Run background tests when enabled (initially or when toggled on)
+    // Run background tests when enabled (initially or when toggled on). Every page where a
+    // developer is looking, the tunnel included; elsewhere only the page on screen.
     const startBackgroundTests = () => {
         if (!testManager.enabled.value)
             return;
-        if (isLocalhost) {
+        if (servedForDevelopment()) {
             setTimeout(runBackgroundTests, 1000);
         }
         else {

package/dist/doc-system/site/dev-server.d.ts

@@ -31,6 +31,11 @@ import { isLoopbackAddressForAuth as isLoopbackAddress } from './dev-auth.js';
  *
  * `root + sep` rather than a bare `startsWith`, or `/srv/docs-evil` counts as inside `/srv/docs`.
  */
+/**
+ * Put `snippet` before every script in `html`: just inside `<head>`, or else just after the
+ * doctype. Never before the doctype, which would put the page in quirks mode.
+ */
+export declare function injectFirst(html: string, snippet: string): string;
 export declare function isUnderRoot(root: string, candidate: string): boolean;
 export declare function resolveWatchPaths(config: {
     docPaths?: string[];

package/dist/doc-system/site/dev-server.js

@@ -28,6 +28,7 @@ import { assertSecretNotServed, ensureSessionSecret, readSessionSecret, sessionS
 import { revocationList, startRevocationSweep } from './device-revocation.js';
 import { resolveDataStore, resolveDataFile, dataContentProblem, listDataFiles, saveDataFile, dataHistory, readDataAt, isGitWorkTree, } from './data-store.js';
 import { SOURCE_ACCESS_HEADER, SOURCE_ENDPOINT_SNIPPET, } from '../../live-example/source-access.js';
+import { DEV_SERVER_SNIPPET } from '../../live-example/dev-served.js';
 /**
  * Every path the dev server watches for changes.
  *
@@ -59,6 +60,20 @@ import { SOURCE_ACCESS_HEADER, SOURCE_ENDPOINT_SNIPPET, } from '../../live-examp
  *
  * `root + sep` rather than a bare `startsWith`, or `/srv/docs-evil` counts as inside `/srv/docs`.
  */
+/**
+ * Put `snippet` before every script in `html`: just inside `<head>`, or else just after the
+ * doctype. Never before the doctype, which would put the page in quirks mode.
+ */
+export function injectFirst(html, snippet) {
+    const head = /<head(\s[^>]*)?>/i.exec(html);
+    if (head) {
+        const at = head.index + head[0].length;
+        return html.slice(0, at) + snippet + html.slice(at);
+    }
+    const doctype = /^\s*<!doctype[^>]*>/i.exec(html);
+    const at = doctype ? doctype[0].length : 0;
+    return html.slice(0, at) + snippet + html.slice(at);
+}
 export function isUnderRoot(root, candidate) {
     const base = path.resolve(root);
     const target = path.resolve(candidate);
@@ -1373,12 +1388,19 @@ export async function devServer(config, opts = {}) {
             // deployed static site, which has none, is never asked.
             (config.editableSources ? SOURCE_ENDPOINT_SNIPPET : '');
         const encoding = negotiateEncoding(request?.headers.get('accept-encoding') ?? null);
-        if ((extras || asRoot) && filePath.endsWith('.html')) {
+        if (filePath.endsWith('.html')) {
             const read = await Bun.file(filePath).text();
             const html = asRoot ? rootRelativeUrls(read) : read;
-            const injected = html.includes('</body>')
+            const withExtras = html.includes('</body>')
                 ? html.replace('</body>', `${extras}</body>`)
                 : html + extras;
+            /*
+            Tests on by default, every page, for whoever is looking through the dev server (the tunnel
+            included); see dev-served.ts. FIRST in <head>, unlike the extras: it is read when the
+            bundle evaluates, and on the iife path that is a classic script, which runs as it is
+            parsed, before anything at the end of <body> exists.
+            */
+            const injected = injectFirst(withExtras, DEV_SERVER_SNIPPET);
             // Injected HTML is built per request, so it is compressed but never cached — the
             // cache key would have to include the injected extras, and HTML is small anyway.
             const body = encoding

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

@@ -12,7 +12,7 @@ the Bun.build note in orchestrator.ts.
 
 Build-time only. Never import this from browser code.
 */
-import { buildEpub } from './epub.js';
+import { buildEpub, EpubImageError, EPUB_IMAGE_EXIT } from './epub.js';
 import { BUILT_IN_DIALECTS, normalizeDialectNames, registerLiveLanguage, } from '../example-policy.js';
 const payloadPath = process.argv[2];
 if (!payloadPath) {
@@ -26,4 +26,15 @@ for (const name of normalizeDialectNames(config.dialects)) {
     if (!BUILT_IN_DIALECTS.has(name))
         registerLiveLanguage(name);
 }
-await buildEpub(config, opts ?? {});
+try {
+    await buildEpub(config, opts ?? {});
+}
+catch (error) {
+    // A distinct exit code, so the parent fails a `strict` build on THIS and still only warns
+    // about the ePub's other failures (it is otherwise a side artifact).
+    if (error instanceof EpubImageError) {
+        console.error(error.message);
+        process.exit(EPUB_IMAGE_EXIT);
+    }
+    throw error;
+}

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

@@ -79,3 +79,9 @@ export declare function renderEpubDownloads(text: string, volumes: EpubVolume[])
  * `undefined` when it should not: no ePub is built, or `epub.printCover` is `false`.
  */
 export declare function printCoverManifestUrl(config: VolumeNamingConfig): string | undefined;
+/**
+ * epub-cli's exit code when a local image cannot be bound into the book. The build fails on it
+ * under `strict` and only warns otherwise. Here, not in epub.ts, so the orchestrator can read it
+ * without importing the ePub builder it runs in a child.
+ */
+export declare const EPUB_IMAGE_EXIT = 3;

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

@@ -139,3 +139,9 @@ export function printCoverManifestUrl(config) {
         return undefined;
     return `${(config.basePath ?? '/').replace(/\/+$/, '')}/${VOLUME_MANIFEST}`;
 }
+/**
+ * epub-cli's exit code when a local image cannot be bound into the book. The build fails on it
+ * under `strict` and only warns otherwise. Here, not in epub.ts, so the orchestrator can read it
+ * without importing the ePub builder it runs in a child.
+ */
+export const EPUB_IMAGE_EXIT = 3;

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

@@ -1,3 +1,4 @@
+import { EPUB_IMAGE_EXIT } from './epub-volumes.js';
 import type { SiteConfig } from './site-config.js';
 import { DEFAULT_BOOK_CSS, stripDocMeta } from '../book-html.js';
 export { DEFAULT_BOOK_CSS, stripDocMeta };
@@ -75,8 +76,33 @@ export declare function toXhtml(html: string): string;
  * untouched. `bookFiles` maps in-book slug → chapter filename.
  */
 export declare function rewriteInBookLinks(html: string, bookFiles: Map<string, string>, slugMap: Record<string, string>, basePath?: string): string;
+export { EPUB_IMAGE_EXIT };
+/** Thrown by buildEpub under `strict` when a local image cannot be bound into the book. */
+export declare class EpubImageError extends Error {
+    name: string;
+}
+/** An image bound into the book: where it lives in OEBPS, and where it came from. */
+export interface BookImage {
+    /** path inside OEBPS, e.g. `images/figs/a.jpg` */
+    file: string;
+    mediaType: string;
+    /** absolute path of the source file */
+    source: string;
+}
+/**
+ * Rewrite the local images in `html` (`<img src>` and each `srcset` candidate) to book-local
+ * paths, registering each file in `images` (keyed by absolute source path, so a figure used
+ * twice is bound once). Root-absolute srcs have `basePath` stripped; relative ones resolve
+ * against `pagePath`, the page's own site path. Local srcs that cannot be bound are added to
+ * `unbound` and left untouched. Not handled: `<picture><source>` and SVG `<image>`.
+ */
+export declare function embedLocalImages(html: string, webRoot: string, basePath: string | undefined, images: Map<string, BookImage>, unbound?: Set<string>, pagePath?: string): string;
 /**
  * Build an EPUB 3 book from the extracted corpus. Returns the output path.
  */
 export declare function versionAnchoredDate(version: string, override?: string): string;
+/**
+ * Build the ePub for `config`'s corpus and return its path. Under `config.strict`, throws
+ * {@link EpubImageError} when a local image cannot be bound into the book.
+ */
 export declare function buildEpub(config: SiteConfig, opts?: BuildEpubOptions): Promise<string>;

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

@@ -21,7 +21,7 @@ import { highlightHtml } from '../highlight.js';
 import { buildSlugMap, pathForSlug, resolveParent, slugForPath, withBase, wikilinkTargets, } from '../routing.js';
 import { buildNavTree } from '../nav-tree.js';
 import { partitionByBook, placeInBook, bookTextOf, DEFAULT_BOOK, } from '../book-target.js';
-import { COVER_MEDIA_TYPES, coverStem, epubVolumeIdentity, } from './epub-volumes.js';
+import { COVER_MEDIA_TYPES, EPUB_IMAGE_EXIT, 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';
@@ -216,6 +216,145 @@ export function rewriteInBookLinks(html, bookFiles, slugMap, basePath) {
         return file ? `href="${file}${hash}"` : match;
     });
 }
+/*
+Images bound INTO the book.
+
+A chapter's `<img src="/images/fig.jpg">` used to ship as-is, pointing at a site path that
+does not exist inside the zip: the book carried no image files at all, so every local
+figure was a broken image in every reader. Fine for a library whose only images are remote
+README badges; fatal for a manual whose content IS its figures.
+
+A root-absolute src (`/images/fig.jpg`) is resolved against the built web root — the output
+dir, which already holds the copied `staticDirs` — so the book embeds exactly the file the page
+shows. basePath is stripped first, as for links. A relative src (`img/fig.jpg`) is first
+resolved against the page's own path (`/slug/`), as a browser on the site resolves it, so it
+binds the same file the page shows. Remote and `data:` srcs are left alone. A local image that
+is missing, escapes the web root, or is not an EPUB core image type is left as-is and reported,
+because a figure that silently vanishes from a book is worse than one that visibly fails; under
+`strict` it fails the build.
+*/
+export { EPUB_IMAGE_EXIT };
+/** Thrown by buildEpub under `strict` when a local image cannot be bound into the book. */
+export class EpubImageError extends Error {
+    name = 'EpubImageError';
+}
+/** EPUB 3 core media types for images, by extension. */
+const IMAGE_MEDIA_TYPES = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+};
+/** The five entities an attribute value can carry, and numeric references. */
+function decodeAttr(value) {
+    return value.replace(/&(?:#(\d+)|#x([\da-f]+)|(amp|lt|gt|quot|apos));/gi, (match, dec, hex, name) => dec
+        ? String.fromCodePoint(Number(dec))
+        : hex
+            ? String.fromCodePoint(parseInt(hex, 16))
+            : { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }[name.toLowerCase()] ?? match);
+}
+// An `<img>` tag, with `>` allowed inside quoted attribute values (`alt="a > b"`).
+const IMG_TAG = /<img\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+// One attribute of a tag: name, then a double-, single- or un-quoted value.
+const ATTRIBUTE = /(\s)([^\s=>/"']+)(\s*=\s*)(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g;
+/**
+ * Rewrite the local images in `html` (`<img src>` and each `srcset` candidate) to book-local
+ * paths, registering each file in `images` (keyed by absolute source path, so a figure used
+ * twice is bound once). Root-absolute srcs have `basePath` stripped; relative ones resolve
+ * against `pagePath`, the page's own site path. Local srcs that cannot be bound are added to
+ * `unbound` and left untouched. Not handled: `<picture><source>` and SVG `<image>`.
+ */
+export function embedLocalImages(html, webRoot, basePath, images, unbound = new Set(), 
+// the page's own site path, for relative srcs; '/' for the root page
+pagePath = '/') {
+    const root = path.resolve(webRoot);
+    const bp = basePath && basePath !== '/' ? basePath.replace(/\/$/, '') : '';
+    // the book-local path for one src, or null to leave it as it is
+    const bind = (src) => {
+        // remote (any scheme, or protocol-relative) and data: stay as they are
+        if (!src || /^[a-z][a-z\d+.-]*:/i.test(src) || src.startsWith('//'))
+            return null;
+        const fragment = /#.*$/.exec(src)?.[0] ?? '';
+        let p = src.replace(/[?#].*$/, '');
+        if (!p)
+            return null;
+        if (p.startsWith('/')) {
+            if (bp && (p === bp || p.startsWith(bp + '/')))
+                p = p.slice(bp.length);
+        }
+        else {
+            // keep the raw percent-encoding: decoded once below, like a root-absolute src
+            p = new URL(p, `https://book.invalid${pagePath}`).pathname;
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(p);
+        }
+        catch {
+            decoded = p;
+        }
+        const source = path.join(root, decoded);
+        const mediaType = IMAGE_MEDIA_TYPES[path.extname(source).toLowerCase()];
+        if (!source.startsWith(root + path.sep) ||
+            !mediaType ||
+            !fs.existsSync(source) ||
+            !fs.statSync(source).isFile()) {
+            unbound.add(src);
+            return null;
+        }
+        let image = images.get(source);
+        if (!image) {
+            const rel = path
+                .relative(root, source)
+                .split(path.sep)
+                .map((seg) => seg.replace(/[^\w.-]/g, '_'))
+                .join('/');
+            // Sanitizing can make two sources collide (`a b.jpg`, `a_b.jpg`); keep both.
+            const taken = new Set([...images.values()].map((i) => i.file));
+            let file = `images/${rel}`;
+            const ext = path.extname(file);
+            for (let n = 2; taken.has(file); n += 1) {
+                file = `images/${rel.slice(0, rel.length - ext.length)}-${n}${ext}`;
+            }
+            image = { file, mediaType, source };
+            images.set(source, image);
+        }
+        // A fragment names a part of the file (an SVG sprite), so it travels with it.
+        return image.file + fragment;
+    };
+    return html.replace(IMG_TAG, (tag) => tag.replace(ATTRIBUTE, (match, space, name, eq, dq, sq, bare) => {
+        const attr = name.toLowerCase();
+        if (attr !== 'src' && attr !== 'srcset')
+            return match;
+        const raw = dq ?? sq ?? bare ?? '';
+        const quote = dq !== undefined ? '"' : sq !== undefined ? "'" : '"';
+        const value = decodeAttr(raw);
+        let rewritten;
+        if (attr === 'src') {
+            rewritten = bind(value);
+        }
+        else {
+            // `url 2x, url 640w`: bind each candidate, keep its descriptor
+            let changed = false;
+            const candidates = value.split(',').map((candidate) => {
+                const [url, ...descriptor] = candidate.trim().split(/\s+/);
+                const bound = bind(url);
+                if (bound === null)
+                    return candidate.trim();
+                changed = true;
+                return [bound, ...descriptor].join(' ');
+            });
+            rewritten = changed ? candidates.join(', ') : null;
+        }
+        // decoded above, so escaped again: a fragment or an untouched srcset candidate may
+        // carry `&` or a quote
+        return rewritten === null
+            ? match
+            : `${space}${name}${eq}${quote}${escapeXml(rewritten)}${quote}`;
+    }));
+}
 // `pageUrl` is the live-site URL of THIS doc (already including baseUrl, basePath
 // and the correct root for README → '/'); each example link just appends `#id`.
 function injectExampleLinks(doc, pageUrl, policy = 'auto') {
@@ -267,7 +406,7 @@ function containerXml() {
 </container>
 `;
 }
-function packageOpf(meta, chapters, cover) {
+function packageOpf(meta, chapters, cover, images = []) {
     const manifestItems = [
         `<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>`,
         `<item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml"/>`,
@@ -280,6 +419,7 @@ function packageOpf(meta, chapters, cover) {
             ]
             : []),
         ...chapters.map((c) => `<item id="${c.id}" href="${c.href}" media-type="application/xhtml+xml"/>`),
+        ...images.map((img, i) => `<item id="img-${i + 1}" href="${escapeXml(img.file)}" media-type="${img.mediaType}"/>`),
     ];
     const spine = [
         ...(cover ? [`<itemref idref="cover-page"/>`] : []),
@@ -415,8 +555,10 @@ async function zipEpub(buildDir, outputAbs) {
     await $ `find . -exec touch -t 202001010000 {} +`.cwd(buildDir).quiet();
     // 1) mimetype first, stored (-0), no extra fields (-X)
     await $ `zip -X0 ${outputAbs} mimetype`.cwd(buildDir).quiet();
-    // 2) everything else, deflated (-9), recursive (-r), no extra fields, no dir entries (-D)
-    await $ `zip -Xr9D ${outputAbs} META-INF OEBPS -x mimetype`
+    // 2) everything else, deflated (-9), recursive (-r), no extra fields, no dir entries (-D).
+    // Images that are already compressed are stored (-n): deflating a book's worth of JPEGs on
+    // every rebuild costs time and saves nothing.
+    await $ `zip -Xr9D -n .jpg:.jpeg:.png:.gif:.webp ${outputAbs} META-INF OEBPS -x mimetype`
         .cwd(buildDir)
         .quiet();
 }
@@ -601,6 +743,10 @@ export function versionAnchoredDate(version, override) {
         .toISOString()
         .replace(/\.\d+Z$/, 'Z');
 }
+/**
+ * Build the ePub for `config`'s corpus and return its path. Under `config.strict`, throws
+ * {@link EpubImageError} when a local image cannot be bound into the book.
+ */
 export async function buildEpub(config, opts = {}) {
     const projectVersion = await Bun.file(`${process.cwd()}/package.json`)
         .json()
@@ -731,6 +877,8 @@ export async function buildEpub(config, opts = {}) {
     // example links back to its anchor on the live site.
     const baseUrl = config.baseUrl?.replace(/\/+$/, '');
     const chapters = [];
+    const images = new Map();
+    const unboundImages = new Set();
     for (const node of flatten(roots)) {
         const doc = node.doc;
         // The doc's live-site URL, matching generate-site's canonical link: README
@@ -743,7 +891,7 @@ export async function buildEpub(config, opts = {}) {
         is the same `highlightHtml` the static pages use, so a code block looks the same on the
         site, in the book and in print.
         */
-        const html = rewriteInBookLinks(
+        const linked = rewriteInBookLinks(
         /*
         `'none'` — an ePub has no live examples, so the live-fence skip that protects the web
         page buys nothing here and cost the reader 237 of 284 code blocks (js, html, css and
@@ -752,6 +900,7 @@ export async function buildEpub(config, opts = {}) {
         highlighting cannot break the "Run this example live" links.
         */
         await highlightHtml(renderDocMarkdown(stripDocMeta(bookTextOf(doc)), { wikilinks }), 'none'), bookFiles, slugMap, config.basePath);
+        const html = embedLocalImages(linked, outDir, config.basePath, images, unboundImages, pathForSlug(slugMap[doc.filename] ?? ''));
         // happy-dom occasionally throws on exotic content (e.g. an internal selector
         // bug); fall back to the regex pass for that doc rather than aborting.
         let bodyHtml;
@@ -772,13 +921,34 @@ export async function buildEpub(config, opts = {}) {
             title: doc.title,
         });
     }
+    for (const img of images.values()) {
+        const dest = path.join(buildDir, 'OEBPS', img.file);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(img.source, dest);
+    }
+    if (unboundImages.size) {
+        const list = [...unboundImages];
+        const report = `epub: ${list.length} local image(s) not bound into the book (missing, outside ` +
+            `the site, or not jpg/png/gif/svg/webp):\n` +
+            list
+                .slice(0, 10)
+                .map((s) => `      ${s}`)
+                .join('\n') +
+            (list.length > 10 ? `\n      … and ${list.length - 10} more` : '');
+        if (config.strict) {
+            // nothing of this book is kept: a stray build folder would land in the site output
+            fs.rmSync(buildDir, { recursive: true, force: true });
+            throw new EpubImageError(report);
+        }
+        console.warn(report);
+    }
     // Cover (explicit image, or generated from the title + favicon).
     const cover = await makeCover(config, opts, meta);
     if (cover) {
         fs.writeFileSync(path.join(buildDir, 'OEBPS', cover.file), cover.data);
         fs.writeFileSync(path.join(buildDir, 'OEBPS', 'cover.xhtml'), coverPageXhtml(meta.title, cover.file));
     }
-    fs.writeFileSync(path.join(buildDir, 'OEBPS', 'package.opf'), packageOpf(meta, chapters, cover));
+    fs.writeFileSync(path.join(buildDir, 'OEBPS', 'package.opf'), packageOpf(meta, chapters, cover, [...images.values()]));
     fs.writeFileSync(path.join(buildDir, 'OEBPS', 'contents.xhtml'), tocPageXhtml(roots, fileFor));
     fs.writeFileSync(path.join(buildDir, 'OEBPS', 'nav.xhtml'), navXhtml(meta, roots, fileFor));
     fs.writeFileSync(path.join(buildDir, 'OEBPS', 'toc.ncx'), tocNcx(meta, roots, fileFor));
@@ -804,7 +974,9 @@ 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` +
+        (images.size ? `, ${images.size} images` : '') +
+        ')' +
         (coverPath ? `, cover ${path.basename(coverPath)}` : ''));
     return output;
 }

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

@@ -18,7 +18,7 @@ export type { Doc } from './docs.js';
 export type { LibraryBundle } from './library-bundle.js';
 export { generateSite } from './generate-site.js';
 export type { GenerateSiteConfig } from './generate-site.js';
-export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';
+export { buildEpub, DEFAULT_BOOK_CSS, EpubImageError } from './epub.js';
 export type { BuildEpubOptions, BookMeta } from './epub.js';
 export { selectBookDocs } from '../book-manifest.js';
 export type { BookManifest } from '../book-manifest.js';

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

@@ -20,7 +20,7 @@ export { auditDependencies, reportAudit, resolveAuditMode, } from './audit-guard
 export { openDevBrowser, buildOpenPlan } from './open-browser.js';
 export { extractDocs, saveDocsJSON } from './docs.js';
 export { generateSite } from './generate-site.js';
-export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';
+export { buildEpub, DEFAULT_BOOK_CSS, EpubImageError } from './epub.js';
 export { selectBookDocs } from '../book-manifest.js';
 export { placeInBook, bookTextOf } from '../book-target.js';
 // Insets and conditional text (#217): `extractDocs` applies these; exported for a consumer

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

@@ -29,7 +29,7 @@ export function registerSiteDialects(config) {
     }
 }
 import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
-import { attachCovers, listEpubVolumes, printCoverManifestUrl, VOLUME_MANIFEST, renderEpubDownloads, } from './epub-volumes.js';
+import { EPUB_IMAGE_EXIT, attachCovers, listEpubVolumes, printCoverManifestUrl, VOLUME_MANIFEST, renderEpubDownloads, } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
 import { assetStampInputs, computeAssetStamp, missingStampInputWarning, } from './asset-stamp.js';
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, } from 'fs';
@@ -88,6 +88,8 @@ async function buildEpubInChild(config, opts) {
             // the ePub's "run this example live" links count examples the way the page does, so it
             // must know the site's dialects too (1.16.3 review F3)
             dialects: config.dialects,
+            // an image the book cannot bind fails a strict build (EPUB_IMAGE_EXIT)
+            strict: config.strict,
         },
         opts,
     };
@@ -103,6 +105,9 @@ async function buildEpubInChild(config, opts) {
     }, EPUB_TIMEOUT_MS);
     try {
         const code = await child.exited;
+        if (code === EPUB_IMAGE_EXIT && config.strict) {
+            misconfigured(true, '⚠️  epub: a local image could not be bound into the book (listed above).');
+        }
         if (code !== 0) {
             console.warn(`⚠️  epub build failed (exit ${code}). The site is fine; the .epub may be stale.`);
         }