@heroiclands/package-build 24.1.1 → 25.1.0

package/engine/script-font-delivery.mjs

@@ -14,7 +14,7 @@
 /**
  * **Delivering the installed faces to each target.** A consumer that installs
  * `@heroiclands/fonts` and sets text in one of its faces, with `font=` or by a
- * language note's `data.writtenIn`, gets the fonts on the site, in the Foundry
+ * encoding document's `data.font`, gets the fonts on the site, in the Foundry
  * module and in its books; without both, nothing ships and nothing links to it.
  *
  * - **Site and Foundry** receive `fonts.css`, listing only the WOFF2 sources,
@@ -32,7 +32,6 @@ import YAML from "yaml";
 import { baseStyleLayer } from "./base-styles.mjs";
 import { scanRuns } from "./content-scripts.mjs";
 import { FONTS_MANIFEST, resolveScriptFonts } from "./script-fonts.mjs";
-import { LANGUAGE_SUBTYPE } from "./word-terms.mjs";
 
 /**
  * Where the files land in the staged Foundry module, relative to its root.
@@ -72,14 +71,14 @@ const usedFaces = new WeakMap();
 const FRONTMATTER = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 
 /**
- * The face a language note names in `data.writtenIn`, where it is installed.
+ * The face an encoding document names in `data.font`, where it is installed.
  *
  * @param {string} source - The note's file.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
  * @param {import("./content-session.mjs").ContentNoteSource} [parsed] - Already parsed authored note.
  * @returns {string|undefined} The face's slug.
  */
-function writtenInFace(source, installed, parsed) {
+function encodingNoteFace(source, installed, parsed) {
     const yaml = FRONTMATTER.exec(source)?.[1];
     if (yaml === undefined) return undefined;
     let fm;
@@ -88,18 +87,16 @@ function writtenInFace(source, installed, parsed) {
     } catch {
         return undefined;
     }
-    if (fm?.type !== "skill" || String(fm.subType ?? "").toLowerCase() !== LANGUAGE_SUBTYPE)
-        return undefined;
-    const font = fm.data?.writtenIn?.font;
+    if (fm?.type !== "doc" || !fm.data?.mappings || !fm.data?.rules) return undefined;
+    const font = fm.data?.font;
     return typeof font === "string" && installed.faces.has(font) ? font : undefined;
 }
 
 /**
  * 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.
@@ -123,8 +120,8 @@ export function facesUsed(config, installed, session) {
             if (entry.isDirectory()) walk(full);
             else if (entry.isFile() && entry.name.endsWith(".md")) {
                 const source = session?.sources.get(full)?.raw ?? fs.readFileSync(full, "utf8");
-                if (/^\s*writtenIn:/m.test(source)) {
-                    const face = writtenInFace(source, installed, session?.parsed.get(full));
+                if (/^\s*font:/m.test(source)) {
+                    const face = encodingNoteFace(source, installed, session?.parsed.get(full));
                     if (face) used.add(face);
                 }
                 if (!/\bfont=/.test(source)) continue;

package/engine/script-fonts.mjs

@@ -17,7 +17,7 @@
  * each one draws — in its `fonts.json`, and this module reads them from the
  * **consuming package's** install.
  *
- * package-build declares no dependency on `@heroiclands/fonts` in any field:
+ * package-build declares no runtime dependency on `@heroiclands/fonts`:
  * the fonts package depends on package-build to build, so the consumer adds it
  * as a devDependency of its own and package-build resolves it from the
  * consumer's root. Resolving from this module's own location would find
@@ -42,6 +42,7 @@ export const FONTS_MANIFEST = "fonts.json";
  * @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.
  */
 

package/engine/site-build.mjs

@@ -807,8 +807,8 @@ export function renderSitePage(
         ...markupAnchorFindings(page.body),
     ])
         secretErrors.push({
-            file: page.file,
-            line: (page.bodyLine ?? 1) + error.line - 1,
+            file: error.file ?? page.file,
+            line: error.file ? error.line : (page.bodyLine ?? 1) + error.line - 1,
             column: error.column,
             message: error.message,
         });
