@heroiclands/package-build 22.24.0 → 22.25.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 22.25.0
+
+### Minor Changes
+
+Write poems in a `:::poetry` fence to preserve verse lines, relative indentation, and stanza breaks across journals, websites, and books. A poem placed first in a `:::figure` uses the Poem counter and may carry a caption and reference.
+
+The bundled Hugo theme's image-role and banner guards now run as part of package-build lint. Affiliation notes must declare a `data.governance.ranks` rung at level 1; a missing ordinary standing now produces a located error.
+
 ## 22.24.0
 
 ### Minor Changes

package/assets/styles/content-base.css

@@ -106,6 +106,51 @@
     }
 }
 
+/* Each verse line breaks in the markup; each paragraph is a stanza. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry {
+    margin: 1.5rem 0;
+    line-height: 1.7;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry p {
+    margin: 0;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry p + p {
+    margin-top: 1em;
+}
+
+.poetry .poetry-line {
+    display: inline-block;
+    margin-inline-start: var(--poetry-indent, 0em);
+    white-space: pre-wrap;
+}
+
+.poetry .poetry-line.i1 {
+    --poetry-indent: 1.25em;
+}
+.poetry .poetry-line.i2 {
+    --poetry-indent: 2.5em;
+}
+.poetry .poetry-line.i3 {
+    --poetry-indent: 3.75em;
+}
+.poetry .poetry-line.i4 {
+    --poetry-indent: 5em;
+}
+.poetry .poetry-line.i5 {
+    --poetry-indent: 6.25em;
+}
+.poetry .poetry-line.i6 {
+    --poetry-indent: 7.5em;
+}
+.poetry .poetry-line.i7 {
+    --poetry-indent: 8.75em;
+}
+.poetry .poetry-line.i8 {
+    --poetry-indent: 10em;
+}
+
 /*
  * 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

package/ci/check-banners.mjs

@@ -0,0 +1,183 @@
+/*
+ * This file is part of the Heroic Lands shared Hugo theme.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * CI guard: every banner `data/banners.yaml` declares must actually be published.
+ *
+ * `partials/hero-banner.html` needs to know which banner images exist, and Hugo
+ * cannot ask a remote asset host that question at build time — so the answer is
+ * declared in `data/banners.yaml` instead. A declaration nothing
+ * checks is kept in step by hope, and the hole it was written to close reopens
+ * the first time it drifts. It already had: when this check was written, four
+ * names present in a local working copy of the artwork repository were not
+ * published, and three that were published appeared in no local copy at all.
+ *
+ * So this fetches every declared name and fails on any non-200. It is the test
+ * the template cannot make, moved to the one place that can make it.
+ *
+ * Usage:
+ *   node utils/check-banners.mjs [--base <url>] [--concurrency <n>]
+ *
+ * The host defaults to the Heroic Lands CDN and can be pointed anywhere with
+ * `--base` or `BANNER_BASE_URL`, so a consumer publishing its own artwork set
+ * can run the same check against its own `data/banners.yaml`.
+ *
+ * A network failure is reported as a failure rather than skipped: a check that
+ * passes when it could not reach the host is worse than no check at all.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { parse } from "yaml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DATA_FILE = resolve(HERE, "..", "hugo-theme", "data", "banners.yaml");
+const DEFAULT_BASE = "https://cdn.heroiclands.org";
+
+function parseArgs(argv) {
+    const opts = {
+        base: process.env.BANNER_BASE_URL || DEFAULT_BASE,
+        concurrency: 8,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--base") opts.base = argv[(i += 1)];
+        else if (arg === "--concurrency") opts.concurrency = Number(argv[(i += 1)]);
+        else {
+            console.error(`check-banners: unrecognised argument ${arg}`);
+            process.exit(2);
+        }
+    }
+    if (!opts.base) {
+        console.error("check-banners: no asset host; pass --base or set BANNER_BASE_URL");
+        process.exit(2);
+    }
+    if (!Number.isInteger(opts.concurrency) || opts.concurrency < 1) {
+        console.error("check-banners: --concurrency must be a positive integer");
+        process.exit(2);
+    }
+    return opts;
+}
+
+/** Diagnostics carry the fields they can know and drop the ones they cannot. */
+function diag(line, message) {
+    const where = line ? `${DATA_FILE}:${line}` : DATA_FILE;
+    console.error(`${where}: error: ${message}`);
+}
+
+function fail(message, line) {
+    diag(line, message);
+    process.exit(1);
+}
+
+/** Line number of a declared name, so an editor can jump straight to it. */
+function lineOf(source, name) {
+    const index = source
+        .split("\n")
+        .findIndex((l) => l.trim() === `- ${name}` || l.trim() === `- "${name}"`);
+    return index === -1 ? 0 : index + 1;
+}
+
+/** Read and validate the inventory, so a malformed file fails loudly. */
+function readInventory() {
+    const source = readFileSync(DATA_FILE, "utf8");
+    const data = parse(source);
+    const dir = data?.dir;
+    const fallback = data?.fallback;
+    const available = data?.available;
+
+    if (typeof dir !== "string" || !dir) fail("`dir` must be a non-empty string");
+    if (typeof fallback !== "string" || !fallback) fail("`fallback` must be a non-empty string");
+    if (!Array.isArray(available) || available.length === 0)
+        fail("`available` must be a non-empty list");
+    if (available.some((n) => typeof n !== "string" || !n))
+        fail("`available` must hold only non-empty strings");
+
+    const dupes = [...new Set(available.filter((n, i) => available.indexOf(n) !== i))];
+    if (dupes.length) fail(`duplicate names: ${dupes.join(", ")}`, lineOf(source, dupes[0]));
+
+    const unsorted = available.findIndex((n, i) => i > 0 && available[i - 1] > n);
+    if (unsorted !== -1)
+        fail(
+            "`available` must be sorted, so a diff shows what changed",
+            lineOf(source, available[unsorted]),
+        );
+
+    // The fallback is what every unlisted name resolves to, so its absence would
+    // turn one dead URL into every dead URL.
+    const fallbackName = fallback.replace(/\.[^./]+$/, "");
+    if (!available.includes(fallbackName))
+        fail(`the fallback ${fallback} is not itself listed in \`available\``);
+
+    return { source, dir, available };
+}
+
+async function probe(url) {
+    try {
+        // HEAD first — it is what the question actually is. Some object stores
+        // answer 405 to it, so fall back to a ranged GET rather than reporting a
+        // published file as missing.
+        let res = await fetch(url, { method: "HEAD", redirect: "follow" });
+        if (res.status === 405 || res.status === 501) {
+            res = await fetch(url, {
+                headers: { Range: "bytes=0-0" },
+                redirect: "follow",
+            });
+        }
+        return {
+            ok: res.status === 200 || res.status === 206,
+            status: String(res.status),
+        };
+    } catch (err) {
+        return { ok: false, status: `network error: ${err.message}` };
+    }
+}
+
+async function main() {
+    const { base, concurrency } = parseArgs(process.argv.slice(2));
+    const { source, dir, available } = readInventory();
+    const root = `${base.replace(/\/$/, "")}/${dir.replace(/^\//, "")}`;
+
+    const failures = [];
+    const queue = [...available];
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        for (let name = queue.shift(); name !== undefined; name = queue.shift()) {
+            const url = `${root}/${name}.webp`;
+            const { ok, status } = await probe(url);
+            if (!ok) failures.push({ name, url, status });
+        }
+    });
+    await Promise.all(workers);
+
+    if (failures.length) {
+        failures.sort((a, b) => a.name.localeCompare(b.name));
+        for (const { name, url, status } of failures) {
+            diag(
+                lineOf(source, name),
+                `declared banner ${name} is not published (${status}): ${url}`,
+            );
+        }
+        console.error(
+            `check-banners: ${failures.length} of ${available.length} declared banners are missing from ${base}.`,
+        );
+        console.error(
+            "Publish the artwork, or drop the name — an undrawn name here is a 404 on every page that resolves to it.",
+        );
+        process.exit(1);
+    }
+
+    console.log(`check-banners: all ${available.length} declared banners resolve at ${base}`);
+}
+
+await main();

