@heroiclands/package-build 22.21.0 → 22.22.0

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

@@ -1,13 +1,21 @@
 /**
- * Replace prepared SQL fences with Markdown tables while retaining source lines.
- * Query execution happens in the asynchronous SQL preparation pass.
+ * Replace prepared SQL fences and page lists with Markdown while retaining
+ * source lines.
+ *
+ * Both directives read the content index, so both are answered before this
+ * pass runs — query execution in the asynchronous SQL preparation pass, page
+ * lists in {@link module:engine/page-lists.preparePageLists} — and each is
+ * looked up by the ordinal of its own kind of fence within the body.
+ *
  * @param {string} markdown - The authored body.
- * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @param {{source?: string, sqlTables?: object[], pageLists?: object[]}} [context] -
+ *   Prepared results.
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-export function expandContentTables(markdown: string, { source, sqlTables }?: {
+export function expandContentTables(markdown: string, { source, sqlTables, pageLists }?: {
     source?: string;
     sqlTables?: object[];
+    pageLists?: object[];
 }): {
     markdown: string;
     errors: object[];

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

@@ -0,0 +1,72 @@
+/**
+ * What a note opening a list item with `[ ]` or `[x]` is told.
+ *
+ * @param {string} marker - The matched marker, as written.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function taskListMessage(marker: string): string;
+/**
+ * Every list item opened with `[ ]` or `[x]` in one note's body.
+ *
+ * @param {string} body - The note's markdown, without its frontmatter.
+ * @param {string} file - The note's path, for the finding.
+ * @param {object} [opts]
+ * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
+ * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>} One finding per item, in source
+ *   order.
+ */
+export function checkTaskLists(body: string, file: string, { bodyLine, bodyColumn }?: {
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+}): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    message: string;
+}>;
+/**
+ * Walk a content tree and report every list item opened with `[ ]` or `[x]`.
+ *
+ * The frontmatter fence is taken off first, so what is scanned is the body and
+ * the positions are still the file's. A file with no frontmatter is scanned
+ * whole: it is not a note, but a stray `.md` in the tree carrying the marker is
+ * the same problem for the same reason.
+ *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "warning", message: string}>, files: number}} The findings, and
+ *   how many files were read.
+ */
+export function lintContentTaskLists(contentBase: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "warning";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * A list item's marker, immediately followed by `[ ]` or `[x]` and a space —
+ * bulleted (`-`, `*`, `+`) or ordered (`1.` or `1)`), at the start of a line.
+ *
+ * The leading indentation is a lookbehind rather than part of the match, so a
+ * nested item's finding points at the marker itself, not at the line's first
+ * column.
+ *
+ * @type {RegExp}
+ */
+export const TASK_LIST_MARKER: RegExp;

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

@@ -2,9 +2,15 @@
  * Read the shared braced attribute grammar used by body extensions.
  * Callers validate which names and classes their extension understands.
  * @param {string} source - Text inside the braces.
+ * @param {object} [options={}]
+ * @param {RegExp} [options.idPattern=NAME] - What an `#id` may be named. A
+ *   construct whose id is published as an HTML `id` admits a digit first and
+ *   passes a looser pattern; the default is the pattern every other name takes.
  * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[]}}
  */
-export function parseExtensionAttributes(source: string): {
+export function parseExtensionAttributes(source: string, { idPattern }?: {
+    idPattern?: RegExp | undefined;
+}): {
     id: string;
     classes: string[];
     values: Record<string, string>;
@@ -12,3 +18,18 @@ export function parseExtensionAttributes(source: string): {
 };
 /** A Boolean attribute is spelled exactly `true` or `false`. */
 export function booleanAttribute(value: any, key: any): boolean;
+/**
+ * The attribute keys no construct writes onto an element.
+ *
+ * `id=` and `class=` are refused in favour of `#id` and `.class`, which the
+ * grammar already states; a key beginning `on` is an event handler, and nothing
+ * authored in a note becomes code on a published page.
+ *
+ * Shared by every construct that writes an author's attributes onto an element,
+ * because a refusal that held on one and not the next would be the hole the
+ * other construct is checked for.
+ *
+ * @param {Record<string, string>} values - The `key=value` attributes parsed.
+ * @returns {string[]} One message per refused key, in the order written.
+ */
+export function refusedAttributes(values: Record<string, string>): string[];

package/types/engine/frontmatter.d.mts

@@ -137,7 +137,7 @@ export function resolveRelation(fm: object, ctx?: string): Record<string, string
  *
  * @param {object} fm - The item frontmatter.
  * @param {string} [ctx] - Optional label for the error (defaults to the item's
- *   title/name, else "item").
+ *   display name, else "item").
  * @returns {string} The declared subType.
  * @throws {Error} When `subType` is missing or blank.
  */

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

@@ -0,0 +1,174 @@
+/**
+ * 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 captioned heading and a heading inside a
+ * fence or a named block are 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 `scanCaptions` 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 caption also opens a page, which is `splitPages`' business: a caption is
+ * found by the caption pass, and a heading it captions is listed here and
+ * dropped there.
+ *
+ * @param {string} source - A note's markdown body.
+ * @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): 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,4 +1,4 @@
-/** Render a note body with Foundry's secret section markup. */
+/** Render a note body with Foundry's named-block markup. */
 export function renderFoundryMarkdown(body: any, captions: any, footnoteNumbers: any, docId: any): string;
 /**
  * Parses a markdown file with YAML frontmatter.
@@ -426,18 +426,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-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/journals.d.mts

@@ -4,7 +4,8 @@
  * 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
@@ -15,12 +16,13 @@
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   markdown: string}>} Pages in document order.
+ *   classes: string[], markdown: string}>} Pages in document order.
  */
 export function splitPages(body: string, leadName?: string): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
+    classes: string[];
     markdown: string;
 }>;
 /**
@@ -97,10 +99,14 @@ 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.
+ *
  * @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<{
@@ -116,6 +122,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 +142,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
@@ -150,13 +158,12 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   before they read it rather than after.
  * @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, }: {
     id: string;
     name: string;
     markdown: string;
     leadName?: string | undefined;
     folder?: string | null | undefined;
-    flags?: object | undefined;
     stats?: object | undefined;
     infoboxes?: {
         id: string;

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

@@ -15,3 +15,26 @@ export function renderMarkdownExpressions(body: string, { fm, dates, sqlResults,
     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-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";

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

@@ -42,8 +42,6 @@ export function exclusiveTagGroups(type: string, groups?: object): {
  * The spelling of the tag *itself* still is — a near miss is a near miss, and
  * the frontmatter lint is what reports it; nothing here guesses.
  *
- * Reads `tags` and the singular `tag` spelling.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {string} tag - The tag to look for, in its declared spelling.
  * @returns {boolean} Whether the note carries it.
@@ -135,6 +133,59 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * One top-level frontmatter key.
+ *
+ * Narrower than a {@link DataFieldSpec}: the top level is a fixed list rather
+ * than a per-type vocabulary, nothing there is keyed by pack or resolved as an
+ * Address, and the value's shape is checked by whatever owns the region the key
+ * opens — `name`, `tags` and each system block each have their own check.
+ *
+ * @typedef {object} TopLevelFieldSpec
+ * @property {string} name - The key, as a note writes it.
+ * @property {boolean} [system] - The key opens a game system's block, so it is
+ *   one of {@link module:engine/systems.SYSTEM_IDS} rather than a fixed key.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * **The top-level vocabulary**, in the order a formatted note writes it.
+ *
+ * The region describes the note as a published artefact: what it is called,
+ * what kind of thing it is about, how it is classified, and which of the other
+ * two regions it opens. Everything else a note states is a fact about the
+ * subject, which belongs under `data:`, or a fact about one system's document,
+ * which belongs inside that system's block.
+ *
+ * **Closed, like the other two regions.** A key this list does not name is a
+ * finding at its own line, because a region that passed one through would turn
+ * a misspelling into a value nothing reads — `title` beside `name`, or `pack`
+ * where `data.pack` was meant.
+ *
+ * **The system blocks are derived from the system registry**, so recognising a
+ * further system is a change to {@link module:engine/systems.SYSTEM_IDS} and to
+ * nothing else. They sort by name after the fixed keys: a block is the largest
+ * thing a note writes, every one of them belongs at the end, and a rule a
+ * reader can restate in one sentence is worth more than a hand-kept order.
+ *
+ * Five readers derive from this one list — the frontmatter lint's accepted set,
+ * the message it prints, the formatter's key order, the content-format check,
+ * and the author-facing reference — so none of them can fall behind the others.
+ *
+ * @type {readonly TopLevelFieldSpec[]}
+ */
+export const NOTE_TOP_LEVEL_FIELDS: readonly TopLevelFieldSpec[];
+/**
+ * The top-level keys, in formatted order.
+ *
+ * @type {readonly string[]}
+ */
+export const NOTE_TOP_LEVEL_KEYS: readonly string[];
+/**
+ * Membership test for the top-level vocabulary.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NOTE_TOP_LEVEL_KEY_SET: ReadonlySet<string>;
 /**
  * The `data:` keys **every** note type accepts, whatever it is.
  *
@@ -174,15 +225,17 @@ export const GM_TAG: "gm";
 /**
  * The tags that **classify** a note, grouped by what they classify.
  *
- * `tags:` lives at the open top level and most tags belong there: a theme, a
- * region, a working state is the author's own and this build has no opinion
- * about it. A classifying tag is different, because something queries it — a
+ * `tags:` holds an open vocabulary of *values*, and most tags belong there: a
+ * theme, a region, a working state is the author's own and this build has no
+ * opinion about it. A classifying tag is different, because something queries
+ * it — a
  * settlement tagged `village` appears in the list of villages and an untagged
  * one does not, so `vilage` does not merely look wrong, it removes the note from
  * an index while the index still renders a table that looks complete.
  *
  * **This list is not a closed set.** An unrecognised tag is legal, because the
- * region is open; what is reported is a **near miss** — a tag close enough to a
+ * values are the author's; what is reported is a **near miss** — a tag close
+ * enough to a
  * declared one to be a typo of it.
  *
  * **Each group names the types it applies to**, and that scope is what makes the
@@ -418,3 +471,26 @@ export type TypeVocabulary = {
         index?: object;
     }) => object[]) | undefined;
 };
+/**
+ * One top-level frontmatter key.
+ *
+ * Narrower than a {@link DataFieldSpec}: the top level is a fixed list rather
+ * than a per-type vocabulary, nothing there is keyed by pack or resolved as an
+ * Address, and the value's shape is checked by whatever owns the region the key
+ * opens — `name`, `tags` and each system block each have their own check.
+ */
+export type TopLevelFieldSpec = {
+    /**
+     * - The key, as a note writes it.
+     */
+    name: string;
+    /**
+     * - The key opens a game system's block, so it is
+     * one of {@link module :engine/systems.SYSTEM_IDS} rather than a fixed key.
+     */
+    system?: boolean | undefined;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};