@heroiclands/package-build 22.21.0 → 22.23.0

package/types/engine/heading-attributes.d.mts

@@ -0,0 +1,179 @@
+/**
+ * Read a heading's text and the attribute block it may end with.
+ *
+ * A suffix that is not an attribute block — a set written in braces, a die
+ * expression — is left in the text and reported, so no surface silently prints
+ * a heading with words missing and no author is told to fix nothing.
+ *
+ * **One mistake draws one finding.** Braces holding nothing the grammar
+ * recognises are reported once, naming the braces: an author who wrote
+ * `{a, b}` meant no attribute block at all, and a complaint per fragment inside
+ * it says the same thing twice in words that name neither the heading nor the
+ * fix. Braces that *are* an attribute block, carrying one bad attribute beside
+ * good ones, relay the grammar's own complaint about that attribute.
+ *
+ * @param {string} heading - A heading's text, hashes already removed.
+ * @returns {{text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], braces: boolean}}
+ *   `text` is what a surface sets, `braces` whether a suffix was there at all.
+ */
+export function splitHeadingAttributes(heading: string): {
+    text: string;
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+    problems: string[];
+    braces: boolean;
+};
+/**
+ * Whether a heading opens a journal page.
+ *
+ * A Foundry UUID addresses a page and nothing smaller, so a section a link can
+ * reach has to be one: a top-level heading starts a page, and so does any
+ * heading that names an anchor. {@link module:engine/journals.splitPages}
+ * decides *where* a page begins — a heading inside a fence or a named block is
+ * its business — and asks this which headings are eligible, so no caller
+ * re-decides it.
+ *
+ * @param {{level: number, id: string}} heading - From
+ *   {@link scanHeadingAttributes}, or any `{level, id}` pair.
+ * @returns {boolean} Whether the heading opens a page.
+ */
+export function opensPage({ level, id }: {
+    level: number;
+    id: string;
+}): boolean;
+/**
+ * Every heading in a body, with what its attribute block declares.
+ *
+ * Fenced code is skipped: `#` opens a comment in most of what gets fenced, and
+ * an example heading in a document is not a heading of it.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a
+ *   finding lands where an editor can open it.
+ * @returns {{headings: Array<{level: number, line: number, text: string,
+ *   id: string, classes: string[], values: Record<string, string>}>,
+ *   errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanHeadingAttributes(source: string, bodyLine?: number): {
+    headings: Array<{
+        level: number;
+        line: number;
+        text: string;
+        id: string;
+        classes: string[];
+        values: Record<string, string>;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * A markdown-it plugin writing a heading's attribute block onto its element.
+ *
+ * The website's renderer reads the block itself, so the surfaces that use
+ * markdown-it read it here and publish the same `id`, the same classes and the
+ * same attributes — rather than typesetting the braces an author wrote.
+ *
+ * @param {object} md - A markdown-it instance.
+ * @returns {void}
+ */
+export function headingAttributesPlugin(md: object): void;
+/**
+ * Parse one line as a heading, and say whether it starts a journal page.
+ *
+ * The single reading of that rule. {@link module:engine/journals.splitPages}
+ * builds its pages from it; `scanBlocks` and `scanFigures` refuse a heading
+ * that starts a page written where it cannot become one. All three ask this, so
+ * none of them can disagree about what a heading line means or about what starts
+ * a page — and the attribute block comes off here, so a class beside an anchor
+ * is not read as part of the anchor by any of them.
+ *
+ * @param {string} line - One line of a note's body.
+ * @returns {{level: number, text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], startsPage: boolean}|null}
+ *   `null` when the line is not a heading.
+ */
+export function parseHeadingLine(line: string): {
+    level: number;
+    text: string;
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+    problems: string[];
+    startsPage: boolean;
+} | null;
+/**
+ * Every heading that opens a journal page, by the line it sits on.
+ *
+ * The walk that decides it: fenced code holds no headings, a named block holds
+ * no page — the block is one passage of the page it is written in — and what is
+ * left is read by {@link opensPage}. {@link module:engine/journals.splitPages}
+ * builds the pages from this, and the passes that honour a class on a
+ * page-opening heading ask the same question of the same answer.
+ *
+ * A figure fence also opens a page, which is `splitPages`' business: a fence is
+ * found by the figure pass, and the page it opens is named for its label.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {ReadonlySet<number>} [blockLines] - The 0-based lines sitting inside
+ *   a named block, supplied by the caller. A named block is read by
+ *   {@link module:engine/content-blocks.scanBlocks}, which knows every name in
+ *   the registry, reads an opener's attribute block, and tracks nesting by
+ *   depth — so the caller that already holds that answer passes it rather than
+ *   a second reading of the same lines being kept here.
+ * @returns {Map<number, {level: number, line: number, text: string, id: string,
+ *   classes: string[], values: Record<string, string>}>} Keyed by 0-based line.
+ */
+export function pageOpenings(source: string, blockLines?: ReadonlySet<number>): Map<number, {
+    level: number;
+    line: number;
+    text: string;
+    id: string;
+    classes: string[];
+    values: Record<string, string>;
+}>;
+/**
+ * The spans a `.secret` heading withholds, and the classes written where no
+ * surface can honour them.
+ *
+ * A span runs from its heading to the line before the next heading that opens a
+ * page, which is the stretch Foundry makes one page of. A `.secret` on a heading
+ * that opens no page covers no page, so no surface can withhold it: that is a
+ * finding at the heading's own line rather than a class quietly ignored.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{sections: Array<{start: number, end: number, heading: object}>,
+ *   errors: Array<{line: number, column: number, message: string}>}} `start` and
+ *   `end` are 0-based line indexes, `end` exclusive.
+ */
+export function withheldSections(source: string, bodyLine?: number): {
+    sections: Array<{
+        start: number;
+        end: number;
+        heading: object;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * A heading line: its hashes and the text after them.
+ *
+ * Shared with every pass that has to find a heading before reading what it
+ * declares, so the passes cannot disagree about which lines are headings.
+ */
+export const HEADING_LINE: RegExp;
+/**
+ * The class that withholds a section from players.
+ *
+ * Written on the heading that opens the section, so the section stays linkable:
+ * secrecy is a property of the section, not of the name a link resolves to.
+ */
+export const WITHHELD_CLASS: "secret";

package/types/engine/helpers.d.mts

@@ -1,5 +1,21 @@
-/** Render a note body with Foundry's secret section markup. */
-export function renderFoundryMarkdown(body: any, captions: any, footnoteNumbers: any, docId: any): string;
+/**
+ * Render a note body with Foundry's named-block markup.
+ *
+ * @param {string} body - The body, tables expanded and wikilinks resolved.
+ * @param {Array<{id: string, label: string}>} [figures] - Labels assigned by
+ *   a note-wide scan, matched by id — see
+ *   {@link module:engine/content-figures.renderFigureBlocks}.
+ * @param {Map<string, number>} [footnoteNumbers] - Shared across the note.
+ * @param {string} [docId] - Threaded into footnote anchors.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares — see
+ *   {@link module:engine/content-figures.scanFigures}.
+ * @returns {string} The rendered HTML.
+ */
+export function renderFoundryMarkdown(body: string, figures?: Array<{
+    id: string;
+    label: string;
+}>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined): string;
 /**
  * Parses a markdown file with YAML frontmatter.
  *
@@ -206,11 +222,11 @@ export function makeFilename(name: string, id: string): string;
  * the other.
  *
  * **`title` does not follow this rule**, and must not be made to. On a
- * `type: affiliation` note `title` is *also* a declared item field whose default
- * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
- * key the site emitter reads as the page title — so `title: null` stringifies
- * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means.
+ * `type: affiliation` note `title` is a declared item field with its own
+ * default (`""`, in `sohl/item-fields.mjs`), authored only inside the item's
+ * own `sohl` block — the closed top-level vocabulary has no `title` entry, so
+ * there is no shared key for this function's null-versus-blank distinction to
+ * apply to.
  *
  * **`banner:` does not follow it either, deliberately.** It is not a file
  * inside a Foundry install: it reaches no compiled document and no book, its
@@ -426,18 +442,21 @@ export function convertNoteWikilinks(body: string, { type, id, pack, docPack, in
     unresolved: Array<object>;
 };
 /**
- * Expand prepared SQL tables before resolving wikilinks in generated cells.
+ * Expand prepared SQL tables and page lists before resolving wikilinks in the
+ * links they generate.
  * @param {string} body - The note body.
- * @param {object} ctx - Source and prepared query results.
+ * @param {object} ctx - Source and prepared results.
  * @param {string} ctx.name - Name used in diagnostics.
  * @param {number} [ctx.bodyLine] - The first body line in the source file.
  * @param {object[]} [ctx.sqlTables] - Prepared SQL results in document order.
+ * @param {object[]} [ctx.pageLists] - Prepared page lists in document order.
  * @returns {{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}
  */
-export function expandNoteTables(body: string, { name, bodyLine, sqlTables }: {
+export function expandNoteTables(body: string, { name, bodyLine, sqlTables, pageLists }: {
     name: string;
     bodyLine?: number | undefined;
     sqlTables?: object[] | undefined;
+    pageLists?: object[] | undefined;
 }): {
     markdown: string;
     lineMap: Array<{

package/types/engine/homepage.d.mts

@@ -119,7 +119,7 @@ export function checkHomepageCount(found: ReadonlyArray<{
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
  * authored `name.full` wins, because a front page may greet a reader
- * differently from a package browser. A top-level `title` is also readable.
+ * differently from a package browser.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -244,12 +244,12 @@ export const HOMEPAGE_DESTINATION: string;
  * `name` and `shortcode` are permitted: the shortcode is what a link is
  * written with, and `name` titles the page like every other note's.
  *
- * **A named class, not an allow-list, and that boundary is the decision.** A
- * homepage's frontmatter is *emitted into the published page*
- * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
- * parameter this build has never heard of and has no standing to refuse.
- * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release.
+ * **A named class, not an allow-list, and that boundary is the decision.**
+ * What this class answers is a key the top-level vocabulary *accepts* and a
+ * homepage still cannot use, which is a different question from an unknown
+ * key: the frontmatter lint refuses those for every note alike, naming the
+ * closed vocabulary, so repeating that judgement per type would be a second
+ * answer to one question.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
  * on every note whatever its type, so it is answered there rather than

package/types/engine/index.d.mts

@@ -61,6 +61,7 @@ export * as contentCharset from "./content-charset.mjs";
 export * as contentIcons from "./content-icons.mjs";
 export * as contentHtml from "./content-html.mjs";
 export * as contentImages from "./content-images.mjs";
+export * as contentTaskLists from "./content-tasklists.mjs";
 export * as contentEmbeds from "./content-embeds.mjs";
 export * as pathnames from "./pathnames.mjs";
 export * as contentLinks from "./content-links.mjs";

package/types/engine/infobox-registry.d.mts

@@ -51,14 +51,17 @@ export function compilesSystemDocument(fm: object, map: object, router: object):
  * @param {object} [options.router] - The pack router deciding which system
  *   compiles a document for this note. Defaults to the consuming repository's.
  * @param {object} [options.dates] - Calendar conversion context.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @returns {object[]} The boxes, in the order every medium renders them.
  * @throws {Error} When the built set disagrees with what the note's type maps
  *   to — see {@link module:engine/infobox.assertInfoboxSet}.
  */
-export function noteInfoboxes(fm: object, { resolve, router, dates }?: {
+export function noteInfoboxes(fm: object, { resolve, router, dates, contentPackage }?: {
     resolve?: ((ref: unknown, hint?: object) => object | undefined) | undefined;
     router?: object | undefined;
     dates?: object | undefined;
+    contentPackage?: string | undefined;
 }): object[];
 /**
  * Every system's infobox declaration, in the order a page shows them.

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

@@ -54,12 +54,17 @@ export function sectionHasContent(section: object): boolean;
  * reference, so the link works on paper as a cross-reference and in a PDF
  * viewer as a jump. Everything else is set as its own words.
  *
+ * A panel's rows address pages the same way prose does, so a page the book does
+ * not print is set as the absolute URL a reader can follow — see
+ * {@link module:engine/pdf-render.absolutePageUrl}.
+ *
  * @param {object} value - A `link` value.
  * @param {Map<string, string>} links - Address slug → the book's anchor.
  * @param {(anchor: string) => string} labelFor - The anchor's Typst label.
+ * @param {string} [site] - The absolute address this book's pages are served at.
  * @returns {string} Typst markup.
  */
-export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string): string;
+export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string, site?: string): string;
 /**
  * Every box as one Typst panel each, breaking between sections.
  *

package/types/engine/infobox.d.mts

@@ -154,12 +154,15 @@ export function linkValue(ref: unknown, resolve: (ref: unknown, hint?: object) =
  * @param {object} [options] - Options.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a relation row's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @param {object} [options.presentation] - The overlay to read.
  * @returns {object} The box.
  */
 export function noteInfobox(fm: object, options?: {
     resolve?: ((ref: unknown) => object | undefined) | undefined;
+    contentPackage?: string | undefined;
     vocabulary?: object | undefined;
     presentation?: object | undefined;
 }): object;
@@ -268,6 +271,8 @@ export function systemRowsSection(fm: object, fields: readonly object[], { block
  *   Resolves one declared field against the note.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @returns {object[]} The boxes.
  */
@@ -277,6 +282,7 @@ export function buildInfoboxes(fm: object, options: {
     compilesDocument: (fm: object, map: object) => boolean;
     resolveField: (field: object, fm: object, opts: object) => object;
     resolve?: ((ref: unknown) => object | undefined) | undefined;
+    contentPackage?: string | undefined;
     vocabulary?: object | undefined;
 }): object[];
 /**

package/types/engine/journals.d.mts

@@ -1,10 +1,11 @@
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
- * code blocks are respected so `# foo` inside ``` blocks doesn't trigger
- * a split. Content before the first H1 (if non-empty) becomes a leading
- * page. Each H1 yields a page whose name is the heading
+ * code blocks are respected so `# foo` inside ``` or ~~~ blocks doesn't
+ * trigger a split. Content before the first H1 (if non-empty) becomes a
+ * leading page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
- * `anchorSlug`).
+ * `anchorSlug`). The classes the heading declares come along as `classes`, so
+ * a surface that honours one has it without reading the suffix again.
  *
  * `leadName` names that leading page. A journal note's is "Introduction",
  * because it introduces the pages that follow. An item doc's is the item — a
@@ -12,15 +13,26 @@
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
+ * A figure fence carries its own record along onto the page it starts, as
+ * `figure` — `null` for a page a heading started. {@link buildPages} reads it
+ * to build the `image` or `text` page a fence begins; nothing else sets it.
+ *
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   markdown: string}>} Pages in document order.
+ *   classes: string[], figure: object|null, markdown: string}>} Pages in
+ *   document order.
  */
-export function splitPages(body: string, leadName?: string): Array<{
+export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
+    classes: string[];
+    figure: object | null;
     markdown: string;
 }>;
 /**
@@ -97,13 +109,24 @@ export function journalPageId(entryId: string, page: {
  * @param {Array<object>} rawPages - From {@link splitPages}.
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {string} noteName - The note, for error messages.
+ * A page whose heading carries `.secret` is given to the GM alone, by the one
+ * ownership value Foundry reads as "nobody but a GM". Every other page states
+ * no ownership and inherits the journal's. A figure-started page states none
+ * either: {@link scanFigures} validates a figure's classes against its own
+ * closed vocabulary, which carries no `.secret`.
+ *
+ * @param {Array<object>} figures - From {@link scanFigures}, numbered across
+ *   the whole note. Read by a page a heading started; a page a figure started
+ *   carries its own figure already, from {@link splitPages}.
+ * @param {(address: string) => string|undefined} [resolveRole] - See
+ *   {@link splitPages}.
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
- *   text: {format: number, content: string}, _key: string}>} The page
- *   documents, in order.
+ *   text: {format: number, content: string}, _key: string,
+ *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
-export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, captions: any): Array<{
+export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, figures: Array<object>, resolveRole?: (address: string) => string | undefined): Array<{
     _id: string;
     name: string;
     type: string;
@@ -116,6 +139,9 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
         content: string;
     };
     _key: string;
+    ownership?: {
+        default: number;
+    };
 }>;
 /**
  * Assemble one JournalEntry document from a note's converted markdown.
@@ -133,7 +159,6 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  * @param {string} [params.leadName] - Name for the page before the first
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
- * @param {object} [params.flags] - Document flags.
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
@@ -148,15 +173,18 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
+ * @param {(address: string) => string|undefined} [params.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure page's
+ *   name reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infoboxes, notice, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, }: {
     id: string;
     name: string;
     markdown: string;
     leadName?: string | undefined;
     folder?: string | null | undefined;
-    flags?: object | undefined;
     stats?: object | undefined;
     infoboxes?: {
         id: string;
@@ -164,6 +192,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
         html: string;
     }[] | undefined;
     notice?: string | undefined;
+    resolveRole?: ((address: string) => string | undefined) | undefined;
 }): object;
 /**
  * Journals pack compiler.

package/types/engine/lore-events.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Validate one `lore` note's `data.events`.
+ *
+ * Registered as the `events` field's own `check` in `note-vocabulary.mjs`, so
+ * it runs on every `lore` note regardless of `subType` — an occasion is not a
+ * calendar fact, and nothing here is scoped to `subType: calendar`.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @param {{index?: object}} [options]
+ * @returns {object[]} Findings, each positioned at the entry that earned it.
+ */
+export function checkLoreEvents(note: object, { index }?: {
+    index?: object;
+}): object[];

package/types/engine/markdown-expressions.d.mts

@@ -3,15 +3,59 @@ export function sqlQueriesInMarkdown(body: any, fm?: {}): any[];
 /**
  * Expand scalar frontmatter references and registered functions in Markdown prose.
  * @param {string} body
- * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>, file?: string, bodyLine?: number}} [options]
+ * @param {{fm?: object, dates?: object, sqlResults?: Map<string, object>,
+ *   figures?: {get: (id: string) => {label: string, caption: string,
+ *   hasCaption: boolean}|undefined, note?: (address: string) =>
+ *   {url: string|null, figures: Map<string, object>}|undefined,
+ *   link?: Function}, file?: string, bodyLine?: number}} [options] -
+ *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
+ *   note's `:::figure` fences by id, and `note` resolves another note's the
+ *   way a wikilink would — omitted, a cross-note address is refused rather
+ *   than looked up. `link` overrides how a resolved reference renders; the
+ *   default is a Markdown link to the target's own anchor.
  */
-export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, file, bodyLine }?: {
+export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults, figures, file, bodyLine }?: {
     fm?: object;
     dates?: object;
     sqlResults?: Map<string, object>;
+    figures?: {
+        get: (id: string) => {
+            label: string;
+            caption: string;
+            hasCaption: boolean;
+        } | undefined;
+        note?: (address: string) => {
+            url: string | null;
+            figures: Map<string, object>;
+        } | undefined;
+        link?: Function;
+    };
     file?: string;
     bodyLine?: number;
 }): {
     markdown: string;
     findings: any[];
 };
+/**
+ * An inline expression, as an author writes one.
+ *
+ * Hugo shortcodes begin `{{<` or `{{%` and stay in the source for Hugo.
+ *
+ * Exported because a renderer that meets one has met a body this pass never ran
+ * over, and has to be able to say so.
+ *
+ * @type {RegExp}
+ */
+export const EXPRESSION: RegExp;
+/**
+ * Each helper's parameters and what it does, keyed by name.
+ *
+ * The authoring document describes this surface, and a test holds the two
+ * together. A consumer reads it to list what an expression may call.
+ *
+ * @type {Readonly<Record<string, Readonly<{params: string, summary: string}>>>}
+ */
+export const EXPRESSION_HELPERS: Readonly<Record<string, Readonly<{
+    params: string;
+    summary: string;
+}>>>;

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

@@ -91,8 +91,71 @@ export function formatNoteDate(date: any, era: any, daysPerYear: any, formatName
     text: string;
     prose: string | null;
 } | null;
+/**
+ * The occurrences of one recurring series overlapping a bound.
+ *
+ * **No materialized occurrence list.** An annual series anchored centuries
+ * back has thousands of occurrences to the present, and the only questions a
+ * build asks are "is this year one of them" and "which is next" — so an
+ * omitted bound answers with a single occurrence rather than every one a live
+ * series could have:
+ *
+ * - `to` omitted: the first occurrence at or after `from` (default, the
+ *   anchor's own year) — "next".
+ * - `from` omitted, `to` given: the last occurrence at or before `to` —
+ *   "the greatest occurrence at or before `until`".
+ * - Both given: every occurrence between them, inclusive — a membership
+ *   probe is `from === to`.
+ *
+ * **The lower bound is not optional.** A candidate year before the anchor's
+ * own year is never an occurrence, however a bare modulo would read it: `%`
+ * takes the sign of its dividend in both JavaScript and SQL, so a year
+ * exactly one period before the anchor would otherwise match. `k` is clamped
+ * at zero rather than left to run negative.
+ *
+ * **The period advances the canonical year, never the era-relative year.**
+ * `date.canonicalYear` is already on the continuous axis `canonicalYear`
+ * builds — era year `-1` sits immediately before era year `1`, but canonical
+ * year `0` is an ordinary integer between them — so stepping by whole
+ * multiples of `every` on `canonicalYear` crosses an epoch with no special
+ * case. Counting in era-relative years instead would need a correction at
+ * every crossing and silently loses one year each time it is forgotten.
+ *
+ * **Precision, approximation and the day of year carry through untouched.**
+ * Every occurrence is the anchor's own record with only `canonicalYear`
+ * advanced, so a day-precision anchor's `canonicalDay` — including one inside
+ * a short intercalary month — names the same day of every occurrence, and an
+ * approximate anchor's occurrences are approximate too.
+ *
+ * @param {object} date - The anchor's resolved record
+ *   ({@link parseNoteDate}), carrying a real `canonicalYear`. A year-0 "any
+ *   year" anchor carries none and has no series through this function — its
+ *   `recurs` is refused, and its own next occurrence is computed directly
+ *   from the day of year alone.
+ * @param {{every?: number, on?: object[]}} [recurs] - The declared
+ *   recurrence: a whole-year period, or an enumeration of further resolved
+ *   date records (each already carrying its own `canonicalYear`). Neither
+ *   admits the other.
+ * @param {object} [bounds]
+ * @param {number} [bounds.from] - The lower bound, inclusive, as a canonical
+ *   year.
+ * @param {number} [bounds.to] - The upper bound, inclusive, as a canonical
+ *   year.
+ * @returns {object[]} Occurrence records, in increasing order.
+ */
+export function occurrencesOf(date: object, recurs?: {
+    every?: number;
+    on?: object[];
+}, { from, to }?: {
+    from?: number | undefined;
+    to?: number | undefined;
+}): object[];
 /** Normalize a note's declared dates for indexes and generated pages. */
-export function resolvedDateFields(fm: any, context: any): {};
+export function resolvedDateFields(fm: any, context: any): {
+    events: any;
+} | {
+    events?: undefined;
+};
 /**
  * The literal that says a thing happened and the date is not recorded.
  *

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

@@ -1,10 +1,7 @@
 /** Return authored keys from an opening YAML frontmatter map. */
 export function authoredNoteKeys(markdown: any): string[];
-/** The complete ordered top-level vocabulary for addressed content notes. */
-export const NOTE_TOP_LEVEL_KEYS: readonly string[];
-/** Membership test for the top-level vocabulary. */
-export const NOTE_TOP_LEVEL_KEY_SET: Set<string>;
 /** The name properties every note accepts, in display order. */
 export const NOTE_NAME_KEYS: readonly string[];
 /** Additional name components accepted by an individual character. */
 export const CHARACTER_NAME_KEYS: readonly string[];
+export { NOTE_TOP_LEVEL_FIELDS, NOTE_TOP_LEVEL_KEYS, NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";