@heroiclands/package-build 25.3.0 → 25.5.0

package/engine/pdf-render.mjs

@@ -86,7 +86,7 @@ import { scanSpans } from "./content-spans.mjs";
 import { GENERIC_FONTS, renderRuns, scanRuns } from "./content-scripts.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
-import { rightToLeft, scanVerse } from "./content-verse.mjs";
+import { rightToLeft } from "./content-verse.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { panelRoman, scanScrolls, scrollPanels, scrollParagraphs } from "./content-scroll.mjs";
 import { BOOK_INK, BOOK_RUBRIC, fontOutlines, scrollPanelSvg } from "./font-outlines.mjs";
@@ -499,7 +499,7 @@ export function markdownToTypst(markdown, opts = {}) {
     const given = opts.nested ? String(markdown ?? "") : stripHtmlComments(markdown);
     const separated = opts.footnoteDefinitions === undefined ? separateFootnotes(given) : null;
     const authored = separated?.markdown ?? given;
-    const definitions = opts.footnoteDefinitions ?? separated?.definitions ?? "";
+    let definitions = opts.footnoteDefinitions ?? separated?.definitions ?? "";
     const footnoteState = opts.footnoteState ?? { seen: new Set() };
     const sharedOptions = {
         ...opts,
@@ -513,10 +513,16 @@ export function markdownToTypst(markdown, opts = {}) {
     // Text marked with a language, a font or a map is rewritten once, ahead of
     // every other pass, line for line; the nested calls below read the result,
     // and the scroll fences' layouts the rewrite returns.
+    const markingSource = definitions ? `${authored}\n\n${definitions}` : authored;
     const marked =
-        opts.nested ? undefined : renderRuns(authored, opts.runs, undefined, { target: "book" });
-    const source = marked ? marked.markdown : authored;
+        opts.nested ? undefined : (
+            renderRuns(markingSource, opts.runs, undefined, { target: "book" })
+        );
+    const markedFootnotes = marked && definitions ? separateFootnotes(marked.markdown) : undefined;
+    const source = markedFootnotes?.markdown ?? marked?.markdown ?? authored;
+    if (markedFootnotes) definitions = markedFootnotes.definitions;
     if (marked) {
+        sharedOptions.footnoteDefinitions = definitions;
         sharedOptions.scrolls = marked.scrolls;
         sharedOptions.verses = marked.verses;
     }
@@ -775,22 +781,14 @@ function renderBlock(tokens, i, out, ctx) {
                 out.push(scrollBlock(token, ctx));
                 return 1;
             }
-            if (token.type === "fence" && /^verse(?:\s|$)/.test(token.info?.trim() || "")) {
-                const opening = `${token.markup}${token.info}`;
-                const scanned = scanVerse(`${opening}\n${token.content}${token.markup}`, {
-                    checkWorks: false,
-                });
-                // Findings are collected before rendering. Keep malformed verse
-                // literal rather than assigning invalid parts to display cells.
-                if (scanned.errors.length && !token.meta?.versePaired) {
-                    out.push(rawBlock(token.content, token.info));
-                    return 1;
-                }
-                const poem = scanned.blocks[0];
-                const content = workVerse(token, poem, ctx);
-                const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
-                out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
-            } else out.push(rawBlock(token.content, token.info?.trim() || ""));
+            out.push(rawBlock(token.content, token.info?.trim() || ""));
+            return 1;
+        }
+        case "verse_div": {
+            const poem = token.meta.verse;
+            const content = workVerse(token, poem, ctx);
+            const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
+            out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
             return 1;
         }
         case "hr":
@@ -1286,15 +1284,20 @@ const FONT_CLASSES = Object.freeze(["script", ...Object.values(GENERIC_FONTS)]);
 /** The logical lines of one stanza, with a shared label and paired scripts. */
 function workVerse(token, poem, ctx) {
     const paired = token.meta.versePaired;
-    const labelled = Boolean(poem?.attributes.work);
+    const labelled = token.type !== "verse_inline" && Boolean(poem?.attributes.work);
     const nativeClasses = paired?.classes ?? poem?.classes;
     const nativeAttributes = paired?.attributes ?? poem?.attributes;
-    return (token.meta.verseGroups ?? [])
+    const body = (token.meta.verseGroups ?? [])
         .map((group) => {
             if (group.cantoBreak) {
                 const mark =
                     group.children?.length ? renderInline({ children: group.children }, ctx) : "";
-                return `${mark ? scriptWrapped(mark, nativeClasses, nativeAttributes) + "\n" : ""}#v(0.5em)`;
+                const heading =
+                    group.titleChildren?.length ?
+                        `#heading(level: 3, outlined: false, bookmarked: false)[${renderInline({ children: group.titleChildren }, ctx)}]`
+                    :   "";
+                const anchor = group.id ? ` <${sectionLabel(ctx.anchorPrefix, group.id)}>` : "";
+                return `${mark ? scriptWrapped(mark, nativeClasses, nativeAttributes) + "\n" : ""}#v(0.5em)${heading ? "\n" + heading : ""}${anchor}`;
             }
             const label = labelled ? `#text(size: 0.75em, fill: luma(45%))[${group.label}]` : "";
             const lineText = (line, roman = false) => {
@@ -1328,6 +1331,8 @@ function workVerse(token, poem, ctx) {
             return `#set text(dir: ltr)\n#grid(columns: (${columns}), column-gutter: 1.5em, row-gutter: 0.35em,\n  ${cells.join(",\n  ")}\n)`;
         })
         .join("\n\n");
+    const notes = (token.meta.verseNotes ?? []).map((line) => renderInline(line, ctx)).join("");
+    return body + notes;
 }
 
 /**
@@ -1374,6 +1379,12 @@ function renderInline(token, ctx) {
             case "code_inline":
                 out.push(inlineRaw(child.content));
                 break;
+            case "verse_inline": {
+                const content = workVerse(child, child.meta.verse, ctx);
+                const id = child.attrGet?.("id");
+                out.push(`#box[${content}]${id ? ` <${sectionLabel(ctx.anchorPrefix, id)}>` : ""}`);
+                break;
+            }
             case "span_open": {
                 if (["em", "strong"].includes(child.tag)) {
                     const classes = (child.attrGet?.("class") ?? "").split(/\s+/);

package/engine/prose-lint.mjs

@@ -35,6 +35,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { formatNoteFrontmatter } from "./note-format.mjs";
+import { protectVerseSource } from "./verse-format.mjs";
 
 import {
     MARKDOWNLINT_CONFIG,
@@ -161,6 +162,17 @@ export async function checkFormatting(root, opts = {}) {
             }
         }
 
+        const format = async (input) => {
+            const protectedSource =
+                ["markdown", "mdx"].includes(info.inferredParser) ?
+                    protectVerseSource(input)
+                :   undefined;
+            const output = await prettier.format(protectedSource?.markdown ?? input, options);
+            return formatNoteFrontmatter(
+                protectedSource ? protectedSource.restore(output) : output,
+            );
+        };
+
         // A file Prettier cannot parse is a finding, not a crash. Its own CLI
         // reports the syntax error and carries on to the next file, and a
         // single unparseable file in a large tree must not cost the report on
@@ -172,7 +184,7 @@ export async function checkFormatting(root, opts = {}) {
                 let formatted = source;
                 let converged = false;
                 for (let pass = 0; pass < MAX_FORMAT_PASSES; pass += 1) {
-                    const next = formatNoteFrontmatter(await prettier.format(formatted, options));
+                    const next = await format(formatted);
                     if (next === formatted) {
                         converged = true;
                         break;
@@ -206,7 +218,7 @@ export async function checkFormatting(root, opts = {}) {
                 continue;
             }
 
-            if (formatNoteFrontmatter(await prettier.format(source, options)) !== source) {
+            if ((await format(source)) !== source) {
                 findings.push({
                     file,
                     severity: "error",

package/engine/roman-characters.mjs

@@ -121,15 +121,25 @@ export function romanTextProblems(text, inventory) {
     );
     const quotes = [];
     let sentenceStart = true;
+    const sentenceText = () => {
+        sentenceStart = false;
+        if (quotes.length) quotes.at(-1).hasText = true;
+    };
     const report = (offset, message) => out.push({ offset, message });
     for (let offset = 0; offset < text.length;) {
         const char = String.fromCodePoint(text.codePointAt(offset));
+        // Verse retains this escape so the encoder can distinguish a literal
+        // slash from its line control. The slash itself is standard Roman.
+        if (text.startsWith("\\/", offset)) {
+            offset++;
+            continue;
+        }
         if (char === "⟦") {
             // The encoding validates codage and its boundary grammar. Roman
             // punctuation and language letters never reinterpret its contents.
             const close = text.indexOf("⟧", offset + 1);
             offset = close < 0 ? text.length : close + 1;
-            sentenceStart = false;
+            sentenceText();
             continue;
         }
         const cluster = decomposed.get(offset);
@@ -139,16 +149,25 @@ export function romanTextProblems(text, inventory) {
                 `\`${cluster}\` is not NFC spelling in \`${inventory.language}\`; write \`${cluster.normalize("NFC")}\``,
             );
             offset += cluster.length;
-            sentenceStart = false;
+            sentenceText();
+            continue;
+        }
+        // An independent language child projects to an opaque empty name.
+        if (text.startsWith("{}", offset)) {
+            offset += 2;
+            sentenceText();
             continue;
         }
-        if (isRomanWhitespace(char)) {
+        // Layout, pauses and name boundaries supply no sentence text.
+        if (isRomanWhitespace(char) || "/,{}".includes(char)) {
             offset += char.length;
             continue;
         }
         if (char === "^") {
-            const start =
-                Math.max(text.lastIndexOf("\n", offset - 1), text.lastIndexOf("/", offset - 1)) + 1;
+            let slash = text.lastIndexOf("/", offset - 1);
+            while (slash >= 0 && (/\\+$/.exec(text.slice(0, slash))?.[0].length ?? 0) % 2)
+                slash = text.lastIndexOf("/", slash - 1);
+            const start = Math.max(text.lastIndexOf("\n", offset - 1), slash) + 1;
             if (/^\^*$/.test(text.slice(start, offset))) {
                 // Indentation is layout and leaves sentence-start ellipsis
                 // semantics intact. The reference encoder uses these bounds.
@@ -199,7 +218,7 @@ export function romanTextProblems(text, inventory) {
             const expected = quotes.length % 2 === 0 ? "«" : "‹";
             if (char !== expected)
                 report(offset, `a quotation at this depth opens with \`${expected}\``);
-            quotes.push({ char, offset });
+            quotes.push({ char, offset, sentenceStart, hasText: false });
             sentenceStart = true;
         } else if (char === "»" || char === "›") {
             const opening = quotes.at(-1);
@@ -209,7 +228,8 @@ export function romanTextProblems(text, inventory) {
                 if (char !== expected)
                     report(offset, `this quotation closes with \`${expected}\`, not \`${char}\``);
                 quotes.pop();
-                sentenceStart = false;
+                sentenceStart = opening.sentenceStart && !opening.hasText;
+                if (opening.hasText) sentenceText();
             }
         } else if (char === "—" || (char === "…" && !sentenceStart)) {
             const rest = text.slice(offset + char.length);
@@ -218,9 +238,11 @@ export function romanTextProblems(text, inventory) {
                     offset,
                     `\`${char}\` is immediately followed by a terminal (\`.\`, \`?\`, \`‼\` or \`!\`) except at the end of a run`,
                 );
-            sentenceStart = false;
-        } else if (TERMINALS.has(char)) sentenceStart = true;
-        else sentenceStart = false;
+        } else if (TERMINALS.has(char)) {
+            if (sentenceStart)
+                report(offset, `terminal \`${char}\` has no sentence text before it`);
+            sentenceStart = true;
+        } else sentenceText();
         offset += char.length;
     }
     for (const opening of quotes)

package/engine/roman-run.mjs

@@ -52,6 +52,7 @@
  * @param {(span: RomanSpan) => string} [options.opaqueSpan] - Placeholder for an independent child. The default empty name keeps sentence state without introducing that child's letters.
  * @param {ReadonlyArray<readonly [number, number]>} [options.exclude] - Absolute source ranges that carry layout or presentation syntax.
  * @param {boolean} [options.markNames] - Whether name children contribute braces.
+ * @param {boolean} [options.preserveSlashEscape] - Keep a literal verse slash distinct from a line control.
  * @returns {{text: string, offsets: number[], spans: ProjectedSpan[]}} Logical text and source locations, with child ranges for presentation.
  */
 export function plainRomanRun(
@@ -64,6 +65,7 @@ export function plainRomanRun(
         opaqueSpan = () => "{}",
         exclude = [],
         markNames = true,
+        preserveSlashEscape = false,
     } = {},
 ) {
     let text = "";
@@ -134,6 +136,7 @@ export function plainRomanRun(
             const escaped =
                 source[at] === "\\" && at + 1 < past && /[!-/:-@[-`{-~]/.test(source[at + 1]);
             const offset = at + (escaped ? 1 : 0);
+            if (escaped && preserveSlashEscape && source[offset] === "/") append("\\", at);
             // A terminal Markdown line-break slash is layout, not Roman.
             if (source[at] === "\\" && !escaped && /[\r\n]/.test(source[at + 1] ?? "")) {
                 at++;

package/engine/roman-verse.mjs

@@ -38,6 +38,7 @@ export function plainRomanVerse(source, options = {}) {
         .filter((boundary) => boundary.sourceOffset >= from && boundary.sourceOffset <= to);
     const projected = plainRomanRun(source, {
         ...options,
+        preserveSlashEscape: true,
         from,
         to,
         exclude: [

package/engine/run-rows.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Spans, divs and verse fences marked with `lang=`, `font=` or `enc=`, projected
+ * Spans, divs and verse divs and quoted verse spans marked with `lang=`, `font=` or `enc=`, projected
  * from own-note index records into the SQL `runs` relation. Every value is a
  * column value and none is a key, so two notes writing one tag in different
  * case are two rows. Documentation records and assets contribute no rows.

package/engine/sql-tables.mjs

@@ -682,7 +682,7 @@ async function createNameRelation(connection, file, records, prefix, audience) {
 }
 
 /**
- * Create the `runs` relation: one row per span, div and verse fence an own
+ * Create the `runs` relation: one row per span, div and verse div an own
  * note marks with `lang=`, `font=` or `enc=`, with the columns
  * {@link module:engine/run-rows.RUN_COLUMNS} names. The columns are declared
  * rather than inferred, so every value stays a string and none becomes a

package/engine/verse-format.mjs

@@ -0,0 +1,89 @@
+/*
+ * 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
+ */
+
+/** Preserve complete authored verse regions through surrounding prose formatting. @module */
+
+import { verseRegions } from "./verse-regions.mjs";
+import { scanSpans } from "./content-spans.mjs";
+import { util } from "prettier";
+
+/**
+ * Replace verse markup with opaque placeholders, retaining container prefixes
+ * and inline display widths. Restoration follows the formatter's line endings.
+ * @param {string} source - Complete Markdown source.
+ * @returns {{markdown: string, restore: (formatted: string) => string}} Protected source and restoration.
+ */
+export function protectVerseSource(source) {
+    const syntax = source.replace(/^\uFEFF?---\r?\n[^]*?\r?\n---(?:\r?\n|$)/, (frontmatter) =>
+        frontmatter.replace(/[^\r\n]/g, " "),
+    );
+    const ranges = [
+        ...verseRegions(syntax)
+            .filter((region) => region.closed)
+            .map((region) => ({ from: region.contentStarts[0], to: region.to, block: true })),
+        ...scanSpans(syntax)
+            .spans.filter((span) =>
+                span.attrs.some(
+                    ([key, value]) => key === "class" && value.split(/\s+/).includes("verse"),
+                ),
+            )
+            .map((span) => ({ from: span.start, to: span.end, block: false })),
+    ].sort((a, b) => a.from - b.from || b.to - a.to);
+    const outer = ranges.filter(
+        (range, index) =>
+            !ranges
+                .slice(0, index)
+                .some((parent) => parent.from <= range.from && parent.to >= range.to),
+    );
+    let nonce = 0;
+    let prefix = `V${nonce}V`;
+    while (source.includes(prefix)) prefix = `V${++nonce}V`;
+    const replacements = outer.map((range, index) => {
+        const original = source.slice(range.from, range.to);
+        const key = `${prefix}${index.toString(36)}V`;
+        const marker =
+            range.block ? `<!--${key}-->` : key.padEnd(util.getStringWidth(original), "X");
+        return {
+            ...range,
+            original,
+            marker,
+            newline: range.block ? /(?:\r\n|\r|\n)$/.exec(original)?.[0] : undefined,
+        };
+    });
+    let markdown = source;
+    for (const entry of [...replacements].reverse())
+        markdown =
+            markdown.slice(0, entry.from) +
+            entry.marker +
+            (entry.newline ?? "") +
+            markdown.slice(entry.to);
+    return {
+        markdown,
+        restore(formatted) {
+            const newline = /\r\n|\r|\n/.exec(formatted)?.[0] ?? "\n";
+            let restored = formatted;
+            for (const entry of replacements) {
+                const escaped = entry.marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                const pattern = new RegExp(
+                    `${escaped}${entry.newline ? "(?:\\r\\n|\\r|\\n)" : ""}`,
+                );
+                if (!pattern.test(restored))
+                    throw new Error("the formatter changed a protected verse placeholder");
+                restored = restored.replace(pattern, () =>
+                    entry.original.replace(/\r\n|\r|\n/g, newline),
+                );
+            }
+            return restored;
+        },
+    };
+}

package/engine/verse-metre.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * **A verse fence declares its metre, and the build counts its beats.** A
+ * **A verse div declares its metre, and the build counts its beats.** A
  * metre is declared once, as an entry of a `doc` note's `data.metres`:
  *
  * ```yaml
@@ -21,7 +21,7 @@
  *     - { name: hexameter, beats: 6, kind: accentual }
  * ```
  *
- * A fence that states `scan=` with the `name` and `lang=` with a language
+ * A div that states `scan=` with the `name` and `lang=` with a language
  * whose note states `data.sounds.stress` is counted line by line, and a line
  * that cannot have the metre's beats is a warning at that line. No `scan=`
  * means no check.
@@ -278,7 +278,7 @@ export function lineBeats(text, book) {
  * 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 }, metre) {
@@ -287,13 +287,13 @@ export function metreMessage({ min, max }, metre) {
 }
 
 /**
- * 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.
@@ -325,7 +325,7 @@ export function metreFindings(blocks, lines, ctx) {
         if (lang === undefined) {
             error(
                 at("scan", "key"),
-                "`scan=` counts beats by a language's stress rule: the fence needs a `lang=`",
+                "`scan=` counts beats by a language's stress rule: the div needs a `lang=`",
             );
             continue;
         }
@@ -351,7 +351,16 @@ export function metreFindings(blocks, lines, ctx) {
         for (const group of model.groups) {
             if (group.cantoBreak) continue;
             for (const reading of group.lines) {
-                const tokens = verseParser.parseInline(reading.text, {})[0]?.children ?? [];
+                const units = reading.text
+                    .split("")
+                    .map((text, index) => ({ text, offset: reading.offsets[index] }))
+                    .filter(
+                        ({ offset }) =>
+                            !model.layout.some(([from, to]) => offset >= from && offset < to),
+                    );
+                const tokens =
+                    verseParser.parseInline(units.map((unit) => unit.text).join(""), {})[0]
+                        ?.children ?? [];
                 const tag = (name) => (ctx.languages?.[name]?.tag ?? name).toLowerCase();
                 const foreign = tokens.find(
                     (token) =>
@@ -361,7 +370,7 @@ export function metreFindings(blocks, lines, ctx) {
                 );
                 if (foreign) {
                     error(
-                        sourcePosition(reading.offsets[foreign.meta.start] ?? reading.from),
+                        sourcePosition(units[foreign.meta.start]?.offset ?? reading.from),
                         "`scan=` counts one language's beats; this verse line contains another language",
                     );
                     continue;

package/engine/verse-regions.mjs

@@ -0,0 +1,190 @@
+/*
+ * 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[]} contentStarts - Original-source content offsets for each region line, after container prefixes.
+ * @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 contentStarts = [];
+            for (let number = first; number < (closed ? close + 1 : past); number++) {
+                const normalizedStart = state.src.lastIndexOf("\n", state.bMarks[number] - 1) + 1;
+                contentStarts.push(
+                    starts[number] + state.bMarks[number] + state.tShift[number] - normalizedStart,
+                );
+            }
+            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,
+                contentStarts,
+                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]);
+}