@heroiclands/package-build 22.20.0 → 22.22.0

package/types/engine/homepage.d.mts

@@ -119,7 +119,7 @@ export function checkHomepageCount(found: ReadonlyArray<{
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
  * authored `name.full` wins, because a front page may greet a reader
- * differently from a package browser. A top-level `title` is also readable.
+ * differently from a package browser.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -244,12 +244,12 @@ export const HOMEPAGE_DESTINATION: string;
  * `name` and `shortcode` are permitted: the shortcode is what a link is
  * written with, and `name` titles the page like every other note's.
  *
- * **A named class, not an allow-list, and that boundary is the decision.** A
- * homepage's frontmatter is *emitted into the published page*
- * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
- * parameter this build has never heard of and has no standing to refuse.
- * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release.
+ * **A named class, not an allow-list, and that boundary is the decision.**
+ * What this class answers is a key the top-level vocabulary *accepts* and a
+ * homepage still cannot use, which is a different question from an unknown
+ * key: the frontmatter lint refuses those for every note alike, naming the
+ * closed vocabulary, so repeating that judgement per type would be a second
+ * answer to one question.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
  * on every note whatever its type, so it is answered there rather than

package/types/engine/index.d.mts

@@ -61,6 +61,7 @@ export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";
 export * as contentImages from "./content-images.mjs";
+export * as contentTaskLists from "./content-tasklists.mjs";
 export * as contentEmbeds from "./content-embeds.mjs";
 export * as pathnames from "./pathnames.mjs";
 export * as contentLinks from "./content-links.mjs";

package/types/engine/infobox-render.d.mts

@@ -54,12 +54,17 @@ export function sectionHasContent(section: object): boolean;
  * reference, so the link works on paper as a cross-reference and in a PDF
  * viewer as a jump. Everything else is set as its own words.
  *
+ * A panel's rows address pages the same way prose does, so a page the book does
+ * not print is set as the absolute URL a reader can follow — see
+ * {@link module:engine/pdf-render.absolutePageUrl}.
+ *
  * @param {object} value - A `link` value.
  * @param {Map<string, string>} links - Address slug → the book's anchor.
  * @param {(anchor: string) => string} labelFor - The anchor's Typst label.
+ * @param {string} [site] - The absolute address this book's pages are served at.
  * @returns {string} Typst markup.
  */
-export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string): string;
+export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string, site?: string): string;
 /**
  * Every box as one Typst panel each, breaking between sections.
  *

package/types/engine/journals.d.mts

@@ -4,7 +4,8 @@
  * a split. Content before the first H1 (if non-empty) becomes a leading
  * page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
- * `anchorSlug`).
+ * `anchorSlug`). The classes the heading declares come along as `classes`, so
+ * a surface that honours one has it without reading the suffix again.
  *
  * `leadName` names that leading page. A journal note's is "Introduction",
  * because it introduces the pages that follow. An item doc's is the item — a
@@ -15,12 +16,13 @@
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   markdown: string}>} Pages in document order.
+ *   classes: string[], markdown: string}>} Pages in document order.
  */
 export function splitPages(body: string, leadName?: string): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
