@heroiclands/package-build 25.2.1 → 25.4.0

package/engine/first-use.mjs

@@ -45,6 +45,7 @@ import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
 import MarkdownIt from "markdown-it";
 import { readQualifier } from "./address.mjs";
+import { verseRegions } from "./verse-regions.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { RUN_KEYS } from "./content-scripts.mjs";
@@ -169,14 +170,37 @@ const overlaps = (values, value) => {
  * Explicit inline occurrences, authored strong text and structural exclusions
  * at original source offsets.
  */
-function prose(source, capturedNames) {
+function prose(source, capturedNames, capturedSpans) {
     const links = [],
         paragraphs = [],
         regions = [],
         excluded = [],
         strong = [],
         html = [];
-    const masked = source
+    const spans = capturedSpans ?? scanSpans(source);
+    const verseMasks = verseRegions(source).map((region) => ({
+        start: region.from,
+        end: region.to,
+        block: true,
+    }));
+    for (const span of spans.spans)
+        if (
+            span.verseModel ||
+            span.attrs.some(
+                ([key, value]) => key === "class" && value.split(/\s+/).includes("verse"),
+            )
+        )
+            verseMasks.push({ start: span.start, end: span.end, block: false });
+    excluded.push(...verseMasks);
+    const verseRanges = verseMasks
+        .sort((a, b) => a.start - b.start || b.end - a.end)
+        .filter(
+            (range, index, all) =>
+                !all
+                    .slice(0, index)
+                    .some((parent) => parent.start <= range.start && parent.end >= range.end),
+        );
+    let masked = source
         .replace(/!\[\[[^\]\n]+\]\]|\{\{[^}\n]+\}\}/g, (text, start) => {
             excluded.push({ start, end: start + text.length });
             return blank(text);
@@ -193,6 +217,11 @@ function prose(source, capturedNames) {
             });
             return "x".repeat(text.length);
         });
+    for (const range of [...verseRanges].reverse())
+        masked =
+            masked.slice(0, range.start) +
+            masked.slice(range.start, range.end).replace(/[^\r\n]/g, range.block ? " " : "x") +
+            masked.slice(range.end);
     const tree = parser.parse(masked);
     const env = { references: Object.create(null) };
     const inline = (node) => {
@@ -285,7 +314,7 @@ function prose(source, capturedNames) {
     });
     const authoredLinks = [...new Map(actualLinks.map((link) => [link.start, link])).values()];
     const linked = ranges(authoredLinks);
