@heroiclands/package-build 23.10.0 → 23.12.0

package/types/engine/being-age.d.mts

@@ -15,11 +15,9 @@ export function parseAgeMagnitude(raw: unknown): {
  *
  * @param {unknown} bornRaw - The being's authored `born`, or `undefined`/`null`
  *   where it wrote none.
- * @param {unknown} presentRaw - The package's `data.present`, as
- *   {@link module:engine/calendar-notes.worldInvariants} read it, or
- *   `undefined`/`null` where the package states none.
+ * @param {unknown} presentRaw - The configured neutral current date.
  * @returns {number|null} The age, or `null` where `born` is `unknown` or
- *   absent, where no present is declared, or where either date fails to parse.
+ *   absent or future, or where either date fails to parse.
  */
 export function computeAge(bornRaw: unknown, presentRaw: unknown, dateContext?: {}): number | null;
 /**
@@ -35,58 +33,26 @@ export function computeAge(bornRaw: unknown, presentRaw: unknown, dateContext?:
  * itself untouched.
  *
  * @param {object} fm - A note's frontmatter, as freshly parsed.
- * @param {unknown} presentRaw - The package's declared present, or
- *   `undefined`/`null` where it states none.
+ * @param {unknown} presentRaw - The configured neutral current date.
  * @returns {void}
  */
 export function applyComputedBeingAge(fm: object, presentRaw: unknown, dateContext?: {}): void;
 /**
- * A being's `data.present`, read from every `place` note a batch of records or
- * frontmatter objects carries.
- *
- * Two shapes reach this by way of two thin adapters, because the callers that
- * need a present hold their notes two different ways: a flat index record
- * (`type` and `data` at the top level) and a raw walk's `{frontmatter}` pair.
- * Neither shape is the `{fm, type}` pair {@link worldInvariants} reads, so each
- * adapter states the one conversion its caller needs rather than asking every
- * caller to know it.
- *
- * @param {readonly object[]|undefined} records - Flat index records — a
- *   content-index record, or anything else spreading a note's frontmatter to
- *   its own top level.
- * @returns {unknown} The present, or `null` where no `place` note in the batch
- *   declares one.
- */
-export function presentAmongRecords(records: readonly object[] | undefined): unknown;
-/**
- * The present read from a batch of raw frontmatter objects.
- *
- * @param {readonly (object|null|undefined)[]|undefined} frontmatters - One
- *   entry per note walked, as parsed — never a record.
- * @returns {unknown} The present, or `null` where none is declared.
- */
-export function presentAmongFrontmatters(frontmatters: readonly (object | null | undefined)[] | undefined): unknown;
-/**
- * Check a being's authored `age` against what `born` and the package's present
- * compute.
+ * Check an authored age against the birth date and configured current date.
  *
  * Registered as `being`'s whole-note `check` in `note-vocabulary.mjs`, run the
  * way `checkPlace` and `checkCalendarNote` are — beside every other check the
  * closed `data:` container earns, with the same `index`.
  *
- * Two silences, both deliberate: beside `born: unknown` or an absent `born`
- * there is nothing to disagree with, and a package that declares no present
- * computes no age to disagree with either — both cases are read by
- * {@link computeAge} returning `null`, and neither says a word.
+ * An unknown or absent birth date supplies no computed age to compare.
  *
- * @param {object} note - The note, as the link index hands it over —
- *   {@link module:engine/calendar-notes.worldInvariants}'s `index.notes` shape.
+ * @param {object} note - The note, as the link index hands it over.
  * @param {object} [opts]
- * @param {object} [opts.index] - The link index, holding the package's `place`
- *   notes. Its absence skips the check, the way a reference check with no
- *   index skips reporting every reference as dead.
+ * @param {object} [opts.index] - Calendar context for authored birth dates.
+ * @param {string} [opts.currentDate="720.1"] - The configured neutral current date.
  * @returns {object[]} Findings — at most one `warning`, naming both values.
  */
-export function checkBeingAge(note: object, { index }?: {
+export function checkBeingAge(note: object, { index, currentDate }?: {
     index?: object | undefined;
+    currentDate?: string | undefined;
 }): object[];

package/types/engine/calendar-notes.d.mts

@@ -5,13 +5,12 @@
  * note has no year, and every question that depends on one goes unasked.
  *
  * @param {object} [index] - The link index, holding every note in the package.
- * @returns {{year: object|null, present: unknown, moon: object|null,
+ * @returns {{year: object|null, moon: object|null,
  *   body: object|null, moonName: string|null, yearNote: object|null,
  *   moonNote: object|null}} What the package's notes state.
  */
 export function worldInvariants(index?: object): {
     year: object | null;
-    present: unknown;
     moon: object | null;
     body: object | null;
     moonName: string | null;
@@ -41,9 +40,6 @@ export function checkCalendarDateFormats(note: any): {
  * - a moon with no year is refused, because a cycle measured in days has
  *   nothing to be measured against.
  *
- * `data.present` is read through the parser a note's dates go through, with the
- * corpus in hand, so a present written in an era resolves where it is written.
- *
  * @param {object} note - The note, as the link index hands it over.
  * @param {object} [opts]
  * @param {object} [opts.index] - The link index, holding every note.
@@ -185,7 +181,7 @@ export const CALENDAR_FIELDS: readonly object[];
  * The `data:` keys a world or a celestial body may write.
  *
  * Four groups, and which note carries which is a fact about the body rather
- * than a convention: a planet states its own size, tilt, year and present; a
+ * than a convention: a planet states its own size, tilt and year; a
  * moon states its own size, orbit and cycle.
  *
  * @type {readonly object[]}

package/types/engine/compile-corpus.d.mts

@@ -16,7 +16,7 @@
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
  * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
- * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
+ * @returns {Promise<{currentDate: string, records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, session, }: {
@@ -28,6 +28,7 @@ export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, r
     problems?: object[] | undefined;
     session?: import("./content-session.mjs").ContentSession | undefined;
 }): Promise<{
+    currentDate: string;
     records: object[];
     parsed: Map<string, object>;
     linkIndex: object;

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

@@ -234,6 +234,7 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  *   asserts that it does not exist. The same holds for a culture conflict: a
  *   reader receives each as a finding, and the emitter throws once, listing
  *   every one.
+ * @param {string} [options.currentDate="720.1"] - Setting-wide neutral current date.
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
@@ -246,13 +247,14 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
     manifest?: object | undefined;
     addressContext?: object | undefined;
     problems?: object[] | undefined;
+    currentDate?: string | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;

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

@@ -1,7 +1,13 @@
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
+ * @param {object} [options] - Surface presentation.
+ * @param {boolean} [options.source] - Emit opaque authored source tokens for buffer preview.
+ * @param {boolean} [options.spoilers] - Add focusable CSS spoiler wrappers (Foundry).
  */
-export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
+export function spanMarkdownPlugin(md: typeof import("markdown-it"), { spoilers, source }?: {
+    source?: boolean | undefined;
+    spoilers?: boolean | undefined;
+}): 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.

package/types/engine/current-date.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Validate a quoted neutral date and preserve its authored day digits.
+ * @param {unknown} [value] - Explicit configuration or adapter override.
+ * @returns {string} Validated neutral date; undefined selects the default.
+ * @throws {TypeError} An explicit value is not a valid neutral date string.
+ */
+export function normalizeCurrentDate(value?: unknown): string;
+/** Default day on the neutral setting timeline. */
+export const DEFAULT_CURRENT_DATE: "720.1";

package/types/engine/definition-list.d.mts

@@ -0,0 +1,8 @@
+/** Semantic dictionary rows for HTML definition lists. @module */
+/**
+ * Group each term and its definitions without reparsing their Markdown tokens.
+ * Register after markdown-it-deflist; nested blocks and footnotes retain their
+ * document context.
+ * @param {import("markdown-it")} md - An HTML Markdown parser with definition lists.
+ */
+export function dictionaryListPlugin(md: typeof import("markdown-it")): void;

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

@@ -32,6 +32,7 @@ export function systemAddressFindings(note: object, { index, schemas, systems }?
  * @param {object} note - A note from the link index (`{fm, file, raw, type}`).
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {string} [opts.currentDate="720.1"] - Setting-wide neutral date for age checks.
  * @param {object} [opts.index] - The link index, for the reference check, which
  *   runs through its `shortcodeHit`. Its absence skips that check rather than
  *   reporting every reference as dead.
@@ -59,8 +60,9 @@ export function systemAddressFindings(note: object, { index, schemas, systems }?
  *   about those keys.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index, vocabulary, packs, emittedArt, addressContext, systems, }: {
+export function lintNote(note: object, { schemas, index, currentDate, vocabulary, packs, emittedArt, addressContext, systems, }: {
     schemas: Record<string, readonly object[]>;
+    currentDate?: string | undefined;
     index?: object | undefined;
     vocabulary?: Record<string, object> | undefined;
     emittedArt?: ((type: string) => {
@@ -77,6 +79,7 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, emit
  * @param {object} index - From `buildLinkIndex`.
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {string} [opts.currentDate="720.1"] - Setting-wide neutral date for age checks.
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares; see {@link lintNote}.
  * @param {boolean} [opts.references=true] - Whether to check references.
@@ -90,8 +93,9 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, emit
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emittedArt, references, systems }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emittedArt, references, systems, currentDate }: {
     schemas: Record<string, readonly object[]>;
+    currentDate?: string | undefined;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
     systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;

package/types/engine/index.d.mts

@@ -39,6 +39,8 @@ export * as cultureChoice from "./culture-choice.mjs";
 export * as reckoningMarkers from "./reckoning-markers.mjs";
 export * as calendarNotes from "./calendar-notes.mjs";
 export * as calendarArtifacts from "./calendar-artifacts.mjs";
+export * as definitionList from "./definition-list.mjs";
+export * as currentDate from "./current-date.mjs";
 export * as beingAge from "./being-age.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";

package/types/engine/npc-generate.d.mts

@@ -59,7 +59,7 @@ export function appearanceParagraph({ name, age, gender, height, frame, appearan
  *   about a name that does not fit.
  * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
  *   different person from the same spec.
- * @param {unknown} [context.present] - The package's present, or `null`.
+ * @param {unknown} [context.currentDate] - The setting's neutral current date, defaulting to "720.1".
  * @param {object} [context.dateContext] - The reckoning context the present
  *   and `born` are read in, with `daysPerYear`.
  * @param {{icon?: unknown, species?: unknown, packFolder?: unknown}} [context.defaults] -
@@ -75,7 +75,7 @@ export function generateNpc(spec: object, context: {
     names: object;
     language?: string | undefined;
     seed?: string | undefined;
-    present?: unknown;
+    currentDate?: unknown;
     dateContext?: object | undefined;
     defaults?: {
         icon?: unknown;

package/types/engine/preview-current-date.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Read only currentDate from the nearest package configuration.
+ * YAML does not load the full build configuration. An MJS configuration executes
+ * its own module, as any caller opting into a code configuration expects.
+ * @param {string} root - Directory at which configuration discovery starts.
+ * @returns {Promise<string>} Validated neutral current date.
+ */
+export function readPreviewCurrentDate(root: string): Promise<string>;

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

@@ -4,6 +4,8 @@
  * @param {readonly SiteEntry[]} entries - Every page the site will publish,
  *   each already knowing its own `url`.
  * @param {object} [options] - Cross-package inputs.
+ * @param {string} [options.package] - The builder's own content package.
+ * @param {string} [options.currentDate="720.1"] - Setting-wide neutral date for recurring events.
  * @param {Map<string, {package: string, type?: string}>} [options.foreignIndex]
  *   The merged index from `loadForeignIndexes`. Omit when the build publishes
  *   no cross-package links.
@@ -16,7 +18,9 @@
  * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Exact-text scanner projections.
  * @returns {SiteIndex} The index, and what could not be addressed unambiguously.
  */
-export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages, package: builderPackage, records, foreignReferences, syntax, }?: {
+export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, noIndexPackages, package: builderPackage, currentDate, records, foreignReferences, syntax, }?: {
+    package?: string | undefined;
+    currentDate?: string | undefined;
     foreignIndex?: Map<string, {
         package: string;
         type?: string;

package/types/engine/site-preview.d.mts

@@ -1,34 +1,41 @@
-/** Prepare saved project state once, then render live text without writing a site. */
-export function prepareSitePreview({ config }?: {
-    config?: import("../content-config.mjs").ContentBuildConfig | undefined;
-}): Promise<{
-    /** Render the active buffer. Other local and foreign notes remain saved. */
-    render(file: any, text: any): Promise<{
-        ok: boolean;
-        findings: {
-            file: string;
-            severity: string;
-            message: string;
-        }[];
-        markdown?: undefined;
-        frontmatter?: undefined;
-    } | {
-        ok: boolean;
-        findings: {
-            path: string;
-            link: string;
-            file: string;
-            severity: string;
-        }[];
-        markdown?: undefined;
-        frontmatter?: undefined;
-    } | {
-        ok: boolean;
-        markdown: string;
-        frontmatter: any;
-        findings: never[];
-    }>;
-    /** Re-read saved notes and dependency indexes after a save. */
-    refresh(): Promise<void>;
-    close(): Promise<void>;
+/**
+ * Render one complete buffer with no configuration, index, filesystem or database.
+ * @param {string} text - Markdown, optionally beginning with YAML frontmatter.
+ * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string}} [options] - Explicit palette, profile visibility, diagnostic filename and neutral current date (default "720.1").
+ * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null.
+ */
+export function renderPreview(text: string, { dark, infobox, file, currentDate }?: {
+    dark?: boolean;
+    infobox?: boolean;
+    file?: string;
+    currentDate?: string;
+}): {
+    ok: boolean;
+    html: string;
+    frontmatter: object;
+    findings: object[];
+};
+/**
+ * Opt in to reading only the project's currentDate setting; never called by renderPreview.
+ * @param {string} root - Directory from which to find the nearest package configuration.
+ * @returns {Promise<string>} Validated neutral date, or the shared default when no setting is present.
+ */
+export function readPreviewCurrentDate(root: string): Promise<string>;
+/** Both explicit palettes, scoped to the preview container. */
+export function previewStyles(): string;
+/** Explicit dependency policy: a new registered helper requires a preview decision. */
+export const PREVIEW_HELPERS: Readonly<{
+    eq: "local";
+    gt: "local";
+    gte: "local";
+    lt: "local";
+    lte: "local";
+    not: "local";
+    and: "local";
+    or: "local";
+    words: "local";
+    digits: "local";
+    sql: "dependent";
+    dateformat: "dependent";
+    ref: "reference";
 }>;

package/types/engine/wikilink-syntax.d.mts

@@ -9,6 +9,7 @@
  * @property {string} anchor - The `#section` slug, `""` when there is none.
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+ * @property {ReturnType<typeof parseExtensionAttributes>} [attributes] - Trailing extension attributes.
  * @property {boolean} labelled - Whether a `|` was present at all. A link
  *   without one addresses nothing and is a finding — see
  *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
@@ -20,9 +21,10 @@
  * not the whole link, so a caller that has already matched does not re-match.
  *
  * @param {string} rawInner - The text between `[[` and `]]`.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {ParsedWikilink} The parts, each trimmed.
  */
-export function parseWikilink(rawInner: string): ParsedWikilink;
+export function parseWikilink(rawInner: string, literal?: string): ParsedWikilink;
 /**
  * The label an author actually supplied, or `null` when they supplied none.
  *
@@ -158,13 +160,14 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
  *   shortcode as written.
+ * @param {string[]} [finding.problems] - Invalid attribute diagnostics.
  * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
  *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, problems, }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
@@ -172,6 +175,7 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
     type?: string | undefined;
     stub?: string | undefined;
     shortcode?: string | undefined;
+    problems?: string[] | undefined;
     declared?: string | undefined;
 }): string;
 /**
@@ -188,9 +192,23 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * Read an operational link target in its enclosing Address context.
  * @param {string} inner - Lexical link contents.
  * @param {object} context - Builder defaults and type vocabulary.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {object} Typed target and diagnostic source spelling.
  */
-export function readWikilink(inner: string, context: object): object;
+export function readWikilink(inner: string, context: object, literal?: string): object;
+/** Whether the actual referenced destination needs spoiler presentation.
+ * @param {object} destination - Resolved note metadata.
+ * @param {string} [anchor] - Referenced prose anchor.
+ * @returns {boolean} Whole-note or section audience.
+ */
+export function secretDestination(destination: object, anchor?: string): boolean;
+/** Apply destination-derived presentation without changing its address.
+ * @param {string} reference - Rendered reference Markdown.
+ * @param {object} parsed - Shared parsed wikilink.
+ * @param {object} destination - Resolved target metadata.
+ * @returns {string} Inline spoiler or visible reference.
+ */
+export function presentWikilink(reference: string, parsed: object, destination: object): string;
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
@@ -297,6 +315,25 @@ export type ParsedWikilink = {
      * is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
      */
     display: string | null;
+    /**
+     * - Trailing extension attributes.
+     */
+    attributes?: {
+        id: string;
+        classes: string[];
+        values: Record<string, string>;
+        problems: string[];
+        positions?: Record<string, {
+            key: {
+                start: number;
+                end: number;
+            };
+            value: {
+                start: number;
+                end: number;
+            };
+        }>;
+    } | undefined;
     /**
      * - Whether a `|` was present at all. A link
      * without one addresses nothing and is a finding — see