@heroiclands/package-build 22.28.0 → 23.1.0

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.

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

@@ -0,0 +1,143 @@
+/**
+ * The pathname a generated section names the map from a place by.
+ *
+ * @param {string} shortcode - The place.
+ * @returns {string} `generated/from-<shortcode>.svg`.
+ */
+export function fromHereSource(shortcode: string): string;
+/**
+ * The file the map from a place is drawn into, wherever a surface draws it.
+ *
+ * @param {string} shortcode - The place.
+ * @returns {string} `from-<shortcode>.svg`.
+ */
+export function fromHereFile(shortcode: string): string;
+/**
+ * The drawing an image pathname names, when it names one the build makes.
+ *
+ * @param {string} src - An image's address, as the Markdown carries it.
+ * @returns {string|null} The drawn file's name, or `null` for any other image.
+ */
+export function generatedDrawing(src: string): string | null;
+/**
+ * Whether an authored image addresses the directory the build's drawings use.
+ *
+ * @param {string} src - The address, exactly as authored.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function generatedDirectoryProblem(src: string): string;
+/**
+ * Whether a note's own body declares a prose anchor with this slug.
+ *
+ * @param {object} record - The note's index record, whose `anchors` were read
+ *   from the authored body.
+ * @param {string} slug - The section's anchor.
+ * @returns {boolean} Whether the author has written the section.
+ */
+export function authoredSection(record: object, slug: string): boolean;
+/**
+ * The heading line of one generated section, with its anchor.
+ *
+ * @param {string} slug - One of {@link GENERATED_SECTIONS}.
+ * @returns {string} `# <Heading> {#<slug>}`.
+ */
+export function sectionHeading(slug: string): string;
+/**
+ * One note's sections, joined in {@link GENERATED_SECTIONS} order.
+ *
+ * @param {Iterable<Map<string, string>|undefined>} parts - Each a map of slug
+ *   to that section's Markdown, heading included.
+ * @returns {string} The sections, or `""` when there are none.
+ */
+export function joinSections(parts: Iterable<Map<string, string> | undefined>): string;
+/**
+ * A note's body with its generated sections after it — the one way the two
+ * are joined, so the pass that answers their fences and every pass that
+ * expands them read the same text.
+ *
+ * @param {string} body - The authored body.
+ * @param {string|undefined} sections - Its sections, from {@link joinSections}.
+ * @returns {string} The body the surfaces receive.
+ */
+export function appendGeneratedSections(body: string, sections: string | undefined): string;
+/**
+ * Mark where a note's generated sections begin.
+ *
+ * @param {string} markdown - The expanded body.
+ * @param {number|undefined} from - The 0-based line the sections start on,
+ *   from {@link module:engine/content-tables.expandContentTables}.
+ * @returns {string} The body, with {@link GENERATED_BOUNDARY} on its own line
+ *   before the sections; unchanged where there are none.
+ */
+export function markGenerated(markdown: string, from: number | undefined): string;
+/**
+ * Split a body at its {@link GENERATED_BOUNDARY}.
+ *
+ * @param {string} markdown - A body {@link markGenerated} marked.
+ * @returns {{authored: string, generated: string}} The author's text, and the
+ *   generated sections after it — `""` when there are none.
+ */
+export function splitGenerated(markdown: string): {
+    authored: string;
+    generated: string;
+};
+/**
+ * A note's **generated sections**: the H1 sections the build appends after
+ * everything the author wrote, each under a fixed anchor.
+ *
+ * Two families share the one mechanism. The derived lists —
+ * {@link module:engine/derived-sections} — say where a place sits, who governs
+ * it, what it governs, which works concern the note and what the map from a
+ * place shows. The event views — {@link module:engine/event-views} — list the
+ * events concerning a note. Each section is Markdown an author could have
+ * written, so the website, the Foundry journal and the book receive one text
+ * and set it as they set an authored section: Foundry starts a page at the
+ * heading, the website a section in its table of contents, the book a section
+ * of the entry.
+ *
+ * Three rules hold for every section:
+ *
+ * - **An author's own anchor replaces it.** A note whose body declares a prose
+ *   anchor with the section's slug keeps its own section and is given no
+ *   generated one.
+ * - **A section with nothing to show is not generated.**
+ * - **Sections follow the author's text in the order of
+ *   {@link GENERATED_SECTIONS}.**
+ *
+ * This module is a leaf: it holds the order, the join and the boundary, and
+ * imports nothing, so the table expansion every surface runs can read it
+ * without reaching the derivations.
+ *
+ * @module
+ */
+/**
+ * Every generated section, in the order it follows the author's text: where a
+ * place sits and who governs it, then what happened, then what was written
+ * about it, then the map.
+ *
+ * @type {ReadonlyArray<Readonly<{slug: string, heading: string}>>}
+ */
+export const GENERATED_SECTIONS: ReadonlyArray<Readonly<{
+    slug: string;
+    heading: string;
+}>>;
+/**
+ * The directory, inside a package's own pathname space, that holds the
+ * drawings the build makes. A generated section names a drawing as
+ * `generated/<name>`, and each surface serves it from where it drew it: the
+ * website inlines it, the Foundry compile stages it into the module under
+ * `assets/generated/`, and the book draws it beside its Typst source. An
+ * authored image is never addressed here.
+ *
+ * @type {string}
+ */
+export const GENERATED_DRAWING_DIR: string;
+/**
+ * The line a surface inserts where a note's generated sections begin, when it
+ * treats them differently from the author's text. Private-use characters, so
+ * no pass between the expansion and the split reads it as markup, and no
+ * output carries it: {@link splitGenerated} removes it.
+ *
+ * @type {string}
+ */
+export const GENERATED_BOUNDARY: string;

