@heroiclands/package-build 18.2.0 → 20.0.0

package/engine/web-wikilinks.mjs

@@ -46,7 +46,8 @@ import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-system-type-shortcode` key, so a package-qualified
 // address is matched the way a vendored manifest publishes it — by the
 // segments the target supplies, with the system wildcarded unless stated (#59).
-import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+import { canonicalKey, expandAddress, readCanonicalKey } from "./content-address.mjs";
+import { NO_SYSTEM } from "./systems.mjs";
 // The one rule about a link's shape both builds share: it carries a label, and
 // {@link unlabelledLinkMessage} is the one place that says so (#180).
 import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
@@ -85,32 +86,33 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  * @param {object|null} read - From {@link readQualifier}.
  * @returns {string | null} The index key, or `null` when not an address.
  */
-function lookupRead(index, read) {
+function lookupRead(index, read, contentPackage) {
     if (!read || read.reason) return undefined;
-    // An unqualified address stays the system-blind short key, which is the
-    // wildcard an author writing `[[skill-melee]]` means, and resolves within
-    // this package only.
-    if (!read.package) return index.get(`${read.type}/${read.shortcode}`.toLowerCase());
+    // Every omitted segment defaults from where the link is written (#336) —
+    // package from the citing package, system from the block, which on a page
+    // body is `none` — so the target expands to exactly one canonical address
+    // and this is a plain lookup. No filter, no single-hit rule, and no
+    // ambiguity: one key names one entry.
+    //
+    // It replaced a system-blind short key for the unqualified form, which
+    // could be silently overwritten by a second note of the same
+    // `(type, shortcode)` under another system.
+    const key = expandAddress(read, { package: contentPackage, system: NO_SYSTEM });
+    const found = index.get(key);
+    if (found || read.package) return found;
 
-    // A package-qualified one is matched by the segments it supplies, with the
-    // system wildcarded unless stated (#59) — an exact `get` cannot express
-    // that, and would silently miss every address whose system it did not
-    // guess. Exactly one hit resolves; two are an ambiguity for the caller to
-    // report rather than a pick to make here.
-    const type = String(read.type).toLowerCase();
-    const shortcode = String(read.shortcode).toLowerCase();
-    const pkg = String(read.package).toLowerCase();
-    let found;
-    for (const [key, value] of index) {
-        const parts = readCanonicalKey(key);
-        if (!parts) continue;
-        if (parts.package !== pkg) continue;
-        if (read.system && parts.system !== String(read.system).toLowerCase()) continue;
-        if (parts.type !== type || parts.shortcode !== shortcode) continue;
-        if (found) return undefined;
-        found = value;
-    }
-    return found;
+    // A local target may also be keyed by its short form. On the KB that is not
+    // a second answer: an item note renders as **one page** which is its own
+    // documentation, so `skill/climb`, `docskill/climb` and both canonical
+    // addresses are all the same value (#1362) — the fallback cannot pick
+    // differently, only earlier. It stays because an index built before the
+    // canonical documentation key was added still carries the short one, and
+    // because a page collision here is caught by the site index's own
+    // `ambiguous` set rather than by silent overwrite as in the pack index.
+    return (
+        index.get(`${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase()) ??
+        undefined
+    );
 }
 
 /**
@@ -366,7 +368,7 @@ export function resolveWebWikilinks(body, ctx) {
         const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
         const rawKey = target.toLowerCase();
         const hit =
-            lookupRead(ctx.index, read) ??
+            lookupRead(ctx.index, read, ctx.contentPackage) ??
             // `section/slug` is the site's own address for a page, and it is in
             // the same map. Admitted only when the target carries a slash, so
             // a page's bare slug cannot answer for an address.
@@ -375,7 +377,11 @@ export function resolveWebWikilinks(body, ctx) {
             // local one (#1446), so a cross-package hit needs no special case
             // below. Local wins: a live build is authoritative and a vendored
             // manifest can only be staler.
-            (ctx.foreign ? lookupRead(ctx.foreign, read) : undefined);
+            // A short form names *this* package (#336), so it never reaches a
+            // vendored manifest; only a fully qualified address does.
+            (ctx.foreign && read?.package ?
+                lookupRead(ctx.foreign, read, ctx.contentPackage)
+            :   undefined);
         if (hit) {
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**

package/engine/wikilink-syntax.mjs

@@ -182,6 +182,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
     new Set([
         "unlabelled",
         "not-an-address",
+        "not-lowercase",
         "unknown-type",
         "unresolved",
         "ambiguous",
@@ -276,6 +277,12 @@ export function linkFindingMessage({ reason, target, packages, anchor }) {
                 `[[package-system-type-shortcode|Text]] for a note in another ` +
                 `package`
             );
+        case "not-lowercase":
+            return (
+                `address [[${target}]] capitalises a package, system or type ` +
+                `segment — those three are lowercase, and only the shortcode ` +
+                `keeps its case`
+            );
         case "unknown-type":
             return `address [[${target}]] names no known content type`;
         case "ambiguous":

package/engine/wikilinks.mjs

@@ -87,7 +87,9 @@ import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
-import { isSystemSegment } from "./systems.mjs";
+import { isSystemSegment, NO_SYSTEM } from "./systems.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
@@ -207,6 +209,48 @@ export function resolveItemDocType(qualifier, types) {
  *   but names no known type; or `null` when it is not an address at all.
  */
 export function readQualifier(target, types, packages) {
+    // **Package, system and type are lowercase; the shortcode is not.** A
+    // shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
+    // `HsTunic` — so it is written as the note declares it. The three segments
+    // in front of it are closed vocabularies with one spelling each, and
+    // accepting `Skill` beside `skill` would bless two ways of writing one
+    // address. Reported rather than folded, so the corpus has one form.
+    //
+    // Tested only once the target *parses*: a note name is full of capitals
+    // (`[[Shock State]]`), and calling that a badly-cased address rather than
+    // not an address would name the wrong mistake. Neither tree carries a
+    // violation — 10,538 authored targets — so this pins a rule already kept.
+    const read = readQualifierCased(target, types, packages);
+    if (read && !read.reason && qualifyingSegments(target).some((s) => /[A-Z]/.test(s))) {
+        return { reason: "not-lowercase" };
+    }
+    return read;
+}
+
+/**
+ * The segments of a target that must be lowercase — everything but the
+ * shortcode, which is case-sensitive and keeps whatever the note declares.
+ *
+ * @param {string} target - The link target, anchor already removed.
+ * @returns {string[]} The package / system / type segments, as written.
+ */
+function qualifyingSegments(target) {
+    const slash = target.lastIndexOf("/");
+    // The legacy `type/shortcode` form states only a type.
+    if (slash > 0) return [target.slice(0, slash)];
+    const parts = target.split("-");
+    return parts.slice(0, -1);
+}
+
+/**
+ * {@link readQualifier} without the lowercase rule — the grammar alone.
+ *
+ * @param {string} target
+ * @param {Set<string>} types
+ * @param {Set<string>} [packages]
+ * @returns {object|null}
+ */
+function readQualifierCased(target, types, packages) {
     // The slash form is legacy and states neither package nor system, so it is
     // read first and separately. A slash is unconditionally a qualifier —
     // nothing else uses one — which is why an unknown type before it is
@@ -440,25 +484,24 @@ function foreignHits(index, read) {
     const wanted = norm(read.itemDoc ? `doc${read.type}` : read.type);
     const shortcode = norm(read.shortcode);
 
-    // One filter for every reading, because an address is matched **by the
-    // segments it supplies** and wildcarded on the ones it does not (#59). A
-    // package-qualified target used to take a separate exact-`get` path, which
-    // is what let this function carry its own copy of the key grammar — a
-    // hand-built `${package}-${type}-${shortcode}` and a literal segment count
-    // — and drift from `readCanonicalKey` the moment the grammar gained a
-    // system segment. There is one reader now.
+    // **An omitted package means this package** (#336), so a short form
+    // addresses nothing foreign and never reaches a dependency's index. A link
+    // that resolved into another package only because no local note claimed the
+    // address was resolving by accident, and would have retargeted silently the
+    // day one did. Reaching another package is the fully qualified form's job.
     //
-    // The system is a wildcard unless the target states one: most authored
-    // links name none, and defaulting it to `none` would exclude every link to
-    // an item, which is the majority — 1,632 of `sohl`'s own resolve into the
-    // items pack. Ambiguity is caught by the caller's single-hit rule rather
-    // than pre-empted by a guess here.
+    // The system likewise comes from where the link is written — `none` in a
+    // body — so both segments are known here and this is an exact lookup rather
+    // than a filter. That is what makes a cross-package `ambiguous` impossible:
+    // one key, one entry.
+    if (!read.package) return [];
+    const wantedSystem = norm(read.system ?? NO_SYSTEM);
     const hits = [];
     for (const [key, entry] of index.foreign) {
         const parts = readCanonicalKey(key);
         if (!parts) continue;
-        if (read.package && parts.package !== norm(read.package)) continue;
-        if (read.system && parts.system !== norm(read.system)) continue;
+        if (parts.package !== norm(read.package)) continue;
+        if (parts.system !== wantedSystem) continue;
         if (parts.type !== wanted || parts.shortcode !== shortcode) continue;
         hits.push(entry);
     }
@@ -616,7 +659,22 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                 });
                 return unresolvedLink(text || target, target);
             }
