@heroiclands/package-build 25.3.0 → 25.4.0

package/engine/content-verse.mjs

@@ -12,14 +12,17 @@
  */
 
 import MarkdownIt from "markdown-it";
-import { WIKILINK } from "./wikilink-syntax.mjs";
+import footnotePlugin from "markdown-it-footnote";
+import { footnoteLabels, footnoteReferences } from "./content-footnotes.mjs";
+import { inlineText } from "./name-markup.mjs";
 import { pageOpenings } from "./heading-attributes.mjs";
+import { inlineSyntaxRanges, verseRegions } from "./verse-regions.mjs";
 import { blockTokens } from "./markdown-blocks.mjs";
 import { slugify } from "./content-slug.mjs";
-import { spanMarkdownPlugin } from "./content-spans.mjs";
+import { scanSpans, spanMarkdownPlugin } from "./content-spans.mjs";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
 
-const lineParser = new MarkdownIt({ html: true }).use(spanMarkdownPlugin);
+const lineParser = new MarkdownIt({ html: true }).use(footnotePlugin).use(spanMarkdownPlugin);
 
 /**
  * Read one verse line. Marker offsets are zero-based in the authored line;
@@ -94,7 +97,7 @@ export function rightToLeft(text) {
     );
 }
 
-/** The authored attributes of a verse fence. */
+/** The authored attributes of a verse div. */
 export const VERSE_KEYS = Object.freeze([
     "form",
     "scan",
@@ -109,111 +112,60 @@ export const VERSE_KEYS = Object.freeze([
 /** A canto separator, including the escaped form produced by a native run. */
 export const STANZA_BREAK = /^(?:\\?\*){3}$/;
 
-/** 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, { checkWorks = true } = {}) {
-    const lines = String(source ?? "").split("\n"),
+    const text = String(source ?? "");
+    const lines = text.split("\n"),
         blocks = [],
         errors = [];
-    const literalLines = new Set();
-    for (const token of blockTokens(source)) {
-        if (!token.map || !["blockquote_open", "html_block"].includes(token.type)) continue;
-        for (let line = token.map[0]; line < token.map[1]; line++) literalLines.add(line);
+    for (const token of blockTokens(text)) {
+        if (token.type === "fence" && /^verse(?:\s|$)/.test(token.info.trim()))
+            errors.push({
+                line: token.map[0] + 1,
+                column: 1,
+                message: "verse uses a .verse div: write ::: {.verse …} and a closing :::",
+            });
     }
-    let opening = null;
-    for (let i = 0; i < lines.length; i++) {
-        if (literalLines.has(i)) continue;
-        const match = /^ *(`{3,}|~{3,})(.*)$/.exec(lines[i]);
-        if (opening) {
-            if (
-                match &&
-                match[1][0] === opening.fence[0] &&
-                match[1].length >= opening.fence.length &&
-                !match[2].trim()
-            ) {
-                if (opening.name === "verse") {
-                    const body = lines.slice(opening.start + 1, i).join("\n");
-                    if (!body.trim())
-                        errors.push({
-                            line: opening.start + 1,
-                            column: 1,
-                            message: "verse block is empty",
-                        });
-                    for (let n = opening.start + 1; n < i; n++) {
-                        const col = lines[n].indexOf("\t");
-                        if (col >= 0)
-                            errors.push({
-                                line: n + 1,
-                                column: col + 1,
-                                message: "tabs are not allowed in verse",
-                            });
-                    }
-                    const block = { ...opening, end: i, body };
-                    block.model = parseVerse(body);
-                    const bodyOffset = lines.slice(0, opening.start + 1).join("\n").length + 1;
-                    for (const finding of block.model.errors) {
-                        const prefix = String(source).slice(0, bodyOffset + finding.offset);
-                        errors.push({
-                            line: prefix.split("\n").length,
-                            column: prefix.length - prefix.lastIndexOf("\n"),
-                            message: finding.message,
-                        });
-                    }
-                    blocks.push(block);
-                }
-                opening = null;
-            }
-            continue;
-        }
-        if (!match) continue;
-        const info = match[2].trim();
-        opening = {
-            start: i,
-            fence: match[1],
-            name: info.split(/\s/)[0],
-            attributes: {},
-            id: "",
-            classes: [],
-            indent: /^ */.exec(lines[i])[0],
-        };
-        if (opening.name !== "verse") continue;
-        const raw = info.slice(6).trim();
-        const at = { line: i + 1, column: 1 };
-        if (raw && !/^\{[^}\n]*\}$/.test(raw)) {
-            errors.push({ ...at, message: "verse attributes need {…} braces" });
-            continue;
-        }
-        const parsed = parseExtensionAttributes(raw ? raw.slice(1, -1) : "");
-        opening.id = parsed.id;
-        opening.classes = parsed.classes;
-        opening.attributes = parsed.values;
-        for (const message of [...parsed.problems, ...refusedAttributes(parsed.values)])
+    const definedFootnotes = footnoteLabels(text);
+    for (const region of verseRegions(text)) {
+        const at = { line: region.start + 1, column: region.indent.length + 1 };
+        for (const message of [...region.problems, ...refusedAttributes(region.attributes)])
             errors.push({ ...at, message });
-        for (const [key, value] of Object.entries(parsed.values)) {
-            if (key === "work" && !value.trim())
-                errors.push({
-                    line: i + 1,
-                    column: keyColumn(lines[i], key),
-                    message: "work= needs a nonempty page-local key",
-                });
+        if (!region.closed) errors.push({ ...at, message: "verse div needs a closing ::: line" });
+        if (!region.body.trim()) errors.push({ ...at, message: "verse div is empty" });
+        for (const key of Object.keys(region.attributes))
             if (!VERSE_KEYS.includes(key))
                 errors.push({
-                    line: i + 1,
-                    column: keyColumn(lines[i], key),
+                    ...at,
+                    column: keyColumn(lines[region.start], key),
                     message: `${key}= is not a verse attribute`,
                 });
+        if (region.attributes.work !== undefined && !region.attributes.work.trim())
+            errors.push({ ...at, message: "work= needs a nonempty page-local key" });
+        const model = parseVerse(region.body, { footnotes: definedFootnotes });
+        for (const finding of model.errors) {
+            const preceding = text.slice(0, region.bodyStart + finding.offset);
+            errors.push({
+                line: preceding.split("\n").length,
+                column: preceding.length - preceding.lastIndexOf("\n"),
+                message: finding.message,
+            });
+        }
+        for (const match of region.body.matchAll(/\t/g)) {
+            const preceding = text.slice(0, region.bodyStart + match.index);
+            errors.push({
+                line: preceding.split("\n").length,
+                column: preceding.length - preceding.lastIndexOf("\n"),
+                message: "tabs are not allowed in verse",
+            });
         }
+        blocks.push({ ...region, model });
     }
-    if (opening?.name === "verse")
-        errors.push({
-            line: opening.start + 1,
-            column: 1,
-            message: "verse block needs a closing code fence",
-        });
     if (checkWorks) {
         const openings = [...pageOpenings(source).keys()];
         const pages = new Map();
@@ -231,7 +183,7 @@ export function scanVerse(source, { checkWorks = true } = {}) {
 /**
  * The 1-based column of `key=`, or of a class or id token, in an opening line.
  *
- * @param {string} opening - The fence's opening line.
+ * @param {string} opening - The div's opening line.
  * @param {string} key - The key, or a `.class` or `#id` token.
  * @returns {number} Its column, or the brace's when it is not found.
  */
@@ -244,51 +196,6 @@ function keyColumn(opening, key) {
     return (at < 0 ? brace : brace + at) + 1;
 }
 
-/** Source ranges whose slash characters belong to inline syntax. */
-function syntaxRanges(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 (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]);
-}
-
 /**
  * A logical line with its authored UTF-16 coordinates.
  * @typedef {object} VerseLine
@@ -310,7 +217,7 @@ function syntaxRanges(source) {
 
 /**
  * @typedef {VerseStanza & {canto: number, stanza: number, label: string, cantoBreak?: false}} VerseTextGroup
- * @typedef {{cantoBreak: true, from: number, to: number, text?: string}} VerseCantoBreak
+ * @typedef {{cantoBreak: true, from: number, to: number, text?: string, id?: string, title?: string}} VerseCantoBreak
  * @typedef {{kind: "line"|"stanza"|"canto", sourceOffset: number}} VerseBoundary
  * @typedef {{offset: number, message: string}} VerseFinding
  */
@@ -322,21 +229,27 @@ function syntaxRanges(source) {
  * @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.
+ * @property {VerseFinding[]} errors - Findings relative to the verse body.
+ * @property {VerseLine[]} notes - Defined references without substantive verse text.
  */
 
 /**
- * An authored verse fence with its parsed logical structure.
+ * An authored verse div 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 {number} start - Opening div's zero-based source line.
+ * @property {number} end - Closing div's zero-based source line.
+ * @property {number} from - Complete div first offset.
+ * @property {number} to - Offset past complete div.
+ * @property {number} bodyStart - First body offset.
+ * @property {number} bodyEnd - Offset past body text.
+ * @property {boolean} closed - Whether the closing delimiter exists.
+ * @property {string[]} problems - Attribute syntax findings.
+ * @property {"verse"} name - Region name.
  * @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 {string} indent - Opening div's leading spaces.
+ * @property {string} body - Authored verse body.
  * @property {VerseModel} model - Logical structure relative to the body.
  */
 
@@ -350,22 +263,55 @@ function syntaxRanges(source) {
  * @property {Record<string, string>} attributes - Native language, direction and search attributes.
  */
 
+/** Read a standard canto separator's semantic attributes. */
+function cantoLine(line) {
+    const match = /^---[ \t]+(\{.*)$/.exec(line.trim());
+    if (!match) return undefined;
+    const closed = match[1].endsWith("}");
+    const parsed = parseExtensionAttributes(closed ? match[1].slice(1, -1) : match[1].slice(1));
+    if (!parsed.classes.includes("canto")) return undefined;
+    if (!closed) parsed.problems.push("a canto break needs --- {.canto} attribute braces");
+    for (const key of Object.keys(parsed.values))
+        if (key !== "title") parsed.problems.push(`${key}= is not a canto attribute`);
+    for (const name of parsed.classes)
+        if (name !== "canto") parsed.problems.push(`.${name} is not a canto class`);
+    return {
+        id: parsed.id,
+        title: parsed.values.title ?? "",
+        problems: [...parsed.problems, ...refusedAttributes(parsed.values)],
+    };
+}
+
 /**
  * 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) {
+export function parseVerse(body, { inline = false, footnotes = new Set() } = {}) {
     const source = String(body ?? "");
     const groups = [],
         boundaries = [],
         layout = [],
         errors = [];
+    if (inline)
+        for (const match of source.matchAll(/\r?\n[ \t]*\r?\n/g))
+            errors.push({
+                offset: match.index,
+                message: "an inline .verse quotation uses // for a stanza break, not a blank line",
+            });
     const cantos = [{ stanzas: [] }];
-    const protectedRanges = syntaxRanges(source);
-    const spans = (lineParser.parseInline(source, {})[0]?.children ?? [])
+    const references = footnoteReferences(source, { definitions: footnotes, inline: true });
+    layout.push(...references.map((ref) => [ref.from, ref.to]));
+    const protectedRanges = [
+        ...inlineSyntaxRanges(source),
+        ...references.map((ref) => [ref.from, ref.to]),
+    ].sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    const children = [];
+    lineParser.inline.parse(source, lineParser, {}, children);
+    const spans = children
         .filter((token) => token.meta?.span)
         .map((token) => ({
             start: token.meta.start,
@@ -378,14 +324,43 @@ export function parseVerse(body) {
         from = 0,
         level = 0,
         lines = [];
+    const pendingNotes = [];
     let pendingBreak;
+    const cantoIds = new Set();
+    if (inline)
+        for (const match of source.matchAll(/---[ \t]+\{[^}]*\.canto[^}]*\}/g)) {
+            const escaped = /\\+$/.exec(source.slice(0, match.index))?.[0].length ?? 0;
+            if (
+                escaped % 2 ||
+                protectedRanges.some(([first, past]) => match.index >= first && match.index < past)
+            )
+                continue;
+            errors.push({
+                offset: match.index,
+                message: "an inline .verse quotation has no canto breaks",
+            });
+        }
     const append = (value, at) => {
         text += value;
         for (let index = 0; index < value.length; index++) offsets.push(at + index);
     };
     const finishLine = (at) => {
+        let kind = "empty";
         const trimmed = text.trimEnd();
         if (trimmed.trim()) {
+            if (
+                STANZA_BREAK.test(trimmed) &&
+                !errors.some(
+                    (error) =>
+                        error.offset >= from &&
+                        error.offset <= at &&
+                        error.message.includes("--- {.canto}"),
+                )
+            )
+                errors.push({
+                    offset: from,
+                    message: "write a canto break as --- {.canto}, preceded by a blank line",
+                });
             let lineText = trimmed,
                 lineOffsets = offsets.slice(0, trimmed.length);
             for (const span of spans
@@ -423,15 +398,54 @@ export function parseVerse(body) {
                 lineText = kept.map(({ char }) => char).join("");
                 lineOffsets = kept.map(({ offset }) => offset);
             }
-            lines.push({ text: lineText, level, from, to: at, offsets: lineOffsets });
+            const line = { text: lineText, level, from, to: at, offsets: lineOffsets };
+            const visible = [];
+            const hasReferences =
+                footnoteReferences(lineText, { definitions: footnotes, inline: true }).length > 0;
+            if (hasReferences)
+                lineParser.inline.parse(
+                    lineText,
+                    lineParser,
+                    {
+                        footnotes: {
+                            refs: Object.fromEntries([...footnotes].map((key) => [":" + key, -1])),
+                        },
+                    },
+                    visible,
+                );
+            const onlyReferences =
+                hasReferences &&
+                !inlineText(visible).trim() &&
+                !visible.some((token) => token.type === "image");
+            kind = onlyReferences ? "note" : "content";
+            if (onlyReferences) {
+                const previous =
+                    lines.at(-1) ?? groups.findLast((group) => !group.cantoBreak)?.lines.at(-1);
+                if (previous) {
+                    previous.text += line.text;
+                    previous.offsets.push(...line.offsets);
+                } else pendingNotes.push(line);
+            } else {
+                if (pendingNotes.length) {
+                    line.text = pendingNotes.map((note) => note.text).join("") + line.text;
+                    line.offsets = [
+                        ...pendingNotes.flatMap((note) => note.offsets),
+                        ...line.offsets,
+                    ];
+                    pendingNotes.length = 0;
+                }
+                lines.push(line);
+            }
         }
         text = "";
         offsets = [];
         level = 0;
         from = at;
+        return kind;
     };
     const finishStanza = (at) => {
-        finishLine(at);
+        const kind = finishLine(at);
+        const emitted = lines.length > 0;
         if (lines.length) {
             const stanza = { lines, from: lines[0].from, to: at };
             cantos.at(-1).stanzas.push(stanza);
@@ -443,17 +457,25 @@ export function parseVerse(body) {
             });
             lines = [];
         }
+        return { kind, emitted };
     };
     const event = (kind, at, past) => {
-        if (kind === "line") finishLine(at);
-        else finishStanza(at);
+        const result =
+            kind === "line" ? { kind: finishLine(at), emitted: false } : finishStanza(at);
         layout.push([at, past]);
-        boundaries.push({ kind, sourceOffset: at });
+        if (!(
+            result.kind === "note" &&
+            (kind === "line" || (kind === "stanza" && !result.emitted))
+        ))
+            boundaries.push({ kind, sourceOffset: at });
         from = past;
     };
     for (let at = 0; at < source.length;) {
+        while (protectedRanges[protectedIndex]?.[1] <= at) protectedIndex++;
+        const protectedRange = protectedRanges[protectedIndex];
+        const protectedAt = protectedRange && protectedRange[0] <= at;
         const lineStart = at === 0 || /[\r\n]/.test(source[at - 1]);
-        if (lineStart) {
+        if (lineStart && !protectedAt) {
             const physical = /^[^\r\n]*/.exec(source.slice(at))[0];
             const newline = /^(?:\r\n|\r|\n)/.exec(source.slice(at + physical.length))?.[0] ?? "";
             if (!physical.trim()) {
@@ -461,25 +483,59 @@ export function parseVerse(body) {
                 at += physical.length + newline.length;
                 continue;
             }
-            if (STANZA_BREAK.test(physical.trim())) {
-                event("canto", at, at + physical.length + newline.length);
-                if (!cantos.at(-1).stanzas.length)
-                    errors.push({
-                        offset: at,
-                        message: "a canto break needs a stanza before and after it",
-                    });
-                else {
-                    groups.push({ cantoBreak: true, from: at, to: at + physical.length });
-                    cantos.push({ stanzas: [] });
+            if (STANZA_BREAK.test(physical.trim()))
+                errors.push({
+                    offset: at,
+                    message: "write a canto break as --- {.canto}, preceded by a blank line",
+                });
+            const canto = cantoLine(physical);
+            if (canto) {
+                if (inline) {
+                    if (!errors.some((error) => error.offset === at))
+                        errors.push({
+                            offset: at,
+                            message: "an inline .verse quotation has no canto breaks",
+                        });
+                } else {
+                    for (const message of canto.problems) errors.push({ offset: at, message });
+                    if (
+                        at &&
+                        source.slice(0, at).trimEnd().length &&
+                        !/(?:\r?\n)[ \t]*(?:\r?\n)$/.test(source.slice(0, at))
+                    )
+                        errors.push({
+                            offset: at,
+                            message: "a canto break needs a blank line before it",
+                        });
+                    if (canto.id && cantoIds.has(canto.id))
+                        errors.push({
+                            offset: at,
+                            message: `canto anchor #${canto.id} is written more than once`,
+                        });
+                    if (canto.id) cantoIds.add(canto.id);
+                    event("canto", at, at + physical.length + newline.length);
+                    if (!cantos.at(-1).stanzas.length)
+                        errors.push({
+                            offset: at,
+                            message: "a canto break needs a stanza before and after it",
+                        });
+                    else {
+                        groups.push({
+                            cantoBreak: true,
+                            from: at,
+                            to: at + physical.length,
+                            id: canto.id,
+                            title: canto.title,
+                        });
+                        cantos.push({ stanzas: [] });
+                    }
+                    pendingBreak = at;
+                    at += physical.length + newline.length;
+                    continue;
                 }
-                pendingBreak = at;
-                at += physical.length + newline.length;
-                continue;
             }
         }
-        while (protectedRanges[protectedIndex]?.[1] <= at) protectedIndex++;
-        const protectedRange = protectedRanges[protectedIndex];
-        const protectedAt = protectedRange && protectedRange[0] <= at;
+
         if (!text && !/\s/.test(source[at])) {
             if (!level) from = at;
             const remaining = source.slice(at);
@@ -533,7 +589,31 @@ export function parseVerse(body) {
     for (const group of groups)
         if (!group.cantoBreak)
             group.label = multi ? `${group.canto}:${group.stanza}` : String(group.stanza);
-    return { cantos, groups, boundaries, layout, errors };
+    return { cantos, groups, boundaries, layout, errors, notes: pendingNotes };
+}
+
+/**
+ * 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, source) {
+    const findings = parseVerse(span.text, {
+        inline: true,
+        footnotes: footnoteLabels(source),
+    }).errors;
+    for (const [key] of span.attrs)
+        if (["form", "work", "scan"].includes(key))
+            findings.push({ offset: 0, message: `${key}= is not an inline .verse attribute` });
+    return findings.map((finding) => {
+        const prefix = source.slice(0, span.start + 1 + finding.offset);
+        return {
+            line: prefix.split("\n").length,
+            column: prefix.length - prefix.lastIndexOf("\n"),
+            message: finding.message,
+        };
+    });
 }
 
 /** Logical line text for consumers that do not need source locations. */
@@ -557,8 +637,8 @@ export const stanzaSeparator = (group) => group.length === 1 && STANZA_BREAK.tes
 
 /**
  * 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) {
     const works = new Map(),
@@ -612,16 +692,17 @@ export function workShapeFindings(blocks) {
 
 /**
  * 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,
-    { labelled = false, model = parseVerse(body), presentation } = {},
+    { labelled = false, model = parseVerse(body), presentation, inline = false } = {},
 ) {
     const escape = (value) =>
         String(value)
@@ -634,7 +715,7 @@ export function verseMarkdown(
         .map(([key, value]) => ` ${key}="${escape(value)}"`)
         .join("");
     const nativeClasses = ["verse-native", ...(presentation?.classes ?? [])].join(" ");
-    return model.groups
+    const content = model.groups
         .map((group) => {
             if (group.cantoBreak) {
                 const mark = group.text ? inlineVerse(group.text) : "";
@@ -642,7 +723,14 @@ export function verseMarkdown(
                     mark && presentation ?
                         `<span class="${escape(nativeClasses)}"${nativeAttrs}${!presentation.attributes?.dir && rightToLeft(group.text) ? ' dir="rtl"' : ""}>${mark}</span>`
                     :   mark;
-                return `<span class="verse-canto-break" aria-hidden="true">${content}</span>`;
+                const heading =
+                    group.title ?
+                        `<span class="verse-canto-heading" role="heading" aria-level="3"${group.id ? ` id="${escape(slugify(group.id))}"` : ""}>${inlineVerse(group.title)}</span>`
+                    : group.id ? `<span id="${escape(slugify(group.id))}"></span>`
+                    : "";
+                return (
+                    heading + `<span class="verse-canto-break" aria-hidden="true">${content}</span>`
+                );
             }
             const label = labelled ? `<span class="verse-label">${group.label}</span>` : "";
             const rows = group.lines
@@ -653,15 +741,27 @@ export function verseMarkdown(
                         return `<span class="verse-row"><span class="${escape(nativeClasses)}"${nativeAttrs}${!presentation?.attributes?.dir && rightToLeft(line.text) ? ' dir="rtl"' : ""}>${content(line.text)}</span><span class="verse-roman">${content(line.romanText)}</span></span>`;
                     return content(line.text);
                 })
-                .join(group.lines.some((line) => line.romanText !== undefined) ? "\n" : "  \n");
-            return `<div class="verse-stanza">${label}\n\n${rows}\n\n</div>`;
+                .join(
+                    group.lines.some((line) => line.romanText !== undefined) ?
+                        inline ? ""
+                        :   "\n"
+                    : inline ? "<br/>"
+                    : "  \n",
+                );
+            return inline ?
+                    `<span class="verse-stanza">${rows}</span>`
+                :   `<div class="verse-stanza">${label}\n\n${rows}\n\n</div>`;
         })
-        .join("\n\n");
+        .join(inline ? '<br class="verse-stanza-break"/>' : "\n\n");
+    const notes = (model.notes ?? [])
+        .map((note) => inlineVerse(note.romanText ?? note.text))
+        .join("");
+    return content + (notes ? `<span class="verse-footnotes">${notes}</span>` : "");
 }
 
 /**
- * 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.
  */
@@ -680,13 +780,10 @@ export function renderVerse(source, { verses = new Map() } = {}) {
         output.push(...lines.slice(cursor, block.start));
         const transported = verses.get(block.body);
         const model = transported?.model ?? block.model;
-        const paired = model.groups.some(
-            (group) =>
-                !group.cantoBreak && group.lines.some((line) => line.romanText !== undefined),
-        );
+        const paired = Boolean(transported);
         const labelled = block.attributes.work !== undefined;
         const attrs = [
-            `class="${escape(["verse", ...block.classes.filter((value) => !paired || !transported?.classes?.includes(value)), ...(paired ? ["verse-paired"] : []), ...(labelled ? ["verse-labelled"] : [])].join(" "))}"`,
+            `class="${escape(["verse", ...block.classes.filter((value) => value !== "verse" && (!paired || !transported?.classes?.includes(value))), ...(paired ? ["verse-paired"] : []), ...(labelled ? ["verse-labelled"] : [])].join(" "))}"`,
         ];
         if (block.id) attrs.push(`id="${escape(slugify(block.id))}"`);
         for (const [key, value] of Object.entries(block.attributes)) {
@@ -722,3 +819,34 @@ export function renderVerse(source, { verses = new Map() } = {}) {
     output.push(...lines.slice(cursor));
     return { markdown: output.join("\n"), errors };
 }
+
+/**
+ * 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) {
+    const spans = scanSpans(source).spans.filter((span) =>
+        span.attrs.some(([key, value]) => key === "class" && value.split(/\s+/).includes("verse")),
+    );
+    const footnotes = footnoteLabels(source);
+    let markdown = source;
+    for (const span of spans
+        .filter(
+            (span) => !spans.some((parent) => parent.start < span.start && parent.end >= span.end),
+        )
+        .sort((a, b) => b.start - a.start)) {
+        const model = span.verseModel ?? parseVerse(span.text, { inline: true, footnotes });
+        const attrs = span.attrs
+            .map(
+                ([key, value]) =>
+                    `${key}="${String(key === "class" ? value + " verse-inline" : value)
+                        .replace(/&/g, "&amp;")
+                        .replace(/"/g, "&quot;")}"`,
+            )
+            .join(" ");
+        const html = `<span ${attrs}>${verseMarkdown(span.text, { model, inline: true })}</span>`;
+        markdown = markdown.slice(0, span.start) + html + markdown.slice(span.end);
+    }
+    return markdown;
+}