@heroiclands/package-build 24.1.1 → 25.1.0

package/engine/encoding-notes.mjs

@@ -0,0 +1,186 @@
+/*
+ * 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
+ */
+
+/** Encoding documents and glyph codes read from the consumer's content and fonts. */
+import fs from "node:fs";
+import path from "node:path";
+import { compileEncoding, EncodingError } from "./encoding.mjs";
+import { parseAddress, renderAddress, isAddressTuple } from "./address.mjs";
+import { positionOfFrontmatterPath, positionOfYamlPath } from "./diagnostics.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { addressSuffixes } from "./address-render.mjs";
+import { faceSlug } from "./script-fonts.mjs";
+
+function codePointPosition(raw, position) {
+    if (position.line === undefined || position.column === undefined) return position;
+    const line = raw.split("\n")[position.line - 1] ?? "";
+    return { ...position, column: [...line.slice(0, position.column - 1)].length + 1 };
+}
+
+/** 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, contentPackage) {
+    if (value === "default" || value === undefined) return "default";
+    const parsed = parseAddress(
+        value,
+        {
+            package: contentPackage,
+            system: "note",
+            type: "doc",
+            types: new Set(["doc"]),
+        },
+        { declared: true },
+    );
+    return isAddressTuple(parsed) && parsed.type === "doc" ? renderAddress(parsed) : 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) {
+    return Object.fromEntries(
+        ["language", "font", "accepts", "vowels", "mappings", "rules"]
+            .filter((key) => data?.[key] !== undefined)
+            .map((key) => [key, data[key]]),
+    );
+}
+
+/** 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, font) {
+    const file = fonts?.root ? path.join(fonts.root, "fonts.json") : "package.json";
+    const familyIndex = fonts?.manifest?.families?.findIndex((entry) => faceSlug(entry) === font);
+    const raw = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const failure = (message, keyPath = []) => {
+        throw Object.assign(new EncodingError(message), {
+            file,
+            ...(raw && keyPath.length ?
+                codePointPosition(
+                    raw,
+                    positionOfYamlPath(raw, ["families", familyIndex, ...keyPath]),
+                )
+            :   {}),
+        });
+    };
+    const face = fonts?.manifest?.families?.find((entry) => faceSlug(entry) === font);
+    if (!face) failure(`Font \`${font}\` is not installed from @heroiclands/fonts`);
+    const codes = Object.create(null);
+    for (const [pointIndex, point] of (face.codepoints ?? []).entries()) {
+        if (typeof point.code !== "string" || !/^[A-Za-z0-9_]+$/.test(point.code))
+            failure(`Font \`${font}\` has a missing or invalid glyph code at ${point.codepoint}`, [
+                "codepoints",
+                pointIndex,
+                "code",
+            ]);
+        const matched = /^U\+([0-9A-F]{4,6})$/.exec(point.codepoint ?? "");
+        const scalar = matched ? Number.parseInt(matched[1], 16) : -1;
+        if (scalar < 0 || scalar > 0x10ffff || (scalar >= 0xd800 && scalar <= 0xdfff))
+            failure(`Font \`${font}\` has an invalid code point ${point.codepoint}`, [
+                "codepoints",
+                pointIndex,
+                "codepoint",
+            ]);
+        if (Object.hasOwn(codes, point.code))
+            failure(`Font \`${font}\` repeats glyph code \`${point.code}\``, [
+                "codepoints",
+                pointIndex,
+                "code",
+            ]);
+        codes[point.code] = String.fromCodePoint(scalar);
+    }
+    if (!Object.keys(codes).length) failure(`Font \`${font}\` publishes no glyph codes`);
+    return codes;
+}
+
+/** 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, config = {}, fonts) {
+    const encodings = new Map(),
+        definitions = new Map(),
+        findings = [];
+    for (const record of records ?? []) {
+        if (
+            !isNoteRecord(record) ||
+            record.type !== "doc" ||
+            (!Object.hasOwn(record.data ?? {}, "mappings") &&
+                !Object.hasOwn(record.data ?? {}, "rules"))
+        )
+            continue;
+        const identity = {
+            package: record.package ?? config.contentPackage,
+            system: "note",
+            type: "doc",
+            shortcode: record.shortcode,
+        };
+        const name = renderAddress(identity);
+        const file =
+            typeof record.file === "string" ?
+                record.file
+            :   path.resolve(
+                    config.paths?.content ?? config.rootDir ?? ".",
+                    record.file?.path ?? "",
+                );
+        let raw = record.raw ?? "";
+        if (!raw && fs.existsSync(file) && fs.statSync(file).isFile())
+            raw = fs.readFileSync(file, "utf8");
+        try {
+            const data = encodingData(record.data);
+            if (!Object.hasOwn(config.languages ?? {}, data.language))
+                throw new EncodingError(
+                    `Encoding language \`${data.language}\` is not configured`,
+                    { key: "language" },
+                );
+            const codes = fontCodes(fonts, data.font);
+            const encoding = compileEncoding(data, { codes, name });
+            if (encodings.has(name))
+                throw new EncodingError(`Encoding document \`${name}\` is repeated`);
+            encodings.set(name, encoding);
+            definitions.set(name, { data, codes });
+            if ((record.package ?? config.contentPackage) === config.contentPackage) {
+                for (const alias of addressSuffixes(identity))
+                    if (alias !== "default") encodings.set(alias, encoding);
+            }
+        } catch (error) {
+            const own = !error.file || error.file === file;
+            const key =
+                error.key?.startsWith("mappings.") ?
+                    ["mappings", error.key.slice("mappings.".length)]
+                :   (error.key
+                        ?.split(".")
+                        .map((part) => (/^\d+$/.test(part) ? Number(part) : part)) ?? []);
+            findings.push({
+                file: error.file ?? file,
+                ...(own ?
+                    codePointPosition(raw, positionOfFrontmatterPath(raw, ["data", ...key]))
+                :   {
+                        ...(error.line === undefined ? {} : { line: error.line }),
+                        ...(error.column === undefined ? {} : { column: error.column }),
+                    }),
+                severity: "error",
+                message: error.message,
+            });
+        }
+    }
+    return { encodings, definitions, findings };
+}

package/engine/encoding-standard.mjs

@@ -0,0 +1,42 @@
+/*
+ * 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
+ */
+
+/** Shared Roman punctuation and invisible structural controls for every encoding. */
+export const STANDARD_ROWS = Object.freeze(
+    [
+        [".", "\u{E0100}"],
+        ["?", "\u{E0101}"],
+        ["‼", "\u{E0102}"],
+        ["!", "\u{E0103}"],
+        { from: "^", to: "\u{E0104}", at: "line-start" },
+        [",", "\u{E0105}"],
+        ["«", "\u{E0106}"],
+        ["»", "\u{E0107}"],
+        ["‹", "\u{E0108}"],
+        ["›", "\u{E0109}"],
+        ["—", "\u{E010A}"],
+        ["…", "\u{E010B}"],
+        ["/", "\u{E010C}"],
+        ["{", "\u{E0110}"],
+        ["}", "\u{E0111}"],
+    ].map(Object.freeze),
+);
+/** Controls belong to the engine and never come from font encoding files. */
+export const STANDARD_CONTROLS = Object.freeze({
+    verseStanza: "\u{E010D}",
+    verseCanto: "\u{E010E}",
+    wordSeparator: " ",
+    literalOpen: "\u{E0112}",
+    literalClose: "\u{E0113}",
+    literalEscape: "\u{E0115}",
+});

