@heroiclands/package-build 22.21.0 → 22.23.0

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
@@ -418,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/pathnames.d.mts

@@ -82,6 +82,32 @@ export function packageAddresses(config: object): Map<string, {
  *   resolves on one surface and nowhere else.
  */
 export function resolvePathname(raw: string | null | undefined, config: object): PathnameForms | null;
+/**
+ * The pathname one authored image address keys an asset's role and pixel
+ * size under — `<package>/assets/<suffix>`, the same key
+ * {@link module:engine/art-fields.assetImageInfoByPathname} builds from the
+ * asset record itself.
+ *
+ * **Why this exists apart from `resolvePathname`'s own forms.** An embed
+ * rewrites to that exact pathname — see
+ * {@link module:engine/content-embeds.resolveEmbeds} — but an author's own
+ * body image is free to write the bare, own-package form instead
+ * (`images/m.webp`), which names the identical file without naming the
+ * package. The two forms have to key the same lookup, and `resolvePathname`
+ * already answers which package a bare form belongs to; this just restates
+ * that answer in the one shape a renderer looks a picture's role up by.
+ *
+ * **Never throws.** A lookup is a best-effort read, not a validation — the
+ * pathname lint is what refuses a Foundry-spelled address — so a value
+ * {@link resolvePathname} refuses outright answers `null` here as well, the
+ * same as a blank or an external one.
+ *
+ * @param {string} src - The address, as authored or as an embed resolved it.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string|null} The pathname, or `null` for an address naming no
+ *   asset record to look up.
+ */
+export function assetPathnameKey(src: string, config: object): string | null;
 /**
  * The directory a package ships its files in, and the segment that marks a
  * pathname's first segment as a package name.

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

@@ -13,17 +13,34 @@
  * makes the source a consumer can compile by hand with no flags, and what keeps
  * a build from touching a path outside its own output.
  *
- * Only a file **this** package ships can be staged. A pathname naming another
- * package's file, or a URL, names something no build here can open — a build
- * reaches no network — and the caller reports it as a picture the book will not
- * carry.
+ * A file **this** package ships stages directly. A pathname naming another
+ * package's file stages instead from a declared replacement's cached archive,
+ * when `opts.resolveReplacement` — the pure function
+ * {@link module:engine/asset-replacement.resolveAssetReplacement} —
+ * answers it; `opts.foreignIndex` is the merged index that answer is read
+ * against. A pathname naming a package no replacement carries it for, or a
+ * URL, names something no build here can open — a build reaches no network —
+ * and the caller reports it as a picture the book will not carry.
  *
  * @param {string} src - The pathname, as authored.
  * @param {object} config - The resolved configuration.
+ * @param {object} [opts]
+ * @param {Map<string, object>} [opts.foreignIndex] - Every fetched
+ *   dependency's own records, keyed by canonical address — the index a
+ *   replacement's record is read out of.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, or an
+ *   equivalent a caller injects for a test. Omitted, a foreign pathname this
+ *   package does not own stays declined exactly as it always has.
  * @returns {{from: string, to: string}|null} The file, and where under the
  *   output directory it is staged.
+ * @throws {Error} When a declared replacement answers the address but its
+ *   archive was never fetched.
  */
-export function stagedImagePath(src: string, config: object): {
+export function stagedImagePath(src: string, config: object, opts?: {
+    foreignIndex?: Map<string, object> | undefined;
+    resolveReplacement?: Function | undefined;
+}): {
     from: string;
     to: string;
 } | null;
@@ -66,13 +83,18 @@ export function pdfFileName(artifact: string, version: string): string;
  * @param {string} [opts.version] - Stamped on the title page and the file name.
  * @param {boolean} [opts.compile] - Whether to run Typst. False leaves the
  *   `.typ` source, which is what the unit tests read.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, for tests.
+ *   Loaded from that module otherwise, and only when a relationship declares
+ *   `assetReplacement: true` — a build with none never imports it.
  * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
  */
-export function buildPdf({ config, out, version, compile }?: {
+export function buildPdf({ config, out, version, compile, resolveReplacement, }?: {
     config?: object | undefined;
     out?: string | undefined;
     version?: string | undefined;
     compile?: boolean | undefined;
+    resolveReplacement?: Function | undefined;
 }): Promise<object>;
 /**
  * The command line the compile runs, as data.

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

@@ -1,3 +1,33 @@
+/**
+ * The width the book draws one picture at, in inches, when nothing authored
+ * narrows it to a named `size=`.
+ *
+ * > drawn width = min(the role's slot, natural pixels ÷ the print floor)
+ *
+ * **Every size here is a maximum, never a target**: a picture is never drawn
+ * larger than it was made. The print floor is {@link PDF_PAGE.dpi}, the same
+ * constant the page geometry above is set against, so a role's slot and the
+ * page it is drawn on cannot disagree about what a pixel is worth.
+ *
+ * An icon-type address takes the nominal icon width whatever role it might
+ * otherwise carry — `role` never reaches one, since the asset record refuses
+ * it there. A vector carries no pixel count, so nothing narrows its role's
+ * slot. A picture declaring no role answers `undefined`: the medium's
+ * ordinary size, decided elsewhere by a named `size=` or by its own natural
+ * pixels within whatever it is set in.
+ *
+ * @param {object} [asset] - What {@link module:engine/art-fields.assetImageInfoByPathname}
+ *   records for the picture's address.
+ * @param {string} [asset.type] - The asset's type — `icon` or `image`.
+ * @param {string} [asset.role] - The picture's declared role.
+ * @param {number|""} [asset.width] - The file's own pixel width; blank for a vector.
+ * @returns {number|undefined} The drawn width, in inches.
+ */
+export function bookImageWidthIn({ type, role, width }?: {
+    type?: string | undefined;
+    role?: string | undefined;
+    width?: number | "" | undefined;
+}): number | undefined;
 /**
  * Optimize staged raster images without changing their authored files.
  *
@@ -36,3 +66,25 @@ export const pdfTextWidth: number;
 /** Usable height of a portrait page in inches. */
 export const pdfTextHeight: number;
 export function pdfColumnWidth(columns?: number): number;
+/**
+ * The fraction of the page's one-column measure a picture's role may fill at
+ * most — one table, read by {@link bookImageWidthIn}, so a policy change here
+ * is the one line it costs rather than an edit to every note drawing a role.
+ *
+ * A `portrait` or an `emblem` names a subject or a mark, which sits beside
+ * prose rather than replacing a page of it; a `banner`, a `plate` and a `map`
+ * are each meant to be looked at in full. The measure is the page's own text
+ * width, {@link pdfTextWidth}, so a role's slot does not shrink when a page
+ * happens to be set in two columns — it is what the picture is *for* that
+ * sets the slot, not the layout it lands in.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const BOOK_ROLE_SLOTS: Readonly<Record<string, number>>;
+/**
+ * The book's nominal width for an icon-type picture, in inches, whatever its
+ * file holds — almost every icon is an SVG with no pixel count to measure.
+ *
+ * @type {number}
+ */
+export const BOOK_ICON_WIDTH_IN: number;

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.
  *
@@ -51,12 +69,36 @@ export function createParser(registry?: object): object;
  *   the staged file's path, relative to the `.typ`. An address this does not
  *   carry has no file the compiler can open, so the figure prints its caption
  *   alone — see {@link renderImage}.
+ * @param {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   [opts.assets] - An image's address as authored → what
+ *   {@link module:engine/art-fields.assetImageInfoByPathname} records for it,
+ *   which is what sizes a picture carrying no named `size=` — see
+ *   {@link module:engine/pdf-images.bookImageWidthIn}. An address missing from
+ *   this map draws at the medium's ordinary size, the same as today.
  * @param {number} [opts.headingOffset] - Added to every heading level, so a
  *   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?: {
@@ -65,9 +107,49 @@ export function markdownToTypst(markdown: string, opts?: {
     links?: Map<string, string> | undefined;
     glyphs?: Map<string, string> | undefined;
     images?: Map<string, string> | undefined;
+    assets?: Map<string, {
+        type: string;
+        role?: string;
+        width: number | "";
+        height: number | "";
+    }> | 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

@@ -237,7 +237,7 @@ export function pageDestination(page: {
     bundle?: boolean | undefined;
 }): string;
 /** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, }: {
+export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, }: {
     index: any;
     foreign: any;
     universe: any;
@@ -247,9 +247,10 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     sqlTables: any;
     config: any;
     artIndex: any;
+    figuresByAddress?: Map<any, any> | undefined;
 }): {
     page: any;
-    body: any;
+    body: string;
     data: object;
     resolved: any[];
     tableErrors: object[];
@@ -266,8 +267,27 @@ 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[];
+    embedErrors: {
+        file: string;
+        line: number;
+        column: number | undefined;
+        severity: "error";
+        message: string;
+    }[];
 };
 /**
  * Renders and writes every page.
@@ -304,7 +324,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
  *   it by wikilink, and its own markdown links name content pages. `maps` is
  *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   related: Map<string, import("./related-pages.mjs").Related>,
  *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
@@ -317,6 +337,7 @@ export function renderPages(pages: object[], options: object): {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    embedErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
     maps: number;
 };
@@ -349,7 +370,8 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
+ *   mapFindings: object[],
  *   manifests: object|null}} `mapFindings` is what drawing the maps found —
  *   warnings, never a reason to fail the build.
  */
@@ -362,6 +384,7 @@ export function buildSite({ config, sqlTables }?: {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    embedErrors: object[];
     mapFindings: object[];
     manifests: object | null;
 };

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