@heroiclands/package-build 23.0.0 → 23.1.0

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

@@ -104,10 +104,8 @@ export class BasePackCompiler {
      * here is what lets the lint tell an inert key from a live one.
      *
      * A pass that emits art **anywhere** in its document declares it, not only
-     * one that writes a top-level `img`: the scenes pass puts the path on the
-     * scene's background rather than on a property called `img`, and the value
-     * is no less live for it. The question this answers is whether the authored
-     * path reaches the output at all.
+     * one that writes a top-level `img`. The question this answers is whether
+     * the authored path reaches the output at all.
      *
      * @type {readonly string[]}
      */
@@ -392,6 +390,17 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm: object, body: string): string;
+    /**
+     * Every note's events by Address, for an inline reference to an event's
+     * field — built once per compile from the corpus's records and the fetched
+     * dependency indexes, the same inputs the website and the book build it
+     * from, so a reference prints the same text on all three.
+     *
+     * @returns {{note: (written: string) => object|undefined}} The lookup.
+     */
+    eventNotes(): {
+        note: (written: string) => object | undefined;
+    };
     /**
      * The Foundry path one authored art address names, or `null`.
      *

package/types/engine/calendar-notes.d.mts

@@ -163,6 +163,13 @@ export const INVARIANT_SUBTYPES: readonly string[];
 /** Calendaria's display locations that a calendar note can format. */
 export const CALENDAR_DATE_FORMAT_KEYS: readonly string[];
 export { CALENDAR_FORMAT_TOKENS };
+/**
+ * The keys of one entry in each of a calendar's lists, as inner-key
+ * declarations.
+ *
+ * @type {Readonly<Record<string, readonly import("./data-keys.mjs").InnerKeySpec[]>>}
+ */
+export const CALENDAR_ENTRY_FIELDS: Readonly<Record<string, readonly import("./data-keys.mjs").InnerKeySpec[]>>;
 /**
  * The `data:` keys a calendar note may write — the closed list, in authored
  * order.

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

@@ -53,10 +53,21 @@ export const CONTENT_FORMAT_PATH: string;
  *   property — what a note actually writes. `appearance.eye_color` is authored
  *   as `appearance`, so that is the key recorded.
  * @property {Set<string>} dataPaths - The declared paths, whole.
+ * @property {Map<string, DataRow>} [dataRows] - Each documented path's row, as
+ *   a reference document states it. Read from a Markdown specification only.
  * @property {string[]} subTypes - The declared `subType` values,
  *   in document order — empty when it states none, which is the ordinary case
  *   for a type that has no `subType` at all.
  */
+/**
+ * One row of a `data` property table, as a reference document states it.
+ *
+ * @typedef {object} DataRow
+ * @property {string} shape - The second cell, the value's shape in words.
+ * @property {string} text - The whole row as written, for a reader looking for
+ *   a marker anywhere in it.
+ * @property {number} line - 1-based line of the row.
+ */
 /**
  * One `system.*` target the specification names for one note type.
  *
@@ -93,6 +104,12 @@ export const CONTENT_FORMAT_PATH: string;
  * @property {MappingClaim[]} claims - Every `system.*` target, in document order.
  * @property {Map<string, VocabularySpec>} vocabularies - Key → the values it
  *   admits, for every closed vocabulary the document states as a table.
+ * @property {Map<string, DataRow>} [sharedDataRows] - The rows of the shared
+ *   `data` property table — the keys every type accepts — by path. Read from a
+ *   Markdown specification only.
+ * @property {Map<string, DataRow>} [eventRows] - The rows of the event key
+ *   tables, by path from one event entry (`names[].by`). Read from a Markdown
+ *   specification only.
  */
 /**
  * What a shared row's `noteType` reads, in place of a type name.
@@ -127,6 +144,11 @@ export type TypeSpec = {
      * - The declared paths, whole.
      */
     dataPaths: Set<string>;
+    /**
+     * - Each documented path's row, as
+     * a reference document states it. Read from a Markdown specification only.
+     */
+    dataRows?: Map<string, DataRow> | undefined;
     /**
      * - The declared `subType` values,
      * in document order — empty when it states none, which is the ordinary case
@@ -134,6 +156,24 @@ export type TypeSpec = {
      */
     subTypes: string[];
 };
