@heroiclands/package-build 22.4.1 → 22.4.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.4.2
+
+### Patch Changes
+
+- 8dedb23: **A module embedding HM3 spells, invocations or psionics compiles.** A being's
+  embedded `spell`, `invocation` or `psionic` reference that names no shortcode
+  template and no `data.icon` of its own now takes that subtype's own default
+  art — the icon HM3 itself assigns a freshly created item of that kind —
+  instead of the build refusing the actor outright.
+- 54109cf: **A module embedding HârnMaster 3 weapons compiles.** A being's `(type,
+  shortcode)` reference into HM3's one-to-many `weapongear` row resolves when
+  its `type` names one of the row's own subtypes — `weapongear` or
+  `missilegear` — instead of being refused as ambiguous.
+
 ## 22.4.1
 
 ### Patch Changes

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/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`.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.1",
+    "version": "22.4.2",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/actor-compiler.d.mts

@@ -280,6 +280,26 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   subtype, or why the reference names none.
      */
     embeddedSubtype(type: string): import("./document-subtypes.mjs").ReferencedSubtype;
+    /**
+     * 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: string, subType: string): string;
     /**
      * Read an entry's `model:` — the address of the item it is a copy of.
      *

package/types/engine/document-subtypes.d.mts

@@ -140,7 +140,7 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  * 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`.
@@ -151,12 +151,19 @@ export function documentSubtype(map: DocumentSubtypeMap, noteType: string | unde
  *   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

package/types/hm3/actors.d.mts

@@ -15,6 +15,15 @@ export class Hm3Actors extends SystemActorCompiler {
      * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
      */
     static documentSubtypes: import("../engine/document-subtypes.mjs").DocumentSubtypeMap;
+    /**
+     * @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: any, subType: any): string;
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *