@heroiclands/package-build 23.12.5 → 23.12.7

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @heroiclands/package-build
 
+## 23.12.7
+
+### Patch Changes
+
+**Writing in the setting's languages and scripts**
+
+- Text can be marked with its language and set in one of the HeroicLands fonts, or in plain serif, sans or monospace, on the site, in Foundry and in books.
+- Roman spelling converts into a script through a mapping note, which takes a word from the language's dictionary when the dictionary spells it differently.
+- `package-build transliterate` and `package-build lexicon` show a passage or a word exactly as a build sets it.
+- Converted text is checked against its language, and an unknown word or unregistered name is reported where it is written.
+- A language's present endings can replace its infinitive ending, as Vylari's do.
+
+## 23.12.6
+
+### Patch Changes
+
+A package can name a default calendar with `defaultCalendar` in its configuration, and it replaces the world note's calendar as the one dates fall back to.
+
+A note's dates print in its own `data.calendar`, which any note may now set, else its culture's, else for a place its parents', else the default. A place whose parents keep different calendars is a build error until it names its own.
+
+Chronologies and the other event sections print every date in the calendar of the page showing them, and `dateformat` with no calendar named uses the note's.
+
 ## 23.12.5
 
 ### Patch Changes

package/assets/styles/content-base.css

@@ -164,6 +164,31 @@
     --poetry-indent: 10em;
 }
 
