@heroiclands/package-build 23.12.4 → 23.12.6

package/engine/reckoning-markers.mjs

@@ -209,13 +209,69 @@ export function resolveReckoningMarkers(index, daysPerYear) {
     return { eras, markers, findings };
 }
 
+/**
+ * The key a note's resolved calendar is filed under: its type and shortcode.
+ *
+ * @param {object|undefined} fm - A note's frontmatter or record.
+ * @returns {string|undefined} The key.
+ */
+export function noteCalendarKey(fm) {
+    return fm?.type && fm?.shortcode ? `${fm.type}\u0000${fm.shortcode}` : undefined;
+}
+
+/**
+ * A record's `resolvedCalendar` as its canonical Address string: an Address
+ * tuple, as a record in memory carries it, or the string an encoded record
+ * carries.
+ *
+ * @param {unknown} value - The value.
+ * @returns {string|undefined} The Address, or `undefined` for none.
+ */
+export function calendarAddress(value) {
+    if (typeof value === "string") return value || undefined;
+    return value && typeof value === "object" && "shortcode" in value ?
+            renderAddress(/** @type {any} */ (value))
+        :   undefined;
+}
+
+/**
+ * Each note's resolved calendar, by {@link noteCalendarKey}, from the
+ * `resolvedCalendar` the content index writes on a record.
+ *
+ * @param {Iterable<object>|undefined} notes - Index records, or
+ *   `{ fm, resolvedCalendar }` entries.
+ * @returns {Map<string, string>} Note key to the calendar's canonical Address.
+ */
+export function noteCalendarMap(notes) {
+    const out = new Map();
+    for (const note of notes ?? []) {
+        const calendar = calendarAddress(note?.resolvedCalendar);
+        if (!calendar) continue;
+        const key = noteCalendarKey(note?.fm ?? note?.frontmatter ?? note);
+        if (key && !out.has(key)) out.set(key, calendar);
+    }
+    return out;
+}
+
 /** One resolved date context per corpus index. */
 const contexts = new WeakMap();
 
-/** Read the world's year length and resolve every calendar era in one corpus. */
+/**
+ * Read the world's year length and resolve every calendar era in one corpus.
+ *
+ * The context also carries `noteCalendars`, each note's resolved calendar by
+ * note, read from the `resolvedCalendar` the content index writes on a record;
+ * {@link module:engine/note-calendars.noteCalendar} reads it.
+ */
 export function reckoningContext(index) {
     if (!index || typeof index !== "object")
-        return { eras: new Map(), markers: new Map(), daysPerYear: undefined, findings: [] };
+        return {
+            eras: new Map(),
+            markers: new Map(),
+            daysPerYear: undefined,
+            findings: [],
+            noteCalendars: new Map(),
+        };
     const cached = contexts.get(index);
     if (cached) return cached;
     const world = (index.notes ?? []).find((note) => {
@@ -224,7 +280,11 @@ export function reckoningContext(index) {
     });
     const fm = world?.fm ?? world?.frontmatter ?? world;
     const daysPerYear = fm?.data?.year?.days;
-    const context = { ...resolveReckoningMarkers(index, daysPerYear), daysPerYear };
+    const context = {
+        ...resolveReckoningMarkers(index, daysPerYear),
+        daysPerYear,
+        noteCalendars: noteCalendarMap(index.notes),
+    };
     contexts.set(index, context);
     return context;
 }

package/engine/related-pages.mjs

@@ -49,6 +49,8 @@ import { homepageAddresses } from "./homepage.mjs";
  *                          site-root-relative form the page states for itself.
  * @property {string} [gloss] Why the author recommends this page.
  * @property {string} type  The note's `type`, which the theme groups by.
+ * @property {string} [sort] The note's `name.sort`. It orders the list in place
+ *                          of `title` and is not published.
  */
 
 /**
@@ -73,7 +75,10 @@ import { homepageAddresses } from "./homepage.mjs";
  * @returns {number}
  */
 function byTypeThenTitle(a, b) {
-    return a.type.localeCompare(b.type, "en") || a.title.localeCompare(b.title, "en");
+    return (
+        a.type.localeCompare(b.type, "en") ||
+        (a.sort ?? a.title).localeCompare(b.sort ?? b.title, "en")
+    );
 }
 
 /**
@@ -118,7 +123,12 @@ export function relatedPages(edges, entries, deliberate = new Map()) {
     const list = (urls) =>
         [...urls]
             .map((url) => /** @type {RelatedEntry} */ (entries.get(url)))
