@heroiclands/package-build 20.3.1 → 20.5.0

package/types/engine/helpers.d.mts

@@ -5,7 +5,7 @@
  * `body` is the trimmed raw markdown after the frontmatter block, and
  * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
  * 1-based **file** position of the body's first character, which is what turns
- * an offset within `body` into a position a diagnostic can name (#17) — see
+ * an offset within `body` into a position a diagnostic can name — see
  * {@link positionInBody}. If the file has no frontmatter block, returns
  * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
  * position: there is no body to have one.
@@ -23,28 +23,10 @@ export function parseMarkdownFile(filePath: any): {
     bodyLine: number;
     bodyColumn: number;
 };
-/**
- * Recursively yields every `.md` file under `rootDir`, parsed.
- * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
- * bodyColumn }` for each match — the last two from
- * {@link parseMarkdownFile}, so a caller can report a position inside the
- * body as a position in the file (#17).
- * Silently skips directories that don't exist.
- *
- * Directory names in `skipDirectories` are ignored wherever they appear. The
- * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
- * templater convention this repository's vault happens to use, not a property
- * of a content tree, so it is configured rather than hard-coded (#1508).
- *
- * @param {string} rootDir - Root of the tree to walk.
- * @param {object} [opts]
- * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
- *   Defaults to the configured list.
- */
 /**
  * Refuse a corpus read whose scope its caller did not state.
  *
- * The rule of #243 in one place, so every reader of the tree refuses the same
+ * The rule in one place, so every reader of the tree refuses the same
  * way and says so in the same words. It is shared rather than repeated because
  * the corpus is no longer read only by {@link walkMarkdownTree}: a pass that
  * reads the content index instead is making the identical claim about which
@@ -68,7 +50,7 @@ export function assertStatedScope(skipDirectories: readonly string[] | undefined
  * cycle. They take the records their caller already holds.
  *
  * That is not a workaround dressed up as a rule. A compile runs several passes
- * over one tree, and the whole of #243 is that they must not each answer "which
+ * over one tree, and the whole point is that they must not each answer "which
  * files are the corpus?" for themselves. Requiring the answer to be handed in
  * makes the sharing structural rather than remembered.
  *
@@ -78,8 +60,35 @@ export function assertStatedScope(skipDirectories: readonly string[] | undefined
  * @returns {void}
  */
 export function assertSuppliedCorpus(records: readonly object[] | undefined, who: string): void;
-export function walkMarkdownTree(rootDir: any, { skipDirectories }?: {}): Generator<{
-    file: string;
+/**
+ * Recursively yields every `.md` file under `rootDir`, parsed.
+ *
+ * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
+ * bodyColumn }` for each match — the last from {@link parseMarkdownFile}, so a
+ * caller can report a position inside the body as a position in the file. A
+ * root that does not exist yields nothing, and a directory that cannot be read
+ * is warned about and skipped.
+ *
+ * Directory names in `skipDirectories` are ignored wherever they appear. The
+ * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
+ * templater convention this repository's vault happens to use, not a property
+ * of a content tree, so it is stated by the caller rather than hard-coded.
+ *
+ * @param {string} rootDir - Root of the tree to walk.
+ * @param {object} opts
+ * @param {readonly string[]} opts.skipDirectories - Directory names to ignore.
+ *   Required: the scope is the caller's to state, so two passes cannot
+ *   disagree about which files are the corpus.
+ * @yields {{frontmatter: object|null, body: string, description: string,
+ *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
+ *   One entry per `.md` file found.
+ * @throws {Error} When `skipDirectories` is not stated — see
+ *   {@link assertStatedScope}.
+ */
+export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
+    skipDirectories: readonly string[];
+}): Generator<{
+    file: string & NonSharedBuffer;
     absPath: string;
     frontmatter: null;
     body: string;
@@ -87,7 +96,7 @@ export function walkMarkdownTree(rootDir: any, { skipDirectories }?: {}): Genera
     bodyLine?: undefined;
     bodyColumn?: undefined;
 } | {
-    file: string;
+    file: string & NonSharedBuffer;
     absPath: string;
     frontmatter: any;
     body: string;
@@ -97,7 +106,7 @@ export function walkMarkdownTree(rootDir: any, { skipDirectories }?: {}): Genera
 }, void, unknown>;
 /**
  * The template priority a note states, for a system that treats an unstated one
- * as "not a template" rather than as an authoring error (#266).
+ * as "not a template" rather than as an authoring error.
  *
  * Reads exactly the positions {@link resolveTemplatePriority} reads, including
  * the retiring `archetype` spelling, and refuses the same contradiction — so
@@ -119,7 +128,7 @@ export function statedTemplatePriority(fm: object, label: string, { block }?: {
 }): number | null;
 /**
  * Resolve the required `templatePriority` frontmatter for an Item/Actor entry
- * (the archetype contract, #604). The property is a nullable number that
+ * (the archetype contract). The property is a nullable number that
  * authors must state explicitly:
  *   - a number → the document is a template of that priority.
  *   - `null`   → the document is not a template.
@@ -128,7 +137,7 @@ export function statedTemplatePriority(fm: object, label: string, { block }?: {
  *
  * Reads the positions {@link findTemplatePriority} lists: `data.templatePriority`
  * first — the specified home — then the system block and the top level, and
- * finally the retiring `archetype` spelling in the same two places (#266).
+ * finally the retiring `archetype` spelling in the same two places.
  *
  * @param {object} fm      Parsed frontmatter.
  * @param {string} label   Human-readable context for error messages.
@@ -143,8 +152,7 @@ export function resolveTemplatePriority(fm: object, label: string, { block }?: {
 }): number | undefined;
 /**
  * The value a document's `system.templatePriority` carries, from the required
- * `templatePriority` frontmatter (#126, sohl#1780, renamed off `archetype` by
- * #266 / sohl#1836).
+ * `templatePriority` frontmatter (`archetype` is the legacy spelling).
  *
  * A **schema field**, so the tri-state is written out in full rather than
  * expressed by a key's presence: a number is a template at that priority, and
@@ -174,7 +182,7 @@ export function makeFilename(name: any, id: any): string;
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
  * work for Foundry, the knowledgebase, and the website. **Its first segment
- * says which package owns the file** (#331), and there are exactly three
+ * says which package owns the file**, and there are exactly three
  * answers:
  *
  * | Authored path starts with | Owner                 | Emitted              |
@@ -186,7 +194,7 @@ export function makeFilename(name: any, id: any): string;
  * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
  * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
  * root is derived from the configuration, and is the one place `systems/sohl`
- * is ever spelled (#1508). An authored
+ * is ever spelled. An authored
  * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
  * whichever package is compiling it.
  *
@@ -197,13 +205,13 @@ export function makeFilename(name: any, id: any): string;
  * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
  * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
  * own tree is the fact; the directory names inside it are that package's
- * business (#331).
+ * business.
  *
  * **Off-install addresses pass through too**, which is the same rule rather
  * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
  * package owns. See {@link addressesAnotherPackage}.
  *
- * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * **`banner:` does not follow this rule, deliberately.** It is not an
  * asset path inside a Foundry install at all: it reaches no compiled document,
  * and its only consumer is the Hugo theme, which prefixes a relative value with
  * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
@@ -211,7 +219,7 @@ export function makeFilename(name: any, id: any): string;
  * the CDN serves — so they are documented apart rather than reconciled into one
  * rule that would be true of neither.
  *
- * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * **Two empties, and they mean opposite things.** `null` — or an absent
  * key, which reaches here as `undefined` — means _unset_: the note names no art
  * and the caller's default applies. `""` means _blank on purpose_: the note
  * names no art **and wants none**, so no default may replace it. Both come back
@@ -230,7 +238,7 @@ export function makeFilename(name: any, id: any): string;
  * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
  * key the site emitter reads as the page title — so `title: null` stringifies
  * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means; see #218.
+ * that disagree about what empty means; see.
  *
  * This is translation only: the default for an unset path is domain-specific
  * (actors default differently from items, and gear differently again), so each
@@ -241,14 +249,22 @@ export function makeFilename(name: any, id: any): string;
  * `itemArt()`, which runs the path back through this function so a registry
  * entry and a note's `img:` are spelled the same way (#7).
  *
+ * **A package with no asset root cannot answer at all.** `assetRoot` is derived
+ * from the package kind, and a `documentation` package has none: Foundry serves
+ * no files for it. Only a compiling pass reaches here, and a documentation
+ * package runs none, so a path arriving with no root to put it under is a pass
+ * running where it should not — reported as that, rather than emitted as
+ * `null/icons/relic.svg` into a document nobody would check.
+ *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
- * @param {{assetRoot: string}} [config] - The resolved build configuration.
+ * @param {{assetRoot: string|null}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
  * @returns {string | null} the Foundry-relative path; `""` for a deliberate
  *   blank, and `null` when the note names no art at all.
+ * @throws {Error} When the configuration has no asset root.
  */
 export function resolveImg(raw: string | null | undefined, config?: {
-    assetRoot: string;
+    assetRoot: string | null;
 }): string | null;
 /**
  * Resolves the display name from frontmatter, preferring `name.full`,
@@ -263,7 +279,7 @@ export function resolveName(fm: any, defaultValue?: string): any;
  * its migration shims on: a record stamped older than a shim is rewritten by it
  * on load. Every pack once shipped `coreVersion: "14"`, which sorts *below*
  * every v14 build and so left all shipped content permanently eligible for
- * every v14 migration (#1533).
+ * every v14 migration.
  *
  * **Read from the configuration, not from the shipped manifest.** It used to
  * open `paths.packageManifest` and take `compatibility.minimum` out of it,
@@ -289,7 +305,7 @@ export function supportedCoreVersion(config?: {
 /**
  * Default `_stats` block for compiled compendium entries.
  *
- * Every stamped identity is configuration (#1508): four compilers used to pass
+ * Every stamped identity is configuration: four compilers used to pass
  * the same frozen `"0.6.0"` literal, and `systemId` / `lastModifiedBy` were
  * written into this function. `coreVersion` alone is *not* configuration — it
  * comes from {@link supportedCoreVersion}, the configured Foundry floor,
@@ -313,13 +329,12 @@ export function buildStats(systemVersion?: string, config?: {
     };
 }): object;
 /**
- * The `_stats` block for one pack, stamped with the system that pack is for
- * (#48).
+ * The `_stats` block for one pack, stamped with the system that pack is for.
  *
  * **`systemId` travels with `systemVersion`.** They are one decision, so where
  * one is omitted both are. Stamping a per-pack version against a package-wide
  * id would emit `systemId: sohl, systemVersion: 1.6.3` on HM3 documents — a
- * *plausible lie*, which is worse than the missing value #43 fixed, because
+ * *plausible lie*, which is worse than a missing value, because
  * nothing about it looks wrong.
  *
  * Resolution, in order:
@@ -358,11 +373,11 @@ export function defaultStats(): object;
  *
  * Each note's pack is resolved here, once, and stored on its index entry: a
  * UUID carries a pack name, so a repository shipping several packs of one type
- * (#1566) would otherwise address every one of them as the first. A note whose
+ * would otherwise address every one of them as the first. A note whose
  * declaration is unroutable is indexed against the conventional name and left
  * for the compile pass to report — the index has no business failing a build,
  * and the pass fails it with a far better message. The one exception is a
- * **retired** content type (SoHL#1580): this walk is the first to see every
+ * **retired** content type: this walk is the first to see every
  * note together with its path, and unlike an unroutable declaration there is
  * no pass that would ever claim such a note and report it.
  *
@@ -370,9 +385,23 @@ export function defaultStats(): object;
  * @param {object} [router] - The pack router. Supplied by the calling pass so
  *   the index and the compile agree about where each note landed; defaults to
  *   this repository's own.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
+ *   every corpus reader takes; the scope is already settled by `records`.
+ * @param {object} [opts.config] - The resolved build configuration; loaded when
+ *   omitted.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once per
+ *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {object[]} [opts.problems] - Part of the same options bag; the notes
+ *   the index cannot record are collected where the corpus is derived.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase: string, router?: object, { skipDirectories, config, records, problems }?: {}): {
+export function buildContentLinkIndex(contentBase: string, router?: object, { skipDirectories, config, records, problems }?: {
+    skipDirectories?: readonly string[] | undefined;
+    config?: object | undefined;
+    records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
+}): {
     byShortcode: Map<any, any>;
     types: Set<any>;
 };
@@ -381,25 +410,49 @@ export function buildContentLinkIndex(contentBase: string, router?: object, { sk
  * target in the content tree. Every compiler funnels through this so the
  * diagnostic text and the leave-it-alone fallback are identical everywhere.
  *
- * Each report names the **file, line and column** the link sits on (#17), so
+ * Each report names the **file, line and column** the link sits on, so
  * it can be opened and fixed — and so two identical links on one note are
  * tellable apart. That needs `file` and the note's `bodyLine` / `bodyColumn`;
  * without them the diagnostic still reports, one field shorter, rather than
  * inventing a position.
  *
  * @param {string} body - The note's markdown body, tables already expanded.
- * @param {object} ctx - `{ type, id, pack, docPack, index, name }` — `name` is
- *   used in the message, and the two pack names address a `[[#slug]]`
- *   self-link, whose target is the source note itself and so has no index
- *   entry. Position is carried by `{ file, bodyLine, bodyColumn, lineMap }`,
- *   the last from {@link expandNoteTables}.
+ * @param {object} ctx
+ * @param {string} ctx.type - The source note's content type.
+ * @param {string} ctx.id - The source note's document id.
+ * @param {string} ctx.pack - The pack the note's own document lands in, which
+ *   addresses a `[[#slug]]` self-link: its target is the source note itself, so
+ *   it has no index entry.
+ * @param {string} ctx.docPack - The pack the note's documentation journal lands
+ *   in, addressing a self-link the same way.
+ * @param {object} ctx.index - The address index every link resolves through.
+ * @param {string} ctx.name - The note, for the message.
+ * @param {string} [ctx.file] - The note's file, so a report names it.
+ * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line.
+ * @param {number} [ctx.bodyColumn] - 1-based file column of the same character.
+ * @param {Array<{line: number, generated: boolean}>} [ctx.lineMap] - Which
+ *   authored line each body line came from, from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
  * @throws {Error} On any link that does not resolve — an unlabelled one, a
  *   target that is not an address, or an address nothing publishes. The error
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */
-export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap }: object): {
+export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap }: {
+    type: string;
+    id: string;
+    pack: string;
+    docPack: string;
+    index: object;
+    name: string;
+    file?: string | undefined;
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    lineMap?: {
+        line: number;
+        generated: boolean;
+    }[] | undefined;
+}): {
     markdown: string;
     unresolved: Array<object>;
 };
