@heroiclands/package-build 21.1.0 → 22.0.0

package/ci/emit-asset-index.mjs

@@ -0,0 +1,32 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Publish this package's own content index, for the readers that are not this
+ * process.
+ *
+ * Run by `prepack`, beside the declaration build and for the same reason: the
+ * artifact is derived from what the tree already holds, so it belongs in the
+ * tarball and not in the repository. A build inside this process never reads
+ * it — {@link module:engine/packagebuild-index.packageBuildRecords} walks the
+ * shipped tree — so an absent file makes nothing fail, and anything reading the
+ * published form gets the same records the walk produces.
+ *
+ * Not a `package-build` subcommand: no consuming repository has a reason to run
+ * it, and a CLI that offers one would be surface nobody asked for.
+ */
+
+import { emitPackageBuildIndex } from "../engine/packagebuild-index.mjs";
+
+const { file, assets, bytes } = emitPackageBuildIndex();
+console.log(`package-build: ${file} (${assets} asset(s), ${bytes} bytes)`);

package/content-config.mjs

@@ -70,6 +70,8 @@ import YAML from "yaml";
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
+import { ASSET_TYPE_NAMES } from "./engine/asset-types.mjs";
+import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
@@ -149,6 +151,12 @@ const DOCUMENTATION_REFUSES = Object.freeze({
  */
 export const DEFAULT_PATHS = /** @type {const} */ ({
     content: "assets/content",
+    // The asset roots' parent — `icons/`, `images/` and `audio/` sit directly
+    // under it, and the content tree beside them. Named separately from
+    // `content` rather than derived from its parent, because the two are free to
+    // move independently and deriving one from the other would make relocating
+    // either a surprise for the other.
+    assets: "assets",
     // Where `content-index` writes this package's note index. Under `build/`
     // because it is derived and disposable — regenerating it costs a
     // frontmatter parse — and emphatically not under `stage`, which is mirrored
@@ -361,6 +369,9 @@ export function publishesContentPages(config) {
  *
  * @typedef {object} PathsInput
  * @property {string} [content]          Content tree root.
+ * @property {string} [assets]           The asset roots' parent — the directory
+ *                                       holding `icons/`, `images/` and
+ *                                       `audio/`.
  * @property {string} [contentIndex]     Where `content-index` writes this
  *                                       package's note index. Outbound, and a
  *                                       derived artifact — never a source, and
@@ -383,6 +394,7 @@ export function publishesContentPages(config) {
  *
  * @typedef {object} ResolvedPaths
  * @property {string} content
+ * @property {string} assets
  * @property {string} contentIndex
  * @property {string} packJson
  * @property {string} stage
@@ -827,7 +839,7 @@ function requireNonEmptyString(value, field) {
 }
 
 /**
- * The `contentPackage`, checked against the two rules an address puts on it.
+ * The `contentPackage`, checked against the three rules an address puts on it.
  *
  * It is the first segment of every canonical address this repository publishes
  * (`package-system-type-shortcode`, so `sohl-none-doc-gear`), and an address is
@@ -856,6 +868,13 @@ function requireNonEmptyString(value, field) {
  *    package's id to *be* its system id, and `sohl-sohl-skill-clmb` is the
  *    honest address that results — which is the reason to prevent the ones that
  *    are avoidable.
+ * 3. _Not reserved_. `packagebuild` addresses the files this toolchain ships
+ *    itself, so a repository claiming the name would publish addresses that
+ *    collide with them — see {@link module:engine/packages}.
+ *
+ * The type vocabulary rule reaches the **asset** types too: `icon`, `image` and
+ * `audio` are types an address names exactly as it names a being, so a package
+ * called `image` would make `image-thorn` readable two ways.
  *
  * @param {unknown} value - The configured `contentPackage`.
  * @param {ReadonlySet<string>} docEntryTypes - Every type whose prose compiles
@@ -878,6 +897,15 @@ function requireContentPackage(value, docEntryTypes) {
                 "than merely ugly. `harn-adventures` became `harnadventures`",
         );
     }
+    if (isReservedPackage(pkg)) {
+        fail(
+            "contentPackage",
+            `is \`${pkg}\`, which is a reserved package name. ` +
+                `\`${pkg}-none-image-<shortcode>\` already addresses a file the ` +
+                "toolchain itself ships, so a package claiming the name would " +
+                "publish addresses that collide with it. Rename the package",
+        );
+    }
     // The closed vocabulary is read alongside the configured registries, not
     // instead of them, because neither is a superset of the other. The format's
     // vocabulary holds every type a note may declare *however this repository
@@ -891,6 +919,7 @@ function requireContentPackage(value, docEntryTypes) {
     const typeNames = new Set([
         ...Object.keys(PACK_BY_TYPE),
         ...Object.keys(NOTE_VOCABULARY),
+        ...ASSET_TYPE_NAMES,
         ...docEntryTypes,
         ...[...docEntryTypes].map((type) => `doc${type}`),
     ]);

package/docs/api.md

@@ -336,6 +336,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `DRAFT_TAG`               | `const DRAFT_TAG`                            | —                                        | naming the declared tag that marks a note as unfinished                                      |
 | `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                        | looking up, per content type, its `data:` field list and its closed `subType` values         |
+| `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`               | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere |
 | `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                                    |
@@ -388,11 +389,12 @@ The declared infobox: what a note's summary panel holds, decided once and render
 
 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           |
+| 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                                         |
+| `compilesSystemDocument` | `compilesSystemDocument(fm, map, router)` | `boolean`             | asking whether one system compiles a document for one note, which is what a system box's _available_ asserts |
 
 ### `engine.infoboxRender`
 
@@ -462,6 +464,7 @@ Which note-type → document-subtype maps this toolchain ships, and the two ques
 | ----------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `KNOWN_DOCUMENT_SUBTYPE_MAPS` | `const KNOWN_DOCUMENT_SUBTYPE_MAPS`      | —                                                                                                                                 | The note-type → document-subtype maps this toolchain ships.                                                                            |
 | `ACTOR_TYPES`                 | `const ACTOR_TYPES`                      | —                                                                                                                                 | Every note type any shipped map compiles into an **Actor**.                                                                            |
+| `DEFAULT_DOCUMENT_SUBTYPES`   | `const DEFAULT_DOCUMENT_SUBTYPES`        | —                                                                                                                                 | The map a pack declaring no `system:` compiles its documents against.                                                                  |
 | `subtypeMapFor`               | `function subtypeMapFor(system)`         | {import("./document-subtypes.mjs").DocumentSubtypeMap\|undefined} Its map, or `undefined` where this toolchain ships none for it. | The map one system ships, by its id.                                                                                                   |
 | `schemaSubtypeOf`             | `function schemaSubtypeOf(system, type)` | {string} The document subtype to look up.                                                                                         | The document subtype a note type compiles into for one system — the translation the _schema_ check needs, and the reason it needs one. |
 
@@ -521,19 +524,19 @@ Emitting this package's cross-package link manifest. `engine/content-address.mjs
 
 Emitting this package's content index. Every content build already walks the whole note tree and parses every note's frontmatter — the pack compilers, the site build, and the content-table expander each do it — and every one of them throws the result away when it finishes. So nothing outside a build can ask a question about the content: "which beings carry no `kbcat`?", "what does this table actually select?", "did that type rename leave anything behind?" have no answer short of writing a throwaway script that re-walks the tree. Eight dead Bestiary tables shipped for weeks behind exactly that gap.
 
-| Export                  | Signature                                                                                       | Returns                                                                                                                                                                                                                  | Use it when                                                                                                                                                                      |
-| ----------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                             | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well. | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                       |
-| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                  | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                      | Recursively sort an object's keys, so serialization is order-independent.                                                                                                        |
-| `asciiName`             | `function asciiName(name)`                                                                      | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                           | A note's display name reduced to printable 7-bit ASCII.                                                                                                                          |
-| `asciiAliases`          | `function asciiAliases(aliases)`                                                                | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                    | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                              |
-| `serializeContentIndex` | `function serializeContentIndex(records)`                                                       | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                           | Serialize records as JSON Lines.                                                                                                                                                 |
-| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                           | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                        | The index records for a content tree, without writing anything.                                                                                                                  |
-| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                             | {{file: string, notes: number, bytes: number}} Where it was written, how many notes it holds, and its size.                                                                                                              | Emit this package's content index.                                                                                                                                               |
-| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })` | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                      | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                             |
-| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, manifest, problems })`     | `Array<Record<string, any>>`                                                                                                                                                                                             | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's) |
+| Export                  | Signature                                                                                               | Returns                                                                                                                                                                                                                  | Use it when                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                     | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well. | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                |
+| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                          | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                      | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                 |
+| `asciiName`             | `function asciiName(name)`                                                                              | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                           | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                   |
+| `asciiAliases`          | `function asciiAliases(aliases)`                                                                        | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                    | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                       |
+| `serializeContentIndex` | `function serializeContentIndex(records)`                                                               | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                           | Serialize records as JSON Lines.                                                                                                                                                                                          |
+| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                                   | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                        | The index records for a content tree, without writing anything.                                                                                                                                                           |
+| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                                     | {{file: string, notes: number, assets: number, records: number, bytes: number}} Where it was written, how many notes and how many assets it holds, how many records that is in all, and its size.                        | Emit this package's content index.                                                                                                                                                                                        |
+| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })`         | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                      | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                      |
+| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems })` | `Array<Record<string, any>>`                                                                                                                                                                                             | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file |
 
-`engine.contentIndex` also re-exports five names from neighbouring leaf modules, at this same import path:
+`engine.contentIndex` also re-exports seven names from neighbouring leaf modules, at this same import path:
 
 | Export                | Signature                        | Returns                                                        | Use it when                                                                                                                                                                      |
 | --------------------- | -------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -541,7 +544,59 @@ Emitting this package's content index. Every content build already walks the who
 | `DERIVED_KEYS`        | `const DERIVED_KEYS`             | —                                                              | reading which keys the content index adds to a record, and which a note therefore may not author itself                                                                          |
 | `noteFile`            | `noteFile(contentBase, record)`  | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                      |
 | `authoredFrontmatter` | `authoredFrontmatter(record)`    | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading back exactly what a note authored from its index record, so a pass can lint or compile from the index without reasoning about derived fields as if the author wrote them |
-| `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's, when enumerating the corpus                                                                                  |
+| `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                              |
+| `isAssetRecord`       | `isAssetRecord(record)`          | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                  |
+| `recordPath`          | `recordPath(record)`             | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                              |
+
+### `engine.assetTypes`
+
+The asset types — `icon`, `image` and `audio` — and the three roots they are walked from. An asset is addressed exactly as a note is; what differs is that a `.webp` carries no frontmatter and has nowhere to say what it is, so the root supplies the type and the list of roots is closed.
+
+| Export             | Signature                     | Returns                                                      | Use it when                                                                                               |
+| ------------------ | ----------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `ASSET_TYPES`      | `const ASSET_TYPES`           | `readonly AssetType[]` — type, root, extensions, description | walking the roots, or presenting the vocabulary                                                           |
+| `ASSET_TYPE_NAMES` | `const ASSET_TYPE_NAMES`      | `ReadonlySet<string>`                                        | admitting the asset types into a type vocabulary an address is parsed against                             |
+| `ASSET_SYSTEM`     | `const ASSET_SYSTEM`          | `string` — always `none`                                     | writing an asset address, whose `<system>` segment is a property of the type rather than of the reference |
+| `IMAGE_EXTENSIONS` | `const IMAGE_EXTENSIONS`      | `readonly string[]` — lowercase, dot-led                     | deciding whether a file under a picture root is an asset at all                                           |
+| `AUDIO_EXTENSIONS` | `const AUDIO_EXTENSIONS`      | `readonly string[]` — lowercase, dot-led                     | the same question for `audio/`                                                                            |
+| `isAssetType`      | `isAssetType(type)`           | `boolean`                                                    | scoping a rewrite rule, which may substitute a file and nothing else                                      |
+| `assetTypeOfRoot`  | `assetTypeOfRoot(root)`       | `AssetType \| undefined`                                     | reading a root directory name back to the type it declares                                                |
+| `isAssetShortcode` | `isAssetShortcode(shortcode)` | `boolean`                                                    | telling an addressable filename from one that carries a version string, a hyphen or a date stamp          |
+
+### `engine.assetIndex`
+
+The asset record: one line of the content index per addressable file. The record is emitted by the package holding the bytes, so its `path` is that package's path and each consumer joins its own root onto it — Foundry its data directory, the website its CDN prefix, the book its asset base.
+
+| Export                      | Signature                                                       | Returns                       | Use it when                                                                       |
+| --------------------------- | --------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
+| `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from            |
+| `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields |
+| `PROVENANCE_FILE`           | `const PROVENANCE_FILE`                                         | `string` — `provenance.yaml`  | naming the file a directory records provenance for its subtree in                 |
+| `PROVENANCE_SIDECAR_SUFFIX` | `const PROVENANCE_SIDECAR_SUFFIX`                               | `string` — `.yaml`            | naming a per-file record, which replaces an inherited one wholesale               |
+| `collectAssetRecords`       | `collectAssetRecords(assetsBase, { contentPackage, problems })` | `Array<Record<string, any>>`  | reading a package's asset roots into index records, without walking its notes     |
+
+### `engine.packages`
+
+The `<package>` segment's own registry: the names no repository may claim. A content package names itself, and exactly one name is held back — `packagebuild`, which addresses the files the toolchain ships itself.
+
+| Export                 | Signature                    | Returns                               | Use it when                                                                    |
+| ---------------------- | ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
+| `PACKAGEBUILD_PACKAGE` | `const PACKAGEBUILD_PACKAGE` | `string` — `packagebuild`             | naming the address namespace package-build's own assets publish under          |
+| `metadataFileName`     | `metadataFileName(pkg)`      | `string` — `<package>-metadata.jsonl` | naming a package's content index, wherever it is written, published or fetched |
+| `RESERVED_PACKAGES`    | `const RESERVED_PACKAGES`    | `ReadonlySet<string>`                 | listing the names a configuration is refused for claiming                      |
+| `isReservedPackage`    | `isReservedPackage(pkg)`     | `boolean`                             | checking one candidate `contentPackage` against the reservation                |
+
+### `engine.packagebuildIndex`
+
+The toolchain's own content index — the files it ships, addressed. Every other package's index is fetched; this one is read from disk, because package-build is an npm dependency of every consumer rather than a Foundry package. The records join `foreign.index` like any other package's, so every lookup stays one path, and the special case is entirely about acquisition.
+
+| Export                    | Signature                                     | Returns                                         | Use it when                                                               |
+| ------------------------- | --------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
+| `PACKAGEBUILD_ROOT`       | `const PACKAGEBUILD_ROOT`                     | `string`                                        | naming this package's own root, wherever it is installed                  |
+| `PACKAGEBUILD_ASSETS`     | `const PACKAGEBUILD_ASSETS`                   | `string`                                        | naming the asset directory it ships                                       |
+| `PACKAGEBUILD_INDEX_FILE` | `const PACKAGEBUILD_INDEX_FILE`               | `string`                                        | naming where the published index sits, beside the files it describes      |
+| `packageBuildRecords`     | `packageBuildRecords(assetsBase)`             | `Array<Record<string, any>>`                    | reading the records for the files it ships, walked rather than read back  |
+| `emitPackageBuildIndex`   | `emitPackageBuildIndex({ assetsBase, file })` | `{file: string, assets: number, bytes: number}` | publishing that walk as a file, for the readers that are not this process |
 
 ### `engine.siteBuild`
 
@@ -625,6 +680,20 @@ 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.contentEmbeds`
+
+`![[address|label]]` — the wikilink that renders a picture where it stands. An embed is the wikilink the syntax module defines, with `!` meaning _render it here_, and the syntax supplying the default type `image`. It resolves to an ordinary markdown image before any surface renders it, so the figure, the staging list and the directive all come from the image machinery that already exists. An embed reaches asset types only.
+
+| Export               | Signature                                | Returns                                                                                                                                                          | Use it when                                                     |
+| -------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `EMBED_DEFAULT_TYPE` | `const EMBED_DEFAULT_TYPE`               | —                                                                                                                                                                | The type a bare shortcode takes, supplied by the syntax itself. |
+| `EMBED_PATTERN`      | `const EMBED_PATTERN`                    | —                                                                                                                                                                | An embed, as authored, with the directive it may carry.         |
+| `embedsIn`           | `function embedsIn(body)`                | {ParsedEmbed[]} One entry per embed.                                                                                                                             | Every embed in one body, in source order.                       |
+| `resolveEmbed`       | `function resolveEmbed(index, embed)`    | {{pathname: string}\|{reason: string, target: string, type?: string}} The authored pathname, or the finding.                                                     | What one embed resolves to, or why it does not.                 |
+| `embedProblems`      | `function embedProblems(embed)`          | {Array<{link: string, offset: number, message: string}>} One entry per defect.                                                                                   | What is wrong with one embed's directive or placement.          |
+| `resolveEmbeds`      | `function resolveEmbeds(body, ctx)`      | {{markdown: string, unresolved: Array<object>, problems: Array<object>}} The body, the embeds that named nothing, and the directives that could not be honoured. | Rewrite every embed into the image each surface renders.        |
+| `checkEmbeds`        | `function checkEmbeds(body, file, opts)` | {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 embeds, located.                     |
+
 ### `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.
@@ -652,13 +721,15 @@ An image saying how wide it is and where it sits. A markdown image carries no in
 
 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. |
+| 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. |
+| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory. |
+| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.     |
 
 ### `engine.contentLinks`
 
@@ -845,7 +916,10 @@ The content tree, built into a book. The I/O half of the PDF surface: it reads t
 | `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.                                   |
+| `compileTypst`    | `function compileTypst(typPath, pdfPath, pdf`              | {{ok: boolean, message: string, findings: object[]}} What happened.                             | Run Typst over the emitted source.                                   |
+| `typstArgs`       | `function typstArgs(typPath, pdfPath, pdf)`                | {string[]} The arguments, in order.                                                             | The command line the compile runs, as data.                          |
+| `typstWarnings`   | `function typstWarnings(output)`                           | {object[]} One finding per warning the compiler wrote.                                          | The compiler's own warnings, as findings.                            |
+| `BOOK_FONTS_PATH` | `const BOOK_FONTS_PATH`                                    | {string} The directory holding them.                                                            | The faces the book is set in, shipped with this package.             |
 
 ### `engine.baseCompiler`
 
@@ -1413,7 +1487,9 @@ console.log(normalizeRepoUrl("git@github.com:HeroicLands/sohl.git"));
 | ------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ARTIFACTS`                    | `const ARTIFACTS`                                                                   | —                                                                                                                       | reading the two Foundry package kinds (`"system"`, `"module"`) as the artifact name their manifest and release archive are called                                                  |
 | `normalizeRepoUrl`             | `normalizeRepoUrl(repository)`                                                      | `string` — normalised `https://` URL, no trailing slash                                                                 | normalising `package.json`'s `repository` field (object or shorthand string, `git+…git` or plain) to the exact URL Foundry fetches release assets from                             |
-| `releaseUrls`                  | `releaseUrls({ repoUrl, version, artifact })`                                       | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's release addresses — `manifest` points at `releases/latest` so an installed package can discover updates, `download` is pinned to this version              |
+| `HOMEPAGE_ORIGIN`              | `HOMEPAGE_ORIGIN`                                                                   | `string` — the origin every package's homepage is served from                                                           | stating the site origin once, so the address a manifest advertises and the address the configuration documents cannot disagree                                                     |
+| `packageHomepage`              | `packageHomepage(contentPackage)`                                                   | `string` — `<origin>/<contentPackage>/`                                                                                 | deriving the homepage a manifest's `url` points at; throws when given no name rather than advertising `<origin>/undefined/`                                                        |
+| `releaseUrls`                  | `releaseUrls({ repoUrl, homeUrl, version, artifact })`                              | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's addresses — `url` is the homepage a reader follows before installing, while `bugs`, `manifest` and `download` stay on the repository holding the artefacts |
 | `metadataUrl`                  | `metadataUrl({ repoUrl, version, contentPackage })`                                 | `string` — the version-pinned asset URL                                                                                 | computing where this release publishes its content index, pinned to this version like `download` so a dependency's manifest and its fetched index always describe the same release |
 | `manifestPacks`                | `manifestPacks(config)`                                                             | `object[]`                                                                                                              | deriving the manifest's `packs` array from the one pack list the build already has, in build order, companions flattened in                                                        |
 | `packFolderFindings`           | `packFolderFindings({ packFolders, packs = [] })`                                   | `Array<{severity: "error"\|"warning", message: string, pack: string, folder?: string, keyPath: Array<string\|number>}>` | checking a declared `packFolders` against the derived pack list — a folder naming a pack that does not exist is an error, a pack no folder names is a warning                      |

package/docs/commands.md

@@ -441,7 +441,7 @@ None.
 
 **NAME**
 
-Take a newer version of a dependency, keeping the lockfile's formatting.
+Take a newer published version of a declared dependency.
 
 **SYNOPSIS**
 
@@ -453,17 +453,20 @@ package-build bump [packages..] [--tag <tag>] [--check]
 
 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.
+move — and holding both files to the indentation they already carry.
 
-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.
+npm performs the resolution, which is what this exists for. A version whose
+dependency set differs from the one it replaces is handled as correctly as one
+that moves three lines, while editing the `version` / `resolved` / `integrity`
+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.
+npm writes `package-lock.json` with the indentation `package.json` uses, so a
+consumer whose manifest is formatted gets a formatted lockfile back and the
+diff is the version change alone. The indentation step covers the case where
+the two files disagree: each is written back with the indent it already
+carried, rather than the lockfile taking the manifest's. A run that had to put
+an indent back names the file it rewrote.
 
 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
@@ -496,7 +499,6 @@ every package is already current.
 ```
 $ 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/docs/configuration.md

@@ -439,6 +439,7 @@ HeroicLands layout, resolved against `rootDir`:
 | Key                   | Default                | What it is                                                                                 |
 | --------------------- | ---------------------- | ------------------------------------------------------------------------------------------ |
 | `paths.content`       | `assets/content`       | The content tree root.                                                                     |
+| `paths.assets`        | `assets`               | The asset roots' parent, holding `icons/`, `images/` and `audio/`.                         |
 | `paths.contentIndex`  | `build/content-index`  | Where `content-index` writes this package's note index. Derived and disposable.            |
 | `paths.packJson`      | `build/packs-json`     | Build-only per-entry JSON intermediate.                                                    |
 | `paths.stage`         | `build/stage/packs`    | Compiled LevelDB packs.                                                                    |
@@ -457,7 +458,7 @@ An empty value is refused generically:
 
 Any other key is refused:
 
-> ``package-build config: `paths.<key>` is not a recognized option (expected one of: content, contentIndex, packJson, stage, unpack, foreignCache, metadataCache).``
+> ``package-build config: `paths.<key>` is not a recognized option (expected one of: content, assets, contentIndex, packJson, stage, unpack, foreignCache, metadataCache).``
 
 ### `skipDirectories`
 
@@ -850,12 +851,20 @@ reader downloaded, and a title with no document has nothing to print:
 `pdf.fonts` names font **families**, not files — the renderer asks the font
 stack for a family by name:
 
-| Key (under `pdf.fonts`) | Type          | Required | Default                                                          |
-| ----------------------- | ------------- | -------- | ---------------------------------------------------------------- |
-| `pdf.fonts.serif`       | string        | no       | `""`                                                             |
-| `pdf.fonts.sans`        | string        | no       | `""`                                                             |
-| `pdf.fonts.mono`        | string        | no       | `""`                                                             |
-| `pdf.fonts.path`        | string (path) | no       | `""` — where the renderer may look beyond the system's own fonts |
+| Key (under `pdf.fonts`) | Type          | Required | Default                                                   |
+| ----------------------- | ------------- | -------- | --------------------------------------------------------- |
+| `pdf.fonts.serif`       | string        | no       | `""` — the book is set in `Libertinus Serif`              |
+| `pdf.fonts.sans`        | string        | no       | `""` — its headings in `Libertinus Sans`                  |
+| `pdf.fonts.mono`        | string        | no       | `""` — its raw and code spans in `DejaVu Sans Mono`       |
+| `pdf.fonts.path`        | string (path) | no       | `""` — faces of your own, searched as well as the shipped |
+
+Each role falls back to a face that resolves on a machine carrying none of them:
+the toolchain ships the sans and the compiler embeds the other two. The compile
+searches the shipped directory, and `pdf.fonts.path` when one is given, and
+nothing the machine has installed — so a face named here has to come from one of
+those two places, and a name nothing resolves is reported rather than set in the
+fallback. Shipped alongside the sans, and available to a package that names it,
+is `Libertinus Mono`.
 
 > ``package-build config: `pdf.fonts` must be a mapping.``