@heroiclands/package-build 20.6.0 → 21.0.0

package/types/engine/pathnames.d.mts

@@ -0,0 +1,189 @@
+/**
+ * What is wrong with an authored pathname, or `""` when nothing is.
+ *
+ * Config-free, and a sentence rather than a code, so the lint that has a line
+ * and a column to attach it to and the resolver that has only a file say the
+ * same thing about the same value.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function pathnameProblem(raw: string | null | undefined): string;
+/**
+ * Every content package this build can resolve a pathname against.
+ *
+ * The package being built; every game system it compiles content for, which
+ * Foundry serves from `systems/<id>`; and every other package it declares a
+ * relationship with, which states that package's Foundry id and — where the two
+ * words differ — what its content is called.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Map<string, {root: string|null, id: string|null, own: boolean}>} The
+ *   packages, by content package name. `root` is the Foundry directory the
+ *   package is served from, `null` where the package ships no Foundry package.
+ */
+export function packageAddresses(config: object): Map<string, {
+    root: string | null;
+    id: string | null;
+    own: boolean;
+}>;
+/**
+ * Resolve one authored pathname into the address each surface serves.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @param {object} config - The resolved build configuration. Required rather
+ *   than defaulted, which is what keeps this module a leaf: it reads a
+ *   configuration and never loads one, so the lint can import it without a
+ *   repository to resolve.
+ * @returns {PathnameForms|null} The four forms, or `null` when the note names
+ *   no file at all.
+ * @throws {Error} When the pathname is written in Foundry's own spelling, which
+ *   resolves on one surface and nowhere else.
+ */
+export function resolvePathname(raw: string | null | undefined, config: object): PathnameForms | null;
+/**
+ * One authored pathname, and the four addresses it resolves to.
+ *
+ * A note names a file once — in `img:`, in `data.portrait:`, in the body of a
+ * markdown image — and four surfaces have to serve it: a Foundry install, this
+ * repository's own working tree, the website, and the book. Each addresses the
+ * same file differently, so the authored pathname is a *statement of
+ * ownership* and every surface derives its own address from it. One statement,
+ * four derivations, one rule.
+ *
+ * ## The rule
+ *
+ * **The first segment says which package owns the file, when it is followed by
+ * `assets/`.** Everything after `assets/` is the *suffix* — the path inside
+ * that package's shipped tree, and the one piece every form is built from.
+ *
+ * | Authored                    | Owner            | Suffix              |
+ * | --------------------------- | ---------------- | ------------------- |
+ * | `sohl/assets/icons/a.svg`   | the `sohl` package | `icons/a.svg`     |
+ * | `images/beings/b.webp`      | **this** package | `images/beings/b.webp` |
+ *
+ * A pathname that does not open with `<package>/assets/` belongs to the package
+ * being built, and the whole of it is the suffix. That is the ordinary case and
+ * the one nearly every note writes.
+ *
+ * The four forms, for a `thalorna` note writing `images/map.webp` (`thalorna`
+ * ships as the Foundry module `sohl-thalorna`):
+ *
+ * | Form      | Address                                            |
+ * | --------- | -------------------------------------------------- |
+ * | `foundry` | `modules/sohl-thalorna/assets/images/map.webp`      |
+ * | `local`   | `assets/images/map.webp`                            |
+ * | `web`     | `https://cdn.heroiclands.org/thalorna/images/map.webp` |
+ * | `pdf`     | `assets/images/map.webp`                            |
+ *
+ * **`<package>` and `<foundry-id>` are two different names.** The package is
+ * `thalorna` — what the content is called, what the website serves it under,
+ * and what a note writes. The Foundry id is `sohl-thalorna` — what Foundry
+ * installs the module as, and the only place that name appears. They coincide
+ * for `sohl` and `hm3`, which is exactly why the two are kept apart here rather
+ * than treated as one value.
+ *
+ * `local` and `pdf` read the same and mean different places: `local` is the file
+ * in the owning repository's working tree, `pdf` is where the book stages a copy
+ * beside its Typst source. They are derived separately because only one of them
+ * is a file a build may open — see {@link PathnameForms.own}.
+ *
+ * ## What is not a package pathname
+ *
+ * **An off-install address passes through on every surface**: a URL, a
+ * protocol-relative `//host/…`, or a `/`-rooted path, which Foundry serves from
+ * the data root and which names no package at all. That is how a note addresses
+ * core Foundry art (`/icons/svg/mystery-man.svg`) or a package this build knows
+ * nothing about (`/systems/dnd5e/icons/spell.webp`).
+ *
+ * **A package this build has never heard of keeps its ownership.** The website
+ * and the book need only the package's name and the suffix, so both resolve;
+ * the Foundry address needs the package's kind and its Foundry id, which only a
+ * declared relationship carries, so that one form comes back `null` and the
+ * caller that needs it refuses. Reading such a pathname as this package's own
+ * would file one package's name inside another's tree and say nothing.
+ *
+ * **A `systems/…` or `modules/…` pathname is refused.** It is a Foundry address
+ * written where an ownership statement belongs: it resolves for Foundry and for
+ * nothing else, because neither the website nor the book has any such directory.
+ * {@link pathnameProblem} names the replacement, and every surface refuses the
+ * value rather than deriving an address from it — a wrong address that resolves
+ * to a 404 is the failure this module exists to remove, and inventing one here
+ * would reintroduce it one directory along.
+ *
+ * ## The two empties
+ *
+ * `null` — or an absent key, which arrives as `undefined` — means **unset**: the
+ * note names no file and the caller's default applies. `""` means **blank on
+ * purpose**: the note names no file and wants none, so no default may replace
+ * it. `resolvePathname` returns `null` for the first and a form object whose
+ * every address is `""` for the second, so the two stay distinguishable all the
+ * way to the caller.
+ *
+ * @module
+ */
+/**
+ * The directory a package ships its files in, and the segment that marks a
+ * pathname's first segment as a package name.
+ *
+ * One constant rather than a literal in six places: it is the second segment of
+ * an authored package pathname, the last segment of a Foundry asset root, the
+ * whole of the `local` form's prefix, and the directory the book stages into.
+ *
+ * @type {string}
+ */
+export const ASSETS_SEGMENT: string;
+/**
+ * The surfaces one authored pathname resolves for.
+ *
+ * Exported so a test can assert that every form a resolution carries is one of
+ * these, and that none is missing — the guard against a fifth surface being
+ * added to one caller and forgotten in the resolver.
+ *
+ * @type {readonly string[]}
+ */
+export const PATHNAME_SURFACES: readonly string[];
+/**
+ * One authored pathname, resolved.
+ */
+export type PathnameForms = {
+    /**
+     * The pathname exactly as the note wrote it.
+     */
+    authored: string;
+    /**
+     * `blank` for `""`, `external`
+     * for an address no package owns, `package` for an owned file.
+     */
+    state: "blank" | "external" | "package";
+    /**
+     * The content package that owns the file, or
+     * `null` when no package does.
+     */
+    package: string | null;
+    /**
+     * The path inside that package's shipped tree.
+     */
+    suffix: string | null;
+    /**
+     * Whether the owner is the package being built, and so
+     * whether `local` names a file this build may open.
+     */
+    own: boolean;
+    /**
+     * The address inside a Foundry install.
+     */
+    foundry: string | null;
+    /**
+     * The file in the owning repository's tree.
+     */
+    local: string | null;
+    /**
+     * The address the website serves.
+     */
+    web: string | null;
+    /**
+     * Where the book stages its copy.
+     */
+    pdf: string | null;
+};

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

