@heroiclands/package-build 21.1.0 → 21.2.0

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "21.1.0",
+    "version": "21.2.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 },

package/sohl/note-schemas.mjs

@@ -146,26 +146,14 @@ const BEING_FIELDS = Object.freeze([
  * business; their authored vocabulary is the same, so they share one
  * declaration rather than three copies that could drift.
  *
- * `img` is the one required field — the compiler refuses a map note without it,
- * since a scene with no background is not a map. It was spelled `image` and
- * read from the `sohl:` block; both were read while the trees were
- * swept; that retirement has since completed and `image` is gone.
+ * `data.bgImage` is the one required piece of art — the compiler refuses a map
+ * note without it, since a scene with no background is not a map. It is
+ * declared in the note vocabulary rather than here, because it is an art slot
+ * like every other and a Scene has no `img` for the shared key to reach.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const MAP_FIELDS = Object.freeze([
-    {
-        name: "img",
-        ...STRING,
-        required: true,
-        // Art is not system-specific — a Scene is a core Foundry document, and
-        // every other note type carries its `img` at the note's top level.
-        shared: true,
-        describe:
-            "The scene's background image. Owned by whichever package its first segment " +
-            "names — `systems/…` and `modules/…` are emitted unchanged, anything else is " +
-            "this package's own and is rooted under its assets.",
-    },
     {
         name: "dimensions",
         ...LIST,

package/types/content-config.d.mts

@@ -66,6 +66,7 @@ export const PACKAGE_KINDS: readonly ["systems", "modules", "documentation"];
 export const DOCUMENTATION_KIND: string;
 export namespace DEFAULT_PATHS {
     let content: "assets/content";
+    let assets: "assets";
     let contentIndex: "build/content-index";
     let packJson: "build/packs-json";
     let stage: "build/stage/packs";
@@ -299,6 +300,12 @@ export type PathsInput = {
      * Content tree root.
      */
     content?: string | undefined;
+    /**
+     * The asset roots' parent — the directory
+     *            holding `icons/`, `images/` and
+     *            `audio/`.
+     */
+    assets?: string | undefined;
     /**
      * Where `content-index` writes this
      *      package's note index. Outbound, and a
@@ -338,6 +345,7 @@ export type PathsInput = {
  */
 export type ResolvedPaths = {
     content: string;
+    assets: string;
     contentIndex: string;
     packJson: string;
     stage: string;

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

@@ -182,6 +182,29 @@ export class SystemActorCompiler extends BasePackCompiler {
         itemsSourceDirs?: never[] | undefined;
         foreignSourceDirs?: never[] | undefined;
     });
+    /**
+     * The actor's two pieces of art, resolved, with the being default beneath
+     * them.
+     *
+     * **The default is chosen from the note's tags**, which only a compiler can
+     * read: a `character` falls back to one file and a `creature` to another,
+     * and both are addresses in the package that ships them. A tree whose index
+     * cannot answer that address — a dependency not yet fetched — falls through
+     * to the subtype's own default, so the document is never left with no art.
+     *
+     * `tokenIcon` unset follows `icon`, and the fallback is applied after
+     * resolution rather than before: a note naming an icon and no token icon
+     * means "the token wears the profile art", not "the token wears the
+     * default".
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} fallback - The subtype's own default art path.
+     * @returns {{img: string, token: string}} The two paths.
+     */
+    actorArt(fm: object, fallback: string): {
+        img: string;
+        token: string;
+    };
     /** @type {readonly string[]} */
     itemsSourceDirs: readonly string[];
     foreignSourceDirs: any;
@@ -260,6 +283,12 @@ export class SystemActorCompiler extends BasePackCompiler {
      * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
      *
+     * **An entry's `data:` is the authoring container, not a document field.**
+     * Its art slot is read here and the container itself goes no further, so an
+     * entry writing `data.icon` reaches the document as a resolved `img` and an
+     * entry writing none takes its type's default — the same two rules an item
+     * note compiles under, reached by the same functions.
+     *
      * @param {Map<string, object>} itemsMap - The predefined items, by address.
      * @param {string} actorId - The owning actor's id, seeding embedded ids.
      * @param {string} type - The **note** type the reference names.