@heroiclands/package-build 22.22.0 → 22.24.0

package/docs/api.md

@@ -132,29 +132,30 @@ can write the result directly without introducing formatting drift.
 
 The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the block, the shared top level, and a retiring position in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
 
-| Export                      | Signature                                         | Returns                                | Use it when                                                                                   |
-| --------------------------- | ------------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                           | —                                      | naming the key inside a system block whose contents are the system's own vocabulary           |
-| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                 | —                                      | mapping a system-block key to the document property it becomes                                |
-| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                          | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                   |
-| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                         | —                                      | enumerating every key any system block may carry                                              |
-| `setPath`                   | `setPath(target, dotted, value)`                  | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                               |
-| `systemBlock`               | `systemBlock(fm, block)`                          | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed        |
-| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                   | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                   |
-| `systemData`                | `systemData(fm, block)`                           | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                 |
-| `blockField`                | `blockField(fm, block, key, defaultValue)`        | the value                              | reading a key from one system's block, falling back to the top level                          |
-| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`        | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block    |
-| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`     | the value                              | reading a property a system block may override, else the shared top-level one                 |
-| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)` | the value                              | reading a system override, then shared `data`, then a top-level value                         |
-| `legacyKeyOf`               | `legacyKeyOf(field)`                              | `string \| undefined`                  | finding the key a field is authored at inside a system block                                  |
-| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                       | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                     |
-| `authoredKey`               | `authoredKey(name)`                               | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it |
-| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`               | `{value, from}`                        | resolving one declared field against a note, in the declared source order                     |
-| `systemDataPaths`           | `systemDataPaths(data, prefix)`                   | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                |
-| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`         | `string[]`                             | finding authored paths a system's published schema does not declare                           |
-| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes |
-| `claimedPaths`              | `claimedPaths(fields)`                            | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`            |
-| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                 | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                       |
+| Export                      | Signature                                           | Returns                                | Use it when                                                                                                                                          |
+| --------------------------- | --------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                             | —                                      | naming the key inside a system block whose contents are the system's own vocabulary                                                                  |
+| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                   | —                                      | mapping a system-block key to the document property it becomes                                                                                       |
+| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                            | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                                                                          |
+| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                           | —                                      | enumerating every key any system block may carry                                                                                                     |
+| `setPath`                   | `setPath(target, dotted, value)`                    | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                                                                                      |
+| `systemBlock`               | `systemBlock(fm, block)`                            | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed                                                               |
+| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                     | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                                                                          |
+| `systemData`                | `systemData(fm, block)`                             | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                                                                        |
+| `blockField`                | `blockField(fm, block, key, defaultValue)`          | the value                              | reading a key from one system's block, falling back to the top level                                                                                 |
+| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`          | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block                                                           |
+| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`       | the value                              | reading a property a system block may override, else the shared top-level one                                                                        |
+| `resolveDataProperty`       | `resolveDataProperty(fm, block, key, defaultValue)` | `{value, from}`                        | resolving a shared `data:` key every type accepts — a system override, then shared `data`, then a top-level value — and reporting which one answered |
+| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)`   | the value                              | `resolveDataProperty`'s value alone, in the same order                                                                                               |
+| `legacyKeyOf`               | `legacyKeyOf(field)`                                | `string \| undefined`                  | finding the key a field is authored at inside a system block                                                                                         |
+| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                         | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                                                                            |
+| `authoredKey`               | `authoredKey(name)`                                 | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it                                                        |
+| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`                 | `{value, from}`                        | resolving one declared field against a note, in the declared source order                                                                            |
+| `systemDataPaths`           | `systemDataPaths(data, prefix)`                     | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                                                                       |
+| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`           | `string[]`                             | finding authored paths a system's published schema does not declare                                                                                  |
+| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                  | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes                                                        |
+| `claimedPaths`              | `claimedPaths(fields)`                              | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`                                                                   |
+| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                   | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                                                                              |
 
 ### `engine.codeFences`
 
