@heroiclands/package-build 20.6.0 → 21.0.0

package/engine/pdf-toc.mjs

@@ -54,16 +54,86 @@ import { positionOfYamlPath } from "./diagnostics.mjs";
 /**
  * Presentation a node may declare, and that its descendants inherit.
  *
- * Reserved now although the first release renders none of them, because the
- * shape of the file is the thing consumers commit to: a book that has to be
- * restructured to gain a running head has the wrong format, not the wrong
- * renderer. Inheritance is what makes them worth declaring at all — `Gear` says
- * once which infobox its entries use, and nine sections beneath it agree.
+ * Inheritance is what makes them worth declaring at all — `Gear` says once
+ * which banner its entries are plated over, and nine sections beneath it
+ * agree.
+ *
+ * **`page` and `footer` are read by the renderer**, and their shapes are
+ * checked here so that a key nothing can act on is an error rather than a
+ * silence. `header` and `infobox` are reserved and read by nothing: the
+ * running head is a foot in this design, and which infobox a note draws is
+ * decided by the note's type. They keep their place in the format because the
+ * shape of the file is the thing consumers commit to.
  *
  * @type {readonly string[]}
  */
 export const PRESENTATION_KEYS = Object.freeze(["header", "footer", "infobox", "page"]);
 
+/** Keys the `page:` presentation may carry. @type {readonly string[]} */
+const PAGE_KEYS = Object.freeze(["banner", "columns", "kicker"]);
+
+/**
+ * How many columns a section's pages may be set in.
+ *
+ * One or two is the real choice; the ceiling is there so a typo that reads as
+ * a number cannot produce a page of unreadable slivers.
+ *
+ * @type {number}
+ */
+const MAX_COLUMNS = 4;
+
+/**
+ * Check the presentation a section declares, in the two keys anything reads.
+ *
+ * @param {Record<string, unknown>} entry - The section.
+ * @param {Array<string|number>} at - Where it sits in the document.
+ * @param {object} ctx - `{ findings, text }`.
+ * @returns {void}
+ */
+function checkPresentation(entry, at, ctx) {
+    if (entry.footer !== undefined && typeof entry.footer !== "string") {
+        ctx.findings.push(
+            finding(ctx, [...at, "footer"], "`footer:` must be the name the running foot carries"),
+        );
+    }
+    if (entry.page === undefined) return;
+    if (!entry.page || typeof entry.page !== "object" || Array.isArray(entry.page)) {
+        ctx.findings.push(finding(ctx, [...at, "page"], "`page:` must be a mapping"));
+        return;
+    }
+    const page = /** @type {Record<string, unknown>} */ (entry.page);
+    for (const key of Object.keys(page)) {
+        if (!PAGE_KEYS.includes(key)) {
+            ctx.findings.push(
+                finding(ctx, [...at, "page", key], `unknown key \`${key}:\` under \`page:\``, {
+                    key: true,
+                }),
+            );
+        }
+    }
+    for (const key of ["banner", "kicker"]) {
+        if (page[key] !== undefined && (typeof page[key] !== "string" || !page[key].trim())) {
+            ctx.findings.push(
+                finding(ctx, [...at, "page", key], `\`page.${key}:\` must be a non-empty string`),
+            );
+        }
+    }
+    if (
+        page.columns !== undefined &&
+        (!Number.isInteger(page.columns) ||
+            /** @type {number} */ (page.columns) < 1 ||
+            /** @type {number} */ (page.columns) > MAX_COLUMNS)
+    ) {
+        ctx.findings.push(
+            finding(
+                ctx,
+                [...at, "page", "columns"],
+                `\`page.columns:\` must be a whole number from 1 to ${MAX_COLUMNS}`,
+            ),
+        );
+    }
+}
+
 /** Keys a section node may carry. @type {readonly string[]} */
 const SECTION_KEYS = Object.freeze(["sectionName", "contents", ...PRESENTATION_KEYS]);
 
@@ -164,6 +234,8 @@ function walkSections(contents, keyPath, trail, inherited, ctx) {
             }
         }
 
