@heroiclands/package-build 22.22.0 → 22.23.0

package/docs/reference/format-details.md

@@ -352,7 +352,7 @@ order without changing the Markdown body.
 
 #### Dates and calendars
 
-A canonical date is `<year>[.<day>[:HHMMSS]]`. The day is one-based within the world's year. `720` covers the whole year; `720.136` covers that day; `720.136:143005` identifies one second. Negative years are valid. Prefix either form with `~` to express uncertainty beyond its written interval. `unknown` is allowed only in fields that accept an unknown occurrence.
+A canonical date is `<year>[.<day>[:HHMMSS]]`. The day is one-based within the world's year, bound against `data.year.days` on the world's `place` note. A tree whose notes declare no world year bounds no day: the value is read as written, however large. `720` covers the whole year; `720.136` covers that day; `720.136:143005` identifies one second. Negative years are valid. Prefix either form with `~` to express uncertainty beyond its written interval. `unknown` is allowed only in fields that accept an unknown occurrence.
 
 **Quote a canonical date that states a day.** `born: "667.130"` is read as written; unquoted, YAML parses the scalar as a number and a trailing zero on the day is gone before any date reader sees it, so `667.130` and `667.13` arrive as one value. A number-valued date is an error wherever appending a zero to its day would still name a day inside the world's year — the message names the file, the line and both readings — and is read as written where no such day exists, since `675.2810` is no day of a 365-day year. A bare year loses nothing and needs no quotes.
 
@@ -701,12 +701,12 @@ exactly as `seat` declares `place` — a bare shortcode takes its type from the
 declaration, and qualification climbs the same short-form ladder every other
 link uses.
 
-| field       | default type | accepts         | resolves into                | on                                        |
-| ----------- | ------------ | --------------- | ---------------------------- | ----------------------------------------- |
-| `icon`      | `icon`       | `icon`, `image` | `document.img`               | every Actor/Item type, and embedded items |
-| `tokenIcon` | `icon`       | `icon`, `image` | `prototypeToken.texture.src` | Actor types                               |
-| `bgImage`   | `image`      | `icon`, `image` | `background.src`             | map types                                 |
-| `banner`    | `image`      | `icon`, `image` | the site hero image          | any note; not a Foundry field             |
+| field       | default type | accepts         | resolves into                 | on                                        |
+| ----------- | ------------ | --------------- | ----------------------------- | ----------------------------------------- |
+| `icon`      | `icon`       | `icon`, `image` | `document.img`                | every Actor/Item type, and embedded items |
+| `tokenIcon` | `icon`       | `icon`, `image` | `prototypeToken.texture.src`  | Actor types                               |
+| `bgImage`   | `image`      | `icon`, `image` | `background.src`              | map types                                 |
+| `banner`    | `image`      | `icon`, `image` | the site hero image, 1792×768 | any note; not a Foundry field             |
 
 All four are authored under `data:`:
 
