@heroiclands/package-build 22.22.0 → 22.23.0

package/types/engine/asset-replacement.d.mts

@@ -0,0 +1,22 @@
+/**
+ * The replacement record for one asset address, or `null`.
+ *
+ * @param {string} address - A canonical asset address.
+ * @param {object} opts
+ * @param {string} opts.localPackage - The compiling package's own segment.
+ * @param {readonly string[]} opts.replacements - The package segments of
+ *   every relationship declaring `assetReplacement: true`, in declaration
+ *   order.
+ * @param {Map<string, object>} opts.index - The merged content index, keyed
+ *   by canonical address.
+ * @returns {{record: object, package: string}|null} The first replacement
+ *   carrying the address, or `null` when none does.
+ */
+export function resolveAssetReplacement(address: string, { localPackage, replacements, index }: {
+    localPackage: string;
+    replacements: readonly string[];
+    index: Map<string, object>;
+}): {
+    record: object;
+    package: string;
+} | null;

package/types/engine/asset-types.d.mts

@@ -27,6 +27,24 @@ export function assetTypeOfRoot(root: unknown): AssetType | undefined;
  * @returns {boolean} Whether it matches {@link ADDRESS_SEGMENT_PATTERN}.
  */
 export function isAssetShortcode(shortcode: string): boolean;
+/**
+ * The pixel dimensions a raster image's own header states.
+ *
+ * Read from the file's bytes directly rather than through a decoder, so a
+ * corrupt or partial file fails closed — the same `undefined` answer as a
+ * format this carries no reader for — instead of throwing out of the asset
+ * walk. An SVG has no pixel dimensions to read; stating one would be a
+ * fabricated viewBox reading rather than a fact about the file.
+ *
+ * @param {string} absPath - The file's absolute path.
+ * @param {string} ext - Its extension, lowercase and dot-led.
+ * @returns {{width: number, height: number}|undefined} The declared size, or
+ *   `undefined` when the format carries none, or the header cannot be read.
+ */
+export function imageDimensions(absPath: string, ext: string): {
+    width: number;
+    height: number;
+} | undefined;
 /**
  * The `<system>` segment every asset address carries.
  *

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

@@ -1,20 +1,3 @@
-/**
- * The tallies one pass accumulates while walking the tree.
- *
- * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it declares a retired frontmatter field
- * — and it is an error; a skipped one legitimately belongs to another pass, and
- * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence.
- *
- * @typedef {object} PassStats
- * @property {number} compiled - Notes that became a document.
- * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
- * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes this pack **refused** — one declaring a
- *   retired frontmatter field, or one routed to a system pack whose system it
- *   says nothing about. Counted as errors, never as skips.
- */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
  *

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

@@ -45,6 +45,22 @@ export function resolveEmbed(index: object, embed: ParsedEmbed): {
     target: string;
     type?: string;
 };
