@heroiclands/package-build 25.1.0 → 25.1.2

package/engine/encoding-lexicon.mjs

@@ -20,7 +20,7 @@ import { isNoteRecord } from "./index-records.mjs";
 import { nearest } from "./near-miss.mjs";
 import { isLanguageRecord, lineageChain, noteAddressOf } from "./word-rows.mjs";
 import { derivedForms, foldWord } from "./word-forms.mjs";
-import { WRITTEN_ENDINGS } from "./language-terms.mjs";
+import { WRITTEN_ENDINGS, RESERVED_TONGUE } from "./language-terms.mjs";
 import { LANGUAGE_SUBTYPE, glossText } from "./word-terms.mjs";
 import { writingsOf } from "./language-writings.mjs";
 import { encodeText, validateSource, EncodingError } from "./encoding.mjs";
@@ -389,9 +389,21 @@ export function nativeRows(records) {
     return rows;
 }
 
-/** Project only conversion-readable language data to a JSON-safe object. */
+/** Each lexicon's projection, made once and shared by every conversion that reads it. */
+const serialized = new WeakMap();
+
+/**
+ * Project only conversion-readable language data to a JSON-safe object. The
+ * projection of one lexicon is made once and shared, so it must not be modified.
+ */
 export function serializeLexicon(lexicon) {
     if (!lexicon) return undefined;
+    if (!serialized.has(lexicon)) serialized.set(lexicon, projectLexicon(lexicon));
+    return serialized.get(lexicon);
+}
+
+/** The conversion-readable data of a lexicon, copied. */
+function projectLexicon(lexicon) {
     const select = (value, keys) =>
         Object.fromEntries(
             keys
@@ -658,7 +670,9 @@ export function checkEncodingLexicon(note, ctx) {
         );
         listOf(element?.examples).forEach((form, j) => add(form, ["elements", i, "examples", j]));
     });
-    listOf(data.register).forEach((name, i) => add(name?.name, ["register", i, "name"]));
+    listOf(data.register).forEach((name, i) => {
+        if (name?.tongue !== RESERVED_TONGUE) add(name?.name, ["register", i, "name"]);
+    });
     const findings = [],
         seen = new Set();
     for (const encoding of encodings)

package/engine/encoding-template.mjs

@@ -61,10 +61,13 @@ export function templateProgram(data, options, fault) {
                 "A glyph code must resolve to nonempty Unicode scalar text",
             );
     }
