@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/ids.mjs

@@ -0,0 +1,192 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Deterministic document ids, derived by hashing rather than stored.
+ *
+ * Several pack-build passes must agree on an id without being able to see each
+ * other's output — the items pass and the journals pass on an item doc's entry
+ * id, a section link and the page it addresses on that page's id. They agree by
+ * deriving the id from the same inputs, so the derivation has to be reachable
+ * from every one of them.
+ *
+ * That is why this is its own module and not part of `helpers.mjs`: link
+ * resolution needs it, and `helpers.mjs` imports the link resolver. A leaf with
+ * no local imports can be depended on from anywhere without a cycle.
+ */
+
+import crypto from "crypto";
+
+/**
+ * Stable 16-char hex id derived from `${namespace}:${value}`. Use for deriving
+ * page ids from heading text when no explicit id is supplied.
+ *
+ * @param {string} namespace - Keeps unrelated derivations from colliding.
+ * @param {string} value - The input the id is a function of.
+ * @returns {string} A 16-character hexadecimal Foundry id.
+ */
+export function makeId(namespace, value) {
+    return crypto
+        .createHash("sha1")
+        .update(`${namespace}:${value}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+
+/**
+ * Every content type that compiles into a Foundry `Scene` — a **map note**
+ * (#1525). The three differ only in derived canvas defaults, which is the map
+ * compiler's business; everything else treats them alike.
+ *
+ * Declared in this leaf module because several passes that must not depend on
+ * the map compiler need it: the pack router below, and the doc-carrying type
+ * set in `item-docs.mjs` (a map note's prose becomes a JournalEntry, exactly as
+ * an item's or a macro's does).
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const MAP_TYPES = Object.freeze(
+    new Set(["battlemap", "localmap", "regionalmap"]),
+);
+
+/**
+ * Content type → the pack its documents compile into, and the document type
+ * that pack holds.
+ *
+ * These are pack **names**, not addresses. The package that owns the pack is
+ * supplied by the caller, because it is a property of the repository doing the
+ * building and not of the content: the same notes compiled by a different
+ * repository belong to a different package. Baking the package into these
+ * values is what made every link emitted by `sohl-thalorna` address the `sohl`
+ * system (#1498) — correct here only by coincidence.
+ *
+ * @type {Readonly<Record<string, {pack: string, docType: string}>>}
+ */
+export const PACK_BY_TYPE = Object.freeze({
+    doc: { pack: "journals", docType: "JournalEntry" },
+    macro: { pack: "macros", docType: "Macro" },
+    being: { pack: "actors", docType: "Actor" },
+    ...Object.fromEntries(
+        [...MAP_TYPES].map((type) => [
+            type,
+            { pack: "scenes", docType: "Scene" },
+        ]),
+    ),
+});
+
+/**
+ * Content types that no longer exist, and what replaced each one.
+ *
+ * `character` and `creature` were retired in favour of the single `being` they
+ * had always compiled into (SoHL#1580). They are recorded here rather than
+ * simply deleted because deleting them is the one change that fails *quietly*:
+ * every type not named in {@link PACK_BY_TYPE} falls through to the open item
+ * set below, so a note or a link left on the old spelling would be routed to
+ * the items pack — a wrong answer, arrived at silently, which is exactly the
+ * failure mode the open-set default exists to avoid for real item types.
+ *
+ * Keeping the names lets {@link assertTypeNotRetired} say what happened and
+ * what to write instead. Entries stay for as long as content in the wild might
+ * still carry them.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RETIRED_TYPES = Object.freeze({
+    character: "being",
+    creature: "being",
+});
+
+/**
+ * Throw if `type` names a retired content type.
+ *
+ * @param {string} type - The note's declared `type`, or a link's qualifier.
+ * @param {string} [where] - What carries it — a file path, a link target —
+ *   appended to the message so the reader can go straight to it.
+ * @throws {Error} Naming the replacement type.
+ */
+export function assertTypeNotRetired(type, where) {
+    const replacement = RETIRED_TYPES[type];
+    if (!replacement) return;
+    throw new Error(
+        `Content type "${type}" was retired in favour of "${replacement}"` +
+            (where ? ` — ${where}` : "") +
+            `. Both compiled to the same document, so the fix is mechanical: ` +
+            `write "${replacement}".`,
+    );
+}
+
+/** Where every other content type compiles: the items pack. */
+export const ITEM_PACK = Object.freeze({ pack: "items", docType: "Item" });
+
+/**
+ * The pack a type's documents live in, in the conventional one-pack-per-type
+ * layout.
+ *
+ * Item types are the open set — a new one is added whenever the system grows a
+ * document type — so they are the **default** rather than an enumerated list. A
+ * hand-maintained list is what made an entire content directory silently
+ * unlinkable once (#1276); nothing to maintain, nothing to forget.
+ *
+ * The `docType` is the authority: it is a property of the *content type* and
+ * holds however a repository names or splits its packs. The `pack` is the
+ * conventional name only — a repository may rename its packs, or ship several
+ * of one type (#1566), in which case the pack a particular note's document
+ * lands in comes from `engine/pack-router.mjs` and is passed to
+ * {@link compendiumUuid} explicitly. This module stays free of the
+ * configuration so the link resolver above it can stay pure.
+ *
+ * @param {string} type - The target note's `type`.
+ * @returns {{pack: string, docType: string}} The pack and document type.
+ * @throws {Error} If `type` names a retired content type — see
+ *   {@link RETIRED_TYPES}. The open-set default would otherwise route it to the
+ *   items pack and say nothing.
+ */
+export function packForType(type) {
+    assertTypeNotRetired(type);
+    return PACK_BY_TYPE[type] ?? ITEM_PACK;
+}
+
+/**
+ * A document's full compendium UUID.
+ *
+ * This is the one place a UUID is spelled. Every link is resolved by looking up
+ * an address computed here — never by concatenating a prefix at the point of
+ * use, which is how the package came to be hard-coded in two separate files.
+ *
+ * @param {string} packageId - The Foundry package that ships the pack, e.g.
+ *   `sohl`. A system id or a module id; Foundry addresses both the same way.
+ * @param {string} type - The note's content `type`.
+ * @param {string} id - The document's id.
+ * @param {string} [packName] - The pack the document actually landed in, from
+ *   the pack router. Supplied wherever the note is known, because a repository
+ *   may ship several packs of one type and a UUID carries the pack name
+ *   (#1566). Omitted only where there is no note to route — the conventional
+ *   name from {@link packForType} then stands in.
+ * @returns {string} `Compendium.<packageId>.<pack>.<DocumentType>.<id>`
+ */
+export function compendiumUuid(packageId, type, id, packName) {
+    const { pack, docType } = packForType(type);
+    return `Compendium.${packageId}.${packName || pack}.${docType}.${id}`;
+}
+
+/**
+ * The UUID of a JournalEntry page.
+ *
+ * @param {string} entryUuid - The owning entry's UUID, from
+ *   {@link compendiumUuid}.
+ * @param {string} pageId - The page's id.
+ * @returns {string} The page's UUID.
+ */
+export function pageUuid(entryUuid, pageId) {
+    return `${entryUuid}.JournalEntryPage.${pageId}`;
+}

package/engine/index.mjs

@@ -0,0 +1,142 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The package-agnostic half of the toolchain: everything that knows how a
+ * HeroicLands content tree is shaped, but nothing about any particular game
+ * system's data model.
+ *
+ * The content walk, frontmatter parsing, table generation, wikilink
+ * resolution, id and folder derivation, the link manifest and the web-address
+ * rule, `BasePackCompiler`, and the generic Foundry document compilers
+ * (journals, macros, scenes) all live here (#1512).
+ *
+ * **Each module is re-exported as its own namespace, not flattened.** Several
+ * of them deliberately re-export a neighbour's symbol so a caller keeps one
+ * import path (`helpers` re-exports the frontmatter readers and `makeId`;
+ * `wikilinks` re-exports the pack router). Flattened, every such name would
+ * become an ambiguous star export and vanish from this barrel silently. Each
+ * module is also reachable as its own entry point —
+ * `@heroiclands/package-build/engine/<module>` — which is how a build that
+ * needs one thing avoids loading the whole pipeline.
+ *
+ * @module
+ */
+
+/** Deterministic document ids, the conventional pack map, and compendium UUIDs. */
+export * as ids from "./ids.mjs";
+
+/** Fenced-code detection, so a rewrite never edits a code block. */
+export * as codeFences from "./code-fences.mjs";
+
+/** The `sohl:` frontmatter readers, shared by every content package. */
+export * as frontmatter from "./frontmatter.mjs";
+
+/** The content walk's note census — the empty-tree guard's evidence. */
+export * as contentTree from "./content-tree.mjs";
+
+/** The consuming repository's resolved `package-build.config.yaml`. */
+export * as packConfig from "./pack-config.mjs";
+
+/** Which pack of a document type a note's document lands in (#1566). */
+export * as packRouter from "./pack-router.mjs";
+
+/** The content package a build compiles, and the Foundry package it ships in. */
+export * as contentPackage from "./content-package.mjs";
+
+/** The shipped Foundry manifest: locating it, reading it, guarding its id. */
+
+/** The URL a content note is published at — the one web-address rule. */
+export * as contentSlug from "./content-slug.mjs";
+
+/** Section and address derivation on top of {@link contentSlug}. */
+export * as contentAddress from "./content-address.mjs";
+
+/** Whether a vendored manifest can still be addressed, not merely read. */
+export * as foreignManifests from "./foreign-manifests.mjs";
+
+/** The cross-package link manifest: reader, writer, and canonical keys. */
+export * as kbManifest from "./kb-manifest.mjs";
+
+/** Deriving this package's own link manifest from its content tree. */
+export * as manifestEmit from "./manifest-emit.mjs";
+
+/** Publishing a content tree as a website: the pass, and its integrity gates. */
+export * as siteBuild from "./site-build.mjs";
+
+/** Address rules every content tree is linted against: shape, uniqueness, alias. */
+export * as contentLint from "./content-lint.mjs";
+
+/** Resolving every link in a tree, and the ones that land nowhere. */
+export * as contentLinks from "./content-links.mjs";
+
+/** Wikilinks resolved to a **web URL** — the site half of the pair below. */
+export * as webWikilinks from "./web-wikilinks.mjs";
+
+/** Dataview-style content tables, expanded into markdown at compile time. */
+export * as contentTables from "./content-tables.mjs";
+
+/** Markdown parsing, stats, folders, images, and the wikilink index. */
+export * as helpers from "./helpers.mjs";
+
+/** The consumer's resolved item-type registry: the whitelist and its builders. */
+export * as itemRegistry from "./item-registry.mjs";
+
+/** Which types carry documentation of their own, and where it is addressed. */
+export * as itemDocs from "./item-docs.mjs";
+
+/** Wikilinks resolved to a **Foundry UUID**: qualifiers, the index, rewriting. */
+export * as wikilinks from "./wikilinks.mjs";
+
+/** What a `[[…]]` is, before either resolver decides where it points. */
+export * as wikilinkSyntax from "./wikilink-syntax.mjs";
+
+/** The address index a site build resolves its wikilinks against. */
+export * as siteIndex from "./site-index.mjs";
+
+/** The shape every pack compiler shares. */
+export * as baseCompiler from "./base-compiler.mjs";
+
+/** The JournalEntry compiler, and the page/anchor derivation it shares. */
+export * as journals from "./journals.mjs";
+
+/** The Macro compiler. */
+export * as macros from "./macros.mjs";
+
+/** The map-note schema a Scene is authored in. */
+export * as mapNotes from "./map-notes.mjs";
+
+/** The Scene and Adventure compiler. */
+export * as scenes from "./scenes.mjs";
+
+/** The compiled-pack Scene/Level integrity guard. */
+export * as sceneLevels from "./scene-levels.mjs";
+
+/** Pack JSON generation — the pass that turns a content tree into documents. */
+export * as generate from "./generate.mjs";
+
+/** Compile, unpack, and clean the LevelDB packs. */
+export * as compendiums from "./compendiums.mjs";
+
+// The region-event vocabulary stays flat as well as namespaced: the Foundry
+// runtime imports these three by name through
+// `@heroiclands/package-build/engine/region-events`, and they were part of this
+// barrel's surface before the pipeline arrived (#1510).
+export {
+    CURATED_REGION_EVENTS,
+    EXCLUDED_REGION_EVENTS,
+    REGION_EVENT_TO_TRIGGER,
+} from "./region-events.mjs";
+
+/** The curated region-event vocabulary, shared with the Foundry runtime. */
+export * as regionEvents from "./region-events.mjs";

package/engine/item-docs.mjs

@@ -0,0 +1,153 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **Item docs** — an item's prose compiled as a JournalEntry, with the item
+ * keeping only a pointer to it.
+ *
+ * An item note's body describes what the thing *is*. That is documentation, and
+ * documentation belongs in the journals pack, so each item note compiles into a
+ * JournalEntry and the item's `system.docHtml` becomes nothing but a `@UUID`
+ * link to that entry's first page — the description-as-pointer convention
+ * (#1356), which {@link sohl.utils.descriptionLinkTarget} recognises and
+ * Display Description follows.
+ *
+ * The prose then exists once. Previously every actor carrying an item carried
+ * its own copy of that item's description: 7.59 MB across the actors pack, of
+ * which only 133 KB was distinct text (#1348). Nothing about actors changes —
+ * they embed whatever the item carries, and what the item carries is now a link.
+ *
+ * **Two passes, no shared state.** The items pass writes the pointer; the
+ * journals pass writes the entry it points at. Neither can see the other's
+ * output, so both derive the same ids from the item note's own id — the same
+ * technique {@link anchorPageId} uses to let a section link and its page agree.
+ *
+ * **The shape generalises.** A `macro` note is the same arrangement: it
+ * compiles into a Macro, and its prose into a JournalEntry addressed
+ * `docmacro/<shortcode>` (#1514). So is a **map note**, which compiles into a
+ * Scene and whose prose becomes the place description its map pins point at
+ * (#1525). {@link docEntryTypes} is the one set both the compilers and the
+ * link manifest read to know which types work this way.
+ *
+ * Plain ESM with no Foundry and no filesystem access, so it is unit-testable.
+ */
+
+import { compendiumUuid, makeId, pageUuid } from "./ids.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { itemTypes } from "./item-registry.mjs";
+import { packRouter } from "./pack-router.mjs";
+
+/**
+ * Every content type that compiles into an item — and therefore into an item
+ * doc. Re-exported here rather than restated because both passes need it: the
+ * items pass to know what to compile, the journals pass to know whose prose it
+ * is holding.
+ *
+ * It is the consuming repository's `itemBuilders` keys, resolved once in
+ * `item-registry.mjs` alongside the builder lookup the Item compiler dispatches
+ * through — one object, so the whitelist and the table cannot disagree
+ * (#1504/#1563).
+ */
+export { itemTypes };
+
+/**
+ * Every content type whose **prose compiles into a JournalEntry of its own**,
+ * addressed by the virtual `doc<type>` qualifier.
+ *
+ * Every item type, plus `macro` — a macro note's body documents the script the
+ * note also compiles into a Macro (#1514), which is the same shape as an item
+ * and its description: one note, two documents, the prose living in the
+ * journals pack.
+ *
+ * **One set, read by the compiler and the emitter alike.** The journals pass
+ * decides what to compile from it, and the link manifest decides what to
+ * publish a `doc<type>` entry for. Held apart, the two drift into a manifest
+ * that asserts documentation nothing compiled — or a compiled entry no
+ * consumer can address. It is composed exactly once, in `defineConfig`, and
+ * read from there — never recomposed at a call site.
+ *
+ * `doc` notes and actors are absent: each is a single document, so it has no
+ * separate documentation to address.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {ReadonlySet<string>} The configured doc-carrying types.
+ */
+export function docEntryTypes() {
+    return loadPackConfig().docEntryTypes;
+}
+
+/**
+ * Whether a content note's type is one whose prose becomes a JournalEntry of
+ * its own.
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {boolean} True for an item type, for `macro` and for a map type;
+ *   false for `doc` and for actors.
+ */
+export function hasDocEntry(type) {
+    return docEntryTypes().has(String(type));
+}
+
+/**
+ * The id of the JournalEntry a note's prose compiles into — an item's, or a
+ * macro's.
+ *
+ * Derived from the note's own id so that the pass writing the document and the
+ * pass writing its documentation agree without either reading the other's
+ * output. It is deliberately not the note's id itself: the two documents are
+ * distinct, live in different packs, and sharing an id would make either one's
+ * UUID ambiguous to read.
+ *
+ * The `"item-doc"` hash namespace is **frozen**: it is baked into every entry
+ * id already shipped, and every `@UUID` pointing at one. It names where the
+ * derivation started, not what may use it.
+ *
+ * @param {string} itemId - The note's `id` frontmatter.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function itemDocEntryId(itemId) {
+    return makeId("item-doc", itemId);
+}
+
+/**
+ * The description an item carries in place of its prose: a `@UUID` link to the
+ * first page of its item doc, and nothing else.
+ *
+ * "Nothing else" is the whole convention — a description that is *only* a link
+ * is a pointer, and anything alongside it would make it ordinary prose that
+ * happens to contain a link, which the runtime would then show verbatim.
+ *
+ * @param {string} packageId - The Foundry package shipping the journals pack.
+ *   Supplied rather than assumed (#1498).
+ * @param {string} itemId - The item note's `id` frontmatter.
+ * @param {string} name - The item's name, used as the link's label. It shows
+ *   only if the target ever fails to resolve, where a broken link naming the
+ *   item beats a bare UUID.
+ * @param {string} firstPageId - The id of the entry's first page, from
+ *   {@link journalPageId}.
+ * @returns {string} The pointer to store in `system.docHtml`.
+ */
+export function itemDocPointer(packageId, itemId, name, firstPageId) {
+    // An item doc is a *derived* document: it lands in the default
+    // JournalEntry pack whatever Item pack the item itself was routed to
+    // (#1566).
+    const entryUuid = compendiumUuid(
+        packageId,
+        "doc",
+        itemDocEntryId(itemId),
+        packRouter().defaultOf("JournalEntry"),
+    );
+    return `@UUID[${pageUuid(entryUuid, firstPageId)}]{${name}}`;
+}

package/engine/item-registry.mjs

@@ -0,0 +1,129 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **The resolved item-type registry** — the consuming repository's
+ * `itemBuilders` table, and the type whitelist derived from its keys.
+ *
+ * Both are read from the one resolved configuration, so they are literally the
+ * same object's keys and values: a type cannot be whitelisted for compilation
+ * without the builder that compiles it, which is the guarantee #1504 exists
+ * for. The Item compiler dispatches through {@link itemBuilder}, so the table a
+ * consumer configured is the table its notes compile with — the whitelist and
+ * the dispatch used to come from different places, and a consumer supplying its
+ * own registry got the types it asked for and the builders it did not (#1563).
+ *
+ * **The registry itself is a consumer's, and stays a leaf.** SoHL's lives in
+ * `@heroiclands/package-build/sohl/item-builders`; the consumer names it in
+ * `package-build.config.yaml`. That module must never read the resolved
+ * configuration — it is loaded *during* the resolution such a read would be
+ * asking for, whether the loader requires it by name for a data config or a
+ * code config imports it directly, so a read from there would close a cycle
+ * around the configuration's own evaluation. Data travels *into*
+ * configuration; only modules like this one, which nothing on that path
+ * imports, read back out of it.
+ *
+ * @module
+ */
+
+import { loadPackConfig } from "./pack-config.mjs";
+import { resolveImg } from "./helpers.mjs";
+
+/**
+ * Every content type that compiles into an item — and therefore into an item
+ * doc. Read by the Item compiler to know what to claim, and by the journals
+ * pass to know whose prose it is holding.
+ *
+ * **Derived, never authored.** These are the keys of the consuming
+ * repository's `itemBuilders` registry, so the whitelist and the builder table
+ * are the same list and cannot drift apart. They already had: `trait` was
+ * whitelisted long after the item type was retired (#651), with no builder
+ * behind it, so every `type: trait` note passed the gate and then failed to
+ * compile (#1504).
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {ReadonlySet<string>} The configured item types.
+ */
+export function itemTypes() {
+    return loadPackConfig().itemTypes;
+}
+
+/**
+ * The builder the consuming repository registered for an item type.
+ *
+ * Unreachable through the compiler — its whitelist *is* this registry's keys —
+ * so a throw here means a caller invented a type. It names the type rather than
+ * failing as an anonymous `is not a function` (#1504).
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {(fm: object) => object} The builder for that type.
+ * @throws {Error} When the configuration registers no builder for `type`.
+ */
+export function itemBuilder(type) {
+    const builder = /** @type {Record<string, Function>} */ (
+        loadPackConfig().itemBuilders
+    )[type];
+    if (typeof builder !== "function") {
+        throw new Error(
+            `No builder registered for item type "${type}" — add one to the ` +
+                `\`itemBuilders\` registry this repository declares in ` +
+                `package-build.config.yaml, or stop declaring the type.`,
+        );
+    }
+    return /** @type {(fm: object) => object} */ (builder);
+}
+
+/**
+ * The default art for an item type — the image a note of that type is given
+ * when it carries no `img:` of its own.
+ *
+ * Read from the consuming repository's `itemBuilders` registry, the same place
+ * the type itself is declared, so a consumer's own type can bring art a
+ * SoHL-owned table could never hold. Art used to be looked up in
+ * `sohl/default-item-art.mjs` instead: a type was configurable while its
+ * default art was not, so a second consumer's items compiled only if every one
+ * of its notes set `img:` (#7).
+ *
+ * **Still fail-fast.** A type with neither a note-level `img:` nor paired art
+ * aborts the pack build rather than shipping a mismatched icon — the contract
+ * `defaultItemArt` was written for. Only the error's *owner* changed: it now
+ * names the registry the consumer declares and can add to.
+ *
+ * **Resolved by the same rule a note's `img:` is.** The path goes through
+ * {@link resolveImg}, so `icons/relic.svg` means the consumer's own asset root
+ * in the registry exactly as it does on a note, and an already-served path
+ * (`systems/sohl/assets/…`, as every SoHL default is) passes through untouched.
+ * One spelling, one meaning, wherever it is written.
+ *
+ * @param {string} type - the item type.
+ * @returns {string} The default image path for that type.
+ * @throws {Error} When the type's registry entry pairs no `img`.
+ */
+export function itemArt(type) {
+    const art = /** @type {Record<string, string|undefined>} */ (
+        loadPackConfig().itemArt
+    )[type];
+    if (!art) {
+        throw new Error(
+            `No default art for item type "${type}" — the note carries no ` +
+                `\`img:\`, and the \`itemBuilders\` entry for "${type}" in this ` +
+                `repository's package-build.config.yaml pairs none with its ` +
+                `builder. Write the entry as ` +
+                `\`${type}: { system: <builder>, img: "<path>" }\`, or give the ` +
+                `note an \`img:\` of its own.`,
+        );
+    }
+    return resolveImg(art);
+}