+/**
+ * The role an address's asset declares, read through the same resolution an
+ * embed's address takes.
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` — for
+ * an address still in its authored form, before {@link resolveEmbeds} has
+ * rewritten it into the ordinary image every surface renders.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {string} address - The address as authored, inside `![[...]]`.
+ * @returns {string|undefined} The role, or `undefined` for a note's address,
+ *   one that resolves nowhere, or a picture that declares none.
+ */
+export function embedRole(index: object, address: string): string | undefined;
 /**
  * What is wrong with one embed's directive or placement, if anything.
  *

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

@@ -0,0 +1,101 @@
+/** Number a sequence of figures with counters shared across documents. */
+export function numberFigures(figures: any, counts: any): any;
+/**
+ * Read every `:::figure` fence in a body.
+ *
+ * SQL fences are expanded before this pass, so their output is a table.
+ *
+ * @param {string} source - A note body with expanded tables.
+ * @param {object} [options] - Options.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a picture whose
+ *   asset declares `role: map` counts as `map` rather than `figure`. Omitted,
+ *   every picture counts as `figure` — the same reading a role other than
+ *   `map` gets.
+ * @returns {{figures: Array<{id: string, slug: string, caption: string,
+ *   hasCaption: boolean, classes: string[], kind: string, number: number,
+ *   label: string, line: number, bodyStart: number, bodyEnd: number,
+ *   captionStart: number, captionEnd: number, close: number}>,
+ *   errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanFigures(source: string, { resolveRole }?: {
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+}): {
+    figures: Array<{
+        id: string;
+        slug: string;
+        caption: string;
+        hasCaption: boolean;
+        classes: string[];
+        kind: string;
+        number: number;
+        label: string;
+        line: number;
+        bodyStart: number;
+        bodyEnd: number;
+        captionStart: number;
+        captionEnd: number;
+        close: number;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Render figure fences as HTML, leaving other Markdown untouched.
+ *
+ * A code, table or prose figure's contents are left as Markdown inside the
+ * wrapper, blank-line separated from its tags exactly as
+ * {@link module:engine/content-blocks.renderBlocks} leaves a named block's
+ * body — so the surrounding render sees it as part of its own document and a
+ * footnote reference inside it resolves against the note's own definitions.
+ *
+ * A figure's contents are rendered here rather than left for a later pass,
+ * because a picture-only fence has to become the surface's own `<figure>`
+ * markup directly inside the wrapper this function writes; the surrounding
+ * render never sees it as Markdown, so a footnote reference inside one is not
+ * resolved, the same gap a block's own title carries.
+ *
+ * @param {string} source - A note body with expanded tables.
+ * @param {(markdown: string) => string} [renderMarkdown] - How to render a
+ *   figure's own contents.
+ * @param {Array<{id: string, label: string}>} [numbers] - Labels assigned by a
+ *   surface that counts across documents, matched by id.
+ * @param {object} [options] - Options.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - See
+ *   {@link scanFigures}.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderFigureBlocks(source: string, renderMarkdown?: (markdown: string) => string, numbers?: Array<{
+    id: string;
+    label: string;
+}>, { resolveRole }?: {
+    resolveRole?: ((address: string) => string | undefined) | undefined;
+}): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/** A figure's automatically determined kind, and the word that labels it. */
+export const FIGURE_NAMES: Readonly<{
+    code: "Code";
+    table: "Table";
+    figure: "Figure";
+    map: "Map";
+    prose: "Prose";
+}>;
+/**
+ * The classes a figure takes.
+ *
+ * `.border` states that the captioned thing is drawn inside a border, and each
+ * medium owns what that means. The vocabulary is closed: a class absent from it
+ * is a finding naming the class.
+ *
+ * @type {readonly string[]}
+ */
+export const FIGURE_CLASSES: readonly string[];

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

@@ -81,3 +81,10 @@ export function footnoteFindings(source: string): Array<{
     column: number;
     message: string;
 }>;
+/**
+ * A footnote reference's shape, wherever it is written — excluding a
+ * definition's own `[^id]:` opener, which this never matches.
+ *
+ * @type {RegExp}
+ */
+export const FOOTNOTE_REFERENCE: RegExp;

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

