@heroiclands/package-build 21.1.0 → 22.0.0

package/engine/pathnames.mjs

@@ -93,6 +93,8 @@
  * @module
  */
 
+import { PACKAGEBUILD_PACKAGE } from "./packages.mjs";
+
 /**
  * The directory a package ships its files in, and the segment that marks a
  * pathname's first segment as a package name.
@@ -220,6 +222,78 @@ export function pathnameProblem(raw) {
     );
 }
 
+/**
+ * Whether this build installs anything into a Foundry data directory.
+ *
+ * A `documentation` package compiles no packs and installs nowhere, so no note
+ * of its reaches a Foundry document and no pathname of its can be dead on a
+ * surface it never touches. A check that reports a missing Foundry address asks
+ * this first, so the one kind with no Foundry surface is not told about it.
+ *
+ * Read from {@link packageAddresses} rather than from a key, so "does this
+ * package have a Foundry root?" is answered in one place by the map that
+ * derives every other package's.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {boolean} Whether the package being built has a Foundry root.
+ */
+export function servesFoundry(config) {
+    const own = config?.contentPackage ? packageAddresses(config).get(config.contentPackage) : null;
+    return Boolean(own?.root);
+}
+
+/**
+ * Why a pathname has no Foundry address, or `""` when it has one.
+ *
+ * The sibling of {@link pathnameProblem} one step further on: that one asks
+ * whether a pathname is written correctly at all, and this one asks whether
+ * *this* build can turn a correctly written pathname into a path a Foundry
+ * install serves. Both answer in a sentence rather than a code, so the caller
+ * that holds a line and a column and the caller that holds only a file say the
+ * same thing about the same value.
+ *
+ * `""` for every pathname that resolves — and for the three shapes that
+ * legitimately reach Foundry untranslated: a URL, a protocol-relative
+ * `//host/…`, and a `/`-rooted path Foundry serves from its data root. A blank
+ * pathname is a deliberate blank and resolves to a blank on every surface, so
+ * it is not a problem either.
+ *
+ * `""` as well for a pathname {@link pathnameProblem} already refuses. That
+ * defect has its own finding naming its own replacement, and reporting a second
+ * one about the same characters would send the author to one mistake twice.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function foundryAddressProblem(raw, config) {
+    if (pathnameProblem(raw)) return "";
+    const forms = resolvePathname(raw, config);
+    if (forms === null || forms.foundry !== null) return "";
+    if (forms.package === PACKAGEBUILD_PACKAGE) {
+        return (
+            `\`${forms.authored}\` names a file the \`${PACKAGEBUILD_PACKAGE}\` package ` +
+            "ships, and Foundry installs no package of that name — package-build is an " +
+            "npm dependency of a package rather than a package of its own, so its files " +
+            "reach the website and the book and never a Foundry document. Address a " +
+            "`/`-rooted path or a URL"
+        );
+    }
+    if (forms.own) {
+        return (
+            `\`${forms.authored}\` names a file this package serves, and a ` +
+            "`documentation` package has no asset root to serve it from — Foundry " +
+            "installs no such package. Address a `/`-rooted path or a URL"
+        );
+    }
+    return (
+        `\`${forms.authored}\` names a file the \`${forms.package}\` package ships, and ` +
+        "this build declares no relationship with a package of that name, so there is " +
+        "no Foundry address to derive. Declare it under `relationships`, or address " +
+        "the file by a `/`-rooted path"
+    );
+}
+
 /**
  * Every game system this build compiles content for.
  *

package/engine/pdf-build.mjs

@@ -64,6 +64,20 @@
  * `.typ` source on disk, which is both the diagnostic and the thing a consumer
  * can compile by hand.
  *
+ * ## The faces are the toolchain's and the compiler's, never the machine's
+ *
+ * Every face the book sets resolves from one of two places that travel with the
+ * build: the faces this package ships — see {@link BOOK_FONTS_PATH} — and the
+ * ones the compiler embeds. The compile passes the shipped directory as
+ * `--font-path` and `--ignore-system-fonts` alongside it, so a machine carrying
+ * its own copy of a named family cannot quietly set a different book from the
+ * same source.
+ *
+ * `pdf.fonts.path` is searched as well, so a consumer naming a face of its own
+ * in `pdf.fonts` still resolves it — and a name nothing resolves is reported,
+ * because the compiler says so and a compile that says it still exits 0 with a
+ * book set in the fallback.
+ *
  * @module
  */
 
