@heroiclands/package-build 20.4.0 → 20.6.0

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

@@ -95,11 +95,11 @@ export function locateConfigError(err: unknown, configPath?: string): unknown;
  *
  * @param {unknown} data - The parsed configuration document.
  * @param {string} configPath - Absolute path of the file it was parsed from.
- * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.
  * @throws {Error} When the document is not a mapping, declares `rootDir`, or
  *   names an item-builder registry this package does not ship.
  */
-export function configFromData(data: unknown, configPath: string): import("../config.mjs").ContentBuildConfig;
+export function configFromData(data: unknown, configPath: string): import("../content-config.mjs").ContentBuildConfig;
 /**
  * The consuming repository's resolved, frozen configuration.
  *
@@ -108,12 +108,12 @@ export function configFromData(data: unknown, configPath: string): import("../co
  * configuration (#2). The result is memoised, so calling it in a default
  * parameter — the usual spelling here — costs one property read per call.
  *
- * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @returns {import("../content-config.mjs").ContentBuildConfig} The frozen configuration.
  * @throws {Error} When no configuration file can be found, or the one named
  *   cannot be loaded. Absence is a defect, not a fallback: without it the
  *   compilers know neither what to compile nor where to put it.
  */
-export function loadPackConfig(): import("../config.mjs").ContentBuildConfig;
+export function loadPackConfig(): import("../content-config.mjs").ContentBuildConfig;
 /**
  * The file {@link loadPackConfig} resolved the configuration from.
  *

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

@@ -0,0 +1,42 @@
+/**
+ * The file name a downloaded book identifies itself by.
+ *
+ * The zip and the manifest take their names from the manifest, so an asset's
+ * name and its advertised URL cannot disagree. A PDF has no advertised URL, so
+ * its name is a free choice — which is exactly why it is fixed here rather than
+ * left for each of six consumers to invent.
+ *
+ * @param {string} artifact - The package's artifact name.
+ * @param {string} version - The version being released.
+ * @returns {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned.
+ */
+export function pdfFileName(artifact: string, version: string): string;
+/**
+ * Build the book.
+ *
+ * @param {object} [opts] - Options.
+ * @param {object} [opts.config] - A resolved configuration; loaded when absent.
+ * @param {string} [opts.out] - Where to write, overriding `pdf.out`.
+ * @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.
+ * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
+ */
+export function buildPdf({ config, out, version, compile }?: {
+    config?: object | undefined;
+    out?: string | undefined;
+    version?: string | undefined;
+    compile?: boolean | undefined;
+}): Promise<object>;
+/**
+ * Run Typst over the emitted source.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string} pdfPath - Where the PDF goes.
+ * @param {object} pdf - The resolved `pdf:` block.
+ * @returns {{ok: boolean, message: string}} What happened.
+ */
+export function compileTypst(typPath: string, pdfPath: string, pdf?: object): {
+    ok: boolean;
+    message: string;
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Every glyph name a font carries, with the codepoint that reaches it.
+ *
+ * @param {string} file - Path to a `.ttf`/`.otf`.
+ * @returns {Map<string, number>} Name → codepoint.
+ */
+export function glyphTable(file: string): Map<string, number>;
+/**
+ * The family name a font file announces, for Typst's `text(font: …)`.
+ *
+ * Read from the `name` table rather than from the file name, because the file
+ * is what a consumer happened to call it and the family is what the font stack
+ * will match on.
+ *
+ * @param {string} file - Path to a `.ttf`/`.otf`.
+ * @returns {string} The family name, or "" when the table cannot be read.
+ */
+export function familyName(file: string): string;
+/**
+ * Resolve every icon in a registry against the fonts a consumer named.
+ *
+ * @param {object} registry - The resolved `icons:` registry.
+ * @param {Record<string, string>} iconFonts - Family name → font file.
+ * @param {object[]} [findings] - Collected here rather than thrown.
+ * @returns {Map<string, {font: string, codepoint: number}>} Icon name → glyph.
+ */
+export function resolveIconGlyphs(registry: object, iconFonts?: Record<string, string>, findings?: object[]): Map<string, {
+    font: string;
+    codepoint: number;
+}>;

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

@@ -0,0 +1,156 @@
+/**
+ * Escape literal text for Typst markup.
+ *
+ * @param {string} text - Text as the author wrote it.
+ * @returns {string} The same text, inert.
+ */
+export function escapeTypst(text: string): string;
+/**
+ * Escape a string going inside Typst string quotes, as a `#link` URL does.
+ *
+ * @param {string} text - The raw value.
+ * @returns {string} The same value, quotable.
+ */
+export function escapeTypstString(text: string): string;
+/**
+ * A Typst label, from a plan anchor.
+ *
+ * Typst labels admit a narrower charset than an anchor does, so anything else
+ * folds to a hyphen. The plan already guarantees anchors are unique, and a fold
+ * that merged two of them would silently give one destination two meanings —
+ * so the fold is injective by construction: only characters Typst rejects move,
+ * and they move to a character the slugifier never emits twice in a row.
+ *
+ * @param {string} anchor - The plan's anchor.
+ * @returns {string} A Typst label name.
+ */
+export function labelFor(anchor: string): string;
+/**
+ * A markdown-it configured to parse, not to render.
+ *
+ * `html: false` is the load-bearing setting: raw HTML in a note has no route to
+ * Typst at all, which is why {@link module:engine/content-html} reports it. With
+ * HTML disabled markdown-it emits the tag as text, so it arrives in the book
+ * visibly wrong rather than invisibly missing.
+ *
+ * @param {object} [registry] - The icon registry.
+ * @returns {object} A markdown-it instance.
+ */
+export function createParser(registry?: object): object;
+/**
+ * Render markdown as Typst content.
+ *
+ * @param {string} markdown - The note's body, tables expanded and links resolved.
+ * @param {object} [opts] - Options.
+ * @param {object} [opts.md] - A parser from {@link createParser}, reused across
+ *   a whole book rather than rebuilt for each of 2,500 notes.
+ * @param {object} [opts.registry] - The icon registry, when no parser is passed.
+ * @param {Map<string, string>} [opts.links] - Address slug → plan anchor.
+ * @param {Map<string, string>} [opts.glyphs] - Icon name → `{font, char}`.
+ * @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.
+ * @returns {string} Typst markup.
+ */
+export function markdownToTypst(markdown: string, opts?: {
+    md?: object | undefined;
+    registry?: object | undefined;
+    links?: Map<string, string> | undefined;
+    glyphs?: Map<string, string> | undefined;
+    headingOffset?: number | undefined;
+    anchorPrefix?: string | undefined;
+}): string;
+/**
+ * The whole book, as one Typst document.
+ *
+ * **Pure, and that is the point.** Everything a reviewer of #316 has to check
+ * about structure — the outline's shape, the anchors, which links went inward,
+ * the order entries print in — is decided here from a plan and a map of bodies,
+ * with no filesystem and no compiler. {@link module:engine/pdf-build} supplies
+ * both and runs Typst over the result.
+ *
+ * ## Three surfaces, one heading tree
+ *
+ * A roster of 2,500 entries wants every entry reachable from a viewer's
+ * sidebar, and emphatically does not want all 2,500 printed in the front
+ * matter: that is forty pages of contents before the book starts. It also
+ * wants every heading in a note's own body to keep working as a link target,
+ * without appearing on either surface — the anchor an author writes for
+ * `[[note#appearance]]` is structure, not a destination either outline offers
+ * on its own.
+ *
+ * `heading` carries `outlined` and `bookmarked` independently, so the three
+ * wants are three settings rather than three passes:
+ *
+ * - A **section** — `outlined: true, bookmarked: true` — prints in the paper
+ *   contents and the PDF sidebar alike.
+ * - A **note leaf**, titled from `name.full`, is `outlined: false,
+ *   bookmarked: true`: reachable from the sidebar, absent from the printed
+ *   contents.
+ * - A **body heading**, inside a note's own markdown, is `outlined: false,
+ *   bookmarked: false`: a real heading with a label, so it still supplies a
+ *   link target, a running head and a page break, but neither outline lists
+ *   it. {@link markdownToTypst} emits these.
+ *
+ * `#outline()` needs no depth limit under this model: what prints is decided
+ * per heading, not by how deep the tree happens to go.
+ *
+ * ## Headings carry the structure, so nothing else has to
+ *
+ * Every section, every prose file and every entry is a real Typst heading at
+ * its plan depth. That single decision supplies both outlines, the running
+ * heads and the page breaks at once — where drawing titles as styled text
+ * would have meant building all four by hand and keeping them agreeing with
+ * each other.
+ *
+ * @param {object} opts - Options.
+ * @param {object} opts.plan - From {@link module:engine/pdf-toc.planDocument}.
+ * @param {Map<string, string>} opts.bodies - Anchor → the entry's rendered
+ *   Typst body. An entry with no body prints its heading alone.
+ * @param {string} opts.title - The document's title.
+ * @param {string} [opts.subtitle] - Shown under it on the title page.
+ * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
+ * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
+ * @param {string} [opts.version] - Stamped on the title page when given.
+ * @returns {string} A complete `.typ` document.
+ */
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, }?: {
+    plan: object;
+    bodies: Map<string, string>;
+    title: string;
+    subtitle?: string | undefined;
+    front?: string[] | undefined;
+    fonts?: object | undefined;
+    version?: string | undefined;
+}): string;
+/**
+ * Point every internal link at a label the document actually declares.
+ *
+ * **Typst refuses to compile a reference to a label that is not there.** That
+ * makes one mistyped `[[note#appearance]]`, or an anchor written inside a code
+ * fence where no heading is emitted, fatal to a 1,200-page book — and fatal at
+ * the very end, after everything else has succeeded. A reference book cannot
+ * have that failure mode: the link is the least important thing on the page and
+ * would be taking the other two thousand entries down with it.
+ *
+ * So references are reconciled against declarations before the source is
+ * written. A link to a section that does not exist falls back to the **entry**
+ * that would have contained it, which is where a reader wants to end up anyway;
+ * a link with no entry to fall back to becomes plain text. Both are reported.
+ *
+ * A declaration is a label not preceded by `#link(` — the only two places a
+ * label appears are the heading that declares one and the link that uses one.
+ *
+ * @param {string} source - The assembled Typst document.
+ * @param {object[]} [findings] - Collected here rather than thrown.
+ * @returns {string} The same document, with no reference left dangling.
+ */
+export function resolveDanglingLabels(source: string, findings?: object[]): string;
+/**
+ * Every icon name a body uses, so a build can resolve them once.
+ *
+ * @param {string} markdown - A note body.
+ * @returns {string[]} The names, in order of appearance, with repeats.
+ */
+export function iconNamesIn(markdown: string): string[];

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