@@ -30,16 +30,28 @@ export function parseImageDirective(raw?: string): {
     problems: string[];
 };
 /**
- * The classes a figure carries, from a parsed directive.
+ * The class a picture's role names, or `""` for no role or one outside the
+ * closed set — the same silent-degrade rule every other unrecognised value
+ * here gets, since a role this far downstream has already been validated or
+ * dropped by the asset record that carries it.
  *
- * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
+ * @param {string} [role] - The role, from the resolved asset record.
+ * @returns {string} The class, or `""`.
+ */
+export function roleClass(role?: string): string;
+/**
+ * The classes a figure carries, from a parsed directive and its asset's role.
+ *
+ * @param {{classes?: string[], size?: string, float?: string, role?: string}} [directive] -
+ *   As parsed, plus the role the resolved asset record carries, if any.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes, size, float }?: {
+export function figureClasses({ classes, size, float, role }?: {
     classes?: string[];
     size?: string;
     float?: string;
+    role?: string;
 }): string;
 /**
  * Text going inside an HTML attribute or between tags.
@@ -55,28 +67,57 @@ export function escapeHtml(text: string): string;
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
+ * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * label and authored caption around whatever this returns; the alt text stays
+ * on the `img` element alone.
+ *
+ * **The role class and the `width`/`height` attributes are what a stylesheet
+ * elsewhere keys a role's size on.** This module states none — the measure a
+ * `portrait` fills on a page is a Hugo theme's or a Foundry system's own
+ * decision — and emits only what the resolved asset record states: a role
+ * class when the picture declares one, and the attributes whenever the
+ * picture resolved to an asset record at all, blank for a vector. The
+ * attributes reserve the picture's own layout space before it loads, which is
+ * what lets a page avoid reflowing as pictures load in.
+ *
  * @param {object} image - The image.
  * @param {string} image.src - The address, resolved for the surface.
- * @param {string} [image.alt] - The alt text, which is also the caption.
+ * @param {string} [image.alt] - The alt text, for a reader who cannot see the
+ *   picture.
  * @param {string[]} [image.classes] - Width classes, from the directive.
  * @param {string} [image.size] - Named display size, from the directive.
  * @param {string} [image.float] - The float position, from the directive.
+ * @param {string} [image.role] - The picture's declared role, from the
+ *   resolved asset record.
+ * @param {number|""} [image.width] - The file's own pixel width, from the
+ *   resolved asset record; `""` for a vector. Omitted entirely when the
+ *   address resolved to no asset record at all.
+ * @param {number|""} [image.height] - As `width`.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt, classes, size, float }: {
+export function imageFigureHtml({ src, alt, classes, size, float, role, width, height, }: {
     src: string;
     alt?: string | undefined;
     classes?: string[] | undefined;
     size?: string | undefined;
     float?: string | undefined;
+    role?: string | undefined;
+    width?: number | "" | undefined;
+    height?: number | "" | undefined;
 }): string;
 /**
  * Whether a match sits alone in its own paragraph.
  *
- * "Alone" is the whole of a block: nothing else on its line, and a blank line
- * or the end of the body either side of it. A leading `>` or list marker
- * disqualifies it for the same reason a word does — the paragraph it belongs to
- * holds something the figure would have to be lifted out of.
+ * "Alone" is the whole of a block: nothing else on its line, and a blank line,
+ * a body-extension delimiter or the end of the body either side of it. A
+ * leading `>` or list marker disqualifies it for the same reason a word does —
+ * the paragraph it belongs to holds something the figure would have to be
+ * lifted out of.
+ *
+ * **A footnote reference trailing the match is not "other text."** `[^note]`
+ * annotates the picture rather than sitting beside it in prose, the same
+ * standing its own directive already has, so `![A ranger](r.webp)[^note]` is
+ * still alone.
  *
  * @param {string} text - The body the match indexes into.
  * @param {number} start - Where the match begins.
@@ -127,6 +168,9 @@ 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 {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
+ *   table expansion, mapping each line of `body` back to the line an author
+ *   wrote, for a caller handing in a body whose tables already expanded.
  * @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,
@@ -136,9 +180,13 @@ export function imageSourcesIn(body: string): string[];
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body: string, file: string, { bodyLine, bodyColumn, config }?: {
+export function checkImages(body: string, file: string, { bodyLine, bodyColumn, lineMap, config }?: {
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;
+    lineMap?: {
+        line: number;
+        generated: boolean;
+    }[] | undefined;
     config?: object | undefined;
 }): Array<{
     file: string;
@@ -201,9 +249,18 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
  * @param {(src: string) => string} [resolveSrc] - Translates an authored
  *   pathname into the address this surface serves. The default is the identity,
  *   for a caller rendering the format rather than publishing it.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` translates it. The default answers nothing,
+ *   which is what an address resolving to no asset record gets anyway.
  * @returns {string} The same body, with each block image as a `<figure>`.
  */
