@heroiclands/package-build 21.1.0 → 21.2.0

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

@@ -198,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.

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

@@ -47,6 +47,26 @@ export function schemaSubtypeOf(system: string | undefined, type: string): strin
  * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
  */
 export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[];
+/**
+ * The map a pack declaring no `system:` compiles its documents against.
+ *
+ * A pack names the system its documents are shaped for, and one declaring none
+ * is compiled by the fallback pass for its document type — a single-system
+ * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
+ * follows one map whatever a note carries, which makes this the answer to "a
+ * document compiled here belongs to *which* system?" wherever a pack has not
+ * said.
+ *
+ * Stated here rather than read off the compiler classes because those are not
+ * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
+ * which draws infoboxes, so anything the infobox reads cannot import a pass.
+ * `tests/default-document-subtypes.test.ts` holds this to `compilerFor`, which
+ * is where the fallback is actually decided — so the two cannot drift apart in
+ * silence.
+ *
+ * @type {import("./document-subtypes.mjs").DocumentSubtypeMap}
+ */
+export const DEFAULT_DOCUMENT_SUBTYPES: import("./document-subtypes.mjs").DocumentSubtypeMap;
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *

package/types/engine/web-wikilinks.d.mts

@@ -66,15 +66,25 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * web pages, so the author wrote a real address and there is simply nothing to
  * link to.
  *
+ * ## Embeds first, and they are not links
+ *
+ * `![[address|label]]` names a file rather than a note, so it is resolved into
+ * an ordinary markdown image before anything looks for a link — which is what
+ * stops the link pass reading an embed's interior as a link to a note nobody
+ * wrote. The image the rewrite leaves behind is what
+ * {@link module:engine/content-images.renderImageFigures} turns into a figure
+ * for the website, and what the book reads its staging list out of.
+ *
  * @param {string} body - The markdown body.
- * @param {object} ctx - `{ index, collide, sections, contentTypes, packages,
- *   foreign, type, errors, src, file }`.
+ * @param {object} ctx - `{ index, assets, collide, sections, contentTypes,
+ *   packages, foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type; `foreign`
- *   is the cross-package manifest index. `src` is the page's display
+ *   is the cross-package manifest index; `assets` is the address space an embed
+ *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in.
- * @returns {string} The body with wikilinks rewritten.
+ * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;
 export { slugify };

package/types/engine/wikilink-syntax.d.mts

@@ -128,15 +128,18 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {Iterable<string>} [finding.packages] - For `ambiguous`, the
  *   claimants.
  * @param {string} [finding.anchor] - For `unknown-anchor`, the section named.
+ * @param {string} [finding.type] - For `not-an-asset`, the type the address
+ *   named.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
     anchor?: string | undefined;
+    type?: string | undefined;
 }): string;
 /**
  * Whether a parsed link addresses a section of the page it is written on.
@@ -193,6 +196,13 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
  * prose in search of a closer. Erring towards "not a link" leaves the author's
  * text as written, which is the safe direction for a rewriter.
+ *
+ * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
+ * keeps every reader from seeing one as the other. Stated here rather than in
+ * each reader for the reason the rest of this module exists: the checker, the
+ * pack compilers and the web resolver all match on this pattern, and three
+ * copies of the exclusion is three places for it to be forgotten. An embed's
+ * own grammar is {@link module:engine/content-embeds}.
  */
 export const WIKILINK: RegExp;
 /**
@@ -207,7 +217,9 @@ export const WIKILINK: RegExp;
  *
  * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
  * - `unknown-type` — definitely qualified, but names no type this build knows.
+ * - `not-an-asset` — a real address, embedded where only a file can be drawn.
  * - `unresolved` — parses as an address, and nothing publishes it.
  * - `ambiguous` — more than one package publishes the short address.
  * - `unknown-anchor` — the address resolved, the `#section` it names did not.