@heroiclands/package-build 22.7.0 → 22.8.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @heroiclands/package-build
 
+## 22.8.0
+
+### Minor Changes
+
+**A being's dates**
+
+- A being says when it was born and when it died: `born:` takes over from `birthday:`, and `died:` sits beside it.
+- Either date may read `unknown` where it was never recorded; an absent `born` says the being was never born, and an absent `died` says it is alive.
+- `age:` is optional, and is an override — write it only where the number should win over the date, and write it `~34` where it is somebody's estimate.
+- A note still writing `birthday:` compiles identically and is told once what to write instead.
+- A profile reads its two dates ahead of the line describing the being's appearance.
+
+### Patch Changes
+
+**Dates**
+
+- A package can state how its year is divided — how many months, and how many
+  days to a month — and the date it treats as the present.
+- A refused `BF`/`AF` date now states the replacement rule instead of a computed value, which was wrong for `AF`.
+
+**The book**
+
+- A numbered or bulleted point whose text runs to more than one paragraph now
+  sets every paragraph flush under the point, so it reads as one block hanging
+  off its number instead of a stray indented paragraph beneath it.
+
+**A draft entry's notice**
+
+- The sentence sets in italic, with `Draft.` in bold ahead of it, on the page, in a journal entry and on an actor's dossier alike: the entry speaking about its own state rather than about the world.
+- In the book the notice's mark sits in a column of its own, so a sentence that runs to two lines sets both of them clear of it.
+- The mark is a filled disc with the exclamation knocked out of it, in the book's accent.
+- The sentence sets at the size, face and ink of the entry's prose; the rule down its edge and the mark are what set it apart.
+
 ## 22.7.0
 
 ### Minor Changes

package/content-config.mjs

