@heroiclands/package-build 23.11.0 → 23.12.0

package/hugo-theme/layouts/_default/list.html

@@ -19,7 +19,7 @@
   <div class="single-content">
     {{ if .Content }}
     <div class="single-body" data-pagefind-body>
-      {{ .Content }}
+      {{ partial "dictionary-lists.html" .Content }}
     </div>
     {{ end }}
 

package/hugo-theme/layouts/blog/list.html

@@ -4,7 +4,7 @@
   <div class="single-content">
     {{ if .Content }}
     <div class="single-body">
-      {{ .Content }}
+      {{ partial "dictionary-lists.html" .Content }}
     </div>
     {{ end }}
 

package/hugo-theme/layouts/blog-post/single.html

@@ -22,7 +22,7 @@
     </div>
 
     <div class="single-body" data-pagefind-body>
-      {{ .Content }}
+      {{ partial "dictionary-lists.html" .Content }}
     </div>
 
     {{ partial "related.html" . }}

package/hugo-theme/layouts/partials/dictionary-lists.html

@@ -0,0 +1,53 @@
+{{- /* Group the final Goldmark HTML. Quote-aware tokens preserve attributes,
+     literal examples, comments and raw blocks; a stack gives each nested list
+     its own rows. Existing grouped lists keep their authored divs. */ -}}
+{{- $source := string . -}}
+{{- if not (findRE `(?i)<dl(?:\s|>)` $source) -}}{{- return ($source | safeHTML) -}}{{- end -}}
+{{- $pattern := `(?is)<!--.*?-->|<script\b(?:[^"'<>]|"[^"]*"|'[^']*')*>.*?</script\s*>|<style\b(?:[^"'<>]|"[^"]*"|'[^']*')*>.*?</style\s*>|<pre\b(?:[^"'<>]|"[^"]*"|'[^']*')*>.*?</pre\s*>|<textarea\b(?:[^"'<>]|"[^"]*"|'[^']*')*>.*?</textarea\s*>|<![^>]*>|</?[a-z][a-z0-9:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>|[^<]+|<` -}}
+{{- $parts := slice -}}
+{{- $lists := slice -}}
+{{- $elements := slice -}}
+{{- $tokens := findRE $pattern $source -}}
+{{- range $i, $token := $tokens -}}
+  {{- if and (gt (len $lists) 0) (gt $i 0) (lt (add $i 1) (len $tokens)) (findRE `^\s+$` $token) (findRE `(?i)^</dt\s*>$` (index $tokens (sub $i 1))) (findRE `(?i)^<dd(?:\s|>)` (index $tokens (add $i 1))) -}}
+    {{- $token = "" -}}
+  {{- end -}}
+  {{- if and (gt (len $lists) 0) (gt $i 0) (lt (add $i 1) (len $tokens)) (findRE `^\s+$` $token) (findRE `(?i)^<dd(?:\s[^>]*)?>$` (index $tokens (sub $i 1))) (findRE `(?i)^<p(?:\s|>)` (index $tokens (add $i 1))) -}}
+    {{- $token = "" -}}
+  {{- end -}}
+  {{- $tag := "" -}}
+  {{- $opaque := findRE `(?i)^<(?:!--|script\b|style\b|pre\b|textarea\b)` $token -}}
+  {{- if and (not $opaque) (findRE `(?i)^</?[a-z]` $token) -}}
+    {{- $tag = lower (replaceRE `(?is)^</?([a-z][a-z0-9:-]*).*` "$1" $token) -}}
+    {{- $closing := hasPrefix $token "</" -}}
+    {{- if and (eq $tag "dl") (not $closing) -}}
+      {{- $list := newScratch -}}
+      {{- $list.Set "row" false -}}
+      {{- $lists = $lists | append $list -}}
+      {{- if or (findRE `(?i)\sclass\s*=\s*["'](?:[^"']*\s)?dictionary(?:\s|["'])` $token) (findRE `(?i)\sclass\s*=\s*dictionary(?:\s|>)` $token) -}}
+      {{- else if findRE `(?i)\sclass\s*=\s*["']` $token -}}
+        {{- $token = replaceRE `(?i)(\sclass\s*=\s*["'])` "${1}dictionary " $token -}}
+      {{- else if findRE `(?i)\sclass\s*=` $token -}}
+        {{- $token = replaceRE `(?i)(\sclass\s*=\s*)([^\s>]+)` `${1}"dictionary ${2}"` $token -}}
+      {{- else -}}
+        {{- $token = replaceRE `(?i)^<dl` `<dl class="dictionary"` $token -}}
+      {{- end -}}
+    {{- else if and (eq $tag "dt") (not $closing) (gt (len $lists) 0) (eq (index $elements (sub (len $elements) 1)) "dl") -}}
+      {{- $list := index $lists (sub (len $lists) 1) -}}
+      {{- if $list.Get "row" -}}{{- $parts = $parts | append "</div>" -}}{{- end -}}
+      {{- $parts = $parts | append "<div>" -}}
+      {{- $list.Set "row" true -}}
+    {{- else if and (eq $tag "dl") $closing (gt (len $lists) 0) -}}
+      {{- $list := index $lists (sub (len $lists) 1) -}}
+      {{- if $list.Get "row" -}}{{- $parts = $parts | append "</div>" -}}{{- end -}}
+      {{- $lists = first (sub (len $lists) 1) $lists -}}
+    {{- end -}}
+    {{- if $closing -}}
+      {{- if gt (len $elements) 0 -}}{{- $elements = first (sub (len $elements) 1) $elements -}}{{- end -}}
+    {{- else if not (or (findRE `/\s*>$` $token) (in (slice "area" "base" "br" "col" "embed" "hr" "img" "input" "link" "meta" "param" "source" "track" "wbr") $tag)) -}}
+      {{- $elements = $elements | append $tag -}}
+    {{- end -}}
+  {{- end -}}
+  {{- $parts = $parts | append $token -}}
+{{- end -}}
+{{- return (delimit $parts "" | safeHTML) -}}

