@heroiclands/package-build 23.10.0 → 23.12.0

package/docs/api.md

@@ -744,23 +744,23 @@ The corpus registry anchors each calendar's year 1, day 1 to its canonical `data
 
 A calendar is a `lore` note with `subType: calendar`, declaring the months it keeps, the weekdays it names, the seasons it marks and the eras it counts years in. How long the year is, how the day divides and how the moon moves are facts about the **world**, written on its `place` note and its moon's, and no calendar may restate them — which is why the months summing to the world's year is the only arithmetic a calendar note is held to. One definition is emitted per calendar, in array shape: Foundry core prunes the keys outside its schema, and Calendaria converts the arrays to its own keyed collections.
 
-| Export                      | Signature                                             | Returns                                    | Use it when                                                                       |
-| --------------------------- | ----------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
-| `CALENDAR_SUBTYPE`          | `const CALENDAR_SUBTYPE`                              | —                                          | naming the `lore` subType whose notes are calendars                               |
-| `INVARIANT_SUBTYPES`        | `const INVARIANT_SUBTYPES`                            | —                                          | naming the `place` subTypes a world fact may be written on                        |
-| `CALENDAR_FIELDS`           | `const CALENDAR_FIELDS`                               | —                                          | reading the closed list of what a calendar note may declare                       |
-| `CALENDAR_ENTRY_FIELDS`     | `const CALENDAR_ENTRY_FIELDS`                         | —                                          | reading the keys one entry of each calendar list takes, as inner-key declarations |
-| `CALENDAR_DATE_FORMAT_KEYS` | `const CALENDAR_DATE_FORMAT_KEYS`                     | —                                          | reading the supported Calendaria display slots                                    |
-| `CALENDAR_FORMAT_TOKENS`    | `const CALENDAR_FORMAT_TOKENS`                        | —                                          | checking bare date tokens in a format string                                      |
-| `INVARIANT_FIELDS`          | `const INVARIANT_FIELDS`                              | —                                          | reading the closed list of what a body may declare about itself                   |
-| `checkCalendarNote`         | `checkCalendarNote(note, opts)`                       | `object[]` — findings                      | holding a `lore` note to the family and to the year the world keeps               |
-| `checkCalendarDateFormats`  | `checkCalendarDateFormats(note)`                      | `object[]` — findings                      | checking named patterns and the readable default                                  |
-| `checkWorldFacts`           | `checkWorldFacts(note, opts)`                         | `object[]` — findings                      | holding a `place` note's world facts to one body, one year and one moon           |
-| `worldInvariants`           | `worldInvariants(index)`                              | `{year, present, moon, body, moonName, …}` | reading the year, the present and the moon a package's own notes state            |
-| `quarterDays`               | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year         | asking which days the year turns on                                               |
-| `compileCalendar`           | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition                  | building the one object both a core consumer and Calendaria read                  |
-| `compileCalendars`          | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year       |
-| `calendariaEnvelope`        | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings             |
+| Export                      | Signature                                             | Returns                            | Use it when                                                                       |
+| --------------------------- | ----------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
+| `CALENDAR_SUBTYPE`          | `const CALENDAR_SUBTYPE`                              | —                                  | naming the `lore` subType whose notes are calendars                               |
+| `INVARIANT_SUBTYPES`        | `const INVARIANT_SUBTYPES`                            | —                                  | naming the `place` subTypes a world fact may be written on                        |
+| `CALENDAR_FIELDS`           | `const CALENDAR_FIELDS`                               | —                                  | reading the closed list of what a calendar note may declare                       |
+| `CALENDAR_ENTRY_FIELDS`     | `const CALENDAR_ENTRY_FIELDS`                         | —                                  | reading the keys one entry of each calendar list takes, as inner-key declarations |
+| `CALENDAR_DATE_FORMAT_KEYS` | `const CALENDAR_DATE_FORMAT_KEYS`                     | —                                  | reading the supported Calendaria display slots                                    |
+| `CALENDAR_FORMAT_TOKENS`    | `const CALENDAR_FORMAT_TOKENS`                        | —                                  | checking bare date tokens in a format string                                      |
+| `INVARIANT_FIELDS`          | `const INVARIANT_FIELDS`                              | —                                  | reading the closed list of what a body may declare about itself                   |
+| `checkCalendarNote`         | `checkCalendarNote(note, opts)`                       | `object[]` — findings              | holding a `lore` note to the family and to the year the world keeps               |
+| `checkCalendarDateFormats`  | `checkCalendarDateFormats(note)`                      | `object[]` — findings              | checking named patterns and the readable default                                  |
+| `checkWorldFacts`           | `checkWorldFacts(note, opts)`                         | `object[]` — findings              | holding a `place` note's world facts to one body, one year and one moon           |
+| `worldInvariants`           | `worldInvariants(index)`                              | `{year, moon, body, moonName, …}`  | reading the year and moon a package's own notes state                             |
+| `quarterDays`               | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year | asking which days the year turns on                                               |
+| `compileCalendar`           | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition          | building the one object both a core consumer and Calendaria read                  |
+| `compileCalendars`          | `compileCalendars(index, opts)`                       | `{calendars, invariants}`          | building every calendar a package declares, or none where it states no year       |
+| `calendariaEnvelope`        | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope     | wrapping a definition for a hand import through Calendaria's settings             |
 
 ### `engine.calendarArtifacts`
 
