@heroiclands/package-build 22.4.1 → 22.4.3

package/engine/actor-compiler.mjs

@@ -646,6 +646,29 @@ export class SystemActorCompiler extends BasePackCompiler {
         return referencedSubtype(this.documentSubtypes, type, "Item");
     }
 
+    /**
+     * The default art for an embedded item's type, when the entry names none
+     * of its own and copies no template that carries one.
+     *
+     * **The base case is {@link itemArt}**, keyed by the note vocabulary — the
+     * same table an item note's own compile defaults from, because most
+     * references are written in that vocabulary too (`weapongear`, `skill`,
+     * `armorgear`). It is not the whole answer: a reference into a one-to-many
+     * row may instead name one of the row's own **subtypes** directly — HM3's
+     * `spell`, `invocation` and `psionic` are never a note's own `type`, only
+     * `mysticalability`'s `hm3.type` discriminator ever writes them, so no
+     * note-type table has a row for them. A system whose one-to-many rows are
+     * addressed that way overrides this to answer for those subtypes too; see
+     * `hm3/actors.mjs`.
+     *
+     * @param {string} type - The **note** type the reference names.
+     * @param {string} subType - The document subtype it resolved to.
+     * @returns {string} The default image path.
+     */
+    embeddedItemArt(type, subType) {
+        return itemArt(type, this.system);
+    }
+
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *
@@ -825,7 +848,9 @@ export class SystemActorCompiler extends BasePackCompiler {
         // default answers last. Nullish coalescing throughout, so `icon: ""`
         // ships blank on purpose rather than collecting a default.
         merged.img =
-            this.artPath(overlay ?? {}, "icon") ?? merged.img ?? itemArt(type, this.system);
+            this.artPath(overlay ?? {}, "icon") ??
+            merged.img ??
+            this.embeddedItemArt(type, /** @type {string} */ (subType));
         const identity = embeddedIdentity(merged, this.system);
         const claim = `${actorId}\u0000${itemAddress(/** @type {string} */ (subType), identity)}`;
         const first = this.#embeddedClaims.get(claim);

package/engine/changelog-group.mjs

@@ -0,0 +1,256 @@
+/*
+ * 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
+ */
+
+/**
+ * Fold a release's changeset blocks together by their bold label.
+ *
+ * `@heroiclands/package-build/changelog` (`changelog.cjs`) writes each
+ * changeset's summary into `CHANGELOG.md` as its own block, verbatim, under
+ * `### <Bump> Changes` — one per changeset, in whatever order Changesets
+ * happened to read the files. A repository that groups its release prose by
+ * subject (`**Compendiums**`, `**Website**`) ends up with the same label
+ * opening several scattered blocks instead of one, because nothing ever
+ * merges them: three pull requests touching compendium content each write
+ * their own `**Compendiums**` block, and the release reads as three
+ * unrelated entries rather than one.
+ *
+ * `groupChangelogText` merges same-label blocks into one, in the display
+ * order `changelog.labels` declares, with the unlabelled lead paragraph
+ * first and any label absent from that vocabulary last. It reuses
+ * {@link module:engine/changelog-lint.topLevelBlocks} — the same block
+ * model `changelog check` reads a block's label from — rather than parsing
+ * the markdown a second way.
+ *
+ * @module
+ */
+
+import {
+    codeLineSet,
+    lineColOf,
+    releaseSectionRange,
+    topLevelBlocks,
+    topLevelBullets,
+} from "./changelog-lint.mjs";
+
+/** A `### <Bump> Changes` heading — the generated scaffold, never authored. */
+const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes$/gm;
+
+/**
+ * A labelled block's own `**Label**` line, split from everything after it.
+ *
+ * @param {string} blockText - One block, as {@link topLevelBlocks} collects
+ *   it — its first line is the label line for a labelled block.
+ * @returns {{labelLine: string, rest: string}} `rest` has its leading blank
+ *   line dropped; a block with nothing but the label line yields `""`.
+ */
+function splitLabelLine(blockText) {
+    const nl = blockText.indexOf("\n");
+    if (nl === -1) return { labelLine: blockText, rest: "" };
+    return { labelLine: blockText.slice(0, nl), rest: blockText.slice(nl + 1).replace(/^\n+/, "") };
+}
+
+/**
+ * A block's top-level items: its bullets, or — when it carries none — the
+ * whole thing as one paragraph item. This is what merging concatenates and
+ * deduplicates, so a bulleted `**Compendiums**` block and a prose one merge
+ * on the same footing.
+ *
+ * @param {string} text - A block's content, label line already stripped (or
+ *   a lead block's whole text).
+ * @returns {string[]}
+ */
+function itemsOf(text) {
+    const trimmed = text.replace(/\s+$/, "");
+    if (!trimmed) return [];
+    const bullets = topLevelBullets(trimmed, codeLineSet(trimmed));
+    if (bullets.length === 0) return [trimmed];
+    return bullets.map((bullet) => bullet.text.replace(/\s+$/, ""));
+}
+
+/**
+ * The first occurrence of each item, exact-duplicate text dropped, order
+ * preserved — the "an exact-duplicate bullet once" rule.
+ *
+ * @param {string[]} items
+ * @returns {string[]}
+ */
+function dedupeItems(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const key = item.trim();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+
+/**
+ * Join a merged group's items the way its own shape calls for: bullets
+ * adjacent, one to a line; a paragraph or a mix of paragraphs separated by a
+ * blank line, the same spacing a changeset's own multi-paragraph summary
+ * already uses.
+ *
+ * @param {string[]} items
+ * @returns {string}
+ */
+function joinItems(items) {
+    if (items.length === 0) return "";
+    const allBullets = items.every((item) => /^-\s/.test(item));
+    return items.join(allBullets ? "\n" : "\n\n");
+}
+
+/**
+ * One label's blocks (or every unlabelled one), folded into the single
+ * block `group` writes for it.
+ *
+ * @param {Array<{label: string|null, text: string}>} blocks - Every block
+ *   sharing one label, in file order. All carry the same `label`.
+ * @returns {string}
+ */
+function mergeGroup(blocks) {
+    if (blocks[0].label === null) {
+        return joinItems(dedupeItems(blocks.flatMap((block) => itemsOf(block.text))));
+    }
+    const { labelLine } = splitLabelLine(blocks[0].text);
+    const items = dedupeItems(blocks.flatMap((block) => itemsOf(splitLabelLine(block.text).rest)));
+    return items.length ? `${labelLine}\n\n${joinItems(items)}` : labelLine;
+}
+
+/**
+ * Where a group sorts, relative to the others in its section.
+ *
+ * The unlabelled lead group always sorts first, whether or not
+ * `changelog.labels` is declared — it is the summary a changeset writes with
+ * no category, and reads like the section's own opening line. A declared
+ * vocabulary then orders everything else by its position in that list, with
+ * an undeclared label sorted after every declared one; with no vocabulary
+ * declared at all, every labelled group keeps the order its label first
+ * appeared in.
+ *
+ * @param {string|null} key - A group's label, or `null` for the lead group.
+ * @param {string[]} appearanceOrder - Every key, in the order its first
+ *   block appeared in the section.
+ * @param {readonly string[]|null} labels - `changelog.labels`, or `null`.
+ * @returns {[number, number]} `[tier, rank]`, compared tier first.
+ */
+function groupRank(key, appearanceOrder, labels) {
+    if (key === null) return [-1, 0];
+    if (labels) {
+        const configured = labels.indexOf(key);
+        return configured === -1 ? [1, appearanceOrder.indexOf(key)] : [0, configured];
+    }
+    return [0, appearanceOrder.indexOf(key)];
+}
+
+/**
+ * Fold one `### <Bump> Changes` section's blocks together by label.
+ *
+ * @param {string} bodyText - Everything after the heading, up to the next
+ *   one or the end of the release section.
+ * @param {readonly string[]|null} labels - `changelog.labels`, in display
+ *   order, or `null` when the repository declares none.
+ * @returns {{text: string, unknown: Array<{label: string, startLine: number}>}}
+ *   The regrouped body (no leading or trailing blank lines), and every label
+ *   it wrote that `labels` does not declare, each at its merged block's
+ *   first-occurring line within `bodyText` — empty when `labels` is `null`,
+ *   since nothing is "unknown" against no vocabulary.
+ */
+function groupSection(bodyText, labels) {
+    const codeLines = codeLineSet(bodyText);
+    const blocks = topLevelBlocks(bodyText, codeLines);
+    if (blocks.length === 0) return { text: "", unknown: [] };
+
+    /** @type {string[]} */
+    const appearanceOrder = [];
+    /** @type {Map<string|null, Array<{label: string|null, text: string}>>} */
+    const groups = new Map();
+    for (const block of blocks) {
+        if (!groups.has(block.label)) {
+            groups.set(block.label, []);
+            appearanceOrder.push(block.label);
+        }
+        groups.get(block.label).push(block);
+    }
+
+    const sortedKeys = [...appearanceOrder].sort((a, b) => {
+        const [aTier, aRank] = groupRank(a, appearanceOrder, labels);
+        const [bTier, bRank] = groupRank(b, appearanceOrder, labels);
+        return aTier - bTier || aRank - bRank;
+    });
+
+    const unknown =
+        labels === null ?
+            []
+        :   sortedKeys
+                .filter((key) => key !== null && !labels.includes(key))
+                .map((key) => ({ label: key, startLine: groups.get(key)[0].startLine }));
+
+    const text = sortedKeys.map((key) => mergeGroup(groups.get(key))).join("\n\n");
+    return { text, unknown };
+}
+
+/**
+ * `changelog group`: fold the newest release's changeset blocks together by
+ * their bold label, order them, and file an undeclared one last.
+ *
+ * Every earlier release section is untouched, byte for byte — only the
+ * first `## <version>` section's `### <Bump> Changes` bodies are rewritten,
+ * each independently (a label groups within its own bump level, never
+ * across one). Running this on its own output is a no-op: a release already
+ * in label order, with each label merged to one block, groups to itself.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order. `null`/absent orders every group by first appearance
+ *   instead, lead paragraph first, and files nothing as unknown.
+ * @returns {{text: string, findings: Array<{line: number,
+ *   severity: "warning", message: string}>}}
+ */
+export function groupChangelogText(text, { labels = null } = {}) {
+    const range = releaseSectionRange(text);
+    if (!range) return { text, findings: [] };
+
+    const section = text.slice(range.start, range.end);
+    const headings = [...section.matchAll(CHANGES_HEADING_RE)];
+    if (headings.length === 0) return { text, findings: [] };
+
+    let rebuilt = section.slice(0, headings[0].index);
+    /** @type {Array<{line: number, severity: "warning", message: string}>} */
+    const findings = [];
+
+    for (let i = 0; i < headings.length; i++) {
+        const heading = headings[i];
+        const bodyStart = heading.index + heading[0].length;
+        const bodyEnd = i + 1 < headings.length ? headings[i + 1].index : section.length;
+        const { text: grouped, unknown } = groupSection(section.slice(bodyStart, bodyEnd), labels);
+
+        const isVeryLast = i === headings.length - 1 && range.end === text.length;
+        rebuilt += heading[0] + (grouped ? `\n\n${grouped}` : "") + (isVeryLast ? "\n" : "\n\n");
+
+        const { line: bodyFirstLine } = lineColOf(text, range.start + bodyStart);
+        for (const { label, startLine } of unknown) {
+            findings.push({
+                line: bodyFirstLine + (startLine - 1),
+                severity: "warning",
+                message:
+                    `changelog-group/unknown-label "${label}" is not declared in ` +
+                    "`changelog.labels` — filed last, in order of first appearance",
+            });
+        }
+    }
+
+    return { text: text.slice(0, range.start) + rebuilt + text.slice(range.end), findings };
+}

package/engine/changelog-lint.mjs

@@ -49,6 +49,9 @@ const TOP_BULLET_RE = /^-\s+/;
 /** A list item indented under something else. */
 const NESTED_BULLET_RE = /^[ \t]+[-*+]\s+/;
 
+/** A bold label opening a block at column 0: `**Compendiums**`. */
+const LABEL_LINE_RE = /^\*\*([^*]+)\*\*/;
+
 /** A commit-hash prefix: `- abc1234: …`, or a bare hex token opening the bullet. */
 const COMMIT_HASH_RE = /^-\s+([0-9a-fA-F]{7,40})(?=[:\s]|$)/;
 
@@ -92,7 +95,7 @@ const MAX_SECTION_LINES = 60;
  * @param {number} index - 0-based character offset.
  * @returns {{line: number, column: number}}
  */
-function lineColOf(text, index) {
+export function lineColOf(text, index) {
     const before = text.slice(0, Math.max(0, index));
     const nl = before.lastIndexOf("\n");
     return { line: before.split("\n").length, column: index - nl };
@@ -108,7 +111,7 @@ function lineColOf(text, index) {
  * @param {string} text - The section text.
  * @returns {Set<number>} Lines that fall inside a fenced or indented block.
  */
-function codeLineSet(text) {
+export function codeLineSet(text) {
     const lines = new Set();
     for (const region of codeRegions(text, { spans: false })) {
         const from = lineColOf(text, region.start).line;
@@ -185,7 +188,7 @@ function checkCodeFences(text) {
  *   {@link codeLineSet}.
  * @returns {Array<{startLine: number, text: string}>}
  */
-function topLevelBullets(text, codeLines) {
+export function topLevelBullets(text, codeLines) {
     const lines = text.split("\n");
     /** @type {Array<{startLine: number, text: string}>} */
     const bullets = [];
@@ -211,13 +214,93 @@ function topLevelBullets(text, codeLines) {
             continue;
         }
         // Column 0, not a bullet: a bold subsection label or a scaffold
-        // heading closes whatever bullet was open.
+        // heading closes whatever bullet was open — pushed here, or it is
+        // lost rather than merely closed.
+        if (current) bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
         current = null;
     }
     if (current) bullets.push({ startLine: current.startLine, text: current.parts.join("\n") });
     return bullets;
 }
 
+/**
+ * Every top-level block of release prose — one rendered changeset entry, or
+ * one unlabelled paragraph standing in for one.
+ *
+ * `@heroiclands/package-build/changelog` (`changelog.cjs`) writes a
+ * changeset's whole summary as one block, verbatim, so a block here holds
+ * together the same way that summary is authored: a bold label opening a
+ * line at column 0 (`**Compendiums**`) starts a new block, and — unlike
+ * {@link topLevelBullets}, where a bullet marker *is* the top-level
+ * construct — a `-` bullet at column 0 belongs to whatever block is
+ * already open, since a label's bullets sit unindented directly under it.
+ * Any other column-0 line (plain prose with no label, a bullet with no
+ * block open yet) starts the one "lead" block (`label: null`) a changeset
+ * with no category writes — the case `changelog group` sorts first and
+ * `check` never flags. Nested detail — a wrapped line, a bullet's own
+ * continuation — stays indented and belongs to whatever it follows.
+ * `changelog group` folds same-label blocks together; `check` warns when a
+ * block's label is not in the declared vocabulary.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @param {Set<number>} [scaffoldLines] - Generated heading lines that close
+ *   whatever block is open without starting one, from
+ *   {@link scaffoldLineSet} — empty for a caller that already isolated one
+ *   `### <Bump> Changes` body, since no heading falls inside it.
+ * @returns {Array<{startLine: number, label: string|null, text: string}>}
+ */
+export function topLevelBlocks(text, codeLines, scaffoldLines = new Set()) {
+    const lines = text.split("\n");
+    /** @type {Array<{startLine: number, label: string|null, text: string}>} */
+    const blocks = [];
+    /** @type {{startLine: number, label: string|null, parts: string[]}|null} */
+    let current = null;
+    const close = () => {
+        if (current)
+            blocks.push({
+                startLine: current.startLine,
+                label: current.label,
+                text: current.parts.join("\n"),
+            });
+        current = null;
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+        const lineNo = i + 1;
+        const raw = lines[i];
+
+        if (codeLines.has(lineNo)) {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        if (scaffoldLines.has(lineNo)) {
+            close();
+            continue;
+        }
+        const atColumnZero = raw.trim() !== "" && !/^[ \t]/.test(raw);
+        if (!atColumnZero) {
+            if (current) current.parts.push(raw);
+            continue;
+        }
+        const label = LABEL_LINE_RE.exec(raw)?.[1] ?? null;
+        if (label !== null) {
+            close();
+            current = { startLine: lineNo, label, parts: [raw] };
+            continue;
+        }
+        if (TOP_BULLET_RE.test(raw) && current) {
+            current.parts.push(raw);
+            continue;
+        }
+        close();
+        current = { startLine: lineNo, label: null, parts: [raw] };
+    }
+    close();
+    return blocks;
+}
+
 /**
  * A bullet's word count, the bullet marker and markdown decoration stripped.
  *
@@ -502,6 +585,41 @@ function checkCodeLikeTokens(text, maskedRegions) {
     return findings;
 }
 
+/**
+ * A block's bold label absent from the declared `changelog.labels`
+ * vocabulary — the drift `**Character data**` beside `**Characters**`
+ * produces, invisible until something reads the declared list against what a
+ * changeset actually wrote. A warning, not an error: an undeclared label
+ * still ships and still groups (`changelog group` files it last), so nothing
+ * here blocks a release — it only says the vocabulary and the prose have
+ * drifted apart.
+ *
+ * @param {Array<{startLine: number, label: string|null}>} blocks - From
+ *   {@link topLevelBlocks}.
+ * @param {readonly string[]|null|undefined} labels - `changelog.labels`, or
+ *   `null`/`undefined` when the repository declares none, in which case
+ *   nothing is checked — there is no vocabulary for a label to drift from.
+ * @returns {RelativeFinding[]}
+ */
+function checkUnknownLabels(blocks, labels) {
+    if (!labels) return [];
+    /** @type {RelativeFinding[]} */
+    const findings = [];
+    for (const block of blocks) {
+        if (block.label === null || labels.includes(block.label)) continue;
+        findings.push({
+            line: block.startLine,
+            column: 3, // right after the opening `**`
+            severity: "warning",
+            message:
+                `changelog-check/unknown-label "${block.label}" is not declared in ` +
+                "`changelog.labels` (declared: " +
+                `${labels.join(", ")}) — add it there, or correct the label`,
+        });
+    }
+    return findings;
+}
+
 /**
  * The 1-based lines a caller drops from the heading rule because they are the
  * generated scaffold, never authored prose: the section's own `## <version>`
@@ -524,13 +642,17 @@ function scaffoldLineSet(text) {
  * Run every rule over one section of release prose.
  *
  * @param {string} text - The section, already isolated by the caller.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, for
+ *   {@link checkUnknownLabels}. `null`/absent checks nothing.
  * @returns {RelativeFinding[]} Findings with line numbers relative to `text`.
  */
-function lintSection(text) {
+function lintSection(text, { labels = null } = {}) {
     const codeLines = codeLineSet(text);
     const maskedRegions = codeRegions(text, { spans: true });
     const scaffoldLines = scaffoldLineSet(text);
     const bullets = topLevelBullets(text, codeLines);
+    const blocks = topLevelBlocks(text, codeLines, scaffoldLines);
 
     return [
         ...checkCommitHash(text, codeLines, scaffoldLines),
@@ -544,6 +666,7 @@ function lintSection(text) {
         ...checkTooManyBullets(bullets),
         ...checkTooManyLines(text),
         ...checkCodeLikeTokens(text, maskedRegions),
+        ...checkUnknownLabels(blocks, labels),
     ].sort((a, b) => a.line - b.line || (a.column ?? 0) - (b.column ?? 0));
 }
 
@@ -593,12 +716,19 @@ function extractReleaseSection(text) {
  * Lint one pending changeset (`.changeset/*.md`).
  *
  * @param {string} text - The file's full contents, frontmatter included.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintChangesetText(text) {
+export function lintChangesetText(text, { labels = null } = {}) {
     const { body, startLine } = stripFrontmatter(text);
-    const findings = lintSection(body).map((f) => ({ ...f, line: f.line + startLine - 1 }));
+    const findings = lintSection(body, { labels }).map((f) => ({
+        ...f,
+        line: f.line + startLine - 1,
+    }));
     return { findings };
 }
 
@@ -606,10 +736,14 @@ export function lintChangesetText(text) {
  * Lint the first `## <version>` release section of a `CHANGELOG.md`.
  *
  * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintReleaseText(text) {
+export function lintReleaseText(text, { labels = null } = {}) {
     const section = extractReleaseSection(text);
     if (!section) {
         return {
@@ -621,9 +755,34 @@ export function lintReleaseText(text) {
             ],
         };
     }
-    const findings = lintSection(section.body).map((f) => ({
+    const findings = lintSection(section.body, { labels }).map((f) => ({
         ...f,
         line: f.line + section.startLine - 1,
     }));
     return { findings };
 }
+
+/**
+ * The first `## <version>` release section of a changelog, as raw character
+ * offsets rather than {@link extractReleaseSection}'s line-joined copy.
+ *
+ * `extractReleaseSection` rebuilds its `body` by joining a slice of
+ * `text.split("\n")`, which is fine for reporting a line number but drops
+ * the exact byte the next `## ` heading sits after — a caller rewriting the
+ * file in place, such as `changelog group`, needs `text.slice(start, end)`
+ * to be the section verbatim, so it can splice a replacement back in without
+ * guessing at the whitespace on either side.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{start: number, end: number}|null} `null` when no `## ` heading
+ *   is present. `text.slice(start, end)` is the section, byte-exact,
+ *   including whatever separates it from the next `## ` heading or the end
+ *   of the file.
+ */
+export function releaseSectionRange(text) {
+    const matches = [...text.matchAll(/^## /gm)];
+    if (matches.length === 0) return null;
+    const start = matches[0].index;
+    const end = matches.length > 1 ? matches[1].index : text.length;
+    return { start, end };
+}

package/engine/document-subtypes.mjs

@@ -329,7 +329,7 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  * dependency catalogue actually carry, and a reference is translated forward
  * here before it is looked up.
  *
- * Four answers, and only the first resolves:
+ * Five answers, and only the last refuses:
  *
  * - _A one-to-one row_ → the subtype it declares. `armor` addresses an
  *   `armorgear`.
@@ -340,12 +340,19 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  *   existed.
  * - _A row for another document class_ → a problem. A being is not an item,
  *   however the address is spelled.
- * - _A one-to-many row_ → a problem naming the candidates. The note that owns
- *   such a row resolves it from its own frontmatter block; a reference has no
- *   block, so nothing here can choose, and choosing anyway would be right about
- *   half the time. No system declares a one-to-many **Item** row today, so this
- *   is a guard rather than a behaviour — but it is a loud one, which is the
- *   whole point of the issue.
+ * - _A one-to-many row, named by one of its own permitted subtypes_ → that
+ *   subtype. HM3's `weapongear` row is keyed by the note type `weapongear` but
+ *   permits `["weapongear", "missilegear"]`; a reference spelled `weapongear`
+ *   is not ambiguous — it already names the subtype it wants, the same as a
+ *   reference spelled `missilegear` does by matching no row at all and taking
+ *   the unmapped fallback above. Only the row's own key can coincide with one
+ *   of its subtypes, so this is never a second guess at the note's
+ *   frontmatter — the row was looked up by this exact spelling.
+ * - _A one-to-many row, named by neither the row's other permitted subtypes
+ *   nor resolved above_ → a problem naming the candidates. The note that owns
+ *   such a row resolves it from its own frontmatter block; a reference naming
+ *   only the row has no block to read a discriminator from, so nothing here
+ *   can choose, and choosing anyway would be right about half the time.
  *
  * A **retired** spelling is refused by name before any of that. Without it a
  * reference left behind by a merge would take the unmapped fallback and address
@@ -392,6 +399,16 @@ export function referencedSubtype(map, noteType, document) {
     }
     if (!row.subType) {
         const permitted = /** @type {readonly string[]} */ (row.subTypes);
+        // The reference is not ambiguous when its own spelling names one of the
+        // row's permitted subtypes rather than merely the row itself: a
+        // `weapongear` reference into HM3's one-to-many `weapongear` row already
+        // says which subtype it wants, in the same way a `missilegear`
+        // reference does by never matching this row's key at all. Only a
+        // reference that names the row without naming a subtype is genuinely
+        // undecidable.
+        if (permitted.includes(currentType(noteType))) {
+            return { subType: currentType(noteType) };
+        }
         return {
             problem:
                 `a "${noteType}" note compiles into more than one ${map.system} ` +

package/hm3/actors.mjs

@@ -162,6 +162,35 @@ function defaultActorImg(subType) {
     return img;
 }
 
+/**
+ * Default art for the three subtypes HM3's one-to-many `mysticalability` row
+ * permits — `spell`, `invocation` and `psionic` — keyed by the **document**
+ * subtype rather than the note type.
+ *
+ * `hm3/default-item-art.mjs` is keyed the other way on purpose: a registry
+ * entry is addressed by what a note calls itself, and no note ever authors
+ * `type: spell` — only `mysticalability`, discriminated by its own
+ * `hm3.type`. But a being's `(type, shortcode)` reference has no note to
+ * discriminate, so it names the subtype it wants directly, and an embedded
+ * entry that supplies neither a template's own `img` nor a `data.icon` of its
+ * own reaches {@link Hm3Actors#embeddedItemArt} in exactly that vocabulary.
+ *
+ * Each path is the icon HM3's own item sheet assigns a freshly created item
+ * of that subtype — `HM3.defaultMagicIconName`, `HM3.defaultRitualIconName`
+ * and `HM3.defaultPsionicsIconName` in the system's own `config.js` — so a
+ * compiled item looks like one created in the client. `weapongear` and
+ * `missilegear` need no row here: a reference spelled either resolves through
+ * `HM3_DEFAULT_ITEM_ART`'s own `weapongear` key (see #582), and every
+ * predefined weapon and missile in HM3's catalogue carries its own `img`.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const EMBEDDED_ITEM_ART = Object.freeze({
+    invocation: "systems/hm3/images/icons/svg/circle.svg",
+    psionic: "systems/hm3/images/icons/svg/psionics.svg",
+    spell: "systems/hm3/images/icons/svg/pentacle.svg",
+});
+
 /**
  * HM3's Actor compile pass.
  *
@@ -192,6 +221,19 @@ export class Hm3Actors extends SystemActorCompiler {
         return this.buildActor(this.itemsMap, fm, markdown);
     }
 
+    /**
+     * @inheritdoc
+     *
+     * Answers for `spell`, `invocation` and `psionic` too — see
+     * {@link EMBEDDED_ITEM_ART} — falling back to the engine's note-type
+     * table for every other reference, `weapongear` and `missilegear`
+     * included.
+     */
+    embeddedItemArt(type, subType) {
+        const art = /** @type {Record<string, string|undefined>} */ (EMBEDDED_ITEM_ART)[subType];
+        return art ?? super.embeddedItemArt(type, subType);
+    }
+
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *