@heroiclands/package-build 25.2.1 → 25.4.0

package/types/engine/content-verse.d.mts

@@ -1,5 +1,3 @@
-/** The authored verse lines, excluding blank lines and stanza separators. */
-export function verseLines(body: any): string[];
 /**
  * Read one verse line. Marker offsets are zero-based in the authored line;
  * textColumn is the one-based column of its first non-space character.
@@ -12,103 +10,286 @@ export function verseLine(line: any): {
     markerLength: number;
     textColumn: number;
 };
+/** A verse is inline Markdown even when it starts with block syntax. */
+export function inlineVerse(text: any): string;
+/**
+ * Whether text runs right to left: its first letter is in a right-to-left
+ * block. A face's right-to-left code points sit in U+1E800–U+1EFFF.
+ *
+ * @param {string} text - Text, after any map.
+ * @returns {boolean} Whether it starts right to left.
+ */
+export function rightToLeft(text: string): boolean;
+/** Read verse divs; start/end are inclusive zero-based source lines.
+ * @param {string} source - Authored Markdown.
+ * @param {object} [options] - Whole-page validation choices.
+ * @param {boolean} [options.checkWorks] - Whether to validate page-local versions.
+ * @returns {{blocks: VerseBlock[], errors: VerseDiagnostic[]}} Located divs and findings.
+ */
+export function scanVerse(source: string, { checkWorks }?: {
+    checkWorks?: boolean | undefined;
+}): {
+    blocks: VerseBlock[];
+    errors: VerseDiagnostic[];
+};
+/**
+ * Parse logical verse lines, stanzas and cantos without losing authored offsets.
+ * Offsets are UTF-16 positions relative to body. Delimiters and indentation are
+ * layout ranges; source newlines inside a logical line contribute one space.
+ * @param {string} body - Authored verse body.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels.
+ * @returns {VerseModel} The shared structure with offsets relative to the body.
+ */
+export function parseVerse(body: string, { inline, footnotes }?: {
+    inline?: boolean;
+    footnotes?: ReadonlySet<string>;
+}): VerseModel;
 /**
- * Blank lines divide verse groups. A standalone `***` is its own group and
- * separates stanzas. Each text line carries its period-based indentation.
+ * Validate a quoted verse span using its original source coordinates.
+ * @param {{start: number, text: string, attrs: Array<[string,string]>}} span - Authored span.
+ * @param {string} source - Complete Markdown source.
+ * @returns {VerseDiagnostic[]} Located inline-only findings.
  */
+export function inlineVerseFindings(span: {
+    start: number;
+    text: string;
+    attrs: Array<[string, string]>;
+}, source: string): VerseDiagnostic[];
+/** Logical line text for consumers that do not need source locations. */
+export function verseLines(body: any): string[];
+/** Paragraph groups with separate canto gaps. */
 export function verseStanzas(body: any): {
     text: string;
     level: number;
 }[][];
-/** A verse is inline Markdown even when it starts with block syntax. */
-export function inlineVerse(text: any): string;
 /**
- * Keep blank-line verse groups as paragraphs and each text line a hard break.
- * A standalone `***` emits a separate stanza gap.
- * The surrounding renderer still sees the entire note, so links and footnote
- * definitions remain in scope. The span carries the indent for each line.
+ * Compare the stanza counts of each version of a page-local work.
+ * @param {VerseBlock[]} blocks - Divs belonging to one page.
+ * @returns {VerseDiagnostic[]} Findings at affected opening divs.
  */
-export function verseMarkdown(body: any, step?: number): string;
+export function workShapeFindings(blocks: VerseBlock[]): VerseDiagnostic[];
 /**
- * The number a line shows: `undefined` when the verse is not numbered, `""`
- * when this line is not one of every `step`th.
- *
- * @param {number} line - The line's number, 1-based across the verse.
- * @param {number} step - The verse's `numstep`.
- * @returns {string|undefined} The number shown.
+ * Render a shared verse structure while preserving surrounding inline Markdown.
+ * @param {string} body - Authored verse body.
+ * @param {object} [options] - Shared structure and display choices.
+ * @param {boolean} [options.labelled] - Whether each stanza carries its label.
+ * @param {VerseModel} [options.model] - Parsed structure; defaults to parsing the body.
+ * @param {VersePresentation} [options.presentation] - Native-cell font and language.
+ * @param {boolean} [options.inline] - Whether wrappers must remain inline-safe.
+ * @returns {string} Markdown with verse layout wrappers.
  */