package/types/engine/holdings.d.mts

@@ -1,4 +1,4 @@
-/** @typedef {{title:string,url?:string,type:string,subType?:string}} HoldingsEntry */
+/** @typedef {{title:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
 /**
  * @typedef {object} HoldingsNode
  * @property {string} shortcode
@@ -14,21 +14,22 @@
  * @property {unknown} [government] Null is explicit anarchy; absence is omission.
  */
 /** @typedef {{contains?:HoldingsEntry[],governed_by?:HoldingsEntry[],governed_places?:HoldingsEntry[]}} Holdings */
-/** Historical shortcode projection for callers that explicitly need one.
+/** The shortcodes a `parents` value names, bare or qualified.
  * @param {unknown} value
  * @returns {string[]}
  */
 export function shortcodesOf(value: unknown): string[];
 /** Read local facts without converting government omission into anarchy.
  * @param {object} fm
- * @param {{title:string,url?:string,package?:string,system?:string,governmentSystem?:string}} page
+ * @param {{title:string,url?:string,package?:string,system?:string,canonical?:string,governmentSystem?:string}} page
  * @returns {HoldingsNode|null}
  */
-export function holdingsNode(fm: object, { title, url, package: pkg, system, governmentSystem }: {
+export function holdingsNode(fm: object, { title, url, package: pkg, system, canonical, governmentSystem }: {
     title: string;
     url?: string;
     package?: string;
     system?: string;
+    canonical?: string;
     governmentSystem?: string;
 }): HoldingsNode | null;
 /** @param {Map<string,object>|undefined} foreignIndex @returns {HoldingsNode[]} */
@@ -57,25 +58,10 @@ export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { government
  * @returns {object[]} Located warning findings.
  */
 export function checkGovernment(note: object): object[];
-/**
- * The historical API name for the government advisory. Tenure is no longer checked.
- * @deprecated Use checkGovernment.
- * @param {object} note - The place note.
- * @param {object} [_opts] - Historical options, no longer needed.
- * @returns {object[]} Government advisory findings.
- */
-export function checkHeld(note: object, _opts?: object): object[];
-/** Derived keys, including retired keys removed from generated pages.
- * @type {readonly string[]}
- */
-export const HOLDINGS_KEYS: readonly string[];
-/** @deprecated Government advisories apply to every inhabited place subtype.
- * @type {readonly string[]}
- */
-export const HELD_SUBTYPES: readonly string[];
 export type HoldingsEntry = {
     title: string;
     url?: string;
+    address: string;
     type: string;
     subType?: string;
 };

package/types/engine/ids.d.mts

@@ -7,6 +7,13 @@
  * @returns {string} A 16-character hexadecimal Foundry id.
  */
 export function makeId(namespace: string, value: string): string;
+/**
+ * Whether a content note's type compiles into a Scene.
+ *
+ * @param {string} [type] - The note's `type` frontmatter.
+ * @returns {boolean} True for a map type.
+ */
+export function isMapType(type?: string): boolean;
 /**
  * Throw if `type` names a retired content type.
  *
@@ -105,24 +112,20 @@ export function compendiumUuid(packageId: string, type: string, id: string, pack
  */
 export function pageUuid(entryUuid: string, pageId: string): string;
 /**
- * Every content type that compiles into a Foundry `Scene` — a **map note**.
- * The three differ only in derived canvas defaults, which is the map
- * compiler's business; everything else treats them alike.
+ * Every content type that compiles into a Foundry `Scene` — a **map note**,
+ * which carries its Scene as exported from Foundry.
  *
- * Declared in this leaf module because several passes that must not depend on
- * the map compiler need it: the pack router below, and the doc-carrying type
- * set in `item-docs.mjs` (a map note's prose becomes a JournalEntry, exactly as
- * an item's or a macro's does).
+ * Declared in this leaf module because several passes need it: the pack router
+ * below, the scenes pass, and the doc-carrying type set in `item-docs.mjs` (a
+ * map note's prose becomes a JournalEntry, exactly as an item's or a macro's
+ * does).
  *
  * @type {ReadonlySet<string>}
  */
 export const MAP_TYPES: ReadonlySet<string>;
 /**
- * The map subTypes, which differ only in the canvas defaults derived for them.
- *
- * As three *types* they would cost three entries in the pack
- * router, three in the claims set and three in every consumer's section config
- * — for one idea that the specification had always described as one type.
+ * The map subTypes. A subType says what kind of map a note is; every one
+ * carries its Scene as exported from Foundry.
  *
  * @type {readonly string[]}
  */

package/types/engine/index.d.mts

@@ -81,7 +81,7 @@ export * as pdfBuild from "./pdf-build.mjs";
 export * as baseCompiler from "./base-compiler.mjs";
 export * as journals from "./journals.mjs";
 export * as macros from "./macros.mjs";
-export * as mapNotes from "./map-notes.mjs";
+export * as exportedScene from "./exported-scene.mjs";
 export * as scenes from "./scenes.mjs";
 export * as bundleNotes from "./bundle-notes.mjs";
 export * as bundles from "./bundles.mjs";

package/types/engine/infobox.d.mts

@@ -423,10 +423,11 @@ export const GEAR_UNITS: Readonly<Record<string, {
  * Three properties, all optional:
  *
  * - `label` — what the row is called. Absent means the key, humanised.
- * - `withheld` — why the field carries no row. Two reasons only: it is
+ * - `withheld` — why the field carries no row. Three reasons only: it is
  *   machinery — something that steers a build or an interface rather than
- *   describing the subject — or it is an image, which rule 2 keeps out of the
- *   box.
+ *   describing the subject, which includes a calendar's definition and a map's
+ *   canvas — it is an image, which rule 2 keeps out of the box, or it is a
+ *   source system's own detail, which no surface's box shows.
  * - `unit` — what the quantity is measured in, appended to the value verbatim.
  *   See {@link applyUnit}.
  * - `group` / `phrase` — the field composes into one row with its group mates
@@ -468,3 +469,12 @@ export const NOTE_FIELD_PRESENTATION: Readonly<Record<string, {
  * @type {readonly string[]}
  */
 export const UNSET_VALUES: readonly string[];
+/**
+ * The section id and title a being's memberships are drawn under.
+ *
+ * @type {Readonly<{id: string, label: string}>}
+ */
+export const MEMBERSHIPS_SECTION: Readonly<{
+    id: string;
+    label: string;
+}>;

package/types/engine/journals.d.mts

@@ -13,9 +13,15 @@
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
- * A figure fence carries its own record along onto the page it starts, as
- * `figure` — `null` for a page a heading started. {@link buildPages} reads it
- * to build the `image` or `text` page a fence begins; nothing else sets it.
+ * A captioned item's page holds the item alone, and carries the item's record
+ * as `figure` — `null` for every other page. {@link buildPages} reads it to
+ * build the `image` or `text` page; nothing else sets it. The page is named
+ * for the item's number, or else its caption's visible text.
+ *
+ * Body that follows an item, up to the next page opening, resumes in a
+ * **continuation** of the section the item interrupted: the section's name,
+ * level and classes, with `continues` naming the item it follows. A
+ * continuation holding nothing is not emitted.
  *
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
@@ -24,8 +30,8 @@
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   classes: string[], figure: object|null, markdown: string}>} Pages in
- *   document order.
+ *   classes: string[], figure: object|null, continues?: string,
+ *   markdown: string}>} Pages in document order.
  */
 export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined): Array<{
     name: string;
@@ -33,6 +39,7 @@ export function splitPages(body: string, leadName?: string, resolveRole?: (addre
     level: number;
     classes: string[];
     figure: object | null;
+    continues?: string;
     markdown: string;
 }>;
 /**
@@ -95,13 +102,18 @@ export function assertUniqueAnchors(rawPages: Array<{
  * a lint error. {@link assertUniquePages} states the same thing at compile
  * time, where the packer would otherwise report only an opaque duplicate key.
  *
+ * A continuation page shares its section's name, so it is keyed by that name
+ * and the captioned item it follows.
+ *
  * @param {string} entryId - The owning JournalEntry's `_id`.
- * @param {{anchorSlug: string|null, name: string}} page - From {@link splitPages}.
+ * @param {{anchorSlug: string|null, name: string, continues?: string}} page -
+ *   From {@link splitPages}.
  * @returns {string} A 16-character Foundry id.
  */
 export function journalPageId(entryId: string, page: {
     anchorSlug: string | null;
     name: string;
+    continues?: string;
 }): string;
 /**
  * Compile split pages into JournalEntryPage documents.
@@ -109,11 +121,12 @@ 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. A figure-started page states none
- * either: {@link scanFigures} validates a figure's classes against its own
- * closed vocabulary, which carries no `.secret`.
+ * A page whose opening heading carries `.secret` is given to the GM alone, by
+ * the one ownership value Foundry reads as "nobody but a GM"; so is a captioned
+ * item's page and a continuation page inside such a section. Every other page
+ * states no ownership and inherits the journal's. A caption's own classes carry
+ * no `.secret`, because {@link scanFigures} validates them against a closed
+ * vocabulary without it.
  *
  * @param {Array<object>} figures - From {@link scanFigures}, numbered across
  *   the whole note. Read by a page a heading started; a page a figure started

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

@@ -0,0 +1,29 @@
+/**
+ * Require `data.language` to address a `skill` note whose subType is
+ * `language`.
+ *
+ * An Address that does not resolve is the reference check's to report, so
+ * this speaks only about a target that exists and is the wrong kind.
+ *
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageChoice(note: object, { index }?: {
+    index?: object;
+}): object[];
+/**
+ * Refuse a literature field on a lore note of any other subType.
+ *
+ * @param {object} note
+ * @returns {object[]} One error per literature key written off `literature`.
+ */
+export function checkLiteratureNote(note: object): object[];
+/** The `lore` subType whose notes are works of literature. */
+export const LITERATURE_SUBTYPE: "literature";
+/**
+ * The fields a `literature` note may state. Every one is optional.
+ *
+ * @type {ReadonlyArray<object>}
+ */
+export const LITERATURE_FIELDS: ReadonlyArray<object>;

package/types/engine/literature-works.d.mts

@@ -0,0 +1,67 @@
+/**
+ * One local page's node.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {{title: string, url?: string, package?: string}} page
+ * @returns {WorksNode|null} Null for a note with no type or shortcode.
+ */
+export function worksNode(fm: object, { title, url, package: pkg }: {
+    title: string;
+    url?: string;
+    package?: string;
+}): WorksNode | null;
+/**
+ * The works a fetched index carries, as nodes. Only a work can list itself on
+ * a page, and only a page of this package can carry the list, so a foreign
+ * entry that is not a work is never needed here.
+ *
+ * @param {Map<string, object>|undefined} foreignIndex
+ * @returns {WorksNode[]}
+ */
+export function foreignWorksNodes(foreignIndex: Map<string, object> | undefined): WorksNode[];
+/**
+ * Invert every work's subjects into the list each subject's page carries.
+ *
+ * A subject is resolved in its work's own package. A work naming one subject
+ * twice lists once; a work naming itself is not listed on its own page.
+ * Entries sort by title.
+ *
+ * @param {Iterable<WorksNode|null>} nodes - Every local page, then any foreign work.
+ * @param {object} options
+ * @param {ReadonlySet<string>} options.types - Note types an Address may name.
+ * @returns {Map<string, {works: WorkEntry[]}>} Keyed by the subject page's URL.
+ */
+export function worksPages(nodes: Iterable<WorksNode | null>, { types }: {
+    types: ReadonlySet<string>;
+}): Map<string, {
+    works: WorkEntry[];
+}>;
+export type WorkEntry = {
+    title: string;
+    url?: string;
+    address: string;
+    form?: string;
+};
+export type WorksNode = {
+    /**
+     * Own Address, normalized to the `note` system.
+     */
+    key: string;
+    title: string;
+    /**
+     * Absent for a note that publishes no page.
+     */
+    url?: string | undefined;
+    /**
+     * Owning content package.
+     */
+    package?: string | undefined;
+    /**
+     * A work's `data.form`.
+     */
+    form?: string | undefined;
+    /**
+     * A work's `data.subjects`; empty for any other note.
+     */
+    subjects: unknown[];
+};

package/types/engine/map-graphviz.d.mts

@@ -1,24 +1,16 @@
 /**
- * Render a DOT source file to SVG, plain positions, or a PNG background.
- *
- * A PNG uses the same Graphviz SVG layout as the vector map. SVG dimensions
- * are in points; resvg starts at 96 pixels per inch, so the zoom converts
- * the requested DPI to the same physical size as Graphviz's PNG output.
+ * Render a DOT source file to SVG.
  *
  * @param {string} dotPath - The saved DOT source.
  * @param {string} outPath - The output file.
  * @param {object} opts
  * @param {"dot"|"twopi"|"neato"} opts.engine - Layout engine.
- * @param {"svg"|"plain"|"png"} [opts.format="svg"] - Output format.
  * @param {2} [opts.nop] - Preserve positioned nodes as `neato -n2` does.
- * @param {number} [opts.dpi=96] - PNG resolution.
  * @returns {{warnings: string}} Renderer warnings.
  */
-export function renderDot(dotPath: string, outPath: string, { engine, format, nop, dpi }: {
+export function renderDot(dotPath: string, outPath: string, { engine, nop }: {
     engine: "dot" | "twopi" | "neato";
-    format?: "svg" | "png" | "plain" | undefined;
     nop?: 2 | undefined;
-    dpi?: number | undefined;
 }): {
     warnings: string;
 };

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

@@ -7,14 +7,19 @@ export function sqlQueriesInMarkdown(body: any, fm?: {}): any[];
  *   figures?: {get: (id: string) => {label: string, caption: string,
  *   hasCaption: boolean}|undefined, note?: (address: string) =>
  *   {url: string|null, figures: Map<string, object>}|undefined,
- *   link?: Function}, file?: string, bodyLine?: number}} [options] -
+ *   link?: Function}, events?: {note: (written: string) => object|undefined,
+ *   own?: (fm: object) => object|undefined},
+ *   file?: string, bodyLine?: number}} [options] -
  *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
  *   note's captioned items by id, and `note` resolves another note's the
  *   way a wikilink would — omitted, a cross-note address is refused rather
  *   than looked up. `link` overrides how a resolved reference renders; the
