@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/pdf-render.mjs

@@ -67,7 +67,14 @@ import deflistPlugin from "markdown-it-deflist";
 
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
 import { iconPlugin, ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
-import { IMAGE_CLASSES, IMAGE_FLOATS, imagePlugin } from "./content-images.mjs";
+import {
+    IMAGE_CLASSES,
+    IMAGE_FLOATS,
+    IMAGE_PATTERN,
+    checkImages,
+    imagePlugin,
+} from "./content-images.mjs";
+import { bookImageWidthIn } from "./pdf-images.mjs";
 
 /** Requested print width for every named image size. */
 export const BOOK_IMAGE_WIDTHS = Object.freeze({
@@ -79,7 +86,7 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
     "full-width": '"full-width"',
 });
 import { slugify } from "./content-slug.mjs";
-import { scanCaptions } from "./content-captions.mjs";
+import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { HTML_TAG, htmlMessage } from "./content-html.mjs";
@@ -290,7 +297,7 @@ function offsetPosition(source, offset, opts = {}) {
  *   those passes did not run — `opts.prepared` — because each of them leaves the
  *   markup as written when it fails and has already said so in its own words.
  *
- * A `:::` block and a `:::caption` are the pair this pass does handle, and their
+ * A `:::` block and a `:::figure` are the pair this pass does handle, and their
  * own scanners decide what is well formed; their findings are reported here so
  * that a front-matter file, a prose file and a note body all get them.
  *
@@ -341,8 +348,15 @@ function reportUnrenderable(source, definitions, opts, original) {
                 );
         }
     }
-    for (const error of scanCaptions(source).errors)
+    for (const error of scanFigures(source).errors)
         report(linePosition(error.line, error.column, opts), "error", error.message);
+    // An image sharing its paragraph with other text, or an address or title
+    // the website's own lint already refuses — asked here too, so the book
+    // fails on the same input rather than typesetting the directive as
+    // though it were absent. `checkImages` resolves `opts.bodyLine` and
+    // `opts.bodyColumn` itself.
+    for (const error of checkImages(source, opts.file ?? "", opts))
+        report({ line: error.line, column: error.column }, error.severity, error.message);
     for (const error of scanHeadingAttributes(source).errors)
         report(linePosition(error.line, error.column, opts), "error", error.message);
     for (const error of withheldSections(source).errors)