@@ -750,7 +750,7 @@ noticed:
 | `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
 | `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
 | `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
+| `banner`               | `Address`              | The page's hero image — an `image` address, cut to 1792×768.         |
 
 `icon` is legal everywhere because most types compile into a document that
 carries one; where a type's passes emit none, the lint says so and the value is
@@ -853,12 +853,12 @@ ships as the Foundry module `harn-ensemble`) writing `images/map.webp`:
 And for the same note writing `sohl/assets/icons/noun/shield.svg`, a file the
 system ships and this repository does not hold:
 
-| Surface     | Address                                                   |
-| ----------- | --------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`               |
-| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository  |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`  |
-| **Book**    | not carried — a build stages only what this package ships |
+| Surface     | Address                                                       |
+| ----------- | ------------------------------------------------------------- |
+| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`                   |
+| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository      |
+| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`      |
+| **Book**    | not carried, unless a declared replacement carries it instead |
 
 **The content package name and Foundry id are separate values.**
 `harnensemble` is what the content is called, what a note writes, and what the
@@ -884,6 +884,29 @@ index enabled, an asset with no matching note is a located build error. See
 [asset bindings](../configuration.md#packagebuildstagedir-and-packagebuildassets)
 for the configuration and cache requirements.
 
+**A package declared as a replacement is carried into the book, from its
+fetched archive, when it answers the address; every other foreign package
+stays not carried.** A relationship declaring `assetReplacement: true` names a
+dependency whose asset tree answers this package's own addresses first — see
+[`relationships`](../configuration.md#relationships) — and the book is the one
+surface that otherwise refuses a foreign file outright, so it is the one
+surface this changes. A `thalorna` note embedding
+`![[thalornaaltart-none-icon-anvil|An anvil]]` names `thalornaaltart`'s own
+address, exactly as a note citing `sohl`'s shared bestiary art would; when
+`thalornaaltart` is declared with `assetReplacement: true` and its fetched
+archive carries `icon-anvil` under its own package, the book stages that file
+from the archive instead of printing the caption with no picture. A note
+citing a different package's own address this way — `sohl`'s bestiary art,
+say — stays refused exactly as the row above states, because `sohl` was never
+declared as a replacement: a package answers in place of another only when it
+opted in, never because its archive happens to carry a file at the same type
+and shortcode.
+
+A relationship declaring `assetReplacement: true` whose archive was never
+fetched is a configuration mistake, not an ordinary unresolved address: the
+book reports a located error naming the relationship and instructing
+`package-build deps fetch`, rather than printing a caption with no picture.
+
 **The host is configuration.** `site.assets` in `package-build.config.yaml` is
 the root the web form is joined onto, and a package-owned image on a page with
 none set is an error naming that key.
@@ -927,6 +950,18 @@ Foundry destination: searching a built `packs-json` tree for it turns up
 nothing. It reaches the generated page and the book's section plates, and
 nothing else.
 
+**A hero image is 1792×768.** It 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. The size is stated once, by the
+slot itself, which is what gives an artist a figure to work to before any file
+exists.
+
+No other art slot states a size, and none of them asks anything of a picture's
+dimensions. An `icon` is drawn at a nominal size per medium whatever its file
+holds; a map's `bgImage` sets its own scene's dimensions, so it is whatever size
+the map is; and a picture written in prose is fitted to the room it has. Those
+three accept whatever they are given.
+
 It is an `Address` all the same, defaulting to type `image`, so a section note
 writes `banner: skillbnr` and a note borrowing another package's plate writes
 `banner: packagebuild-none-image-skillbnr`. The resolved record carries the
@@ -1685,14 +1720,17 @@ carries no frontmatter, no anchors and no `foundry` block: a file declares
 nothing about itself, compiles into no document, and publishes no page, so the
 `address` holds the canonical key and no page slug.
 
-| `asset` field | Source     | What it says                                                       |
-| ------------- | ---------- | ------------------------------------------------------------------ |
-| `path`        | the walk   | Where the file sits inside the emitting package's asset directory. |
-| `attribution` | provenance | The person holding the rights, to whom attribution is legally due. |
-| `source`      | provenance | Where it came from — a URL, or a sentence.                         |
-| `ai`          | provenance | Whether the file is machine-generated — `true` or `false`.         |
-| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.       |
-| `notes`       | provenance | Anything else a person reading the attribution needs.              |
+| `asset` field | Source     | What it says                                                                                                                                                                                                                         |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `path`        | the walk   | Where the file sits inside the emitting package's asset directory.                                                                                                                                                                   |
+| `attribution` | provenance | The person holding the rights, to whom attribution is legally due.                                                                                                                                                                   |
+| `source`      | provenance | Where it came from — a URL, or a sentence.                                                                                                                                                                                           |
+| `ai`          | provenance | Whether the file is machine-generated — strictly the YAML boolean `true` or `false`; any other value is a finding, never a stringified record. Unstated resolves to `false`.                                                         |
+| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.                                                                                                                                                                         |
+| `notes`       | provenance | Anything else a person reading the attribution needs.                                                                                                                                                                                |
+| `role`        | provenance | What the picture is for — `portrait`, `emblem`, `banner`, `plate` or `map`. Absent for an ordinary picture; a value outside that set is a finding. The `image` type only — a value on an `icon` address is a finding and is dropped. |
+| `width`       | the walk   | The file's pixel width, read from its own header. Blank for an SVG, which has no pixel dimensions.                                                                                                                                   |
+| `height`      | the walk   | The file's pixel height, read from its own header. Blank for an SVG, which has no pixel dimensions.                                                                                                                                  |
 
 Every field is present on every record, blank where nothing states one. A fixed
 shape is what lets a consumer read `asset.license` without first asking whether
@@ -1711,6 +1749,90 @@ joins its own root onto it:
 Foundry paths use the **Foundry package id**. The two values are both `thalorna`
 for this image; `harnensemble` content uses `harn-ensemble` in its Foundry paths.
 
+##### What a role declares
+
+`role` names what the picture is for, from a closed set:
+
+| Role       | What it names                                            |
+| ---------- | -------------------------------------------------------- |
+| `portrait` | A picture of a subject — a being, a building, an object. |
+| `emblem`   | A device, arms, a sigil — a mark rather than a scene.    |
+| `banner`   | A wide strip across the head of a page or a book plate.  |
+| `plate`    | A full-measure illustration meant to be looked at.       |
+| `map`      | A plan or chart, read by examining its detail.           |
+
+An asset declaring no role is an ordinary picture: there is no default role
+name, only the absence of one. A value outside this set is refused with a
+finding naming the file, the key and the accepted values, and the record
+carries no role rather than the one it was given. `role` belongs to the
+`image` type only — an `icon` address carries one nominal size per medium
+whatever the file holds, so a `role` declared there is a finding and is
+dropped rather than carried through.
+
+A declared role makes two checks possible. **Shape**, an error, flags an
+asset whose aspect ratio departs from the median of every other asset
+sharing its role — the expectation is derived from the role-sharing group
+itself at build time, never from a second, hand-kept table. **Resolution**,
+a warning, flags an asset whose pixel width falls short of what its role's
+largest print slot needs. Both exempt a vector asset, which carries no pixel
+dimensions and no aspect that survives being drawn at a nominal size.
+
+`role: map` also selects a `:::figure` fence's counter — see
+[figures and numbered references](../authoring/links-and-markup.md#figures-and-numbered-references).
+A fence whose picture draws an address with that role counts as `Map` rather
+than `Figure`, on every surface that numbers it, because the role is the one
+fact the fence's own markup cannot state.
+
+##### What a role draws at
+
+A role names what a picture is for; it says nothing about how large one
+draws. Deciding that is a medium's own job — the book owns a table mapping
+each role to a maximum, and a website's or a Foundry system's stylesheet owns
+the equivalent table for its own surface, keyed off the role class and the
+`width`/`height` attributes the emitted markup carries (blank for a vector).
+Changing a role's slot is one line in that table, not an edit to every note
+drawing one.
+
+**Every size is a maximum, never a target.** The drawn width is the smaller of
+the role's slot and what the file's own pixels support at the medium's print
+floor:
+
+> drawn width = min(the role's slot, natural pixels ÷ the print floor)
+
+A picture is never drawn larger than it was made: a 512px portrait stretched
+across the slot a `plate` fills is a soft rectangle that reads as broken. A
+vector carries no pixel count, so nothing narrows its role's slot; it always
+draws at the slot. An `icon` address takes the medium's nominal icon size
+whatever role it might otherwise have had — `role` never reaches one, since
+the asset record refuses it there.
+
+The book's table, and the print floor it reads from the same constant its page
+geometry is set against (300 dpi):
+
+| Role                        | The book's slot                   |
+| --------------------------- | --------------------------------- |
+| `portrait`, `emblem`        | half the page's text measure      |
+| `banner`, `plate`, `map`    | the full page's text measure      |
+| an `icon` address, any role | one inch, whatever the file holds |
+
+On this book's US Letter page the text measure is about 7.00in, so a
+`portrait` or an `emblem` draws at up to about 3.50in and a `banner`, a
+`plate` or a `map` draws at up to about 7.00in — still the smaller of that
+and what the file's pixels support.
+
+**A worked example.** A `portrait`-role file measuring 900×1350px, drawn with
+no named `size=`: at 300 dpi its pixels support 900 ÷ 300 = 3.00in, which is
+narrower than the role's 3.50in slot, so the book draws it at 3.00in. The same
+picture at 1200×1800px supports 4.00in, wider than the slot, so the book draws
+it at its 3.50in slot instead — the slot bounds it, exactly as a maximum
+should. Either way the emitted markup for the website and for a Foundry
+journal carries `note-image-role-portrait` as a class and `900`/`1350` (or
+`1200`/`1800`) as its `width`/`height` attributes, which is what a stylesheet
+on either surface sizes a `portrait` from.
+
+A named `size=` written beside the embed overrides a role's slot outright, the
+same as it always has — a role decides the size nothing else states.
+
 ##### Where provenance comes from
 
 A `provenance.yaml` states the provenance fields in the table above, and nothing
@@ -1738,9 +1860,40 @@ resolving a chain by hand.
 That is also why `attribution` and `license` are **required in any record that
 exists**: a key left out is not inherited from above, it is simply absent, so a
 record stating neither leaves every file it covers with no rights holder and no
-terms. Omitting one is a finding. `source`, `ai` and `notes` stay optional,
+terms. Omitting one is a finding. `source`, `ai`, `notes` and `role` stay optional,
 because a blank is a truthful answer for each of them.
 
+##### A declared replacement resolves first
+
+A package may declare, on a `relationships.<kind>[]` entry, that a
+dependency's asset tree answers this package's own asset addresses ahead of
+its local record — `assetReplacement: true` in `package-build.config.yaml`.
+Once declared, an asset address resolves in this order:
+
+1. **Every declared replacement, in declaration order.** The package segment
+   of each relationship declaring `assetReplacement: true` is tried in the
+   order those relationships are written, and the first one carrying the
+   address wins.
+2. **Falling through to the package's own record** when no declared
+   replacement carries the address — the resolution this package already
+   performs with no `assetReplacement` declared at all.
+
+**This reaches asset types only.** A being, an item or a lore note is never
+replaced this way, whatever a relationship declares: the rule tests the
+address's type, not the relationship. A replacement answers only `icon`,
+`image` and `audio` addresses whose package segment is this package's own; an
+address naming any other type, or naming a different package, is untouched.
+
+**A replacement's own output address is never itself looked up against
+another replacement.** Resolving `thalornaaltart-none-image-thorn` never asks
+whether something replaces `thalornaaltart` — resolution is a single pass over
+the declared list, not a chain, which forecloses a cycle by construction.
+
+This is distinct from a `foreign` lookup, which serves a declared dependency's
+own content for an address this package's local index does not carry. A
+replacement is consulted **before** the local address; a foreign lookup only
+**after** it misses locally.
+
 #### A font is not an asset
 
 `assets/fonts` is not a root, and a font has no address.
@@ -2089,7 +2242,7 @@ See the [authoring examples](../authoring/links-and-markup.md#footnotes-and-defi
 ```
 
 Any header can end with a braced attribute block, in the same grammar a
