@heroiclands/package-build 25.0.0 → 25.1.0

package/types/engine/encoding-template.d.mts

@@ -0,0 +1,43 @@
+/**
+ * Validate note data and resolve its code references without reading files.
+ * @param {any} data - Encoding-note data, excluding ordinary document metadata.
+ * @param {{codes?: Record<string,string>, name?: string}} options - Selected font codes and document identity.
+ * @param {(key:string,message:string)=>never} fault - Schema-error constructor supplied by the engine.
+ */
+export function templateProgram(data: any, options: {
+    codes?: Record<string, string>;
+    name?: string;
+}, fault: (key: string, message: string) => never): {
+    definition: {
+        groupCase?: string | undefined;
+        name: string;
+        fonts: any[];
+        accepts: any[];
+        separator: string;
+        vowels: any;
+        rows: Readonly<unknown>[];
+        codes: [string, string][];
+        controls: Readonly<{
+            verseStanza: "󠄍";
+            verseCanto: "󠄎";
+            wordSeparator: " ";
+            literalOpen: "󠄒";
+            literalClose: "󠄓";
+            literalEscape: "󠄕";
+        }>;
+    };
+    rowKeys: string[];
+    metadata: {
+        name: string;
+        language: any;
+        font: any;
+        template: Readonly<{
+            normalization: "NFC";
+            vowelGroups: any;
+            maxVowelGroup: number;
+            stress: "󠄔" | undefined;
+            diaeresis: boolean;
+            grave: boolean;
+        }>;
+    };
+};

package/types/engine/encoding-terms.d.mts

@@ -0,0 +1,105 @@
+/** Closed nested keys, also documented by the generated note reference. */
+export const ENCODING_RULE_FIELDS: readonly ({
+    allowed?: string[] | undefined;
+    kind: string;
+    shape: string;
+    name: any;
+    describe: any;
+    required: boolean;
+} | {
+    name: any;
+    kind: string;
+    shape: string;
+    describe: any;
+    fields: any;
+} | {
+    name: string;
+    kind: string;
+    shape: string;
+    describe: string;
+    entries: {
+        kind: string;
+        shape: string;
+        fields: {
+            name: any;
+            kind: string;
+            shape: string;
+            describe: any;
+            required: boolean;
+        }[];
+    };
+})[];
+/** The additional data keys a document may use to define its encoding. */
+export const ENCODING_NOTE_FIELDS: readonly ({
+    name: any;
+    kind: string;
+    shape: string;
+    describe: any;
+    required: boolean;
+} | {
+    name: string;
+    kind: string;
+    shape: string;
+    entries: {
+        kind: string;
+        shape: string;
+        describe: string;
+    };
+    describe: string;
+    values?: undefined;
+    fields?: undefined;
+} | {
+    name: string;
+    kind: string;
+    shape: string;
+    values: {
+        describe: string;
+        kind: string;
+        shape: string;
+        entries: {
+            kind: string;
+            shape: string;
+            describe: string;
+        };
+    };
+    describe: string;
+    entries?: undefined;
+    fields?: undefined;
+} | {
+    name: string;
+    kind: string;
+    shape: string;
+    fields: readonly ({
+        allowed?: string[] | undefined;
+        kind: string;
+        shape: string;
+        name: any;
+        describe: any;
+        required: boolean;
+    } | {
+        name: any;
+        kind: string;
+        shape: string;
+        describe: any;
+        fields: any;
+    } | {
+        name: string;
+        kind: string;
+        shape: string;
+        describe: string;
+        entries: {
+            kind: string;
+            shape: string;
+            fields: {
+                name: any;
+                kind: string;
+                shape: string;
+                describe: any;
+                required: boolean;
+            }[];
+        };
+    })[];
+    describe: string;
+    entries?: undefined;
+    values?: undefined;
+})[];

package/types/engine/encoding.d.mts

