@heroiclands/package-build 24.0.4 → 24.1.1

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

@@ -46,10 +46,9 @@ export function scanRuns(source: string, ctx?: RunContext, syntax?: import("./co
  * Rewrite text marked with `lang=`, `font=` and `map=` into the plain span,
  * div and verse grammar the rest of each chain renders, one line for one line.
  *
- * - **A verse in columns is expanded first** into one span per column entry
- *   per verse line, by {@link module:engine/content-verse.expandVerse}, so
- *   each entry is mapped and set as a span with its keys is. That is the one
- *   rewrite that changes the number of lines.
+ * - **Numbered verse prefixes and indentation markers** stay outside run text.
+ *   Each authored run chooses its own language and presentation; physical
+ *   lines and source positions remain unchanged.
  * - **The map, if any, is applied first.** Characters Markdown would read are
  *   then backslash-escaped, so they reach every later pass as characters.
  * - **Emphasis in a face** becomes an `<em>` or a `<strong>` carrying its
@@ -93,6 +92,8 @@ export function renderRuns(source: string, ctx?: RunContext, syntax?: import("./
 };
 /** The keys this module reads, which no construct passes through as written. */
 export const RUN_KEYS: readonly string[];
+/** Explicit opt-in to native-script presentation on this construct. */
+export const NATIVEFONT_CLASS: "nativefont";
 /** The generic families `font=` may name, each with the class that sets it. */
 export const GENERIC_FONTS: Readonly<{
     mono: "font-mono";
@@ -175,6 +176,11 @@ export type RunDetail = {
      * - A span's offset of its closing `]`.
      */
     contentEnd: number | undefined;
+    /**
+     * - A resolved reference's
+     * visible label bounds, by absolute offset; its target stays untouched.
+     */
+    reference: [number, number] | undefined;
     /**
      * -
      * The convention its language's note states.
@@ -270,9 +276,9 @@ export type RunContext = {
 /**
  * One span, div, verse fence or scroll fence carrying `lang=`, `font=` or
  * `map=`. Its `lang`, `font` and `map` are the ones it is set with: its own,
- * else the innermost div or fence around it that states one, else its
- * language's script. A scroll fence that still names no face takes the face of
- * its map where the map is drawn in one.
+ * else inherited language or an ordinary prose family. Native map/face
+ * defaults are selected only by this construct's explicit `.nativefont`
+ * opt-in; marked children make their own presentation choice.
  */
 export type Run = {
     /**
@@ -314,4 +320,9 @@ export type Run = {
      * fence's 0-based closing line.
      */
     end: number;
+    /**
+     * - True only for an explicit native opt-in
+     * with its own language; retained by index records for deferred defaults.
+     */
+    nativefont?: boolean | undefined;
 };

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

@@ -8,9 +8,11 @@
  * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
  * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
  * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @param {boolean} [options.trackChanges] - Snapshot physical input metadata for build phase guards.
+ * @param {ReturnType<typeof createContentTimings>} [options.timings] - Invocation stage accounting.
  * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
  */
-export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, }?: {
+export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, timings, trackChanges, }?: {
     config?: import("../content-config.mjs").ContentBuildConfig | undefined;
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
@@ -21,6 +23,17 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
         packsOfType: (docType: string) => string[];
         defaultOf: (docType: string) => string | undefined;
     } | undefined;
+    trackChanges?: boolean | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): Promise<ContentSession>;
 /**
  * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
@@ -47,6 +60,8 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
  * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
  * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
  * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {ReturnType<typeof createContentTimings>} timings
+ * @property {() => void} assertUnchanged
  * @property {() => void} dispose
  */
 /**
@@ -96,6 +111,8 @@ export type ContentSession = {
     publication: () => Promise<import("./content-index.mjs").PreparedContentIndex>;
     compileCorpus: () => ReturnType<typeof import("./compile-corpus.mjs").buildCompileCorpus>;
     prepare: (targets: readonly ContentTarget[]) => Promise<ContentSession>;
+    timings: ReturnType<typeof createContentTimings>;
+    assertUnchanged: () => void;
     dispose: () => void;
 };
 import * as blocks from "./content-blocks.mjs";
@@ -106,3 +123,4 @@ import { captureContentSources } from "./content-sources.mjs";
 import { loadForeignIndexes } from "./metadata-index.mjs";
 import * as sql from "./sql-tables.mjs";
 import { buildLinkIndex } from "./content-links.mjs";
+import { createContentTimings } from "./content-timings.mjs";

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

@@ -0,0 +1,14 @@
+/** Sequential, nested stage accounting for one content invocation. */
+export function createContentTimings(): {
+    /** @template T @param {string} name @param {() => T} work @returns {T} */
+    sync<T>(name: string, work: () => T): T;
+    /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
+    measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+    /** @param {string} name */
+    hit(name: string): void;
+    snapshot(): {
+        totalMs: number;
+        stages: any;
+        hits: any;
+    };
+};

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

@@ -1,9 +1,20 @@
-/** The authored verse lines, excluding stanza separators. */
+/** The authored verse lines, excluding blank lines and stanza separators. */
 export function verseLines(body: any): string[];
 /**
- * The least-indented verse is level zero. Every two additional leading spaces
- * add one level; a leftover space is discarded and the level stops at eight.
- * Blank lines divide stanzas rather than contributing to the baseline.
+ * 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.
+ * Periods inside a span set indentation only when that span starts the line.
+ */
+export function verseLine(line: any): {
+    text: string;
+    level: number;
+    markerStart: number;
+    markerLength: number;
+    textColumn: number;
+};
+/**
+ * Blank lines divide verse groups. A standalone `***` is its own group and
+ * separates stanzas. Each text line carries its period-based indentation.
  */
 export function verseStanzas(body: any): {
     text: string;
@@ -12,7 +23,8 @@ export function verseStanzas(body: any): {
 /** A verse is inline Markdown even when it starts with block syntax. */
 export function inlineVerse(text: any): string;
 /**
- * Keep stanzas as Markdown paragraphs and make every verse line a hard break.
+ * 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.
  */
@@ -41,61 +53,20 @@ export function scanVerse(source: string): {
         classes: never[];
         indent: string;
     }[];
-    errors: {
-        line: number;
-        column: number;
-        message: string;
-    }[];
+    errors: any[];
 };
-/** Whether a verse states a column. */
+/** 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;
 /**
- * A column's stacked entries, each with its offset in the written value.
- *
- * @param {string} value - A `col1=` or `col2=` value.
- * @returns {Array<{raw: string, offset: number, lang?: string, map?: string, font?: string, offsets: {lang: number, map?: number, font?: number}}>}
- *   Each entry; one whose `lang` is `undefined` is malformed.
- */
-export function columnEntries(value: string): Array<{
-    raw: string;
-    offset: number;
-    lang?: string;
-    map?: string;
-    font?: string;
-    offsets: {
-        lang: number;
-        map?: number;
-        font?: number;
-    };
-}>;
-/**
- * The columns of a verse, the left first, each entry located in the opening
- * line.
+ * 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 {@link scanVerse}.
- * @param {string} opening - Its opening line.
- * @returns {Array<{key: string, entries: Array<ReturnType<typeof columnEntries>[number] & {column: number, columns: {lang: number, map?: number, font?: number}}>}>}
- *   1-based columns.
- */
-export function verseColumns(block: object, opening: string): Array<{
-    key: string;
-    entries: Array<ReturnType<typeof columnEntries>[number] & {
-        column: number;
-        columns: {
-            lang: number;
-            map?: number;
-            font?: number;
-        };
-    }>;
-}>;
-/**
- * The verse lines of a verse in columns: each blank-line group of span lines
- * is one verse line, and a line holding only `***` breaks the stanza.
- *
- * @param {object} block - A verse from {@link scanVerse}.
- * @param {string[]} lines - The source, by line.
- * @returns {Array<{stanzaBreak: true, line: number}|{stanzaBreak?: false, parts: Array<{line: number, column: number, text: string, textColumn: number, lang?: string, span: boolean, extra: boolean, indent: number}>}>}
- *   0-based lines, 1-based columns.
+ * @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}>}>}
  */
 export function verseGroups(block: object, lines: string[]): Array<{
     stanzaBreak: true;
@@ -103,14 +74,15 @@ export function verseGroups(block: object, lines: string[]): Array<{
 } | {
     stanzaBreak?: false;
     parts: Array<{
-        line: number;
         column: number;
-        text: string;
+        line: number;
+        sourceColumn: number;
         textColumn: number;
-        lang?: string;
-        span: boolean;
-        extra: boolean;
+        text: string;
         indent: number;
+        markerStart: number;
+        markerLength: number;
+        prefixLength: number;
     }>;
 }>;
 /**
@@ -121,75 +93,15 @@ export function verseGroups(block: object, lines: string[]): Array<{
  * @returns {boolean} Whether it starts right to left.
  */
 export function rightToLeft(text: string): boolean;
-/**
- * Where a line of {@link expandVerseOrigins}'s output came from.
- *
- * @typedef {object} VerseOrigin
- * @property {number} line - The source line, 0-based.
- * @property {number} [textColumn] - For an entry's line, the 1-based source
- *   column of its text's first character.
- * @property {boolean} [span] - Whether the source line is a span, whose `[`
- *   sits before its text.
- * @property {number} [textLength] - The length of the entry's text.
- * @property {{line: number, columns: {lang: number, map?: number, font?: number}}} [entry] -
- *   Where the entry is written in the opening line.
- */
-/**
- * Write each verse line of a sound verse in columns as one span per column
- * entry, the left column's entries first, each with the entry's language,
- * mapping and font. Every target runs it before marked text is rewritten, so
- * each entry is set exactly as a span with those keys is. The verse gains the
- * class {@link COLUMNS_CLASS}; a verse already carrying it, a verse with a
- * finding, and a verse without columns are left as written.
- *
- * @param {string} source - Markdown.
- * @returns {{markdown: string, origins: VerseOrigin[]}} The Markdown, and
- *   where each of its lines came from.
- */
-export function expandVerseOrigins(source: string): {
-    markdown: string;
-    origins: VerseOrigin[];
-};
-/**
- * {@link expandVerseOrigins}'s Markdown alone.
- *
- * @param {string} source - Markdown.
- * @returns {string} The Markdown with each verse in columns expanded.
- */
-export function expandVerse(source: string): string;
-/**
- * Where a position in {@link expandVerseOrigins}'s output was written.
- *
- * A position in an entry's text is the same character of the source line; a
- * position in its keys is the entry's part in the opening line that states
- * the key it falls in.
- *
- * @param {{line: number, column: number}} at - 1-based, in the output.
- * @param {string[]} expanded - The output, by line.
- * @param {VerseOrigin[]} origins - From {@link expandVerseOrigins}.
- * @returns {{line: number, column: number}} 1-based, in the source.
- */
-export function sourcePosition(at: {
-    line: number;
-    column: number;
-}, expanded: string[], origins: VerseOrigin[]): {
-    line: number;
-    column: number;
-};
 /** Replace verse fences with HTML wrappers whose body remains inline Markdown.
  * @param {string} source - Authored Markdown.
  */
 export function renderVerse(source: string): {
     markdown: string;
-    errors: {
-        line: number;
-        column: number;
-        message: string;
-    }[];
+    errors: any[];
 };
-/** The keys that set a verse in columns, the left first. */
-export const COLUMN_KEYS: readonly string[];
-/** The class the build gives a verse in columns once its lines are expanded. */
+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`
@@ -198,43 +110,5 @@ export const COLUMNS_CLASS: "verse-columns";
  * the faces, and reach the element as they are written.
  */
 export const VERSE_KEYS: readonly string[];
-/**
- * The line that breaks a stanza in a verse in columns, `***`, also as the
- * rewrite of marked text escapes it.
- */
+/** A line separating stanzas, including escaped output from a native run. */
 export const STANZA_BREAK: RegExp;
-/**
- * Where a line of {@link expandVerseOrigins}'s output came from.
- */
-export type VerseOrigin = {
-    /**
-     * - The source line, 0-based.
-     */
-    line: number;
-    /**
-     * - For an entry's line, the 1-based source
-     * column of its text's first character.
-     */
-    textColumn?: number | undefined;
-    /**
-     * - Whether the source line is a span, whose `[`
-     * sits before its text.
-     */
-    span?: boolean | undefined;
-    /**
-     * - The length of the entry's text.
-     */
-    textLength?: number | undefined;
-    /**
-     * -
-     * Where the entry is written in the opening line.
-     */
-    entry?: {
-        line: number;
-        columns: {
-            lang: number;
-            map?: number;
-            font?: number;
-        };
-    } | undefined;
-};

package/types/engine/run-rows.d.mts

@@ -6,10 +6,12 @@
  * @property {string|null} lang - The language it is set in, as written: its
  *   own `lang=`, else the one the div or fence around it states.
  * @property {string|null} tag - The BCP 47 tag it resolves to, or null.
- * @property {string|null} font - Its font, as written and inherited the same
- *   way, else its language's script's.
- * @property {string|null} map - Its map, as written and inherited the same way,
- *   else its language's script's.
+ * @property {string|null} font - Its explicit font, an inherited ordinary
+ *   prose family, or the configured default for an opted-in native run.
+ * @property {string|null} map - Its explicit map or the configured map of an
+ *   opted-in native run; null for Roman language-only text.
+ * @property {boolean} [nativefont] - Explicit native opt-in on this construct;
+ *   absent on Roman runs. This internal flag is not a SQL column.
  * @property {number} line - 1-based file line of its opening.
  * @property {number} column - 1-based UTF-16 file column of its opening.
  */
@@ -36,7 +38,7 @@ export function recordRuns(body: string, { context, bodyLine, bodyColumn, syntax
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): RecordRun[];
 /**
- * Give every recorded run the map and face its language's note names in
+ * Give explicitly native recorded runs the map and face their language names in
  * `data.writtenIn`, where the run leaves them unstated, as a run is set. Read
  * once every record exists, since a run's language note may be recorded after
  * the note that marks it.
@@ -88,15 +90,20 @@ export type RecordRun = {
      */
     tag: string | null;
     /**
-     * - Its font, as written and inherited the same
-     * way, else its language's script's.
+     * - Its explicit font, an inherited ordinary
+     * prose family, or the configured default for an opted-in native run.
      */
     font: string | null;
     /**
-     * - Its map, as written and inherited the same way,
-     * else its language's script's.
+     * - Its explicit map or the configured map of an
+     * opted-in native run; null for Roman language-only text.
      */
     map: string | null;
+    /**
+     * - Explicit native opt-in on this construct;
+     * absent on Roman runs. This internal flag is not a SQL column.
+     */
+    nativefont?: boolean | undefined;
     /**
      * - 1-based file line of its opening.
      */

package/types/engine/script-font-delivery.d.mts

@@ -7,19 +7,21 @@
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {ReadonlySet<string>} The slugs of the faces used.
  */
-export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts): ReadonlySet<string>;
+export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts, session?: import("./content-session.mjs").ContentSession): ReadonlySet<string>;
 /**
  * The files a target receives, as paths relative to the fonts package root.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{root: string, version: string, files: string[]}|undefined} The
  *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
  *   listed format. `undefined` when the consumer ships none.
  */
-export function scriptFontFiles(config: DeliveryConfig, formats: string[]): {
+export function scriptFontFiles(config: DeliveryConfig, formats: string[], session?: import("./content-session.mjs").ContentSession): {
     root: string;
     version: string;
     files: string[];
@@ -46,18 +48,20 @@ export function stagedStylesheet(css: string, staged: ReadonlySet<string>): stri
  * @param {string} dest - The directory to fill; created when there is
  *   something to put in it.
  * @param {string[]} formats - The font formats the target uses.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {number} How many files were written; 0 when the consumer ships none.
  */
-export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[]): number;
+export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[], session?: import("./content-session.mjs").ContentSession): number;
 /**
  * Whether the package ships what its manifest and stylesheet promise: the
  * stylesheet, the licence and every file the manifest lists.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{file: string, severity: "error", message: string}[]} One finding
  *   per missing file, located at the manifest; empty when the consumer ships none.
  */
-export function checkScriptFonts(config: DeliveryConfig): {
+export function checkScriptFonts(config: DeliveryConfig, session?: import("./content-session.mjs").ContentSession): {
     file: string;
     severity: "error";
     message: string;

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 fences, from {@link module:engine/content-verse.scanVerse}.
  * @param {string[]} lines - The source's lines.
- * @param {{metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, columnsClass: string, columnKeys: readonly string[], 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>, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
  *   The metres and books, and how the fence says its columns and where its
  *   keys sit.
  * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
@@ -86,11 +86,12 @@ export function metreFindings(blocks: ReadonlyArray<{
     attributes: Record<string, string>;
     classes: string[];
 }>, lines: string[], ctx: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+    }>>;
     metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>;
     metreBooks?: ReadonlyMap<string, MetreBook>;
     lexicons?: ReadonlyMap<string, unknown>;
-    columnsClass: string;
-    columnKeys: readonly string[];
     attributeColumns: (line: string, key: string) => {
         key: number;
         value: number;