@heroiclands/package-build 21.0.0 → 21.2.0

package/types/engine/base-compiler.d.mts

@@ -129,6 +129,11 @@ export class BasePackCompiler {
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
+     * @param {string} [options.assetsBase] - The asset roots' parent, whose
+     *   files the art addresses resolve against. Stated beside `contentBase`
+     *   because the two move independently: a caller compiling a tree it
+     *   assembled states where that tree's files are, and one compiling the
+     *   repository's own leaves it to the configuration.
      * @param {string} options.dest - Where this pass writes its JSON.
      * @param {readonly string[]} options.skipDirectories - Directories the walk
      *   never descends into. Required: see {@link assertStatedScope}.
@@ -148,8 +153,9 @@ export class BasePackCompiler {
      *   over, derived once and shared by every pass. A pass handed none derives
      *   its own in `prepare`, and reports that corpus's problems itself.
      */
-    constructor({ contentBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
+    constructor({ contentBase, assetsBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
         contentBase: string;
+        assetsBase?: string | undefined;
         dest: string;
         skipDirectories: readonly string[];
         folderResolver?: ((address: string | null) => string | null) | undefined;
@@ -164,6 +170,12 @@ export class BasePackCompiler {
     });
     /** @type {string} */
     contentBase: string;
+    /**
+     * The asset roots' parent, whose files the art addresses resolve against.
+     *
+     * @type {string|undefined}
+     */
+    assetsBase: string | undefined;
     /** @type {string} */
     outputDir: string;
     /** @type {(path: string|null) => string|null} */
@@ -348,6 +360,35 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm: object, body: string): string;
+    /**
+     * The Foundry path one authored art address names, or `null`.
+     *
+     * **The two empties survive.** `null` and an absent key mean *no art named*,
+     * so the caller's own default applies with nullish coalescing; `""` means
+     * *ship blank on purpose* and no default may replace it. That is
+     * {@link module:engine/helpers.resolveImg}'s rule, reached through it rather
+     * than restated, which is also what puts an art address and a body image
+     * through one ownership rule.
+     *
+     * An address nothing answers is reported against the note and treated as
+     * unnamed, so the document takes its default rather than shipping a path
+     * that installs nowhere.
+     *
+     * @param {unknown} value - The value as authored.
+     * @param {string} key - The key it was authored at, for the message.
+     * @param {string} type - The asset type a bare value takes.
+     * @returns {string|null} The Foundry-relative path, `""` for a deliberate
+     *   blank, or `null` where the note names none.
+     */
+    artPathOf(value: unknown, key: string, type: string): string | null;
+    /**
+     * The Foundry path one art slot of a note names, or `null`.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} key - The slot's key under `data:`.
+     * @returns {string|null} As {@link BasePackCompiler#artPathOf}.
+     */
+    artPath(fm: object, key: string): string | null;
     /**
      * Reports a warning about the note being compiled.
      *

package/types/engine/compile-corpus.d.mts

@@ -3,6 +3,8 @@
  *
  * @param {object} opts - Options.
  * @param {string} opts.contentBase - Root of the content tree.
+ * @param {string} [opts.assetsBase] - The asset roots' parent, whose files the
+ *   art addresses resolve against. Defaults to the configured one.
  * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
  *   caller as every corpus read requires.
  * @param {object} opts.router - The pack router this compile resolved. Shared
@@ -17,8 +19,9 @@
  *   sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
-export function buildCompileCorpus({ contentBase, skipDirectories, router, config, problems, }: {
+export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, }: {
     contentBase: string;
+    assetsBase?: string | undefined;
     skipDirectories: readonly string[];
     router: object;
     config?: object | undefined;

package/types/engine/content-charset.d.mts

@@ -78,6 +78,10 @@ export function checkText(text: string, file: string): Array<{
  * theoretical exclusion — it was the first thing a run over `sohl-thalorna`
  * reported before the skip existed.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore

package/types/engine/content-embeds.d.mts

@@ -0,0 +1,218 @@
+/**
+ * One embed, parsed.
+ *
+ * @typedef {object} ParsedEmbed
+ * @property {string} all - The embed exactly as authored, directive included.
+ * @property {string} inner - The whole interior of the brackets.
+ * @property {string} written - The link part as authored, anchor included. An
+ *   embed names a file and a file has no sections, so an anchor is carried into
+ *   the address rather than stripped off it — where it fails the address charset
+ *   and is reported as what it is.
+ * @property {string|null} display - The text after `|`, `null` when unlabelled.
+ * @property {boolean} labelled - Whether a `|` was present at all.
+ * @property {string} directive - The `{…}` as written, or `""`.
+ * @property {number} index - Where the embed begins in the body.
+ * @property {number} length - How much of the body it occupies.
+ * @property {boolean} block - Whether it stands alone in its own paragraph.
+ */
+/**
+ * Every embed in one body, in source order.
+ *
+ * Code is skipped, because an embed shown as an example is prose *about* an
+ * embed — which is what makes this module's own documentation writable.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @returns {ParsedEmbed[]} One entry per embed.
+ */
+export function embedsIn(body: string): ParsedEmbed[];
+/**
+ * What one embed resolves to, or why it does not.
+ *
+ * The reasons are {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS},
+ * the vocabulary every resolver shares, so an author meets one wording for one
+ * mistake whichever build they ran first.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {ParsedEmbed} embed - The embed.
+ * @returns {{pathname: string}|{reason: string, target: string, type?: string}}
+ *   The authored pathname the picture is at, or the finding.
+ */
+export function resolveEmbed(index: object, embed: ParsedEmbed): {
+    pathname: string;
+} | {
+    reason: string;
+    target: string;
+    type?: string;
+};
+/**
+ * What is wrong with one embed's directive or placement, if anything.
+ *
+ * Separate from the link findings beside it because the two speak different
+ * vocabularies: a link finding is a `reason` from the closed set every resolver
+ * shares, and this is an image's own complaint about a brace or a paragraph.
+ * Collapsing them would put a sentence where a `reason` belongs.
+ *
+ * @param {ParsedEmbed} embed - The embed.
+ * @returns {Array<{link: string, offset: number, message: string}>} One entry
+ *   per defect. `link` is the embed exactly as authored, which is what lets a
+ *   caller with no offsets locate it by searching the note for the literal.
+ */
+export function embedProblems(embed: ParsedEmbed): Array<{
+    link: string;
+    offset: number;
+    message: string;
+}>;
+/**
+ * Rewrite every embed in one body into the image each surface already renders.
+ *
+ * An embed that does not resolve is left **exactly as authored** and reported,
+ * so a missing picture degrades to visible literal text rather than to a broken
+ * `src` or a swallowed paragraph. So is one whose directive does not parse: a
+ * directive holding a problem is not honoured at all, and the braces reaching
+ * the page as their own literal text is how the mistake is visible without a
+ * log.
+ *
+ * Call this **before** wikilink resolution. The rewrite consumes the `!` along
+ * with the brackets, which is what stops the link pass reading an embed's
+ * interior as an ordinary link to a note that does not exist.
+ *
+ * @param {string} body - The note's markdown, tables already expanded.
+ * @param {object} ctx
+ * @param {object} ctx.index - The address index assets resolve through.
+ * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
+ *   offset: number, reason: string, type?: string}>,
+ *   problems: Array<{link: string, offset: number, message: string}>,
+ *   images: Array<{link: string, offset: number, pathname: string}>}} The body,
+ *   the embeds that named nothing, the directives that could not be honoured,
+ *   and the pathname each embed that did resolve now names. Every `offset` is
+ *   0-based in `body`, which is what lets a caller report a line and a column
+ *   and tell two identical embeds apart.
+ *
+ *   **`images` is how a surface holds an embed to its own rule.** The rewrite
+ *   is surface-agnostic — a file the website serves and the book stages is not
+ *   always one a Foundry install carries — so a caller that cares asks about
+ *   the pathname while it still knows which embed produced it, rather than
+ *   searching a rewritten body for a literal the note never wrote.
+ */
+export function resolveEmbeds(body: string, { index }: {
+    index: object;
+}): {
+    markdown: string;
+    unresolved: Array<{
+        link: string;
+        target: string;
+        offset: number;
+        reason: string;
+        type?: string;
+    }>;
+    problems: Array<{
+        link: string;
+        offset: number;
+        message: string;
+    }>;
+    images: Array<{
+        link: string;
+        offset: number;
+        pathname: string;
+    }>;
+};
+/**
+ * Every defect in one note's embeds, located.
+ *
+ * {@link resolveEmbeds} with its two lists turned into the one shape a finding
+ * takes, for a caller that wants the report and not the rewrite.
+ *
+ * **Errors, not warnings**, for the reason an image's are: `reportFindings`
+ * fails on an error and not on a warning, so a refusal reported as advisory
+ * publishes anyway, looking exactly like a directive that worked.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {object} [opts.index] - The address index assets resolve through.
+ * @returns {Array<{file: string, line: number, column: number|undefined,
+ *   severity: "error", message: string}>} One finding per defect, in source
+ *   order.
+ */
+export function checkEmbeds(body: string, file: string, { bodyLine, bodyColumn, index }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    index?: object | undefined;
+}): Array<{
+    file: string;
+    line: number;
+    column: number | undefined;
+    severity: "error";
+    message: string;
+}>;
+/**
+ * The type a bare shortcode takes, supplied by the syntax itself.
+ *
+ * A picture is what `!` asks for, so `image` is what an unqualified embed names.
+ * An icon is reached by stating it — `![[icon-anvil|An anvil]]` — because the two
+ * have separate shortcode namespaces and neither is derivable from the other.
+ *
+ * @type {string}
+ */
+export const EMBED_DEFAULT_TYPE: string;
+/**
+ * An embed, as authored, with the directive it may carry.
+ *
+ * The interior admits no `]` or newline, exactly as a wikilink's does: an embed
+ * is written on one line, and an unclosed `![[` is a typo rather than licence to
+ * consume the rest of the document looking for a closer.
+ *
+ * The directive is `{…}` immediately after the closing `]]`, holding no newline,
+ * for the reason {@link module:engine/content-images.IMAGE_PATTERN} gives: a
+ * brace that opens and never closes on its line is prose.
+ *
+ * @type {RegExp}
+ */
+export const EMBED_PATTERN: RegExp;
+/**
+ * One embed, parsed.
+ */
+export type ParsedEmbed = {
+    /**
+     * - The embed exactly as authored, directive included.
+     */
+    all: string;
+    /**
+     * - The whole interior of the brackets.
+     */
+    inner: string;
+    /**
+     * - The link part as authored, anchor included. An
+     * embed names a file and a file has no sections, so an anchor is carried into
+     * the address rather than stripped off it — where it fails the address charset
+     * and is reported as what it is.
+     */
+    written: string;
+    /**
+     * - The text after `|`, `null` when unlabelled.
+     */
+    display: string | null;
+    /**
+     * - Whether a `|` was present at all.
+     */
+    labelled: boolean;
+    /**
+     * - The `{…}` as written, or `""`.
+     */
+    directive: string;
+    /**
+     * - Where the embed begins in the body.
+     */
+    index: number;
+    /**
+     * - How much of the body it occupies.
+     */
+    length: number;
+    /**
+     * - Whether it stands alone in its own paragraph.
+     */
+    block: boolean;
+};

package/types/engine/content-html.d.mts

@@ -39,6 +39,10 @@ export function checkHtml(body: string, file: string, { bodyLine, bodyColumn }?:
  * whole: it is not a note, but a stray `.md` in the tree carrying markup is the
  * same problem for the same reason.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore

package/types/engine/content-icons.d.mts

@@ -111,6 +111,10 @@ export function checkIconRegistry(registry: {
  * with nothing imported between them. The cost is one extra pass over the tree,
  * which is the cheaper half of a lint that already parses every note.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.

package/types/engine/content-images.d.mts

@@ -123,13 +123,19 @@ export function imageSourcesIn(body: string): string[];
  * @param {object} [opts]
  * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
  * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {object} [opts.config] - The resolved build configuration. Supplied,
+ *   an address is also held to the one surface a pathname can be dead on
+ *   without any other pass noticing — see the Foundry address below. Omitted,
+ *   the config-free checks run alone, which is what lets a caller with no
+ *   repository to resolve still read a body.
  * @returns {Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body: string, file: string, { bodyLine, bodyColumn }?: {
+export function checkImages(body: string, file: string, { bodyLine, bodyColumn, config }?: {
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;
+    config?: object | undefined;
 }): Array<{
     file: string;
     line: number;
@@ -143,16 +149,23 @@ export function checkImages(body: string, file: string, { bodyLine, bodyColumn }
  * Its own walk, like the icon and HTML checks beside it, so all three stay
  * leaves with nothing imported between them.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {object} [opts.config] - The resolved build configuration, passed to
+ *   {@link checkImages} so an address is held to the Foundry surface too.
  * @returns {{findings: Array<{file: string, line: number, column: number|undefined,
  *   severity: "error", message: string}>, files: number}} The findings, and how
  *   many files were read.
  */
-export function lintContentImages(contentBase: string, { skipDirectories }?: {
+export function lintContentImages(contentBase: string, { skipDirectories, config }?: {
     skipDirectories?: readonly string[] | undefined;
+    config?: object | undefined;
 }): {
     findings: Array<{
         file: string;

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

@@ -31,16 +31,6 @@ export function noteAddress(frontmatter: Record<string, any>, contentPackage: st
     slug: string;
     canonical: string;
 } | null;
-/**
- * Recursively sort an object's keys, so serialization is order-independent.
- *
- * Arrays keep their order — it is authored — but every object inside one is
- * sorted too. Anything that is not a plain object is returned as it is.
- *
- * @param {unknown} value - The value to normalize.
- * @returns {unknown} The value with every plain object's keys in sorted order.
- */
-export function sortKeysDeep(value: unknown): unknown;
 /**
  * A note's display name reduced to printable 7-bit ASCII.
  *
@@ -129,12 +119,22 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
  * An item note yields two records — the item, and the documentation journal
  * that is a document in its own right.
  *
+ * **The asset roots are walked in the same pass.** A package's addressable files
+ * sit beside `content/` rather than inside it, and they publish into the same
+ * index under the same address grammar — so there is no second walk, no second
+ * artifact, and no notion of an "art module" anywhere in the toolchain. A
+ * package whose tree holds only assets is one by consequence.
+ *
  * @param {string} contentBase - The content tree to walk.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package the tree compiles as.
  * @param {readonly string[]} options.skipDirectories - The walk's scope, stated
  *   by the caller. An absent one is the caller's omission, and
  *   {@link module:engine/helpers.walkMarkdownTree} throws on it.
+ * @param {string} [options.assetsBase] - The package's asset directory, holding
+ *   the three asset roots. Omitted, no asset is indexed — which is what a caller
+ *   walking a bare content fixture wants, and what an asset-free package gets
+ *   anyway.
  * @param {object} [options.manifest] - The package manifest, which the Foundry
  *   entries are derived against.
  * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
@@ -144,9 +144,10 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, manifest, problems }: {
+export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems }: {
     contentPackage: string;
     skipDirectories: readonly string[];
+    assetsBase?: string | undefined;
     manifest?: object | undefined;
     problems?: object[] | undefined;
 }): Array<Record<string, any>>;
@@ -170,6 +171,10 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *
  * @param {object} [opts]
  * @param {string} [opts.contentBase] - The tree, defaulting to the configured one.
+ * @param {string} [opts.assetsBase] - The asset roots' parent, defaulting to
+ *   the configured one. Stated separately from `contentBase` because the two
+ *   move independently — a caller walking an assembled fixture tree says where
+ *   that fixture's files are.
  * @param {object} [opts.config] - Resolved configuration, defaulting to ambient.
  * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, for a
  *   caller that resolved one of its own; defaults to the resolved
@@ -183,8 +188,9 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  *   exist.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, config, skipDirectories, problems }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, }?: {
     contentBase?: string | undefined;
+    assetsBase?: string | undefined;
     config?: object | undefined;
     skipDirectories?: readonly string[] | undefined;
     problems?: object[] | undefined;
@@ -198,8 +204,9 @@ export function indexRecordsFor({ contentBase, config, skipDirectories, problems
  * @param {string} [options.outDir] - Where to write; defaults to the configured
  *   `paths.contentIndex`.
  * @param {object} [options.config] - A resolved configuration; loaded when omitted.
- * @returns {{file: string, notes: number, bytes: number}} Where it was written,
- *   how many notes it holds, and its size.
+ * @returns {{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.
  * @throws {Error} When the content tree is absent, or when it yields no note at
  *   all — an empty index is indistinguishable from a mis-pointed tree, and a
  *   reader would take it as the authoritative statement that this package has
@@ -212,11 +219,16 @@ export function emitContentIndex({ contentBase, outDir, config }?: {
 }): {
     file: string;
     notes: number;
+    assets: number;
+    records: number;
     bytes: number;
 };
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";
+import { isAssetRecord } from "./index-records.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { noteFile } from "./index-records.mjs";
-export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isNoteRecord, noteFile };
+import { recordPath } from "./index-records.mjs";
+import { sortKeysDeep } from "./index-records.mjs";
+export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, noteFile, recordPath, sortKeysDeep };

package/types/engine/frontmatter-lint.d.mts

@@ -240,27 +240,24 @@ export const UNIVERSAL_KEYS: ReadonlySet<string>;
  */
 export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, SystemBlockSpec>>;
 /**
- * The frontmatter fields that name artwork, and so resolve through
- * {@link module:engine/helpers.resolveImg}.
+ * The frontmatter fields that name artwork.
  *
- * Both, always: a being carries `img` and `portrait` independently — the token
- * art and the sheet portrait — and a rule about how the translator reads an
- * empty value belongs to the translator, not to whichever key happens to be
- * more common. Eleven `sohl-kethira-basic` beings write `portrait: ""` and no
- * note in any tree writes `img: ""` on a being; a check keyed on `img` alone
- * would have called that tree clean.
+ * {@link module:engine/art-fields.ART_SLOTS} is the declaration; this is that
+ * list in the shape the checks below read, so the linter states no art key of
+ * its own and a slot added there is checked here with no second edit. All four
+ * are authored under `data:`, which is what `inData` records.
  *
- * **Each carries where it is authored**, because the two no longer agree. The
- * specification puts an actor's portrait under `data:` and leaves its token art
- * at the note's top level, so `portrait` has a third position to read and `img`
- * does not — and a check that read only the two they share would pass a
- * `data.portrait: ""` it could not see.
+ * `document` separates the three that reach a compiled document from `banner`,
+ * which reaches none by design. The inert-art check reads it: a key that is
+ * *meant* to reach no document is not an inert key, and reporting every note
+ * that names a hero image would bury the finding that matters.
  *
- * @type {readonly {key: string, inData: boolean}[]}
+ * @type {readonly {key: string, inData: boolean, document: boolean}[]}
  */
 export const ART_FIELDS: readonly {
     key: string;
     inData: boolean;
+    document: boolean;
 }[];
 /**
  * What one system block accepts beyond the keys every block carries.

package/types/engine/helpers.d.mts

@@ -385,6 +385,9 @@ export function buildContentLinkIndex(contentBase: string, router?: object, { sk
  *   in, addressing a self-link the same way.
  * @param {object} ctx.index - The address index every link resolves through.
  * @param {string} ctx.name - The note, for the message.
+ * @param {object} [ctx.config] - The resolved build configuration, which is
+ *   what says which packages this build can address a file in. Loaded when
+ *   omitted, exactly as an art field's resolution loads it.
  * @param {string} [ctx.file] - The note's file, so a report names it.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line.
  * @param {number} [ctx.bodyColumn] - 1-based file column of the same character.
@@ -392,17 +395,19 @@ export function buildContentLinkIndex(contentBase: string, router?: object, { sk
  *   authored line each body line came from, from {@link expandNoteTables}.
  * @returns {{markdown: string, unresolved: Array<object>}}
  * @throws {Error} On any link that does not resolve — an unlabelled one, a
- *   target that is not an address, or an address nothing publishes. The error
+ *   target that is not an address, or an address nothing publishes — and on a
+ *   body image whose pathname names no file a Foundry install serves. The error
  *   carries `file` and `position`, so a caller reports it in the same form
  *   rather than re-deriving one.
  */
-export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap }: {
+export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap, config }: {
     type: string;
     id: string;
     pack: string;
     docPack: string;
     index: object;
     name: string;
+    config?: object | undefined;
     file?: string | undefined;
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;

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

@@ -1,3 +1,13 @@
+/**
+ * Recursively sort an object's keys, so serialization is order-independent.
+ *
+ * Arrays keep their order — it is authored — but every object inside one is
+ * sorted too. Anything that is not a plain object is returned as it is.
+ *
+ * @param {unknown} value - The value to normalize.
+ * @returns {unknown} The value with every plain object's keys in sorted order.
+ */
+export function sortKeysDeep(value: unknown): unknown;
 /**
  * The file a record was read from, as an absolute path.
  *
@@ -36,19 +46,50 @@ export function noteFile(contentBase: string, record: object): string;
  */
 export function authoredFrontmatter(record: Record<string, any>): Record<string, any>;
 /**
- * Whether a record is a note's, rather than a documentation journal's.
+ * Whether a record addresses a **file** rather than a note.
+ *
+ * The index holds two record shapes in one file, and this is how a reader tells
+ * them apart. An asset record carries no frontmatter, no anchors and no
+ * `foundry` block — a `.webp` declares nothing about itself — so every pass that
+ * reads a note's fields has to skip it, and the `asset` block is what marks it.
+ *
+ * Asked of the block rather than of `type`, so a fourth asset type needs no
+ * edit here: what makes a record an asset's is that it describes a file, and the
+ * block is the description.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {boolean} True for an asset's record.
+ */
+export function isAssetRecord(record: Record<string, any>): boolean;
+/**
+ * Whether a record is a note's, rather than a documentation journal's or an
+ * asset's.
  *
  * An item note yields two records — itself and the JournalEntry its prose
  * compiles into — and the second is a document, not a note: it has no file of
  * its own to read, no frontmatter an author wrote, and its `type` is the
  * virtual `doc<type>` that `readQualifier` resolves rather than a type any tree
- * declares. A reader enumerating the corpus wants the notes; one resolving an
- * address wants both.
+ * declares. An asset's record is not a note either, for the stronger reason that
+ * nobody authored it at all. A reader enumerating the corpus wants the notes;
+ * one resolving an address wants all three.
  *
  * @param {Record<string, any>} record - An index record.
  * @returns {boolean} True for a note's own record.
  */
 export function isNoteRecord(record: Record<string, any>): boolean;
+/**
+ * The path a record names inside its package, whichever shape it is.
+ *
+ * The two shapes state it differently and honestly: a note names the `.md` it
+ * was parsed from, relative to the content root, while an asset names the file
+ * it *is*, relative to the package's asset directory. Both are paths within one
+ * package, so one total order covers the whole index — which is what keeps the
+ * artifact byte-stable across a rebuild.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {string} The path, or `""` for a record naming neither.
+ */
+export function recordPath(record: Record<string, any>): string;
 /**
  * The keys the content index adds to a record, which a note therefore may not
  * carry itself.

package/types/engine/index.d.mts

@@ -27,12 +27,17 @@ export * as noteRenames from "./note-renames.mjs";
 export * as metadataIndex from "./metadata-index.mjs";
 export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
+export * as assetTypes from "./asset-types.mjs";
+export * as assetIndex from "./asset-index.mjs";
+export * as packages from "./packages.mjs";
+export * as packagebuildIndex from "./packagebuild-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";
 export * as contentImages from "./content-images.mjs";
+export * as contentEmbeds from "./content-embeds.mjs";
 export * as pathnames from "./pathnames.mjs";
 export * as contentLinks from "./content-links.mjs";
 export * as webWikilinks from "./web-wikilinks.mjs";