@heroiclands/package-build 21.0.0 → 21.2.0

package/types/engine/infobox-registry.d.mts

@@ -6,6 +6,38 @@
  *   toolchain ships none for it.
  */
 export function infoboxFor(system: string | undefined): object | undefined;
+/**
+ * Whether one system compiles a document for one note.
+ *
+ * This is what a system box's _available_ asserts, and it is the compile's own
+ * question rather than a reading of the frontmatter. A note carrying no block
+ * is not a note a system has nothing for: where the pack compiling its document
+ * declares no `system:`, the document is built from `data:` and the field
+ * defaults and ships exactly like any other.
+ *
+ * Three statements answer it, and they are the three the compile itself
+ * follows:
+ *
+ * 1. **The map** says which document class this system makes of the note's
+ *    type. No row, no document — and no box either, which is why a caller
+ *    reaching here already has one.
+ * 2. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by.
+ * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
+ *    system's data and takes only notes that say something about it — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside. Declaring none, it is compiled by the fallback
+ *    pass, which needs no block and answers for
+ *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
+ *    so a tree with no HM3 pack ships no HM3 document however a note is
+ *    written.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} map - The system's note-type → document-subtype map.
+ * @param {object} router - The pack router this build is driven by.
+ * @returns {boolean} True when this system compiles a document for this note.
+ */
+export function compilesSystemDocument(fm: object, map: object, router: object): boolean;
 /**
  * Every box one note carries, wired to the registries this toolchain ships.
  *
@@ -17,12 +49,15 @@ export function infoboxFor(system: string | undefined): object | undefined;
  * @param {object} [options] - Options.
  * @param {(ref: unknown, hint?: object) => object|undefined} [options.resolve] -
  *   Resolves a reference to `{name, url?, uuid?, address?, subType?}`.
+ * @param {object} [options.router] - The pack router deciding which system
+ *   compiles a document for this note. Defaults to the consuming repository's.
  * @returns {object[]} The boxes, in the order every medium renders them.
  * @throws {Error} When the built set disagrees with what the note's type maps
  *   to — see {@link module:engine/infobox.assertInfoboxSet}.
  */