+/**
+ * One row of a `data` property table, as a reference document states it.
+ */
+export type DataRow = {
+    /**
+     * - The second cell, the value's shape in words.
+     */
+    shape: string;
+    /**
+     * - The whole row as written, for a reader looking for
+     * a marker anywhere in it.
+     */
+    text: string;
+    /**
+     * - 1-based line of the row.
+     */
+    line: number;
+};
 /**
  * One `system.*` target the specification names for one note type.
  */
@@ -212,4 +252,16 @@ export type ContentFormat = {
      * admits, for every closed vocabulary the document states as a table.
      */
     vocabularies: Map<string, VocabularySpec>;
+    /**
+     * - The rows of the shared
+     * `data` property table — the keys every type accepts — by path. Read from a
+     * Markdown specification only.
+     */
+    sharedDataRows?: Map<string, DataRow> | undefined;
+    /**
+     * - The rows of the event key
+     * tables, by path from one event entry (`names[].by`). Read from a Markdown
+     * specification only.
+     */
+    eventRows?: Map<string, DataRow> | undefined;
 };

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

@@ -176,11 +176,14 @@ export function imageSourcesIn(body: string): string[];
  *   without any other pass noticing — see the Foundry address below. Omitted,
  *   the config-free checks run alone, which is what lets a caller with no
  *   repository to resolve still read a body.