@@ -818,8 +818,8 @@ export function renderSitePage(
         headingErrors.push({ file: page.file, ...error });
     for (const error of footnoteFindings(page.body))
         footnoteErrors.push({
-            file: page.file,
-            line: (page.bodyLine ?? 1) + error.line - 1,
+            file: error.file ?? page.file,
+            line: error.file ? error.line : (page.bodyLine ?? 1) + error.line - 1,
             column: error.column,
             message: error.message,
         });
@@ -1008,11 +1008,20 @@ export function renderPages(pages, options) {
             drawings: maps,
             runs,
         });
+    const externalRunFindings = new Set();
     for (const page of pages) {
         const result = renderOne(page);
         tableErrors.push(...result.tableErrors);
         expressionErrors.push(...result.expressionErrors);
-        secretErrors.push(...result.secretErrors);
+        secretErrors.push(
+            ...result.secretErrors.filter((error) => {
+                if (!error.file || error.file === page.file) return true;
+                const key = JSON.stringify([error.file, error.line, error.column, error.message]);
+                if (externalRunFindings.has(key)) return false;
+                externalRunFindings.add(key);
+                return true;
+            }),
+        );
         captionErrors.push(...result.captionErrors);
         headingErrors.push(...result.headingErrors);
         footnoteErrors.push(...result.footnoteErrors);

package/engine/site-preview.mjs

@@ -21,6 +21,7 @@ import { PREVIEW_HELPERS, colored, wikiSource } from "./preview-source.mjs";
 import { dataFields } from "./note-vocabulary.mjs";
 import { applyComputedBeingAge } from "./being-age.mjs";
 import { DEFAULT_CURRENT_DATE, normalizeCurrentDate } from "./current-date.mjs";
+import { scanRuns } from "./content-scripts.mjs";
 
 export { PREVIEW_HELPERS };
 
@@ -76,7 +77,7 @@ function localInfobox(fm, md) {
  * @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,
@@ -84,6 +85,7 @@ export function renderPreview(
 ) {
     const date = normalizeCurrentDate(currentDate);
     const findings = [];
+    let bodyLine = 1;
     let frontmatter = {},
         body = String(text ?? "");
     try {
@@ -92,6 +94,7 @@ export function renderPreview(
             parsed.data && typeof parsed.data === "object" && !Array.isArray(parsed.data) ?
                 structuredClone(parsed.data)
             :   {};
+        bodyLine = body.slice(0, body.length - parsed.content.length).split("\n").length;
         body = parsed.content;
     } catch (error) {
         findings.push({ file, severity: "warning", message: String(error.message) });
@@ -123,6 +126,13 @@ export function renderPreview(
     let markdown = authored;
     let figures = scan.figures;
     if (indexed) {
+        for (const error of scanRuns(body, index.runs).errors)
+            findings.push({
+                file,
+                severity: "error",
+                ...error,
+                line: error.file && error.file !== file ? error.line : bodyLine + error.line - 1,
+            });
         const expanded = index.expand(authored, { fm: frontmatter, file });
         markdown = expanded.markdown;
         figures = expanded.figures;
@@ -134,7 +144,7 @@ export function renderPreview(
     });
     const profile = infobox ? localInfobox(frontmatter, renderer.md) : "";
     return {
-        ok: true,
+        ok: !findings.some((finding) => finding.severity === "error"),
         html: `<div class="hl-preview hl-preview-${dark ? "dark" : "light"}">${profile}<main class="hl-preview-main">${content}</main></div>`,
         frontmatter,
         findings,

package/engine/sql-tables.mjs

@@ -36,8 +36,7 @@ import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventCalendars, eventRows } from "./
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
 import { RUN_COLUMNS, ownerOf, runsRows } from "./run-rows.mjs";
-import { MAP_COLUMNS, mapRows } from "./text-maps.mjs";
-import { NATIVE_COLUMNS, nativeRows } from "./map-lexicon.mjs";
+import { NATIVE_COLUMNS, nativeRows } from "./encoding-lexicon.mjs";
 import {
     GLOSSARY_COLUMNS,
     AFFIX_COLUMNS,
@@ -217,6 +216,31 @@ export function findSqlBlocks(markdown) {
     return blocks;
 }
 
+/** Keep encoding source keys as case-sensitive values in the SQL projection.
+ * The canonical index retains its authored mapping object; DuckDB structs
+ * cannot distinguish a and A as field names.
+ */
+function sqlRecord(record) {
+    const mappings = record?.data?.mappings;
+    if (
+        record?.type !== "doc" ||
+        !mappings ||
+        typeof mappings !== "object" ||
+        Array.isArray(mappings)
+    )
+        return record;
+    return {
+        ...record,
+        data: {
+            ...record.data,
+            mappings: Object.entries(mappings).map(([from, value]) => ({
+                from,
+                codes: Array.isArray(value) ? value : [value],
+            })),
+        },
+    };
+}
+
 /**
  * Open a DuckDB view over the content index.
  *
@@ -274,7 +298,7 @@ export async function openNotesDatabase(
     const base = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "content-sql-"));
     fs.mkdirSync(base, { recursive: true });
     const jsonl = path.join(base, "notes.jsonl");
-    const encoded = records.map((record) => encodeAddresses(record));
+    const encoded = records.map((record) => sqlRecord(encodeAddresses(record)));
 
     const instance = await DuckDBInstance.create(":memory:");
     const connection = await instance.connect();
@@ -284,7 +308,7 @@ export async function openNotesDatabase(
     } catch (err) {
         // DuckDB names the clashing key but not the notes that spell it.
         if (/Duplicate name ".*" in struct/.test(String(err?.message))) {
-            const lines = keyCaseCollisionDiagnostics(records, { contentBase });
+            const lines = keyCaseCollisionDiagnostics(encoded, { contentBase });
             if (lines.length) {
                 const located = new Error(lines.join("\n"));
                 /** @type {any} */ (located).located = true;
@@ -296,7 +320,7 @@ export async function openNotesDatabase(
     await createEventRelation(connection, path.join(base, "events.jsonl"), encoded, "", audience);
     await createNameRelation(connection, path.join(base, "names.jsonl"), encoded, "", audience);
     await createRunRelation(connection, path.join(base, "runs.jsonl"), encoded, "", audience);
-    await createMapRelation(connection, path.join(base, "maps.jsonl"), encoded, "", audience);
+    await createNativeRelation(connection, path.join(base, "natives.jsonl"), encoded, "", audience);
     await createWordRelations(connection, path.join(base, "notes"), encoded, "", audience);
 
     // One schema per declared dependency, so `FROM sohl.notes` reads the notes
@@ -317,7 +341,7 @@ export async function openNotesDatabase(
             .readFileSync(dep.file, "utf8")
             .split("\n")
             .filter((line) => line.trim())
-            .map((line) => flattenPublishedAddresses(JSON.parse(line)));
+            .map((line) => sqlRecord(flattenPublishedAddresses(JSON.parse(line))));
         await createRelations(connection, flat, depRecords, `${schema}.`, audience);
         await createEventRelation(
             connection,
@@ -340,9 +364,9 @@ export async function openNotesDatabase(
             `${schema}.`,
             audience,
         );
-        await createMapRelation(
+        await createNativeRelation(
             connection,
-            flat.replace(/\.jsonl$/, "-maps.jsonl"),
+            flat.replace(/\.jsonl$/, "-natives.jsonl"),
             depRecords,
             `${schema}.`,
             audience,
@@ -382,7 +406,6 @@ export async function openNotesDatabase(
         "events",
         "names",
         "runs",
-        "maps",
         "words",
         "affixes",
         "fields",
@@ -643,7 +666,7 @@ async function createNameRelation(connection, file, records, prefix, audience) {
 
 /**
  * Create the `runs` relation: one row per span, div and verse fence an own
- * note marks with `lang=`, `font=` or `map=`, with the columns
+ * note marks with `lang=`, `font=` or `enc=`, with the columns
  * {@link module:engine/run-rows.RUN_COLUMNS} names. The columns are declared
  * rather than inferred, so every value stays a string and none becomes a
  * struct key whose case DuckDB folds.
@@ -665,30 +688,12 @@ async function createRunRelation(connection, file, records, prefix, audience) {
     ]);
 }
 
-/**
- * Create the `maps` relation: one row per row of a mapping note's
- * `data.map`, with the columns {@link module:engine/text-maps.MAP_COLUMNS}
- * names; and the `natives` relation, one row per native form of a language's
- * word, with the columns {@link module:engine/map-lexicon.NATIVE_COLUMNS}
- * names. A row is a row here, never a struct key, so `A` and `a` are two rows.
- *
- * @param {object} connection - An open DuckDB connection.
- * @param {string} file - Where to write the rows.
- * @param {object[]} records - Index records, every Address a string.
- * @param {string} prefix - A schema to qualify the relation name with.
- * @param {"all"|"public"} audience - Whether to leave out GM notes.
- * @returns {Promise<void>}
- */
-async function createMapRelation(connection, file, records, prefix, audience) {
-    const rows = mapRows(
-        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
-        ownerOf,
-    );
-    await createTypedRelation(connection, file, `${prefix}maps`, rows, MAP_COLUMNS, ["row"]);
+/** Project authored native entries into the natives SQL relation. */
+async function createNativeRelation(connection, file, records, prefix, audience) {
     const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
     await createTypedRelation(
         connection,
-        file.replace(/maps\.jsonl$/, "natives.jsonl"),
+        file,
         `${prefix}natives`,
         nativeRows(visible),
         NATIVE_COLUMNS,

package/engine/verse-metre.mjs

@@ -52,7 +52,7 @@
 import { nearest } from "./near-miss.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { METRE_KINDS, METRE_NAME } from "./metre-declaration.mjs";
-import { languageRecordsByName } from "./map-lexicon.mjs";
+import { languageRecordsByName } from "./encoding-lexicon.mjs";
 import { STRESS_LONGER, STRESS_MARKS, STRESS_TWO } from "./language-terms.mjs";
 import { parseWordClass } from "./word-classes.mjs";
 import { derivedForms, foldWord } from "./word-forms.mjs";

package/engine/word-forms.mjs

@@ -50,7 +50,7 @@
  * @module
  */
 
-import { pluralByRule, pluralOf } from "./dictionary-rows.mjs";
+import { pluralByRule, pluralOf } from "./word-inflections.mjs";
 import { replaceClosing, verbForm, verbPattern } from "./verb-pattern.mjs";
 import { parseWordClass } from "./word-classes.mjs";
 import { WORD } from "./word-pattern.mjs";

package/engine/word-inflections.mjs

@@ -0,0 +1,48 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { parseWordClass } from "./word-classes.mjs";
+
+/**
+ * A noun's stated plural, or the first literal ending replacement that fits.
+ *
+ * @param {{form: string, class?: unknown, plural?: unknown}} word - A word of
+ *   `data.words`.
+ * @param {Record<string, any>|undefined} grammar - Its language's
+ *   `data.grammar`.
+ * @returns {string|null} The plural, or `null` for a word that is no noun or
+ *   that no rule fits.
+ */
+export function pluralOf(word, grammar) {
+    if (parseWordClass(word.class).base !== "n") return null;
+    if (typeof word.plural === "string" && word.plural) return word.plural;
+    return pluralByRule(word.form, grammar);
+}
+
+/**
+ * The plural a language's `data.grammar.plural` rule gives a form: the first
+ * literal ending replacement that fits, whatever the form's class.
+ *
+ * @param {string} form - The form.
+ * @param {Record<string, any>|undefined} grammar - Its language's
+ *   `data.grammar`.
+ * @returns {string|null} The plural, or `null` where no rule fits.
+ */
+export function pluralByRule(form, grammar) {
+    for (const rule of Array.isArray(grammar?.plural) ? grammar.plural : []) {
+        if (typeof rule?.ending !== "string" || typeof rule.becomes !== "string") continue;
+        if (form.endsWith(rule.ending))
+            return (rule.ending ? form.slice(0, -rule.ending.length) : form) + rule.becomes;
+    }
+    return null;
+}

package/engine/word-rows.mjs

@@ -71,7 +71,7 @@ export const GLOSSARY_COLUMNS = Object.freeze(["note", "position", ...GLOSSARY_E
 
 /**
  * The affix's own keys an affix row carries: all but `native`, its writings
- * under a logographic map, which `package-build lexicon` resolves.
+ * under an encoding, which `package-build lexicon` resolves.
  */
 const AFFIX_ROW_KEYS = Object.freeze(AFFIX_KEYS.filter((key) => key !== "native"));
 

package/engine/word-terms.mjs

@@ -106,28 +106,28 @@ export const WORD_SOURCE_FIELDS = Object.freeze([
  */
 export const WORD_NATIVE_FIELDS = Object.freeze([
     Object.freeze({
-        name: "map",
+        name: "enc",
         kind: "string",
         required: true,
-        shape: "a mapping note's `data.map.name`",
-        describe: "The map the native form is written for.",
+        shape: "an encoding document Address",
+        describe: "The encoding the native form is written for.",
     }),
     Object.freeze({
         name: "font",
         kind: "string",
-        shape: "a face the map lists",
+        shape: "a face the encoding lists",
         describe:
-            "The one face the native form is for; unstated, it is for every face the map lists, " +
+            "The one face the native form is for; unstated, it is for every face the encoding lists, " +
             "and a form stated for a face wins over it there.",
     }),
     Object.freeze({
         name: "text",
         kind: "string",
         required: true,
-        shape: "the word in the script, as the map's characters",
+        shape: "the word in the script, as the encoding's characters",
         describe:
-            "The word as the script writes it, where the map's rows would write it otherwise, " +
-            "or as a logographic map writes it.",
+            "The word as the script writes it, where the encoding's rows would write it otherwise, " +
+            "or by an explicit native spelling.",
     }),
 ]);
 
@@ -253,17 +253,16 @@ export const WORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "native",
         kind: "list",
-        shape: "a list of `{ map, font?, text }`",
+        shape: "a list of `{ enc, font?, text }`",
         entries: Object.freeze({
             kind: "map",
-            shape: "a map — `{ map, font?, text }`",
+            shape: "a map — `{ enc, font?, text }`",
             fields: WORD_NATIVE_FIELDS,
         }),
         describe:
-            "The word's native form under a map. Under a map that spells by its rows it is " +
-            "stated only where the rows spell the word differently, and the word's derived " +
-            "forms are spelled by the rows; under a logographic map it is the word's writing, " +
-            "which its derived forms and the words built on it are written from.",
+            "The word's own writing for an encoding and optional face. It precedes complete " +
+            "parts and the encoding's rows; an entry for a face precedes an unqualified entry. " +
+            "Derived forms can use the stem and explicitly written grammatical endings.",
     }),
 ]);
 
@@ -426,14 +425,14 @@ export const AFFIX_FIELDS = Object.freeze([
     Object.freeze({
         name: "native",
         kind: "list",
-        shape: "a list of `{ map, font?, text }`",
+        shape: "a list of `{ enc, font?, text }`",
         entries: Object.freeze({
             kind: "map",
-            shape: "a map — `{ map, font?, text }`",
+            shape: "a map — `{ enc, font?, text }`",
             fields: WORD_NATIVE_FIELDS,
         }),
         describe:
-            "The affix's writing under a logographic map, which a word whose `built` names the " +
+            "The affix's writing under an encoding, which a word whose `built` names the " +
             "affix is written with.",
     }),
 ]);

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "24.1.1",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
+    "version": "25.1.0",
+    "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",
     "main": "./index.mjs",
@@ -97,7 +97,12 @@
             "import": "./templates.mjs"
         },
         "./changelog": "./changelog.cjs",
-        "./package.json": "./package.json"
+        "./package.json": "./package.json",
+        "./convert": {
+            "types": "./types/convert.d.mts",
+            "import": "./convert.mjs",
+            "default": "./convert.mjs"
+        }
     },
     "bin": {
         "package-build": "./bin/package-build.mjs",
@@ -134,7 +139,8 @@
         "stage.mjs",
         "templates.mjs",
         "types",
-        "vendor"
+        "vendor",
+        "convert.mjs"
     ],
     "dependencies": {
         "@duckdb/node-api": "^1.5.5-r.4",
@@ -184,7 +190,7 @@
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
-        "@heroiclands/fonts": "^0.1.5",
+        "@heroiclands/fonts": "^1.0.0",
         "@types/node": "^26.2.0",
         "esbuild": "^0.28.2",
         "markdownlint": "^0.42.0",

package/types/config.d.mts

@@ -113,6 +113,7 @@ export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
  *                                   named first in the manifest's `styles`.
  * @property {Readonly<Record<string, unknown>>} manifest  The manifest
  *                                   specification, emitted as declared.
+ * @property {string|null} converterData  Optional JSON path relative to the build stage.
  * @property {string|null} manifestFlags  Module to load a `flags` function
  *                                   from, for namespaced flags a repository has
  *                                   to compute. `null` when it declares none.
@@ -260,6 +261,10 @@ export type PackageBuildConfig = {
      * specification, emitted as declared.
      */
     manifest: Readonly<Record<string, unknown>>;
+    /**
+     * Optional JSON path relative to the build stage.
+     */
+    converterData: string | null;
     /**
      * Module to load a `flags` function
      * from, for namespaced flags a repository has

package/types/convert.d.mts

@@ -0,0 +1,44 @@
+/** Validate the format-2 converter data without opening files or using Node.
+ * @param {ConverterData} data Parsed JSON, treated as read-only.
+ * @returns {ConverterData} The validated data.
+ */
+export function validateData(data: ConverterData): ConverterData;
+/** Encode with the selected encoding document's language, optionally stated explicitly.
+ * @param {ConverterData} data The module's parsed converter data.
+ * @param {string|null|undefined} language A language key, or null to infer it from the encoding.
+ * @param {string} text Roman input.
+ * @param {ConversionOptions} [options] Encoding, face or verse overrides.
+ */
+export function encode(data: ConverterData, language: string | null | undefined, text: string, options?: ConversionOptions): {
+    text: string;
+    findings: object[];
+};
+/** Decode with the selected encoding document's optional language lexicon.
+ * @param {ConverterData} data The module's parsed converter data.
+ * @param {string|null|undefined} language A language key, or null to infer it from the encoding.
+ * @param {string} text Encoded Unicode input.
+ * @param {ConversionOptions} [options] Encoding or face overrides.
+ */
+export function decode(data: ConverterData, language: string | null | undefined, text: string, options?: ConversionOptions): {
+    text: string;
+    findings: object[];
+};
+export type ConverterLexicon = {
+    language: string;
+    data: Record<string, any>;
+};
+export type ConverterLanguage = {
+    name: string;
+    lexicon?: ConverterLexicon;
+};
+export type ConverterData = {
+    format: 2;
+    contentPackage: string;
+    encodings: Record<string, any>;
+    languages: Record<string, ConverterLanguage>;
+};
+export type ConversionOptions = {
+    enc?: string;
+    font?: string;
+    verse?: boolean;
+};

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.8110.0";
+export const CHROME_BUILD_ID: "158.0.8122.0";
 /**
  * The disposable world's identity and credentials.
  */

package/types/engine/base-compiler.d.mts

@@ -476,10 +476,11 @@ export class BasePackCompiler {
      * naming the file alone beats naming a line that is not the problem.
      *
      * @param {string} message - What is wrong, in one sentence.
-     * @param {{line?: number, column?: number}} [position] - Where, if known.
+     * @param {{file?: string, line?: number, column?: number}} [position] - Where, if known.
      * @returns {void}
      */
     noteWarn(message: string, position?: {
+        file?: string;
         line?: number;
         column?: number;
     }): void;
@@ -487,10 +488,11 @@ export class BasePackCompiler {
      * Reports an error about the note being compiled.
      *
      * @param {string} message - What is wrong, in one sentence.
-     * @param {{line?: number, column?: number}} [position] - Where, if known.
+     * @param {{file?: string, line?: number, column?: number}} [position] - Where, if known.
      * @returns {void}
      */
     noteError(message: string, position?: {
+        file?: string;
         line?: number;
         column?: number;
     }): void;

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

@@ -9,6 +9,14 @@
  * @returns {boolean} Whether Tier 1 admits it.
  */
 export function isLetterTier(cp: number): boolean;
+/**
+ * Whether a code point belongs to a declared setting-script encoding block.
+ * This identifies native input independently of a language's Roman inventory;
+ * a selected native face must still draw the individual character.
+ * @param {number} cp - A Unicode code point.
+ * @returns {boolean}
+ */
+export function isSettingScriptCodePoint(cp: number): boolean;
 /**
  * Whether the charset admits a code point anywhere in a note.
  *