@heroiclands/package-build 20.3.1 → 20.5.0

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

@@ -6,7 +6,7 @@
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
- * It was once the key's whole tail, and #59 ended that: the key gained a
+ * It is not the key's whole tail: the key carries a
  * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
  * the tail with that segment dropped. The behaviour here is unchanged, and
  * deliberately — a page has no system to name (see the module note above), so
@@ -14,11 +14,11 @@
  * consumer deriving a `path` from a key drops the *package and the system*, not
  * the package alone.
  *
- * The hyphen is a separator and never occurs inside a segment: a shortcode is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
- * and a type is a bare word. That is the same charset guarantee positional key
- * parsing rests on, so the address and the key cannot disagree about where one
- * ends and the other begins.
+ * The hyphen is a separator and never occurs inside a segment: a shortcode
+ * matches `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`, enforced by
+ * `content-lint.mjs`) and a type is a bare word. That is the same charset
+ * guarantee positional key parsing rests on, so the address and the key
+ * cannot disagree about where one ends and the other begins.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The address segment, e.g. `weapongear-dagger`.
@@ -50,9 +50,9 @@ export function addressSlug(fm: object): string;
  *
  * **It is a pure function of the frontmatter**, and takes no options. Nothing
  * about the file the note was read from reaches it: the `README.md` convention