@@ -71,10 +85,12 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 import YAML from "yaml";
 
 import { loadPackConfig } from "./pack-config.mjs";
+import { routerFor } from "./pack-router.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
@@ -83,6 +99,8 @@ import { parseDocumentTree, runTreeFilters, planDocument } from "./pdf-toc.mjs";
 import { collectContentPages, siteGates, tableUniverse, gatesFailed } from "./site-build.mjs";
 import { resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { resolveWebWikilinks } from "./web-wikilinks.mjs";
+import { linkFindingMessage } from "./wikilink-syntax.mjs";
+import { assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imageSourcesIn } from "./content-images.mjs";
@@ -379,6 +397,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         skipDirectories: resolved.skipDirectories,
         records,
     });
+    // The address space an `![[…]]` embed resolves against — the same one the
+    // site builds, so one authored picture reaches both surfaces or neither.
+    const assets = assetAddressIndex(records, {
+        config: resolved,
+        foreign: gates.foreign,
+        types: gates.index?.contentTypes ?? [],
+    });
     const md = createParser(resolved.icons);
     const glyphs = resolveIconGlyphs(resolved.icons, resolved.pdf.iconFonts, findings);
 
@@ -478,6 +503,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             type: page.fm.type ?? null,
             errors: wikiErrors,
             foreignIndex: gates.foreign.index,
+            assets,
         });
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
@@ -487,7 +513,10 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             findings.push({
                 file: page.file,
                 severity: "warning",
-                message: String(err.message ?? err),
+                // A link finding names a `reason` from the shared table and no
+                // sentence of its own; an embed's directive complaint carries
+                // the sentence instead.
+                message: err.message ?? (err.reason ? linkFindingMessage(err) : String(err)),
             });
         }
         stageImages(resolvedBody, page.file);
