@heroiclands/package-build 25.3.0 → 25.5.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)
@@ -107,12 +114,21 @@ const CONTAINER_PREFIX = /^(?:[ \t]{0,3}>[ \t]?|[ \t]{0,3}(?:[-*+]|\d{1,9}[.)])[
  */
 export function misplacedFootnoteDefinitions(source) {
     const lines = String(source ?? "").split("\n");
+    const verseLines = new Set(
+        verseRegions(String(source ?? "")).flatMap((region) =>
+            Array.from({ length: region.end - region.start + 1 }, (_, i) => region.start + i),
+        ),
+    );
     const errors = [];
     let fence = null;
     // Inside the continuation of a genuine top-level definition: a blank
     // line or a four-space indent belongs to it, not to a new mistake.
     let continuation = false;
     for (let i = 0; i < lines.length; i++) {
+        if (verseLines.has(i)) {
+            continuation = false;
+            continue;
+        }
         const line = lines[i];
         const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
         if (fence) {
@@ -240,3 +256,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 { inlineVerse, scanVerse } 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,48 +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, { checkWorks: false }).blocks[0];
-            if (!poem) continue;
-            const paired = state.env.verses?.get(token.content.replace(/\n$/, ""));
-            const model = paired?.model ?? poem.model;
-            token.meta.verse = poem;
-            token.meta.versePaired = paired;
-            const parse = (text) => {
-                const children = [];
-                state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
-                return children;
-            };
-            token.meta.verseGroups = model.groups.map((group) =>
-                group.cantoBreak ?
-                    { ...group, children: group.text ? parse(group.text) : [] }
-                :   {
-                        ...group,
-                        lines: group.lines.map((line) => ({
-                            ...line,
-                            children: parse(line.text),
-                            ...(paired ?
-                                { romanChildren: parse(line.romanText ?? line.text) }
-                            :   {}),
-                        })),
-                    },
-            );
+            if (token.type !== "verse_div") continue;
+            parseVerseContent(token, state.md, state.env, token.meta.verseRegion);
         }
     });
 }
@@ -384,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);
@@ -456,6 +469,7 @@ export function createRenderer(target, options = {}) {
                 renderInline,
             },
         ).markdown;
+        text = renderVerseQuotes(text);
         if (target === "web") text = renderSpans(text).markdown;
         return target === "web" ? renderWithheldSections(text) : text;
     };
@@ -476,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 ?? ""))))
+            ),
     };
 }