- * that made one note address a whole section is retired with the section itself
- * (#204), so every note is addressed alike and there is one rule and no branch.
- * It took an address scheme until #215, to validate a `landing` rule it then
+ * that made one note address a whole section is retired with the section itself,
+ * so every note is addressed alike and there is one rule and no branch.
+ * It takes no address scheme; the `landing` rule it once validated is
  * discarded; with that key retired, `prefix` was the only thing left in the
  * scheme and the paragraph above is the reason it never applied.
  *
@@ -85,9 +85,9 @@ export function packageAddress(fm: object): string;
  * merge is a real conflict rather than an artefact of two packages sharing a
  * namespace. `(type, shortcode)` alone is unique only *within* a package, and
  * two independently authored packages reaching for the same short string is a
- * matter of time (#1499).
+ * matter of time.
  *
- * **The system segment (#59).** A package may ship content for more than one
+ * **The system segment.** A package may ship content for more than one
  * system, and one note then compiles into a document per system — an actor in
  * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
  * land on one key, so the address cannot name either of them. `harn-ensemble`
@@ -137,7 +137,7 @@ export function blockSystem(keyPath?: string): string;
 /**
  * Expand a written address to the one canonical address it names.
  *
- * **An omitted segment defaults from where the link is written** (#336) — it is
+ * **An omitted segment defaults from where the link is written** — it is
  * not a wildcard, and resolution is not a search. Package omitted means the
  * citing note's own; system omitted means {@link blockSystem} of the key path it
  * was written under. So every short form has exactly one expansion, computed
@@ -182,12 +182,12 @@ export function expandAddress(read: {
  *
  * Parsing is plain positional counting: split on the separator, require
  * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
- * **The charset rule is what makes that sound** — every segment is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
- * so the hyphen is purely a separator and the count alone determines every
- * field. That is enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
- * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * **The charset rule is what makes that sound** — every segment matches
+ * `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`), so the hyphen is
+ * purely a separator and the count alone determines every field. That is
+ * enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
+ * `defineConfig`, and types are bare words. Were any of them free to
  * carry a hyphen, no amount of counting would recover the fields and the reader
  * would need a vocabulary to match against instead.
  *
@@ -251,7 +251,7 @@ export function packageRelative(url: string, base: string): string;
 export function resolvePackageUrl(rel: string, base: string): string;
 /**
  * The Foundry `_id` of the document a note compiles into, derived from its
- * canonical address (#270).
+ * canonical address.
  *
  * A note used to author this — an opaque 16-character string, one per note,
  * that said nothing its address did not and that no check guaranteed. The
@@ -278,7 +278,7 @@ export function resolvePackageUrl(rel: string, base: string): string;
  * @returns {string} A 16-character Foundry id.
  */
 export function documentId(pkg: string, system: string, type: string, shortcode: string): string;
-/** The knowledgebase's mount within this package's site (#1470). */
+/** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX: "kb/";
 /**
  * How many segments a canonical key has, and therefore how many the reader

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

@@ -22,7 +22,7 @@ export function declaredPaths(artifact: object): Set<string>;
  *
  * A shared row names no type, so it is placed rather than typed: "in the shared
  * mappings" instead of "on a `weapongear`". Reading `on a \`the shared
- * mappings\`` would be the alternative, and a diagnostic is prose (#275).
+ * mappings\`` would be the alternative, and a diagnostic is prose.
  *
  * @param {object} finding - `{system, systemVersion, noteType, source, target, shared}`.
  * @returns {string} The message.
@@ -79,16 +79,16 @@ export function measureNote(note: object, format: import("./content-format.mjs")
 /**
  * Measure a corpus, and count what it finds by class.
  *
- * The counts are the point as much as the findings: #127 promotes a class to
- * fatal when its count reaches zero, so a run that prints them is the epic's
- * progress bar.
+ * The counts are the point as much as the findings: a class is promoted to
+ * fatal when its count reaches zero, so a run that prints them is the
+ * migration's progress bar.
  *
  * @param {Iterable<object>} notes - `{file, raw, fm}` for each authored note.
  * @param {import("./content-format.mjs").ContentFormat} format - The parsed
  *   specification.
  * @param {object} [opts]
  * @param {boolean} [opts.strict=false] - Report the findings as errors rather
- *   than warnings. #127 turns this on one slice at a time.
+ *   than warnings. Turned on one slice at a time.
  * @returns {{findings: object[], notes: number, byClass: Record<string, number>}}
  */
 export function measureCorpus(notes: Iterable<object>, format: import("./content-format.mjs").ContentFormat, { strict }?: {
@@ -107,7 +107,7 @@ export function measureCorpus(notes: Iterable<object>, format: import("./content
 export function fieldDriftMessage({ noteType, source, target, name, to }: object): string;
 /**
  * Check the specification's per-type tables against the field declarations that
- * compile them (#136).
+ * compile them.
  *
  * @param {object} opts
  * @param {import("./content-format.mjs").ContentFormat} opts.format - The

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

@@ -52,7 +52,7 @@ export const CONTENT_FORMAT_PATH: string;
  *   `the shared mappings` for a row of the shared tables — see `shared`.
  * @property {boolean} [shared] - Whether the row came from a **shared** mapping
  *   table, which stands before the first `### type:` heading and states what
- *   every type maps identically (#275). Absent on a per-type row, so the two
+ *   every type maps identically. Absent on a per-type row, so the two
  *   never mix: only a per-type row has a field declaration to be checked
  *   against.
  * @property {string} system - The system column it sits under, from the header.
@@ -121,7 +121,7 @@ export type MappingClaim = {
     /**
      * - Whether the row came from a **shared** mapping
      * table, which stands before the first `### type:` heading and states what
-     * every type maps identically (#275). Absent on a per-type row, so the two
+     * every type maps identically. Absent on a per-type row, so the two
      * never mix: only a per-type row has a field declaration to be checked
      * against.
      */

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

@@ -0,0 +1,78 @@
+/**
+ * What a note carrying raw HTML is told.
+ *
+ * It names the tag, because a file with several is fixed one at a time, and it
+ * says why rather than only what: an author who does not know the book cannot
+ * render it will read the finding as pedantry about a tag that plainly works.
+ *
+ * @param {string} tag - The matched markup, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function htmlMessage(tag: string): string;
+/**
+ * Every raw HTML tag in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per tag, in source
+ *   order.
+ */
+export function checkHtml(body: string, file: string, { bodyLine, bodyColumn }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+}): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    message: string;
+}>;
+/**
+ * Walk a content tree and report raw HTML in every note's prose.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying markup is the
+ * same problem for the same reason.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>, files: number}} The findings, and
+ *   how many files were read.
+ */
+export function lintContentHtml(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "warning";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * A raw HTML tag, opening, closing or self-closing.
+ *
+ * The name must start a tag for the match to begin, which is what keeps
+ * markdown's own angle brackets out of it: an autolink is `<https://…>`, and
+ * `https` is followed by `:` rather than whitespace or `>`, so the pattern
+ * stops. A comparison written in prose — `a < b` — has no name after the
+ * bracket at all.
+ *
+ * Attributes are consumed as "anything but a bracket", deliberately loosely: a
+ * finding names the tag, and a pattern that tried to parse attribute syntax
+ * would be a second HTML parser with its own bugs, in a module whose whole
+ * point is that nothing here should be parsing HTML.
+ *
+ * @type {RegExp}
+ */
+export const HTML_TAG: RegExp;

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

@@ -2,11 +2,13 @@
  * The family an entry draws from, named or defaulted.
  *
  * @param {{family?: string}} entry - A registry entry.
- * @returns {string} The family name.
+ * @param {IconRegistry} [registry] - The registry it came from.
+ * @returns {string|undefined} The family name, or nothing when neither the
+ *   entry nor the registry says.
  */
 export function familyOf(entry: {
     family?: string;
-}): string;
+}, registry?: IconRegistry): string | undefined;
 /**
  * Read the brace of an icon token.
  *
@@ -26,15 +28,11 @@ export function parseIconAttributes(raw?: string): {
  * Look one name up.
  *
  * @param {string} name - The name written between the colons, without `icon-`.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
- * @returns {{style: string, icon: string, label: string}|null} The entry, or
- *   `null` when the registry does not declare it.
+ * @param {IconRegistry} [registry] - The package's registry.
+ * @returns {object|null} The entry, or `null` when the registry does not
+ *   declare it.
  */
-export function resolveIcon(name: string, registry?: Record<string, object>): {
-    style: string;
-    icon: string;
-    label: string;
-} | null;
+export function resolveIcon(name: string, registry?: IconRegistry): object | null;
 /**
  * The HTML the journals and the website emit — what the system already renders.
  *
@@ -43,14 +41,13 @@ export function resolveIcon(name: string, registry?: Record<string, object>): {
  * an icon dropped into a sentence has no such parent, and "the ☆ toggles it"
  * read aloud as "the toggles it" is a sentence with a hole in it.
  *
- * @param {{style: string, icon: string, label: string}} entry - A registry entry.
+ * @param {object} entry - A registry entry.
+ * @param {Record<string, string>} [attrs] - The token's attributes.
+ * @param {IconRegistry} [registry] - The registry the entry came from, which is
+ *   what says how its family spells a class.
  * @returns {string} An `<i>` element.
  */
-export function iconHtml(entry: {
-    style: string;
-    icon: string;
-    label: string;
-}, attrs?: {}): string;
+export function iconHtml(entry: object, attrs?: Record<string, string>, registry?: IconRegistry): string;
 /**
  * Every icon a string names, in the order written.
  *
@@ -71,11 +68,11 @@ export function iconsIn(text: string): Array<{
  *
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @param {IconRegistry} [registry] - The package's registry.
  * @returns {Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>} The unknown names.
  */
-export function lintIcons(text: string, file: string, registry?: Record<string, object>): Array<{
+export function lintIcons(text: string, file: string, registry?: IconRegistry): Array<{
     file: string;
     line: number;
     column: number;
@@ -83,13 +80,27 @@ export function lintIcons(text: string, file: string, registry?: Record<string,
     message: string;
 }>;
 /**
- * Refuse a registry that names a style Font Awesome Free does not ship.
+ * What is wrong with a package's declared registry.
  *
- * @param {Record<string, object>} registry - A package's icon table.
+ * Both halves are checked, because either alone is unusable: an icon naming a
+ * family nothing declares has no class prefix, and a family nothing names is a
+ * font declared for no reason.
+ *
+ * A **style** is checked against the family's own `styles`, not against a list
+ * here. Font Awesome Free ships three weights and another font ships none or
+ * five, and only the declaration knows which — so a `duotone` entry is refused
+ * because the family that entry belongs to does not list `duotone`, which is a
+ * statement the consumer made about the font it actually ships.
+ *
+ * @param {{families?: object, icons?: object}} registry - A package's declared
+ *   registry, before it is resolved.
  * @param {string} [where="icons"] - Where to say the fault is.
  * @returns {Array<{severity: "warning", message: string}>} What is wrong with it.
  */
-export function checkIconRegistry(registry: Record<string, object>, where?: string): Array<{
+export function checkIconRegistry(registry: {
+    families?: object;
+    icons?: object;
+}, where?: string): Array<{
     severity: "warning";
     message: string;
 }>;
@@ -103,13 +114,13 @@ export function checkIconRegistry(registry: Record<string, object>, where?: stri
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
- * @param {Record<string, object>} [opts.registry] - The package's icon table.
+ * @param {IconRegistry} [opts.registry] - The package's registry.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} What it found.
  */
 export function lintContentIcons(contentBase: string, { skipDirectories, registry }?: {
     skipDirectories?: readonly string[] | undefined;
-    registry?: Record<string, object> | undefined;
+    registry?: IconRegistry | undefined;
 }): {
     findings: Array<{
         file: string;
@@ -127,52 +138,69 @@ export function lintContentIcons(contentBase: string, { skipDirectories, registr
  * is reported by {@link lintIcons}, and a rendered page that still shows
  * `:icon-stra:` is how the author finds it without reading a log.
  *
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * **A function is accepted as well as a table**, and resolved per render. The
+ * shared markdown-it instance is a module-level constant, so it is built before
+ * any configuration is read; a getter lets it draw the package's own registry
+ * without the module load order deciding whether that registry exists yet.
+ *
+ * @param {Record<string, object>|(() => Record<string, object>)} [registry] -
+ *   The registry, or something that returns it.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function iconPlugin(registry?: Record<string, object>): (md: object) => void;
+export function iconPlugin(registry?: Record<string, object> | (() => Record<string, object>)): (md: object) => void;
 /**
- * The Font Awesome styles a registry entry may name.
- *
- * Free ships these three and no others, so a `light` or `duotone` entry would
- * name a glyph the shipped font does not contain — refused here rather than
- * discovered as a blank space in a printed book.
- *
- * @type {readonly string[]}
+ * A **family** is an icon font, and a consumer declares the ones it ships.
+ *
+ * Nothing here names Font Awesome, or Game-Icons, or any other font. A registry
+ * entry is a promise that a glyph will render, and only the package that ships
+ * the font can keep it: the Game-Icons webfont is built by a consumer from its
+ * own templates, and even Font Awesome — which Foundry supplies in-app — is
+ * present on neither the knowledgebase nor the page of a book unless somebody
+ * puts it there. A toolchain that shipped a table would be promising on a
+ * consumer's behalf.
+ *
+ * The vocabulary is the consumer's for a second reason, independent of fonts. A
+ * name like `victory-star-tester` is one game system's concept; another system
+ * compiled by this same toolchain has different icons meaning different things.
+ * What is shared is the *mechanism* — the syntax, the resolution, the checks —
+ * and that is what lives here.
+ *
+ * A family declares:
+ *
+ * - `class` — the prefix its stylesheet uses (`fa`, `ginf`, `bi`).
+ * - `styles` — the weights it ships, in the spelling its classes use. An empty
+ *   list means the font has none, and then a `style` on an entry names
+ *   something that does not exist and is reported rather than rendered.
+ * - `describe` — one line, so a finding can say which font it means.
+ *
+ * @typedef {object} IconFamily
+ * @property {string} class - The stylesheet's class prefix.
+ * @property {readonly string[]} styles - The weights it ships; empty for none.
+ * @property {string} describe - One line, for a finding.
  */
-export const ICON_STYLES: readonly string[];
 /**
- * The icon families a registry entry may draw from.
- *
- * **Two, because the interface uses two.** The SoHL icon legend says so in its
- * own prose: Font Awesome for most things, and Game-Icons.net *"for the arms,
- * gear, and condition glyphs that Font Awesome does not cover"* — eighteen of
- * them, `ginf-broadsword` and its kin (#391).
+ * A resolved registry: the families a package ships, and the icons it names.
  *
- * They differ in more than a class prefix, which is why this is a family rather
- * than a naming convention:
+ * `defaultFamily` is what an entry that names none belongs to. It is optional,
+ * and where a package declares exactly one family that one is it — so a
+ * single-font package writes no `family` anywhere.
  *
- * - Font Awesome has **weights**, so an entry names a `style` and a filled and
- *   hollow pair is one icon twice. Game-Icons has none, so a `style` on such an
- *   entry names something that does not exist.
- * - They resolve to **different fonts**. A PDF has to embed both, and find each
- *   codepoint in its own table — Font Awesome's from the file it ships,
- *   Game-Icons' from the `game-icons-codepoints.json` the consumer's own
- *   `build-icon-font.mjs` writes.
+ * @typedef {object} IconRegistry
+ * @property {Readonly<Record<string, IconFamily>>} families
+ * @property {string|undefined} defaultFamily
+ * @property {Readonly<Record<string, object>>} icons
+ */
+/**
+ * The registry a package that declares none gets: nothing at all.
  *
- * `class` is the prefix the web surfaces use. `styled` says whether a `style`
- * belongs on the entry at all, which is what lets a mistake be reported rather
- * than rendered as a class nobody defined.
+ * Empty rather than a starter set, because a starter set is a promise about
+ * fonts this package does not ship. A tree with no `icons:` configured names no
+ * icons, and `:icon-star:` in one of its notes renders as its own literal text
+ * and is reported — which is the visible failure, not a silent one.
  *
- * @type {Readonly<Record<string, {class: string, styled: boolean, describe: string}>>}
+ * @type {IconRegistry}
  */
-export const ICON_FAMILIES: Readonly<Record<string, {
-    class: string;
-    styled: boolean;
-    describe: string;
-}>>;
-/** The family an entry that does not name one belongs to. */
-export const DEFAULT_ICON_FAMILY: "fontawesome";
+export const EMPTY_ICON_REGISTRY: IconRegistry;
 /**
  * The sizes a note may ask for, and what each means on a page.
  *
@@ -208,38 +236,6 @@ export const ICON_ATTRIBUTES: Readonly<Record<string, {
     values: readonly string[];
     describe: string;
 }>>;
-/**
- * The icons the user guide already depicts, under the names it should call them.
- *
- * Each entry is read off the interface it describes rather than invented, and
- * that is meant literally — the table was checked against the system's own
- * templates, which is how `delete` came to be `fa-trash` rather than the
- * `fa-trash-can` first written here. The sheets draw `fa-trash` twenty-five
- * times and `fa-trash-can` never, so the first spelling would have printed an
- * icon the reader has never seen on screen. A registry that is not checked
- * against the interface is just a second place to be wrong.
- *
- * The names are what a *writer* would reach for — `delete`, not `trash` —
- * because the writer is the one typing them; the Font Awesome spelling is this
- * table's business, not theirs.
- *
- * **Three entries share `xmark`, and that is the point of naming rather than
- * drawing.** A `✕` in the guide means "not applicable" in a Healing Rate
- * column, "remove this row" on a control, and "close" on a dialog's corner. One
- * glyph, three sentences, three different things for a reader who cannot see
- * it — so they are three names with three labels, and the fact that Font
- * Awesome happens to draw them identically stays in this table.
- *
- * `run` and `expand` are likewise distinct: `▶` runs an action, and its label
- * should say so. `fa-play` is what the sheets use for it.
- *
- * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
- */
-export const DEFAULT_ICONS: Readonly<Record<string, {
-    style: string;
-    icon: string;
-    label: string;
-}>>;
 /**
  * The shape a note writes, and the one this module claims.
  *
@@ -247,7 +243,7 @@ export const DEFAULT_ICONS: Readonly<Record<string, {
  * surface that also renders `:smile:` can tell the two apart without a lookup,
  * and a reader can tell what `:icon-star:` is without knowing this module
  * exists. Names are lowercase, digits and hyphens — the charset an address
- * segment already uses (#59), so nothing new has to be explained.
+ * segment already uses, so nothing new has to be explained.
  *
  * Not `:name[content]`. That is remark-directive syntax, and this toolchain
  * parses with markdown-it; a directive would render as its own literal text.
@@ -270,3 +266,54 @@ export const DEFAULT_ICONS: Readonly<Record<string, {
  * @type {RegExp}
  */
 export const ICON_PATTERN: RegExp;
+/**
+ * A **family** is an icon font, and a consumer declares the ones it ships.
+ *
+ * Nothing here names Font Awesome, or Game-Icons, or any other font. A registry
+ * entry is a promise that a glyph will render, and only the package that ships
+ * the font can keep it: the Game-Icons webfont is built by a consumer from its
+ * own templates, and even Font Awesome — which Foundry supplies in-app — is
+ * present on neither the knowledgebase nor the page of a book unless somebody
+ * puts it there. A toolchain that shipped a table would be promising on a
+ * consumer's behalf.
+ *
+ * The vocabulary is the consumer's for a second reason, independent of fonts. A
+ * name like `victory-star-tester` is one game system's concept; another system
+ * compiled by this same toolchain has different icons meaning different things.
+ * What is shared is the *mechanism* — the syntax, the resolution, the checks —
+ * and that is what lives here.
+ *
+ * A family declares:
+ *
+ * - `class` — the prefix its stylesheet uses (`fa`, `ginf`, `bi`).
+ * - `styles` — the weights it ships, in the spelling its classes use. An empty
+ *   list means the font has none, and then a `style` on an entry names
+ *   something that does not exist and is reported rather than rendered.
+ * - `describe` — one line, so a finding can say which font it means.
+ */
+export type IconFamily = {
+    /**
+     * - The stylesheet's class prefix.
+     */
+    class: string;
+    /**
+     * - The weights it ships; empty for none.
+     */
+    styles: readonly string[];
+    /**
+     * - One line, for a finding.
+     */
+    describe: string;
+};
+/**
+ * A resolved registry: the families a package ships, and the icons it names.
+ *
+ * `defaultFamily` is what an entry that names none belongs to. It is optional,
+ * and where a package declares exactly one family that one is it — so a
+ * single-font package writes no `family` anywhere.
+ */
+export type IconRegistry = {
+    families: Readonly<Record<string, IconFamily>>;
+    defaultFamily: string | undefined;
+    icons: Readonly<Record<string, object>>;
+};

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

@@ -91,21 +91,65 @@ export function asciiName(name: unknown): string | null;
  *   a consumer iterating it should not have to check first.
  */
 export function asciiAliases(aliases: unknown): Array<string>;
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * The frontmatter as authored, plus what the index derives from it: the package
+ * it compiles as, its address, ASCII folds of its name and aliases, the anchors
+ * of its body, its Foundry block, the address of its documentation journal, and
+ * where the file sits within the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} [options.absPath] - The file, read only on the failing path to
+ *   locate the offending key.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word. `file` and, where the file was
+ *   read, `position` ride on the error.
+ */
 export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, }: {
-    frontmatter: any;
-    relPath: any;
-    absPath: any;
-    contentPackage: any;
-    body: any;
-    bodyLine: any;
-    manifest: any;
+    frontmatter: Record<string, any>;
+    relPath: string;
+    absPath?: string | undefined;
+    contentPackage: string;
+    body?: string | undefined;
+    bodyLine?: number | undefined;
+    manifest?: object | undefined;
 }): Record<string, any>;
-export function collectContentIndex(contentBase: any, { contentPackage, skipDirectories, manifest, problems }: {
-    contentPackage: any;
-    skipDirectories: any;
-    manifest: any;
-    problems: any;
-}): Record<string, any>[];
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * An item note yields two records — the item, and the documentation journal
+ * that is a document in its own right.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {readonly string[]} options.skipDirectories - The walk's scope, stated
+ *   by the caller. An absent one is the caller's omission, and
+ *   {@link module:engine/helpers.walkMarkdownTree} throws on it.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
+ *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
+ *   note throws — the contract the emitter needs, since an index missing a note
+ *   asserts that it does not exist.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, manifest, problems }: {
+    contentPackage: string;
+    skipDirectories: readonly string[];
+    manifest?: object | undefined;
+    problems?: object[] | undefined;
+}): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
  *
@@ -120,7 +164,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *
  * The half of {@link emitContentIndex} that derives rather than emits, so a
  * pass that needs the corpus in memory — a SQL content table, the link check,
- * and in time every reader #243 converts — builds it the same way the artifact
+ * and in time every converted reader — builds it the same way the artifact
  * is built, rather than by walking and parsing again with its own idea of the
  * scope.
  *
@@ -131,7 +175,7 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   caller that resolved one of its own; defaults to the resolved
  *   configuration's. Stated separately from `config` because a caller that was
  *   *handed* a scope must be able to pass it on rather than have it silently
- *   replaced by the one its configuration happens to carry (#243).
+ *   replaced by the one its configuration happens to carry.
  * @param {object[]} [opts.problems] - Supplied by a **reader**: a note that
  *   cannot be recorded is pushed here as a diagnostic and skipped, instead of
  *   aborting the derivation. Omitted, the note throws — which is the contract