@@ -776,18 +776,45 @@ identical bytes.
 | ----------------------- | ---------------------------------------------------- | ------------------------------- | ---------------------------------------------------- |
 | `emitCalendarArtifacts` | `emitCalendarArtifacts({config, calendariaVersion})` | `{directory, calendars, files}` | writing calendar files for a package's Foundry stage |
 
+### `engine.definitionList`
+
+HTML definition lists use semantic dictionary rows. The plugin groups each term
+and all its definitions inside one `div` under `dl.dictionary`, preserving
+nested blocks, inline formatting and document footnotes. Register it after
+`markdown-it-deflist`.
+
+| Export                 | Signature                  | Returns | Use it when                                                     |
+| ---------------------- | -------------------------- | ------- | --------------------------------------------------------------- |
+| `dictionaryListPlugin` | `dictionaryListPlugin(md)` | `void`  | Giving an HTML Markdown parser the shared dictionary structure. |
+
+The website groups Goldmark's final HTML through the `dictionary-lists.html`
+partial, retaining its headings, TOC and footnotes. Shared content styles use a
+150px hanging indent, a `.75em` term gap and `.5em` space between entries. At
+viewport widths of 600px or less the indent is 100px. Terms are bold and stay on
+one line. A long term pushes the first definition farther right; continuation
+lines return to the common indent. Profile infobox grids keep their own layout.
+
+### `engine.currentDate`
+
+The shared current-date setting is a neutral string and requires no calendar or
+configuration loading. Undefined selects the default; invalid explicit values
+throw `TypeError`. Day digits remain exactly as authored.
+
+| Export                 | Signature                      | Returns   | Use it when                                     |
+| ---------------------- | ------------------------------ | --------- | ----------------------------------------------- |
+| `DEFAULT_CURRENT_DATE` | Constant                       | `"720.1"` | Selecting the setting-wide default.             |
+| `normalizeCurrentDate` | `normalizeCurrentDate(value?)` | `string`  | Validating a configuration or adapter override. |
+
 ### `engine.beingAge`
 
-The middle state of a being's `age`: absent beside a dated `born`, it is computed against the package's declared present — the two dates compared, not the two years subtracted, so a birthday later in the year than the present counts one less. `applyComputedBeingAge` fills it in on the frontmatter object a pass already holds, never on the note; `checkBeingAge` is `being`'s `NOTE_VOCABULARY` check, raising a warning where an authored `age` disagrees with what a dated `born` computes to. An estimate's `~` is read the way a date's is: the authored string stays verbatim, and `ageYears` carries the magnitude beside it.
+The middle state of a being's `age`: absent beside a dated `born`, it is computed against the configured `currentDate` (default `"720.1"`) — the two dates compared, not the two years subtracted, so a birthday later in the year than the present counts one less. `applyComputedBeingAge` fills it in on the frontmatter object a pass already holds, never on the note; `checkBeingAge` is `being`'s `NOTE_VOCABULARY` check, raising a warning where an authored `age` disagrees with what a dated `born` computes to. An estimate's `~` is read the way a date's is: the authored string stays verbatim, and `ageYears` carries the magnitude beside it.
 
-| Export                     | Signature                                | Returns                        | Use it when                                                               |
-| -------------------------- | ---------------------------------------- | ------------------------------ | ------------------------------------------------------------------------- |
-| `computeAge`               | `computeAge(bornRaw, presentRaw)`        | `number \| null`               | reading the age two dates imply, in whole years                           |
-| `parseAgeMagnitude`        | `parseAgeMagnitude(raw)`                 | `{approximate, value} \| null` | reading an authored `age`'s `~` mark and its magnitude                    |
-| `applyComputedBeingAge`    | `applyComputedBeingAge(fm, presentRaw)`  | `void` — mutates `fm.data`     | filling in a being's computed `age`, or the `ageYears` beside an estimate |
-| `presentAmongRecords`      | `presentAmongRecords(records)`           | the present, or `null`         | reading the declared present from a batch of flat index records           |
-| `presentAmongFrontmatters` | `presentAmongFrontmatters(frontmatters)` | the present, or `null`         | reading the declared present from a batch of raw frontmatter objects      |
-| `checkBeingAge`            | `checkBeingAge(note, opts)`              | `object[]` — findings          | holding a being's authored `age` to what `born` and the present compute   |
+| Export                  | Signature                                     | Returns                        | Use it when                                                               |
+| ----------------------- | --------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------- |
+| `computeAge`            | `computeAge(bornRaw, presentRaw)`             | `number \| null`               | reading the age two dates imply, in whole years                           |
+| `parseAgeMagnitude`     | `parseAgeMagnitude(raw)`                      | `{approximate, value} \| null` | reading an authored `age`'s `~` mark and its magnitude                    |
+| `applyComputedBeingAge` | `applyComputedBeingAge(fm, presentRaw)`       | `void` — mutates `fm.data`     | filling in a being's computed `age`, or the `ageYears` beside an estimate |
+| `checkBeingAge`         | `checkBeingAge(note, { index, currentDate })` | `object[]` — findings          | holding a being's authored `age` to what `born` and the present compute   |
 
 ### `engine.contentAddress`
 
