@heroiclands/package-build 25.5.4 → 25.6.0

package/engine/standings.mjs

@@ -31,7 +31,8 @@
  * **`rank` is a number, not a link.** The body declares `{level, title,
  * description}` for every rung of its `governance.ranks`, so a number indexes
  * into that ladder and the body stays the single source for what its level 5 is
- * called. **`office` is a string**, matched against the keys of the body's
+ * called. **`office` is a string, or a list of them** for one being holding
+ * several posts in one body, each matched against the keys of the body's
  * `governance.offices` map: there are far more offices in a tree than bodies,
  * most of them held by one body alone, and an Address would make writing the
  * fact wait on authoring a page about the post.
@@ -55,7 +56,7 @@ import { acceptsType, isAddressTuple, parseAddress, renderAddress } from "./addr
 import { AddressEntries } from "./address-values.mjs";
 import { slugify } from "./content-slug.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { fitsKind } from "./data-keys.mjs";
+import { fitsKind, pathLabel } from "./data-keys.mjs";
 import { STANDING_BODY_TYPES, STANDING_FIELDS, STANDING_KEYS } from "./standing-terms.mjs";
 
 export { STANDING_BODY_TYPES, STANDING_FIELDS, STANDING_KEYS };
@@ -221,12 +222,45 @@ export function standingsDigest(fm) {
     };
 }
 
