@heroiclands/package-build 22.22.0 → 22.24.0

package/engine/foreign-catalog.mjs

@@ -38,6 +38,12 @@
  * local pack's output — the resolution logic needs no knowledge of where an
  * item came from.
  *
+ * `assetArchive: true` is the sibling flag, for a dependency whose bytes are
+ * wanted and whose items are not: an asset-replacement source such as
+ * `thalornaaltart` ships no Item packs at all. It unpacks the same release
+ * archive without extracting anything from it, so a relationship declaring
+ * both flags on one entry is fetched once rather than twice.
+ *
  * **The network is never touched by a compile.** Fetching is its own command
  * (`package-build deps fetch`), and a compile whose cache is cold fails saying
  * so. A build that silently downloads is not reproducible, fails strangely
@@ -56,7 +62,6 @@ import os from "node:os";
 import path from "node:path";
 
 import { unzipSync } from "fflate";
-import { extractPack } from "@foundryvtt/foundryvtt-cli";
 
 import log from "loglevel";
 
@@ -73,17 +78,22 @@ import {
 const STAMP = ".complete";
 
 /**
- * Every declared relationship that opted into supplying an item catalogue.
+ * Every declared relationship carrying a given flag, in declaration order.
+ *
+ * Shared by {@link itemCatalogRelationships} and
+ * {@link assetArchiveRelationships}: both read the same shape out of the same
+ * walk, filtered on a different key.
  *
  * @param {object} config - The resolved build configuration.
+ * @param {"itemCatalog"|"assetArchive"} flag - Which boolean to filter on.
  * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
- *   The opted-in relationships, in declaration order.
+ *   The opted-in relationships.
  */
-export function itemCatalogRelationships(config) {
+function flaggedRelationships(config, flag) {
     const out = [];
     for (const [kind, entries] of Object.entries(config.relationships ?? {})) {
         for (const rel of entries ?? []) {
-            if (rel.itemCatalog) {
+            if (rel[flag]) {
                 out.push({
                     id: rel.id,
                     manifest: rel.manifest,
@@ -96,6 +106,29 @@ export function itemCatalogRelationships(config) {
     return out;
 }
 
+/**
+ * Every declared relationship that opted into supplying an item catalogue.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
+ *   The opted-in relationships, in declaration order.
+ */
+export function itemCatalogRelationships(config) {
+    return flaggedRelationships(config, "itemCatalog");
+}
+
+/**
+ * Every declared relationship that opted into supplying its release archive
+ * for asset bytes alone, with no item catalogue built from it.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
+ *   The opted-in relationships, in declaration order.
+ */
+export function assetArchiveRelationships(config) {
+    return flaggedRelationships(config, "assetArchive");
+}
+
 /**
  * The cache directory for one dependency at one version.
  *
@@ -292,6 +325,8 @@ async function extractItemPacks(id, version, manifest, root, dir) {
                 `cannot supply an item catalogue`,
         );
     }
+    // Loaded here so importing the content index does not load the extractor.
+    const { extractPack } = await import("@foundryvtt/foundryvtt-cli");
     for (const pack of itemPacks) {
         const src = resolvePackPath(root, pack.path);
         if (!src) {
@@ -366,15 +401,21 @@ export function pinnedManifestUrl(url, verified) {
 }
 
 /**
- * Fetch one dependency and extract its Item packs.
- *
- * Idempotent: a complete cache for the resolved version is left alone.
- *
- * @param {object} config - The resolved build configuration.
- * @param {{id: string, manifest: string}} rel - The declared relationship.
- * @returns {Promise<string>} The dependency's cache directory.
+ * Resolve a dependency's manifest, pinned to `compatibility.verified` the way
+ * both fetch paths require.
+ *
+ * Shared by {@link fetchCatalog} and {@link fetchAssetArchive}: both read the
+ * same manifest before deciding what to unpack from it.
+ *
+ * @param {{id: string, manifest: string, verified?: string}} rel - The
+ *   declared relationship.
+ * @param {string} subject - What floats when no version is verified —
+ *   "catalogue" or "archive" — named in the warning a reader would otherwise
+ *   get no word for.
+ * @returns {Promise<{manifest: object, version: string}>} The manifest and
+ *   its resolved version.
  */
-export async function fetchCatalog(config, rel) {
+async function resolveManifest(rel, subject) {
     const { url, pinned } = pinnedManifestUrl(rel.manifest, rel.verified);
     const manifest = await fetchManifest(url);
     const version = manifest.version;
@@ -391,10 +432,24 @@ export async function fetchCatalog(config, rel) {
     }
     if (!rel.verified) {
         log.warn(
-            `${rel.id}: no \`compatibility.verified\`, so its catalogue floats ` +
+            `${rel.id}: no \`compatibility.verified\`, so its ${subject} floats ` +
                 `with whatever ${url} currently serves`,
         );
     }
+    return { manifest, version };
+}
+
+/**
+ * Fetch one dependency and extract its Item packs.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string}} rel - The declared relationship.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export async function fetchCatalog(config, rel) {
+    const { manifest, version } = await resolveManifest(rel, "catalogue");
     const dir = catalogDir(config, rel.id, version);
     if (isComplete(dir)) {
         log.info(`${rel.id}@${version}: already cached`);
@@ -420,6 +475,61 @@ export async function fetchCatalog(config, rel) {
     return dir;
 }
 
+/**
+ * Whether an asset-archive-only cache is present and complete.
+ *
+ * No item catalogue is built on this path, so completeness never asks for
+ * `item-packs.json` — an asset-only dependency, such as `thalornaaltart`,
+ * ships none.
+ *
+ * @param {string} dir - The dependency's cache directory.
+ * @returns {boolean} True when the archive was fetched to completion.
+ */
+const isArchiveComplete = (dir) => fs.existsSync(path.join(dir, STAMP));
+
+/**
+ * Fetch one dependency's release archive for its asset bytes alone, building
+ * no item catalogue from it.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone. Where a
+ * relationship also declares `itemCatalog: true`, {@link fetchCatalog} already
+ * unpacked this same archive into this same cache directory, and
+ * {@link fetchAllCatalogs} does not call this function for it — the two never
+ * download the same bytes twice.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string, verified?: string}} rel - The
+ *   declared relationship.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export async function fetchAssetArchive(config, rel) {
+    const { manifest, version } = await resolveManifest(rel, "archive");
+    const dir = catalogDir(config, rel.id, version);
+    if (isArchiveComplete(dir)) {
+        log.info(`${rel.id}@${version}: already cached`);
+        return dir;
+    }
+
+    const download = manifest.download;
+    if (!download) {
+        throw new Error(`${rel.id}@${version}: its manifest declares no \`download\``);
+    }
+
+    // Rebuild from empty: a previous run may have died partway, and a stale
+    // half-tree is worse than no tree.
+    fs.rmSync(dir, { recursive: true, force: true });
+    const raw = path.join(dir, "package");
+    fs.mkdirSync(raw, { recursive: true });
+
+    log.info(`${rel.id}@${version}: downloading ${download}`);
+    await downloadAndUnzip(download, raw);
+
+    cacheSchemaArtifact(raw, dir);
+    // Last, so a fetch that died partway is never mistaken for a complete one.
+    fs.writeFileSync(path.join(dir, STAMP), `${version}\n`);
+    return dir;
+}
+
 /**
  * Locate a declared pack inside an unpacked archive.
  *
@@ -700,17 +810,33 @@ export async function fetchAllMetadata(config) {
 /**
  * Fetch every opted-in dependency. The `deps fetch` command.
  *
+ * A relationship declaring both `itemCatalog: true` and `assetArchive: true`
+ * is fetched once: {@link fetchCatalog} already unpacks the archive on its
+ * way to extracting the item catalogue, so this skips the archive-only fetch
+ * for any id {@link fetchCatalog} already handled.
+ *
  * @param {object} config - The resolved build configuration.
  * @returns {Promise<number>} How many dependencies were fetched.
  */
 export async function fetchAllCatalogs(config) {
-    const rels = itemCatalogRelationships(config);
-    if (!rels.length) {
-        log.info("No relationship declares `itemCatalog: true`; nothing to fetch.");
+    const itemRels = itemCatalogRelationships(config);
+    const archiveRels = assetArchiveRelationships(config);
+    if (!itemRels.length && !archiveRels.length) {
+        log.info(
+            "No relationship declares `itemCatalog: true` or `assetArchive: true`; " +
+                "nothing to fetch.",
+        );
         return 0;
     }
-    for (const rel of rels) await fetchCatalog(config, rel);
-    return rels.length;
+    for (const rel of itemRels) await fetchCatalog(config, rel);
+    const alreadyFetched = new Set(itemRels.map((rel) => rel.id));
+    let archiveFetched = 0;
+    for (const rel of archiveRels) {
+        if (alreadyFetched.has(rel.id)) continue;
+        await fetchAssetArchive(config, rel);
+        archiveFetched++;
+    }
+    return itemRels.length + archiveFetched;
 }
 
 /**

package/engine/frontmatter-lint.mjs

@@ -64,10 +64,12 @@ import {
 } from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { addressPositions } from "./note-addresses.mjs";
-import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
+import { authoredFields, readsLegacyKey, readsRetiredTopLevel } from "./field-spec.mjs";
 import {
     legacyKeyOf,
+    resolveDataProperty,
     resolveFieldValue,
+    retiredTopLevelKey,
     systemBlock,
     SYSTEM_BLOCK_KEYS,
     unknownBlockKeys,
@@ -101,6 +103,7 @@ import {
     legacyKeyMessage,
     readAliasedField,
     retiredAliasMessage,
+    retiredTopLevelMessage,
     sectionRetiredMessage,
     traitsRetiredMessage,
 } from "./retired-fields.mjs";
@@ -137,6 +140,19 @@ export const UNIVERSAL_KEYS = Object.freeze(
     new Set(["packFolder", "pack", "archetype", "templatePriority", "kbcat"]),
 );
 
+/**
+ * The shared `data:` keys declared for every note type that still have a
+ * retiring top-level spelling — `pack` and `packFolder`, the two
+ * {@link module:engine/note-vocabulary.SHARED_DATA_FIELDS} entries
+ * {@link module:engine/system-block.resolveDataProperty} reads off a tree's
+ * bare top level. Unlike a type's own declarations, which the retiring set
+ * below derives from `schemas`, these apply to every type at once, so they
+ * are named once here rather than attached to one type's vocabulary.
+ *
+ * @type {readonly string[]}
+ */
+const UNIVERSAL_RETIRING_DATA_KEYS = Object.freeze(["pack", "packFolder"]);
+
 /**
  * The system blocks a build checks, and what each accepts beyond the shared
  * vocabulary.
@@ -511,6 +527,9 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
             message:
                 type === "affiliation" && key === "commonSkills" ?
                     "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
+                : type === "lore" && key === "event" ?
+                    "`data.event` is retired — write `data.events`, a list of occurrences, " +
+                    "instead, each `{ when, until?, recurs? }`; a note may state several"
                 :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
                     `the container is closed, so the key reaches no document ` +
                     `and no page` +
@@ -1209,6 +1228,22 @@ export function lintNote(
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+
+    // The keys the closed top-level region refuses in general, but a
+    // declaration still reads at the retiring position — this type's own
+    // fields, which `resolveFieldValue`'s step 3b resolves, plus `pack` and
+    // `packFolder`, declared for every type and resolved the same way by
+    // {@link resolveDataProperty}. Derived ahead of the schema lookup below,
+    // which runs after the closed-region check, so that check can skip
+    // exactly these and nothing else: a key no declaration names stays
+    // refused.
+    const retiringTopLevelKeys = new Set([
+        ...UNIVERSAL_RETIRING_DATA_KEYS,
+        ...authoredFields(schemas?.[currentType(type)] ?? [])
+            .filter((field) => field.topLevelMeans === undefined)
+            .map((field) => retiredTopLevelKey(field))
+            .filter((key) => key !== undefined),
+    ]);
     if (type === "being") {
         const archetypes = fm.data?.archetypes;
         if (
@@ -1589,6 +1624,9 @@ export function lintNote(
 
     for (const key of authoredNoteKeys(raw())) {
         if (NOTE_TOP_LEVEL_KEY_SET.has(key)) continue;
+        // Reported below, as the retiring position it is rather than a key
+        // nobody recognises.
+        if (retiringTopLevelKeys.has(key)) continue;
         const position = positionInFrontmatter(raw(), key, undefined, { topLevel: true });
         if (
             findings.some(
@@ -1610,6 +1648,28 @@ export function lintNote(
         });
     }
 
+    // `pack` and `packFolder` are declared for every type, so each is
+    // checked once here rather than in the per-type `fields` loop below,
+    // which only iterates a type's own declarations. A **warning**, for the
+    // reason the per-type retiring position above is one: the note compiles
+    // to the correct document either way, so failing a build over it would
+    // red a tree that has done nothing wrong yet. Checked against every
+    // configured system block, because `resolveDataProperty` reads a
+    // system's own override before the top level, and a note may configure
+    // more than one.
+    for (const key of UNIVERSAL_RETIRING_DATA_KEYS) {
+        const retiring = Object.keys(systems ?? {}).some(
+            (blockName) => resolveDataProperty(fm, blockName, key).from === "topLevel",
+        );
+        if (!retiring) continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message: retiredTopLevelMessage({ name: `data.${key}` }),
+        });
+    }
+
     // The type's charset, before anything that looks the type up. A
     // hyphenated type is unaddressable, and every lookup below would report it
     // as a type nobody declared — true, but not the reason, and it would send
@@ -1827,6 +1887,18 @@ export function lintNote(
                 message: legacyKeyMessage("sohl", field),
             });
         }
+        // `readsLegacyKey`'s sibling for the other retiring position — the
+        // note's own top level, which `data:` gathered the fact off. Also a
+        // **warning**: the closed-region check above already let this exact
+        // key through for this exact reason, and the two must agree.
+        if (readsRetiredTopLevel(field, from)) {
+            findings.push({
+                file: note.file,
+                ...at(retiredTopLevelKey(field)),
+                severity: "warning",
+                message: retiredTopLevelMessage(field),
+            });
+        }
         const absent = from === "default" || value === undefined || value === null;
         // Where the field belongs, as a message names it: a shared field is not
         // under `sohl:`, so telling an author to write `sohl.img` would send

package/engine/heading-attributes.mjs

@@ -7,15 +7,15 @@
  * # The Harbor {#harbor .wide}
  * ```
  *
- * The index, the link checker, the journal compiler, the caption pass and the
+ * The index, the link checker, the journal compiler, the figure pass and the
  * book all ask what a heading declares, and they have to give the same answer:
  * an id a surface publishes as an anchor, classes a surface may honour, and
  * attributes an HTML surface writes onto the element. This is where that
  * reading lives, so there is one grammar — the same one a `:::` block and a
- * `:::caption` are written in.
+ * `:::figure` are written in.
  *
  * **A leaf, deliberately.** `anchors.mjs` is shared by the compilers, the index
- * and the link checker and cannot import any of them; the caption pass is
+ * and the link checker and cannot import any of them; the figure pass is
  * imported by `anchors.mjs` and so cannot import it back. A module that imports
  * only the attribute grammar can be asked by all of them.
  *
@@ -38,7 +38,7 @@ const SUFFIX = /^(.*?)\s*\{([^}\n]*)\}\s*$/;
 /**
  * A heading's id.
  *
- * Looser than a caption's or a block's, which must begin with a letter: a
+ * Looser than a figure's or a block's, which must begin with a letter: a
  * heading's id is published as an HTML `id` and as a Foundry page anchor, both
  * of which admit a digit first, and the corpus carries ids that are Foundry
  * document ids and ids derived from a numbered heading.
@@ -108,9 +108,9 @@ export const WITHHELD_CLASS = "secret";
  * A Foundry UUID addresses a page and nothing smaller, so a section a link can
  * reach has to be one: a top-level heading starts a page, and so does any
  * heading that names an anchor. {@link module:engine/journals.splitPages}
- * decides *where* a page begins — a captioned heading and a heading inside a
- * fence or a named block are its business — and asks this which headings are
- * eligible, so no caller re-decides it.
+ * decides *where* a page begins — a heading inside a fence or a named block is
+ * its business — and asks this which headings are eligible, so no caller
+ * re-decides it.
  *
  * @param {{level: number, id: string}} heading - From
  *   {@link scanHeadingAttributes}, or any `{level, id}` pair.
@@ -204,7 +204,7 @@ export function headingAttributesPlugin(md) {
  * Parse one line as a heading, and say whether it starts a journal page.
  *
  * The single reading of that rule. {@link module:engine/journals.splitPages}
- * builds its pages from it; `scanBlocks` and `scanCaptions` refuse a heading
+ * builds its pages from it; `scanBlocks` and `scanFigures` refuse a heading
  * that starts a page written where it cannot become one. All three ask this, so
  * none of them can disagree about what a heading line means or about what starts
  * a page — and the attribute block comes off here, so a class beside an anchor
@@ -240,24 +240,37 @@ export function parseHeadingLine(line) {
  * builds the pages from this, and the passes that honour a class on a
  * page-opening heading ask the same question of the same answer.
  *
- * A caption also opens a page, which is `splitPages`' business: a caption is
- * found by the caption pass, and a heading it captions is listed here and
- * dropped there.
+ * A figure fence also opens a page, which is `splitPages`' business: a fence is
+ * found by the figure pass, and the page it opens is named for its label.
  *
  * @param {string} source - A note's markdown body.
+ * @param {ReadonlySet<number>} [blockLines] - The 0-based lines sitting inside
+ *   a named block, supplied by the caller. A named block is read by
+ *   {@link module:engine/content-blocks.scanBlocks}, which knows every name in
+ *   the registry, reads an opener's attribute block, and tracks nesting by
+ *   depth — so the caller that already holds that answer passes it rather than
+ *   a second reading of the same lines being kept here.
  * @returns {Map<number, {level: number, line: number, text: string, id: string,
  *   classes: string[], values: Record<string, string>}>} Keyed by 0-based line.
  */
-export function pageOpenings(source) {
+export function pageOpenings(source, blockLines = new Set()) {
     const lines = String(source ?? "").split("\n");
     const openings = new Map();
-    let inCodeBlock = false;
-    let inBlock = false;
+    let codeFence = null;
     for (const [index, line] of lines.entries()) {
-        if (line.trim().startsWith("```")) inCodeBlock = !inCodeBlock;
-        if (!inCodeBlock && /^:::secret[ \t]*$/.test(line)) inBlock = true;
-        else if (!inCodeBlock && /^:::[ \t]*$/.test(line)) inBlock = false;
-        if (inCodeBlock || inBlock) continue;
+        // A fence's closer must carry the same character as its opener and
+        // be at least as long, same as {@link scanHeadingAttributes} tracks
+        // it below — a longer fence is what lets a fenced example carry a
+        // shorter fence of its own as literal content.
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+        } else if (fence) {
+            codeFence = fence[1];
+        }
+        if (codeFence !== null || blockLines.has(index)) continue;
         const heading = parseHeadingLine(line);
         if (!heading?.startsPage) continue;
         openings.set(index, { ...heading, line: index + 1 });

package/engine/helpers.mjs

@@ -42,8 +42,15 @@ import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 import { iconPlugin } from "./content-icons.mjs";
 import { imagePlugin, imagesIn } from "./content-images.mjs";
-import { resolveEmbeds } from "./content-embeds.mjs";
-import { foundryAddressProblem, pathnameProblem, resolvePathname } from "./pathnames.mjs";
+import { embedRole, resolveEmbeds } from "./content-embeds.mjs";
+import { collectAssetRecords } from "./asset-index.mjs";
+import { assetImageInfoByPathname } from "./art-fields.mjs";
+import {
+    assetPathnameKey,
+    foundryAddressProblem,
+    pathnameProblem,
+    resolvePathname,
+} from "./pathnames.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -67,7 +74,7 @@ import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderBlocks } from "./content-blocks.mjs";
 import { headingAttributesPlugin } from "./heading-attributes.mjs";
-import { renderCaptionBlocks, scanCaptions } from "./content-captions.mjs";
+import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
 import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
@@ -84,6 +91,9 @@ export {
     parseValueDesc,
 } from "./frontmatter.mjs";
 
+/** @type {Map<string, object>|undefined} */
+let localAssetImageInfoCache;
+
 /**
  * The markdown renderer every surface shares.
  *
@@ -117,25 +127,65 @@ export const md = markdownit({ html: true })
     // serves a file from inside the install, so a body image's address is
     // translated by the same rule `img:` follows.
     .use(
-        imagePlugin((src) => {
-            // **Reported upstream, never here.** A renderer has no channel to
-            // report through, and this one runs inside the very passes whose
-            // job is to collect findings — a throw would take the whole lint
-            // down and lose every other finding in the tree. So nothing reaches
-            // this point unreported: {@link convertNoteWikilinks} refuses a body
-            // image with no address inside the install before a compiler renders
-            // one, and the address passes report the same pathname with a line
-            // and a column. What is left here is a fallback for a caller with no
-            // configuration to resolve against, where the authored pathname is
-            // the most honest thing to emit.
-            try {
-                return resolveImg(src, loadPackConfig()) ?? src;
-            } catch {
-                return src;
-            }
-        }),
+        imagePlugin(
+            (src) => {
+                // **Reported upstream, never here.** A renderer has no channel to
+                // report through, and this one runs inside the very passes whose
+                // job is to collect findings — a throw would take the whole lint
+                // down and lose every other finding in the tree. So nothing reaches
+                // this point unreported: {@link convertNoteWikilinks} refuses a body
+                // image with no address inside the install before a compiler renders
+                // one, and the address passes report the same pathname with a line
+                // and a column. What is left here is a fallback for a caller with no
+                // configuration to resolve against, where the authored pathname is
+                // the most honest thing to emit.
+                try {
+                    return resolveImg(src, loadPackConfig()) ?? src;
+                } catch {
+                    return src;
+                }
+            },
+            (src) => {
+                // A body image is free to write the bare, own-package form,
+                // so the address is normalized to the pathname the cache
+                // below keys by before it is looked up.
+                try {
+                    const key = assetPathnameKey(src, loadPackConfig());
+                    return key ? localAssetImageInfo().get(key) : undefined;
+                } catch {
+                    return undefined;
+                }
+            },
+        ),
     );
 
+/**
+ * The pictures this package's own tree ships, by the pathname their address
+ * resolves to — read lazily and cached for the process, exactly as
+ * {@link loadPackConfig} is, since one compile reads one tree once.
+ *
+ * **Local only.** A picture embedded from a dependency carries no role or
+ * pixel size here: fetching a foreign package's own asset index to size one
+ * inline Foundry image is a cost this lazy cache does not pay, and the
+ * picture simply draws at the medium's ordinary size, as it always has.
+ *
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ */
+function localAssetImageInfo() {
+    if (localAssetImageInfoCache) return localAssetImageInfoCache;
+    try {
+        const config = loadPackConfig();
+        const records = collectAssetRecords(config.paths.assets, {
+            contentPackage: config.contentPackage,
+            problems: [],
+        });
+        localAssetImageInfoCache = assetImageInfoByPathname(records);
+    } catch {
+        localAssetImageInfoCache = new Map();
+    }
+    return localAssetImageInfoCache;
+}
+
 md.renderer.rules.footnote_block_open = () =>
     '<section class="footnotes"><h2>Footnotes</h2><ol class="footnotes-list">\n';
 md.renderer.rules.footnote_caption = (tokens, idx, _options, env) => {
@@ -155,11 +205,26 @@ md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
     return `<li id="fn${id}" class="footnote-item" value="${number}">`;
 };
 
-/** Render a note body with Foundry's named-block markup. */
-export function renderFoundryMarkdown(body, captions, footnoteNumbers, docId) {
+/**
+ * Render a note body with Foundry's named-block markup.
+ *
+ * @param {string} body - The body, tables expanded and wikilinks resolved.
+ * @param {Array<{id: string, label: string}>} [figures] - Labels assigned by
+ *   a note-wide scan, matched by id — see
+ *   {@link module:engine/content-figures.renderFigureBlocks}.
+ * @param {Map<string, number>} [footnoteNumbers] - Shared across the note.
+ * @param {string} [docId] - Threaded into footnote anchors.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares — see
+ *   {@link module:engine/content-figures.scanFigures}.
+ * @returns {string} The rendered HTML.
+ */
+export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, resolveRole) {
     const blocks = renderBlocks(body, "foundry");
-    const captioned = renderCaptionBlocks(blocks.markdown, (block) => md.render(block), captions);
-    return md.render(captioned.markdown, { footnoteNumbers, docId });
+    const figured = renderFigureBlocks(blocks.markdown, (block) => md.render(block), figures, {
+        resolveRole,
+    });
+    return md.render(figured.markdown, { footnoteNumbers, docId });
 }
 
 /**
@@ -545,16 +610,18 @@ export function makeFilename(name, id) {
  * the other.
  *
  * **`title` does not follow this rule**, and must not be made to. On a
- * `type: affiliation` note `title` is *also* a declared item field whose default
- * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
- * key the site emitter reads as the page title — so `title: null` stringifies
- * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means.
+ * `type: affiliation` note `title` is a declared item field with its own
+ * default (`""`, in `sohl/item-fields.mjs`), authored only inside the item's
+ * own `sohl` block — the closed top-level vocabulary has no `title` entry, so
+ * there is no shared key for this function's null-versus-blank distinction to
+ * apply to.
  *
  * **`banner:` does not follow it either, deliberately.** It is not a file
- * inside a Foundry install: it reaches no compiled document and no book, its
- * only consumer is the Hugo theme, and the theme resolves it against the site's
- * own asset root. See `docs/content-format.md`.
+ * inside a Foundry install: it reaches no compiled document, and the site build
+ * resolves it through the website's own resolver before a page is written, so
+ * the theme receives a URL rather than an address. The book's section plates
+ * read a banner of their own, from the book plan's `presentation.page.banner`
+ * rather than from a note. See `docs/guides/site.md`.
  *
  * For items, the default is the art paired with the type's builder, reached
  * through `itemArt()`, which runs the pathname back through this function so a
@@ -941,7 +1008,9 @@ export function convertNoteWikilinks(
         docPack,
         index,
         captionLabels: new Map(
-            scanCaptions(source).captions.map((caption) => [caption.id, caption.label]),
+            scanFigures(source, { resolveRole: (address) => embedRole(index, address) })
+                .figures.filter((figure) => figure.id)
+                .map((figure) => [figure.id, figure.label]),
         ),
     });
     /**