+/* Text set in one of the faces. The font family and features come from the
+ * face's own class; a right-to-left block or verse reads from the right. */
+.script-block {
+    margin: 1rem 0;
+    line-height: 1.7;
+}
+
+.script-block[dir="rtl"],
+.poetry[dir="rtl"] {
+    text-align: start;
+}
+
+/* Text set in the reader's generic families, `font=serif`, `sans` and `mono`. */
+.font-serif {
+    font-family: serif;
+}
+
+.font-sans {
+    font-family: sans-serif;
+}
+
+.font-mono {
+    font-family: monospace;
+}
+
 /*
  * Historical info/warn section classes remain available for styled prose.
  * New alerts use the separate alert classes below.

package/bin/content-commands.mjs

@@ -30,6 +30,8 @@
  *   npx package-build site [--out <dir>]
  *   npx package-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
  *   npx package-build reachability <dir> [file] [--index <shortcode>]
+ *   npx package-build transliterate <map> [--lang <language>] [--font <slug>] [--hex] [text..]
+ *   npx package-build lexicon <language> --map <map> [--font <slug>] [--json]
  *   npx package-build addresses diff --from <zip|dir> [--strict]
  *   npx package-build npc new (--spec <json> | --specfile <path>) [--seed <text>] [--out <path>]
  *
@@ -62,7 +64,19 @@ import {
     unaddressableForeignPackages,
     formatUnaddressableFinding,
 } from "../engine/metadata-index.mjs";
-import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
+import {
+    fetchNavigation,
+    generateHugoConfig,
+    HUGO_SOURCE,
+    writeHugoConfig,
+} from "../engine/site-config.mjs";
+import {
+    checkScriptFonts,
+    copyScriptFonts,
+    scriptFontFiles,
+    SITE_FONTS_DIR,
+    siteFontsDestination,
+} from "../engine/script-font-delivery.mjs";
 import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { checkDocLinks, checkDocIndex } from "../engine/docs-checks.mjs";
 import { checkArtSlotSizes } from "../engine/art-fields.mjs";
@@ -102,6 +116,14 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { markupFindings } from "../engine/markup-validation.mjs";
+import { runContext } from "../engine/content-scripts.mjs";
+import {
+    checkLexiconNatives,
+    checkMapFonts,
+    languageNoteFindings,
+    lexiconEntries,
+    transliterate,
+} from "../engine/map-lexicon.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
 import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
 import { loadPackageBuildConfig } from "../config.mjs";
@@ -300,6 +322,8 @@ export function registerContentCommands(cli) {
         )
         .command(withIndexPreflight(mapCommand()))
         .command(withIndexPreflight(reachabilityCommand()))
+        .command(transliterateCommand())
+        .command(lexiconCommand())
         .command(addressesCommand())
         .command(withIndexPreflight(npcCommand()));
 }
@@ -461,7 +485,7 @@ function withBodyPreflight(
                         :   undefined;
                     const records = session?.records ?? indexRecordsFor({ config, contentBase });
                     if (session?.problems.length) {
-                        emitDiagnostic(session.problems[0]);
+                        for (const problem of session.problems) emitDiagnostic(problem);
                         process.exitCode = 1;
                         return;
                     }
@@ -1257,10 +1281,19 @@ function lintCommand() {
                     assetsBase: config.paths.assets,
                 });
 
+                // Text marked with a language, a font or a map, checked against
+                // the languages this package declares, the faces it installed
+                // and the maps its notes declare.
+                const runs = runContext(config, records);
                 const findings = [
                     ...index.notes.flatMap((note) =>
-                        markupFindings(note.raw, note.file, session.syntax),
+                        markupFindings(note.raw, note.file, session.syntax, runs),
                     ),
+                    // Each mapping note's faces, each language's native forms
+                    // and each language's `note`, against the faces and maps.
+                    ...index.notes.flatMap((note) => checkMapFonts(note, runs)),
+                    ...index.notes.flatMap((note) => checkLexiconNatives(note, runs)),
+                    ...languageNoteFindings({ ...config, configFile: packConfigPath() }, records),
                     ...index.notes.flatMap(firstUseChecker),
                     ...(names ? [names] : []),
                     ...addresses.findings,
@@ -1891,6 +1924,38 @@ function pdfCommand() {
     };
 }
 
+/**
+ * Copy the installed script fonts into the Hugo static tree, under a path that
+ * names their version, and drop any other version's copy.
+ *
+ * A package that has not installed `@heroiclands/fonts`, or sets no text in
+ * one of its faces, gets no copy; a package missing a file its fonts depend on
+ * gets a located error and a non-zero exit.
+ *
+ * @param {object} config - The resolved content configuration.
+ * @returns {void}
+ */
+function stageSiteFonts(config) {
+    const root = path.join(config.rootDir, HUGO_SOURCE, "static", SITE_FONTS_DIR);
+    fs.rmSync(root, { recursive: true, force: true });
+    const found = scriptFontFiles(config, ["woff2"]);
+    if (!found) return;
+    const findings = checkScriptFonts(config);
+    for (const finding of findings) emitDiagnostic(finding);
+    if (findings.length) {
+        process.exitCode = 1;
+        return;
+    }
+    const dest = path.join(
+        config.rootDir,
+        HUGO_SOURCE,
+        "static",
+        siteFontsDestination(found.version),
+    );
+    const count = copyScriptFonts(config, dest, ["woff2"]);
+    log.info(`wrote ${count} script font file(s) to ${path.relative(process.cwd(), dest)}`);
+}
+
 /**
  * `package-build site` — publish the content tree as a website.
  *
@@ -2077,6 +2142,7 @@ function siteCommand() {
                 );
                 const { file } = writeHugoConfig(config, hugo);
                 log.info(`wrote ${path.relative(process.cwd(), file)}`);
+                stageSiteFonts(config);
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -2241,6 +2307,201 @@ function mapCommand() {
     };
 }
 
+/**
+ * The run context a mapping command reads: the content index's maps and
+ * lexicons, and the configured languages and installed faces, exactly as the
+ * build has them.
+ *
+ * @returns {{config: object, ctx: object}|undefined} The context, or
+ *   `undefined` when the content tree could not be read whole, which is
+ *   reported.
+ */
+function mappingContext() {
+    const config = loadPackConfig();
+    const problems = [];
+    const records = indexRecordsFor({
+        contentBase: config.paths.content,
+        config,
+        skipDirectories: config.skipDirectories,
+        problems,
+    });
+    for (const problem of problems) emitDiagnostic(problem);
+    if (problems.length) return undefined;
+    return { config, ctx: runContext(config, records) };
+}
+
+/**
+ * Report what a mapping command was given that names nothing: an unknown
+ * language at the configuration's `languages`, and an unknown map or face at
+ * the content tree, where mapping notes are. A word the rows cannot
+ * capitalise is in the passage given, so it has no file.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {{problem: string, about: string}} found - What is wrong.
+ * @param {string} [lang] - The language asked for.
+ */
+function reportMapping(config, found) {
+    if (found.about === "lang") {
+        const file = packConfigPath();
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        } catch {
+            text = undefined;
+        }
+        emitDiagnostic({
+            file,
+            ...(text ? positionOfYamlPath(text, ["languages"], { key: true }) : {}),
+            severity: "error",
+            message: found.problem,
+        });
+    } else if (found.about === "word")
+        // A word of the passage given, which sits in no file.
+        emitDiagnostic({ severity: "error", message: found.problem });
+    else emitDiagnostic({ file: config.paths.content, severity: "error", message: found.problem });
+    process.exitCode = 1;
+}
+
+/**
+ * `package-build transliterate <map> [text..]` — map a passage exactly as the
+ * build maps a run marked with the same `map=`, `lang=` and `font=`.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function transliterateCommand() {
+    return {
+        command: "transliterate <map> [text..]",
+        describe: "Map a passage into a script exactly as the build maps a marked run",
+        builder: (yargs) =>
+            yargs
+                .positional("map", {
+                    type: "string",
+                    describe: "The `data.map.name` of a mapping note",
+                })
+                .positional("text", {
+                    type: "string",
+                    array: true,
+                    describe: "The passage; `-` or nothing reads it from stdin",
+                })
+                .option("lang", {
+                    type: "string",
+                    describe: "A declared language, whose lexicon is read first",
+                })
+                .option("font", {
+                    type: "string",
+                    describe: "The face; required when the map lists more than one",
+                })
+                .option("hex", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Print the code points, as `U+XXXX` separated by spaces",
+                }),
+        handler: (argv) => {
+            try {
+                const read = mappingContext();
+                if (!read) {
+                    process.exitCode = 1;
+                    return;
+                }
+                const words = (argv.text ?? []).map(String);
+                const text =
+                    !words.length || (words.length === 1 && words[0] === "-") ?
+                        fs.readFileSync(0, "utf8").replace(/\r?\n$/, "")
+                    :   words.join(" ");
+                const mapped = transliterate(
+                    read.ctx,
+                    { map: String(argv.map), lang: argv.lang, font: argv.font },
+                    text,
+                );
+                if ("problem" in mapped) {
+                    reportMapping(read.config, mapped);
+                    return;
+                }
+                console.log(
+                    argv.hex ?
+                        Array.from(
+                            mapped.text,
+                            (char) =>
+                                `U+${char.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`,
+                        ).join(" ")
+                    :   mapped.text,
+                );
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
+/**
+ * `package-build lexicon <language> --map <map>` — every word of a language's
+ * lexicon with its native form under a map, as the build writes it.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function lexiconCommand() {
+    return {
+        command: "lexicon <language>",
+        describe: "List a language's words with their native forms under a map",
+        builder: (yargs) =>
+            yargs
+                .positional("language", {
+                    type: "string",
+                    describe: "A declared language whose `note` names its language note",
+                })
+                .option("map", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "The `data.map.name` of a mapping note",
+                })
+                .option("font", {
+                    type: "string",
+                    describe: "The face; required when the map lists more than one",
+                })
+                .option("json", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Print a JSON array rather than tab-separated lines",
+                }),
+        handler: (argv) => {
+            try {
+                const read = mappingContext();
+                if (!read) {
+                    process.exitCode = 1;
+                    return;
+                }
+                const listed = lexiconEntries(read.ctx, {
+                    lang: String(argv.language),
+                    map: String(argv.map),
+                    font: argv.font,
+                });
+                if ("problem" in listed) {
+                    reportMapping(read.config, listed);
+                    return;
+                }
+                if (argv.json) console.log(JSON.stringify(listed.entries, null, 2));
+                else
+                    for (const entry of listed.entries)
+                        console.log(
+                            [
+                                entry.form,
+                                entry.native,
+                                entry.exception ? "exception" : "rows",
+                                entry.class ?? "",
+                                entry.gloss ?? "",
+                            ].join("\t"),
+                        );
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `package-build reachability <dir> [file]` — check that a corpus reads through.
  *

package/bin/package-build.mjs

@@ -96,6 +96,11 @@ import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pac
 import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
 import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
 import { baseStyleStageEntry } from "../engine/base-styles.mjs";
+import {
+    checkScriptFonts,
+    copyScriptFonts,
+    STAGED_FONTS_DIR,
+} from "../engine/script-font-delivery.mjs";
 import {
     CDN_ENV,
     cdnCredentials,
@@ -576,6 +581,26 @@ function assetsCommand() {
                 count += staged.entries;
                 files += staged.files;
             }
+
+            // The installed fonts, when the package has installed the fonts
+            // package and a note sets text in one of its faces: the
+            // stylesheet, the WOFF2 files and the licence, which the
+            // manifest's `styles` names.
+            const fontFindings = checkScriptFonts(packConfig);
+            if (fontFindings.length) {
+                const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
+                error.located = true;
+                die(error);
+            }
+            const fonts = copyScriptFonts(
+                packConfig,
+                path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
+                ["woff2"],
+            );
+            if (fonts) {
+                count += 1;
+                files += fonts;
+            }
             console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
         }),
     };

package/content-config.mjs

@@ -70,6 +70,7 @@ import { normalizeCurrentDate } from "./engine/current-date.mjs";
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
+import { isLanguageTag } from "./engine/language-tag.mjs";
 import { ASSET_TYPE_NAMES, shippingLicensesProblem } from "./engine/asset-types.mjs";
 import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
@@ -571,6 +572,10 @@ export function publishesContentPages(config) {
  *                                          resolved against it, so the build never
  *                                          depends on the working directory.
  * @property {string} [currentDate] Setting-wide neutral current date; defaults to "720.1".
+ * @property {string} [defaultCalendar]     Shortcode of the `lore` note with
+ *                                          `subType: calendar` that prints the
+ *                                          dates of a note no other rule gives a
+ *                                          calendar.
  * @property {string} contentPackage        Content package name — the address
  *                                          namespace every note in this
  *                                          repository is published under.
@@ -610,6 +615,9 @@ export function publishesContentPages(config) {
  *                                          `{ system, builders }` registries
  *                                          instead, and the accepted type
  *                                          vocabulary is their union.
+ * @property {Record<string, LanguageSpec>} [languages]  The languages a
+ *                                          note may tag text with, by short
+ *                                          name. Default `{}`.
  * @property {PackSpec[]} packs             Packs to compile. More than one entry
  *                                          may share a `type`: a note then names
  *                                          the pack it belongs in with its
@@ -646,6 +654,8 @@ export function publishesContentPages(config) {
  *
  * @typedef {object} ContentBuildConfig
  * @property {string} currentDate Setting-wide neutral current date.
+ * @property {string|null} defaultCalendar The calendar of last resort's
+ *                                     shortcode, `null` when none is named.
  * @property {string} rootDir
  * @property {string} contentPackage
  * @property {string|null} foundryPackage  `null` for a `documentation`
@@ -713,6 +723,8 @@ export function publishesContentPages(config) {
  *                                     fonts this package ships and the names it
  *                                     draws from them; empty when it declares
  *                                     none.
+ * @property {Readonly<Record<string, Readonly<LanguageSpec>>>} languages
+ *                                     Frozen; `{}` when absent.
  * @property {readonly Readonly<ResolvedPackSpec>[]} packs
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
@@ -730,6 +742,7 @@ const CONFIG_KEYS = [
     "rootDir",
     "contentPackage",
     "currentDate",
+    "defaultCalendar",
     "foundryPackage",
     "homepage",
     "authors",
@@ -740,6 +753,7 @@ const CONFIG_KEYS = [
     "skipDirectories",
     "forbidGeneratedArt",
     "icons",
+    "languages",
     "packs",
     "docs",
     "site",
@@ -912,6 +926,88 @@ function fail(field, problem) {
     throw Object.assign(new TypeError(`package-build config: \`${field}\` ${problem}.`), { field });
 }
 
+/**
+ * The configured `defaultCalendar`: a calendar note's shortcode, or `null`.
+ * Whether it names a calendar note is checked against the content tree when
+ * the content index is built.
+ *
+ * @param {unknown} value - The configured value.
+ * @returns {string|null} The shortcode.
+ */
+function normalizeDefaultCalendar(value) {
+    if (value === undefined || value === null) return null;
+    if (typeof value !== "string" || !isAddressSegment(value))
+        fail(
+            "defaultCalendar",
+            "must be the shortcode of a calendar note — lowercase letters and digits",
+        );
+    return /** @type {string} */ (value);
+}
+
+/**
+ * One entry of `languages`.
+ *
+ * @typedef {object} LanguageSpec
+ * @property {string} tag   Its BCP 47 tag. A constructed language takes
+ *                          `art-x-<name>`.
+ * @property {string} [note] The Address of its language note, whose
+ *                          `data.words` is the lexicon a mapped run in the
+ *                          language reads first.
+ */
+
+/**
+ * What a language name may be: lowercase letters, digits and single hyphens,
+ * starting with a letter. Lowercase keeps two names from differing only in
+ * case, which an index keyed by them cannot tell apart.
+ */
+const LANGUAGE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/**
+ * Check `languages` and freeze it.
+ *
+ * @param {unknown} value - The configured mapping.
+ * @returns {Readonly<Record<string, Readonly<LanguageSpec>>>} The frozen
+ *   mapping; `{}` when absent.
+ */
+function normalizeLanguages(value) {
+    if (value === undefined || value === null) return Object.freeze({});
+    if (!isPlainObject(value)) fail("languages", "must be a mapping of language name to `{tag}`");
+    const out = {};
+    for (const [name, entry] of Object.entries(/** @type {object} */ (value))) {
+        const where = `languages.${name}`;
+        if (!LANGUAGE_NAME.test(name))
+            fail(
+                where,
+                "is not a name: a name is lowercase letters, digits and single hyphens, " +
+                    "starting with a letter",
+            );
+        if (!isPlainObject(entry)) fail(where, "must be a mapping with `tag`");
+        rejectUnknownKeys(entry, ["tag", "note"], `${where}.`);
+        const { tag, note } = /** @type {Record<string, unknown>} */ (entry);
+        if (tag === undefined || tag === null || tag === "")
+            fail(
+                `${where}.tag`,
+                "must be a BCP 47 language tag, such as `art-x-vyl` for a constructed language",
+            );
+        if (!isLanguageTag(tag))
+            fail(
+                `${where}.tag`,
+                `${String(tag)} is not a valid BCP 47 language tag; a constructed ` +
+                    "language takes `art-x-<name>`",
+            );
+        if (note !== undefined && (typeof note !== "string" || note.trim() === ""))
+            fail(
+                `${where}.note`,
+                "must be the Address of a language note, such as `skill-vylarilng`",
+            );
+        out[name] = Object.freeze({
+            tag: /** @type {string} */ (tag),
+            ...(note === undefined ? {} : { note: /** @type {string} */ (note) }),
+        });
+    }
+    return Object.freeze(out);
+}
+
 /**
  * @param {object} object
  * @param {readonly string[]} allowed
@@ -2973,6 +3069,7 @@ export function defineConfig(config) {
                 fail("currentDate", error.message);
             }
         })(),
+        defaultCalendar: normalizeDefaultCalendar(input.defaultCalendar),
         contentPackage: requireContentPackage(input.contentPackage, docEntryTypes, {
             rootDir,
             packageKind,
@@ -3049,6 +3146,7 @@ export function defineConfig(config) {
         skipDirectories: Object.freeze(skipDirectories),
         forbidGeneratedArt,
         icons: normalizeIcons(input.icons, rootDir),
+        languages: normalizeLanguages(input.languages),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),
         docs: normalizeDocs(input.docs),

package/docs/api.md

@@ -723,7 +723,7 @@ resolved value: the culture a place or affiliation inherits through
 
 ### `engine.markdownExpressions`
 
-`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. The `ref` helper links to a captioned item by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`, in the calendar it names or else the note's resolved calendar, which it reads from `dates.noteCalendars` — the map a reckoning context built over content-index records carries; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. The `ref` helper links to a captioned item by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
 
 | Export                      | Signature                                  | Returns                | Use it when                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -736,10 +736,13 @@ resolved value: the culture a place or affiliation inherits through
 
 The corpus registry anchors each calendar's year 1, day 1 to its canonical `data.epoch` and maps every declared era to that calendar. Exactly one `start: null` era covers earlier years and counts backwards; exactly one `start: 1` era begins the forward count. Other starts are distinct positive calendar years. Numeric order determines bounds, irrespective of array order. Duplicate starts and markers, missing required eras, and invalid epochs are findings. Short qualifiers are ambiguous when they name eras in several packages; a full Address selects one.
 
-| Export                    | Signature                                     | Returns                                  | Use it when                                                 |
-| ------------------------- | --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
-| `resolveReckoningMarkers` | `resolveReckoningMarkers(index, daysPerYear)` | `{eras, markers, findings}`              | resolving authored eras, their markers, and their bounds    |
-| `reckoningContext`        | `reckoningContext(index)`                     | `{eras, markers, daysPerYear, findings}` | sharing one resolved date context across checks on a corpus |
+| Export                    | Signature                                     | Returns                                                 | Use it when                                                                                           |
+| ------------------------- | --------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `resolveReckoningMarkers` | `resolveReckoningMarkers(index, daysPerYear)` | `{eras, markers, findings}`                             | resolving authored eras, their markers, and their bounds                                              |
+| `reckoningContext`        | `reckoningContext(index)`                     | `{eras, markers, daysPerYear, findings, noteCalendars}` | sharing one resolved date context across checks on a corpus                                           |
+| `noteCalendarMap`         | `noteCalendarMap(notes)`                      | `Map<string, string>`                                   | reading each record's `resolvedCalendar` by note, as `reckoningContext` carries it in `noteCalendars` |
+| `noteCalendarKey`         | `noteCalendarKey(fm)`                         | `string \| undefined`                                   | finding a note's entry in `noteCalendars` by its type and shortcode                                   |
+| `calendarAddress`         | `calendarAddress(value)`                      | `string \| undefined`                                   | reading a record's `resolvedCalendar`, tuple or string, as its canonical Address                      |
 
 ### `engine.calendarNotes`
 
@@ -2532,15 +2535,16 @@ The wildcard engine subpath exposes
 `@heroiclands/package-build/engine/dictionary-rows` for deriving the
 `dictionary` and `terms` SQL relations from content-index records:
 
-| Export                  | Signature                                       | Returns                                     | Use it when                                                             |
-| ----------------------- | ----------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
-| `DICTIONARY_COLUMNS`    | `const DICTIONARY_COLUMNS`                      | A readonly list of column names             | Declaring the schema of a language's dictionary.                        |
-| `TERM_COLUMNS`          | `const TERM_COLUMNS`                            | A readonly list of column names             | Declaring the schema of owner-specific glossary terms.                  |
-| `ETYMOLOGY_KEYS`        | `const ETYMOLOGY_KEYS`                          | A readonly list of keys                     | Reading the structure of a dictionary word's etymology.                 |
-| `dictionaryLetter`      | `dictionaryLetter(text)`                        | `string`                                    | Deriving a heading letter from a sort key.                              |
-| `dictionaryEntryAnchor` | `dictionaryEntryAnchor(language, name)`         | `string`                                    | Deriving the stable entry anchor for a word in a language's dictionary. |
-| `dictionaryAndTermRows` | `dictionaryAndTermRows(records, all = records)` | `{ dictionary: object[], terms: object[] }` | Deriving dictionary words and glossary terms for the selected records.  |
-| `serializeRows`         | `serializeRows(rows)`                           | `string`                                    | Writing deterministic JSON Lines with keys sorted at every depth.       |
+| Export                  | Signature                                       | Returns                                     | Use it when                                                                                        |
+| ----------------------- | ----------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `DICTIONARY_COLUMNS`    | `const DICTIONARY_COLUMNS`                      | A readonly list of column names             | Declaring the schema of a language's dictionary.                                                   |
+| `TERM_COLUMNS`          | `const TERM_COLUMNS`                            | A readonly list of column names             | Declaring the schema of owner-specific glossary terms.                                             |
+| `ETYMOLOGY_KEYS`        | `const ETYMOLOGY_KEYS`                          | A readonly list of keys                     | Reading the structure of a dictionary word's etymology.                                            |
+| `dictionaryLetter`      | `dictionaryLetter(text)`                        | `string`                                    | Deriving a heading letter from a sort key.                                                         |
+| `dictionaryEntryAnchor` | `dictionaryEntryAnchor(language, name)`         | `string`                                    | Deriving the stable entry anchor for a word in a language's dictionary.                            |
+| `dictionaryAndTermRows` | `dictionaryAndTermRows(records, all = records)` | `{ dictionary: object[], terms: object[] }` | Deriving dictionary words and glossary terms for the selected records.                             |
+| `serializeRows`         | `serializeRows(rows)`                           | `string`                                    | Writing deterministic JSON Lines with keys sorted at every depth.                                  |
+| `pluralOf`              | `pluralOf(word, grammar)`                       | `string \| null`                            | Deriving a noun's plural: its own `plural`, else the first `grammar.plural` row whose ending fits. |
 
 `dictionaryEntryAnchor` takes the language's canonical Address and the
 word's form. Its `word-` anchor is derived from the full SHA-256 digest of