@@ -504,6 +533,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         // first, because the image lives in the body and the body follows.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
+            router: routerFor(resolved),
         });
         const panel = infoboxesToTypst(boxes, {
             link: (value) => linkToTypst(value, plan.links, labelFor),
@@ -613,6 +643,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     }
 
     const compiled = compileTypst(typPath, pdfPath, resolved.pdf);
+    findings.push(...compiled.findings);
     if (!compiled.ok) {
         findings.push({ file: typPath, severity: "error", message: compiled.message });
         return { built: false, reason: null, findings, typ: typPath, pdf: null, stats };
@@ -620,24 +651,113 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     return { built: true, reason: null, findings, typ: typPath, pdf: pdfPath, stats };
 }
 
+/**
+ * The faces the book is set in that the compiler does not carry itself.
+ *
+ * Resolved from this module rather than from the working directory, on the same
+ * rule the specification and `--version` follow: a consumer runs the build
+ * inside its own repository, and the faces it sets the book in are the ones
+ * that came with the toolchain version it resolved.
+ *
+ * What is here is the **sans**, in the three styles a heading can ask for, the
+ * superfamily's **mono** for a package that names it, and the licence they
+ * travel under. The serif is not: the compiler embeds one, and a second copy of
+ * a face it already carries is a file nothing selects.
+ *
+ * It is **not** an addressable asset root: the compiler matches a face by
+ * family name, so nothing addresses these files and nothing needs to.
+ *
+ * @type {string}
+ */
+export const BOOK_FONTS_PATH = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "assets",
+    "fonts",
+);
+
+/**
+ * The command line the compile runs, as data.
+ *
+ * Separate from running it so the flags that decide which faces are in play
+ * can be asserted without a compiler installed — which is the half of the
+ * invocation that changes what the book looks like.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string} pdfPath - Where the PDF goes.
+ * @param {object} [pdf] - The resolved `pdf:` block.
+ * @returns {string[]} The arguments, in order.
+ */
+export function typstArgs(typPath, pdfPath, pdf = {}) {
+    // One flag, the paths joined by the platform's separator: the compiler
+    // takes a list, and the shipped faces come first so a consumer's own
+    // directory extends the set rather than standing in for it.
+    const fontPaths = [BOOK_FONTS_PATH];
+    if (pdf.fonts?.path) fontPaths.push(pdf.fonts.path);
+    return [
+        "compile",
+        "--ignore-system-fonts",
+        "--font-path",
+        fontPaths.join(path.delimiter),
+        typPath,
+        pdfPath,
+    ];
+}
+
+/**
+ * The compiler's own warnings, as findings.
+ *
+ * A compile that says `unknown font family` still exits 0 and still writes a
+ * book — one set in whatever face the fallback reached. That is the failure
+ * this surface is least able to see, so the compiler's warnings are read back
+ * and reported on the same terms as everything else the build finds.
+ *
+ * Typst writes a warning as a `warning:` line followed by a `┌─ file:line:col`
+ * locator over a source excerpt. The message and the position are taken; the
+ * excerpt is not, since the reader has the file.
+ *
+ * @param {string} output - What the compiler wrote to stderr.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} One finding per warning.
+ */
+export function typstWarnings(output) {
+    const lines = String(output || "").split("\n");
+    const findings = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const warned = /^warning: (.+)$/.exec(lines[i]);
+        if (!warned) continue;
+        const finding = { file: "", severity: "warning", message: warned[1].trim() };
+        const at = /^\s*┌─ (.+):(\d+):(\d+)\s*$/.exec(lines[i + 1] ?? "");
+        if (at) {
+            // The compiler writes the path relative to its own working
+            // directory, which is this process's, so resolving it there is what
+            // recovers the file a reader can open.
+            finding.file = path.resolve(at[1]);
+            finding.line = Number(at[2]);
+            finding.column = Number(at[3]);
+        }
+        findings.push(finding);
+    }
+    return findings;
+}
+
 /**
  * Run Typst over the emitted source.
  *
  * @param {string} typPath - The `.typ` file.
  * @param {string} pdfPath - Where the PDF goes.
  * @param {object} pdf - The resolved `pdf:` block.
- * @returns {{ok: boolean, message: string}} What happened.
+ * @returns {{ok: boolean, message: string, findings: object[]}} What happened,
+ *   and what the compiler warned about on the way.
  */
 export function compileTypst(typPath, pdfPath, pdf = {}) {
     const binary = pdf.binary || "typst";
-    const args = ["compile"];
-    if (pdf.fonts?.path) args.push("--font-path", pdf.fonts.path);
-    args.push(typPath, pdfPath);
+    const args = typstArgs(typPath, pdfPath, pdf);
     let result;
     try {
         result = spawnSync(binary, args, { encoding: "utf8" });
     } catch (err) {
-        return { ok: false, message: `could not run \`${binary}\`: ${err.message}` };
+        return { ok: false, message: `could not run \`${binary}\`: ${err.message}`, findings: [] };
     }
     if (result.error) {
         const missing = /** @type {any} */ (result.error).code === "ENOENT";
@@ -649,13 +769,18 @@ export function compileTypst(typPath, pdfPath, pdf = {}) {
                     "`typst compile` over it produces the book. Name another binary with " +
                     "`pdf.binary`."
                 :   `could not run \`${binary}\`: ${result.error.message}`,
+            findings: [],
         };
     }
     if (result.status !== 0) {
         const detail = String(result.stderr || result.stdout || "")
             .trim()
             .split("\n")[0];
-        return { ok: false, message: `\`${binary} compile\` failed: ${detail}` };
+        return {
+            ok: false,
+            message: `\`${binary} compile\` failed: ${detail}`,
+            findings: [],
+        };
     }
-    return { ok: true, message: "" };
+    return { ok: true, message: "", findings: typstWarnings(result.stderr) };
 }

package/engine/pdf-render.mjs