+/**
+ * The posts one standing names, as written: one post, or each post of a list.
+ *
+ * Every entry is kept, blank or not text included, so the check can locate
+ * each one; a reader of the posts themselves takes {@link standingOffices}.
+ *
+ * @param {unknown} office - A standing's authored `office`.
+ * @returns {Array<{value: unknown, at: Array<number>}>} Each post with its
+ *   position below `office` — `[]` for the single form, `[i]` for a list entry.
+ */
+function writtenOffices(office) {
+    if (office === undefined || office === null) return [];
+    if (Array.isArray(office)) return office.map((value, i) => ({ value, at: [i] }));
+    return [{ value: office, at: [] }];
+}
+
+/**
+ * The posts a standing holds, trimmed, in the order written.
+ *
+ * `office` is one post or a list of them, and every reader — the line on the
+ * being's page, the SoHL item, the derived holders of an office — wants the
+ * same list from both.
+ *
+ * @param {object} [standing] - `{rank, office}`, either or both absent.
+ * @returns {string[]} The posts, blank and non-text entries left out.
+ */
+export function standingOffices(standing) {
+    return writtenOffices(standing?.office)
+        .map(({ value }) => (typeof value === "string" ? value.trim() : ""))
+        .filter(Boolean);
+}
+
 /**
  * What a standing says before the body that confers it — `War Chief, Hárár
  * (5), of ` — or `""` where no standing is held.
  *
  * The office leads, because it is the more particular of the two: a reader
- * meeting "War Chief" has been told the rung as well. The rung follows as its
+ * meeting "War Chief" has been told the rung as well. Several posts in one
+ * body lead in the order written, `Treasurer, Chancellor, …`. The rung follows as its
  * title with its level in parentheses, read from the body's own ladder; where
  * the ladder names no rung at that level, or none is available, it reads as
  * `Rank 5` and the number is not repeated. The body closes the phrase, which is
@@ -241,9 +275,7 @@ export function standingsDigest(fm) {
  * @returns {string} The words before the body's name, ending `of `.
  */
 export function standingLead(standing, digest) {
-    const parts = [];
-    if (typeof standing?.office === "string" && standing.office.trim())
-        parts.push(standing.office.trim());
+    const parts = [...standingOffices(standing)];
     const rank = standing?.rank;
     const level = typeof rank === "number" || typeof rank === "string" ? Number(rank) : NaN;
     if (rank !== "" && Number.isFinite(level)) {
@@ -264,7 +296,7 @@ export function standingLead(standing, digest) {
  * 3. the entry states a standing at all — what a stated standing holds is the
  *    inner-key check's, read from {@link STANDING_FIELDS};
  * 4. a `rank` is a level the named body's `governance.ranks` declares;
- * 5. an `office` is a key of that body's `governance.offices`.
+ * 5. each post an `office` names is a key of that body's `governance.offices`.
  *
  * Both of the last two are read from the named body's own frontmatter as the
  * lint runs, so a rung or a post that does not exist fails on every being pointing
@@ -474,39 +506,59 @@ function rankFindings(note, standing, body, path, resolved) {
     ];
 }
 
-/** Whether an `office` is a post the named body names. */
+/**
+ * Whether each post an `office` names is one the named body names.
+ *
+ * `office` is one post or a list of them, and each is checked on its own and
+ * located at its own value, so a list naming one unknown post among several is
+ * one finding at that post.
+ */
 function officeFindings(note, standing, body, path, resolved) {
-    // Absent is a membership with no post; a value that is not text is the
-    // inner-key check's finding.
-    if (typeof standing.office !== "string") return [];
-    const at = () => position(note, [...path, "office"]);
-    if (!standing.office.trim())
-        return [
-            {
+    const roster = resolved.fm ? officeRoster(resolved.fm.data?.governance?.offices) : undefined;
+    const findings = [];
+    for (const { value, at: below } of writtenOffices(standing.office)) {
+        if (typeof value !== "string") {
+            // A list entry that is not text is the inner-key check's finding,
+            // read from the declaration's `entries`. The single form is one
+            // post too, and the inner-key check reads only a list's entries.
+            if (!below.length)
+                findings.push({
+                    ...position(note, [...path, "office"]),
+                    message:
+                        `\`${pathLabel(["data", "affiliations", ...path.slice(2), "office"])}\` ` +
+                        `should be ${STANDING_FIELDS.find((f) => f.name === "office").shape}, ` +
+                        `but reads ${JSON.stringify(value)}`,
+                });
+            continue;
+        }
+        const at = () => position(note, [...path, "office", ...below]);
+        if (!value.trim()) {
+            findings.push({
                 ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body}: \`office\` must name a post from its ` +
-                    `\`governance.offices\`, but reads ${JSON.stringify(standing.office)}`,
-            },
-        ];
-    if (!resolved.fm) return [];
-    const roster = officeRoster(resolved.fm.data?.governance?.offices);
-    if (roster.has(standing.office)) return [];
-    if (!roster.size)
-        return [
-            {
+                    `\`governance.offices\`, but reads ${JSON.stringify(value)}`,
+            });
+            continue;
+        }
+        if (!roster || roster.has(value)) continue;
+        if (!roster.size) {
+            findings.push({
                 ...at(),
                 message:
                     `\`data.affiliations\` entry for ${body} names an office, and that body ` +
                     `${resolved.address} declares no \`data.governance.offices\` to hold one`,
-            },
-        ];
-    return [
-        {
+            });
+            // One finding says the body holds no posts; each further post
+            // would repeat it.
+            break;
+        }
+        findings.push({
             ...at(),
             message:
-                `\`data.affiliations\` entry for ${body}: office ${JSON.stringify(standing.office)} is not ` +
+                `\`data.affiliations\` entry for ${body}: office ${JSON.stringify(value)} is not ` +
                 `an office ${resolved.address} names; it holds ${[...roster.keys()].join(", ")}`,
-        },
-    ];
+        });
+    }
+    return findings;
 }

package/engine/unique-items.mjs

@@ -0,0 +1,85 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * 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.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **A one-of-a-kind item is tied to the places and beings involved.**
+ *
+ * `data.unique: true` on a gear note marks an item there is only one of — a
+ * named hammer, a crown, a sword in a tomb. Where it lies and who claims it are
+ * prose, because possession changes with play and ownership is a claim that
+ * can be disputed; so the note's own links are what tie it to the world, and a
+ * unique item whose note links no place and no being is a finding.
+ *
+ * A link counts wherever the note writes it: a wikilink in its body, or a
+ * `made` or `lost` event Address naming a place's or a being's event.
+ *
+ * @module
+ */
+
+import { isAddressTuple, parseAddress } from "./address.mjs";
+import { matchAllOutsideCode } from "./code-fences.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
+
+/** The note types a unique item's links must reach at least one of. */
+export const UNIQUE_ITEM_LINK_TYPES = Object.freeze(["place", "being"]);
+
+/**
+ * The note type one written target names, or `""` where it is no Address.
+ *
+ * @param {unknown} target - A wikilink target or an authored Address.
+ * @param {object} [index] - The lint's address index.
+ * @returns {string} The type.
+ */
+function typeOf(target, index) {
+    if (isAddressTuple(target)) return target.type;
+    // An event Address arrives decoded as a link to its note and anchor.
+    if (isAddressTuple(target?.target)) return target.target.type;
+    const tuple = parseAddress(String(target ?? "").split("#")[0], {
+        package: index?.contentPackage,
+        system: "note",
+        types: index?.types,
+        packages: index?.packages,
+    });
+    return tuple.reason ? "" : String(tuple.type ?? "");
+}
+
+/**
+ * Report a unique item whose note links no place or being.
+ *
+ * @param {object} note - The note: `file`, `raw`, `body` and parsed `fm`.
+ * @param {{index?: object}} [options] - The lint's options.
+ * @returns {object[]} The finding, located at `unique`, or none.
+ */
+export function checkUniqueItem(note, { index } = {}) {
+    const data = note.fm?.data;
+    if (data?.unique !== true && data?.unique !== "true") return [];
+    const targets = [
+        data.made,
+        data.lost,
+        ...matchAllOutsideCode(note.body ?? "", new RegExp(WIKILINK.source, "g")).map(
+            ([, inner]) => parseWikilink(inner).target,
+        ),
+    ].filter(Boolean);
+    if (targets.some((target) => UNIQUE_ITEM_LINK_TYPES.includes(typeOf(target, index)))) return [];
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "unique"], { key: true }),
+            severity: "error",
+            message:
+                "a unique item links no place or being; link where it lies or who " +
+                "holds or claims it in the note's prose",
+        },
+    ];
+}