-export function lineNumber(line: number, step: number): string | undefined;
-/** Read verse code fences; start/end are inclusive zero-based source lines.
- * @param {string} source - Authored Markdown.
+export function verseMarkdown(body: string, { labelled, model, presentation, inline }?: {
+    labelled?: boolean | undefined;
+    model?: VerseModel | undefined;
+    presentation?: VersePresentation | undefined;
+    inline?: boolean | undefined;
+}): string;
+/**
+ * Replace verse divs with wrappers whose bodies remain inline Markdown.
+ * @param {string} source - Markdown containing verse divs.
+ * @param {object} [options] - Encoded display models.
+ * @param {Map<string, VersePresentation>} [options.verses] - Presentations keyed by rewritten body.
  */
-export function scanVerse(source: string): {
-    blocks: {
-        end: number;
-        body: string;
-        start: number;
-        fence: string;
-        name: string;
-        attributes: {};
-        id: string;
-        classes: never[];
-        indent: string;
-    }[];
-    errors: any[];
+export function renderVerse(source: string, { verses }?: {
+    verses?: Map<string, VersePresentation> | undefined;
+}): {
+    markdown: string;
+    errors: VerseDiagnostic[];
 };
-/** The number of verse columns; an omitted or invalid count uses the ordinary layout. */
-export function verseColumnCount(block: any): number;
-/** Whether a verse uses the numbered multi-column protocol. */
-export function hasColumns(block: any): boolean;
 /**
- * Blank-separated multi-column rows with ordered physical parts. Text retains
- * its authored inline markup and spacing after the numeric prefix. All source
- * offsets are measured before prefixes or indentation periods are removed.
- *
- * @param {object} block - A verse from scanVerse.
- * @param {string[]} lines - The complete source, by line.
- * @returns {Array<{stanzaBreak: true, line: number}|{stanzaBreak?: false, parts: Array<{column: number, line: number, sourceColumn: number, textColumn: number, text: string, indent: number, markerStart: number, markerLength: number, prefixLength: number}>}>}
+ * Render quoted verse with inline-safe wrappers and shared logical structure.
+ * @param {string} source - Markdown after block verse rendering.
+ * @returns {string} Markdown retaining surrounding prose.
  */
-export function verseGroups(block: object, lines: string[]): Array<{
-    stanzaBreak: true;
-    line: number;
-} | {
-    stanzaBreak?: false;
-    parts: Array<{
-        column: number;
-        line: number;
-        sourceColumn: number;
-        textColumn: number;
-        text: string;
-        indent: number;
-        markerStart: number;
-        markerLength: number;
-        prefixLength: number;
-    }>;
-}>;
+export function renderVerseQuotes(source: string): string;
+/** The authored attributes of a verse div. */
+export const VERSE_KEYS: readonly string[];
+/** A canto separator, including the escaped form produced by a native run. */
+export const STANZA_BREAK: RegExp;
+export function stanzaSeparator(group: any): boolean;
 /**
- * Whether text runs right to left: its first letter is in a right-to-left
- * block. A face's right-to-left code points sit in U+1E800–U+1EFFF.
- *
- * @param {string} text - Text, after any map.
- * @returns {boolean} Whether it starts right to left.
+ * A logical line with its authored UTF-16 coordinates.
  */
-export function rightToLeft(text: string): boolean;
-/** Replace verse fences with HTML wrappers whose body remains inline Markdown.
- * @param {string} source - Authored Markdown.
+export type VerseLine = {
+    /**
+     * - Inline Markdown in this presentation.
+     */
+    text: string;
+    /**
+     * - Leading-period indentation depth.
+     */
+    level: number;
+    /**
+     * - First authored offset, including indentation.
+     */
+    from: number;
+    /**
+     * - Offset at the line ending.
+     */
+    to: number;
+    /**
+     * - Source offset for each UTF-16 text unit.
+     */
+    offsets: number[];
+    /**
+     * - Roman text paired with an encoded line.
+     */
+    romanText?: string | undefined;
+};
+/**
+ * A stanza's logical lines and authored bounds.
  */
