@heroiclands/package-build 22.26.0 → 22.28.0

package/engine/site-preview.mjs

@@ -284,12 +284,28 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                 });
                 const related = relatedPages(edges, entries).get(page.url);
                 if (related) result.data.related = related;
-                const holdings = holdingsPages([
-                    ...allPages.map((item) =>
-                        holdingsNode(item.fm, { title: item.name, url: item.url }),
-                    ),
-                    ...foreignHoldingsNodes(snapshot.gates.foreign.index),
-                ]);
+                const holdings = holdingsPages(
+                    [
+                        ...allPages.map((item) =>
+                            holdingsNode(item.fm, {
+                                title: item.name,
+                                url: item.url,
+                                package: item.pkg ?? config.contentPackage,
+                            }),
+                        ),
+                        ...foreignHoldingsNodes(snapshot.gates.foreign.index),
+                    ],
+                    {
+                        governmentNodes: records
+                            .filter((record) => !isGmNote(record))
+                            .map((record) =>
+                                holdingsNode(record, {
+                                    title: record.name?.full ?? record.shortcode,
+                                    package: config.contentPackage,
+                                }),
+                            ),
+                    },
+                );
                 Object.assign(result.data, holdings.get(page.url));
                 return {
                     ok: true,

package/engine/stub-lint.mjs

@@ -12,34 +12,16 @@
  */
 
 /**
- * An empty body must be deliberate.
+ * Every typed note needs a nonempty body.
  *
- * An empty body is what makes a note a **stub**, and the whole scheme turns on
- * that being on purpose rather than something somebody forgot. So four rules
- * hold the state honest, and two more report what the rules cannot decide:
+ * A missing or whitespace-only body is an error, whether or not the note has
+ * a `draft` tag or a frontmatter description. Placeholder-only bodies remain
+ * errors. A nonempty body below twenty-five words receives a warning when it
+ * is not tagged `draft`; the author decides whether that short note is done.
  *
- * 1. **A stub states what it is.** With nothing in the body, the `description`
- *    is the only sentence a reader gets and it is what every table and index
- *    prints. An **error**.
- * 2. **A stub is not tagged `draft`.** A thing not started is not a thing in
- *    progress. An **error**.
- * 3. **A body that renders to nothing is an abandoned draft, not a stub.** This
- *    is what keeps the empty-body rule's severity honest: the softer cases are
- *    *reported* rather than silently treated as one state or the other. An
- *    **error**.
- * 4. **A short unmarked body may be a draft that forgot its marker.** A
- *    **warning**, never an error — a note reading `See [[affiliation-meivor|Mëivōr]]`
- *    says everything it has to say, and a corpus holds many of them.
- * 5. **A long-standing draft is a report, not a finding.** It is unfinished,
- *    which the tag already says, so the oldest are listed and nobody is asked
- *    to dismiss a warning they cannot clear.
- * 6. **The counts are reported**, per package and per type, so the ratio of
- *    written to unwritten is visible on every run rather than discovered in a
- *    year.
- *
- * **What this does not decide is what earns a body.** Whether a given village
- * deserves prose is a question about a setting, and it belongs in the
- * repository that ships it. The toolchain's job is to make promotion free.
+ * Counts and the oldest drafts remain reports. Classification and indexing
+ * still derive full, draft and stub states from the existing note records;
+ * validation reports missing content without changing those records.
  *
  * @module
  */
@@ -50,7 +32,7 @@ import path from "node:path";
 import { authoredFrontmatter, isNoteRecord, isStub, noteFile } from "./index-records.mjs";
 import { positionInFrontmatter, positionOfLiteral } from "./diagnostics.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
-import { bodyWordCount, isStubNote, placeholderBody } from "./note-state.mjs";
+import { bodyWordCount, placeholderBody } from "./note-state.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
 
 /**
@@ -67,16 +49,6 @@ export const SHORT_BODY_WORDS = 25;
 /** How many of the oldest drafts the report names. */
 const OLDEST_DRAFTS = 10;
 
-/**
- * Whether a note states a description.
- *
- * @param {Record<string, any>} fm - The note's authored frontmatter.
- * @returns {boolean} Whether `description` carries a sentence.
- */
-function hasDescription(fm) {
-    return String(fm?.description ?? "").trim() !== "";
-}
-
 /**
  * Check one note's state, and say where the fault is.
  *
@@ -87,29 +59,14 @@ function checkNote({ fm, body, file, raw }) {
     const findings = [];
     const at = (key, value) => positionInFrontmatter(raw, key, value, { topLevel: true });
 
-    if (isStubNote(fm, body)) {
-        if (!hasDescription(fm)) {
-            findings.push({
-                file,
-                ...at("type", fm.type),
-                severity: "error",
-                message:
-                    "this note has no body, so it is a stub — and a stub carries " +
-                    "a `description`, which is the only sentence a reader gets " +
-                    "and what every table listing it prints",
-            });
-        }
-        if (isDraftNote(fm)) {
-            findings.push({
-                file,
-                ...at("type", fm.type),
-                severity: "error",
-                message:
-                    "this note has no body and is tagged `draft`, and a thing " +
-                    "not started is not a thing in progress — remove the tag, " +
-                    "or write a body",
-            });
-        }
+    if (String(body ?? "").trim() === "") {
+        findings.push({
+            file,
+            ...at("type", fm.type),
+            severity: "error",
+            message:
+                "this note has no body — write a nonempty body, even when it is tagged `draft`",
+        });
         return findings;
     }
 
@@ -122,8 +79,7 @@ function checkNote({ fm, body, file, raw }) {
             severity: "error",
             message:
                 `this note's body says only "${phrase}", so it publishes a page ` +
-                `that tells a reader nothing — empty the body to make this a ` +
-                `stub, or write it`,
+                `that tells a reader nothing — replace the placeholder with content`,
         });
         return findings;
     }
@@ -204,8 +160,8 @@ export function lintNoteStates(contentBase, { records, contentPackage } = {}) {
         if (state === "draft") drafts.push({ file, modified: fs.statSync(absPath).mtime });
 
         // Held to the rules only where there is a note to hold: a file that
-        // declares no type declares nothing for them to read, and asking it for
-        // a `description` would report vault scaffolding as content.
+        // declares no type declares nothing for them to read; requiring its
+        // body would report vault scaffolding as content.
         if (record.type) findings.push(...checkNote({ fm, body, file, raw }));
     }
 

package/engine/wikilinks.mjs

@@ -100,7 +100,8 @@ export function anchorPageId(noteId, anchorSlug) {
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
  *   name?: string, pack?: string, docPack?: string, none?: boolean,
- *   draft?: boolean}>} docs -
+ *   draft?: boolean, anchors?: Set<string>, anchorUuids?: Record<string,string>,
+ *   docAnchorUuids?: Record<string,string>}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
  *   one-pack-per-type names stand in. `none` says the note declares
@@ -153,9 +154,11 @@ export function buildWikilinkIndex(
     // that stored value. Nothing downstream assembles a UUID from parts, so a
     // link and its target cannot disagree about where the document lives.
     const uuidByDoc = new Map();
+    const byId = new Map();
 
     for (const d of docs) {
         if (!d.id || !d.type) continue;
+        byId.set(`${d.type}/${d.id}`, d);
         types.add(norm(d.type));
 
         uuidByDoc.set(
@@ -172,6 +175,8 @@ export function buildWikilinkIndex(
                     // type and a UUID carries the pack name, so the address
                     // cannot be derived from the type alone.
                     uuid: compendiumUuid(packageId, d.type, d.id, d.pack),
+                    anchors: d.anchorUuids,
+                    docAnchors: d.docAnchorUuids,
                     // The readable note has a separate JournalEntry whose id
                     // is derived from the item's id.
                     docUuid: compendiumUuid(packageId, "doc", itemDocEntryId(d.id), d.docPack),
@@ -216,6 +221,7 @@ export function buildWikilinkIndex(
         foreignReferences,
         types,
         uuidByDoc,
+        byId,
         packageId,
         /** The content package this build publishes, which an art address defaults to. */
         contentPackage: contentPackage ?? packageId,
@@ -433,7 +439,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
         // Kept for the foreign fallback below, which needs the parsed address.
         let qualifiedRead = null;
         if (target === "" && slug) {
-            doc = { type, id, pack, docPack };
+            doc = index.byId?.get(`${type}/${id}`) ?? { type, id, pack, docPack };
         } else {
             const qualified = parsed.problem ?? parsed.target;
             qualifiedRead = qualified;
@@ -546,7 +552,13 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
         // reader. A foreign anchor has always been checked this way —
         // the manifest carries the map — and a local one now is too, from the
         // anchor set the index carries.
-        if (slug && isJournal && doc.anchors && !doc.anchors.has(slug)) {
+        const anchorUuids = itemDoc ? addresses.docAnchors : addresses.anchors;
+        if (
+            slug &&
+            isJournal &&
+            ((doc.anchors && !doc.anchors.has(slug)) ||
+                (anchorUuids && !Object.hasOwn(anchorUuids, slug)))
+        ) {
             unresolved.push({
                 link: all,
                 target,
@@ -558,7 +570,9 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
             return unresolvedLink(text || doc.name || target, target);
         }
         const uuid =
-            slug && isJournal ? pageUuid(entryUuid, anchorPageId(entryId, slug)) : entryUuid;
+            slug && isJournal ?
+                (anchorUuids?.[slug] ?? pageUuid(entryUuid, anchorPageId(entryId, slug)))
+            :   entryUuid;
         const link = `@UUID[${uuid}]{${text}}`;
         // A link into a note that exists but is not written renders marked.
         // Presentation only — the UUID above is unchanged, and a

package/githooks/pre-push

@@ -4,7 +4,7 @@
 # container, over a clean export of HEAD — so a red GitHub check is something
 # you chose rather than something you discover.
 #
-# The steps are not listed here. `utils/ci-steps.mjs` reads them out of
+# The steps are not listed here. `ci/ci-steps.mjs` reads them out of
 # `.github/workflows/build.yml`, because a hook holding its own copy of the
 # command list is a second statement of one thing, and the copy is the one that
 # goes stale — silently, since running four of five steps still exits 0.

package/hugo-theme/layouts/partials/holdings/entry.html

@@ -1,7 +1,7 @@
 {{- /*
   One entry of a holdings list — `{title, url, type, subType}`, as
-  `@heroiclands/package-build` derives from `contains`, `held_by` and
-  `holdings` (see the "holdings card" section of the README).
+  `@heroiclands/package-build` derives from `contains`, `governed_by` and
+  `governed_places` (see the "holdings card" section of the README).
 
   `url` is absent for a stub: a note with an empty body, which carries its
   facts into every list that names it but publishes no page of its own. The

package/hugo-theme/layouts/partials/holdings.html

@@ -1,22 +1,22 @@
 {{- /*
-  Holdings card.
+  Geography and government card.
 
   Three small tables, rendered after the body and before the Related card
   (see `page-body.html`), from front matter `@heroiclands/package-build`
   derives and a note never authors itself:
 
     contains:  [{ title, url, type, subType }]  places sitting within this one
-    held_by:   [{ title, url, type, subType }]  affiliations holding this place
-    holdings:  [{ title, url, type, subType }]  places this affiliation holds
+    governed_by:   [{ title, url, type, subType }]  affiliations governing this place
+    governed_places:  [{ title, url, type, subType }]  places this affiliation governs
 
-  A place page carries `contains` and/or `held_by`; an affiliation page
-  carries `holdings`. Neither is checked here — presence of the key is the
+  A place page carries `contains` and/or `governed_by`; an affiliation page
+  carries `governed_places`. Neither is checked here — presence of the key is the
   only test, the same silent-disappear convention the Related card follows:
   a page carrying none of the three renders no card at all.
 
-  `contains` and `holdings` list places, so each is broken into groups by
+  `contains` and `governed_places` list places, so each is broken into groups by
   kind (`holdings/kind-groups.html`) — the towns together, the hamlets
-  together. `held_by` lists affiliations, whose kinds have no fixed
+  together. `governed_by` lists affiliations, whose kinds have no fixed
   hierarchy to group by, so it stays one flat grid with the kind printed
   beside each name instead of as a group heading.
 
@@ -27,10 +27,10 @@
   was established.
 */ -}}
 {{- $within := .Params.contains -}}
-{{- $heldBy := .Params.held_by -}}
-{{- $holds := .Params.holdings -}}
+{{- $government := .Params.governed_by -}}
+{{- $governed := .Params.governed_places -}}
 
-{{- if or $within $heldBy $holds -}}
+{{- if or $within $government $governed -}}
 <section class="holdings" data-pagefind-ignore>
   {{- with $within }}
   <div class="holdings-table">
@@ -38,9 +38,9 @@
     {{ partial "holdings/kind-groups.html" . }}
   </div>
   {{- end }}
-  {{- with $heldBy }}
+  {{- with $government }}
   <div class="holdings-table">
-    <h3 class="holdings-table-label">Held by</h3>
+    <h3 class="holdings-table-label">Governed by</h3>
     <ul class="holdings-table-grid">
       {{- range . }}
       <li>
@@ -51,9 +51,9 @@
     </ul>
   </div>
   {{- end }}
-  {{- with $holds }}
+  {{- with $governed }}
   <div class="holdings-table">
-    <h3 class="holdings-table-label">Holdings</h3>
+    <h3 class="holdings-table-label">Governed places</h3>
     {{ partial "holdings/kind-groups.html" . }}
   </div>
   {{- end }}

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

@@ -2868,9 +2868,9 @@ summary.info-sidebar-title::after {
    group's entries laid out as a CSS grid that reflows its own column count
    from the available width — two or three columns on a desktop, one on a
    phone — with no breakpoint needed. Related groups by the connected page's
-   `type`; Holdings groups `contains` and `holdings` by place `subType`
+   `type`; Holdings groups `contains` and `governed_places` by place `subType`
    (`.holdings-kind-group`, one level deeper, for the region/settlement/site
-   hierarchy) and leaves `held_by` a flat grid with the kind printed beside
+   hierarchy) and leaves `governed_by` a flat grid with the kind printed beside
    each name. */
 
 .related,
@@ -2980,3 +2980,41 @@ summary.info-sidebar-title::after {
     padding: 1.25rem 1.25rem;
   }
 }
+
+/* GitHub-style author alerts remain open and inherit the prose foreground. */
+.single-content .alert {
+  border-inline-start: 0.25rem solid var(--pb-alert-color);
+  padding: 0.5rem 1rem;
+  margin: 1rem 0;
+  color: inherit;
+  background: transparent;
+}
+.single-content .alert-title {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  margin: 0 0 0.5rem;
+  font-weight: 600;
+  color: var(--pb-alert-color);
+}
+.single-content .alert-icon {
+  width: 1em;
+  height: 1em;
+  flex-shrink: 0;
+  fill: currentColor;
+}
+.single-content .alert > :last-child {
+  margin-bottom: 0;
+}
+.single-content .alert-note {
+  --pb-alert-color: #4493f8;
+}
+.single-content .alert-tip {
+  --pb-alert-color: #3fb950;
+}
+.single-content .alert-important {
+  --pb-alert-color: #ab7df8;
+}
+.single-content .alert-warning {
+  --pb-alert-color: #d29922;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.26.0",
+    "version": "22.28.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",
@@ -182,6 +182,8 @@
     "scripts": {
         "test": "vitest run",
         "test:watch": "vitest",
+        "build": "node bin/package-build.mjs ci",
+        "deploy:npm": "node ci/publish-npm.mjs",
         "prepack": "run-s build:types build:asset-index",
         "build:types": "tsc -p tsconfig.dts.json",
         "build:asset-index": "node ci/emit-asset-index.mjs",

package/sohl/item-fields.mjs

@@ -449,22 +449,6 @@ export const ITEM_FIELDS = Object.freeze({
             default: null,
             describe: "Where the affiliation's authority sits, by place address.",
         },
-        {
-            // The geographic relation, kept apart from the organisational one
-            // above: `parents` is *subordinate to*, this is *holds sway over*.
-            //
-            // Authored plural and emitted singular, as the content format's
-            // mapping row states (`data.domains` → `system.domain`). The two
-            // spellings are deliberate rather than a slip, so the declaration
-            // carries both rather than either side guessing.
-            name: "data.domains",
-            legacyKey: "domains",
-            to: "domain",
-            ...ADDRESS_LIST,
-            address: PLACE_ITEMS,
-            default: [],
-            describe: "Places this affiliation holds sway over, by address.",
-        },
     ]),
 
     affliction: Object.freeze([

package/types/engine/anchors.d.mts

@@ -1,9 +1,8 @@
 /**
- * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
+ * The identifiers a note declares on headings, captions, divs, poems and spans.
  *
- * A bare `#` heading starts a journal page without declaring a slug, and so
- * does a figure fence that declares no id. A fence that declares one declares a
- * slug and starts an addressable journal page.
+ * Headings and captions may start journal pages. Div, poem and inline-span
+ * anchors address locations within their containing pages.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
@@ -22,3 +21,13 @@ export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (a
     level: number;
     line: number;
 }>;
+/** Collisions involving a div, verse or inline-span anchor.
+ * Heading and caption collisions are diagnosed by their existing scanners.
+ * @param {string} body - Authored Markdown.
+ * @returns {Array<{line: number, column: number, message: string}>} Located collisions.
+ */
+export function markupAnchorFindings(body: string): Array<{
+    line: number;
+    column: number;
+    message: string;
+}>;

package/types/engine/art-fields.d.mts

@@ -144,7 +144,7 @@ export function resolveArtRecord(index: object, value: unknown, defaultType: str
  * carries once an embed's address has been rewritten into the ordinary image
  * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
  *
- * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * This is the lookup a captioned item's `map` counter reaches through —
  * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
  * for a caller that reads a body after that rewrite: a Foundry journal, an
  * item or actor's documentation, and the book.

package/types/engine/code-fences.d.mts

@@ -17,11 +17,13 @@ export function parseHeaderArgs(info: string): {
  * @param {object} [options]
  * @param {boolean} [options.spans=true] - Include inline code spans. Set false
  *   to consider only block-level code.
+ * @param {boolean} [options.poetryAsProse=true] - Treat verse bodies as inline prose.
  * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
  *   source order. `end` is exclusive.
  */
-export function codeRegions(markdown: string | null | undefined, { spans }?: {
+export function codeRegions(markdown: string | null | undefined, { spans, poetryAsProse }?: {
     spans?: boolean | undefined;
+    poetryAsProse?: boolean | undefined;
 }): Array<{
     start: number;
     end: number;

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

@@ -0,0 +1,62 @@
+/** Read alerts outside code examples, retaining inclusive source line ranges.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanAlerts(source: string): {
+    blocks: {
+        start: number;
+        end: number;
+        depth: number;
+        type: string;
+        title: any;
+        id: string;
+        classes: never[];
+        attributes: {
+            [k: string]: any;
+        };
+        body: string;
+    }[];
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Render alert wrappers while preserving ordinary Markdown and note footnotes.
+ * @param {string} source - Authored Markdown.
+ * @param {"web"|"foundry"} [target="web"] - Publishing surface.
+ */
+export function renderAlerts(source: string, target?: "web" | "foundry"): {
+    markdown: string;
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Mark alert blockquotes and remove their marker before inline parsing.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function alertMarkdownPlugin(md: typeof import("markdown-it")): void;
+/** Alert titles and static icons shared by all publishing surfaces. */
+export const ALERT_TYPES: Readonly<{
+    note: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    tip: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    important: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    warning: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+}>;

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

@@ -67,20 +67,13 @@ export function renderBlocks(source: string, target: "foundry" | "web"): {
 export function renderWithheldSections(source: string): string;
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES: Readonly<{
-    info: "Info";
     secret: "Secret";
-    warn: "Warn";
 }>;
 /**
- * Blocks that may hold another named block.
+ * Container fences whose bodies are scanned and rendered recursively.
  *
- * A box inside a GM-only section is a real thing to write — the section is a
- * container for whatever the GM reads, boxes included — so a `secret` holds one
- * and the box stays inside it. A box inside a box is noise, so `info` and `warn`
- * hold no named block and a second opener inside one is a finding.
- *
- * Exported because a renderer has to know it: the body of a container is read
- * for blocks of its own, and the body of a box is not.
+ * A secret may hold general divs; a general div may hold another div or a
+ * secret. A secret nested directly within another secret is refused.
  *
  * @type {readonly string[]}
  */

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

@@ -49,7 +49,7 @@ export function resolveEmbed(index: object, embed: ParsedEmbed): {
  * The role an address's asset declares, read through the same resolution an
  * embed's address takes.
  *
- * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * This is the lookup a captioned item's `map` counter reaches through —
  * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` — for
  * an address still in its authored form, before {@link resolveEmbeds} has
  * rewritten it into the ordinary image every surface renders.

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

@@ -1,21 +1,15 @@
 /** Number a sequence of figures with counters shared across documents. */
 export function numberFigures(figures: any, counts: any): any;
 /**
- * Read every `:::figure` fence in a body.
- *
- * SQL fences are expanded before this pass, so their output is a table.
- *
- * @param {string} source - A note body with expanded tables.
+ * Read leading captions and their following blocks outside literal fences.
+ * Historical figure API names remain for caption references and consumers.
+ * @param {string} source - The authored or expanded note body.
  * @param {object} [options] - Options.
- * @param {(address: string) => string|undefined} [options.resolveRole] - From
- *   a picture's address to the role its asset declares, so a picture whose
- *   asset declares `role: map` counts as `map` rather than `figure`. Omitted,
- *   every picture counts as `figure` — the same reading a role other than
- *   `map` gets.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - Asset role lookup.
  * @returns {{figures: Array<{id: string, slug: string, caption: string,
- *   hasCaption: boolean, classes: string[], kind: string, number: number,
- *   label: string, line: number, bodyStart: number, bodyEnd: number,
- *   captionStart: number, captionEnd: number, close: number}>,
+ *   hasCaption: boolean, classes: string[], attributes: Record<string,string>,
+ *   kind: string, numbered: boolean, number: number, label: string, line: number,
+ *   bodyStart: number, bodyEnd: number, captionStart: number, captionEnd: number, close: number}>,
  *   errors: Array<{line: number, column: number, message: string}>}}
  */
 export function scanFigures(source: string, { resolveRole }?: {
@@ -27,7 +21,9 @@ export function scanFigures(source: string, { resolveRole }?: {
         caption: string;
         hasCaption: boolean;
         classes: string[];
+        attributes: Record<string, string>;
         kind: string;
+        numbered: boolean;
         number: number;
         label: string;
         line: number;
@@ -44,7 +40,7 @@ export function scanFigures(source: string, { resolveRole }?: {
     }>;
 };
 /**
- * Render figure fences as HTML, leaving other Markdown untouched.
+ * Render leading captions and their next blocks as HTML, leaving other Markdown untouched.
  *
  * A code, table or prose figure's contents are left as Markdown inside the
  * wrapper, blank-line separated from its tags exactly as
@@ -84,6 +80,7 @@ export function renderFigureBlocks(source: string, renderMarkdown?: (markdown: s
 /** A figure's automatically determined kind, and the word that labels it. */
 export const FIGURE_NAMES: Readonly<{
     code: "Code";
+    example: "Example";
     table: "Table";
     figure: "Figure";
     map: "Map";
@@ -91,12 +88,8 @@ export const FIGURE_NAMES: Readonly<{
     prose: "Prose";
 }>;
 /**
- * The classes a figure takes.
- *
- * `.border` states that the captioned thing is drawn inside a border, and each
- * medium owns what that means. The vocabulary is closed: a class absent from it
- * is a finding naming the class.
- *
+ * Historical built-in presentation classes, retained for theme consumers.
+ * Captions now accept arbitrary classes through the shared attribute grammar.
  * @type {readonly string[]}
  */
 export const FIGURE_CLASSES: readonly string[];

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

@@ -67,7 +67,7 @@ export function escapeHtml(text: string): string;
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
- * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * **No `<figcaption>` is emitted here.** A captioned item draws its own
  * label and authored caption around whatever this returns; the alt text stays
  * on the `img` element alone.
  *