@heroiclands/package-build 22.22.0 → 22.23.0

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

@@ -51,14 +51,17 @@ export function compilesSystemDocument(fm: object, map: object, router: object):
  * @param {object} [options.router] - The pack router deciding which system
  *   compiles a document for this note. Defaults to the consuming repository's.
  * @param {object} [options.dates] - Calendar conversion context.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @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, router, dates }?: {
+export function noteInfoboxes(fm: object, { resolve, router, dates, contentPackage }?: {
     resolve?: ((ref: unknown, hint?: object) => object | undefined) | undefined;
     router?: object | undefined;
     dates?: object | undefined;
+    contentPackage?: string | undefined;
 }): object[];
 /**
  * Every system's infobox declaration, in the order a page shows them.

package/types/engine/infobox.d.mts

@@ -154,12 +154,15 @@ export function linkValue(ref: unknown, resolve: (ref: unknown, hint?: object) =
  * @param {object} [options] - Options.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a relation row's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @param {object} [options.presentation] - The overlay to read.
  * @returns {object} The box.
  */
 export function noteInfobox(fm: object, options?: {
     resolve?: ((ref: unknown) => object | undefined) | undefined;
+    contentPackage?: string | undefined;
     vocabulary?: object | undefined;
     presentation?: object | undefined;
 }): object;
@@ -268,6 +271,8 @@ export function systemRowsSection(fm: object, fields: readonly object[], { block
  *   Resolves one declared field against the note.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @returns {object[]} The boxes.
  */
@@ -277,6 +282,7 @@ export function buildInfoboxes(fm: object, options: {
     compilesDocument: (fm: object, map: object) => boolean;
     resolveField: (field: object, fm: object, opts: object) => object;
     resolve?: ((ref: unknown) => object | undefined) | undefined;
+    contentPackage?: string | undefined;
     vocabulary?: object | undefined;
 }): object[];
 /**

package/types/engine/journals.d.mts

@@ -1,8 +1,8 @@
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
- * code blocks are respected so `# foo` inside ``` blocks doesn't trigger
- * a split. Content before the first H1 (if non-empty) becomes a leading
- * page. Each H1 yields a page whose name is the heading
+ * code blocks are respected so `# foo` inside ``` or ~~~ blocks doesn't
+ * trigger a split. Content before the first H1 (if non-empty) becomes a
+ * leading page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
  * `anchorSlug`). The classes the heading declares come along as `classes`, so
  * a surface that honours one has it without reading the suffix again.
@@ -13,16 +13,26 @@
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
+ * A figure fence carries its own record along onto the page it starts, as
+ * `figure` — `null` for a page a heading started. {@link buildPages} reads it
+ * to build the `image` or `text` page a fence begins; nothing else sets it.
+ *
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   classes: string[], markdown: string}>} Pages in document order.
+ *   classes: string[], figure: object|null, markdown: string}>} Pages in
+ *   document order.
  */
-export function splitPages(body: string, leadName?: string): Array<{
+export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
     classes: string[];
+    figure: object | null;
     markdown: string;
 }>;
 /**
@@ -101,15 +111,22 @@ export function journalPageId(entryId: string, page: {
  * @param {string} noteName - The note, for error messages.
  * A page whose heading carries `.secret` is given to the GM alone, by the one
  * ownership value Foundry reads as "nobody but a GM". Every other page states
- * no ownership and inherits the journal's.
- *
+ * no ownership and inherits the journal's. A figure-started page states none
+ * either: {@link scanFigures} validates a figure's classes against its own
+ * closed vocabulary, which carries no `.secret`.
+ *
+ * @param {Array<object>} figures - From {@link scanFigures}, numbered across
+ *   the whole note. Read by a page a heading started; a page a figure started
+ *   carries its own figure already, from {@link splitPages}.
+ * @param {(address: string) => string|undefined} [resolveRole] - See
+ *   {@link splitPages}.
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
  *   text: {format: number, content: string}, _key: string,
  *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
-export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, captions: any): Array<{
+export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, figures: Array<object>, resolveRole?: (address: string) => string | undefined): Array<{
     _id: string;
     name: string;
     type: string;
@@ -156,9 +173,13 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
+ * @param {(address: string) => string|undefined} [params.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, }: {
     id: string;
     name: string;
     markdown: string;
@@ -171,6 +192,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, stats,
         html: string;
     }[] | undefined;
     notice?: string | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
 }): object;
 /**
  * Journals pack compiler.

package/types/engine/lore-events.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Validate one `lore` note's `data.events`.
+ *
+ * Registered as the `events` field's own `check` in `note-vocabulary.mjs`, so
+ * it runs on every `lore` note regardless of `subType` — an occasion is not a
+ * calendar fact, and nothing here is scoped to `subType: calendar`.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {{index?: object}} [options]
+ * @returns {object[]} Findings, each positioned at the entry that earned it.
+ */
+export function checkLoreEvents(note: object, { index }?: {
+    index?: object;
+}): object[];

package/types/engine/markdown-expressions.d.mts

@@ -3,12 +3,33 @@ export function sqlQueriesInMarkdown(body: any, fm?: {}): any[];
 /**
  * Expand scalar frontmatter references and registered functions in Markdown prose.
  * @param {string} body
- * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>, file?: string, bodyLine?: number}} [options]
+ * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>,
+ *   figures?: {get: (id: string) => {label: string, caption: string,
+ *   hasCaption: boolean}|undefined, note?: (address: string) =>
+ *   {url: string|null, figures: Map<string, object>}|undefined,
+ *   link?: Function}, file?: string, bodyLine?: number}} [options] -
+ *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
+ *   note's `:::figure` fences by id, and `note` resolves another note's the
+ *   way a wikilink would — omitted, a cross-note address is refused rather
+ *   than looked up. `link` overrides how a resolved reference renders; the
+ *   default is a Markdown link to the target's own anchor.
  */
-export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, file, bodyLine }?: {
+export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, figures, file, bodyLine }?: {
     fm?: object;
     dates?: object;
     sqlResults?: Map<string, object>;
+    figures?: {
+        get: (id: string) => {
+            label: string;
+            caption: string;
+            hasCaption: boolean;
+        } | undefined;
+        note?: (address: string) => {
+            url: string | null;
+            figures: Map<string, object>;
+        } | undefined;
+        link?: Function;
+    };
     file?: string;
     bodyLine?: number;
 }): {

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

@@ -91,8 +91,71 @@ export function formatNoteDate(date: any, era: any, daysPerYear: any, formatName
     text: string;
     prose: string | null;
 } | null;
+/**
+ * The occurrences of one recurring series overlapping a bound.
+ *
+ * **No materialized occurrence list.** An annual series anchored centuries
+ * back has thousands of occurrences to the present, and the only questions a
+ * build asks are "is this year one of them" and "which is next" — so an
+ * omitted bound answers with a single occurrence rather than every one a live
+ * series could have:
+ *
+ * - `to` omitted: the first occurrence at or after `from` (default, the
+ *   anchor's own year) — "next".
+ * - `from` omitted, `to` given: the last occurrence at or before `to` —
+ *   "the greatest occurrence at or before `until`".
+ * - Both given: every occurrence between them, inclusive — a membership
+ *   probe is `from === to`.
+ *
+ * **The lower bound is not optional.** A candidate year before the anchor's
+ * own year is never an occurrence, however a bare modulo would read it: `%`
+ * takes the sign of its dividend in both JavaScript and SQL, so a year
+ * exactly one period before the anchor would otherwise match. `k` is clamped
+ * at zero rather than left to run negative.
+ *
+ * **The period advances the canonical year, never the era-relative year.**
+ * `date.canonicalYear` is already on the continuous axis `canonicalYear`
+ * builds — era year `-1` sits immediately before era year `1`, but canonical
+ * year `0` is an ordinary integer between them — so stepping by whole
+ * multiples of `every` on `canonicalYear` crosses an epoch with no special
+ * case. Counting in era-relative years instead would need a correction at
+ * every crossing and silently loses one year each time it is forgotten.
+ *
+ * **Precision, approximation and the day of year carry through untouched.**
+ * Every occurrence is the anchor's own record with only `canonicalYear`
+ * advanced, so a day-precision anchor's `canonicalDay` — including one inside
+ * a short intercalary month — names the same day of every occurrence, and an
+ * approximate anchor's occurrences are approximate too.
+ *
+ * @param {object} date - The anchor's resolved record
+ *   ({@link parseNoteDate}), carrying a real `canonicalYear`. A year-0 "any
+ *   year" anchor carries none and has no series through this function — its
+ *   `recurs` is refused, and its own next occurrence is computed directly
+ *   from the day of year alone.
+ * @param {{every?: number, on?: object[]}} [recurs] - The declared
+ *   recurrence: a whole-year period, or an enumeration of further resolved
+ *   date records (each already carrying its own `canonicalYear`). Neither
+ *   admits the other.
+ * @param {object} [bounds]
+ * @param {number} [bounds.from] - The lower bound, inclusive, as a canonical
+ *   year.
+ * @param {number} [bounds.to] - The upper bound, inclusive, as a canonical
+ *   year.
+ * @returns {object[]} Occurrence records, in increasing order.
+ */
+export function occurrencesOf(date: object, recurs?: {
+    every?: number;
+    on?: object[];
+}, { from, to }?: {
+    from?: number | undefined;
+    to?: number | undefined;
+}): object[];
 /** Normalize a note's declared dates for indexes and generated pages. */
-export function resolvedDateFields(fm: any, context: any): {};
+export function resolvedDateFields(fm: any, context: any): {
+    events: any;
+} | {
+    events?: undefined;
+};
 /**
  * The literal that says a thing happened and the date is not recorded.
  *

package/types/engine/pathnames.d.mts

@@ -82,6 +82,32 @@ 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;
+/**
+ * The pathname one authored image address keys an asset's role and pixel
+ * size under — `<package>/assets/<suffix>`, the same key
+ * {@link module:engine/art-fields.assetImageInfoByPathname} builds from the
+ * asset record itself.
+ *
+ * **Why this exists apart from `resolvePathname`'s own forms.** An embed
+ * rewrites to that exact pathname — see
+ * {@link module:engine/content-embeds.resolveEmbeds} — but an author's own
+ * body image is free to write the bare, own-package form instead
+ * (`images/m.webp`), which names the identical file without naming the
+ * package. The two forms have to key the same lookup, and `resolvePathname`
+ * already answers which package a bare form belongs to; this just restates
+ * that answer in the one shape a renderer looks a picture's role up by.
+ *
+ * **Never throws.** A lookup is a best-effort read, not a validation — the
+ * pathname lint is what refuses a Foundry-spelled address — so a value
+ * {@link resolvePathname} refuses outright answers `null` here as well, the
+ * same as a blank or an external one.
+ *
+ * @param {string} src - The address, as authored or as an embed resolved it.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string|null} The pathname, or `null` for an address naming no
+ *   asset record to look up.
+ */
+export function assetPathnameKey(src: string, config: object): string | null;
 /**
  * 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

@@ -13,17 +13,34 @@
  * makes the source a consumer can compile by hand with no flags, and what keeps
  * a build from touching a path outside its own output.
  *
- * Only a file **this** package ships can be staged. A pathname naming another
- * package's file, or a URL, names something no build here can open — a build
- * reaches no network — and the caller reports it as a picture the book will not
- * carry.
+ * A file **this** package ships stages directly. A pathname naming another
+ * package's file stages instead from a declared replacement's cached archive,
+ * when `opts.resolveReplacement` — the pure function
+ * {@link module:engine/asset-replacement.resolveAssetReplacement} —
+ * answers it; `opts.foreignIndex` is the merged index that answer is read
+ * against. A pathname naming a package no replacement carries it for, or a
+ * URL, names something no build here can open — a build reaches no network —
+ * and the caller reports it as a picture the book will not carry.
  *
  * @param {string} src - The pathname, as authored.
  * @param {object} config - The resolved configuration.
+ * @param {object} [opts]
+ * @param {Map<string, object>} [opts.foreignIndex] - Every fetched
+ *   dependency's own records, keyed by canonical address — the index a
+ *   replacement's record is read out of.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, or an
+ *   equivalent a caller injects for a test. Omitted, a foreign pathname this
+ *   package does not own stays declined exactly as it always has.
  * @returns {{from: string, to: string}|null} The file, and where under the
  *   output directory it is staged.
+ * @throws {Error} When a declared replacement answers the address but its
+ *   archive was never fetched.
  */
-export function stagedImagePath(src: string, config: object): {
+export function stagedImagePath(src: string, config: object, opts?: {
+    foreignIndex?: Map<string, object> | undefined;
+    resolveReplacement?: Function | undefined;
+}): {
     from: string;
     to: string;
 } | null;
@@ -66,13 +83,18 @@ export function pdfFileName(artifact: string, version: string): string;
  * @param {string} [opts.version] - Stamped on the title page and the file name.
  * @param {boolean} [opts.compile] - Whether to run Typst. False leaves the
  *   `.typ` source, which is what the unit tests read.
+ * @param {Function} [opts.resolveReplacement] - {@link
+ *   module:engine/asset-replacement.resolveAssetReplacement}, for tests.
+ *   Loaded from that module otherwise, and only when a relationship declares
+ *   `assetReplacement: true` — a build with none never imports it.
  * @returns {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.
  */
-export function buildPdf({ config, out, version, compile }?: {
+export function buildPdf({ config, out, version, compile, resolveReplacement, }?: {
     config?: object | undefined;
     out?: string | undefined;
     version?: string | undefined;
     compile?: boolean | undefined;
+    resolveReplacement?: Function | undefined;
 }): Promise<object>;
 /**
  * The command line the compile runs, as data.

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

@@ -1,3 +1,33 @@
+/**
+ * The width the book draws one picture at, in inches, when nothing authored
+ * narrows it to a named `size=`.
+ *
+ * > drawn width = min(the role's slot, natural pixels ÷ the print floor)
+ *
+ * **Every size here is a maximum, never a target**: a picture is never drawn
+ * larger than it was made. The print floor is {@link PDF_PAGE.dpi}, the same
+ * constant the page geometry above is set against, so a role's slot and the
+ * page it is drawn on cannot disagree about what a pixel is worth.
+ *
+ * An icon-type address takes the nominal icon width whatever role it might
+ * otherwise carry — `role` never reaches one, since the asset record refuses
+ * it there. A vector carries no pixel count, so nothing narrows its role's
+ * slot. A picture declaring no role answers `undefined`: the medium's
+ * ordinary size, decided elsewhere by a named `size=` or by its own natural
+ * pixels within whatever it is set in.
+ *
+ * @param {object} [asset] - What {@link module:engine/art-fields.assetImageInfoByPathname}
+ *   records for the picture's address.
+ * @param {string} [asset.type] - The asset's type — `icon` or `image`.
+ * @param {string} [asset.role] - The picture's declared role.
+ * @param {number|""} [asset.width] - The file's own pixel width; blank for a vector.
+ * @returns {number|undefined} The drawn width, in inches.
+ */
+export function bookImageWidthIn({ type, role, width }?: {
+    type?: string | undefined;
+    role?: string | undefined;
+    width?: number | "" | undefined;
+}): number | undefined;
 /**
  * Optimize staged raster images without changing their authored files.
  *
@@ -36,3 +66,25 @@ export const pdfTextWidth: number;
 /** Usable height of a portrait page in inches. */
 export const pdfTextHeight: number;
 export function pdfColumnWidth(columns?: number): number;
+/**
+ * The fraction of the page's one-column measure a picture's role may fill at
+ * most — one table, read by {@link bookImageWidthIn}, so a policy change here
+ * is the one line it costs rather than an edit to every note drawing a role.
+ *
+ * A `portrait` or an `emblem` names a subject or a mark, which sits beside
+ * prose rather than replacing a page of it; a `banner`, a `plate` and a `map`
+ * are each meant to be looked at in full. The measure is the page's own text
+ * width, {@link pdfTextWidth}, so a role's slot does not shrink when a page
+ * happens to be set in two columns — it is what the picture is *for* that
+ * sets the slot, not the layout it lands in.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const BOOK_ROLE_SLOTS: Readonly<Record<string, number>>;
+/**
+ * The book's nominal width for an icon-type picture, in inches, whatever its
+ * file holds — almost every icon is an SVG with no pixel count to measure.
+ *
+ * @type {number}
+ */
+export const BOOK_ICON_WIDTH_IN: number;

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

@@ -69,6 +69,12 @@ export function stripHtmlComments(markdown: string): string;
  *   the staged file's path, relative to the `.typ`. An address this does not
  *   carry has no file the compiler can open, so the figure prints its caption
  *   alone — see {@link renderImage}.
+ * @param {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   [opts.assets] - An image's address as authored → what
+ *   {@link module:engine/art-fields.assetImageInfoByPathname} records for it,
+ *   which is what sizes a picture carrying no named `size=` — see
+ *   {@link module:engine/pdf-images.bookImageWidthIn}. An address missing from
+ *   this map draws at the medium's ordinary size, the same as today.
  * @param {number} [opts.headingOffset] - Added to every heading level, so a
  *   note's own `##` nests beneath the entry heading the book gave it.
  * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
@@ -101,6 +107,12 @@ export function markdownToTypst(markdown: string, opts?: {
     links?: Map<string, string> | undefined;
     glyphs?: Map<string, string> | undefined;
     images?: Map<string, string> | undefined;
+    assets?: Map<string, {
+        type: string;
+        role?: string;
+        width: number | "";
+        height: number | "";
+    }> | undefined;
     headingOffset?: number | undefined;
     anchorPrefix?: string | undefined;
     findings?: object[] | undefined;

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

@@ -237,7 +237,7 @@ export function pageDestination(page: {
     bundle?: boolean | undefined;
 }): string;
 /** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, }: {
+export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, }: {
     index: any;
     foreign: any;
     universe: any;
@@ -247,6 +247,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     sqlTables: any;
     config: any;
     artIndex: any;
+    figuresByAddress?: Map<any, any> | undefined;
 }): {
     page: any;
     body: string;
@@ -280,6 +281,13 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     }[];
     wikiErrors: any[];
     imageErrors: any[];
+    embedErrors: {
+        file: string;
+        line: number;
+        column: number | undefined;
+        severity: "error";
+        message: string;
+    }[];
 };
 /**
  * Renders and writes every page.
@@ -316,7 +324,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
  *   it by wikilink, and its own markdown links name content pages. `maps` is
  *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
  *   related: Map<string, import("./related-pages.mjs").Related>,
  *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
@@ -329,6 +337,7 @@ export function renderPages(pages: object[], options: object): {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    embedErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
     maps: number;
 };
@@ -361,7 +370,8 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   wikiErrors: object[], imageErrors: object[], embedErrors: object[],
+ *   mapFindings: object[],
  *   manifests: object|null}} `mapFindings` is what drawing the maps found —
  *   warnings, never a reason to fail the build.
  */
@@ -374,6 +384,7 @@ export function buildSite({ config, sqlTables }?: {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    embedErrors: object[];
     mapFindings: object[];
     manifests: object | null;
 };

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

@@ -24,6 +24,60 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
     records?: object[] | undefined;
     foreignReferences?: Map<string, object> | undefined;
 }): SiteIndex;
+/**
+ * The address keys one page's figures are reachable by — the same two forms
+ * {@link buildSiteIndex} assigns the page itself, so a `ref` crossing into it
+ * resolves by exactly the address a wikilink would use.
+ *
+ * @param {string} pkg - The page's own content package.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {Set<string>} The short `type/shortcode` key and the canonical
+ *   `package-system-type-shortcode` one.
+ */
+export function figureIndexKeys(pkg: string, type: string, shortcode: string): Set<string>;
+/**
+ * Resolve a `ref` call's cross-note address to the target's own figures and
+ * its own address — the `figures.note` a `ref` helper's render context reads,
+ * built once and threaded into every page.
+ *
+ * Reads the written address exactly as a wikilink does
+ * ({@link readQualifier}, {@link expandAddress}), so a `ref` crossing into
+ * another note and a `[[…]]` link to the same note agree on what resolves and
+ * what does not: a target naming no known type or no fetched package's index
+ * is unresolved for both, and one address names one note for both.
+ *
+ * @param {string} target - The address as written, anchor already removed —
+ *   {@link module:engine/wikilink-syntax.ParsedWikilink.target}.
+ * @param {object} options
+ * @param {Set<string>} options.contentTypes - Every type this build reads as
+ *   an address qualifier.
+ * @param {Set<string>} options.packages - Every package an address may name.
+ * @param {Set<string>} options.noIndexPackages - Packages declared
+ *   `contentIndex: false`.
+ * @param {string} options.contentPackage - The package a target with no
+ *   package segment defaults to.
+ * @param {Map<string, {url: string}>} options.siteIndexMap - {@link SiteIndex}'s
+ *   own `index`, read for the target's existence and its URL.
+ * @param {Map<string, Map<string, object>>} options.figuresByAddress - Every
+ *   note's figures, by id, keyed as {@link figureIndexKeys} keys the note.
+ * @returns {{url: string, figures: Map<string, object>}|undefined} The
+ *   target's own address and figures, or `undefined` when the address names
+ *   no note this build resolves.
+ */
+export function resolveCrossNoteFigures(target: string, { contentTypes, packages, noIndexPackages, contentPackage, siteIndexMap, figuresByAddress }: {
+    contentTypes: Set<string>;
+    packages: Set<string>;
+    noIndexPackages: Set<string>;
+    contentPackage: string;
+    siteIndexMap: Map<string, {
+        url: string;
+    }>;
+    figuresByAddress: Map<string, Map<string, object>>;
+}): {
+    url: string;
+    figures: Map<string, object>;
+} | undefined;
 /**
  * The per-page context a wikilink resolver takes.
  *

package/types/engine/system-block.d.mts

@@ -95,8 +95,32 @@ export function sharedProperty(fm: object, source: string, defaultValue?: any):
  */
 export function blockProperty(fm: object, block: string, key: string, defaultValue?: any): any;
 /**
- * A system override followed by a shared `data:` value. The top-level value
- * remains readable while content repositories move their authored fields.
+ * A system override followed by a shared `data:` value followed by the
+ * retiring top-level spelling `data:` gathered it off, reporting which one
+ * answered.
+ *
+ * {@link module:engine/field-spec.resolveFieldValue}'s counterpart for a
+ * universal `data:` key — `pack` and `packFolder`, declared for every note
+ * type rather than per type, so neither is a `FieldSpec` that resolver takes.
+ * The order is the same shape: a system's own override, then the shared
+ * `data:` position, then the bare top-level key a tree authored before
+ * `data:` existed. The top-level value stays readable while a tree still on
+ * it moves its authored fields.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} block - The system block key.
+ * @param {string} key - The shared property.
+ * @param {any} [defaultValue] - Returned when no position declares it.
+ * @returns {{value: any, from: FieldSource}} The value, and where it came
+ *   from.
+ */
+export function resolveDataProperty(fm: object, block: string, key: string, defaultValue?: any): {
+    value: any;
+    from: FieldSource;
+};
+/**
+ * {@link resolveDataProperty}'s value alone, for a caller that only compiles
+ * a document and has no use for which position answered.
  *
  * @param {object} fm - The note's frontmatter.
  * @param {string} block - The system block key.

package/types/hm3/actors.d.mts

@@ -1,3 +1,21 @@
+/**
+ * Native HM3 facts shared by its actor subtypes.
+ *
+ * Species is native text. The note's lore Address in `data.species` is
+ * independent and supplies no native value.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+export const ACTOR_FIELDS: readonly import("../engine/field-spec.mjs").FieldSpec[];
+/**
+ * The two `data:` facts HM3 declares on a `character` and not on a `creature`.
+ *
+ * Both name their shared source and their legacy in-block key, for the reason
+ * {@link ACTOR_FIELDS} does.
+ *
+ * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
+ */
+export const CHARACTER_FIELDS: readonly import("../engine/field-spec.mjs").FieldSpec[];
 /**
  * HM3's Actor compile pass.
  *