package/engine/verse-metre.mjs

@@ -62,8 +62,48 @@ import MarkdownIt from "markdown-it";
 import { spanMarkdownPlugin } from "./content-spans.mjs";
 import { parseVerse } from "./content-verse.mjs";
 import { inlineText } from "./name-markup.mjs";
+import { WIKILINK, authoredLabel, parseWikilink } from "./wikilink-syntax.mjs";
 
 const verseParser = new MarkdownIt().use(spanMarkdownPlugin);
+const wikilinkAt = new RegExp(WIKILINK.source, "y");
+
+// Parse link labels in place so neighbouring spans keep their source offsets.
+verseParser.inline.ruler.before("link", "metre_wikilink", (state, silent) => {
+    const start = state.pos;
+    wikilinkAt.lastIndex = start;
+    const match = wikilinkAt.exec(state.src);
+    if (!match || start + match[0].length > state.posMax) return false;
+    const finish = start + match[0].length;
+    if (silent) {
+        state.pos = finish;
+        return true;
+    }
+    const parsed = parseWikilink(match[1], match[0]);
+    const label = authoredLabel(parsed) ?? state.env.referenceName?.(parsed.target);
+    const token = state.push("span_open", "span", 1);
+    token.meta = {
+        span: true,
+        start,
+        end: finish,
+        unresolvedReference: !parsed.labelled || label === undefined || label === "",
+    };
+    if (parsed.attributes?.classes.length)
+        token.attrSet("class", parsed.attributes.classes.join(" "));
+    for (const [key, value] of Object.entries(parsed.attributes?.values ?? {}))
+        token.attrSet(key, value);
+    const nested = [];
+    state.md.inline.parse(label ?? "", state.md, state.env, nested);
+    const labelStart = start + match[0].indexOf("|") + 1;
+    for (const child of nested)
+        if (child.meta?.span) {
+            child.meta.start += labelStart;
+            child.meta.end += labelStart;
+        }
+    state.tokens.push(...nested);
+    state.push("span_close", "span", -1);
+    state.pos = finish;
+    return true;
+});
 
 export { METRE_KINDS, METRE_NAME, checkMetresField } from "./metre-declaration.mjs";
 