-export function renderImageFigures(body: string, resolveSrc?: (src: string) => string): string;
+export function renderImageFigures(body: string, resolveSrc?: (src: string) => string, lookupAsset?: (src: string) => {
+    type?: string;
+    role?: string;
+    width?: number | "";
+    height?: number | "";
+} | undefined): string;
 /**
  * A markdown-it plugin that reads an image's directive and renders its figure.
  *
@@ -226,9 +283,18 @@ export function renderImageFigures(body: string, resolveSrc?: (src: string) => s
  *   address into the one this surface serves. Foundry is handed the path inside
  *   the install; a renderer that resolves the address itself — the book stages
  *   its own copy — passes nothing and gets the address as authored.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` runs. The default answers nothing, which is
+ *   what an address resolving to no asset record gets anyway.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function imagePlugin(resolveSrc?: (src: string) => string): (md: object) => void;
+export function imagePlugin(resolveSrc?: (src: string) => string, lookupAsset?: (src: string) => {
+    type?: string;
+    role?: string;
+    width?: number | "";
+    height?: number | "";
+} | undefined): (md: object) => void;
 /**
  * The width classes an image may carry, and what each means to a renderer.
  *

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

@@ -103,6 +103,10 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   entries are derived against.
  * @param {object} [options.addressContext] - Address resolution context.
  * @param {object} [options.dateContext] - Calendar conversion context.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
@@ -114,7 +118,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
  */
