@heroiclands/package-build 22.22.0 → 22.23.0

package/engine/note-dates.mjs

@@ -25,6 +25,14 @@
  * neutral and resolved named dates. A neutral year retains `precision: "year"`
  * and has no `canonicalDay`; day one is used only to calculate its bounds.
  *
+ * **Year 0 means any year**, and is accepted only where a caller passes
+ * `allowZeroYear` — a `lore` event's `when`. `when: "0.5"` is the fifth day of
+ * the year, in every year: the value carries `year: 0` and a `canonicalDay`,
+ * but no `canonicalYear` and no `sort`, since it names no point on the axis
+ * and cannot date its own note. Every other field keeps the ordinary
+ * refusal, and a bare `0` with no day is refused everywhere — any year with
+ * no day names nothing.
+ *
  * @module
  */
 
@@ -199,6 +207,10 @@ export function parseNoteDate(value, options) {
         daysPerYear,
         field,
         allowUnknown = true,
+        // Narrows the year-0 refusal for exactly one caller: an `events`
+        // entry's `when`, where year 0 means "this day, every year" rather
+        // than a point on the axis. Every other field keeps the refusal.
+        allowZeroYear = false,
         file,
         raw,
         keyPath,
@@ -331,7 +343,14 @@ export function parseNoteDate(value, options) {
             return refuse(`${subject} cannot resolve its calendar date: ${err.message}`);
         }
     }
