@heroiclands/package-build 22.21.0 → 22.22.0

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,10 +28,16 @@
  * `ACTOR_VAULT_TYPE = "being"` here and emitted `type: "being"` several hundred
  * lines below, which made the two vocabularies agree by coincidence.
  *
- * 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.
+ * 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.
+ *
+ * **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
@@ -105,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 {
     /**
@@ -184,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) => {
@@ -333,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.
@@ -387,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
@@ -411,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.
      *

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

@@ -0,0 +1,93 @@
+/**
+ * The cascade layer the sheet loads into, per package kind.
+ *
+ * Foundry declares its layer order in `css/foundry2.css`, ending
+ * `… layouts, system, modules, exceptions` — the eighth and ninth being, by its
+ * own comments, default game system styles and default module styles. That is
+ * what this sheet is, so it takes the layer its kind is given and is therefore
+ * the weakest thing a package can load:
+ *
+ * - **An unlayered package sheet beats it**, because an unlayered rule beats
+ *   every layered one whatever its specificity.
+ * - **A package sheet naming any other layer beats it too**, because a layer
+ *   Foundry's order does not mention is appended after the ones it does.
+ *
+ * So a package overrides the base sheet from its own, whichever way it declares
+ * one, and the override needs no `!important` and no specificity contest.
+ *
+ * @param {"system"|"module"} artifact - Which artifact is shipped.
+ * @returns {string} The layer name.
+ */
+export function baseStyleLayer(artifact: "system" | "module"): string;
+/**
+ * The manifest `styles` entry for the base sheet.
+ *
+ * Foundry's `styles` is an array of `{layer?, src}`, and a bare string is
+ * migrated into that shape on read, so the object form is written directly.
+ *
+ * @param {"system"|"module"} artifact - Which artifact is shipped.
+ * @returns {{src: string, layer: string}} The entry.
+ */
+export function baseStyleEntry(artifact: "system" | "module"): {
+    src: string;
+    layer: string;
+};
+/**
+ * The absolute path of the sheet as installed, so the stage can copy it.
+ *
+ * Resolved against this module rather than against the consumer's working
+ * directory, because the file belongs to this package and arrives through
+ * `node_modules`.
+ *
+ * @returns {string} Absolute path of the shipped stylesheet.
+ */
+export function baseStylesheetSource(): string;
+/**
+ * The `[source, destination]` pair that stages the sheet.
+ *
+ * The destination is relative, in the same spelling the repository's own asset
+ * table uses, so the caller resolves both against the repository root exactly
+ * as it resolves every other entry.
+ *
+ * @param {string} stageDir - The configured stage directory, relative to the
+ *   repository root.
+ * @returns {[string, string]} The pair, for `stageAssets`.
+ */
+export function baseStyleStageEntry(stageDir: string): [string, string];
+/**
+ * The manifest's `styles`, with the base sheet named first.
+ *
+ * **First rather than last**, because `styles` is load order: a package's own
+ * sheet has to be read after the base one for an override written at equal
+ * specificity in an equal layer to take. The cascade layer makes the override
+ * work anyway, and the order makes it work for the right reason.
+ *
+ * A declared entry addressing the same file is not duplicated — a repository
+ * that named the staged path itself gets one entry, keeping whatever layer it
+ * chose, so declaring it is a way of placing it rather than an error.
+ *
+ * @param {object} options
+ * @param {unknown} [options.declared] - The declared `styles`, whatever shape
+ *   it was written in; anything that is not a list is returned untouched.
+ * @param {"system"|"module"} options.artifact - Which artifact is shipped.
+ * @param {boolean} [options.enabled] - Whether the package takes the base
+ *   sheet. `false` returns the declared list unchanged.
+ * @returns {unknown} The `styles` to emit, or `undefined` when there is
+ *   nothing to emit at all.
+ */
+export function withBaseStyle({ declared, artifact, enabled }: {
+    declared?: unknown;
+    artifact: "system" | "module";
+    enabled?: boolean | undefined;
+}): unknown;
+/**
+ * Where the shipped sheet lands inside the staged package.
+ *
+ * Under `styles/` beside a package's own sheet, and named for the toolchain so
+ * nothing a repository writes can collide with it. The path is relative to the
+ * staged package root, which is what both the stage entry and the manifest's
+ * `styles` are addressed in.
+ *
+ * @type {string}
+ */
+export const BASE_STYLESHEET_DEST: string;

package/types/engine/content-blocks.d.mts

@@ -0,0 +1,87 @@
+/**
+ * Find named blocks, leaving code examples alone.
+ *
+ * A block reaches `blocks` only when it is well formed and closed; everything
+ * else is a finding, and the surrounding blocks are unaffected.
+ *
+ * @param {string} source - Markdown that may contain named blocks.
+ * @returns {{blocks: Array<{name: string, title: string, id: string, classes: string[], attributes: Record<string, string>, start: number, end: number, body: string}>, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanBlocks(source: string): {
+    blocks: Array<{
+        name: string;
+        title: string;
+        id: string;
+        classes: string[];
+        attributes: Record<string, string>;
+        start: number;
+        end: number;
+        body: string;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Render named blocks for one publishing surface.
+ *
+ * `foundry` emits a `<section>` whose heading is its first line; `web` emits a
+ * `<details>` the reader opens. Neither carries an inline `style`.
+ *
+ * The body is left as Markdown between the wrapper's tags, each separated from
+ * its tag by a blank line — see the module docs for why that is what lets the
+ * surrounding render treat the body as real content rather than an opaque
+ * fragment.
+ *
+ * A finding does not stop the well-formed blocks around it from rendering.
+ *
+ * @param {string} source - Markdown containing named blocks.
+ * @param {"foundry"|"web"} target - Publishing surface.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderBlocks(source: string, target: "foundry" | "web"): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Wrap each withheld section in the disclosure a `secret` block renders as.
+ *
+ * The section's own Markdown is left as Markdown, with a blank line either side
+ * of it, so the page's renderer still reads it: the heading keeps its id, the
+ * prose keeps its links, and only the disclosure around them is written as HTML.
+ *
+ * **A spoiler, not access control.** The section is in the published page, so a
+ * reader who opens the element or reads the source reads it. Foundry is the one
+ * surface that withholds anything.
+ *
+ * @param {string} source - A page's Markdown, headings intact.
+ * @returns {string} The same Markdown, each withheld section inside a
+ *   `<details>`.
+ */
+export function renderWithheldSections(source: string): string;
+/** The blocks an author may open, with the heading each takes by default. */
+export const BLOCK_NAMES: Readonly<{
+    info: "Info";
+    secret: "Secret";
+    warn: "Warn";
+}>;
+/**
+ * Blocks that may hold another named block.
+ *
+ * A box inside a GM-only section is a real thing to write — the section is a
+ * container for whatever the GM reads, boxes included — so a `secret` holds one
+ * and the box stays inside it. A box inside a box is noise, so `info` and `warn`
+ * hold no named block and a second opener inside one is a finding.
+ *
+ * Exported because a renderer has to know it: the body of a container is read
+ * for blocks of its own, and the body of a box is not.
+ *
+ * @type {readonly string[]}
+ */
+export const BLOCK_CONTAINERS: readonly string[];

package/types/engine/content-captions.d.mts

@@ -27,7 +27,20 @@ export function scanCaptions(source: string): {
         message: string;
     }>;
 };
