@heroiclands/package-build 25.2.1 → 25.4.0

package/engine/content-figures.mjs

@@ -18,6 +18,7 @@ import MarkdownIt from "markdown-it";
 import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 
+import { verseRegions } from "./verse-regions.mjs";
 import { slugify } from "./content-slug.mjs";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
 import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
@@ -184,9 +185,20 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         errors = [],
         ids = new Set();
     const counts = {};
+    const verse = verseRegions(String(source ?? ""));
+    const verseStarts = new Map(verse.map((region) => [region.start, region]));
+    const verseLines = new Set(
+        verse.flatMap((region) =>
+            Array.from(
+                { length: region.end - region.start + 1 },
+                (_, index) => region.start + index,
+            ),
+        ),
+    );
     let codeFence = null;
     const fault = (line, message) => errors.push({ line: line + 1, column: 1, message });
     for (let i = 0; i < lines.length; i++) {
+        if (verseLines.has(i)) continue;
         const fence = FENCE.exec(lines[i]);
         if (codeFence) {
             if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
@@ -233,7 +245,11 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
         let bodyEnd;
         const firstLine = lines[bodyStart];
         let kind;
-        if (/^ {0,3}:::(?:[ \t]+\{.*\})?[ \t]*$/.test(firstLine)) {
+        if (verseStarts.has(bodyStart)) {
+            const region = verseStarts.get(bodyStart);
+            bodyEnd = region.end + 1;
+            kind = "poem";
+        } else if (/^ {0,3}:::(?:[ \t]+\{.*\})?[ \t]*$/.test(firstLine)) {
             let depth = 1,
                 literal = null;
             bodyEnd = bodyStart + 1;
@@ -305,10 +321,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
                 fault(bodyStart, "this block cannot be captioned");
                 continue;
             }
-            kind =
-                first.type === "fence" && /^verse(?:\s|$)/.test(first.info) ?
-                    "poem"
-                :   figureKind(first, contents.trim(), resolveRole);
+            kind = figureKind(first, contents.trim(), resolveRole);
         }
         if (explicit) kind = explicit === "verse" ? "poem" : explicit;
         const id = attributes.id;
@@ -338,6 +351,7 @@ export function scanFigures(source, { resolveRole = () => undefined } = {}) {
     }
     let literal = null;
     for (let at = 0; at < lines.length; at++) {
+        if (verseLines.has(at)) continue;
         const fence = FENCE.exec(lines[at]);
         if (literal) {
             if (fence && fence[1][0] === literal[0] && fence[1].length >= literal.length)

package/engine/content-footnotes.mjs

@@ -29,7 +29,8 @@
  * @module
  */
 
-import { matchAllOutsideCode } from "./code-fences.mjs";
+import { inlineSyntaxRanges, verseRegions } from "./verse-regions.mjs";
+import { codeRegions, matchAllOutsideCode } from "./code-fences.mjs";
 
 /**
  * Where a character offset in `source` falls, as a 1-based line and column.
@@ -52,9 +53,15 @@ function lineColumn(source, offset) {
 export function separateFootnotes(source) {
     const lines = String(source ?? "").split("\n");
     const body = [...lines];
+    const verseLines = new Set(
+        verseRegions(String(source ?? "")).flatMap((region) =>
+            Array.from({ length: region.end - region.start + 1 }, (_, i) => region.start + i),
+        ),
+    );
     const definitions = [];
     let fence = null;
     for (let i = 0; i < lines.length; i++) {
+        if (verseLines.has(i)) continue;
         const marker = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
         if (fence) {
             if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length)
@@ -240,3 +247,55 @@ export function footnoteFindings(source) {
         (a, b) => a.line - b.line || a.column - b.column,
     );
 }
+
+/**
+ * Labels defined at the top level of this note.
+ * @param {string} source - Complete authored note Markdown.
+ * @returns {Set<string>} Same-note footnote labels.
+ */
+export function footnoteLabels(source) {
+    if (!source.includes("[^")) return new Set();
+    return new Set(
+        [...separateFootnotes(source).definitions.matchAll(/^\[\^([^\]\s]+)\]:/gm)].map(
+            (match) => match[1],
+        ),
+    );
+}
+
+/**
+ * Actual defined references, excluding literal code, escapes and metadata.
+ * @param {string} source - Full note or raw inline fragment.
+ * @param {object} [options] - Definition context and source grammar.
+ * @param {ReadonlySet<string>} [options.definitions] - Same-note labels; derived from source when omitted.
+ * @param {boolean} [options.inline] - Treat all source as inline verse/prose.
+ * @returns {Array<{from:number,to:number,key:string,text:string}>} Original UTF-16 source ranges.
+ */
+export function footnoteReferences(
+    source,
+    { definitions = footnoteLabels(source), inline = false } = {},
+) {
+    if (!definitions.size || !source.includes("[^")) return [];
+    const protectedRanges = inlineSyntaxRanges(source).filter(
+        ([from]) => source[from] !== "{" || source[from - 1] === "]",
+    );
+    const code = inline ? [] : codeRegions(source);
+    return [...source.matchAll(/\[\^([^\]\s]+)\]/g)].flatMap((match) => {
+        const from = match.index,
+            to = from + match[0].length;
+        const escapes = /\\+$/.exec(source.slice(0, from))?.[0].length ?? 0;
+        if (
+            !definitions.has(match[1]) ||
+            escapes % 2 ||
+            protectedRanges.some(([first, past]) => from >= first && from < past) ||
+            code.some((range) => from >= range.start && from < range.end)
+        )
+            return [];
+        if (
+            !inline &&
+            source[to] === ":" &&
+            /^[ \t]*$/.test(source.slice(source.lastIndexOf("\n", from - 1) + 1, from))
+        )
+            return [];
+        return [{ from, to, key: match[1], text: match[0] }];
+    });
+}

package/engine/content-index.mjs

@@ -1568,7 +1568,7 @@ function dynamicPublicationBody(body) {
     const source = String(body ?? "");
     return (
         [...matchAllOutsideCode(source, EXPRESSION)].length > 0 ||
-        codeRegions(source, { spans: false, verseAsProse: false }).some(({ start, end }) => {
+        codeRegions(source, { spans: false }).some(({ start, end }) => {
             const opener = FENCE_LINE.exec(source.slice(start, end).split("\n", 1)[0]);
             const language = opener && parseHeaderArgs(opener[3]).language;
             return language === "sql" || language === PAGE_LIST_LANGUAGE;

package/engine/content-render.mjs

@@ -47,7 +47,7 @@
  * 2. **Captioned items** — each figure's wrapper and label. Its number, kind
  *    and role come from the figure scan expansion made, so a figure is
  *    numbered once; see {@link module:engine/content-figures.renderFigureBlocks}.
- * 3. **Named blocks, verse and scrolls** — `:::` blocks, verse fences and
+ * 3. **Named blocks, verse and scrolls** — `:::` blocks, verse divs and
  *    `scroll` fences.
  * 4. **Alerts.**
  * 5. **Spans and withheld sections** — written here on the `web` target; the
@@ -79,7 +79,8 @@ import { imagePlugin } from "./content-images.mjs";
 import { renderRuns } from "./content-scripts.mjs";
 import { renderSpans, spanMarkdownPlugin } from "./content-spans.mjs";
 import { cartoucheFigures, renderSymbolSpans } from "./content-symbols.mjs";
-import { hasColumns, inlineVerse, scanVerse, verseGroups, verseStanzas } from "./content-verse.mjs";
+import { inlineVerse, parseVerse, renderVerseQuotes } from "./content-verse.mjs";
+import { verseDivPlugin } from "./verse-regions.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 import { dictionaryEntryPlugin } from "./dictionary-layout.mjs";
 import { headingAttributesPlugin, headingIdsPlugin } from "./heading-attributes.mjs";
@@ -115,50 +116,59 @@ export function highlightCode(code, language) {
     return hljs.highlight(code, { language: name, ignoreIllegals: true }).value;
 }
 
-/**
- * Parse the verse a `verse` fence holds as inline Markdown.
- *
- * A fence is literal to the block parser; a poem's lines are prose with
- * inline Markdown. The lines are parsed before footnote definitions are
- * collected, with the surrounding note's env, so a reference in a verse
- * resolves against definitions written outside the fence.
- *
- * @param {import("markdown-it")} md - Markdown parser to extend.
- */
+/** Parse logical verse lines in the note's shared inline environment. */
+function parseVerseContent(token, md, env, region) {
+    const body = token.type === "verse_inline" ? token.meta.text : token.content;
+    const inline = token.type === "verse_inline";
+    const paired = inline ? undefined : env.verses?.get(body);
+    const footnotes = new Set(Object.keys(env.footnotes?.refs ?? {}).map((key) => key.slice(1)));
+    const model = paired?.model ?? region.model ?? parseVerse(body, { inline, footnotes });
+    token.meta ??= {};
+    token.meta.verse = region;
+    token.meta.versePaired = paired;
+    const parse = (text) => {
+        const children = [];
+        md.inline.parse(inlineVerse(text), md, env, children);
+        return children;
+    };
+    token.meta.verseNotes = (model.notes ?? []).map((line) => ({
+        children: parse(line.romanText ?? line.text),
+    }));
+    token.meta.verseGroups = model.groups.map((group) =>
+        group.cantoBreak ?
+            {
+                ...group,
+                children: group.text ? parse(group.text) : [],
+                titleChildren: group.title ? parse(group.title) : [],
+            }
+        :   {
+                ...group,
+                lines: group.lines.map((line) => ({
+                    ...line,
+                    children: parse(line.text),
+                    ...(paired ? { romanChildren: parse(line.romanText ?? line.text) } : {}),
+                })),
+            },
+    );
+}
+
+/** An opaque quoted verse is parsed once, before footnote collection. */
+function quotedVerse(token, state) {
+    const classes = (token.attrGet("class") ?? "")
+        .split(/\s+/)
+        .filter((name) => name && name !== "verse");
+    const attributes = Object.fromEntries(
+        (token.attrs ?? []).filter(([key]) => !["id", "class"].includes(key)),
+    );
+    parseVerseContent(token, state.md, state.env, { id: token.attrGet("id"), classes, attributes });
+}
+
+/** A verse div's raw body receives inline parsing without block interpretation. */
 function verseInlinePlugin(md) {
     md.core.ruler.after("inline", "verse_inline", (state) => {
         for (const token of state.tokens) {
-            if (token.type !== "fence" || !/^verse(?:\s|$)/.test(token.info?.trim() || ""))
-                continue;
-            token.meta ??= {};
-            const source = `${token.markup}${token.info}\n${token.content}${token.markup}`;
-            const poem = scanVerse(source).blocks[0];
-            if (hasColumns(poem)) {
-                token.meta.verseGroups = verseGroups(poem, source.split("\n")).map((group) => {
-                    if (group.stanzaBreak) return group;
-                    return {
-                        ...group,
-                        parts: group.parts.map((part) => {
-                            const children = [];
-                            state.md.inline.parse(
-                                inlineVerse(part.text),
-                                state.md,
-                                state.env,
-                                children,
-                            );
-                            return { ...part, children };
-                        }),
-                    };
-                });
-                continue;
-            }
-            token.meta.verseStanzas = verseStanzas(token.content).map((stanza) =>
-                stanza.map(({ text, level }) => {
-                    const children = [];
-                    state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
-                    return { children, level, stanzaBreak: /^\*{3}$/.test(text) };
-                }),
-            );
+            if (token.type !== "verse_div") continue;
+            parseVerseContent(token, state.md, state.env, token.meta.verseRegion);
         }
     });
 }
@@ -386,7 +396,8 @@ export function createRenderer(target, options = {}) {
     use("footnotes", footnotePlugin);
     if (book) {
         use("alerts", alertMarkdownPlugin);
-        use("spans", spanMarkdownPlugin);
+        use("spans", spanMarkdownPlugin, { verseInline: quotedVerse });
+        use("verse-div", verseDivPlugin);
         use("verse-inline", verseInlinePlugin);
         use("script-emphasis", scriptEmphasisPlugin);
         use("definition-lists", deflistPlugin);
@@ -433,8 +444,12 @@ export function createRenderer(target, options = {}) {
     const prepare = (markdown, env = {}) => {
         let text = String(markdown ?? "");
         if (preview) text = sourceMalformedAlerts(text);
-        if (env.runs)
-            text = renderRuns(text, env.runs, undefined, { target: RUN_TARGET[target] }).markdown;
+        let verses = env.verses;
+        if (env.runs) {
+            const marked = renderRuns(text, env.runs, undefined, { target: RUN_TARGET[target] });
+            text = marked.markdown;
+            verses = marked.verses;
+        }
         // A glyph and a cartouche are pictures on every target that draws
         // HTML, so they are written before any stage renders a fragment. The
         // buffer-only preview shows a glyph as the source it was written in
@@ -448,12 +463,13 @@ export function createRenderer(target, options = {}) {
             { resolveRole: env.resolveRole, renderInline },
         );
         text = renderAlerts(
-            renderBlocks(figured.markdown, target, { renderInline }).markdown,
+            renderBlocks(figured.markdown, target, { renderInline, verses }).markdown,
             target,
             {
                 renderInline,
             },
         ).markdown;
+        text = renderVerseQuotes(text);
         if (target === "web") text = renderSpans(text).markdown;
         return target === "web" ? renderWithheldSections(text) : text;
     };
@@ -474,6 +490,8 @@ export function createRenderer(target, options = {}) {
                     )
             ),
         renderInline:
-            book ? unsupported : (markdown) => restore(md.renderInline(String(markdown ?? ""))),
+            book ? unsupported : (
+                (markdown) => restore(md.renderInline(renderVerseQuotes(String(markdown ?? ""))))
+            ),
     };
 }