package/ci/ci-steps.mjs

@@ -139,7 +139,7 @@ function prTriggeredWorkflows() {
  * @param {string} file - The workflow.
  * @returns {{run: Array<{name: string, run: string}>, skipped: string[]}} Its steps.
  */
-function stepsIn(file) {
+export function stepsIn(file) {
     const lines = fs.readFileSync(file, "utf8").split("\n");
     const run = [];
     const skipped = [];
@@ -164,25 +164,32 @@ function stepsIn(file) {
             continue;
         }
 
-        const inline = /^-?\s*run:\s*(?!\|)(.+)$/.exec(text);
-        if (inline) {
-            run.push({ name: name ?? inline[1], run: inline[1].trim() });
-            name = null;
-            continue;
-        }
         // A `run: |` block scalar: every following line indented deeper.
-        if (/^-?\s*run:\s*\|\s*$/.test(text)) {
+        if (/^-?\s*run:\s*\|[+-]?\s*$/.test(text)) {
             const base = indentOf(line);
             const body = [];
             while (i + 1 < lines.length) {
                 const next = lines[i + 1];
                 if (next.trim() !== "" && indentOf(next) <= base) break;
-                body.push(next.trim());
+                body.push(next);
                 i += 1;
             }
-            const command = body.filter(Boolean).join(" && ");
+            const margin = Math.min(
+                ...body.filter((line) => line.trim()).map((line) => indentOf(line)),
+            );
+            const command = body
+                .map((line) => line.slice(margin))
+                .join("\n")
+                .trimEnd();
             if (command) run.push({ name: name ?? command, run: command });
             name = null;
+            continue;
+        }
+        const inline = /^-?\s*run:\s*(.+)$/.exec(text);
+        if (inline) {
+            run.push({ name: name ?? inline[1], run: inline[1].trim() });
+            name = null;
+            continue;
         }
     }
     return { run, skipped };
@@ -223,7 +230,10 @@ function main() {
 
     for (const [i, step] of run.entries()) {
         console.log(`\nci-steps: [${i + 1}/${run.length}] ${step.name}\n  $ ${step.run}`);
-        const result = spawnSync(step.run, { cwd: ROOT, shell: true, stdio: "inherit" });
+        const result = spawnSync("bash", ["-e", "-o", "pipefail", "-c", step.run], {
+            cwd: ROOT,
+            stdio: "inherit",
+        });
         if (result.status !== 0) {
             console.error(
                 `\nci-steps: FAILED at "${step.name}" — this is what GitHub would report.\n` +

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

@@ -93,7 +93,7 @@ The fence displays **Table 1: Regional trade routes**, and `{{ref "#trade"}}` di
 
 **`.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.
 
-**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; 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`, 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.
+**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.
 
 **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`.
 
@@ -172,7 +172,7 @@ The bridge closes during the spring flood.
 ```
 
 Each heads itself with its own name — **Secret**, **Info**, **Warn** — and takes
-a closing `:::`. A name that is not one of the three is reported.
+a closing `:::`. Poetry has its own fence below; other names are reported.
 
 **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
@@ -232,6 +232,73 @@ 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.
 
+### Poetry
+
+Use `:::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.
+
+Leading spaces indent individual verse lines. The least-indented nonblank line
+sets level zero for the whole poem, so a common indentation on every line has no
+visual effect. Each additional two spaces adds one level, up to `i8`; an odd
+extra space rounds down. Each medium sets the actual width of a level, with
+every higher level wider than the preceding one. Tabs anywhere in the poem are
+an error. Interior spaces are preserved on a best-effort basis.
+
+| Extra leading spaces | Indent class |
+| -------------------- | ------------ |
+| 0–1                  | none         |
+| 2–3                  | `i1`         |
+| 4–5                  | `i2`         |
+| 6–7                  | `i3`         |
+| 8–9                  | `i4`         |
+| 10–11                | `i5`         |
+| 12–13                | `i6`         |
+| 14–15                | `i7`         |
+| 16 or more           | `i8`         |
+
+For example, a line with four leading spaces and a line with six leading spaces
+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}
+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
+positive count for each verse line in order, separated by commas, with blank
+stanza lines omitted. The build checks the number of counts, not the syllables
+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`:
+
+```markdown
+:::figure {#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.
+
 ## Footnotes and definition lists
 
 Write a footnote reference as `[^id]` and its definition as `[^id]: text`.

package/docs/content-format.md

@@ -27,6 +27,8 @@ A nonempty note body creates one system-agnostic Foundry JournalEntry. Content b
 
 A `:::figure {#anchor}` fence numbers whatever it holds — prose, code, a table, or an image. Its anchor makes the fence a target `{{ref "#anchor"}}` can point to, displaying the generated kind and number, such as **Figure 12**. Foundry gives the fence its own JournalEntryPage. See [figures and numbered references](authoring/links-and-markup.md#figures-and-numbered-references) for the syntax.
 
+A `:::poetry` fence keeps each authored line as a verse line and blank lines as stanza breaks. Inside a `:::figure`, a poem written first gives that figure the **Poem** counter and an optional caption. See [poetry](authoring/links-and-markup.md#poetry) for attributes and examples.
+
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
 `{allow-empty=true}` are examples. Inline font glyphs use the package's icon
@@ -49,6 +51,13 @@ explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
 
+An `affiliation` note declares `data.governance.ranks` with at least one rung at
+`level: 1`. Each rung states `level`, `title`, and `description`. A being's
+`data.affiliations` entry names a rank on that body's ladder; level 1 is the
+ordinary standing when no higher rank applies. A single level-1 rung is enough
+when the body expresses its hierarchy through `governance.offices` instead.
+Missing ranks, an empty list, or a ladder without level 1 are build errors.
+
 | Authored section | SoHL Actor          | HM3 Actor            |
 | ---------------- | ------------------- | -------------------- |
 | `{#appearance}`  | `system.appearance` | `system.description` |

package/docs/reference/format-details.md

@@ -2648,7 +2648,7 @@ displays **Table 1** as a link.
 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 `///`
+any nested code or poetry 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.
@@ -2681,11 +2681,11 @@ 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
+of six counters it draws from — `Code`, `Table`, `Figure`, `Map`, `Poem`, `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`; a `:::poetry` fence as the first nonblank content is `Poem`; everything else is `Prose`. A poem, table or 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.

package/docs/reference/theme-pages.md

@@ -301,8 +301,8 @@ its label beneath whatever it holds:
 </div>
 ```
 
-The kind is `code`, `table`, `figure`, `map` or `prose`, labelled **Code**,
-**Table**, **Figure**, **Map** and **Prose**. Every kind is drawn alike — the
+The kind is `code`, `table`, `figure`, `map`, `poem` or `prose`, labelled **Code**,
+**Table**, **Figure**, **Map**, **Poem** and **Prose**. Every kind is drawn alike — the
 block carries the spacing, its contents add none of their own at the edges,
 and the label reads as a caption rather than as another paragraph of the body
 — so a kind added to the vocabulary arrives styled. A fence carrying an `id`

package/engine/content-blocks.mjs

@@ -50,6 +50,7 @@ import MarkdownIt from "markdown-it";
 import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import { poetryMarkdown, verseLines } from "./content-poetry.mjs";
 import { WITHHELD_CLASS, parseHeadingLine, withheldSections } from "./heading-attributes.mjs";
 
 const parser = new MarkdownIt({ html: true }).use(footnotePlugin).use(deflistPlugin);
@@ -63,6 +64,8 @@ const titleParser = new MarkdownIt({ html: false });
 
 const OPEN = /^:::([A-Za-z][A-Za-z0-9-]*)(?:[ \t]+(.*?))?[ \t]*$/;
 const CLOSE = /^:::[ \t]*$/;
+const INDENTED_POETRY_OPEN = /^ +:::poetry(?:[ \t]+(.*?))?[ \t]*$/;
+const INDENTED_CLOSE = /^ *:::[ \t]*$/;
 
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES = Object.freeze({
@@ -98,7 +101,7 @@ const FOREIGN = Object.freeze(["figure"]);
 /** `title` is the heading. Everything else an author writes becomes an attribute. */
 const TITLE = "title";
 
-const names = () => Object.keys(BLOCK_NAMES).join(", ");
+const names = () => [...Object.keys(BLOCK_NAMES), "poetry"].join(", ");
 
 /** Text safe inside a double-quoted attribute. */
 function escapeAttribute(value) {
@@ -132,7 +135,7 @@ export function scanBlocks(source) {
 
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        const fence = opening?.name === "poetry" ? null : /^ {0,3}(`{3,}|~{3,})/.exec(line);
         if (codeFence) {
             if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
                 codeFence = null;
@@ -144,7 +147,7 @@ export function scanBlocks(source) {
             continue;
         }
 
-        if (CLOSE.test(line)) {
+        if (CLOSE.test(line) || (opening?.name === "poetry" && INDENTED_CLOSE.test(line))) {
             // A closer belongs to the innermost block still open, whichever
             // pass owns it.
             if (opening && innerOpen > 0) {
@@ -163,11 +166,21 @@ export function scanBlocks(source) {
                 opening = null;
                 continue;
             }
-            const body = lines
-                .slice(opening.start + 1, i)
-                .join("\n")
-                .trim();
-            if (!body) {
+            const bodyLines = lines.slice(opening.start + 1, i);
+            const rawBody = bodyLines.join("\n");
+            const body = opening.name === "poetry" ? rawBody : rawBody.trim();
+            if (opening.name === "poetry") {
+                for (let offset = 0; offset < bodyLines.length; offset++) {
+                    const column = bodyLines[offset].indexOf("\t");
+                    if (column >= 0)
+                        errors.push({
+                            line: opening.start + offset + 2,
+                            column: column + 1,
+                            message: "tabs are not allowed in poetry",
+                        });
+                }
+            }
+            if (!body.trim()) {
                 errors.push({
                     line: opening.start + 1,
                     column: 1,
@@ -176,12 +189,23 @@ export function scanBlocks(source) {
                 opening = null;
                 continue;
             }
+            if (opening.name === "poetry" && opening.attributes.syllables) {
+                const expected = opening.attributes.syllables.split(",").length;
+                const actual = verseLines(body).length;
+                if (expected !== actual)
+                    errors.push({
+                        line: opening.start + 1,
+                        column: 1,
+                        message: `poetry syllables= gives ${expected} counts for ${actual} verse lines`,
+                    });
+            }
             // An H1, or an anchored heading at any level, starts a Foundry
             // journal page — splitting the block's own page in two and
             // publishing the rest with no wrapper around it, a GM-only
             // section included. Refused rather than split: a lower heading
             // with no anchor is still the ordinary way to structure a box.
-            for (let at = opening.start + 1; at < i; at++) {
+            // Poetry treats those same characters as verse text.
+            for (let at = opening.start + 1; opening.name !== "poetry" && at < i; at++) {
                 if (!parseHeadingLine(lines[at])?.startsPage) continue;
                 const article = /^[aeiou]/i.test(opening.name) ? "an" : "a";
                 errors.push({
@@ -198,7 +222,8 @@ export function scanBlocks(source) {
             continue;
         }
 
-        const open = OPEN.exec(line);
+        const indentedPoetry = INDENTED_POETRY_OPEN.exec(line);
+        const open = OPEN.exec(line) ?? (indentedPoetry && [line, "poetry", indentedPoetry[1]]);
         if (!open) continue;
         const [, name, raw = ""] = open;
         const at = { line: i + 1, column: 1 };
@@ -207,7 +232,7 @@ export function scanBlocks(source) {
             else foreignOutside += 1;
             continue;
         }
-        if (!Object.hasOwn(BLOCK_NAMES, name)) {
+        if (!Object.hasOwn(BLOCK_NAMES, name) && name !== "poetry") {
             errors.push({ ...at, message: `there is no ${name} block; the blocks are ${names()}` });
             opening = { start: i, rejected: true };
             continue;
@@ -254,11 +279,30 @@ export function scanBlocks(source) {
                 continue;
             }
             for (const [key, value] of Object.entries(parsed.values)) {
+                if (name === "poetry") {
+                    if (!["form", "meter", "rhyme", "syllables", "lang"].includes(key))
+                        errors.push({ ...at, message: `${key}= is not a poetry attribute` });
+                    else if (key === "syllables" && !/^[1-9]\d*(?:,[1-9]\d*)*$/.test(value))
+                        errors.push({
+                            ...at,
+                            message: "poetry syllables= needs positive comma-separated counts",
+                        });
+                    else if (key === "lang" && !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(value))
+                        errors.push({ ...at, message: "poetry lang= needs a language tag" });
+                }
                 if (key === TITLE) title = value;
                 else attributes[key] = value;
             }
         }
-        opening = { start: i, name, title, id, classes, attributes };
+        opening = {
+            start: i,
+            name,
+            title,
+            id,
+            classes,
+            attributes,
+            indent: name === "poetry" ? /^ */.exec(line)[0] : "",
+        };
     }
 
     if (opening && !opening.rejected) {
@@ -295,11 +339,26 @@ function attributeText(block, target, classes) {
     const parts = [`class="${escapeAttribute(classes.join(" "))}"`];
     if (id) parts.push(`id="${escapeAttribute(id)}"`);
     for (const [key, value] of Object.entries(block.attributes)) {
-        parts.push(`${key}="${escapeAttribute(value)}"`);
+        const attribute = block.name === "poetry" && key !== "lang" ? `data-${key}` : key;
+        parts.push(`${attribute}="${escapeAttribute(value)}"`);
     }
     return parts.join(" ");
 }
 
+/** Keep a poem in its list, without turning standalone readable indentation into code. */
+function poetryWrapperIndent(lines, block) {
+    const indent = block.indent;
+    if (indent.length < 4) return indent;
+    for (let at = block.start - 1; at >= 0; at--) {
+        const line = lines[at];
+        if (!line.trim()) continue;
+        const leading = /^ */.exec(line)[0].length;
+        if (/^ *(?:[-+*]|\d+[.)]) +/.test(line) && leading < indent.length) return indent;
+        if (leading < indent.length) break;
+    }
+    return "";
+}
+
 /**
  * Render named blocks for one publishing surface.
  *
@@ -327,7 +386,6 @@ export function renderBlocks(source, target) {
         output.push(...lines.slice(cursor, block.start));
         const classes = [block.name, ...block.classes];
         const attributes = attributeText(block, target, classes);
-        const title = titleParser.renderInline(block.title);
         // A container's body may hold a block of its own, rendered first so
         // its own wrapper is already written when the outer one wraps it in
         // turn — nesting composes because each level is markdown-with-raw-HTML
@@ -336,6 +394,17 @@ export function renderBlocks(source, target) {
             BLOCK_CONTAINERS.includes(block.name) ?
                 renderBlocks(block.body, target).markdown
             :   block.body;
+        if (block.name === "poetry") {
+            const indent = poetryWrapperIndent(lines, block);
+            const verses = poetryMarkdown(held)
+                .split("\n")
+                .map((line) => (line ? `${indent}${line}` : line))
+                .join("\n");
+            output.push("", `${indent}<div ${attributes}>`, "", verses, "", `${indent}</div>`, "");
+            cursor = block.end + 1;
+            continue;
+        }
+        const title = titleParser.renderInline(block.title);
         if (target === "foundry") {
             output.push(
                 "",

package/engine/content-figures.mjs

@@ -107,6 +107,7 @@ export const FIGURE_NAMES = Object.freeze({
     table: "Table",
     figure: "Figure",
     map: "Map",
+    poem: "Poem",
     prose: "Prose",
 });
 
@@ -204,9 +205,10 @@ function picturesAreMap(contents, resolveRole) {
  * @param {string} contents - The contents, trimmed.
  * @param {(address: string) => string|undefined} resolveRole - The caller's
  *   lookup from a picture's address to the role its asset declares.
- * @returns {"code"|"table"|"figure"|"map"|"prose"} The kind.
+ * @returns {"code"|"table"|"figure"|"map"|"poem"|"prose"} The kind.
  */
 function figureKind(first, contents, resolveRole) {
+    if (/^(?: *:::poetry(?:\s|$)|<div\b[^>]*\bclass="poetry(?:\s|"))/.test(contents)) return "poem";
     if (first?.type === "table_open") return "table";
     if (first?.type === "fence" && /^\s*sql\b/i.test(first.info ?? "")) return "table";
     if (first?.type === "fence" || first?.type === "code_block") return "code";
@@ -240,7 +242,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
     const lines = String(source ?? "").split("\n");
     const figures = [];
     const errors = [];
-    const counts = { code: 0, table: 0, figure: 0, map: 0, prose: 0 };
+    const counts = { code: 0, table: 0, figure: 0, map: 0, poem: 0, prose: 0 };
     const ids = new Set();
     const headingIds = [];
     let codeFence = null;
@@ -292,10 +294,17 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         let close = start + 1;
         let split = -1;
         let nested = null;
+        let namedDepth = 0;
         const fenced = new Set();
         while (close < lines.length) {
             const body = lines[close];
             const bodyFence = FENCE.exec(body);
+            if (namedDepth) {
+                fenced.add(close);
+                if (/^ *:::[ \t]*$/.test(body)) namedDepth--;
+                close++;
+                continue;
+            }
             if (nested) {
                 fenced.add(close);
                 if (
@@ -313,6 +322,12 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
                 close++;
                 continue;
             }
+            if (/^ *:::poetry(?:\s|$)/.test(body)) {
+                namedDepth++;
+                fenced.add(close);
+                close++;
+                continue;
+            }
             if (CLOSE.test(body)) break;
             if (SPLIT.test(body)) {
                 if (split < 0) split = close;
@@ -446,7 +461,7 @@ export function renderFigureBlocks(
         output.push(...lines.slice(cursor, figure.line - 1));
         const numbered = (figure.id ? byId.get(figure.id) : null) ?? figure;
         const contents = lines.slice(figure.bodyStart, figure.bodyEnd).join("\n");
-        const classes = ["content-figure", `content-figure-${figure.kind}`, ...figure.classes];
+        const classes = ["content-figure", `content-figure-${numbered.kind}`, ...figure.classes];
         const id = figure.slug ? ` id="${escapeHtml(figure.slug)}"` : "";
         output.push(`<div${id} class="${escapeHtml(classes.join(" "))}">`);
         if (figure.kind === "figure" || figure.kind === "map") {

package/engine/content-poetry.mjs

@@ -0,0 +1,61 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/** The authored verse lines, excluding stanza separators. */
+export function verseLines(body) {
+    return String(body ?? "")
+        .split("\n")
+        .filter((line) => line.trim());
+}
+
+/**
+ * The least-indented verse is level zero. Every two additional leading spaces
+ * add one level; a leftover space is discarded and the level stops at eight.
+ * Blank lines divide stanzas rather than contributing to the baseline.
+ */
+export function poetryStanzas(body) {
+    const lines = String(body ?? "").split("\n");
+    const verses = verseLines(body);
+    if (!verses.length) return [];
+    const baseline = Math.min(...verses.map((line) => /^ */.exec(line)[0].length));
+    const stanzas = [];
+    let stanza = [];
+    for (const line of lines) {
+        if (!line.trim()) {
+            if (stanza.length) stanzas.push(stanza);
+            stanza = [];
+            continue;
+        }
+        const spaces = /^ */.exec(line)[0].length;
+        stanza.push({
+            text: line.slice(spaces).trimEnd(),
+            level: Math.min(8, Math.floor((spaces - baseline) / 2)),
+        });
+    }
+    if (stanza.length) stanzas.push(stanza);
+    return stanzas;
+}
+
+/** A verse is inline Markdown even when it starts with block syntax. */
+export function inlineVerse(text) {
+    return String(text)
+        .replace(/^(#{1,6}\s|>\s|[-+*]\s|:{1,2}\s|`{3,}|~{3,}|-{3,}\s*$)/, "\\$1")
+        .replace(/^(\d+)([.)])\s/, "$1\\$2 ");
+}
+
+/**
+ * Keep stanzas as Markdown paragraphs and make every verse line a hard break.
+ * The surrounding renderer still sees the entire note, so links and footnote
+ * definitions remain in scope. The span carries the indent for each line.
+ */
+export function poetryMarkdown(body) {
+    return poetryStanzas(body)
+        .map((stanza) =>
+            stanza
+                .map(
+                    ({ text, level }) =>
+                        `<span class="poetry-line${level ? ` i${level}` : ""}">${inlineVerse(text)}</span>`,
+                )
+                .join("  \n"),
+        )
+        .join("\n\n");
+}

package/engine/note-vocabulary.mjs

@@ -105,7 +105,7 @@ import { checkSocialTies } from "./social-ties.mjs";
 import { checkStandings } from "./standings.mjs";
 import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
-import { checkRankLadder } from "./rank-ladder.mjs";
+import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkLoreEvents } from "./lore-events.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
@@ -1014,6 +1014,7 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     affiliation: Object.freeze({
         stubbable: true,
+        check: checkAffiliationRankFloor,
         subTypes: Object.freeze([
             "guild",
             "order",

package/engine/pdf-build.mjs

@@ -744,7 +744,7 @@ export async function buildPdf({
      * @param {number} columns - The entry's page columns.
      * @returns {string} Typst markup.
      */
-    const figureCounts = { code: 0, table: 0, figure: 0, map: 0, prose: 0 };
+    const figureCounts = { code: 0, table: 0, figure: 0, map: 0, poem: 0, prose: 0 };
     // The role lookup a `:::figure` fence's `map` counter reaches through —
     // see `engine/content-figures.mjs`'s `resolveRole`. Addressed form, for a
     // page's own scan below, which runs before its embeds are rewritten into

package/engine/pdf-render.mjs

@@ -88,6 +88,7 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
 import { slugify } from "./content-slug.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
+import { inlineVerse, poetryStanzas } from "./content-poetry.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { HTML_TAG, htmlMessage } from "./content-html.mjs";
 import { EXPRESSION } from "./markdown-expressions.mjs";
@@ -526,7 +527,16 @@ export function markdownToTypst(markdown, opts = {}) {
         }
     }
     if (!opts.insideAdmonition) {
-        const { blocks } = scanBlocks(source);
+        const figuresHoldingPoetry = scanFigures(source).figures;
+        const blocks = scanBlocks(source).blocks.filter(
+            (block) =>
+                !figuresHoldingPoetry.some(
+                    (figure) =>
+                        block.name === "poetry" &&
+                        block.start >= figure.bodyStart &&
+                        block.end < figure.bodyEnd,
+                ),
+        );
         if (blocks.length) {
             const lines = source.split("\n");
             const output = [];
@@ -538,6 +548,24 @@ export function markdownToTypst(markdown, opts = {}) {
                         insideAdmonition: true,
                     }),
                 );
+                if (block.name === "poetry") {
+                    const content = poetryStanzas(block.body)
+                        .map((stanza) =>
+                            stanza
+                                .map(({ text, level }) => {
+                                    const verse = markdownToTypst(inlineVerse(text), {
+                                        ...sharedOptions,
+                                        insideAdmonition: true,
+                                    });
+                                    return `${level ? `#h(${level * 1.25}em)` : ""}${verse}`;
+                                })
+                                .join(" \\\n"),
+                        )
+                        .join("\n\n");
+                    output.push(`\n#block(width: 100%)[${content}]\n`);
+                    cursor = block.end + 1;
+                    continue;
+                }
                 const { color, background, symbol } = BLOCK_PRINT[block.name];
                 // The title is inline markdown, rendered the way every other
                 // phrase in the book is. Set as it was written it would be read
@@ -601,7 +629,9 @@ export function markdownToTypst(markdown, opts = {}) {
                 { ...caption, imagesRemaining: { n: countImages(block) } }
             :   caption;
         const segments = [
-            renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
+            caption.kind === "poem" ?
+                markdownToTypst(block, { ...sharedOptions, captions: undefined })
+            :   renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
         ];
         if (caption.kind !== "table" && caption.kind !== "figure" && caption.kind !== "map") {
             segments.push(

package/engine/rank-ladder.mjs

@@ -50,6 +50,38 @@ const RUNG_KEYS = Object.freeze(["level", "title", "description", "lore"]);
 /** The keys a rung must carry a value for. */
 const REQUIRED_TEXT = Object.freeze(["title", "description"]);
 
+/** Every affiliation has an ordinary standing that a being can name as rank 1. */
+export function checkAffiliationRankFloor(note) {
+    if (note.fm?.type !== "affiliation") return [];
+    const governance = note.fm?.data?.governance;
+    const ranks = governance?.ranks;
+    // A non-list already has a shape finding. Do not repeat it here.
+    if (ranks !== undefined && ranks !== null && !Array.isArray(ranks)) return [];
+    if (
+        Array.isArray(ranks) &&
+        ranks.some((rung) => integer(rung?.level) && Number(rung.level) === 1)
+    )
+        return [];
+
+    const path = Array.isArray(ranks) ? ["data", "governance", "ranks"] : ["data", "governance"];
+    const atRankOrGovernance = positionOfFrontmatterPath(note.raw ?? "", path, { key: true });
+    const position =
+        atRankOrGovernance.line !== undefined ?
+            atRankOrGovernance
+        :   positionOfFrontmatterPath(note.raw ?? "", ["data"], { key: true });
+    return [
+        {
+            file: note.file,
+            ...position,
+            severity: "error",
+            message:
+                !Array.isArray(ranks) || ranks.length === 0 ?
+                    "affiliation needs data.governance.ranks with a level 1 standing"
+                :   "affiliation data.governance.ranks needs a level 1 standing",
+        },
+    ];
+}
+
 /**
  * Whether a value is a YAML mapping rather than a list or a scalar.
  *

package/hugo-theme/data/banners.yaml

@@ -19,7 +19,7 @@
 # used as given and never looked for here.
 #
 # Keeping it in step is not left to hope: `npm run lint:banners`
-# (`utils/check-banners.mjs`, part of `npm run lint`) fetches every name below
+# (`ci/check-banners.mjs`, part of `npm run lint`) fetches every name below
 # from a real asset host and fails on any non-200. Add a name here only after
 # the file is published, or the check will say so.
 #

package/hugo-theme/static/css/style.css

@@ -1373,6 +1373,35 @@ a.tag:hover {
   background: var(--bg-card);
 }
 
+/* Verse lines are hard breaks in the markup; paragraphs mark stanzas. */
+.single-content .poetry {
+  margin: 1.5rem 0;
+  line-height: 1.7;
+}
+
+.single-content .poetry p {
+  margin: 0;
+}
+
+.single-content .poetry p + p {
+  margin-top: 1em;
+}
+
+.single-content .poetry .poetry-line {
+  display: inline-block;
+  margin-inline-start: var(--poetry-indent, 0em);
+  white-space: pre-wrap;
+}
+
+.single-content .poetry .poetry-line.i1 { --poetry-indent: 1.25em; }
+.single-content .poetry .poetry-line.i2 { --poetry-indent: 2.5em; }
+.single-content .poetry .poetry-line.i3 { --poetry-indent: 3.75em; }
+.single-content .poetry .poetry-line.i4 { --poetry-indent: 5em; }
+.single-content .poetry .poetry-line.i5 { --poetry-indent: 6.25em; }
+.single-content .poetry .poetry-line.i6 { --poetry-indent: 7.5em; }
+.single-content .poetry .poetry-line.i7 { --poetry-indent: 8.75em; }
+.single-content .poetry .poetry-line.i8 { --poetry-indent: 10em; }
+
 /* Ornamental horizontal rule: thin line flanking a centered gold
    diamond. Uses gradients on ::before/::after to keep the markup
    clean (authors just write `---` in markdown). */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.24.0",
+    "version": "22.25.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -187,10 +187,12 @@
         "build:asset-index": "node ci/emit-asset-index.mjs",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:content-format",
+        "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:image-roles lint:banners lint:content-format",
         "lint:markdown": "node bin/package-build.mjs markdown",
         "lint:yaml": "node bin/package-build.mjs yaml",
         "lint:labels": "node bin/package-build.mjs labels check",
+        "lint:image-roles": "vitest run tests/theme-image-roles.test.ts",
+        "lint:banners": "node ci/check-banners.mjs",
         "lint:markdown:fix": "node bin/package-build.mjs markdown --fix",
         "lint:content-format": "npm run lint:content-format:schema && npm run lint:content-format:fields && node ci/content-format-reference.mjs --check",
         "lint:content-format:schema": "node bin/package-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json --schema hm3=tests/fixtures/content-format/schema-hm3.json",

package/types/engine/content-figures.d.mts

@@ -87,6 +87,7 @@ export const FIGURE_NAMES: Readonly<{
     table: "Table";
     figure: "Figure";
     map: "Map";
+    poem: "Poem";
     prose: "Prose";
 }>;
 /**

package/types/engine/content-poetry.d.mts

@@ -0,0 +1,19 @@
+/** The authored verse lines, excluding stanza separators. */
+export function verseLines(body: any): string[];
+/**
+ * The least-indented verse is level zero. Every two additional leading spaces
+ * add one level; a leftover space is discarded and the level stops at eight.
+ * Blank lines divide stanzas rather than contributing to the baseline.
+ */
+export function poetryStanzas(body: any): {
+    text: string;
+    level: number;
+}[][];
+/** A verse is inline Markdown even when it starts with block syntax. */
+export function inlineVerse(text: any): string;
+/**
+ * Keep stanzas as Markdown paragraphs and make every verse line a hard break.
+ * The surrounding renderer still sees the entire note, so links and footnote
+ * definitions remain in scope. The span carries the indent for each line.
+ */
+export function poetryMarkdown(body: any): string;

package/types/engine/rank-ladder.d.mts

@@ -1,3 +1,11 @@
+/** Every affiliation has an ordinary standing that a being can name as rank 1. */
+export function checkAffiliationRankFloor(note: any): {
+    severity: string;
+    message: string;
+    line?: number;
+    column?: number;
+    file: any;
+}[];
 /**
  * Check one affiliation's `data.governance.ranks` against the rung contract.
  *