@heroiclands/package-build 23.11.0 → 23.12.0

package/docs/reference/theme-pages.md

@@ -515,4 +515,4 @@ A row is a linked title and, when the page carries one, its description.
 
 ## Alerts
 
-The content renderer emits an `aside` with `alert` and `alert-note`, `alert-tip`, `alert-important`, `alert-warning` classes. The `alert-title` header contains a Font Awesome icon and the type's label. Shared styles supply a colored left rule, colored header and ordinary readable body; alerts do not use `details` and never start collapsed. Authored identifiers, additional classes and named attributes belong to the entire aside. Secret blocks retain their separate expandable presentation on the website.
+The content renderer emits an `aside` with `alert` and `alert-note`, `alert-tip`, `alert-important`, `alert-warning` classes. The `alert-title` header contains a Font Awesome icon and the type's label. Shared styles supply a colored left rule, colored header, tinted background and readable body text. The website uses the dark palette; Foundry selects a light or dark palette from its color scheme. Alerts do not use `details` and never start collapsed. Authored identifiers, additional classes and named attributes belong to the entire aside. Secret blocks retain their separate expandable presentation on the website.

package/docs/source-preview.md

@@ -0,0 +1,172 @@
+---
+shortcode: source-preview
+name: { full: "Source preview and Gitea renderer" }
+type: doc
+subType: reference
+---
+
+# Source preview and Gitea renderer
+
+Preview renders only the supplied Markdown buffer. It works with ordinary
+Markdown, optional YAML frontmatter, and local Heroic Lands extensions, without
+configuration, a content tree, dependency caches, a content index or Pandoc.
+
+```sh
+package-build-preview < note.md > preview.html
+package-build-preview --dark < note.md > preview.html
+package-build-preview --current-date 740.1 < note.md > preview.html
+package-build-preview --css > preview.css
+```
+
+The command writes an HTML fragment by default. Include `preview.css` in the
+hosting page to apply the syntax colors, panels and tinted alerts. Light mode
+is the default; `--dark` is explicit and independent of browser preferences.
+`--css` emits both scoped palettes and does not read stdin. `--help` lists the
+options. Unsupported arguments exit 1. Findings go to stderr; success exits 0,
+and render errors exit 1. A partial preview may accompany error findings.
+
+Wikilinks, image and portrait links retain their complete source: blue brackets,
+purple addresses, bold foreground labels and grey attributes. Entire spans are bold, including their visible brackets and attributes.
+Definition-list terms are bold and definitions use normal text. SQL and pagelist fences remain grey source;
+they never execute. Calendar expressions, dependent expressions, references and
+maps remain green source. Local expressions can evaluate against authored
+frontmatter. Missing ages are calculated from neutral birth dates and the root
+`currentDate` setting, defaulting to `"720.1"`, as for other package outputs.
+Authored ages, including `0`, take precedence. Unknown or calendar-dependent
+birth dates omit the age row; `{{data.age}}` is empty when unavailable. Generated sections,
+related pages and See also are absent. Preview performs no publication or link
+checks. Alerts render with their icons, titles, Markdown bodies and tinted
+backgrounds, including nested alerts. Secret blocks are closed disclosure
+spoilers. An authored `.secret` heading hides its section through the next
+heading at the same or a higher level, while retaining its anchor. Secret spans
+redact their label until hover or keyboard focus; explicit `.secret` wikilink
+and image attributes similarly redact their inner source. The authored outer
+brackets and attributes remain visible. This uses scoped CSS and a focusable
+wrapper, with no preview JavaScript required.
+
+Applications import `renderPreview` and `previewStyles` from
+`@heroiclands/package-build/preview`. The HTML wrapper has `hl-preview` and
+exactly one mode class: `hl-preview-light` or `hl-preview-dark`. See the
+[API reference](api.md) for the function contract.
+
+## Current date
+
+Declare the setting-wide date as a quoted root configuration value:
+
+```yaml
+currentDate: "720.1"
+```
+
+The standalone command discovers the nearest `package-build.config.yaml`,
+`.yml` or `.mjs` from its working directory. YAML reads only `currentDate`; it
+requires no other package fields, content or index. MJS executes its trusted
+configuration module. Missing configuration or an absent setting uses `"720.1"`.
+Invalid explicit values fail with a configuration diagnostic. Use
+`--current-date DATE` to override discovery for one invocation. Dates must use
+neutral `<year>[.<day>[:HHMMSS]]` syntax; named-calendar dates are refused.
+
+The pure `renderPreview` API accepts `currentDate` and never reads configuration.
+Hosts can opt into `await readPreviewCurrentDate(projectRoot)` to read the root
+setting before rendering. Repeated calls observe configuration edits. This is
+the same root setting used by compilation, website output and other toolchain
+consumers; there is no separate preview date setting.
+
+## Gitea installation
+
+Install Node 24 or newer and this package in the Gitea runtime, including the
+container image when applicable. The examples assume installation at
+`/opt/heroiclands/node_modules/@heroiclands/package-build` and a usable Node
+executable on Gitea's PATH. Pin the package version in the installation's
+`package.json` and lockfile.
+
+Copy [the complete renderer configuration](../assets/preview/gitea.ini) into
+`app.ini`. It replaces whole-file rendering for the listed Markdown extensions;
+it does not replace Gitea's issue-comment or pull-request discussion renderer.
+The renderer section must appear before its sanitizer sections. Its command
+reads stdin and emits HTML; it needs no repository checkout. Change the absolute
+command path to match the installation. Gitea normally uses the shared default
+`"720.1"` because it receives no repository checkout. To select the deployment's
+setting-wide date explicitly, use:
+
+```ini
+RENDER_COMMAND = /opt/heroiclands/node_modules/.bin/package-build-preview --current-date 740.1
+```
+
+Keep this override aligned with the setting's root configuration. Without an
+override, run Gitea from a directory with no package-build configuration so
+unrelated local configuration cannot select the date.
+
+The supplied configuration keeps sanitization enabled and disables Gitea's
+post-processing so preserved source and literal links remain intact. It permits
+only the preview's class families on the elements that need them, plus the SVG
+attributes needed for alert icons. Gitea's default SVG rules retain `viewBox`,
+`width`, `height`, `aria-hidden`, path `d` and `fill-rule`; the extra rules retain
+`fill="currentColor"` and circle coordinates. The wrapper mode class, syntax
+span classes, fence classes and infobox wrapper must survive sanitization for
+styling to work. Source is escaped text, so no additional source-data attributes
+are required. The `secretFocus` rule retains only `tabindex="0"` on span
+wrappers so keyboard users can reveal redacted source labels. Do not enable
+arbitrary styles, scripts or data-URI images.
+
+Install the stylesheet and optional theme adapter beneath the Gitea custom
+path. Here `custom` means the actual instance's `CustomPath`:
+
+```sh
+mkdir -p custom/public/assets/css custom/public/assets/js
+/opt/heroiclands/node_modules/.bin/package-build-preview --css > custom/public/assets/css/heroiclands-preview.css
+cp /opt/heroiclands/node_modules/@heroiclands/package-build/assets/preview/gitea-theme.js custom/public/assets/js/heroiclands-preview.js
+```
+
+Add to `custom/templates/custom/header.tmpl`, preserving existing content:
+
+```html
+<link rel="stylesheet" href="{{AppSubUrl}}/assets/css/heroiclands-preview.css" />
+<script defer src="{{AppSubUrl}}/assets/js/heroiclands-preview.js"></script>
+```
+
+Restart Gitea after configuration/template changes. Regenerate the CSS asset
+when updating the package. These are administrator installation instructions;
+package-build does not deploy or change the server configuration.
+
+## Gitea theme selection
+
+The external renderer runs on the server and cannot see a reader's active
+theme. The installed browser adapter reads Gitea's root CSS variable
+`--is-dark-theme`, selecting dark for `true` and light for `false`. It follows
+`data-theme` changes, stylesheet loads and newly inserted preview nodes. It
+changes only `.markup.markdown .hl-preview` mode classes; the surrounding Gitea
+interface keeps its own colors. A custom theme that omits the variable retains
+the initial renderer mode.
+
+Without the browser adapter, use the default command for fixed light rendering,
+or append `--dark` to `RENDER_COMMAND` for fixed dark rendering. Explicit CLI
+mode never changes itself. Theme adaptation happens only when the administrator
+installs the separate browser script.
+
+## Sanitizer validation
+
+[The validation harness](../assets/preview/check-sanitizer.go) applies the
+shipped INI rules using the actual `bluemonday` sanitizer and the relevant
+Gitea SVG defaults. It requires a Go toolchain and a temporary module with
+`github.com/microcosm-cc/bluemonday` at the version used by the target Gitea
+release. Run it against generated preview HTML:
+
+```sh
+go run check-sanitizer.go /path/to/gitea.ini < preview.html > sanitized.html
+```
+
+Check both light and dark fixtures containing all four alert types, a custom
+title, nesting, wikilinks and attributes, SQL/pagelist fences, infoboxes, poetry
+and footnotes. All wrapper/token classes and icon shapes should remain, while
+injected scripts and event-handler attributes should disappear. This replay
+checks the sanitizer primitives; also inspect the result in the actual Gitea
+version before deployment, since defaults can vary between releases.
+
+Configuration and installation follow Gitea's
+[external renderer documentation](https://docs.gitea.com/administration/external-renderers/).
+The relevant implementation contracts are its
+[command adapter](https://github.com/go-gitea/gitea/blob/main/modules/markup/external/external.go),
+[sanitizer defaults](https://github.com/go-gitea/gitea/blob/main/modules/markup/sanitizer_default.go),
+[renderer settings](https://github.com/go-gitea/gitea/blob/main/modules/setting/markup.go),
+[root theme attribute](https://github.com/go-gitea/gitea/blob/main/templates/base/head.tmpl),
+and [theme scheme variable](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes/theme-gitea-dark.css).

package/engine/base-compiler.mjs

@@ -103,10 +103,11 @@ import { packForType } from "./ids.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 import { carriesSystemBlock } from "./system-block.mjs";
 import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
-// A being's computed `age`, filled in against the package's own declared
-// present before this pass reads `data:` for anything else — see
+// A being's computed `age`, filled in against the configured setting
+// current date before this pass reads `data:` for anything else — see
 // `engine/being-age.mjs`.
-import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
+import { applyComputedBeingAge } from "./being-age.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { annotateAssetReferences, assetReferenceLookup } from "./asset-references.mjs";
@@ -632,10 +633,8 @@ export class BasePackCompiler {
         if (this.constructor.convertsWikilinks) {
             this.sqlTables = this.corpus.sqlTables;
         }
-        // The package's declared present, read once from the same corpus — so
-        // a being's computed `age` reaches every compiled document, not only
-        // the content index.
-        this.worldPresent = presentAmongRecords(this.corpus.records);
+        // Use the compile corpus's setting date.
+        this.currentDate = normalizeCurrentDate(this.corpus.currentDate);
         this.unresolvedLinks = 0;
     }
 
@@ -1277,7 +1276,7 @@ export class BasePackCompiler {
                 stats.skippedOther++;
                 continue;
             }
-            applyComputedBeingAge(fm, this.worldPresent, dates);
+            applyComputedBeingAge(fm, this.currentDate, dates);
             // `package:` is refused before `selects`, so a note is answered
             // whichever pass would have claimed it: a note's package is the
             // repository's configured one, so declaring it restates a

package/engine/being-age.mjs

@@ -11,51 +11,9 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-/**
- * **The middle state of `age`: absent beside a dated `born`, it follows from
- * the date.**
- *
- * `age` is a three-state override — authored it wins, absent beside a dated
- * `born` it is computed, absent beside `born: unknown` or an absent `born` it
- * stays unknown. This module builds the middle state, which nothing else in
- * the toolchain does: `born` and `age` are read straight through to every
- * compiled surface exactly as authored, unless a note's own package states the
- * day the setting stops.
- *
- * ## Where the present comes from
- *
- * A world's `present` is a fact about the world, not about a calendar or a
- * build configuration — it is `data.present` on the package's own `place` note
- * of `subType: world` (or `celestial`), read through
- * {@link module:engine/calendar-notes.worldInvariants}. A package with no such
- * note states no present, computes no age, and says nothing about it: the
- * absence is silent, exactly as a package that declares no calendar is asked
- * no calendar questions.
- *
- * ## The arithmetic is on two dates, not on two years
- *
- * A year subtracted from a year is wrong whenever the birthday has not yet
- * happened in the present's year — the common shape, not the exception. So
- * {@link computeAge} compares the two dates' canonical day ordinals where an
- * era marker supplies them. The birthday that still lies ahead in the current
- * year does not count as a completed year. An unmarked slash date has no
- * calendar to convert, so it uses its written month and day as its ordinal.
- *
- * ## `~` follows the convention {@link module:engine/note-dates} sets
- *
- * A date's `~` marks the value approximate without changing what it parses to,
- * so a renderer keeps the authored text and a comparison still has a number.
- * {@link parseAgeMagnitude} draws the same distinction for `age` — the tilde,
- * the magnitude — without routing through {@link module:engine/note-dates}
- * itself: `age` is a plain count of years, not a date, so it has no month, no
- * day, no era, and — unlike a date — no refusal of `0`. Reusing the date
- * grammar's month/day/era machinery here would accept an age nothing about the
- * field means, and refuse the one age an infant can have.
- *
- * @module
- */
+/** Authored ages and setting-wide current-date age calculations. @module */
 
-import { worldInvariants } from "./calendar-notes.mjs";
+import { DEFAULT_CURRENT_DATE } from "./current-date.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
@@ -107,11 +65,9 @@ export function parseAgeMagnitude(raw) {
  *
  * @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, presentRaw, dateContext = {}) {
     if (bornRaw === undefined || bornRaw === null) return null;
@@ -126,11 +82,15 @@ export function computeAge(bornRaw, presentRaw, dateContext = {}) {
     // A resolved marker supplies a canonical day. An unmarked slash date uses
     // its written month and day. Missing parts read as the first day that the
     // value can name.
-    const bornOrdinal = born.canonicalDay ?? (born.month ?? 1) * 100 + (born.day ?? 1);
-    const presentOrdinal = present.canonicalDay ?? (present.month ?? 1) * 100 + (present.day ?? 1);
+    const bornOrdinal =
+        born.canonicalDay ?? (born.month === null ? 1 : (born.month ?? 1) * 100 + (born.day ?? 1));
+    const presentOrdinal =
+        present.canonicalDay ??
+        (present.month === null ? 1 : (present.month ?? 1) * 100 + (present.day ?? 1));
     const notYetHappened = bornOrdinal > presentOrdinal;
 
-    return present.canonicalYear - born.canonicalYear - (notYetHappened ? 1 : 0);
+    const age = present.canonicalYear - born.canonicalYear - (notYetHappened ? 1 : 0);
+    return age < 0 ? null : age;
 }
 
 /**
@@ -146,8 +106,7 @@ export function computeAge(bornRaw, presentRaw, 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, presentRaw, dateContext = {}) {
@@ -171,63 +130,21 @@ export function applyComputedBeingAge(fm, presentRaw, dateContext = {}) {
 }
 
 /**
- * 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) {
-    return worldInvariants({
-        notes: (records ?? []).map((record) => ({ fm: record, type: record?.type })),
-    }).present;
-}
-
-/**
- * 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) {
-    return worldInvariants({
-        notes: (frontmatters ?? []).map((fm) => ({ fm, type: fm?.type })),
-    }).present;
-}
-
-/**
- * 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, { index } = {}) {
+export function checkBeingAge(note, { index, currentDate = DEFAULT_CURRENT_DATE } = {}) {
     if (!isBeingType(note?.type ?? note?.fm?.type)) return [];
     const data = dataOf(note?.fm);
     if (!data) return [];
@@ -235,10 +152,7 @@ export function checkBeingAge(note, { index } = {}) {
     const bornRaw = data.born;
     const ageRaw = data.age;
     if (ageRaw === undefined || ageRaw === null || ageRaw === "") return [];
-    if (!index) return [];
-
-    const present = worldInvariants(index).present;
-    const computed = computeAge(bornRaw, present, reckoningContext(index));
+    const computed = computeAge(bornRaw, currentDate, reckoningContext(index));
     if (computed === null) return [];
 
     const authored = parseAgeMagnitude(ageRaw);

package/engine/calendar-notes.mjs

@@ -20,7 +20,7 @@
  * A **world fact** is how long the year is, how the day divides, and how the
  * moon moves. Every people on the world lives under the same ones, so no
  * calendar may restate them: they are read from the package's `place` notes —
- * `data.year` and `data.present` from the world, `data.moon` from the moon —
+ * `data.year` from the world, `data.moon` from the moon —
  * and written by the emitters.
  *
  * A **calendar** is one people's division of those days: the months they name,
@@ -301,7 +301,7 @@ export const CALENDAR_FIELDS = Object.freeze([
  * 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[]}
@@ -349,12 +349,6 @@ export const INVARIANT_FIELDS = Object.freeze([
         kind: "number",
         describe: "How many seconds the minute divides into.",
     },
-    {
-        name: "present",
-        shape: "a date",
-        kind: "string",
-        describe: "The day the setting stops and play begins — what an age is computed against.",
-    },
     {
         name: "body.diameterKm",
         shape: "number",
@@ -438,14 +432,13 @@ function keysWritten(note, keys) {
  * 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) {
     const empty = {
         year: null,
-        present: null,
         moon: null,
         body: null,
         moonName: null,
@@ -459,7 +452,6 @@ export function worldInvariants(index) {
         const data = dataOf(note);
         if (!found.yearNote && data.year && typeof data.year === "object") {
             found.year = data.year;
-            found.present = data.present ?? null;
             found.yearNote = note;
         }
         if (!found.moonNote && data.moon && typeof data.moon === "object") {
@@ -619,9 +611,6 @@ function checkCalendarDayNames(note, daysPerYear) {
  * - 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.
@@ -650,17 +639,6 @@ export function checkWorldFacts(note, { index } = {}) {
         return findings;
     }
 
-    if (written.includes("present")) {
-        const { findings: dated } = parseNoteDate(dataOf(note).present, {
-            ...reckoningContext(index),
-            field: "data.present",
-            allowUnknown: false,
-            file: note.file,
-            raw: note.raw,
-            keyPath: ["data", "present"],
-        });
-        findings.push(...dated);
-    }
     if (written.includes("moon") && dataOf(note).moon?.newOn !== undefined) {
         const parsed = parseNoteDate(dataOf(note).moon.newOn, {
             ...reckoningContext(index),

package/engine/compile-corpus.mjs

@@ -61,7 +61,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  *   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 async function buildCompileCorpus({
@@ -99,6 +99,7 @@ export async function buildCompileCorpus({
     const sqlOptions = { ...corpusOptions, skipDirectories, parsed };
     const sqlTables = await prepareTreeSqlTables(contentBase, sqlOptions);
     return {
+        currentDate: resolved.currentDate,
         records,
         parsed,
         problems: collected,

package/engine/content-format.yaml

@@ -333,7 +333,6 @@ types:
             - year.hoursPerDay
             - year.minutesPerHour
             - year.secondsPerMinute
-            - present
             - body.diameterKm
             - body.orbitalRadiusKm
             - body.orbit

package/engine/content-index.mjs

@@ -179,7 +179,8 @@ import { isDraftNote } from "./note-vocabulary.mjs";
 // A being's computed `age` — the middle state between an authored override and
 // an unknown one — filled in against the package's own declared present before
 // a record is built, so the index carries it without the note being written to.
-import { applyComputedBeingAge, presentAmongFrontmatters } from "./being-age.mjs";
+import { applyComputedBeingAge } from "./being-age.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { resolvedDateFields } from "./note-dates.mjs";
 
@@ -1097,6 +1098,7 @@ export function resolveCultures(
  *   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}.
@@ -1113,6 +1115,7 @@ export function collectContentIndex(
     contentBase,
     {
         contentPackage,
+        currentDate,
         skipDirectories,
         assetsBase,
         manifest,
@@ -1134,10 +1137,7 @@ export function collectContentIndex(
     // tree to walk and the index is its asset records. The caller decides
     // whether an absent tree is a mistake; by the time the walk is reached it
     // is simply a package with nothing to compile.
-    // Materialised rather than consumed lazily: the present is read from this
-    // same walk before the loop below reads it a second time, and
-    // `walkMarkdownTree` is a generator — a single-use one, exhausted the
-    // moment anything else iterates it first.
+    // Materialize parsed notes once for shared calendar and source context.
     const notes = fs.existsSync(contentBase) ? [...walkMarkdownTree(contentBase, walkOpts)] : [];
     const parsedNotes = [];
     for (const note of notes) {
@@ -1165,10 +1165,8 @@ export function collectContentIndex(
         problems.push(problem);
     }
 
-    // The package's declared present, read once from whichever `place` note in
-    // this same walk states one — the whole tree is already in memory, so no
-    // second read is needed to answer a question about all of it.
-    const present = presentAmongFrontmatters(parsedNotes.map((n) => n.frontmatter));
+    // Every derived age and recurring event uses the same configured date.
+    const present = normalizeCurrentDate(currentDate);
     // Carried on the same context `resolvedDateFields` reads: a recurring
     // event's `next` is computed against this present exactly as a being's
     // `age` already is, above.
@@ -1497,6 +1495,7 @@ export function indexRecordsFor({
     };
     return collectContentIndex(tree, {
         contentPackage: resolved.contentPackage,
+        currentDate: resolved.currentDate,
         addressContext: {
             ...noteAddressContext(resolved),
             declaresAddress: dependencyAddresses(resolved),
@@ -1680,6 +1679,7 @@ export async function prepareContentIndex({ contentBase, config, session } = {})
         });
         const index = buildSiteIndex(pages, {
             package: resolved.contentPackage,
+            currentDate: resolved.currentDate,
             records: visible,
             foreignIndex: foreign.index,
             syntax: session?.syntax,

package/engine/content-spans.mjs

@@ -22,17 +22,23 @@ import { inlineText } from "./name-markup.mjs";
 /** 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, { spoilers = false } = {}) {
+export function spanMarkdownPlugin(md, { spoilers = false, source = false } = {}) {
     if (spoilers) {
         md.renderer.rules.span_open = (tokens, index, options, env, renderer) => {
             const token = tokens[index];
             const secret = (token.attrGet("class") ?? "").split(/\s+/).includes("secret");
-            return (
-                renderer.renderToken(tokens, index, options) +
-                (secret ? '<strong class="inline-secret-label">Secret:</strong> ' : "")
-            );
+            if (secret) {
+                token.attrSet("data-inline-spoiler", "");
+                token.attrSet("tabindex", "0");
+                if (!token.attrGet("title"))
+                    token.attrSet("title", "Spoiler: hover or focus to reveal");
+                if (!token.attrGet("aria-label"))
+                    token.attrSet("aria-label", "Spoiler; focus to reveal");
+            }
+            return renderer.renderToken(tokens, index, options);
         };
     }
     md.inline.ruler.after("link", "bracket_span", (state, silent) => {
@@ -89,6 +95,22 @@ export function spanMarkdownPlugin(md, { spoilers = false } = {}) {
             state.pos = finish;
             return true;
         }
+        if (source) {
+            // An incomplete attribute stays opaque through the end of its line.
+            if (state.src[finish] === "{") {
+                const newline = state.src.indexOf("\n", finish);
+                finish = newline < 0 ? state.posMax : newline;
+            }
+            const token = state.push("span_source", "", 0);
+            token.content = state.src.slice(start, finish);
+            token.meta = {
+                text: state.src.slice(start + 1, end),
+                labelEnd: end - start,
+                secret: parsed.classes.includes("secret"),
+            };
+            state.pos = finish;
+            return true;
+        }
         const token = state.push("span_open", "span", 1);
         token.meta = {
             span: true,