@heroiclands/package-build 23.8.0 → 23.10.0

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

@@ -0,0 +1,108 @@
+/**
+ * Capture one source tree for index, lint, links and compilation.
+ * No source or parser state is persisted or reused by another invocation.
+ * Prepared SQL databases close within their existing preparation functions.
+ * @param {object} [options]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.config] - Exact resolved configuration.
+ * @param {string} [options.contentBase] - Content root, defaulting to configuration.
+ * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
+ * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
+ * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
+ */
+export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, }?: {
+    config?: import("../content-config.mjs").ContentBuildConfig | undefined;
+    contentBase?: string | undefined;
+    assetsBase?: string | undefined;
+    skipDirectories?: readonly string[] | undefined;
+    router?: {
+        resolve: (fm: object, docType: string, system?: string) => string | undefined;
+        resolveOrNull: (fm: object, docType: string, system?: string) => string | undefined;
+        packsOfType: (docType: string) => string[];
+        defaultOf: (docType: string) => string | undefined;
+    } | undefined;
+}): Promise<ContentSession>;
+/**
+ * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
+ * @typedef {(source: string) => {blocks: ReturnType<typeof blocks.scanBlocks>, alerts: ReturnType<typeof alerts.scanAlerts>, spans: ReturnType<typeof spans.scanSpans>}} ContentSyntax
+ * @typedef {{config?: import("../content-config.mjs").ContentBuildConfig, contentBase?: string, assetsBase?: string, skipDirectories?: readonly string[], router?: ReturnType<typeof routerFor>}} ContentSessionContext
+ * @typedef {{frontmatter: object|null, body: string, raw: string, bodyLine?: number, bodyColumn?: number}} ContentNoteSource
+ * @typedef {object} ContentSession
+ * @property {import("../content-config.mjs").ContentBuildConfig} config
+ * @property {string} contentBase
+ * @property {string} assetsBase
+ * @property {readonly string[]} skipDirectories
+ * @property {ReturnType<typeof routerFor>} router
+ * @property {ReturnType<typeof captureContentSources>} inventory
+ * @property {Map<string, {raw: string}>} sources
+ * @property {object[]} records
+ * @property {Map<string, ContentNoteSource>} parsed
+ * @property {object[]} problems
+ * @property {ReturnType<typeof loadForeignIndexes>} foreign
+ * @property {ContentSyntax} syntax
+ * @property {(options?: ContentSessionContext) => void} assertContext
+ * @property {(audience?: "all"|"public") => ReturnType<typeof sql.prepareTreeSqlTables>} sqlTables
+ * @property {() => ReturnType<typeof sql.prepareLinkSqlTables>} linkTables
+ * @property {(kind?: "lint"|"links") => Promise<ReturnType<typeof buildLinkIndex>>} audit
+ * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
+ * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
+ * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {() => void} dispose
+ */
+/**
+ * The explicit runner's target vocabulary and execution order.
+ * @type {readonly ContentTarget[]}
+ */
+export const CONTENT_TARGETS: readonly ContentTarget[];
+export type ContentTarget = "index" | "lint" | "links" | "compile";
+export type ContentSyntax = (source: string) => {
+    blocks: ReturnType<typeof blocks.scanBlocks>;
+    alerts: ReturnType<typeof alerts.scanAlerts>;
+    spans: ReturnType<typeof spans.scanSpans>;
+};
+export type ContentSessionContext = {
+    config?: import("../content-config.mjs").ContentBuildConfig;
+    contentBase?: string;
+    assetsBase?: string;
+    skipDirectories?: readonly string[];
+    router?: ReturnType<typeof routerFor>;
+};
+export type ContentNoteSource = {
+    frontmatter: object | null;
+    body: string;
+    raw: string;
+    bodyLine?: number;
+    bodyColumn?: number;
+};
+export type ContentSession = {
+    config: import("../content-config.mjs").ContentBuildConfig;
+    contentBase: string;
+    assetsBase: string;
+    skipDirectories: readonly string[];
+    router: ReturnType<typeof routerFor>;
+    inventory: ReturnType<typeof captureContentSources>;
+    sources: Map<string, {
+        raw: string;
+    }>;
+    records: object[];
+    parsed: Map<string, ContentNoteSource>;
+    problems: object[];
+    foreign: ReturnType<typeof loadForeignIndexes>;
+    syntax: ContentSyntax;
+    assertContext: (options?: ContentSessionContext) => void;
+    sqlTables: (audience?: "all" | "public") => ReturnType<typeof sql.prepareTreeSqlTables>;
+    linkTables: () => ReturnType<typeof sql.prepareLinkSqlTables>;
+    audit: (kind?: "lint" | "links") => Promise<ReturnType<typeof buildLinkIndex>>;
+    publication: () => Promise<import("./content-index.mjs").PreparedContentIndex>;
+    compileCorpus: () => ReturnType<typeof import("./compile-corpus.mjs").buildCompileCorpus>;
+    prepare: (targets: readonly ContentTarget[]) => Promise<ContentSession>;
+    dispose: () => void;
+};
+import * as blocks from "./content-blocks.mjs";
+import * as alerts from "./content-alerts.mjs";
+import * as spans from "./content-spans.mjs";
+import { routerFor } from "./pack-router.mjs";
+import { captureContentSources } from "./content-sources.mjs";
+import { loadForeignIndexes } from "./metadata-index.mjs";
+import * as sql from "./sql-tables.mjs";
+import { buildLinkIndex } from "./content-links.mjs";

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

@@ -0,0 +1,32 @@
+/**
+ * Capture exact text once and retain directory entries for physical checks.
+ * The index walk and raw check walks retain their established traversal orders.
+ * @param {string} contentBase - Absolute content root.
+ * @param {string} assetsBase - Absolute assets root.
+ * @param {readonly string[]} skipDirectories - Resolved directory scope.
+ * @returns {{sources: Map<string, {raw: string}>, indexSources: Map<string, {raw: string}>, paths: Array<{root: string, file: string, name: string, directory: boolean}>}} Captured input and physical walk order.
+ */
+export function captureContentSources(contentBase: string, assetsBase: string, skipDirectories: readonly string[]): {
+    sources: Map<string, {
+        raw: string;
+    }>;
+    indexSources: Map<string, {
+        raw: string;
+    }>;
+    paths: Array<{
+        root: string;
+        file: string;
+        name: string;
+        directory: boolean;
+    }>;
+};
+/**
+ * Select the exact physical scope of a raw checker from a captured map.
+ * @param {string} contentBase - Content root.
+ * @param {Map<string, {raw: string}>} sources - Captured physical sources.
+ * @param {readonly string[]} skipDirectories - Directory names to ignore.
+ * @param {Set<string>} extensions - Lowercase extensions accepted by the caller.
+ */
+export function capturedSources(contentBase: string, sources: Map<string, {
+    raw: string;
+}>, skipDirectories: readonly string[], extensions: Set<string>): Generator<string[], void, unknown>;

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

@@ -4,15 +4,13 @@
 export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
 /** Read span anchors and located attribute diagnostics outside literal code.
  * @param {string} source - Authored Markdown.
+ * @returns {import("./name-markup.mjs").SpanScan} Actual spans, explicit names and located diagnostics.
  */
-export function scanSpans(source: string): {
-    spans: any[];
-    errors: any[];
-};
+export function scanSpans(source: string): import("./name-markup.mjs").SpanScan;
 /** Emit span tags while leaving their inline content as Markdown for Hugo.
  * @param {string} source - Authored Markdown.
  */
 export function renderSpans(source: string): {
     markdown: string;
-    errors: any[];
+    errors: import("./name-markup.mjs").SpanFinding[];
 };

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

@@ -12,7 +12,8 @@
  *   Prepared results.
  * A note's generated sections — see {@link module:engine/generated-sections} —
  * are appended to the body first, from the `generated` text the preparation
- * set on its results, and expanded with it.
+ * set on its results, and expanded with it. Automatic lexical lists, carried
+ * on `lexical`, then fill their authored sections or append a new section.
  *
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[],
  *   generatedFrom?: number}} `generatedFrom` is the 0-based line of the

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

@@ -43,12 +43,16 @@ export function checkTaskLists(body: string, file: string, { bodyLine, bodyColum
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
  *   in addition to the dot-directories always skipped.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Exact captured source strings; omitted, walks and reads the tree.
  * @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 }?: {
+export function lintContentTaskLists(contentBase: string, { skipDirectories, sources }?: {
     skipDirectories?: readonly string[] | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
 }): {
     findings: Array<{
         file: string;

package/types/engine/culture-reach.d.mts

@@ -32,12 +32,15 @@ export function glossaryCorpus(index: object): GlossaryCorpus;
  *
  * @param {object} index - The link index.
  * @param {object} note - The culture or affiliation note.
+ * @param {object} [entry] - A glossary entry, whose resolved language selects
+ *   its dictionary words. Absent, the note's own language is used.
  * @returns {Map<string, string[]>} The terms; empty for a note no source reaches.
  */
-export function noteTerms(index: object, note: object): Map<string, string[]>;
+export function noteTerms(index: object, note: object, entry?: object): Map<string, string[]>;
 /**
  * Warn of an affiliation that reaches no culture, its own or one it inherits,
- * in a tree that describes peoples.
+ * in a tree that describes peoples. Its ranks and offices then have no
+ * culture associations for term queries.
  *
  * @param {object} note - An `affiliation` note.
  * @param {{index?: object}} [context]
@@ -63,4 +66,21 @@ export type GlossaryCorpus = {
      * give it.
      */
     terms: Map<string, Map<string, string[]>>;
+    /**
+     * - The ranks and
+     * offices each owner can name.
+     */
+    governance: Map<string, Map<string, string[]>>;
+    /**
+     * - Each
+     * language's dictionary words.
+     */
+    words: Map<string, Array<{
+        form: string;
+        gloss: unknown;
+    }>>;
+    /**
+     * - Each language's parent.
+     */
+    families: Map<string, string | undefined>;
 };

package/types/engine/data-keys.d.mts

@@ -13,6 +13,8 @@
  *   every surface shows it exactly as written, never recased.
  * @property {string} shape - The shape in words, for a finding and the reference.
  * @property {boolean} [required] - The key must be stated, with a value.
+ * @property {boolean} [allowEmpty] - A required string may be empty where
+ *   empty text is a stated value.
  * @property {boolean} [nullable] - An explicit `null` states the key, for a
  *   required key whose null has a meaning of its own.
  * @property {string} [label] - The infobox row label, where humanising the key
@@ -117,6 +119,11 @@ export type InnerKeySpec = {
      * - The key must be stated, with a value.
      */
     required?: boolean | undefined;
+    /**
+     * - A required string may be empty where
+     * empty text is a stated value.
+     */
+    allowEmpty?: boolean | undefined;
     /**
      * - An explicit `null` states the key, for a
      * required key whose null has a meaning of its own.

package/types/engine/diagnostics.d.mts

@@ -1,3 +1,13 @@
+/**
+ * Split opening YAML frontmatter from its untrimmed body without parsing it.
+ * LF and CRLF delimiters retain the exact source strings and their offsets.
+ * @param {string} raw - Complete Markdown source.
+ * @returns {{yaml: string, body: string}|null} Source slices, or no fence.
+ */
+export function splitFrontmatter(raw: string): {
+    yaml: string;
+    body: string;
+} | null;
 /**
  * The `file:line:column` locator, with whatever is known.
  *

package/types/engine/dictionary-layout.d.mts

@@ -1,3 +1,11 @@
+/**
+ * Render a dictionary entry's marked headword as an inline native heading in
+ * Foundry. Its paragraph becomes a div, so the heading has a valid container.
+ * The shared Markdown keeps its span and its containing journal page.
+ *
+ * @param {import("markdown-it")} md - The Foundry Markdown parser.
+ */
+export function dictionaryEntryPlugin(md: typeof import("markdown-it")): void;
 /**
  * @typedef {object} LayoutOptions
  * @property {(ref: object) => boolean} [linkable] - Whether an Address can be
@@ -6,10 +14,16 @@
  * @property {object} [addressContext] - Address resolution context.
  * @property {(address: string) => string|undefined} [labelOf] - A note's
  *   `name.full`, by its Address.
- * @property {boolean|"only"} [showKey=true] - Whether the key is printed;
- *   `"only"` prints the key and nothing else.
+ * @property {boolean|"only"} [showKey=true] - Whether the key and dictionary
+ *   head tables are printed; `"only"` prints the key and nothing else.
  * @property {string} [pageLanguage] - The language of the page the fence is
  *   on, which no entry is tagged with.
+ * @property {string} [pageOwner] - The containing page's canonical note Address;
+ *   a sense attributed only to its own row's owner omits that label on this page.
+ * @property {boolean} [entryAnchors=true] - Whether dictionary headwords carry
+ *   their canonical targets; custom SQL views leave those to the automatic list.
+ * @property {object} [verbs] - The owning language's stated pattern, including
+ *   when its automatic dictionary has no eligible word entries.
  */
 /**
  * Render a result of words as a dictionary.
@@ -44,6 +58,8 @@ export const LAYOUT_REQUIRED_COLUMNS: Readonly<{
 }>;
 /** The mark a common entry opens with. */
 export const COMMON_MARK: "\u2022";
+/** The word-entry span class whose Foundry rendering is a native TOC heading. */
+export const DICTIONARY_ENTRY_CLASS: "dictionary-entry";
 export type LayoutOptions = {
     /**
      * - Whether an Address can be
@@ -64,8 +80,8 @@ export type LayoutOptions = {
      */
     labelOf?: ((address: string) => string | undefined) | undefined;
     /**
-     * - Whether the key is printed;
-     * `"only"` prints the key and nothing else.
+     * - Whether the key and dictionary
+     * head tables are printed; `"only"` prints the key and nothing else.
      */
     showKey?: boolean | "only" | undefined;
     /**
@@ -73,4 +89,19 @@ export type LayoutOptions = {
      * on, which no entry is tagged with.
      */
     pageLanguage?: string | undefined;
+    /**
+     * - The containing page's canonical note Address;
+     * a sense attributed only to its own row's owner omits that label on this page.
+     */
+    pageOwner?: string | undefined;
+    /**
+     * - Whether dictionary headwords carry
+     * their canonical targets; custom SQL views leave those to the automatic list.
+     */
+    entryAnchors?: boolean | undefined;
+    /**
+     * - The owning language's stated pattern, including
+     * when its automatic dictionary has no eligible word entries.
+     */
+    verbs?: object | undefined;
 };

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

@@ -1,3 +1,12 @@
+/**
+ * The stable prose anchor of a word in one language's dictionary. The exact
+ * language and NFC form identify it, including case and accents.
+ *
+ * @param {string} language - The language's canonical note Address.
+ * @param {string} name - The dictionary headword.
+ * @returns {string} The anchor slug.
+ */
+export function dictionaryEntryAnchor(language: string, name: string): string;
 /**
  * The heading letter of a sort key: its first letter or digit, accents taken
  * off and apostrophes skipped, in capitals; `#` where it has none.

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

@@ -6,15 +6,29 @@
  * @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[]}}
+ * @param {boolean} [options.positions=false] - Retain the first supplied
+ *   attribute's key/value ranges as UTF-16 offsets within this input.
+ * @returns {{id: string, classes: string[], values: Record<string, string>, problems: string[],
+ *   positions?: Record<string, {key: {start: number, end: number}, value: {start: number, end: number}}>}}
  */
-export function parseExtensionAttributes(source: string, { idPattern }?: {
+export function parseExtensionAttributes(source: string, { idPattern, positions }?: {
     idPattern?: RegExp | undefined;
+    positions?: boolean | undefined;
 }): {
     id: string;
     classes: string[];
     values: Record<string, string>;
     problems: string[];
+    positions?: Record<string, {
+        key: {
+            start: number;
+            end: number;
+        };
+        value: {
+            start: number;
+            end: number;
+        };
+    }>;
 };
 /** A Boolean attribute is spelled exactly `true` or `false`. */
 export function booleanAttribute(value: any, key: any): boolean;

package/types/engine/first-use.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Prepare indexed names once, then check only explicit occurrences without reading files.
+ * @param {{records: readonly object[], index: object,
+ *   catalog?: import("./names.mjs").NameCatalog,
+ *   parsed?: Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>,
+ *   syntax?: import("./content-session.mjs").ContentSyntax}} options - Lint's
+ *   records/resolver and optional captured authored-body projections.
+ * @returns {(note: {file: string, raw: string}) => Array<{file: string, line: number, column: number, severity: "warning", rules: string[], message: string}>} Located warning diagnostics.
+ */
+export function createFirstUseChecker({ records, index, parsed, syntax, catalog, }: {
+    records: readonly object[];
+    index: object;
+    catalog?: import("./names.mjs").NameCatalog;
+    parsed?: Map<string, {
+        raw: string;
+        body: string;
+        bodyLine?: number;
+        bodyColumn?: number;
+    }>;
+    syntax?: import("./content-session.mjs").ContentSyntax;
+}): (note: {
+    file: string;
+    raw: string;
+}) => Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "warning";
+    rules: string[];
+    message: string;
+}>;

package/types/engine/foundry-entries.d.mts

@@ -1,5 +1,7 @@
 /**
- * Every page of a note's journal, as `anchorName → whole UUID`.
+ * Every anchor of a note's journal, as `anchorName → Foundry target`.
+ * A dictionary word's native heading carries its fragment after the
+ * containing page's UUID.
  *
  * Whole, not a fragment appended to the entry's UUID: nothing owns a page
  * address, so a complete link restates no fact, and it keeps the page-id hash
@@ -11,9 +13,10 @@
  * @param {string} entryId - The entry's id, which page ids hash against.
  * @param {string} body - The note's markdown body.
  * @param {string} name - The note's name, used as the lead page's title.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session scanner projections.
  * @returns {Record<string, string>} The anchors.
  */
-export function anchorsOf(entryUuid: string, entryId: string, body: string, name: string): Record<string, string>;
+export function anchorsOf(entryUuid: string, entryId: string, body: string, name: string, syntax?: import("./content-session.mjs").ContentSyntax): Record<string, string>;
 /**
  * The manifest entries a single note produces.
  *
@@ -35,11 +38,17 @@ export function anchorsOf(entryUuid: string, entryId: string, body: string, name
  * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
  * what lets the content index publish an identity it did not re-derive.
  *
- * @param {object} ctx - Resolved identities: `{ contentPackage,
- *   foundryPackageId, packRouter }`.
+ * @param {{contentPackage: string, foundryPackageId: string, packRouter: object, web?: boolean, skipDirectories?: readonly string[], syntax?: import("./content-session.mjs").ContentSyntax}} ctx - Resolved identities and optional session scanner projections.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.
  */
-export function entriesForNote(fm: object, name: string, address: string, body: string, ctx: object): Array<object>;
+export function entriesForNote(fm: object, name: string, address: string, body: string, ctx: {
+    contentPackage: string;
+    foundryPackageId: string;
+    packRouter: object;
+    web?: boolean;
+    skipDirectories?: readonly string[];
+    syntax?: import("./content-session.mjs").ContentSyntax;
+}): Array<object>;
 /**
  * Every note this package publishes, as manifest entries.
  *

package/types/engine/generate.d.mts

@@ -201,12 +201,16 @@ export function emptyPassErrors(passes: Array<{
  *   package's tree — and how the guard-order test below induces id drift, now
  *   that the manifest is located by configuration rather than by the working
  *   directory.
+ * @param {import("./content-session.mjs").ContentSession} [opts.session] - Same configuration, root and scope as this generation.
+ * @param {boolean} [opts.reportPreparation=true] - Emit shared preparation findings; false when already reported by the caller.
  * @returns {Promise<number>} Total error count across the generated packs.
  * @throws {Error} If the configured Foundry package id has drifted from the
  *   shipped manifest's `id` (see `package-manifest.mjs`).
  */
-export function generatePacksJson({ only, config }?: {
+export function generatePacksJson({ only, config, session, reportPreparation, }?: {
     only?: string | undefined;
     config?: object | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
+    reportPreparation?: boolean | undefined;
 }): Promise<number>;
 export function packJsonDir(name: string, config?: object): string;

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

@@ -46,8 +46,8 @@ export function opensPage({ level, id }: {
 /**
  * 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.
+ * Code and raw HTML blocks are skipped: an example heading in a document is
+ * not a heading of it, including an example in an HTML comment.
  *
  * @param {string} source - A note's markdown body.
  * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a

package/types/engine/helpers.d.mts

@@ -17,7 +17,7 @@ export function renderFoundryMarkdown(body: string, figures?: Array<{
     label: string;
 }>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined): string;
 /**
- * Parses a markdown file with YAML frontmatter.
+ * Parses a markdown file with LF or CRLF YAML frontmatter delimiters.
  *
  * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
@@ -29,13 +29,19 @@ export function renderFoundryMarkdown(body: string, figures?: Array<{
  * `{ frontmatter: null, body: "", description: "", raw }` and no
  * position: there is no body to have one.
  * @param {string} filePath - Markdown file to read.
- * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
+ * @param {object} [opts]
+ * @param {object} [opts.addressContext] - Address defaults for decoded fields.
+ * @param {string} [opts.raw] - Exact captured source; omitted, reads the file.
+ * @param {boolean} [opts.renderDescription=true] - Render the body's HTML description.
+ *   False leaves `description` empty for readers that only use authored text.
  * @returns {{frontmatter: object|null, body: string, description: string, raw: string,
  *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
  *   line?: number, column?: number}}} Parsed note and body position.
  */
-export function parseMarkdownFile(filePath: string, { addressContext }?: {
-    addressContext?: object;
+export function parseMarkdownFile(filePath: string, { addressContext, raw: capturedRaw, renderDescription }?: {
+    addressContext?: object | undefined;
+    raw?: string | undefined;
+    renderDescription?: boolean | undefined;
 }): {
     frontmatter: object | null;
     body: string;
@@ -105,17 +111,24 @@ export function assertSuppliedCorpus(records: readonly object[] | undefined, who
  *   Required: the scope is the caller's to state, so two passes cannot
  *   disagree about which files are the corpus.
  * @param {object} [opts.addressContext] - Address resolution context.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Selected sources in walk order.
+ *   Supplied, the walk parses these strings instead of reading the filesystem.
+ * @param {boolean} [opts.renderDescription=true] - Render each body's description.
  * @yields {{frontmatter: object|null, body: string, description: string,
  *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
  *   One entry per `.md` file found.
  * @throws {Error} When `skipDirectories` is not stated — see
  *   {@link assertStatedScope}.
  */
-export function walkMarkdownTree(rootDir: string, { skipDirectories, addressContext }?: {
+export function walkMarkdownTree(rootDir: string, { skipDirectories, addressContext, sources, renderDescription }?: {
     skipDirectories: readonly string[];
     addressContext?: object | undefined;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
+    renderDescription?: boolean | undefined;
 }): Generator<{
-    file: string & NonSharedBuffer;
+    file: string;
     absPath: string;
     frontmatter: object | null;
     body: string;
@@ -364,11 +377,24 @@ export function defaultStats(): object;
  *   omitted.
  * @param {readonly object[]} [opts.records] - The corpus, derived once per
  *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
+ * @param {Map<string, object[]>} [opts.sqlTables] - Prepared directives,
+ *   including the anchors and Foundry page maps of their expanded bodies.
+ * @param {ReturnType<import("./metadata-index.mjs").loadForeignIndexes>} [opts.foreign] -
+ *   Captured dependency address and reference views for this context.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
-export function buildContentLinkIndex(contentBase: string, router?: object, { config, records }?: {
+export function buildContentLinkIndex(contentBase: string, router?: object, { config, records, sqlTables, foreign: capturedForeign }?: {
     config?: object | undefined;
     records?: readonly object[] | undefined;
+    sqlTables?: Map<string, object[]> | undefined;
+    foreign?: {
+        index: Map<string, object>;
+        packages: Set<string>;
+        stale: Array<{
+            package: string;
+            reason: string;
+        }>;
+    } | undefined;
 }): {
     byShortcode: Map<any, any>;
     types: Set<any>;

package/types/engine/index.d.mts

@@ -50,6 +50,7 @@ export * as noteIds from "./note-ids.mjs";
 export * as metadataIndex from "./metadata-index.mjs";
 export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
+export * as contentSession from "./content-session.mjs";
 export * as assetTypes from "./asset-types.mjs";
 export * as assetIndex from "./asset-index.mjs";
 export * as assetShipping from "./asset-shipping.mjs";

package/types/engine/journals.d.mts

@@ -29,11 +29,12 @@
  *   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}.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session scanner projections.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
  *   classes: string[], figure: object|null, continues?: string,
  *   markdown: string}>} Pages in document order.
  */
-export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined): Array<{
+export function splitPages(body: string, leadName?: string, resolveRole?: (address: string) => string | undefined, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     name: string;
     anchorSlug: string | null;
     level: number;
@@ -190,9 +191,10 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   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}.
+ * @param {import("./content-session.mjs").ContentSyntax} [params.syntax] - Session scanner projections.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, syntax, }: {
     id: string;
     name: string;
     markdown: string;
@@ -206,6 +208,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, stats,
     }[] | undefined;
     notice?: string | undefined;
     resolveRole?: ((address: string) => string | undefined) | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
 }): object;
 /**
  * Journals pack compiler.

package/types/engine/language-terms.d.mts

@@ -319,6 +319,13 @@ export const NEAR_NAME_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[]
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */
 export const NAMING_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
+/**
+ * The six present persons of the one optional regular verb pattern, in
+ * presentation order. Empty endings leave the citation form unchanged.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const VERB_PERSON_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
  * The `data` fields this module declares, in the order the vocabulary lists
  * them. {@link module:engine/language-data.checkLanguageData} checks what the