@heroiclands/package-build 20.7.0 → 21.0.0

package/content-config.mjs

@@ -474,6 +474,10 @@ export function publishesContentPages(config) {
  *
  * @typedef {object} RelationshipSpec
  * @property {string} id             The other package's id.
+ * @property {string} [contentPackage]  What the other package's content is
+ *                                   called, where that differs from its Foundry
+ *                                   id. It is the name a note writes when it
+ *                                   addresses a file that package ships.
  * @property {string} [type]         `system`, `module`, or `world`.
  * @property {string} [manifest]     Where its manifest is published.
  * @property {CompatibilitySpec} [compatibility]  The version range of *that*
@@ -712,6 +716,7 @@ const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
     "out",
     "base",
+    "assets",
     "packages",
     "sections",
     "readmeSections",
@@ -728,7 +733,14 @@ const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: ""
 const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
-const RELATIONSHIP_KEYS = ["id", "type", "manifest", "compatibility", "itemCatalog"];
+const RELATIONSHIP_KEYS = [
+    "id",
+    "contentPackage",
+    "type",
+    "manifest",
+    "compatibility",
+    "itemCatalog",
+];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
 const ITEM_REGISTRY_KEYS = ["system", "builders"];
 const PACK_KEYS = [
@@ -1414,6 +1426,38 @@ function normalizeSectionMeta(value, where) {
     return Object.freeze(out);
 }
 
+/**
+ * The asset host the website resolves a pathname against.
+ *
+ * The one address in this configuration that is not this repository's own. A
+ * note names a file by the package that owns it and the path inside that
+ * package's `assets/`, and the website serves every package's files from one
+ * host — so the host is the missing half of a web address, and it is written
+ * here because a build has no way to find it out.
+ *
+ * **Absolute, and with no trailing slash.** The forms are joined with a single
+ * `/`, so a trailing one would double it; it is trimmed rather than refused,
+ * because a doubled slash is the sort of thing a reader's eye slides past. A
+ * relative value is refused outright: it would resolve against each page's own
+ * URL, which is the failure the key exists to remove.
+ *
+ * @param {unknown} value - The configured value, or `undefined`.
+ * @returns {string} The host, without its trailing slash; `""` when unset.
+ */
+function normalizeSiteAssets(value) {
+    if (value === undefined) return "";
+    const assets = requireNonEmptyString(value, "site.assets");
+    if (!/^https?:\/\/[^/]+/.test(assets)) {
+        fail(
+            "site.assets",
+            "must be an absolute `http://` or `https://` address — it is the host " +
+                "every package's imagery is served from, and a relative value " +
+                "resolves against whichever page happens to carry the image",
+        );
+    }
+    return assets.replace(/\/+$/, "");
+}
+
 /**
  * A map of section name → landing metadata.
  *
@@ -1447,6 +1491,7 @@ function normalizeSite(value) {
     const empty = Object.freeze({
         out: "",
         base: "",
+        assets: "",
         packages: Object.freeze([]),
         sections: Object.freeze({}),
         readmeSections: Object.freeze({}),
@@ -1502,6 +1547,7 @@ function normalizeSite(value) {
     return Object.freeze({
         out: input.out === undefined ? "" : requireNonEmptyString(input.out, "site.out"),
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
+        assets: normalizeSiteAssets(input.assets),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
         readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),
@@ -1814,6 +1860,18 @@ function normalizeRelationships(value) {
                 const spec = {
                     id: requireNonEmptyString(rel.id, `${at}.id`),
                 };
+                // What the other package's *content* is called, where that
+                // differs from its Foundry id. A note addresses a file by the
+                // content package that owns it — `thalorna/assets/…` — and the
+                // Foundry id (`sohl-thalorna`) appears only in the install
+                // path this derives. Omitted where the two are the same word,
+                // which they are for every system.
+                if (rel.contentPackage !== undefined) {
+                    spec.contentPackage = requireNonEmptyString(
+                        rel.contentPackage,
+                        `${at}.contentPackage`,
+                    );
+                }
                 for (const key of ["type", "manifest"]) {
                     if (rel[key] !== undefined) {
                         spec[key] = requireNonEmptyString(rel[key], `${at}.${key}`);

package/docs/api.md

@@ -338,6 +338,8 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                        | looking up, per content type, its `data:` field list and its closed `subType` values         |
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |
 | `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                      | reading the declared tags a note of a type may carry, flattened                              |
+| `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
+| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
@@ -346,6 +348,66 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `dataFields`              | `dataFields(type, vocabulary)`               | `readonly DataFieldSpec[] \| undefined`  | looking up the `data:` keys a note type may carry                                            |
 | `subTypes`                | `subTypes(type, vocabulary)`                 | `readonly string[] \| null \| undefined` | looking up the closed `subType` values a note type declares                                  |
 
+### `engine.infobox`
+
+The declared infobox: what a note's summary panel holds, decided once and rendered by each medium. The note box's fields are the type's own `data:` vocabulary, in its declared order, so a key added to a type appears everywhere with no second edit; the overlay declares only the label and the handful of keys that carry no row.
+
+| Export                    | Signature                              | Returns                     | Use it when                                                                            |
+| ------------------------- | -------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------- |
+| `INFOBOX_LAYOUTS`         | `const INFOBOX_LAYOUTS`                | —                           | looking up the four section layouts and the property each carries its content in       |
+| `INFOBOX_VALUE_KINDS`     | `const INFOBOX_VALUE_KINDS`            | —                           | enumerating what a row's value may be                                                  |
+| `DURATION_LABELS`         | `const DURATION_LABELS`                | —                           | naming a duration pair — the roll and the flat number of seconds — in either overlay   |
+| `GEAR_UNITS`              | `const GEAR_UNITS`                     | —                           | naming a gear item's price and weight, and the unit each carries, in either overlay    |
+| `UNSET_VALUES`            | `const UNSET_VALUES`                   | —                           | enumerating the words a corpus writes when it means "there is nothing here"            |
+| `applyUnit`               | `applyUnit(kind, value, unit)`         | `object`                    | putting a declared unit on a row's value, where the quantity is                        |
+| `NOT_AVAILABLE`           | `const NOT_AVAILABLE`                  | —                           | naming what a mapped system that produced no document says                             |
+| `NOTHING_BEYOND_PROFILE`  | `const NOTHING_BEYOND_PROFILE`         | —                           | naming what a system holding nothing the note box has not shown says                   |
+| `NOTE_BOX_ID`             | `const NOTE_BOX_ID`                    | —                           | naming the note infobox, which is not a system id                                      |
+| `NOTE_BOX_TITLE`          | `const NOTE_BOX_TITLE`                 | —                           | naming the note infobox's heading                                                      |
+| `NOTE_SECTION_ID`         | `const NOTE_SECTION_ID`                | —                           | naming the note infobox's single section                                               |
+| `NOTE_FIELD_PRESENTATION` | `const NOTE_FIELD_PRESENTATION`        | —                           | looking up a `data:` key's label, the group it composes into, or why it carries no row |
+| `assertInfoboxSet`        | `assertInfoboxSet(boxes, fm, options)` | `readonly object[]`, throws | refusing a page that carries anything but the boxes its type maps to                   |
+| `buildInfoboxes`          | `buildInfoboxes(fm, options)`          | `object[]`                  | building every box a note carries, against a given set of maps and declarations        |
+| `defineInfobox`           | `defineInfobox(declaration)`           | `object`                    | declaring one system's half of the infobox                                             |
+| `hasRenderableValue`      | `hasRenderableValue(kind, value)`      | `boolean`                   | deciding whether a built value is worth a row                                          |
+| `hasValue`                | `hasValue(value)`                      | `boolean`                   | deciding whether an authored value is worth a row                                      |
+| `humanizeFieldName`       | `humanizeFieldName(name)`              | `string`                    | turning a declared key into the label a reader sees                                    |
+| `humanizeValue`           | `humanizeValue(value)`                 | `string`                    | turning an authored value into readable text                                           |
+| `isDeclaredDefault`       | `isDeclaredDefault(field, raw)`        | `boolean`                   | deciding whether a value is the one the field's own declaration would have supplied    |
+| `isUnsetSentinel`         | `isUnsetSentinel(value)`               | `boolean`                   | deciding whether a value is a word meaning "nothing here" rather than a value          |
+| `linkValue`               | `linkValue(ref, resolve, hint)`        | `object`                    | resolving one reference into a `link` value                                            |
+| `noteInfobox`             | `noteInfobox(fm, options)`             | `object`                    | building the note box alone, from the type's `data:` vocabulary                        |
+| `overlayFor`              | `overlayFor(presentation, type, name)` | `object`                    | reading a field's overlay entry, preferring the `<type>.<field>` key over the bare one |
+| `presentValue`            | `presentValue(value)`                  | `string`                    | showing a value in a row, capitalising an enumerated one and leaving prose as written  |
+| `requiredInfoboxIds`      | `requiredInfoboxIds(fm, options)`      | `string[]`                  | asking which boxes a note's type maps to                                               |
+| `sectionHolds`            | `sectionHolds(section)`                | `boolean`                   | deciding whether a section holds anything a medium would draw                          |
+| `systemRowsSection`       | `systemRowsSection(fm, fields, ctx)`   | `object[]`                  | building the rows a type's own field declaration yields                                |
+| `valueKindOf`             | `valueKindOf(field, value)`            | `string`                    | reading the value kind a field declaration implies                                     |
+
+### `engine.infoboxRegistry`
+
+The infobox declarations this toolchain ships, one per system, and the single call each medium makes to build a note's boxes.
+
+| Export            | Signature                    | Returns               | Use it when                                                                    |
+| ----------------- | ---------------------------- | --------------------- | ------------------------------------------------------------------------------ |
+| `KNOWN_INFOBOXES` | `const KNOWN_INFOBOXES`      | —                     | enumerating every system's infobox declaration, in the order a page shows them |
+| `infoboxFor`      | `infoboxFor(system)`         | `object \| undefined` | looking up one system's declaration by its id                                  |
+| `noteInfoboxes`   | `noteInfoboxes(fm, options)` | `object[]`, throws    | building every box one note carries, wired to the shipped registries           |
+
+### `engine.infoboxRender`
+
+Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
+
+| Export                 | Signature                             | Returns   | Use it when                                                              |
+| ---------------------- | ------------------------------------- | --------- | ------------------------------------------------------------------------ |
+| `infoboxTypstPreamble` | `infoboxTypstPreamble()`              | `string`  | emitting the panel definitions the book's bodies call, once per document |
+| `infoboxesToHtml`      | `infoboxesToHtml(boxes, options)`     | `string`  | drawing the boxes as `<details>` disclosures, open by default            |
+| `infoboxesToTypst`     | `infoboxesToTypst(boxes, options)`    | `string`  | drawing the boxes as panels that break between their sections            |
+| `linkToHtml`           | `linkToHtml(value)`                   | `string`  | drawing a link value as an anchor on its URL                             |
+| `linkToTypst`          | `linkToTypst(value, links, labelFor)` | `string`  | drawing a link value as a cross-reference into the book                  |
+| `linkToUuid`           | `linkToUuid(value)`                   | `string`  | drawing a link value as a Foundry document reference                     |
+| `sectionHasContent`    | `sectionHasContent(section)`          | `boolean` | deciding whether a section holds anything worth drawing                  |
+
 ### `engine.systems`
 
 The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.
@@ -563,6 +625,41 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 | `checkHtml`       | `function checkHtml(body, file,`        | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} One finding per tag, in source order.                                  | Every raw HTML tag in one note's body.                         |
 | `lintContentHtml` | `function lintContentHtml(contentBase,` | {{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}} The findings, and how many files were read. | Walk a content tree and report raw HTML in every note's prose. |
 
+### `engine.contentImages`
+
+An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in two closed vocabularies: a width class, and a `float:` position.
+
+| Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
+| --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
+| `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
+| `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
+| `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
+| `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                        | What is wrong with an image's address, or `""` when nothing is.              |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], float: string, problems: string[]}} What was written, and what cannot be honoured.                                        | Read the directive on an image.                                              |
+| `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                         | The classes a figure carries, from a parsed directive.                       |
+| `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                       | Text going inside an HTML attribute or between tags.                         |
+| `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                        | One image as the `<figure>` both HTML surfaces render.                       |
+| `standsAlone`         | `function standsAlone(text, start, end)`        | {boolean} Whether the match is a block of its own.                                                                                             | Whether a match sits alone in its own paragraph.                             |
+| `imagesIn`            | `function imagesIn(body)`                       | {Array<{alt: string, src: string, title: string, directive: string, index: number, length: number, block: boolean}>} One entry per image.      | Every image in one body, with its directive and its position.                |
+| `imageSourcesIn`      | `function imageSourcesIn(body)`                 | {string[]} The addresses, with repeats.                                                                                                        | Every image address one body names, in order of appearance.                  |
+| `checkImages`         | `function checkImages(body, file,`              | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.  | Every defect in one note's images.                                           |
+| `lintContentImages`   | `function lintContentImages(contentBase,`       | {{findings: Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>, files: number}} What it found. | Walk a content tree and report every image it cannot render as authored.     |
+| `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                 | Rewrite every block image in a body into the figure the website publishes.   |
+| `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                   | A markdown-it plugin that reads an image's directive and renders its figure. |
+
+### `engine.pathnames`
+
+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 the first segment says which package owns it when an `assets/` follows. Every surface derives its own address from that one statement: the path inside a Foundry install, the file in the owning repository's tree, the address the website serves, and where the book stages its copy.
+
+| Export              | Signature                               | Returns                                                                                            | Use it when                                                         |
+| ------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `ASSETS_SEGMENT`    | `const ASSETS_SEGMENT`                  | —                                                                                                  | The directory a package ships its files in.                         |
+| `PATHNAME_SURFACES` | `const PATHNAME_SURFACES`               | —                                                                                                  | The surfaces one authored pathname resolves for.                    |
+| `pathnameProblem`   | `function pathnameProblem(raw)`         | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.   |
+| `packageAddresses`  | `function packageAddresses(config)`     | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.    |
+| `resolvePathname`   | `function resolvePathname(raw, config)` | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves. |
+
 ### `engine.contentLinks`
 
 Resolving every link in a content tree, and reporting the ones that land nowhere. Three link defects survive both content builds silently, so neither the pack compilers nor a site build catches them:
@@ -672,6 +769,7 @@ Wikilink resolution for the pack compilers. Content notes link to one another wi
 | `readQualifier`      | `function readQualifier(target, types, packages)`                       | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type; or `null` when it is not an address at all.                                      | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
 | `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                              | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
 | `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                | Builds the link-resolution tables for a content tree.                                                                                                                      |
+| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                     | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
 | `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named. | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
 
 ### `engine.wikilinkSyntax`
@@ -694,10 +792,11 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 
 **The address index a site build resolves its wikilinks against.** Every consumer that publishes a content tree as a website has to answer the same question — given `[[Something]]`, which page? — and every one of them answered it with its own copy of the same 150 lines. `sohl`'s and `sohl-thalorna`'s site builds still share 147 identical lines of it, comments and indentation aside. This is that shared half, lifted out whole.
 
-| Export           | Signature                          | Returns                                                               | Use it when                                               |
-| ---------------- | ---------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
-| `buildSiteIndex` | `function buildSiteIndex(entries,` | {SiteIndex} The index, and what could not be addressed unambiguously. | Build the address index a site's wikilink resolver reads. |
-| `wikiContext`    | `function wikiContext(built,`      | {object} The resolver context.                                        | The per-page context a wikilink resolver takes.           |
+| Export              | Signature                                          | Returns                                                                                                                        | Use it when                                                                                                  |
+| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `buildSiteIndex`    | `function buildSiteIndex(entries,`                 | {SiteIndex} The index, and what could not be addressed unambiguously.                                                          | Build the address index a site's wikilink resolver reads.                                                    |
+| `wikiContext`       | `function wikiContext(built,`                      | {object} The resolver context.                                                                                                 | The per-page context a wikilink resolver takes.                                                              |
+| `resolveInfoboxRef` | `function resolveInfoboxRef(siteIndex, ref, hint)` | {{name?: string, url?: string, address?: string, subType?: string}\|undefined} The page, or `undefined` where nothing answers. | Resolve one infobox reference — a bare shortcode, a short address or a canonical one — against a site index. |
 
 ### `engine.pdfToc`
 
@@ -714,16 +813,17 @@ The document tree a PDF is built from, and the plan it resolves to (#316). The p
 
 A note's markdown, and a document plan, rendered as Typst source. **This module emits text and reads nothing.** It takes markdown and a plan and returns a `.typ` document; the filesystem, the note bodies and the compiler that turns the result into a PDF all live in {@link module:engine/pdf-build}. That split is what lets the outline, the table of contents, every anchor and every link destination be asserted in a unit test with no renderer installed — which is most of what a book has to get right, and all of what a test can check without eyes.
 
-| Export                  | Signature                                                              | Returns                                                      | Use it when                                                              |
-| ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| `escapeTypst`           | `function escapeTypst(text)`                                           | {string} The same text, inert.                               | Escape literal text for Typst markup.                                    |
-| `escapeTypstString`     | `function escapeTypstString(text)`                                     | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does. |
-| `labelFor`              | `function labelFor(anchor)`                                            | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                       |
-| `createParser`          | `function createParser(registry)`                                      | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                        |
-| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                              | {string} Typst markup.                                       | Render markdown as Typst content.                                        |
-| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
-| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                      | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
-| `iconNamesIn`           | `function iconNamesIn(markdown)`                                       | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
+| Export                  | Signature                                                                                 | Returns                                                      | Use it when                                                              |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `escapeTypst`           | `function escapeTypst(text)`                                                              | {string} The same text, inert.                               | Escape literal text for Typst markup.                                    |
+| `escapeTypstString`     | `function escapeTypstString(text)`                                                        | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does. |
+| `labelFor`              | `function labelFor(anchor)`                                                               | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                       |
+| `createParser`          | `function createParser(registry)`                                                         | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                        |
+| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                                                 | {string} Typst markup.                                       | Render markdown as Typst content.                                        |
+| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
+| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                                         | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
+| `iconNamesIn`           | `function iconNamesIn(markdown)`                                                          | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
+| `bookTypstPreamble`     | `function bookTypstPreamble()`                                                            | {string} Typst markup.                                       | The Typst definitions the book's page furniture is drawn with.           |
 
 ### `engine.pdfFonts`
 
@@ -739,11 +839,13 @@ Which glyph an icon name resolves to, read from the font that carries it. {@link
 
 The content tree, built into a book. The I/O half of the PDF surface: it reads the configuration, the document tree and the notes, drives the passes the site build already owns, hands the result to {@link module:engine/pdf-render} and runs Typst over what comes back. Everything about _what the book says_ is decided in the pure half; this module is where the filesystem and the compiler live.
 
-| Export         | Signature                                           | Returns                                                               | Use it when                                           |
-| -------------- | --------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
-| `pdfFileName`  | `function pdfFileName(artifact, version)`           | {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned. | The file name a downloaded book identifies itself by. |
-| `buildPdf`     | `async buildPdf({ config, out, version, compile })` | {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.     | Build the book.                                       |
-| `compileTypst` | `function compileTypst(typPath, pdfPath, pdf`       | {{ok: boolean, message: string}} What happened.                       | Run Typst over the emitted source.                    |
+| Export            | Signature                                                  | Returns                                                                                         | Use it when                                                          |
+| ----------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `pdfFileName`     | `function pdfFileName(artifact, version)`                  | {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned.                           | The file name a downloaded book identifies itself by.                |
+| `buildPdf`        | `async buildPdf({ config, out, version, compile })`        | {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.                               | Build the book.                                                      |
+| `stagedImagePath` | `function stagedImagePath(src, config)`                    | {{from: string, to: string}\|null} The file, and where under the output directory it is staged. | The file on disk an authored image address names, or `null`.         |
+| `stageBanners`    | `function stageBanners(entries, config, outDir, findings)` | {Map<string, string>} Declared path → the staged file's path, relative to the `.typ`.           | Copy every banner the document tree names into the output directory. |
+| `compileTypst`    | `function compileTypst(typPath, pdfPath, pdf`              | {{ok: boolean, message: string}} What happened.                                                 | Run Typst over the emitted source.                                   |
 
 ### `engine.baseCompiler`
 
@@ -940,6 +1042,24 @@ SoHL's Actor pass — what a SoHL `being` document holds and nothing else: the b
 | -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Actors` | `class Actors` | —       | not called directly — imported and driven by `engine/generate.mjs`; must run after the items passes, since it reads their generated JSON trees |
 
+### `sohl.infobox`
+
+Which of SoHL's facts a note's summary panel carries, and how they group. Read off the same field declaration the compiler obeys, with a builder of its own only where a box is derived rather than read field by field.
+
+| Export                    | Signature                       | Returns               | Use it when                                                                         |
+| ------------------------- | ------------------------------- | --------------------- | ----------------------------------------------------------------------------------- |
+| `SOHL_INFOBOX`            | `const SOHL_INFOBOX`            | —                     | reading SoHL's infobox declaration                                                  |
+| `SOHL_INFOBOX_TITLE`      | `const SOHL_INFOBOX_TITLE`      | —                     | naming SoHL's box                                                                   |
+| `SOHL_FIELD_PRESENTATION` | `const SOHL_FIELD_PRESENTATION` | —                     | looking up what one of SoHL's fields is called, or why it carries no row            |
+| `PROTECTION_FIELDS`       | `const PROTECTION_FIELDS`       | —                     | reading the declarations of the aspects armour is rated against, in the order shown |
+| `UNSTATED`                | `const UNSTATED`                | —                     | naming what a strike mode shows where a value was not stated                        |
+| `armorSections`           | `armorSections(fm, ctx)`        | `object[]`            | building armour's box, protection included                                          |
+| `beingSections`           | `beingSections(fm, ctx)`        | `object[]`            | building a being's attributes, skills, mystical abilities and equipment             |
+| `decodeItem`              | `decodeItem(entry)`             | `object \| undefined` | reading what one `sohl.items` entry names, whichever form it was written in         |
+| `projectileSections`      | `projectileSections(fm, ctx)`   | `object[]`            | building a projectile's box, its impact composed into one row                       |
+| `strikeModes`             | `strikeModes(declared)`         | `[string, object][]`  | reading a weapon's strike modes, whichever of the two shapes were authored          |
+| `weaponSections`          | `weaponSections(fm, ctx)`       | `object[]`            | building a weapon's box, strike modes included                                      |
+
 ### `sohl.kbPasses`
 
 The `sohl` knowledgebase's own body passes: two rewrites driven by a TypeDoc symbol map and a repository layout only this package has, named from `site.passOptions` the same way an asset transform is named from configuration. Neither rewrite ever fails a build — an unresolved `{@link}` degrades to a code span, and a relative link outside the documentation tree becomes a GitHub blob URL — but building the bundle from a misconfigured `symbolMap` fails loudly before any page renders.
@@ -1002,6 +1122,16 @@ HM3's note-type → document-subtype map. Unlike SoHL's near-identity map, HM3's
 | `HM3_TYPE_KEY`          | `const HM3_TYPE_KEY`          | —       | reading the frontmatter key (`hm3.type`) inside the `hm3:` block that resolves a one-to-many content type to its HM3 document subtype                  |
 | `HM3_DOCUMENT_SUBTYPES` | `const HM3_DOCUMENT_SUBTYPES` | —       | looking up which Foundry document and subtype a content type compiles into under HM3; a type absent from this map compiles into no HM3 document at all |
 
+### `hm3.infobox`
+
+Which of HM3's facts a note's summary panel carries, read off the same field list the item builders obey.
+
+| Export                   | Signature                      | Returns | Use it when                                   |
+| ------------------------ | ------------------------------ | ------- | --------------------------------------------- |
+| `HM3_INFOBOX`            | `const HM3_INFOBOX`            | —       | reading HM3's infobox declaration             |
+| `HM3_INFOBOX_TITLE`      | `const HM3_INFOBOX_TITLE`      | —       | naming HM3's box                              |
+| `HM3_FIELD_PRESENTATION` | `const HM3_FIELD_PRESENTATION` | —       | looking up what one of HM3's fields is called |
+
 ### `hm3.items`
 
 HM3's Item pass — the parts of compiling a note into an HM3 Item that are facts about HM3: the `description` key rendered from a note's `{#appearance}` section (the one HM3 Item field with nowhere else to put it), and the `flags.hm3.templatePriority` flag HM3's data model has no field for. There is no HM3 equivalent of SoHL's `docHtml` — the prose still compiles into its JournalEntry, it just isn't addressed from the item.

package/docs/commands.md

@@ -437,6 +437,81 @@ package-build: registry and §3 agree (11 labels).
 
 None.
 
+### `package-build bump [packages..]`
+
+**NAME**
+
+Take a newer version of a dependency, keeping the lockfile's formatting.
+
+**SYNOPSIS**
+
+```
+package-build bump [packages..] [--tag <tag>] [--check]
+```
+
+**DESCRIPTION**
+
+Takes the newest published version of one or more declared dependencies,
+updating `package-lock.json` — and `package.json` when the declared range has to
+move — then restoring both files to the indentation they already used.
+
+npm performs the resolution, so a version whose dependency set differs from the
+one it replaces is handled as correctly as one that moves three lines. Editing
+those three lines by hand is only right while the two dependency sets are
+identical, and nothing tells the author when they are not.
+
+The indentation is the reason this exists rather than `npm install` being run
+directly. Every repository consuming this toolchain writes `package-lock.json`
+with four spaces and prettier-ignores it; npm rewrites it with two, turning a
+three-line version change into a whole-file reformat no reviewer can read past.
+
+Named no packages, it takes every `@heroiclands/*` dependency the manifest
+declares. That scope is the one a person bumps by hand — a first-party release
+is taken the moment it publishes, usually to unblock the change that prompted
+it, while third-party updates arrive from Dependabot on their own schedule.
+
+The version reported is the one the **lockfile** resolves, not the range the
+manifest declares, because `npm ci` installs from the lockfile. Above 1.0 a
+caret range usually already admits the new version, so the manifest does not
+move and the lockfile is the whole change; below 1.0 a caret is locked to the
+minor, so it does.
+
+Writes no `node_modules`: install the result with `npm ci`.
+
+**OPTIONS**
+
+| Option    | Type    | Default  | Description                                 |
+| --------- | ------- | -------- | ------------------------------------------- |
+| `--tag`   | string  | `latest` | The dist-tag to take.                       |
+| `--check` | boolean | `false`  | Report what would change and write nothing. |
+
+**EXIT STATUS**
+
+1 if the working directory holds no `package.json` or no `package-lock.json`. 1
+if a named package is not a declared dependency. Otherwise 0, including when
+every package is already current.
+
+**EXAMPLES**
+
+```
+$ package-build bump
+@heroiclands/package-build  20.6.0 → 20.7.0
+   kept the existing indentation of package-lock.json
+
+Install it with `npm ci`, which resolves from the lockfile this just moved.
+```
+
+```
+$ package-build bump @heroiclands/hugo-theme --check
+@heroiclands/hugo-theme  0.5.0 → 0.6.0
+
+Run without --check to take it.
+```
+
+**SEE ALSO**
+
+`package-build clean`.
+
 ### `package-build yaml [paths..]`
 
 **NAME**

package/docs/configuration.md

@@ -689,6 +689,7 @@ Any other key under `docs.itemFields` is refused:
 | ----------------------- | -------- | ------- |
 | `site.out`              | string   | `""`    |
 | `site.base`             | string   | `""`    |
+| `site.assets`           | string   | `""`    |
 | `site.packages`         | string[] | `[]`    |
 | `site.sections`         | object   | `{}`    |
 | `site.readmeSections`   | object   | `{}`    |
@@ -706,7 +707,7 @@ rewrites.
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: out, base, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: out, base, assets, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections).``
 
 `site.out` is the output root, resolved by `engine/site-build.mjs`; unset,
 it is refused **at build time** rather than by `defineConfig` (an unset
@@ -715,6 +716,23 @@ wipes on every run would be the working tree):
 
 > `site.out is not set, so there is nowhere to write the site. Refusing to continue: the output directory is wiped on every run, and an unset one resolves to the repository root.`
 
+`site.assets` is the host every package's imagery is served from, and it is
+the one address in this file that is not this repository's own. A note names
+a file by the package that owns it and the path inside that package's
+`assets/` (see `docs/content-format.md`), and the website joins the two onto
+this host — `https://cdn.heroiclands.org` + `/thalorna` +
+`/images/map.webp`. A build has no way to find the host out, so a page
+carrying a package-owned image with none set is an error naming this key.
+Absolute, and the trailing slash is trimmed:
+
+> ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
+
+The consuming Hugo site spells the same host as `params.cdnBaseURL`, which
+its theme resolves a relative asset path against. The two are the same
+address written for two readers: this one is what the toolchain emits into a
+page, that one is what the theme joins onto anything the toolchain left
+relative.
+
 `site.packages` names which content packages' notes the site walks, beyond
 this one's own; `site.pass` names a repository's own body-rewrite bundle
 (the one part of the site contract that is code, exactly as `itemBuilders`
@@ -925,22 +943,31 @@ system relationship it declares — see [`stats.systemVersion`](#statssystemvers
 
 Each entry, in any of the four lists:
 
-| Key (under `relationships.<kind>[]`)    | Type                            | Required | Default |
-| --------------------------------------- | ------------------------------- | -------- | ------- |
-| `relationships.systems[].id`            | string                          | yes      | —       |
-| `relationships.systems[].type`          | string                          | no       | none    |
-| `relationships.systems[].manifest`      | string                          | no       | none    |
-| `relationships.systems[].compatibility` | object, `{minimum?, verified?}` | no       | none    |
-| `relationships.systems[].itemCatalog`   | boolean                         | no       | `false` |
+| Key (under `relationships.<kind>[]`)     | Type                            | Required | Default |
+| ---------------------------------------- | ------------------------------- | -------- | ------- |
+| `relationships.systems[].id`             | string                          | yes      | —       |
+| `relationships.systems[].contentPackage` | string                          | no       | the id  |
+| `relationships.systems[].type`           | string                          | no       | none    |
+| `relationships.systems[].manifest`       | string                          | no       | none    |
+| `relationships.systems[].compatibility`  | object, `{minimum?, verified?}` | no       | none    |
+| `relationships.systems[].itemCatalog`    | boolean                         | no       | `false` |
 
-(the same four keys apply under `requires[]`, `recommends[]` and
+(the same keys apply under `requires[]`, `recommends[]` and
 `conflicts[]`.)
 
 > ``package-build config: `relationships.<kind>[<index>]` must be a mapping.``
 
 > ``package-build config: `relationships.<kind>[<index>].id` must be a non-empty string.``
 
-> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, type, manifest, compatibility, itemCatalog).``
+> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog).``
+
+`contentPackage` names what the other package's _content_ is called, where
+that differs from its Foundry id. A note addresses a file by the content
+package that owns it — `thalorna/assets/images/map.webp` — and the Foundry id
+(`sohl-thalorna`) appears only in the install path that pathname resolves to.
+Omit it where the two are the same word, which they are for every system:
+
+> ``package-build config: `relationships.<kind>[<index>].contentPackage` must be a non-empty string.``
 
 `itemCatalog` opts into extracting the named package's Item packs so the
 actors pass can resolve embedded items this repository does not hold — off