@@ -1290,30 +1317,33 @@ index for checking page links.
 
 ### `engine.sitePreview`
 
-`prepareSitePreview({ config })` reads the saved content tree and declared dependency indexes, prepares its SQL corpus, and returns a private preview context. Pass the active note's absolute path and complete buffer text to `render(file, text)`. A successful result has `{ ok: true, markdown, frontmatter, findings: [] }`; a failed result has `{ ok: false, findings }` and no replacement content. Findings identify the source file and carry a line and column when the offending text can be located.
+`renderPreview(text, { dark = false, infobox = true, file = "", currentDate = "720.1" })` renders the current Markdown buffer directly to HTML. Frontmatter is optional. It needs no package configuration, saved note, content tree, dependency cache, database or Pandoc installation. The result is `{ ok, html, frontmatter, findings }`; `file` only labels diagnostics. Malformed frontmatter produces a warning and remains visible without preventing a preview update.
 
-| Export               | Signature                        | Returns                                    | Use it when                                        |
-| -------------------- | -------------------------------- | ------------------------------------------ | -------------------------------------------------- |
-| `prepareSitePreview` | `prepareSitePreview({ config })` | `{render(file, text), refresh(), close()}` | An editor needs a private, reusable page renderer. |
+| Export                   | Signature                       | Returns                               | Use it when                                                            |
+| ------------------------ | ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
+| `renderPreview`          | `renderPreview(text, options?)` | `{ ok, html, frontmatter, findings }` | An editor or external renderer needs a preview from one buffer.        |
+| `previewStyles`          | `previewStyles()`               | CSS string                            | A host needs the shared, scoped light and dark palettes.               |
+| `readPreviewCurrentDate` | `readPreviewCurrentDate(root)`  | `Promise<string>`                     | Opting into the nearest project's validated root current-date setting. |
+| `PREVIEW_HELPERS`        | Constant                        | Helper dependency policy              | Checking preview coverage when adding an expression helper.            |
 
-The context keeps other notes and foreign packages at their saved state. Call `refresh()` after a save to read them again, and `close()` when the editor releases the project. Rendering and refreshing never write the authored notes or the site's `build/hugo/content` mount. The editor owns any private HTML artifact and keeps its last complete artifact when a render fails.
+The returned HTML includes an `.hl-preview` wrapper with exactly one explicit mode class, `.hl-preview-light` or `.hl-preview-dark`. Include `previewStyles()` once in the host document. The stylesheet colors only the preview container, including its backgrounds, source tokens, alerts and optional local infobox. Set `dark` from the host's selected theme; browser preference does not override it.
 
 ```js
-import { sitePreview } from "@heroiclands/package-build/engine";
+import { renderPreview, previewStyles } from "@heroiclands/package-build/engine/site-preview";
 
-const preview = await sitePreview.prepareSitePreview({ config });
-try {
-  const result = await preview.render(absoluteFile, currentBufferText);
-  if (result.ok) {
-    // Convert result.markdown and result.frontmatter to the editor's HTML preview.
-  } else {
-    showDiagnostics(result.findings);
-  }
-} finally {
-  await preview.close();
-}
+const result = renderPreview(currentBufferText, { dark: true });
+// Include previewStyles() in a stylesheet and result.html in the preview document.
+showDiagnostics(result.findings);
 ```
 