-            itemDoc = qualified.itemDoc;
+            // An omitted system defaults from where the link is written (#336),
+            // and a body is under no system block, so it is `none`. Under
+            // `none` a system-bearing type addresses its *documentation* — a
+            // note's `none` address IS its `doc<type>` entry — which is what a
+            // prose link almost always means. Stating the system is how prose
+            // reaches the Item instead.
+            //
+            // Only a type whose *own* document carries a system is redirected.
+            // A `macro` and the map types have documentation journals too, but
+            // their own documents are core ones already at `none`, so
+            // `macro-autoattack` names the Macro and `docmacro-autoattack` its
+            // journal — two live addresses the redirect would collapse.
+            itemDoc =
+                qualified.itemDoc ||
+                ((qualified.system ?? NO_SYSTEM) === NO_SYSTEM &&
+                    systemOf(qualified.type, KNOWN_DOCUMENT_SUBTYPE_MAPS) !== NO_SYSTEM);
             doc = index.byShortcode.get(`${qualified.type}/${qualified.shortcode}`);
         }
         if (!doc) {

package/hm3/actors.mjs

@@ -29,10 +29,11 @@
  * **What is emitted, and what is deliberately not.** Four rows of the content
  * format's `being` mapping table give HM3 a destination — `data.portrait` →
  * `system.bioImage`, `data.species`, `data.gender`, `data.occupation`, and
- * `data.templatePriority` → `flags.hm3.templatePriority` — and, since #305,
- * three of them are *declared as those sources* rather than as the bare key the
- * corpus writes, so the specification's mapping is executable rather than
- * aspirational. Plus the two anchored prose sections: `{#appearance}` is HM3's `description` and `{#dossier}` its
+ * `data.templatePriority` → `flags.hm3.templatePriority` — and every one of
+ * them is *declared as that source* rather than as the bare key the corpus
+ * writes, so the specification's mapping is executable rather than
+ * aspirational. Three were declared by #305; `data.portrait` was still read by
+ * hand until #332, and so was the one row that did not work. Plus the two anchored prose sections: `{#appearance}` is HM3's `description` and `{#dossier}` its
  * `biography`. Everything else an HM3 actor carries — the thirteen abilities,
  * the sunsign, `move`, `fatigue`, `shockIndex`, a creature's `loadRating` — has
  * no shared source stated anywhere, so it is authored at its own path under
@@ -49,15 +50,19 @@
  */
 
 import { resolveName, resolveImg } from "../engine/helpers.mjs";
-import { buildFromFields, STRING } from "../engine/field-spec.mjs";
+import { buildFromFields, readField, retiredTopLevelKey, STRING } from "../engine/field-spec.mjs";
 import { SystemActorCompiler } from "../engine/actor-compiler.mjs";
 import { renderSection } from "../engine/anchored-sections.mjs";
 import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
-// The retirement window's report, shared with the frontmatter lint so the
-// two cannot say different things about the same key (#305).
-import { legacyKeyMessage, locateFrontmatterKey } from "../engine/retired-fields.mjs";
+// The retirement window's reports, shared with the frontmatter lint so the
+// two cannot say different things about the same key (#305, #332).
+import {
+    legacyKeyMessage,
+    locateFrontmatterKey,
+    retiredTopLevelMessage,
+} from "../engine/retired-fields.mjs";
 // The note-level `hm3:` block: `hm3.system` onto the document's `system`
 // verbatim, and `hm3.img` / `hm3.items` / `hm3.effects` / `hm3.flags`
 // overriding their shared top-level forms for this system alone (#58).
@@ -94,6 +99,33 @@ const ACTOR_FIELDS = Object.freeze([
     },
 ]);
 