-export function renderVerse(source: string): {
-    markdown: string;
-    errors: any[];
+export type VerseStanza = {
+    /**
+     * - Lines in reading order.
+     */
+    lines: VerseLine[];
+    /**
+     * - First authored offset.
+     */
+    from: number;
+    /**
+     * - Offset at the stanza ending.
+     */
+    to: number;
+};
+export type VerseTextGroup = VerseStanza & {
+    canto: number;
+    stanza: number;
+    label: string;
+    cantoBreak?: false;
+};
+export type VerseCantoBreak = {
+    cantoBreak: true;
+    from: number;
+    to: number;
+    text?: string;
+    id?: string;
+    title?: string;
+};
+export type VerseBoundary = {
+    kind: "line" | "stanza" | "canto";
+    sourceOffset: number;
+};
+export type VerseFinding = {
+    offset: number;
+    message: string;
 };
-export function stanzaSeparator(group: any): boolean;
-/** The layout class the build gives a verse whose cols count exceeds one. */
-export const COLUMNS_CLASS: "verse-columns";
 /**
- * The keys a verse fence's attribute block takes. `lang`, `font` and `map`
- * are read by `scanRuns` in content-scripts.mjs; `dir`, and on the site
- * `data-pagefind-ignore`, are written by its rewrite of a fence set in one of
- * the faces, and reach the element as they are written.
+ * Shared authored verse structure and source locations.
  */
-export const VERSE_KEYS: readonly string[];
-/** A line separating stanzas, including escaped output from a native run. */
-export const STANZA_BREAK: RegExp;
+export type VerseModel = {
+    /**
+     * - Cantos in reading order.
+     */
+    cantos: Array<{
+        stanzas: VerseStanza[];
+    }>;
+    /**
+     * - Stanzas and canto breaks.
+     */
+    groups: Array<VerseTextGroup | VerseCantoBreak>;
+    /**
+     * - Explicit authored boundaries.
+     */
+    boundaries: VerseBoundary[];
+    /**
+     * - Source ranges omitted from encoded letters.
+     */
+    layout: Array<[number, number]>;
+    /**
+     * - Findings relative to the verse body.
+     */
+    errors: VerseFinding[];
+    /**
+     * - Defined references without substantive verse text.
+     */
+    notes: VerseLine[];
+};
+/**
+ * An authored verse div with its parsed logical structure.
+ */
+export type VerseBlock = {
+    /**
+     * - Opening div's zero-based source line.
+     */
+    start: number;
+    /**
+     * - Closing div's zero-based source line.
+     */
+    end: number;
+    /**
+     * - Complete div first offset.
+     */
+    from: number;
+    /**
+     * - Offset past complete div.
+     */
+    to: number;
+    /**
+     * - First body offset.
+     */
+    bodyStart: number;
+    /**
+     * - Offset past body text.
+     */
+    bodyEnd: number;
+    /**
+     * - Whether the closing delimiter exists.
+     */
+    closed: boolean;
+    /**
+     * - Attribute syntax findings.
+     */
+    problems: string[];
+    /**
+     * - Region name.
+     */
+    name: "verse";
+    /**
+     * - Authored attribute values.
+     */
+    attributes: Record<string, string>;
+    /**
+     * - Authored anchor, or the empty string.
+     */
+    id: string;
+    /**
+     * - Authored presentation classes.
+     */
+    classes: string[];
+    /**
+     * - Opening div's leading spaces.
+     */
+    indent: string;
+    /**
+     * - Authored verse body.
+     */
+    body: string;
+    /**
+     * - Logical structure relative to the body.
+     */
+    model: VerseModel;
+};
+export type VerseDiagnostic = {
+    line: number;
+    column: number;
+    message: string;
+};
+/**
+ * An encoded verse's shared display model and native-cell presentation.
+ */
+export type VersePresentation = {
+    /**
+     * - Logical structure with paired line text.
+     */
+    model: VerseModel;
+    /**
+     * - Native script and font classes.
+     */
+    classes: string[];
+    /**
+     * - Native language, direction and search attributes.
+     */
+    attributes: Record<string, string>;
+};

package/types/engine/name-markup.d.mts

@@ -26,6 +26,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.
  */
 /**
  * One located span-grammar or refused-attribute finding.
@@ -139,6 +140,10 @@ export type ContentSpan = {
      * - Authored key/value sites by retained attribute name.
      */
     attributePositions: Record<string, SpanAttributePosition>;
+    /**
+     * - Logical model of an inline verse quotation.
+     */
+    verseModel?: import("./content-verse.mjs").VerseModel | undefined;
 };
 /**
  * One located span-grammar or refused-attribute finding.

package/types/engine/roman-verse.d.mts

@@ -1,14 +1,14 @@
 /**
- * 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: string, options?: Parameters<typeof plainRomanRun>[1] & {
-    isCantoLine?: (line: string) => boolean;
+    model?: ReturnType<typeof parseVerse>;
+    modelOffset?: number;
 }): ReturnType<typeof plainRomanRun> & {
     boundaries: Array<{
         kind: "line" | "stanza" | "canto";
@@ -21,3 +21,4 @@ export function plainRomanVerse(source: string, options?: Parameters<typeof plai
     }>;
 };
 import { plainRomanRun } from "./roman-run.mjs";
+import { parseVerse } from "./content-verse.mjs";

package/types/engine/verse-format.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Replace verse markup with opaque placeholders and restore its original bytes.
+ * @param {string} source - Complete Markdown source.
+ * @returns {{markdown: string, restore: (formatted: string) => string}} Protected source and exact restoration.
+ */
+export function protectVerseSource(source: string): {
+    markdown: string;
+    restore: (formatted: string) => string;
+};