@@ -667,14 +667,22 @@ function renderLink(href, inner, ctx) {
  * ## The width class is the measure
  *
  * An image with no class is one column wide. That is `width: 100%` of whatever
- * container it is set in — the page today, and a column once the book is set in
- * two — so the ordinary case needs nothing but an ordinary block and stays
- * correct through the change.
- *
- * `.full-width` has to leave its column, and a block cannot: only a float
- * placed with `scope: "parent"` spans every column of the page. So a
- * full-width image is always placed, whether or not it states a `float:`, and
- * an image that states neither is left in the flow where it was written.
+ * container it is set in — a column of the two the body is set in — so the
+ * ordinary case needs nothing but an ordinary block, and lands exactly where it
+ * was written.
+ *
+ * `.full-width` has to leave its column, and only a float placed with
+ * `scope: "parent"` spans every column of a page. A float, though, is placed
+ * where the page has room rather than where it was written: it is set at the
+ * top of the page, above the prose that introduces it, and where the page is
+ * too far along to take it, on the next page — after prose that follows it in
+ * the note. Document order governs what follows an image, so
+ * {@link bookTypstPreamble}'s `book-figure` breaks the page first and places
+ * the figure at the top of the fresh one, where nothing is above it to displace
+ * it and nothing that follows it can print first.
+ *
+ * A `.full-width` image that **also states a `float:`** is asking for a float,
+ * and keeps one — deferral is the honest consequence of the request.
  *
  * ## A float occupies the measure
  *
@@ -712,8 +720,10 @@ function renderImage(token, ctx) {
     // In the flow where it was written: no class asking for the page, and no
     // position asking for the top or the bottom of the column.
     if (!float && scope === "column") return `\n${figure}\n\n`;
-    const align = float?.align ?? "top";
-    return `\n#place(${align}, float: true, scope: "${scope}", clearance: 0.7em)[\n${figure}\n]\n\n`;
+    // The page, in document order: a width class says how wide the picture is
+    // and not when it appears.
+    if (!float) return `\n#book-figure[\n${figure}\n]\n\n`;
+    return `\n#place(${float.align}, float: true, scope: "${scope}", clearance: 0.7em)[\n${figure}\n]\n\n`;
 }
 
 /**
@@ -904,6 +914,26 @@ export function bookTypstPreamble() {
             "  place(top + left)[#book-plate(kicker, title, banner, 9cm, body)]\n" +
             "  pagebreak()\n" +
             "}",
+        // A full-width figure spans the page in document order. Only a float
+        // spans every column, and a float is placed where the page has room
+        // rather than where it was written — at the top, above the prose that
+        // introduces it, or on the next page when this one is too far along.
+        // Breaking first puts it at the top of a page whose float region is
+        // empty, which is the one place it cannot be displaced. A picture
+        // taller than the page takes a page of its own, for the reason
+        // `book-wide` states.
+        //
+        // `measure` alone is stable here. A rule reading `here().position()`
+        // to keep the break for the cases that need it does not converge: the
+        // position decides the layout and the layout decides the position.
+        "#let book-figure(body) = context {\n" +
+            "  if measure(block(width: book-text-width)[#body]).height >= book-text-height * 0.88 {\n" +
+            "    page(columns: 1)[#body]\n" +
+            "  } else {\n" +
+            "    pagebreak(weak: true)\n" +
+            '    place(top, float: true, scope: "parent", clearance: 0.7em)[#body]\n' +
+            "  }\n" +
+            "}",
         // Wide content spans the page, and how it spans depends on how tall it
         // is: a float is unbreakable and silently overflows, so anything taller
         // than a page takes pages of its own instead.
@@ -1007,7 +1037,9 @@ export function bookTypstPreamble() {
  * @param {string} opts.title - The document's title.
  * @param {string} [opts.subtitle] - Shown under it on the title page.
  * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
- * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
+ * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names. Each
+ *   falls back to the face the toolchain ships or the compiler embeds, so a
+ *   caller that names none still sets the book in all three.
  * @param {string} [opts.version] - Stamped on the title page when given.
  * @param {string} [opts.preamble] - Definitions the bodies call, emitted once
  *   above the title page. A panel every entry draws is a set of rules stated
@@ -1029,8 +1061,13 @@ export function renderBook({
     preamble = "",
     banners = new Map(),
 } = {}) {
+    // The two halves of one superfamily, chosen together: matched metrics are
+    // most of why the sans can carry every heading over a serif body without
+    // the page reading as two books. The mono is a separate claim — the
+    // superfamily's own is missing the Latin Extended Additional letters this
+    // corpus spells names with, where the compiler's embedded face carries them.
     const serif = fonts.serif || "Libertinus Serif";
-    const sans = fonts.sans || serif;
+    const sans = fonts.sans || "Libertinus Sans";
     const mono = fonts.mono || "DejaVu Sans Mono";
     const out = [];
 

package/engine/scenes.mjs

@@ -53,7 +53,6 @@ import log from "loglevel";
 import {
     parseMarkdownFile,
     sohlField,
-    resolveImg,
     resolveName,
     slugify,
     defaultStats,
@@ -130,15 +129,15 @@ export class Scenes extends BasePackCompiler {
     static label = "map";
 
     /**
-     * A map note's `img` is its background art, and it is **required**: the map
-     * compiler refuses a note without one. It lands on the scene's level rather
-     * than on a property spelled `img`, which makes no difference to the
-     * question this declaration answers — the authored path reaches the output.
-     * The place Adventure this pass bundles carries it too.
+     * A map note's `bgImage` is its background art, and it is **required**: the
+     * map compiler refuses a note without one. It lands on the scene's level
+     * rather than on a property spelled `img`, which makes no difference to the
+     * question this declaration answers — the authored address reaches the
+     * output. The place Adventure this pass bundles carries it too.
      *
      * @type {readonly string[]}
      */
-    static emitsArt = Object.freeze(["img"]);
+    static emitsArt = Object.freeze(["bgImage"]);
 
     /** @type {string} */
     adventureDir;
@@ -152,13 +151,14 @@ export class Scenes extends BasePackCompiler {
 
     constructor({
         contentBase,
+        assetsBase,
         dest,
         skipDirectories,
         companionDests = {},
         folderResolver = () => null,
         repoRoot = process.cwd(),
     }) {
-        super({ contentBase, dest, folderResolver, skipDirectories });
+        super({ contentBase, assetsBase, dest, folderResolver, skipDirectories });
         if (!companionDests.adventures) {
             throw new Error("Scenes compiler requires an `adventures` companion destination");
         }
@@ -426,6 +426,9 @@ export class Scenes extends BasePackCompiler {
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
+            // The art resolver, so the map pass turns an address into the path
+            // each surface serves without holding an index of its own.
+            art: (value, key, type) => this.artPathOf(value, key, type),
             name,
             folder,
             stats: this.stats,
@@ -473,7 +476,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: resolveImg(sohlField(fm, "img", null)),
+                img: this.artPath(fm, "bgImage"),
                 pinned: false,
                 scenes: [],
                 journal: [],

package/engine/site-build.mjs

@@ -55,7 +55,6 @@ import { protectCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderImageFigures } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
-import { ART_FIELDS } from "./frontmatter-lint.mjs";
 import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { loadForeignIndexes } from "./metadata-index.mjs";
@@ -63,10 +62,12 @@ import { noteInfoboxes } from "./infobox-registry.mjs";
 import { formatUnaddressableFinding, unaddressableForeignPackages } from "./metadata-index.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { routerFor } from "./pack-router.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 // The corpus, from the one pass that derives it.
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { ART_SLOTS, artPathname, assetAddressIndex } from "./art-fields.mjs";
 import {
     checkHomepageCount,
     homepageDestination,
@@ -627,13 +628,16 @@ export function sectionFrontmatter(meta) {
  *   for.
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
+ * @param {(value: unknown, type: string) => string|null} [options.artSrc] -
+ *   Translates an art address into the pathname the website resolver takes, or
+ *   `null` where nothing answers it.
  * @param {(src: string) => string} [options.webSrc] - Translates an authored
  *   pathname into the address the website serves. Every artwork field goes
  *   through it, so a page's `img:` and its body images name the same file the
  *   same way.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page, { readmeSections = {}, decorate, webSrc }) {
+export function pageFrontmatter(page, { readmeSections = {}, decorate, webSrc, artSrc }) {
     const { fm, name, slug, sec, isReadme } = page;
     let data;
     if (page.kind === "content") {
@@ -665,29 +669,39 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate, webSrc })
         if (meta) Object.assign(data, sectionFrontmatter(meta));
     }
     delete data.aliases;
-    if (webSrc) resolveArtFields(data, webSrc);
+    if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
 
 /**
- * Rewrite a page's artwork fields into the addresses the website serves.
+ * Rewrite a page's artwork addresses into the URLs the website serves.
  *
- * The same fields the linter holds to the pathname rule, read from the same
- * list, so a third art field added to the vocabulary reaches the page without
- * anyone remembering this function exists. Only an authored **string** is
- * touched: `null` is a note naming no art and `""` is one naming none on
- * purpose, and neither is a pathname to resolve.
+ * The slots are read from {@link module:engine/art-fields.ART_SLOTS}, so a slot
+ * added to the vocabulary reaches the page without anyone remembering this
+ * function exists. Only an authored **string** is touched: `null` is a note
+ * naming no art and `""` is one naming none on purpose, and neither is an
+ * address to resolve.
+ *
+ * **An address nothing answers is dropped**, not emitted as written. The theme
+ * renders nothing where a value is absent — its silent-disappear convention —
+ * and a raw address left in place would reach the reader as a broken image
+ * source with nothing saying why.
  *
  * @param {object} data - The frontmatter being emitted, rewritten in place.
- * @param {(src: string) => string} webSrc - The website's resolver.
+ * @param {(src: string) => string} webSrc - The website's pathname resolver.
+ * @param {(value: unknown, type: string) => string|null} artSrc - The address
+ *   resolver, yielding the pathname `webSrc` takes.
  * @returns {void}
  */
-function resolveArtFields(data, webSrc) {
-    for (const { key, inData } of ART_FIELDS) {
-        const holder = inData && isPlainObject(data.data) ? data.data : data;
-        const value = holder?.[key];
+function resolveArtFields(data, webSrc, artSrc) {
+    for (const { key, type } of ART_SLOTS) {
+        const holder = isPlainObject(data.data) ? data.data : null;
+        if (!holder) continue;
+        const value = holder[key];
         if (typeof value !== "string" || value === "") continue;
-        holder[key] = webSrc(value);
+        const pathname = artSrc(value, type);
+        if (pathname === null) delete holder[key];
+        else holder[key] = webSrc(pathname);
     }
 }
 
@@ -758,8 +772,17 @@ export function renderPages(pages, options) {
         linkable = (d) => Boolean(d.fm.shortcode),
         sqlTables,
         config,
+        records = [],
     } = options;
 
+    // The address space the art slots and the body's embeds resolve against:
+    // the files this package ships, and the ones a dependency published.
+    const artIndex = assetAddressIndex(records, {
+        config,
+        foreign,
+        types: index?.contentTypes ?? [],
+    });
+
     const tableErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
@@ -817,9 +840,11 @@ export function renderPages(pages, options) {
             type: page.fm.type ?? null,
             errors: wikiErrors,
             foreignIndex: foreign.index,
+            assets: artIndex,
         });
 
         const webSrc = webAddresses(page.file);
+        const artSrc = (value, type) => artPathname(artIndex, value, type).pathname;
         const resolve = (text) => {
             let t = text;
             if (pass.beforeLinks) t = pass.beforeLinks(t, page);
@@ -851,7 +876,7 @@ export function renderPages(pages, options) {
             body = markdown;
         }
 
-        const data = pageFrontmatter(page, { readmeSections, decorate, webSrc });
+        const data = pageFrontmatter(page, { readmeSections, decorate, webSrc, artSrc });
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
@@ -1235,6 +1260,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
         outRoot: out,
         sqlTables,
         config: resolved,
+        records: ctx.records,
         index: gates.index,
         foreign: gates.foreign,
         universe: tableUniverse(pages),
@@ -1254,6 +1280,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             // book from one definition.
             data.infoboxes = noteInfoboxes(page.fm, {
                 resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
+                router: routerFor(resolved),
             });
         },
     });

package/engine/site-index.mjs

@@ -322,6 +322,8 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
  *   diagnostic names. Absent, `src` stands in.
  * @param {Map<string, object>} [options.foreignIndex] - The foreign index, for
  *   resolvers that distinguish a foreign hit from a local one.
+ * @param {object} [options.assets] - The address space an `![[…]]` embed
+ *   resolves against, shaped as every asset resolver reads one.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -330,10 +332,17 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built, { src, file, type = null, errors, foreignIndex = new Map() }) {
+export function wikiContext(
+    built,
+    { src, file, type = null, errors, foreignIndex = new Map(), assets },
+) {
     return {
         index: built.index,
         foreign: foreignIndex,
+        // The address space an embed resolves against. Separate from `index`
+        // because the two hold different record shapes: a note's entry carries
+        // a URL and a name, an asset's carries the path to a file.
+        assets,
         collide: built.ambiguous,
         sections: built.sections,
         contentTypes: built.contentTypes,