@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/pdf-build.mjs

@@ -94,18 +94,25 @@ import {
     gatesFailed,
     resolveSitePass,
 } from "./site-build.mjs";
-import { resolveInfoboxRef, wikiContext } from "./site-index.mjs";
+import {
+    figureIndexKeys,
+    resolveCrossNoteFigures,
+    resolveInfoboxRef,
+    wikiContext,
+} from "./site-index.mjs";
 import { resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { positionOfLiteral } from "./diagnostics.mjs";
-import { artPathname, assetAddressIndex } from "./art-fields.mjs";
+import { artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
+import { embedRole } from "./content-embeds.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
-import { numberCaptions, scanCaptions } from "./content-captions.mjs";
+import { numberFigures, scanFigures } from "./content-figures.mjs";
 import { collectAnchors } from "./anchors.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imagesIn, parseImageDirective } from "./content-images.mjs";
 import {
+    bookImageWidthIn,
     PDF_IMAGE_INCHES,
     PDF_PAGE,
     pdfColumnWidth,
@@ -113,7 +120,15 @@ import {
     pdfTextWidth,
     resamplePdfImages,
 } from "./pdf-images.mjs";
-import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
+import {
+    ASSETS_SEGMENT,
+    assetPathnameKey,
+    pathnameProblem,
+    resolvePathname,
+} from "./pathnames.mjs";
+import { ASSET_SYSTEM, assetTypeOfRoot, isAssetShortcode } from "./asset-types.mjs";
+import { canonicalKey } from "./address.mjs";
+import { isComplete as isForeignCacheComplete, newestVersionDir } from "./metadata-index.mjs";
 import {
     createParser,
     labelFor,
@@ -128,6 +143,7 @@ import { noteInfoboxes } from "./infobox-registry.mjs";
 import { resolveIconGlyphs } from "./pdf-fonts.mjs";
 import { buildMaps, relatedPlaces } from "./map-build.mjs";
 import { mapWorld } from "./map-places.mjs";
+import { resolveAssetReplacement } from "./asset-replacement.mjs";
 
 /**
  * The file on disk an authored image pathname names, or `null`.
@@ -144,21 +160,165 @@ import { mapWorld } from "./map-places.mjs";
  * makes the source a consumer can compile by hand with no flags, and what keeps
  * a build from touching a path outside its own output.
  *
- * Only a file **this** package ships can be staged. A pathname naming another
- * package's file, or a URL, names something no build here can open — a build
- * reaches no network — and the caller reports it as a picture the book will not
- * carry.
+ * A file **this** package ships stages directly. A pathname naming another
+ * package's file stages instead from a declared replacement's cached archive,
+ * when `opts.resolveReplacement` — the pure function
+ * {@link module:engine/asset-replacement.resolveAssetReplacement} —
+ * answers it; `opts.foreignIndex` is the merged index that answer is read
+ * against. A pathname naming a package no replacement carries it for, or a
+ * URL, names something no build here can open — a build reaches no network —
+ * and the caller reports it as a picture the book will not carry.
  *
  * @param {string} src - The pathname, as authored.
  * @param {object} config - The resolved configuration.
+ * @param {object} [opts]
+ * @param {Map<string, object>} [opts.foreignIndex] - Every fetched
+ *   dependency's own records, keyed by canonical address — the index a
+ *   replacement's record is read out of.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, or an
+ *   equivalent a caller injects for a test. Omitted, a foreign pathname this
+ *   package does not own stays declined exactly as it always has.
  * @returns {{from: string, to: string}|null} The file, and where under the
  *   output directory it is staged.
+ * @throws {Error} When a declared replacement answers the address but its
+ *   archive was never fetched.
  */
-export function stagedImagePath(src, config) {
+export function stagedImagePath(src, config, opts = {}) {
     const forms = resolvePathname(src, config);
-    if (!forms || forms.state !== "package" || !forms.own) return null;
+    if (!forms || forms.state !== "package") return null;
+    // A declared replacement answers before the package's own file does, which
+    // is the whole of what declaring one buys: the address a note writes is
+    // this package's own, and the picture staged for it is the replacement's.
+    // A miss falls through, so a package declaring none stages exactly what it
+    // ships.
+    const replaced = opts.resolveReplacement ? stagedReplacementPath(forms, config, opts) : null;
+    if (replaced) return replaced;
+    if (forms.own) {
+        return {
+            from: path.resolve(config.rootDir, forms.local),
+            to: forms.pdf,
+        };
+    }
+    return null;
+}
+
+/**
+ * Every declared relationship that opted a dependency in as this package's
+ * asset replacement, in declaration order.
+ *
+ * The same shape {@link module:engine/foreign-catalog.itemCatalogRelationships}
+ * returns, read directly rather than through that module: this file stays a
+ * leaf over the configuration it is handed, and the flag is as small to read
+ * back as it was to validate.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, package: string}>} The relationships, each
+ *   with the package segment its own content index publishes under.
+ */
+function assetReplacementRelationships(config) {
+    const out = [];
+    for (const entries of Object.values(config.relationships ?? {})) {
+        for (const rel of entries ?? []) {
+            if (rel.assetReplacement) {
+                out.push({ id: rel.id, package: rel.contentPackage ?? rel.id });
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * The address a pathname this package does not own is read back as, for
+ * asking whether a declared replacement answers it instead of the package
+ * the pathname names.
+ *
+ * {@link module:engine/asset-replacement.resolveAssetReplacement} only ever
+ * matches an address whose package segment is the compiling package's own,
+ * so the pathname's own package is set aside and its suffix — the one piece
+ * every surface derives from, and the piece a replacement publishes under
+ * its own package instead — is read back as this package's type and
+ * shortcode.
+ *
+ * @param {import("./pathnames.mjs").PathnameForms} forms - The pathname,
+ *   resolved.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string|null} The canonical address, or `null` when the suffix is
+ *   not shaped like an asset's.
+ */
+function localAssetAddress(forms, config) {
+    const segments = String(forms.suffix ?? "").split("/");
+    const assetType = assetTypeOfRoot(segments[0]);
+    if (!assetType) return null;
+    const base = segments[segments.length - 1];
+    const ext = path.extname(base);
+    const shortcode = (ext ? base.slice(0, -ext.length) : base).toLowerCase();
+    if (!isAssetShortcode(shortcode)) return null;
+    return canonicalKey(config.contentPackage, ASSET_SYSTEM, assetType.type, shortcode);
+}
+
+/**
+ * The cache directory one relationship's archive was fetched into, found the
+ * way {@link module:engine/foreign-catalog.foreignItemCatalogDirs} finds an
+ * item catalogue's: the newest `.complete`-stamped `<id>@<version>`
+ * directory under `config.paths.foreignCache`.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {string} id - The relationship's dependency id.
+ * @returns {string|null} The directory, or `null` when nothing is cached.
+ */
+function cachedReplacementDir(config, id) {
+    const root = config.paths.foreignCache;
+    if (!fs.existsSync(root)) return null;
+    const cached = fs
+        .readdirSync(root)
+        .filter((name) => name.startsWith(`${id}@`))
+        .map((name) => path.join(root, name))
+        .filter(isForeignCacheComplete);
+    return cached.length ? newestVersionDir(cached) : null;
+}
+
+/**
+ * The file a declared replacement stages in place of a pathname this package
+ * does not own, or `null` when no replacement answers it.
+ *
+ * @param {import("./pathnames.mjs").PathnameForms} forms - The pathname,
+ *   resolved, with `forms.own` already `false`.
+ * @param {object} config - The resolved build configuration.
+ * @param {object} opts
+ * @param {Map<string, object>} [opts.foreignIndex] - Every fetched
+ *   dependency's own records, keyed by canonical address.
+ * @param {Function} opts.resolveReplacement - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}.
+ * @returns {{from: string, to: string}|null} The file, staged at the same
+ *   `pdf`-relative path this address would have taken had this package
+ *   shipped it.
+ * @throws {Error} When the replacement that answers the address has not
+ *   been fetched.
+ */
+function stagedReplacementPath(forms, config, { foreignIndex = new Map(), resolveReplacement }) {
+    const address = localAssetAddress(forms, config);
+    if (!address) return null;
+    const relationships = assetReplacementRelationships(config);
+    if (!relationships.length) return null;
+    const hit = resolveReplacement(address, {
+        localPackage: config.contentPackage,
+        replacements: relationships.map((rel) => rel.package),
+        index: foreignIndex,
+    });
+    if (!hit) return null;
+    const assetPath = hit.record?.asset?.path;
+    if (!assetPath) return null;
+    const rel = relationships.find((entry) => entry.package === hit.package);
+    const dir = cachedReplacementDir(config, rel?.id ?? hit.package);
+    if (!dir) {
+        throw new Error(
+            `\`${hit.package}\` declares \`assetReplacement: true\` and carries \`${address}\`, ` +
+                "but its archive has not been fetched. Run `package-build deps fetch` first.",
+        );
+    }
     return {
-        from: path.resolve(config.rootDir, forms.local),
+        from: path.join(dir, ASSETS_SEGMENT, assetPath),
         to: forms.pdf,
     };
 }
@@ -301,9 +461,19 @@ function readDocumentTree(file) {
  * @param {string} [opts.version] - Stamped on the title page and the file name.
  * @param {boolean} [opts.compile] - Whether to run Typst. False leaves the
  *   `.typ` source, which is what the unit tests read.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, for tests.
+ *   Loaded from that module otherwise, and only when a relationship declares
+ *   `assetReplacement: true` — a build with none never imports it.
  * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
  */
-export async function buildPdf({ config, out, version = "", compile = true } = {}) {
+export async function buildPdf({
+    config,
+    out,
+    version = "",
+    compile = true,
+    resolveReplacement,
+} = {}) {
     const resolved = config ?? loadPackConfig();
     const findings = [];
 
@@ -441,6 +611,17 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     const md = createParser(resolved.icons);
     const glyphs = resolveIconGlyphs(resolved.icons, resolved.pdf.iconFonts, findings);
 
+    // Asked only where a relationship declares `assetReplacement: true`: with
+    // none declared the resolver is never consulted, and staging gives the
+    // answer it gives a package that declares no replacement. A caller may
+    // supply its own, which is how the staging tests drive it.
+    const stagingOpts = {
+        foreignIndex: gates.foreign.index,
+        resolveReplacement:
+            resolveReplacement ??
+            (assetReplacementRelationships(resolved).length ? resolveAssetReplacement : null),
+    };
+
     const outDir = path.resolve(
         resolved.rootDir,
         out || resolved.pdf.out || path.join("build", "dist"),
@@ -449,6 +630,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
 
     /** @type {Map<string, string>} Authored address → the staged file's path. */
     const images = new Map();
+    /** @type {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+     *  Authored address, exactly as the note wrote it → its asset's role and
+     *  pixel size. Keyed the same way {@link images} is rather than by the
+     *  asset index's own canonical pathname, because a body image is free to
+     *  write the bare, own-package form — see
+     *  {@link module:engine/pathnames.assetPathnameKey}. */
+    const imageAssets = new Map();
     /** @type {Map<string, {from: string, to: string, relative: string, file: string, uses: Array<{width: number, height: number}>}>} */
     const imageCandidates = new Map();
     /** @type {Set<string>} Addresses already looked for, staged or not. */
@@ -473,8 +661,18 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             const wide =
                 directive.size === "full-width" || directive.classes.includes("full-width");
             const availableWidth = wide ? pdfTextWidth : pdfColumnWidth(columns);
+            const assetKey = assetPathnameKey(src, resolved);
+            const asset = assetKey ? assets.byPath.get(assetKey) : undefined;
+            if (asset) imageAssets.set(src, asset);
+            // `auto` is the one size a role or an icon's nominal width can
+            // narrow — a named `size=` is the author's own statement, honoured
+            // as it always was.
+            const roleWidth = directive.size === "auto" ? bookImageWidthIn(asset) : undefined;
             const use = {
-                width: Math.min(PDF_IMAGE_INCHES[directive.size] ?? availableWidth, availableWidth),
+                width: Math.min(
+                    roleWidth ?? PDF_IMAGE_INCHES[directive.size] ?? availableWidth,
+                    availableWidth,
+                ),
                 height: pdfTextHeight * 0.8,
             };
             if (seenImages.has(src)) {
@@ -491,7 +689,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 findings.push({ file, severity: "error", message: problem });
                 continue;
             }
-            const staged = stagedImagePath(src, resolved);
+            let staged;
+            try {
+                staged = stagedImagePath(src, resolved, stagingOpts);
+            } catch (err) {
+                findings.push({ file, severity: "error", message: err.message });
+                continue;
+            }
             if (!staged) {
                 findings.push({
                     file,
@@ -540,16 +744,24 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
      * @param {number} columns - The entry's page columns.
      * @returns {string} Typst markup.
      */
-    const captionCounts = { code: 0, table: 0, figure: 0, prose: 0 };
-    const frontCaptions = new Map();
+    const figureCounts = { code: 0, table: 0, figure: 0, map: 0, prose: 0 };
+    // The role lookup a `:::figure` fence's `map` counter reaches through —
+    // see `engine/content-figures.mjs`'s `resolveRole`. Addressed form, for a
+    // page's own scan below, which runs before its embeds are rewritten into
+    // ordinary images; `pathRoles` is the same lookup keyed by the pathname
+    // that rewrite leaves behind, for the renderer's own rescan of the
+    // resolved body.
+    const resolveRole = (address) => embedRole(assets, address);
+    const pathRoles = pathnameRoles(assets);
+    const frontFigures = new Map();
     for (const file of resolved.pdf.front) {
         try {
-            const scan = scanCaptions(fs.readFileSync(file, "utf8"));
+            const scan = scanFigures(fs.readFileSync(file, "utf8"), { resolveRole });
             // Numbered here, because a number runs across the whole book and only
-            // this loop knows the order; what is *wrong* with a caption is
+            // this loop knows the order; what is *wrong* with a figure is
             // reported by the renderer, which reads every one of the three kinds
             // of markdown a book is made of.
-            frontCaptions.set(file, numberCaptions(scan.captions, captionCounts));
+            frontFigures.set(file, numberFigures(scan.figures, figureCounts));
         } catch {
             // The rendering pass reports an unreadable front-matter file.
         }
@@ -560,17 +772,83 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         config: resolved,
         book: true,
     });
+
+    /**
+     * Every entry's own figures, numbered across the whole book in reading
+     * order, before any entry's expressions render — so a cross-note `ref`
+     * finds the number its target carries in the finished book rather than a
+     * page-local recount. Walked in the same order {@link bodies} fills
+     * below, so `figureCounts` lands on the same final tallies either way;
+     * the note's table expansion is cached here too, so the render loop does
+     * not redo it.
+     *
+     * @type {Map<string, {markdown?: string, errors?: object[],
+     *   lineMap?: object[], numberedFigures: object[]}>}
+     */
+    const prepared = new Map();
+    // Every note's figures, by the address a `ref` crossing into it would
+    // write — see `engine/site-index.mjs`'s `figureIndexKeys`.
+    const figuresByAddress = new Map();
+    for (const entry of plan.entries) {
+        if (entry.kind === "note") {
+            const file = noteFile(contentBase, entry.record);
+            const page = byFile.get(file);
+            if (!page) continue; // reported as `missing` by the render loop below
+            const src = page.relPath ?? page.base;
+            const { markdown, errors, lineMap } = expandContentTables(page.body, {
+                docs: universe.get(page.pkg) ?? [],
+                linkable: (d) => Boolean(d.fm.shortcode),
+                source: src,
+                sqlTables: sqlTables?.get(page.file),
+                pageLists: sqlTables?.pageLists?.get(page.file),
+                self: { fm: page.fm, path: page.relPath },
+            });
+            const numberedFigures = numberFigures(
+                scanFigures(markdown, { resolveRole }).figures,
+                figureCounts,
+            );
+            prepared.set(entry.anchor, { markdown, errors, lineMap, numberedFigures });
+            const shortcode = page.fm.shortcode;
+            if (typeof shortcode === "string" && shortcode) {
+                const byId = new Map(
+                    numberedFigures
+                        .filter((figure) => figure.id)
+                        .map((figure) => [
+                            figure.id,
+                            {
+                                label: figure.label,
+                                caption: figure.caption,
+                                hasCaption: figure.hasCaption,
+                            },
+                        ]),
+                );
+                const type = String(page.fm.type ?? "").toLowerCase();
+                for (const key of figureIndexKeys(page.pkg, type, shortcode))
+                    figuresByAddress.set(key, byId);
+            }
+            continue;
+        }
+        if (entry.kind === "prose") {
+            const file = path.resolve(resolved.rootDir, entry.file);
+            let text;
+            try {
+                text = fs.readFileSync(file, "utf8");
+            } catch {
+                continue; // reported by the render loop below
+            }
+            prepared.set(entry.anchor, {
+                numberedFigures: numberFigures(
+                    scanFigures(text, { resolveRole }).figures,
+                    figureCounts,
+                ),
+            });
+        }
+    }
+
     const renderPage = (page, headingOffset, anchorPrefix, columns) => {
         const src = page.relPath ?? page.base;
         const wikiErrors = [];
-        const { markdown, errors, lineMap } = expandContentTables(page.body, {
-            docs: universe.get(page.pkg) ?? [],
-            linkable: (d) => Boolean(d.fm.shortcode),
-            source: src,
-            sqlTables: sqlTables?.get(page.file),
-            pageLists: sqlTables?.pageLists?.get(page.file),
-            self: { fm: page.fm, path: page.relPath },
-        });
+        const { markdown, errors, lineMap, numberedFigures } = prepared.get(anchorPrefix);
         // A content-table finding states its `reason`, its 0-based line within
         // the body and its column, exactly as the site build reports them.
         // Reading it as `message` yields `[object Object]` and discards the
@@ -593,16 +871,31 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             foreignIndex: gates.foreign.index,
             assets,
         });
-        const captionScan = scanCaptions(markdown);
-        const numberedCaptions = numberCaptions(captionScan.captions, captionCounts);
         linkCtx.captionLabels = new Map(
-            numberedCaptions.map((caption) => [caption.id, caption.label]),
+            numberedFigures
+                .filter((figure) => figure.id)
+                .map((figure) => [figure.id, figure.label]),
         );
         // This page's own anchors, so a `[[#slug]]` self-link is checked
         // against what the page actually declares, exactly as the site build
         // checks it.
         linkCtx.anchors = new Set(collectAnchors(markdown).map((anchor) => anchor.slug));
         linkCtx.output = "book";
+        // What the `ref` expression helper needs beyond the label — the
+        // caption text and whether one was authored — keyed as
+        // `engine/site-build.mjs` keys its own, but built from this note's
+        // *book-wide* numbering rather than its page-local count: the book
+        // numbers each kind across the whole book in reading order, so a
+        // reference has to read the number the book gives the figure, not the
+        // number the note would give it alone.
+        const figuresById = new Map(
+            numberedFigures
+                .filter((figure) => figure.id)
+                .map((figure) => [
+                    figure.id,
+                    { label: figure.label, caption: figure.caption, hasCaption: figure.hasCaption },
+                ]),
+        );
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
         // wikilink, and resolving it would make the example impossible to write.
@@ -612,6 +905,25 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             sqlResults: sqlTables?.inline?.get(page.file),
             file: page.file,
             bodyLine: page.bodyLine,
+            figures: {
+                get: (id) => figuresById.get(id),
+                // A cross-note `ref` resolves the written address exactly as
+                // a wikilink does, against every note's figures numbered
+                // before any entry's expressions render — see `prepared`
+                // above. The default link renders the target's own web
+                // address, which `renderLink` in `engine/pdf-render.mjs`
+                // resolves to the entry the book gave it, exactly as an
+                // ordinary cross-note wikilink does.
+                note: (target) =>
+                    resolveCrossNoteFigures(target, {
+                        contentTypes: gates.index.contentTypes,
+                        packages: gates.index.packages,
+                        noIndexPackages: gates.index.noIndexPackages,
+                        contentPackage: gates.index.contentPackage,
+                        siteIndexMap: gates.index.index,
+                        figuresByAddress,
+                    }),
+            },
         });
         findings.push(...expressions.findings);
         const resolvedBody = protectCode(expressions.markdown, (text) =>
@@ -657,21 +969,24 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             links: plan.links,
             glyphs,
             images,
+            assets: imageAssets,
             headingOffset,
             anchorPrefix,
-            captions: numberedCaptions,
+            captions: numberedFigures,
             url: site,
             findings,
             file: page.file,
             bodyLine: page.bodyLine,
             lineMap,
             prepared: true,
+            resolveRole: (pathname) => pathRoles.get(pathname),
         });
         // Infoboxes follow the authored body within this note's entry.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
             router: routerFor(resolved),
             dates: gates.index.dateContext,
+            contentPackage: gates.index.contentPackage,
         });
         const panel = infoboxesToTypst(boxes, {
             link: (value) => linkToTypst(value, plan.links, labelFor, site),
@@ -724,9 +1039,10 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                     links: plan.links,
                     glyphs,
                     images,
+                    assets: imageAssets,
                     headingOffset: entry.depth,
                     anchorPrefix: entry.anchor,
-                    captions: numberCaptions(scanCaptions(text).captions, captionCounts),
+                    captions: prepared.get(entry.anchor).numberedFigures,
                     url: site,
                     findings,
                     file,
@@ -753,8 +1069,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 links: plan.links,
                 glyphs,
                 images,
+                assets: imageAssets,
                 footnotePrefix: `footnote-front-${index + 1}`,
-                captions: frontCaptions.get(file),
+                captions: frontFigures.get(file),
                 url: site,
                 findings,
                 file,
@@ -790,7 +1107,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     const stageMapBackground = (entry, value, title) => {
         const file = noteFile(contentBase, entry.record);
         const found = artPathname(assets, value, "image", ["image", "icon"]);
-        const staged = stagedImagePath(found.pathname ?? value, resolved);
+        let staged;
+        try {
+            staged = stagedImagePath(found.pathname ?? value, resolved, stagingOpts);
+        } catch (err) {
+            findings.push({ file, severity: "error", message: err.message });
+            return;
+        }
         if (!staged || !fs.existsSync(staged.from)) {
             findings.push({
                 file,

package/engine/pdf-images.mjs

@@ -40,6 +40,70 @@ export const pdfTextHeight = PDF_PAGE.height - 2 * PDF_PAGE.margin;
 export const pdfColumnWidth = (columns = 2) =>
     (pdfTextWidth * (1 - 0.04 * (columns - 1))) / columns;
 
+/**
+ * The fraction of the page's one-column measure a picture's role may fill at
+ * most — one table, read by {@link bookImageWidthIn}, so a policy change here
+ * is the one line it costs rather than an edit to every note drawing a role.
+ *
+ * A `portrait` or an `emblem` names a subject or a mark, which sits beside
+ * prose rather than replacing a page of it; a `banner`, a `plate` and a `map`
+ * are each meant to be looked at in full. The measure is the page's own text
+ * width, {@link pdfTextWidth}, so a role's slot does not shrink when a page
+ * happens to be set in two columns — it is what the picture is *for* that
+ * sets the slot, not the layout it lands in.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const BOOK_ROLE_SLOTS = Object.freeze({
+    portrait: 0.5,
+    emblem: 0.5,
+    banner: 1,
+    plate: 1,
+    map: 1,
+});
+
+/**
+ * The book's nominal width for an icon-type picture, in inches, whatever its
+ * file holds — almost every icon is an SVG with no pixel count to measure.
+ *
+ * @type {number}
+ */
+export const BOOK_ICON_WIDTH_IN = 1;
+
+/**
+ * The width the book draws one picture at, in inches, when nothing authored
+ * narrows it to a named `size=`.
+ *
+ * > drawn width = min(the role's slot, natural pixels ÷ the print floor)
+ *
+ * **Every size here is a maximum, never a target**: a picture is never drawn
+ * larger than it was made. The print floor is {@link PDF_PAGE.dpi}, the same
+ * constant the page geometry above is set against, so a role's slot and the
+ * page it is drawn on cannot disagree about what a pixel is worth.
+ *
+ * An icon-type address takes the nominal icon width whatever role it might
+ * otherwise carry — `role` never reaches one, since the asset record refuses
+ * it there. A vector carries no pixel count, so nothing narrows its role's
+ * slot. A picture declaring no role answers `undefined`: the medium's
+ * ordinary size, decided elsewhere by a named `size=` or by its own natural
+ * pixels within whatever it is set in.
+ *
+ * @param {object} [asset] - What {@link module:engine/art-fields.assetImageInfoByPathname}
+ *   records for the picture's address.
+ * @param {string} [asset.type] - The asset's type — `icon` or `image`.
+ * @param {string} [asset.role] - The picture's declared role.
+ * @param {number|""} [asset.width] - The file's own pixel width; blank for a vector.
+ * @returns {number|undefined} The drawn width, in inches.
+ */
+export function bookImageWidthIn({ type, role, width } = {}) {
+    if (type === "icon") return BOOK_ICON_WIDTH_IN;
+    const fraction = role ? BOOK_ROLE_SLOTS[role] : undefined;
+    if (!fraction) return undefined;
+    const slot = fraction * pdfTextWidth;
+    if (typeof width !== "number" || !Number.isFinite(width) || width <= 0) return slot;
+    return Math.min(slot, width / PDF_PAGE.dpi);
+}
+
 /**
  * Optimize staged raster images without changing their authored files.
  *