@@ -0,0 +1,155 @@
+/**
+ * Validate and compile an encoding note with a separately resolved font code table.
+ * @param {any} data Encoding-note data with mappings and executable rules.
+ * @param {{codes?: Record<string,string>, name?: string}} [options] Font glyph codes and canonical note identity.
+ */
+export function compileEncoding(data: any, options?: {
+    codes?: Record<string, string>;
+    name?: string;
+}): Readonly<{
+    name: any;
+    language?: any;
+    font?: any;
+    template?: Readonly<{
+        normalization: "NFC";
+        vowelGroups: any;
+        maxVowelGroup: number;
+        stress: "󠄔" | undefined;
+        diaeresis: boolean;
+        grave: boolean;
+    }> | undefined;
+    fonts: readonly any[];
+    separator: any;
+    separatorRow: {
+        from: string;
+        to: any;
+        key: string;
+    };
+    vowels: Set<any>;
+    accepted: Set<any>;
+    controls: any;
+    groupCase: any;
+    roundTrip: any;
+    shared: {
+        rows: any;
+        index: Map<any, any>;
+        readings: Map<any, any>;
+    };
+    faces: Map<any, any>;
+    codes: {
+        rows: any;
+        index: Map<any, any>;
+        readings: Map<any, any>;
+    };
+}>;
+/**
+ * Compile the internal row program, including isolated execution conformance fixtures.
+ * Application inputs go through compileEncoding's closed note schema.
+ * @internal
+ * @param {any} definition Fully resolved internal rows.
+ * @param {Partial<ReturnType<typeof templateProgram>["metadata"]>} [metadata] Validated note metadata, supplied by the template compiler.
+ */
+export function compileRows(definition: any, metadata?: Partial<ReturnType<typeof templateProgram>["metadata"]>): Readonly<{
+    name: any;
+    language?: any;
+    font?: any;
+    template?: Readonly<{
+        normalization: "NFC";
+        vowelGroups: any;
+        maxVowelGroup: number;
+        stress: "󠄔" | undefined;
+        diaeresis: boolean;
+        grave: boolean;
+    }> | undefined;
+    fonts: readonly any[];
+    separator: any;
+    separatorRow: {
+        from: string;
+        to: any;
+        key: string;
+    };
+    vowels: Set<any>;
+    accepted: Set<any>;
+    controls: any;
+    groupCase: any;
+    roundTrip: any;
+    shared: {
+        rows: any;
+        index: Map<any, any>;
+        readings: Map<any, any>;
+    };
+    faces: Map<any, any>;
+    codes: {
+        rows: any;
+        index: Map<any, any>;
+        readings: Map<any, any>;
+    };
+}>;
+/**
+ * Validate Roman spelling and literal syntax without requiring ordinary mapping coverage.
+ * Accepted words may instead have authoritative native writings in the language note.
+ * @param {ReturnType<typeof compileEncoding>} enc - Compiled encoding and its font codes.
+ * @param {string} text - Authored Roman source, normalized to NFC for template rules.
+ * @param {{font?:string,start?:number,end?:number}} [options] - Face and authored UTF-16 bounds.
+ * @returns {void} Throws EncodingError at the authored UTF-16 offset and code-point column.
+ */
+export function validateSource(enc: ReturnType<typeof compileEncoding>, text: string, options?: {
+    font?: string;
+    start?: number;
+    end?: number;
+}): void;
+/**
+ * Encode matched pieces while preserving offsets into the original source.
+ * @param {ReturnType<typeof compileEncoding>} enc - Compiled encoding note.
+ * @param {string} text - Authored Roman source.
+ * @param {{font?: string, verse?: boolean, start?: number, end?: number}} [options] - Source bounds and presentation.
+ */
+export function encodePieces(enc: ReturnType<typeof compileEncoding>, text: string, options?: {
+    font?: string;
+    verse?: boolean;
+    start?: number;
+    end?: number;
+}): {
+    from: any;
+    to: any;
+    start: any;
+    end: any;
+    row: any;
+}[];
+/**
+ * Encode text using exactly the rows of its compiled encoding. Unknown input is refused.
+ * @param {ReturnType<typeof compileEncoding>} enc
+ * @param {string} text
+ * @param {{font?: string, verse?: boolean}} [options]
+ * @returns {string}
+ */
+export function encodeText(enc: ReturnType<typeof compileEncoding>, text: string, options?: {
+    font?: string;
+    verse?: boolean;
+}): string;
+/**
+ * Decode a note's uniquely decodable output, including nonprefix glyph sequences.
+ * @param {ReturnType<typeof compileEncoding>} enc - Compiled encoding note.
+ * @param {string} text - Native text with optional literal spans.
+ * @param {{font?: string}} [options] - Selected encoding face.
+ * @returns {string} Roman source, with literals kept between their visible markers.
+ */
+export function decodeText(enc: ReturnType<typeof compileEncoding>, text: string, options?: {
+    font?: string;
+}): string;
+/**
+ * A schema fault or text refusal. Text offsets are UTF-16; columns count code points.
+ */
+export class EncodingError extends Error {
+    /** @param {string} message @param {{text?: string, offset?: number, key?: string}} [details] */
+    constructor(message: string, { text, offset, key }?: {
+        text?: string;
+        offset?: number;
+        key?: string;
+    });
+    key: string | undefined;
+    offset: number | undefined;
+    line: number | undefined;
+    column: number | undefined;
+}
+import { templateProgram } from "./encoding-template.mjs";

