@heroiclands/package-build 22.14.3 → 22.15.0

package/engine/map-graphviz.mjs

@@ -1,147 +1,66 @@
-/*
- * 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
- */
+// SPDX-License-Identifier: GPL-3.0-or-later
 
-/**
- * GraphViz, as `content-build map` reaches it.
- *
- * GraphViz is a build-time tool of the map command alone: nothing else in the
- * toolchain draws, so nothing else depends on it, and a package that never
- * runs `map` never needs it installed. The command finds the engine it needs
- * once, names what to install when it is absent, and runs it over a `.dot`
- * file it has already written — the `.dot` is always kept beside the `.svg`,
- * so a drawing can be re-rendered, inspected or diffed without re-reading the
- * content index.
- *
- * @module
- */
+/** Render DOT maps with the Graphviz runtime installed by npm. */
 
 import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { instance } from "@viz-js/viz";
+import { Resvg } from "@resvg/resvg-js";
 
-/**
- * The layout engines the map command may ask for. `dot` draws a tree by
- * rank, `twopi` the same tree radially, `neato` a graph by its edge lengths —
- * and, with every node pinned, the map from a place.
- *
- * @type {readonly string[]}
- */
+/** The layout engines accepted by the map command. */
 export const GRAPHVIZ_ENGINES = Object.freeze(["dot", "twopi", "neato"]);
 
-/**
- * Where a package manager puts GraphViz when `PATH` does not say: Homebrew
- * on Apple silicon, Homebrew on Intel, and the system directories.
- *
- * @type {readonly string[]}
- */
-const KNOWN_DIRECTORIES = Object.freeze([
-    "/opt/homebrew/bin",
-    "/usr/local/bin",
-    "/usr/bin",
-    "/opt/local/bin",
-]);
+const graphviz = await instance();
 
 /**
- * Find a GraphViz engine's binary.
+ * Render a DOT source file to SVG, plain positions, or a PNG background.
  *
- * `PATH` first, then the directories a package manager installs into, so a
- * shell whose profile does not export Homebrew's directory still finds it.
- * The result is a path to a file that exists; whether it runs is the render's
- * business.
+ * A PNG uses the same Graphviz SVG layout as the vector map. SVG dimensions
+ * are in points; resvg starts at 96 pixels per inch, so the zoom converts
+ * the requested DPI to the same physical size as Graphviz's PNG output.
  *
- * @param {string} engine - One of {@link GRAPHVIZ_ENGINES}.
- * @param {object} [opts]
- * @param {Record<string, string|undefined>} [opts.env] - The environment to
- *   read `PATH` from, defaulting to the process's.
- * @param {readonly string[]} [opts.fallbacks] - The directories tried after
- *   `PATH`, defaulting to the package managers' ones.
- * @returns {string|undefined} The binary, or `undefined` when none is found.
- * @throws {Error} When `engine` is not a GraphViz engine this command uses.
+ * @param {string} dotPath - The saved DOT source.
+ * @param {string} outPath - The output file.
+ * @param {object} opts
+ * @param {"dot"|"twopi"|"neato"} opts.engine - Layout engine.
+ * @param {"svg"|"plain"|"png"} [opts.format="svg"] - Output format.
+ * @param {2} [opts.nop] - Preserve positioned nodes as `neato -n2` does.
+ * @param {number} [opts.dpi=96] - PNG resolution.
+ * @returns {{warnings: string}} Renderer warnings.
  */