- *   default is a Markdown link to the target's own anchor.
+ *   default is a Markdown link to the target's own anchor. `events` is what an
+ *   event reference reads: every note's events by Address, from
+ *   {@link module:engine/event-fields.eventNoteIndex}; omitted, an event
+ *   reference is refused.
  */
-export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, figures, file, bodyLine }?: {
+export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, figures, events, file, bodyLine }?: {
     fm?: object;
     dates?: object;
     sqlResults?: Map<string, object>;
@@ -30,6 +35,10 @@ export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults,
         } | undefined;
         link?: Function;
     };
+    events?: {
+        note: (written: string) => object | undefined;
+        own?: (fm: object) => object | undefined;
+    };
     file?: string;
     bodyLine?: number;
 }): {

package/types/engine/near-miss.d.mts

@@ -0,0 +1,42 @@
+/**
+ * The near miss a closed vocabulary names when it refuses a key: the declared
+ * key an unknown one was most likely meant to be, and the declared list as an
+ * English sentence.
+ *
+ * Shared by every closed region — the top level, `data:`, a system block, and
+ * the inner keys of a `data:` field — so a misspelling is answered the same
+ * way at every depth.
+ *
+ * @module
+ */
+/**
+ * Edit distance, capped — enough to answer "did you mean".
+ *
+ * A misspelled property is the failure class this check exists for, and a
+ * finding that names the key the author *meant* turns a hunt through the
+ * reference into a one-character fix.
+ *
+ * @param {string} a - One string.
+ * @param {string} b - The other.
+ * @returns {number} The Levenshtein distance.
+ */
+export function distance(a: string, b: string): number;
+/**
+ * A closed vocabulary as an English list, for the message that names it.
+ *
+ * Written from the declaration rather than spelled into the message, so a key
+ * the vocabulary gains cannot go unmentioned by the finding that refuses its
+ * neighbours.
+ *
+ * @param {readonly string[]} keys - The declared keys, in declared order.
+ * @returns {string} `"a, b, or c"`.
+ */
+export function listed(keys: readonly string[]): string;
+/**
+ * The declared key an unknown one was most likely meant to be.
+ *
+ * @param {string} key - The unknown key.
+ * @param {Iterable<string>} candidates - The declared keys.
+ * @returns {string|undefined} The nearest, when it is near enough to suggest.
+ */
+export function nearest(key: string, candidates: Iterable<string>): string | undefined;

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

@@ -19,6 +19,12 @@ export function decodeNoteAddresses(fm: object, context: object): object;
 export function noteAddressContext(config: object): object;
 /**
  * Decode Address properties contributed by an index record.
+ *
+ * A record read from a published index writes every Address as
+ * `{ address, anchor, anchorKind }`; each becomes a tuple, or an
+ * {@link AddressLink} where it carries an anchor, before the declared
+ * positions are read.
+ *
  * @param {object} record - The record.
  * @param {object} context - Builder defaults.
  * @returns {object} The typed record.
@@ -40,4 +46,4 @@ export const STRUCTURED_ADDRESSES: readonly ({
     accepts: string[];
     system?: undefined;
 })[];
-export { AddressEntries, encodeAddresses, cloneAddressState } from "./address-values.mjs";
+export { AddressEntries, encodeAddresses, cloneAddressState, publishAddresses, readPublishedAddresses, flattenPublishedAddresses } from "./address-values.mjs";