@heroiclands/package-build 25.4.0 → 25.5.0

package/engine/content-verse.mjs

@@ -124,16 +124,19 @@ export function scanVerse(source, { checkWorks = true } = {}) {
         blocks = [],
         errors = [];
     for (const token of blockTokens(text)) {
-        if (token.type === "fence" && /^verse(?:\s|$)/.test(token.info.trim()))
+        if (token.type === "fence" && /^verse(?:\s|$)/.test(token.info.trim())) {
+            const opening = lines[token.map[0]];
+            const marker = opening?.indexOf(token.markup);
             errors.push({
                 line: token.map[0] + 1,
-                column: 1,
+                ...(marker !== undefined && marker >= 0 ? { column: marker + 1 } : {}),
                 message: "verse uses a .verse div: write ::: {.verse …} and a closing :::",
             });
+        }
     }
     const definedFootnotes = footnoteLabels(text);
     for (const region of verseRegions(text)) {
-        const at = { line: region.start + 1, column: region.indent.length + 1 };
+        const at = { line: region.start + 1, column: region.contentStarts[0] - region.from + 1 };
         for (const message of [...region.problems, ...refusedAttributes(region.attributes)])
             errors.push({ ...at, message });
         if (!region.closed) errors.push({ ...at, message: "verse div needs a closing ::: line" });
@@ -164,7 +167,7 @@ export function scanVerse(source, { checkWorks = true } = {}) {
                 message: "tabs are not allowed in verse",
             });
         }
-        blocks.push({ ...region, model });
+        blocks.push({ ...region, column: at.column, model });
     }
     if (checkWorks) {
         const openings = [...pageOpenings(source).keys()];
@@ -176,7 +179,7 @@ export function scanVerse(source, { checkWorks = true } = {}) {
         }
         for (const page of pages.values()) errors.push(...workShapeFindings(page));
     }
-    errors.sort((a, b) => a.line - b.line || a.column - b.column);
+    errors.sort((a, b) => a.line - b.line || (a.column ?? 0) - (b.column ?? 0));
     return { blocks, errors };
 }
 