+Ordinary Markdown, definition lists, footnotes, alert boxes, poetry, captions, local figures and container blocks render locally. Alerts reuse the four shared icons and titles, accept custom titles and nested alerts, and have opaque tinted backgrounds in both modes. Definition terms are bold; definitions retain ordinary Markdown styling. Wikilinks and image embeds retain their entire authored source: blue opening markers (including all of `![[`), brackets and pipes, purple addresses and anchors, bold foreground labels, and grey attributes. Spans retain their entire source in bold, with blue brackets and grey attributes. Code examples stay literal. Incomplete syntax remains visible while editing.
+
+SQL and pagelist fences remain grey source, including delimiters. Calendar/date expressions, cross-note references and maps remain green source. A dependent call nested inside a pure helper preserves the entire outer expression. Pure helpers and scalar frontmatter expressions evaluate locally; same-note figure references and non-date event facts can resolve from this buffer. Infobox fields show authored values and green reference source; image and portrait wikilinks use the image syntax colors. Missing ages are calculated locally from neutral birth dates and `currentDate`, defaulting to `"720.1"`; authored ages, including `0`, take precedence. Unavailable ages remain `null` internally, have no infobox row, and render as empty text in `{{data.age}}`. Named-calendar birth dates remain unavailable without calendar context. Set `infobox: false` to omit the profile.
+
+`readPreviewCurrentDate(root)` is an explicit configuration adapter. It discovers the nearest `package-build.config.yaml`, `.yml` or `.mjs` using the shared resolver. YAML reads only top-level `currentDate`, without loading the build pipeline or validating unrelated fields; MJS executes the trusted configuration module. Missing config or an absent setting returns the shared default. Invalid explicit values reject with a configuration-file diagnostic. Repeated calls reread YAML and refresh a changed MJS file. `renderPreview` never calls this adapter or reads configuration itself.
+
+Generated sections, Related pages and authored See also sections are absent. Preview performs no publication eligibility or link checks and never resolves other notes. It does not write notes or generated site files. Callers render each buffer directly without preparing or maintaining a snapshot.
+
 ### `engine.contentLint`
 
 Linting a content tree's **addresses** — the rules every package's notes are authored against, wherever those notes live. These rules do not live in a consumer's `utils/`, which has two consequences and no upside. `thalorna` and `kethira` notes were checked by nothing at all, so the packages most likely to carry authoring mistakes were the ones nothing inspected. And one rule with two implementations can disagree without anything detecting it, which the canonical-separator handling already did once on each side.
@@ -1474,6 +1504,15 @@ Wikilink resolution for the knowledgebase build. The same authored links the pac
 | `frontmatterWikilinks` | `function frontmatterWikilinks(fm)`       | {Array<{path: string, link: string}>} In reading order; `path` is the dotted key path of the offending value (`government.summary`, `aliases.1`). | Every wikilink authored inside a frontmatter value.                   |
 | `resolveWebWikilinks`  | `function resolveWebWikilinks(body, ctx)` | {string} The body with wikilinks rewritten.                                                                                                       | Rewrites the wikilinks in a markdown body as KB-local markdown links. |
 