@@ -76,6 +76,7 @@ import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.m
 import { MAP_TYPES, NO_PACK, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
+import { UNKNOWN_DATE, parseNoteDate } from "./engine/note-dates.mjs";
 
 /**
  * What kind of package this is.
@@ -725,6 +726,10 @@ export function publishesContentPages(config) {
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
  *                                     each pack followed by its companions.
+ * @property {Readonly<{months: number|null, monthDays: number|null, present: string|null}>} calendar
+ *                                     How this package's year is divided, and
+ *                                     the date it calls the present. Every
+ *                                     value `null` when none is declared.
  * @property {Readonly<PackageBuildSection>} packageBuild  Passed through
  *                                     frozen, uninterpreted. `{}` when absent.
  * @property {Readonly<DocsSpec>} docs   Frozen; `{}` when absent.
@@ -754,11 +759,13 @@ const CONFIG_KEYS = [
     "relationships",
     "systems",
     "requiresSystem",
+    "calendar",
     "packageBuild",
     "publish",
     "changelog",
 ];
 const SYSTEM_KEYS = ["manifest", "compatibility"];
+const CALENDAR_KEYS = ["months", "monthDays", "present"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const CHANGELOG_KEYS = ["labels"];
@@ -2070,6 +2077,76 @@ function normalizeRequiresSystem(value) {
     return requireNonEmptyString(value, "requiresSystem");
 }
 
+/**
+ * How this package's year is divided, and the date it calls the present.
+ *
+ * **Nothing here is about which people count from what.** A reckoning is an
+ * era, declared by the affiliation that proclaimed it, and its epoch is the
+ * `start` written on that note — so the only things configuration states are
+ * the ones no note could.
+ *
+ * `months` and `monthDays` bound a written month and day. Both are optional,
+ * and an absent one is checked against nothing: a toolchain that assumed a
+ * Gregorian year here would refuse `667/2/30`, an ordinary date in a year of
+ * twelve thirty-day months. One subdivision to a package — an era moves where
+ * year 1 sits, it does not divide the year differently.
+ *
+ * `present` is the date the package computes an age against, written in the
+ * same grammar a note's dates use, so a package whose present is best said in
+ * an era says it that way. A package that states none computes no age, which
+ * is the right answer for a corpus that has no present.
+ *
+ * @param {unknown} value - The declared `calendar:` mapping.
+ * @returns {Readonly<{months: number|null, monthDays: number|null, present: string|null}>}
+ *   Frozen; every value `null` when absent.
+ */
+function normalizeCalendar(value) {
+    if (value === undefined || value === null) {
+        return Object.freeze({ months: null, monthDays: null, present: null });
+    }
+    if (!isPlainObject(value)) fail("calendar", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, CALENDAR_KEYS, "calendar.");
+
+    const bound = (key) => {
+        const held = input[key];
+        if (held === undefined || held === null) return null;
+        if (!Number.isInteger(held) || /** @type {number} */ (held) < 1) {
+            fail(`calendar.${key}`, "must be a positive integer");
+        }
+        return /** @type {number} */ (held);
+    };
+    const months = bound("months");
+    const monthDays = bound("monthDays");
+
+    // Read through the parser the notes use rather than a second grammar, and
+    // against this package's own bounds — a present outside the year it
+    // declares is the one date nothing downstream would report.
+    let present = null;
+    if (input.present !== undefined && input.present !== null) {
+        if (typeof input.present !== "string" && typeof input.present !== "number") {
+            fail("calendar.present", "must be a date written as a string");
+        }
+        if (String(input.present).trim() === UNKNOWN_DATE) {
+            fail(
+                "calendar.present",
+                `must be a date — a package that states no present computes no age, ` +
+                    `so leave the key out rather than writing \`${UNKNOWN_DATE}\``,
+            );
+        }
+        const { date, findings } = parseNoteDate(input.present, {
+            calendar: { months, monthDays },
+            allowUnknown: false,
+        });
+        const refused = findings.find((finding) => finding.severity === "error");
+        if (refused)
+            fail("calendar.present", `is not a date this package can read — ${refused.message}`);
+        present = /** @type {{text: string}} */ (date).text;
+    }
+
+    return Object.freeze({ months, monthDays, present });
+}
+
 /**
  * Validate the declared relationships.
  *
@@ -2801,6 +2878,7 @@ export function defineConfig(config) {
         relationships: normalizeRelationships(input.relationships),
         systems,
         requiresSystem,
+        calendar: normalizeCalendar(input.calendar),
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
         changelog: normalizeChangelog(input.changelog),

package/docs/api.md

@@ -604,6 +604,28 @@ The closed registry of system ids, and the `none` that stands for no system at a
 | `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                      |
 | `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment                     |
 
+### `engine.calendars`
+
+The axis every date normalises onto, and the one function that puts a reckoning on it. A reckoning is an **era** declared by the affiliation that proclaimed it, and its epoch is the `start` written on that note — nothing is registered in configuration. The conversion is piecewise on the sign, because the authored numbering has no year zero while the normalised value does: authored `-1` is `0`, and `-1` and `1` are adjacent.
+
+| Export              | Signature                       | Returns                                       | Use it when                                                                     |
+| ------------------- | ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
+| `CANONICAL_EPOCH`   | `const CANONICAL_EPOCH`         | —                                             | naming where the canonical axis's own year 1 sits                               |
+| `canonicalYear`     | `canonicalYear(year, epoch?)`   | `number` — the signed year on the axis        | converting a year written in one reckoning to the number everything compares on |
+| `dateSortKey`       | `dateSortKey(year, month, day)` | `number`                                      | ordering mixed-precision dates against a single number                          |
+| `calendarStructure` | `calendarStructure(calendar)`   | `{months, monthDays}` — `null` where unstated | reading the month bounds a package declares, before phrasing a finding          |
+
+### `engine.noteDates`
+
+A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era shortcode>]` — and every field holding one parses through a single grammar into a single record. Print `text`, order on `sort`, do arithmetic on `canonicalYear`. A bare value sits on the canonical axis and carries `era: null`; one naming an era carries the qualifier and no `canonicalYear` or `sort` keys at all until the era is resolved against the corpus. The literal `unknown` parses to the same record with the year half empty, carrying a null `sort` and a null `canonicalYear`, so nothing can order it to one end of a list.
+
+| Export                  | Signature                       | Returns                                            | Use it when                                                   |
+| ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`            | —                                                  | naming the literal that says a date is not recorded           |
+| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`       | —                                                  | matching the date grammar directly                            |
+| `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`   | —                                                  | checking that a string is an era qualifier a date could carry |
+| `parseNoteDate`         | `parseNoteDate(value, options)` | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned  |
+
 ### `engine.contentAddress`
 
 Where a content note publishes on the web. One rule, in one place, because two builds need the same answer: the knowledgebase build renders the page, and the link manifest records the address other packages link to. Stating it twice is how a manifest comes to assert a URL that resolves at build time and 404s for the reader.

package/docs/configuration.md

@@ -48,7 +48,7 @@ around its own evaluation.
 
 ### Quick reference
 
-21 top-level keys. `rootDir` is not one of them — a data configuration never
+22 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
@@ -74,13 +74,14 @@ authoring.
 | [`relationships`](#relationships)           | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`systems`](#systems)                       | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
+| [`calendar`](#calendar)                     | object                                                                     | no                                                                                                 | no bounds, no present                       |
 | [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                                        |
 | [`publish`](#publish)                       | object                                                                     | no; **required**, with `site: content`, in a `documentation` package                               | `{site: "homepage", address: {prefix: ""}}` |
 | [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`                            |
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, calendar, 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
@@ -290,7 +291,7 @@ Unlike the first three, authoring `itemBuilders` is not an error — it is
 
 ---
 
-## The 21 keys
+## The 22 keys
 
 ### `contentPackage`
 
@@ -1297,6 +1298,59 @@ With one, naming what it does declare instead:
 
 > ``package-build config: `requiresSystem` must be a non-empty string.``
 
+### `calendar`
+
+**Type:** object · **Optional** · default: no bounds and no present.
+
+How this package's year is divided, and the date it calls the present:
+
+```yaml
+calendar:
+  months: 12
+  monthDays: 30
+  present: 720/6/19
+```
+
+**Nothing here is about which people count from what.** A reckoning is an
+**era**, declared by the affiliation that proclaimed it, and its epoch is the
+`start` written on that note — so the only things this block states are the ones
+no note could.
+
+| Key (under `calendar`) | Type             | Required | Default |
+| ---------------------- | ---------------- | -------- | ------- |
+| `calendar.months`      | positive integer | no       | `null`  |
+| `calendar.monthDays`   | positive integer | no       | `null`  |
+| `calendar.present`     | date string      | no       | `null`  |
+
+`months` and `monthDays` bound a written month and day. **Both are optional, and
+an absent one is checked against nothing** — a year of twelve thirty-day months
+is as ordinary here as a Gregorian one, so the bound is declared or it is not
+applied. One subdivision to a package: an era moves where year 1 sits, it does
+not divide the year differently.
+
+`present` is the date an age is computed against. It is written in the same
+grammar a note's dates use — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era
+shortcode>]` — so a package whose present is best said in an era says it that
+way, and one that states no present computes no age at all.
+
+An age is a function of two **dates**, not two years: subtracting years alone
+reds every note whose birthday falls later in the year than the present date, so
+the day is part of what is declared.
+
+> ``package-build config: `calendar` must be a mapping.``
+
+> ``package-build config: `calendar.months` must be a positive integer.``
+
+> ``package-build config: `calendar.monthDays` must be a positive integer.``
+
+> ``package-build config: `calendar.present` must be a date written as a string.``
+
+> ``package-build config: `calendar.present` must be a date — a package that states no present computes no age, so leave the key out rather than writing `unknown`.``
+
+> ``package-build config: `calendar.present` is not a date this package can read — `720/13/1` writes month 13, and `calendar.months` declares a year of 12.``
+
+> ``package-build config: `calendar.<key>` is not a recognized option (expected one of: months, monthDays, present).``
+
 ### `packageBuild`
 
 Reserved for `@heroiclands/package-build`'s own packaging half — see

package/docs/content-format.md

@@ -2301,8 +2301,9 @@ Generates a living (or undead, or spirit) being.
 | `affiliations`              | `WikiLink[]`                                   | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
 | `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
 | `species`                   | `WikiLink`                                     | Being's species (lore)                                                                           |
-| `age`                       | `number`                                       | Age of the character                                                                             |
-| `birthday`                  | `YYYY/MM/DD`                                   | Date of birth of the character                                                                   |
+| `born`                      | `YYYY/MM/DD \| unknown`                        | When the being was born; absent, it was never born                                               |
+| `died`                      | `YYYY/MM/DD \| unknown`                        | When the being died; absent, it is alive                                                         |
+| `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                    |
 | `height`                    | `number`                                       | Height in meters                                                                                 |
 | `weight`                    | `number`                                       | Weight in kilograms                                                                              |
 | `frame`                     | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                              |
@@ -2312,6 +2313,31 @@ Generates a living (or undead, or spirit) being.
 | `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
 | `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
 
+#### When a being was born, when it died, and how old it is
+
+**Absence asserts a fact rather than recording a gap**, and that is what these
+three fields are built around.
+
+- **`born` absent** says the being was **never born** — a construct, a spirit,
+  an elemental, a thing that was made. **`born: unknown`** says it was born and
+  the date is unrecorded, which is the commonest shape in a tree.
+- **`died` absent** says the being is **alive**, which is the common case and so
+  takes the cheapest form. **`died: unknown`** says it is dead and the date is
+  unrecorded. Both spellings of `died` mean dead.
+- **`age` is optional and is an override.** Written, it wins over anything the
+  dates say. Unwritten beside a dated `born`, it is the age that follows from
+  the date. Unwritten beside `born: unknown` or an absent `born`, the age is
+  unknown.
+
+Most people in a setting do not know their own birth date, so an age beside
+`born: unknown` is an ordinary complete record and not a note working around the
+schema. Where the number is somebody's estimate rather than a fact, write it
+`~34` — the same `~` a date carries.
+
+`birthday:` is the retired spelling of `born:`. Both are read and `born` wins,
+so a note compiles identically either way; the old spelling is reported until
+every tree has moved.
+
 #### The lead image
 
 **A being's portrait is the first thing inside its `{#appearance}` section,

package/engine/calendars.mjs

@@ -0,0 +1,132 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **The axis every date normalises onto, and the one function that puts a
+ * reckoning on it.**
+ *
+ * A setting keeps several counts of years at once, each proclaimed by a body
+ * that has a note — a founding, a first occasion, a reign. A date either names
+ * one of them or names none, in which case it sits on the **canonical axis**.
+ *
+ * ## The canonical axis is an authoring device, not a calendar
+ *
+ * The axis is the line of integers dates written by peoples who never met are
+ * compared on. Nobody in a setting keeps it, no body stands behind it, and no
+ * shortcode addresses it: a date is on the axis exactly when it names no era.
+ * A reckoning whose year 1 happens to sit where the axis's year 1 sits
+ * coincides with it numerically and is still that people's own count.
+ *
+ * ## There is no year zero, and one function converts
+ *
+ * The authored numbering skips zero — `-1` sits immediately before `1` — while
+ * the normalised value does not, so that arithmetic across an epoch is one
+ * subtraction rather than a special case somebody forgets.
+ *
+ * ```text
+ * authored        …  -3   -2   -1    1    2    3  …
+ * canonicalYear   …  -2   -1    0    1    2    3  …
+ * ```
+ *
+ * ```text
+ * canonicalYear(y, E) = E + (y > 0 ? y - 1 : y)
+ * ```
+ *
+ * `E` is where a reckoning's year 1 sits on the axis — the `canonicalYear` of
+ * an era's own `start`. The axis is the same function with `E` of
+ * {@link CANONICAL_EPOCH}, which holds by definition: the axis's year 1 is the
+ * axis's year 1.
+ *
+ * **The conversion is piecewise on the sign**, and that is the property worth
+ * guarding. Collapsed to a single branch it is correct on one side of an epoch
+ * and off by one on the other, which is invisible in any list that does not
+ * span it.
+ *
+ * ## The month structure is the package's, and an absent bound checks nothing
+ *
+ * An era moves where year 1 sits; it does not divide the year differently. So
+ * the subdivision is declared once for the package, in `calendar.months` and
+ * `calendar.monthDays`, and a package that declares neither is bounded below
+ * and not above — a toolchain that invented twelve Gregorian months would
+ * refuse `667/2/30`, which is an ordinary date in a year of twelve thirty-day
+ * months.
+ *
+ * @module
+ */
+
+/**
+ * Where the canonical axis's own year 1 sits — on itself.
+ *
+ * It takes no configuration entry and no era row, because it is true by
+ * definition rather than by declaration.
+ *
+ * @type {number}
+ */
+export const CANONICAL_EPOCH = 1;
+
+/**
+ * The year on the canonical axis that a written year lands on.
+ *
+ * The whole of the conversion. A reckoning differs from its neighbours in
+ * where its year 1 sits and in nothing else, so an era states one number and
+ * this states what to do with it.
+ *
+ * The two branches are the year-zero hole: the authored numbering has no year
+ * 0, so a positive year is one place closer to the epoch than its magnitude
+ * suggests and a negative year is exactly its magnitude below it.
+ *
+ * @param {number} year - The year as authored, signed, within its own
+ *   reckoning. Never 0 — the authored numbering has no such year.
+ * @param {number} [epoch] - Where that reckoning's year 1 sits on the axis.
+ *   Omitted, the axis itself.
+ * @returns {number} The signed year on the axis — authored `-1` is `0`.
+ */
+export function canonicalYear(year, epoch = CANONICAL_EPOCH) {
+    return epoch + (year > 0 ? year - 1 : year);
+}
+
+/**
+ * The total-order key a date sorts on.
+ *
+ * Month and day fold into the fraction, so a mixed-precision list sorts stably
+ * against a single number instead of a three-key comparator. The arithmetic is
+ * done in ten-thousandths and divided once, because `year + 6 / 100 + 19 /
+ * 10000` accumulates a rounding error and `689.0619` is a value a reader
+ * compares against by eye.
+ *
+ * A coarser value sorts **before** the finer values inside it: `689` precedes
+ * `689/1`, which is the ordering a reader expects of a year whose month nobody
+ * wrote.
+ *
+ * @param {number} year - The year on the canonical axis.
+ * @param {number|null} month - The month, or `null`.
+ * @param {number|null} day - The day, or `null`.
+ * @returns {number} The sort key.
+ */
+export function dateSortKey(year, month, day) {
+    return (year * 10000 + (month ?? 0) * 100 + (day ?? 0)) / 10000;
+}
+
+/**
+ * The bounds a package states for a month, or `null` where it states none.
+ *
+ * Separate from the check that reads it so a caller can ask what a package
+ * declares without phrasing a finding about it.
+ *
+ * @param {{months?: number|null, monthDays?: number|null}} [calendar] - The
+ *   resolved `calendar:` block.
+ * @returns {{months: number|null, monthDays: number|null}} What it declares.
+ */
+export function calendarStructure(calendar) {
+    return { months: calendar?.months ?? null, monthDays: calendar?.monthDays ?? null };
+}

package/engine/content-format-check.mjs

@@ -102,6 +102,7 @@ import { currentType } from "./ids.mjs";
 import { SCHEMA_ARTIFACT_VERSION } from "./schema-check.mjs";
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -357,8 +358,16 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
 
     // `data:` is closed: every key it carries must be one the type declares.
     const data = isBlock(fm.data) ? fm.data : undefined;
+    // The retired spelling of a key the format states is measured as the key it
+    // will be written as, exactly as a note still on a renamed *type* is
+    // measured against the section it will move to. The rename itself is the
+    // frontmatter lint's finding, and reporting it here as well would count one
+    // note twice in a migration whose counts are the point.
+    const renamedDataKeys = new Set(
+        [...spec.dataKeys].map((key) => RETIRED_FIELD_ALIASES[key]).filter(Boolean),
+    );
     for (const key of Object.keys(data ?? {})) {
-        if (spec.dataKeys.has(key)) continue;
+        if (spec.dataKeys.has(key) || renamedDataKeys.has(key)) continue;
         const guess = nearest(key, spec.dataKeys);
         add(
             "unknown-data-key",

package/engine/draft-notice.mjs

@@ -33,6 +33,14 @@
  * is the floor each surface is built to, because each of them can lose
  * everything around it.
  *
+ * **The label is bold roman and the sentence is italic**, on every surface. The
+ * words around it are the world describing itself; this one sentence is the
+ * text speaking about its own state, and italic is how a reader is told the
+ * voice has changed. It is the one typographic mark the sentence carries:
+ * smaller or lighter type would say the reader may skip it, which is the
+ * opposite of what it is for, and a bold italic beside the mark would be one
+ * emphasis too many.
+ *
  * ## What each surface can rely on
  *
  * - **Foundry** renders a JournalEntry's own HTML inside a sheet, so the floor
@@ -87,7 +95,8 @@ export const BOOK_DRAFT_NOTICE = "book-draft-notice";
  * `body.game .app blockquote` carries a left rule and an indent — so the
  * treatment survives with no stylesheet of this package's own. The mark is a
  * Font Awesome element, which Foundry bundles; `aria-hidden` keeps it out of a
- * screen reader, where the label reads it.
+ * screen reader, where the label reads it. The sentence is an `em`, which every
+ * renderer of HTML sets in italic with no stylesheet to ask.
  *
  * @returns {string} The notice's HTML.
  */
@@ -95,7 +104,7 @@ export function draftNoticeHtml() {
     return (
         `<blockquote class="${DRAFT_NOTICE_CLASS}">` +
         `<p><i class="fa-solid ${DRAFT_NOTICE_ICON}" aria-hidden="true"></i> ` +
-        `<strong>${DRAFT_NOTICE_LABEL}</strong> ${DRAFT_NOTICE}</p>` +
+        `<strong>${DRAFT_NOTICE_LABEL}</strong> <em>${DRAFT_NOTICE}</em></p>` +
         `</blockquote>`
     );
 }
@@ -139,9 +148,30 @@ export function withDraftNotice(fm, html) {
 /**
  * The `#let` the book's notice is drawn by.
  *
- * Emitted with the rest of the book's preamble. The mark is a circle with an
- * exclamation set inside it: two primitives and the face already setting the
- * page, so there is no font to resolve and nothing that can come out as a box.
+ * Emitted with the rest of the book's preamble. The mark is a disc with an
+ * exclamation knocked out of it: two primitives and the face already setting
+ * the page, so there is no font to resolve and nothing that can come out as a
+ * box. It is filled in the accent the book rules its headings with and the
+ * glyph is the colour of the paper, so the mark carries against the running
+ * face rather than reading as a character of it.
+ *
+ * **The mark is a column, not a word.** A two-column grid puts it beside the
+ * sentence rather than inside it, so a notice that takes two lines sets its
+ * second line against the first and never under the disc; the grid centres the
+ * mark's cell on the block, so it holds the middle of one line or two. The rule
+ * is the block's own left stroke and spans whatever height the sentence takes.
+ *
+ * **The sentence sets in the book's body face, size and ink**, because it is
+ * the one thing in the entry a reader has to read before trusting the rest. The
+ * rule and the mark set the block apart; nothing else has to, and type set
+ * smaller or lighter than the prose around it reads as apparatus a reader may
+ * skip. The mark scales with that text, so a consumer setting the book larger
+ * or smaller carries the disc with it.
+ *
+ * **One number sets the mark.** The glyph is a multiple of the disc's radius
+ * rather than a size of its own, so the exclamation keeps its share of the disc
+ * however large the disc is drawn and resizing the mark is one edit. Both are
+ * `em`, so the mark still follows the body text.
  *
  * @returns {string} The Typst definition.
  */
@@ -152,14 +182,16 @@ export function bookDraftNoticePreamble() {
         "  inset: (left: 0.7em, top: 0.35em, bottom: 0.35em),\n" +
         "  stroke: (left: 1.6pt + book-faint))[\n" +
         "  #set par(justify: false, first-line-indent: 0em)\n" +
-        "  #set text(size: 8.6pt, fill: book-faint)\n" +
-        "  #box(baseline: 0.18em, circle(radius: 0.42em, stroke: 0.6pt + book-faint)[\n" +
-        '    #align(center + horizon)[#text(size: 6.4pt, weight: "bold")[!]]\n' +
-        "  ])\n" +
-        "  #h(0.4em)\n" +
-        '  #text(weight: "bold")[#label]\n' +
-        "  #h(0.25em)\n" +
-        "  #body\n" +
+        "  #let radius = 0.69em\n" +
+        "  #grid(columns: (auto, 1fr), column-gutter: 0.5em,\n" +
+        "    align: (center + horizon, horizon),\n" +
+        "    circle(radius: radius, fill: book-accent)[\n" +
+        "      #align(center + horizon)[\n" +
+        '        #text(size: 1.6 * radius, weight: "bold", fill: book-paper)[!]\n' +
+        "      ]\n" +
+        "    ],\n" +
+        '    [#text(weight: "bold")[#label]#h(0.25em)#emph[#body]],\n' +
+        "  )\n" +
         "]"
     );
 }

package/engine/frontmatter-lint.mjs

@@ -455,8 +455,34 @@ function checkDataContainer(note, { type, fields, packs }) {
     /** First segment of each declared name — `charges.value` is authored as `charges`. */
     const declared = new Set(fields.map((f) => f.name.split(".")[0]));
 
+    // The retired spelling of a key this type declares → what to write now.
+    // Built from the type's own declaration, so a renamed `data:` key is
+    // retired exactly where its replacement exists and stays an unrecognised
+    // key on every other type.
+    const renamed = new Map();
+    for (const name of declared) {
+        const retired = RETIRED_FIELD_ALIASES[name];
+        if (retired) renamed.set(retired, name);
+    }
+
     for (const key of Object.keys(entries)) {
         if (declared.has(key)) continue;
+        const current = renamed.get(key);
+        if (current) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw, ["data", key], { key: true }),
+                // A warning, as every retired spelling is: the note compiles to
+                // the correct document, so failing a build over it would red a
+                // tree that has done nothing wrong yet. The refusal comes once
+                // no tree writes the key, and needs no code — with the alias
+                // gone the spelling is an unrecognised key again, which the
+                // loop below already refuses.
+                severity: "warning",
+                message: retiredAliasMessage(key, current),
+            });
+            continue;
+        }
         const guess = nearest(key, declared);
         findings.push({
             file: note.file,

package/engine/index.mjs

@@ -124,6 +124,12 @@ export * as siteMaps from "./site-maps.mjs";
 /** The closed registry of system ids, and the `none` that stands for no system. */
 export * as systems from "./systems.mjs";
 
+/** The reckonings a package dates by, and the arithmetic that puts them on one line. */
+export * as calendars from "./calendars.mjs";
+
+/** A note's dates: one authored string, one grammar, one record shape. */
+export * as noteDates from "./note-dates.mjs";
+
 /** The one normalisation this build makes: prose to a URL-safe token. */
 export * as contentSlug from "./content-slug.mjs";