-export function noteInfoboxes(fm: object, { resolve }?: {
+export function noteInfoboxes(fm: object, { resolve, router }?: {
     resolve?: ((ref: unknown, hint?: object) => object | undefined) | undefined;
+    router?: object | undefined;
 }): object[];
 /**
  * Every system's infobox declaration, in the order a page shows them.

package/types/engine/infobox.d.mts

@@ -246,9 +246,11 @@ export function systemRowsSection(fm: object, fields: readonly object[], { block
  *   build ships, which decide the box set.
  * @param {readonly object[]} [options.providers] - The systems' infobox
  *   declarations, keyed by `system`.
- * @param {(fm: object, block: string) => boolean} options.carriesBlock -
- *   Whether the note says anything about a system, which decides
- *   {@link NOT_AVAILABLE}.
+ * @param {(fm: object, map: object) => boolean} options.compilesDocument -
+ *   Whether that system compiles a document for this note, which decides
+ *   {@link NOT_AVAILABLE}. Asked of the routing and the passes rather than of
+ *   the frontmatter: a pack declaring no `system:` compiles a note from `data:`
+ *   and the field defaults, so the block's presence is not the question.
  * @param {(field: object, fm: object, opts: object) => object} options.resolveField -
  *   Resolves one declared field against the note.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
@@ -259,7 +261,7 @@ export function systemRowsSection(fm: object, fields: readonly object[], { block
 export function buildInfoboxes(fm: object, options: {
     maps: readonly object[];
     providers?: readonly object[] | undefined;
-    carriesBlock: (fm: object, block: string) => boolean;
+    compilesDocument: (fm: object, map: object) => boolean;
     resolveField: (field: object, fm: object, opts: object) => object;
     resolve?: ((ref: unknown) => object | undefined) | undefined;
     vocabulary?: object | undefined;

package/types/engine/macros.d.mts

@@ -83,13 +83,17 @@ export function resolveMacroScope(fm: object, label: string): string;
  * @param {string} opts.command - The command, from {@link macroCommand}.
  * @param {string|null} [opts.folder] - The resolved folder id.
  * @param {object} [opts.stats] - The `_stats` block.
+ * @param {string|null} [opts.img] - The resolved art, from the note's `icon`
+ *   address. Passed in rather than resolved here, because an address is
+ *   answered by the compile's index and this function takes no index.
  * @returns {MacroDocument} The Macro document.
  * @throws {Error} When the frontmatter's macro type or scope is unusable.
  */
-export function buildMacroEntry(fm: object, { command, folder, stats }: {
+export function buildMacroEntry(fm: object, { command, folder, stats, img }: {
     command: string;
     folder?: string | null | undefined;
     stats?: object | undefined;
+    img?: string | null | undefined;
 }): MacroDocument;
 /**
  * The anchor the executable script lives under: `# Script {#script}`.
@@ -112,11 +116,11 @@ export const MACRO_TYPES: readonly string[];
 /** The Foundry macro scopes (`CONST.MACRO_SCOPES`), in schema order. */
 export const MACRO_SCOPES: readonly string[];
 /**
- * Foundry's own default macro artwork, used when a note authors no `img`.
+ * Foundry's own default macro artwork, used when a note names no `icon`.
  *
- * A core path, deliberately: it is not translated by {@link resolveImg} (which
- * roots `icons/…` under this system's assets), so it must be stated after that
- * translation rather than as authored frontmatter.
+ * A core path, deliberately: it names a file Foundry itself ships rather than an
+ * address in any package, so it is stated after the art resolution rather than
+ * as something a note could author.
  */
 export const DEFAULT_MACRO_IMG: "icons/svg/dice-target.svg";
 /**

package/types/engine/map-notes.d.mts

@@ -140,7 +140,8 @@ export function buildShape(spec: object, geom: MapGeometry): object;
  *   `packageId`, `journalEntryId`, `journalPack` (the pack the note's derived
  *   JournalEntry landed in), `pageIds` (heading key → page id),
  *   `resolveRegionRef` / `resolveBehaviorRef` / `resolveEffectRef` (address →
- *   UUID), `knownActions`, `warnings`, and optionally `folder` and `stats`.
+ *   UUID), `art` (an art address → the path each surface serves),
+ *   `knownActions`, `warnings`, and optionally `folder` and `stats`.
  * @returns {object} The Scene document, keyed for the pack.
  * @throws {Error} On any authoring mistake Foundry would accept silently.
  */
@@ -156,13 +157,16 @@ export function buildScene(fm: object, ctx: object): object;
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
- * @param {string} [img] - The background art, already resolved from the note.
- *   Passed by {@link buildScene}, which reads it from the note rather than from
- *   the block; defaults to the block's own `img`, so a direct two-argument call
- *   still works.
+ * @param {string} img - The background art, already resolved from the note's
+ *   `bgImage` address by {@link buildScene}. Passed rather than resolved here,
+ *   because an address is answered by the compile's index and this function
+ *   takes none.
+ * @param {(value: unknown, key: string, type: string) => string|null} [art] -
+ *   The art resolver, for the foreground overlay. Omitted, a note naming one
+ *   gets no overlay rather than a path nothing serves.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl: object, sceneId: string, img?: string): object;
+export function buildLevel(sohl: object, sceneId: string, img: string, art?: (value: unknown, key: string, type: string) => string | null): object;
 /**
  * Compile the `walls:` and `doors:` blocks into Wall documents.
  *

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

@@ -1,20 +1,3 @@
-/**
- * What a package's content index is called, wherever it is written or fetched.
- *
- * **The local index and the published artifact are one file.** A package emits
- * this, ships it as a release asset, and advertises it as `flags.metadataUrl`;
- * a consumer fetches that same file into its cache and reads it. Naming it in
- * one function is what keeps the emitter, the release and the fetcher from
- * drifting into three spellings of one artifact.
- *
- * The `-metadata` suffix earns its place: a bare `<package>.jsonl` says nothing
- * about what it holds, and these files land in a cache directory beside other
- * packages' artifacts where the name is all a reader has.
- *
- * @param {string} pkg - The content package name.
- * @returns {string} The file name, e.g. `sohl-metadata.jsonl`.
- */
-export function metadataFileName(pkg: string): string;
 /**
  * Every dependency whose published index this build resolves addresses through.
  *
@@ -211,6 +194,7 @@ export function formatUnaddressableFinding(finding: {
     entries: number;
     sampleKey: string;
 }, config: object): string;
+export { metadataFileName };
 /**
  * The relationship kinds that are dependencies, and therefore citable.
  *
@@ -224,3 +208,4 @@ export function formatUnaddressableFinding(finding: {
  */
 export const METADATA_RELATIONSHIP_KINDS: readonly string[];
 export function isComplete(dir: string): boolean;
+import { metadataFileName } from "./packages.mjs";

package/types/engine/note-vocabulary.d.mts

@@ -115,6 +115,9 @@ export function assertVocabularyCharset(vocabulary: Readonly<Record<string, Type
  * @param {string} type - The note's `type`.
  * @param {Readonly<Record<string, TypeVocabulary>>} [vocabulary] - The registry
  *   to read, defaulting to {@link NOTE_VOCABULARY}.
+ * {@link SHARED_DATA_FIELDS} come first, because they are part of every type's
+ * declaration and a caller asking what a type accepts must be told all of it.
+ *
  * @returns {readonly DataFieldSpec[]|undefined} The declaration, or `undefined`
  *   when the type declares none — which is not the same as declaring an empty
  *   one, and is why the lint makes no claim rather than refusing every key.
@@ -131,6 +134,26 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * The `data:` keys **every** note type accepts, whatever it is.
+ *
+ * `data:` is a closed container and the per-type vocabularies are the only
+ * lists there are, so a key legal on every type needs somewhere that is not one
+ * type's list — including the types whose own vocabulary is empty. Repeating a
+ * row in twenty-five tables would be twenty-five chances for one of them to
+ * disagree with the rest.
+ *
+ * Both are art slots, and they are legal everywhere for different reasons.
+ * `icon` is the document's profile art and most types compile into a document
+ * that carries one; where a type's passes emit none, the frontmatter lint says
+ * so as a warning rather than the vocabulary refusing the key, because the
+ * value may still be read by a page template. `banner` reaches no compiled
+ * document at all — it is the page's hero image — and a page is what every note
+ * publishes.
+ *
+ * @type {readonly DataFieldSpec[]}
+ */
+export const SHARED_DATA_FIELDS: readonly DataFieldSpec[];
 /**
  * The declared tag that marks a note as **unfinished**.
  *
@@ -269,6 +292,13 @@ export type DataFieldSpec = {
      * one the message holds.
      */
     entryShape?: string | undefined;
+    /**
+     * - The type a bare value takes. An art slot declares
+     * one — `icon` for `icon` and `tokenIcon`, `image` for `bgImage` and
+     * `banner` — so `icon: anvil` names `icon-anvil` while a value carrying the
+     * separator states its own address.
+     */
+    ref?: string | undefined;
     /**
      * - For a `scalar-or-map` field, what its keys name.
      * `"pack"` means each is a pack this package declares, so a key naming none

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

@@ -0,0 +1,56 @@
+/**
+ * The index records for the files this package ships.
+ *
+ * Walked rather than read back, so an installed copy and a git checkout answer
+ * alike and there is no state to be stale. The tree is small — a handful of
+ * banners — so the walk costs nothing a build would notice.
+ *
+ * @param {string} [assetsBase] - The asset directory, for a caller testing
+ *   against a tree of its own.
+ * @returns {Array<Record<string, any>>} One record per addressable file.
+ */
+export function packageBuildRecords(assetsBase?: string): Array<Record<string, any>>;
+/**
+ * Publish the index as a file, for the readers that are not this process.
+ *
+ * The website, the book and the Foundry runtime each read a package's index as
+ * JSON Lines; this package's has to be one too, and it ships in the tarball
+ * beside the images it describes.
+ *
+ * @param {object} [options] - Options.
+ * @param {string} [options.assetsBase] - The asset directory to walk.
+ * @param {string} [options.file] - Where to write it.
+ * @returns {{file: string, assets: number, bytes: number}} Where it was
+ *   written, how many files it holds, and its size.
+ */
+export function emitPackageBuildIndex({ assetsBase, file }?: {
+    assetsBase?: string | undefined;
+    file?: string | undefined;
+}): {
+    file: string;
+    assets: number;
+    bytes: number;
+};
+/**
+ * This package's own root, wherever it is installed.
+ *
+ * Derived from this module's location rather than from a configuration: the
+ * files being indexed sit beside it in the same tarball, so the one reliable
+ * answer is "up from here". A consuming repository's `rootDir` names its own
+ * tree and says nothing about where its dependencies live.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_ROOT: string;
+/**
+ * The asset directory this package ships.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_ASSETS: string;
+/**
+ * Where the published index sits, beside the files it describes.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_INDEX_FILE: string;

package/types/engine/packages.d.mts

@@ -0,0 +1,62 @@
+/**
+ * What a package's content index is called, wherever it is written or fetched.
+ *
+ * **The local index and the published artifact are one file.** A package emits
+ * this, ships it as a release asset, and advertises it as `flags.metadataUrl`;
+ * a consumer fetches that same file into its cache and reads it. Naming it in
+ * one function is what keeps the emitter, the release and the fetcher from
+ * drifting into three spellings of one artifact.
+ *
+ * The `-metadata` suffix earns its place: a bare `<package>.jsonl` says nothing
+ * about what it holds, and these files land in a cache directory beside other
+ * packages' artifacts where the name is all a reader has.
+ *
+ * It lives here rather than beside the loader because the loader reaches the
+ * toolchain's own index, which has to name its file without importing the
+ * loader back.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file name, e.g. `sohl-metadata.jsonl`.
+ */
+export function metadataFileName(pkg: string): string;
+/**
+ * Whether a package name is held back from the open registry.
+ *
+ * @param {unknown} pkg - The candidate `contentPackage`.
+ * @returns {boolean} True when the name is reserved.
+ */
+export function isReservedPackage(pkg: unknown): boolean;
+/**
+ * The `<package>` segment's own registry: the names no repository may claim.
+ *
+ * A content package names itself, so the registry is open — and exactly one
+ * name is held back from it.
+ *
+ * **`packagebuild` is a package that is not a package.** package-build is an npm
+ * package rather than a system or a module, and it ships a set of images —
+ * section banners chiefly — that many packages draw on. Addressing them as
+ * `packagebuild-none-image-<shortcode>` lets a note reach one without declaring a
+ * dependency on some parent system or module it otherwise has no relationship
+ * with, which is the whole point: the alternative is every package depending on
+ * one of the others just to borrow a banner.
+ *
+ * So nothing may create a real package that collides with the name, and its
+ * resolution is special-cased, because no installed directory sits behind it.
+ *
+ * This module is a **leaf with no local imports**, so the configuration
+ * validator can name it without closing a cycle around `content-config.mjs`.
+ *
+ * @module
+ */
+/**
+ * The address namespace package-build's own assets publish under.
+ *
+ * @type {string}
+ */
+export const PACKAGEBUILD_PACKAGE: string;
+/**
+ * Every package name a repository may not claim.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const RESERVED_PACKAGES: ReadonlySet<string>;

package/types/engine/pathnames.d.mts

@@ -9,6 +9,47 @@
  * @returns {string} The problem, as a finding's sentence, or `""`.
  */
 export function pathnameProblem(raw: string | null | undefined): string;
+/**
+ * Whether this build installs anything into a Foundry data directory.
+ *
+ * A `documentation` package compiles no packs and installs nowhere, so no note
+ * of its reaches a Foundry document and no pathname of its can be dead on a
+ * surface it never touches. A check that reports a missing Foundry address asks
+ * this first, so the one kind with no Foundry surface is not told about it.
+ *
+ * Read from {@link packageAddresses} rather than from a key, so "does this
+ * package have a Foundry root?" is answered in one place by the map that
+ * derives every other package's.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {boolean} Whether the package being built has a Foundry root.
+ */
+export function servesFoundry(config: object): boolean;
+/**
+ * Why a pathname has no Foundry address, or `""` when it has one.
+ *
+ * The sibling of {@link pathnameProblem} one step further on: that one asks
+ * whether a pathname is written correctly at all, and this one asks whether
+ * *this* build can turn a correctly written pathname into a path a Foundry
+ * install serves. Both answer in a sentence rather than a code, so the caller
+ * that holds a line and a column and the caller that holds only a file say the
+ * same thing about the same value.
+ *
+ * `""` for every pathname that resolves — and for the three shapes that
+ * legitimately reach Foundry untranslated: a URL, a protocol-relative
+ * `//host/…`, and a `/`-rooted path Foundry serves from its data root. A blank
+ * pathname is a deliberate blank and resolves to a blank on every surface, so
+ * it is not a problem either.
+ *
+ * `""` as well for a pathname {@link pathnameProblem} already refuses. That
+ * defect has its own finding naming its own replacement, and reporting a second
+ * one about the same characters would send the author to one mistake twice.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function foundryAddressProblem(raw: string | null | undefined, config: object): string;
 /**
  * Every content package this build can resolve a pathname against.
  *
@@ -41,87 +82,6 @@ export function packageAddresses(config: object): Map<string, {
  *   resolves on one surface and nowhere else.
  */
 export function resolvePathname(raw: string | null | undefined, config: object): PathnameForms | null;
-/**
- * One authored pathname, and the four addresses it resolves to.
- *
- * A note names a file once — in `img:`, in `data.portrait:`, in the body of a
- * markdown image — and four surfaces have to serve it: a Foundry install, this
- * repository's own working tree, the website, and the book. Each addresses the
- * same file differently, so the authored pathname is a *statement of
- * ownership* and every surface derives its own address from it. One statement,
- * four derivations, one rule.
- *
- * ## The rule
- *
- * **The first segment says which package owns the file, when it is followed by
- * `assets/`.** Everything after `assets/` is the *suffix* — the path inside
- * that package's shipped tree, and the one piece every form is built from.
- *
- * | Authored                    | Owner            | Suffix              |
- * | --------------------------- | ---------------- | ------------------- |
- * | `sohl/assets/icons/a.svg`   | the `sohl` package | `icons/a.svg`     |
- * | `images/beings/b.webp`      | **this** package | `images/beings/b.webp` |
- *
- * A pathname that does not open with `<package>/assets/` belongs to the package
- * being built, and the whole of it is the suffix. That is the ordinary case and
- * the one nearly every note writes.
- *
- * The four forms, for a `thalorna` note writing `images/map.webp` (`thalorna`
- * ships as the Foundry module `sohl-thalorna`):
- *
- * | Form      | Address                                            |
- * | --------- | -------------------------------------------------- |
- * | `foundry` | `modules/sohl-thalorna/assets/images/map.webp`      |
- * | `local`   | `assets/images/map.webp`                            |
- * | `web`     | `https://cdn.heroiclands.org/thalorna/images/map.webp` |
- * | `pdf`     | `assets/images/map.webp`                            |
- *
- * **`<package>` and `<foundry-id>` are two different names.** The package is
- * `thalorna` — what the content is called, what the website serves it under,
- * and what a note writes. The Foundry id is `sohl-thalorna` — what Foundry
- * installs the module as, and the only place that name appears. They coincide
- * for `sohl` and `hm3`, which is exactly why the two are kept apart here rather
- * than treated as one value.
- *
- * `local` and `pdf` read the same and mean different places: `local` is the file
- * in the owning repository's working tree, `pdf` is where the book stages a copy
- * beside its Typst source. They are derived separately because only one of them
- * is a file a build may open — see {@link PathnameForms.own}.
- *
- * ## What is not a package pathname
- *
- * **An off-install address passes through on every surface**: a URL, a
- * protocol-relative `//host/…`, or a `/`-rooted path, which Foundry serves from
- * the data root and which names no package at all. That is how a note addresses
- * core Foundry art (`/icons/svg/mystery-man.svg`) or a package this build knows
- * nothing about (`/systems/dnd5e/icons/spell.webp`).
- *
- * **A package this build has never heard of keeps its ownership.** The website
- * and the book need only the package's name and the suffix, so both resolve;
- * the Foundry address needs the package's kind and its Foundry id, which only a
- * declared relationship carries, so that one form comes back `null` and the
- * caller that needs it refuses. Reading such a pathname as this package's own
- * would file one package's name inside another's tree and say nothing.
- *
- * **A `systems/…` or `modules/…` pathname is refused.** It is a Foundry address
- * written where an ownership statement belongs: it resolves for Foundry and for
- * nothing else, because neither the website nor the book has any such directory.
- * {@link pathnameProblem} names the replacement, and every surface refuses the
- * value rather than deriving an address from it — a wrong address that resolves
- * to a 404 is the failure this module exists to remove, and inventing one here
- * would reintroduce it one directory along.
- *
- * ## The two empties
- *
- * `null` — or an absent key, which arrives as `undefined` — means **unset**: the
- * note names no file and the caller's default applies. `""` means **blank on
- * purpose**: the note names no file and wants none, so no default may replace
- * it. `resolvePathname` returns `null` for the first and a form object whose
- * every address is `""` for the second, so the two stay distinguishable all the
- * way to the caller.
- *
- * @module
- */
 /**
  * The directory a package ships its files in, and the segment that marks a
  * pathname's first segment as a package name.

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

@@ -74,15 +74,72 @@ export function buildPdf({ config, out, version, compile }?: {
     version?: string | undefined;
     compile?: boolean | undefined;
 }): Promise<object>;
+/**
+ * The command line the compile runs, as data.
+ *
+ * Separate from running it so the flags that decide which faces are in play
+ * can be asserted without a compiler installed — which is the half of the
+ * invocation that changes what the book looks like.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string} pdfPath - Where the PDF goes.
+ * @param {object} [pdf] - The resolved `pdf:` block.
+ * @returns {string[]} The arguments, in order.
+ */
+export function typstArgs(typPath: string, pdfPath: string, pdf?: object): string[];
+/**
+ * The compiler's own warnings, as findings.
+ *
+ * A compile that says `unknown font family` still exits 0 and still writes a
+ * book — one set in whatever face the fallback reached. That is the failure
+ * this surface is least able to see, so the compiler's warnings are read back
+ * and reported on the same terms as everything else the build finds.
+ *
+ * Typst writes a warning as a `warning:` line followed by a `┌─ file:line:col`
+ * locator over a source excerpt. The message and the position are taken; the
+ * excerpt is not, since the reader has the file.
+ *
+ * @param {string} output - What the compiler wrote to stderr.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} One finding per warning.
+ */
+export function typstWarnings(output: string): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: string;
+    message: string;
+}>;
 /**
  * Run Typst over the emitted source.
  *
  * @param {string} typPath - The `.typ` file.
  * @param {string} pdfPath - Where the PDF goes.
  * @param {object} pdf - The resolved `pdf:` block.
- * @returns {{ok: boolean, message: string}} What happened.
+ * @returns {{ok: boolean, message: string, findings: object[]}} What happened,
+ *   and what the compiler warned about on the way.
  */
 export function compileTypst(typPath: string, pdfPath: string, pdf?: object): {
     ok: boolean;
     message: string;
+    findings: object[];
 };
+/**
+ * The faces the book is set in that the compiler does not carry itself.
+ *
+ * Resolved from this module rather than from the working directory, on the same
+ * rule the specification and `--version` follow: a consumer runs the build
+ * inside its own repository, and the faces it sets the book in are the ones
+ * that came with the toolchain version it resolved.
+ *
+ * What is here is the **sans**, in the three styles a heading can ask for, the
+ * superfamily's **mono** for a package that names it, and the licence they
+ * travel under. The serif is not: the compiler embeds one, and a second copy of
+ * a face it already carries is a file nothing selects.
+ *
+ * It is **not** an addressable asset root: the compiler matches a face by
+ * family name, so nothing addresses these files and nothing needs to.
+ *
+ * @type {string}
+ */
+export const BOOK_FONTS_PATH: string;

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

@@ -55,7 +55,6 @@ export function createParser(registry?: object): object;
  *   note's own `##` nests beneath the entry heading the book gave it.
  * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
  *   every `{#slug}` the body declares.
- * @param {boolean} [opts.dropCap] - Whether to open the body with a raised
  *   capital. Set for an entry, which begins a page; not for front matter or a
  *   prose file, which carry headings of their own.
  * @returns {string} Typst markup.
@@ -68,7 +67,6 @@ export function markdownToTypst(markdown: string, opts?: {
     images?: Map<string, string> | undefined;
     headingOffset?: number | undefined;
     anchorPrefix?: string | undefined;
-    dropCap?: boolean | undefined;
 }): string;
 /**
  * The Typst definitions the book's page furniture is drawn with.
@@ -200,7 +198,9 @@ export function bookTypstPreamble(): string;
  * @param {string} opts.title - The document's title.
  * @param {string} [opts.subtitle] - Shown under it on the title page.
  * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
- * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
+ * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names. Each
+ *   falls back to the face the toolchain ships or the compiler embeds, so a
+ *   caller that names none still sets the book in all three.
  * @param {string} [opts.version] - Stamped on the title page when given.
  * @param {string} [opts.preamble] - Definitions the bodies call, emitted once
  *   above the title page. A panel every entry draws is a set of rules stated

package/types/engine/scenes.d.mts

@@ -23,8 +23,9 @@ export function collectKnownActionNames(repoRoot: string): Set<string>;
  * scene's id-based references resolve on import.
  */
 export class Scenes extends BasePackCompiler {
-    constructor({ contentBase, dest, skipDirectories, companionDests, folderResolver, repoRoot, }: {
+    constructor({ contentBase, assetsBase, dest, skipDirectories, companionDests, folderResolver, repoRoot, }: {
         contentBase: any;
+        assetsBase: any;
         dest: any;
         skipDirectories: any;
         companionDests?: {} | undefined;

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

@@ -237,15 +237,19 @@ export function sectionFrontmatter(meta: object): object;
  *   for.
  * @param {(data: object, page: object) => void} [options.decorate] - Called
  *   with each page's frontmatter, for whatever a consumer's own pass adds.
+ * @param {(value: unknown, type: string) => string|null} [options.artSrc] -
+ *   Translates an art address into the pathname the website resolver takes, or
+ *   `null` where nothing answers it.
  * @param {(src: string) => string} [options.webSrc] - Translates an authored
  *   pathname into the address the website serves. Every artwork field goes
  *   through it, so a page's `img:` and its body images name the same file the
  *   same way.
  * @returns {object} The frontmatter to write.
  */
-export function pageFrontmatter(page: object, { readmeSections, decorate, webSrc }: {
+export function pageFrontmatter(page: object, { readmeSections, decorate, webSrc, artSrc }: {
     readmeSections?: Record<string, object> | undefined;
     decorate?: ((data: object, page: object) => void) | undefined;
+    artSrc?: ((value: unknown, type: string) => string | null) | undefined;
     webSrc?: ((src: string) => string) | undefined;
 }): object;
 /**

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

@@ -34,6 +34,8 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex }?:
  *   diagnostic names. Absent, `src` stands in.
  * @param {Map<string, object>} [options.foreignIndex] - The foreign index, for
  *   resolvers that distinguish a foreign hit from a local one.
+ * @param {object} [options.assets] - The address space an `![[…]]` embed
+ *   resolves against, shaped as every asset resolver reads one.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -42,12 +44,13 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex }?:
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex }: {
+export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets }: {
     src: string;
     type?: string | null | undefined;
     errors: object[];
     file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
+    assets?: object | undefined;
 }): object;
 /**
  * Resolve one infobox reference against a site index.