@@ -0,0 +1,114 @@
+/**
+ * Validate the raw tree and flatten it into nodes.
+ *
+ * The format has no chapter/section distinction: every node is a section, and
+ * the leaves of the *document* are the notes and prose its contents resolve to.
+ * Depth is whatever the tree says, so nothing here caps or normalises it.
+ *
+ * `contents` is an **ordered, heterogeneous** list — prose, filters and child
+ * sections interleave in the sequence written, and that sequence is preserved
+ * exactly. A section that opens with a `file:` and then lists its entries is
+ * saying something different from one that does the reverse.
+ *
+ * @param {unknown} raw - The parsed document, as YAML returns it.
+ * @param {object} [opts] - Options.
+ * @param {string} [opts.text] - The file's source, for finding positions. Every
+ *   finding without one is still reported, just without a locator.
+ * @returns {{nodes: object[], findings: object[]}} The flattened tree and what
+ *   was wrong with it.
+ */
+export function parseDocumentTree(raw: unknown, { text }?: {
+    text?: string | undefined;
+}): {
+    nodes: object[];
+    findings: object[];
+};
+/**
+ * Run every filter, and report the ones that would not run.
+ *
+ * The I/O half, kept apart from the planner for the reason the whole engine
+ * keeps them apart: the plan is then assertable without a database. The build
+ * owns the statement — `SELECT * FROM notes WHERE <clause>` — which is what
+ * makes a filter unable to reach another package's schema, unable to project
+ * something that is not a note, and unable to pick up the `doc<type>`
+ * documentation rows that ride the same index as the notes they document.
+ *
+ * **A filter that selects nothing is an error**, and the distinction that makes
+ * that consistent is worth stating. A *note* no clause selects is expected: the
+ * book is a selection and a project decides what its own volume carries. A
+ * *clause* that selects no note is not the same thing — a filter is a deliberate
+ * act, so one matching nothing is either wrong or left over from a structure
+ * that has moved on, and in both cases the tree should not carry it. Reported
+ * with the section's name and the filter's position, so the choice between
+ * fixing it and deleting it is the author's.
+ *
+ * @param {object[]} nodes - From {@link parseDocumentTree}.
+ * @param {{query: (sql: string) => Promise<{rows: object[]}>}} db - An open
+ *   database, from {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {object} [opts] - Options.
+ * @param {(record: object) => boolean} [opts.keep] - Which rows are notes.
+ * @param {string} [opts.text] - The document's source, for finding positions.
+ * @returns {Promise<{selections: Map<string, object[]>, findings: object[]}>}
+ */
+export function runTreeFilters(nodes: object[], db: {
+    query: (sql: string) => Promise<{
+        rows: object[];
+    }>;
+}, { keep, text }?: {
+    keep?: ((record: object) => boolean) | undefined;
+    text?: string | undefined;
+}): Promise<{
+    selections: Map<string, object[]>;
+    findings: object[];
+}>;
+/**
+ * Resolve the flattened tree into the document plan.
+ *
+ * The plan is an ordered list of entries — `section`, `prose`, `note` — and it
+ * is the artifact worth having. Order, depth, the outline, the table of
+ * contents, anchor uniqueness and every link destination are all readable from
+ * it, so nearly the whole of what #316 asks for can be asserted here, on data,
+ * without a renderer or a PDF. Only how the result *looks* needs eyes.
+ *
+ * **Notes are sorted, prose is not.** A section's entries come out in
+ * `nameAscii` order — the ASCII fold `buildIndexRecord` already derives, so a
+ * circumflex sorts with its letter instead of after `Z` as a raw codepoint
+ * comparison would put it. Prose keeps the position it was written in, because
+ * its place in the sequence is the author's statement.
+ *
+ * **A section with nothing in it does not print**, and emptiness is judged after
+ * its descendants are: a section holding only sections that all resolved to
+ * nothing is itself empty. In a correct tree this never fires — a filter that
+ * selects nothing is reported by {@link runTreeFilters} as the error it is — so
+ * this is the graceful half of that failure rather than a feature: a build whose
+ * filters are broken still produces a readable document to look at while they
+ * are fixed. A section holding only prose is not empty; it is a preface.
+ *
+ * @param {object[]} nodes - From {@link parseDocumentTree}.
+ * @param {object} [opts] - Options.
+ * @param {Map<string, object[]>} [opts.selections] - Records each filter
+ *   selected, keyed by item id. Run by the caller: DuckDB is async and this is
+ *   not.
+ * @returns {{entries: object[], links: Map<string, string>, stats: object}}
+ *   The plan, the address→anchor map inbound wikilinks resolve through, and
+ *   what the selection came to.
+ */
+export function planDocument(nodes: object[], { selections }?: {
+    selections?: Map<string, object[]> | undefined;
+}): {
+    entries: object[];
+    links: Map<string, string>;
+    stats: object;
+};
+/**
+ * Presentation a node may declare, and that its descendants inherit.
+ *
+ * Reserved now although the first release renders none of them, because the
+ * shape of the file is the thing consumers commit to: a book that has to be
+ * restructured to gain a running head has the wrong format, not the wrong
+ * renderer. Inheritance is what makes them worth declaring at all — `Gear` says
+ * once which infobox its entries use, and nine sections beneath it agree.
+ *
+ * @type {readonly string[]}
+ */
+export const PRESENTATION_KEYS: readonly string[];