package/engine/encoding-template.mjs

@@ -0,0 +1,313 @@
+/*
+ * 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
+ */
+
+/** Compile the closed encoding-note template into the engine's internal row program. */
+import { STANDARD_ROWS, STANDARD_CONTROLS } from "./encoding-standard.mjs";
+import { assertUniqueOutputs } from "./encoding-integrity.mjs";
+
+const map = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const scalar = (value) =>
+    typeof value === "string" &&
+    !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value);
+const base = (value) => value.normalize("NFD").replace(/\p{M}/gu, "");
+const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const codeName = /^[A-Za-z0-9_]+$/;
+
+/**
+ * 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, options, fault) {
+    const closed = (value, allowed, key) => {
+        if (!map(value)) fault(key, `${key || "Encoding data"} must be an object`);
+        for (const name of Object.keys(value))
+            if (!allowed.includes(name))
+                fault(key ? `${key}.${name}` : name, `Unknown encoding key ${name}`);
+    };
+    const exact = (value, expected, key) => {
+        if (value !== expected) fault(key, `${key} must be ${JSON.stringify(expected)}`);
+    };
+    const fixed = (value, fields, key) => {
+        closed(value, Object.keys(fields), key);
+        for (const [name, expected] of Object.entries(fields))
+            exact(value[name], expected, `${key}.${name}`);
+    };
+    closed(data, ["language", "font", "accepts", "vowels", "mappings", "rules"], "");
+    closed(options, ["codes", "name"], "options");
+    for (const key of ["language", "font"])
+        if (typeof data[key] !== "string" || !slug.test(data[key]))
+            fault(key, `${key} must be a lowercase slug`);
+    if (options.name !== undefined && (!scalar(options.name) || !options.name))
+        fault("options.name", "name must be a nonempty document identity");
+    if (!map(options.codes)) fault("options.codes", "Supply the selected font's glyph code table");
+    for (const [name, target] of Object.entries(options.codes)) {
+        if (!codeName.test(name))
+            fault(`options.codes.${name}`, "A glyph code must be a short named code");
+        if (!scalar(target) || !target)
+            fault(
+                `options.codes.${name}`,
+                "A glyph code must resolve to nonempty Unicode scalar text",
+            );
+    }
+    const resolve = (value, key) => {
+        const sequence = typeof value === "string" ? [value] : value;
+        if (!Array.isArray(sequence) || !sequence.length)
+            fault(key, "A mapping is a glyph code or a nonempty sequence of glyph codes");
+        return sequence
+            .map((name) => {
+                if (
+                    typeof name !== "string" ||
+                    !codeName.test(name) ||
+                    !Object.hasOwn(options.codes, name)
+                )
+                    fault(key, `Unknown glyph code ${String(name)}`);
+                return options.codes[name];
+            })
+            .join("");
+    };
+    closed(
+        data.rules,
+        [
+            "normalization",
+            "matching",
+            "case",
+            "stress",
+            "vowel-groups",
+            "diaeresis",
+            "grave-accent",
+            "contextual-mappings",
+            "y",
+        ],
+        "rules",
+    );
+    const rules = data.rules;
+    exact(rules.normalization, "NFC", "rules.normalization");
+    exact(rules.matching, "longest-first", "rules.matching");
+    if (rules.case !== undefined)
+        fixed(
+            rules.case,
+            {
+                "single-letter": "preserve",
+                "consonant-group": "lowercase-or-initial-uppercase",
+                "other-group-cases": "forbidden",
+            },
+            "rules.case",
+        );
+    for (const key of ["diaeresis", "grave-accent"])
+        if (rules[key] !== undefined) fixed(rules[key], { allowed: false }, `rules.${key}`);
+    const vowels = data.vowels ?? "";
+    if (!scalar(vowels)) fault("vowels", "vowels must be a Unicode scalar string");
+    const vowelSet = new Set([...vowels].map(base));
+    if (rules.y !== undefined) {
+        fixed(rules.y, { kind: "consonant", sound: "y in yes", "vowel-reading": false }, "rules.y");
+        if (/[yY]/u.test(vowels)) fault("rules.y", "Consonant y cannot be declared a vowel");
+    }
+    let vowelGroups = [];
+    if (rules["vowel-groups"] !== undefined) {
+        const block = rules["vowel-groups"];
+        closed(
+            block,
+            ["reading", "allow-splitting", "unrecognized-adjacent-vowels", "groups"],
+            "rules.vowel-groups",
+        );
+        exact(block.reading, "established", "rules.vowel-groups.reading");
+        exact(block["allow-splitting"], false, "rules.vowel-groups.allow-splitting");
+        exact(
+            block["unrecognized-adjacent-vowels"],
+            "separate",
+            "rules.vowel-groups.unrecognized-adjacent-vowels",
+        );
+        if (!Array.isArray(block.groups))
+            fault("rules.vowel-groups.groups", "List established vowel groups explicitly");
+        const seen = new Set();
+        vowelGroups = block.groups
+            .map((group, i) => {
+                const key = `rules.vowel-groups.groups.${i}`;
+                if (
+                    !scalar(group) ||
+                    [...group].length < 2 ||
+                    group !== group.toLowerCase() ||
+                    base(group) !== group ||
+                    [...group].some((c) => !vowelSet.has(c)) ||
+                    seen.has(group)
+                )
+                    fault(
+                        key,
+                        "A vowel group is a unique lowercase sequence of declared unaccented vowels",
+                    );
+                seen.add(group);
+                return group;
+            })
+            .sort((a, b) => [...b].length - [...a].length);
+    }
+    let stress;
+    if (rules.stress !== undefined) {
+        const block = rules.stress;
+        closed(
+            block,
+            [
+                "modifier",
+                "position",
+                "printing",
+                "effect",
+                "changes-sound",
+                "changes-length",
+                "vowel-group-position",
+            ],
+            "rules.stress",
+        );
+        for (const [name, value] of Object.entries({
+            position: "after-stressed-vowel",
+            printing: false,
+            effect: "stress-only",
+            "changes-sound": false,
+            "changes-length": false,
+            "vowel-group-position": "first-vowel",
+        }))
+            exact(block[name], value, `rules.stress.${name}`);
+        stress = resolve(block.modifier, "rules.stress.modifier");
+        if (stress !== "\u{E0114}")
+            fault("rules.stress.modifier", "Stress is the nonprinting U+E0114 modifier");
+        if (!vowels) fault("vowels", "Stress rules require declared vowels");
+    }
+    closed(data.mappings, Object.keys(map(data.mappings) ? data.mappings : {}), "mappings");
+    const validateSource = (from, key) => {
+        if (!scalar(from) || !from || from !== from.normalize("NFC"))
+            fault(key, "Mapping sources must be nonempty NFC Unicode scalar text");
+        if (/[\p{White_Space}⟦⟧]/u.test(from))
+            fault(key, "Whitespace and literal markers belong to the shared standard");
+        const decomposed = from.normalize("NFD");
+        if (rules.diaeresis && decomposed.includes("\u0308")) fault(key, "Diaeresis is forbidden");
+        if (rules["grave-accent"] && decomposed.includes("\u0300"))
+            fault(key, "Grave accents are forbidden");
+    };
+    const validateOutput = (from, to, key) => {
+        if (/[\u{E010D}\u{E010E}\u{E0112}\u{E0113}\u{E0115}]/u.test(to))
+            fault(key, "Structural controls cannot be mapping outputs");
+        if (from.normalize("NFD").includes("\u0301") && stress) {
+            const plain = from.normalize("NFD").replaceAll("\u0301", "").normalize("NFC");
+            if (
+                [...from].length !== 1 ||
+                !vowelSet.has(base(from)) ||
+                !Object.hasOwn(data.mappings, plain) ||
+                to !== resolve(data.mappings[plain], key) + stress
+            )
+                fault(
+                    key,
+                    "An acute vowel must emit its unchanged vowel followed by the stress modifier",
+                );
+        } else if (stress && to.includes(stress))
+            fault(key, "The stress modifier belongs only after an acute vowel");
+    };
+    const mappings = [];
+    for (const [from, output] of Object.entries(data.mappings)) {
+        const key = `mappings.${from}`;
+        validateSource(from, key);
+        const to = resolve(output, key);
+        validateOutput(from, to, key);
+        mappings.push([from, to]);
+    }
+    const contextual = [];
+    if (rules["contextual-mappings"] !== undefined) {
+        if (!Array.isArray(rules["contextual-mappings"]))
+            fault("rules.contextual-mappings", "Contextual mappings must be a list");
+        const seen = new Set();
+        for (const [i, row] of rules["contextual-mappings"].entries()) {
+            const key = `rules.contextual-mappings.${i}`;
+            closed(row, ["match", "before", "emit"], key);
+            if (
+                !scalar(row.match) ||
+                !row.match ||
+                row.match !== row.match.normalize("NFC") ||
+                seen.has(row.match)
+            )
+                fault(`${key}.match`, "A contextual match must be unique nonempty NFC text");
+            exact(row.before, "vowel", `${key}.before`);
+            if (!vowels) fault(`${key}.before`, "Before-vowel mappings require declared vowels");
+            validateSource(row.match, `${key}.match`);
+            const to = resolve(row.emit, `${key}.emit`);
+            validateOutput(row.match, to, `${key}.emit`);
+            seen.add(row.match);
+            contextual.push({ from: row.match, to, before: "vowel" });
+        }
+    }
+    if (rules.case)
+        for (const [from] of [...mappings, ...contextual.map((r) => [r.from])]) {
+            if ([...from].length < 2 || !/^\p{L}+$/u.test(from)) continue;
+            const lower = from.toLowerCase(),
+                initial = [...lower][0].toUpperCase() + [...lower].slice(1).join("");
+            if (from !== lower && from !== initial)
+                fault(`mappings.${from}`, "A group must be lowercase or initial uppercase");
+        }
+    const overridden = new Set(mappings.map(([from]) => from));
+    const rows = [
+        ...STANDARD_ROWS.filter((row) => !overridden.has(Array.isArray(row) ? row[0] : row.from)),
+        ...contextual,
+        ...mappings,
+    ];
+    assertUniqueOutputs(
+        [
+            ...rows.map((row) => {
+                if (Array.isArray(row))
+                    return { from: row[0], to: row[1], key: `mappings.${row[0]}` };
+                const index = contextual.indexOf(row);
+                return {
+                    ...row,
+                    key: index < 0 ? "rules" : `rules.contextual-mappings.${index}.emit`,
+                };
+            }),
+            { from: " ", to: " ", key: "rules" },
+        ],
+        fault,
+    );
+    const accepts = data.accepts ?? [
+        ...new Set([
+            ...Object.keys(data.mappings).join(""),
+            ...contextual.map((r) => r.from).join(""),
+        ]),
+    ];
+    if (!Array.isArray(accepts)) fault("accepts", "accepts must be a list of characters or ranges");
+    return {
+        definition: {
+            name: "encoding-note",
+            fonts: [data.font],
+            accepts: [...accepts, ...STANDARD_ROWS.map((r) => (Array.isArray(r) ? r[0] : r.from))],
+            separator: " ",
+            vowels,
+            rows,
+            codes: Object.entries(options.codes),
+            controls: STANDARD_CONTROLS,
+            ...(rules.case ? { groupCase: "initial" } : {}),
+        },
+        rowKeys: rows.map((row) => {
+            if (Array.isArray(row)) return `mappings.${row[0]}`;
+            const index = contextual.indexOf(row);
+            return index < 0 ? "rules" : `rules.contextual-mappings.${index}`;
+        }),
+        metadata: {
+            name: options.name ?? `${data.language}-${data.font}`,
+            language: data.language,
+            font: data.font,
+            template: Object.freeze({
+                normalization: "NFC",
+                vowelGroups: Object.freeze(vowelGroups),
+                maxVowelGroup: Math.max(0, ...vowelGroups.map((group) => [...group].length)),
+                stress,
+                diaeresis: !!rules.diaeresis,
+                grave: !!rules["grave-accent"],
+            }),
+        },
+    };
+}

package/engine/encoding-terms.mjs

@@ -0,0 +1,141 @@
+/*
+ * 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
+ */
+
+/** Frontmatter shapes for executable encoding documents. */
+const text = (name, describe, required = false) => ({
+    name,
+    kind: "string",
+    shape: "a string",
+    describe,
+    required,
+});
+const fixed = (name, value) => ({
+    ...text(name, `Required value: ${JSON.stringify(value)}.`, true),
+    kind: typeof value === "boolean" ? "boolean" : "string",
+    shape: JSON.stringify(value),
+    ...(typeof value === "string" ? { allowed: [value] } : {}),
+});
+const block = (name, describe, fields) => ({ name, kind: "map", shape: "a map", describe, fields });
+const sequence = {
+    kind: "string-or-list",
+    shape: "a glyph code or list of codes",
+    entries: {
+        kind: "string",
+        shape: "a glyph code",
+        describe: "A code published by the selected font.",
+    },
+};
+/** Closed nested keys, also documented by the generated note reference. */
+export const ENCODING_RULE_FIELDS = Object.freeze([
+    fixed("normalization", "NFC"),
+    fixed("matching", "longest-first"),
+    block("case", "Case handling for letters and consonant groups.", [
+        fixed("single-letter", "preserve"),
+        fixed("consonant-group", "lowercase-or-initial-uppercase"),
+        fixed("other-group-cases", "forbidden"),
+    ]),
+    block("stress", "The font's nonprinting stress modifier after an acute vowel.", [
+        text("modifier", "The font code for U+E0114.", true),
+        fixed("position", "after-stressed-vowel"),
+        fixed("printing", false),
+        fixed("effect", "stress-only"),
+        fixed("changes-sound", false),
+        fixed("changes-length", false),
+        fixed("vowel-group-position", "first-vowel"),
+    ]),
+    block("vowel-groups", "Explicit recognized vowel groups and their acute placement.", [
+        fixed("reading", "established"),
+        fixed("allow-splitting", false),
+        fixed("unrecognized-adjacent-vowels", "separate"),
+        {
+            name: "groups",
+            kind: "list",
+            shape: "a list of vowel groups",
+            required: true,
+            entries: {
+                kind: "string",
+                shape: "a lowercase vowel sequence",
+                describe: "One recognized sequence of declared unaccented vowels.",
+            },
+            describe: "The complete authored group inventory.",
+        },
+    ]),
+    block("diaeresis", "Whether diaeresis mappings are allowed.", [fixed("allowed", false)]),
+    block("grave-accent", "Whether grave-accent mappings are allowed.", [fixed("allowed", false)]),
+    {
+        name: "contextual-mappings",
+        kind: "list",
+        shape: "a list of conditional mappings",
+        describe: "Before-vowel alternatives applied before unconditional mappings.",
+        entries: {
+            kind: "map",
+            shape: "a contextual mapping",
+            fields: [
+                text("match", "The source sequence.", true),
+                fixed("before", "vowel"),
+                {
+                    name: "emit",
+                    ...sequence,
+                    required: true,
+                    describe: "The font codes written by this alternative.",
+                },
+            ],
+        },
+    },
+    block("y", "The consonant reading of y.", [
+        fixed("kind", "consonant"),
+        fixed("sound", "y in yes"),
+        fixed("vowel-reading", false),
+    ]),
+]);
+/** The additional data keys a document may use to define its encoding. */
+export const ENCODING_NOTE_FIELDS = Object.freeze([
+    {
+        ...text("language", "The configured language alias an encoding document writes."),
+        shape: "a configured language alias",
+    },
+    {
+        ...text("font", "The encoding's installed font, which supplies all glyph codes."),
+        shape: "an installed font slug",
+    },
+    {
+        name: "accepts",
+        kind: "list",
+        shape: "a list of characters or ranges",
+        entries: {
+            kind: "string",
+            shape: "characters or a range",
+            describe: "Accepted Roman characters or a range.",
+        },
+        describe: "Accepted Roman letters and additions to standard punctuation.",
+    },
+    text("vowels", "The letters a contextual vowel match reads as vowels."),
+    {
+        name: "mappings",
+        kind: "map",
+        shape: "Roman strings to glyph codes",
+        values: {
+            ...sequence,
+            describe: "The font code or sequence written for this Roman string.",
+        },
+        describe: "Roman source strings mapped to codes published by the selected font.",
+    },
+    {
+        name: "rules",
+        kind: "map",
+        shape: "the closed encoding rules vocabulary",
+        fields: ENCODING_RULE_FIELDS,
+        describe:
+            "Executable normalization, matching, case, stress, vowel groups, accents and contextual mappings.",
+    },
+]);