@heroiclands/package-build 22.26.0 → 22.27.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @heroiclands/package-build
 
+## 22.27.0
+
+### Minor Changes
+
+- Governing bodies list the places they govern from each place’s stated government, keeping those lists consistent with place descriptions.
+- Tables that listed governing bodies through affiliation territory lists must query each place’s government instead.
+- Captions now precede the item they describe; use `:@` for numbered captions or `:` for captions without numbers.
+- Write poetry in a `poetry` code fence, and use attributed divs and inline spans to group or style text.
+- Replace former figure wrappers with leading captions; the old figure and poetry div fences are no longer supported.
+- Blockquote alerts provide note, tip, important and warning callouts; the former info and warn div fences are removed.
+
 ## 22.26.0
 
 ### Minor Changes

package/README.md

@@ -46,6 +46,8 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Error locations and severities                    | [Diagnostics](docs/diagnostics.md)                           |
 | Architectural rationale                           | [Design](docs/design.md)                                     |
 
-Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](docs/authoring/frontmatter.md#place-governments).
+Place notes may declare a governing affiliation with `data.government` (`Address`, default target type `affiliation`), or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](docs/authoring/frontmatter.md#place-governments) and [government migration](docs/guides/government-migration.md).
+
+Leading captions, generic fenced divs, inline spans, and poetry code fences are described in [links and markup](docs/authoring/links-and-markup.md).
 
 The package is GPL-3.0-or-later for code and CC-BY-SA-4.0 for original content. See [LICENSE.md](LICENSE.md).

package/assets/styles/content-base.css

@@ -152,9 +152,8 @@
 }
 
 /*
- * Named body blocks. `:::info` and `:::warn` emit a `<section>` carrying the
- * block's name as its class, so the appearance belongs here rather than in an
- * inline `style` a consumer cannot override.
+ * Historical info/warn section classes remain available for styled prose.
+ * New alerts use the separate alert classes below.
  *
  * `secret` is deliberately absent: Foundry styles `section.secret` itself and
  * owns the reveal control on it, and a rule here would fight both.
@@ -205,3 +204,47 @@
         --pb-block-edge: #7a5100;
     }
 }
+
+/* Alerts share ordinary body colors, with an accent on their edge and title. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert {
+    border-inline-start: 0.25rem solid var(--pb-alert-color);
+    padding: 0.5rem 1rem;
+    margin: 1rem 0;
+    color: inherit;
+    background: transparent;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    margin: 0 0 0.5rem;
+    font-weight: 600;
+    color: var(--pb-alert-color);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-icon {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+    fill: currentColor;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .alert
+    > :last-child {
+    margin-bottom: 0;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-note {
+    --pb-alert-color: #0969da;
+    --pb-alert-color: light-dark(#0969da, #4493f8);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-tip {
+    --pb-alert-color: #1a7f37;
+    --pb-alert-color: light-dark(#1a7f37, #3fb950);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-important {
+    --pb-alert-color: #8250df;
+    --pb-alert-color: light-dark(#8250df, #ab7df8);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-warning {
+    --pb-alert-color: #9a6700;
+    --pb-alert-color: light-dark(#9a6700, #d29922);
+}

package/docs/api.md

@@ -372,6 +372,7 @@ An addressed content note accepts exactly these top-level keys, in this order: `
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
 | `assertVocabularyCharset` | `assertVocabularyCharset(vocabulary, where)` | throws                                   | refusing a vocabulary declaration whose type or subType breaks the address charset           |
+| `isLegacyDataField`       | `isLegacyDataField(type, key)`               | `boolean`                                | testing accepted but ignored transitional affiliation `data.domains` input                   |
 | `dataFields`              | `dataFields(type, vocabulary)`               | `readonly DataFieldSpec[] \| undefined`  | looking up the `data:` keys a note type may carry                                            |
 | `subTypes`                | `subTypes(type, vocabulary)`                 | `readonly string[] \| null \| undefined` | looking up the closed `subType` values a note type declares                                  |
 
@@ -497,22 +498,24 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 
 ### `engine.holdings`
 
-What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the population-based government advisory `package-build lint` runs on a place.
+What lies within a place and which affiliation explicitly governs it — read off `data.parents` and resolved explicit `data.government` across this package and every fetched index, inverted into the `contains`, `governed_by` and `governed_places` lists the site build writes — and the population-based government advisory `package-build lint` runs on a place.
 
-| Export                 | Signature                            | Returns                 | Use it when                                                                                                                 |
-| ---------------------- | ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                | `readonly string[]`     | the three derived keys — `contains`, `held_by`, `holdings` — which a note cannot author                                     |
-| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                | `readonly string[]`     | deprecated historical tenure subtypes; government checks apply to every place subtype                                       |
-| `holdingsNode`         | `holdingsNode(fm, { title, url })`   | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation              |
-| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)` | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                  |
-| `holdingsPages`        | `holdingsPages(nodes)`               | `Map<string, Holdings>` | inverting `parents` and `domains` into each page's sorted lists, keyed by URL, for every page with at least one entry       |
-| `shortcodesOf`         | `shortcodesOf(value)`                | `string[]`              | the shortcodes a `parents` or `domains` value names — bare, addressed or wikilinked — empties dropped and repeats collapsed |
-| `checkGovernment`      | `checkGovernment(note)`              | `object[]`              | warning at `data.population` for positive population with no own `data.government` key; explicit null means anarchy         |
-| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | deprecated compatibility wrapper for `checkGovernment`; holdings do not determine government                                |
+| Export                 | Signature                                           | Returns                 | Use it when                                                                                                                                |
+| ---------------------- | --------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                               | `readonly string[]`     | derived `contains`, `governed_by`, `governed_places` and retired `held_by`/`holdings` keys removed from authored page metadata             |
+| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                               | `readonly string[]`     | deprecated historical tenure subtypes; government checks apply to every place subtype                                                      |
+| `holdingsNode`         | `holdingsNode(fm, { title, url, package, system })` | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation                             |
+| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)`                | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                                 |
+| `holdingsPages`        | `holdingsPages(nodes, { governmentNodes })`         | `Map<string, Holdings>` | inverting `parents` and resolved explicit `government` into each page's sorted lists, keyed by URL, for every page with at least one entry |
+| `shortcodesOf`         | `shortcodesOf(value)`                               | `string[]`              | the shortcodes a `parents` value names — bare or qualified Addresses — empties dropped and repeats collapsed                               |
+| `checkGovernment`      | `checkGovernment(note)`                             | `object[]`              | warning at `data.population` for positive population with no own `data.government` key; explicit null means anarchy                        |
+| `checkHeld`            | `checkHeld(note, { index })`                        | `object[]`              | deprecated compatibility wrapper for `checkGovernment`; holdings do not determine government                                               |
+
+Government-only supplemental records passed in `holdingsPages` options include public local stubs in the reverse lists without adding them to the geographical graph. Published nodes retain precedence; stubs without URLs render as plain text.
 
 ### `engine.populations`
 
-Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `package-build lint` runs all four as warnings.
+Whether a world's population figures agree from the region down — the regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `package-build lint` runs all three as warnings.
 
 | Export                  | Signature                                | Returns                | Use it when                                                                                                  |
 | ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -700,7 +703,7 @@ invokes the check during frontmatter lint.
 
 ### `engine.markdownExpressions`
 
-`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.
+`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 captioned item 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                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -1964,3 +1967,20 @@ The Changesets changelog generator, loaded with `require` — a CommonJS module
 ## `./package.json`
 
 Not a JavaScript module — this subpath entry exists so tooling (bundlers, `import.meta.resolve`, a script reading the installed version) can resolve the package's own `package.json` through Node's package-exports resolution instead of reaching outside the declared export map.
+
+## Markup parsing modules
+
+The engine wildcard subpath also exposes the body parsers below. Historical figure API names now operate on leading captions; `:::figure` is removed.
+
+| Module                       | Exports                                                                                      | Contract                                                                                                                                                                                                                               |
+| ---------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`       | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
+| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`    | Read div and secret fences; info/warn names are retired; generic div records have `name: "div"` and no generated title. Scanning includes poetry errors.                                                                               |
+| `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
+| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans and located errors; the renderer preserves inline Markdown in attributed HTML spans.                                                                             |
+
+`scanFigures` retains `line` (1-based caption line), `bodyStart`/`bodyEnd` (0-based, exclusive-end target range), and `close` (last consumed target line), plus caption attributes, kind, label and number. Unnumbered captions have an empty label and consume no number. `collectAnchors` discovers heading, caption, div, poem and span identifiers; `markupAnchorFindings(body)` reports collisions involving non-page identifiers; Foundry maps non-page anchors to the actual containing page UUID. An unnumbered `ref` requires `form="title"` or `form="full"`.
+
+`engine/content-alerts.mjs` exposes `ALERT_TYPES`, `scanAlerts(source)` and `renderAlerts(source, target)` and `alertMarkdownPlugin(md)`. The scanner returns `{blocks, errors}`; alert records carry `type`, `id`, `classes`, `attributes`, `title`, `body` and inclusive zero-based `start`/`end` source lines. The renderer produces attributed `aside.alert` wrappers while leaving alert body Markdown in the document's scope. Alert validation and anchor discovery run in site, Foundry and book pipelines.
+
+Alert `title` is the displayed heading override; absent, it defaults to the label in `ALERT_TYPES`. It does not change the alert type’s icon or color.

package/docs/authoring/frontmatter.md

@@ -41,7 +41,7 @@ One body describes the subject for both systems. A being's `{#appearance}` and `
 
 ## Place governments
 
-A place may state its governing affiliation in `data.government`. Use an affiliation Address, either a local shortcode or a fully qualified Address from this package or a fetched dependency:
+A place may state its governing affiliation in `data.government`. The field type is `Address`, with `affiliation` as the default target type when the type is omitted. Use either a local shortcode or a fully qualified affiliation Address from this package or a fetched dependency:
 
 ```yaml
 data:
@@ -58,7 +58,7 @@ Write `government: null` for **complete anarchy**. Omitting the key leaves gover
 | Any                   | Explicit `null`     | None; complete anarchy           |
 | Any                   | Affiliation Address | None; the reference must resolve |
 
-These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. Holdings remain tenure facts; the former unconditional “unheld land” warning is retired.
+These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. The generated `governed_by` and `governed_places` lists use only explicit government references. Legacy affiliation `data.domains` is accepted temporarily but ignored; record any distinct ownership or influence in prose. See [government migration](../guides/government-migration.md).
 
 ## Publication and summaries
 

package/docs/authoring/links-and-markup.md

@@ -37,7 +37,7 @@ The harbor faces west.
 Travelers present their papers here. See [[#harbor|the harbor]].
 ```
 
-A `:::figure` fence starts a JournalEntryPage too, in Foundry alone — the web and the book keep the fence in the flow of the page around it. A fence holding exactly one picture, captioned with plain text and nothing else, becomes a page of type `image`: the picture is its `src`, the caption is `image.caption`, and the page is named for the figure's own number, such as "Figure 3". A fence carrying no caption still takes the `image` type when it holds one picture, named the same way. Every other fence takes a page of type `text` instead — a grouped fence holding more than one picture, an audio embed, a fence whose caption carries emphasis, an icon, or a link, and a fence that shares its page with trailing prose before the next heading or fence.
+A leading caption starts a captioned-item JournalEntryPage in Foundry. A solitary image with a plain caption can be an image page; other captioned items become text pages. Websites and books keep captioned items in the surrounding flow.
 
 The prose introducing a fence and the fence itself land on two different Foundry pages, so a reference such as `{{ref "#trade"}}` written just above a fence sends a Foundry reader to a different page than the one carrying the sentence. Give the introducing prose its own heading, or accept that following the reference leaves the page, before relying on a fence to sit inside a longer page's flow.
 
@@ -63,178 +63,130 @@ A `:::secret` block inside the section is legal and renders as it does anywhere
 
 The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
-## Figures and numbered references
+## Captions and numbered references
 
-A `:::figure` fence numbers whatever it holds and, written with an id, makes it a target `{{ref}}` can point to:
+Write a caption on its own line **before** the item it describes, with a blank line before and after the caption. `:` produces an unnumbered caption; `:@` produces a numbered caption. One or more spaces separate the marker from its text. An optional attribute block at the end accepts an identifier, classes and named attributes:
 
-````markdown
-:::figure {#trade}
-
-```sql
-SELECT name.full AS "Market" FROM notes WHERE type = 'place'
-```
+```markdown
+:@ Regional trade routes {#trade .border type=table}
 
-///
-Regional trade routes
-:::
+| Route | Days |
+| ----- | ---- |
+| North | 4    |
 
 Refer to {{ref "#trade"}} for the market routes.
-````
+```
 
-The fence displays **Table 1: Regional trade routes**, and `{{ref "#trade"}}` displays **Table 1** as a link. **A figure is numbered because it is a fence, not because it carries caption text** — an ordinary table or picture written outside any fence is numbered not at all.
+This displays **Table 1: Regional trade routes**; the reference links to **Table 1**. An unnumbered `: Regional trade routes {#trade}` displays only its text, has an anchor, and does not consume a number. An item with no caption remains unnumbered.
 
-**The construct is `:::figure`**, with an optional `{#id .border}` attribute block, closed by `:::`. Everything between the opening line and the closing `:::` is the captioned thing.
+The caption attaches to exactly the next supported block:
 
-**The first `///` at the top level of the fence separates the captioned thing from its caption.** A second `///` at the top level is an error — a figure holds one caption. A `///` written inside a nested code fence is content, not a separator, so a captioned code listing can carry `///` as a comment of its own.
+| Next item                            | Inferred type | Numbered label |
+| ------------------------------------ | ------------- | -------------- |
+| Markdown table                       | `table`       | Table          |
+| Image, Markdown or wikilink          | `figure`      | Figure         |
+| SQL fence, including backtick SQL    | `table`       | Table          |
+| Poetry fence                         | `poetry`      | Poem           |
+| Any other code fence                 | `code`        | Code           |
+| Paragraph, quote block or fenced div | `prose`       | Prose          |
 
-**The caption is optional.** A fence with no `///` draws its label alone, with nothing under it. So the counter and the label come from the fence itself, whether or not an author writes a caption.
+The optional `type` attribute overrides inference and accepts `figure`, `table`, `poetry`, `code`, `prose`, and `example`. `type=example` uses **Example 1**, **Example 2**, and so on. It does not allow an unsupported target. A heading, list, thematic break, another caption or end of document after a caption is an error. Caption markers without separating spaces or caption text are errors too.
 
-**`{#id}` is optional too.** A fence that declares none is still numbered and drawn; it carries no anchor, so nothing can refer to it. Give a figure an id only when prose needs to point at it.
+Identifiers are optional and must be unique within the note. Classes are unrestricted; `.border` uses the shared border style, while other classes can be styled by the medium. Named attributes use `key=value`, with quoted values for text containing spaces. Use `#id` and `.class` rather than `id=` and `class=`; event-handler attributes are refused.
 
-**`.border` draws the figure and its label inside a border.** It is the only class the construct accepts — any other class, such as `.wide`, is an error naming the class. `key="value"` is refused outright: a figure takes an id and classes, nothing else.
+Each numbered type has its own counter. Websites and Foundry number within a note; books number across their reading order. Unnumbered captions neither display nor consume a number. A map image can retain its asset-derived **Map** classification when no type is specified.
 
-**The counter is derived from the fence's contents, never authored.** A table is a table; an `sql` fence is a table, because its rendered output is one; any other fence or code block is code; pictures alone, one or several, are a figure; a `:::poetry` fence written first makes it a poem; everything else is prose. A fence around prose with `.border` is a numbered, referable boxed aside — the `Prose` counter's whole purpose. The counters are `Code`, `Table`, `Figure`, `Map`, `Poem`, and `Prose`. The website and a Foundry journal number each counter within the note; a book numbers each counter across the book in reading order.
+`{{ref "#trade"}}` displays the numbered label as a link. `form="full"` includes caption text and `form="title"` displays the caption alone. Use title form for an unnumbered caption. Cross-note references can name the note address before the anchor, such as `{{ref "place-harbor#trade"}}`; the displayed number belongs to the target on the surface rendering it. Links inside caption text contribute their visible text to references, so the reference does not contain a nested link.
 
-**A picture counts as `Map` instead of `Figure` when the asset it draws declares `role: map`** in its provenance — see [the asset provenance reference](../reference/format-details.md). The fence's own markup cannot say so; a picture of a map looks like any other picture, so the fact rides entirely on the asset's own record. A fence grouping several pictures counts as `Map` only when every one of them declares the role; one picture without it keeps the whole fence a `Figure`.
+Foundry gives a captioned item its own JournalEntryPage. A solitary image with a plain caption can use an image page; captions with inline markup and other items use text pages. On the website and in the book the item stays in the flow of the surrounding page.
 
-**A reference is written `{{ref "#thorn"}}`**, rendering as a link reading "Figure 13". `form="full"` renders the number and the caption; `form="title"` renders the caption alone; `form="number"` is the default, and may be written explicitly. A link written inside the caption contributes only its label text to a `full` or `title` reference, because the reference is itself a link and an anchor cannot nest inside another.
+**Migration:** `:::figure` is no longer supported. Move the former `///` caption before the item as `:@ Caption {#id}` and remove the figure wrapper. To caption a group or passage, put it inside a generic fenced div and caption that div with an explicit type if needed. `///` is no longer a caption delimiter.
 
-**A reference may name another note's figure**, writing the note's address before the anchor: `{{ref "place-thornford#trade"}}` points at the figure `#trade` in `place-thornford`. It renders the number that figure carries **on the surface doing the rendering** — its own count within `place-thornford` on the website and in a Foundry journal, and its place in the book's reading order in the book, which may differ from the number it carries on its own page. An anchor matching no figure in the addressed note is refused, and so is an address naming no note at all.
+## Images and protected content
 
-In a Foundry journal, a reference resolves to the figure's own JournalEntryPage — the `image` page a solitary, plainly captioned picture becomes, or the `text` page any other fence becomes — addressed exactly as an authored `[[#anchor|Text]]` link to the same anchor would be. A reference naming another note's figure is not resolved there: a journal addresses a page by UUID, and has none for a note outside the one compiling.
+An image or icon embed stands on its own line; one that does not is a lint error naming the line, because a width or a position means nothing applied to a word in the middle of a sentence. `size` accepts `auto`, `small`, `medium`, `large`, `xlarge` and `full-width`; the medium maps those names to suitable dimensions, and `full-width` is the full page in the book and the full content width elsewhere. `float` controls placement and takes `top-left`, `top-right`, `bottom-left`, `bottom-right` or `center`; on a page a float occupies the column measure, so only the vertical half of a corner position has an effect there. The asset remains an Address, so moving the file within its asset root does not change the link. See [assets](assets.md) and [image directives](../reference/format-details.md#images).
 
-**A figure needs contents and a closing `:::`.** Its id, when one is given, must be unique in the note; its caption, when one is given, is the one `///` section the fence carries.
+### Fenced divs
 
-A few worked examples. A captioned picture:
+A bare `:::` opens a div section. An optional attribute block applies to the whole fenced area. A bare `:::` closes the section:
 
 ```markdown
-:::figure {#thorn}
-![[being-foobar|The Great Beast]]
-///
-The great beast, as drawn by [[person-havard|Havard]].
-:::
-```
-
-This draws **Figure 1**, labelled "Figure 1: The great beast, as drawn by Havard." beneath the picture.
+::: {#harbor-note .border lang=en}
+The harbor remains open through winter.
 
-A grouped fence holding two pictures as one figure — a plate rather than two separate plates:
-
-```markdown
-:::figure {#passes}
-![[image-northpass|Northern approach]]
-![[image-southpass|Southern approach]]
-///
-The two approaches to the pass.
+A second paragraph belongs to the same div.
 :::
 ```
 
-Both pictures draw together under one label, **Figure 2**, because the fence is the unit the counter numbers — not the pictures inside it.
+An attribute-bearing opener allows a nested div to be distinguished from the bare closer. Divs carry no automatic title or number; style their classes for the medium. Use a leading caption to caption the entire div. The same attribute grammar is available on named blocks; identifiers, classes and named attributes belong to the entire section. Headings that would start a Foundry journal page cannot split a fenced section.
 
-A fence with no caption:
+### Inline spans
+
+`[inline content]` represents a span. Follow it immediately with an optional attribute block to apply an identifier, classes and named attributes:
 
 ```markdown
-:::figure {#anvil}
-![[icon-anvil|A worn anvil]]
-:::
+The watch wears [a _blue_ sash]{#watch-sash .uniform lang=en}.
 ```
 
-This draws **Figure 3**, with no caption line beneath it, and still carries the anchor `#anvil`.
+Inline Markdown remains active inside the span. Bracket spans have lower priority than URL links, image links, reference links, footnotes and wikilinks. A bracketed form immediately preceded by `!`, followed by `(` or another `[`, or beginning with `[[` is not a span, even when the link is unresolved. Ordinary links retain their existing syntax. Escape a bracket when it should be literal, or put examples inside a code span or fence. A span identifier addresses that point in the note; it does not start a journal page.
 
-A reference in running prose:
+### Alerts
+
+Alerts replace the former `:::info` and `:::warn` fences. Start with a special blockquote marker, optionally followed by an attribute block, then write the alert body as a standard blockquote:
 
 ```markdown
-See {{ref "#thorn"}} for the plate, or {{ref "#thorn" form="full"}} for the full description.
-```
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
 
-This displays as "See [Figure 1](#thorn) for the plate, or [Figure 1: The great beast, as drawn by Havard.](#thorn) for the full description," each bracketed phrase a link to the figure.
+> [!TIP]
+> Helpful advice for doing things better or more easily.
 
-A reference to a figure in another note:
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
 
-```markdown
-The market routes are drawn in {{ref "place-thornford#trade"}}.
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
 ```
 
-On the website this links into `place-thornford`'s own page, reading "Table 1" — the number that fence carries there, whatever number it carries in the book or in a note of its own.
-
-## Images and protected content
-
-An image or icon embed stands on its own line; one that does not is a lint error naming the line, because a width or a position means nothing applied to a word in the middle of a sentence. `size` accepts `auto`, `small`, `medium`, `large`, `xlarge` and `full-width`; the medium maps those names to suitable dimensions, and `full-width` is the full page in the book and the full content width elsewhere. `float` controls placement and takes `top-left`, `top-right`, `bottom-left`, `bottom-right` or `center`; on a page a float occupies the column measure, so only the vertical half of a corner position has an effect there. The asset remains an Address, so moving the file within its asset root does not change the link. See [assets](assets.md) and [image directives](../reference/format-details.md#images).
+| Marker         | Label     | Appearance                                        |
+| -------------- | --------- | ------------------------------------------------- |
+| `[!NOTE]`      | Note      | Blue rule and `fa-regular fa-message`             |
+| `[!TIP]`       | Tip       | Green rule and `fa-regular fa-lightbulb`          |
+| `[!IMPORTANT]` | Important | Purple rule and `fa-solid fa-circle-info`         |
+| `[!WARNING]`   | Warning   | Amber rule and `fa-solid fa-triangle-exclamation` |
 
-### Named blocks
+The label and icon sit above the body. Alerts are visible callouts, not expandable sections. Inline Markdown, links, multiple paragraphs, lists and code examples remain available inside the quote. Prefix blank lines within the body with `>` to keep paragraphs in the same alert.
 
-Three named blocks set a passage apart from the prose around it. `:::secret`
-marks GM material, `:::info` a neutral note, and `:::warn` a caution:
+Attributes follow the marker and apply to the alert:
 
 ```markdown
-:::warn
-The bridge closes during the spring flood.
-:::
+> [!WARNING] {#flood-warning .seasonal lang=en title="Seasonal closure"}
+> The eastern road closes during spring floods.
+>
+> Use the ridge path instead.
 ```
 
-Each heads itself with its own name — **Secret**, **Info**, **Warn** — and takes
-a closing `:::`. Poetry has its own fence below; other names are reported.
+Use `#id`, `.class` and named attributes in the shared braced grammar. The marker determines the default label, icon and color. An authored `title` replaces the default **Note**, **Tip**, **Important** or **Warning** heading while preserving the alert type’s icon and color. Event-handler attributes, malformed attributes, unknown alert types and empty alert bodies are errors. Ordinary blockquotes and alert examples inside literal code remain unchanged. A leading caption can describe an alert as a quote block, normally with the `prose` type or an explicit `example` type.
+
+Migrate former info blocks to `[!NOTE]` alerts and warn blocks to `[!WARNING]` alerts. The old named fences are errors. `:::secret` remains supported.
 
-**A GM-only section holds a box.** A `:::secret` is a container for whatever the
-GM reads, boxes included, and a box written inside one stays inside it. A box
-holds no named block of its own, so a second box inside a box is reported. A
-`:::figure` fence may be written inside any of them. The two draw a box for
-different reasons: a named block says what kind of aside a passage is, while a
-`:::figure` fence makes a passage numbered and referable — nesting one inside
-the other gives a passage both.
+### Secret blocks
 
-**An attribute block follows the name.** It is the same braced grammar the other
-body extensions use, so it carries an id, classes, and any attribute the element
-should have. `title` is reserved and supplies the heading in place of the default:
+`:::secret` sets GM material apart. Its optional attributes accept an identifier, classes and named attributes. `title` supplies its heading; without a title the heading is **Secret**:
 
 ```markdown
-:::secret {#harbor title="For the GM" .wide data-stage="two"}
+:::secret {#harbor-secret title="For the GM"}
 The harbor master is working for the smugglers.
 :::
 ```
 
-That block carries the classes `secret wide`, the id `harbor`, and
-`data-stage="two"`, and it heads **For the GM**. A title carries emphasis of its
-own — `title="The *Genzet* only"` — and nothing else: a tag written there is
-shown rather than obeyed. Set the id with `#id` and classes with `.class` rather
-than through an `id=` or `class=` key, and note that an event handler such as
-`onclick=` is refused rather than written.
-
-**The name is the first class on the element, and the appearance belongs to a
-stylesheet.** No block is emitted with an inline `style`, so a package restyles
-one from its own sheet. `info` and `warn` are styled by the base stylesheet;
-`secret` is left to Foundry, which styles `section.secret` itself and owns the
-reveal control on it.
-
-Each surface renders the same block its own way:
-
-| Surface | Output                                                                             |
-| ------- | ---------------------------------------------------------------------------------- |
-| Foundry | `<section class="secret" id="harbor">` with the title as its first line            |
-| Web     | `<details class="secret" id="harbor">` the reader opens, titled in its `<summary>` |
-| Book    | a coloured print box headed by the title                                           |
-
-A `secret` with no id of its own is given one derived from its body on the
-Foundry surface, because Foundry remembers a revealed section by its id.
-
-**A secret is a presentation distinction, not access control.** Players who
-deliberately inspect source or generated output may see it. The
-[detailed reference](../reference/format-details.md#what-a-note-produces)
-describes each medium's handling.
-
-**One malformed block does not silence the others.** A block whose attributes do
-not parse is reported at its own line and left as written; every well-formed
-block in the same note still renders.
-
-**A heading that would start its own journal page cannot be written inside a
-block, or inside a `:::figure` fence.** An H1, or a heading of any level
-carrying an `{#anchor}`, is reported at its own line there — starting a page
-would tear the block or the figure in two, and a reader could open the second
-half with none of the box around it. A lower heading with no anchor is
-unaffected and is the ordinary way to structure a long box.
+A secret block can contain alerts and general divs. It cannot contain another secret block. A heading that starts its own journal page cannot split a secret block or general div; use a lower heading without an anchor within the section.
+
+Foundry renders a secret section; the website renders an expandable spoiler, and the book renders a labeled box. An untitled secret takes its normal default title, and a Foundry secret without an id receives an id derived from its body. The presentation does not make published HTML private: deliberately inspecting generated source can reveal its content. Use YAML comments for information that must never be published.
 
 ### Poetry
 
-Use `:::poetry` to preserve verse lines and stanzas. Every nonblank source line
+Use a code fence with the language `poetry` to preserve verse lines and stanzas. Every nonblank source line
 is one verse line; blank lines separate stanzas. Inline emphasis, links and
 footnotes work as they do in prose. The fence itself adds no title, caption or
 number.
@@ -263,15 +215,15 @@ render at levels zero and `i1` respectively. This also works when the entire
 fence is indented inside a list item. Poetry is upright by default; use normal
 Markdown emphasis when italics are part of the poem.
 
-```markdown
-:::poetry {form=ballad meter="common meter" rhyme=ABCB syllables="8,6,8,6" lang=en}
+````markdown
+```poetry {form=ballad meter="common meter" rhyme=ABCB syllables="8,6,8,6" lang=en}
 The lantern burns beside the gate,
 The harbor sleeps below.
 
 The keeper guards the road till dawn,
 And keeps a light aglow.
-:::
 ```
+````
 
 The optional `form`, `meter` and `rhyme` attributes record the author's intent;
 the build does not infer stress, rhyme or pronunciation. `syllables` gives a
@@ -281,23 +233,18 @@ spoken. `lang` is a language tag for the rendered HTML. An optional `#id`
 addresses the poem itself. There are no `title` or `lines` attributes, and no
 special punctuation for stress, pauses or refrains.
 
-To number and caption a poem, put it first inside a `:::figure`:
+To number and caption a poem, put a leading numbered caption before the poetry fence:
 
-```markdown
-:::figure {#watch-song}
-:::poetry {form=ballad}
+````markdown
+:@ A song sung by the harbor watch. {#watch-song}
+
+```poetry {form=ballad}
 The watch has gone to sea,
 The lantern marks the shore.
-:::
-///
-A song sung by the harbor watch.
-:::
 ```
+````
 
-The inner `:::` closes the poem; the outer one closes the figure. That figure
-uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. The
-caption after `///` belongs to the figure. A poem outside a figure is
-unnumbered. Prose written before the poem makes the figure a **Prose** figure.
+This uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. Use `:` for a caption without a number. `:::poetry` is no longer supported.
 
 ## Footnotes and definition lists
 
@@ -471,21 +418,21 @@ There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} bein
 
 <!-- expression-helpers:start -->
 
-| Helper       | Parameters                                 | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eq`         | `a b`                                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `gt`         | `a b`                                      | True when a is greater than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `gte`        | `a b`                                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `lt`         | `a b`                                      | True when a is less than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `lte`        | `a b`                                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `not`        | `value`                                    | True when the value is false, zero, empty or absent.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `and`        | `value …`                                  | True when every value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `or`         | `value …`                                  | True when any value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `words`      | `number`                                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                                                                                                                                                                                                                                                                                                                               |
-| `digits`     | `number`                                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `sql`        | `"query"`                                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                                                                                                                                                                                                                                                                                                                                          |
-| `dateformat` | `calendar date ["format"]`                 | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern.                                                                                                                                                                                                                                                                                                             |
-| `ref`        | `address [form="number"\|"full"\|"title"]` | A link to a `:::figure` fence, by its anchor — `"#thorn"` on this note, `"note-address#thorn"` on another. `form` is `number` (the default, and admitted explicitly), rendering "Figure 13"; `full`, the number and the caption; or `title`, the caption alone. Always renders as a link to the figure, and a link inside the caption contributes only its label text. The number rendered is the one the figure carries on the surface doing the rendering, whichever note names it. |
+| Helper       | Parameters                                 | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eq`         | `a b`                                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `gt`         | `a b`                                      | True when a is greater than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `gte`        | `a b`                                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `lt`         | `a b`                                      | True when a is less than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `lte`        | `a b`                                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `not`        | `value`                                    | True when the value is false, zero, empty or absent.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `and`        | `value …`                                  | True when every value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `or`         | `value …`                                  | True when any value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `words`      | `number`                                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                                                                                                                                                                                                                                                                                                                            |
+| `digits`     | `number`                                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `sql`        | `"query"`                                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                                                                                                                                                                                                                                                                                                                                       |
+| `dateformat` | `calendar date ["format"]`                 | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern.                                                                                                                                                                                                                                                                                                          |
+| `ref`        | `address [form="number"\|"full"\|"title"]` | A link to a captioned item, by its anchor — `"#thorn"` on this note, `"note-address#thorn"` on another. `form` is `number` (the default, and admitted explicitly), rendering "Figure 13"; `full`, the number and the caption; or `title`, the caption alone. Always renders as a link to the figure, and a link inside the caption contributes only its label text. The number rendered is the one the figure carries on the surface doing the rendering, whichever note names it. |
 
 <!-- expression-helpers:end -->