@@ -240,11 +280,12 @@ function wordBeats(word, book) {
     const folded = foldWord(word);
     const count = nucleiOf(folded, book.pairs).length;
     if (count === 0) return { min: 0, max: 0 };
+    const bases = book.classes.get(folded);
     if (count > 1) {
+        const functionWord = bases && [...bases].every((base) => !BEAT_BASES.includes(base));
         const first = stressIndex(folded, book.rule, book.pairs) === 0;
-        return { min: 1, max: count >= 4 && !first ? 2 : 1 };
+        return { min: functionWord ? 0 : 1, max: count >= 4 && !first ? 2 : 1 };
     }
-    const bases = book.classes.get(folded);
     if (!bases) return { min: 1, max: 1 };
     const carrying = [...bases].filter((base) => BEAT_BASES.includes(base)).length;
     if (carrying === bases.size) return { min: 1, max: 1 };
@@ -292,7 +333,7 @@ export function metreMessage({ min, max }, metre) {
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
  *   The divs, from {@link module:engine/content-verse.scanVerse}.
  * @param {string[]} lines - The source's lines.
- * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
+ * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, referenceName?: (target: string) => string|undefined, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
  *   The metres and books, and how the div says its columns and where its
  *   keys sit.
  * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
@@ -358,9 +399,12 @@ export function metreFindings(blocks, lines, ctx) {
                         ({ offset }) =>
                             !model.layout.some(([from, to]) => offset >= from && offset < to),
                     );
+                const inlineContext = { referenceName: ctx.referenceName };
                 const parsed =
-                    verseParser.parseInline(units.map((unit) => unit.text).join(""), {})[0]
-                        ?.children ?? [];
+                    verseParser.parseInline(
+                        units.map((unit) => unit.text).join(""),
+                        inlineContext,
+                    )[0]?.children ?? [];
                 let presentationDepth = 0;
                 const tokens = parsed.filter((token) => {
                     if (presentationDepth) {
@@ -395,6 +439,7 @@ export function metreFindings(blocks, lines, ctx) {
                     );
                     continue;
                 }
+                if (tokens.some((token) => token.meta?.unresolvedReference)) continue;
                 const beats = lineBeats(text, book);
                 if (metre.beats >= beats.min && metre.beats <= beats.max) continue;
                 warnings.push({

package/engine/verse-regions.mjs

@@ -26,6 +26,8 @@ import { parseExtensionAttributes } from "./extension-attributes.mjs";
  * @property {number} bodyStart - First body offset.
  * @property {number} bodyEnd - Offset past body text, excluding its final newline.
  * @property {string} body - Authored body bytes.
+ * @property {string} logicalBody - Body without Markdown container prefixes.
+ * @property {number[]} bodyOffsets - Logical UTF-16 offsets mapped to authored body offsets, including the end.
  * @property {Record<string,string>} attributes - Authored values.
  * @property {string} id - Anchor or empty string.
  * @property {string[]} classes - Authored classes including verse.
@@ -95,6 +97,18 @@ export function verseDivPlugin(md) {
                 if (original[bodyEnd - 1] === "\n") bodyEnd--;
                 if (original[bodyEnd - 1] === "\r") bodyEnd--;
             }
+            const bodyOffsets = [];
+            let logicalBody = "";
+            for (let number = first + 1; number < (closed ? close : past); number++) {
+                const lineEnd = Math.min(starts[number] + rawLines[number].length, bodyEnd);
+                const contentStart = Math.min(contentStarts[number - first], lineEnd);
+                const pastLine = Math.min(starts[number + 1] ?? bodyEnd, bodyEnd);
+                for (let offset = contentStart; offset < pastLine; offset++) {
+                    logicalBody += original[offset];
+                    bodyOffsets.push(offset - bodyStart);
+                }
+            }
+            bodyOffsets.push(bodyEnd - bodyStart);
             const region = {
                 start: first,
                 end: closed ? close : past - 1,
@@ -104,6 +118,8 @@ export function verseDivPlugin(md) {
                 bodyStart,
                 bodyEnd,
                 body: original.slice(bodyStart, bodyEnd),
+                logicalBody,
+                bodyOffsets,
                 attributes: parsed.values,
                 id: parsed.id,
                 classes: parsed.classes,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.5.4",
+    "version": "25.6.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -157,7 +157,7 @@
         "eslint-plugin-yml": "^3.8.1",
         "fflate": "^0.8.3",
         "flesch": "^2.0.1",
-        "glob": "^13.0.6",
+        "glob": "^14.0.3",
         "handlebars": "^4.7.10",
         "highlight.js": "^11.12.0",
         "ignore": "^7.0.12",
@@ -168,7 +168,7 @@
         "markdown-it": "^15.0.0",
         "markdown-it-deflist": "^4.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "minimatch": "^10.2.6",
+        "minimatch": "^11.0.3",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
         "remark-frontmatter": "^5.0.0",
@@ -243,5 +243,10 @@
         "sohl",
         "song-of-heroic-lands"
     ],
-    "homepage": "https://github.com/HeroicLands/package-build#documentation"
+    "homepage": "https://github.com/HeroicLands/package-build#documentation",
+    "overrides": {
+        "minimatch": "$minimatch",
+        "katex": "0.18.2",
+        "re2js": "2.8.7"
+    }
 }

package/site-theme/data/banner-kinds.yaml

@@ -64,8 +64,10 @@ kinds:
     mysticalability: mystical-abilities
     place:
         celestial: default
+        district: default
         feature: default
         region: region
+        route: default
         settlement: settlement
         site: default
         structure: default

package/sohl/actors.mjs

@@ -42,7 +42,8 @@
  * **A membership is derived, never authored here.** `data.affiliations` names
  * the bodies a being belongs to and the standing it holds in each, and each
  * entry becomes one embedded affiliation item: the entry's `rank` is that
- * item's `system.level`, its `office` is `system.office`, and the first of its
+ * item's `system.level`, its `office` is `system.office` (several posts joined
+ * by commas), and the first of its
  * `societies` is `system.society`, the one society the SoHL item carries. A
  * standing is a fact about the setting rather than about one system — it does
  * not become true because SoHL is installed — so the system block states none
@@ -76,7 +77,7 @@ import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
 // A being's memberships and the standing it holds in each, read from the one
 // place they are authored. The rank *is* the affiliation item's `level`, so
 // there is nothing to map and nowhere for a second authoring to disagree.
-import { readStandings } from "../engine/standings.mjs";
+import { readStandings, standingOffices } from "../engine/standings.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -234,7 +235,7 @@ export class Actors extends SystemActorCompiler {
             const shortcode = body?.shortcode;
             if (!shortcode) continue;
             const level = Number(standing?.rank);
-            const office = typeof standing?.office === "string" ? standing.office.trim() : "";
+            const office = standingOffices(standing).join(", ");
             const [first] = Array.isArray(standing?.societies) ? standing.societies : [];
             const society = typeof first === "string" ? first.trim() : "";
             const system = {

package/types/e2e.d.mts

@@ -494,7 +494,7 @@ export const E2E_SCENE_ID: "heroiclandsScene";
 /** How the suite may be run. */
 export const E2E_MODES: readonly string[];
 /** The Chrome for Testing build shared by local and CI Cypress runs. */
-export const CHROME_BUILD_ID: "158.0.8122.0";
+export const CHROME_BUILD_ID: "159.0.8136.0";
 /**
  * The disposable world's identity and credentials.
  */

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

@@ -74,7 +74,8 @@ export function lintContentHtml(contentBase: string, { skipDirectories, sources
  * markdown's own angle brackets out of it: an autolink is `<https://…>`, and
  * `https` is followed by `:` rather than whitespace or `>`, so the pattern
  * stops. A comparison written in prose — `a < b` — has no name after the
- * bracket at all.
+ * bracket at all. A doubled `<<` opens a quotation, so its second bracket
+ * never starts an HTML tag.
  *
  * Attributes are consumed as "anything but a bracket", deliberately loosely: a
  * finding names the tag, and a pattern that tried to parse attribute syntax

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

@@ -5,6 +5,8 @@
  *   resolved configuration.
  * @param {Iterable<Record<string, any>>} [records] - The content index's
  *   records, whose language notes supply lexical writings and script choices.
+ * @param {{referenceName?: (target: string) => string|undefined}} [options] -
+ *   The rendering or validation index's own target-name lookup.
  * @returns {RunContext} Its languages, the faces installed where it sits, and
  *   the encodings. A fonts package that cannot be read gives no faces; a run naming
  *   one is reported.
@@ -16,7 +18,9 @@ export function runContext(config: {
     paths?: {
         content?: string;
     };
-} | undefined, records?: Iterable<Record<string, any>>): RunContext;
+} | undefined, records?: Iterable<Record<string, any>>, { referenceName: indexedName }?: {
+    referenceName?: (target: string) => string | undefined;
+}): RunContext;
 /**
  * Find the spans, divs and verse divs marked with `lang=`, `font=` or
  * `enc=`, and every fault in their markup and their text.
@@ -326,6 +330,10 @@ export type RunContext = {
      * {@link module :engine/verse-metre.metreBooksFromRecords}.
      */
     metreBooks?: ReadonlyMap<string, import("./verse-metre.mjs").MetreBook> | undefined;
+    /**
+     * - An indexed wikilink target's visible name.
+     */
+    referenceName?: ((target: string) => string | undefined) | undefined;
     /**
      * -
      * Exact Roman source inventories by configured alias and BCP 47 tag.

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

@@ -37,12 +37,13 @@ export function scanVerse(source: string, { checkWorks }?: {
  * Offsets are UTF-16 positions relative to body. Delimiters and indentation are
  * layout ranges; source newlines inside a logical line contribute one space.
  * @param {string} body - Authored verse body.
- * @param {{inline?: boolean, footnotes?: ReadonlySet<string>}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>, sourceOffsets?: number[]}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels; sourceOffsets maps projected body positions to authored offsets, including the end.
  * @returns {VerseModel} The shared structure with offsets relative to the body.
  */
-export function parseVerse(body: string, { inline, footnotes }?: {
+export function parseVerse(body: string, { inline, footnotes, sourceOffsets }?: {
     inline?: boolean;
     footnotes?: ReadonlySet<string>;
+    sourceOffsets?: number[];
 }): VerseModel;
 /**
  * Validate a quoted verse span using its original source coordinates.
@@ -271,6 +272,14 @@ export type VerseBlock = {
      * - Authored verse body.
      */
     body: string;
+    /**
+     * - Body without Markdown container prefixes.
+     */
+    logicalBody: string;
+    /**
+     * - Logical UTF-16 offsets mapped to authored body offsets, including the end.
+     */
+    bodyOffsets: number[];
     /**
      * - Logical structure relative to the body.
      */

package/types/engine/core-report.d.mts

@@ -4,7 +4,7 @@
  * @param {Iterable<Record<string, any>>} records - Index records.
  * @param {{language?: string}} [options] - A language to report alone, by its
  *   name, shortcode or reference slug whether or not it states `data.core`.
- * @returns {{concepts: number, languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
+ * @returns {{concepts: number, notCovered: string[], languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
  *   The report, or the problem when there is no concept list or the language
  *   asked for is none.
  */
@@ -12,6 +12,7 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
     language?: string;
 }): {
     concepts: number;
+    notCovered: string[];
     languages: Array<{
         name: string;
         language: string;
@@ -36,10 +37,13 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
  * A core report as text: one block per language, its missing concepts under
  * their groups with counts, each concept's id and gloss tab-separated.
  *
- * @param {{concepts: number, languages: Array<object>}} report - A report from {@link coreReport}.
+ * The default report ends with the names of languages it does not measure.
+ *
+ * @param {{concepts: number, notCovered: string[], languages: Array<object>}} report - A report from {@link coreReport}.
  * @returns {string} The text, ending in a newline.
  */
 export function coreReportText(report: {
     concepts: number;
+    notCovered: string[];
     languages: Array<object>;
 }): string;

package/types/engine/culture-reach.d.mts

@@ -42,6 +42,9 @@ export function noteTerms(index: object, note: object, entry?: object): Map<stri
  * in a tree that describes peoples. Its ranks and offices then have no
  * culture associations for term queries.
  *
+ * The note's `data.culture` is the culture the content index resolved for it:
+ * its own, else the one its `data.parents` chain agrees on.
+ *
  * @param {object} note - An `affiliation` note.
  * @param {{index?: object}} [context]
  * @returns {object[]} One warning, at the note's `type`, or none.

package/types/engine/declared-sections.d.mts

@@ -0,0 +1,30 @@
+/** Authored headings, excluding literal examples and named containers. */
+export function declaredHeadings(markdown: any, syntax: any): {
+    level: number;
+    line: number;
+    text: string;
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+}[];
+/**
+ * Insert indexed content at its heading while preserving subsequent source lines.
+ * @param {string} markdown - Expanded body.
+ * @param {Array<{slug:string,heading:string,markdown:string}>} [sections] - Declared content.
+ * @param {{authored?:string,lineMap?:object[],generatedFrom?:number,syntax?:Function}} [context] - Captured source mappings.
+ * @returns {{markdown:string,lineMap:object[],generatedFrom?:number}} Expanded body and locations.
+ */
+export function insertDeclaredSections(markdown: string, sections?: Array<{
+    slug: string;
+    heading: string;
+    markdown: string;
+}>, { authored, lineMap, generatedFrom, syntax }?: {
+    authored?: string;
+    lineMap?: object[];
+    generatedFrom?: number;
+    syntax?: Function;
+}): {
+    markdown: string;
+    lineMap: object[];
+    generatedFrom?: number;
+};

package/types/engine/derived-sections.d.mts

@@ -51,15 +51,19 @@ export function drawMapsFrom(records: object[], { outDir, foreignIndex, config,
  *   prepared results are keyed.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes.
  * @param {object} [opts.config] - The resolved configuration.
+ * @param {(file:string)=>string|undefined} [opts.rawOf] - Captured source locators.
+ * @param {object[]} [opts.all=records] - Complete records for settlement validation.
  * @param {string} [opts.only] - One note file to give sections to; absent,
  *   every note.
  * @returns {Map<string, Map<string, string>>} Note file to its sections, each
  *   keyed by its slug, for every note given at least one.
  */
-export function derivedSections(records: object[], { fileOf, foreignIndex, config, only }: {
+export function derivedSections(records: object[], { fileOf, foreignIndex, config, only, rawOf, all }: {
     fileOf: (record: object) => string;
     foreignIndex?: Map<string, object> | undefined;
     config?: object | undefined;
+    rawOf?: ((file: string) => string | undefined) | undefined;
+    all?: object[] | undefined;
     only?: string | undefined;
 }): Map<string, Map<string, string>>;
 /**