+        checkPresentation(entry, at, ctx);
+
         const presentation = { ...inherited };
         for (const key of PRESENTATION_KEYS) {
             if (entry[key] !== undefined) presentation[key] = entry[key];

package/engine/scenes.mjs

@@ -53,6 +53,7 @@ import log from "loglevel";
 import {
     parseMarkdownFile,
     sohlField,
+    resolveImg,
     resolveName,
     slugify,
     defaultStats,
@@ -472,7 +473,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: sohlField(fm, "img", null),
+                img: resolveImg(sohlField(fm, "img", null)),
                 pinned: false,
                 scenes: [],
                 journal: [],

package/engine/site-build.mjs

@@ -53,9 +53,13 @@ import { slugify } from "./content-slug.mjs";
 import { addressSlug } from "./content-address.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { buildSiteIndex, wikiContext } from "./site-index.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";
+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";
@@ -267,6 +271,14 @@ export function collectContentPages(contentBase, ctx) {
  * addressed by type and slug: they are a book with chapters, and a reader
  * follows their paths. A `README` is its directory's landing.
  *
+ * **The section is the tree's, never the note's.** `tree.section` is the
+ * mount point a `trees` entry configures — fixed, physical, and the same
+ * value `site-index.mjs` indexes a tree page's address under. A note's own
+ * `subType` is a genre and reaches no address, the same contract
+ * `packageAddress()` holds for a content page: reading it here would move a
+ * page's URL, its file destination (`pageDestination`) and the address a
+ * wikilink cites it by, every time an author classified it.
+ *
  * @param {object} tree - `{ from, rel, section, route }`.
  * @param {object} ctx - `{ mount }`.
  * @returns {{pages: object[], fmLinkFindings: object[]}}
@@ -287,7 +299,7 @@ export function collectTreePages(tree, ctx) {
         const rel = path.relative(tree.from, file).replace(/\\/g, "/");
         const base = path.basename(rel);
         const isReadme = base.toLowerCase() === "readme.md";
-        const sec = fm.subType ?? tree.section;
+        const sec = tree.section;
         const h1 = /^#\s+(.+?)\s*$/m.exec(body);
         const h1Title = h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
         const name = fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");
@@ -615,9 +627,13 @@ 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 {(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 }) {
+export function pageFrontmatter(page, { readmeSections = {}, decorate, webSrc }) {
     const { fm, name, slug, sec, isReadme } = page;
     let data;
     if (page.kind === "content") {
@@ -649,9 +665,40 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
         if (meta) Object.assign(data, sectionFrontmatter(meta));
     }
     delete data.aliases;
+    if (webSrc) resolveArtFields(data, webSrc);
     return data;
 }
 
+/**
+ * Rewrite a page's artwork fields into the addresses 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.
+ *
+ * @param {object} data - The frontmatter being emitted, rewritten in place.
+ * @param {(src: string) => string} webSrc - The website's resolver.
+ * @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];
+        if (typeof value !== "string" || value === "") continue;
+        holder[key] = webSrc(value);
+    }
+}
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Where a page is written, relative to the output root.
  *
@@ -696,7 +743,8 @@ export function pageDestination(page) {
  *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs.
- * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}
+ * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
+ *   wikiErrors: object[], imageErrors: object[]}}
  */
 export function renderPages(pages, options) {
     const {
@@ -709,12 +757,54 @@ export function renderPages(pages, options) {
         decorate,
         linkable = (d) => Boolean(d.fm.shortcode),
         sqlTables,
+        config,
     } = options;
 
     const tableErrors = [];
     const wikiErrors = [];
+    const imageErrors = [];
     const byKind = {};
 
+    /**
+     * The address the website serves for one authored pathname.
+     *
+     * A pathname the rule refuses, and a package-owned one with no asset host
+     * to resolve against, are both reported and emitted as authored: a page
+     * still publishes, with a picture the reader can see is missing, and the
+     * build exits non-zero. The occurrence count is what lets the command find
+     * the literal in the note and report a line and a column, the way a
+     * wikilink finding is located.
+     *
+     * @param {string} file - The note, for the finding.
+     * @returns {(src: string) => string} The resolver for that note's images.
+     */
+    const webAddresses = (file) => {
+        /** @type {Map<string, number>} */
+        const seen = new Map();
+        return (src) => {
+            const occurrence = (seen.get(src) ?? 0) + 1;
+            seen.set(src, occurrence);
+            const problem = pathnameProblem(src);
+            if (problem) {
+                imageErrors.push({ file, src, occurrence, message: problem });
+                return src;
+            }
+            const forms = resolvePathname(src, config);
+            if (!forms || forms.web !== null) return forms?.web ?? src;
+            imageErrors.push({
+                file,
+                src,
+                occurrence,
+                message:
+                    `\`${src}\` names a file the \`${forms.package}\` package ships, and ` +
+                    "no asset host is configured to serve it from — set `site.assets` in " +
+                    "package-build.config.yaml. Emitted as authored, the address resolves " +
+                    "against the page's own URL, which is nowhere",
+            });
+            return src;
+        };
+    };
+
     for (const page of pages) {
         // The page's path in the tree an author edits: below the content root
         // for a content note, below the tree's own root for a `trees` page. It
@@ -729,12 +819,17 @@ export function renderPages(pages, options) {
             foreignIndex: foreign.index,
         });
 
+        const webSrc = webAddresses(page.file);
         const resolve = (text) => {
             let t = text;
             if (pass.beforeLinks) t = pass.beforeLinks(t, page);
             t = resolveWebWikilinks(t, ctx);
             if (pass.afterLinks) t = pass.afterLinks(t, page);
-            return t;
+            // Last, so a consumer's own rewrites see the image as the note
+            // wrote it rather than as a figure. Hugo is handed markdown, not a
+            // rendered page, so a `{…}` directive left in the body would reach
+            // the reader as its own literal braces.
+            return renderImageFigures(t, webSrc);
         };
 
         let body = page.body;
@@ -756,14 +851,14 @@ export function renderPages(pages, options) {
             body = markdown;
         }
 
-        const data = pageFrontmatter(page, { readmeSections, decorate });
+        const data = pageFrontmatter(page, { readmeSections, decorate, webSrc });
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors };
+    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors };
 }
 
 /**
@@ -963,7 +1058,7 @@ export function resolveOutputRoot(rootDir, out) {
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
  */
 export function buildSite({ config, outRoot, sqlTables } = {}) {
     const resolved = config ?? loadPackConfig();
@@ -1057,6 +1152,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             manifests: null,
             tableErrors: [],
             wikiErrors: [],
+            imageErrors: [],
             stats: null,
         };
     }
@@ -1074,6 +1170,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             manifests: null,
             tableErrors: [],
             wikiErrors: [],
+            imageErrors: [],
             stats: {
                 homepages: writeHomepages(homeRoot, homepages, resolved),
                 landings: 0,
@@ -1125,6 +1222,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             stats: null,
             tableErrors: [],
             wikiErrors: [],
+            imageErrors: [],
         };
     }
 
@@ -1136,6 +1234,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
     const rendered = renderPages(pages, {
         outRoot: out,
         sqlTables,
+        config: resolved,
         index: gates.index,
         foreign: gates.foreign,
         universe: tableUniverse(pages),
@@ -1149,6 +1248,13 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
             if (isBeing(page.fm)) {
                 data.sohl = deriveBeingInfo(page.fm.sohl, gates.index.refIndex);
             }
+            // The declared infobox, travelling in the page's own front matter.
+            // The site theme draws it; what it holds is settled here, so the
+            // same panel reaches the website, a compendium journal and the
+            // book from one definition.
+            data.infoboxes = noteInfoboxes(page.fm, {
+                resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
+            });
         },
     });
 
@@ -1166,6 +1272,7 @@ export function buildSite({ config, outRoot, sqlTables } = {}) {
         gates,
         tableErrors: rendered.tableErrors,
         wikiErrors: rendered.wikiErrors,
+        imageErrors: rendered.imageErrors,
         stats: {
             ...rendered.byKind,
             homepages: homepagesWritten,

package/engine/site-index.mjs

@@ -95,9 +95,10 @@ import { isDraftNote } from "./note-vocabulary.mjs";
  * @property {Set<string>} contentTypes  Every type the resolver should read as
  *                                       an address qualifier, local and foreign.
  * @property {Set<string>} sections      Section names, lowercased.
- * @property {Map<string, {name: string, url: string}>} refIndex  `type:shortcode`
- *                                       → page, for callers resolving embedded
- *                                       references (a being's items, say).
+ * @property {Map<string, {name: string, url: string, subType?: string}>} refIndex
+ *                                       `type:shortcode` → page, for callers
+ *                                       resolving embedded references (a
+ *                                       being's items, say).
  * @property {{key: string, package: string}[]} conflicts  Addresses claimed by
  *                                       more than one package. Non-empty is a
  *                                       build failure; the caller reports it.
@@ -230,13 +231,23 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
         if (e.kind !== "content") continue;
         const type = String(e.fm.type).toLowerCase();
         contentTypes.add(type);
-        const value = { url: e.url, name: e.name, draft: isDraftNote(e.fm) };
+        // `subType` rides along because a caller resolving a reference often
+        // needs to know what it found, not only where it is: an infobox groups
+        // a being's skills by the family each skill note declares, and that
+        // fact lives on the target rather than on the reference.
+        const value = {
+            url: e.url,
+            name: e.name,
+            draft: isDraftNote(e.fm),
+            ...(e.fm.subType ? { subType: e.fm.subType } : {}),
+        };
 
         const shortcode = e.fm.shortcode;
         if (typeof shortcode === "string" && shortcode) {
             refIndex.set(`${e.fm.type}:${shortcode}`, {
                 name: e.name,
                 url: e.url,
+                ...(e.fm.subType ? { subType: e.fm.subType } : {}),
             });
             index.set(`${type}/${shortcode}`.toLowerCase(), value);
             // The canonical address alongside the short one. The short form
@@ -338,3 +349,81 @@ export function wikiContext(built, { src, file, type = null, errors, foreignInde
         file,
     };
 }
+
+/**
+ * Resolve one infobox reference against a site index.
+ *
+ * A note writes a reference three ways and all three reach here: a bare
+ * **shortcode** (`slntlncmpny`), a short **address** (`affiliation-slntlncmpny`)
+ * and a **canonical** one (`sohl-sohl-skill-melee`). The first is the ordinary
+ * case and the ambiguous one — a shortcode is unique within a type and not
+ * across a tree — so a caller that knows what it expects passes `hint.type`
+ * and the lookup is narrowed to it.
+ *
+ * **Without a hint the types are tried in sorted order**, so two trees holding
+ * the same note resolve it the same way. A shortcode two types both claim
+ * answers with the first alphabetically, which is a stable wrong answer rather
+ * than an unstable one; a caller that cares supplies the hint.
+ *
+ * The `address` on the answer is the slug form — `type-shortcode` — because
+ * that is what the book's own link map is keyed by and what a wikilink is
+ * written as.
+ *
+ * @param {SiteIndex} siteIndex - The index.
+ * @param {unknown} ref - The reference, as authored.
+ * @param {object} [hint] - `{type}`, where the caller knows it.
+ * @returns {{name?: string, url?: string, address?: string, subType?: string}|undefined}
+ *   The page, or `undefined` where nothing answers.
+ */
+export function resolveInfoboxRef(siteIndex, ref, hint) {
+    if (typeof ref !== "string" || !ref) return undefined;
+    const wanted = ref.toLowerCase();
+    const keys = [];
+    if (hint?.type) keys.push(`${String(hint.type).toLowerCase()}/${wanted}`);
+    // An authored address already names its own type, so it is tried whole
+    // before the type sweep — `affiliation-slntlncmpny` must not be read as a
+    // shortcode of some other type that happens to spell it.
+    if (wanted.includes("-")) {
+        keys.push(wanted);
+        const segments = wanted.split("-");
+        if (segments.length >= 2) {
+            keys.push(`${segments[segments.length - 2]}/${segments[segments.length - 1]}`);
+        }
+    }
+    if (!hint?.type) {
+        for (const type of [...(siteIndex?.contentTypes ?? [])].sort()) {
+            keys.push(`${type}/${wanted}`);
+        }
+    }
+    for (const key of keys) {
+        const found = siteIndex?.index?.get(key);
+        if (!found) continue;
+        const slug = key.includes("/") ? key.replace("/", "-") : addressSlugOfKey(key);
+        // No `uuid`, although a foreign entry carries one: this resolver
+        // answers for the **published** surfaces, which address a page by URL
+        // and an entry in the book by its slug. A compendium reference is what
+        // `resolveReference` answers with, from the compile's own index.
+        return {
+            ...(found.name ? { name: found.name } : {}),
+            ...(found.url ? { url: found.url } : {}),
+            ...(found.subType ? { subType: found.subType } : {}),
+            address: slug,
+        };
+    }
+    return undefined;
+}
+
+/**
+ * The `type-shortcode` slug of a canonical key.
+ *
+ * A canonical key is `package-system-type-shortcode`, and its slug is the last
+ * two segments — the same rule `contentAddress` states, applied to a key
+ * rather than to frontmatter.
+ *
+ * @param {string} key - The canonical key.
+ * @returns {string} The slug.
+ */
+function addressSlugOfKey(key) {
+    const segments = String(key).split("-");
+    return segments.length >= 2 ? segments.slice(-2).join("-") : key;
+}

package/engine/wikilinks.mjs

@@ -781,3 +781,96 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
 
     return { markdown: out, unresolved };
 }
+
+/**
+ * The short `type/shortcode` view of an index's foreign entries.
+ *
+ * Derived once per index and memoised: a compile resolves references on every
+ * one of thousands of notes, and rebuilding the view per note would rescan a
+ * dependency's whole published index each time. Keyed on the index object, so
+ * it is discarded with it.
+ *
+ * An address two foreign packages both claim is left out rather than resolved
+ * to whichever loaded first — the same rule the wikilink resolver follows.
+ *
+ * @type {WeakMap<object, Map<string, object>>}
+ */
+const FOREIGN_BY_SHORTCODE = new WeakMap();
+
+/** The memoised short view of `index.foreign`. */
+function foreignByShortcode(index) {
+    const cached = FOREIGN_BY_SHORTCODE.get(index);
+    if (cached) return cached;
+    const short = new Map();
+    const ambiguous = new Set();
+    for (const [key, value] of index?.foreign ?? []) {
+        const parts = readCanonicalKey(key);
+        if (!parts) continue;
+        const shortKey = `${norm(parts.type)}/${norm(parts.shortcode)}`;
+        if (short.has(shortKey) && short.get(shortKey).package !== value.package) {
+            ambiguous.add(shortKey);
+        } else {
+            short.set(shortKey, value);
+        }
+    }
+    for (const key of ambiguous) short.delete(key);
+    FOREIGN_BY_SHORTCODE.set(index, short);
+    return short;
+}
+
+/**
+ * Resolve one reference against a compile's address index.
+ *
+ * The compile-time counterpart of
+ * {@link module:engine/site-index.resolveInfoboxRef}: the same three authored
+ * forms — a bare shortcode, a short address, a canonical one — answered with
+ * what a **compendium** can use. A local target answers with the UUID its own
+ * document was addressed by; a foreign one with the UUID its package
+ * published.
+ *
+ * @param {object} index - From {@link buildWikilinkIndex}.
+ * @param {unknown} ref - The reference, as authored.
+ * @param {object} [hint] - `{type}`, where the caller knows what it expects.
+ * @returns {{name?: string, uuid?: string, address?: string, subType?: string}|undefined}
+ *   The target, or `undefined` where nothing answers.
+ */
+export function resolveReference(index, ref, hint) {
+    if (typeof ref !== "string" || !ref) return undefined;
+    const wanted = norm(ref);
+    const keys = [];
+    if (hint?.type) keys.push(`${norm(hint.type)}/${wanted}`);
+    if (wanted.includes("-")) {
+        const segments = wanted.split("-");
+        if (segments.length >= 2) {
+            keys.push(`${segments[segments.length - 2]}/${segments[segments.length - 1]}`);
+        }
+    }
+    if (!hint?.type) {
+        for (const type of [...(index?.types ?? [])].sort()) keys.push(`${type}/${wanted}`);
+    }
+
+    const foreign = foreignByShortcode(index);
+    for (const key of keys) {
+        const local = index?.byShortcode?.get(key);
+        if (local) {
+            return {
+                ...(local.name ? { name: local.name } : {}),
+                ...(local.subType ? { subType: local.subType } : {}),
+                ...(index.uuidByDoc?.get(local)?.uuid ?
+                    { uuid: index.uuidByDoc.get(local).uuid }
+                :   {}),
+                address: key.replace("/", "-"),
+            };
+        }
+        const away = foreign.get(key);
+        if (away) {
+            return {
+                ...(away.name ? { name: away.name } : {}),
+                ...(away.uuid ? { uuid: away.uuid } : {}),
+                ...(away.subType ? { subType: away.subType } : {}),
+                address: key.replace("/", "-"),
+            };
+        }
+    }
+    return undefined;
+}

package/hm3/default-item-art.mjs

@@ -19,12 +19,11 @@
  * no `img:` of its own, rather than shipping a mismatched icon. So every type
  * `item-builders.mjs` declares has a row here.
  *
- * **Paths are fully resolved.** `resolveImg` rewrites a leading `icons/` or
- * `images/` to the *consuming package's* asset root, which is not where these
- * live: they are shipped by the HM3 system. Written as `systems/hm3/images/…`
- * they pass through untouched and address the icons HM3's own compendiums
- * already use, so an item compiled from a note looks like its hand-authored
- * neighbours.
+ * **Paths name the package that owns the file.** These icons are not the
+ * consuming package's — they are shipped by the HM3 system — so they are
+ * written `hm3/assets/…` and each surface derives its own address from that.
+ * That addresses the icons HM3's own compendiums already use, so an item
+ * compiled from a note looks like its hand-authored neighbours.
  *
  * **A one-to-many type gets one default**, because art is keyed by note type
  * and a note type is what a registry entry addresses. `weapongear` compiles
@@ -42,15 +41,15 @@
  * @type {Readonly<Record<string, string>>}
  */
 export const HM3_DEFAULT_ITEM_ART = Object.freeze({
-    armorgear: "systems/hm3/images/icons/svg/armor.svg",
-    armorlocation: "systems/hm3/images/icons/svg/anatomy.svg",
-    containergear: "systems/hm3/images/icons/svg/sack.svg",
-    miscgear: "systems/hm3/images/icons/svg/miscgear.svg",
-    mysticalability: "systems/hm3/images/icons/svg/psionics.svg",
-    projectilegear: "systems/hm3/images/icons/svg/arrow.svg",
-    skill: "systems/hm3/images/icons/svg/skills.svg",
-    trauma: "systems/hm3/images/icons/svg/injury.svg",
-    weapongear: "systems/hm3/images/icons/svg/sword.svg",
+    armorgear: "hm3/assets/images/icons/svg/armor.svg",
+    armorlocation: "hm3/assets/images/icons/svg/anatomy.svg",
+    containergear: "hm3/assets/images/icons/svg/sack.svg",
+    miscgear: "hm3/assets/images/icons/svg/miscgear.svg",
+    mysticalability: "hm3/assets/images/icons/svg/psionics.svg",
+    projectilegear: "hm3/assets/images/icons/svg/arrow.svg",
+    skill: "hm3/assets/images/icons/svg/skills.svg",
+    trauma: "hm3/assets/images/icons/svg/injury.svg",
+    weapongear: "hm3/assets/images/icons/svg/sword.svg",
 });
 
 /**

package/hm3/index.mjs

@@ -51,6 +51,9 @@ export * as actors from "./actors.mjs";
 /** Where HM3 records the template priority — one rule, called by both compilers. */
 export * as templatePriority from "./template-priority.mjs";
 
+/** Which of HM3's facts a note's summary panel carries. */
+export * as infobox from "./infobox.mjs";
+
 // Flat as well as namespaced, matching the SoHL barrel: the default-art map is
 // the one export a Foundry runtime would import by name.
 export { HM3_DEFAULT_ITEM_ART, hm3DefaultItemArt } from "./default-item-art.mjs";