-export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -124,9 +128,10 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, contentPackage
     manifest?: object | undefined;
     addressContext?: object | undefined;
     dateContext?: object | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
 }): Record<string, any>;
 /** Derive every index record belonging to one parsed note. */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, }: {
+export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext, dateContext, resolveRole, }: {
     frontmatter: any;
     body: any;
     bodyLine: any;
@@ -136,6 +141,7 @@ export function indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absP
     manifest: any;
     addressContext: any;
     dateContext: any;
+    resolveRole: any;
 }): object[];
 /**
  * Read a content tree into index records, in the order they will be written.

package/types/engine/field-reference.d.mts

@@ -1,3 +1,24 @@
+/**
+ * The one line explaining why a single field's shared top-level fallback is
+ * off.
+ *
+ * **The field's reason stands on its own** — a complete sentence, or more
+ * than one — rather than completing a clause the frame starts. A field that
+ * collides with a top-level spelling meaning something else can say so
+ * ("`weight` is the item's own, independent of the note's."); a field whose
+ * top-level spelling is refused outright by the closed vocabulary can say
+ * that instead, honestly, which "there it means …" cannot: a refused key
+ * carries no meaning to report.
+ *
+ * Exported so a guard can walk every field declaring `topLevelMeans` across
+ * every registry and check that each one composes into a grammatical
+ * sentence, without reimplementing the frame it is checking.
+ *
+ * @param {import("./field-spec.mjs").FieldSpec} field - A field declaring
+ *   `topLevelMeans`.
+ * @returns {string} The composed markdown line.
+ */
+export function topLevelExemptionLine(field: import("./field-spec.mjs").FieldSpec): string;
 /**
  * Render the per-type item frontmatter reference.
  *

package/types/engine/field-spec.d.mts

@@ -213,19 +213,21 @@ export function runtimeOnlyFields(fields: readonly FieldSpec[]): FieldSpec[];
  *   retiring one — so a field can move into `data:` while the corpus catches
  *   up, instead of on a flag day across four repositories. A declaration that
  *   names one is mid-sweep by construction; see {@link readsLegacyKey}.
- * @property {string} [topLevelMeans] - **What the note's top-level key of this
- *   name means instead** — declared only where it means something else, and
- *   stating it removes the shared top-level position from this field's
- *   resolution order.
+ * @property {string} [topLevelMeans] - **Why the note's top-level key of this
+ *   name is not this field's source** — declared wherever that key's spelling
+ *   means something else at the note level, or the closed top-level
+ *   vocabulary refuses it outright, and stating either removes the shared
+ *   top-level position from this field's resolution order.
  *
  *   A field's `name` doubles as its identity and as the shared property it
  *   draws from, which is right wherever the two levels state the same quantity
  *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
- *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   spelling collides across the two vocabularies, or names a key the closed
+ *   top-level vocabulary does not admit at all. An `affiliation` item's
  *   `system.title` is the style of address an office carries; a note's
- *   top-level `title` is the note's own heading. Nothing relates them, and
- *   before this key one silently fed the other, stringifying an authored
- *   `title: null` into fifteen documents.
+ *   top-level `title` is refused outright. Nothing relates them, and before
+ *   this key one silently fed the other, stringifying an authored `title:
+ *   null` into fifteen documents.
  *
  *   **The value is the reason**, not a flag with a comment beside it. A boolean
  *   would record the decision and lose the case for it, and the next person
@@ -466,19 +468,21 @@ export type FieldSpec = {
      */
     legacyKey?: string | undefined;
     /**
-     * - **What the note's top-level key of this
-     * name means instead** — declared only where it means something else, and
-     * stating it removes the shared top-level position from this field's
-     * resolution order.
+     * - **Why the note's top-level key of this
+     * name is not this field's source** — declared wherever that key's spelling
+     * means something else at the note level, or the closed top-level
+     * vocabulary refuses it outright, and stating either removes the shared
+     * top-level position from this field's resolution order.
      *
      * A field's `name` doubles as its identity and as the shared property it
      * draws from, which is right wherever the two levels state the same quantity
      * — `data.weight` is the weight, whoever reads it. It is wrong wherever a
-     * spelling collides across the two vocabularies. An `affiliation` item's
+     * spelling collides across the two vocabularies, or names a key the closed
+     * top-level vocabulary does not admit at all. An `affiliation` item's
      * `system.title` is the style of address an office carries; a note's
-     * top-level `title` is the note's own heading. Nothing relates them, and
-     * before this key one silently fed the other, stringifying an authored
-     * `title: null` into fifteen documents.
+     * top-level `title` is refused outright. Nothing relates them, and before
+     * this key one silently fed the other, stringifying an authored `title:
+     * null` into fifteen documents.
      *
      * **The value is the reason**, not a flag with a comment beside it. A boolean
      * would record the decision and lose the case for it, and the next person

package/types/engine/foreign-catalog.d.mts

@@ -11,6 +11,20 @@ export function itemCatalogRelationships(config: object): Array<{
     kind: string;
     verified: string | undefined;
 }>;
+/**
+ * Every declared relationship that opted into supplying its release archive
+ * for asset bytes alone, with no item catalogue built from it.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
+ *   The opted-in relationships, in declaration order.
+ */
+export function assetArchiveRelationships(config: object): Array<{
+    id: string;
+    manifest: string;
+    kind: string;
+    verified: string | undefined;
+}>;
 /**
  * The cache directory for one dependency at one version.
  *
@@ -95,6 +109,26 @@ export function fetchCatalog(config: object, rel: {
     id: string;
     manifest: string;
 }): Promise<string>;
+/**
+ * Fetch one dependency's release archive for its asset bytes alone, building
+ * no item catalogue from it.
+ *
+ * Idempotent: a complete cache for the resolved version is left alone. Where a
+ * relationship also declares `itemCatalog: true`, {@link fetchCatalog} already
+ * unpacked this same archive into this same cache directory, and
+ * {@link fetchAllCatalogs} does not call this function for it — the two never
+ * download the same bytes twice.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @param {{id: string, manifest: string, verified?: string}} rel - The
+ *   declared relationship.
+ * @returns {Promise<string>} The dependency's cache directory.
+ */
+export function fetchAssetArchive(config: object, rel: {
+    id: string;
+    manifest: string;
+    verified?: string;
+}): Promise<string>;
 /**
  * Fill the cache from a locally built artifact rather than a release.
  *
@@ -167,6 +201,11 @@ export function fetchAllMetadata(config: object): Promise<number>;
 /**
  * Fetch every opted-in dependency. The `deps fetch` command.
  *
+ * A relationship declaring both `itemCatalog: true` and `assetArchive: true`
+ * is fetched once: {@link fetchCatalog} already unpacks the archive on its
+ * way to extracting the item catalogue, so this skips the archive-only fetch
+ * for any id {@link fetchCatalog} already handled.
+ *
  * @param {object} config - The resolved build configuration.
  * @returns {Promise<number>} How many dependencies were fetched.
  */

package/types/engine/heading-attributes.d.mts