+    classes: string[];
     markdown: string;
 }>;
 /**
@@ -97,10 +99,14 @@ export function journalPageId(entryId: string, page: {
  * @param {Array<object>} rawPages - From {@link splitPages}.
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {string} noteName - The note, for error messages.
+ * A page whose heading carries `.secret` is given to the GM alone, by the one
+ * ownership value Foundry reads as "nobody but a GM". Every other page states
+ * no ownership and inherits the journal's.
+ *
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
- *   text: {format: number, content: string}, _key: string}>} The page
- *   documents, in order.
+ *   text: {format: number, content: string}, _key: string,
+ *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
 export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, captions: any): Array<{
@@ -116,6 +122,9 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
         content: string;
     };
     _key: string;
+    ownership?: {
+        default: number;
+    };
 }>;
 /**
  * Assemble one JournalEntry document from a note's converted markdown.
@@ -133,7 +142,6 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  * @param {string} [params.leadName] - Name for the page before the first
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
- * @param {object} [params.flags] - Document flags.
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
@@ -150,13 +158,12 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infoboxes, notice, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, }: {
     id: string;
     name: string;
     markdown: string;
     leadName?: string | undefined;
     folder?: string | null | undefined;
-    flags?: object | undefined;
     stats?: object | undefined;
     infoboxes?: {
         id: string;

package/types/engine/markdown-expressions.d.mts

@@ -15,3 +15,26 @@ export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults,
     markdown: string;
     findings: any[];
 };
+/**
+ * An inline expression, as an author writes one.
+ *
+ * Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
+ *
+ * Exported because a renderer that meets one has met a body this pass never ran
+ * over, and has to be able to say so.
+ *
+ * @type {RegExp}
+ */
+export const EXPRESSION: RegExp;
+/**
+ * Each helper's parameters and what it does, keyed by name.
+ *
+ * The authoring document describes this surface, and a test holds the two
+ * together. A consumer reads it to list what an expression may call.
+ *
+ * @type {Readonly<Record<string, Readonly<{params: string, summary: string}>>>}
+ */
+export const EXPRESSION_HELPERS: Readonly<Record<string, Readonly<{
+    params: string;
+    summary: string;
+}>>>;

package/types/engine/note-frontmatter.d.mts

@@ -1,10 +1,7 @@
 /** Return authored keys from an opening YAML frontmatter map. */
 export function authoredNoteKeys(markdown: any): string[];
-/** The complete ordered top-level vocabulary for addressed content notes. */
-export const NOTE_TOP_LEVEL_KEYS: readonly string[];
-/** Membership test for the top-level vocabulary. */
-export const NOTE_TOP_LEVEL_KEY_SET: Set<string>;
 /** The name properties every note accepts, in display order. */
 export const NOTE_NAME_KEYS: readonly string[];
 /** Additional name components accepted by an individual character. */
 export const CHARACTER_NAME_KEYS: readonly string[];