@@ -408,6 +422,12 @@ function reportUnrenderable(source, definitions, opts, original) {
  *   the staged file's path, relative to the `.typ`. An address this does not
  *   carry has no file the compiler can open, so the figure prints its caption
  *   alone — see {@link renderImage}.
+ * @param {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   [opts.assets] - An image's address as authored → what
+ *   {@link module:engine/art-fields.assetImageInfoByPathname} records for it,
+ *   which is what sizes a picture carrying no named `size=` — see
+ *   {@link module:engine/pdf-images.bookImageWidthIn}. An address missing from
+ *   this map draws at the medium's ordinary size, the same as today.
  * @param {number} [opts.headingOffset] - Added to every heading level, so a
  *   note's own `##` nests beneath the entry heading the book gave it.
  * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
@@ -440,6 +460,7 @@ export function markdownToTypst(markdown, opts = {}) {
         links = new Map(),
         glyphs = new Map(),
         images = new Map(),
+        assets = new Map(),
         headingOffset = 0,
         anchorPrefix = "",
     } = opts;
@@ -466,6 +487,7 @@ export function markdownToTypst(markdown, opts = {}) {
         links,
         glyphs,
         images,
+        assets,
         headingOffset,
         anchorPrefix,
         url: opts.url,
@@ -544,18 +566,18 @@ export function markdownToTypst(markdown, opts = {}) {
         }
     }
     const lines = source.split("\n");
-    const localCaptions = scanCaptions(source).captions;
+    const localFigures = scanFigures(source, { resolveRole: opts.resolveRole }).figures;
     // Numbered by the caller, which counts across the whole book, and placed by
     // the scan above, which is the only reading of *this* body. Paired by
-    // position: two captions may share an id — a finding, and the book is built
-    // anyway — and keying on one would give the second caption's lines to the
-    // first, printing its block twice and losing its label.
-    const provided = opts.captions ?? localCaptions;
-    const numbered = new Map(provided.map((caption) => [caption.id, caption]));
-    const captions = localCaptions.map((caption, at) => {
+    // position: two figures may share an id — a finding, and the book is built
+    // anyway — and keying on one would give the second figure's lines to the
+    // first, printing its contents twice and losing its label.
+    const provided = opts.captions ?? localFigures;
+    const numbered = new Map(provided.map((figure) => [figure.id, figure]));
+    const captions = localFigures.map((figure, at) => {
         const counted =
-            provided[at]?.id === caption.id ? provided[at] : (numbered.get(caption.id) ?? caption);
-        return { ...caption, label: counted.label, number: counted.number };
+            provided[at]?.id === figure.id ? provided[at] : (numbered.get(figure.id) ?? figure);
+        return { ...figure, label: counted.label, number: counted.number };
     });
     if (!captions.length) return renderMarkdownSegment(source, md, ctx, definitions);
     const out = [];
@@ -569,14 +591,29 @@ export function markdownToTypst(markdown, opts = {}) {
                 definitions,
             ),
         );
-        const block = lines.slice(caption.blockStart, caption.blockEnd).join("\n");
-        out.push(renderMarkdownSegment(block, md, { ...ctx, caption }, definitions));
-        if (caption.kind !== "table" && caption.kind !== "figure") {
-            out.push(
-                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}]] <${sectionLabel(anchorPrefix, slugify(caption.id))}>\n\n`,
+        const block = lines.slice(caption.bodyStart, caption.bodyEnd).join("\n");
+        // A grouped figure's images are rendered through the same call that
+        // reads `ctx.caption`, so `renderImage` needs to know which one is
+        // last — see the counter it decrements, set only for a `figure`-kind
+        // fence, where more than one image can share the one caption.
+        const captioned =
+            caption.kind === "figure" || caption.kind === "map" ?
+                { ...caption, imagesRemaining: { n: countImages(block) } }
+            :   caption;
+        const segments = [
+            renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
+        ];
+        if (caption.kind !== "table" && caption.kind !== "figure" && caption.kind !== "map") {
+            segments.push(
+                `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}]]${typstAnchor(anchorPrefix, caption)}\n\n`,
             );
         }
-        cursor = caption.blockEnd;
+        out.push(
+            caption.classes.includes("border") ?
+                figureBorder(segments.join(""))
+            :   segments.join(""),
+        );
+        cursor = caption.close + 1;
     }
     out.push(renderMarkdownSegment(lines.slice(cursor).join("\n"), md, ctx, definitions));
     return out.filter(Boolean).join("\n\n");
@@ -885,9 +922,63 @@ function inlineMarkup(text, ctx) {
     return inline ? renderInline(inline, ctx) : "";
 }
 
-/** Caption text with the same inline Markdown handling as the surrounding prose. */
+/**
+ * A figure's label, with its caption when it carries one.
+ *
+ * The caption's inline Markdown is handled the way the surrounding prose is. A
+ * figure with no caption draws its label alone.
+ *
+ * @param {object} caption - A figure record.
+ * @param {object} ctx - Render context.
+ * @returns {string} Typst markup.
+ */
 function captionMarkup(caption, ctx) {
-    return `${escapeTypst(caption.label)}: ${inlineMarkup(caption.text, ctx)}`;
+    const label = escapeTypst(caption.label);
+    return caption.hasCaption ? `${label}: ${inlineMarkup(caption.caption, ctx)}` : label;
+}
+
+/**
+ * How many markdown images a figure's contents carry.
+ *
+ * A grouped figure's `///` caption describes the whole plate, not any one
+ * picture in it, so {@link renderImage} needs to know which image is the
+ * last — the one that carries the group's single label and anchor — and this
+ * is the count it counts down from.
+ *
+ * @param {string} contents - The figure's captioned contents, as authored.
+ * @returns {number} How many images the contents hold.
+ */
+function countImages(contents) {
+    return (String(contents ?? "").match(IMAGE_PATTERN) ?? []).length;
+}
+
+/**
+ * `.border` draws the whole figure — its content and its label together —
+ * inside a hairline box. A thin stroke is print's equivalent of a border and
+ * padding on the web and in a Foundry journal: a figure already sits inside
+ * its own column or float, so the book's version of a border is the lightest
+ * mark that still reads as one rather than a second, heavier frame around a
+ * frame.
+ *
+ * @param {string} body - The figure's own rendered Typst, content and label.
+ * @returns {string} Typst markup.
+ */
+function figureBorder(body) {
+    return `\n#block(width: 100%, stroke: 0.4pt + luma(60%), inset: 8pt, above: 0.6em, below: 0.6em)[\n${body}\n]\n\n`;
+}
+
+/**
+ * The Typst label a figure is referenced by, or `""` when it declares no id.
+ *
+ * A figure with no id is numbered and drawn and nothing addresses it, so it is
+ * given no label: an empty one would collide with every other idless figure.
+ *
+ * @param {string} prefix - The entry's anchor prefix.
+ * @param {object} caption - A figure record.
+ * @returns {string} A ` <label>` to append, or `""`.
+ */
+function typstAnchor(prefix, caption) {
+    return caption.id ? ` <${sectionLabel(prefix, slugify(caption.id))}>` : "";
 }
 
 /**
@@ -966,7 +1057,7 @@ function renderTable(tokens, ctx) {
     const caption = ctx.caption;
     const labelled =
         caption ?
-            `#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}] <${sectionLabel(ctx.anchorPrefix, slugify(caption.id))}>\n${drawn}`
+            `#text(size: 7.6pt, style: "italic")[${captionMarkup(caption, ctx)}]${typstAnchor(ctx.anchorPrefix, caption)}\n${drawn}`
         :   drawn;
     // Wide content is given an explicit span rather than left to overflow the
     // measure: past three columns a table is set across the page, and
@@ -1186,6 +1277,16 @@ function renderLink(href, inner, ctx) {
     return `#link("${escapeTypstString(absolutePageUrl(url, ctx.url))}")[${inner}]`;
 }
 
+/**
+ * A width in inches, as a Typst length literal.
+ *
+ * @param {number} inches - The width.
+ * @returns {string} A Typst length, rounded to a thousandth of an inch.
+ */
+function typstInches(inches) {
+    return `${Math.round(inches * 1000) / 1000}in`;
+}
+
 /**
  * One image, as the figure the book prints.
  *
@@ -1221,32 +1322,55 @@ function renderLink(href, inner, ctx) {
  * `#image` on a path Typst cannot open is a compile error, and a compile error
  * in a 2,500-entry book is fatal at the very end of a run that otherwise
  * succeeded — over an illustration, which is the least important thing on the
- * page. An address the build could not stage prints its caption alone instead,
- * and the build reports the address it could not find.
+ * page. An address the build could not stage prints its authored caption alone
+ * instead, if it has one, and nothing at all if it does not; the build reports
+ * the address it could not find either way.
+ *
+ * ## A grouped figure's one label belongs to the last picture
+ *
+ * Only a figure-kind fence labels an image inline — a fence holding anything
+ * besides pictures is prose, and gets its label from the generic block-level
+ * print in {@link markdownToTypst} instead, the same as a code or a table
+ * fence. Within a figure-kind fence, `ctx.caption.imagesRemaining` counts down
+ * one picture at a time; the picture that brings it to zero is the last one in
+ * document order, and only that one carries the caption and the anchor. Every
+ * other picture in the group draws with no caption at all. Attaching the label
+ * to each of them would print the same text under every picture and emit the
+ * same Typst label more than once, which Typst refuses to compile.
  *
  * @param {object} token - An `image` token.
  * @param {object} ctx - Render context.
  * @returns {string} Typst markup.
  */
 function renderImage(token, ctx) {
-    const alt = token.content || token.attrGet?.("alt") || "";
-    // Only a genuine figure caption labels the image inline — a caption
-    // reclassified as prose, because something besides the image shares its
-    // block, gets its label from the generic block-level caption print in
-    // {@link markdownToTypst} instead, the same as a code or prose caption
-    // always has. Reading it here regardless of kind printed the label twice.
-    const figureCaption = ctx.caption?.kind === "figure" ? ctx.caption : null;
-    const captionText = figureCaption ? captionMarkup(figureCaption, ctx) : escapeTypst(alt);
+    const figureCaption =
+        ctx.caption?.kind === "figure" || ctx.caption?.kind === "map" ? ctx.caption : null;
+    const remaining = figureCaption?.imagesRemaining;
+    const isLastImage = !remaining || --remaining.n <= 0;
+    const labelled = Boolean(figureCaption) && isLastImage;
+    const captionText = labelled ? captionMarkup(figureCaption, ctx) : "";
     const caption = captionText ? `[${captionText}]` : "none";
-    const anchor =
-        figureCaption ? ` <${sectionLabel(ctx.anchorPrefix, slugify(figureCaption.id))}>` : "";
-    const staged = ctx.images.get(token.attrGet?.("src") ?? "");
+    const anchor = labelled ? typstAnchor(ctx.anchorPrefix, figureCaption) : "";
+    const src = token.attrGet?.("src") ?? "";
+    const staged = ctx.images.get(src);
     if (!staged)
         return captionText ?
                 `\n#block(below: 0.6em)[#text(size: 7.6pt, style: "italic", fill: luma(45%))${caption}]${anchor}\n\n`
             :   "";
 
-    const size = BOOK_IMAGE_WIDTHS[token.meta?.size] ?? BOOK_IMAGE_WIDTHS.auto;
+    // A named `size=` is the author's own statement and wins outright. Left
+    // unstated — `auto`, written or implied — the picture's role or its icon
+    // type decides instead, and only a picture declaring neither falls back to
+    // the natural-pixel `auto` Typst resolves for itself.
+    const requestedSize = token.meta?.size;
+    const roleWidthIn =
+        requestedSize && requestedSize !== "auto" ?
+            undefined
+        :   bookImageWidthIn(ctx.assets?.get(src));
+    const size =
+        roleWidthIn !== undefined ?
+            typstInches(roleWidthIn)
+        :   (BOOK_IMAGE_WIDTHS[requestedSize] ?? BOOK_IMAGE_WIDTHS.auto);
     const figure = `#book-image("${escapeTypstString(staged)}", requested: ${size}, caption: ${caption})${anchor}`;
 
     const width = token.meta?.classes?.[0];

package/engine/scenes.mjs

@@ -80,7 +80,7 @@ import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.m
 import { buildItineraryScenes } from "./itinerary-scenes.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { rasterizeMapSvg } from "./map-raster.mjs";
-import { artPathname, artSlot } from "./art-fields.mjs";
+import { artPathname, artSlot, pathnameRoles } from "./art-fields.mjs";
 import { buildExportedScene } from "./exported-scene.mjs";
 
 /**
@@ -395,11 +395,15 @@ export class Scenes extends BasePackCompiler {
      * @param {string} markdown - The converted body.
      * @param {string} entryId - The JournalEntry's id.
      * @param {string} name - The map's name (its lead page).
+     * @param {(address: string) => string|undefined} resolveRole - See
+     *   {@link module:engine/journals.splitPages}; threaded through so an
+     *   unanchored map figure's page key agrees with the journal this pass
+     *   derives it against.
      * @returns {Map<string, string>} heading key → page id.
      */
-    #pageIds(markdown, entryId, name) {
+    #pageIds(markdown, entryId, name, resolveRole) {
         const pageIds = new Map();
-        splitPages(markdown, name).forEach((page) => {
+        splitPages(markdown, name, resolveRole).forEach((page) => {
             const id = journalPageId(entryId, page);
             if (page.anchorSlug) pageIds.set(page.anchorSlug, id);
             const slug = slugify(page.name);
@@ -439,6 +443,12 @@ export class Scenes extends BasePackCompiler {
     compileNote(fm, markdown) {
         const name = resolveName(fm);
         const hasBody = Boolean(String(markdown).trim());
+        // The markdown this pass reads has already had its embeds rewritten
+        // into ordinary images, each `src` the pathname `pathnameRoles` keys
+        // its roles by — see {@link module:engine/journals.Journals#buildEntry},
+        // which derives this same journal's pages the same way.
+        const roles = pathnameRoles(this.linkIndex);
+        const resolveRole = (pathname) => roles.get(pathname);
         // The same doc-entry id the journals pass derives, from the
         // shared `docEntryTypes` arrangement — so neither
         // pass has to read the other's output.
@@ -511,7 +521,8 @@ export class Scenes extends BasePackCompiler {
                         hasBody ?
                             this.#packRouter.resolve(fm, "JournalEntry")
                         :   this.#packRouter.defaultOf("JournalEntry"),
-                    pageIds: hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
+                    pageIds:
+                        hasBody ? this.#pageIds(markdown, entryId, name, resolveRole) : new Map(),
                     knownActions: this.knownActions,
                     warnings,
                     ...this.#resolvers(this.index, this.effectsByAddress, fm.shortcode),
@@ -535,6 +546,7 @@ export class Scenes extends BasePackCompiler {
                     name,
                     markdown,
                     leadName: name,
+                    resolveRole,
                     // As in the journals pass: an address resolves in the
                     // pack that emits it, which is what makes the folder
                     // materialise there too. The id spelling that used

package/engine/site-build.mjs

@@ -64,12 +64,18 @@ import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderBlocks, renderWithheldSections, scanBlocks } from "./content-blocks.mjs";
 import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
-import { renderCaptionBlocks, scanCaptions } from "./content-captions.mjs";
+import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
 import { footnoteFindings } from "./content-footnotes.mjs";
 import { collectAnchors } from "./anchors.mjs";
-import { renderImageFigures } from "./content-images.mjs";
-import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
-import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
+import { checkImages, renderImageFigures } from "./content-images.mjs";
+import { assetPathnameKey, pathnameProblem, resolvePathname } from "./pathnames.mjs";
+import {
+    buildSiteIndex,
+    figureIndexKeys,
+    resolveCrossNoteFigures,
+    resolveInfoboxRef,
+    wikiContext,
+} from "./site-index.mjs";
 import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
@@ -88,7 +94,8 @@ import { isNoteRecord, noteFile } from "./index-records.mjs";
 // The one statement of what an empty body means, shared with the index.
 import { isStubNote } from "./note-state.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
-import { ART_SLOTS, artPathname, assetAddressIndex } from "./art-fields.mjs";
+import { ART_SLOTS, artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
+import { embedRole } from "./content-embeds.mjs";
 import {
     HOMEPAGE_DESTINATION,
     checkHomepageCount,
@@ -699,6 +706,7 @@ export function renderSitePage(
         sqlTables,
         config,
         artIndex,
+        figuresByAddress = new Map(),
     },
 ) {
     const tableErrors = [];
@@ -709,6 +717,7 @@ export function renderSitePage(
     const footnoteErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
+    const embedErrors = [];
     const resolved = [];
     const src = page.relPath ?? page.base;
     const ctx = wikiContext(index, {
@@ -745,10 +754,36 @@ export function renderSitePage(
         return src;
     };
     const artSrc = (value, type, accepts) => artPathname(artIndex, value, type, accepts).pathname;
+    // The role lookup a `:::figure` fence's `map` counter reaches through —
+    // see `engine/content-figures.mjs`'s `resolveRole`. Addressed form, for
+    // the page's own scan below, which runs before an embed is rewritten into
+    // an ordinary image; `roleByWebSrc` is the same lookup keyed by the web
+    // address each picture that reaches `renderImageFigures` resolves to,
+    // recorded as it is resolved rather than built across the whole corpus —
+    // `webSrc` itself reports an image's own problems as a side effect, which
+    // a speculative call over every asset would misfire for one this page
+    // never names.
+    const resolveRole = (address) => embedRole(artIndex, address);
+    const pathRoles = pathnameRoles(artIndex);
+    const roleByWebSrc = new Map();
+    const webSrcWithRole = (src) => {
+        const result = webSrc(src);
+        const role = pathRoles.get(src);
+        if (role) roleByWebSrc.set(result, role);
+        return result;
+    };
+    // The picture's role and pixel size, by the address it resolved to — read
+    // before `webSrc` translates it to the page's own host. A body image is
+    // free to write the bare, own-package form, so the address is normalized
+    // to the pathname the asset index keys by first.
+    const lookupAsset = (src) => {
+        const key = assetPathnameKey(src, config);
+        return key ? artIndex?.byPath?.get(key) : undefined;
+    };
     const resolve = (text) => {
         let transformed = pass.beforeLinks ? pass.beforeLinks(text, page) : text;
         transformed = resolveWebWikilinks(transformed, ctx);
-        return renderImageFigures(transformed, webSrc);
+        return renderImageFigures(transformed, webSrcWithRole, lookupAsset);
     };
 
     const { markdown, errors, lineMap } = expandContentTables(page.body, {
@@ -760,8 +795,21 @@ export function renderSitePage(
         self: { fm: searchableFrontmatter(page.fm, page.pkg), path: page.relPath },
     });
     tableErrors.push(...errors);
-    const captionScan = scanCaptions(markdown);
-    ctx.captionLabels = new Map(captionScan.captions.map((caption) => [caption.id, caption.label]));
+    const figureScan = scanFigures(markdown, { resolveRole });
+    ctx.captionLabels = new Map(
+        figureScan.figures.filter((figure) => figure.id).map((figure) => [figure.id, figure.label]),
+    );
+    // What the `ref` expression helper needs beyond the label: the caption
+    // text and whether one was authored, by the same id `ctx.captionLabels`
+    // keys on.
+    const figuresById = new Map(
+        figureScan.figures
+            .filter((figure) => figure.id)
+            .map((figure) => [
+                figure.id,
+                { label: figure.label, caption: figure.caption, hasCaption: figure.hasCaption },
+            ]),
+    );
     // This page's own anchors, so a `[[#slug]]` self-link is checked against
     // what the page actually declares rather than trusted unconditionally.
     ctx.anchors = new Set(collectAnchors(markdown).map((anchor) => anchor.slug));
@@ -771,12 +819,29 @@ export function renderSitePage(
         file: page.file,
         bodyLine: page.bodyLine,
         sqlResults: sqlTables?.inline?.get(page.file),
+        figures: {
+            get: (id) => figuresById.get(id),
+            // A cross-note `ref` resolves the written address exactly as a
+            // wikilink does, against every page's figures scanned before any
+            // page's expressions render — see `renderPages`.
+            note: (target) =>
+                resolveCrossNoteFigures(target, {
+                    contentTypes: index.contentTypes,
+                    packages: index.packages,
+                    noIndexPackages: index.noIndexPackages,
+                    contentPackage: index.contentPackage,
+                    siteIndexMap: index.index,
+                    figuresByAddress,
+                }),
+        },
     });
     expressionErrors.push(...expressions.findings);
     const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
     const blocks = renderBlocks(protectCode(expressions.markdown, resolve), "web");
-    const captioned = renderCaptionBlocks(blocks.markdown);
-    for (const error of captionScan.errors)
+    const figured = renderFigureBlocks(blocks.markdown, undefined, undefined, {
+        resolveRole: (address) => roleByWebSrc.get(address),
+    });
+    for (const error of figureScan.errors)
         captionErrors.push({
             file: page.file,
             line: (page.bodyLine ?? 1) + (lineMap[error.line - 1]?.line ?? error.line - 1),
@@ -801,12 +866,18 @@ export function renderSitePage(
             column: error.column,
             message: error.message,
         });
+    // An image sharing its paragraph with other text, or an address or title
+    // the lint already refuses — asked here too, so a site build run on its
+    // own fails on the same input `renderImageFigures` otherwise renders as
+    // though the directive were absent.
+    for (const error of checkImages(page.body, page.file, { bodyLine: page.bodyLine ?? 1 }))
+        embedErrors.push(error);
     return {
         page,
         // The disclosure is written last, over the Markdown the page ships: the
         // passes before this one carry line positions into their findings, and a
         // line inserted ahead of them would move every one of them.
-        body: renderWithheldSections(captioned.markdown),
+        body: renderWithheldSections(figured.markdown),
         data,
         resolved,
         tableErrors,
@@ -817,6 +888,7 @@ export function renderSitePage(
         footnoteErrors,
         wikiErrors,
         imageErrors,
+        embedErrors,
     };
 }
 
@@ -855,7 +927,7 @@ export function renderSitePage(
  *   it by wikilink, and its own markdown links name content pages. `maps` is
  *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   related: Map<string, import("./related-pages.mjs").Related>,
  *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
@@ -888,6 +960,38 @@ export function renderPages(pages, options) {
         types: index?.contentTypes ?? [],
     });
 
+    // Every page's own figures, by the address a `ref` crossing into it would
+    // write — scanned once, before any page's own expressions render, so a
+    // page citing another's figure finds it already numbered. Numbering stays
+    // per page: each `scanFigures` call here starts its own counters, exactly
+    // as the page's own render does, so the number a cross-note `ref` reports
+    // is the one the target's own page carries.
+    const figuresByAddress = new Map();
+    for (const page of pages) {
+        const shortcode = page.fm.shortcode;
+        if (typeof shortcode !== "string" || !shortcode) continue;
+        const src = page.relPath ?? page.base;
+        const { markdown } = expandContentTables(page.body, {
+            docs: universe.get(page.pkg) ?? [],
+            linkable,
+            source: src,
+            sqlTables: sqlTables?.get(page.file),
+            pageLists: sqlTables?.pageLists?.get(page.file),
+            self: { fm: searchableFrontmatter(page.fm, page.pkg), path: page.relPath },
+        });
+        const byId = new Map(
+            scanFigures(markdown)
+                .figures.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);
+    }
+
     const tableErrors = [];
     const expressionErrors = [];
     const secretErrors = [];
@@ -896,6 +1000,7 @@ export function renderPages(pages, options) {
     const footnoteErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
+    const embedErrors = [];
     const byKind = {};
     // The link graph, as `(source URL, target URL)` — read off each page's
     // resolution below, and off the homepage's markdown links.
@@ -932,6 +1037,7 @@ export function renderPages(pages, options) {
             sqlTables,
             config,
             artIndex,
+            figuresByAddress,
         });
         tableErrors.push(...result.tableErrors);
         expressionErrors.push(...result.expressionErrors);
@@ -941,6 +1047,7 @@ export function renderPages(pages, options) {
         footnoteErrors.push(...result.footnoteErrors);
         wikiErrors.push(...result.wikiErrors);
         imageErrors.push(...result.imageErrors);
+        embedErrors.push(...result.embedErrors);
         rendered.push({ page, body: result.body, data: result.data });
         for (const hit of result.resolved) if (hit.url) edges.push([page.url, hit.url]);
     }
@@ -986,6 +1093,7 @@ export function renderPages(pages, options) {
         footnoteErrors,
         wikiErrors,
         imageErrors,
+        embedErrors,
         related,
         maps: withMap,
         ...(capture ? { ...(outputs ? { outputs } : {}), edges, entries } : {}),
@@ -1036,6 +1144,7 @@ export function sitePageDecorator(config, index) {
             resolve: (ref, hint) => resolveInfoboxRef(index, ref, hint),
             router,
             dates: index.dateContext,
+            contentPackage: index.contentPackage,
         });
     };
 }
@@ -1057,7 +1166,8 @@ export function sitePageDecorator(config, index) {
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
+ *   mapFindings: object[],
  *   manifests: object|null}} `mapFindings` is what drawing the maps found —
  *   warnings, never a reason to fail the build.
  */
@@ -1156,6 +1266,7 @@ export function buildSite({ config, sqlTables } = {}) {
             footnoteErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            embedErrors: [],
             mapFindings: [],
             stats: null,
         };
@@ -1180,6 +1291,7 @@ export function buildSite({ config, sqlTables } = {}) {
             footnoteErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            embedErrors: [],
             mapFindings: [],
             stats: {
                 homepages: writeHomepages(homeRoot, homepages, resolved),
@@ -1230,6 +1342,7 @@ export function buildSite({ config, sqlTables } = {}) {
             footnoteErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            embedErrors: [],
             mapFindings: [],
         };
     }
@@ -1290,6 +1403,7 @@ export function buildSite({ config, sqlTables } = {}) {
         footnoteErrors: rendered.footnoteErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
+        embedErrors: rendered.embedErrors,
         mapFindings: drawn.findings,
         stats: {
             ...rendered.byKind,