@@ -1,3 +1,49 @@
+/**
+ * The file on disk an authored image pathname names, or `null`.
+ *
+ * Two of the four forms {@link module:engine/pathnames.resolvePathname}
+ * derives, used together: `local` is the file in this repository's own tree,
+ * and `pdf` is where the book stages a copy of it.
+ *
+ * **Typst decides where that copy goes.** It resolves a path against its root —
+ * the directory holding the source it is given — and refuses to read anything
+ * above it. So a file reaches the compiler by being copied under the output
+ * directory rather than by widening the root to the whole repository: the
+ * emitted `.typ` and everything it opens sit in one directory, which is what
+ * makes the source a consumer can compile by hand with no flags, and what keeps
+ * a build from touching a path outside its own output.
+ *
+ * Only a file **this** package ships can be staged. A pathname naming another
+ * package's file, or a URL, names something no build here can open — a build
+ * reaches no network — and the caller reports it as a picture the book will not
+ * carry.
+ *
+ * @param {string} src - The pathname, as authored.
+ * @param {object} config - The resolved configuration.
+ * @returns {{from: string, to: string}|null} The file, and where under the
+ *   output directory it is staged.
+ */
+export function stagedImagePath(src: string, config: object): {
+    from: string;
+    to: string;
+} | null;
+/**
+ * Copy every banner the document tree names into the output directory.
+ *
+ * **A missing banner is not a failure.** A section plate implies a banner per
+ * section and art arrives later than rendering does, so a section that names
+ * none draws its plate over the book's ink and says nothing about it. One that
+ * names a file the build cannot read is a different matter — that is a
+ * statement the tree makes and the build cannot honour — and it is reported.
+ *
+ * @param {object[]} entries - The plan's entries.
+ * @param {object} config - The resolved configuration.
+ * @param {string} outDir - Where the book is written.
+ * @param {object[]} findings - Collected here rather than thrown.
+ * @returns {Map<string, string>} Declared path → the staged file's path,
+ *   relative to the `.typ`.
+ */
+export function stageBanners(entries: object[], config: object, outDir: string, findings?: object[]): Map<string, string>;
 /**
  * The file name a downloaded book identifies itself by.
  *

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

@@ -47,10 +47,17 @@ export function createParser(registry?: object): object;
  * @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 {Map<string, string>} [opts.images] - An image's address as authored →
+ *   the staged file's path, relative to the `.typ`. An address this does not
+ *   carry has no file the compiler can open, so the figure prints its caption
+ *   alone — see {@link renderImage}.
  * @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.
+ * @param {boolean} [opts.dropCap] - Whether to open the body with a raised
+ *   capital. Set for an entry, which begins a page; not for front matter or a
+ *   prose file, which carry headings of their own.
  * @returns {string} Typst markup.
  */
 export function markdownToTypst(markdown: string, opts?: {
@@ -58,9 +65,51 @@ export function markdownToTypst(markdown: string, opts?: {
     registry?: object | undefined;
     links?: Map<string, string> | undefined;
     glyphs?: Map<string, string> | undefined;
+    images?: Map<string, string> | undefined;
     headingOffset?: number | undefined;
     anchorPrefix?: string | undefined;
+    dropCap?: boolean | undefined;
 }): string;
+/**
+ * The Typst definitions the book's page furniture is drawn with.
+ *
+ * Emitted once at the head of the document, for the reason the infobox panel's
+ * rules are: 2,000 entries each restating the plate, the running foot and the
+ * drop cap is a megabyte of repetition, and the one place a reader changes how
+ * the book looks should be one place.
+ *
+ * ## The geometry is stated, not discovered
+ *
+ * The page is US Letter with a 1.9cm margin, and the plate bleeds off all
+ * three edges it touches — so the plate has to know the paper's width and the
+ * margin it is escaping. Both are `#let` bindings here rather than numbers
+ * repeated down the file, and every other measure is arithmetic on them.
+ *
+ * ## Three things that cost time to discover, encoded here
+ *
+ * - **A title inherits the body's justification and hyphenation** unless told
+ *   otherwise. Both are habits of body text that make a display line look
+ *   broken, so the plate turns them off inside itself.
+ * - **The plate's height follows its title**, and the line count is derived
+ *   from the title's *natural* width: measuring an already-wrapped block does
+ *   not report the wrapped height, and a percentage width cannot resolve
+ *   inside `measure`. So the title arrives as a string to be measured
+ *   alongside the heading that is actually drawn.
+ * - **A float is not breakable.** A table taller than the page placed as one
+ *   silently piles its rows on top of each other at the foot of the page —
+ *   no warning, no error. So `book-wide` measures first and gives a table that
+ *   will not fit its own single-column pages instead.
+ *
+ * ## The ornament is drawn, not typed
+ *
+ * The running foot's centre mark is a rotated square rather than a dingbat
+ * character, because the faces a consumer names and the faces a build runner
+ * carries are not the same set, and a missing glyph on 2,000 feet is a
+ * tofu box on every page of the book.
+ *
+ * @returns {string} Typst markup.
+ */
+export function bookTypstPreamble(): string;
 /**
  * The whole book, as one Typst document.
  *
@@ -96,6 +145,46 @@ export function markdownToTypst(markdown: string, opts?: {
  * `#outline()` needs no depth limit under this model: what prints is decided
  * per heading, not by how deep the tree happens to go.
  *
+ * ## An entry owns its page, and the page is set in two columns
+ *
+ * A reference book is consulted rather than read through. An entry beginning
+ * halfway down a page is harder to find, cannot carry its own running head
+ * honestly, and makes a page number in the contents point at the middle of
+ * something else — so every entry opens a page of its own, under a full-bleed
+ * plate carrying a kicker and its name.
+ *
+ * The body is set in **two columns**, the measure a reference work wants and
+ * the one every other decision follows from: an image with no width class is a
+ * column wide, the infobox flows in the column measure and breaks between its
+ * sections, and a table wider than {@link WIDE_TABLE_COLUMNS} spans the page.
+ * The columns are the *page's* rather than a `columns()` block's, because only
+ * a page with columns can carry a float that spans them — which is what the
+ * plate, a wide table and a full-width figure all need.
+ *
+ * Two columns are print's answer and print's alone: a scrolling page has no
+ * fixed viewport, so the website keeps one measure.
+ *
+ * ## What a section declares, its entries inherit
+ *
+ * {@link module:engine/pdf-toc.PRESENTATION_KEYS} travels down the document
+ * tree, and two of those keys are read here:
+ *
+ * - **`page`** — `banner:`, the plate's picture; `kicker:`, the line above an
+ *   entry's name; and `columns:`, the measure the section's pages are set in.
+ * - **`footer`** — the name the running foot carries, which is the section's
+ *   own title when nothing says otherwise.
+ *
+ * `header` and `infobox` are reserved and read by nothing: the running head is
+ * a foot in this design, and which infobox a note draws is decided by the
+ * note's type.
+ *
+ * ## A missing banner is a plate without a picture
+ *
+ * A section plate implies a banner per section, and art arrives later than
+ * rendering does. A section that names no banner — or names one the build
+ * cannot read — still gets its plate, its kicker and its title, set over the
+ * book's ink.
+ *
  * ## Headings carry the structure, so nothing else has to
  *
  * Every section, every prose file and every entry is a real Typst heading at
@@ -113,9 +202,16 @@ export function markdownToTypst(markdown: string, opts?: {
  * @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.
+ * @param {string} [opts.preamble] - Definitions the bodies call, emitted once
+ *   above the title page. A panel every entry draws is a set of rules stated
+ *   here rather than repeated 2,500 times.
+ * @param {Map<string, string>} [opts.banners] - A banner as the document tree
+ *   declared it → the staged file's path, relative to the `.typ`. A declared
+ *   banner this map does not carry has no file the compiler can open, so the
+ *   plate draws without a picture.
  * @returns {string} A complete `.typ` document.
  */
-export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, }?: {
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners, }?: {
     plan: object;
     bodies: Map<string, string>;
     title: string;
@@ -123,6 +219,8 @@ export function renderBook({ plan, bodies, title, subtitle, front, fonts, versio
     front?: string[] | undefined;
     fonts?: object | undefined;
     version?: string | undefined;
+    preamble?: string | undefined;
+    banners?: Map<string, string> | undefined;
 }): string;
 /**
  * Point every internal link at a label the document actually declares.

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

@@ -103,11 +103,16 @@ export function planDocument(nodes: object[], { selections }?: {
 /**
  * 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.
+ * Inheritance is what makes them worth declaring at all — `Gear` says once
+ * which banner its entries are plated over, and nine sections beneath it
+ * agree.
+ *
+ * **`page` and `footer` are read by the renderer**, and their shapes are
+ * checked here so that a key nothing can act on is an error rather than a
+ * silence. `header` and `infobox` are reserved and read by nothing: the
+ * running head is a foot in this design, and which infobox a note draws is
+ * decided by the note's type. They keep their place in the format because the
+ * shape of the file is the thing consumers commit to.
  *
  * @type {readonly string[]}
  */

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

@@ -36,6 +36,14 @@ export function collectContentPages(contentBase: string, ctx: object): {
  * addressed by type and slug: they are a book with chapters, and a reader
  * follows their paths. A `README` is its directory's landing.
  *
+ * **The section is the tree's, never the note's.** `tree.section` is the
+ * mount point a `trees` entry configures — fixed, physical, and the same
+ * value `site-index.mjs` indexes a tree page's address under. A note's own
+ * `subType` is a genre and reaches no address, the same contract
+ * `packageAddress()` holds for a content page: reading it here would move a
+ * page's URL, its file destination (`pageDestination`) and the address a
+ * wikilink cites it by, every time an author classified it.
+ *
  * @param {object} tree - `{ from, rel, section, route }`.
  * @param {object} ctx - `{ mount }`.
  * @returns {{pages: object[], fmLinkFindings: object[]}}
@@ -229,11 +237,16 @@ export function sectionFrontmatter(meta: object): object;
  *   for.
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
+ * @param {(src: string) => string} [options.webSrc] - Translates an authored
+ *   pathname into the address the website serves. Every artwork field goes
+ *   through it, so a page's `img:` and its body images name the same file the
+ *   same way.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page: object, { readmeSections, decorate }: {
+export function pageFrontmatter(page: object, { readmeSections, decorate, webSrc }: {
     readmeSections?: Record<string, object> | undefined;
     decorate?: ((data: object, page: object) => void) | undefined;
+    webSrc?: ((src: string) => string) | undefined;
 }): object;
 /**
  * Where a page is written, relative to the output root.
@@ -273,13 +286,15 @@ export function pageDestination(page: any): string;
  *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs.
- * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}
+ * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
+ *   wikiErrors: object[], imageErrors: object[]}}
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
     byKind: Record<string, number>;
     tableErrors: object[];
     wikiErrors: object[];
+    imageErrors: object[];
 };
 /**
  * Writes the Hugo sections a published tree declares.
@@ -398,7 +413,7 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  *   `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}}
+ *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
  */
 export function buildSite({ config, outRoot, sqlTables }?: {
     config?: object | undefined;
@@ -409,6 +424,7 @@ export function buildSite({ config, outRoot, sqlTables }?: {
     stats: object | null;
     tableErrors: object[];
     wikiErrors: object[];
+    imageErrors: object[];
     manifests: object | null;
 };
 export { formatUnaddressableFinding };

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

@@ -49,6 +49,37 @@ export function wikiContext(built: SiteIndex, { src, file, type, errors, foreign
     file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
 }): object;
+/**
+ * Resolve one infobox reference against a site index.
+ *
+ * A note writes a reference three ways and all three reach here: a bare
+ * **shortcode** (`slntlncmpny`), a short **address** (`affiliation-slntlncmpny`)
+ * and a **canonical** one (`sohl-sohl-skill-melee`). The first is the ordinary
+ * case and the ambiguous one — a shortcode is unique within a type and not
+ * across a tree — so a caller that knows what it expects passes `hint.type`
+ * and the lookup is narrowed to it.
+ *
+ * **Without a hint the types are tried in sorted order**, so two trees holding
+ * the same note resolve it the same way. A shortcode two types both claim
+ * answers with the first alphabetically, which is a stable wrong answer rather
+ * than an unstable one; a caller that cares supplies the hint.
+ *
+ * The `address` on the answer is the slug form — `type-shortcode` — because
+ * that is what the book's own link map is keyed by and what a wikilink is
+ * written as.
+ *
+ * @param {SiteIndex} siteIndex - The index.
+ * @param {unknown} ref - The reference, as authored.
+ * @param {object} [hint] - `{type}`, where the caller knows it.
+ * @returns {{name?: string, url?: string, address?: string, subType?: string}|undefined}
+ *   The page, or `undefined` where nothing answers.
+ */
+export function resolveInfoboxRef(siteIndex: SiteIndex, ref: unknown, hint?: object): {
+    name?: string;
+    url?: string;
+    address?: string;
+    subType?: string;
+} | undefined;
 /**
  * One page the site will publish, as the index needs to see it.
  */
@@ -123,13 +154,14 @@ export type SiteIndex = {
      */
     sections: Set<string>;
     /**
-     * `type:shortcode`
-     * → page, for callers resolving embedded
-     * references (a being's items, say).
+     *                                       `type:shortcode` → page, for callers
+     *                                       resolving embedded references (a
+     *                                       being's items, say).
      */
     refIndex: Map<string, {
         name: string;
         url: string;
+        subType?: string;
     }>;
     /**
      * Addresses claimed by

package/types/engine/wikilinks.d.mts

@@ -199,6 +199,28 @@ export function convertWikilinks(markdown: string, { type, id, pack, docPack, in
         anchor?: string;
     }>;
 };
+/**
+ * Resolve one reference against a compile's address index.
+ *
+ * The compile-time counterpart of
+ * {@link module:engine/site-index.resolveInfoboxRef}: the same three authored
+ * forms — a bare shortcode, a short address, a canonical one — answered with
+ * what a **compendium** can use. A local target answers with the UUID its own
+ * document was addressed by; a foreign one with the UUID its package
+ * published.
+ *
+ * @param {object} index - From {@link buildWikilinkIndex}.
+ * @param {unknown} ref - The reference, as authored.
+ * @param {object} [hint] - `{type}`, where the caller knows what it expects.
+ * @returns {{name?: string, uuid?: string, address?: string, subType?: string}|undefined}
+ *   The target, or `undefined` where nothing answers.
+ */
+export function resolveReference(index: object, ref: unknown, hint?: object): {
+    name?: string;
+    uuid?: string;
+    address?: string;
+    subType?: string;
+} | undefined;
 import { ITEM_PACK } from "./ids.mjs";
 import { PACK_BY_TYPE } from "./ids.mjs";
 import { packForType } from "./ids.mjs";

package/types/hm3/default-item-art.d.mts

@@ -18,12 +18,11 @@ export function hm3DefaultItemArt(type: string): string;
  * no `img:` of its own, rather than shipping a mismatched icon. So every type
  * `item-builders.mjs` declares has a row here.
  *
- * **Paths are fully resolved.** `resolveImg` rewrites a leading `icons/` or
- * `images/` to the *consuming package's* asset root, which is not where these
- * live: they are shipped by the HM3 system. Written as `systems/hm3/images/…`
- * they pass through untouched and address the icons HM3's own compendiums
- * already use, so an item compiled from a note looks like its hand-authored
- * neighbours.
+ * **Paths name the package that owns the file.** These icons are not the
+ * consuming package's — they are shipped by the HM3 system — so they are
+ * written `hm3/assets/…` and each surface derives its own address from that.
+ * That addresses the icons HM3's own compendiums already use, so an item
+ * compiled from a note looks like its hand-authored neighbours.
  *
  * **A one-to-many type gets one default**, because art is keyed by note type
  * and a note type is what a registry entry addresses. `weapongear` compiles

package/types/hm3/index.d.mts

@@ -4,4 +4,5 @@ export * as documentSubtypes from "./document-subtypes.mjs";
 export * as items from "./items.mjs";
 export * as actors from "./actors.mjs";
 export * as templatePriority from "./template-priority.mjs";
+export * as infobox from "./infobox.mjs";
 export { HM3_DEFAULT_ITEM_ART, hm3DefaultItemArt } from "./default-item-art.mjs";

package/types/hm3/infobox.d.mts

@@ -0,0 +1,22 @@
+/** What this system's box is called. @type {string} */
+export const HM3_INFOBOX_TITLE: string;
+/**
+ * HM3's presentation overlay: what one of this system's fields is called where
+ * humanising its key gives the wrong word.
+ *
+ * **Not a second field list.** A field it does not mention still gets a row
+ * under its own humanised name, so a field added to {@link HM3_ITEM_FIELDS}
+ * reaches the box with no edit here.
+ *
+ * @type {Readonly<Record<string, {label?: string, withheld?: string}>>}
+ */
+export const HM3_FIELD_PRESENTATION: Readonly<Record<string, {
+    label?: string;
+    withheld?: string;
+}>>;
+/**
+ * HM3's infobox declaration.
+ *
+ * @type {object}
+ */
+export const HM3_INFOBOX: object;

package/types/sohl/being-info.d.mts

@@ -26,13 +26,14 @@ export function isBeing(fm: {
  * @param {object|null|undefined} sohl - The note's `sohl` frontmatter block.
  * @param {Map<string, {name?: string, url?: string}>} index - Content index,
  *   `"<type>:<shortcode>"` → the item's page.
- * @returns {object|null|undefined} The block with its info-block fields filled
- *   in, or the input unchanged when there is nothing to derive from.
+ * @returns {object|null} The block with its info-block fields filled in, or the
+ *   input unchanged when there is nothing to derive from — with an absent block
+ *   reported as `null`, the value an empty one already carries.
  */
 export function deriveBeingInfo(sohl: object | null | undefined, index: Map<string, {
     name?: string;
     url?: string;
-}>): object | null | undefined;
+}>): object | null;
 /**
  * The note `type` whose pages carry a being info block.
  *

package/types/sohl/index.d.mts

@@ -3,6 +3,7 @@ export * as documentSubtypes from "./document-subtypes.mjs";
 export * as items from "./items.mjs";
 export * as actors from "./actors.mjs";
 export * as kbPasses from "./kb-passes.mjs";
+export * as infobox from "./infobox.mjs";
 export { AFFILIATION_STANDINGS } from "./affiliation-standings.mjs";
 export { DEFAULT_ITEM_ART, defaultItemArt } from "./default-item-art.mjs";
 export { BEING_TYPE, GEAR_TYPE_TO_KEY, deriveBeingInfo, isBeing } from "./being-info.mjs";