+/**
+ * The actor's bio image — the fourth row of the specification's `being` table,
+ * and the last one that was still read by hand.
+ *
+ * Declared for the reason {@link ACTOR_FIELDS} is, and fixed for the reason
+ * `data.species` was: read with `blockProperty(fm, block, "portrait")` it saw
+ * the block and the note's top level and nothing else, so the `data.portrait`
+ * the specification names never reached the document and the `?? defaultImg`
+ * beside it dressed the miss up as "this note names no art" (#332).
+ *
+ * It is **not** in `ACTOR_FIELDS`, because `buildFromFields` has no seam for
+ * the subtype default that has to follow it — the `?? defaultImg` is the whole
+ * of what distinguishes an unnamed portrait from a deliberately blank one
+ * (#218), and it needs a subtype the coercion is not handed.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const BIO_IMAGE_FIELD = Object.freeze({
+    name: "data.portrait",
+    legacyKey: "portrait",
+    to: "bioImage",
+    shape: "path",
+    read: (raw) => resolveImg(raw),
+    default: null,
+    describe: "Path to the portrait image.",
+});
+
 /**
  * The two `data:` facts HM3 declares on a `character` and not on a `creature`.
  *
@@ -259,29 +291,44 @@ export class Hm3Actors extends SystemActorCompiler {
                 locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
             );
 
-        // Both spellings, as everywhere else: `packFolder` is a folder note's
-        // address and `folder` a Foundry id, and which one applies comes from
-        // the field it was written in rather than from the string (#251, #255).
-        // This pass read only the id, so an HM3 tree could not file an actor by
-        // address at all — which its own sweep needs.
-        const packFolderAddress = blockField(fm, block, "packFolder", null);
-        const folder =
-            packFolderAddress ?
-                this.folderResolver(packFolderAddress, { isAddress: true })
-            :   this.folderResolver(blockField(fm, block, "folder", null));
+        // The shared level's own retiring position — the top-level key `data:`
+        // gathered the field off (#332). Same signal, same severity, separate
+        // callback: a note may have moved one position and not the other.
+        // Anchored at column 1, because the two spellings coincide — `portrait`
+        // names a block key and a top-level one — and a locator that took the
+        // first match would point at the wrong line.
+        const onRetiredTopLevel = (field) =>
+            this.noteWarn(
+                retiredTopLevelMessage(field),
+                locateFrontmatterKey(
+                    this.currentNote?.absPath,
+                    retiredTopLevelKey(field),
+                    undefined,
+                    { topLevel: true },
+                ),
+            );
+        const reports = { block, onLegacyKey, onRetiredTopLevel };
+
+        // One spelling, as everywhere else: `packFolder` names a folder note
+        // by its address. This pass once read only the Foundry id, so an HM3
+        // tree could not file an actor by address at all — which its own sweep
+        // needs; the id spelling is retired outright (#251, #255, #260).
+        const folder = this.folderResolver(blockField(fm, block, "packFolder", null), {
+            isAddress: true,
+        });
 
         const system = {
             // Nullish, not `||` (#218): a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
-            bioImage: resolveImg(blockProperty(fm, block, "portrait")) ?? defaultImg,
+            // Resolved through the declaration so `data.portrait` is reached at
+            // all — see {@link BIO_IMAGE_FIELD} (#332).
+            bioImage: readField(BIO_IMAGE_FIELD, fm, reports) ?? defaultImg,
             description: renderSection(body || "", "appearance"),
             biography: renderSection(body || "", "dossier"),
-            ...buildFromFields(ACTOR_FIELDS, { block, onLegacyKey })(fm),
+            ...buildFromFields(ACTOR_FIELDS, reports)(fm),
             // Declared on `character` alone, so written there alone — see the
             // module note.
-            ...(subType === "character" ?
-                buildFromFields(CHARACTER_FIELDS, { block, onLegacyKey })(fm)
-            :   {}),
+            ...(subType === "character" ? buildFromFields(CHARACTER_FIELDS, reports)(fm) : {}),
         };
 
         // Whatever the note authors under `hm3.system`, at the DataModel's own

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "18.2.0",
+    "version": "20.0.0",
     "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",
@@ -155,7 +155,7 @@
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
-        "vitest": "^4.1.10"
+        "vitest": "^5.0.0"
     },
     "scripts": {
         "test": "vitest run",

package/sohl/actors.mjs

@@ -63,6 +63,14 @@ import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
 // shared top-level forms for this system alone (#58).
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+import { readField, retiredTopLevelKey } from "../engine/field-spec.mjs";
+// The retirement window's reports, shared with the frontmatter lint so the two
+// cannot say different things about the same key (#305, #332).
+import {
+    legacyKeyMessage,
+    locateFrontmatterKey,
+    retiredTopLevelMessage,
+} from "../engine/retired-fields.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -81,6 +89,38 @@ const DEFAULT_IMG = {
     being: "systems/sohl/assets/icons/game-icons/delapouite/person.svg",
 };
 
+/**
+ * The being's sheet portrait — the one row of the content format's actor
+ * mapping table that is authored rather than derived.
+ *
+ * **Declared, because the position is not a spelling anyone can guess.** This
+ * was read with `blockProperty(fm, SYSTEM, "portrait")`, which knows the block
+ * and the note's top level and nothing else — so `data.portrait`, the position
+ * the specification names and `sohl-thalorna` writes on 646 beings, was
+ * invisible, and `?? defaultImg` on the next line turned every miss into the
+ * generic person icon rather than into a complaint (#332). Going through
+ * {@link module:engine/field-spec.readField} is what makes the mapping table
+ * executable here as it already is for HM3's `data.species`.
+ *
+ * `img` is deliberately **not** declared beside it: the mapping table keeps a
+ * note's token art at the top level, so `blockProperty` is the whole of its
+ * resolution and there is no `data.img` to reach for.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const PORTRAIT_FIELD = Object.freeze({
+    name: "data.portrait",
+    legacyKey: "portrait",
+    to: "portrait",
+    shape: "path",
+    // The two empties survive, because the caller's `?? defaultImg` is what
+    // tells them apart: `null` and an absent key mean "no art named, default
+    // me", `""` means "ship blank on purpose" (#218).
+    read: (raw) => resolveImg(raw),
+    default: null,
+    describe: "Path to the portrait image.",
+});
+
 /**
  * The default art for an actor subtype.
  *
@@ -206,21 +246,48 @@ export class Actors extends SystemActorCompiler {
                     this.errorCount++;
                     return;
                 }
-                const { shortcode, type, ...rest } = entry;
-                if (!type) {
-                    this.noteError(`${ctx}: sohl.items[${index}] missing type`);
+                const { model, shortcode, type, ...rest } = entry;
+                if (shortcode !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] carries a top-level ` +
+                            `\`shortcode\` — that key is retired. Name the item ` +
+                            `this entry copies with \`model:\` (an address, e.g. ` +
+                            `\`${type ?? "skill"}-${shortcode}\`), and use ` +
+                            `\`system.shortcode\` for this item's own identity.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const read = model === undefined ? null : this.readModel(model, index, ctx);
+                if (model !== undefined && !read) return;
+                if (read && type !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] states both \`model\` and ` +
+                            `\`type\` — the model's address already names the ` +
+                            `type, so the second is a place to be wrong. Drop \`type\`.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const effectiveType = read ? read.type : type;
+                if (!effectiveType) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] names no \`model\` and no ` +
+                            `\`type\` — an entry that copies nothing must state ` +
+                            `\`name\`, \`type\` and \`system.shortcode\`.`,
+                    );
                     this.errorCount++;
                     return;
                 }
                 const embedded = this.resolveEmbedded(
                     itemsMap,
                     actorId,
-                    type,
-                    shortcode || null,
+                    effectiveType,
+                    read ? read.shortcode : null,
                     rest,
                     `items:${index}`,
                     ctx,
-                    { fmKey: "items" },
+                    { fmKey: "items", modelPackage: read?.package ?? null },
                 );
                 if (embedded) items.push(embedded);
             });
@@ -298,6 +365,36 @@ export class Actors extends SystemActorCompiler {
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
+        // The two retiring positions a declared field may be read from (#305,
+        // #332). **Warnings**, on the pattern every retirement in this package
+        // follows: the note compiles to the correct document either way, so
+        // reddening a tree over one would refuse before the sweep rather than
+        // after it. What they buy is a count — the whole reason #332 was
+        // invisible for so long is that nothing said which position a value
+        // had come from, and a default is indistinguishable from a miss.
+        const portraitReports = {
+            block: SYSTEM,
+            onLegacyKey: (field) =>
+                this.noteWarn(
+                    legacyKeyMessage(SYSTEM, field),
+                    locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
+                ),
+            // Anchored at column 1: the two positions share a spelling here —
+            // `sohl.portrait` and `portrait` — so a locator that took the first
+            // match would point at the block key while the message named the
+            // top-level one.
+            onRetiredTopLevel: (field) =>
+                this.noteWarn(
+                    retiredTopLevelMessage(field),
+                    locateFrontmatterKey(
+                        this.currentNote?.absPath,
+                        retiredTopLevelKey(field),
+                        undefined,
+                        { topLevel: true },
+                    ),
+                ),
+        };
+
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
@@ -311,7 +408,9 @@ export class Actors extends SystemActorCompiler {
             templatePriority: systemTemplatePriority(fm, ctx),
             // Nullish, not `||` (#218): a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
+            // Resolved through the declaration so `data.portrait` is reached at
+            // all — see {@link PORTRAIT_FIELD} (#332).
+            portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };