@heroiclands/package-build 23.12.5 → 23.12.7

package/engine/markdown-expressions.mjs

@@ -15,11 +15,12 @@ import Handlebars from "handlebars";
 
 import { isAddressTuple, renderAddress } from "./address.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
-import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
+import { calendarEras, formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
 import { numberWords, numberDigits } from "./number-words.mjs";
 import { slugify } from "./content-slug.mjs";
 import { WIKILINK, authoredLabel, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
-import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
+import { EVENT_REFERENCE_FIELDS, eventFieldText, printEventDate } from "./event-fields.mjs";
+import { noteCalendar } from "./note-calendars.mjs";
 
 /**
  * An inline expression, as an author writes one.
@@ -33,6 +34,48 @@ import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
  */
 export const EXPRESSION = /(?<![\\{])\{\{(?![{<%])([^{}\n]+)\}\}(?!\})/g;
 
+/**
+ * Which of `dateformat`'s arguments is which. Three are a calendar, a date and
+ * a format. Two are a calendar and a date, unless the first is absent — a
+ * `data.calendar` the note leaves unset is no calendar — or is a date that
+ * names no calendar, when they are a date and a format. One is a date.
+ *
+ * @param {unknown[]} given - The arguments, without Handlebars' options.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {{calendar?: unknown, authored: unknown, format?: unknown}} The roles.
+ */
+function dateformatArguments(given, dates) {
+    if (given.length >= 3) {
+        const [calendar, authored, format] = given;
+        return { calendar: calendar ?? undefined, authored, format };
+    }
+    if (given.length < 2) return { authored: given[0] };
+    const [first, second] = given;
+    if (first === undefined || first === null) return { authored: second };
+    if (typeof first === "number") return { authored: first, format: second };
+    if (typeof first === "string" && !namesCalendar(first, dates)) {
+        const parsed = parseNoteDate(first, { ...dates, allowUnknown: false });
+        if (parsed.date && !parsed.findings.some((item) => item.severity === "error"))
+            return { authored: first, format: second };
+    }
+    return { calendar: first, authored: second };
+}
+
+/**
+ * Whether a string names a calendar or one of its eras.
+ *
+ * @param {string} value - The string.
+ * @param {object} [dates] - The reckoning context.
+ * @returns {boolean} Whether it resolves to one.
+ */
+function namesCalendar(value, dates) {
+    try {
+        return calendarEras(value, dates).length > 0;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * Every helper an expression may call, with the parameters it takes.
  *
@@ -135,30 +178,42 @@ const HELPERS = Object.freeze([
     }),
     Object.freeze({
         name: "dateformat",
-        params: 'calendar date ["format"]',
+        params: '[calendar] date ["format"]',
         summary:
-            "A date written in a calendar. The calendar is an Address or its shortcode, the date " +
-            "is the value a note carries, and the optional third argument names an output pattern.",
+            "A date written in a calendar. The calendar is an Address or its shortcode; left " +
+            "out, it is the note's own calendar — its `data.calendar`, else its culture's, " +
+            "else for a place its parents', else the configured `defaultCalendar` — and a " +
+            "note with none prints the date as written. The date is the value a note " +
+            "carries, and the optional last argument names an output pattern.",
         make:
-            ({ dates }) =>
-            (calendar, authored, formatOrOptions) => {
+            ({ dates, fm }) =>
+            (...args) => {
+                const { calendar, authored, format } = dateformatArguments(
+                    args.slice(0, -1),
+                    dates,
+                );
                 if (
-                    !(typeof calendar === "string" || isAddressTuple(calendar)) ||
-                    !["string", "number"].includes(typeof authored)
+                    !(
+                        calendar === undefined ||
+                        typeof calendar === "string" ||
+                        isAddressTuple(calendar)
+                    ) ||
+                    !["string", "number"].includes(typeof authored) ||
+                    !(format === undefined || typeof format === "string")
                 )
-                    throw new TypeError("dateformat needs a calendar Address and a date");
+                    throw new TypeError("dateformat needs a date, and takes a calendar Address");
                 const parsed = parseNoteDate(authored, { ...dates, allowUnknown: false });
                 const error = parsed.findings.find((item) => item.severity === "error");
                 if (error || !parsed.date)
                     throw new RangeError(error?.message ?? "date does not resolve");
-                const printable = formatDateInCalendar(
-                    parsed.date,
-                    isAddressTuple(calendar) ? renderAddress(calendar) : calendar,
-                    dates,
-                    typeof formatOrOptions === "string" ? formatOrOptions : undefined,
-                );
+                const reference =
+                    calendar === undefined ? noteCalendar(fm, dates)
+                    : isAddressTuple(calendar) ? renderAddress(calendar)
+                    : calendar;
+                if (reference === undefined) return printEventDate(authored, parsed.date, dates);
+                const printable = formatDateInCalendar(parsed.date, reference, dates, format);
                 if (!printable)
-                    throw new RangeError(`date cannot be printed in calendar ${calendar}`);
+                    throw new RangeError(`date cannot be printed in calendar ${reference}`);
                 return printable.prose ?? printable.text;
             },
     }),

package/engine/markup-validation.mjs

@@ -13,6 +13,7 @@
 
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
+import { scanRuns } from "./content-scripts.mjs";
 
 /**
  * Validate authored block syntax with positions in the original file.
@@ -20,20 +21,33 @@ import { scanAlerts } from "./content-alerts.mjs";
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
  * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
- * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
+ *   languages, faces and maps. Given, text marked with `lang=`, `font=` and
+ *   `map=` is checked against them; a caller with no package configuration
+ *   leaves it out.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors,
+ *   then warnings.
  */
-export function markupFindings(source, file, syntax) {
+export function markupFindings(source, file, syntax, runs) {
     const body = String(source ?? "").replace(
         /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
         (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
     );
     const scanned = syntax?.(body);
-    return [
+    const marked = runs ? scanRuns(body, runs, syntax) : undefined;
+    const errors = [
         ...(scanned?.blocks ?? scanBlocks(body)).errors,
         ...(scanned?.alerts ?? scanAlerts(body)).errors,
+        ...(marked?.errors ?? []),
     ].map((error) => ({
         file,
         ...error,
         severity: "error",
     }));
+    const warnings = (marked?.warnings ?? []).map((warning) => ({
+        file,
+        ...warning,
+        severity: "warning",
+    }));
+    return [...errors, ...warnings];
 }

package/engine/names.mjs

@@ -19,8 +19,8 @@ import { formatLocator } from "./diagnostics.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { WORD } from "./word-pattern.mjs";
 
-const WORD = /[\p{L}\p{M}\p{N}]+(?:[’'–-][\p{L}\p{M}\p{N}]+)*/gu;
 const compare = (a, b) =>
     a < b ? -1
     : a > b ? 1

package/engine/note-calendars.mjs

@@ -0,0 +1,314 @@
+/*
+ * 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
+ */
+
+/**
+ * **The calendar a note's dates print in.** A note's calendar is the first of:
+ *
+ * 1. its own `data.calendar`, on any type;
+ * 2. its culture's calendar: the culture note its `data.culture` names,
+ *    resolved by these same rules;
+ * 3. for a `place`, its `data.parents`, each resolved by these same rules. Two
+ *    or more distinct calendars among them are an error at the place's
+ *    `data.parents`, fixed by stating `data.calendar` on the place;
+ * 4. the package's configured `defaultCalendar`;
+ * 5. otherwise none, and a date prints as it was written.
+ *
+ * Steps 2 and 3 take only a calendar some note states: a culture or parent
+ * that itself falls through to the default contributes nothing, so parents
+ * that all fall through give the default and raise no error. A note met again
+ * while it is being resolved — a cycle through `data.parents` or
+ * `data.culture` — contributes nothing either, and the chain goes on to the
+ * default.
+ *
+ * The content index writes the result onto each note record as
+ * `resolvedCalendar`, the calendar note's Address, and
+ * every reader of a note's calendar reads it from there: the event views, the
+ * `dateformat` helper and the infobox's dates.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { canonicalKey, isAddressTuple, readCanonicalKey, renderAddress } from "./address.mjs";
+import { isAddressSegment } from "./address-charset.mjs";
+import { AddressLink } from "./address-values.mjs";
+import { formatDiagnostic, positionOfFrontmatterPath, positionOfYamlPath } from "./diagnostics.mjs";
+import { isNoteRecord, noteFile } from "./index-records.mjs";
+import { noteCalendarKey } from "./reckoning-markers.mjs";
+import { NOTE_SYSTEM } from "./systems.mjs";
+
+/** The configuration key naming the calendar of last resort. */
+export const DEFAULT_CALENDAR_KEY = "defaultCalendar";
+
+/**
+ * The canonical key an Address names, without any anchor.
+ *
+ * @param {unknown} value - A tuple, an {@link AddressLink}, or anything else.
+ * @returns {string|undefined} The key, or `undefined` for anything else.
+ */
+function addressKey(value) {
+    const tuple = value instanceof AddressLink ? value.target : value;
+    return isAddressTuple(tuple) ? renderAddress(tuple) : undefined;
+}
+
+/**
+ * Whether a record is a calendar note.
+ *
+ * @param {Record<string, any>|undefined} record - An index record.
+ * @returns {boolean} Whether it is a `lore` note with `subType: calendar`.
+ */
+function isCalendarNote(record) {
+    return record?.type === "lore" && String(record.subType ?? "").toLowerCase() === "calendar";
+}
+
+/**
+ * The canonical key of the calendar `defaultCalendar` names, or why it names none.
+ *
+ * @param {unknown} shortcode - The configured value.
+ * @param {string} contentPackage - The package the shortcode is read in.
+ * @param {(key: string) => Record<string, any>|undefined} recordOf - A local
+ *   note by canonical key.
+ * @returns {{key?: string, problem?: string}} The calendar, or the problem.
+ */
+function defaultCalendarKey(shortcode, contentPackage, recordOf) {
+    if (shortcode === undefined || shortcode === null) return {};
+    const named = String(shortcode);
+    const key =
+        isAddressSegment(named) ?
+            canonicalKey(contentPackage, NOTE_SYSTEM, "lore", named)
+        :   undefined;
+    if (key && isCalendarNote(recordOf(key))) return { key };
+    return {
+        problem:
+            `${DEFAULT_CALENDAR_KEY} ${named} names no calendar note in ${contentPackage}; ` +
+            `name the shortcode of a lore note with subType: calendar`,
+    };
+}
+
+/**
+ * Write each note's resolved calendar into its record, as `resolvedCalendar`.
+ *
+ * Reads each note's authored `data.calendar`, `data.culture` and
+ * `data.parents`, so it runs before the index writes a resolved culture over
+ * `data.culture`. A culture or parent in another package contributes the
+ * calendar its published entry states in `data.calendar`, and nothing else.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {string} [options.defaultCalendar] - The configured calendar of last
+ *   resort, a calendar note's shortcode.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
+ * @param {string} [options.contentBase] - The content tree, for opening a note
+ *   to locate a finding.
+ * @param {(key: string) => Record<string, any>|undefined} [options.foreignRecord] -
+ *   Another package's entry for a canonical address.
+ * @param {object[]} [options.problems] - Receives each finding. Omitted, the
+ *   findings are collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and anything is reported.
+ */
+export function resolveNoteCalendars(
+    records,
+    { contentPackage, defaultCalendar, configFile, contentBase, foreignRecord, problems, parsed },
+) {
+    const notes = new Map();
+    for (const record of records) {
+        if (!isNoteRecord(record) || !isAddressSegment(String(record.shortcode ?? ""))) continue;
+        const key = canonicalKey(contentPackage, NOTE_SYSTEM, record.type, record.shortcode);
+        if (!notes.has(key)) notes.set(key, record);
+    }
+    const findings = [];
+
+    const fallback = defaultCalendarKey(defaultCalendar, contentPackage, (key) => notes.get(key));
+    if (fallback.problem) {
+        const file = configFile ?? "package-build.config.yaml";
+        const source =
+            configFile && /\.ya?ml$/.test(configFile) && fs.existsSync(configFile) ?
+                fs.readFileSync(configFile, "utf8")
+            :   undefined;
+        findings.push({
+            file,
+            ...(source ? positionOfYamlPath(source, [DEFAULT_CALENDAR_KEY], { key: true }) : {}),
+            severity: "error",
+            message: fallback.problem,
+        });
+    }
+
+    const memo = new Map();
+    const inProgress = new Set();
+
+    /**
+     * The calendar some note states for a source Address, local or foreign.
+     *
+     * @param {unknown} value - A `data.culture` or `data.parents` Address.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const statedThrough = (value) => {
+        const key = addressKey(value);
+        if (!key) return undefined;
+        const tuple = value instanceof AddressLink ? value.target : value;
+        if (tuple.package === contentPackage) {
+            const record = notes.get(
+                canonicalKey(contentPackage, NOTE_SYSTEM, tuple.type, tuple.shortcode),
+            );
+            return record ? resolve(record) : undefined;
+        }
+        return addressKey(foreignRecord?.(key)?.data?.calendar);
+    };
+
+    /**
+     * Report parents that disagree.
+     *
+     * @param {Record<string, any>} record - The place.
+     * @param {Array<{key: string, via: unknown}>} distinct - The calendars and
+     *   the parent each came through.
+     */
+    const conflict = (record, distinct) => {
+        const file = contentBase ? noteFile(contentBase, record) : record.file?.path;
+        const raw =
+            parsed?.get(file)?.raw ??
+            (contentBase && fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined);
+        let position = positionOfFrontmatterPath(raw, ["data", "parents"], { key: true });
+        if (position.line === undefined)
+            position = positionOfFrontmatterPath(raw, ["data"], { key: true });
+        const via = (value) => {
+            const tuple = value instanceof AddressLink ? value.target : value;
+            return tuple.package === contentPackage ? tuple.shortcode : addressKey(tuple);
+        };
+        const named = distinct.map(({ key, via: source }) => `${key} via ${via(source)}`);
+        findings.push({
+            file,
+            ...position,
+            severity: "error",
+            message:
+                `place ${record.shortcode}: data.parents resolve to different calendars ` +
+                `(${named.join(", ")}); state data.calendar`,
+        });
+    };
+
+    /**
+     * The calendar a note states through its own field, its culture or — for a
+     * place — its parents, ignoring the default.
+     *
+     * @param {Record<string, any>} record - The note.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const resolveRecord = (record) => {
+        const own = addressKey(record.data?.calendar);
+        if (own) return own;
+        const culture = statedThrough(record.data?.culture);
+        if (culture) return culture;
+        if (record.type !== "place") return undefined;
+        const parents = Array.isArray(record.data?.parents) ? record.data.parents : [];
+        const distinct = new Map();
+        for (const parent of parents) {
+            const calendar = statedThrough(parent);
+            if (calendar && !distinct.has(calendar)) distinct.set(calendar, parent);
+        }
+        if (distinct.size > 1) {
+            conflict(
+                record,
+                [...distinct].map(([key, via]) => ({ key, via })),
+            );
+            return undefined;
+        }
+        return distinct.keys().next().value;
+    };
+
+    /**
+     * A local note's stated calendar, memoised; a note already being resolved
+     * is a cycle and states nothing.
+     *
+     * @param {Record<string, any>} record - The note.
+     * @returns {string|undefined} The calendar's canonical key.
+     */
+    const resolve = (record) => {
+        if (memo.has(record)) return memo.get(record);
+        if (inProgress.has(record)) return undefined;
+        inProgress.add(record);
+        const result = resolveRecord(record);
+        inProgress.delete(record);
+        memo.set(record, result);
+        return result;
+    };
+
+    // Walked in address order, so which note of a cycle is met first is a fact
+    // about the content rather than about directory-read order.
+    const calendars = new Map();
+    for (const key of [...notes.keys()].sort())
+        calendars.set(key, resolve(notes.get(key)) ?? fallback.key);
+    // A note's second record — an item's documentation journal — is the same
+    // note, and reads in the same calendar.
+    for (const record of records) {
+        if (!isNoteRecord(record) || !isAddressSegment(String(record.shortcode ?? ""))) continue;
+        const calendar = calendars.get(
+            canonicalKey(contentPackage, NOTE_SYSTEM, record.type, record.shortcode),
+        );
+        if (calendar) record.resolvedCalendar = readCanonicalKey(calendar);
+        else delete record.resolvedCalendar;
+    }
+
+    findings.sort(
+        (a, b) =>
+            String(a.file).localeCompare(String(b.file), "en") ||
+            (a.line ?? 0) - (b.line ?? 0) ||
+            (a.column ?? 0) - (b.column ?? 0),
+    );
+    if (problems) problems.push(...findings);
+    else if (findings.length)
+        throw Object.assign(new Error(findings.map(formatDiagnostic).join("\n")), {
+            located: true,
+        });
+    return records;
+}
+
+/**
+ * The configuration file in a package root, where a configured value is
+ * reported.
+ *
+ * @param {string|undefined} rootDir - The package root.
+ * @param {readonly string[]} names - The file names a configuration may take.
+ * @returns {string|undefined} The first that exists.
+ */
+export function configFileIn(rootDir, names) {
+    if (!rootDir) return undefined;
+    for (const name of names) {
+        const file = path.join(rootDir, name);
+        if (fs.existsSync(file)) return file;
+    }
+    return undefined;
+}
+
+/**
+ * The calendar a note's dates print in: the one the content index resolved for
+ * it, where the reckoning context carries it, else the note's own
+ * `data.calendar`.
+ *
+ * @param {object|undefined} fm - The note's frontmatter.
+ * @param {{noteCalendars?: Map<string, string>}} [dates] - The reckoning context.
+ * @returns {string|undefined} The calendar's Address or shortcode.
+ */
+export function noteCalendar(fm, dates) {
+    const key = noteCalendarKey(fm);
+    const resolved = key ? dates?.noteCalendars?.get(key) : undefined;
+    if (resolved) return resolved;
+    const own = fm?.data?.calendar;
+    if (own === undefined || own === null || own === "") return undefined;
+    return addressKey(own) ?? String(own);
+}

package/engine/note-vocabulary.mjs

@@ -153,6 +153,7 @@ import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkSettlementTables } from "./settlement-tables.mjs";
+import { checkMapField } from "./text-maps.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -1030,6 +1031,17 @@ export const SHARED_DATA_FIELDS = Object.freeze([
         describe:
             "Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.",
     }),
+    Object.freeze({
+        name: "calendar",
+        ...LINK,
+        ref: "lore",
+        accepts: Object.freeze(["lore"]),
+        check: checkCalendarChoice,
+        describe:
+            "The calendar this note's dates print in, as a calendar lore note. Absent, the " +
+            "note takes its culture's calendar, then — for a place — its parents', then the " +
+            "configured `defaultCalendar`.",
+    }),
     Object.freeze({
         name: "id",
         ...TEXT,
@@ -1503,6 +1515,47 @@ export const BEING_ARCHETYPES = Object.freeze({
     guildsperson: "Has professional training, standing, or connections that open doors.",
 });
 
+/**
+ * One row of a mapping note's `data.map.rows` or of a face's own `rows`.
+ *
+ * @type {object}
+ */
+const MAP_ROW_ENTRY = Object.freeze({
+    kind: "list-or-map",
+    shape: "`[from, to]` or `{ from, to, before?, at? }`",
+    entries: Object.freeze({ ...TEXT, shape: "a string" }),
+    fields: Object.freeze([
+        {
+            name: "from",
+            ...TEXT,
+            shape: "a string of one or more characters",
+            required: true,
+            describe: "The one or more characters the row matches.",
+        },
+        {
+            name: "to",
+            ...TEXT,
+            shape: "a string, which may be empty",
+            required: true,
+            allowEmpty: true,
+            describe: "What the row writes in their place; empty to drop them.",
+        },
+        {
+            name: "before",
+            ...TEXT,
+            allowed: Object.freeze(["vowel", "consonant"]),
+            describe:
+                "`vowel` or `consonant`: what must follow the match for the " + "row to apply.",
+        },
+        {
+            name: "at",
+            ...TEXT,
+            allowed: Object.freeze(["start", "end"]),
+            describe: "`start` or `end`: where the match must sit for the row to " + "apply.",
+        },
+    ]),
+});
+
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.
@@ -1596,14 +1649,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "When the being was born — a date, or `unknown` where the birth is " +
                     "unrecorded. Absent, the being was never born.",
             },
-            {
-                name: "calendar",
-                ...LINK,
-                ref: "lore",
-                accepts: ["lore"],
-                check: checkCalendarChoice,
-                describe: "Calendar that displays this being's dates.",
-            },
             {
                 name: "died",
                 ...TEXT,
@@ -2145,6 +2190,77 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "The culture a setting guide introduces, as a culture lore note. " +
                     "Required on `settingguide`; no other subType states it.",
             },
+            {
+                name: "map",
+                kind: "map",
+                shape: "a map — `{ name, vowels?, fonts, rows }`",
+                check: checkMapField,
+                fields: Object.freeze([
+                    {
+                        name: "name",
+                        ...TEXT,
+                        required: true,
+                        describe:
+                            "What `map=` names the map by: lowercase letters, digits and `-`, " +
+                            "unique in the package.",
+                    },
+                    {
+                        name: "vowels",
+                        ...TEXT,
+                        describe:
+                            "The characters a row's `before: vowel` reads as vowels; any other " +
+                            "letter is a consonant.",
+                    },
+                    {
+                        name: "rows",
+                        kind: "list",
+                        shape: "list of `[from, to]` or `{ from, to, before?, at? }`",
+                        required: true,
+                        entries: MAP_ROW_ENTRY,
+                        describe:
+                            "The rewrites, each `[from, to]` or `{ from, to, before?, at? }`: " +
+                            "`before` is `vowel` or `consonant`, `at` is `start` or `end`. The " +
+                            "longest `from` wins, and a character no row matches passes through.",
+                    },
+                    {
+                        name: "fonts",
+                        kind: "list",
+                        shape: "list of `{ font, rows? }`",
+                        required: true,
+                        entries: Object.freeze({
+                            kind: "map",
+                            shape: "a map — `{ font, rows? }`",
+                            fields: Object.freeze([
+                                {
+                                    name: "font",
+                                    ...TEXT,
+                                    required: true,
+                                    shape: "an installed face's slug",
+                                    describe:
+                                        "A face the map is drawn in, by the slug `font=` names it by.",
+                                },
+                                {
+                                    name: "rows",
+                                    kind: "list",
+                                    shape: "list of `[from, to]` or `{ from, to, before?, at? }`",
+                                    entries: MAP_ROW_ENTRY,
+                                    describe:
+                                        "Rows for this face alone, tried before the shared `rows`; " +
+                                        "the same shapes and conditions.",
+                                },
+                            ]),
+                        }),
+                        describe:
+                            "The faces the map is drawn in, at least one, each with any rows of " +
+                            "its own. A run in another face is refused, and each face must draw " +
+                            "every character its rows and the lexicon's native forms write.",
+                    },
+                ]),
+                describe:
+                    "A mapping, which text marked `map=` with its `name` is rewritten by " +
+                    "before it is set. See " +
+                    "[mapping notes](format-details.md#mapping-notes).",
+            },
         ]),
     }),
 
@@ -2281,14 +2397,6 @@ export const NOTE_VOCABULARY = Object.freeze({
         check: checkPlace,
         data: Object.freeze([
             EVENTS_FIELD,
-            {
-                name: "calendar",
-                ...LINK,
-                ref: "lore",
-                accepts: ["lore"],
-                check: checkCalendarChoice,
-                describe: "Calendar that displays this place's dates.",
-            },
             {
                 name: "demonym",
                 ...TEXT,