@heroiclands/package-build 25.3.0 → 25.4.0

package/engine/verse-regions.mjs

@@ -0,0 +1,181 @@
+/*
+ * 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
+ */
+
+import MarkdownIt from "markdown-it";
+import { WIKILINK } from "./wikilink-pattern.mjs";
+import { parseExtensionAttributes } from "./extension-attributes.mjs";
+
+/**
+ * A raw verse div, opaque to ordinary Markdown block syntax.
+ * @typedef {object} VerseRegion
+ * @property {number} start - Opening line, zero based.
+ * @property {number} end - Closing line, zero based and inclusive.
+ * @property {number} from - First offset of the complete region.
+ * @property {number} to - Offset past the complete region.
+ * @property {number} bodyStart - First body offset.
+ * @property {number} bodyEnd - Offset past body text, excluding its final newline.
+ * @property {string} body - Authored body bytes.
+ * @property {Record<string,string>} attributes - Authored values.
+ * @property {string} id - Anchor or empty string.
+ * @property {string[]} classes - Authored classes including verse.
+ * @property {string} indent - Opening indentation.
+ * @property {"verse"} name - Region kind.
+ * @property {boolean} closed - Whether a closing delimiter is present.
+ * @property {string[]} problems - Attribute syntax findings.
+ */
+
+/** Recognize an opener without interpreting its body as Markdown blocks. */
+function opener(line) {
+    const named = /^ *:::verse(?:[ \t]+(.*))?$/.exec(line);
+    const generic = /^ *:::[ \t]+(\{.*)$/.exec(line);
+    if (!named && !generic) return undefined;
+    const raw = (named?.[1] ?? generic?.[1] ?? "").trim();
+    const braced = /^\{[^\n]*\}$/.test(raw);
+    const parsed = parseExtensionAttributes(braced ? raw.slice(1, -1) : raw.replace(/^\{/, ""));
+    if (!named && !parsed.classes.includes("verse")) return undefined;
+    if (raw && !braced) parsed.problems.push("verse div attributes need {…} braces");
+    if (!parsed.classes.includes("verse")) parsed.classes.unshift("verse");
+    return parsed;
+}
+
+/**
+ * Install the opaque verse-div block rule. Tokens carry raw source regions.
+ * @param {import("markdown-it")} md - Markdown parser.
+ */
+export function verseDivPlugin(md) {
+    md.block.ruler.before(
+        "code",
+        "verse_div",
+        (state, first, past, silent) => {
+            if (state.sCount[first] - state.blkIndent >= 4) return false;
+            const line = state.src.slice(
+                state.bMarks[first] + state.tShift[first],
+                state.eMarks[first],
+            );
+            const parsed = opener(line);
+            if (!parsed) return false;
+            if (silent) return true;
+            let close = first + 1;
+            while (close < past) {
+                const text = state.src.slice(
+                    state.bMarks[close] + state.tShift[close],
+                    state.eMarks[close],
+                );
+                if (/^ *:::[ \t]*$/.test(text)) break;
+                close++;
+            }
+            const closed = close < past;
+            const original = state.env.verseSource ?? state.src;
+            const rawLines = original.split(/\r\n|\r|\n/);
+            const starts = [0];
+            for (const match of original.matchAll(/\r\n|\r|\n/g))
+                starts.push(match.index + match[0].length);
+            const from = starts[first] ?? original.length;
+            const bodyStart = starts[first + 1] ?? original.length;
+            let bodyEnd = starts[close] ?? original.length;
+            if (bodyEnd > bodyStart) {
+                if (original[bodyEnd - 1] === "\n") bodyEnd--;
+                if (original[bodyEnd - 1] === "\r") bodyEnd--;
+            }
+            const region = {
+                start: first,
+                end: closed ? close : past - 1,
+                from,
+                to: starts[closed ? close + 1 : past] ?? original.length,
+                bodyStart,
+                bodyEnd,
+                body: original.slice(bodyStart, bodyEnd),
+                attributes: parsed.values,
+                id: parsed.id,
+                classes: parsed.classes,
+                indent: /^ */.exec(rawLines[first] ?? "")[0],
+                name: "verse",
+                closed,
+                problems: parsed.problems,
+            };
+            const token = state.push("verse_div", "div", 0);
+            token.block = true;
+            token.map = [first, closed ? close + 1 : past];
+            token.content = region.body;
+            token.meta = { verseRegion: region };
+            state.line = closed ? close + 1 : past;
+            return true;
+        },
+        { alt: ["paragraph", "reference", "blockquote", "list"] },
+    );
+}
+
+const parser = new MarkdownIt({ html: true }).use(verseDivPlugin);
+parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
+
+/**
+ * Locate complete raw verse divs while leaving literal examples untouched.
+ * @param {string} source - Authored Markdown.
+ * @returns {VerseRegion[]} Regions in source order, including unclosed divs.
+ */
+export function verseRegions(source) {
+    return parser
+        .parse(source, { verseSource: source })
+        .filter((token) => token.type === "verse_div")
+        .map((token) => token.meta.verseRegion);
+}
+
+/**
+ * Source ranges belonging to inline syntax rather than visible verse text.
+ * @param {string} source - Inline Markdown.
+ * @returns {Array<[number,number]>} Protected UTF-16 ranges.
+ */
+export function inlineSyntaxRanges(source) {
+    const ranges = [];
+    for (const match of source.matchAll(new RegExp(WIKILINK.source, "g"))) {
+        const separator = match[0].indexOf("|");
+        const close = match[0].indexOf("]]");
+        ranges.push([match.index, match.index + (separator < 0 ? close + 2 : separator + 1)]);
+        ranges.push([match.index + close, match.index + match[0].length]);
+    }
+    for (let at = 0; at < source.length; at++) {
+        if (source[at] === "\\") {
+            at++;
+            continue;
+        }
+        const char = source[at];
+        let past = -1;
+        if (char === "⟦") past = source.indexOf("⟧", at + 1) + 1;
+        else if (char === "`") {
+            const mark = /^`+/.exec(source.slice(at))[0];
+            const close = source.indexOf(mark, at + mark.length);
+            if (close >= 0) past = close + mark.length;
+        } else if (source.startsWith("<!--", at)) past = source.indexOf("-->", at + 4) + 3;
+        else if (char === "<") past = source.indexOf(">", at + 1) + 1;
+        else if (char === "{") past = source.indexOf("}", at + 1) + 1;
+        else if (char === "(" && source[at - 1] === "]") {
+            let depth = 1;
+            for (let next = at + 1; next < source.length; next++) {
+                if (source[next] === "\\") {
+                    next++;
+                    continue;
+                }
+                if (source[next] === "(") depth++;
+                if (source[next] === ")" && !--depth) {
+                    past = next + 1;
+                    break;
+                }
+            }
+        }
+        if (past > at) {
+            ranges.push([at, past]);
+            at = past - 1;
+        }
+    }
+    return ranges.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+}

package/engine/wikilink-pattern.mjs

@@ -0,0 +1,31 @@
+/*
+ * 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
+ */
+
+/** The dependency-free lexical wikilink pattern. @module */
+
+/**
+ * A wikilink, as authored.
+ *
+ * **Newlines are excluded deliberately.** A link is written on one line; an
+ * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
+ * prose in search of a closer. Erring towards "not a link" leaves the author's
+ * text as written, which is the safe direction for a rewriter.
+ *
+ * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
+ * keeps every reader from seeing one as the other. Stated here rather than in
+ * each reader for the reason the rest of this module exists: the checker, the
+ * resolver and the embed reader all match on this pattern, and a copy of the
+ * exclusion in each is a place for it to be forgotten. An embed's
+ * own grammar is {@link module:engine/content-embeds}.
+ */
+export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\](?:\{(?:[^{}"\n]|"(?:\\.|[^"\\\n])*")*\})?/g;

package/engine/wikilink-syntax.mjs

@@ -42,22 +42,8 @@ import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
  * @module
  */
 
-/**
- * A wikilink, as authored.
- *
- * **Newlines are excluded deliberately.** A link is written on one line; an
- * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
- * prose in search of a closer. Erring towards "not a link" leaves the author's
- * text as written, which is the safe direction for a rewriter.
- *
- * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
- * keeps every reader from seeing one as the other. Stated here rather than in
- * each reader for the reason the rest of this module exists: the checker, the
- * resolver and the embed reader all match on this pattern, and a copy of the
- * exclusion in each is a place for it to be forgotten. An embed's
- * own grammar is {@link module:engine/content-embeds}.
- */
-export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\](?:\{(?:[^{}"\n]|"(?:\\.|[^"\\\n])*")*\})?/g;
+import { WIKILINK } from "./wikilink-pattern.mjs";
+export { WIKILINK } from "./wikilink-pattern.mjs";
 
 /**
  * The parts of a wikilink's interior.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.3.0",
+    "version": "25.4.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",

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

@@ -1384,6 +1384,30 @@ a.tag:hover {
     margin: 0;
 }
 
+/* A quotation stays within its prose paragraph; canto titles retain heading type. */
+.single-content .verse.verse-inline {
+    display: inline-block;
+    vertical-align: baseline;
+    max-inline-size: 100%;
+    margin: 0;
+    container-type: normal;
+}
+.single-content .verse.verse-inline .verse-stanza {
+    display: block;
+    margin: 0;
+}
+.single-content .verse.verse-inline .verse-stanza + .verse-stanza {
+    margin-top: 0.5em;
+}
+.single-content .verse .verse-canto-heading {
+    display: block;
+    margin: 0.5em 0;
+    font-family: var(--font-display);
+    font-size: 1.1em;
+    font-weight: bold;
+    line-height: 1.3;
+}
+
 /* Logical stanzas share labels across native and Roman presentations. */
 .single-content .verse {
     margin: 1.5rem 0;

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

@@ -17,13 +17,11 @@ 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.verseAsProse=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, verseAsProse }?: {
+export function codeRegions(markdown: string | null | undefined, { spans }?: {
     spans?: boolean | undefined;
-    verseAsProse?: boolean | undefined;
 }): Array<{
     start: number;
     end: number;

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

@@ -81,6 +81,29 @@ export function footnoteFindings(source: string): Array<{
     column: number;
     message: string;
 }>;
+/**
+ * Labels defined at the top level of this note.
+ * @param {string} source - Complete authored note Markdown.
+ * @returns {Set<string>} Same-note footnote labels.
+ */
+export function footnoteLabels(source: string): Set<string>;
+/**
+ * Actual defined references, excluding literal code, escapes and metadata.
+ * @param {string} source - Full note or raw inline fragment.
+ * @param {object} [options] - Definition context and source grammar.
+ * @param {ReadonlySet<string>} [options.definitions] - Same-note labels; derived from source when omitted.
+ * @param {boolean} [options.inline] - Treat all source as inline verse/prose.
+ * @returns {Array<{from:number,to:number,key:string,text:string}>} Original UTF-16 source ranges.
+ */
+export function footnoteReferences(source: string, { definitions, inline }?: {
+    definitions?: ReadonlySet<string> | undefined;
+    inline?: boolean | undefined;
+}): Array<{
+    from: number;
+    to: number;
+    key: string;
+    text: string;
+}>;
 /**
  * A footnote reference's shape, wherever it is written — excluding a
  * definition's own `[^id]:` opener, which this never matches.

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

@@ -18,7 +18,7 @@ export function runContext(config: {
     };
 } | undefined, records?: Iterable<Record<string, any>>): RunContext;
 /**
- * Find the spans, divs and verse fences marked with `lang=`, `font=` or
+ * Find the spans, divs and verse divs marked with `lang=`, `font=` or
  * `enc=`, and every fault in their markup and their text.
  *
  * @param {string} source - Authored Markdown: a note body, or a whole file
@@ -80,7 +80,7 @@ export function scanRuns(source: string, ctx?: RunContext, syntax?: import("./co
  *   scanner projections.
  * @param {{target?: "site"|"foundry"|"book"}} [options] - The target the
  *   Markdown is rendered for; only `site` writes the search marker.
- * @returns {{markdown: string, errors: Array<{file?: string, line: number, column: number, message: string}>, scrolls: Map<string, import("./content-scroll.mjs").ScrollLayout>, verses: Map<string, {model: ReturnType<typeof import("./content-verse.mjs").parseVerse>, classes: string[], attributes: Record<string, string>}>}}
+ * @returns {{markdown: string, errors: Array<{file?: string, line: number, column: number, message: string}>, scrolls: Map<string, import("./content-scroll.mjs").ScrollLayout>, verses: Map<string, {model: ReturnType<typeof import("./content-verse.mjs").parseVerse>, classes: string[], attributes: Record<string, string>, inline: boolean}>}}
  *   The rewritten Markdown, the findings of {@link scanRuns}, and each
  *   rewritten scroll fence's layout, by its rewritten body.
  */
@@ -99,6 +99,7 @@ export function renderRuns(source: string, ctx?: RunContext, syntax?: import("./
         model: ReturnType<typeof import("./content-verse.mjs").parseVerse>;
         classes: string[];
         attributes: Record<string, string>;
+        inline: boolean;
     }>;
 };
 /** The keys this module reads, which no construct passes through as written. */
@@ -350,7 +351,7 @@ export type RunContext = {
     directions?: ReadonlyMap<string, "vertical-rl"> | undefined;
 };
 /**
- * One span, div, verse fence or scroll fence carrying run attributes.
+ * One span, div, verse div or scroll fence carrying run attributes.
  * Values combine explicit choices, class-only inheritance, encoding-document
  * language/font defaults and the Roman default encoding.
  */

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

@@ -3,10 +3,12 @@
  * @param {object} [options] - Surface presentation.
  * @param {boolean} [options.source] - Emit opaque authored source tokens for buffer preview.
  * @param {boolean} [options.spoilers] - Add focusable CSS spoiler wrappers (Foundry).
+ * @param {(token: any, state: any) => void} [options.verseInline] - Populate an opaque quoted-verse token during inline parsing.
  */
-export function spanMarkdownPlugin(md: typeof import("markdown-it"), { spoilers, source }?: {
+export function spanMarkdownPlugin(md: typeof import("markdown-it"), { spoilers, source, verseInline }?: {
     source?: boolean | undefined;
     spoilers?: boolean | undefined;
+    verseInline?: ((token: any, state: any) => void) | undefined;
 }): void;
 /** Read span anchors and located attribute diagnostics outside literal code.
  * @param {string} source - Authored Markdown.

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

@@ -20,11 +20,11 @@ export function inlineVerse(text: any): string;
  * @returns {boolean} Whether it starts right to left.
  */
 export function rightToLeft(text: string): boolean;
-/** Read verse code fences; start/end are inclusive zero-based source lines.
+/** Read verse divs; start/end are inclusive zero-based source lines.
  * @param {string} source - Authored Markdown.
  * @param {object} [options] - Whole-page validation choices.
  * @param {boolean} [options.checkWorks] - Whether to validate page-local versions.
- * @returns {{blocks: VerseBlock[], errors: VerseDiagnostic[]}} Located fences and findings.
+ * @returns {{blocks: VerseBlock[], errors: VerseDiagnostic[]}} Located divs and findings.
  */
 export function scanVerse(source: string, { checkWorks }?: {
     checkWorks?: boolean | undefined;
@@ -32,68 +32,29 @@ export function scanVerse(source: string, { checkWorks }?: {
     blocks: VerseBlock[];
     errors: VerseDiagnostic[];
 };
-/**
- * A logical line with its authored UTF-16 coordinates.
- * @typedef {object} VerseLine
- * @property {string} text - Inline Markdown in this presentation.
- * @property {number} level - Leading-period indentation depth.
- * @property {number} from - First authored offset, including indentation.
- * @property {number} to - Offset at the line ending.
- * @property {number[]} offsets - Source offset for each UTF-16 text unit.
- * @property {string} [romanText] - Roman text paired with an encoded line.
- */
-/**
- * A stanza's logical lines and authored bounds.
- * @typedef {object} VerseStanza
- * @property {VerseLine[]} lines - Lines in reading order.
- * @property {number} from - First authored offset.
- * @property {number} to - Offset at the stanza ending.
- */
-/**
- * @typedef {VerseStanza & {canto: number, stanza: number, label: string, cantoBreak?: false}} VerseTextGroup
- * @typedef {{cantoBreak: true, from: number, to: number, text?: string}} VerseCantoBreak
- * @typedef {{kind: "line"|"stanza"|"canto", sourceOffset: number}} VerseBoundary
- * @typedef {{offset: number, message: string}} VerseFinding
- */
-/**
- * Shared authored verse structure and source locations.
- * @typedef {object} VerseModel
- * @property {Array<{stanzas: VerseStanza[]}>} cantos - Cantos in reading order.
- * @property {Array<VerseTextGroup|VerseCantoBreak>} groups - Stanzas and canto breaks.
- * @property {VerseBoundary[]} boundaries - Explicit authored boundaries.
- * @property {Array<[number, number]>} layout - Source ranges omitted from encoded letters.
- * @property {VerseFinding[]} errors - Findings relative to the fence body.
- */
-/**
- * An authored verse fence with its parsed logical structure.
- * @typedef {object} VerseBlock
- * @property {number} start - Opening fence's zero-based source line.
- * @property {number} end - Closing fence's zero-based source line.
- * @property {string} fence - Authored fence delimiter.
- * @property {"verse"} name - Fence language.
- * @property {Record<string, string>} attributes - Authored attribute values.
- * @property {string} id - Authored anchor, or the empty string.
- * @property {string[]} classes - Authored presentation classes.
- * @property {string} indent - Opening fence's leading spaces.
- * @property {string} body - Authored fence body.
- * @property {VerseModel} model - Logical structure relative to the body.
- */
-/** @typedef {{line: number, column: number, message: string}} VerseDiagnostic */
-/**
- * An encoded verse's shared display model and native-cell presentation.
- * @typedef {object} VersePresentation
- * @property {VerseModel} model - Logical structure with paired line text.
- * @property {string[]} classes - Native script and font classes.
- * @property {Record<string, string>} attributes - Native language, direction and search attributes.
- */
 /**
  * Parse logical verse lines, stanzas and cantos without losing authored offsets.
  * 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 fence body.
+ * @param {string} body - Authored verse body.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels.
  * @returns {VerseModel} The shared structure with offsets relative to the body.
  */
-export function parseVerse(body: string): VerseModel;
+export function parseVerse(body: string, { inline, footnotes }?: {
+    inline?: boolean;
+    footnotes?: ReadonlySet<string>;
+}): VerseModel;
+/**
+ * Validate a quoted verse span using its original source coordinates.
+ * @param {{start: number, text: string, attrs: Array<[string,string]>}} span - Authored span.
+ * @param {string} source - Complete Markdown source.
+ * @returns {VerseDiagnostic[]} Located inline-only findings.
+ */
+export function inlineVerseFindings(span: {
+    start: number;
+    text: string;
+    attrs: Array<[string, string]>;
+}, source: string): VerseDiagnostic[];
 /** Logical line text for consumers that do not need source locations. */
 export function verseLines(body: any): string[];
 /** Paragraph groups with separate canto gaps. */
@@ -103,27 +64,29 @@ export function verseStanzas(body: any): {
 }[][];
 /**
  * Compare the stanza counts of each version of a page-local work.
- * @param {VerseBlock[]} blocks - Fences belonging to one page.
- * @returns {VerseDiagnostic[]} Findings at affected opening fences.
+ * @param {VerseBlock[]} blocks - Divs belonging to one page.
+ * @returns {VerseDiagnostic[]} Findings at affected opening divs.
  */
 export function workShapeFindings(blocks: VerseBlock[]): VerseDiagnostic[];
 /**
  * Render a shared verse structure while preserving surrounding inline Markdown.
- * @param {string} body - Authored fence body.
+ * @param {string} body - Authored verse body.
  * @param {object} [options] - Shared structure and display choices.
  * @param {boolean} [options.labelled] - Whether each stanza carries its label.
  * @param {VerseModel} [options.model] - Parsed structure; defaults to parsing the body.
  * @param {VersePresentation} [options.presentation] - Native-cell font and language.
+ * @param {boolean} [options.inline] - Whether wrappers must remain inline-safe.
  * @returns {string} Markdown with verse layout wrappers.
  */
-export function verseMarkdown(body: string, { labelled, model, presentation }?: {
+export function verseMarkdown(body: string, { labelled, model, presentation, inline }?: {
     labelled?: boolean | undefined;
     model?: VerseModel | undefined;
     presentation?: VersePresentation | undefined;
+    inline?: boolean | undefined;
 }): string;
 /**
- * Replace verse fences with wrappers whose bodies remain inline Markdown.
- * @param {string} source - Markdown containing verse fences.
+ * Replace verse divs with wrappers whose bodies remain inline Markdown.
+ * @param {string} source - Markdown containing verse divs.
  * @param {object} [options] - Encoded display models.
  * @param {Map<string, VersePresentation>} [options.verses] - Presentations keyed by rewritten body.
  */
@@ -133,7 +96,13 @@ export function renderVerse(source: string, { verses }?: {
     markdown: string;
     errors: VerseDiagnostic[];
 };
-/** The authored attributes of a verse fence. */
+/**
+ * Render quoted verse with inline-safe wrappers and shared logical structure.
+ * @param {string} source - Markdown after block verse rendering.
+ * @returns {string} Markdown retaining surrounding prose.
+ */
+export function renderVerseQuotes(source: string): string;
+/** The authored attributes of a verse div. */
 export const VERSE_KEYS: readonly string[];
 /** A canto separator, including the escaped form produced by a native run. */
 export const STANZA_BREAK: RegExp;
@@ -195,6 +164,8 @@ export type VerseCantoBreak = {
     from: number;
     to: number;
     text?: string;
+    id?: string;
+    title?: string;
 };
 export type VerseBoundary = {
     kind: "line" | "stanza" | "canto";
@@ -227,28 +198,52 @@ export type VerseModel = {
      */
     layout: Array<[number, number]>;
     /**
-     * - Findings relative to the fence body.
+     * - Findings relative to the verse body.
      */
     errors: VerseFinding[];
+    /**
+     * - Defined references without substantive verse text.
+     */
+    notes: VerseLine[];
 };
 /**
- * An authored verse fence with its parsed logical structure.
+ * An authored verse div with its parsed logical structure.
  */
 export type VerseBlock = {
     /**
-     * - Opening fence's zero-based source line.
+     * - Opening div's zero-based source line.
      */
     start: number;
     /**
-     * - Closing fence's zero-based source line.
+     * - Closing div's zero-based source line.
      */
     end: number;
     /**
-     * - Authored fence delimiter.
+     * - Complete div first offset.
+     */
+    from: number;
+    /**
+     * - Offset past complete div.
+     */
+    to: number;
+    /**
+     * - First body offset.
+     */
+    bodyStart: number;
+    /**
+     * - Offset past body text.
+     */
+    bodyEnd: number;
+    /**
+     * - Whether the closing delimiter exists.
+     */
+    closed: boolean;
+    /**
+     * - Attribute syntax findings.
      */
-    fence: string;
+    problems: string[];
     /**
-     * - Fence language.
+     * - Region name.
      */
     name: "verse";
     /**
@@ -264,11 +259,11 @@ export type VerseBlock = {
      */
     classes: string[];
     /**
-     * - Opening fence's leading spaces.
+     * - Opening div's leading spaces.
      */
     indent: string;
     /**
-     * - Authored fence body.
+     * - Authored verse body.
      */
     body: string;
     /**

package/types/engine/name-markup.d.mts

@@ -26,6 +26,7 @@
  * @property {string} visible - Visible text from the actual parsed children.
  * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
  * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ * @property {ReturnType<typeof import("./content-verse.mjs").parseVerse>} [verseModel] - Logical model of an inline verse quotation.
  */
 /**
  * One located span-grammar or refused-attribute finding.
@@ -139,6 +140,10 @@ export type ContentSpan = {
      * - Authored key/value sites by retained attribute name.
      */
     attributePositions: Record<string, SpanAttributePosition>;
+    /**
+     * - Logical model of an inline verse quotation.
+     */
+    verseModel?: import("./content-verse.mjs").VerseModel | undefined;
 };
 /**
  * One located span-grammar or refused-attribute finding.

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

@@ -0,0 +1,9 @@
+/**
+ * Replace verse markup with opaque placeholders and restore its original bytes.
+ * @param {string} source - Complete Markdown source.
+ * @returns {{markdown: string, restore: (formatted: string) => string}} Protected source and exact restoration.
+ */
+export function protectVerseSource(source: string): {
+    markdown: string;
+    restore: (formatted: string) => string;
+};

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

@@ -60,7 +60,7 @@ export function lineBeats(text: string, book: MetreBook): {
  * The warning for a line that cannot have its metre's beats.
  *
  * @param {{min: number, max: number}} beats - The line's beats.
- * @param {import("./metre-declaration.mjs").Metre} metre - The fence's metre.
+ * @param {import("./metre-declaration.mjs").Metre} metre - The div's metre.
  * @returns {string} The message.
  */
 export function metreMessage({ min, max }: {
@@ -68,13 +68,13 @@ export function metreMessage({ min, max }: {
     max: number;
 }, metre: import("./metre-declaration.mjs").Metre): string;
 /**
- * Check the verse fences that state `scan=`.
+ * Check the verse divs that state `scan=`.
  *
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
- *   The fences, from {@link module:engine/content-verse.scanVerse}.
+ *   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 -
- *   The metres and books, and how the fence says its columns and where its
+ *   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
  *   positions.