@heroiclands/package-build 22.22.0 → 22.24.0

package/packagebuild-metadata.jsonl

@@ -1,13 +1,13 @@
-{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","source":""},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","source":""},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","source":""},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","source":""},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","source":""},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","source":""},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","source":""},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","source":""},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","source":""},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","source":""},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","source":""},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","source":""},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
-{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"ai":"","attribution":"Tom Rodriguez","license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","source":""},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-afflictionbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-armorclothingbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-attributebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-containerbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-devdocsbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-miscgearbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-mysticalabilitybnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-projectilebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-rulesbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-skillbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-traumabnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-userguidebnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
+{"address":{"canonical":"packagebuild-none-image-weapongearbnr"},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}

package/sohl/item-fields.mjs

@@ -391,9 +391,10 @@ export const ITEM_FIELDS = Object.freeze({
             ...STRING,
             default: "",
             topLevelMeans:
-                "An office's style of address belongs to the membership that " +
-                "holds the office, so nothing outside the item supplies it. " +
-                "Author it at `sohl.system.title` on the item, or at the " +
+                "A top-level `title` is refused outright, since an office's " +
+                "style of address belongs to the membership that holds the " +
+                "office and nothing outside the item supplies it. Author it " +
+                "at `sohl.system.title` on the item, or at the " +
                 "`system.title` of the entry in a being's `sohl.items`.",
             describe: "The style of address the office carries.",
         },

package/types/content-config.d.mts

@@ -126,6 +126,16 @@ export const RETIRED_ADDRESS_KEYS: Readonly<Record<string, string>>;
 export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
 }>;
+/**
+ * Every key a declared relationship may carry.
+ *
+ * Read by the manifest writer as well as by the configuration check: the keys
+ * Foundry's own relationship schema does not name are the build's own, and the
+ * published manifest carries none of them.
+ *
+ * @type {readonly string[]}
+ */
+export const RELATIONSHIP_KEYS: readonly string[];
 /**
  * How the loader hands {@link defineConfig} the system version it resolved.
  *
@@ -274,7 +284,8 @@ export type PathsInput = {
     unpack?: string | undefined;
     /**
      * Where a dependency declaring
-     *      `itemCatalog: true` is unpacked.
+     *      `itemCatalog: true` or
+     *      `assetArchive: true` is unpacked.
      *      Inbound, and fetched rather than
      *      committed.
      */
@@ -438,6 +449,21 @@ export type RelationshipSpec = {
      * `_stats.systemVersion` is stamped from.
      */
     compatibility?: CompatibilitySpec | undefined;
+    /**
+     * Whether `deps fetch` unpacks this
+     *  dependency's release archive and extracts
+     *  its Item packs, so the actors pass can
+     *  resolve embedded items this repository
+     *  does not hold. Needs a `manifest`.
+     */
+    itemCatalog?: boolean | undefined;
+    /**
+     * Whether `deps fetch` unpacks this
+     * dependency's release archive for its
+     * asset bytes alone, building no item
+     * catalogue from it. Needs a `manifest`.
+     */
+    assetArchive?: boolean | undefined;
     /**
      * Whether `deps fetch` fetches this
      * dependency's content index. Default
@@ -449,6 +475,16 @@ export type RelationshipSpec = {
      * index.
      */
     contentIndex?: boolean | undefined;
+    /**
+     * Whether this dependency's asset
+     * tree answers this package's own asset
+     * addresses ahead of its local record.
+     * Default `false`. Refuses `contentIndex:
+     * false` on the same entry, since a
+     * replacement with no fetched index to
+     * check against resolves nothing.
+     */
+    assetReplacement?: boolean | undefined;
 };
 /**
  * How a generated documentation page is framed in the repository publishing it.
@@ -628,6 +664,12 @@ export type ContentBuildConfigInput = {
      *    `Templates`). Default `[]`.
      */
     skipDirectories?: string[] | undefined;
