@heroiclands/package-build 25.5.3 → 25.5.5

package/engine/verse-metre.mjs

@@ -62,8 +62,48 @@ import MarkdownIt from "markdown-it";
 import { spanMarkdownPlugin } from "./content-spans.mjs";
 import { parseVerse } from "./content-verse.mjs";
 import { inlineText } from "./name-markup.mjs";
+import { WIKILINK, authoredLabel, parseWikilink } from "./wikilink-syntax.mjs";
 
 const verseParser = new MarkdownIt().use(spanMarkdownPlugin);
+const wikilinkAt = new RegExp(WIKILINK.source, "y");
+
+// Parse link labels in place so neighbouring spans keep their source offsets.
+verseParser.inline.ruler.before("link", "metre_wikilink", (state, silent) => {
+    const start = state.pos;
+    wikilinkAt.lastIndex = start;
+    const match = wikilinkAt.exec(state.src);
+    if (!match || start + match[0].length > state.posMax) return false;
+    const finish = start + match[0].length;
+    if (silent) {
+        state.pos = finish;
+        return true;
+    }
+    const parsed = parseWikilink(match[1], match[0]);
+    const label = authoredLabel(parsed) ?? state.env.referenceName?.(parsed.target);
+    const token = state.push("span_open", "span", 1);
+    token.meta = {
+        span: true,
+        start,
+        end: finish,
+        unresolvedReference: !parsed.labelled || label === undefined || label === "",
+    };
+    if (parsed.attributes?.classes.length)
+        token.attrSet("class", parsed.attributes.classes.join(" "));
+    for (const [key, value] of Object.entries(parsed.attributes?.values ?? {}))
+        token.attrSet(key, value);
+    const nested = [];
+    state.md.inline.parse(label ?? "", state.md, state.env, nested);
+    const labelStart = start + match[0].indexOf("|") + 1;
+    for (const child of nested)
+        if (child.meta?.span) {
+            child.meta.start += labelStart;
+            child.meta.end += labelStart;
+        }
+    state.tokens.push(...nested);
+    state.push("span_close", "span", -1);
+    state.pos = finish;
+    return true;
+});
 
 export { METRE_KINDS, METRE_NAME, checkMetresField } from "./metre-declaration.mjs";
 