package/hugo-theme/layouts/partials/page-body.html

@@ -67,7 +67,7 @@
     {{ end }}
 
     <div class="single-body" data-pagefind-body>
-      {{ .Content }}
+      {{ partial "dictionary-lists.html" .Content }}
     </div>
 
     {{ partial "related.html" . }}

package/hugo-theme/static/css/style.css

@@ -2955,20 +2955,21 @@ summary.info-sidebar-title::after {
   }
 }
 
-/* GitHub-style author alerts remain open and inherit the prose foreground. */
+/* Author alerts use the dark palette of this site's single-mode theme. */
 .single-content .alert {
   border-inline-start: 0.25rem solid var(--pb-alert-color);
-  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+  padding: 1rem;
   margin: 1rem 0;
-  color: inherit;
-  background: transparent;
+  color: #e6edf3;
+  background: var(--pb-alert-background);
 }
 .single-content .alert-title {
   display: flex;
   align-items: center;
   gap: 0.5em;
   margin: 0 0 0.5rem;
-  font-weight: 600;
+  font-weight: 700;
   color: var(--pb-alert-color);
 }
 .single-content .alert-icon {
@@ -2981,16 +2982,20 @@ summary.info-sidebar-title::after {
   margin-bottom: 0;
 }
 .single-content .alert-note {
-  --pb-alert-color: #4493f8;
+  --pb-alert-color: #58a6ff;
+  --pb-alert-background: #101a28;
 }
 .single-content .alert-tip {
-  --pb-alert-color: #3fb950;
+  --pb-alert-color: #7ee787;
+  --pb-alert-background: #102018;
 }
 .single-content .alert-important {
-  --pb-alert-color: #ab7df8;
+  --pb-alert-color: #c4b0ff;
+  --pb-alert-background: #1c172a;
 }
 .single-content .alert-warning {
   --pb-alert-color: #d29922;
+  --pb-alert-background: #241d10;
 }
 
 /* Inline spoiler controls remain inline, with links outside the button. */
@@ -3008,3 +3013,12 @@ summary.info-sidebar-title::after {
 }
 .inline-secret-toggle:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
 .inline-secret-content { margin-inline-start: 0.25em; }
+
+/* Authored definition lists use dictionary rows; profile grids remain separate. */
+.single-body .dictionary { --indent:150px; --gap:.75em; margin:0; display:block; }
+.single-body .dictionary > div { padding-left:var(--indent); text-indent:calc(-1 * var(--indent)); margin-bottom:.5em; }
+.single-body .dictionary > div > dt { display:inline-block; min-width:calc(var(--indent) - var(--gap)); margin-right:var(--gap); font-weight:bold; white-space:nowrap; text-indent:0; text-align:left; }
+.single-body .dictionary > div > dd { display:inline; margin:0; font-weight:normal; }
+.single-body .dictionary > div > dd > :is(p, ul, ol, dl, blockquote, pre, table, div) { text-indent:0; }
+.single-body .dictionary > div > dd > p:first-child { display:inline; }
+@media (max-width:600px) { .single-body .dictionary { --indent:100px; } }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.11.0",
+    "version": "23.12.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -35,6 +35,11 @@
             "types": "./types/hm3/*.d.mts",
             "import": "./hm3/*.mjs"
         },
+        "./preview": {
+            "types": "./types/engine/site-preview.d.mts",
+            "import": "./engine/site-preview.mjs",
+            "default": "./engine/site-preview.mjs"
+        },
         "./content-config": {
             "types": "./types/content-config.d.mts",
             "import": "./content-config.mjs"
@@ -95,7 +100,8 @@
         "./package.json": "./package.json"
     },
     "bin": {
-        "package-build": "./bin/package-build.mjs"
+        "package-build": "./bin/package-build.mjs",
+        "package-build-preview": "./bin/package-build-preview.mjs"
     },
     "files": [
         "CHANGELOG-content-build.md",

package/types/content-config.d.mts

@@ -628,6 +628,10 @@ export type ContentBuildConfigInput = {
      * depends on the working directory.
      */
     rootDir: string;
+    /**
+     * Setting-wide neutral current date; defaults to "720.1".
+     */
+    currentDate?: string | undefined;
     /**
      * Content package name — the address
      * namespace every note in this
@@ -748,6 +752,10 @@ export type ContentBuildConfigInput = {
  * The normalized, frozen configuration the toolchain reads.
  */
 export type ContentBuildConfig = {
+    /**
+     * Setting-wide neutral current date.
+     */
+    currentDate: string;
     rootDir: string;
     contentPackage: string;
     /**

package/types/engine/base-compiler.d.mts

@@ -358,7 +358,7 @@ export class BasePackCompiler {
     reportsCorpusProblems: boolean | undefined;
     linkIndex: any;
     sqlTables: any;
-    worldPresent: unknown;
+    currentDate: string | undefined;
     /**
      * Report every finding {@link BasePackCompiler#convertBody} collected
      * across its passes, and decline the note if there were any.

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,9 +1,11 @@
 /** 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.spoilers] - Add visible static Secret labels (Foundry).
+ * @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"), { spoilers }?: {
+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.

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";
 }>;