@heroiclands/package-build 23.12.3 → 23.12.5

package/engine/event-fields.mjs

@@ -23,7 +23,7 @@
  */
 
 import { ownDocumentSystem, parseAddress, readCanonicalKey, renderAddress } from "./address.mjs";
-import { formatNoteDate, parseNoteDate } from "./note-dates.mjs";
+import { formatDateInCalendar, formatNoteDate, parseNoteDate } from "./note-dates.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
 
 /** The fields of an event an inline reference may print, in the order a message names them. */
@@ -161,6 +161,29 @@ export function printEventDate(written, date, dates) {
     return printable?.prose ?? printable?.text ?? date.prose ?? date.text ?? String(written);
 }
 
+/**
+ * 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, date, dates, calendar) {
+    if (date?.known && calendar) {
+        try {
+            const printable = formatDateInCalendar(date, calendar, dates);
+            const text = printable?.prose ?? printable?.text;
+            if (text) return text;
+        } catch {
+            // A calendar that does not resolve leaves the date in its own era.
+        }
+    }
+    return printEventDate(written, date, dates);
+}
+
 /**
  * One field of one event, as the text a reference prints, or why it cannot.
  *

package/engine/event-rows.mjs

@@ -25,10 +25,16 @@
  * `resolvedDates.events`, position for position with `data.events`, and the
  * sort keys are read from it rather than parsed again here.
  *
+ * **`whenText` and `untilText` are the dates as a reader sees them**: printed
+ * as the `dateformat` helper prints a date, in the calendar the owning note
+ * names in `data.calendar`, else the one the world note names, else in the era
+ * the date itself names. A date that does not resolve keeps its authored text.
+ *
  * @module
  */
 
 import { ownDocumentSystem, renderAddress } from "./address.mjs";
+import { printEventDateIn } from "./event-fields.mjs";
 import { EVENT_ENTRY_KEYS } from "./note-event-terms.mjs";
 
 /** The columns a row carries besides the event's own keys, before them. */
@@ -37,11 +43,15 @@ const IDENTITY_COLUMNS = Object.freeze(["note", "address"]);
 /** The sort keys a row carries, after the event's own keys. */
 export const EVENT_SORT_COLUMNS = Object.freeze(["whenSort", "whenYear", "untilSort", "untilYear"]);
 
+/** The printed dates a row carries, after the sort keys. */
+export const EVENT_TEXT_COLUMNS = Object.freeze(["whenText", "untilText"]);
+
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS = Object.freeze([
     ...IDENTITY_COLUMNS,
     ...EVENT_ENTRY_KEYS,
     ...EVENT_SORT_COLUMNS,
+    ...EVENT_TEXT_COLUMNS,
 ]);
 
 /** The keys whose authored value is a date, printed as the text it was written as. */
@@ -84,22 +94,41 @@ function axisKeys(date) {
     };
 }
 
+/**
+ * The calendar the world note names, which displays every date whose own note
+ * names none.
+ *
+ * @param {Record<string, any>[]} records - Index records.
+ * @returns {string|undefined} The calendar's Address or shortcode.
+ */
+function worldCalendar(records) {
+    for (const record of records) {
+        if (record?.type === "place" && record.data?.year?.days && record.data.calendar)
+            return String(record.data.calendar);
+    }
+    return undefined;
+}
+
 /**
  * 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.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records) {
+export function eventRows(records, dates) {
     const rows = [];
-    for (const record of records) {
+    const all = [...records];
+    const world = worldCalendar(all);
+    for (const record of all) {
         const events = record?.data?.events;
         if (!Array.isArray(events) || !events.length) continue;
         const note = noteAddressOf(record);
         if (!note) continue;
         const resolved =
             Array.isArray(record.resolvedDates?.events) ? record.resolvedDates.events : [];
+        const calendar = record.data?.calendar ? String(record.data.calendar) : world;
         events.forEach((entry, position) => {
             if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
             const row = {
@@ -119,6 +148,12 @@ export function eventRows(records) {
             row.whenYear = when.year;
             row.untilSort = until.sort;
             row.untilYear = until.year;
+            for (const key of DATE_KEYS) {
+                row[`${key}Text`] =
+                    row[key] === null ?
+                        null
+                    :   printEventDateIn(row[key], resolved[position]?.[key], dates, calendar);
+            }
             rows.push(row);
         });
     }

package/engine/event-views.mjs

@@ -65,8 +65,9 @@ const BY_DATE = "ORDER BY e.whenSort NULLS LAST, e.address";
  *
  * @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}) => {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 = Object.freeze([
     Object.freeze({
@@ -75,6 +76,7 @@ export const EVENT_VIEWS = Object.freeze([
         applies: (record) => record.type === "place",
         query: chronologyQuery,
         owners: chronologyOwners,
+        felt: chronologyFeltOwners,
     }),
     Object.freeze({
         slug: "events",
@@ -91,8 +93,8 @@ export const EVENT_VIEWS = Object.freeze([
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
+                    '       e.whenText AS "When",',
                     '       e.summary AS "What happened",',
-                    '       e."when" AS "When",',
                     `       array_to_string(list_transform(${named}, w -> w.role), ', ') AS "Role"`,
                     "FROM events e",
                     `WHERE len(${named}) > 0`,
@@ -120,8 +122,8 @@ export const EVENT_VIEWS = Object.freeze([
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
+                    '       e.whenText AS "When",',
                     '       e.summary AS "Event",',
-                    '       e."when" AS "When",',
                     '       e.account.says AS "What they say",',
                     '       e.account.agrees AS "Agrees"',
                     "FROM (SELECT *, unnest(accounts) AS account FROM events) e",
@@ -151,8 +153,8 @@ export const EVENT_VIEWS = Object.freeze([
             return {
                 fence: [
                     "SELECT e.note AS _ref,",
+                    '       e.whenText AS "When",',
                     '       e.summary AS "What followed",',
-                    '       e."when" AS "When",',
                     `       array_to_string(list_transform(${edges}, f -> f.how), ', ') AS "How"`,
                     "FROM events e",
                     `WHERE len(${edges}) > 0`,
@@ -237,6 +239,36 @@ function chronologyOwnRows(shape) {
  * @returns {Promise<Set<string>>} The roots with at least one own row.
  */
 async function chronologyOwners(db, selves, shape) {
+    return chronologyRoots(db, selves, shape, chronologyOwnRows(shape));
+}
+
+/**
+ * Which places have a row felt there, asked of every place in one query. A
+ * chronology prints its `Felt here` column only for these.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {string[][]} selves - Each place's Address, in each form.
+ * @param {CorpusShape} shape - What the corpus states.
+ * @returns {Promise<Set<string>>} The roots with at least one felt row.
+ */
+async function chronologyFeltOwners(db, selves, shape) {
+    if (!shape.reach) return new Set();
+    return chronologyRoots(db, selves, shape, [
+        `len(list_filter(${chronologyFelt()}, r -> coalesce(r.how, '') <> '')) > 0`,
+    ]);
+}
+
+/**
+ * The roots among `selves` for which an event satisfies one of `conditions`,
+ * over the places at or below each root.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {string[][]} selves - Each place's Address, in each form.
+ * @param {CorpusShape} shape - What the corpus states.
+ * @param {string[]} conditions - Alternatives over `e` and `here.places`.
+ * @returns {Promise<Set<string>>} The roots with at least one such event.
+ */
+async function chronologyRoots(db, selves, shape, conditions) {
     const values = [...new Set(selves.map((self) => self[0]))]
         .map((root) => `(${literal(root)})`)
         .join(", ");
@@ -258,7 +290,7 @@ async function chronologyOwners(db, selves, shape) {
             "here AS (SELECT root, list(place) AS places FROM below GROUP BY root)",
             "SELECT DISTINCT here.root AS root",
             "FROM events e, here",
-            `WHERE ${chronologyOwnRows(shape).join(" OR ")}`,
+            `WHERE ${conditions.join(" OR ")}`,
         ].join("\n"),
     );
     return new Set(rows.map((row) => String(row.root)));
@@ -275,10 +307,12 @@ async function chronologyOwners(db, selves, shape) {
  *
  * @param {string[]} self - The place's Address, in each form.
  * @param {CorpusShape} shape - What the corpus states.
+ * @param {{felt?: boolean}} [columns] - `felt: false` when no row of this
+ *   place is felt there, which leaves the `Felt here` column out.
  * @returns {{fence: string, own: string}|null} The query, and the one that
  *   counts the place's own rows.
  */
-function chronologyQuery(self, shape) {
+function chronologyQuery(self, shape, columns = {}) {
     if (!shape.locus && !shape.reach) return null;
     const below =
         shape.parents ?
@@ -298,11 +332,13 @@ function chronologyQuery(self, shape) {
         ...below,
         "here AS (SELECT list(place) AS places FROM below)",
         "SELECT e.note AS _ref,",
-        '       e.summary AS "What happened",',
-        '       e."when" AS "When",',
-        shape.reach ?
-            `       array_to_string(list_transform(${felt}, r -> r.how), '; ') AS "Felt here"`
-        :   '       NULL AS "Felt here"',
+        '       e.whenText AS "When",',
+        shape.reach && columns.felt !== false ?
+            '       e.summary AS "What happened",'
+        :   '       e.summary AS "What happened"',
+        ...(shape.reach && columns.felt !== false ?
+            [`       array_to_string(list_transform(${felt}, r -> r.how), '; ') AS "Felt here"`]
+        :   []),
         "FROM events e, here",
     ];
     const context = shape.depth ? ["e.depth = 'world'"] : [];
@@ -394,6 +430,7 @@ export async function eventViewSections(db, records, fileOf, only) {
     // A view that can say which notes have rows in one query is asked once, over
     // every note it will be given, and the per-note count is skipped.
     const owned = new Map();
+    const felt = new Map();
     for (const view of EVENT_VIEWS) {
         if (!view.owners) continue;
         const selves = [];
@@ -404,7 +441,10 @@ export async function eventViewSections(db, records, fileOf, only) {
             const self = selfForms(record);
             if (view.query(self, shape)) selves.push(self);
         }
-        if (selves.length) owned.set(view.slug, await view.owners(db, selves, shape));
+        if (selves.length) {
+            owned.set(view.slug, await view.owners(db, selves, shape));
+            if (view.felt) felt.set(view.slug, await view.felt(db, selves, shape));
+        }
     }
     for (const record of all) {
         if (!record?.address || record.documents || !record.shortcode) continue;
@@ -413,7 +453,11 @@ export async function eventViewSections(db, records, fileOf, only) {
         const sections = new Map();
         for (const view of EVENT_VIEWS) {
             if (!view.applies(record) || authoredSection(record, view.slug)) continue;
-            const query = view.query(self, shape);
+            const query = view.query(
+                self,
+                shape,
+                felt.has(view.slug) ? { felt: felt.get(view.slug).has(self[0]) } : undefined,
+            );
             if (!query) continue;
             const has =
                 owned.has(view.slug) ?

package/engine/frontmatter-lint.mjs

@@ -1285,6 +1285,17 @@ export function lintNote(
                     });
                 }
             }
+            if (
+                Object.hasOwn(name, "sort") &&
+                (typeof name.sort !== "string" || !name.sort.trim())
+            ) {
+                findings.push({
+                    file: note.file,
+                    ...nameAt(["sort"]),
+                    severity: "error",
+                    message: "`name.sort` must be a nonempty string",
+                });
+            }
             for (const key of CHARACTER_NAME_KEYS) {
                 if (!Object.hasOwn(name, key) || !allowed.has(key)) continue;
                 if (typeof name[key] === "string" && name[key].trim()) continue;

package/engine/generated-sections.mjs

@@ -41,6 +41,13 @@
  * @module
  */
 
+/**
+ * The anchor of the Chronology section, which the book sets across the page.
+ *
+ * @type {string}
+ */
+export const CHRONOLOGY_SLUG = "chronology";
+
 /**
  * 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
@@ -53,7 +60,7 @@ export const GENERATED_SECTIONS = Object.freeze(
         { slug: "within", heading: "Within" },
         { slug: "governedby", heading: "Governed by" },
         { slug: "governedplaces", heading: "Governed places" },
-        { slug: "chronology", heading: "Chronology" },
+        { slug: CHRONOLOGY_SLUG, heading: "Chronology" },
         { slug: "events", heading: "Events" },
         { slug: "accounts", heading: "Accounts" },
         { slug: "followed", heading: "What followed" },

package/engine/holdings.mjs

@@ -24,13 +24,14 @@ import { isAddressTuple, ownDocumentSystem, parseAddress, renderAddress } from "
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 
-/** @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.
@@ -108,6 +109,7 @@ function listed(node) {
 function entryOf(node) {
     return {
         title: node.title,
+        ...(node.sort ? { sort: node.sort } : {}),
         ...(listed(node) ? { url: node.url } : {}),
         address: ownKey(node),
         type: node.type,
@@ -118,7 +120,7 @@ function entryOf(node) {
 function bySubTypeThenTitle(a, b) {
     return (
         (a.subType ?? "").localeCompare(b.subType ?? "", "en") ||
-        a.title.localeCompare(b.title, "en")
+        (a.sort ?? a.title).localeCompare(b.sort ?? b.title, "en")
     );
 }
 
@@ -141,6 +143,7 @@ export function holdingsNode(
         type,
         subType: fm.subType == null ? undefined : String(fm.subType),
         title,
+        ...(typeof fm.name?.sort === "string" && fm.name.sort ? { sort: fm.name.sort } : {}),
         url,
         ...(pkg ? { package: pkg } : {}),
         ...(system ? { system } : {}),
@@ -173,6 +176,9 @@ export function foreignHoldingsNodes(foreignIndex) {
             type,
             subType: entry.subType == null ? undefined : String(entry.subType),
             title: String(entry.name ?? tuple.shortcode),
+            ...(typeof entry.nameSort === "string" && entry.nameSort ?
+                { sort: entry.nameSort }
+            :   {}),
             url: entry.url,
             parents:
                 type === "place" ?

package/engine/infobox-render.mjs

@@ -296,9 +296,14 @@ function entryToTypst(entry, link) {
 }
 
 /**
- * One section as Typst, whole and unbreakable.
+ * One section as Typst.
  *
- * `lead` rides **inside** the block rather than above it. A panel breaks
+ * A stat grid is whole and unbreakable. A section of rows or run-in lists may
+ * break between its rows, so a section taller than the space left on a page
+ * continues on the next one instead of running past the page's foot; each row
+ * stays whole, and the section's label and `lead` stay with its first row.
+ *
+ * `lead` rides **inside** the section rather than above it. A panel breaks
  * between its sections, and a title sitting outside the first one is a break
  * the panel is allowed to take — which leaves the heading and a rule stranded
  * at the foot of a page with nothing under them.
@@ -309,8 +314,9 @@ function entryToTypst(entry, link) {
  * @returns {string} Typst markup.
  */
 function sectionToTypst(section, link, lead = "") {
-    const body = lead ? [lead] : [];
-    if (section.label) body.push(`#infobox-head[${escapeTypst(section.label)}]`);
+    const head = lead ? [lead] : [];
+    if (section.label) head.push(`#infobox-head[${escapeTypst(section.label)}]`);
+    const body = [];
 
     if (section.layout === "rows") {
         for (const row of section.rows ?? []) {
@@ -346,7 +352,12 @@ function sectionToTypst(section, link, lead = "") {
         }
     }
 
-    return `#block(breakable: false)[\n${body.join("\n")}\n]`;
+    if (section.layout === "grid" || body.length < 2)
+        return `#block(breakable: false)[\n${[...head, ...body].join("\n")}\n]`;
+    const [first, ...rest] = body;
+    const kept = `#block(breakable: false)[\n${[...head, first].join("\n")}\n]`;
+    const rows = rest.map((row) => `#block(breakable: false)[${row}]`);
+    return `#block(breakable: true)[\n${[kept, ...rows].join("\n")}\n]`;
 }
 
 /**

package/engine/infobox.mjs

@@ -593,6 +593,27 @@ export function valueKindOf(field, value) {
     return Array.isArray(value) ? "list" : "text";
 }
 
+/**
+ * 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) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return String(value);
+    const size = Math.abs(n);
+    if (size < 1e6) return n.toLocaleString("en-US", { maximumFractionDigits: 20 });
+    // A figure that rounds up to a thousand million is a billion.
+    const [scale, word] = size < 999.95e6 ? [1e6, "million"] : [1e9, "billion"];
+    const scaled = Math.round((n / scale) * 10) / 10;
+    return `${scaled.toLocaleString("en-US", { maximumFractionDigits: 1 })} ${word}`;
+}
+
 /**
  * Build one row's value, resolving whatever the kind says is a reference.
  *
@@ -616,7 +637,7 @@ function rowValue(kind, raw, resolve, hint, verbatim = false) {
     if (kind === "list") {
         return (Array.isArray(raw) ? raw : [raw]).filter(hasValue).map((v) => shown(v));
     }
-    if (kind === "number") return raw;
+    if (kind === "number") return formatQuantity(raw);
     return shown(raw);
 }
 
@@ -904,7 +925,7 @@ function declaredKeyRows(fields, raw) {
             (inner.kind === "number" || inner.kind === "integer") &&
             Number.isFinite(Number(value))
         ) {
-            rows.push({ label, kind: "number", value: Number(value) });
+            rows.push({ label, kind: "number", value: formatQuantity(Number(value)) });
         } else {
             rows.push({ label, kind: "text", value: shown(value) });
         }

package/engine/literature-works.mjs

@@ -31,11 +31,12 @@ import { AddressLink } from "./address-values.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 import { LITERATURE_SUBTYPE } from "./literature-notes.mjs";
 
-/** @typedef {{title: string, url?: string, address: string, form?: string}} WorkEntry */
+/** @typedef {{title: string, sort?: string, url?: string, address: string, form?: string}} WorkEntry */
 /**
  * @typedef {object} WorksNode
  * @property {string} key Own Address, normalized to the `note` system.
  * @property {string} title
+ * @property {string} [sort] The note's `name.sort`; the list files by it in place of `title`.
  * @property {string} [url] Absent for a note that publishes no page.
  * @property {string} [package] Owning content package.
  * @property {string} [form] A work's `data.form`.
@@ -79,6 +80,7 @@ export function worksNode(fm, { title, url, package: pkg }) {
     return {
         key: renderAddress({ package: pkg ?? "local", system: "note", type, shortcode }),
         title,
+        ...(typeof fm.name?.sort === "string" && fm.name.sort ? { sort: fm.name.sort } : {}),
         ...(url ? { url } : {}),
         ...(pkg ? { package: pkg } : {}),
         ...(work && typeof data.form === "string" && data.form ? { form: data.form } : {}),
@@ -107,6 +109,9 @@ export function foreignWorksNodes(foreignIndex) {
         out.push({
             key: renderAddress({ ...tuple, system: "note" }),
             title: String(entry.name ?? tuple.shortcode),
+            ...(typeof entry.nameSort === "string" && entry.nameSort ?
+                { sort: entry.nameSort }
+            :   {}),
             ...(entry.url ? { url: entry.url } : {}),
             package: tuple.package,
             ...(typeof entry.form === "string" && entry.form ? { form: entry.form } : {}),
@@ -149,6 +154,7 @@ export function worksPages(nodes, { types }) {
             if (!block) lists.set(target.url, (block = { works: [] }));
             block.works.push({
                 title: work.title,
+                ...(work.sort ? { sort: work.sort } : {}),
                 ...(work.url ? { url: work.url } : {}),
                 address: work.key,
                 ...(work.form ? { form: work.form } : {}),
@@ -156,6 +162,6 @@ export function worksPages(nodes, { types }) {
         }
     }
     for (const block of lists.values())
-        block.works.sort((a, b) => a.title.localeCompare(b.title, "en"));
+        block.works.sort((a, b) => (a.sort ?? a.title).localeCompare(b.sort ?? b.title, "en"));
     return lists;
 }

package/engine/metadata-index.mjs

@@ -445,6 +445,9 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
             const foundry = record.foundry?.[parts.system];
             index.set(key, {
                 name: record.name?.full ?? record.name,
+                ...(typeof record.name?.sort === "string" && record.name.sort ?
+                    { nameSort: record.name.sort }
+                :   {}),
                 aliases: record.name?.aliases,
                 // Absent where the package publishes no page for it. A consumer
                 // must tolerate that rather than invent an href, exactly as it

package/engine/name-sort.mjs

@@ -0,0 +1,91 @@
+/*
+ * 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 key a name-ordered list files a note under, and the ASCII fold ordering
+ * compares it on. A leaf module, so every list that orders notes by name can
+ * read the key without importing the content index.
+ *
+ * @module
+ */
+
+import unidecode from "unidecode";
+
+/**
+ * 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) {
+    if (typeof name !== "string") return null;
+    const folded = unidecode(name)
+        .replace(/[^\x20-\x7E]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return folded === "" ? null : folded;
+}
+
+/**
+ * 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) {
+    const name = /** @type {any} */ (record)?.name;
+    for (const candidate of [name?.sort, name?.full]) {
+        if (typeof candidate === "string" && candidate.trim()) return candidate;
+    }
+    return 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) {
+    const key = nameSortOf(record);
+    if (key === undefined) return "";
+    return asciiName(key) ?? key;
+}

package/engine/note-frontmatter.mjs

@@ -22,7 +22,7 @@ export {
 } from "./note-vocabulary.mjs";
 
 /** The name properties every note accepts, in display order. */
-export const NOTE_NAME_KEYS = Object.freeze(["full", "aliases"]);
+export const NOTE_NAME_KEYS = Object.freeze(["full", "aliases", "sort"]);
 
 /** Additional name components accepted by an individual character. */
 export const CHARACTER_NAME_KEYS = Object.freeze(["given", "clan"]);

package/engine/note-vocabulary.mjs

@@ -939,7 +939,7 @@ export const NOTE_TOP_LEVEL_FIELDS = Object.freeze([
     }),
     Object.freeze({
         name: "name",
-        describe: "The display names — a required `full`, and any `aliases`.",
+        describe: "The display names — a required `full`, and any `aliases` and `sort`.",
     }),
     Object.freeze({
         name: "type",

package/engine/page-lists.mjs

@@ -41,6 +41,7 @@
  * @module
  */
 
+import { nameSortKey } from "./name-sort.mjs";
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
 import { booleanAttribute } from "./extension-attributes.mjs";
 import { isNoteRecord } from "./index-records.mjs";
@@ -195,8 +196,8 @@ export function findPageListBlocks(markdown) {
     return blocks;
 }
 
-/** A page's sort key, folded so a circumflex sorts with its letter. */
-const nameKey = (record) => String(record?.nameAscii ?? record?.name?.full ?? "").toLowerCase();
+/** A page's sort key: its `name.sort` or `name.full`, folded so a circumflex sorts with its letter. */
+const nameKey = (record) => nameSortKey(record).toLowerCase();
 
 /** The address a page is addressed by, as a stable tiebreak. */
 const slugKey = (record) => String(record?.address?.slug ?? "");