@@ -651,7 +652,7 @@ The neutral day spelling is `<year>.<day>[:HHMMSS]`. The pure conversion functio
 
 ### `engine.noteDates`
 
-A date on a note is one authored scalar. `<year>[.<day>[:HHMMSS]]` names a calendar-neutral year, day, or second; `datefrom vrcal 23 Taranis 326 VR` names a calendar, a named month, and an era. Year and day values span their written interval; a clock time identifies a second. Either form may begin with `~` for uncertainty beyond that interval. The `approximate` field records that explicit marker, while `precision` and `seconds` describe the interval or time. A resolved date carries a canonical year, span, and sort key; a neutral year has no `canonicalDay`, while day-precision dates have one. Print `prose ?? text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. `resolvedDateFields` supplies identical derived records to JSONL and generated page frontmatter.
+A date on a note is one authored scalar. `<year>[.<day>[:HHMMSS]]` names a calendar-neutral year, day, or second; `datefrom vrcal 23 Taranis 326 VR` names a calendar, a named month, and an era. Year and day values span their written interval; a clock time identifies a second. Either form may begin with `~` for uncertainty beyond that interval. The `approximate` field records that explicit marker, while `precision` and `seconds` describe the interval or time. A resolved date carries a canonical year, span, and sort key; a neutral year has no `canonicalDay`, while day-precision dates have one. Print `prose ?? text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. Year `0` is accepted only where a caller passes `allowZeroYear` — a `lore` event's `when` — and means "this day, every year": the value carries no `canonicalYear` and no `sort`. `resolvedDateFields` supplies identical derived records to JSONL and generated page frontmatter, including a `lore` note's `data.events`, each entry's `recurs` and computed `next`.
 
 | Export                  | Signature                                                     | Returns                                            | Use it when                                                    |
 | ----------------------- | ------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
@@ -664,6 +665,7 @@ A date on a note is one authored scalar. `<year>[.<day>[:HHMMSS]]` names a calen
 | `formatNoteDate`        | `formatNoteDate(date, era, daysPerYear, formatName?)`         | `{era, year, month, day, text, prose}` or `null`   | printing a resolved date in a chosen era or its authored form  |
 | `formatDateInCalendar`  | `formatDateInCalendar(date, reference, context, formatName?)` | printable record or `null`                         | selecting a calendar's era and printing a resolved date in it  |
 | `calendarEras`          | `calendarEras(reference, context)`                            | ordered era records                                | resolving an addressed calendar or one of its eras             |
+| `occurrencesOf`         | `occurrencesOf(date, recurs, options)`                        | occurrence records, in increasing order            | finding a recurring event's next, last, or a membership probe  |
 | `resolvedDateFields`    | `resolvedDateFields(fm, context)`                             | map of normalized dates                            | deriving being and lore event date records for index and pages |
 
 ### `engine.dateConversion`
@@ -695,7 +697,7 @@ invokes the check during frontmatter lint.
 
 ### `engine.markdownExpressions`
 
