@heroiclands/package-build 25.2.1 → 25.3.0

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, scanVerse } 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";
@@ -522,7 +516,10 @@ export function markdownToTypst(markdown, opts = {}) {
     const marked =
         opts.nested ? undefined : renderRuns(authored, opts.runs, undefined, { target: "book" });
     const source = marked ? marked.markdown : authored;
-    if (marked) sharedOptions.scrolls = marked.scrolls;
+    if (marked) {
+        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 +540,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 +689,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();
@@ -779,34 +777,19 @@ function renderBlock(tokens, i, out, ctx) {
             }
             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}`);
+                const scanned = scanVerse(`${opening}\n${token.content}${token.markup}`, {
+                    checkWorks: false,
+                });
                 // Findings are collected before rendering. Keep malformed verse
                 // literal rather than assigning invalid parts to display cells.
-                if (scanned.errors.length) {
+                if (scanned.errors.length && !token.meta?.versePaired) {
                     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 content = workVerse(token, poem, ctx);
                 const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
-                out.push(
-                    `\n#block(width: 100%)[${scriptWrapped(content, poem?.classes, poem?.attributes)}]${anchor}\n`,
-                );
+                out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
             } else out.push(rawBlock(token.content, token.info?.trim() || ""));
             return 1;
         }
@@ -1300,90 +1283,51 @@ 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 = Boolean(poem?.attributes.work);
+    const nativeClasses = paired?.classes ?? poem?.classes;
+    const nativeAttributes = paired?.attributes ?? poem?.attributes;
+    return (token.meta.verseGroups ?? [])
+        .map((group) => {
+            if (group.cantoBreak) {
+                const mark =
+                    group.children?.length ? renderInline({ children: group.children }, ctx) : "";
+                return `${mark ? scriptWrapped(mark, nativeClasses, nativeAttributes) + "\n" : ""}#v(0.5em)`;
+            }
+            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");
 }
 
 /**
@@ -1719,8 +1663,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 +1955,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/roman-verse.mjs

@@ -12,16 +12,15 @@
  */
 
 /** Logical verse text and separately located structural boundaries. @module */
-import { verseLine } from "./content-verse.mjs";
+import { parseVerse } from "./content-verse.mjs";
 import { plainRomanRun } from "./roman-run.mjs";
 
 /**
- * Remove visual indentation before checking or encoding Roman verse. Each
- * content line keeps its own boundary, including the last line before a stanza
- * or canto; those extra structural controls do not consume its line boundary.
- * The caller writes the boundaries through its selected encoding.
+ * Project verse text with explicit authored line, stanza and canto boundaries.
+ * Source newlines within a logical line are whitespace. Delimiters and visual
+ * indentation do not reach the encoder as letters.
  * @param {string} source - Complete authored source.
- * @param {Parameters<typeof plainRomanRun>[1] & {isCantoLine?: (line: string) => boolean}} [options] - Run bounds, spans and layout projection.
+ * @param {Parameters<typeof plainRomanRun>[1] & {model?: ReturnType<typeof parseVerse>, modelOffset?: number}} [options] - Run bounds, spans and layout projection.
  * @returns {ReturnType<typeof plainRomanRun> & {boundaries: Array<{kind: "line"|"stanza"|"canto", at: number, sourceOffset: number}>, errors: Array<{offset: number, message: string}>}} Visible text, positions and structural events.
  */
 export function plainRomanVerse(source, options = {}) {
@@ -29,28 +28,60 @@ export function plainRomanVerse(source, options = {}) {
         from = 0,
         to = source.length,
         exclude = [],
-        isCantoLine = (line) => /^\s*---\s+\{\.canto\}\s*$/.test(line),
+        model: sharedModel,
+        modelOffset = from,
     } = options;
-    const lines = [];
-    const layout = [...exclude];
-    let at = from;
-    for (const match of source.slice(from, to).matchAll(/([^\r\n]*)(\r\n|\r|\n|$)/g)) {
-        if (!match[0]) continue;
-        const line = match[1];
-        const end = at + line.length;
-        const kind =
-            isCantoLine(line) ? "canto"
-            : line.trim() ? "content"
-            : "blank";
-        lines.push({ from: at, to: end, kind });
-        if (kind === "canto") layout.push([at, end]);
-        else if (kind === "content") {
-            const { markerStart, markerLength } = verseLine(line);
-            if (markerLength) layout.push([at + markerStart, at + markerStart + markerLength]);
-        }
-        at += match[0].length;
+    const model = sharedModel ?? parseVerse(source.slice(from, to));
+    const base = sharedModel ? modelOffset : from;
+    const boundaries = model.boundaries
+        .map((boundary) => ({ ...boundary, sourceOffset: base + boundary.sourceOffset }))
+        .filter((boundary) => boundary.sourceOffset >= from && boundary.sourceOffset <= to);
+    const projected = plainRomanRun(source, {
+        ...options,
+        from,
+        to,
+        exclude: [
+            ...exclude,
+            ...model.layout
+                .map(([first, past]) => [Math.max(from, base + first), Math.min(to, base + past)])
+                .filter(([first, past]) => past > first),
+        ],
+    });
+    const text = [],
+        offsets = [],
+        positions = [],
+        ends = [];
+    const pending = [...boundaries];
+    let boundaryIndex = 0;
+    const appendBoundary = (boundary) => {
+        text.push("\n");
+        offsets.push(boundary.sourceOffset);
+    };
+    for (let index = 0; index < projected.text.length; index++) {
+        ends[index] = text.length;
+        while (
+            pending[boundaryIndex] &&
+            pending[boundaryIndex].sourceOffset <= projected.offsets[index]
+        )
+            appendBoundary(pending[boundaryIndex++]);
+        positions[index] = text.length;
+        const char = projected.text[index];
+        if (char === "\n" && projected.text[index - 1] === "\r") continue;
+        text.push(/[\r\n]/.test(char) ? " " : char);
+        offsets.push(projected.offsets[index]);
     }
-    const projected = plainRomanRun(source, { ...options, from, to, exclude: layout });
+    ends[projected.text.length] = text.length;
+    while (pending[boundaryIndex]) appendBoundary(pending[boundaryIndex++]);
+    positions[projected.text.length] = text.length;
+    projected.text = text.join("");
+    projected.offsets = offsets;
+    projected.spans = projected.spans.map((span) => ({
+        ...span,
+        from: positions[span.from],
+        to: ends[span.to],
+        contentFrom: positions[span.contentFrom],
+        contentTo: ends[span.contentTo],
+    }));
     const logicalAt = (offset) => {
         let first = 0,
             past = projected.offsets.length;
@@ -61,35 +92,15 @@ export function plainRomanVerse(source, options = {}) {
         }
         return first;
     };
-    /** @type {Array<{kind: "line"|"stanza"|"canto", at: number, sourceOffset: number}>} */
-    const boundaries = [];
-    for (let index = 0; index < lines.length; index++) {
-        const line = lines[index];
-        if (line.kind === "content")
-            boundaries.push({ kind: "line", at: logicalAt(line.to), sourceOffset: line.to });
-        else if (line.kind === "canto")
-            boundaries.push({ kind: "canto", at: logicalAt(line.from), sourceOffset: line.from });
-        else if (lines[index - 1]?.kind === "content") {
-            const following = lines.slice(index + 1).find((next) => next.kind !== "blank");
-            if (following?.kind === "content")
-                boundaries.push({
-                    kind: "stanza",
-                    at: logicalAt(line.from),
-                    sourceOffset: line.from,
-                });
-        }
-    }
-    const errors = [];
-    for (let index = 0; index < projected.text.length; index++) {
-        if (projected.text[index] === "⟦") {
-            const close = projected.text.indexOf("⟧", index + 1);
-            index = close < 0 ? projected.text.length : close;
-        } else if (projected.text[index] === "/")
-            errors.push({
-                offset: projected.offsets[index],
-                message:
-                    "a verse fence uses authored line endings for verse boundaries; write no literal `/` inside it",
-            });
-    }
-    return { ...projected, boundaries, errors };
+    return {
+        ...projected,
+        boundaries: boundaries.map(({ kind, sourceOffset }) => ({
+            kind,
+            sourceOffset,
+            at: logicalAt(sourceOffset),
+        })),
+        errors: model.errors
+            .map(({ offset, message }) => ({ offset: base + offset, message }))
+            .filter((error) => error.offset >= from && error.offset < to),
+    };
 }

package/engine/verse-metre.mjs

@@ -60,7 +60,7 @@ import { WORD } from "./word-pattern.mjs";
 
 import MarkdownIt from "markdown-it";
 import { spanMarkdownPlugin } from "./content-spans.mjs";
-import { STANZA_BREAK, verseLine } from "./content-verse.mjs";
+import { parseVerse } from "./content-verse.mjs";
 import { inlineText } from "./name-markup.mjs";
 
 const verseParser = new MarkdownIt().use(spanMarkdownPlugin);
@@ -311,13 +311,6 @@ export function metreFindings(blocks, lines, ctx) {
             column: ctx.attributeColumns(opening, key)[part],
         });
         const error = (position, message) => errors.push({ ...position, message });
-        if (Number(block.attributes.cols ?? 1) > 1) {
-            error(
-                at("scan", "key"),
-                "`scan=` counts the beats of one language's lines; a verse with cols>1 groups independent physical lines",
-            );
-            continue;
-        }
         const metre = metres.get(name);
         if (!metre) {
             const near = nearest(name, [...metres.keys()]);
@@ -346,40 +339,40 @@ export function metreFindings(blocks, lines, ctx) {
             );
             continue;
         }
-        for (let line = block.start + 1; line < block.end; line++) {
-            const text = lines[line];
-            if (!text.trim() || STANZA_BREAK.test(text.trim())) continue;
-            const reading = verseLine(text);
-            const tokens = verseParser.parseInline(reading.text, {})[0]?.children ?? [];
-            const tag = (name) => (ctx.languages?.[name]?.tag ?? name).toLowerCase();
-            const foreign = tokens.find(
-                (token) =>
-                    token.type === "span_open" &&
-                    token.attrGet("lang") &&
-                    tag(token.attrGet("lang")) !== tag(lang),
-            );
-            if (foreign) {
-                error(
-                    {
-                        line: line + 1,
-                        column:
-                            reading.textColumn +
-                            foreign.meta.start +
-                            (reading.markerStart <= reading.textColumn - 1 + foreign.meta.start ?
-                                reading.markerLength
-                            :   0),
-                    },
-                    "`scan=` counts one language's beats; this verse line contains another language",
+        const body = lines.slice(block.start + 1, block.end).join("\n");
+        const model = block.model ?? parseVerse(body);
+        const sourcePosition = (offset) => {
+            const preceding = body.slice(0, offset);
+            return {
+                line: block.start + 2 + preceding.split("\n").length - 1,
+                column: preceding.length - preceding.lastIndexOf("\n"),
+            };
+        };
+        for (const group of model.groups) {
+            if (group.cantoBreak) continue;
+            for (const reading of group.lines) {
+                const tokens = verseParser.parseInline(reading.text, {})[0]?.children ?? [];
+                const tag = (name) => (ctx.languages?.[name]?.tag ?? name).toLowerCase();
+                const foreign = tokens.find(
+                    (token) =>
+                        token.type === "span_open" &&
+                        token.attrGet("lang") &&
+                        tag(token.attrGet("lang")) !== tag(lang),
                 );
-                continue;
+                if (foreign) {
+                    error(
+                        sourcePosition(reading.offsets[foreign.meta.start] ?? reading.from),
+                        "`scan=` counts one language's beats; this verse line contains another language",
+                    );
+                    continue;
+                }
+                const beats = lineBeats(inlineText(tokens), book);
+                if (metre.beats >= beats.min && metre.beats <= beats.max) continue;
+                warnings.push({
+                    ...sourcePosition(reading.from),
+                    message: metreMessage(beats, metre),
+                });
             }
-            const beats = lineBeats(inlineText(tokens), book);
-            if (metre.beats >= beats.min && metre.beats <= beats.max) continue;
-            warnings.push({
-                line: line + 1,
-                column: /^\s*/.exec(text)[0].length + 1,
-                message: metreMessage(beats, metre),
-            });
         }
     }
     return { errors, warnings };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.2.1",
+    "version": "25.3.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",