-export function findGraphviz(engine, { env = process.env, fallbacks = KNOWN_DIRECTORIES } = {}) {
+export function renderDot(dotPath, outPath, { engine, format = "svg", nop, dpi = 96 }) {
     if (!GRAPHVIZ_ENGINES.includes(engine)) {
-        throw new Error(
-            `"${engine}" is not a GraphViz engine the map command uses; ` +
-                `choose ${GRAPHVIZ_ENGINES.join(", ")}`,
-        );
+        throw new Error(`Unsupported Graphviz engine "${engine}" for ${dotPath}`);
     }
-    const onPath = String(env.PATH ?? "")
-        .split(path.delimiter)
-        .filter(Boolean);
-    for (const dir of [...onPath, ...fallbacks]) {
-        const candidate = path.join(dir, engine);
-        try {
-            if (fs.statSync(candidate).isFile()) return candidate;
-        } catch {
-            // Not here; the next directory may have it.
+    const dot = fs.readFileSync(dotPath, "utf8");
+    try {
+        const result = graphviz.render(dot, {
+            engine: nop === 2 ? "nop2" : engine,
+            format: format === "png" ? "svg" : format,
+        });
+        if (result.status !== "success" || !result.output) {
+            throw new Error(result.errors.map((error) => error.message).join("; ") || "no output");
         }
+        if (format === "png") {
+            const image = new Resvg(result.output, {
+                fitTo: { mode: "zoom", value: dpi / 96 },
+            }).render();
+            fs.writeFileSync(outPath, image.asPng());
+        } else {
+            fs.writeFileSync(outPath, result.output);
+        }
+        // The embedded renderer uses Times metrics for the generated bold
+        // headings; its warning repeats for every map and needs no action.
+        return {
+            warnings: result.errors
+                .filter(
+                    (error) =>
+                        error.level === "warning" &&
+                        !error.message.includes("no hard-coded metrics for 'Helvetica-Bold'"),
+                )
+                .map((error) => error.message)
+                .join("; "),
+        };
+    } catch (error) {
+        throw new Error(`Graphviz failed over ${dotPath}: ${error.message}`, { cause: error });
     }
-    return undefined;
-}
-
-/**
- * What installs GraphViz on the two platforms a contributor is likely to be
- * on, as the clause every "not installed" message ends with.
- *
- * @type {string}
- */
-export const GRAPHVIZ_INSTALL =
-    "install GraphViz (`brew install graphviz` on macOS, " +
-    "`apt-get install graphviz` on Debian or Ubuntu)";
-
-/**
- * What to say when an engine is not installed: the name, and what installs
- * it.
- *
- * @param {string} engine - The engine that was wanted.
- * @returns {string} The message.
- */
-export function graphvizMissingMessage(engine) {
-    return (
-        `GraphViz's \`${engine}\` is not installed, and \`content-build map\` draws with it; ` +
-        `${GRAPHVIZ_INSTALL} and run the command again`
-    );
-}
-
-/**
- * Render a `.dot` file with a GraphViz engine.
- *
- * The engine is run over the file rather than fed the text, so the file the
- * command keeps is exactly what was drawn. Warnings GraphViz prints — an
- * unknown font, an overlapping label — are returned rather than swallowed,
- * and a non-zero exit is an error naming the file.
- *
- * @param {string} dotPath - The `.dot` file.
- * @param {string} outPath - Where to write the rendering.
- * @param {object} opts
- * @param {string} opts.binary - The engine's binary, from {@link findGraphviz}.
- * @param {string} [opts.format="svg"] - The `-T` format.
- * @param {string[]} [opts.args] - Further arguments, before the file.
- * @returns {{warnings: string}} What the engine printed on stderr.
- * @throws {Error} When the engine exits non-zero or cannot be run.
- */
-export function renderDot(dotPath, outPath, { binary, format = "svg", args = [] }) {
-    const result = spawnSync(binary, [`-T${format}`, ...args, dotPath, "-o", outPath], {
-        encoding: "utf8",
-    });
-    if (result.error) {
-        throw new Error(`${binary} could not be run over ${dotPath}: ${result.error.message}`);
-    }
-    if (result.status !== 0) {
-        throw new Error(
-            `${binary} failed over ${dotPath} (exit ${result.status}): ` +
-                `${String(result.stderr ?? "").trim()}`,
-        );
-    }
-    return { warnings: String(result.stderr ?? "").trim() };
 }

package/engine/map-notes.mjs

@@ -113,6 +113,12 @@ export const MAP_SUBTYPE_PROFILES = Object.freeze({
         fog: { mode: 0 /* DISABLED */ },
         padding: 0,
     }),
+    totm: Object.freeze({
+        grid: { type: 0 /* GRIDLESS */, distance: 1, units: "" },
+        tokenVision: false,
+        fog: { mode: 0 /* DISABLED */ },
+        padding: 0,
+    }),
 });
 
 /**
@@ -894,6 +900,23 @@ export function buildScene(fm, ctx) {
     const sceneId = fm.id;
     if (!sceneId) throw new Error("a map note needs an `id`");
     const profile = mapProfile(fm.subType);
+    const scale = fm.data?.scale;
+    if (scale !== undefined) {
+        if (
+            fm.subType !== "regionalmap" ||
+            !scale ||
+            typeof scale !== "object" ||
+            Array.isArray(scale) ||
+            Object.keys(scale).some((key) => !["distance", "unit"].includes(key)) ||
+            !(Number.isFinite(scale.distance) && scale.distance > 0) ||
+            typeof scale.unit !== "string" ||
+            !scale.unit.trim()
+        ) {
+            throw new Error(
+                "`data.scale` on a regionalmap is {distance: positive number, unit: nonempty string}",
+            );
+        }
+    }
 
     const dimensions = sohl.dimensions;
     if (
@@ -903,7 +926,7 @@ export function buildScene(fm, ctx) {
     ) {
         throw new Error("`dimensions` is [width, height] in whole pixels — the map's own size");
     }
-    const pxPerGrid = sohl.pxPerGrid;
+    const pxPerGrid = fm.subType === "totm" ? 100 : sohl.pxPerGrid;
     if (!Number.isInteger(pxPerGrid) || pxPerGrid <= 0) {
         throw new Error(
             "`pxPerGrid` is the whole number of pixels per grid square, and must " +
@@ -933,8 +956,8 @@ export function buildScene(fm, ctx) {
         grid: {
             type: profile.grid.type,
             size: pxPerGrid,
-            distance: profile.grid.distance,
-            units: profile.grid.units,
+            distance: scale?.distance ?? profile.grid.distance,
+            units: scale?.unit ?? profile.grid.units,
         },
         tokenVision: profile.tokenVision,
         fog: { mode: profile.fog.mode },

package/engine/map-places.mjs

@@ -332,7 +332,8 @@ export function mapWorld({ records, foreignIndex, contentBase, base, config }) {
  * What `parents` says about the world's shape.
  *
  * @typedef {object} Containment
- * @property {string|undefined} world - The one `subType: world` place.
+ * @property {string|undefined} world - The world when exactly one is present.
+ * @property {string[]} worlds - Every `subType: world` place, sorted.
  * @property {string[]} continents - Regions parented directly on the world,
  *   in name order.
  * @property {Map<string, string>} continentOf - Each place's continent, for
@@ -412,8 +413,12 @@ function findCycles(places) {
  * @returns {Containment} The analysis.
  */
 export function analyzeContainment(places, polities = []) {
-    const worlds = [...places.values()].filter((p) => p.subType === "world");
-    const world = worlds[0]?.shortcode;
+    const worlds = [...places.values()]
+        .filter((p) => p.subType === "world")
+        .map((p) => p.shortcode)
+        .sort();
+    const world = worlds.length === 1 ? worlds[0] : undefined;
+    const worldSet = new Set(worlds);
 
     /** @type {Map<string, string[]>} */
     const children = new Map();
@@ -431,8 +436,8 @@ export function analyzeContainment(places, polities = []) {
     const resolve = (sc, visiting) => {
         if (continentOf.has(sc)) return continentOf.get(sc);
         const place = places.get(sc);
-        if (!place || sc === world || visiting.has(sc)) return undefined;
-        if (place.subType === "region" && world !== undefined && place.parents.includes(world)) {
+        if (!place || worldSet.has(sc) || visiting.has(sc)) return undefined;
+        if (place.subType === "region" && place.parents.some((parent) => worldSet.has(parent))) {
             continentOf.set(sc, sc);
             return sc;
         }
@@ -476,7 +481,7 @@ export function analyzeContainment(places, polities = []) {
     };
     for (const sc of [...places.keys()].sort()) {
         const place = /** @type {MapPlace} */ (places.get(sc));
-        if (place.parents.length === 0 && sc !== world) anomalies.noParent.push(sc);
+        if (place.parents.length === 0 && !worldSet.has(sc)) anomalies.noParent.push(sc);
         if (place.parents.length > 1) anomalies.multiParent.push(sc);
         if (place.local && place.subType === "region" && place.hasPackFolder === false) {
             anomalies.regionNoPackFolder.push(sc);
@@ -492,6 +497,7 @@ export function analyzeContainment(places, polities = []) {
 
     return {
         world,
+        worlds,
         continents,
         continentOf,
         children,

package/engine/map-raster.mjs

@@ -0,0 +1,49 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { Resvg } from "@resvg/resvg-js";
+
+/** Rasterize an authored SVG map into the staged Foundry package. */
+export function rasterizeMapSvg({ foundryPath, width, height, sceneId, config }) {
+    if (!config) throw new Error("SVG map rasterization requires the package build configuration");
+    if (![width, height].every((value) => Number.isInteger(value) && value > 0)) {
+        throw new Error("an SVG map needs `sohl.dimensions: [width, height]` in whole pixels");
+    }
+    const marker = "/assets/";
+    const at = foundryPath.indexOf(marker);
+    if (at < 0 || !foundryPath.toLowerCase().endsWith(".svg")) {
+        throw new Error(`map art path "${foundryPath}" is not an SVG inside assets`);
+    }
+    const suffix = foundryPath.slice(at + marker.length);
+    const source = path.resolve(config.rootDir, "assets", suffix);
+    const assetRoot = path.resolve(config.rootDir, "assets");
+    if (!source.startsWith(`${assetRoot}${path.sep}`) || !fs.existsSync(source)) {
+        throw new Error(`map SVG "${foundryPath}" is not a local asset this package can rasterize`);
+    }
+    const staged = path.resolve(
+        config.rootDir,
+        config.packageBuild.stageDir,
+        "assets/maps/rasterized",
+        `${sceneId}.png`,
+    );
+    fs.mkdirSync(path.dirname(staged), { recursive: true });
+    try {
+        const image = new Resvg(fs.readFileSync(source), {
+            fitTo: { mode: "width", value: width },
+        }).render();
+        if (image.height !== height) {
+            throw new Error(
+                `the SVG is ${width}×${image.height} at the stated width, not ${width}×${height}`,
+            );
+        }
+        fs.writeFileSync(staged, image.asPng());
+    } catch (error) {
+        throw new Error(`could not rasterize map SVG "${foundryPath}": ${error.message}`, {
+            cause: error,
+        });
+    }
+    return `${config.packageKind}/${config.foundryPackage.id}/assets/maps/rasterized/${sceneId}.png`;
+}

package/engine/note-dates.mjs

@@ -12,93 +12,34 @@
  */
 
 /**
- * **A date on a note: one authored string, one grammar, one record.**
+ * Parse authored note dates into records used by content checks and renderers.
  *
- * ```text
- * [~] [-] YYYY [/ MM [/ DD]] [ ERA ]
+ * A neutral day is `<year>.<day>[:HHMMSS]`, where `day` is an ordinal within
+ * the world's year. A marked date is `<marker>(<year>[/<month>[/<day>]])`.
+ * The marker selects one era and its calendar's ordered month list; the era's
+ * start places its year one on the neutral timeline. A bare year is year
+ * precision, and `unknown` is unordered. The parser also accepts unmarked
+ * slash dates and addressed era qualifiers.
  *
- * ERA : (?:[a-z0-9]+-){0,3}[a-z0-9]+ . [a-z0-9]+
- * ```
- *
- * - `~` — approximate. It marks the value and does not change what it parses
- *   to, so a renderer can print `c. -2110` from the same number it sorts on.
- *   It precedes the sign: `~-2500`, never `-~2500`.
- * - `-` — before the epoch the year is counted from. There is no year zero, so
- *   `-1` sits immediately before `1`.
- * - `YYYY` — required.
- * - `MM`, `DD` — optional, in that order.
- * - `ERA` — a calendar's address plus `.<era shortcode>`, in the four address
- *   forms {@link ERA_QUALIFIER_PATTERN} admits. Omitted, the date sits on the
- *   canonical axis and is attributed to nobody.
- *
- * **Precision falls out of how much is written.** `-984` is a year, `689/6` a
- * month, `689/6/19` a day. There is no precision vocabulary, so there is
- * nothing to fall out of step with the value it describes.
- *
- * ## A trailing token is only ever an era
- *
- * It has exactly one shape and it always contains exactly one dot, so **a
- * trailing token at all means the value needs the corpus, and no token means
- * it is already on the axis** — which is readable off the string, before
- * anything is resolved.
- *
- * ## The rule to copy: print `text`, order on `sort`, do arithmetic on `canonicalYear`
- *
- * Every parsed date carries all three, because neither the string nor the
- * number is cheap to derive from the other at read time:
- *
- * ```yaml
- * text: "689/6/19"   # authored, verbatim — what a page prints
- * known: true        # what a query branches on
- * era: null          # the reckoning named, or null for the canonical axis
- * year: 689          # as authored, signed, within its own reckoning
- * month: 6           # null where unwritten
- * day: 19            # null where unwritten
- * approximate: false # the `~`
- * precision: day     # derived: day | month | year
- * canonicalYear: 689 # signed — arithmetic
- * sort: 689.0619     # total order across mixed precision — sorting
- * ```
- *
- * `era` is `null` for a bare value and there is no substitute for it: the
- * canonical axis is not a reckoning anybody keeps and has no address, so
- * filling the field would state an identification that is not true.
- *
- * ## A number is written only where there is one to write
- *
- * A date naming an era carries the qualifier and **no `canonicalYear` and no
- * `sort` keys at all** until the era is resolved against the corpus. They are
- * absent rather than null, because a record carrying `known: true` beside a
- * null year and a null sort is indistinguishable from the `unknown` record
- * below — which is the one shape whose confusion is invisible in the output.
- *
- * ## `unknown` is a value, and it is unordered
- *
- * `"unknown"` says the thing happened and the date is not recorded. It parses
- * to the same record with the year half empty — `known: false`, and **a null
- * `canonicalYear` and a null `sort`**.
- *
- * Both shortcuts past that are silently wrong. Normalising it to `0` sorts the
- * ancient dead into the year immediately before the epoch; treating it as a
- * null year and letting a comparison default it sorts them into the present,
- * beside the living. So anything that orders or filters on a date leaves an
- * unknown one out of the ordering and reports it as its own group, and a range
- * filter never matches it, because the record does not claim a year and a
- * filter must not claim one for it.
- *
- * ## Absence is not a finding, and neither is a bare value
- *
- * An absent value is a fact about the subject rather than a gap, so parsing
- * nothing yields nothing and reports nothing. A bare value is the canonical
- * axis, always, and it is silent: an unattributed date is the honest form for
- * a date an author is placing rather than a record somebody in the setting
- * kept.
+ * `text` keeps the authored spelling. `canonicalYear` and `sort` are set for
+ * neutral and resolved marked dates. A marked date also carries
+ * `canonicalDay`, the ordinal day within its neutral year. An addressed era
+ * qualifier carries no resolved year until a caller supplies its era facts.
  *
  * @module
  */
 
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
-import { calendarStructure, canonicalYear, dateSortKey, daysInMonth } from "./calendars.mjs";
+import {
+    calendarStructure,
+    canonicalDateFromOffset,
+    canonicalDayOffset,
+    canonicalYear,
+    dateSortKey,
+    dayOfYear,
+    daysInMonth,
+    parseCanonicalDate,
+} from "./calendars.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
 /**
@@ -186,6 +127,10 @@ function unknownRecord() {
  *   the value is written in, as its note declares it. Its ordered month list
  *   bounds a written month and a written day, the day against the length of
  *   the month it names. A calendar that declares no list bounds nothing.
+ * @param {Map<string, object>} [options.markers] - Resolved era markers from
+ *   the corpus, each carrying its calendar and canonical start.
+ * @param {number} [options.daysPerYear] - The world's year length, required for
+ *   canonical days and marked dates.
  * @param {string} [options.field] - The key that carried it, named in every
  *   message. Omitted, a message names the value alone.
  * @param {boolean} [options.allowUnknown=true] - Whether `"unknown"` is a
@@ -199,7 +144,16 @@ function unknownRecord() {
  *   the value is absent or refused, and every finding the value earned.
  */
 export function parseNoteDate(value, options) {
-    const { calendar, field, allowUnknown = true, file, raw, keyPath } = options ?? {};
+    const {
+        calendar,
+        markers,
+        daysPerYear,
+        field,
+        allowUnknown = true,
+        file,
+        raw,
+        keyPath,
+    } = options ?? {};
     const findings = [];
 
     // Absence is a fact about the subject, not a gap — nothing to parse and
@@ -235,6 +189,86 @@ export function parseNoteDate(value, options) {
     }
 
     const trimmed = text.trim();
+    const marked = /^([A-Z][A-Z0-9]*)\((.*)\)$/.exec(trimmed);
+    if (marked) {
+        const [, marker, payload] = marked;
+        const reckoning = markers?.get(marker);
+        if (!reckoning) return refuse(`${subject} names unknown reckoning marker ${marker}`);
+        if (!Number.isSafeInteger(daysPerYear) || daysPerYear < 1)
+            return refuse(`${subject} needs the world's year length to resolve ${marker}`);
+        const parsed = parseNoteDate(payload, {
+            calendar: reckoning.calendar,
+            field,
+            allowUnknown: false,
+            file,
+            raw,
+            keyPath,
+        });
+        if (parsed.findings.some((finding) => finding.severity === "error") || !parsed.date)
+            return { date: null, findings: parsed.findings };
+        if (!parsed.date.known)
+            return refuse(`${subject} wraps an unknown date; write \`unknown\` by itself`);
+        if (parsed.date.era !== null)
+            return refuse(
+                `${subject} names two reckonings; the payload of ${marker} is a calendar date`,
+            );
+        if (parsed.date.canonicalDay !== undefined)
+            return refuse(
+                `${subject} puts a canonical day inside ${marker}; write its calendar month and day`,
+            );
+        const { months } = calendarStructure(reckoning.calendar);
+        if (!months) return refuse(`${subject} names ${marker}, whose calendar declares no months`);
+        const ordinal = dayOfYear(months, parsed.date.month ?? 1, parsed.date.day ?? 1);
+        const start = canonicalDayOffset(reckoning.epochYear, reckoning.epochDay, 1, daysPerYear);
+        const yearOffset = parsed.date.year > 0 ? parsed.date.year - 1 : parsed.date.year;
+        const offset = start + yearOffset * daysPerYear + ordinal - 1;
+        if (!Number.isSafeInteger(offset))
+            return refuse(`${subject} lies outside the supported canonical day range`);
+        if (reckoning.endOffset !== undefined && offset > reckoning.endOffset)
+            return refuse(`${subject} lies after the end of reckoning marker ${marker}`);
+        const canonical = canonicalDateFromOffset(offset, 1, daysPerYear);
+        return {
+            date: {
+                ...parsed.date,
+                text,
+                era: reckoning.era,
+                marker,
+                canonicalYear: canonical.year,
+                canonicalDay: canonical.day,
+                sort: canonical.year + (canonical.day - 1) / daysPerYear,
+            },
+            findings: parsed.findings,
+        };
+    }
+
+    if (trimmed.includes(".")) {
+        const canonical = parseCanonicalDate(trimmed, daysPerYear);
+        if (canonical) {
+            return {
+                date: {
+                    text,
+                    known: true,
+                    era: null,
+                    year: canonical.year,
+                    month: null,
+                    day: canonical.day,
+                    approximate: false,
+                    precision: "day",
+                    canonicalYear: canonical.year,
+                    canonicalDay: canonical.day,
+                    ...(canonical.seconds === undefined ? {} : { seconds: canonical.seconds }),
+                    sort:
+                        canonical.year +
+                        (canonical.day - 1 + (canonical.seconds ?? 0) / 86400) / daysPerYear,
+                },
+                findings,
+            };
+        }
+        if (/^-?\d+\.\d+/.test(trimmed))
+            return refuse(
+                `${subject} is not a canonical date — write \`<year>.<day>[:HHMMSS]\` with a day inside the world's year`,
+            );
+    }
     const match = NOTE_DATE_PATTERN.exec(trimmed);
     if (!match) {
         if (DAY_WITHOUT_MONTH_PATTERN.test(trimmed)) {
@@ -264,10 +298,8 @@ export function parseNoteDate(value, options) {
         }
         return refuse(
             `${subject} is not a date — write ` +
-                `\`[~][-]YYYY[/MM[/DD]] [<calendar shortcode>.<era shortcode>]\`: ` +
-                `a year, negative where it falls before the epoch it is counted ` +
-                `from, optionally a month and a day, and an era where the date is a ` +
-                `reckoning somebody kept`,
+                `\`<year>.<day>[:HHMMSS]\` or ` +
+                `\`<marker>(<year>[/<month>[/<day>]])\``,
         );
     }
 
@@ -276,6 +308,14 @@ export function parseNoteDate(value, options) {
     const year = Number(yearText);
     const month = monthText === undefined ? null : Number(monthText);
     const day = dayText === undefined ? null : Number(dayText);
+    if (
+        !Number.isSafeInteger(year) ||
+        (month !== null && !Number.isSafeInteger(month)) ||
+        (day !== null && !Number.isSafeInteger(day))
+    )
+        return refuse(
+            `${subject} needs whole year, month, and day numbers inside the supported range`,
+        );
 
     // No year zero, in any reckoning: the years either side of an epoch are -1
     // and 1. `-0` is the same year written the other way and is refused with it.