@heroiclands/package-build 22.21.0 → 22.23.0

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.
      */

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

@@ -0,0 +1,22 @@
+/**
+ * The replacement record for one asset address, or `null`.
+ *
+ * @param {string} address - A canonical asset address.
+ * @param {object} opts
+ * @param {string} opts.localPackage - The compiling package's own segment.
+ * @param {readonly string[]} opts.replacements - The package segments of
+ *   every relationship declaring `assetReplacement: true`, in declaration
+ *   order.
+ * @param {Map<string, object>} opts.index - The merged content index, keyed
+ *   by canonical address.
+ * @returns {{record: object, package: string}|null} The first replacement
+ *   carrying the address, or `null` when none does.
+ */
+export function resolveAssetReplacement(address: string, { localPackage, replacements, index }: {
+    localPackage: string;
+    replacements: readonly string[];
+    index: Map<string, object>;
+}): {
+    record: object;
+    package: string;
+} | null;

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

@@ -27,6 +27,24 @@ export function assetTypeOfRoot(root: unknown): AssetType | undefined;
  * @returns {boolean} Whether it matches {@link ADDRESS_SEGMENT_PATTERN}.
  */
 export function isAssetShortcode(shortcode: string): boolean;
+/**
+ * The pixel dimensions a raster image's own header states.
+ *
+ * Read from the file's bytes directly rather than through a decoder, so a
+ * corrupt or partial file fails closed — the same `undefined` answer as a
+ * format this carries no reader for — instead of throwing out of the asset
+ * walk. An SVG has no pixel dimensions to read; stating one would be a
+ * fabricated viewBox reading rather than a fact about the file.
+ *
+ * @param {string} absPath - The file's absolute path.
+ * @param {string} ext - Its extension, lowercase and dot-led.
+ * @returns {{width: number, height: number}|undefined} The declared size, or
+ *   `undefined` when the format carries none, or the header cannot be read.
+ */
+export function imageDimensions(absPath: string, ext: string): {
+    width: number;
+    height: number;
+} | undefined;
 /**
  * The `<system>` segment every asset address carries.
  *

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

@@ -1,20 +1,3 @@
-/**
- * The tallies one pass accumulates while walking the tree.
- *
- * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it declares a retired frontmatter field
- * — and it is an error; a skipped one legitimately belongs to another pass, and
- * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence.
- *
- * @typedef {object} PassStats
- * @property {number} compiled - Notes that became a document.
- * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
- * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes this pack **refused** — one declaring a
- *   retired frontmatter field, or one routed to a system pack whose system it
- *   says nothing about. Counted as errors, never as skips.
- */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
  *
@@ -378,6 +361,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-embeds.d.mts

@@ -45,6 +45,22 @@ export function resolveEmbed(index: object, embed: ParsedEmbed): {
     target: string;
     type?: string;
 };
+/**
+ * The role an address's asset declares, read through the same resolution an
+ * embed's address takes.
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` — for
+ * an address still in its authored form, before {@link resolveEmbeds} has
+ * rewritten it into the ordinary image every surface renders.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {string} address - The address as authored, inside `![[...]]`.
+ * @returns {string|undefined} The role, or `undefined` for a note's address,
+ *   one that resolves nowhere, or a picture that declares none.
+ */
+export function embedRole(index: object, address: string): string | undefined;
 /**
  * What is wrong with one embed's directive or placement, if anything.
  *

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

@@ -0,0 +1,101 @@
+/** Number a sequence of figures with counters shared across documents. */
+export function numberFigures(figures: any, counts: any): any;
+/**
+ * Read every `:::figure` fence in a body.
+ *
+ * SQL fences are expanded before this pass, so their output is a table.
+ *
+ * @param {string} source - A note body with expanded tables.
+ * @param {object} [options] - Options.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a picture whose
+ *   asset declares `role: map` counts as `map` rather than `figure`. Omitted,
+ *   every picture counts as `figure` — the same reading a role other than
+ *   `map` gets.
+ * @returns {{figures: Array<{id: string, slug: string, caption: string,
+ *   hasCaption: boolean, classes: string[], kind: string, number: number,
+ *   label: string, line: number, bodyStart: number, bodyEnd: number,
+ *   captionStart: number, captionEnd: number, close: number}>,
+ *   errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanFigures(source: string, { resolveRole }?: {
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+}): {
+    figures: Array<{
+        id: string;
+        slug: string;
+        caption: string;
+        hasCaption: boolean;
+        classes: string[];
+        kind: string;
+        number: number;
+        label: string;
+        line: number;
+        bodyStart: number;
+        bodyEnd: number;
+        captionStart: number;
+        captionEnd: number;
+        close: number;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Render figure fences as HTML, leaving other Markdown untouched.
+ *
+ * A code, table or prose figure's contents are 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 contents are rendered here rather than left for a later pass,
+ * because a picture-only fence has to become the surface's own `<figure>`
+ * markup directly inside the wrapper this function writes; the surrounding
+ * render never sees it as Markdown, so a footnote reference inside one is not
+ * resolved, the same gap a block's own title carries.
+ *
+ * @param {string} source - A note body with expanded tables.
+ * @param {(markdown: string) => string} [renderMarkdown] - How to render a
+ *   figure's own contents.
+ * @param {Array<{id: string, label: string}>} [numbers] - Labels assigned by a
+ *   surface that counts across documents, matched by id.
+ * @param {object} [options] - Options.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - See
+ *   {@link scanFigures}.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderFigureBlocks(source: string, renderMarkdown?: (markdown: string) => string, numbers?: Array<{
+    id: string;
+    label: string;
+}>, { resolveRole }?: {
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+}): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/** A figure's automatically determined kind, and the word that labels it. */
+export const FIGURE_NAMES: Readonly<{
+    code: "Code";
+    table: "Table";
+    figure: "Figure";
+    map: "Map";
+    prose: "Prose";
+}>;
+/**
+ * The classes a figure takes.
+ *
+ * `.border` states that the captioned thing is drawn inside a border, and each
+ * medium owns what that means. The vocabulary is closed: a class absent from it
+ * is a finding naming the class.
+ *
+ * @type {readonly string[]}
+ */
+export const FIGURE_CLASSES: readonly string[];

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

@@ -8,3 +8,83 @@ 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;
+}>;
+/**
+ * A footnote reference's shape, wherever it is written — excluding a
+ * definition's own `[^id]:` opener, which this never matches.
+ *
+ * @type {RegExp}
+ */
+export const FOOTNOTE_REFERENCE: RegExp;

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>}
  */