+export { NOTE_TOP_LEVEL_FIELDS, NOTE_TOP_LEVEL_KEYS, NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";

package/types/engine/note-vocabulary.d.mts

@@ -42,8 +42,6 @@ export function exclusiveTagGroups(type: string, groups?: object): {
  * The spelling of the tag *itself* still is — a near miss is a near miss, and
  * the frontmatter lint is what reports it; nothing here guesses.
  *
- * Reads `tags` and the singular `tag` spelling.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} tag - The tag to look for, in its declared spelling.
  * @returns {boolean} Whether the note carries it.
@@ -135,6 +133,59 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * One top-level frontmatter key.
+ *
+ * Narrower than a {@link DataFieldSpec}: the top level is a fixed list rather
+ * than a per-type vocabulary, nothing there is keyed by pack or resolved as an
+ * Address, and the value's shape is checked by whatever owns the region the key
+ * opens — `name`, `tags` and each system block each have their own check.
+ *
+ * @typedef {object} TopLevelFieldSpec
+ * @property {string} name - The key, as a note writes it.
+ * @property {boolean} [system] - The key opens a game system's block, so it is
+ *   one of {@link module:engine/systems.SYSTEM_IDS} rather than a fixed key.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * **The top-level vocabulary**, in the order a formatted note writes it.
+ *
+ * The region describes the note as a published artefact: what it is called,
+ * what kind of thing it is about, how it is classified, and which of the other
+ * two regions it opens. Everything else a note states is a fact about the
+ * subject, which belongs under `data:`, or a fact about one system's document,
+ * which belongs inside that system's block.
+ *
+ * **Closed, like the other two regions.** A key this list does not name is a
+ * finding at its own line, because a region that passed one through would turn
+ * a misspelling into a value nothing reads — `title` beside `name`, or `pack`
+ * where `data.pack` was meant.
+ *
+ * **The system blocks are derived from the system registry**, so recognising a
+ * further system is a change to {@link module:engine/systems.SYSTEM_IDS} and to
+ * nothing else. They sort by name after the fixed keys: a block is the largest
+ * thing a note writes, every one of them belongs at the end, and a rule a
+ * reader can restate in one sentence is worth more than a hand-kept order.
+ *
+ * Five readers derive from this one list — the frontmatter lint's accepted set,
+ * the message it prints, the formatter's key order, the content-format check,
+ * and the author-facing reference — so none of them can fall behind the others.
+ *
+ * @type {readonly TopLevelFieldSpec[]}
+ */
+export const NOTE_TOP_LEVEL_FIELDS: readonly TopLevelFieldSpec[];
+/**
+ * The top-level keys, in formatted order.
+ *
+ * @type {readonly string[]}
+ */
+export const NOTE_TOP_LEVEL_KEYS: readonly string[];
+/**
+ * Membership test for the top-level vocabulary.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NOTE_TOP_LEVEL_KEY_SET: ReadonlySet<string>;
 /**
  * The `data:` keys **every** note type accepts, whatever it is.
  *
@@ -174,15 +225,17 @@ export const GM_TAG: "gm";
 /**
  * The tags that **classify** a note, grouped by what they classify.
  *
- * `tags:` lives at the open top level and most tags belong there: a theme, a
- * region, a working state is the author's own and this build has no opinion
- * about it. A classifying tag is different, because something queries it — a
+ * `tags:` holds an open vocabulary of *values*, and most tags belong there: a
+ * theme, a region, a working state is the author's own and this build has no
+ * opinion about it. A classifying tag is different, because something queries
+ * it — a
  * settlement tagged `village` appears in the list of villages and an untagged
  * one does not, so `vilage` does not merely look wrong, it removes the note from
  * an index while the index still renders a table that looks complete.
  *
  * **This list is not a closed set.** An unrecognised tag is legal, because the
- * region is open; what is reported is a **near miss** — a tag close enough to a
+ * values are the author's; what is reported is a **near miss** — a tag close
+ * enough to a
  * declared one to be a typo of it.
  *
  * **Each group names the types it applies to**, and that scope is what makes the
@@ -296,15 +349,29 @@ export type DataFieldSpec = {
      * value — which is the honest answer wherever the specification's stated
      * shape and the shape notes are authored in today disagree.
      */
-    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "shortcode" | "scalar-or-map" | undefined;
+    kind?: "string" | "number" | "boolean" | "map" | "address" | "list" | "shortcode" | "list-or-map" | "scalar-or-map" | undefined;
     /**
      * - Type of each list or pack-map value.
      */
     entryKind?: "address" | "shortcode" | undefined;
     /**
-     * - Type of each map key.
+     * - Type of each map key. On a
+     * `list-or-map` field it describes the map form alone, and `entryKind` the
+     * list form alone: reading both of one value would check a map's entries as
+     * if they were its keys.
      */
     keyKind?: "address" | "shortcode" | undefined;
+    /**
+     * - The map's entries are standings held in the
+     * body each is keyed by, so a row names the two together — see
+     * {@link module :engine/standings}.
+     */
+    standings?: boolean | undefined;
+    /**
+     * - The map names posts, each with a description,
+     * so each takes a row labelled and anchored by the post's own name.
+     */
+    roster?: boolean | undefined;
     /**
      * - An alternative `subType:<skill-subtype>` key.
      */
@@ -404,3 +471,26 @@ export type TypeVocabulary = {
         index?: object;
     }) => object[]) | undefined;
 };