+    /**
+     * Whether `lint` refuses an asset
+     *  record of this package carrying
+     *  `ai: true`. Default `false`.
+     */
+    forbidGeneratedArt?: boolean | undefined;
     /**
      * Reserved for
      * `@heroiclands/package-build`, which
@@ -764,6 +806,11 @@ export type ContentBuildConfig = {
      */
     docEntryTypes: ReadonlySet<string>;
     skipDirectories: readonly string[];
+    /**
+     * Whether `lint` refuses an asset
+     * record of this package carrying `ai: true`.
+     */
+    forbidGeneratedArt: boolean;
     /**
      * The
      * fonts this package ships and the names it

package/types/engine/anchors.d.mts

@@ -1,17 +1,22 @@
 /**
- * The `{#slug}` and `:::caption {#slug}` anchors a note declares.
+ * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
  *
- * A bare `#` heading starts a journal page without declaring a slug. Captioned
- * blocks declare a slug and start an addressable journal page.
+ * A bare `#` heading starts a journal page without declaring a slug, and so
+ * does a figure fence that declares no id. A fence that declares one declares a
+ * slug and starts an addressable journal page.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
  *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
  *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @param {(address: string) => string|undefined} [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 {Array<{slug: string, name: string, level: number, line: number}>}
  *   In document order.
  */
-export function collectAnchors(body: string, bodyLine?: number): Array<{
+export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (address: string) => string | undefined): Array<{
     slug: string;
     name: string;
     level: number;

package/types/engine/art-fields.d.mts

@@ -61,6 +61,29 @@ export function assetAddressIndex(records?: readonly object[], { config, foreign
     } | undefined;
     types?: Iterable<string> | undefined;
 }): object;
