@heroiclands/package-build 21.1.0 → 22.0.0

package/engine/helpers.mjs

@@ -32,8 +32,9 @@ import yaml from "yaml";
 import unidecode from "unidecode";
 import markdownit from "markdown-it";
 import { iconPlugin } from "./content-icons.mjs";
-import { imagePlugin } from "./content-images.mjs";
-import { resolvePathname } from "./pathnames.mjs";
+import { imagePlugin, imagesIn } from "./content-images.mjs";
+import { resolveEmbeds } from "./content-embeds.mjs";
+import { foundryAddressProblem, pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -46,7 +47,7 @@ import { loadForeignIndexes } from "./metadata-index.mjs";
 // The record accessors only — deriving records reaches the pack router and the
 // manifest emitter, which reach the compilers, which load this module. Reading
 // a record needs none of that.
-import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
+import { authoredFrontmatter, isAssetRecord, isNoteRecord, noteFile } from "./index-records.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
 // One vocabulary of link findings, and one message per class, so the three
 // resolvers cannot word the same defect differently.
@@ -100,13 +101,16 @@ export const md = markdownit({ html: true })
     // translated by the same rule `img:` follows.
     .use(
         imagePlugin((src) => {
-            // **Reported elsewhere, never here.** A renderer has no channel to
+            // **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. A pathname this
-            // rule refuses is a Foundry address, so emitting it unchanged is
-            // right on the one surface this renderer serves, and the passes
-            // that own the other three refuse it with a line and a column.
+            // 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 {
@@ -494,19 +498,9 @@ export function resolveImg(raw, config = loadPackConfig()) {
     const forms = resolvePathname(raw, config);
     if (forms === null) return null;
     if (forms.foundry !== null) return forms.foundry;
-    if (forms.own) {
-        throw new Error(
-            `package-build: \`${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.`,
-        );
-    }
-    throw new Error(
-        `package-build: \`${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.`,
-    );
+    // One sentence per class, stated where the rule is, so an art field that
+    // refuses and a body image that refuses tell an author the same thing.
+    throw new Error(`package-build: ${foundryAddressProblem(raw, config)}.`);
 }
 
 /**
@@ -704,9 +698,18 @@ export function buildContentLinkIndex(
     { skipDirectories, config, records, problems } = {},
 ) {
     const docs = [];
+    /** The files this package ships, by canonical address. */
+    const assets = new Map();
     const resolved = config ?? loadPackConfig();
     assertSuppliedCorpus(records, "buildContentLinkIndex");
     for (const record of records) {
+        // An asset's record addresses a file rather than a note, so it becomes
+        // no `doc` and takes no part in link resolution — it is keyed for the
+        // art fields, which name a file and never a document.
+        if (isAssetRecord(record)) {
+            if (record.address?.canonical) assets.set(record.address.canonical, record);
+            continue;
+        }
         // A documentation journal is a document this tree emits, not a note in
         // it; the note it documents is indexed here and carries its address.
         if (!isNoteRecord(record)) continue;
@@ -782,7 +785,9 @@ export function buildContentLinkIndex(
         `Wikilink index: ${docs.length} local document(s), ` +
             `${foreign.size} foreign address(es)`,
     );
-    return buildWikilinkIndex(docs, resolved.foundryPackage, foreign, resolved.contentPackage);
+    return buildWikilinkIndex(docs, resolved.foundryPackage, foreign, resolved.contentPackage, {
+        assets,
+    });
 }
 
 /**
@@ -807,6 +812,9 @@ export function buildContentLinkIndex(
  *   in, addressing a self-link the same way.
  * @param {object} ctx.index - The address index every link resolves through.
  * @param {string} ctx.name - The note, for the message.
+ * @param {object} [ctx.config] - The resolved build configuration, which is
+ *   what says which packages this build can address a file in. Loaded when
+ *   omitted, exactly as an art field's resolution loads it.
  * @param {string} [ctx.file] - The note's file, so a report names it.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line.
  * @param {number} [ctx.bodyColumn] - 1-based file column of the same character.
@@ -814,15 +822,24 @@ export function buildContentLinkIndex(
  *   authored line each body line came from, from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
  * @throws {Error} On any link that does not resolve — an unlabelled one, a
- *   target that is not an address, or an address nothing publishes. The error
+ *   target that is not an address, or an address nothing publishes — and on a
+ *   body image whose pathname names no file a Foundry install serves. The error
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */
 export function convertNoteWikilinks(
     body,
-    { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap },
+    { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap, config },
 ) {
-    const result = convertWikilinks(body ?? "", {
+    const source = body ?? "";
+    // **Embeds first, and on the authored text.** An embed's interior is a
+    // wikilink, so resolving it here is what stops the link pass reading
+    // `![[wildboar|Wild Boar]]` as a link to a note called `wildboar`. The
+    // rewrite it produces carries no newline, so the line every later offset
+    // lands on — and the `lineMap` a generated table supplied — survive it, and
+    // only the embed's own findings need the authored text to locate against.
+    const embedded = resolveEmbeds(source, { index });
+    const result = convertWikilinks(embedded.markdown, {
         type,
         id,
         pack,
@@ -832,14 +849,15 @@ export function convertNoteWikilinks(
     /**
      * Where one unresolved link sits, in file coordinates.
      *
-     * @param {object} u - An entry of `result.unresolved`.
+     * @param {object} u - An entry of an `unresolved` list.
+     * @param {string} text - The body its `offset` indexes into.
      * @returns {{line?: number, column?: number, generated?: boolean}} Empty
      *   when the caller supplied no position to resolve against.
      */
-    const locate = (u) =>
+    const locate = (u, text) =>
         bodyLine === undefined || u.offset === undefined ?
             {}
-        :   positionInBody(body ?? "", u.offset, {
+        :   positionInBody(text, u.offset, {
                 bodyLine,
                 bodyColumn,
                 lineMap,
@@ -850,10 +868,11 @@ export function convertNoteWikilinks(
      *
      * @param {object} u - The offending link.
      * @param {string} message - What is wrong.
+     * @param {string} text - The body its `offset` indexes into.
      * @returns {never}
      */
-    const fail = (u, message) => {
-        const at = locate(u);
+    const fail = (u, message, text) => {
+        const at = locate(u, text);
         // A link this build wrote is not at any authored position, so say
         // where it came from rather than implying an edit site.
         const err = new Error(
@@ -864,6 +883,39 @@ export function convertNoteWikilinks(
         throw err;
     };
 
+    for (const u of embedded.unresolved) {
+        fail(u, `${linkFindingMessage(u)} — in "${name}".`, source);
+    }
+    // A directive that cannot be honoured is refused for the reason an image's
+    // is: rendering as the ordinary width looks exactly like a directive that
+    // worked, so it fails here rather than publishing a page nobody asked for.
+    for (const problem of embedded.problems) {
+        fail(problem, `${problem.message} — in "${name}".`, source);
+    }
+
+    // **One scan, both spellings.** By here an `![[…]]` embed has been
+    // rewritten into the ordinary image every surface renders, so a single walk
+    // of the rewritten body holds an authored `![alt](…)` and an embed to the
+    // same rule — there is no second image path to keep in step.
+    //
+    // A pathname the rule refuses is **refused here too, not emitted**. The
+    // renderer below has no channel to report through and hands the journal the
+    // pathname as authored — which for one class resolves against nothing
+    // Foundry serves, and for the other resolves here and on neither of the
+    // remaining two surfaces. Every surface refuses such a value rather than
+    // deriving an address from it, and this is that refusal on the Foundry one:
+    // the same one an art field already makes through {@link resolveImg}.
+    const images = imagesIn(embedded.markdown);
+    if (images.length) {
+        const resolved = config ?? loadPackConfig();
+        for (const image of images) {
+            const problem =
+                pathnameProblem(image.src) || foundryAddressProblem(image.src, resolved);
+            if (!problem) continue;
+            fail({ offset: image.index }, `${problem} — in "${name}".`, embedded.markdown);
+        }
+    }
+
     for (const u of result.unresolved) {
         // Every class fails, and every class is worded by the shared table.
         // The three resolvers read one authored link, so an author who
@@ -873,7 +925,7 @@ export function convertNoteWikilinks(
         //
         // The note's name is appended rather than woven in: the message is the
         // defect, the name is the context this build can add.
-        fail(u, `${linkFindingMessage(u)} — in "${name}".`);
+        fail(u, `${linkFindingMessage(u)} — in "${name}".`, embedded.markdown);
     }
     return result;
 }

package/engine/index-records.mjs

@@ -59,8 +59,30 @@ export const DERIVED_KEYS = Object.freeze([
     "foundry",
     "documentation",
     "documents",
+    "asset",
 ]);
 
+/**
+ * Recursively sort an object's keys, so serialization is order-independent.
+ *
+ * Arrays keep their order — it is authored — but every object inside one is
+ * sorted too. Anything that is not a plain object is returned as it is.
+ *
+ * @param {unknown} value - The value to normalize.
+ * @returns {unknown} The value with every plain object's keys in sorted order.
+ */
+export function sortKeysDeep(value) {
+    if (Array.isArray(value)) return value.map(sortKeysDeep);
+    if (value === null || typeof value !== "object") return value;
+    // A Date or any other exotic object would lose itself in a rebuild from
+    // entries, and YAML frontmatter can produce one.
+    if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = sortKeysDeep(value[key]);
+    return out;
+}
+
 /**
  * The file a record was read from, as an absolute path.
  *
@@ -109,18 +131,55 @@ export function authoredFrontmatter(record) {
 }
 
 /**
- * Whether a record is a note's, rather than a documentation journal's.
+ * Whether a record addresses a **file** rather than a note.
+ *
+ * The index holds two record shapes in one file, and this is how a reader tells
+ * them apart. An asset record carries no frontmatter, no anchors and no
+ * `foundry` block — a `.webp` declares nothing about itself — so every pass that
+ * reads a note's fields has to skip it, and the `asset` block is what marks it.
+ *
+ * Asked of the block rather than of `type`, so a fourth asset type needs no
+ * edit here: what makes a record an asset's is that it describes a file, and the
+ * block is the description.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean} True for an asset's record.
+ */
+export function isAssetRecord(record) {
+    return Boolean(record?.asset);
+}
+
+/**
+ * Whether a record is a note's, rather than a documentation journal's or an
+ * asset's.
  *
  * An item note yields two records — itself and the JournalEntry its prose
  * compiles into — and the second is a document, not a note: it has no file of
  * its own to read, no frontmatter an author wrote, and its `type` is the
  * virtual `doc<type>` that `readQualifier` resolves rather than a type any tree
- * declares. A reader enumerating the corpus wants the notes; one resolving an
- * address wants both.
+ * declares. An asset's record is not a note either, for the stronger reason that
+ * nobody authored it at all. A reader enumerating the corpus wants the notes;
+ * one resolving an address wants all three.
  *
  * @param {Record<string, any>} record - An index record.
  * @returns {boolean} True for a note's own record.
  */
 export function isNoteRecord(record) {
-    return !record?.documents;
+    return !record?.documents && !isAssetRecord(record);
+}
+
+/**
+ * The path a record names inside its package, whichever shape it is.
+ *
+ * The two shapes state it differently and honestly: a note names the `.md` it
+ * was parsed from, relative to the content root, while an asset names the file
+ * it *is*, relative to the package's asset directory. Both are paths within one
+ * package, so one total order covers the whole index — which is what keeps the
+ * artifact byte-stable across a rebuild.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {string} The path, or `""` for a record naming neither.
+ */
+export function recordPath(record) {
+    return String(record?.file?.path ?? record?.asset?.path ?? "");
 }

package/engine/index.mjs

@@ -120,6 +120,18 @@ export * as foundryEntries from "./foundry-entries.mjs";
 /** Publishing the note tree as a queryable JSON Lines index. */
 export * as contentIndex from "./content-index.mjs";
 
+/** The asset types — `icon`, `image`, `audio` — and the roots they are walked from. */
+export * as assetTypes from "./asset-types.mjs";
+
+/** The asset record: one index line per addressable file, and its provenance. */
+export * as assetIndex from "./asset-index.mjs";
+
+/** The `<package>` segment's registry: the names no repository may claim. */
+export * as packages from "./packages.mjs";
+
+/** The toolchain's own content index — the files it ships, addressed. */
+export * as packagebuildIndex from "./packagebuild-index.mjs";
+
 /** Publishing a content tree as a website: the pass, and its integrity gates. */
 export * as siteBuild from "./site-build.mjs";
 
@@ -138,6 +150,9 @@ export * as contentHtml from "./content-html.mjs";
 /** An image saying how wide it is and where it sits, in two closed vocabularies. */
 export * as contentImages from "./content-images.mjs";
 
+/** `![[…]]` — the wikilink that renders a picture where it stands. */
+export * as contentEmbeds from "./content-embeds.mjs";
+
 /** One authored pathname, and the four addresses the surfaces derive from it. */
 export * as pathnames from "./pathnames.mjs";
 

package/engine/infobox-registry.mjs

@@ -23,9 +23,11 @@
  * @module
  */
 
+import { subtypeRow } from "./document-subtypes.mjs";
 import { assertInfoboxSet, buildInfoboxes } from "./infobox.mjs";
+import { packRouter } from "./pack-router.mjs";
 import { carriesSystemBlock, resolveFieldValue } from "./system-block.mjs";
-import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+import { DEFAULT_DOCUMENT_SUBTYPES, KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 import { SOHL_INFOBOX } from "../sohl/infobox.mjs";
 import { HM3_INFOBOX } from "../hm3/infobox.mjs";
 
@@ -52,6 +54,49 @@ export function infoboxFor(system) {
     return KNOWN_INFOBOXES.find((entry) => entry.system === system);
 }
 
+/**
+ * Whether one system compiles a document for one note.
+ *
+ * This is what a system box's _available_ asserts, and it is the compile's own
+ * question rather than a reading of the frontmatter. A note carrying no block
+ * is not a note a system has nothing for: where the pack compiling its document
+ * declares no `system:`, the document is built from `data:` and the field
+ * defaults and ships exactly like any other.
+ *
+ * Three statements answer it, and they are the three the compile itself
+ * follows:
+ *
+ * 1. **The map** says which document class this system makes of the note's
+ *    type. No row, no document — and no box either, which is why a caller
+ *    reaching here already has one.
+ * 2. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by.
+ * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
+ *    system's data and takes only notes that say something about it — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside. Declaring none, it is compiled by the fallback
+ *    pass, which needs no block and answers for
+ *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
+ *    so a tree with no HM3 pack ships no HM3 document however a note is
+ *    written.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} map - The system's note-type → document-subtype map.
+ * @param {object} router - The pack router this build is driven by.
+ * @returns {boolean} True when this system compiles a document for this note.
+ */
+export function compilesSystemDocument(fm, map, router) {
+    const row = subtypeRow(map, fm?.type);
+    if (!row?.document) return false;
+
+    const packName = router.resolveOrNull(fm, row.document, map.system);
+    if (!packName) return false;
+
+    const packSystem = router.systemOf(packName);
+    if (!packSystem) return map.system === DEFAULT_DOCUMENT_SUBTYPES.system;
+    return packSystem === map.system && carriesSystemBlock(fm, map.block);
+}
+
 /**
  * Every box one note carries, wired to the registries this toolchain ships.
  *
@@ -63,15 +108,17 @@ export function infoboxFor(system) {
  * @param {object} [options] - Options.
  * @param {(ref: unknown, hint?: object) => object|undefined} [options.resolve] -
  *   Resolves a reference to `{name, url?, uuid?, address?, subType?}`.
+ * @param {object} [options.router] - The pack router deciding which system
+ *   compiles a document for this note. Defaults to the consuming repository's.
  * @returns {object[]} The boxes, in the order every medium renders them.
  * @throws {Error} When the built set disagrees with what the note's type maps
  *   to — see {@link module:engine/infobox.assertInfoboxSet}.
  */
-export function noteInfoboxes(fm, { resolve } = {}) {
+export function noteInfoboxes(fm, { resolve, router = packRouter() } = {}) {
     const boxes = buildInfoboxes(fm, {
         maps: KNOWN_DOCUMENT_SUBTYPE_MAPS,
         providers: KNOWN_INFOBOXES,
-        carriesBlock: carriesSystemBlock,
+        compilesDocument: (note, map) => compilesSystemDocument(note, map, router),
         resolveField: resolveFieldValue,
         resolve,
     });

package/engine/infobox.mjs

@@ -56,7 +56,7 @@
  *    appears before it.
  * 2. **It contains no image.** A picture is authored in the text with its own
  *    directive, and its position governs. {@link NOTE_FIELD_PRESENTATION}
- *    withholds `portrait`, `img` and `overlay` for that reason and no other.
+ *    withholds the art slots and `overlay` for that reason and no other.
  * 3. **A section is the unit that flows.** Sections are whole and unbreakable;
  *    the panel breaks between them. This is what lets a long box cross a
  *    column or page boundary without splitting a stat grid.
@@ -266,8 +266,10 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     color: Object.freeze({
         withheld: "sidebar machinery, not a fact about the subject",
     }),
-    portrait: Object.freeze({ withheld: "an image, which the box never carries" }),
-    img: Object.freeze({ withheld: "an image, which the box never carries" }),
+    icon: Object.freeze({ withheld: "an image, which the box never carries" }),
+    tokenIcon: Object.freeze({ withheld: "an image, which the box never carries" }),
+    bgImage: Object.freeze({ withheld: "an image, which the box never carries" }),
+    banner: Object.freeze({ withheld: "an image, which the box never carries" }),
     overlay: Object.freeze({ withheld: "an image, which the box never carries" }),
 
     birthday: Object.freeze({ label: "Born" }),
@@ -834,9 +836,11 @@ export function systemRowsSection(
  *   build ships, which decide the box set.
  * @param {readonly object[]} [options.providers] - The systems' infobox
  *   declarations, keyed by `system`.
- * @param {(fm: object, block: string) => boolean} options.carriesBlock -
- *   Whether the note says anything about a system, which decides
- *   {@link NOT_AVAILABLE}.
+ * @param {(fm: object, map: object) => boolean} options.compilesDocument -
+ *   Whether that system compiles a document for this note, which decides
+ *   {@link NOT_AVAILABLE}. Asked of the routing and the passes rather than of
+ *   the frontmatter: a pack declaring no `system:` compiles a note from `data:`
+ *   and the field defaults, so the block's presence is not the question.
  * @param {(field: object, fm: object, opts: object) => object} options.resolveField -
  *   Resolves one declared field against the note.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
@@ -848,7 +852,7 @@ export function buildInfoboxes(fm, options) {
     const {
         maps,
         providers = [],
-        carriesBlock,
+        compilesDocument,
         resolveField,
         resolve,
         vocabulary = NOTE_VOCABULARY,
@@ -860,7 +864,7 @@ export function buildInfoboxes(fm, options) {
     for (const map of maps ?? []) {
         if (!subtypeRow(map, fm?.type)) continue;
         const provider = providers.find((entry) => entry.system === map.system);
-        const available = Boolean(carriesBlock(fm, map.block));
+        const available = Boolean(compilesDocument(fm, map));
         const box = {
             id: map.system,
             kind: "system",

package/engine/item-compiler.mjs

@@ -48,7 +48,7 @@
 
 import log from "loglevel";
 
-import { resolveName, resolveImg } from "./helpers.mjs";
+import { resolveName } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { foundryPackageId } from "./content-package.mjs";
@@ -117,15 +117,15 @@ export class SystemItemCompiler extends BasePackCompiler {
     static requiresSystemBlock = true;
 
     /**
-     * An Item carries an `img` — its icon — which this pass writes from the
-     * note's own path, falling back to the type's default art.
+     * An Item carries one piece of art — its icon — which this pass writes from
+     * the address the note names, falling back to the type's default art.
      *
-     * `portrait` is **not** among them: a portrait is a being's sheet picture,
-     * and an item has nowhere to put one.
+     * `tokenIcon` is **not** among them: an Item places no token, so it has
+     * nowhere to put a second picture.
      *
      * @type {readonly string[]}
      */
-    static emitsArt = Object.freeze(["img"]);
+    static emitsArt = Object.freeze(["icon"]);
 
     /**
      * The note-type → document-subtype map this pass compiles against.
@@ -372,10 +372,10 @@ export class SystemItemCompiler extends BasePackCompiler {
             // both registries are keyed by content type — while the document's
             // own subtype comes from the system's map.
             type: subType,
-            // Nullish, not `||`: `resolveImg` returns `null` for a
-            // note that names no art and `""` for one that wants none, and only
-            // the first may be replaced by the type's default.
-            img: resolveImg(blockProperty(fm, system, "img")) ?? itemArt(type, system),
+            // Nullish, not `||`: an art address resolves to `null` for a note
+            // that names none and `""` for one that wants none, and only the
+            // first may be replaced by the type's default.
+            img: this.artPath(fm, "icon") ?? itemArt(type, system),
             _id: id,
             system: built,
             effects: Array.isArray(effects) ? [...effects] : [],

package/engine/journals.mjs

@@ -440,6 +440,9 @@ export class Journals extends BasePackCompiler {
         // URLs: a player reading this at the table stays in Foundry.
         const boxes = noteInfoboxes(fm, {
             resolve: (ref, hint) => resolveReference(this.linkIndex, ref, hint),
+            // This compile's own router, so the panel's `available` is decided
+            // by the pack list this build is being driven by.
+            router: this.router,
         });
 
         return buildJournalEntry({

package/engine/macros.mjs

@@ -51,7 +51,7 @@
 
 import log from "loglevel";
 
-import { sohlField, resolveName, resolveImg, defaultStats, folderField } from "./helpers.mjs";
+import { sohlField, resolveName, defaultStats, folderField } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { splitPages } from "./journals.mjs";
 
@@ -79,11 +79,11 @@ export const MACRO_TYPES = Object.freeze(["script", "chat"]);
 export const MACRO_SCOPES = Object.freeze(["global", "actors", "actor"]);
 
 /**
- * Foundry's own default macro artwork, used when a note authors no `img`.
+ * Foundry's own default macro artwork, used when a note names no `icon`.
  *
- * A core path, deliberately: it is not translated by {@link resolveImg} (which
- * roots `icons/…` under this system's assets), so it must be stated after that
- * translation rather than as authored frontmatter.
+ * A core path, deliberately: it names a file Foundry itself ships rather than an
+ * address in any package, so it is stated after the art resolution rather than
+ * as something a note could author.
  */
 export const DEFAULT_MACRO_IMG = "icons/svg/dice-target.svg";
 
@@ -248,10 +248,13 @@ export function resolveMacroScope(fm, label) {
  * @param {string} opts.command - The command, from {@link macroCommand}.
  * @param {string|null} [opts.folder] - The resolved folder id.
  * @param {object} [opts.stats] - The `_stats` block.
+ * @param {string|null} [opts.img] - The resolved art, from the note's `icon`
+ *   address. Passed in rather than resolved here, because an address is
+ *   answered by the compile's index and this function takes no index.
  * @returns {MacroDocument} The Macro document.
  * @throws {Error} When the frontmatter's macro type or scope is unusable.
  */
-export function buildMacroEntry(fm, { command, folder = null, stats = defaultStats() }) {
+export function buildMacroEntry(fm, { command, folder = null, stats = defaultStats(), img }) {
     const name = resolveName(fm);
     const id = fm.id;
     return {
@@ -262,8 +265,8 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         type: resolveMacroType(fm, name),
         author: null,
         // Nullish, not `||`: a macro note that names no art gets the
-        // shared default, one that writes `img: ""` ships blank on purpose.
-        img: resolveImg(fm.img) ?? DEFAULT_MACRO_IMG,
+        // shared default, one that writes `icon: ""` ships blank on purpose.
+        img: (img === undefined ? null : img) ?? DEFAULT_MACRO_IMG,
         scope: resolveMacroScope(fm, name),
         command,
         folder,
@@ -289,19 +292,18 @@ export class Macros extends BasePackCompiler {
 
     /**
      * The command must be exactly what the author typed, so this pass reads the
-     * note as authored: no table expansion, no wikilink conversion, and no
-     * content-wide link index it would never consult. The journals pass
-     * compiles the converted copy of the same body independently.
+     * note as authored: no table expansion and no wikilink conversion. The
+     * journals pass compiles the converted copy of the same body independently.
      */
     static convertsWikilinks = false;
 
     /**
-     * A Macro carries an `img` — the tile art Foundry shows on the hotbar —
+     * A Macro carries one piece of art — the tile Foundry shows on the hotbar —
      * defaulting to {@link DEFAULT_MACRO_IMG} where the note names none.
      *
      * @type {readonly string[]}
      */
-    static emitsArt = Object.freeze(["img"]);
+    static emitsArt = Object.freeze(["icon"]);
 
     /**
      * @param {object} fm - The note's frontmatter.
@@ -323,6 +325,7 @@ export class Macros extends BasePackCompiler {
         const name = resolveName(fm);
         return buildMacroEntry(fm, {
             command: macroCommand(body, name),
+            img: this.artPath(fm, "icon"),
             folder: this.folderResolver(folderField(fm).value, {
                 isAddress: folderField(fm).isAddress,
             }),