@heroiclands/package-build 22.25.0 → 22.27.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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
+
+Place notes can name their governing affiliation in `data.government`, or state `null` for complete anarchy. A place with positive population and no government now receives an advisory. Places with zero, null or unspecified population no longer receive the old unheld-land warning; holdings remain separate tenure facts. Governments appear in note infoboxes and persist in published metadata.
+
 ## 22.25.0
 
 ### Minor Changes

package/README.md

@@ -46,4 +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` (`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

@@ -348,6 +348,8 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 ### `engine.noteVocabulary`
 
+`DataFieldSpec.nullText` declares the infobox text for an explicitly authored null. The place `government` field uses “Complete anarchy”; omitted fields remain absent. Its Address targets must be affiliations.
+
 An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `dnd5e`, `hm3`, `sohl`. A key outside this list is an error at its own line. The system blocks are one per system the address vocabulary recognizes, sorted by name after the fixed keys, so a further system is a change to `SYSTEM_IDS` alone. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
 
 | Export                    | Signature                                    | Returns                                  | Use it when                                                                                  |
@@ -370,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                                  |
 
@@ -495,21 +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 tenure check `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[]`     | 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                                               |
 
-| 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[]`     | the place subTypes tenure is checked on — `settlement`, `site`, `structure`                                                  |
-| `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  |
-| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | linting a place's tenure — a settlement, site or structure no affiliation's `domains` names is a warning at its `type:` line |
+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                                                                                                  |
 | ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -697,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                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -1961,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

@@ -39,6 +39,27 @@ A `sohl:`, `hm3:` or `dnd5e:` block holds values for that Foundry system. Its `s
 
 One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.
 
+## Place governments
+
+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:
+  population: 1200
+  government: crown
+```
+
+Write `government: null` for **complete anarchy**. Omitting the key leaves government unspecified. Null is retained in published metadata and displayed as “Complete anarchy” in website, Foundry and book infoboxes; an omitted key has no Government row. A reference displays a link to the governing affiliation.
+
+| Population            | Government          | Governance advisory              |
+| --------------------- | ------------------- | -------------------------------- |
+| Positive              | Omitted             | Warning at `data.population`     |
+| Missing, zero or null | Omitted             | None                             |
+| 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. 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
 
 A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; the book places boxes after the authored body, Foundry appends one page per box, and the website places boxes in its responsive side rail. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.