@heroiclands/package-build 24.1.1 → 25.1.0

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

@@ -0,0 +1,39 @@
+/** Complete an encoding reference with the document type and citing package.
+ * @param {unknown} value - Authored encoding Address or default.
+ * @param {string} [contentPackage] - The citing note's package.
+ * @returns {string|undefined} Canonical Address, default, or an invalid reference.
+ */
+export function encodingAddress(value: unknown, contentPackage?: string): string | undefined;
+/** The executable fields a document owns, excluding ordinary document metadata.
+ * @param {Record<string, any>} data - Authored document data.
+ * @returns {Record<string, any>} Only the compiler's fields.
+ */
+export function encodingData(data: Record<string, any>): Record<string, any>;
+/** Read this selected face's published glyph codes, with no external code tables.
+ * @param {import("./script-fonts.mjs").ScriptFonts|undefined} fonts - Consumer fonts.
+ * @param {string} font - The selected face's slug.
+ * @returns {Record<string,string>} Code-to-Unicode mapping for this font only.
+ */
+export function fontCodes(fonts: import("./script-fonts.mjs").ScriptFonts | undefined, font: string): Record<string, string>;
+/** Compile each encoding document once and resolve references by document Address.
+ * @param {Iterable<Record<string, any>>} records - Content index records.
+ * @param {{languages?: Record<string, any>, contentPackage?: string, rootDir?: string, paths?: {content?: string}}} [config] - Consumer context.
+ * @param {import("./script-fonts.mjs").ScriptFonts} [fonts] - Installed glyph metadata.
+ * @returns {{encodings: Map<string, ReturnType<typeof compileEncoding>>, definitions: Map<string,{data:Record<string,any>,codes:Record<string,string>}>, findings:object[]}} Runtime and serializable document inputs.
+ */
+export function encodingsFromRecords(records: Iterable<Record<string, any>>, config?: {
+    languages?: Record<string, any>;
+    contentPackage?: string;
+    rootDir?: string;
+    paths?: {
+        content?: string;
+    };
+}, fonts?: import("./script-fonts.mjs").ScriptFonts): {
+    encodings: Map<string, ReturnType<typeof compileEncoding>>;
+    definitions: Map<string, {
+        data: Record<string, any>;
+        codes: Record<string, string>;
+    }>;
+    findings: object[];
+};
+import { compileEncoding } from "./encoding.mjs";

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

@@ -0,0 +1,11 @@
+/** Shared Roman punctuation and invisible structural controls for every encoding. */
+export const STANDARD_ROWS: readonly Readonly<unknown>[];
+/** Controls belong to the engine and never come from font encoding files. */
+export const STANDARD_CONTROLS: Readonly<{
+    verseStanza: "󠄍";
+    verseCanto: "󠄎";
+    wordSeparator: " ";
+    literalOpen: "󠄒";
+    literalClose: "󠄓";
+    literalEscape: "󠄕";
+}>;

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

@@ -65,6 +65,7 @@ export * as previewIndex from "./preview-index.mjs";
 export * as contentRender from "./content-render.mjs";
 export * as contentLint from "./content-lint.mjs";
 export * as contentCharset from "./content-charset.mjs";
+export * as romanCharacters from "./roman-characters.mjs";
 export * as pathCharset from "./path-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";
@@ -96,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

@@ -0,0 +1,45 @@
+/**
+ * Semantic problems in a supplied inventory. Shape belongs to the vocabulary.
+ * An empty string explicitly declares no written characters.
+ * @param {unknown} value - The authored `data.roman`.
+ * @returns {string[]} Findings at that field.
+ */
+export function romanInventoryProblems(value: unknown): string[];
+/**
+ * @typedef {object} RomanInventory
+ * @property {string} language - The configured language name.
+ * @property {ReadonlySet<string>|undefined} characters - Exact code points, absent for a missing declaration.
+ */
+/**
+ * Each configured language note's own inventory, by alias and BCP 47 tag.
+ * Language-family ancestry does not supply an inventory. Unassociated external
+ * tags have no entry and keep their ordinary behavior.
+ * @param {ReadonlyMap<string, Record<string, any>>} records - Configured language notes.
+ * @param {Readonly<Record<string, {tag: string}>>} languages - Language configuration.
+ * @returns {Map<string, RomanInventory>}
+ */
+export function romanInventoriesOf(records: ReadonlyMap<string, Record<string, any>>, languages?: Readonly<Record<string, {
+    tag: string;
+}>>): Map<string, RomanInventory>;
+/**
+ * Invalid source characters, retaining offsets in the supplied unescaped text.
+ * No punctuation, case or normalization repair is performed.
+ * @param {string} text - Visible Roman source.
+ * @param {RomanInventory} inventory - Its language's declared characters.
+ * @returns {Array<{offset: number, message: string}>}
+ */
+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.
+     */
+    language: string;
+    /**
+     * - Exact code points, absent for a missing declaration.
+     */
+    characters: ReadonlySet<string> | undefined;
+};

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";