@@ -237,6 +240,7 @@ function keyColumn(opening, key) {
  * An authored verse div with its parsed logical structure.
  * @typedef {object} VerseBlock
  * @property {number} start - Opening div's zero-based source line.
+ * @property {number} [column] - Opening delimiter's one-based source column, when known.
  * @property {number} end - Closing div's zero-based source line.
  * @property {number} from - Complete div first offset.
  * @property {number} to - Offset past complete div.
@@ -253,7 +257,7 @@ function keyColumn(opening, key) {
  * @property {VerseModel} model - Logical structure relative to the body.
  */
 
-/** @typedef {{line: number, column: number, message: string}} VerseDiagnostic */
+/** @typedef {{line: number, column?: number, message: string}} VerseDiagnostic */
 
 /**
  * An encoded verse's shared display model and native-cell presentation.
@@ -594,15 +598,20 @@ export function parseVerse(body, { inline = false, footnotes = new Set() } = {})
 
 /**
  * Validate a quoted verse span using its original source coordinates.
- * @param {{start: number, text: string, attrs: Array<[string,string]>}} span - Authored span.
+ * @param {{start: number, text: string, attrs: Array<[string,string]>, verseModel?: VerseModel}} 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;
+    const findings = [
+        ...(
+            span.verseModel ??
+            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` });
@@ -641,6 +650,10 @@ export const stanzaSeparator = (group) => group.length === 1 && STANZA_BREAK.tes
  * @returns {VerseDiagnostic[]} Findings at affected opening divs.
  */
 export function workShapeFindings(blocks) {
+    const location = (block) => ({
+        line: block.start + 1,
+        ...(block.column === undefined ? {} : { column: block.column }),
+    });
     const works = new Map(),
         errors = [];
     for (const block of blocks) {
@@ -652,8 +665,7 @@ export function workShapeFindings(blocks) {
     for (const [key, versions] of works) {
         if (versions.length === 1) {
             errors.push({
-                line: versions[0].start + 1,
-                column: 1,
+                ...location(versions[0]),
                 message: `work=${key} has only one version`,
             });
             continue;
@@ -669,7 +681,7 @@ export function workShapeFindings(blocks) {
                 for (const block of [first, version]) {
                     const identity = `${block.start}:${message}`;
                     if (!seen.has(identity)) {
-                        errors.push({ line: block.start + 1, column: 1, message });
+                        errors.push({ ...location(block), message });
                         seen.add(identity);
                     }
                 }
@@ -680,7 +692,7 @@ export function workShapeFindings(blocks) {
                 for (const block of [first, version]) {
                     const identity = `${block.start}:${message}`;
                     if (!seen.has(identity)) {
-                        errors.push({ line: block.start + 1, column: 1, message });
+                        errors.push({ ...location(block), message });
                         seen.add(identity);
                     }
                 }

package/engine/encoding-standard.mjs

@@ -27,6 +27,7 @@ export const STANDARD_ROWS = Object.freeze(
         ["—", "\u{E010A}"],
         ["…", "\u{E010B}"],
         ["/", "\u{E010C}"],
+        ["\\/", "\u{E010F}"],
         ["{", "\u{E0110}"],
         ["}", "\u{E0111}"],
     ].map(Object.freeze),

package/engine/encoding-template.mjs

@@ -207,7 +207,7 @@ export function templateProgram(data, options, fault) {
             fault(key, "Grave accents are forbidden");
     };
     const validateOutput = (from, to, key) => {
-        if (/[\u{E010D}\u{E010E}\u{E0112}\u{E0113}\u{E0115}]/u.test(to))
+        if (/[\u{E010D}-\u{E010F}\u{E0112}\u{E0113}\u{E0115}]/u.test(to))
             fault(key, "Structural controls cannot be mapping outputs");
         if (from.normalize("NFD").includes("\u0301") && stress) {
             const plain = from.normalize("NFD").replaceAll("\u0301", "").normalize("NFC");
@@ -343,7 +343,10 @@ export function templateProgram(data, options, fault) {
         definition: {
             name: "encoding-note",
             fonts: [data.font],
-            accepts: [...accepts, ...STANDARD_ROWS.map((r) => (Array.isArray(r) ? r[0] : r.from))],
+            accepts: [
+                ...accepts,
+                ...STANDARD_ROWS.flatMap((r) => [...(Array.isArray(r) ? r[0] : r.from)]),
+            ],
             separator: " ",
             roundTrip: canonical ? "canonical" : "exact",
             vowels,

package/engine/encoding.mjs

@@ -256,7 +256,7 @@ export function compileRows(definition, metadata = {}) {
     const prefix = d.separator ? [separatorRow] : [];
     const controlRows = [];
     if (controls.verseStanza) controlRows.push({ from: "\n\n", to: controls.verseStanza });
-    if (controls.verseCanto) controlRows.push({ from: "--- {.canto}", to: controls.verseCanto });
+    if (controls.verseCanto) controlRows.push({ from: "***", to: controls.verseCanto });
     const shared = tier(sharedRows, [], [...prefix, ...controlRows]);
     const faces = new Map();
     if (d.faces !== undefined && !object(d.faces))
@@ -270,7 +270,7 @@ export function compileRows(definition, metadata = {}) {
             tier(
                 rows(face.rows ?? [], `faces.${font}.rows`, vowels, d.roundTrip === "canonical"),
                 sharedRows,
-                prefix,
+                [...prefix, ...controlRows],
             ),
         );
     }
@@ -330,10 +330,10 @@ function beforeHolds(condition, char, vowels) {
 function holds(row, text, start, end, vowels) {
     if (row.before && !beforeHolds(row.before, firstAt(text, end), vowels)) return false;
     if (row.at === "line-start") {
-        const prefix = text.slice(
-            Math.max(text.lastIndexOf("\n", start - 1), text.lastIndexOf("/", start - 1)) + 1,
-            start,
-        );
+        let slash = text.lastIndexOf("/", start - 1);
+        while (slash >= 0 && (/\\+$/.exec(text.slice(0, slash))?.[0].length ?? 0) % 2)
+            slash = text.lastIndexOf("/", slash - 1);
+        const prefix = text.slice(Math.max(text.lastIndexOf("\n", start - 1), slash) + 1, start);
         if (prefix.replaceAll("^", "")) return false;
     }
     if (row.at === "start" && start > 0 && !boundary(previousAt(text, start))) return false;
@@ -514,8 +514,7 @@ function encodeRawPieces(enc, text, { font, verse = false, start = 0, end = text
             out.push(piece(text.slice(at, end), enc.controls.verseCanto, at, end, null));
             at = end;
             if (verse) {
-                if (text.startsWith("\r\n", at)) at += 2;
-                else if (/[\r\n]/.test(text[at] ?? "")) at++;
+                while (at < bound && /[ \t\r\n]/.test(text[at])) at++;
             }
             continue;
         }
@@ -523,10 +522,6 @@ function encodeRawPieces(enc, text, { font, verse = false, start = 0, end = text
             let end = at;
             while (end < bound && /[ \t\r\n]/.test(text[end])) end++;
             const run = text.slice(at, end).replaceAll("\r\n", "\n").replaceAll("\r", "\n");
-            if (text.startsWith("--- {.canto}", end)) {
-                at = end;
-                continue;
-            }
             const row =
                 run.split("\n").length === 2 ?
                     rowAt(enc, groups, "/", 0)
@@ -614,12 +609,22 @@ function sourceProjection(enc, text, options) {
     return { normalized, sourceAt, begin, bound };
 }
 function cantoEnd(enc, text, at, bound) {
-    const source = "--- {.canto}";
+    const source = "***";
     return (
             enc.controls.verseCanto &&
                 at + source.length <= bound &&
                 text.startsWith(source, at) &&
-                !text.slice(text.lastIndexOf("\n", at - 1) + 1, at).trim()
+                !text
+                    .slice(
+                        Math.max(text.lastIndexOf("\n", at - 1), text.lastIndexOf("\r", at - 1)) +
+                            1,
+                        at,
+                    )
+                    .trim() &&
+                !text
+                    .slice(at + source.length, bound)
+                    .split(/[\r\n]/, 1)[0]
+                    .trim()
         ) ?
             at + source.length
         :   undefined;

package/engine/markdownlint-run.mjs

@@ -51,6 +51,7 @@ import {
     printParseErrorCode,
 } from "jsonc-parser";
 import markdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
 import { minimatch } from "minimatch";
 import { LineCounter, parse as parseYaml, parseDocument } from "yaml";
 
@@ -62,6 +63,13 @@ import {
     resolveModule,
 } from "../vendor/markdownlint.mjs";
 import { walkFiles } from "./walk-files.mjs";
+import { verseRegions } from "./verse-regions.mjs";
+import { scanSpans, spanMarkdownPlugin } from "./content-spans.mjs";
+import { parseVerse } from "./content-verse.mjs";
+import { footnoteLabels, footnoteReferences } from "./content-footnotes.mjs";
+
+/** References inside verse obey inline Markdown, without block interpretation. */
+const referenceParser = markdownIt({ html: true }).use(footnotePlugin).use(spanMarkdownPlugin);
 
 /** Option-file names, in the order the first existing one is taken. */
 const OPTIONS_FILES = Object.freeze([
@@ -542,12 +550,33 @@ export async function runMarkdownlint(params) {
     for (const [dir, files] of groups) {
         const options = await lintOptions(dir, files);
         const malformed = new Set();
+        const sources = new Map();
         for (const file of files) {
-            const findings = markupFindings(fs.readFileSync(file, "utf8"), file);
+            const source = fs.readFileSync(file, "utf8");
+            sources.set(file, protectLintVerse(source));
+            const findings = markupFindings(source, file);
             if (findings.length) malformed.add(file);
             markup.push(...findings);
         }
-        let results = await lint(options);
+        const lintSources = async (selected) => {
+            const { files: _files, ...shared } = options;
+            const results = await lint({
+                ...shared,
+                strings: Object.fromEntries(selected.map((file) => [file, sources.get(file).text])),
+            });
+            for (const file of selected) {
+                const protectedSource = sources.get(file);
+                results[file] = (results[file] ?? [])
+                    .filter((error) => !protectedSource.containsFinding(error))
+                    .map((error) => {
+                        if (!error.fixInfo || !protectedSource.containsFix(error)) return error;
+                        const { fixInfo: _fixInfo, ...unfixable } = error;
+                        return unfixable;
+                    });
+            }
+            return results;
+        };
+        let results = await lintSources(files);
         if (fix) {
             const toFix = [];
             for (const file of files) {
@@ -555,11 +584,15 @@ export async function runMarkdownlint(params) {
                 const fixable = (results[file] ?? []).filter((error) => error.fixInfo);
                 if (!fixable.length) continue;
                 const original = fs.readFileSync(file, "utf8");
-                fs.writeFileSync(file, applyFixes(original, fixable), "utf8");
+                const fixed =
+                    sources.get(file).protected ?
+                        applyVerseSafeFixes(original, fixable)
+                    :   applyFixes(original, fixable);
+                fs.writeFileSync(file, fixed, "utf8");
+                sources.set(file, protectLintVerse(fixed));
                 toFix.push(file);
             }
-            if (toFix.length)
-                results = { ...results, ...(await lint({ ...options, files: toFix })) };
+            if (toFix.length) results = { ...results, ...(await lintSources(toFix)) };
         }
         for (const [file, errors] of Object.entries(results)) resultsByFile.set(file, errors);
     }
@@ -581,3 +614,155 @@ export async function runMarkdownlint(params) {
     );
     return { results: flat, markup };
 }
+
+/**
+ * Hide verse content from Markdown rules and inline configuration without moving
+ * any authored coordinate. Container prefixes and div delimiters remain visible.
+ * @param {string} source - Original file contents.
+ * @returns {object} Masked text and predicates guarding findings and fixes.
+ */
+function protectLintVerse(source) {
+    const syntax = source.replace(/^\uFEFF?---\r?\n[^]*?\r?\n---(?:\r?\n|$)/, (frontmatter) =>
+        frontmatter.replace(/[^\r\n]/g, " "),
+    );
+    const starts = [0];
+    for (const match of source.matchAll(/\r\n|\r|\n/g)) starts.push(match.index + match[0].length);
+    const endOfLine = (line) => {
+        const past = starts[line + 1] ?? source.length;
+        return past - (/\r\n$|[\r\n]$/.exec(source.slice(starts[line], past))?.[0].length ?? 0);
+    };
+    const ranges = [],
+        masks = [],
+        inlineMasks = [],
+        spanBrackets = [],
+        bodyLines = new Set(),
+        verseLines = [],
+        usedReferences = new Set(),
+        footnotes = footnoteLabels(syntax);
+    const referencesInVerse = (text, model) => {
+        const titles = model.groups
+            .filter((group) => group.cantoBreak && group.title)
+            .map((group) => group.title);
+        for (const fragment of [text, ...titles])
+            for (const reference of footnoteReferences(fragment, {
+                definitions: footnotes,
+                inline: true,
+            }))
+                usedReferences.add(referenceParser.utils.normalizeReference(`^${reference.key}`));
+        for (const group of model.groups) {
+            if (group.cantoBreak) {
+                if (group.title) verseLines.push(group.title);
+            } else for (const line of group.lines) verseLines.push(line.text);
+        }
+    };
+    for (const region of verseRegions(syntax)) {
+        if (!region.closed) continue;
+        referencesInVerse(region.body, parseVerse(region.body, { footnotes }));
+        ranges.push([region.bodyStart, starts[region.end]]);
+        for (let line = region.start + 1; line < region.end; line++) {
+            bodyLines.add(line + 1);
+            masks.push([
+                Math.min(region.contentStarts[line - region.start], endOfLine(line)),
+                endOfLine(line),
+            ]);
+        }
+    }
+    for (const span of scanSpans(syntax).spans) {
+        if (!span.verseModel || source[span.end - 1] !== "}") continue;
+        referencesInVerse(span.text, span.verseModel);
+        ranges.push([span.start + 1, span.contentEnd]);
+        spanBrackets.push(span.start, span.contentEnd);
+        // Inline tokens omit quote/list prefixes. Continuation content ends
+        // at its physical line ending (or the located closing bracket), so
+        // its parsed length gives the content start without parsing prefixes.
+        const contentLines = span.text.replace(/\r\n?/g, "\n").split("\n");
+        for (const [index, content] of contentLines.entries()) {
+            const line = span.line - 1 + index;
+            const to = Math.min(endOfLine(line), span.contentEnd);
+            inlineMasks.push([index === 0 ? span.start + 1 : to - content.length, to]);
+        }
+    }
+    const raw = source.split("");
+    for (const [from, to] of masks)
+        for (let at = from; at < to; at++) if (!/[\r\n]/.test(raw[at])) raw[at] = " ";
+    // A blanked physical span line would split its surrounding paragraph.
+    // Neutralize its bracket delimiters too, so the mask cannot manufacture
+    // a reference shortcut to an unrelated definition with the same label.
+    for (const [from, to] of inlineMasks)
+        for (let at = from; at < to; at++) if (/\S/.test(raw[at])) raw[at] = "x";
+    for (const at of spanBrackets) raw[at] = "x";
+    const masked = raw.join("");
+    if (ranges.length) {
+        const env = {};
+        referenceParser.parse(masked, env);
+        // Reference links and images carry their normalized definition label
+        // on the actual emitted token. Speculative parser lookups do not count.
+        const collect = (tokens) => {
+            for (const token of tokens) {
+                const label = token.meta?.label;
+                if (["link_open", "image"].includes(token.type) && label) usedReferences.add(label);
+                if (token.children) collect(token.children);
+            }
+        };
+        for (const line of verseLines) {
+            const tokens = [];
+            referenceParser.inline.parse(line, referenceParser, env, tokens);
+            collect(tokens);
+        }
+    }
+    const intersects = (from, to) => ranges.some(([start, end]) => from < end && to > start);
+    return {
+        text: masked,
+        protected: ranges.length > 0,
+        containsFinding(error) {
+            if (error.ruleNames.includes("MD053")) {
+                const unused = /^Unused link or image reference definition: "([^]*)"$/.exec(
+                    error.errorDetail ?? "",
+                );
+                if (
+                    unused &&
+                    usedReferences.has(referenceParser.utils.normalizeReference(unused[1]))
+                )
+                    return true;
+            }
+            if (bodyLines.has(error.lineNumber)) return true;
+            if (!error.errorRange) return false;
+            const from = starts[error.lineNumber - 1] + error.errorRange[0] - 1;
+            return intersects(from, from + error.errorRange[1]);
+        },
+        containsFix(error) {
+            const fix = error.fixInfo;
+            const line = (fix.lineNumber || error.lineNumber) - 1;
+            const from = starts[line] + (fix.editColumn || 1) - 1;
+            if (fix.deleteCount === -1)
+                return intersects(starts[line], starts[line + 1] ?? source.length);
+            if (intersects(from, from + (fix.deleteCount ?? 0))) return true;
+            return Boolean(
+                fix.insertText && ranges.some(([start, end]) => from >= start && from <= end),
+            );
+        },
+    };
+}
+
+/**
+ * Apply fixes per original line so fixing prose cannot normalize the untouched
+ * line endings of a verse region elsewhere in a mixed-ending file.
+ * @param {string} source - Original file contents.
+ * @param {object[]} errors - Findings whose fixes do not intersect verse.
+ * @returns {string} Source with only the permitted fixes applied.
+ */
+function applyVerseSafeFixes(source, errors) {
+    const byLine = new Map();
+    for (const error of errors) {
+        const line = error.fixInfo.lineNumber || error.lineNumber;
+        if (!byLine.has(line)) byLine.set(line, []);
+        byLine
+            .get(line)
+            .push({ ...error, lineNumber: 1, fixInfo: { ...error.fixInfo, lineNumber: 1 } });
+    }
+    let line = 0;
+    return source.replace(/[^\r\n]*(?:\r\n|\r|\n|$)/g, (original) => {
+        const fixes = byLine.get(++line);
+        return fixes ? applyFixes(original, fixes) : original;
+    });
+}

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/verse-format.mjs

@@ -15,11 +15,13 @@
 
 import { verseRegions } from "./verse-regions.mjs";
 import { scanSpans } from "./content-spans.mjs";
+import { util } from "prettier";
 
 /**
- * Replace verse markup with opaque placeholders and restore its original bytes.
+ * 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 exact restoration.
+ * @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) =>
@@ -28,7 +30,7 @@ export function protectVerseSource(source) {
     const ranges = [
         ...verseRegions(syntax)
             .filter((region) => region.closed)
-            .map((region) => ({ from: region.from, to: region.to, block: true })),
+            .map((region) => ({ from: region.contentStarts[0], to: region.to, block: true })),
         ...scanSpans(syntax)
             .spans.filter((span) =>
                 span.attrs.some(
@@ -43,33 +45,43 @@ export function protectVerseSource(source) {
                 .slice(0, index)
                 .some((parent) => parent.from <= range.from && parent.to >= range.to),
     );
-    let prefix = "VERSEPROTECTEDTOKEN";
-    while (source.includes(prefix)) prefix += "X";
+    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 marker = range.block ? `<!--${prefix}${index}-->` : `${prefix}${index}END`;
-        return { ...range, original, marker, newline: range.block && /\r?\n$/.test(original) };
+        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 ? "\n" : "") +
+            (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 =
-                    entry.block ?
-                        new RegExp(`^[ \t]*${escaped}${entry.newline ? "\\r?\\n" : ""}`, "m")
-                    :   new RegExp(escaped);
+                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);
+                restored = restored.replace(pattern, () =>
+                    entry.original.replace(/\r\n|\r|\n/g, newline),
+                );
             }
             return restored;
         },