package/types/engine/helpers.d.mts

@@ -12,7 +12,7 @@
  *   {@link module:engine/content-figures.scanFigures}.
  * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
  *   languages, faces and maps. Given, text marked with `lang=`, `font=` and
- *   `map=` is rewritten first, so it is tagged for its language, mapped and
+ *   `enc=` is rewritten first, so it is tagged for its language, mapped and
  *   set in its font.
  * @returns {string} The rendered HTML.
  */

package/types/engine/index.d.mts

@@ -97,4 +97,8 @@ export * as sceneLevels from "./scene-levels.mjs";
 export * as generate from "./generate.mjs";
 export * as compendiums from "./compendiums.mjs";
 export * as regionEvents from "./region-events.mjs";
+export * as encoding from "./encoding.mjs";
+export * as encodingLanguage from "./encoding-language.mjs";
+export * as encodingNotes from "./encoding-notes.mjs";
+export * as encodingLexicon from "./encoding-lexicon.mjs";
 export { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS, REGION_EVENT_TO_TRIGGER } from "./region-events.mjs";

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

@@ -352,7 +352,7 @@ export const NAMING_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
  */
 export const VERB_PERSON_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
- * The endings `data.grammar.native` writes under a logographic map: the noun
+ * The endings `data.grammar.native` writes under a encoding: the noun
  * plural, then the six persons of the verb pattern.
  */
 export const WRITTEN_ENDINGS: readonly string[];

package/types/engine/{logographic.d.mts → language-writings.d.mts}

@@ -6,25 +6,25 @@
  *   | {ambiguous: {form: string, glosses: string[]}}} Writing
  */
 /**
- * The text a list of native entries states for a map in a face: the entry for
+ * The text a list of native entries states for a enc in a face: the entry for
  * the face, else the entry for no face.
  *
  * @param {unknown} natives - A `native` list as authored.
- * @param {string} map - The map's name.
+ * @param {string} enc - The encoding's name.
  * @param {string|undefined} font - The face.
  * @returns {string|undefined} The text.
  */
-export function nativeText(natives: unknown, map: string, font: string | undefined): string | undefined;
+export function nativeText(natives: unknown, enc: string, font: string | undefined): string | undefined;
 /**
- * The writings of a language's words under one logographic map in one face.
+ * The writings of a language's words under one encoding in one face.
  *
  * @param {Record<string, any>|undefined} data - The language note's `data`.
- * @param {string} map - The map's name.
+ * @param {string} enc - The encoding's name.
  * @param {string|undefined} font - The face.
  * @returns {{word: (word: string) => Writing, entry: (index: number) => Writing}}
  *   The writing of a run's word, and of the `data.words` entry at an index.
  */