-/** Render captioned blocks as HTML, leaving other Markdown untouched. */
+/**
+ * Render captioned blocks as HTML, leaving other Markdown untouched.
+ *
+ * A code, table or prose caption's block is left as Markdown inside the
+ * wrapper, blank-line separated from its tags exactly as
+ * {@link module:engine/content-blocks.renderBlocks} leaves a named block's
+ * body — so the surrounding render sees it as part of its own document and a
+ * footnote reference inside it resolves against the note's own definitions.
+ *
+ * A figure's block is still rendered here, because its `<figcaption>` has to
+ * be stripped from HTML this pass controls directly; the surrounding render
+ * never sees it as Markdown, so a footnote reference inside a figure caption
+ * is not resolved, the same gap a block's own title carries.
+ */
 export function renderCaptionBlocks(source: any, renderMarkdown: ((src: string, env?: import("markdown-it").Env) => string) | undefined, numbers: any): {
     markdown: any;
     errors: {

package/types/engine/content-footnotes.d.mts

@@ -8,3 +8,76 @@ export function separateFootnotes(source: string): {
     markdown: string;
     definitions: string;
 };
+/**
+ * A footnote definition written inside a list item or a block quote, where
+ * the web and Foundry can resolve it but the book drops it silently.
+ *
+ * A definition inside a table cell is not reported here: a table cell is
+ * inline content, so `[^id]:` there is never recognised as a definition on
+ * any surface and simply prints as written — the reference it was meant to
+ * answer is what {@link unresolvedFootnoteReferences} reports.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, label: string, message: string}>}
+ */
+export function misplacedFootnoteDefinitions(source: string): Array<{
+    line: number;
+    column: number;
+    label: string;
+    message: string;
+}>;
+/**
+ * A footnote reference with no top-level definition to resolve against.
+ *
+ * Covers both commoner slips alike: a label never defined at all, and one
+ * "defined" only inside a table cell, which is inline content and never
+ * registers as a definition on any surface. A label misplaced in a list or a
+ * block quote is excluded — {@link misplacedFootnoteDefinitions} already
+ * reports that mistake at the definition's own line, and reporting it again
+ * at the reference would say the same thing twice.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {string} [definitions] - Its top-level definitions, when a caller
+ *   already extracted them with {@link separateFootnotes}. Derived from
+ *   `source` when omitted; a caller already holding both passes its own
+ *   extraction instead, so the two cannot disagree about what is defined.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function unresolvedFootnoteReferences(source: string, definitions?: string): Array<{
+    line: number;
+    column: number;
+    message: string;
+}>;
+/**
+ * A top-level footnote definition no reference anywhere in the note uses.
+ *
+ * `separateFootnotes` lifts it out correctly, nothing resolves against it,
+ * and the paragraph it held vanishes from every surface with the build
+ * exiting 0 — a dropped paragraph is not something a reader can notice is
+ * missing, so it is an error here rather than a warning, the same severity
+ * every other silent loss this pass catches already carries. A note mid-edit,
+ * with the reference already deleted and the definition not yet followed, is
+ * exactly the case this refuses — which is the point: the alternative is
+ * shipping it.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function unusedFootnoteDefinitions(source: string): Array<{
+    line: number;
+    column: number;
+    message: string;
+}>;
+/**
+ * Every footnote placement finding for one note body — the union
+ * {@link misplacedFootnoteDefinitions}, {@link unresolvedFootnoteReferences}
+ * and {@link unusedFootnoteDefinitions} report, in document order.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Array<{line: number, column: number, message: string}>}
+ */
+export function footnoteFindings(source: string): Array<{
+    line: number;
+    column: number;
+    message: string;
+}>;

package/types/engine/content-format-check.d.mts

@@ -180,12 +180,14 @@ export function checkDeclaredFields({ format, itemFields, system, severity }: {
 /**
  * Top-level keys the format names as the note's own, whatever its type.
  *
- * Top level is otherwise **open** — an unrecognised key there is a Hugo or
- * theme parameter this build has no standing to refuse — so this set exists
- * only to keep a note's own identity fields from being mistaken for a
- * misplaced `data` property where the two share a name. `type` and `subType`
- * are the pair that matters: several mapping tables name `subType` as a shared
- * source, and it is authored at top level by design.
+ * The top-level vocabulary itself, read rather than restated: this set exists
+ * to keep a note's own identity fields from being mistaken for a misplaced
+ * `data` property where the two share a name, and the keys that are a note's
+ * own are exactly the ones the region declares. `type` and `subType` are the
+ * pair that matters — several mapping tables name `subType` as a shared source,
+ * and it is authored at top level by design. A key the region does *not*
+ * declare, such as `id` beside `data.id`, is reported as the misplaced `data`
+ * property it is.
  *
  * @type {ReadonlySet<string>}
  */