@heroiclands/package-build 22.22.0 → 22.24.0

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,16 +222,18 @@ 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
- * only consumer is the Hugo theme, and the theme resolves it against the site's
- * own asset root. See `docs/content-format.md`.
+ * inside a Foundry install: it reaches no compiled document, and the site build
+ * resolves it through the website's own resolver before a page is written, so
+ * the theme receives a URL rather than an address. The book's section plates
+ * read a banner of their own, from the book plan's `presentation.page.banner`
+ * rather than from a note. See `docs/guides/site.md`.
  *
  * For items, the default is the art paired with the type's builder, reached
  * through `itemArt()`, which runs the pathname back through this function so a

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;
 }): {