-export function writingsOf(data: Record<string, any> | undefined, map: string, font: string | undefined): {
+export function writingsOf(data: Record<string, any> | undefined, enc: string, font: string | undefined): {
     word: (word: string) => Writing;
     entry: (index: number) => Writing;
 };

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

@@ -6,7 +6,7 @@
  * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
  *   languages, faces and maps. Given, text marked with `lang=`, `font=` and
- *   `map=` is checked against them; a caller with no package configuration
+ *   `enc=` is checked against them; a caller with no package configuration
  *   leaves it out.
  * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors,
  *   then warnings.

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

@@ -91,7 +91,7 @@ export function stripHtmlComments(markdown: string): string;
  *   finding.
  * @param {import("./content-scripts.mjs").RunContext} [opts.runs] - The
  *   package's languages, faces and maps, which text marked with `lang=`,
- *   `font=` and `map=` is checked against and set by.
+ *   `font=` and `enc=` is checked against and set by.
  * @param {number} [opts.bodyLine] - The 1-based file line the body starts on, so
  *   a finding's line is the file's rather than the body's.
  * @param {number} [opts.bodyColumn] - The 1-based column the body starts at.

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

@@ -26,13 +26,13 @@ export function romanInventoriesOf(records: ReadonlyMap<string, Record<string, a
  * No punctuation, case or normalization repair is performed.
  * @param {string} text - Visible Roman source.
  * @param {RomanInventory} inventory - Its language's declared characters.
- * @param {(char: string) => boolean} [native] - Whether a directly typed native sign is drawn in the selected native face.
  * @returns {Array<{offset: number, message: string}>}
  */
-export function romanTextProblems(text: string, inventory: RomanInventory, native?: (char: string) => boolean): Array<{
+export function romanTextProblems(text: string, inventory: RomanInventory): Array<{
     offset: number;
     message: string;
 }>;
+export function isRomanWhitespace(char: any): boolean;
 export type RomanInventory = {
     /**
      * - The configured language name.

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

@@ -0,0 +1,101 @@
+/**
+ * Project an authored run to logical Roman text while retaining source offsets.
+ * Presentation-only children contribute their text; names contribute standard
+ * braces. The caller decides which children are independent runs and which
+ * ranges are layout or emphasis delimiters.
+ * @module
+ */
+/**
+ * @typedef {object} RomanSpan
+ * @property {number} start - Opening bracket offset.
+ * @property {number} end - Offset past the attribute block.
+ * @property {number} contentEnd - Closing bracket offset.
+ * @property {Array<[string, string]>} [attrs] - Authored attributes.
+ */
+/**
+ * @typedef {object} ProjectedSpan
+ * @property {RomanSpan} source - The authored child.
+ * @property {number} from - Its first logical UTF-16 offset, including name braces.
+ * @property {number} to - Offset past its logical text and braces.
+ * @property {number} contentFrom - Logical text after its opening name brace.
+ * @property {number} contentTo - Offset past the logical text, before its closing name brace.
+ * @property {boolean} name - Whether this child marks a name.
+ * @property {boolean} included - Whether this child contributes its own text.
+ */
+/**
+ * Remove Markdown escapes, inline presentation syntax and excluded layout.
+ * The returned offsets refer to the original source, in UTF-16 units, matching
+ * the source scanner. A supplementary character has two entries, both pointing
+ * at its original first unit. Synthetic braces point at the name's brackets.
+ * @param {string} source - Complete authored source.
+ * @param {object} [options] - Bounds and projections chosen by the run scanner.
+ * @param {number} [options.from] - First included source offset.
+ * @param {number} [options.to] - Offset past the included source.
+ * @param {readonly RomanSpan[]} [options.spans] - Scanned spans, with absolute offsets.
+ * @param {(span: RomanSpan) => boolean} [options.includeSpan] - Whether a child inherits this run.
+ * @param {(span: RomanSpan) => string} [options.opaqueSpan] - Placeholder for an independent child. The default empty name keeps sentence state without introducing that child's letters.
+ * @param {ReadonlyArray<readonly [number, number]>} [options.exclude] - Absolute source ranges that carry layout or presentation syntax.
+ * @param {boolean} [options.markNames] - Whether name children contribute braces.
+ * @returns {{text: string, offsets: number[], spans: ProjectedSpan[]}} Logical text and source locations, with child ranges for presentation.
+ */
+export function plainRomanRun(source: string, { from, to, spans, includeSpan, opaqueSpan, exclude, markNames, }?: {
+    from?: number | undefined;
+    to?: number | undefined;
+    spans?: readonly RomanSpan[] | undefined;
+    includeSpan?: ((span: RomanSpan) => boolean) | undefined;
+    opaqueSpan?: ((span: RomanSpan) => string) | undefined;
+    exclude?: readonly (readonly [number, number])[] | undefined;
+    markNames?: boolean | undefined;
+}): {
+    text: string;
+    offsets: number[];
+    spans: ProjectedSpan[];
+};
+export type RomanSpan = {
+    /**
+     * - Opening bracket offset.
+     */
+    start: number;
+    /**
+     * - Offset past the attribute block.
+     */
+    end: number;
+    /**
+     * - Closing bracket offset.
+     */
+    contentEnd: number;
+    /**
+     * - Authored attributes.
+     */
+    attrs?: [string, string][] | undefined;
+};
+export type ProjectedSpan = {
+    /**
+     * - The authored child.
+     */
+    source: RomanSpan;
+    /**
+     * - Its first logical UTF-16 offset, including name braces.
+     */
+    from: number;
+    /**
+     * - Offset past its logical text and braces.
+     */
+    to: number;
+    /**
+     * - Logical text after its opening name brace.
+     */
+    contentFrom: number;
+    /**
+     * - Offset past the logical text, before its closing name brace.
+     */
+    contentTo: number;
+    /**
+     * - Whether this child marks a name.
+     */
+    name: boolean;
+    /**
+     * - Whether this child contributes its own text.
+     */
+    included: boolean;
+};

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

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ * @param {string} source - Complete authored source.
+ * @param {Parameters<typeof plainRomanRun>[1] & {isCantoLine?: (line: string) => boolean}} [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;
+}): ReturnType<typeof plainRomanRun> & {
+    boundaries: Array<{
+        kind: "line" | "stanza" | "canto";
+        at: number;
+        sourceOffset: number;
+    }>;
+    errors: Array<{
+        offset: number;
+        message: string;
+    }>;
+};
+import { plainRomanRun } from "./roman-run.mjs";

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

@@ -7,11 +7,8 @@
  *   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 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.
+ *   prose family, or the font of the selected encoding document.
+ * @property {string|null} enc - Its resolved encoding document, or default for Roman text.
  * @property {number} line - 1-based file line of its opening.
  * @property {number} column - 1-based UTF-16 file column of its opening.
  */
@@ -38,22 +35,24 @@ export function recordRuns(body: string, { context, bodyLine, bodyColumn, syntax
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): RecordRun[];
 /**
- * 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.
+ * Resolve recorded encoding Addresses and fill the language and font supplied
+ * by each selected document, once every index record exists.
  *
  * @param {Record<string, any>[]} records - The package's index records; each
  *   note record's `runs` is updated in place.
- * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string, rootDir?:string, paths?:{content?:string}}} config -
  *   The configured languages, whose `note` names each language note.
  */
-export function fillWrittenIn(records: Record<string, any>[], config: {
+export function fillEncodingRuns(records: Record<string, any>[], config: {
     languages?: Readonly<Record<string, {
         tag: string;
         note?: string;
     }>>;
     contentPackage?: string;
+    rootDir?: string;
+    paths?: {
+        content?: string;
+    };
 }): void;
 /**
  * The containing page's NOTE identity.
@@ -91,19 +90,13 @@ export type RecordRun = {
     tag: string | null;
     /**
      * - Its explicit font, an inherited ordinary
-     * prose family, or the configured default for an opted-in native run.
+     * prose family, or the font of the selected encoding document.
      */
     font: string | null;
     /**
-     * - Its explicit map or the configured map of an
-     * opted-in native run; null for Roman language-only text.
+     * - Its resolved encoding document, or default for Roman 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;
+    enc: string | null;
     /**
      * - 1-based file line of its opening.
      */

package/types/engine/script-emphasis-terms.d.mts

@@ -26,3 +26,5 @@ export const LANGUAGE_EMPHASES: readonly string[];
 export const SCRIPT_DIRECTIONS: readonly string[];
 /** The `subType` of a script note. */
 export const SCRIPT_SUBTYPE: "script";
+/** The ordinary prose families accepted by font=. */
+export const GENERIC_FAMILIES: readonly string[];

package/types/engine/script-emphasis.d.mts

@@ -12,7 +12,7 @@ export function emphasesFromRecords(records: Iterable<Record<string, any>> | und
  *
  * @param {ReadonlyMap<string, Record<string, any>>} byName - Each configured
  *   language's note record, by language name, from
- *   {@link module:engine/map-lexicon.languageRecordsByName}.
+ *   {@link module:engine/encoding-lexicon.languageRecordsByName}.
  * @returns {Map<string, LanguageEmphasis>} The conventions, by language name;
  *   a language whose note states none, or one the build does not know, is
  *   absent.

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

@@ -1,9 +1,8 @@
 /**
  * The faces the package's notes set text in, read from the notes
  * themselves: every Markdown file under the content tree that writes `font=`
- * is scanned for its runs, and the face every language note names in
- * `data.writtenIn` counts, since a run marked with the language alone is set
- * in it.
+ * is scanned for its runs, and encoding documents supply the fonts their
+ * encoded runs infer.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.

package/types/engine/script-fonts.d.mts

@@ -4,6 +4,7 @@
  * @typedef {object} FaceCodepoint
  * @property {string} codepoint - `U+` and the hexadecimal code point.
  * @property {string} glyph - The glyph's name in the face.
+ * @property {string} [code] - The font's case-sensitive glyph code.
  * @property {string} kind - What it is: `letter`, `numeral`, `mark` and so on.
  */
 /**
@@ -77,6 +78,10 @@ export type FaceCodepoint = {
      * - The glyph's name in the face.
      */
     glyph: string;
+    /**
+     * - The font's case-sensitive glyph code.
+     */
+    code?: string | undefined;
     /**
      * - What it is: `letter`, `numeral`, `mark` and so on.
      */

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

@@ -11,7 +11,7 @@
  * @param {string} text - Markdown, optionally beginning with YAML frontmatter.
  * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string,
  *   index?: import("./preview-index.mjs").PreviewIndex}} [options] - Explicit palette, profile visibility, diagnostic filename, neutral current date (default "720.1") and the content index, from {@link module:engine/preview-index.previewIndex}.
- * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null.
+ * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null. Error findings set `ok` to false while retaining the HTML.
  */
 export function renderPreview(text: string, { dark, infobox, file, currentDate, index }?: {
     dark?: boolean;