@@ -31,9 +31,9 @@ export function splitHeadingAttributes(heading: string): {
  * A Foundry UUID addresses a page and nothing smaller, so a section a link can
  * reach has to be one: a top-level heading starts a page, and so does any
  * heading that names an anchor. {@link module:engine/journals.splitPages}
- * decides *where* a page begins — a captioned heading and a heading inside a
- * fence or a named block are its business — and asks this which headings are
- * eligible, so no caller re-decides it.
+ * decides *where* a page begins — a heading inside a fence or a named block is
+ * its business — and asks this which headings are eligible, so no caller
+ * re-decides it.
  *
  * @param {{level: number, id: string}} heading - From
  *   {@link scanHeadingAttributes}, or any `{level, id}` pair.
@@ -86,7 +86,7 @@ export function headingAttributesPlugin(md: object): void;
  * Parse one line as a heading, and say whether it starts a journal page.
  *
  * The single reading of that rule. {@link module:engine/journals.splitPages}
- * builds its pages from it; `scanBlocks` and `scanCaptions` refuse a heading
+ * builds its pages from it; `scanBlocks` and `scanFigures` refuse a heading
  * that starts a page written where it cannot become one. All three ask this, so
  * none of them can disagree about what a heading line means or about what starts
  * a page — and the attribute block comes off here, so a class beside an anchor
@@ -115,15 +115,20 @@ export function parseHeadingLine(line: string): {
  * builds the pages from this, and the passes that honour a class on a
  * page-opening heading ask the same question of the same answer.
  *
- * A caption also opens a page, which is `splitPages`' business: a caption is
- * found by the caption pass, and a heading it captions is listed here and
- * dropped there.
+ * A figure fence also opens a page, which is `splitPages`' business: a fence is
+ * found by the figure pass, and the page it opens is named for its label.
  *
  * @param {string} source - A note's markdown body.
+ * @param {ReadonlySet<number>} [blockLines] - The 0-based lines sitting inside
+ *   a named block, supplied by the caller. A named block is read by
+ *   {@link module:engine/content-blocks.scanBlocks}, which knows every name in
+ *   the registry, reads an opener's attribute block, and tracks nesting by
+ *   depth — so the caller that already holds that answer passes it rather than
+ *   a second reading of the same lines being kept here.
  * @returns {Map<number, {level: number, line: number, text: string, id: string,
  *   classes: string[], values: Record<string, string>}>} Keyed by 0-based line.
  */
-export function pageOpenings(source: string): Map<number, {
+export function pageOpenings(source: string, blockLines?: ReadonlySet<number>): Map<number, {
     level: number;
     line: number;
     text: string;

package/types/engine/helpers.d.mts

@@ -1,5 +1,21 @@
-/** Render a note body with Foundry's named-block markup. */
-export function renderFoundryMarkdown(body: any, captions: any, footnoteNumbers: any, docId: any): string;
+/**
+ * Render a note body with Foundry's named-block markup.
+ *
+ * @param {string} body - The body, tables expanded and wikilinks resolved.
+ * @param {Array<{id: string, label: string}>} [figures] - Labels assigned by
+ *   a note-wide scan, matched by id — see
+ *   {@link module:engine/content-figures.renderFigureBlocks}.
+ * @param {Map<string, number>} [footnoteNumbers] - Shared across the note.
+ * @param {string} [docId] - Threaded into footnote anchors.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares — see
+ *   {@link module:engine/content-figures.scanFigures}.
+ * @returns {string} The rendered HTML.
+ */
+export function renderFoundryMarkdown(body: string, figures?: Array<{
+    id: string;
+    label: string;
+}>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined): string;
 /**
  * Parses a markdown file with YAML frontmatter.
  *
@@ -206,11 +222,11 @@ export function makeFilename(name: string, id: string): string;
  * the other.
  *
  * **`title` does not follow this rule**, and must not be made to. On a
- * `type: affiliation` note `title` is *also* a declared item field whose default
- * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
- * key the site emitter reads as the page title — so `title: null` stringifies
- * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means.
+ * `type: affiliation` note `title` is a declared item field with its own
+ * default (`""`, in `sohl/item-fields.mjs`), authored only inside the item's
+ * own `sohl` block — the closed top-level vocabulary has no `title` entry, so
+ * there is no shared key for this function's null-versus-blank distinction to
+ * apply to.
  *
  * **`banner:` does not follow it either, deliberately.** It is not a file
  * inside a Foundry install: it reaches no compiled document and no book, its