-    const resolve = (value, key) => {
+    const resolve = (value, key, allowEmpty = false) => {
         const sequence = typeof value === "string" ? [value] : value;
-        if (!Array.isArray(sequence) || !sequence.length)
-            fault(key, "A mapping is a glyph code or a nonempty sequence of glyph codes");
+        if (!Array.isArray(sequence) || (!sequence.length && !allowEmpty))
+            fault(
+                key,
+                "A mapping is a glyph code or a code sequence; an empty sequence requires canonical round trips",
+            );
         return sequence
             .map((name) => {
                 if (
@@ -82,6 +85,8 @@ export function templateProgram(data, options, fault) {
         [
             "normalization",
             "matching",
+            "roundTrip",
+            "word-separators",
             "case",
             "stress",
             "vowel-groups",
@@ -95,6 +100,9 @@ export function templateProgram(data, options, fault) {
     const rules = data.rules;
     exact(rules.normalization, "NFC", "rules.normalization");
     exact(rules.matching, "longest-first", "rules.matching");
+    if (rules.roundTrip !== undefined && !["exact", "canonical"].includes(rules.roundTrip))
+        fault("rules.roundTrip", "roundTrip is exact or canonical");
+    const canonical = rules.roundTrip === "canonical";
     if (rules.case !== undefined)
         fixed(
             rules.case,
@@ -106,7 +114,11 @@ export function templateProgram(data, options, fault) {
             "rules.case",
         );
     for (const key of ["diaeresis", "grave-accent"])
-        if (rules[key] !== undefined) fixed(rules[key], { allowed: false }, `rules.${key}`);
+        if (rules[key] !== undefined) {
+            closed(rules[key], ["allowed"], `rules.${key}`);
+            if (typeof rules[key].allowed !== "boolean")
+                fault(`rules.${key}.allowed`, "allowed must be true or false");
+        }
     const vowels = data.vowels ?? "";
     if (!scalar(vowels)) fault("vowels", "vowels must be a Unicode scalar string");
     const vowelSet = new Set([...vowels].map(base));
@@ -189,8 +201,9 @@ export function templateProgram(data, options, fault) {
         if (/[\p{White_Space}⟦⟧]/u.test(from))
             fault(key, "Whitespace and literal markers belong to the shared standard");
         const decomposed = from.normalize("NFD");
-        if (rules.diaeresis && decomposed.includes("\u0308")) fault(key, "Diaeresis is forbidden");
-        if (rules["grave-accent"] && decomposed.includes("\u0300"))
+        if (rules.diaeresis?.allowed === false && decomposed.includes("\u0308"))
+            fault(key, "Diaeresis is forbidden");
+        if (rules["grave-accent"]?.allowed === false && decomposed.includes("\u0300"))
             fault(key, "Grave accents are forbidden");
     };
     const validateOutput = (from, to, key) => {
@@ -215,10 +228,36 @@ export function templateProgram(data, options, fault) {
     for (const [from, output] of Object.entries(data.mappings)) {
         const key = `mappings.${from}`;
         validateSource(from, key);
-        const to = resolve(output, key);
+        const to = resolve(output, key, canonical);
         validateOutput(from, to, key);
         mappings.push([from, to]);
     }
+    const separators = [];
+    if (rules["word-separators"] !== undefined) {
+        if (!Array.isArray(rules["word-separators"]))
+            fault("rules.word-separators", "word-separators must be a list");
+        const seen = new Set();
+        for (const [i, from] of rules["word-separators"].entries()) {
+            const key = `rules.word-separators.${i}`;
+            validateSource(from, key);
+            if (
+                [...from].some(
+                    (char) =>
+                        "^/{}".includes(char) || /[\p{Cc}\p{Cf}\u{E0100}-\u{E01EF}]/u.test(char),
+                ) ||
+                STANDARD_ROWS.some((row) => (Array.isArray(row) ? row[0] : row.from) === from)
+            )
+                fault(
+                    key,
+                    "Word separators cannot replace shared punctuation or contain structural controls",
+                );
+            if (seen.has(from)) fault(key, "A word separator is stated twice");
+            if (Object.hasOwn(data.mappings, from))
+                fault(key, "A word separator cannot also have an ordinary mapping");
+            seen.add(from);
+            separators.push({ from, to: STANDARD_CONTROLS.wordSeparator });
+        }
+    }
     const contextual = [];
     if (rules["contextual-mappings"] !== undefined) {
         if (!Array.isArray(rules["contextual-mappings"]))
@@ -226,21 +265,36 @@ export function templateProgram(data, options, fault) {
         const seen = new Set();
         for (const [i, row] of rules["contextual-mappings"].entries()) {
             const key = `rules.contextual-mappings.${i}`;
-            closed(row, ["match", "before", "emit"], key);
-            if (
-                !scalar(row.match) ||
-                !row.match ||
-                row.match !== row.match.normalize("NFC") ||
-                seen.has(row.match)
-            )
-                fault(`${key}.match`, "A contextual match must be unique nonempty NFC text");
-            exact(row.before, "vowel", `${key}.before`);
-            if (!vowels) fault(`${key}.before`, "Before-vowel mappings require declared vowels");
+            closed(row, ["match", "before", "at", "emit"], key);
+            if (!scalar(row.match) || !row.match || row.match !== row.match.normalize("NFC"))
+                fault(`${key}.match`, "A contextual match must be nonempty NFC text");
+            if (row.before === undefined && row.at === undefined)
+                fault(key, "A contextual mapping requires before or at");
+            if (row.before !== undefined && !["vowel", "consonant"].includes(row.before))
+                fault(`${key}.before`, "before is vowel or consonant");
+            if (row.at !== undefined && !["start", "end", "line-start"].includes(row.at))
+                fault(`${key}.at`, "at is start, end or line-start");
+            if (row.before && !vowels)
+                fault(
+                    `${key}.before`,
+                    "Before-vowel or before-consonant mappings require declared vowels",
+                );
+            const condition = JSON.stringify([row.match, row.before ?? null, row.at ?? null]);
+            if (seen.has(condition))
+                fault(
+                    `${key}.match`,
+                    "A contextual mapping repeats the same source and conditions",
+                );
             validateSource(row.match, `${key}.match`);
-            const to = resolve(row.emit, `${key}.emit`);
+            const to = resolve(row.emit, `${key}.emit`, canonical);
             validateOutput(row.match, to, `${key}.emit`);
-            seen.add(row.match);
-            contextual.push({ from: row.match, to, before: "vowel" });
+            seen.add(condition);
+            contextual.push({
+                from: row.match,
+                to,
+                ...(row.before !== undefined ? { before: row.before } : {}),
+                ...(row.at !== undefined ? { at: row.at } : {}),
+            });
         }
     }
     if (rules.case)
@@ -256,26 +310,32 @@ export function templateProgram(data, options, fault) {
         ...STANDARD_ROWS.filter((row) => !overridden.has(Array.isArray(row) ? row[0] : row.from)),
         ...contextual,
         ...mappings,
+        ...separators,
     ];
-    assertUniqueOutputs(
-        [
-            ...rows.map((row) => {
-                if (Array.isArray(row))
-                    return { from: row[0], to: row[1], key: `mappings.${row[0]}` };
-                const index = contextual.indexOf(row);
-                return {
-                    ...row,
-                    key: index < 0 ? "rules" : `rules.contextual-mappings.${index}.emit`,
-                };
-            }),
-            { from: " ", to: " ", key: "rules" },
-        ],
-        fault,
-    );
+    const sourceKey = (row) => {
+        if (Array.isArray(row)) return `mappings.${row[0]}`;
+        const separator = separators.indexOf(row);
+        if (separator >= 0) return `rules.word-separators.${separator}`;
+        const context = contextual.indexOf(row);
+        return context < 0 ? "rules" : `rules.contextual-mappings.${context}`;
+    };
+    if (!canonical)
+        assertUniqueOutputs(
+            [
+                ...rows.map((row) =>
+                    Array.isArray(row) ?
+                        { from: row[0], to: row[1], key: sourceKey(row) }
+                    :   { ...row, key: sourceKey(row) },
+                ),
+                { from: " ", to: " ", key: "rules" },
+            ],
+            fault,
+        );
     const accepts = data.accepts ?? [
         ...new Set([
             ...Object.keys(data.mappings).join(""),
             ...contextual.map((r) => r.from).join(""),
+            ...separators.map((row) => row.from).join(""),
         ]),
     ];
     if (!Array.isArray(accepts)) fault("accepts", "accepts must be a list of characters or ranges");
@@ -285,17 +345,14 @@ export function templateProgram(data, options, fault) {
             fonts: [data.font],
             accepts: [...accepts, ...STANDARD_ROWS.map((r) => (Array.isArray(r) ? r[0] : r.from))],
             separator: " ",
+            roundTrip: canonical ? "canonical" : "exact",
             vowels,
             rows,
             codes: Object.entries(options.codes),
             controls: STANDARD_CONTROLS,
             ...(rules.case ? { groupCase: "initial" } : {}),
         },
-        rowKeys: rows.map((row) => {
-            if (Array.isArray(row)) return `mappings.${row[0]}`;
-            const index = contextual.indexOf(row);
-            return index < 0 ? "rules" : `rules.contextual-mappings.${index}`;
-        }),
+        rowKeys: rows.map(sourceKey),
         metadata: {
             name: options.name ?? `${data.language}-${data.font}`,
             language: data.language,
@@ -305,8 +362,8 @@ export function templateProgram(data, options, fault) {
                 vowelGroups: Object.freeze(vowelGroups),
                 maxVowelGroup: Math.max(0, ...vowelGroups.map((group) => [...group].length)),
                 stress,
-                diaeresis: !!rules.diaeresis,
-                grave: !!rules["grave-accent"],
+                diaeresis: rules.diaeresis?.allowed === false,
+                grave: rules["grave-accent"]?.allowed === false,
             }),
         },
     };

package/engine/encoding-terms.mjs

@@ -28,7 +28,7 @@ const fixed = (name, value) => ({
 const block = (name, describe, fields) => ({ name, kind: "map", shape: "a map", describe, fields });
 const sequence = {
     kind: "string-or-list",
-    shape: "a glyph code or list of codes",
+    shape: "a glyph code or list of codes (empty only with canonical round trips)",
     entries: {
         kind: "string",
         shape: "a glyph code",
@@ -39,6 +39,25 @@ const sequence = {
 export const ENCODING_RULE_FIELDS = Object.freeze([
     fixed("normalization", "NFC"),
     fixed("matching", "longest-first"),
+    {
+        ...text(
+            "roundTrip",
+            "Exact by default; canonical permits aliases and empty code sequences and decodes an authored conventional spelling.",
+        ),
+        allowed: ["exact", "canonical"],
+    },
+    {
+        name: "word-separators",
+        kind: "list",
+        shape: "a list of nonempty NFC source sequences",
+        entries: {
+            kind: "string",
+            shape: "a word separator",
+            describe: "A source sequence that writes the shared word space.",
+        },
+        describe:
+            "Source word dividers written as shared spaces, after contextual alternatives; cannot also be ordinary mappings or replace shared punctuation.",
+    },
     block("case", "Case handling for letters and consonant groups.", [
         fixed("single-letter", "preserve"),
         fixed("consonant-group", "lowercase-or-initial-uppercase"),
@@ -70,19 +89,37 @@ export const ENCODING_RULE_FIELDS = Object.freeze([
             describe: "The complete authored group inventory.",
         },
     ]),
-    block("diaeresis", "Whether diaeresis mappings are allowed.", [fixed("allowed", false)]),
-    block("grave-accent", "Whether grave-accent mappings are allowed.", [fixed("allowed", false)]),
+    ...["diaeresis", "grave-accent"].map((name) =>
+        block(name, `Whether ${name} mappings are allowed.`, [
+            {
+                name: "allowed",
+                kind: "boolean",
+                shape: "true or false",
+                required: true,
+                describe:
+                    "False forbids the accent; true permits explicitly mapped and accepted characters.",
+            },
+        ]),
+    ),
     {
         name: "contextual-mappings",
         kind: "list",
         shape: "a list of conditional mappings",
-        describe: "Before-vowel alternatives applied before unconditional mappings.",
+        describe:
+            "Alternatives conditioned on the following letter or source position, applied before unconditional mappings.",
         entries: {
             kind: "map",
             shape: "a contextual mapping",
             fields: [
                 text("match", "The source sequence.", true),
-                fixed("before", "vowel"),
+                {
+                    ...text("before", "Match before a declared vowel or another letter."),
+                    allowed: ["vowel", "consonant"],
+                },
+                {
+                    ...text("at", "Match at word start, word end or line start."),
+                    allowed: ["start", "end", "line-start"],
+                },
                 {
                     name: "emit",
                     ...sequence,

package/engine/encoding.mjs

@@ -322,15 +322,13 @@ function boundary(char) {
     // Python str.isspace also includes the four information separators.
     return SPACE.test(char) || /[\u001C-\u001F]/u.test(char) || BOUNDARY.test(char);
 }
+function beforeHolds(condition, char, vowels) {
+    return Boolean(
+        char && (condition === "vowel" ? vowels.has(char) : !vowels.has(char) && LETTER.test(char)),
+    );
+}
 function holds(row, text, start, end, vowels) {
-    if (row.before) {
-        const char = firstAt(text, end);
-        if (
-            !char ||
-            (row.before === "vowel" ? !vowels.has(char) : vowels.has(char) || !LETTER.test(char))
-        )
-            return false;
-    }
+    if (row.before && !beforeHolds(row.before, firstAt(text, end), vowels)) return false;
     if (row.at === "line-start") {
         const prefix = text.slice(
             Math.max(text.lastIndexOf("\n", start - 1), text.lastIndexOf("/", start - 1)) + 1,
@@ -834,7 +832,7 @@ function decodeRawText(enc, text, { font } = {}) {
 }
 
 /**
- * Decode a note's uniquely decodable output, including nonprefix glyph sequences.
+ * Decode exact output or the conventional reading of an explicitly canonical note.
  * @param {ReturnType<typeof compileEncoding>} enc - Compiled encoding note.
  * @param {string} text - Native text with optional literal spans.
  * @param {{font?: string}} [options] - Selected encoding face.
@@ -845,17 +843,19 @@ export function decodeText(enc, text, options = {}) {
     const readings = tiers(enc, options.font)[0].readings;
     if (typeof text !== "string") throw new EncodingError("Text must be a string");
     if (!templateReaders.has(enc)) {
-        const root = { children: new Map(), row: undefined };
-        for (const group of readings.values())
-            for (const row of group) {
-                let node = root;
-                for (const char of row.to) {
-                    if (!node.children.has(char))
-                        node.children.set(char, { children: new Map(), row: undefined });
-                    node = node.children.get(char);
-                }
-                node.row = row;
+        const root = { children: new Map(), row: undefined, rows: [] };
+        const rows = new Set([...readings.values()].flat().concat(enc.shared.rows));
+        for (const row of rows) {
+            if (!row.to) continue;
+            let node = root;
+            for (const char of row.to) {
+                if (!node.children.has(char))
+                    node.children.set(char, { children: new Map(), row: undefined, rows: [] });
+                node = node.children.get(char);
             }
+            node.row ??= row;
+            node.rows.push(row);
+        }
         templateReaders.set(enc, root);
     }
     const reader = templateReaders.get(enc);
@@ -888,9 +888,15 @@ export function decodeText(enc, text, options = {}) {
             cursor = cursor.children.get(char);
             if (!cursor) break;
             next += char.length;
-            const row = cursor.row;
-            if (!row || !paths.has(next)) continue;
-            if (row.before && !enc.vowels.has(firstAt(paths.get(next).from, 0))) {
+            if (!cursor.row || !paths.has(next)) continue;
+            const following = firstAt(paths.get(next).from, 0);
+            const preferred = cursor.rows.find(
+                (row) => !row.before || beforeHolds(row.before, following, enc.vowels),
+            );
+            // Canonical source can omit the vowel or marker that selected a form.
+            // Prefer applicable aliases, then retain the first authored reading.
+            const row = preferred ?? (enc.roundTrip === "canonical" ? cursor.row : undefined);
+            if (!row) {
                 failedContext = Math.min(failedContext, at);
                 continue;
             }

package/engine/heading-attributes.mjs

@@ -34,15 +34,12 @@
  */
 
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
-import MarkdownIt from "markdown-it";
-
-/** Literal block ranges use the renderer's Markdown grammar. */
-const structureParser = new MarkdownIt({ html: true });
+import { blockTokens } from "./markdown-blocks.mjs";
 
 /** Body lines occupied by code or raw HTML, including comment examples. */
 function literalHeadingLines(source) {
     const lines = new Set();
-    for (const token of structureParser.parse(String(source ?? ""), {})) {
+    for (const token of blockTokens(source)) {
         if (!token.map || !["fence", "code_block", "html_block"].includes(token.type)) continue;
         for (let line = token.map[0]; line < token.map[1]; line++) lines.add(line);
     }

package/engine/language-writings.mjs

@@ -80,8 +80,13 @@ function oneOf(form, candidates) {
     return { ambiguous: { form, glosses: candidates.map(({ gloss }) => gloss) } };
 }
 
+/** Each language data's writings, by encoding and face. */
+const writingsFound = new WeakMap();
+
 /**
- * The writings of a language's words under one encoding in one face.
+ * The writings of a language's words under one encoding in one face. One
+ * `data` yields one set of writings per encoding and face, and each word's
+ * writing is found once, so `data` must not be modified once it is read here.
  *
  * @param {Record<string, any>|undefined} data - The language note's `data`.
  * @param {string} enc - The encoding's name.
@@ -90,6 +95,34 @@ function oneOf(form, candidates) {
  *   The writing of a run's word, and of the `data.words` entry at an index.
  */
 export function writingsOf(data, enc, font) {
+    if (!isMap(data)) return findWritings(data, enc, font);
+    if (!writingsFound.has(data)) writingsFound.set(data, new Map());
+    const byFace = writingsFound.get(data);
+    const key = JSON.stringify([enc, font ?? null]);
+    if (!byFace.has(key)) {
+        const found = findWritings(data, enc, font);
+        const words = new Map();
+        byFace.set(key, {
+            word: (written) => {
+                if (!words.has(written)) words.set(written, found.word(written));
+                return words.get(written);
+            },
+            entry: found.entry,
+        });
+    }
+    return byFace.get(key);
+}
+
+/**
+ * The writings of a language's words under one encoding in one face, found
+ * afresh; see {@link writingsOf}.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @param {string} enc - The encoding's name.
+ * @param {string|undefined} font - The face.
+ * @returns {{word: (word: string) => Writing, entry: (index: number) => Writing}}
+ */
+function findWritings(data, enc, font) {
     const words = listOf(data?.words);
     const affixes = listOf(data?.affixes).filter(isMap);
     const grammar = isMap(data?.grammar) ? data.grammar : undefined;

package/engine/markdown-blocks.mjs

@@ -0,0 +1,58 @@
+/*
+ * 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 block structure of a Markdown source, in the renderer's grammar.
+ *
+ * Several scanners ask only where a source's fences, code blocks, raw HTML and
+ * quotes lie, each reading block tokens' `type`, `map` and `level` and nothing
+ * else. Inline parsing fills only an `inline` token's `children`, so this
+ * parser skips it, and the block tokens it yields are the ones a full parse
+ * yields. The scanners commonly ask about the same source in turn, so the most
+ * recent sources' tokens are kept.
+ *
+ * @module
+ */
+
+import MarkdownIt from "markdown-it";
+
+/** The renderer's block grammar, with inline parsing and its passes switched off. */
+const parser = new MarkdownIt({ html: true });
+parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
+
+/** How many recent sources keep their tokens. */
+const RECENT = 16;
+
+/** @type {Map<string, import("markdown-it").Token[]>} */
+const recent = new Map();
+
+/**
+ * The block tokens of a Markdown source. The array is shared between callers
+ * and must not be modified; an `inline` token carries no `children`.
+ *
+ * @param {unknown} source - Markdown.
+ * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
+ */
+export function blockTokens(source) {
+    const text = String(source ?? "");
+    const hit = recent.get(text);
+    if (hit) {
+        recent.delete(text);
+        recent.set(text, hit);
+        return hit;
+    }
+    const tokens = parser.parse(text, {});
+    recent.set(text, tokens);
+    if (recent.size > RECENT) recent.delete(recent.keys().next().value);
+    return tokens;
+}

package/package.json

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

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

@@ -225,10 +225,12 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @param {Map<string, {raw: string}>} [options.sources] - Selected captured source strings.
  * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Session scanner projections.
  * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
+ * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [options.timings] -
+ *   Invocation stage accounting, which records each phase of the derivation.
  * @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, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, timings, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -257,6 +259,17 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
     }> | undefined;
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
     nameTypes?: Iterable<string> | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
@@ -301,9 +314,11 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Session scanner projections.
  * @param {Iterable<string>} [opts.nameTypes] - Bare name kinds, defaulting to configured item types.
  * @param {Map<string, object>} [opts.foreignIndex] - Captured dependency address view.
+ * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [opts.timings] -
+ *   Invocation stage accounting.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, timings, }?: {
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
     config?: object | undefined;
@@ -322,6 +337,17 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
     nameTypes?: Iterable<string> | undefined;
     foreignIndex?: Map<string, object> | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): object[];
 /**
  * Prepare the complete bodies a content-index publication describes.

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

@@ -27,6 +27,7 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
     timings?: {
         sync<T>(name: string, work: () => T): T;
         measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        start(name: string): () => void;
         hit(name: string): void;
         snapshot(): {
             totalMs: number;

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

@@ -4,6 +4,13 @@ export function createContentTimings(): {
     sync<T>(name: string, work: () => T): T;
     /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
     measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+    /**
+     * Open a stage that runs until the returned function is called, or
+     * until the stage it was opened in ends.
+     * @param {string} name
+     * @returns {() => void}
+     */
+    start(name: string): () => void;
     /** @param {string} name */
     hit(name: string): void;
     snapshot(): {