+/**
+ * What a renderer needs to size one picture, keyed by the pathname its
+ * address resolves to.
+ *
+ * An image reaches a renderer as the resolved pathname an embed or an authored
+ * body image already carries — see {@link readAssetAddress} — never as the
+ * address that produced it, so the lookup a renderer wants is by pathname, not
+ * by {@link assetAddressIndex}'s own `assets` map.
+ *
+ * @param {readonly object[]} records - Asset records, local or foreign.
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   One entry per addressable file, carrying only what a renderer sizes a
+ *   picture from. `role` is omitted when the record states none; `width` and
+ *   `height` are always present, blank (`""`) for a vector — the record's own
+ *   convention, carried through rather than collapsed into an absence a
+ *   renderer could not tell apart from "no asset resolved at all".
+ */
+export function assetImageInfoByPathname(records?: readonly object[]): Map<string, {
+    type: string;
+    role?: string;
+    width: number | "";
+    height: number | "";
+}>;
 /**
  * The asset one authored value names, or why it names none.
  *
@@ -116,6 +139,47 @@ export function resolveArtRecord(index: object, value: unknown, defaultType: str
         path: string;
     };
 } | null;
+/**
+ * Every asset's role, keyed by the pathname it resolves to — the form a body
+ * carries once an embed's address has been rewritten into the ordinary image
+ * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
+ * for a caller that reads a body after that rewrite: a Foundry journal, an
+ * item or actor's documentation, and the book.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @returns {Map<string, string>} Pathname → role, one entry per asset that
+ *   declares one.
+ */
+export function pathnameRoles(index: object): Map<string, string>;
+/**
+ * Flag a note whose art slot names a picture that is not the size that slot
+ * is cut to.
+ *
+ * The size is stated by the slot itself, in
+ * {@link module:engine/art-slots.ART_SLOTS}, so it is written once and a slot
+ * that states none asks nothing of the picture it names. Today the hero image
+ * is the one slot with a fixed strip to fill; a picture written in prose is
+ * fitted to the room it has and is never measured here.
+ *
+ * A vector carries no pixel size to compare, and neither does a raster whose
+ * header cannot be read; neither is flagged.
+ *
+ * @param {readonly object[]} records - The corpus, notes and assets together.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {string} [opts.assetsBase] - Where the asset roots sit, so a finding
+ *   names the file from the working directory as every other finding does.
+ * @returns {object[]} A finding per picture off its slot's size,
+ *   `severity: "error"`.
+ */
+export function checkArtSlotSizes(records?: readonly object[], { config, assetsBase }?: {
+    config?: object | undefined;
+    assetsBase?: string | undefined;
+}): object[];
 /**
  * The pathname an art value names, in the form an authored one takes.
  *

package/types/engine/art-slots.d.mts

@@ -2,7 +2,8 @@
  * The four art slots, in the order the specification tabulates them.
  *
  * `banner` is the one that reaches no compiled document: it is the page's hero
- * image, read by the site and by the book's section plates and by nothing else.
+ * image, read by the site and by nothing else. The book's section plates read a
+ * banner of their own, from the book plan's `presentation.page.banner`.
  * That is what `document: false` states, and it is why the inert-art check
  * skips it — a key that is *meant* to reach no document is not an inert key.
  *

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

@@ -19,6 +19,16 @@ export function collectAssetRecords(assetsBase: string, { contentPackage, proble
     contentPackage: string;
     problems?: object[] | undefined;
 }): Array<Record<string, any>>;
+/**
+ * The closed set of roles a picture may declare.
+ *
+ * Shared with the field declaration below and with every medium that sizes a
+ * picture by its role, so the vocabulary cannot drift between the record that
+ * carries it and the renderer that reads it.
+ *
+ * @type {readonly string[]}
+ */
+export const ASSET_ROLES: readonly string[];
 /**
  * The file a directory records provenance for its subtree in.
  *
@@ -47,6 +57,18 @@ export const PROVENANCE_SIDECAR_SUFFIX: string;
  *   state this key. Omitting one is a finding rather than a blank, because a
  *   record resolves wholesale: the nearest one is the whole answer, so a key it
  *   leaves out is not inherited from above but simply absent.
+ * @property {"boolean"|"integer"} [type] - The value's own type, for a field
+ *   whose answer is not a string. Omitted for every string field; `ai` carries
+ *   the YAML boolean itself rather than a stringified copy, and `width` and
+ *   `height` carry the pixel count the walk measured. Each is refused rather
+ *   than coerced when the value does not match.
+ * @property {readonly string[]} [values] - The closed set a provenance
+ *   declaration must choose one of; a value outside it is a finding and the
+ *   key is left blank, the same treatment an `ai` value of the wrong shape
+ *   gets. `role` is the one field that carries it.
+ * @property {string} [onlyType] - The one asset type this field may be
+ *   declared for. A provenance record stating it for another type is a
+ *   finding, and the value is dropped rather than carried through.
  * @property {string} describe - One line, for the author-facing reference.
  */
 /**
@@ -105,6 +127,27 @@ export type AssetRecordField = {
      * leaves out is not inherited from above but simply absent.
      */
     required?: boolean | undefined;
+    /**
+     * - The value's own type, for a field
+     * whose answer is not a string. Omitted for every string field; `ai` carries
+     * the YAML boolean itself rather than a stringified copy, and `width` and
+     * `height` carry the pixel count the walk measured. Each is refused rather
+     * than coerced when the value does not match.
+     */
+    type?: "boolean" | "integer" | undefined;
+    /**
+     * - The closed set a provenance
+     * declaration must choose one of; a value outside it is a finding and the
+     * key is left blank, the same treatment an `ai` value of the wrong shape
+     * gets. `role` is the one field that carries it.
+     */
+    values?: readonly string[] | undefined;
+    /**
+     * - The one asset type this field may be
+     * declared for. A provenance record stating it for another type is a
+     * finding, and the value is dropped rather than carried through.
+     */
+    onlyType?: string | undefined;
     /**
      * - One line, for the author-facing reference.
      */

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;