package/types/engine/verse-metre.d.mts

@@ -60,7 +60,7 @@ export function lineBeats(text: string, book: MetreBook): {
  * The warning for a line that cannot have its metre's beats.
  *
  * @param {{min: number, max: number}} beats - The line's beats.
- * @param {import("./metre-declaration.mjs").Metre} metre - The fence's metre.
+ * @param {import("./metre-declaration.mjs").Metre} metre - The div's metre.
  * @returns {string} The message.
  */
 export function metreMessage({ min, max }: {
@@ -68,13 +68,13 @@ export function metreMessage({ min, max }: {
     max: number;
 }, metre: import("./metre-declaration.mjs").Metre): string;
 /**
- * Check the verse fences that state `scan=`.
+ * Check the verse divs that state `scan=`.
  *
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
- *   The fences, from {@link module:engine/content-verse.scanVerse}.
+ *   The divs, from {@link module:engine/content-verse.scanVerse}.
  * @param {string[]} lines - The source's lines.
  * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
- *   The metres and books, and how the fence says its columns and where its
+ *   The metres and books, and how the div says its columns and where its
  *   keys sit.
  * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
  *   positions.

package/types/engine/verse-regions.d.mts

@@ -0,0 +1,78 @@
+/**
+ * Install the opaque verse-div block rule. Tokens carry raw source regions.
+ * @param {import("markdown-it")} md - Markdown parser.
+ */
+export function verseDivPlugin(md: typeof import("markdown-it")): void;
+/**
+ * Locate complete raw verse divs while leaving literal examples untouched.
+ * @param {string} source - Authored Markdown.
+ * @returns {VerseRegion[]} Regions in source order, including unclosed divs.
+ */
+export function verseRegions(source: string): VerseRegion[];
+/**
+ * Source ranges belonging to inline syntax rather than visible verse text.
+ * @param {string} source - Inline Markdown.
+ * @returns {Array<[number,number]>} Protected UTF-16 ranges.
+ */
+export function inlineSyntaxRanges(source: string): Array<[number, number]>;
+/**
+ * A raw verse div, opaque to ordinary Markdown block syntax.
+ */
+export type VerseRegion = {
+    /**
+     * - Opening line, zero based.
+     */
+    start: number;
+    /**
+     * - Closing line, zero based and inclusive.
+     */
+    end: number;
+    /**
+     * - First offset of the complete region.
+     */
+    from: number;
+    /**
+     * - Offset past the complete region.
+     */
+    to: number;
+    /**
+     * - First body offset.
+     */
+    bodyStart: number;
+    /**
+     * - Offset past body text, excluding its final newline.
+     */
+    bodyEnd: number;
+    /**
+     * - Authored body bytes.
+     */
+    body: string;
+    /**
+     * - Authored values.
+     */
+    attributes: Record<string, string>;
+    /**
+     * - Anchor or empty string.
+     */
+    id: string;
+    /**
+     * - Authored classes including verse.
+     */
+    classes: string[];
+    /**
+     * - Opening indentation.
+     */
+    indent: string;
+    /**
+     * - Region kind.
+     */
+    name: "verse";
+    /**
+     * - Whether a closing delimiter is present.
+     */
+    closed: boolean;
+    /**
+     * - Attribute syntax findings.
+     */
+    problems: string[];
+};

package/types/engine/wikilink-pattern.d.mts

@@ -0,0 +1,17 @@
+/** The dependency-free lexical wikilink pattern. @module */
+/**
+ * A wikilink, as authored.
+ *
+ * **Newlines are excluded deliberately.** A link is written on one line; an
+ * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
+ * prose in search of a closer. Erring towards "not a link" leaves the author's
+ * text as written, which is the safe direction for a rewriter.
+ *
+ * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
+ * keeps every reader from seeing one as the other. Stated here rather than in
+ * each reader for the reason the rest of this module exists: the checker, the
+ * resolver and the embed reader all match on this pattern, and a copy of the
+ * exclusion in each is a place for it to be forgotten. An embed's
+ * own grammar is {@link module:engine/content-embeds}.
+ */
+export const WIKILINK: RegExp;

package/types/engine/wikilink-syntax.d.mts

@@ -206,47 +206,7 @@ export function secretDestination(destination: object, anchor?: string): boolean
  * @returns {string} Inline spoiler or visible reference.
  */
 export function presentWikilink(reference: string, parsed: object, destination: object): string;
-/**
- * What a `[[…]]` **is**, before anything decides where it points.
- *
- * One authored link is written three ways — a Foundry `@UUID` content link for
- * the packs, a URL for the web, a cross-reference for the book — and those
- * forms are the *only* thing that legitimately differs. The syntax is the
- * author's, and it is the same syntax whichever build is reading it.
- *
- * So the parse lives here, once, and two readers take it: the link checker
- * (`content-links.mjs`) and the resolver (`wikilinks.mjs`). Each receives the
- * parts and decides only what it is for: which document the address names.
- *
- * The one rule about a link's *shape* also lives here — **a link carries a
- * label** ({@link unlabelledLinkMessage}) — because every build states it
- * through one message and the author reads the same words whichever ran
- * first.
- *
- * For the same reason, so does the **vocabulary of link findings**
- * ({@link LINK_FINDING_REASONS}) and the message each one reports through
- * ({@link linkFindingMessage}). Every build reads one authored link; an author
- * meets whichever ran first, and a consumer switching on a `reason` should not
- * be switching on which build produced it.
- *
- * @module
- */
-/**
- * A wikilink, as authored.
- *
- * **Newlines are excluded deliberately.** A link is written on one line; an
- * unclosed `[[` is a typo, and the alternative is letting it swallow arbitrary
- * prose in search of a closer. Erring towards "not a link" leaves the author's
- * text as written, which is the safe direction for a rewriter.
- *
- * **A leading `!` makes it an embed, not a link**, and the lookbehind is what
- * keeps every reader from seeing one as the other. Stated here rather than in
- * each reader for the reason the rest of this module exists: the checker, the
- * resolver and the embed reader all match on this pattern, and a copy of the
- * exclusion in each is a place for it to be forgotten. An embed's
- * own grammar is {@link module:engine/content-embeds}.
- */
-export const WIKILINK: RegExp;
+export { WIKILINK } from "./wikilink-pattern.mjs";
 /**
  * Every way a link can fail, named once for every reader of a link.
  *