@@ -240,11 +280,12 @@ function wordBeats(word, book) {
     const folded = foldWord(word);
     const count = nucleiOf(folded, book.pairs).length;
     if (count === 0) return { min: 0, max: 0 };
+    const bases = book.classes.get(folded);
     if (count > 1) {
+        const functionWord = bases && [...bases].every((base) => !BEAT_BASES.includes(base));
         const first = stressIndex(folded, book.rule, book.pairs) === 0;
-        return { min: 1, max: count >= 4 && !first ? 2 : 1 };
+        return { min: functionWord ? 0 : 1, max: count >= 4 && !first ? 2 : 1 };
     }
-    const bases = book.classes.get(folded);
     if (!bases) return { min: 1, max: 1 };
     const carrying = [...bases].filter((base) => BEAT_BASES.includes(base)).length;
     if (carrying === bases.size) return { min: 1, max: 1 };
@@ -292,7 +333,7 @@ export function metreMessage({ min, max }, metre) {
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
  *   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 -
+ * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, referenceName?: (target: string) => string|undefined, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
  *   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
@@ -358,9 +399,12 @@ export function metreFindings(blocks, lines, ctx) {
                         ({ offset }) =>
                             !model.layout.some(([from, to]) => offset >= from && offset < to),
                     );
+                const inlineContext = { referenceName: ctx.referenceName };
                 const parsed =
-                    verseParser.parseInline(units.map((unit) => unit.text).join(""), {})[0]
-                        ?.children ?? [];
+                    verseParser.parseInline(
+                        units.map((unit) => unit.text).join(""),
+                        inlineContext,
+                    )[0]?.children ?? [];
                 let presentationDepth = 0;
                 const tokens = parsed.filter((token) => {
                     if (presentationDepth) {
@@ -395,6 +439,7 @@ export function metreFindings(blocks, lines, ctx) {
                     );
                     continue;
                 }
+                if (tokens.some((token) => token.meta?.unresolvedReference)) continue;
                 const beats = lineBeats(text, book);
                 if (metre.beats >= beats.min && metre.beats <= beats.max) continue;
                 warnings.push({

package/engine/verse-regions.mjs

@@ -26,6 +26,8 @@ import { parseExtensionAttributes } from "./extension-attributes.mjs";
  * @property {number} bodyStart - First body offset.
  * @property {number} bodyEnd - Offset past body text, excluding its final newline.
  * @property {string} body - Authored body bytes.
+ * @property {string} logicalBody - Body without Markdown container prefixes.
+ * @property {number[]} bodyOffsets - Logical UTF-16 offsets mapped to authored body offsets, including the end.
  * @property {Record<string,string>} attributes - Authored values.
  * @property {string} id - Anchor or empty string.
  * @property {string[]} classes - Authored classes including verse.
@@ -95,6 +97,18 @@ export function verseDivPlugin(md) {
                 if (original[bodyEnd - 1] === "\n") bodyEnd--;
                 if (original[bodyEnd - 1] === "\r") bodyEnd--;
             }
+            const bodyOffsets = [];
+            let logicalBody = "";
+            for (let number = first + 1; number < (closed ? close : past); number++) {
+                const lineEnd = Math.min(starts[number] + rawLines[number].length, bodyEnd);
+                const contentStart = Math.min(contentStarts[number - first], lineEnd);
+                const pastLine = Math.min(starts[number + 1] ?? bodyEnd, bodyEnd);
+                for (let offset = contentStart; offset < pastLine; offset++) {
+                    logicalBody += original[offset];
+                    bodyOffsets.push(offset - bodyStart);
+                }
+            }
+            bodyOffsets.push(bodyEnd - bodyStart);
             const region = {
                 start: first,
                 end: closed ? close : past - 1,
@@ -104,6 +118,8 @@ export function verseDivPlugin(md) {
                 bodyStart,
                 bodyEnd,
                 body: original.slice(bodyStart, bodyEnd),
+                logicalBody,
+                bodyOffsets,
                 attributes: parsed.values,
                 id: parsed.id,
                 classes: parsed.classes,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.5.3",
+    "version": "25.5.5",
     "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",
@@ -157,7 +157,7 @@
         "eslint-plugin-yml": "^3.8.1",
         "fflate": "^0.8.3",
         "flesch": "^2.0.1",
-        "glob": "^13.0.6",
+        "glob": "^14.0.0",
         "handlebars": "^4.7.10",
         "highlight.js": "^11.12.0",
         "ignore": "^7.0.12",
@@ -168,7 +168,7 @@
         "markdown-it": "^15.0.0",
         "markdown-it-deflist": "^4.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "minimatch": "^10.2.6",
+        "minimatch": "^11.0.0",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
         "remark-frontmatter": "^5.0.0",

package/types/e2e.d.mts

@@ -494,7 +494,7 @@ export const E2E_SCENE_ID: "heroiclandsScene";
 /** How the suite may be run. */
 export const E2E_MODES: readonly string[];
 /** The Chrome for Testing build shared by local and CI Cypress runs. */
-export const CHROME_BUILD_ID: "158.0.8122.0";
+export const CHROME_BUILD_ID: "159.0.8136.0";
 /**
  * The disposable world's identity and credentials.
  */

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

@@ -5,6 +5,8 @@
  *   resolved configuration.
  * @param {Iterable<Record<string, any>>} [records] - The content index's
  *   records, whose language notes supply lexical writings and script choices.
+ * @param {{referenceName?: (target: string) => string|undefined}} [options] -
+ *   The rendering or validation index's own target-name lookup.
  * @returns {RunContext} Its languages, the faces installed where it sits, and
  *   the encodings. A fonts package that cannot be read gives no faces; a run naming
  *   one is reported.
@@ -16,7 +18,9 @@ export function runContext(config: {
     paths?: {
         content?: string;
     };
-} | undefined, records?: Iterable<Record<string, any>>): RunContext;
+} | undefined, records?: Iterable<Record<string, any>>, { referenceName: indexedName }?: {
+    referenceName?: (target: string) => string | undefined;
+}): RunContext;
 /**
  * Find the spans, divs and verse divs marked with `lang=`, `font=` or
  * `enc=`, and every fault in their markup and their text.
@@ -326,6 +330,10 @@ export type RunContext = {
      * {@link module :engine/verse-metre.metreBooksFromRecords}.
      */
     metreBooks?: ReadonlyMap<string, import("./verse-metre.mjs").MetreBook> | undefined;
+    /**
+     * - An indexed wikilink target's visible name.
+     */
+    referenceName?: ((target: string) => string | undefined) | undefined;
     /**
      * -
      * Exact Roman source inventories by configured alias and BCP 47 tag.

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

@@ -1,7 +1,7 @@
 /**
  * Capture one source tree for index, lint, links and compilation.
  * No source or parser state is persisted or reused by another invocation.
- * Prepared SQL databases close within their existing preparation functions.
+ * Session-owned SQL resources close after both audiences settle, or on dispose.
  * @param {object} [options]
  * @param {import("../content-config.mjs").ContentBuildConfig} [options.config] - Exact resolved configuration.
  * @param {string} [options.contentBase] - Content root, defaulting to configuration.

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

@@ -37,12 +37,13 @@ export function scanVerse(source: string, { checkWorks }?: {
  * 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.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>, sourceOffsets?: number[]}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels; sourceOffsets maps projected body positions to authored offsets, including the end.
  * @returns {VerseModel} The shared structure with offsets relative to the body.
  */
-export function parseVerse(body: string, { inline, footnotes }?: {
+export function parseVerse(body: string, { inline, footnotes, sourceOffsets }?: {
     inline?: boolean;
     footnotes?: ReadonlySet<string>;
+    sourceOffsets?: number[];
 }): VerseModel;
 /**
  * Validate a quoted verse span using its original source coordinates.
@@ -271,6 +272,14 @@ export type VerseBlock = {
      * - Authored verse body.
      */
     body: string;
+    /**
+     * - Body without Markdown container prefixes.
+     */
+    logicalBody: string;
+    /**
+     * - Logical UTF-16 offsets mapped to authored body offsets, including the end.
+     */
+    bodyOffsets: number[];
     /**
      * - Logical structure relative to the body.
      */

package/types/engine/core-report.d.mts

@@ -4,7 +4,7 @@
  * @param {Iterable<Record<string, any>>} records - Index records.
  * @param {{language?: string}} [options] - A language to report alone, by its
  *   name, shortcode or reference slug whether or not it states `data.core`.
- * @returns {{concepts: number, languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
+ * @returns {{concepts: number, notCovered: string[], languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
  *   The report, or the problem when there is no concept list or the language
  *   asked for is none.
  */
@@ -12,6 +12,7 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
     language?: string;
 }): {
     concepts: number;
+    notCovered: string[];
     languages: Array<{
         name: string;
         language: string;
@@ -36,10 +37,13 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
  * A core report as text: one block per language, its missing concepts under
  * their groups with counts, each concept's id and gloss tab-separated.
  *
- * @param {{concepts: number, languages: Array<object>}} report - A report from {@link coreReport}.
+ * The default report ends with the names of languages it does not measure.
+ *
+ * @param {{concepts: number, notCovered: string[], languages: Array<object>}} report - A report from {@link coreReport}.
  * @returns {string} The text, ending in a newline.
  */
 export function coreReportText(report: {
     concepts: number;
+    notCovered: string[];
     languages: Array<object>;
 }): string;

package/types/engine/language-names.d.mts

@@ -1,5 +1,5 @@
 /**
- * The genders every `data.names.given` states a list for.
+ * The genders a mapped `data.names.given` states a list for.
  *
  * A function rather than a `const`: `note-vocabulary.mjs` reads it while the
  * module graph is still evaluating.
@@ -47,7 +47,7 @@ export function namesProblems(names: unknown, lookVocabulary: Readonly<Record<st
  * keys cannot: a pattern that does not parse, a placeholder naming no list, a
  * list no pattern names, a list name a placeholder cannot spell, an empty list
  * of patterns or of names, an empty name, a pattern or given list keyed by no
- * gender, and a missing `female` or `male` list. Each is located at the pattern, list, entry or key at fault.
+ * gender, and a missing `female` or `male` list in a gender map. Each is located at the pattern, list, entry or key at fault.
  *
  * @param {object} note - The note: `file`, `raw` and parsed `fm`.
  * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
@@ -70,8 +70,8 @@ export function namesFindings(note: object, lookVocabulary: Readonly<Record<stri
     value: string;
 }[]>>): object[];
 /**
- * The given names a gender draws from: its own list, or every given list
- * together where it has none.
+ * The given names a gender draws from: the shared list, its own list, or
+ * every given list together where it has none.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.
@@ -79,8 +79,20 @@ export function namesFindings(note: object, lookVocabulary: Readonly<Record<stri
  */
 export function givenNames(names: object, gender: string): string[];
 /**
- * A name drawn from a language's lists: one of the gender's patterns, where it
- * has more than one, then each placeholder an even draw from its list.
+ * A name's selected literal and placeholder parts. One of the gender's
+ * patterns is selected first, then each placeholder is an even draw from its
+ * source list.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @param {() => number} next - A stream of numbers in `[0, 1)`.
+ * @returns {(PatternPart & {text: string})[]} The selected parts in pattern order.
+ */
+export function drawNameParts(names: object, gender: string, next: () => number): (PatternPart & {
+    text: string;
+})[];
+/**
+ * A name drawn from a language's lists.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.

package/types/engine/npc-generate.d.mts

@@ -57,6 +57,8 @@ export function appearanceParagraph({ name, age, gender, height, frame, appearan
  *   by `namesProblems`.
  * @param {string} [context.language] - The language's Address, for an error
  *   about a name that does not fit.
+ * @param {string} [context.languageCode] - The language code under which a
+ *   generated name's distinct source form is retained.
  * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
  *   different person from the same spec.
  * @param {unknown} [context.currentDate] - The setting's neutral current date, defaulting to "720.1".
@@ -74,6 +76,7 @@ export function generateNpc(spec: object, context: {
     profile: object;
     names: object;
     language?: string | undefined;
+    languageCode?: string | undefined;
     seed?: string | undefined;
     currentDate?: unknown;
     dateContext?: object | undefined;

package/types/engine/page-breaks.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Read page-break markers before any surface rewrites their source.
+ * Code, HTML examples and entire verse divs remain literal. Parser ranges
+ * retain list and quote membership, including lazy continuation lines.
+ * @param {string} source - Authored Markdown body.
+ * @returns {{breaks: Array<{line: number, column: number}>, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanPageBreaks(source: string): {
+    breaks: Array<{
+        line: number;
+        column: number;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Omit valid page breaks on a screen, preserving the surrounding block boundaries.
+ * @param {string} source - Markdown body.
+ * @returns {string} Markdown without valid page-break lines.
+ */
+export function omitPageBreaks(source: string): string;
+/**
+ * Produce the book's page-break token, leaving ordinary thematic breaks alone.
+ * @param {import("markdown-it")} md - The book parser.
+ * @returns {void}
+ */
+export function pageBreakPlugin(md: typeof import("markdown-it")): void;

package/types/engine/pdf-render.d.mts

@@ -98,6 +98,7 @@ export function stripHtmlComments(markdown: string): string;
  * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
  *   table expansion, mapping each line handed in back to the line an author
  *   wrote.
+ * @param {boolean} [opts.pageBreaks] - Internal: whether this slice remains at the note top level.
  * @param {boolean} [opts.prepared] - Whether this body has been through the
  *   passes that resolve a wikilink, an embed and an inline expression. A note's
  *   has; a front-matter file's and a prose file's have not, and markup of theirs
@@ -138,6 +139,7 @@ export function markdownToTypst(markdown: string, opts?: {
         line: number;
         generated: boolean;
     }[] | undefined;
+    pageBreaks?: boolean | undefined;
     prepared?: boolean | undefined;
     url?: string | undefined;
     elsewhere?: {

package/types/engine/site-build.d.mts

@@ -306,6 +306,7 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
@@ -322,8 +323,9 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  *   against the rest of the build, or returns `null` when its address, name
  *   or type changed and the whole site must be built again.
  */
-export function buildSite({ config, sqlTables }?: {
+export function buildSite({ config, sqlTables, progress }?: {
     config?: object | undefined;
+    progress?: ((message: string) => void) | undefined;
     sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;

package/types/engine/site-render.d.mts

@@ -50,19 +50,21 @@ export function writeThemeFiles(out: string, staticDir?: string): string[];
  * @param {string} [options.staticDir] - The theme's own files, copied first.
  * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
  *   draw again into a site already written. Nothing else is touched.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {{files: string[], pages: string[], reachable: string[],
  *   findings: object[]}} Every file written, the address of every page, the
  *   address of each page reachable from the homepage, and the layouts' findings.
  * @throws {Error} When a page's address is outside the site, or a site served
  *   under a path asks for a sitemap index.
  */
-export function writeSite({ site, pages, out, report, staticDir, only }: {
+export function writeSite({ site, pages, out, report, staticDir, only, progress, }: {
     site: object;
     pages: readonly object[];
     out: string;
     report?: ((finding: import("./site-theme.mjs").Finding) => void) | undefined;
     staticDir?: string | undefined;
     only?: ReadonlySet<string> | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): {
     files: string[];
     pages: string[];
@@ -147,6 +149,7 @@ export function deliverSiteFonts(config: object, out: string): {
  * @param {string} options.out - The directory the site is written to, which
  *   is the package's own directory under the deployed root.
  * @param {number} [options.year] - The year the footer states.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{built: object, written: object|null, fonts: object|null,
  *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
  *   What the build found, and, when it found nothing that stops it, what was
@@ -154,10 +157,11 @@ export function deliverSiteFonts(config: object, out: string): {
  *   becomes its page. `written` is `null` when a gate fired.
  * @throws {Error} When the site's settings or its cached menu cannot be read.
  */
-export function buildPackageSite({ config, out, year }: {
+export function buildPackageSite({ config, out, year, progress }: {
     config: object;
     out: string;
     year?: number | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): Promise<{
     built: object;
     written: object | null;

package/types/engine/site-root.d.mts

@@ -73,6 +73,7 @@ export function indexSite(where: {
  *   `site.search` in the configuration. Default `true`.
  * @param {SiteIndexer} [options.indexer] - What builds it. Default
  *   {@link indexSite}.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{files: string[], search: {dir: string, pages: number}|null}>}
  *   The files written, and the index — where it is and how many pages it
  *   holds — or `null` when none was built.
@@ -81,12 +82,13 @@ export function indexSite(where: {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export function writeSiteRoot({ pkg, base, out, search, indexer }: {
+export function writeSiteRoot({ pkg, base, out, search, indexer, progress, }: {
     pkg: string;
     base?: string | undefined;
     out: string;
     search?: boolean | undefined;
     indexer?: SiteIndexer | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): Promise<{
     files: string[];
     search: {

package/types/engine/site-serve-http.d.mts

@@ -0,0 +1 @@
+export {};

package/types/engine/site-serve.d.mts

@@ -9,16 +9,19 @@
  *   directory above `out` by default; `out` itself for a site served at `/`.
  * @param {string} [options.host] - The address to listen on.
  * @param {number} [options.port] - The port; `0` takes any free one.
- * @param {boolean} [options.search] - Build the search index after the first
+ * @param {boolean} [options.search] - Build the search index with each whole
  *   build, where the site has one.
  * @param {number} [options.year] - The year the footer states.
- * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
- *   Told of each build: `built` for a whole build, `page` for one note's page,
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown, message?: string, fatal?: boolean}) => void} [options.report] -
+ *   Told of progress (`message`) and each build: `built` for a whole build, `page` for one note's page,
  *   `theme` for the theme, `failed` with what the build found, `error` with
  *   what it threw.
- * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
- *   The address of the site's home page, how to stop serving, and a promise
- *   for the moment every change seen so far has been written.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>, done: Promise<void>}>}
+ *   Resolves as soon as HTTP listens, before the first build. The address of
+ *   the site's home page, how to stop serving, and a promise for the initial
+ *   build and every change seen so far to finish. Failed builds are reported
+ *   through `report` and leave the last successful site in service. `done`
+ *   resolves on close and rejects if HTTP stops unexpectedly.
  */
 export function serveSite({ config, out, root, host, port, search, year, report, }: {
     config: object;
@@ -34,11 +37,14 @@ export function serveSite({ config, out, root, host, port, search, year, report,
         files?: string[];
         findings?: object[];
         error?: unknown;
+        message?: string;
+        fatal?: boolean;
     }) => void) | undefined;
 }): Promise<{
     url: string;
     close: () => Promise<void>;
     settled: () => Promise<void>;
+    done: Promise<void>;
 }>;
 /** The address a served page listens on for the server's reloads. */
 export const RELOAD_PATH: "/__package-build/reload";

package/types/engine/sql-tables.d.mts

@@ -65,12 +65,13 @@ export function findSqlBlocks(markdown: string): Array<{
  * @param {object} [opts.addressContext] - Address resolution context.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes from
  *   local and dependency relations.
+ * @param {boolean} [opts.testMemoryLimit] - Test-only fixed 256 MB budget;
+ *   production always uses 2 GB. This is not authored configuration.
  * @param {string} [opts.contentBase] - The directory the records' paths are
  *   relative to, so a refused key is reported at its file and line.
- * @returns {Promise<{query: (sql: string) => Promise<object[]>,
- *   close: () => Promise<void>}>} The open database.
+ * @returns {ReturnType<typeof openDatabase>} The open database.
  */
-export function openNotesDatabase(records: object[], { dir, dependencies, addressContext, audience, contentBase }?: {
+export function openNotesDatabase(records: object[], opts?: {
     dir?: string | undefined;
     dependencies?: {
         id: string;
@@ -78,11 +79,21 @@ export function openNotesDatabase(records: object[], { dir, dependencies, addres
     }[] | undefined;
     addressContext?: object | undefined;
     audience?: "all" | "public" | undefined;
+    testMemoryLimit?: boolean | undefined;
     contentBase?: string | undefined;
-}): Promise<{
-    query: (sql: string) => Promise<object[]>;
-    close: () => Promise<void>;
-}>;
+}): ReturnType<typeof openDatabase>;
+/**
+ * Own the SQL resources of one content session. Raw local and dependency JSON
+ * tables are loaded once; each audience derives its relations unchanged in a
+ * separate catalog/connection. Openings are serialized, queries are not.
+ * @param {object[]} records - The session's captured index.
+ * @param {Omit<NonNullable<Parameters<typeof openNotesDatabase>[1]>, "audience"|"dir">} [options] - Shared load options.
+ * @returns {{database: (audience: "all"|"public") => Promise<Awaited<ReturnType<typeof openNotesDatabase>>>, dispose: () => void}}
+ */
+export function createNotesDatabaseScope(records: object[], options?: Omit<NonNullable<Parameters<typeof openNotesDatabase>[1]>, "audience" | "dir">): {
+    database: (audience: "all" | "public") => Promise<Awaited<ReturnType<typeof openNotesDatabase>>>;
+    dispose: () => void;
+};
 /**
  * Run one authored query and shape its result for the renderer.
  *
@@ -301,7 +312,8 @@ export function cachedDependencies(config?: object): Promise<Array<{
  * @param {object} [opts.database] - An open notes database over `records`, from
  *   {@link openNotesDatabase} with this call's `audience` and the declared
  *   dependencies from {@link cachedDependencies}. It is queried and left open;
- *   absent, one is opened and closed here.
+ *   absent, one is opened and closed here. A lazy async factory is also
+ *   accepted and called only when this preparation needs SQL.
  * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes the
  *   generated sections take in, where the caller holds them already; absent,
@@ -376,3 +388,20 @@ export const SQL_FENCE_ATTRIBUTES: Readonly<Record<string, Readonly<{
     default: string;
     summary: string;
 }>>>;
+/**
+ * Open one audience connection, optionally in a session-owned instance.
+ * @param {object[]} records - Content-index records.
+ * @param {NonNullable<Parameters<typeof openNotesDatabase>[1]>} [opts] - Load options.
+ * @param {object} [shared] - Session-owned SQL resources.
+ */
+declare function openDatabase(records: object[], { dir, dependencies, addressContext, audience, contentBase, testMemoryLimit, }?: NonNullable<Parameters<typeof openNotesDatabase>[1]>, shared?: object): Promise<{
+    addressContext: object;
+    stubsExcluded: (sql: string, rows: number) => Promise<number>;
+    languageNotes: Map<string, string>;
+    query(sql: any): Promise<{
+        columnNames: any;
+        rows: any;
+    }>;
+    close(): Promise<void>;
+}>;
+export {};

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

@@ -73,7 +73,7 @@ export function metreMessage({ min, max }: {
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
  *   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 -
+ * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, referenceName?: (target: string) => string|undefined, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
  *   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
@@ -92,6 +92,7 @@ export function metreFindings(blocks: ReadonlyArray<{
     metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>;
     metreBooks?: ReadonlyMap<string, MetreBook>;
     lexicons?: ReadonlyMap<string, unknown>;
+    referenceName?: (target: string) => string | undefined;
     attributeColumns: (line: string, key: string) => {
         key: number;
         value: number;

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

@@ -51,6 +51,14 @@ export type VerseRegion = {
      * - Authored body bytes.
      */
     body: string;
+    /**
+     * - Body without Markdown container prefixes.
+     */
+    logicalBody: string;
+    /**
+     * - Logical UTF-16 offsets mapped to authored body offsets, including the end.
+     */
+    bodyOffsets: number[];
     /**
      * - Authored values.
      */