@heroiclands/package-build 22.26.0 → 22.27.0

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/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.27.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",

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.
  *

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

@@ -17,3 +17,35 @@ export function inlineVerse(text: any): string;
  * definitions remain in scope. The span carries the indent for each line.
  */
 export function poetryMarkdown(body: any): string;
+/** Read poetry code fences; start/end are inclusive zero-based source lines.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanPoetry(source: string): {
+    blocks: {
+        end: number;
+        body: string;
+        start: number;
+        fence: string;
+        name: string;
+        attributes: {};
+        id: string;
+        classes: never[];
+        indent: string;
+    }[];
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Replace verse fences with HTML wrappers whose body remains inline Markdown.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderPoetry(source: string): {
+    markdown: string;
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};

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

@@ -0,0 +1,18 @@
+/** Add bracket spans after recognized Markdown links and footnotes.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
+/** Read span anchors and located attribute diagnostics outside literal code.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanSpans(source: string): {
+    spans: any[];
+    errors: any[];
+};
+/** Emit span tags while leaving their inline content as Markdown for Hugo.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderSpans(source: string): {
+    markdown: string;
+    errors: any[];
+};