-`renderMarkdownExpressions(body, { fm, dates, sqlResults, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. The `ref` helper links to a `:::figure` fence by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
 
 | Export                      | Signature                                  | Returns                | Use it when                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -883,16 +885,17 @@ Emitting this package's content index. Every content build already walks the who
 
 The asset types — `icon`, `image` and `audio` — and the three roots they are walked from. An asset is addressed exactly as a note is; what differs is that a `.webp` carries no frontmatter and has nowhere to say what it is, so the root supplies the type and the list of roots is closed.
 
-| Export             | Signature                     | Returns                                                      | Use it when                                                                                               |
-| ------------------ | ----------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `ASSET_TYPES`      | `const ASSET_TYPES`           | `readonly AssetType[]` — type, root, extensions, description | walking the roots, or presenting the vocabulary                                                           |
-| `ASSET_TYPE_NAMES` | `const ASSET_TYPE_NAMES`      | `ReadonlySet<string>`                                        | admitting the asset types into a type vocabulary an address is parsed against                             |
-| `ASSET_SYSTEM`     | `const ASSET_SYSTEM`          | `string` — always `none`                                     | writing an asset address, whose `<system>` segment is a property of the type rather than of the reference |
-| `IMAGE_EXTENSIONS` | `const IMAGE_EXTENSIONS`      | `readonly string[]` — lowercase, dot-led                     | deciding whether a file under a picture root is an asset at all                                           |
-| `AUDIO_EXTENSIONS` | `const AUDIO_EXTENSIONS`      | `readonly string[]` — lowercase, dot-led                     | the same question for `audio/`                                                                            |
-| `isAssetType`      | `isAssetType(type)`           | `boolean`                                                    | scoping a rewrite rule, which may substitute a file and nothing else                                      |
-| `assetTypeOfRoot`  | `assetTypeOfRoot(root)`       | `AssetType \| undefined`                                     | reading a root directory name back to the type it declares                                                |
-| `isAssetShortcode` | `isAssetShortcode(shortcode)` | `boolean`                                                    | telling an addressable filename from one that carries a version string, a hyphen or a date stamp          |
+| Export             | Signature                       | Returns                                                      | Use it when                                                                                                             |
+| ------------------ | ------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `ASSET_TYPES`      | `const ASSET_TYPES`             | `readonly AssetType[]` — type, root, extensions, description | walking the roots, or presenting the vocabulary                                                                         |
+| `ASSET_TYPE_NAMES` | `const ASSET_TYPE_NAMES`        | `ReadonlySet<string>`                                        | admitting the asset types into a type vocabulary an address is parsed against                                           |
+| `ASSET_SYSTEM`     | `const ASSET_SYSTEM`            | `string` — always `none`                                     | writing an asset address, whose `<system>` segment is a property of the type rather than of the reference               |
+| `IMAGE_EXTENSIONS` | `const IMAGE_EXTENSIONS`        | `readonly string[]` — lowercase, dot-led                     | deciding whether a file under a picture root is an asset at all                                                         |
+| `AUDIO_EXTENSIONS` | `const AUDIO_EXTENSIONS`        | `readonly string[]` — lowercase, dot-led                     | the same question for `audio/`                                                                                          |
+| `isAssetType`      | `isAssetType(type)`             | `boolean`                                                    | scoping a rewrite rule, which may substitute a file and nothing else                                                    |
+| `assetTypeOfRoot`  | `assetTypeOfRoot(root)`         | `AssetType \| undefined`                                     | reading a root directory name back to the type it declares                                                              |
+| `isAssetShortcode` | `isAssetShortcode(shortcode)`   | `boolean`                                                    | telling an addressable filename from one that carries a version string, a hyphen or a date stamp                        |
+| `imageDimensions`  | `imageDimensions(absPath, ext)` | `{width, height} \| undefined`                               | reading a raster file's own pixel size from its header, which an SVG carries none of and a partial file fails closed on |
 
 ### `engine.assetIndex`
 
@@ -900,6 +903,7 @@ The asset record: one line of the content index per addressable file. The record
 
 | Export                      | Signature                                                       | Returns                       | Use it when                                                                                                                                             |
 | --------------------------- | --------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSET_ROLES`               | `const ASSET_ROLES`                                             | `readonly string[]`           | naming the closed set of roles a picture may declare                                                                                                    |
 | `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from                                                                                  |
 | `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields                                                                       |
 | `REQUIRED_PROVENANCE_KEYS`  | `const REQUIRED_PROVENANCE_KEYS`                                | `ReadonlySet<string>`         | the keys a provenance file must state — a record resolves wholesale, so one omitting them leaves every file it covers with no rights holder or no terms |
@@ -1047,6 +1051,7 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 | `EMBED_PATTERN`      | `const EMBED_PATTERN`                    | —                                                                                                                                                                  | An embed, as authored, with the directive it may carry.         |
 | `embedsIn`           | `function embedsIn(body)`                | {ParsedEmbed[]} One entry per embed.                                                                                                                               | Every embed in one body, in source order.                       |
 | `resolveEmbed`       | `function resolveEmbed(index, embed)`    | `{{pathname: string}\|{reason: string, target: string, type?: string}}` The authored pathname, or the finding.                                                     | What one embed resolves to, or why it does not.                 |