-            .sort(byTypeThenTitle);
+            .sort(byTypeThenTitle)
+            .map((entry) => {
+                if (entry.sort === undefined) return entry;
+                const { sort, ...published } = entry;
+                return published;
+            });
 
     const out = new Map();
     for (const [url, { backlinks, mentions }] of graph) {

package/engine/site-build.mjs

@@ -1069,6 +1069,9 @@ export function renderPages(pages, options) {
             title: pageTitle(page),
             url: page.url,
             type: String(page.fm.type),
+            ...(typeof page.fm.name?.sort === "string" && page.fm.name.sort ?
+                { sort: page.fm.name.sort }
+            :   {}),
         });
     }
     for (const home of homepages) {

package/engine/sql-tables.mjs

@@ -31,7 +31,8 @@ import { collectAnchors } from "./anchors.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
-import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
+import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventCalendars, eventRows } from "./event-rows.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
 import {
     GLOSSARY_COLUMNS,
@@ -66,6 +67,7 @@ import { parseMarkdownFile } from "./helpers.mjs";
 import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
 import { authoredFrontmatter, isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
+import { nameSortOf } from "./name-sort.mjs";
 
 /** Rendered in a cell whose value is absent. */
 const EMPTY_CELL = "—";
@@ -438,11 +440,25 @@ export async function openNotesDatabase(
  */
 const WITH_STUBS_SCHEMA = "__with_stubs";
 
+/**
+ * The record with its `nameSort` stated: the declared `name.sort`, otherwise
+ * `name.full`. A record with no name has none.
+ *
+ * @param {object} record - An index record.
+ * @returns {object} The record, with `nameSort` where it has a name.
+ */
+function withNameSort(record) {
+    const key = nameSortOf(record);
+    return key === undefined ? record : { ...record, nameSort: key };
+}
+
 /**
  * Create the two relations an index is read through, and the ladder one of them
  * derives.
  *
- * **`entries` is every row**, stubs included, plus a derived `state` column:
+ * **`entries` is every row**, stubs included, plus a derived `nameSort` column
+ * (the note's `name.sort`, otherwise its `name.full`) and a derived `state`
+ * column:
  *
  * ```text
  * address IS NULL                 → stub
@@ -484,7 +500,7 @@ async function createRelations(connection, file, records, prefix = "", audience
         records
             .map((record) =>
                 JSON.stringify({
-                    record: sortKeysDeep(record),
+                    record: sortKeysDeep(withNameSort(record)),
                     visible: audience !== "public" || !isGmNote(record),
                 }),
             )
@@ -535,9 +551,8 @@ async function createRelations(connection, file, records, prefix = "", audience
  * @returns {Promise<void>}
  */
 async function createEventRelation(connection, file, records, prefix, audience) {
-    const rows = eventRows(
-        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
-    );
+    const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
+    const rows = eventRows(visible, reckoningContext({ notes: records }), eventCalendars(records));
     if (!rows.length) {
         const columns = EVENT_COLUMNS.map((column) => {
             const type = EVENT_SORT_COLUMNS.includes(column) ? "DOUBLE" : "VARCHAR";
@@ -549,7 +564,13 @@ async function createEventRelation(connection, file, records, prefix, audience)
         return;
     }
     fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n"));
-    await createTableFromFile(connection, `${prefix}events`, readJsonAuto(file));
+    // `whenIn` and `untilIn` are keyed by calendar Address, and read as structs
+    // whatever their number of keys, so `whenIn['<calendar>']` always binds.
+    await createTableFromFile(
+        connection,
+        `${prefix}events`,
+        readJsonAuto(file).replace(/\)$/, ", map_inference_threshold=-1)"),
+    );
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.4",
+    "version": "23.12.6",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -637,6 +637,13 @@ export type ContentBuildConfigInput = {
      * Setting-wide neutral current date; defaults to "720.1".
      */
     currentDate?: string | undefined;
+    /**
+     * Shortcode of the `lore` note with
+     *      `subType: calendar` that prints the
+     *      dates of a note no other rule gives a
+     *      calendar.
+     */
+    defaultCalendar?: string | undefined;
     /**
      * Content package name — the address
      * namespace every note in this
@@ -761,6 +768,11 @@ export type ContentBuildConfig = {
      * Setting-wide neutral current date.
      */
     currentDate: string;
+    /**
+     * The calendar of last resort's
+     * shortcode, `null` when none is named.
+     */
+    defaultCalendar: string | null;
     rootDir: string;
     contentPackage: string;
     /**

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

@@ -31,36 +31,6 @@ export function noteAddress(frontmatter: Record<string, any>, contentPackage: st
     slug: string;
     canonical: string;
 } | null;
-/**
- * A note's display name reduced to printable 7-bit ASCII.
- *
- * Content names carry the setting's orthography — `Kûrbúl Helm`, `Hârn`,
- * `Kèthîra` — and nobody types them. A reader searching the index, or an editor
- * completing a wikilink, needs a form that matches what a keyboard produces, so
- * the record states one rather than leaving every consumer to invent it (and to
- * invent a *different* one, which is how two searches over the same data come
- * to disagree).
- *
- * **Transliterated, not stripped.** `unidecode` — the same table
- * {@link slugify} already runs, so an ASCII name and a slug can never disagree
- * about a character — carries a letter across rather than deleting it:
- * diacritics fold (`â`→`a`, `è`→`e`), ligatures expand (`æ`→`ae`, `Œ`→`OE`,
- * `ß`→`ss`), the runic letters spell out (`þ`→`th`, `Þ`→`Th`, `ð`→`d`), and
- * even a vulgar fraction becomes readable (`¾`→`3/4`). Deleting them instead
- * would collapse `Kûrbúl` to `Krbl`, which is worse than the original.
- *
- * Anything still outside printable ASCII after that becomes a space, and runs
- * of whitespace collapse — a space rather than nothing, so a character that
- * transliterates away cannot silently weld two words together.
- *
- * The value is emitted even when it equals the name, so a consumer matching on
- * it never has to branch on whether the name happened to be ASCII already.
- *
- * @param {unknown} name - The note's `name.full`.
- * @returns {string|null} The ASCII form, or `null` when there is no name, or
- *   nothing printable survives.
- */
-export function asciiName(name: unknown): string | null;
 /**
  * A note's `name.aliases` reduced to printable 7-bit ASCII, in order.
  *
@@ -235,6 +205,10 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  *   reader receives each as a finding, and the emitter throws once, listing
  *   every one.
  * @param {string} [options.currentDate="720.1"] - Setting-wide neutral current date.
+ * @param {string} [options.defaultCalendar] - The calendar of last resort, a
+ *   calendar note's shortcode; see {@link module:engine/note-calendars}.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
@@ -247,7 +221,7 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, currentDate, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -255,6 +229,8 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
     addressContext?: object | undefined;
     problems?: object[] | undefined;
     currentDate?: string | undefined;
+    defaultCalendar?: string | undefined;
+    configFile?: string | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;
@@ -449,6 +425,7 @@ export type PreparedContentIndex = {
      */
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 };
+import { asciiName } from "./name-sort.mjs";
 import { collectAnchors } from "./anchors.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
 import { DERIVED_KEYS } from "./index-records.mjs";
@@ -458,4 +435,4 @@ import { isStub } from "./index-records.mjs";
 import { noteFile } from "./index-records.mjs";
 import { recordPath } from "./index-records.mjs";
 import { sortKeysDeep } from "./index-records.mjs";
-export { collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };
+export { asciiName, collectAnchors, authoredFrontmatter, DERIVED_KEYS, isAssetRecord, isNoteRecord, isStub, noteFile, recordPath, sortKeysDeep };

package/types/engine/event-fields.d.mts

@@ -46,6 +46,17 @@ export function eventNoteIndex(records: Iterable<Record<string, any>>, { content
  * @returns {string} The printed date.
  */
 export function printEventDate(written: unknown, date: object | null, dates?: object): string;
+/**
+ * A date as `dateformat` prints it in a calendar, where one is named and
+ * prints it; otherwise as {@link printEventDate} prints it.
+ *
+ * @param {unknown} written - The date as the event writes it.
+ * @param {object|null} date - The resolved date.
+ * @param {object} [dates] - The reckoning context.
+ * @param {string} [calendar] - The calendar's Address or shortcode.
+ * @returns {string} The printed date; the authored text when nothing resolves.
+ */
+export function printEventDateIn(written: unknown, date: object | null, dates?: object, calendar?: string): string;
 /**
  * One field of one event, as the text a reference prints, or why it cannot.
  *

package/types/engine/event-rows.d.mts

@@ -1,12 +1,30 @@
+/**
+ * Every calendar a set of records can print an event's date in: each calendar
+ * note's canonical Address, and every calendar a note resolves to.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string.
+ * @returns {string[]} The calendars, sorted.
+ */
+export function eventCalendars(records: Iterable<Record<string, any>>): string[];
 /**
  * The `events` rows of a set of index records.
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
+ * @param {object} [dates] - The reckoning context the dates are printed in.
+ * @param {readonly string[]} [calendars] - The calendars `whenIn` and
+ *   `untilIn` are keyed by: {@link eventCalendars} of every record of the
+ *   corpus, whatever the audience, so every surface's relation has the same
+ *   keys. Absent, those of `records`.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records: Iterable<Record<string, any>>): object[];
+export function eventRows(records: Iterable<Record<string, any>>, dates?: object, calendars?: readonly string[]): object[];
 /** The sort keys a row carries, after the event's own keys. */
 export const EVENT_SORT_COLUMNS: readonly string[];
+/** The printed dates a row carries, after the sort keys. */
+export const EVENT_TEXT_COLUMNS: readonly string[];
+/** The dates a row carries in every calendar, after the printed ones. */
+export const EVENT_CALENDAR_COLUMNS: readonly string[];
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS: any;

package/types/engine/event-views.d.mts

@@ -34,18 +34,23 @@ export function eventViewSections(db: object, records: Iterable<object>, fileOf:
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null,
- *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
+ *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean, calendar?: string}) => {fence: string, own?: string}|null,
+ *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>,
+ *   felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
 export const EVENT_VIEWS: ReadonlyArray<Readonly<{
     slug: string;
     heading: string;
     applies: (record: object) => boolean;
-    query: (self: string[], shape: CorpusShape) => {
+    query: (self: string[], shape: CorpusShape, columns?: {
+        felt?: boolean;
+        calendar?: string;
+    }) => {
         fence: string;
         own?: string;
     } | null;
     owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>;
+    felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>;
 }>>;
 export type CorpusShape = {
     /**

package/types/engine/generated-sections.d.mts

@@ -110,6 +110,12 @@ export function splitGenerated(markdown: string): {
  *
  * @module
  */
+/**
+ * The anchor of the Chronology section, which the book sets across the page.
+ *
+ * @type {string}
+ */
+export const CHRONOLOGY_SLUG: string;
 /**
  * Every generated section, in the order it follows the author's text: where a
  * place sits and who governs it, then what happened, then what was written

package/types/engine/holdings.d.mts

@@ -1,10 +1,11 @@
-/** @typedef {{title:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
+/** @typedef {{title:string,sort?:string,url?:string,address:string,type:string,subType?:string}} HoldingsEntry */
 /**
  * @typedef {object} HoldingsNode
  * @property {string} shortcode
  * @property {"place"|"affiliation"} type
  * @property {string} [subType]
  * @property {string} title
+ * @property {string} [sort] The note's `name.sort`; the list files by it in place of `title`.
  * @property {string} [url]
  * @property {string} [package] Owning content package.
  * @property {string} [system] Own document system.
@@ -60,6 +61,7 @@ export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { government
 export function checkGovernment(note: object): object[];
 export type HoldingsEntry = {
     title: string;
+    sort?: string;
     url?: string;
     address: string;
     type: string;
@@ -70,6 +72,10 @@ export type HoldingsNode = {
     type: "place" | "affiliation";
     subType?: string | undefined;
     title: string;
+    /**
+     * The note's `name.sort`; the list files by it in place of `title`.
+     */
+    sort?: string | undefined;
     url?: string | undefined;
     /**
      * Owning content package.

package/types/engine/infobox.d.mts

@@ -94,6 +94,17 @@ export function hasRenderableValue(kind: string, value: unknown): boolean;
  * @returns {string} One of {@link INFOBOX_VALUE_KINDS}.
  */
 export function valueKindOf(field: object, value: unknown): string;
+/**
+ * A number as a reader reads it in a profile: under a million in full with
+ * thousands separators (`850`, `12,500`), and from a million up in words with
+ * at most one decimal (`11 million`, `1.2 million`, `3 billion`). Every figure
+ * the setting gives at that scale is an estimate, and the words say so.
+ * Decimals below a million keep the digits they were written with.
+ *
+ * @param {number} value - The number.
+ * @returns {string} The text the row shows.
+ */
+export function formatQuantity(value: number): string;
 /**
  * One row, with its unit on it.
  *

package/types/engine/literature-works.d.mts

@@ -38,6 +38,7 @@ export function worksPages(nodes: Iterable<WorksNode | null>, { types }: {
 }>;
 export type WorkEntry = {
     title: string;
+    sort?: string;
     url?: string;
     address: string;
     form?: string;
@@ -48,6 +49,10 @@ export type WorksNode = {
      */
     key: string;
     title: string;
+    /**
+     * The note's `name.sort`; the list files by it in place of `title`.
+     */
+    sort?: string | undefined;
     /**
      * Absent for a note that publishes no page.
      */

package/types/engine/name-sort.d.mts

@@ -0,0 +1,49 @@
+/**
+ * A note's display name reduced to printable 7-bit ASCII.
+ *
+ * Content names carry the setting's orthography — `Kûrbúl Helm`, `Hârn`,
+ * `Kèthîra` — and nobody types them. A reader searching the index, or an editor
+ * completing a wikilink, needs a form that matches what a keyboard produces, so
+ * the record states one rather than leaving every consumer to invent it (and to
+ * invent a *different* one, which is how two searches over the same data come
+ * to disagree).
+ *
+ * **Transliterated, not stripped.** `unidecode` — the same table
+ * {@link slugify} already runs, so an ASCII name and a slug can never disagree
+ * about a character — carries a letter across rather than deleting it:
+ * diacritics fold (`â`→`a`, `è`→`e`), ligatures expand (`æ`→`ae`, `Œ`→`OE`,
+ * `ß`→`ss`), the runic letters spell out (`þ`→`th`, `Þ`→`Th`, `ð`→`d`), and
+ * even a vulgar fraction becomes readable (`¾`→`3/4`). Deleting them instead
+ * would collapse `Kûrbúl` to `Krbl`, which is worse than the original.
+ *
+ * Anything still outside printable ASCII after that becomes a space, and runs
+ * of whitespace collapse — a space rather than nothing, so a character that
+ * transliterates away cannot silently weld two words together.
+ *
+ * The value is emitted even when it equals the name, so a consumer matching on
+ * it never has to branch on whether the name happened to be ASCII already.
+ *
+ * @param {unknown} name - The note's `name.full`.
+ * @returns {string|null} The ASCII form, or `null` when there is no name, or
+ *   nothing printable survives.
+ */
+export function asciiName(name: unknown): string | null;
+/**
+ * The name a note files under: its `name.sort` when it declares one, otherwise
+ * its `name.full`.
+ *
+ * @param {unknown} record - An index record or a note's frontmatter.
+ * @returns {string|undefined} The unfolded key, or `undefined` for a record
+ *   with no name.
+ */
+export function nameSortOf(record: unknown): string | undefined;
+/**
+ * The key a name-ordered list compares notes on: {@link nameSortOf} folded to
+ * printable ASCII by {@link asciiName}, so an accented sort key files beside
+ * its base letters. Case is left for the caller, which decides whether its
+ * comparison ignores it.
+ *
+ * @param {unknown} record - An index record or a note's frontmatter.
+ * @returns {string} The key, or "" for a record with no name.
+ */
+export function nameSortKey(record: unknown): string;

package/types/engine/note-calendars.d.mts

@@ -0,0 +1,60 @@
+/**
+ * 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: Array<Record<string, any>>, { contentPackage, defaultCalendar, configFile, contentBase, foreignRecord, problems, parsed }: {
+    contentPackage: string;
+    defaultCalendar?: string | undefined;
+    configFile?: string | undefined;
+    contentBase?: string | undefined;
+    foreignRecord?: ((key: string) => Record<string, any> | undefined) | undefined;
+    problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
+}): Array<Record<string, any>>;
+/**
+ * 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: string | undefined, names: readonly string[]): string | 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: object | undefined, dates?: {
+    noteCalendars?: Map<string, string>;
+}): string | undefined;
+/** The configuration key naming the calendar of last resort. */
+export const DEFAULT_CALENDAR_KEY: "defaultCalendar";

package/types/engine/pdf-render.d.mts

@@ -169,6 +169,10 @@ export function absolutePageUrl(url: string, site?: string): string;
  * carried, then the book and the page. A book with an abbreviation reads
  * `Name (Aelw. p12)`; one without reads `Name (_Book title_, p. 12)`.
  *
+ * A link the text already closes a bracket on, as in `(see Name)`, takes the
+ * reference inside that bracket after a comma, `(see Name, Aelw. p12)`, so the
+ * brackets never nest.
+ *
  * The space before the page number, or between the abbreviation and the page,
  * does not break, so a number never starts a line of its own.
  *
@@ -176,12 +180,16 @@ export function absolutePageUrl(url: string, site?: string): string;
  * @param {{title: string, abbreviation?: string, page: string|number}} away -
  *   The home book's title, its abbreviation when it declares one, and the page
  *   the entry starts on.
+ * @param {{bracketed?: boolean}} [opts] - `bracketed` when the text closes a
+ *   bracket right after the link.
  * @returns {string} Typst markup.
  */
 export function crossBookReference(inner: string, away: {
     title: string;
     abbreviation?: string;
     page: string | number;
+}, { bracketed }?: {
+    bracketed?: boolean;
 }): string;
 /**
  * The Typst definitions the book's page furniture is drawn with.

package/types/engine/pdf-toc.d.mts

@@ -72,7 +72,7 @@ export function runTreeFilters(nodes: object[], db: {
  * without a renderer or a PDF. Only how the result *looks* needs eyes.
  *
  * **Notes are sorted, prose is not.** A section's entries come out in
- * `nameAscii` order — the ASCII fold `buildIndexRecord` already derives, so a
+ * name-sort order (`name.sort`, else `name.full`, folded to ASCII), so a
  * circumflex sorts with its letter instead of after `Z` as a raw codepoint
  * comparison would put it. Prose keeps the position it was written in, because
  * its place in the sequence is the author's statement.