package/types/engine/scenes.d.mts

@@ -13,6 +13,15 @@
  * @returns {Set<string>} The known action names.
  */
 export function collectKnownActionNames(repoRoot: string): Set<string>;
+/**
+ * Scenes pack compiler.
+ *
+ * Walks the content tree and compiles every map note into one Scene, resolving
+ * what one note says about another through an index built before any scene is
+ * written. It also writes one Adventure per place, bundling those scenes with
+ * the JournalEntries their prose compiled into, which is what makes a pinned
+ * scene's id-based references resolve on import.
+ */
 export class Scenes extends BasePackCompiler {
     constructor({ contentBase, dest, skipDirectories, companionDests, folderResolver, repoRoot, }: {
         contentBase: any;
@@ -31,7 +40,7 @@ export class Scenes extends BasePackCompiler {
      */
     adventureCount: number;
     index: Map<string, object> | undefined;
-    effectsByAddress: Map<any, any> | undefined;
+    effectsByAddress: Map<string, object> | undefined;
     knownActions: Set<string> | undefined;
     /** place key → `{name, img, scenes: [], journal: []}` */
     places: Map<any, any> | undefined;

package/types/engine/schema-check.d.mts

@@ -291,7 +291,7 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * existed, or a subtype the artifact does not name, produces no findings.
  * `content-build lint` is where a missing artifact is said out loud, once.
  *
- * @param {object} system - The `system` block the compiler produced.
+ * @param {object} emitted - The `system` block the compiler produced.
  * @param {object} opts
  * @param {object} opts.fm - The note's frontmatter, for the authored paths this
  *   check leaves to {@link checkAuthoredSystemData}.
@@ -307,7 +307,7 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * @param {object} [opts.config] - The resolved build configuration.
  * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.
  */
-export function checkEmittedSystemData(emitted: any, { fm, block, documentType, subType, type, fields, system, config, }: {
+export function checkEmittedSystemData(emitted: object, { fm, block, documentType, subType, type, fields, system, config, }: {
     fm: object;
     block: string;
     documentType: string;

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

@@ -126,10 +126,13 @@ export function writeHomepages(outRoot: string, pages: readonly object[], config
  * @param {object[]} pages - Every page, from both walks.
  * @param {object} findings - `{ addressFindings, fmLinkFindings }` from
  *   collection.
- * @param {object} options - `{ config }`.
+ * @param {object} options
+ * @param {object} options.config - The resolved build configuration.
  * @returns {object} The gate results and, when they pass, the built index.
  */
-export function siteGates(pages: object[], findings: object, { config }: object): object;
+export function siteGates(pages: object[], findings: object, { config }: {
+    config: object;
+}): object;
 /**
  * The gate result of a build that ran none of them.
  *
@@ -220,10 +223,18 @@ export function sectionFrontmatter(meta: object): object;
  * section's landing and takes the title and hero the section declares.
  *
  * @param {object} page - The page.
- * @param {object} options - `{ readmeSections, decorate }`.
+ * @param {object} options
+ * @param {Record<string, object>} [options.readmeSections] - The sections a
+ *   published tree declares, which a tree page's own `README` is the landing
+ *   for.
+ * @param {(data: object, page: object) => void} [options.decorate] - Called
+ *   with each page's frontmatter, for whatever a consumer's own pass adds.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page: object, { readmeSections, decorate }: object): object;
+export function pageFrontmatter(page: object, { readmeSections, decorate }: {
+    readmeSections?: Record<string, object> | undefined;
+    decorate?: ((data: object, page: object) => void) | undefined;
+}): object;
 /**
  * Where a page is written, relative to the output root.
  *
@@ -310,10 +321,21 @@ export function renderPages(pages: object[], options: object): {
  * navigation of every page inside it.
  *
  * @param {string} outRoot - The mount directory.
- * @param {object} options - `{ sections, landing, sectionTitle }`.
+ * @param {object} options
+ * @param {Record<string, object>} [options.sections] - The declared sections,
+ *   each written as a titled `_index.md` carrying its own frontmatter.
+ * @param {object} [options.landing] - The mount's own landing frontmatter.
+ *   Omitted, the mount gets no `_index.md` of its own.
+ * @param {((name: string) => string)|null} [options.sectionTitle] - Titles a
+ *   directory below the mount that declared no section. `null` leaves such a
+ *   directory without an `_index.md`.
  * @returns {number} How many landings were written.
  */
-export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: object): number;
+export function writeSectionLandings(outRoot: string, { sections, landing, sectionTitle }: {
+    sections?: Record<string, object> | undefined;
+    landing?: object | undefined;
+    sectionTitle?: ((name: string) => string) | null | undefined;
+}): number;
 /**
  * A section landing's title, from its directory name — `macro` → `Macros`.
  *
@@ -370,12 +392,18 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
  * @param {string} [options.outRoot] - Override the configured output mount.
+ * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
+ *   keyed by the note's absolute file, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring 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[], manifests: object|null}}
  */
 export function buildSite({ config, outRoot, sqlTables }?: {
     config?: object | undefined;
     outRoot?: string | undefined;
+    sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;
     stats: object | null;

package/types/engine/wikilinks.d.mts

@@ -55,8 +55,8 @@ export function resolveItemDocType(qualifier: string, types: Set<string>): strin
  *
  * **Parsing is plain positional counting**, the same rule
  * {@link readCanonicalKey} follows, and it is sound for the same reason: every
- * segment is `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced on
- * shortcodes by `content-lint.mjs`), so the hyphen is purely a
+ * segment matches `ADDRESS_SEGMENT_PATTERN` (enforced on shortcodes by
+ * `content-lint.mjs`), so the hyphen is purely a
  * separator and the count alone determines every field. Verified across the
  * four content trees: 138,204 authored shortcodes, none carrying a separator.
  *
@@ -144,7 +144,6 @@ export function buildWikilinkIndex(docs: Array<{
     byShortcode: Map<string, object>;
     types: Set<string>;
 };
-/** Matches a whole wikilink, capturing its inner text. */
 /**
  * Rewrites every wikilink in a markdown body as a Foundry UUID enricher.
  *

package/types/hm3/actors.d.mts

@@ -1,3 +1,11 @@
+/**
+ * HM3's Actor compile pass.
+ *
+ * Declares HM3's note-type → document-subtype map and builds a `being` note's
+ * document: the subtype the note authors in `hm3.type`, the mapped fields and
+ * the two anchored prose sections, and the embedded items `hm3.items` names.
+ * Everything else is {@link module:engine/actor-compiler}'s.
+ */
 export class Hm3Actors extends SystemActorCompiler {
     /**
      * HM3's note-type → document-subtype map — the one declaration that says

package/types/hm3/items.d.mts

@@ -1,3 +1,11 @@
+/**
+ * HM3's Item compile pass.
+ *
+ * Declares HM3's note-type → document-subtype map, which decides the notes this
+ * pass claims and what each becomes, the one `system` key HM3 writes from prose,
+ * and the template-priority flag HM3's data model has no field for. Everything
+ * else is {@link module:engine/item-compiler}'s.
+ */
 export class Hm3Items extends SystemItemCompiler {
     /**
      * HM3's note-type → document-subtype map — the one declaration that says

package/types/release.d.mts

@@ -15,22 +15,33 @@
  *   Determines both asset names.
  * @param {string} [opts.metadataDir] - Where the build writes its content
  *   index, consulted when the advertised file was not staged.
+ * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
+ *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   bytes: number, version: string}>} The paths written, the archive's size,
- *   and the version the manifest declares. `metadata` is absent when the
- *   manifest advertises no content index.
+ *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   bytes: number, version: string}>} The paths written, what the book build
+ *   found, the archive's size, and the version the manifest declares.
+ *   `metadata` is absent when the manifest advertises no content index, and
+ *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
+ *   book was built, and otherwise the reason none was — itself `null` when the
+ *   book builder could not be loaded, which is reported through
+ *   `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
-export function packRelease({ stageDir, outDir, artifact, metadataDir, }?: {
+export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?: {
     stageDir?: string | undefined;
     outDir?: string | undefined;
     artifact?: "module" | "system" | undefined;
     metadataDir?: string | undefined;
+    pdf?: boolean | undefined;
 }): Promise<{
     zip: string;
     manifest: string;
     metadata?: string;
+    pdf?: string;
+    pdfFindings: object[];
+    pdfSkipped: string | null;
     bytes: number;
     version: string;
 }>;

package/types/sohl/actors.d.mts

@@ -1,3 +1,11 @@
+/**
+ * SoHL's Actor compile pass.
+ *
+ * Declares SoHL's note-type → document-subtype map and builds a `being` note's
+ * document: the body structure and its movement profiles, the embedded
+ * attribute and item documents the frontmatter names, and the `system` block.
+ * Everything else is {@link module:engine/actor-compiler}'s.
+ */
 export class Actors extends SystemActorCompiler {
     /**
      * SoHL's note-type → document-subtype map — the one declaration that says
@@ -12,7 +20,7 @@ export class Actors extends SystemActorCompiler {
      * Build all embedded items for an actor: one per `sohl.attributes`
      * entry plus one per `sohl.items` entry. `sohl.skills` is ignored.
      */
-    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): any[];
+    buildEmbeddedItems(itemsMap: any, actorId: any, fm: any, ctx: any): object[];
     /**
      * Bake each unopened skill's opening mastery level into the document.
      *
@@ -52,7 +60,7 @@ export class Actors extends SystemActorCompiler {
             appearance: string;
             dossier: string;
         };
-        items: any[];
+        items: object[];
         prototypeToken: {
             name: any;
             displayName: number;

package/types/sohl/items.d.mts

@@ -1,3 +1,11 @@
+/**
+ * SoHL's Item compile pass.
+ *
+ * Declares SoHL's note-type → document-subtype map, which decides the notes
+ * this pass claims and what each becomes, and the `system` keys SoHL writes on
+ * every item whatever its type. Everything else is
+ * {@link module:engine/item-compiler}'s.
+ */
 export class Items extends SystemItemCompiler {
     /**
      * SoHL's note-type → document-subtype map — the one declaration that says