@@ -409,10 +462,24 @@ export function convertNoteWikilinks(body: string, { type, id, pack, docPack, in
  * a table that leaves rows tied still emits identically on every build.
  *
  * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
+ *   every corpus reader takes; the scope is already settled by `records`.
+ * @param {object} [opts.config] - The resolved build configuration; loaded when
+ *   omitted.
+ * @param {readonly object[]} [opts.records] - The corpus, derived once per
+ *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {object[]} [opts.problems] - Part of the same options bag; the notes
+ *   the walk cannot read are collected where the corpus is derived.
  * @returns {Array<{fm: object, path: string, tld: string, folder: string,
  *   absPath: string}>}
  */
-export function collectContentDocs(contentBase: string, { skipDirectories, config, records, problems }?: {}): Array<{
+export function collectContentDocs(contentBase: string, { skipDirectories, config, records, problems }?: {
+    skipDirectories?: readonly string[] | undefined;
+    config?: object | undefined;
+    records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
+}): Array<{
     fm: object;
     path: string;
     tld: string;
@@ -426,7 +493,7 @@ export function collectContentDocs(contentBase: string, { skipDirectories, confi
  * A table searches the whole tree, which is one package's notes and nothing
  * else — so there is no longer a package to scope on. It used to filter, back
  * when a tree could hold several packages' notes and `package:` said which was
- * which; that field is retired and the filter with it (#56).
+ * which; that field is retired and the filter with it.
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
@@ -436,10 +503,14 @@ export function collectContentDocs(contentBase: string, { skipDirectories, confi
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
  *   so a failing directive can be reported at its position in the file.
+ * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
+ *   document order, from
+ *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
+ *   no prepared result fails the note: nothing here runs a query.
  * @returns {{markdown: string, lineMap: Array<{line: number,
  *   generated: boolean}>}} The body with every table expanded, and where each
  *   emitted line came from — which is what lets a diagnostic about the
- *   expanded body name an authored position (#17).
+ *   expanded body name an authored position.
  * @throws {Error} When a query is malformed or unsupported — the note fails to
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
@@ -449,6 +520,7 @@ export function expandNoteTables(body: string, { docs, name, fm, bodyLine, sqlTa
     name: string;
     fm?: object | undefined;
     bodyLine?: number | undefined;
+    sqlTables?: object[] | undefined;
 }): {
     markdown: string;
     lineMap: Array<{
@@ -468,7 +540,7 @@ export function folderFilename(name: any, id: any): string;
  * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
  * it is also why {@link module:engine/content-icons} exists rather than an
  * instruction to write `<i class="fa-solid …">` by hand: that would render on
- * the two HTML surfaces and be silently dropped by the third (#378).
+ * the two HTML surfaces and be silently dropped by the third.
  */
 export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";

package/types/engine/homepage.d.mts

@@ -2,7 +2,7 @@
  * The file a homepage is written to, relative to the package's site root.
  *
  * Its **address**, flat at the package root, and stated in the page's own `url`
- * — the same separation every other page has since #181, where the directory
+ * — the same separation every other page has, where the directory
  * decides the Hugo section and the front matter decides the URL. Flat rather
  * than inside a `homepage/` section directory, because a homepage is not one of
  * a kind: a section holding exactly one page would publish a landing at
@@ -45,8 +45,8 @@ export function isHomepage(fm: object | null | undefined): boolean;
  * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
  * `fm.id` **in place** so every downstream reader sees one derived value —
  * deliberately, and documented as such — and this ran over the same object, so
- * a homepage that authors no `id` was told to delete one that is not there
- * (#319). Since the caller already owns the raw note text, it also answers
+ * a homepage that authors no `id` was told to delete one that is not there.
+ * Since the caller already owns the raw note text, it also answers
  * which keys the note actually declared; without an answer every key in `fm`
  * counts, which is the old behaviour and right for a caller holding authored
  * frontmatter only.
@@ -70,19 +70,17 @@ export function checkHomepageAddressFields(fm: object | null | undefined, { isAu
     message: string;
 }>;
 /**
- * Require exactly one homepage note in a content tree (#52).
+ * Require exactly one homepage note in a content tree.
  *
  * "Exactly one" is two rules, and they are **one severity** because they are
  * one defect: a package whose front page is not the page a person chose.
  *
  * - _None_ and the package serves nothing at `/<package>/`. That is the failure
- *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   this exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
  * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
- *   since #182 it is only that.** It used to rest on the fixed destination
- *   every homepage shared — the second overwrote the first — so the address
- *   rule enforced it as a side effect. A homepage is written at its own address
- *   now, so two of them publish two pages and collide over nothing; the
+ *   only that.** A homepage is written at its own address, so two of them
+ *   publish two pages and collide over nothing; the
  *   duplicate-address check catches only the pair that happen to share a
  *   shortcode, and says nothing at all about a `homepage-root` beside a
  *   `homepage-front`. Which of the two the redirect at `/<package>/` should
@@ -153,17 +151,17 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * The note's own, plus the derived values every emitted page carries: the
  * resolved `title`, the package the build derived — no note declares one
- * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * (`package:` is retired) and the theme's breadcrumb partial reads
  * `.Params.package` — and its **address**.
  *
  * The address is stated as `url` for the same reason every other page states
- * one (#181): Hugo publishes a page where its file sits unless told otherwise,
+ * one: Hugo publishes a page where its file sits unless told otherwise,
  * and a homepage's file sits at the package's site root. `slug` is written
  * beside it because it is the last segment of that address and Hugo's own key
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
- * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * **Site-root relative, and so carrying no package base**, exactly as
  * `pageFrontmatter` states a content page's: Hugo resolves a `url`
  * against `baseURL`, whose path is already where the package is served, so a
  * stated base was written twice and published the landing at
@@ -172,7 +170,7 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
- * redirect stub at each one. The field is retired (#180) and refused before a
+ * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
  * @param {object} fm - The note's frontmatter.
@@ -252,14 +250,14 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  */
 export const HOMEPAGE_SHORTCODE: string;
 /**
- * The top-level field a homepage refuses, and what it would decide (#53).
+ * The top-level field a homepage refuses, and what it would decide.
  *
- * **One field, where there used to be three.** `name` and `shortcode` were
+ * **One field rather than three.** `name` and `shortcode` are
  * refused because a page's URL derived from `name.full` while a homepage's
  * destination was fixed, so the address a `shortcode` computed named a page the
- * site build never wrote. A page's URL is its address now (#181) and a homepage
+ * site build never wrote. A page's URL is its address now and a homepage
  * publishes at its own, so both fields decide exactly what they decide
- * everywhere else and are permitted (#182).
+ * everywhere else and are permitted.
  *
  * `id` is untouched by that, and stays: it is the Foundry document id a
  * compendium UUID is built from, and a homepage compiles into no document.
@@ -272,7 +270,7 @@ export const HOMEPAGE_SHORTCODE: string;
  * package-build release.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
- * on every note whatever its type (#180), so it is answered there rather than
+ * on every note whatever its type, so it is answered there rather than
  * here.
  *
  * @type {ReadonlyMap<string, string>}

package/types/engine/ids.d.mts

@@ -56,12 +56,12 @@ export function renamedTypeMessage(retired: string, current: string, where?: str
  * Item types are the open set — a new one is added whenever the system grows a
  * document type — so they are the **default** rather than an enumerated list. A
  * hand-maintained list is what made an entire content directory silently
- * unlinkable once (#1276); nothing to maintain, nothing to forget.
+ * unlinkable once; nothing to maintain, nothing to forget.
  *
  * The `docType` is the authority: it is a property of the *content type* and
  * holds however a repository names or splits its packs. The `pack` is the
  * conventional name only — a repository may rename its packs, or ship several
- * of one type (#1566), in which case the pack a particular note's document
+ * of one type, in which case the pack a particular note's document
  * lands in comes from `engine/pack-router.mjs` and is passed to
  * {@link compendiumUuid} explicitly. This module stays free of the
  * configuration so the link resolver above it can stay pure.
@@ -89,8 +89,8 @@ export function packForType(type: string): {
  * @param {string} id - The document's id.
  * @param {string} [packName] - The pack the document actually landed in, from
  *   the pack router. Supplied wherever the note is known, because a repository
- *   may ship several packs of one type and a UUID carries the pack name
- *   (#1566). Omitted only where there is no note to route — the conventional
+ *   may ship several packs of one type and a UUID carries the pack name.
+ * Omitted only where there is no note to route — the conventional
  *   name from {@link packForType} then stands in.
  * @returns {string} `Compendium.<packageId>.<pack>.<DocumentType>.<id>`
  */
@@ -105,8 +105,8 @@ 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**
- * (#1525). The three differ only in derived canvas defaults, which is the map
+ * 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.
  *
  * Declared in this leaf module because several passes that must not depend on
@@ -120,7 +120,7 @@ export const MAP_TYPES: ReadonlySet<string>;
 /**
  * The map subTypes, which differ only in the canvas defaults derived for them.
  *
- * They were three *types* until #174, which cost three entries in the pack
+ * 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.
  *
@@ -137,8 +137,8 @@ export const MAP_SUBTYPES: readonly string[];
  * addressed as `<type>` and `doc<type>`. These are one, so there is no
  * `docplace` and nothing synthesizes one.
  *
- * `doc` was the only member until #241. `place`, `lore` and `scenario` are in
- * the published content format and were declared for validation in #233, but
+ * `doc` was the only member until. `place`, `lore` and `scenario` are in
+ * the published content format and are declared for validation, but
  * nothing routed them: a note of one lint-ed clean and then compiled into
  * nothing, because {@link PACK_BY_TYPE} did not name it and the open-set
  * default sent it to the items pack. `sohl-thalorna` could not compile a single
@@ -157,7 +157,7 @@ export const JOURNAL_TYPES: ReadonlySet<string>;
  * building and not of the content: the same notes compiled by a different
  * repository belong to a different package. Baking the package into these
  * values is what made every link emitted by `sohl-thalorna` address the `sohl`
- * system (#1498) — correct here only by coincidence.
+ * system — correct here only by coincidence.
  *
  * @type {Readonly<Record<string, {pack: string, docType: string}>>}
  */
@@ -169,7 +169,7 @@ export const PACK_BY_TYPE: Readonly<Record<string, {
  * Content types that no longer exist, and what replaced each one.
  *
  * `character` and `creature` were retired in favour of the single `being` they
- * had always compiled into (SoHL#1580). They are recorded here rather than
+ * had always compiled into. They are recorded here rather than
  * simply deleted because deleting them is the one change that fails *quietly*:
  * every type not named in {@link PACK_BY_TYPE} falls through to the open item
  * set below, so a note or a link left on the old spelling would be routed to
@@ -193,7 +193,7 @@ export const RETIRED_TYPES: Readonly<Record<string, string>>;
  * old one compiles into exactly the document it always did: refusing it would
  * fail a build over a note that is not wrong.
  *
- * So these retire in the three steps `package:` took (#56), and this table is
+ * So these retire in the three steps `package:` took, and this table is
  * the **first**: both spellings resolve, the current one is canonical, and the
  * retired one is *reported* — never refused. The sweep of the content trees and
  * the refusal come after, once no tree writes the old name. That is the same
@@ -201,7 +201,7 @@ export const RETIRED_TYPES: Readonly<Record<string, string>>;
  * reason: a consumer must be able to adopt the new toolchain before its content
  * moves, and there are some 31,000 references to move.
  *
- * **Why these three, and why the other way round now.** #78 renamed
+ * **Why these three, and why this way round.** The specification renamed
  * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
  * and `projectile`, on the argument that the suffix named the *SoHL document
  * subtype* a note compiled into rather than the thing the note is about. That

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

@@ -6,9 +6,9 @@
  * the machine that built the index, would differ between two checkouts of the
  * same tree, and would put someone's home directory in a published artifact. So
  * every pass that reads the index and then needs to open a note has to compose
- * the absolute form, and each of the readers converted for #243 had written its
+ * the absolute form, and each converted reader had written its
  * own `path.join(base, ...record.file.path.split("/"))`. Four copies of one
- * rule is what #243 exists to remove, so here it is once.
+ * rule is what this exists to remove, so here it is once.
  *
  * The split is on `"/"` rather than `path.sep` because the recorded path is
  * always POSIX — that is what makes the index identical on every platform.
@@ -54,7 +54,7 @@ export function isNoteRecord(record: Record<string, any>): boolean;
  * carry itself.
  *
  * `package` is the note's distribution unit — the configured `contentPackage`,
- * since a note declaring its own is a hard error (#56) — and it matches what
+ * since a note declaring its own is a hard error — and it matches what
  * the content-table expander puts on the same field, so a query reads the same
  * value from either. `file` namespaces the note's place in the tree, again
  * matching the expander's `file.*`.

package/types/engine/index.d.mts

@@ -11,6 +11,7 @@ export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
 export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
+export * as derivedFields from "./derived-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
@@ -27,6 +28,7 @@ export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
+export * as contentHtml from "./content-html.mjs";
 export * as contentLinks from "./content-links.mjs";
 export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";
@@ -37,6 +39,10 @@ export * as itemDocs from "./item-docs.mjs";
 export * as wikilinks from "./wikilinks.mjs";
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
 export * as siteIndex from "./site-index.mjs";
+export * as pdfToc from "./pdf-toc.mjs";
+export * as pdfRender from "./pdf-render.mjs";
+export * as pdfFonts from "./pdf-fonts.mjs";
+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";