tosijs-ui 1.16.37 → 1.16.38

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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.`);
         }