@heroiclands/package-build 22.22.0 → 22.23.0

package/engine/site-index.mjs

@@ -66,10 +66,12 @@ import {
     renderAddress,
     isAddressTuple,
     ownDocumentSystem,
+    expandAddress,
 } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
 import { contentPackage } from "./content-package.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
+import { presentAmongRecords } from "./being-age.mjs";
 // The declared tag vocabulary, which is where `draft` is stated.
 import { isDraftNote } from "./note-vocabulary.mjs";
 
@@ -277,7 +279,12 @@ export function buildSiteIndex(
 
     return {
         contentPackage: ownPackage,
-        dateContext: reckoningContext({ notes: records }),
+        // Carried on the same context `resolvedDateFields` reads: a recurring
+        // event's `next` is computed against this present.
+        dateContext: {
+            ...reckoningContext({ notes: records }),
+            present: presentAmongRecords(records),
+        },
         referenceTargets: buildReferenceTargets(records, new Map([...foreignReferences, ...index])),
         index,
         ambiguous,
@@ -288,6 +295,70 @@ export function buildSiteIndex(
     };
 }
 
+/**
+ * The address keys one page's figures are reachable by — the same two forms
+ * {@link buildSiteIndex} assigns the page itself, so a `ref` crossing into it
+ * resolves by exactly the address a wikilink would use.
+ *
+ * @param {string} pkg - The page's own content package.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {Set<string>} The short `type/shortcode` key and the canonical
+ *   `package-system-type-shortcode` one.
+ */
+export function figureIndexKeys(pkg, type, shortcode) {
+    const system = ownDocumentSystem(type);
+    const keys = new Set([
+        `${type}/${shortcode}`.toLowerCase(),
+        canonicalKey(pkg, system, type, shortcode),
+    ]);
+    if (system !== NOTE_SYSTEM) keys.add(canonicalKey(pkg, NOTE_SYSTEM, type, shortcode));
+    return keys;
+}
+
+/**
+ * Resolve a `ref` call's cross-note address to the target's own figures and
+ * its own address — the `figures.note` a `ref` helper's render context reads,
+ * built once and threaded into every page.
+ *
+ * Reads the written address exactly as a wikilink does
+ * ({@link readQualifier}, {@link expandAddress}), so a `ref` crossing into
+ * another note and a `[[…]]` link to the same note agree on what resolves and
+ * what does not: a target naming no known type or no fetched package's index
+ * is unresolved for both, and one address names one note for both.
+ *
+ * @param {string} target - The address as written, anchor already removed —
+ *   {@link module:engine/wikilink-syntax.ParsedWikilink.target}.
+ * @param {object} options
+ * @param {Set<string>} options.contentTypes - Every type this build reads as
+ *   an address qualifier.
+ * @param {Set<string>} options.packages - Every package an address may name.
+ * @param {Set<string>} options.noIndexPackages - Packages declared
+ *   `contentIndex: false`.
+ * @param {string} options.contentPackage - The package a target with no
+ *   package segment defaults to.
+ * @param {Map<string, {url: string}>} options.siteIndexMap - {@link SiteIndex}'s
+ *   own `index`, read for the target's existence and its URL.
+ * @param {Map<string, Map<string, object>>} options.figuresByAddress - Every
+ *   note's figures, by id, keyed as {@link figureIndexKeys} keys the note.
+ * @returns {{url: string, figures: Map<string, object>}|undefined} The
+ *   target's own address and figures, or `undefined` when the address names
+ *   no note this build resolves.
+ */
+export function resolveCrossNoteFigures(
+    target,
+    { contentTypes, packages, noIndexPackages, contentPackage, siteIndexMap, figuresByAddress },
+) {
+    const read = readQualifier(target, contentTypes, packages, noIndexPackages);
+    if (!read || read.reason) return undefined;
+    const key = expandAddress(read, { package: contentPackage, system: NOTE_SYSTEM });
+    const shortKey = `${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase();
+    const entry = siteIndexMap.get(key) ?? siteIndexMap.get(shortKey);
+    if (!entry) return undefined;
+    const figures = figuresByAddress.get(key) ?? figuresByAddress.get(shortKey) ?? new Map();
+    return { url: entry.url, figures };
+}
+
 /**
  * The per-page context a wikilink resolver takes.
  *

package/engine/site-preview.mjs

@@ -270,6 +270,8 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                     const pos = positionOfLiteral(text, error.src, error.occurrence);
                     findings.push({ ...error, ...pos, severity: "error" });
                 }
+                for (const error of result.embedErrors)
+                    findings.push({ ...error, severity: "error" });
                 if (findings.length) return { ok: false, findings };
                 const edges = snapshot.rendered.edges.filter(([source]) => source !== original.url);
                 for (const hit of result.resolved) if (hit.url) edges.push([page.url, hit.url]);

package/engine/system-block.mjs

@@ -104,21 +104,24 @@
  *
  * A field's `name` is both its identity and the shared property it draws from,
  * and those coincide only while the two vocabularies agree about what the
- * spelling means. They do not always. An `affiliation` item's `system.title` is
- * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
- * `title` is the note's own heading, which the site emitter publishes. Two
- * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ * spelling means — or while the top-level vocabulary admits the spelling at
+ * all. They do not always. An `affiliation` item's `system.title` is the style
+ * of address an office carries — "Ajaw", "Warden"; a note's top-level `title`
+ * is refused outright by the closed top-level vocabulary, which has no `title`
+ * entry. Nothing relates them, and step 3 fed the first from the second anyway.
  *
  * It was not a harmless coincidence either, because step 3 answers **without**
  * applying `field.default` — only step 2 does — so an authored `title: null`
  * reached the field's coercion unguarded and shipped as the literal string
  * `"null"` in fifteen documents.
  *
- * So a field may declare `topLevelMeans`: what the top-level key of that name
- * means *instead*. Declaring it removes the whole shared level — step 3 and the
- * retiring 3b alike, since both read the note's top level and the objection is
- * to that level, not to a spelling — leaving the two positions that describe
- * the document rather than the note. It is deliberately
+ * So a field may declare `topLevelMeans`: why the note's top-level key of this
+ * name is not this field's source — declared wherever that key's spelling
+ * means something else at the note level, or the closed top-level vocabulary
+ * refuses it outright. Declaring it removes the whole shared level — step 3
+ * and the retiring 3b alike, since both read the note's top level and the
+ * objection is to that level, not to a spelling — leaving the two positions
+ * that describe the document rather than the note. It is deliberately
  * a per-field opt-out rather than a change to the order — step 3 is right
  * wherever the two levels state the same quantity, which is nearly everywhere —
  * and its value is the reason rather than a bare flag, so the collision is
@@ -362,22 +365,47 @@ export function blockProperty(fm, block, key, defaultValue = undefined) {
 }
 
 /**
- * A system override followed by a shared `data:` value. The top-level value
- * remains readable while content repositories move their authored fields.
+ * A system override followed by a shared `data:` value followed by the
+ * retiring top-level spelling `data:` gathered it off, reporting which one
+ * answered.
+ *
+ * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
+ * universal `data:` key — `pack` and `packFolder`, declared for every note
+ * type rather than per type, so neither is a `FieldSpec` that resolver takes.
+ * The order is the same shape: a system's own override, then the shared
+ * `data:` position, then the bare top-level key a tree authored before
+ * `data:` existed. The top-level value stays readable while a tree still on
+ * it moves its authored fields.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.
  * @param {string} key - The shared property.
  * @param {any} [defaultValue] - Returned when no position declares it.
- * @returns {any} The selected value.
+ * @returns {{value: any, from: FieldSource}} The value, and where it came
+ *   from.
  */
-export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+export function resolveDataProperty(fm, block, key, defaultValue = undefined) {
     const declared = systemBlock(fm, block)?.[key];
-    if (declared !== undefined && declared !== null) return declared;
+    if (declared !== undefined && declared !== null) return { value: declared, from: "block" };
     const shared = isMapping(fm?.data) ? fm.data[key] : undefined;
-    if (shared !== undefined && shared !== null) return shared;
+    if (shared !== undefined && shared !== null) return { value: shared, from: "shared" };
     const legacy = isMapping(fm) ? fm[key] : undefined;
-    return legacy === undefined || legacy === null ? defaultValue : legacy;
+    if (legacy !== undefined && legacy !== null) return { value: legacy, from: "topLevel" };
+    return { value: defaultValue, from: "default" };
+}
+
+/**
+ * {@link resolveDataProperty}'s value alone, for a caller that only compiles
+ * a document and has no use for which position answered.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {any} The selected value.
+ */
+export function blockDataProperty(fm, block, key, defaultValue = undefined) {
+    return resolveDataProperty(fm, block, key, defaultValue).value;
 }
 
 /**

package/hm3/actors.mjs

@@ -78,7 +78,7 @@ import {
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
-const ACTOR_FIELDS = Object.freeze([
+export const ACTOR_FIELDS = Object.freeze([
     {
         name: "species",
         to: "species",
@@ -97,7 +97,7 @@ const ACTOR_FIELDS = Object.freeze([
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
-const CHARACTER_FIELDS = Object.freeze([
+export const CHARACTER_FIELDS = Object.freeze([
     {
         name: "data.gender",
         legacyKey: "gender",

package/manifest.mjs

@@ -48,6 +48,7 @@
  * @module
  */
 
+import { RELATIONSHIP_KEYS } from "./content-config.mjs";
 import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
@@ -390,33 +391,38 @@ export function packFolderFindings({ packFolders, packs = [] }) {
 }
 
 /**
- * Relationship keys that direct the **build**, rather than describe the
- * package.
- *
- * `relationships` is the one manifest block with a second reader.
- * `@heroiclands/package-build` consumes it too, and v1.8.0 added
- * `itemCatalog: true` as an opt-in on a declared dependency: it selects that
- * package's Item packs as a resolution
- * source for the actors pass. That is an instruction to the build, not a fact
- * about the shipped package — Foundry's relationship schema does not define
- * it, and someone reading a published manifest cannot tell a build directive
- * from a declaration about what the package needs.
- *
- * So the block is filtered rather than copied whole. The rule is the
- * distinction, not the name: a key listed here answers *how is this built?*,
- * and every key that survives answers *what does this package depend on?*.
- * `itemCatalog` is the first build-time key to land on a relationship and is
- * unlikely to be the last.
- *
- * A list is enough, and needs no prefix agreed between the two packages,
- * because the input is already closed: package-build normalises a relationship
- * to `id`, `type`, `manifest`, `compatibility` and its own build keys, and
- * rejects anything else at configuration time. A key that reaches here is one
- * the toolchain itself put there.
+ * The relationship keys Foundry's own schema names.
+ *
+ * `RelatedPackage` declares exactly these (`common/packages/base-package.mjs`),
+ * so a key outside them is one the build put there for itself.
+ *
+ * @type {readonly string[]}
+ */
+export const FOUNDRY_RELATIONSHIP_KEYS = Object.freeze([
+    "id",
+    "type",
+    "manifest",
+    "compatibility",
+    "reason",
+]);
+
+/**
+ * The relationship keys the published manifest drops.
+ *
+ * Derived rather than listed: every key this package accepts on a relationship
+ * that Foundry's schema does not name is one the build reads for itself, so a
+ * key added to the configuration is dropped from the manifest without a second
+ * list being kept in step.
+ *
+ * The filter stays a denylist for the reason the pass-through below gives — a
+ * key Foundry adds later reaches the manifest unread rather than being stripped
+ * by an allowlist that has not heard of it.
  *
  * @type {readonly string[]}
  */
-export const BUILD_ONLY_RELATIONSHIP_KEYS = Object.freeze(["itemCatalog"]);
+export const BUILD_ONLY_RELATIONSHIP_KEYS = Object.freeze(
+    RELATIONSHIP_KEYS.filter((key) => !FOUNDRY_RELATIONSHIP_KEYS.includes(key)),
+);
 
 /**
  * The `relationships` block as published — every declared dependency, with the

package/package.json

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

package/packagebuild-metadata.jsonl

@@ -1,13 +1,13 @@
-{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","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":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","source":""},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}

package/sohl/item-fields.mjs

@@ -391,9 +391,10 @@ export const ITEM_FIELDS = Object.freeze({
             ...STRING,
             default: "",
             topLevelMeans:
-                "An office's style of address belongs to the membership that " +
-                "holds the office, so nothing outside the item supplies it. " +
-                "Author it at `sohl.system.title` on the item, or at the " +
+                "A top-level `title` is refused outright, since an office's " +
+                "style of address belongs to the membership that holds the " +
+                "office and nothing outside the item supplies it. Author it " +
+                "at `sohl.system.title` on the item, or at the " +
                 "`system.title` of the entry in a being's `sohl.items`.",
             describe: "The style of address the office carries.",
         },

package/types/content-config.d.mts

@@ -126,6 +126,16 @@ export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
 export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
 }>;
+/**
+ * Every key a declared relationship may carry.
+ *
+ * Read by the manifest writer as well as by the configuration check: the keys
+ * Foundry's own relationship schema does not name are the build's own, and the
+ * published manifest carries none of them.
+ *
+ * @type {readonly string[]}
+ */
+export const RELATIONSHIP_KEYS: readonly string[];
 /**
  * How the loader hands {@link defineConfig} the system version it resolved.
  *
@@ -274,7 +284,8 @@ export type PathsInput = {
     unpack?: string | undefined;
     /**
      * Where a dependency declaring
-     *      `itemCatalog: true` is unpacked.
+     *      `itemCatalog: true` or
+     *      `assetArchive: true` is unpacked.
      *      Inbound, and fetched rather than
      *      committed.
      */
@@ -438,6 +449,21 @@ export type RelationshipSpec = {
      * `_stats.systemVersion` is stamped from.
      */
     compatibility?: CompatibilitySpec | undefined;
+    /**
+     * Whether `deps fetch` unpacks this
+     *  dependency's release archive and extracts
+     *  its Item packs, so the actors pass can
+     *  resolve embedded items this repository
+     *  does not hold. Needs a `manifest`.
+     */
+    itemCatalog?: boolean | undefined;
+    /**
+     * Whether `deps fetch` unpacks this
+     * dependency's release archive for its
+     * asset bytes alone, building no item
+     * catalogue from it. Needs a `manifest`.
+     */
+    assetArchive?: boolean | undefined;
     /**
      * Whether `deps fetch` fetches this
      * dependency's content index. Default
@@ -449,6 +475,16 @@ export type RelationshipSpec = {
      * index.
      */
     contentIndex?: boolean | undefined;
+    /**
+     * Whether this dependency's asset
+     * tree answers this package's own asset
+     * addresses ahead of its local record.
+     * Default `false`. Refuses `contentIndex:
+     * false` on the same entry, since a
+     * replacement with no fetched index to
+     * check against resolves nothing.
+     */
+    assetReplacement?: boolean | undefined;
 };
 /**
  * How a generated documentation page is framed in the repository publishing it.
@@ -628,6 +664,12 @@ export type ContentBuildConfigInput = {
      *    `Templates`). Default `[]`.
      */
     skipDirectories?: string[] | undefined;
+    /**
+     * Whether `lint` refuses an asset
+     *  record of this package carrying
+     *  `ai: true`. Default `false`.
+     */
+    forbidGeneratedArt?: boolean | undefined;
     /**
      * Reserved for
      * `@heroiclands/package-build`, which
@@ -764,6 +806,11 @@ export type ContentBuildConfig = {
      */
     docEntryTypes: ReadonlySet<string>;
     skipDirectories: readonly string[];
+    /**
+     * Whether `lint` refuses an asset
+     * record of this package carrying `ai: true`.
+     */
+    forbidGeneratedArt: boolean;
     /**
      * The
      * fonts this package ships and the names it

package/types/engine/anchors.d.mts

@@ -1,17 +1,22 @@
 /**
- * The `{#slug}` and `:::caption {#slug}` anchors a note declares.
+ * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
  *
- * A bare `#` heading starts a journal page without declaring a slug. Captioned
- * blocks declare a slug and start an addressable journal page.
+ * A bare `#` heading starts a journal page without declaring a slug, and so
+ * does a figure fence that declares no id. A fence that declares one declares a
+ * slug and starts an addressable journal page.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
  *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
  *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{slug: string, name: string, level: number, line: number}>}
  *   In document order.
  */
-export function collectAnchors(body: string, bodyLine?: number): Array<{
+export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (address: string) => string | undefined): Array<{
     slug: string;
     name: string;
     level: number;

package/types/engine/art-fields.d.mts

@@ -61,6 +61,29 @@ export function assetAddressIndex(records?: readonly object[], { config, foreign
     } | undefined;
     types?: Iterable<string> | undefined;
 }): object;
+/**
+ * What a renderer needs to size one picture, keyed by the pathname its
+ * address resolves to.
+ *
+ * An image reaches a renderer as the resolved pathname an embed or an authored
+ * body image already carries — see {@link readAssetAddress} — never as the
+ * address that produced it, so the lookup a renderer wants is by pathname, not
+ * by {@link assetAddressIndex}'s own `assets` map.
+ *
+ * @param {readonly object[]} records - Asset records, local or foreign.
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   One entry per addressable file, carrying only what a renderer sizes a
+ *   picture from. `role` is omitted when the record states none; `width` and
+ *   `height` are always present, blank (`""`) for a vector — the record's own
+ *   convention, carried through rather than collapsed into an absence a
+ *   renderer could not tell apart from "no asset resolved at all".
+ */
+export function assetImageInfoByPathname(records?: readonly object[]): Map<string, {
+    type: string;
+    role?: string;
+    width: number | "";
+    height: number | "";
+}>;
 /**
  * The asset one authored value names, or why it names none.
  *
@@ -116,6 +139,47 @@ export function resolveArtRecord(index: object, value: unknown, defaultType: str
         path: string;
     };
 } | null;
+/**
+ * Every asset's role, keyed by the pathname it resolves to — the form a body
+ * carries once an embed's address has been rewritten into the ordinary image
+ * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
+ * for a caller that reads a body after that rewrite: a Foundry journal, an
+ * item or actor's documentation, and the book.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @returns {Map<string, string>} Pathname → role, one entry per asset that
+ *   declares one.
+ */
+export function pathnameRoles(index: object): Map<string, string>;
+/**
+ * Flag a note whose art slot names a picture that is not the size that slot
+ * is cut to.
+ *
+ * The size is stated by the slot itself, in
+ * {@link module:engine/art-slots.ART_SLOTS}, so it is written once and a slot
+ * that states none asks nothing of the picture it names. Today the hero image
+ * is the one slot with a fixed strip to fill; a picture written in prose is
+ * fitted to the room it has and is never measured here.
+ *
+ * A vector carries no pixel size to compare, and neither does a raster whose
+ * header cannot be read; neither is flagged.
+ *
+ * @param {readonly object[]} records - The corpus, notes and assets together.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {string} [opts.assetsBase] - Where the asset roots sit, so a finding
+ *   names the file from the working directory as every other finding does.
+ * @returns {object[]} A finding per picture off its slot's size,
+ *   `severity: "error"`.
+ */
+export function checkArtSlotSizes(records?: readonly object[], { config, assetsBase }?: {
+    config?: object | undefined;
+    assetsBase?: string | undefined;
+}): object[];
 /**
  * The pathname an art value names, in the form an authored one takes.
  *

package/types/engine/asset-index.d.mts

@@ -19,6 +19,16 @@ export function collectAssetRecords(assetsBase: string, { contentPackage, proble
     contentPackage: string;
     problems?: object[] | undefined;
 }): Array<Record<string, any>>;
+/**
+ * The closed set of roles a picture may declare.
+ *
+ * Shared with the field declaration below and with every medium that sizes a
+ * picture by its role, so the vocabulary cannot drift between the record that
+ * carries it and the renderer that reads it.
+ *
+ * @type {readonly string[]}
+ */
+export const ASSET_ROLES: readonly string[];
 /**
  * The file a directory records provenance for its subtree in.
  *
@@ -47,6 +57,18 @@ export const PROVENANCE_SIDECAR_SUFFIX: string;
  *   state this key. Omitting one is a finding rather than a blank, because a
  *   record resolves wholesale: the nearest one is the whole answer, so a key it
  *   leaves out is not inherited from above but simply absent.
+ * @property {"boolean"|"integer"} [type] - The value's own type, for a field
+ *   whose answer is not a string. Omitted for every string field; `ai` carries
+ *   the YAML boolean itself rather than a stringified copy, and `width` and
+ *   `height` carry the pixel count the walk measured. Each is refused rather
+ *   than coerced when the value does not match.
+ * @property {readonly string[]} [values] - The closed set a provenance
+ *   declaration must choose one of; a value outside it is a finding and the
+ *   key is left blank, the same treatment an `ai` value of the wrong shape
+ *   gets. `role` is the one field that carries it.
+ * @property {string} [onlyType] - The one asset type this field may be
+ *   declared for. A provenance record stating it for another type is a
+ *   finding, and the value is dropped rather than carried through.
  * @property {string} describe - One line, for the author-facing reference.
  */
 /**
@@ -105,6 +127,27 @@ export type AssetRecordField = {
      * leaves out is not inherited from above but simply absent.
      */
     required?: boolean | undefined;
+    /**
+     * - The value's own type, for a field
+     * whose answer is not a string. Omitted for every string field; `ai` carries
+     * the YAML boolean itself rather than a stringified copy, and `width` and
+     * `height` carry the pixel count the walk measured. Each is refused rather
+     * than coerced when the value does not match.
+     */
+    type?: "boolean" | "integer" | undefined;
+    /**
+     * - The closed set a provenance
+     * declaration must choose one of; a value outside it is a finding and the
+     * key is left blank, the same treatment an `ai` value of the wrong shape
+     * gets. `role` is the one field that carries it.
+     */
+    values?: readonly string[] | undefined;
+    /**
+     * - The one asset type this field may be
+     * declared for. A provenance record stating it for another type is a
+     * finding, and the value is dropped rather than carried through.
+     */
+    onlyType?: string | undefined;
     /**
      * - One line, for the author-facing reference.
      */