+ * @param {boolean} [opts.generated] - Whether `body` is a note's generated
+ *   sections, which name the build's own drawings under `generated/`; an
+ *   author's text may not.
  * @returns {Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body: string, file: string, { bodyLine, bodyColumn, lineMap, config }?: {
+export function checkImages(body: string, file: string, { bodyLine, bodyColumn, lineMap, config, generated }?: {
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;
     lineMap?: {
@@ -188,6 +191,7 @@ export function checkImages(body: string, file: string, { bodyLine, bodyColumn,
         generated: boolean;
     }[] | undefined;
     config?: object | undefined;
+    generated?: boolean | undefined;
 }): Array<{
     file: string;
     line: number;

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

@@ -10,7 +10,14 @@
  * @param {string} markdown - The authored body.
  * @param {{source?: string, sqlTables?: object[], pageLists?: object[]}} [context] -
  *   Prepared results.
- * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
+ * A note's generated sections — see {@link module:engine/generated-sections} —
+ * are appended to the body first, from the `generated` text the preparation
+ * set on its results, and expanded with it.
+ *
+ * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[],
+ *   generatedFrom?: number}} `generatedFrom` is the 0-based line of the
+ *   expanded body the generated sections start on, where there are any — what
+ *   a surface reads to tell them from the author's text.
  */
 export function expandContentTables(markdown: string, { source, sqlTables, pageLists }?: {
     source?: string;
@@ -21,4 +28,5 @@ export function expandContentTables(markdown: string, { source, sqlTables, pageL
     errors: object[];
     warnings: object[];
     lineMap: object[];
+    generatedFrom?: number;
 };

package/types/engine/data-keys.d.mts

@@ -0,0 +1,145 @@
+/**
+ * One key inside a field's value.
+ *
+ * @typedef {object} InnerKeySpec
+ * @property {string} name - The key as an author writes it.
+ * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
+ *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
+ *   `list-or-map` or `string-or-list` — see {@link fitsKind}. Absent, the check
+ *   makes no claim about the value.
+ * @property {readonly string[]} [allowed] - The closed set a present value is
+ *   one of, where the key takes a fixed word.
+ * @property {boolean} [verbatim] - The value is a symbol, such as a unit, and
+ *   every surface shows it exactly as written, never recased.
+ * @property {string} shape - The shape in words, for a finding and the reference.
+ * @property {boolean} [required] - The key must be stated, with a value.
+ * @property {boolean} [nullable] - An explicit `null` states the key, for a
+ *   required key whose null has a meaning of its own.
+ * @property {string} [label] - The infobox row label, where humanising the key
+ *   reads wrongly.
+ * @property {string} describe - One line, for the author-facing reference.
+ * @property {readonly InnerKeySpec[]} [fields] - Its own keys, where it is a map.
+ * @property {object} [entries] - One entry, where it is a list of maps.
+ * @property {object} [values] - One value, where it is a map keyed by data.
+ */
+/** Whether a value is a plain map rather than a list, an Address or a scalar. */
+export function isPlainMap(value: any): boolean;
+/**
+ * Whether a present value has a declared kind's shape.
+ *
+ * Shape alone: whether an Address resolves, or a word is in a closed set, is the
+ * field's own check's question. Lenient where YAML is ambiguous — `"12"` is a
+ * number, an emptied map arrives as `[]`, and a `date` may be the bare number
+ * YAML reads `720.1` as — and strict where it is not: a `string` is text, so a
+ * title or a description written as `5` is a finding rather than a value
+ * nothing reads as text. An `address` is one value or a parsed Address; what it
+ * names is the reference check's.
+ *
+ * @param {unknown} value - The authored value, not `undefined` or `null`.
+ * @param {string|undefined} kind - The declared kind.
+ * @returns {boolean} Whether it fits.
+ */
+export function fitsKind(value: unknown, kind: string | undefined): boolean;
+/**
+ * The entries of a map value, whatever form it reached the lint in.
+ *
+ * A map keyed by Address arrives as an {@link AddressEntries} once the note
+ * boundary has typed its keys; `sourceKey` is the text the file holds, so a
+ * finding locates on what the author wrote.
+ *
+ * @param {unknown} value - A map value.
+ * @returns {Array<[string, unknown]>} Its authored keys and values.
+ */
+export function mapEntriesOf(value: unknown): Array<[string, unknown]>;
+/**
+ * A field declaration as the tree its dotted names describe.
+ *
+ * `appearance.eye_color` and `appearance.hair_color` are two keys of one
+ * container, `appearance`, which is itself a map closed to them. Grouping them
+ * here is what lets one walk close the container and every field inside it.
+ *
+ * @param {readonly object[]} fields - The type's `data:` declaration.
+ * @returns {object[]} One spec per top-level key, a dotted group as a `map`
+ *   whose `fields` are its members, with `grouped: true`.
+ */
+export function topLevelSpecs(fields: readonly object[]): object[];
+/**
+ * A path as a reader writes it: `data.routes[0].terrain`.
+ *
+ * @param {ReadonlyArray<string|number>} path - The path from the top of the frontmatter.
+ * @returns {string} The label.
+ */
+export function pathLabel(path: ReadonlyArray<string | number>): string;
+/**
+ * Check every declared field's value against its stated inner keys.
+ *
+ * Run by the frontmatter lint after the container check has refused undeclared
+ * top-level keys and checked each top-level field's own kind, so neither is
+ * repeated here.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {readonly object[]} fields - The type's `data:` declaration, shared
+ *   fields included.
+ * @returns {object[]} Findings, `file:line:column` located on the key at fault.
+ */
+export function checkDataKeys(note: object, fields: readonly object[]): object[];
+/**
+ * One key inside a field's value.
+ */
+export type InnerKeySpec = {
+    /**
+     * - The key as an author writes it.
+     */
+    name: string;
+    /**
+     * - Its value's shape: `string`, `date`, `number`,
+     * `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
+     * `list-or-map` or `string-or-list` — see {@link fitsKind}. Absent, the check
+     * makes no claim about the value.
+     */
+    kind?: string | undefined;
+    /**
+     * - The closed set a present value is
+     * one of, where the key takes a fixed word.
+     */
+    allowed?: readonly string[] | undefined;
+    /**
+     * - The value is a symbol, such as a unit, and
+     * every surface shows it exactly as written, never recased.
+     */
+    verbatim?: boolean | undefined;
+    /**
+     * - The shape in words, for a finding and the reference.
+     */
+    shape: string;
+    /**
+     * - The key must be stated, with a value.
+     */
+    required?: boolean | undefined;
+    /**
+     * - An explicit `null` states the key, for a
+     * required key whose null has a meaning of its own.
+     */
+    nullable?: boolean | undefined;
+    /**
+     * - The infobox row label, where humanising the key
+     * reads wrongly.
+     */
+    label?: string | undefined;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+    /**
+     * - Its own keys, where it is a map.
+     */
+    fields?: readonly InnerKeySpec[] | undefined;
+    /**
+     * - One entry, where it is a list of maps.
+     */
+    entries?: object | undefined;
+    /**
+     * - One value, where it is a map keyed by data.
+     */
+    values?: object | undefined;
+};

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

@@ -0,0 +1,73 @@
+/**
+ * The places of this package that are given the map from them: each one that
+ * states, or is named in, a border or a route, and publishes a page.
+ *
+ * @param {object[]} records - The content-index records.
+ * @param {object} [opts]
+ * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes, whose
+ *   places a local place's border or route may name.
+ * @param {object} [opts.config] - The resolved configuration. `site.maps:
+ *   false` gives no place a map.
+ * @returns {string[]} The places' shortcodes, sorted.
+ */
+export function placesWithMaps(records: object[], { foreignIndex, config }?: {
+    foreignIndex?: Map<string, object> | undefined;
+    config?: object | undefined;
+}): string[];
+/**
+ * Draw the map from each place given one, for a surface that serves the
+ * drawing as a file: the Foundry compile and the book. Each drawing is the
+ * standalone SVG `package-build map --from` writes, with no links, since
+ * neither surface follows a link inside a picture.
+ *
+ * @param {object[]} records - The content-index records.
+ * @param {object} opts
+ * @param {string} opts.outDir - Where to draw. Emptied first, so a place that
+ *   lost its relations keeps no drawing from an earlier run.
+ * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes.
+ * @param {object} [opts.config] - The resolved configuration.
+ * @param {Iterable<string>} [opts.only] - The places to draw, of those given a
+ *   map; absent, every one.
+ * @returns {{maps: Map<string, string>, findings: object[]}} Each drawing's
+ *   file, keyed by the file name a **From here** section names, and what
+ *   drawing found.
+ */
+export function drawMapsFrom(records: object[], { outDir, foreignIndex, config, only }?: {
+    outDir: string;
+    foreignIndex?: Map<string, object> | undefined;
+    config?: object | undefined;
+    only?: Iterable<string> | undefined;
+}): {
+    maps: Map<string, string>;
+    findings: object[];
+};
+/**
+ * The derived sections each note is given.
+ *
+ * @param {object[]} records - The content-index records, of the audience the
+ *   surface publishes to.
+ * @param {object} opts
+ * @param {(record: object) => string} opts.fileOf - A record's note file, as
+ *   prepared results are keyed.
+ * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes.
+ * @param {object} [opts.config] - The resolved configuration.
+ * @param {string} [opts.only] - One note file to give sections to; absent,
+ *   every note.
+ * @returns {Map<string, Map<string, string>>} Note file to its sections, each
+ *   keyed by its slug, for every note given at least one.
+ */
+export function derivedSections(records: object[], { fileOf, foreignIndex, config, only }: {
+    fileOf: (record: object) => string;
+    foreignIndex?: Map<string, object> | undefined;
+    config?: object | undefined;
+    only?: string | undefined;
+}): Map<string, Map<string, string>>;
+/**
+ * The heading each kind of place is grouped under, in the order the place
+ * vocabulary declares its kinds. A kind the vocabulary does not declare is
+ * grouped after these by its own name, and a place stating no kind last, under
+ * **Other**.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const PLACE_KIND_LABELS: Readonly<Record<string, string>>;

package/types/engine/diagnostics.d.mts

@@ -223,6 +223,21 @@ export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string |
  * @returns {Array<string|number>} Its segments, sequence indices as numbers.
  */
 export function yamlKeyPath(field: string): Array<string | number>;
+/**
+ * The scalar a note's frontmatter states at a path, **as the author wrote it**.
+ *
+ * A check reads a note whose Addresses are already resolved to their canonical
+ * form, so a finding quoting the value it holds would quote text the file does
+ * not contain. This reads the file instead, through the same parse
+ * {@link positionOfYamlPath} uses.
+ *
+ * @param {string} raw - The note's full contents, frontmatter included.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node, from the
+ *   top of the frontmatter.
+ * @returns {string|number|boolean|undefined} The scalar, or `undefined` where
+ *   the path names no scalar.
+ */
+export function frontmatterValueAt(raw: string, keyPath: ReadonlyArray<string | number>): string | number | boolean | undefined;
 /**
  * Where a key sits **inside a note's frontmatter fence**, addressed by path.
  *

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

@@ -0,0 +1,99 @@
+/**
+ * @typedef {object} EventView
+ * @property {string} [id] - The event's `id`.
+ * @property {object} entry - The event entry as the index holds it.
+ * @property {object|null} when - Its resolved `when`, or `null`.
+ * @property {object|null} until - Its resolved `until`, or `null`.
+ */
+/**
+ * @typedef {object} EventNote
+ * @property {string} target - The note's canonical Address.
+ * @property {EventView[]} events - Its events, in entry order.
+ * @property {Array<{slug: string, kind?: string}>} anchors - Every anchor it declares.
+ */
+/**
+ * Every note's events, by Address, from this package's index records and the
+ * fetched indexes of its dependencies.
+ *
+ * @param {Iterable<Record<string, any>>} records - This package's content-index records.
+ * @param {object} [options]
+ * @param {string} [options.contentPackage] - The package a written Address
+ *   without one defaults to.
+ * @param {Map<string, object>} [options.foreignIndex] - The merged fetched
+ *   indexes, as `loadForeignIndexes` returns them.
+ * @param {object} [options.dates] - The reckoning context, for a record that
+ *   carries no resolved dates.
+ * @returns {{note: (written: string) => EventNote|undefined,
+ *   own: (fm: object) => EventNote|undefined}} The lookup: `note` from a
+ *   written Address, anchor already removed, to the note it names, and `own`
+ *   from a note of this package's frontmatter to that note.
+ */
+export function eventNoteIndex(records: Iterable<Record<string, any>>, { contentPackage, foreignIndex, dates }?: {
+    contentPackage?: string | undefined;
+    foreignIndex?: Map<string, object> | undefined;
+    dates?: object | undefined;
+}): {
+    note: (written: string) => EventNote | undefined;
+    own: (fm: object) => EventNote | undefined;
+};
+/**
+ * A date as a note prints one: in the era its own marker or qualifier names,
+ * where the reckoning knows that era, else as written — `~` kept either way.
+ *
+ * @param {unknown} written - The date as the event writes it.
+ * @param {object|null} date - The resolved date.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {string} The printed date.
+ */
+export function printEventDate(written: unknown, date: object | null, dates?: object): string;
+/**
+ * One field of one event, as the text a reference prints, or why it cannot.
+ *
+ * @param {EventView} event - The event.
+ * @param {string} field - One of {@link EVENT_REFERENCE_FIELDS}.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {{text: string}|{missing: true}} The text, or that the event states
+ *   no such field.
+ */
+export function eventFieldText(event: EventView, field: string, dates?: object): {
+    text: string;
+} | {
+    missing: true;
+};
+/** The fields of an event an inline reference may print, in the order a message names them. */
+export const EVENT_REFERENCE_FIELDS: readonly string[];
+export type EventView = {
+    /**
+     * - The event's `id`.
+     */
+    id?: string | undefined;
+    /**
+     * - The event entry as the index holds it.
+     */
+    entry: object;
+    /**
+     * - Its resolved `when`, or `null`.
+     */
+    when: object | null;
+    /**
+     * - Its resolved `until`, or `null`.
+     */
+    until: object | null;
+};
+export type EventNote = {
+    /**
+     * - The note's canonical Address.
+     */
+    target: string;
+    /**
+     * - Its events, in entry order.
+     */
+    events: EventView[];
+    /**
+     * - Every anchor it declares.
+     */
+    anchors: Array<{
+        slug: string;
+        kind?: string;
+    }>;
+};

package/types/engine/event-rows.d.mts

@@ -0,0 +1,12 @@
+/**
+ * The `events` rows of a set of index records.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string, already narrowed to the audience being published to.
+ * @returns {object[]} One row per event entry, in record then entry order.
+ */
+export function eventRows(records: Iterable<Record<string, any>>): object[];
+/** The sort keys a row carries, after the event's own keys. */
+export const EVENT_SORT_COLUMNS: readonly string[];
+/** Every column of the `events` relation, in order. */
+export const EVENT_COLUMNS: any;

package/types/engine/event-views.d.mts

@@ -0,0 +1,67 @@
+/**
+ * The views each note is given, by section.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase},
+ *   over the same records.
+ * @param {Iterable<object>} records - The content-index records.
+ * @param {(record: object) => string} fileOf - A record's note file, as the
+ *   prepared results are keyed.
+ * @param {string} [only] - One note file to give views to, every note's being
+ *   read for them; absent, every note is given its views.
+ * @returns {Promise<Map<string, Map<string, string>>>} Note file to its views,
+ *   each keyed by its slug, for every note given at least one.
+ */
+export function eventViewSections(db: object, records: Iterable<object>, fileOf: (record: object) => string, only?: string): Promise<Map<string, Map<string, string>>>;
+/**
+ * The views, in the order
+ * {@link module:engine/generated-sections.GENERATED_SECTIONS} sets them in.
+ *
+ * Each names its anchor `slug`, its `heading`, whether it `applies` to a note's
+ * index record, and the `query` it writes for a note — given the note's
+ * Address in each form an event may name it by, and the shape of the corpus —
+ * or `null` where the corpus states nothing the view could select. A view's
+ * `own` query, where it has one, is what decides whether the view has rows.
+ *
+ * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
+ *   applies: (record: object) => boolean,
+ *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null}>>}
+ */
+export const EVENT_VIEWS: ReadonlyArray<Readonly<{
+    slug: string;
+    heading: string;
+    applies: (record: object) => boolean;
+    query: (self: string[], shape: CorpusShape) => {
+        fence: string;
+        own?: string;
+    } | null;
+}>>;
+export type CorpusShape = {
+    /**
+     * - Some place states `data.parents`.
+     */
+    parents: boolean;
+    /**
+     * - Some event states `where.locus`.
+     */
+    locus: boolean;
+    /**
+     * - Some event states `where.reach`.
+     */
+    reach: boolean;
+    /**
+     * - Some event states `who`.
+     */
+    who: boolean;
+    /**
+     * - Some event states `accounts`.
+     */
+    accounts: boolean;
+    /**
+     * - Some event states `follows`.
+     */
+    follows: boolean;
+    /**
+     * - Some event states `depth`.
+     */
+    depth: boolean;
+};

package/types/engine/exported-scene.d.mts

@@ -1,13 +1,16 @@
 /**
  * Compile a Foundry Scene export into a pack document.
  *
- * Only the note-derived Scene ID, compendium metadata, and pins marked
- * `#anchor` change. Every other authored Scene field passes through.
+ * The Scene passes through as exported. Only the note-derived Scene ID,
+ * compendium metadata, `data.fixup` and pins marked `#anchor` change; nothing
+ * else inside the Scene is read or checked.
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.
  * @param {{journalEntryId?: string, stats?: object, resolveAddress?: Function}} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
  * @returns {object} The keyed Scene document.
+ * @throws {Error} When `data.scene` is not an object, or a fixup or pin anchor
+ *   names something the Scene or the note does not have.
  */
 export function buildExportedScene(fm: object, markdown: string, { journalEntryId, stats, resolveAddress }?: {
     journalEntryId?: string;

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

@@ -166,10 +166,10 @@ export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, SystemBlockSpec>>;
  *
  * {@link module:engine/art-fields.ART_SLOTS} is the declaration; this is that
  * list in the shape the checks below read, so the linter states no art key of
- * its own and a slot added there is checked here with no second edit. All four
- * are authored under `data:`, which is what `inData` records.
+ * its own and a slot added there is checked here with no second edit. Every
+ * slot is authored under `data:`, which is what `inData` records.
  *
- * `document` separates the three that reach a compiled document from `banner`,
+ * `document` separates the slots that reach a compiled document from `banner`,
  * which reaches none by design. The inert-art check reads it: a key that is
  * *meant* to reach no document is not an inert key, and reporting every note
  * that names a hero image would bury the finding that matters.