@heroiclands/package-build 21.1.0 → 22.0.0

package/engine/subtype-registry.mjs

@@ -65,6 +65,27 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
     HM3_DOCUMENT_SUBTYPES,
 ]);
 
+/**
+ * The map a pack declaring no `system:` compiles its documents against.
+ *
+ * A pack names the system its documents are shaped for, and one declaring none
+ * is compiled by the fallback pass for its document type — a single-system
+ * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
+ * follows one map whatever a note carries, which makes this the answer to "a
+ * document compiled here belongs to *which* system?" wherever a pack has not
+ * said.
+ *
+ * Stated here rather than read off the compiler classes because those are not
+ * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
+ * which draws infoboxes, so anything the infobox reads cannot import a pass.
+ * `tests/default-document-subtypes.test.ts` holds this to `compilerFor`, which
+ * is where the fallback is actually decided — so the two cannot drift apart in
+ * silence.
+ *
+ * @type {import("./document-subtypes.mjs").DocumentSubtypeMap}
+ */
+export const DEFAULT_DOCUMENT_SUBTYPES = SOHL_DOCUMENT_SUBTYPES;
+
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *

package/engine/web-wikilinks.mjs

@@ -61,6 +61,7 @@ import { slugify } from "./content-slug.mjs";
 /** KB heading/anchor slug: lowercase, non-alphanumerics to single hyphens. */
 export { slugify };
 import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
+import { resolveEmbeds } from "./content-embeds.mjs";
 
 /**
  * The index key a **piped** target resolves to, or `null` when it does not
@@ -300,15 +301,25 @@ function isPlainMap(value) {
  * web pages, so the author wrote a real address and there is simply nothing to
  * link to.
  *
+ * ## Embeds first, and they are not links
+ *
+ * `![[address|label]]` names a file rather than a note, so it is resolved into
+ * an ordinary markdown image before anything looks for a link — which is what
+ * stops the link pass reading an embed's interior as a link to a note nobody
+ * wrote. The image the rewrite leaves behind is what
+ * {@link module:engine/content-images.renderImageFigures} turns into a figure
+ * for the website, and what the book reads its staging list out of.
+ *
  * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, collide, sections, contentTypes, packages,
- *   foreign, type, errors, src, file }`.
+ * @param {object} ctx - `{ index, assets, collide, sections, contentTypes,
+ *   packages, foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type; `foreign`
- *   is the cross-package manifest index. `src` is the page's display
+ *   is the cross-package manifest index; `assets` is the address space an embed
+ *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in.
- * @returns {string} The body with wikilinks rewritten.
+ * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body, ctx) {
     // How many times each authored link has been seen, so two identical links
@@ -317,15 +328,13 @@ export function resolveWebWikilinks(body, ctx) {
     // `file:line:column:` diagnostic rather than a note-wide one.
     const seen = new Map();
     /**
-     * Records a finding, and returns the marked-up link it renders as.
+     * Records a finding against one authored literal.
      *
-     * @param {string} all - The authored link, brackets and all.
-     * @param {object} finding - `{ target, reason }`, plus any extras the class
-     *   carries.
-     * @param {string} text - What the link renders as.
-     * @returns {string} The marked span.
+     * @param {string} all - The literal, exactly as authored.
+     * @param {object} finding - The finding's own fields.
+     * @returns {void}
      */