+| `embedRole`          | `function embedRole(index, address)`     | {string\|undefined} The role, or `undefined` for a note's address, one that resolves nowhere, or a picture that declares none.                                     | The role an address's asset declares, by the same resolution.   |
 | `embedProblems`      | `function embedProblems(embed)`          | {Array<{link: string, offset: number, message: string}>} One entry per defect.                                                                                     | What is wrong with one embed's directive or placement.          |
 | `resolveEmbeds`      | `function resolveEmbeds(body, ctx)`      | `{{markdown: string, unresolved: Array<object>, problems: Array<object>}}` The body, the embeds that named nothing, and the directives that could not be honoured. | Rewrite every embed into the image each surface renders.        |
 | `checkEmbeds`        | `function checkEmbeds(body, file, opts)` | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.                      | Every defect in one note's embeds, located.                     |
@@ -1055,25 +1060,26 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 
 An image saying how wide it is and where it sits. A directive in the curly-attribute convention Pandoc and Kramdown use supplies a width class, a named `size`, and a `float` position. The named size sets a maximum display width for each surface.
 
-| Export                | Signature                                       | Returns                                                                                                                                          | Use it when                                                                  |
-| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                                | The width classes an image may carry, and what each means to a renderer.     |
-| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                                | The named sizes an image directive accepts.                                  |
-| `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                                | The `float` positions an image may take, and where each puts it.             |
-| `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                                | The class every figure carries, whatever its width or position.              |
-| `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                                | A markdown image, with the directive it may carry.                           |
-| `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                          | What is wrong with an image's address, or `""` when nothing is.              |
-| `parseImageDirective` | `function parseImageDirective(raw)`             | `{{classes: string[], size: string, float: string, problems: string[]}}` What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
-| `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                           | The classes a figure carries, from a parsed directive.                       |
-| `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                         | Text going inside an HTML attribute or between tags.                         |
-| `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                          | One image as the `<figure>` both HTML surfaces render.                       |
-| `standsAlone`         | `function standsAlone(text, start, end)`        | {boolean} Whether the match is a block of its own.                                                                                               | Whether a match sits alone in its own paragraph.                             |
-| `imagesIn`            | `function imagesIn(body)`                       | {Array<{alt: string, src: string, title: string, directive: string, index: number, length: number, block: boolean}>} One entry per image.        | Every image in one body, with its directive and its position.                |
-| `imageSourcesIn`      | `function imageSourcesIn(body)`                 | {string[]} The addresses, with repeats.                                                                                                          | Every image address one body names, in order of appearance.                  |
-| `checkImages`         | `function checkImages(body, file,`              | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.    | Every defect in one note's images.                                           |
-| `lintContentImages`   | `function lintContentImages(contentBase,`       | `{{findings: Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>, files: number}}` What it found. | Walk a content tree and report every image it cannot render as authored.     |
-| `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                   | Rewrite every block image in a body into the figure the website publishes.   |
-| `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                     | A markdown-it plugin that reads an image's directive and renders its figure. |
+| Export                | Signature                                       | Returns                                                                                                                                          | Use it when                                                                          |
+| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                                | The width classes an image may carry, and what each means to a renderer.             |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                                | The named sizes an image directive accepts.                                          |
+| `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                                | The `float` positions an image may take, and where each puts it.                     |
+| `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                                | The class every figure carries, whatever its width or position.                      |
+| `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                                | A markdown image, with the directive it may carry.                                   |
+| `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                          | What is wrong with an image's address, or `""` when nothing is.                      |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | `{{classes: string[], size: string, float: string, problems: string[]}}` What was written, and what cannot be honoured.                          | Read the directive on an image.                                                      |
+| `roleClass`           | `function roleClass(role)`                      | {string} The class, or `""`.                                                                                                                     | The class a picture's role names, or `""` for no role or one outside the closed set. |
+| `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                           | The classes a figure carries, from a parsed directive and its asset's role.          |
+| `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                         | Text going inside an HTML attribute or between tags.                                 |
+| `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                          | One image as the `<figure>` both HTML surfaces render.                               |
+| `standsAlone`         | `function standsAlone(text, start, end)`        | {boolean} Whether the match is a block of its own.                                                                                               | Whether a match sits alone in its own paragraph.                                     |
+| `imagesIn`            | `function imagesIn(body)`                       | {Array<{alt: string, src: string, title: string, directive: string, index: number, length: number, block: boolean}>} One entry per image.        | Every image in one body, with its directive and its position.                        |
+| `imageSourcesIn`      | `function imageSourcesIn(body)`                 | {string[]} The addresses, with repeats.                                                                                                          | Every image address one body names, in order of appearance.                          |
+| `checkImages`         | `function checkImages(body, file,`              | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.    | Every defect in one note's images.                                                   |
+| `lintContentImages`   | `function lintContentImages(contentBase,`       | `{{findings: Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>, files: number}}` What it found. | Walk a content tree and report every image it cannot render as authored.             |
+| `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                   | Rewrite every block image in a body into the figure the website publishes.           |
+| `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                     | A markdown-it plugin that reads an image's directive and renders its figure.         |
 
 ### `engine.contentTaskLists`
 
@@ -1090,15 +1096,16 @@ A list item opened with `[ ]` or `[x]`, reported. The format has no checkbox: a
 
 One authored pathname, and the four addresses it resolves to. A note names a file once — in `img:`, in `data.portrait:`, in the body of a markdown image — and the first segment says which package owns it when an `assets/` follows. Every surface derives its own address from that one statement: the path inside a Foundry install, the file in the owning repository's tree, the address the website serves, and where the book stages its copy.
 
-| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                         |
-| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                         |
-| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                    |
-| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.   |
-| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.    |
-| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves. |
-| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory. |
-| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.     |
+| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                                                                          |
+| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                                                                          |
+| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                                                                     |
+| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.                                                    |
+| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.                                                     |
+| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves.                                                  |
+| `assetPathnameKey`      | `function assetPathnameKey(src, config)`      | {string\|null} The pathname, or `null` for an address naming no asset record to look up.           | The pathname one authored image address keys an asset's role and pixel size under, whichever form it was written in. |
+| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory.                                                  |
+| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.                                                      |
 
 ### `engine.contentLinks`
 
@@ -1233,11 +1240,13 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 `buildSiteIndex` gathers addressable pages and ambiguity findings. `wikiContext`
 provides the per-page context used when resolving a link such as `[[Something]]`.
 
-| Export              | Signature                                          | Returns                                                                                                                        | Use it when                                                                                                  |
-| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `buildSiteIndex`    | `function buildSiteIndex(entries,`                 | {SiteIndex} The index, and what could not be addressed unambiguously.                                                          | Build the address index a site's wikilink resolver reads.                                                    |
-| `wikiContext`       | `function wikiContext(built,`                      | {object} The resolver context.                                                                                                 | The per-page context a wikilink resolver takes.                                                              |
-| `resolveInfoboxRef` | `function resolveInfoboxRef(siteIndex, ref, hint)` | {{name?: string, url?: string, address?: string, subType?: string}\|undefined} The page, or `undefined` where nothing answers. | Resolve one infobox reference — a bare shortcode, a short address or a canonical one — against a site index. |
+| Export                    | Signature                                           | Returns                                                                                                                               | Use it when                                                                                                  |
+| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `buildSiteIndex`          | `function buildSiteIndex(entries,`                  | {SiteIndex} The index, and what could not be addressed unambiguously.                                                                 | Build the address index a site's wikilink resolver reads.                                                    |
+| `figureIndexKeys`         | `function figureIndexKeys(pkg, type, shortcode)`    | {Set<string>} The short `type/shortcode` key and the canonical `package-system-type-shortcode` one.                                   | Get the address keys one page's figures are reachable by, matching `buildSiteIndex`'s own.                   |
+| `resolveCrossNoteFigures` | `function resolveCrossNoteFigures(target, options)` | {{url: string, figures: Map<string, object>}\|undefined} The target's own address and figures, or `undefined` where no note resolves. | Resolve a `ref` call's cross-note address to the target's own figures, the way a wikilink would.             |
+| `wikiContext`             | `function wikiContext(built,`                       | {object} The resolver context.                                                                                                        | The per-page context a wikilink resolver takes.                                                              |
+| `resolveInfoboxRef`       | `function resolveInfoboxRef(siteIndex, ref, hint)`  | {{name?: string, url?: string, address?: string, subType?: string}\|undefined} The page, or `undefined` where nothing answers.        | Resolve one infobox reference — a bare shortcode, a short address or a canonical one — against a site index. |
 
 ### `engine.pdfToc`
 
@@ -1589,9 +1598,11 @@ HM3's Item pass — the parts of compiling a note into an HM3 Item that are fact
 
 HM3's Actor pass — what an HM3 `character` or `creature` holds. A being note authors which HM3 subtype it becomes via `hm3.type` (never defaulted), and only four of the content format's `being` mapping-table rows have an HM3 destination (`portrait`, `species`, `gender`, `occupation`, `templatePriority`) plus the two anchored prose sections (`{#appearance}` → `description`, `{#dossier}` → `biography`); `gender` and `occupation` are written only on a `character`.
 
-| Export      | Signature         | Returns | Use it when                                                        |
-| ----------- | ----------------- | ------- | ------------------------------------------------------------------ |
-| `Hm3Actors` | `class Hm3Actors` | —       | not called directly — imported and driven by `engine/generate.mjs` |
+| Export             | Signature                | Returns | Use it when                                                                   |
+| ------------------ | ------------------------ | ------- | ----------------------------------------------------------------------------- |
+| `Hm3Actors`        | `class Hm3Actors`        | —       | not called directly — imported and driven by `engine/generate.mjs`            |
+| `ACTOR_FIELDS`     | `const ACTOR_FIELDS`     | —       | reading the fields native to every HM3 actor subtype                          |
+| `CHARACTER_FIELDS` | `const CHARACTER_FIELDS` | —       | reading the fields `hm3.actors` declares on `character` and not on `creature` |
 
 ### `hm3.templatePriority`
 
@@ -1631,6 +1642,7 @@ const config = defineConfig({
 | `defineConfig`             | `defineConfig(config)`             | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
 | `PACKAGE_KINDS`            | `const PACKAGE_KINDS`              | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
 | `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`         | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
+| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`          | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
 | `compilesFoundryDocuments` | `compilesFoundryDocuments(config)` | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
 | `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`        | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
 | `DEFAULT_PATHS`            | `const DEFAULT_PATHS`              | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
@@ -1868,7 +1880,8 @@ console.log(normalizeRepoUrl("git@github.com:HeroicLands/sohl.git"));
 | `metadataUrl`                  | `metadataUrl({ repoUrl, version, contentPackage })`                                 | `string` — the version-pinned asset URL                                                                                 | computing where this release publishes its content index, pinned to this version like `download` so a dependency's manifest and its fetched index always describe the same release |
 | `manifestPacks`                | `manifestPacks(config)`                                                             | `object[]`                                                                                                              | deriving the manifest's `packs` array from the one pack list the build already has, in build order, companions flattened in                                                        |
 | `packFolderFindings`           | `packFolderFindings({ packFolders, packs = [] })`                                   | `Array<{severity: "error"\|"warning", message: string, pack: string, folder?: string, keyPath: Array<string\|number>}>` | checking a declared `packFolders` against the derived pack list — a folder naming a pack that does not exist is an error, a pack no folder names is a warning                      |
-| `BUILD_ONLY_RELATIONSHIP_KEYS` | `const BUILD_ONLY_RELATIONSHIP_KEYS`                                                | —                                                                                                                       | reading which `relationships` keys direct the build (e.g. `itemCatalog`) rather than describe the published package, so they can be filtered out of what ships                     |
+| `FOUNDRY_RELATIONSHIP_KEYS`    | `const FOUNDRY_RELATIONSHIP_KEYS`                                                   | `readonly string[]` — `id`, `type`, `manifest`, `compatibility`, `reason`                                               | reading which relationship keys Foundry's own schema names, which is what makes every other declared key the build's own                                                           |
+| `BUILD_ONLY_RELATIONSHIP_KEYS` | `const BUILD_ONLY_RELATIONSHIP_KEYS`                                                | `readonly string[]` — derived                                                                                           | reading which `relationships` keys direct the build rather than describe the published package, so they can be filtered out of what ships                                          |
 | `publishedRelationships`       | `publishedRelationships(relationships)`                                             | `Record<string, unknown>`                                                                                               | producing the `relationships` block as it should be published, with `BUILD_ONLY_RELATIONSHIP_KEYS` dropped and everything else preserved in order                                  |
 | `buildManifest`                | `buildManifest({ config, packageJson, artifact, flags })`                           | `object` — the manifest, ready to serialise                                                                             | assembling the full Foundry package manifest object from the resolved configuration, without writing it anywhere                                                                   |
 | `writeManifest`                | `async writeManifest({ config, packageJson, artifact, outDir, flags, configFile })` | `Promise<{path: string, manifest: object}>`                                                                             | building the manifest and writing it into the staged package; refuses to write when `packFolders` names a pack the build does not produce                                          |

package/docs/authoring/assets.md

@@ -28,4 +28,33 @@ The embed's label is alternative text. `![[icon-harbor|]]` is decorative. `size=
 
 Record provenance for the assets you ship. Put `provenance.yaml` in an asset directory to describe files there and below, or put a YAML sidecar beside one asset to give that file its own record. A sidecar takes precedence over a directory record for that asset. An asset with no record still enters the index with blank provenance fields. Keep attribution with the authored asset so movement through the tree does not lose its source or license. See the [asset record reference](../reference/format-details.md#the-asset-record) for the accepted keys, inheritance, and examples.
 
+A directory of portraits also states what the pictures in it are for:
+
+```yaml
+attribution: Tom Rodriguez
+license: CC-BY-SA-4.0
+role: portrait
+```
+
+**A hero image is 1792×768.** `data.banner` fills one fixed strip wherever it is drawn, so every banner is cut to that size and a picture of any other size is a finding naming both sizes — resize the picture to match. That is the one size any art field requires. A map's `bgImage` sets its own scene's dimensions, so that asks nothing of a picture's dimensions either.
+
+`data.banner` reads in one of three states:
+
+| A note writes      | The page draws                                     |
+| ------------------ | -------------------------------------------------- |
+| an asset Address   | that picture                                       |
+| a blank            | no picture, on purpose, and no default replaces it |
+| nothing, or `null` | a default picture chosen by the note's `type`      |
+
+Omitting the key does not mean "no hero image" — it means artwork chosen for
+the author, which inverts the ordinary reading of an absent key. **A note
+declines with a blank, not with `none`.** `none` parses as an ordinary asset
+Address — a shortcode, not a keyword — and since nothing in the corpus
+answers to it, the build drops the key outright and the page falls through to
+its type's default: the opposite of a decline.
+
+`role` is one of `portrait`, `emblem`, `banner`, `plate` or `map`, and belongs to the `image` type only — declaring it in a `provenance.yaml` under `assets/icons` is a finding, since an icon carries one nominal size per medium whatever the file holds. Leave the key out for an ordinary picture; there is no default role name, only its absence.
+
+**A role decides how large a picture written in prose draws, when nothing else states a size.** Each medium maps a role to a maximum, and the drawn size is the smaller of that slot and what the file's own pixels support — see [what a role draws at](../reference/format-details.md#what-a-role-draws-at). A named `size=` beside the embed still overrides it outright; an icon draws at the medium's nominal icon size whatever role it might otherwise have had, because `role` never reaches an icon address at all.
+
 The build writes transformed or optimized copies under `build/`; the authored file remains the input for the next build. Output paths are derived from the owning package, asset type, and build target. The [icon guide](../guides/icons.md) covers generated icon variants and placement in Foundry.

package/docs/authoring/dates-and-calendars.md

@@ -7,7 +7,7 @@ subType: howto
 
 # Dates, calendars, and eras
 
-A canonical date uses the world's year and day count without choosing a culture's calendar. Write `<year>[.<day>[:HHMMSS]]`: `720` covers year 720, `720.136` covers its day 136, and `720.136:143005` identifies 14:30:05 on that day. The dot separates the year from the **day of year**, not a month. Negative years are valid, and the day must fit the world's declared year length. Prefix a date with `~` when its uncertainty extends outside the stated year, day, or second. `unknown` records an occurrence whose date is not known, in fields that permit it.
+A canonical date uses the world's year and day count without choosing a culture's calendar. Write `<year>[.<day>[:HHMMSS]]`: `720` covers year 720, `720.136` covers its day 136, and `720.136:143005` identifies 14:30:05 on that day. The dot separates the year from the **day of year**, not a month. Negative years are valid, and the day must fit the world's declared year length — `data.year.days` on its `place` note. A tree whose notes declare no world year bounds no day at all: every value is read as written, however large, because there is no year length to check it against. Prefix a date with `~` when its uncertainty extends outside the stated year, day, or second. `unknown` records an occurrence whose date is not known, in fields that permit it.
 
 **Put a date that states a day in quotes.** Write `born: "667.130"`, not `born: 667.130`. Unquoted, YAML reads the scalar as a number, and a number keeps no trailing zero — `667.130` becomes `667.13`, which is day 13 rather than day 130, and the authored digits are gone before any reader of the date can object. A date whose lost zero would still name a day inside the world's year is therefore refused, naming the line and both readings, so quoting it is the fix. A bare year such as `born: 667` loses nothing and needs no quotes.
 
@@ -85,3 +85,39 @@ package-build dateto commoncal 326.114 --format long
 The CLI `datefrom` command requires a day and reads the default (`std`, or first) pattern. `dateto` prints the era covering the canonical day. A clock time makes a date exact; a year or day without one spans the stated interval. `data.epoch` and `data.moon.newOn` require a day. The [detailed date rules](../reference/format-details.md#dates-and-calendars) describe precision and bounds.
 
 In prose, `{{dateformat "commoncal" data.born}}` prints a date in the chosen calendar. `{{dateformat data.calendar data.born}}` uses the note's calendar Address. A third argument chooses another named pattern. A being or place can set `data.calendar`; its infobox uses that calendar for dates.
+
+## Write a recurring date
+
+A `lore` note states its dated occurrences under `data.events`, a list — a note may record a founding once and an annual festival beside it. Each entry is `{ when, until?, recurs? }`, with `when` the occurrence's anchor and first instance:
+
+```yaml
+data:
+  events:
+    - when: 412.1
+      recurs: { every: 1 }
+    - when: 689.5
+      until: 1203.9
+      recurs: { every: 514 }
+```
+
+The first entry is annual, with no end. The second recurs every five hundred fourteen years and stopped after canonical year 1203; `recurs.every` always counts whole years on the canonical axis. In place of a period, `recurs.on` lists the dates somebody actually recorded, strictly increasing and each later than `when`:
+
+```yaml
+data:
+  events:
+    - when: 326.1
+      recurs:
+        on: ["412.1", "689.5"]
+```
+
+A build computes the next occurrence against the world's declared present the way it computes a being's age against it, and publishes it on the web page, in the content index, and in the infobox.
+
+**A day that recurs every year, with no founding date of its own, writes year `0`** — quoted, since every canonical date stating a day must be:
+
+```yaml
+data:
+  events:
+    - when: "0.286"
+```
+
+`when: "0.286"` is the two-hundred-eighty-sixth day of the year, every year — a harvest rite nobody dates to a founding. `recurs` is refused beside it, since the entry is already annual; `until` is allowed, and bounds how long the rite was kept.