@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/web-wikilinks.mjs

@@ -64,6 +64,26 @@ export { slugify };
 import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
 import { resolveEmbeds } from "./content-embeds.mjs";
 
+/**
+ * Whether a page's declared anchors include the slug a link names.
+ *
+ * A local page's entry carries a `Set` (built by {@link module:engine/site-index});
+ * a foreign one carries the `{slug: uuid}` map a fetched manifest publishes.
+ * `undefined` means neither build recorded an answer, which keeps a target
+ * this check cannot speak for exactly as unchecked as it always was.
+ *
+ * @param {Set<string>|Record<string, string>|undefined} anchors - The page's
+ *   declared anchors, or `undefined` where none were recorded.
+ * @param {string} slug - The anchor a link names.
+ * @returns {boolean} Whether the anchor is declared, or `true` when `anchors`
+ *   is `undefined` — which reads as "nothing to check against" rather than
+ *   "declares none".
+ */
+function hasAnchor(anchors, slug) {
+    if (!anchors) return true;
+    return anchors instanceof Set ? anchors.has(slug) : Object.hasOwn(anchors, slug);
+}
+
 /**
  * The index key a **piped** target resolves to, or `null` when it does not
  * parse as an address at all.
@@ -315,7 +335,9 @@ function isPlainMap(value) {
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in. `resolved`, when supplied, is the array every resolved
- *   target's index entry is appended to.
+ *   target's index entry is appended to. `anchors` is the `{#slug}` set
+ *   *this* page declares, which a `[[#slug]]` self-link is checked against;
+ *   absent, a self-link is not checked, exactly as before this existed.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body, ctx) {
@@ -399,6 +421,16 @@ export function resolveWebWikilinks(body, ctx) {
 
         // `[[#section-slug|Text]]` — a section of this same page.
         if (isSamePage({ target, anchor })) {
+            // Checked against this page's own anchors, exactly as a link into
+            // another page is: a self-link naming a section the page does not
+            // declare is as dead as one naming a section nowhere does.
+            if (!hasAnchor(ctx.anchors, anchor)) {
+                return report(
+                    all,
+                    { target, reason: "unknown-anchor", anchor, addressed: true },
+                    label ?? anchor,
+                );
+            }
             return `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`;
         }
 
@@ -419,6 +451,21 @@ export function resolveWebWikilinks(body, ctx) {
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
             :   undefined);
         if (hit) {
+            // A `#section` the target declares no heading for. Checked only
+            // where there is a page to check against — a pack-only hit has no
+            // `url` and therefore nothing for the anchor to address, which is
+            // the asset-like case this must not touch. `anchorPageId` on the
+            // pack build and the KB manifest's own `{slug: uuid}` map both
+            // hash any slug into something that resolves, so an undeclared
+            // one otherwise joins onto the URL unchecked and dead-ends for
+            // the reader.
+            if (anchor && hit.url && !hasAnchor(hit.anchors, anchor)) {
+                return report(
+                    all,
+                    { target, reason: "unknown-anchor", anchor, addressed: true },
+                    label ?? hit.name ?? target,
+                );
+            }
             // The edge, for a caller reading the link graph off this pass.
             ctx.resolved?.push(hit);
             // An address with an *empty* label has no prose to show (a

package/engine/wikilinks.mjs

@@ -583,7 +583,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {unknown} ref - The reference, as authored.
  * @param {object} [hint] - `{type}`, where the caller knows what it expects.
- * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string}|undefined}
+ * @returns {{name?: string, uuid?: string, address?: import("./address.mjs").AddressTuple, subType?: string, standings?: object}|undefined}
  *   The target, or `undefined` where nothing answers.
  */
 export function resolveReference(index, ref, hint) {
@@ -611,6 +611,7 @@ export function resolveReference(index, ref, hint) {
         return {
             name: published.name,
             subType: published.subType,
+            ...(published.standings ? { standings: published.standings } : {}),
             ...(published.uuid ? { uuid: published.uuid } : {}),
             address: tuple,
         };
@@ -638,6 +639,7 @@ export function resolveReference(index, ref, hint) {
         return {
             name: local.name,
             subType: local.subType,
+            ...(local.standings ? { standings: local.standings } : {}),
             ...(uuid ? { uuid } : {}),
             address: tuple,
         };

package/hm3/actors.mjs

@@ -227,9 +227,9 @@ export class Hm3Actors extends SystemActorCompiler {
     /**
      * Build every embedded item an HM3 actor carries, from `hm3.items`.
      *
-     * One list, not two: HM3 keeps a character's abilities in `system.abilities`
-     * rather than as embedded documents, so there is no attributes map to
-     * expand the way SoHL's pass expands `sohl.attributes`.
+     * HM3 keeps a character's abilities in `system.abilities` rather than as
+     * embedded documents, so an ability reaches the document through the
+     * `hm3.system` passthrough and never through this list.
      *
      * @param {Map<string, object>} itemsMap - The predefined items, by address.
      * @param {string} actorId - The owning actor's id, seeding embedded ids.
@@ -333,6 +333,9 @@ export class Hm3Actors extends SystemActorCompiler {
             isAddress: true,
         });
 
+        this.checkAnchoredSection(body || "", "appearance", ctx);
+        this.checkAnchoredSection(body || "", "dossier", ctx);
+
         const system = {
             // `system.bioImage` is **not** written here, for the reason SoHL's
             // `system.portrait` is not: a being's portrait is the lead image of

package/manifest.mjs

@@ -52,6 +52,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 
+import { withBaseStyle } from "./engine/base-styles.mjs";
 import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
 import { metadataFileName } from "./engine/metadata-index.mjs";
 
@@ -548,6 +549,18 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
 
     const merged = { ...declared, ...derived };
 
+    // The shared base stylesheet, named ahead of whatever the package declares.
+    // Derived rather than declared, because every package needs it and four of
+    // the five that do have no stylesheet of their own to name it from. See
+    // `engine/base-styles.mjs` for the layer it loads into and why that is what
+    // lets a package override it.
+    const styles = withBaseStyle({
+        declared: declared.styles,
+        artifact: /** @type {"system"|"module"} */ (artifact),
+        enabled: config.packageBuild?.baseStyles !== false,
+    });
+    if (styles !== undefined) merged.styles = styles;
+
     // The index every consumer resolves this package's addresses through.
     // Written unconditionally, because a package that publishes no
     // index is one nothing can link into — and the failure of an absent one is

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.20.0",
+    "version": "22.22.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/sohl/actors.mjs

@@ -18,10 +18,9 @@
  * reference translation through the system's map, embedding and its stable ids,
  * the anchored prose sections — lives in
  * {@link module:engine/actor-compiler}, where a second system reaches it.
- * What is left here is SoHL's data model: the body structure and its
- * movement profiles, the attributes-and-items frontmatter that becomes embedded
- * documents, the opening mastery level a skill is baked with, and the `system`
- * block itself.
+ * What is left here is SoHL's data model: the `sohl.items` frontmatter that
+ * becomes embedded documents, the opening mastery level a skill is baked with,
+ * and the `system` block itself.
  *
  * One content type today, and the actor subtype it produces is **declared**
  * rather than assumed to be the same word: `sohl/document-subtypes.mjs` maps
@@ -29,15 +28,24 @@
  * `ACTOR_VAULT_TYPE = "being"` here and emitted `type: "being"` several hundred
  * lines below, which made the two vocabularies agree by coincidence.
  *
- * It was two content types — `character` and `creature` — which compiled to the
- * same `being` with no branch anywhere between them; they were retired in
- * retired, and are reported by `assertTypeNotRetired` in
- * `engine/ids.mjs`.
+ * Each entry in `sohl.items` is resolved by `(type, shortcode)` and deep-merged
+ * with the entry's other properties, so an attribute carries its `scoreBase`
+ * and a skill its `masteryLevelBase` as that entry's own `system` overlay.
  *
- * Attributes (`sohl.attributes` map) become embedded attribute items with
- * `scoreBase` set from the map value. Each entry in `sohl.items` is similarly
- * resolved by `(type, shortcode)` and deep-merged with the entry's other
- * properties. `sohl.skills` is ignored.
+ * **A being's own document fields are authored under `sohl.system`**, which
+ * {@link module:engine/system-block.mergeSystemData} writes at the DataModel's
+ * own paths: a being's body is `sohl.system.body`, with
+ * `sohl.system.currentMoveMedium` and `sohl.system.movementProfiles` beside it.
+ * So this pass writes no body itself, and an incorporeal being authors none and
+ * keeps the schema's empty one.
+ *
+ * **A membership is derived, never authored here.** `data.affiliations` names
+ * the bodies a being belongs to and the standing it holds in each, and each
+ * entry becomes one embedded affiliation item: the entry's `rank` is that
+ * item's `system.level` and its `office` is `system.office`. A standing is a
+ * fact about the setting rather than about one system — it does not become true
+ * because SoHL is installed — so the system block states none of it, and a
+ * sheet and a page cannot come to disagree.
  *
  * Not a standalone script — exports the `Actors` compiler class, imported and
  * driven by `engine/generate.mjs`. Must run after the items passes, since it
@@ -58,6 +66,10 @@ 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";
+// A being's memberships and the standing it holds in each, read from the one
+// place they are authored. The rank *is* the affiliation item's `level`, so
+// there is nothing to map and nowhere for a second authoring to disagree.
+import { readStandings } from "../engine/standings.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -98,60 +110,12 @@ function defaultActorImg(subType) {
     return img;
 }
 
-/**
- * Normalize a being's persisted `system.body` from a `sohl.body` block. The
- * authoring frontmatter mirrors the schema field-for-field: `sohl.body` nests
- * `structure` / `weight` / `reachBase` / `bodyScaleBase` / `personalFatigue`,
- * exactly like `system.body`.
- */
-function normalizeBody(bodyObj) {
-    const b = bodyObj && typeof bodyObj === "object" ? bodyObj : {};
-    const weight = b.weight || {};
-    return {
-        structure: b.structure ?? { parts: [], adjacent: [] },
-        weight: {
-            base: weight.base == null ? null : Number(weight.base),
-            calc: String(weight.calc ?? "0"),
-        },
-        reachBase: Number(b.reachBase ?? 0) || 0,
-        bodyScaleBase: Number(b.bodyScaleBase ?? 1) || 1,
-        personalFatigue: String(b.personalFatigue ?? "enc"),
-    };
-}
-
-/** Normalize per-medium movement profiles from a `sohl.movementProfiles` list. */
-function normalizeMovementProfiles(list) {
-    return (Array.isArray(list) ? list : []).map((p) => ({
-        medium: String(p.medium ?? "terrestrial"),
-        feetPerRound: Number(p.feetPerRound ?? 0) || 0,
-        leaguesPerWatch: Number(p.leaguesPerWatch ?? 0) || 0,
-        encumbrance: String(p.encumbrance ?? "0"),
-        strMod: String(p.strMod ?? "0"),
-        disabled: Boolean(p.disabled ?? false),
-    }));
-}
-
-/**
- * Extract a being's body (+ its movement) from a `sohl` block that mirrors the
- * schema: `sohl.body` (nested → `system.body`) and the flat
- * `sohl.currentMoveMedium` / `sohl.movementProfiles` (→ the base-actor movement
- * fields; movement is a universal actor capability, not part of the body).
- */
-function extractBodyAndMovement(fm) {
-    return {
-        body: normalizeBody(sohlField(fm, "body", {})),
-        currentMoveMedium: String(sohlField(fm, "currentMoveMedium", "none")),
-        movementProfiles: normalizeMovementProfiles(sohlField(fm, "movementProfiles", [])),
-    };
-}
-
 /**
  * SoHL's Actor compile pass.
  *
  * Declares SoHL's note-type → document-subtype map and builds a `being` note's
- * document: the body structure and its movement profiles, the embedded
- * attribute and item documents the frontmatter names, and the `system` block.
- * Everything else is {@link module:engine/actor-compiler}'s.
+ * document: the embedded item documents the frontmatter names, and the `system`
+ * block. Everything else is {@link module:engine/actor-compiler}'s.
  */
 export class Actors extends SystemActorCompiler {
     /**
@@ -177,30 +141,12 @@ export class Actors extends SystemActorCompiler {
     }
 
     /**
-     * Build all embedded items for an actor: one per `sohl.attributes`
-     * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
+     * Build all embedded items for an actor: one per `sohl.items` entry, plus
+     * one per body the being belongs to.
      */
     buildEmbeddedItems(itemsMap, actorId, fm, ctx) {
         const items = [];
 
-        const attributes = sohlField(fm, "attributes", null);
-        if (attributes && typeof attributes === "object") {
-            for (const [shortcode, value] of Object.entries(attributes)) {
-                const overlay = { system: { scoreBase: Number(value) || 0 } };
-                const embedded = this.resolveEmbedded(
-                    itemsMap,
-                    actorId,
-                    "attribute",
-                    shortcode,
-                    overlay,
-                    `attr:${shortcode}`,
-                    ctx,
-                    { fmKey: "attributes" },
-                );
-                if (embedded) items.push(embedded);
-            }
-        }
-
         const sohlItems = sohlField(fm, "items", null);
         if (Array.isArray(sohlItems)) {
             sohlItems.forEach((entry, index) => {
@@ -256,10 +202,59 @@ export class Actors extends SystemActorCompiler {
             });
         }
 
+        for (const embedded of this.buildMemberships(itemsMap, actorId, fm, ctx)) {
+            items.push(embedded);
+        }
+
         this.openUnopenedSkills(items, ctx);
         return items;
     }
 
+    /**
+     * One embedded affiliation item per body the being belongs to.
+     *
+     * The body's own compiled item is the model, so a membership carries
+     * whatever that body declares — its subtype, its common skills, its
+     * standings toward others — and the being adds only what is true of *this*
+     * membership: the rung it stands on and the post it holds.
+     *
+     * A being naming a body that compiles to no item is a finding rather than a
+     * silently dropped membership: the note says the being belongs somewhere,
+     * and a sheet that shows nothing says it does not.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined-item catalogue.
+     * @param {string} actorId - The owning actor's id.
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} ctx - Diagnostic context.
+     * @returns {object[]} The embedded items, in the order the note names them.
+     */
+    buildMemberships(itemsMap, actorId, fm, ctx) {
+        const { entries } = readStandings(fm?.data?.affiliations);
+        const items = [];
+        for (const { body, standing } of entries) {
+            const shortcode = body?.shortcode;
+            if (!shortcode) continue;
+            const level = Number(standing?.rank);
+            const office = typeof standing?.office === "string" ? standing.office.trim() : "";
+            const system = {
+                ...(Number.isFinite(level) ? { level } : {}),
+                ...(office ? { office } : {}),
+            };
+            const embedded = this.resolveEmbedded(
+                itemsMap,
+                actorId,
+                "affiliation",
+                shortcode,
+                Object.keys(system).length ? { system } : {},
+                `affiliations:${shortcode}`,
+                ctx,
+                { fmKey: "affiliations", modelPackage: body.package ?? null },
+            );
+            if (embedded) items.push(embedded);
+        }
+        return items;
+    }
+
     /**
      * Bake each unopened skill's opening mastery level into the document.
      *
@@ -277,8 +272,8 @@ export class Actors extends SystemActorCompiler {
      *
      * **The scores used are the ones just written.** `SkillLogic` resolves
      * `attr.<code>` to an attribute's *effective* score, after active effects;
-     * all this pass has is the `scoreBase` it set from `sohl.attributes`. For a
-     * compiled being carrying no attribute-altering effects the two agree,
+     * all this pass has is the `scoreBase` on each embedded attribute item. For
+     * a compiled being carrying no attribute-altering effects the two agree,
      * which is every being in content today. One that did carry such an effect
      * would bake a Skill Base its client then disagrees with — that is the
      * limit of doing this at build time, and the point to revisit if it bites.
@@ -331,6 +326,9 @@ export class Actors extends SystemActorCompiler {
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
+        this.checkAnchoredSection(body || "", "appearance", ctx);
+        this.checkAnchoredSection(body || "", "dossier", ctx);
+
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
@@ -355,25 +353,6 @@ export class Actors extends SystemActorCompiler {
             dossier: withDraftNotice(fm, renderSection(body || "", "dossier")),
         };
 
-        // Fill `system.body` (+ the base-actor movement fields) from the being's
-        // frontmatter, rather than embedding a corpus item. The `sohl`
-        // block mirrors `system` field-for-field: `sohl.body` nests the body
-        // (`structure` / `weight` / …), with `currentMoveMedium` /
-        // `movementProfiles` flat alongside it. An **incorporeal** being omits
-        // `sohl.body` and keeps the schema's empty body.
-        const bodyField = sohlField(fm, "body", null);
-        if (bodyField && typeof bodyField === "object") {
-            const bodyData = extractBodyAndMovement(fm);
-            system.body = bodyData.body;
-            system.currentMoveMedium = bodyData.currentMoveMedium;
-            system.movementProfiles = bodyData.movementProfiles;
-        } else if (bodyField != null) {
-            this.noteError(
-                `${ctx}: sohl.body must be an inline object (structure/weight/…), got ${typeof bodyField}`,
-            );
-            this.errorCount++;
-        }
-
         // Being-only combat grouping (mirrors `system.defaultCombatGroup`).
         const defaultCombatGroup = sohlField(fm, "defaultCombatGroup", undefined);
         if (defaultCombatGroup !== undefined) {

package/sohl/item-fields.mjs

@@ -391,11 +391,10 @@ export const ITEM_FIELDS = Object.freeze({
             ...STRING,
             default: "",
             topLevelMeans:
-                "the note's own title — the heading its page is published under, " +
-                "which has nothing to do with the style of address an office " +
-                "carries. Author this on the membership instead: `sohl.system.title` " +
-                "on the item, or the `system.title` of the entry in a being's " +
-                "`sohl.items`.",
+                "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 " +
+                "`system.title` of the entry in a being's `sohl.items`.",
             describe: "The style of address the office carries.",
         },
         {

package/sohl/items.mjs

@@ -93,7 +93,7 @@ export class Items extends SystemItemCompiler {
             // it — an undeclared `system` key is discarded at construction
             // without a warning.
             templatePriority: systemTemplatePriority(fm, label),
-            actionDefs: Array.isArray(fm.actionDefs) ? fm.actionDefs : [],
+            actionDefs: [],
             notes: "",
             docHtml: description || "",
         };

package/sohl/note-schemas.mjs

@@ -99,37 +99,27 @@ const MACRO_FIELDS = Object.freeze([
 const VEHICLE_FIELDS = Object.freeze([]);
 
 /**
- * A `being` note — an actor, with its body, movement and embedded items.
+ * A `being` note — an actor, with its embedded items and its combat grouping.
+ *
+ * **A being's own document fields are authored under `sohl.system`**, which the
+ * passthrough writes at the DataModel's own paths — a body and the movement that
+ * goes with it are `sohl.system.body`, `sohl.system.currentMoveMedium` and
+ * `sohl.system.movementProfiles`, written together — so this declaration states
+ * none of them. **Attributes and skills are embedded items**, each named by the
+ * catalogue entry it copies, so both are `sohl.items` entries with the score or
+ * the mastery level as that entry's own `system` overlay.
+ *
+ * What is left is the two keys the pass reads off the block itself.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const BEING_FIELDS = Object.freeze([
-    {
-        name: "body",
-        ...MAP,
-        describe: "The being's body structure, by part shortcode.",
-    },
-    {
-        name: "attributes",
-        ...MAP,
-        describe: "Attribute scores, by attribute shortcode.",
-    },
     {
         name: "items",
         ...LIST,
         describe:
             "Items embedded on the being, each addressed by (type, shortcode) or carrying enough fields to stand alone.",
     },
-    {
-        name: "currentMoveMedium",
-        ...STRING,
-        describe: "Which medium the being is currently moving through.",
-    },
-    {
-        name: "movementProfiles",
-        ...LIST,
-        describe: "Movement rates, one profile per medium.",
-    },
     {
         name: "defaultCombatGroup",
         ...AS_AUTHORED,

package/types/config.d.mts

@@ -102,6 +102,9 @@ export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {boolean} baseStyles    Whether the package takes the shared base
+ *                                   stylesheet, staged into `stageDir` and
+ *                                   named first in the manifest's `styles`.
  * @property {Readonly<Record<string, unknown>>} manifest  The manifest
  *                                   specification, emitted as declared.
  * @property {string|null} manifestFlags  Module to load a `flags` function
@@ -235,6 +238,12 @@ export type PackageBuildConfig = {
      */
     stageDir: string;
     assets: readonly Readonly<AssetSpec>[];
+    /**
+     * Whether the package takes the shared base
+     * stylesheet, staged into `stageDir` and
+     * named first in the manifest's `styles`.
+     */
+    baseStyles: boolean;
     /**
      * The manifest
      * specification, emitted as declared.

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

@@ -248,6 +248,17 @@ export class SystemActorCompiler extends BasePackCompiler {
         img: string;
         token: string;
     };
+    /**
+     * Report an `{#appearance}` or `{#dossier}` anchor on a heading
+     * {@link extractAnchorSection} cannot read, rather than letting the field
+     * it feeds compile blank with nothing to say why.
+     *
+     * @param {string} body - The note body.
+     * @param {string} anchorId - `"appearance"` or `"dossier"`.
+     * @param {string} ctx - The actor's label, for the message.
+     * @returns {void}
+     */
+    checkAnchoredSection(body: string, anchorId: string, ctx: string): void;
     /** @type {readonly string[]} */
     itemsSourceDirs: readonly string[];
     foreignSourceDirs: any;

package/types/engine/anchored-sections.d.mts

@@ -6,6 +6,11 @@
  * heading exists. Fenced code blocks are respected so `# foo` inside
  * ``` blocks does not trigger a match.
  *
+ * An anchor declared on a lower heading is found by {@link collectAnchors}
+ * but not by the `#\s+` match below, so it extracts as absent rather than as
+ * wrong — {@link misplacedAnchorSection} is the check a caller runs first to
+ * tell the two apart.
+ *
  * @param {string} body - The note body.
  * @param {string} anchorId - The anchor to find.
  * @returns {string} The section's markdown, or "".
@@ -19,3 +24,22 @@ export function extractAnchorSection(body: string, anchorId: string): string;
  * @returns {string} The rendered HTML, or "".
  */
 export function renderSection(body: string, anchorId: string): string;
+/**
+ * Where an `{#appearance}` or `{#dossier}` anchor sits on a heading below the
+ * top level, which {@link extractAnchorSection} cannot read.
+ *
+ * {@link module:engine/anchors.collectAnchors} finds the anchor at any
+ * level, because a lower heading legitimately starts a journal page. It does
+ * not feed an actor field: an H1-only extractor reads nothing from one, and a
+ * caller that trusts the empty result as "no such section" rather than
+ * "found, but unreadable" compiles a blank field with nothing to say why.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to check, case-insensitively.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{line: number}|null} The misplaced anchor's line, or `null` when
+ *   it is absent or already on an H1.
+ */
+export function misplacedAnchorSection(body: string, anchorId: string, bodyLine?: number): {
+    line: number;
+} | null;

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

@@ -378,6 +378,25 @@ export class BasePackCompiler {
     linkIndex: any;
     sqlTables: any;
     worldPresent: unknown;
+    /**
+     * Report every finding {@link BasePackCompiler#convertBody} collected
+     * across its passes, and decline the note if there were any.
+     *
+     * Reported directly, one `noteError` per finding, rather than thrown as a
+     * single wrapped message: the site build and the book report the same way,
+     * each finding at its own line, and a note with three problems meets all
+     * three in the run that found them instead of one per rebuild. The thrown
+     * sentinel carries `alreadyReported` so the compile loop's generic catch
+     * does not add a fourth, vaguer line on top of the three already said.
+     *
+     * @param {readonly {message: string, line?: number, column?: number}[]} findings
+     * @throws {Error} When `findings` is non-empty, after reporting all of them.
+     */
+    reportConvertBodyFindings(findings: readonly {
+        message: string;
+        line?: number;
+        column?: number;
+    }[]): void;
     /**
      * The body {@link BasePackCompiler#buildEntry} receives.
      *