-    const marked = (capturedNames ?? scanSpans(source).names)
+    const marked = (capturedNames ?? spans.names)
         .filter((span) => eligible(span) && !contains(linked, span))
         .map((span) => ({
             ...span,
@@ -373,7 +402,7 @@ export function nameUses(markdown, vocabulary) {
     // Every use carries the class, so a body without it is read no further.
     if (!source.includes(".name")) return [];
     const spans = scanSpans(source);
-    const { marked, links, strong, inParagraph } = prose(source, spans.names);
+    const { marked, links, strong, inParagraph } = prose(source, spans.names, spans);
     const starts = [0];
     for (let i = 0; i < source.length; i++) if (source[i] === "\n") starts.push(i + 1);
     // A caption and a named block's opening and closing lines are not prose.
@@ -527,14 +556,16 @@ export function createFirstUseChecker({
     const { recognize } = catalog;
     return ({ file, raw }) => {
         const authored = parsed?.get(file);
-        const capturedNames =
-            authored?.raw === raw && Number.isInteger(authored.bodyLine) ?
-                rebaseNameSpans(
-                    (syntax ? syntax(authored.body).spans : scanSpans(authored.body)).names,
-                    { raw, bodyLine: authored.bodyLine, bodyColumn: authored.bodyColumn },
-                )
-            :   undefined;
-        const { marked } = prose(raw, capturedNames);
+        let captured;
+        if (authored?.raw === raw && Number.isInteger(authored.bodyLine)) {
+            const inventory = syntax ? syntax(authored.body).spans : scanSpans(authored.body);
+            const context = { raw, bodyLine: authored.bodyLine, bodyColumn: authored.bodyColumn };
+            captured = {
+                names: rebaseNameSpans(inventory.names, context),
+                spans: rebaseNameSpans(inventory.spans, context),
+            };
+        }
+        const { marked } = prose(raw, captured?.names, captured);
         const findings = new Map();
         const add = (offset, rule, message) => {
             if (!findings.has(offset)) findings.set(offset, { rules: [], messages: [] });

package/engine/heading-attributes.mjs

@@ -40,7 +40,8 @@ import { blockTokens } from "./markdown-blocks.mjs";
 function literalHeadingLines(source) {
     const lines = new Set();
     for (const token of blockTokens(source)) {
-        if (!token.map || !["fence", "code_block", "html_block"].includes(token.type)) continue;
+        if (!token.map || !["fence", "code_block", "html_block", "verse_div"].includes(token.type))
+            continue;
         for (let line = token.map[0]; line < token.map[1]; line++) lines.add(line);
     }
     return lines;

package/engine/journals.mjs

@@ -76,6 +76,7 @@ import { journalHasContent } from "./note-state.mjs";
 import { hasLexicalEntries } from "./lexical-sections.mjs";
 import { draftNoticeFor } from "./draft-notice.mjs";
 import { scanFigures } from "./content-figures.mjs";
+import { verseRegions } from "./verse-regions.mjs";
 import { separateFootnotes } from "./content-footnotes.mjs";
 import { WITHHELD_CLASS, pageOpenings } from "./heading-attributes.mjs";
 import { imagesIn } from "./content-images.mjs";
@@ -154,6 +155,12 @@ export function splitPages(body, leadName = "Introduction", resolveRole, syntax)
         scanFigures(markdown, { resolveRole }).figures.map((figure) => [figure.line - 1, figure]),
     );
     const blockLines = namedBlockLines(markdown, syntax);
+    const verseLines = new Set();
+    for (const region of verseRegions(markdown))
+        for (let line = region.start; line <= region.end; line++) {
+            blockLines.add(line);
+            verseLines.add(line);
+        }
     const openings = pageOpenings(markdown, blockLines);
     const pages = [];
     const beforeFirstH1 = [];
@@ -189,7 +196,7 @@ export function splitPages(body, leadName = "Introduction", resolveRole, syntax)
         // carry a shorter fence of its own as literal content, same as
         // {@link module:engine/content-blocks.scanBlocks} and
         // {@link module:engine/content-figures.scanFigures} track it.
-        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        const fence = verseLines.has(lineIndex) ? null : /^ {0,3}(`{3,}|~{3,})/.exec(line);
         if (codeFence) {
             if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
                 codeFence = null;

package/engine/markdown-blocks.mjs

@@ -25,9 +25,10 @@
  */
 
 import MarkdownIt from "markdown-it";
+import { verseDivPlugin } from "./verse-regions.mjs";
 
 /** The renderer's block grammar, with inline parsing and its passes switched off. */
-const parser = new MarkdownIt({ html: true });
+const parser = new MarkdownIt({ html: true }).use(verseDivPlugin);
 parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
 
 /** How many recent sources keep their tokens. */
@@ -51,7 +52,7 @@ export function blockTokens(source) {
         recent.set(text, hit);
         return hit;
     }
-    const tokens = parser.parse(text, {});
+    const tokens = parser.parse(text, { verseSource: text });
     recent.set(text, tokens);
     if (recent.size > RECENT) recent.delete(recent.keys().next().value);
     return tokens;

package/engine/markup-validation.mjs

@@ -14,6 +14,8 @@
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
 import { scanRuns } from "./content-scripts.mjs";
+import { scanSpans } from "./content-spans.mjs";
+import { verseRegions } from "./verse-regions.mjs";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 
 /** The opening of a shortcode: `{{<` or `{{%`. */
@@ -55,9 +57,24 @@ export function markupFindings(source, file, syntax, runs) {
     );
     const scanned = syntax?.(body);
     const marked = runs ? scanRuns(body, runs, syntax) : undefined;
+    const spans = scanned?.spans ?? scanSpans(body);
+    const verseRanges = [
+        ...verseRegions(body).map((region) => [region.from, region.to]),
+        ...spans.spans.filter((span) => span.verseModel).map((span) => [span.start, span.end]),
+    ];
+    const starts = [0];
+    for (const match of body.matchAll(/\n/g)) starts.push(match.index + 1);
+    const verseErrors = spans.errors.filter((error) => {
+        const offset = (starts[error.line - 1] ?? 0) + error.column - 1;
+        return (
+            error.message.includes(".verse") ||
+            verseRanges.some(([from, to]) => offset >= from && offset < to)
+        );
+    });
     const errors = [
         ...(scanned?.blocks ?? scanBlocks(body)).errors,
         ...(scanned?.alerts ?? scanAlerts(body)).errors,
+        ...verseErrors,
         ...(marked?.errors ?? []),
         ...shortcodeErrors(body),
     ].map((error) => ({

package/engine/name-markup.mjs

@@ -42,6 +42,7 @@
  * @property {string} visible - Visible text from the actual parsed children.
  * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
  * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ * @property {ReturnType<typeof import("./content-verse.mjs").parseVerse>} [verseModel] - Logical model of an inline verse quotation.
  */
 
 /**

package/engine/note-vocabulary.mjs

@@ -2338,7 +2338,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                             ...TEXT,
                             required: true,
                             describe:
-                                "What a verse fence's `scan=` names the metre by: lowercase " +
+                                "What a verse div's `scan=` names the metre by: lowercase " +
                                 "letters, digits and `-`, unique in the package.",
                         },
                         {
@@ -2362,7 +2362,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                     ]),
                 }),
                 describe:
-                    "The metres a verse fence's `scan=` names. A fence that states one is " +
+                    "The metres a verse div's `scan=` names. A div that states one is " +
                     "warned at each line that cannot have its beats. See " +
                     "[metres](../authoring/links-and-markup.md#metre).",
             },

package/engine/pdf-render.mjs

@@ -86,13 +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 {
-    hasColumns,
-    lineNumber,
-    rightToLeft,
-    scanVerse,
-    verseColumnCount,
-} 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";
@@ -505,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,
@@ -519,10 +513,19 @@ 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;
-    if (marked) sharedOptions.scrolls = marked.scrolls;
+        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;
+    }
     // One map for the whole body, not one per block: a heading inside a
     // blockquote or a list item shares the entry's anchor namespace with every
     // other heading in the same body, because `sectionLabel` scopes by entry
@@ -543,6 +546,7 @@ export function markdownToTypst(markdown, opts = {}) {
         footnoteState,
         footnotePrefix: opts.footnotePrefix ?? `footnote-${slugify(anchorPrefix || "body")}`,
         scrolls: marked?.scrolls ?? opts.scrolls ?? new Map(),
+        verses: marked?.verses ?? opts.verses ?? new Map(),
     };
     // A withheld section is set in the box a `:::secret` is set in, and its
     // heading is set inside it: a printed page honours no reader permission, so
@@ -691,7 +695,7 @@ export function markdownToTypst(markdown, opts = {}) {
 /** Render one fragment with the note's footnote definitions available. */
 function renderMarkdownSegment(source, md, ctx, definitions) {
     const input = definitions ? `${source}\n\n${definitions}` : source;
-    const tokens = md.parse(input, {});
+    const tokens = md.parse(input, { verses: ctx.verses });
     const footnoteStart = tokens.findIndex((token) => token.type === "footnote_block_open");
     const visible = footnoteStart < 0 ? tokens : tokens.slice(0, footnoteStart);
     const footnotes = new Map();
@@ -777,37 +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}`);
-                // Findings are collected before rendering. Keep malformed verse
-                // literal rather than assigning invalid parts to display cells.
-                if (scanned.errors.length) {
-                    out.push(rawBlock(token.content, token.info));
-                    return 1;
-                }
-                const poem = scanned.blocks[0];
-                const step = Number(poem?.attributes.numstep ?? 0) || 0;
-                const content =
-                    hasColumns(poem) ? verseGrid(token, poem, step, ctx)
-                    : step ? numberedVerse(token, step, ctx)
-                    : token.meta.verseStanzas
-                            .map((stanza) =>
-                                stanza[0]?.stanzaBreak ?
-                                    "#v(0.5em)"
-                                :   stanza
-                                        .map(({ children, level }) => {
-                                            const verse = renderInline({ children }, ctx);
-                                            return `${level ? `#h(${level * 1.25}em)` : ""}${verse}`;
-                                        })
-                                        .join(" \\\n"),
-                            )
-                            .join("\n\n");
-                const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
-                out.push(
-                    `\n#block(width: 100%)[${scriptWrapped(content, poem?.classes, poem?.attributes)}]${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":
@@ -1300,90 +1281,58 @@ function typstLanguage(tag) {
 /** The classes that set a run in a font: a face's run carries `script`. */
 const FONT_CLASSES = Object.freeze(["script", ...Object.values(GENERIC_FONTS)]);
 
-/** A line number in the book: muted, as on the page. */
-const typstNumber = (number) => (number ? `[#text(fill: luma(45%))[${number}]]` : "[]");
-
-/**
- * A numbered verse without columns: a grid of each line's number and the
- * line, with a row of space between stanzas.
- *
- * @param {object} token - The verse's fence token.
- * @param {number} step - Its `numstep`.
- * @param {object} ctx - Render context.
- * @returns {string} Typst markup.
- */
-function numberedVerse(token, step, ctx) {
-    let count = 0;
-    const stanzas = token.meta.verseStanzas.map((stanza) =>
-        stanza[0]?.stanzaBreak ?
-            "  grid.cell(colspan: 2)[#v(0.5em)],"
-        :   stanza
-                .map(({ children, level }) => {
-                    const verse = renderInline({ children }, ctx);
-                    return `  ${typstNumber(lineNumber(++count, step))}, [${level ? `#h(${level * 1.25}em)` : ""}${verse}],`;
-                })
-                .join("\n"),
-    );
-    return [
-        "#grid(columns: (2.5em, 1fr), column-gutter: 1em, row-gutter: 0.35em,",
-        stanzas.join("\n  grid.cell(colspan: 2)[#v(0.5em)],\n"),
-        ")",
-    ].join("\n");
-}
-
-/**
- * A verse in columns: a grid with a row per verse line, its number first when
- * the verse is numbered, then each column's entries stacked, the first in the
- * normal tone and each later one grey. A part whose text runs right to left
- * is set right to left inside its cell; the grid stays left to right so
- * numbered columns retain their authored order. A `***` line is a row of space
- * across the grid.
- *
- * @param {object} token - The verse's fence token with parsed logical rows.
- * @param {object} poem - The verse, from `scanVerse`.
- * @param {number} step - Its `numstep`.
- * @param {object} ctx - Render context.
- * @returns {string} Typst markup.
- */
-function verseGrid(token, poem, step, ctx) {
-    const count = verseColumnCount(poem);
-    const width = count + (step ? 1 : 0);
-    const columns = [...(step ? ["2.5em"] : []), ...Array(count).fill("1fr")];
-    const rows = [];
-    let row = 0;
-    for (const group of token.meta.verseGroups) {
-        if (group.stanzaBreak) {
-            rows.push(`  grid.cell(colspan: ${width})[#v(0.5em)],`);
-            continue;
-        }
-        const cells = Array.from({ length: count }, () => []);
-        for (const part of group.parts) {
-            const rtl = rightToLeft(part.text);
-            const secondary = cells[part.column - 1].length > 0;
-            const text = renderInline(
-                { children: part.children },
-                secondary ? { ...ctx, textFill: "luma(45%)" } : ctx,
+/** 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 = token.type !== "verse_inline" && Boolean(poem?.attributes.work);
+    const nativeClasses = paired?.classes ?? poem?.classes;
+    const nativeAttributes = paired?.attributes ?? poem?.attributes;
+    const body = (token.meta.verseGroups ?? [])
+        .map((group) => {
+            if (group.cantoBreak) {
+                const mark =
+                    group.children?.length ? renderInline({ children: group.children }, ctx) : "";
+                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) => {
+                const text = renderInline(
+                    { children: roman ? line.romanChildren : line.children },
+                    ctx,
+                );
+                const padded = `${line.level ? `#h(${line.level * 1.25}em)` : ""}${text}`;
+                if (roman || !paired) return padded;
+                const wrapped = scriptWrapped(padded, nativeClasses, nativeAttributes);
+                return rightToLeft(line.text) ? `#set text(dir: rtl)\n${wrapped}` : wrapped;
+            };
+            if (!paired) {
+                const lines = scriptWrapped(
+                    group.lines.map((line) => lineText(line)).join(" \\\n"),
+                    nativeClasses,
+                    nativeAttributes,
+                );
+                return labelled ?
+                        `#grid(columns: (2.5em, 1fr), column-gutter: 0.5em, [${label}], [${lines}])`
+                    :   lines;
+            }
+            const cells = group.lines.map((line, index) =>
+                [
+                    ...(labelled ? [index === 0 ? `[${label}]` : "[]"] : []),
+                    `[${lineText(line)}]`,
+                    `[${lineText(line, true)}]`,
+                ].join(", "),
             );
-            const padded =
-                part.indent ?
-                    `#pad(${rtl ? "right" : "left"}: ${part.indent * 1.25}em)[${text}]`
-                :   text;
-            cells[part.column - 1].push(rtl ? `#set text(dir: rtl)\n${padded}` : padded);
-        }
-        const rendered = cells.map((stacked) => {
-            if (!stacked.length) return "[]";
-            if (stacked.length === 1) return `[${stacked[0]}]`;
-            return `[#stack(dir: ttb, spacing: 0.3em, ${stacked.map((part, k) => (k ? `[#text(fill: luma(45%))[${part}]]` : `[${part}]`)).join(", ")})]`;
-        });
-        const number = step ? [typstNumber(lineNumber(++row, step))] : [];
-        rows.push(`  ${[...number, ...rendered].join(", ")},`);
-    }
-    return [
-        "#set text(dir: ltr)",
-        `#grid(columns: (${columns.join(", ")}), column-gutter: 1.5em, row-gutter: 0.65em,`,
-        ...rows,
-        ")",
-    ].join("\n");
+            const columns = labelled ? "2.5em, 1fr, 1fr" : "1fr, 1fr";
+            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;
 }
 
 /**
@@ -1430,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+/);
@@ -1719,8 +1674,7 @@ function pageOfLabel(label) {
  * @returns {string} Typst markup.
  */
 function renderLink(href, inner, ctx, { bracketed = false } = {}) {
-    // A secondary verse reading keeps its label gray inside the global blue
-    // link presentation, including any native spans or emphasis in that label.
+    // A caller's explicit text fill applies inside the link's label.
     if (ctx.textFill) inner = `#text(fill: ${ctx.textFill})[${inner}]`;
     const url = String(href ?? "");
     const fragment = /#([^?]*)/.exec(url)?.[1] ?? "";
@@ -2012,9 +1966,14 @@ export function bookTypstPreamble(runs = {}, families = {}) {
             "  }\n" +
             "  if lang != none { text(lang: lang, styled) } else { styled }\n" +
             "}",
-        // Span classes reach the book intact.
+        // Plain semantic hooks retain the span classes without choosing their appearance.
+        "#let book-direction(body) = body",
+        "#let book-speaker(body) = body",
         "#let book-span(body, classes: (), lang: none) = {\n" +
-            "  box(book-script-text(body, classes: classes, lang: lang))\n" +
+            "  let styled = book-script-text(body, classes: classes, lang: lang)\n" +
+            '  if "direction" in classes { styled = book-direction(styled) }\n' +
+            '  if "speaker" in classes { styled = book-speaker(styled) }\n' +
+            "  box(styled)\n" +
             "}",
         // Use the file's natural measure for auto. Every requested width is
         // bounded by the available measure and by the height of a page.

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",