-    const report = (all, finding, text) => {
+    const record = (all, finding) => {
         const occurrence = (seen.get(all) ?? 0) + 1;
         seen.set(all, occurrence);
         ctx.errors.push({
@@ -337,12 +346,37 @@ export function resolveWebWikilinks(body, ctx) {
             occurrence,
             ...finding,
         });
+    };
+
+    /**
+     * Records a finding, and returns the marked-up link it renders as.
+     *
+     * @param {string} all - The authored link, brackets and all.
+     * @param {object} finding - `{ target, reason }`, plus any extras the class
+     *   carries.
+     * @param {string} text - What the link renders as.
+     * @returns {string} The marked span.
+     */
+    const report = (all, finding, text) => {
+        record(all, finding);
         return unresolvedLink(text, finding.target);
     };
 
+    // An embed names a file, so it resolves before anything looks for a link.
+    // Its findings are recorded rather than rendered: the rewrite already
+    // leaves an embed it cannot resolve exactly as authored, which is the
+    // visible degradation an unresolved link gets from `unresolvedLink`.
+    const embedded = resolveEmbeds(body, { index: ctx.assets });
+    for (const u of embedded.unresolved) {
+        record(u.link, { target: u.target, reason: u.reason, ...(u.type ? { type: u.type } : {}) });
+    }
+    for (const problem of embedded.problems) {
+        record(problem.link, { target: problem.link, message: problem.message });
+    }
+
     // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
     // inline span is source text, not a link.
-    return replaceOutsideCode(body, WIKILINK, (all, rawInner) => {
+    return replaceOutsideCode(embedded.markdown, WIKILINK, (all, rawInner) => {
         const parsed = parseWikilink(rawInner);
         const { target, anchor, display } = parsed;
         // An empty label is not a label: `[[x|]]` addresses the target and

package/engine/wikilink-syntax.mjs

@@ -57,8 +57,15 @@
  * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
  * prose in search of a closer. Erring towards "not a link" leaves the author's
  * text as written, which is the safe direction for a rewriter.
+ *
+ * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
+ * keeps every reader from seeing one as the other. Stated here rather than in
+ * each reader for the reason the rest of this module exists: the checker, the
+ * pack compilers and the web resolver all match on this pattern, and three
+ * copies of the exclusion is three places for it to be forgotten. An embed's
+ * own grammar is {@link module:engine/content-embeds}.
  */
-export const WIKILINK = /\[\[([^\]\n]+)\]\]/g;
+export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\]/g;
 
 /**
  * The parts of a wikilink's interior.
@@ -171,7 +178,9 @@ export function unlabelledLinkMessage(target) {
  *
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
  * - `unknown-type` — definitely qualified, but names no type this build knows.
+ * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.
@@ -184,6 +193,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "not-an-address",
         "not-lowercase",
         "unknown-type",
+        "not-an-asset",
         "unresolved",
         "ambiguous",
         "unknown-anchor",
@@ -262,11 +272,13 @@ export function ambiguousAddressMessage(target, packages = []) {
  * @param {Iterable<string>} [finding.packages] - For `ambiguous`, the
  *   claimants.
  * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
+ * @param {string} [finding.type] - For `not-an-asset`, the type the address
+ *   named.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor }) {
+export function linkFindingMessage({ reason, target, packages, anchor, type }) {
     switch (reason) {
         case "unlabelled":
             return unlabelledLinkMessage(target);
@@ -285,6 +297,12 @@ export function linkFindingMessage({ reason, target, packages, anchor }) {
             );
         case "unknown-type":
             return `address [[${target}]] names no known content type`;
+        case "not-an-asset":
+            return (
+                `![[${target}]] embeds a \`${type ?? "note"}\`, and an embed draws a ` +
+                `file — only an \`icon\`, an \`image\` or an \`audio\` address can be ` +
+                `embedded. Write [[${target}|Text]] to link to it instead`
+            );
         case "ambiguous":
             return ambiguousAddressMessage(target, packages ?? []);
         case "unknown-anchor":

package/engine/wikilinks.mjs

@@ -86,6 +86,7 @@ import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
+import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isSystemSegment, NO_SYSTEM } from "./systems.mjs";
 import { systemOf } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
@@ -354,11 +355,15 @@ export function anchorPageId(noteId, anchorSlug) {
  *   vendored manifests of packages this build links into but does not publish.
  * @param {string} [contentPackage] - This build's *content* package, which an
  *   authored address may name explicitly. Defaults to `packageId`.
+ * @param {object} [opts] - Options.
+ * @param {Map<string, object>} [opts.assets] - The files this package ships, by
+ *   canonical address. They resolve no link — an asset is not a document — and
+ *   answer only the art fields, which name a file and never a document.
  * @returns {{byShortcode: Map<string, object>, types: Set<string>}} `types` is
  *   every type the tree actually contains, so a qualifier naming no real type
  *   can be told apart from a missing target.
  */
-export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
+export function buildWikilinkIndex(docs, packageId, foreign, contentPackage, { assets } = {}) {
     if (!packageId) {
         throw new Error(
             "buildWikilinkIndex: packageId is required — it is the first " +
@@ -368,7 +373,11 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
     }
 
     const byShortcode = new Map();
-    const types = new Set();
+    // The **asset** types join unconditionally, whether or not this tree holds
+    // a file of each: they are a closed vocabulary rather than a census of what
+    // was found, and an art field hands the resolver `icon-<shortcode>` whose
+    // type has to parse before anything can be looked up.
+    const types = new Set(ASSET_TYPE_NAMES);
 
     // Each note's address is computed once, here, and every reference to it is
     // that stored value. Nothing downstream assembles a UUID from parts, so a
@@ -439,8 +448,12 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
         types,
         uuidByDoc,
         packageId,
+        /** The content package this build publishes, which an art address defaults to. */
+        contentPackage: contentPackage ?? packageId,
         packages,
         foreign: foreignByKey,
+        /** The files this package ships, by canonical address. */
+        assets: assets ?? new Map(),
     };
 }
 

package/hm3/actors.mjs

@@ -49,8 +49,8 @@
  * @module
  */
 
-import { resolveName, resolveImg } from "../engine/helpers.mjs";
-import { buildFromFields, readField, retiredTopLevelKey, STRING } from "../engine/field-spec.mjs";
+import { resolveName } from "../engine/helpers.mjs";
+import { buildFromFields, 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";
@@ -99,33 +99,6 @@ 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".
- *
- * 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,
- * 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`.
  *
@@ -285,7 +258,10 @@ export class Hm3Actors extends SystemActorCompiler {
                 absPath: this.currentNote?.absPath,
             })
         );
-        const defaultImg = defaultActorImg(subType);
+        // The being's own default sits above the subtype's: only the note's
+        // tags say whether it is a person or a creature, and only this pass
+        // reads them.
+        const art = this.actorArt(fm, defaultActorImg(subType));
 
         const items = this.buildEmbeddedItems(itemsMap, id, fm, ctx);
 
@@ -326,11 +302,9 @@ export class Hm3Actors extends SystemActorCompiler {
         });
 
         const system = {
-            // Nullish, not `||`: a note that names no portrait gets the
-            // subtype's default, one that writes `""` ships blank on purpose.
-            // Resolved through the declaration so `data.portrait` is reached at
-            // all — see {@link BIO_IMAGE_FIELD}.
-            bioImage: readField(BIO_IMAGE_FIELD, fm, reports) ?? defaultImg,
+            // `system.bioImage` is **not** written here, for the reason SoHL's
+            // `system.portrait` is not: a being's portrait is the lead image of
+            // its `{#appearance}` section, which is the markup below.
             description: renderSection(body || "", "appearance"),
             biography: renderSection(body || "", "dossier"),
             ...buildFromFields(ACTOR_FIELDS, reports)(fm),
@@ -356,12 +330,11 @@ export class Hm3Actors extends SystemActorCompiler {
         });
 
         const effects = blockProperty(fm, block, "effects");
-        const img = resolveImg(blockProperty(fm, block, "img")) ?? defaultImg;
 
         return {
             name,
             type: subType,
-            img,
+            img: art.img,
             _id: id,
             system,
             items,
@@ -369,7 +342,7 @@ export class Hm3Actors extends SystemActorCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: img },
+                texture: { src: art.token },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },

package/manifest.mjs

@@ -94,6 +94,49 @@ export function normalizeRepoUrl(repository) {
     return url;
 }
 
+/**
+ * Where every HeroicLands package's homepage is served from.
+ *
+ * Stated once here and read by {@link packageHomepage}, so the origin a
+ * manifest advertises and the origin the configuration documents cannot come
+ * to disagree.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_ORIGIN = "https://www.heroiclands.org";
+
+/**
+ * A package's homepage — the page `url` sends a reader to.
+ *
+ * Derived from the content package rather than declared, because the address is
+ * already fixed: every package publishes an authored homepage at
+ * `<origin>/<contentPackage>/`, and the shared site-deploy workflow publishes
+ * it there. A declared copy would be a second spelling of a settled fact, free
+ * to drift — and the one that drifts is this one, because nothing fetches `url`
+ * the way Foundry fetches `manifest`, so a wrong value is never reported.
+ *
+ * The site's own `baseURL` says the same thing, and is deliberately not the
+ * source: it sits at `site/hugo.toml` in most repositories and `kb/hugo.toml`
+ * in the system, so reading it would mean the packaging half knowing where each
+ * repository keeps its site configuration.
+ *
+ * @param {string} contentPackage - The package's content-package name.
+ * @returns {string} The homepage URL, with its trailing slash.
+ * @throws {TypeError} When no name is given. Interpolating a missing one yields
+ *   `<origin>/undefined/`, a URL that resolves and is wrong — and nothing
+ *   fetches `url`, so it would be advertised for as long as nobody clicked it.
+ */
+export function packageHomepage(contentPackage) {
+    const name = String(contentPackage ?? "").trim();
+    if (!name) {
+        throw new TypeError(
+            "the configuration declares no `contentPackage`, so the manifest has " +
+                "no homepage to advertise.",
+        );
+    }
+    return `${HOMEPAGE_ORIGIN}/${name}/`;
+}
+
 /**
  * The addresses a Foundry manifest advertises.
  *
@@ -103,15 +146,23 @@ export function normalizeRepoUrl(repository) {
  * install at that release forever. `download` points at this exact version,
  * because that is the archive this manifest describes.
  *
+ * **`url` is the homepage, not the repository.** It is the Project Homepage
+ * link a reader follows from the package listing *before* installing anything,
+ * so it answers "what is this?" — which a page written for that question does
+ * and a source tree does not. `bugs`, `manifest` and `download` address release
+ * artefacts and stay on the repository that holds them.
+ *
  * @param {object} opts
  * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.homeUrl - The package's homepage, from
+ *   {@link packageHomepage}.
  * @param {string} opts.version - The version being built.
  * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
  * @returns {{url: string, bugs: string, manifest: string, download: string}}
  */
-export function releaseUrls({ repoUrl, version, artifact }) {
+export function releaseUrls({ repoUrl, homeUrl, version, artifact }) {
     return {
-        url: repoUrl,
+        url: homeUrl,
         bugs: `${repoUrl}/issues`,
         manifest: `${repoUrl}/releases/latest/download/${artifact}.json`,
         download: `${repoUrl}/releases/download/v${version}/${artifact}.zip`,
@@ -434,7 +485,12 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
         id: config.foundryPackage,
         version: packageJson.version,
         packs: manifestPacks(config),
-        ...releaseUrls({ repoUrl, version: packageJson.version, artifact }),
+        ...releaseUrls({
+            repoUrl,
+            homeUrl: packageHomepage(config.contentPackage),
+            version: packageJson.version,
+            artifact,
+        }),
     };
     if (config.compatibility) derived.compatibility = config.compatibility;
 
@@ -482,16 +538,14 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     // A flag rather than a top-level key because Foundry's manifest schema is
     // closed and `flags` is its declared extension point; an unknown key at the
     // top level is dropped by some readers and rejected by others.
-    if (config.contentPackage) {
-        merged.flags = {
-            ...(declared.flags ?? {}),
-            metadataUrl: metadataUrl({
-                repoUrl,
-                version: packageJson.version,
-                contentPackage: config.contentPackage,
-            }),
-        };
-    }
+    merged.flags = {
+        ...(declared.flags ?? {}),
+        metadataUrl: metadataUrl({
+            repoUrl,
+            version: packageJson.version,
+            contentPackage: config.contentPackage,
+        }),
+    };
 
     if (flags && Object.keys(flags).length) {
         merged.flags = { ...(merged.flags ?? declared.flags ?? {}) };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "21.1.0",
+    "version": "22.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",
@@ -102,6 +102,8 @@
         "CHANGELOG.md",
         "CONTENT.md",
         "README.md",
+        "assets",
+        "packagebuild-metadata.jsonl",
         "bin",
         "bundle.mjs",
         "ci",
@@ -160,8 +162,9 @@
     "scripts": {
         "test": "vitest run",
         "test:watch": "vitest",
-        "prepack": "npm run build:types",
+        "prepack": "run-s build:types build:asset-index",
         "build:types": "tsc -p tsconfig.dts.json",
+        "build:asset-index": "node ci/emit-asset-index.mjs",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:content-format",

package/packagebuild-metadata.jsonl

@@ -0,0 +1,13 @@
+{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","source":""},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","source":""},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","source":""},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","source":""},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","source":""},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","source":""},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","source":""},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","source":""},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","source":""},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","source":""},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","source":""},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","source":""},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","source":""},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}

package/sohl/actors.mjs

@@ -46,13 +46,7 @@
  * @module
  */
 
-import {
-    sohlField,
-    resolveName,
-    resolveImg,
-    systemTemplatePriority,
-    folderField,
-} from "../engine/helpers.mjs";
+import { sohlField, resolveName, systemTemplatePriority, folderField } from "../engine/helpers.mjs";
 import { openingMasteryLevel } from "./skill-base.mjs";
 import { SystemActorCompiler, renderSection } from "../engine/actor-compiler.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into. Looked up in the
@@ -63,14 +57,6 @@ 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.
 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.
-import {
-    legacyKeyMessage,
-    locateFrontmatterKey,
-    retiredTopLevelMessage,
-} from "../engine/retired-fields.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -89,38 +75,6 @@ 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. 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".
-    read: (raw) => resolveImg(raw),
-    default: null,
-    describe: "Path to the portrait image.",
-});
-
 /**
  * The default art for an actor subtype.
  *
@@ -366,43 +320,16 @@ export class Actors extends SystemActorCompiler {
                 absPath: this.currentNote?.absPath,
             })
         );
-        const defaultImg = defaultActorImg(subType);
+        // The being's own default sits above the subtype's: only the note's
+        // tags say whether it is a person or a creature, and only this pass
+        // reads them.
+        const art = this.actorArt(fm, defaultActorImg(subType));
 
         const items = this.buildEmbeddedItems(itemsMap, id, fm, ctx);
 
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
-        // The two retiring positions a declared field may be read from.
-        // **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 — without one, nothing says which
-        // position a value came 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
@@ -414,11 +341,11 @@ export class Actors extends SystemActorCompiler {
             // with the schema, since an undeclared `system` key is discarded at
             // construction without a warning.
             templatePriority: systemTemplatePriority(fm, ctx),
-            // Nullish, not `||`: a note that names no portrait gets the
-            // subtype's default, one that writes `""` ships blank on purpose.
-            // Resolved through the declaration so `data.portrait` is reached at
-            // all — see {@link PORTRAIT_FIELD}.
-            portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
+            // `system.portrait` is **not** written here. A picture of the
+            // subject is a picture, so a being's portrait is the lead image of
+            // its `{#appearance}` section — which is the markup below — and the
+            // key that used to declare one is not a key. With no authored
+            // source left, the field keeps the schema's own initial.
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
@@ -470,8 +397,7 @@ export class Actors extends SystemActorCompiler {
         return {
             name,
             type: subType,
-            // Nullish, not `||` — see the portrait above.
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
+            img: art.img,
             _id: id,
             system,
             items,
@@ -479,7 +405,7 @@ export class Actors extends SystemActorCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg },
+                texture: { src: art.token },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },