@heroiclands/package-build 23.9.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-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/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/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

@@ -13,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.
  *
@@ -37,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/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;
@@ -366,12 +379,22 @@ export function defaultStats(): object;
  *   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, sqlTables }?: {
+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/lexical-sections.d.mts

@@ -35,15 +35,16 @@ export function lexicalSectionsFor(records: object[], all?: object[]): Map<strin
  *
  * @param {string} markdown - The body with authored directives expanded.
  * @param {LexicalSection[]} [sections=[]] - From {@link lexicalSectionsFor}.
- * @param {{authored?: string, lineMap?: object[], generatedFrom?: number}} [context] -
+ * @param {{authored?: string, lineMap?: object[], generatedFrom?: number, syntax?: import("./content-session.mjs").ContentSyntax}} [context] -
  *   The original authored body, source mappings and the start of appended
  *   nonlexical generated sections. Without `authored`, `markdown` is the source.
  * @returns {{markdown: string, lineMap: object[], generatedFrom?: number}}
  */
-export function insertLexicalSections(markdown: string, sections?: LexicalSection[], { authored, lineMap, generatedFrom }?: {
+export function insertLexicalSections(markdown: string, sections?: LexicalSection[], { authored, lineMap, generatedFrom, syntax }?: {
     authored?: string;
     lineMap?: object[];
     generatedFrom?: number;
+    syntax?: import("./content-session.mjs").ContentSyntax;
 }): {
     markdown: string;
     lineMap: object[];

package/types/engine/markup-validation.d.mts

@@ -3,9 +3,10 @@
  * Frontmatter is masked so literal YAML values cannot become body markup.
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
  */
-export function markupFindings(source: string, file: string): Array<{
+export function markupFindings(source: string, file: string, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     file: string;
     line: number;
     column: number;

package/types/engine/name-markup.d.mts

@@ -0,0 +1,176 @@
+/** Pure projections of parsed inline text and original marked-name positions. */
+/**
+ * An original source range with its opening file position.
+ * @typedef {object} SpanSourceSite
+ * @property {number} start - Inclusive UTF-16 source offset.
+ * @property {number} end - Exclusive UTF-16 source offset.
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ */
+/**
+ * The retained attribute key and value at their authored positions.
+ * @typedef {object} SpanAttributePosition
+ * @property {SpanSourceSite} key - Attribute name, without surrounding whitespace.
+ * @property {SpanSourceSite} value - Authored value, without its surrounding quotes.
+ */
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ * @typedef {object} ContentSpan
+ * @property {string} id - Normalized anchor, or an empty string.
+ * @property {number} start - Inclusive UTF-16 offset of the opening bracket.
+ * @property {number} end - Exclusive UTF-16 offset after the complete span.
+ * @property {number} line - Original 1-based line of the opening bracket.
+ * @property {number} column - Original 1-based UTF-16 column of the bracket.
+ * @property {string} text - Inline label source passed to the existing parser.
+ * @property {number} contentEnd - Original UTF-16 offset of the closing label bracket.
+ * @property {string} visible - Visible text from the actual parsed children.
+ * @property {ReadonlyArray<readonly [string, string]>} attrs - Retained permitted HTML attributes.
+ * @property {Record<string, SpanAttributePosition>} attributePositions - Authored key/value sites by retained attribute name.
+ */
+/**
+ * One located span-grammar or refused-attribute finding.
+ * @typedef {object} SpanFinding
+ * @property {number} line - Original 1-based source line.
+ * @property {number} column - Original 1-based UTF-16 source column.
+ * @property {string} message - The existing grammar or attribute diagnostic.
+ */
+/**
+ * A captured authored span inventory.
+ * @typedef {object} SpanScan
+ * @property {ContentSpan[]} spans - All actual parsed bracketed spans in source order.
+ * @property {ContentSpan[]} names - The same span objects carrying the exact name class.
+ * @property {SpanFinding[]} errors - Located diagnostics in source order.
+ */
+/**
+ * Visible name text from the renderer's actual parsed children. Footnote
+ * markers and images supply no name text; references have already resolved.
+ * @param {readonly object[]} tokens - Parsed inline tokens.
+ * @returns {string} Text without inline formatting or annotation markers.
+ */
+export function inlineText(tokens: readonly object[]): string;
+/**
+ * Rebase an authored body's captured names to its original raw file.
+ * The inventory is read only; no source parsing or second marker scan occurs.
+ * @template {ContentSpan} Span
+ * @param {readonly Span[]} spans - The captured body's name spans.
+ * @param {{raw: string, bodyLine?: number, bodyColumn?: number}} source - Original body origin.
+ * @returns {Span[]} Copies retaining the span metadata with raw offsets and file coordinates.
+ */
+export function rebaseNameSpans<Span extends ContentSpan>(spans: readonly Span[], { raw, bodyLine, bodyColumn }: {
+    raw: string;
+    bodyLine?: number;
+    bodyColumn?: number;
+}): Span[];
+/**
+ * An original source range with its opening file position.
+ */
+export type SpanSourceSite = {
+    /**
+     * - Inclusive UTF-16 source offset.
+     */
+    start: number;
+    /**
+     * - Exclusive UTF-16 source offset.
+     */
+    end: number;
+    /**
+     * - Original 1-based source line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 source column.
+     */
+    column: number;
+};
+/**
+ * The retained attribute key and value at their authored positions.
+ */
+export type SpanAttributePosition = {
+    /**
+     * - Attribute name, without surrounding whitespace.
+     */
+    key: SpanSourceSite;
+    /**
+     * - Authored value, without its surrounding quotes.
+     */
+    value: SpanSourceSite;
+};
+/**
+ * One actual bracketed span and its renderer-derived visible text.
+ */
+export type ContentSpan = {
+    /**
+     * - Normalized anchor, or an empty string.
+     */
+    id: string;
+    /**
+     * - Inclusive UTF-16 offset of the opening bracket.
+     */
+    start: number;
+    /**
+     * - Exclusive UTF-16 offset after the complete span.
+     */
+    end: number;
+    /**
+     * - Original 1-based line of the opening bracket.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 column of the bracket.
+     */
+    column: number;
+    /**
+     * - Inline label source passed to the existing parser.
+     */
+    text: string;
+    /**
+     * - Original UTF-16 offset of the closing label bracket.
+     */
+    contentEnd: number;
+    /**
+     * - Visible text from the actual parsed children.
+     */
+    visible: string;
+    /**
+     * - Retained permitted HTML attributes.
+     */
+    attrs: ReadonlyArray<readonly [string, string]>;
+    /**
+     * - Authored key/value sites by retained attribute name.
+     */
+    attributePositions: Record<string, SpanAttributePosition>;
+};
+/**
+ * One located span-grammar or refused-attribute finding.
+ */
+export type SpanFinding = {
+    /**
+     * - Original 1-based source line.
+     */
+    line: number;
+    /**
+     * - Original 1-based UTF-16 source column.
+     */
+    column: number;
+    /**
+     * - The existing grammar or attribute diagnostic.
+     */
+    message: string;
+};
+/**
+ * A captured authored span inventory.
+ */
+export type SpanScan = {
+    /**
+     * - All actual parsed bracketed spans in source order.
+     */
+    spans: ContentSpan[];
+    /**
+     * - The same span objects carrying the exact name class.
+     */
+    names: ContentSpan[];
+    /**
+     * - Located diagnostics in source order.
+     */
+    errors: SpanFinding[];
+};