-`:::caption` and a named block take. Inside the braces:
+`:::figure` fence and a named block take. Inside the braces:
 
 - `#id` names the anchor a link resolves to (only one allowed)
 - `.class1` names a CSS class (any number of classes allowed)
@@ -2171,11 +2324,14 @@ either side of it, and every surface renders it as a figure. An image sharing a
 paragraph with prose is refused, because a width and a position mean nothing
 applied to a word in the middle of a sentence.
 
-**The alt text is the caption.** Print has no `alt` attribute and has to put
-those words somewhere a reader can see them, so every surface draws them under
-the picture; the two HTML surfaces carry them as `alt` as well. A title —
-`![alt](src "title")` — is refused rather than dropped in silence: there is one
-place for those words and this is it.
+**Alt text renders as a caption on no surface.** On the website and in a
+Foundry journal it stays on the `img` element's `alt` attribute alone, and the
+book prints nothing beneath a picture that carries none. A visible label and
+caption are drawn only for a picture wrapped in [a `:::figure`
+fence](#the-figure-fence), and the text drawn is always the fence's own
+caption. A title — `![alt](src "title")` — is refused rather than dropped in
+silence: there is one place for those words, the alt text, and a title is not
+it.
 
 ##### Width is a class, and the ordinary width carries no marker
 
@@ -2465,34 +2621,110 @@ the tag and, where the directive restricts one, the type. An empty list under
 an authored heading is how a misspelled tag survives a build, so the
 directive's silence is what is refused rather than its output.
 
-##### Captioned blocks
+##### The figure fence
 
-`:::caption {#anchor}` labels the next Markdown block, whether it is prose,
-code, a table, or an image. The closing `:::` ends the caption text; blank lines
-between the fence and its block are allowed. The ID is unique within the note
-and contains letters, digits, `_`, or `-`, beginning with a letter. An empty
-caption, missing ID, missing closer, or missing following block is an error at
-the opening line.
+`:::figure {#anchor .border}` declares what it numbers and, optionally,
+captions: the fence is the unit the counter counts, not the caption text it
+may or may not carry.
 
 ````markdown
-See [[#trade|]] for the market routes.
-
-:::caption {#trade}
-Regional trade routes
-:::
+:::figure {#trade}
 
 ```sql
 SELECT name.full AS "Market" FROM notes WHERE type = 'place'
 ```
+
+///
+Regional trade routes
+:::
+
+Refer to {{ref "#trade"}} for the market routes.
 ````
 
-The block displays **Table 1: Regional trade routes** and `[[#trade|]]`
-displays **Table 1** as a link. A nonempty label after the pipe takes precedence.
-The category comes from the following block: a regular code fence is code,
-a Markdown or expanded SQL table is a table, an image is a figure, and any other
-block is prose. The website and Foundry number each category within a note;
-the PDF numbers each category through the book. Foundry gives a captioned block
-its own JournalEntryPage, so its anchor has a page UUID.
+The fence displays **Table 1: Regional trade routes** and `{{ref "#trade"}}`
+displays **Table 1** as a link.
+
+**The grammar.** `:::figure` opens the fence, on a line of its own and
+optionally followed by a braced attribute block in the grammar a heading and
+a named block take too. A line of `:::` alone closes it. Between the
+two, the first `///` written alone on a line, read at the top level — outside
+any nested code fence — divides what the fence holds from its caption; a `///`
+written inside a nested fence is content, not a divider. A second top-level
+`///` is an error, naming the line: a figure holds one caption, so it carries
+one `///` line.
+
+An opening line that is not `:::figure`, optionally followed by one braced
+attribute block and nothing else, is reported at its own line as
+`a figure's attributes are written as {#id .border}`.
+
+**Every part but the fence itself is optional.**
+
+- **No `{#id}`.** The fence is still numbered and drawn; it carries no anchor,
+  so nothing can address it. An id, when written, must be a name unique within
+  the note — a repeat is `duplicate figure id "<id>"` at the fence's opening
+  line, and an id that collides with a heading anchor in the same note is
+  `heading and figure declare the same anchor "<id>"` at the heading's line.
+- **No `///`.** The fence draws its label alone, with no caption beneath it. A
+  `///` with nothing after it before the closing `:::` is an error at the
+  `///` line: a figure's `///` section carries no caption — write no `///` to
+  leave the figure uncaptioned.
+- **No `.border`.** The fence draws without one. `.border` is the only class
+  the construct declares; any other class is reported at the opening line,
+  naming it: a figure takes no such class, and the classes a figure takes
+  are `.border`. A `key="value"` attribute is reported the same way, naming
+  the key: a figure takes an id and classes, nothing else.
+
+**What is never optional.** A fence with nothing between its opening line and
+its `///` or its closing `:::` is `a figure has no contents`, at the opening
+line. An opening `:::figure` with no matching `:::` runs to the end of the
+note and is `a figure needs a closing :::`, also at the opening line, and
+nothing after it is scanned as a second fence.
+
+**The counter is derived, never authored.** The fence's contents decide which
+of four counters it draws from — `Code`, `Table`, `Figure`, `Prose` — read from
+the first top-level block inside the fence: a table is `Table`; a fenced `sql`
+block is `Table`, because its rendered output is one; any other fenced or
+indented code block is `Code`; one or more pictures and nothing else is
+`Figure`; everything else is `Prose`. A table or a picture written outside any
+`:::figure` fence draws no label and is counted nowhere. The website and a
+Foundry journal number each counter within the note; the book numbers each
+counter across the book in reading order.
+
+**A heading that would start its own journal page cannot be written inside a
+fence.** An H1, or a heading at any level carrying an `{#anchor}`, is reported
+at its own line inside one: `a heading that starts a page cannot be written
+inside a figure — keep an H1 or an anchored heading at the top level, or drop
+the anchor and the level to stay inside it`.
+
+**The `ref` expression renders a link to a figure's anchor.**
+`{{ref "#thorn"}}` renders "Figure 13"; `{{ref "#thorn" form="full"}}` renders
+the number and the caption; `{{ref "#thorn" form="title"}}` renders the
+caption alone. `form="number"` is the default and may be written explicitly;
+a `form` outside this closed set is reported naming the three. A link written
+inside the figure's own caption contributes only its label text to a `full`
+or `title` reference, because the reference is itself a link, and emphasis
+inside the caption is kept. `form="full"` or `form="title"` aimed at a figure
+with no caption is reported naming the anchor: that form needs a caption, and
+the figure has none. An address naming no figure in the note is reported
+naming the anchor; an address naming another note's figure —
+`{{ref "other-note#anchor"}}` — is reported as addressing a figure this build
+does not resolve outside the note carrying the reference. Only a same-note
+anchor resolves, on the website and in the book.
+
+Foundry gives a `:::figure` fence its own JournalEntryPage. A fence holding
+exactly one picture, captioned in plain text with nothing else — or carrying
+no caption at all — becomes a page of type `image`: the picture is its `src`,
+a caption, when there is one, is `image.caption`, and the page is named for
+the figure's own number. Every other fence becomes a page of type `text`
+instead: a fence grouping more than one picture; an embedded sound, there
+being no audio page type; a fence whose caption carries inline markup —
+emphasis, a link, an embedded icon or image — because `image.caption` is a
+`StringField` with nowhere to render it; and a fence that shares its split
+with prose that follows it, because an `image` page has nowhere to carry that
+prose either. On a `text` page the render is the fence's own content, scanned
+and labelled as the first of its kind on that page alone and then corrected to
+the number the note-wide scan already assigned, so a second figure with no id
+is still named for its true, note-wide number rather than recounted from one.
 
 ##### Named blocks
 
@@ -3775,18 +4007,49 @@ the setting itself, rather than instructions or other apparatus for the GM.
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
 
-| `data` property | Values                                                                        | Description                                                  |
-| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `epoch`         | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1         |
-| `months`        | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year           |
-| `weekdays`      | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously |
-| `seasons`       | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                   |
-| `namedDays`     | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                     |
-| `eras`          | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year        |
-| `formats`       | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default           |
-| `event`         | map                                                                           | A dated occurrence and its chronology metadata               |
-
-`data.event` is available on every `lore` subType. It holds structured chronology metadata, including an event's kind, date, sources, and affected places. The shared format checks that it is a map; a content package can check its details. It does not appear as an infobox row.
+| `data` property         | Values                                                                        | Description                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                |
+| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                  |
+| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                        |
+| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                          |
+| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                            |
+| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                               |
+| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                  |
+| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields |
+| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                               |
+| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                    |
+| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                 |
+| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                  |
+| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                         |
+
+`data.events` is available on every `lore` subType. Each entry's `kind`, `depth`, `summary`, `sources`, `standing`, `accounts`, `who`, `where`, `unresolved`, `follows` and `names` hold its chronicle detail; their shapes belong to whatever design governs chronicle records, and this format only asks that they sit inside an entry. The shared format checks `when`, `until` and `recurs`; a content package can check the rest. `events` itself does not appear as an infobox row, but a recurring entry's computed next occurrence does.
+
+An entry reads by what it authors beside `when`:
+
+| authored                          | reads as                                        |
+| --------------------------------- | ----------------------------------------------- |
+| `when`                            | happened once                                   |
+| `when` + `until`                  | ran continuously from then to then              |
+| `when` + `recurs`                 | happened then and happens still                 |
+| `when` + `until` + `recurs.every` | happened then, again on the period, and stopped |
+
+`recurs.every` and `recurs.on` are exclusive — a period with named exceptions is written as an enumeration instead. `recurs` is refused beside `born` or `died`, and beside a `when` of year `0`. `until` is refused beside `recurs.on`, whose own last entry already bounds it.
+
+**The period advances the canonical year, never the era-relative year.** There is no year `0` in era-relative numbering — era year `-1` sits immediately before era year `1` — but canonical year `0` is an ordinary integer on the continuous axis `canonicalYear` builds, so a period of whole years steps on it with no special case at an epoch crossing. Precision and approximation carry through untouched: a year-precision anchor yields year-precision occurrences, an approximate anchor's occurrences are approximate too, and an anchor inside a short intercalary month recurs on that same day in every occurrence, with no special case for the month being short. Each occurrence selects its own era by testing its position against the anchor's calendar, so a later occurrence may print in a different era than its anchor, or print bare where no count was proclaimed for that year — neither is ever a finding, since nobody authored the occurrence.
+
+**Year `0` means any year.** An entry whose `when` states year `0` recurs on that day of every year — `when: "0.5"` is the fifth day of the year, in every year. The value must be quoted, for the reason every canonical date stating a day must be: an unquoted `<year>.<day>` reaches the check as a float, and a day's trailing zero is lost before a date is read. Beside a year-`0` entry, `recurs` is refused (the entry is already annual), `until` is allowed and bounds the series, and the entry carries no `canonicalYear`, era or `sort` — it cannot date its own note. A note's date is its first entry stating a real year.
+
+```yaml
+data:
+  events:
+    - when: 412.1
+      recurs: { every: 1 }
+    - when: "0.286"
+      until: 940.1
+```
+
+The first entry is an anniversary counted from canonical day `412.1`, recurring every year with no end. The second is an autumn rite — the two-hundred-eighty-sixth day of every year — that was kept until canonical year 940 and no longer is.
 
 #### Calendar note structure
 

package/docs/reference/note-types.md

@@ -32,14 +32,14 @@ These are the only keys a note writes at its top level, in the order the formatt
 
 These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.
 
-| Field             | Shape                                           | Meaning                                                                   |
-| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
-| `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.        |
-| `data.pack`       | string                                          | The shared compendium route, with a system block overriding it.           |
-| `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it.  |
-| `data.harnworld`  | map                                             | HârnWorld source details shared by every system.                          |
-| `data.icon`       | an Address                                      | The document's profile art — an `icon` address, resolved into `img`.      |
-| `data.banner`     | an Address                                      | The page's hero image — an `image` address. Reaches no compiled document. |
+| Field             | Shape                                           | Meaning                                                                                    |
+| ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.                         |
+| `data.pack`       | string                                          | The shared compendium route, with a system block overriding it.                            |
+| `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it.                   |
+| `data.harnworld`  | map                                             | HârnWorld source details shared by every system.                                           |
+| `data.icon`       | an Address                                      | The document's profile art — an `icon` address, resolved into `img`.                       |
+| `data.banner`     | an Address                                      | The page's hero image — an `image` address, cut to 1792×768. Reaches no compiled document. |
 
 ## Type-specific fields
 
@@ -432,7 +432,7 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.namedDays` | list of `{ name, abbreviation?, day }`                                              | Names assigned to particular days of the year.                                                                                       |
 | `data.eras`      | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months.                                                 |
 | `data.formats`   | map of named Calendaria format strings                                              | Named patterns for reading and writing this calendar's dates.                                                                        |
-| `data.event`     | event metadata map                                                                  | A dated occurrence and its relationships to other events and places.                                                                 |
+| `data.events`    | list of `{ when, until?, recurs? }`                                                 | This note's dated occurrences — a founding once, an anniversary that recurs, or a list of recorded happenings.                       |
 
 ### map
 

package/engine/anchors.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The anchors a note declares on headings and captioned blocks.
+ * The anchors a note declares on headings and figure fences.
  *
  * **A leaf, deliberately.** This is asked by the link checker, by the content
  * index, and by the builds that emit a link, and they cannot all import one
@@ -29,23 +29,28 @@
  * @module
  */
 
-import { scanCaptions } from "./content-captions.mjs";
+import { scanFigures } from "./content-figures.mjs";
 import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
- * The `{#slug}` and `:::caption {#slug}` anchors a note declares.
+ * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
  *
- * A bare `#` heading starts a journal page without declaring a slug. Captioned
- * blocks declare a slug and start an addressable journal page.
+ * A bare `#` heading starts a journal page without declaring a slug, and so
+ * does a figure fence that declares no id. A fence that declares one declares a
+ * slug and starts an addressable journal page.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
  *   `parseMarkdownFile`. Anchors are reported at their position in the **file**,
  *   so an editor can jump straight to one; passing nothing numbers from the body.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{slug: string, name: string, level: number, line: number}>}
  *   In document order.
  */
-export function collectAnchors(body, bodyLine = 1) {
+export function collectAnchors(body, bodyLine = 1, resolveRole) {
     const anchors = [];
     let inCodeBlock = false;
     const lines = String(body ?? "").split("\n");
@@ -70,12 +75,13 @@ export function collectAnchors(body, bodyLine = 1) {
             line: bodyLine + i,
         });
     }
-    for (const caption of scanCaptions(body).captions) {
+    for (const figure of scanFigures(body, { resolveRole }).figures) {
+        if (!figure.id) continue;
         anchors.push({
-            slug: caption.id,
-            name: caption.label,
+            slug: figure.id,
+            name: figure.label,
             level: 1,
-            line: bodyLine + caption.line - 1,
+            line: bodyLine + figure.line - 1,
         });
     }
     return anchors.sort((a, b) => a.line - b.line);