-    if (/^-?0+\.\d+(?::\d{6})?$/.test(unmarked))
+    // Negative zero (`-0.<day>`) is refused unconditionally — it is the same
+    // year as bare `0` written the other way, and `allowZeroYear` means only
+    // "any year", never "any year, backwards". A bare positive `0.<day>` is
+    // refused everywhere except the one caller that passes `allowZeroYear`.
+    if (
+        /^-0+\.\d+(?::\d{6})?$/.test(unmarked) ||
+        (!allowZeroYear && /^0+\.\d+(?::\d{6})?$/.test(unmarked))
+    )
         return refuse(
             `${subject} writes year 0, and no reckoning has one — the years either ` +
                 `side of an epoch are -1 and 1`,
@@ -343,6 +362,28 @@ export function parseNoteDate(value, options) {
         );
     if (unmarked.includes(".")) {
         const canonical = parseCanonicalDate(unmarked, daysPerYear ?? Number.MAX_SAFE_INTEGER);
+        if (canonical && canonical.year === 0) {
+            // Year 0 means "this day, every year" — it names no point on the
+            // axis, so it carries no `canonicalYear` and no `sort`: nothing
+            // orders it and it cannot date its note, the same silence
+            // `unknown` keeps for the fields that carry no axis position.
+            return {
+                date: {
+                    text,
+                    known: true,
+                    era: null,
+                    year: 0,
+                    month: null,
+                    day: canonical.day,
+                    approximate: approximateInput,
+                    precision: "day",
+                    canonicalDay: canonical.day,
+                    spanDays: 1,
+                    ...(canonical.seconds === undefined ? {} : { seconds: canonical.seconds }),
+                },
+                findings,
+            };
+        }
         if (canonical) {
             return {
                 date: {
@@ -655,19 +696,276 @@ export function formatNoteDate(date, era, daysPerYear, formatName) {
     return { era, year, month, day, text, prose };
 }
 
+/**
+ * The occurrences of one recurring series overlapping a bound.
+ *
+ * **No materialized occurrence list.** An annual series anchored centuries
+ * back has thousands of occurrences to the present, and the only questions a
+ * build asks are "is this year one of them" and "which is next" — so an
+ * omitted bound answers with a single occurrence rather than every one a live
+ * series could have:
+ *
+ * - `to` omitted: the first occurrence at or after `from` (default, the
+ *   anchor's own year) — "next".
+ * - `from` omitted, `to` given: the last occurrence at or before `to` —
+ *   "the greatest occurrence at or before `until`".
+ * - Both given: every occurrence between them, inclusive — a membership
+ *   probe is `from === to`.
+ *
+ * **The lower bound is not optional.** A candidate year before the anchor's
+ * own year is never an occurrence, however a bare modulo would read it: `%`
+ * takes the sign of its dividend in both JavaScript and SQL, so a year
+ * exactly one period before the anchor would otherwise match. `k` is clamped
+ * at zero rather than left to run negative.
+ *
+ * **The period advances the canonical year, never the era-relative year.**
+ * `date.canonicalYear` is already on the continuous axis `canonicalYear`
+ * builds — era year `-1` sits immediately before era year `1`, but canonical
+ * year `0` is an ordinary integer between them — so stepping by whole
+ * multiples of `every` on `canonicalYear` crosses an epoch with no special
+ * case. Counting in era-relative years instead would need a correction at
+ * every crossing and silently loses one year each time it is forgotten.
+ *
+ * **Precision, approximation and the day of year carry through untouched.**
+ * Every occurrence is the anchor's own record with only `canonicalYear`
+ * advanced, so a day-precision anchor's `canonicalDay` — including one inside
+ * a short intercalary month — names the same day of every occurrence, and an
+ * approximate anchor's occurrences are approximate too.
+ *
+ * @param {object} date - The anchor's resolved record
+ *   ({@link parseNoteDate}), carrying a real `canonicalYear`. A year-0 "any
+ *   year" anchor carries none and has no series through this function — its
+ *   `recurs` is refused, and its own next occurrence is computed directly
+ *   from the day of year alone.
+ * @param {{every?: number, on?: object[]}} [recurs] - The declared
+ *   recurrence: a whole-year period, or an enumeration of further resolved
+ *   date records (each already carrying its own `canonicalYear`). Neither
+ *   admits the other.
+ * @param {object} [bounds]
+ * @param {number} [bounds.from] - The lower bound, inclusive, as a canonical
+ *   year.
+ * @param {number} [bounds.to] - The upper bound, inclusive, as a canonical
+ *   year.
+ * @returns {object[]} Occurrence records, in increasing order.
+ */
+export function occurrencesOf(date, recurs, { from, to } = {}) {
+    if (!date?.known || !Number.isSafeInteger(date.canonicalYear)) return [];
+    const anchor = date.canonicalYear;
+
+    if (Array.isArray(recurs?.on)) {
+        if (from === undefined && to === undefined) return [date];
+        const series = [date, ...recurs.on]
+            .filter((occ) => occ?.known && Number.isSafeInteger(occ.canonicalYear))
+            .sort((a, b) => a.canonicalYear - b.canonicalYear);
+        const inRange = series.filter(
+            (occ) =>
+                (from === undefined || occ.canonicalYear >= from) &&
+                (to === undefined || occ.canonicalYear <= to),
+        );
+        if (from === undefined) return inRange.slice(-1);
+        if (to === undefined) return inRange.slice(0, 1);
+        return inRange;
+    }
+
+    const every = recurs?.every;
+    if (!Number.isSafeInteger(every) || every < 1) {
+        const solo = (from === undefined || anchor >= from) && (to === undefined || anchor <= to);
+        return solo ? [date] : [];
+    }
+
+    const lowestK = from === undefined ? 0 : Math.max(0, Math.ceil((from - anchor) / every));
+    if (to === undefined) return [{ ...date, canonicalYear: anchor + lowestK * every }];
+
+    const highestK = Math.floor((to - anchor) / every);
+    if (highestK < lowestK) return [];
+    if (from === undefined) return [{ ...date, canonicalYear: anchor + highestK * every }];
+
+    const out = [];
+    for (let k = lowestK; k <= highestK; k += 1)
+        out.push({ ...date, canonicalYear: anchor + k * every });
+    return out;
+}
+
+/** A resolved date's printed form, in the era its own value selects. */
+function withMarkerProse(date, context) {
+    const era =
+        date.marker ? context?.markers?.get(date.marker)
+        : date.qualifier ? context?.eras?.get(date.qualifier)
+        : null;
+    const printable = formatNoteDate(date, era, context?.daysPerYear);
+    return { ...date, prose: printable?.prose ?? null };
+}
+
+/**
+ * A resolved date's printed form, re-selecting the era that covers its own
+ * position rather than keeping whatever era its anchor was authored in.
+ *
+ * `when`/`until`/`on` are checked exactly as `born`/`died` are: an
+ * era-qualified value carries a `marker` or a `qualifier`, which names the
+ * calendar as well as the era, and a bare canonical value carries neither and
+ * prints bare. What is new here is that a *generated* occurrence keeps the
+ * anchor's marker or qualifier — advancing the year only — so that calendar's
+ * **whole** era list is swept through {@link eraCovering} for the
+ * occurrence's own position, rather than assuming it stays in the era the
+ * anchor was in. A later occurrence may therefore print in a different era
+ * than its anchor, or print bare where no count was proclaimed for that year;
+ * neither is a finding, since nobody authored the occurrence.
+ *
+ * @param {object} date - The resolved date, generated or authored.
+ * @param {object} [context] - As {@link resolvedDateFields} reads it.
+ * @returns {object} The date, carrying `prose`.
+ */
+function withSweptEraProse(date, context, { generated = false } = {}) {
+    if (!date?.known) return { ...date, prose: null };
+    const anchorEra =
+        date.marker ? context?.markers?.get(date.marker)
+        : date.qualifier ? context?.eras?.get(date.qualifier)
+        : null;
+    let era = null;
+    if (anchorEra?.calendarShortcode) {
+        try {
+            const calendarRows = calendarEras(anchorEra.calendarShortcode, context);
+            era = eraCovering(date, calendarRows, context?.daysPerYear);
+        } catch {
+            // Ambiguous or overlapping eras are a corpus defect reported
+            // where the eras themselves are declared; an occurrence prints
+            // bare rather than failing a build over a note that authored
+            // nothing wrong.
+            era = null;
+        }
+    }
+    const printable = formatNoteDate(date, era, context?.daysPerYear);
+    return {
+        ...date,
+        prose: printable?.prose ?? null,
+        // `formatNoteDate`'s own bare `text` echoes `date.text` — the
+        // anchor's authored spelling, which a *generated* occurrence has
+        // outgrown. Only a generated occurrence with no era to print in
+        // needs a text of its own, built from its own canonical year.
+        ...(generated && !era ?
+            {
+                text:
+                    (date.approximate ? "~" : "") +
+                    (date.precision === "day" && Number.isSafeInteger(date.canonicalDay) ?
+                        `${eraYear(date.canonicalYear)}.${date.canonicalDay}`
+                    :   String(eraYear(date.canonicalYear))),
+            }
+        :   {}),
+    };
+}
+
+/** The package's declared present, resolved to a date record, or `null`. */
+function resolvedPresent(context) {
+    if (context?.present === undefined || context?.present === null) return null;
+    const date = parseNoteDate(context.present, { ...context, allowUnknown: false }).date;
+    return date?.known ? date : null;
+}
+
+/**
+ * One `data.events` entry, resolved: its own `when`, `until`, `recurs` and
+ * `next`.
+ *
+ * `recurs.first` and `recurs.last` are canonical years rather than the
+ * fractional `sort` a day-precision date carries, because `every` counts
+ * whole years — a SQL fence testing membership with
+ * `(year - recurs.first) % recurs.every = 0 AND year >= recurs.first` reads
+ * them as the plain integers they are.
+ *
+ * @param {unknown} entry - The authored `{ when, until?, recurs? }`.
+ * @param {object} [context] - As {@link resolvedDateFields} reads it.
+ * @returns {object} The resolved entry; a key is present only where the note
+ *   authored or the build computed something for it.
+ */
+function resolveEventEntry(entry, context) {
+    const row = entry && typeof entry === "object" && !Array.isArray(entry) ? entry : {};
+    const out = {};
+
+    const when = parseNoteDate(row.when, {
+        ...context,
+        allowUnknown: true,
+        allowZeroYear: true,
+    }).date;
+    if (when?.known) out.when = withSweptEraProse(when, context);
+
+    const until = parseNoteDate(row.until, { ...context, allowUnknown: false }).date;
+    if (until?.known) out.until = withSweptEraProse(until, context);
+
+    if (!when?.known) return out;
+
+    // Year 0: an annual day-of-year marker, recurring by construction. Its
+    // own next occurrence is computed directly from the day of year rather
+    // than through `occurrencesOf`, which needs a real anchor year — and it
+    // carries no `recurs` record, since the entry is already annual.
+    if (when.year === 0) {
+        const present = resolvedPresent(context);
+        if (present && Number.isSafeInteger(when.canonicalDay)) {
+            const dueThisYear =
+                !Number.isSafeInteger(present.canonicalDay) ||
+                present.canonicalDay <= when.canonicalDay;
+            const year = dueThisYear ? present.canonicalYear : present.canonicalYear + 1;
+            if (!out.until || year <= out.until.canonicalYear) {
+                out.next = withSweptEraProse({ ...when, canonicalYear: year }, context, {
+                    generated: true,
+                });
+            }
+        }
+        return out;
+    }
+
+    const recurs = row.recurs;
+    if (!recurs || typeof recurs !== "object" || Array.isArray(recurs)) return out;
+
+    const recursOut = {};
+    let series;
+    // An enumeration is bounded by construction — its own last entry — so
+    // `last` is never null for `on`; a period is live unless `until` bounds
+    // it, so `last` is null exactly where there is no `until` to bound it.
+    if (Number.isInteger(recurs.every) && recurs.every >= 1) {
+        recursOut.every = recurs.every;
+        series = { every: recurs.every };
+        recursOut.last =
+            out.until ?
+                (occurrencesOf(when, series, { to: out.until.canonicalYear }).at(-1)
+                    ?.canonicalYear ?? null)
+            :   null;
+    } else if (Array.isArray(recurs.on)) {
+        const onDates = recurs.on
+            .map((raw) => parseNoteDate(raw, { ...context, allowUnknown: false }).date)
+            .filter((parsedOn) => parsedOn?.known);
+        recursOut.on = onDates.map((onDate) => withSweptEraProse(onDate, context));
+        series = { on: onDates };
+        recursOut.last =
+            onDates.length ? onDates[onDates.length - 1].canonicalYear : when.canonicalYear;
+    } else {
+        return out;
+    }
+
+    recursOut.first = when.canonicalYear;
+    out.recurs = recursOut;
+
+    const present = resolvedPresent(context);
+    if (present?.known) {
+        const candidate = occurrencesOf(when, series, { from: present.canonicalYear })[0];
+        if (candidate && (!out.until || candidate.canonicalYear <= out.until.canonicalYear)) {
+            out.next = withSweptEraProse(candidate, context, { generated: true });
+        }
+    }
+    return out;
+}
+
 /** Normalize a note's declared dates for indexes and generated pages. */
 export function resolvedDateFields(fm, context) {
+    if (fm?.type === "lore") {
+        const events = Array.isArray(fm.data?.events) ? fm.data.events : [];
+        const resolved = events.map((entry) => resolveEventEntry(entry, context));
+        return resolved.length ? { events: resolved } : {};
+    }
     const fields =
         fm?.type === "being" ?
             [
                 ["born", fm.data?.born],
                 ["died", fm.data?.died],
             ]
-        : fm?.type === "lore" ?
-            [
-                ["when", fm.data?.event?.when],
-                ["until", fm.data?.event?.until],
-            ]
         :   [];
     const out = {};
     for (const [key, value] of fields) {
@@ -677,12 +975,7 @@ export function resolvedDateFields(fm, context) {
             allowUnknown: key === "born" || key === "died",
         });
         if (parsed.date && !parsed.findings.some((finding) => finding.severity === "error")) {
-            const era =
-                parsed.date.marker ? context?.markers?.get(parsed.date.marker)
-                : parsed.date.qualifier ? context?.eras?.get(parsed.date.qualifier)
-                : null;
-            const printable = formatNoteDate(parsed.date, era, context?.daysPerYear);
-            out[key] = { ...parsed.date, prose: printable?.prose ?? null };
+            out[key] = withMarkerProse(parsed.date, context);
         }
     }
     return out;

package/engine/note-vocabulary.mjs

@@ -107,6 +107,7 @@ import { STANDING_BODY_TYPES } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
 import { checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
+import { checkLoreEvents } from "./lore-events.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
@@ -469,7 +470,9 @@ export const SHARED_DATA_FIELDS = Object.freeze([
         ...LINK,
         ref: "image",
         accepts: ART_SLOTS.find((slot) => slot.key === "banner").accepts,
-        describe: "The page's hero image — an `image` address. Reaches no compiled document.",
+        describe:
+            "The page's hero image — an `image` address, cut to 1792×768. " +
+            "Reaches no compiled document.",
     }),
 ]);
 
@@ -1493,10 +1496,13 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([
             ...CALENDAR_FIELDS,
             {
-                name: "event",
-                kind: "map",
-                shape: "event metadata map",
-                describe: "A dated occurrence and its relationships to other events and places.",
+                name: "events",
+                kind: "list",
+                shape: "list of `{ when, until?, recurs? }`",
+                check: checkLoreEvents,
+                describe:
+                    "This note's dated occurrences — a founding once, an anniversary " +
+                    "that recurs, or a list of recorded happenings.",
             },
         ]),
     }),

package/engine/pathnames.mjs

@@ -443,3 +443,39 @@ export function resolvePathname(raw, config) {
         pdf: `${ASSETS_SEGMENT}/${suffix}`,
     };
 }
+
+/**
+ * The pathname one authored image address keys an asset's role and pixel
+ * size under — `<package>/assets/<suffix>`, the same key
+ * {@link module:engine/art-fields.assetImageInfoByPathname} builds from the
+ * asset record itself.
+ *
+ * **Why this exists apart from `resolvePathname`'s own forms.** An embed
+ * rewrites to that exact pathname — see
+ * {@link module:engine/content-embeds.resolveEmbeds} — but an author's own
+ * body image is free to write the bare, own-package form instead
+ * (`images/m.webp`), which names the identical file without naming the
+ * package. The two forms have to key the same lookup, and `resolvePathname`
+ * already answers which package a bare form belongs to; this just restates
+ * that answer in the one shape a renderer looks a picture's role up by.
+ *
+ * **Never throws.** A lookup is a best-effort read, not a validation — the
+ * pathname lint is what refuses a Foundry-spelled address — so a value
+ * {@link resolvePathname} refuses outright answers `null` here as well, the
+ * same as a blank or an external one.
+ *
+ * @param {string} src - The address, as authored or as an embed resolved it.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string|null} The pathname, or `null` for an address naming no
+ *   asset record to look up.
+ */
+export function assetPathnameKey(src, config) {
+    let forms;
+    try {
+        forms = resolvePathname(src, config);
+    } catch {
+        return null;
+    }
+    if (!forms || forms.state !== "package" || !forms.package) return null;
+    return `${forms.package}/${ASSETS_SEGMENT}/${forms.suffix}`;
+}