+Both `resolveWebWikilinks` and Foundry's `convertWikilinks` derive reference
+spoilers from the resolved note audience and secret-anchor metadata. A trailing
+`{.show}` bypasses automatic spoiler wrapping, without changing destination
+access. A web destination excluded by audience retains its label without an
+href. Same-note secret anchors follow the same rule; a whole-note link to a
+public note does not inherit individual secret sections. See the
+[authoring contract](authoring/links-and-markup.md#references-to-secret-subjects)
+for surface presentation.
+
 ### `engine.contentTables`
 
 Prepared SQL content tables are expanded into Markdown before link resolution.
@@ -1602,8 +1641,8 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | Export                     | Signature                                                  | Returns                                                         | Use it when                                                                                       |
 | -------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `WIKILINK`                 | `const WIKILINK`                                           | —                                                               | A wikilink, as authored.                                                                          |
-| `parseWikilink`            | `function parseWikilink(rawInner)`                         | {ParsedWikilink} The parts, each trimmed.                       | Split a wikilink's interior into its parts.                                                       |
-| `readWikilink`             | `function readWikilink(inner, context)`                    | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                                       |
+| `parseWikilink`            | `function parseWikilink(rawInner, literal?)`               | {ParsedWikilink} The parts, each trimmed.                       | Split a wikilink's interior into its parts.                                                       |
+| `readWikilink`             | `function readWikilink(inner, context, literal?)`          | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                                       |
 | `authoredLabel`            | `authoredLabel({ display })`                               | {string\|null} The label, or `null` when there is none to show. | The label an author actually supplied, or `null` when they supplied none.                         |
 | `unlabelledLinkMessage`    | `function unlabelledLinkMessage(target)`                   | {string} The message, unpunctuated at the end as a finding is.  | What an author writing an unlabelled link is told, in one place.                                  |
 | `LINK_FINDING_REASONS`     | `const LINK_FINDING_REASONS`                               | —                                                               | Every way a link can fail, named once for all three resolvers.                                    |
@@ -1614,6 +1653,15 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | `isEventAnchor`            | `isEventAnchor(hit, anchor)`                               | {boolean} Whether it is an event.                               | Whether the anchor a wikilink names is one of its target's events, which a wikilink may not name. |
 | `isSamePage`               | `isSamePage({ target, anchor })`                           | {boolean} True when the link is same-page.                      | Whether a parsed link addresses a section of the page it is written on.                           |
 
+`parseWikilink` and `readWikilink` accept the complete matched `literal` to
+read a trailing attribute block into `attributes`; its `classes` include the
+explicit `.show` override.
+
+| Export              | Signature                                         | Returns   | Use it when                                                                                       |
+| ------------------- | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
+| `secretDestination` | `secretDestination(destination, anchor?)`         | `boolean` | Read the resolved note's GM audience or the referenced anchor's secret metadata.                  |
+| `presentWikilink`   | `presentWikilink(reference, parsed, destination)` | `string`  | Wrap a rendered reference as an inline spoiler unless the parsed link explicitly carries `.show`. |
+
 ### `engine.siteIndex`
 
 **The address index a site build resolves its wikilinks against.**
@@ -1981,6 +2029,29 @@ Where HM3 records the template priority — one statement (`data.templatePriorit
 | `HM3_DEFAULT_ITEM_ART` | `const HM3_DEFAULT_ITEM_ART` | —                                 | reading the full map of default item artwork keyed by **note** type (not document subtype) for HM3 items |
 | `hm3DefaultItemArt`    | `hm3DefaultItemArt(type)`    | `string` — the default image path | getting the default art path for an HM3 item's note type, throwing when the type is unknown              |
 
+## `./preview`
+
+Import the buffer-only renderer directly without loading the build pipeline:
+
+```js
+import { renderPreview, previewStyles } from "@heroiclands/package-build/preview";
+
+const { html, findings } = renderPreview(currentBufferText, { dark: true });
+const css = previewStyles();
+```
+
+| Export                   | Signature                       | Returns                               | Use it when                                                            |
+| ------------------------ | ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
+| `renderPreview`          | `renderPreview(text, options?)` | `{ ok, html, frontmatter, findings }` | Rendering one Markdown buffer without configuration or an index.       |
+| `previewStyles`          | `previewStyles()`               | CSS string                            | Installing both scoped palettes in an editor or external host.         |
+| `readPreviewCurrentDate` | `readPreviewCurrentDate(root)`  | `Promise<string>`                     | Opting into the nearest project's validated root current-date setting. |
+| `PREVIEW_HELPERS`        | Constant                        | Helper dependency policy              | Checking coverage for every registered expression helper.              |
+
+These are the same exports as [`engine.sitePreview`](#enginesitepreview), with
+the same explicit palette, local infobox, source-preservation and diagnostics
+contract. See [Source preview](source-preview.md) for the standalone command and
+Gitea installation.
+
 ## `./content-config`
 
 The per-repository configuration contract: what `package-build.config.yaml` (or an `.mjs` config calling `defineConfig` directly) must satisfy. `defineConfig` validates and normalizes the whole thing, returning a deeply frozen copy, and performs no I/O — `engine.packConfig` is what locates and reads a repository's file, deriving the three fields absent from authored YAML (`rootDir`, `stats.systemVersion`, the resolved `itemBuilders` table). See `docs/configuration.md` for the full key-by-key reference; this section covers the module's own exported shape.
@@ -2371,6 +2442,21 @@ The engine wildcard subpath also exposes the body parsers below. Their figure ex
 | `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
 | `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans, the exact `.name` inventory and located errors, retaining visible text and attribute positions; rendering preserves inline Markdown and permitted attributes.   |
 
+Inline `.secret` spans preserve their inline content, name classes and
+attributes. Site rendering uses a separate show/hide button and content span,
+so a link inside the content does not become a nested control. Foundry emits a
+focusable inline spoiler: scoped content CSS redacts its text and descendants
+until pointer hover or keyboard focus reveals them. Its focus outline and
+accessible cue identify the reveal interaction. Native Foundry secret sections
+keep their separate controls. Book rendering discards inline `.secret` classes
+and prints their content normally, retaining emphasis, links, anchors and `.name`
+bold styling. Book secret sections and fences retain their visible labelled
+boxes. The span parser's opaque source tokens retain a `secret` boolean from
+their parsed classes for preview presentation.
+`collectAnchors` includes `secret: true` on secret anchors for destination
+presentation. Block and heading secrecy retain their separate scope and
+Foundry permission handling.
+
 `scanFigures` retains `line` (1-based caption line), `bodyStart`/`bodyEnd` (0-based, exclusive-end target range), and `close` (last consumed target line), plus caption attributes, kind, label and number. Unnumbered captions have an empty label and consume no number. `collectAnchors` discovers heading, caption, div, poem and span identifiers; `markupAnchorFindings(body)` reports collisions involving non-page identifiers; Foundry maps non-page anchors to the actual containing page UUID. An unnumbered `ref` requires `form="title"` or `form="full"`.
 
 `engine/markup-validation.mjs` provides shared syntax validation:

package/docs/authoring/first-note.md

@@ -41,6 +41,16 @@ For optional writing suggestions, run `npx package-build prose lint assets/conte
 
 The full Address is `<package>-note-lore-harbor`; `<package>` comes from `contentPackage` in `package-build.config.yaml`. In another note, `[[lore-harbor|Harbor]]` links to it. `[[lore-harbor|]]` asks the renderer to use the target's current name. The pipe is required.
 
+Use another subject's full canonical name at its first prose mention, then
+plain text for later mentions and aliases. Keep a note's own subject in plain
+text. Link indexed subjects even when they are private: the destination's
+audience automatically makes the whole reference a spoiler. Add `.show` only
+to intentionally reveal the reference; it grants no access to the destination.
+For an unwritten subject, use a typed span such as
+`[Aldric Venn]{.name data-type="being/npc"}`. The
+[links and markup guide](links-and-markup.md#marking-names-in-prose) covers
+these rules and separate `[text]{.secret}` spoilers.
+
 ## Grow the note only when needed
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.

package/docs/authoring/frontmatter.md

@@ -25,7 +25,7 @@ data: {}
 
 `description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
 
-Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Links from untagged notes to GM notes are errors; GM notes may link to one another.
+Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Any note can reference a GM note with an ordinary wikilink. The whole reference is automatically a spoiler; `.show` reveals only that reference, without changing the target's audience or permissions. See [references to secret subjects](links-and-markup.md#references-to-secret-subjects).
 
 The formatter keeps a collection on one line when the full line is under 100 characters. Longer collections use full YAML block form. Run `package-build format --write` to apply key order and collection formatting.
 

package/docs/authoring/links-and-markup.md

@@ -23,10 +23,49 @@ A link to a note tagged `draft` retains its target and carries a visible draft c
 
 An HTML comment is an aside to whoever reads the note next, and no surface shows one — the packs and the website emit it into the HTML, where it stays a comment, and a book leaves it out. Write a `markdownlint` pragma or a note about a quoted passage freely. A comment inside a fence or a code span is an example and is printed as written, and a comment that is never closed is an error.
 
+## References to secret subjects
+
+Use an ordinary wikilink for an indexed subject, including a GM-only note:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]
+```
+
+The renderer reads the destination's audience and conceals the entire reference,
+including its label, as a spoiler. Authors do not repeat that audience at each
+reference. A reference to a public subject stays visible. A link to an anchor inside secret content
+conceals its reference too, including a same-note `[[#anchor|label]]`.
+Linking to the public note as a whole does not inherit a section's secrecy.
+
+| Surface | Reference to a secret destination                                                                                                                                      |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Website | An inline show/hide spoiler conceals its label. An omitted GM-only destination produces text without an unusable link. A published secret heading can still be linked. |
+| Foundry | A CSS-redacted inline spoiler reveals the reference on hover or keyboard focus. Private pack and page permissions govern whether its destination can be opened.        |
+| Book    | The reference prints normally, preserving emphasis and name styling. An omitted GM-only destination produces text without a link.                                      |
+
+`.show` removes automatic spoiler presentation on the website and in Foundry.
+Book references already print normally. Where the target is unavailable the
+reference still produces text without a link.
+
+To intentionally reveal this reference, add `.show` immediately after the link:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]{.show}
+[[doc-magictruth|The Truth of Magic]]{.show}
+```
+
+`.show` reveals only this reference. It does not publish the destination, change
+its audience or grant Foundry access. It is redundant for a public target.
+Use `[text]{.secret}` when the text itself is a spoiler, independently of any
+destination; see [inline spoilers](#inline-spoilers).
+
 ## Marking names in prose
 
 Use `[Name]{.name}` for a name that has no indexed note. Link a name that has
-one; an empty link label uses the indexed full name. Bold is emphasis.
+one, including a private subject; an empty link label uses the indexed full
+name. Introduce another subject with its full canonical name at its first prose
+use. Keep the note's own subject in plain text, and use plain text for later
+mentions and aliases. Bold is emphasis.
 Plain text, including capitalized words, is not searched for names.
 
 ```markdown
@@ -39,7 +78,7 @@ creating a placeholder note:
 
 ```markdown
 [Ravenmoor]{.name data-type="place/settlement"}
-[Aldric Venn]{.name data-type="being"}
+[Aldric Venn]{.name data-type="being/npc"}
 ```
 
 `data-type` is optional. It names a declared [note type and
@@ -196,6 +235,40 @@ optional declared type; see [marking names](#marking-names-in-prose).
 
 Inline Markdown remains active inside the span. Bracket spans have lower priority than URL links, image links, reference links, footnotes and wikilinks. A bracketed form immediately preceded by `!`, followed by `(` or another `[`, or beginning with `[[` is not a span, even when the link is unresolved. Ordinary links retain their existing syntax. Escape a bracket when it should be literal, or put examples inside a code span or fence. A span identifier addresses that point in the note; it does not start a journal page.
 
+### Inline spoilers
+
+Mark text itself as a spoiler with `.secret`. It can contain inline Markdown or
+combine with a typed name for an unwritten subject:
+
+```markdown
+The key is [under the **third** stair]{.secret}.
+The informant is [Aldric Venn]{.name .secret data-type="being/npc"}.
+```
+
+This marks only the enclosed text; it does not declare a target's audience.
+For indexed subjects, use the ordinary wikilink and let the destination decide
+whether the reference needs a spoiler. `.show` on a wikilink bypasses automatic
+reference concealment; an enclosing authored `.secret` still marks its text.
+
+On the website an inline spoiler has a button to show or hide its content.
+It stays within the surrounding sentence, and links inside it can be followed
+after revealing it. Foundry redacts inline `secret` spans with a solid cover;
+hover the span or focus it with the keyboard to reveal its text, links and
+images. A visible focus outline and a spoiler cue identify the interaction.
+This does not change native Foundry secret-section controls. The book ignores
+`.secret` on inline spans and prints their text normally, preserving emphasis,
+links, anchors and `.name` bold styling. Secret sections and `:::secret` fences
+retain their visible labelled boxes.
+
+Published web HTML contains the spoiler's text. Revealing the spoiler or reading
+the page source exposes it; this is presentation, not access control. GM-only
+destination notes remain absent from public site and book output.
+
+A `.secret` span does not start a journal page or change surrounding text.
+Use a [secret heading](#a-section-players-must-not-read) to withhold a whole
+Foundry page or a [secret block](#secret-blocks) for a passage in a labelled
+section; those retain their own scope and presentation.
+
 ### Alerts
 
 Alerts replace the former `:::info` and `:::warn` fences. Start with a special blockquote marker, optionally followed by an attribute block, then write the alert body as a standard blockquote:
@@ -362,8 +435,40 @@ Janapada
 : Also the land associated with that community.
 ```
 
-The web and Foundry render a definition list with HTML `<dl>`, `<dt>`, and
-`<dd>` elements. The book renders it as a term list.
+To continue the same definition, leave a blank line and indent the next
+paragraph or block by four spaces. For a fenced code block, indent both fences
+and its contents:
+
+````markdown
+Harbour due
+: A toll on every hull that ties up.
+
+    The harbourmaster collects it before unloading begins.
+
+    ```text
+    One hull: two silver pieces.
+    ```
+
+Anchorage
+: A sheltered place where a ship can lie at anchor.
+````
+
+The continuation paragraph and code block belong to the same definition.
+Repeat `:` only when starting a separate definition for the same term, as in
+the first example. The next unindented term starts a new entry.
+
+Definition lists use a dictionary hanging indent in the website, Foundry,
+preview and book. A bold term begins the row, followed by its normally styled
+definition. Short terms share a definition column 150px from the row's left
+edge; browser viewports of 600px or less use 100px. The gap after a term is
+`.75em`, with `.5em` between entries. A long term stays on one line and pushes
+the first definition farther right; wrapped lines return to the common column.
+The book uses the equivalent print dimensions.
+
+HTML surfaces preserve the semantic `<dl class="dictionary">`, `<dt>` and `<dd>`
+elements, with one grouping `<div>` for each term and all its definitions.
+Multiple definitions, continuation paragraphs, nested lists and footnotes keep
+their normal Markdown meaning. Infobox profiles retain their own layout.
 
 ## Lists
 
@@ -997,8 +1102,8 @@ common.
 
 Public dictionaries omit citations to GM-only notes. `links` checks generated
 tables in the source note's audience: public notes use public rows, and GM
-notes retain GM citations. An authored link from a public note to a GM-only
-note is still reported.
+notes retain GM citations. An authored wikilink from a public note to a GM-only
+note is valid and follows the [secret-reference rules](#references-to-secret-subjects).
 
 #### Custom views
 

package/docs/commands.md

@@ -66,6 +66,50 @@ behaviour where they appear below; read the command, not the name.
 
 ---
 
+## Standalone source preview
+
+### `package-build-preview`
+
+**NAME**
+
+Render a Markdown buffer without a content index.
+
+**SYNOPSIS**
+
+`package-build-preview [--dark] [--current-date DATE] [--css] < note.md`
+
+**DESCRIPTION**
+
+Reads Markdown from stdin and writes an HTML fragment. Requires no package
+configuration. Local Markdown and extensions render; constructs needing other
+notes remain highlighted source. Shared CSS is supplied separately.
+
+**OPTIONS**
+
+- `--dark` — select dark mode; light is the default.
+- `--current-date DATE` — override the setting-wide neutral current date; otherwise
+  read the nearest root configuration setting, defaulting to `"720.1"`.
+- `--css` — emit the shared scoped stylesheet without reading stdin.
+- `--help`, `-h` — show usage.
+
+**EXIT STATUS**
+
+0 on success, 1 for an invalid argument or rendering error. Findings go to
+stderr; stdout contains only HTML (or CSS with `--css`).
+
+**EXAMPLES**
+
+```sh
+package-build-preview --dark < note.md > preview.html
+package-build-preview --css > preview.css
+```
+
+**SEE ALSO**
+
+[Source preview and Gitea renderer](source-preview.md), [API](api.md).
+
+---
+
 ## Package and release operations
 
 ### `package-build ci`
@@ -3017,7 +3061,7 @@ exactly as given, at every depth, and every field it leaves out is generated:
 | `data.templatePriority`, `data.occupation`, `data.died` | `null`.                                                                                                                                   |
 | `data.lore`, `data.homes`                               | `[]`.                                                                                                                                     |
 | `data.affiliations`                                     | `{}`.                                                                                                                                     |
-| `data.born`                                             | An adult age of 18 to 60 years before the package's present, as a `<year>.<day>` date; `unknown` where the package states no present.     |
+| `data.born`                                             | An adult age of 18 to 60 years before the configured `currentDate` (default `"720.1"`), as a `<year>.<day>` date.                         |
 | `data.frame`, `data.appearance.*`                       | Weighted draws from the culture's appearance profile; `extra_features` is `[]`.                                                           |
 | `data.height`                                           | From the profile's range for the gender, in feet and inches.                                                                              |
 | `data.weight`                                           | From the height and the frame's body-mass band, in pounds. A spec giving height and weight but no frame gets the frame they imply.        |
@@ -3105,7 +3149,7 @@ dossier: |
   record rather than of reputation.
 ```
 
-Run against a package whose world states `present: "720.300"`, whose
+Run against a package configured with `currentDate: "720.300"`, whose
 `khelathi` culture carries the profile in
 [appearance profiles](reference/format-details.md#appearance-profiles) and
 names `language: skill-khelathilng`, and whose language carries the lists in

package/docs/configuration.md

@@ -54,7 +54,7 @@ around its own evaluation.
 
 ### Quick reference
 
-23 top-level keys. `rootDir` is not one of them — a data configuration never
+24 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -62,6 +62,7 @@ authoring.
 
 | Key                                         | Type                                                                       | Required                                                                                           | Default                   |
 | ------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------- |
+| [`currentDate`](#currentdate)               | quoted neutral date string                                                 | no                                                                                                 | `"720.1"`                 |
 | [`contentPackage`](#contentpackage)         | string                                                                     | yes                                                                                                | —                         |
 | [`foundryPackage`](#foundrypackage)         | string                                                                     | yes (`.mjs` only — derived in YAML); refused in a `documentation` package                          | —                         |
 | [`homepage`](#homepage)                     | string                                                                     | no (`.mjs` only — derived in YAML)                                                                 | `null`                    |
@@ -87,7 +88,7 @@ authoring.
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -194,7 +195,7 @@ build writes its `name` as `params.author`. `null` when `authors` is empty.
 as an unknown key, at the key's own line, because `authors` is the one list a
 package names its people in:
 
-> ``package-build config: `author` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog).``
+> ``package-build config: `author` is not a recognized option (expected one of: rootDir, contentPackage, currentDate, foundryPackage, homepage, authors, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog).``
 
 `package.json`'s own `author` is npm's and is not read.
 
@@ -294,7 +295,23 @@ Unlike the first three, authoring `itemBuilders` is not an error — it is
 
 ---
 
-## The 22 keys
+## Configuration keys
+
+### `currentDate`
+
+The setting-wide date used for computed ages, age lint, content-index dates,
+Foundry and website output, NPC generation and editor preview. It defaults to
+`"720.1"`. Quote the value so YAML preserves the exact ordinal day digits:
+
+```yaml
+contentPackage: thalorna
+currentDate: "720.130"
+```
+
+Use a neutral `<year>[.<day>[:HHMMSS]]` string. A bare quoted year means its first
+day. Named calendars, `unknown`, numeric YAML values and malformed dates are
+configuration errors located at `currentDate`. Birth dates can still use named
+calendars when the output has the relevant calendar context.
 
 ### `contentPackage`
 

package/docs/content-format.md

@@ -52,8 +52,10 @@ for examples and placement in journals, web pages, and books.
 An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
 Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
-Foundry compiles it only into private compendiums. An untagged note cannot link
-to it. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
+Foundry compiles it only into private compendiums. Ordinary wikilinks to it
+conceal the whole reference as a spoiler; `.show` reveals just the reference.
+`[text]{.secret}` marks text itself as a spoiler. Neither changes the target's
+access permissions. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
 explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.