+/**
+ * One top-level frontmatter key.
+ *
+ * Narrower than a {@link DataFieldSpec}: the top level is a fixed list rather
+ * than a per-type vocabulary, nothing there is keyed by pack or resolved as an
+ * Address, and the value's shape is checked by whatever owns the region the key
+ * opens — `name`, `tags` and each system block each have their own check.
+ */
+export type TopLevelFieldSpec = {
+    /**
+     * - The key, as a note writes it.
+     */
+    name: string;
+    /**
+     * - The key opens a game system's block, so it is
+     * one of {@link module :engine/systems.SYSTEM_IDS} rather than a fixed key.
+     */
+    system?: boolean | undefined;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/page-lists.d.mts

@@ -0,0 +1,126 @@
+/**
+ * Every `pagelist` fence in a markdown body, with the position each occupies.
+ *
+ * Positions are 0-based lines into the body as given, which is what a
+ * diagnostic about a directive needs and what the expander uses to splice
+ * results back in.
+ *
+ * **A malformed directive is still a directive.** It is returned carrying its
+ * problems rather than skipped, so the expander finds a prepared answer at its
+ * ordinal and reports the fault where the fence sits. That includes a fence
+ * nobody closed, which the author meant as a directive and which would
+ * otherwise swallow the rest of the note into a code block.
+ *
+ * @param {string} markdown - The note body, frontmatter already stripped.
+ * @returns {Array<{line: number, close: number, indent: string, tag: string,
+ *   type: string, sort: string, descriptions: boolean, allowEmpty: boolean,
+ *   problems: string[], block: string}>} One entry per fence, in document order.
+ */
+export function findPageListBlocks(markdown: string): Array<{
+    line: number;
+    close: number;
+    indent: string;
+    tag: string;
+    type: string;
+    sort: string;
+    descriptions: boolean;
+    allowEmpty: boolean;
+    problems: string[];
+    block: string;
+}>;
+/**
+ * The pages a directive selects, as index records.
+ *
+ * A **stub** is left out: an empty body publishes no page, which the index says
+ * by holding no address, so there is nothing for the list to link to. A
+ * documentation journal and an asset are not pages an author tagged, which
+ * {@link module:engine/index-records.isNoteRecord} already answers.
+ *
+ * @param {object[]} records - Content-index records.
+ * @param {{tag: string, type: string}} directive - From {@link findPageListBlocks}.
+ * @returns {object[]} The selected records, unordered.
+ */
+export function pagesForList(records: object[], { tag, type }: {
+    tag: string;
+    type: string;
+}): object[];
+/**
+ * Render one directive's answer as markdown.
+ *
+ * **The emitted link is the page's `address.slug`** — the `type-shortcode`
+ * form a wikilink resolves — which is exactly what a table's `_ref` cell
+ * writes. A short form names the package the link is written in, so it is
+ * unambiguous for a list of this package's own pages, and it resolves to the
+ * note's **page** on each surface: a compendium journal in Foundry, a URL on
+ * the web and in the book. An item note's page is its documentation journal,
+ * and the short form reaches it the way prose does.
+ *
+ * @param {object[]} records - Content-index records.
+ * @param {object} directive - From {@link findPageListBlocks}.
+ * @returns {{markdown: string, pages: number}} The list, and how many pages
+ *   are in it.
+ */
+export function renderPageList(records: object[], directive: object): {
+    markdown: string;
+    pages: number;
+};
+/**
+ * Answer every `pagelist` directive in a set of note bodies, ahead of expansion.
+ *
+ * **Why a separate pass.** The same reason the SQL tables have one:
+ * {@link module:engine/content-tables.expandContentTables} is synchronous and
+ * exported, and the corpus is enumerated once by whoever already holds it
+ * rather than derived again inside a renderer. A page list needs no database —
+ * it is a filter over the records — so preparing one costs a walk of what the
+ * caller already has.
+ *
+ * **Keyed by note, then by the directive's ordinal within it**, not by its
+ * line: the passes do not agree on what a body is, and trim it differently,
+ * but a directive's position in the sequence of fences is the same in each.
+ *
+ * A malformed directive is recorded rather than thrown, so one bad fence costs
+ * its own list and not the whole build's report.
+ *
+ * @param {object[]} records - Content-index records, already narrowed to the
+ *   audience the surface publishes to.
+ * @param {Array<{source: string, markdown: string}>} sources - The bodies to scan.
+ * @returns {Map<string, Array<{markdown?: string, pages?: number, empty?: string,
+ *   reason?: string, allowEmpty: boolean}>>} Note to results, in document order.
+ */
+export function preparePageLists(records: object[], sources: Array<{
+    source: string;
+    markdown: string;
+}>): Map<string, Array<{
+    markdown?: string;
+    pages?: number;
+    empty?: string;
+    reason?: string;
+    allowEmpty: boolean;
+}>>;
+/** The fence language that opens a page list. */
+export const PAGE_LIST_LANGUAGE: "pagelist";
+/**
+ * The orders a page list may come out in.
+ *
+ * Ordering is about output rather than about the pages, so it is an attribute
+ * rather than something read off a note. `name` is alphabetical, case and
+ * accents folded; `type` groups the note types and orders by name inside each.
+ *
+ * @type {readonly string[]}
+ */
+export const PAGE_LIST_SORTS: readonly string[];
+/**
+ * The attributes a page-list fence takes, with what each one is for.
+ *
+ * **This is the one list.** The fence is validated against it, the authoring
+ * document's table is generated from it, and the reference is checked against
+ * it — so an attribute added here is one both documents describe, and anything
+ * else an author writes is reported by name.
+ *
+ * @type {Readonly<Record<string, Readonly<{value: string, default: string, summary: string}>>>}
+ */
+export const PAGE_LIST_ATTRIBUTES: Readonly<Record<string, Readonly<{
+    value: string;
+    default: string;
+    summary: string;
+}>>>;

package/types/engine/pdf-render.d.mts

@@ -37,6 +37,24 @@ export function labelFor(anchor: string): string;
  * @returns {object} A markdown-it instance.
  */
 export function createParser(registry?: object): object;
+/**
+ * A markdown body with its HTML comments taken out.
+ *
+ * A comment is an author's aside to the next author — a `markdownlint` pragma, a
+ * note recording why a notice is quoted verbatim — and no surface shows one: the
+ * packs and the website emit it into HTML, where it is a comment still. Typst
+ * has nowhere to put it, so markdown-it hands the delimiters over as prose and
+ * the aside is typeset. It comes out here instead, and a comment inside a fence
+ * or a code span stays, because there it is an example of a comment.
+ *
+ * **The line count is preserved.** Every finding this module reports is located
+ * in the markdown it was handed, so a pass that removed a line would move every
+ * position after it.
+ *
+ * @param {string} markdown - The body, as authored.
+ * @returns {string} The same body, its comments replaced by their own newlines.
+ */
+export function stripHtmlComments(markdown: string): string;
 /**
  * Render markdown as Typst content.
  *
@@ -55,8 +73,26 @@ export function createParser(registry?: object): object;
  *   note's own `##` nests beneath the entry heading the book gave it.
  * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
  *   every `{#slug}` the body declares.
- *   capital. Set for an entry, which begins a page; not for front matter or a
- *   prose file, which carry headings of their own.
+ * @param {object[]} [opts.findings] - Collected here rather than thrown. Every
+ *   construct this pass cannot render is reported into it — see
+ *   {@link reportUnrenderable} — and a caller that passes none renders the same
+ *   Typst and is told nothing.
+ * @param {string} [opts.file] - The file the markdown came from, named in every
+ *   finding.
+ * @param {number} [opts.bodyLine] - The 1-based file line the body starts on, so
+ *   a finding's line is the file's rather than the body's.
+ * @param {number} [opts.bodyColumn] - The 1-based column the body starts at.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
+ *   table expansion, mapping each line handed in back to the line an author
+ *   wrote.
+ * @param {boolean} [opts.prepared] - Whether this body has been through the
+ *   passes that resolve a wikilink, an embed and an inline expression. A note's
+ *   has; a front-matter file's and a prose file's have not, and markup of theirs
+ *   left in one is reported rather than typeset in silence.
+ * @param {string} [opts.url] - The absolute address this book's pages are served
+ *   at. Every link the book sets as a URL is resolved against it, because a
+ *   reader holding a PDF has no page to resolve a path against — see
+ *   {@link renderLink}.
  * @returns {string} Typst markup.
  */
 export function markdownToTypst(markdown: string, opts?: {
@@ -67,7 +103,41 @@ export function markdownToTypst(markdown: string, opts?: {
     images?: Map<string, string> | undefined;
     headingOffset?: number | undefined;
     anchorPrefix?: string | undefined;
+    findings?: object[] | undefined;
+    file?: string | undefined;
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    lineMap?: {
+        line: number;
+        generated: boolean;
+    }[] | undefined;
+    prepared?: boolean | undefined;
+    url?: string | undefined;
 }): string;
+/**
+ * A page address as a reader of the book can follow it.
+ *
+ * **Every link the book sets as a URL is absolute.** A page's address is written
+ * from the root of the site that serves it — `/sohl/skill-guil/` — because on the
+ * website that is the shortest form that is right wherever the page is read
+ * from. A PDF is read from nowhere: a viewer handed a path has no document to
+ * resolve it against, so it either does nothing or looks for a file on the
+ * reader's own disk, and a book of a thousand pages carries a thousand links
+ * that do neither.
+ *
+ * So a root-relative address is resolved against the site's own, which is the
+ * one absolute address a build already holds. A **dependency's** page keeps its
+ * own package prefix, from the registry in
+ * {@link module:engine/content-address.PACKAGE_BASE}, so it resolves to the host
+ * serving that package — and where the registry names a host of its own the
+ * address is already absolute and is left exactly as it is.
+ *
+ * @param {string} url - The address, as the link pass resolved it.
+ * @param {string} [site] - The absolute address this book's pages are served at.
+ * @returns {string} An absolute URL, or the address unchanged when there is no
+ *   site to resolve it against or it is already absolute.
+ */
+export function absolutePageUrl(url: string, site?: string): string;
 /**
  * The Typst definitions the book's page furniture is drawn with.
  *

package/types/engine/rank-ladder.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Check one affiliation's `data.governance.ranks` against the rung contract.
+ *
+ * Each problem is its own finding, so a rung missing all three of its required
+ * keys reports three rather than the first: a reader fixing a ladder wants the
+ * whole of it in one pass.
+ *
+ * **A finding is located by the node it is about**, through the frontmatter's
+ * own YAML tree — a present-but-wrong value points at that value, and an absent
+ * key points at the rung that should have carried it, since a key that was
+ * never written has no position of its own. Where even the rung cannot be
+ * located the position is dropped rather than guessed, and the finding names
+ * the file alone.
+ *
+ * @param {object} note - The note being checked.
+ * @param {string} note.file - Its path, as a diagnostic spells it.
+ * @param {string} [note.raw] - Its source, for the position.
+ * @param {object} [note.fm] - Its parsed frontmatter.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} The findings, in authored order.
+ */
+export function checkRankLadder(note: {
+    file: string;
+    raw?: string | undefined;
+    fm?: object | undefined;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: string;
+    message: string;
+}>;

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

@@ -256,12 +256,10 @@ export function legacyKeyMessage(block: string, field: {
  * What a note writing a field at the **top-level key `data:` gathered it off**
  * is told.
  *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position. The
- * sweep
- * did not invent the facts `data:` holds — it collected them out of the note's
- * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
- * of `data.portrait`, and both are read for the same reason both in-block
- * spellings are: a package moves its corpus when it is ready, not on a flag day.
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position.
+ * `portrait:` beside `img:` is the bare spelling of `data.portrait`, and both
+ * are read for the same reason both in-block spellings are: a package moves its
+ * corpus when it is ready, not on a flag day.
  *
  * It says nothing about which value is emitted, because that is not what an
  * author needs from it. The value is the same either way; what the finding

package/types/engine/site-build.d.mts

@@ -249,7 +249,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     artIndex: any;
 }): {
     page: any;
-    body: any;
+    body: string;
     data: object;
     resolved: any[];
     tableErrors: object[];
@@ -266,6 +266,18 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
         column: number;
         message: string;
     }[];
+    headingErrors: {
+        line: number;
+        column: number;
+        message: string;
+        file: any;
+    }[];
+    footnoteErrors: {
+        file: any;
+        line: number;
+        column: number;
+        message: string;
+    }[];
     wikiErrors: any[];
     imageErrors: any[];
 };

package/types/engine/site-config.d.mts

@@ -178,12 +178,21 @@ export const DISABLE_KINDS: readonly string[];
  * `<span>` marking an unresolved link — and Goldmark drops raw HTML unless
  * told otherwise. A theme cannot supply this: Hugo does not merge a theme's
  * `markup` block.
+ *
+ * `extensions.taskList` is off because the format has no checkbox: Goldmark
+ * enables it by default, which is the only reason a list item opened with
+ * `[ ]` renders a `<input type="checkbox">` here and the same two characters as
+ * plain text in the pack and the book. Off, a list item's text begins right
+ * after its marker on every surface.
  */
 export const MARKUP: Readonly<{
     goldmark: Readonly<{
         renderer: Readonly<{
             unsafe: true;
         }>;
+        extensions: Readonly<{
+            taskList: false;
+        }>;
     }>;
 }>;
 /** Where the navigation is published. */