@onlyworlds/sdk 4.19.0 → 4.20.0

package/AGENTS.md

@@ -63,6 +63,10 @@ against live data). The v1 surface (`OnlyWorldsClient`, the `ElementType` enum)
   world folder and returns `{ worldId, name, world, files: [{ path, data }] }`;
   `writeWorldFile(files, topDir)` makes one. Refusals throw `OwWorldFileError` with a `reason`.
   `world.json`'s `api` block (link and key) is removed both ways.
+- World calendars (since 4.20.0): `worldCalendars(elements)` finds the elements carrying
+  `atlas_calendar` (Atlas owns the field: read it, never write it); `resolveCalendarLens` picks
+  one; `formatStep(config, step)` names a point on the world's integer time line, `parseDate`
+  reads one back. No calendar or a broken one is null: show the bare number.
 - Ids: the client mints **UUIDv7** on an id-less `create` (since 4.2.0; keel mints v7 too).
   A v4 or v7 id you supply is accepted. **Never sort elements by id**: worlds mix v7, v4
   and legacy `06x…` ids (nibble 7 too, but seconds-first). For creation order use

package/CHANGELOG.md

@@ -5,6 +5,21 @@ earlier history lives in git log only.
 
 ## [Unreleased]
 
+## [4.20.0] — 2026-10-14
+
+### Added
+- **World calendars**, Atlas's calendar code in the SDK so Lantern can name dates (Temper,
+  h37 #4284): `formatStep`, `formatYearLabel`, `breakdownStep`, `parseDate` and the rest of
+  Atlas's `src/core/calendar.ts` (Atlas 02d6a6d), plus `worldCalendars`,
+  `resolveCalendarLens` and `readCalendarValue` from its `calendar-lens.ts`, on any element
+  shape. `CALENDAR_FIELD` is `atlas_calendar`: Atlas owns the field, its meaning and its
+  writes, and other tools read it (Skeld, h37 #4286).
+- `src/calendar/calendar.ts` is Atlas's file byte for byte, recorded in
+  `src/calendar/SOURCES.json` (Assembly's copy-drift); `codegen/atlas-calendar.mjs` re-copies it
+  and ports Atlas's 48 kernel tests (TypeScript's transpiler, a five-matcher `test/expect.mjs`
+  over node:test). Watched failing: a planted `floorMod` edit failed two tests and the record
+  (EDITED); a lens edit failed its test. An app that imports none of it bundles none of it.
+
 ## [4.19.0] — 2026-10-14
 
 ### Added

package/README.md

@@ -198,6 +198,24 @@ const zip = writeWorldFile(world.files, 'hollow-reach-0192a000'); // one top-lev
 
 The reader refuses a file before returning anything: a path that could land outside the folder, more than 1 GiB or 200,000 files uncompressed (`maxBytes`, `maxEntries` to change them), no `world.json` with an `id`, or more than one world. Check `err.reason` on the `OwWorldFileError` it throws. The world's OnlyWorlds link and key (`world.json`'s `api`) never travel: both functions remove them. A tool's own folder (`.atlas/` and the like) comes back like any other file; pass `skip: path => …` to leave files out.
 
+## World calendars
+
+A world's time is an integer line (`time_range_current` is a point on it, and so is an Event's `start_date`). A calendar names its points: months, days, eras. Atlas keeps a calendar on an element (a Construct by convention) in its `atlas_calendar` field, and the SDK reads it with Atlas's own calendar code (since 4.20.0). Atlas owns that field and is its only writer; read it, never write it.
+
+```typescript
+import { worldCalendars, resolveCalendarLens, formatStep, formatYearLabel, parseDate } from '@onlyworlds/sdk';
+
+const calendars = worldCalendars(elements);  // [{ id, name, config }]: every element with a valid atlas_calendar
+const cal = resolveCalendarLens(elements, chosenId, { fallbackToOnly: true }); // a world with one calendar uses it
+if (cal) {
+  formatStep(cal.config, 400);      // "4 Alturiak, 1 DR" (with Harptos, from Atlas's tests)
+  formatYearLabel(cal.config, 400); // "1 DR"
+  parseDate(cal.config, '4 Alturiak, 1 DR'); // { step: 400 }; a bare number is always the raw step
+}
+```
+
+No calendar, or a broken one, gives null: show the bare number. `breakdownStep` gives the parts (year, era, month, day, weekday, an intercalary day). The rules are Atlas's calendar design, §5 and §5b.
+
 ## Errors
 
 Every non-2xx response throws `OwApiError` with the API's envelope: `.status`, `.type`, `.code`, `.param` (the field that failed) and `.docUrl`, which is worth showing to your users. A transport failure throws `OwNetworkError`. `err.isValidationError` covers the common case. A write sent with `ifMatch` that found the element moved throws `OwPreconditionFailedError` (412, `err.isPreconditionFailed`), an `OwApiError` that also carries `current`.

package/dist/index.d.ts

@@ -2989,6 +2989,267 @@ declare function planPhoto(source: {
  */
 declare function preparePhoto(input: Blob, opts?: OwPhotoOptions): Promise<OwPreparedPhoto>;
 
+/**
+ * Calendar kernel — pure arithmetic, formatting, and parsing over the world's
+ * integer time line.
+ *
+ * Contract: Forge/Notes/2026-07-14-calendar-design-final.md §5 + §5b (3-lens
+ * gated 2026-07-14). The binding rules, restated where they bite:
+ *
+ * - The number line is the only truth. A calendar names it; it never owns it.
+ * - Absolute year index is ZERO-based: step 0 opens absolute year 0. All
+ *   division is Euclidean floor (negatives depend on it).
+ * - format(step) is total and O(config) — it never walks history.
+ * - Intercalary days belong to no month and render via `format_intercalary`.
+ * - A KNOWN token with no applicable value renders empty (with separator
+ *   collapse); an UNKNOWN token renders literally.
+ * - parse() matches calendar words case-insensitively; bare numbers are ALWAYS
+ *   the raw stored step. Guaranteed property: format(parse(format(n))) ===
+ *   format(n). Exact integer recovery is NOT promised under lossy formats.
+ *
+ * Everything here is pure. No atlas imports beyond nothing — this module is
+ * consumed by the charts room, popovers, and (via freeze) the publish path.
+ */
+interface CalendarEra {
+    name: string;
+    abbrev?: string;
+    /** Up-era: domain start (inclusive). Down-era: the PIVOT (exclusive upper bound). */
+    start: number;
+    /** Up-era: domain end (exclusive); defaults to the next era's start. Down-era: lower bound (inclusive); defaults to -infinity. */
+    end?: number;
+    /** true (default): years number from `start`. false: pure label, {year} shows the absolute year index. */
+    restart?: boolean;
+    /** First year number of a restart era: 0 or 1 (default 1). */
+    year_base?: 0 | 1;
+    /** 'up' (default) or 'down' (BC / Dune B.G. — counts toward the pivot). */
+    direction?: 'up' | 'down';
+    /** Closed eras format old dates but are never offered at date entry. */
+    closed?: boolean;
+}
+interface CalendarMonths {
+    names: string[];
+    /** Same length as names. */
+    lengths: number[];
+}
+interface CalendarWeek {
+    length: number;
+    names: string[];
+    /** 'free' (default): runs across month boundaries, anchor step 0 = names[0].
+     *  'nested': weekday = (day_of_month - 1) mod length; ragged final week legal. */
+    mode?: 'free' | 'nested';
+}
+interface CalendarIntercalary {
+    name: string;
+    /** 0 = before month 1; k = after month k. Requires months. */
+    after_month: number;
+    /** Present only in years where floorMod(absYear, N) === 0 (the leap rule). */
+    every_years?: number;
+    /** Counts in the free-running week (default true). The Shire lock = opting
+     *  exactly Mid-year's Day + Overlithe out (364 = 52 × 7). */
+    in_week?: boolean;
+}
+interface CalendarConfig {
+    version: number;
+    /** Immutable sentinel: the world's time_basic_unit at creation. Machinery only. */
+    grain: string;
+    /** The culture's display word for one step ("Sol"). Defaults to grain. */
+    step_name?: string;
+    eras?: CalendarEra[];
+    bundles?: {
+        /** Coarse-calendar year length. Legal ONLY when months are absent. */
+        year?: {
+            steps: number;
+        };
+        months?: CalendarMonths;
+        week?: CalendarWeek;
+    };
+    intercalary?: CalendarIntercalary[];
+    /** Regular-day template. Tokens: {day} {month} {weekday} {year} {era} {step}. */
+    format?: string;
+    /** Intercalary-day template; may also use {intercalary}. */
+    format_intercalary?: string;
+}
+/** A step, taken apart. Fields are null when the structure doesn't exist. */
+interface StepBreakdown {
+    step: number;
+    /** Absolute year index (zero-based from step 0). */
+    absYear: number;
+    /** The era-local display year (restart arithmetic applied), or absYear when no era / restart:false. */
+    year: number;
+    era: CalendarEra | null;
+    /** 1-based month index, or null (intercalary day / no months). */
+    month: number | null;
+    monthName: string | null;
+    /** 1-based day within the month, or null. */
+    day: number | null;
+    /** Intercalary day name when the step IS one, else null. */
+    intercalary: string | null;
+    weekday: string | null;
+}
+interface ParseResult {
+    step: number;
+}
+interface ParseError {
+    error: string;
+}
+declare function floorDiv(a: number, b: number): number;
+declare function floorMod(a: number, b: number): number;
+declare function validateCalendarConfig(cfg: CalendarConfig): string[];
+/**
+ * Defensive reader for wild configs (hand-edited files, other tools). Returns
+ * null when the value is not a structurally usable calendar — callers fall
+ * back to bare numbers, never a broken axis.
+ */
+declare function readCalendarConfig(value: unknown): CalendarConfig | null;
+/** True when absolute year y contains the leap entry with period N. */
+declare function isLeapYear(y: number, N: number): boolean;
+/** First step of absolute year y. yearStart(0) === 0 by construction. */
+declare function yearStartStep(cfg: CalendarConfig, y: number): number;
+/** Length in steps of absolute year y. */
+declare function yearLength(cfg: CalendarConfig, y: number): number;
+/** Absolute year index of a step. Zero-based; closed-form seed + bounded correction. */
+declare function absoluteYear(cfg: CalendarConfig, step: number): number;
+interface EraDomain {
+    era: CalendarEra;
+    lo: number;
+    hi: number;
+}
+declare function resolveEraDomains(eras: CalendarEra[]): EraDomain[];
+/** The era owning a step: domain containment; wild overlaps resolve to latest start (up wins ties). */
+declare function eraForStep(cfg: CalendarConfig, step: number): CalendarEra | null;
+/** The display year for a step under an era (or the absolute year without one). */
+declare function displayYear(cfg: CalendarConfig, step: number, era: CalendarEra | null): number;
+interface DaySlot {
+    kind: 'month' | 'intercalary';
+    month?: number;
+    day?: number;
+    intercalary?: CalendarIntercalary;
+}
+/** Weekday name for a step, or null (no week / nested outside months / skipped intercalary day). */
+declare function weekdayForStep(cfg: CalendarConfig, step: number, pre?: StepPosition): string | null;
+interface StepPosition {
+    absYear: number;
+    offset: number;
+    slot: DaySlot | null;
+    slots: DaySlot[] | null;
+}
+declare function breakdownStep(cfg: CalendarConfig, step: number): StepBreakdown;
+/** Format a step. Total: every integer formats to a string under every readable config. */
+declare function formatStep(cfg: CalendarConfig, step: number): string;
+/**
+ * Compact year-level label: "{year} {era-abbrev}" — the axis-tick wording when
+ * zoomed wide (full formatStep at tick density would be a wall of month names).
+ * Outside every era: the absolute year index alone.
+ */
+declare function formatYearLabel(cfg: CalendarConfig, step: number): string;
+/**
+ * The base year length in steps (leap days excluded), or null when the
+ * calendar has no year structure above the step. Consumers use it as a
+ * zoom threshold (ticks tighter than a year → full dates, else year labels).
+ */
+declare function approxYearLength(cfg: CalendarConfig): number | null;
+/**
+ * A duration in steps, spoken: "19 years" when the calendar has year
+ * structure and the span reaches it, else "12 days" in the step word. Uses
+ * the BASE year length (leap days are noise at duration granularity); one
+ * decimal below 10 years, whole above. Pure.
+ */
+declare function formatDuration(cfg: CalendarConfig, steps: number): string;
+/**
+ * The first step of each month in absolute year y, in order. O(config) — walks
+ * month lengths + intercalary placement, never the year's days. Empty when the
+ * calendar has no months.
+ */
+declare function monthStartSteps(cfg: CalendarConfig, y: number): {
+    month: number;
+    name: string;
+    step: number;
+}[];
+/**
+ * Mid-rung label for dense axis ticks: "11 Greening 454" — day, month, display
+ * year, NO era word (the era bands carry the era; a label wall repeating "FT"
+ * is noise). Intercalary steps read "Hearthmoot 454". Monthless calendars fall
+ * back to the year label.
+ */
+declare function formatMidLabel(cfg: CalendarConfig, step: number): string;
+interface ParseOptions {
+    /** The world's now (used to default a missing year, per contract rule 9). */
+    now?: number | null;
+}
+/** Absolute year for an era-local display year (inverse of displayYear). */
+declare function absYearForEraYear(cfg: CalendarConfig, era: CalendarEra, Y: number): number;
+/**
+ * Parse a written date to a step.
+ *
+ * Accepted shapes (calendar words case-insensitive):
+ *   "-454" / "454"                      -> the raw stored step, always
+ *   "454 AE" / "Year 12 FT"             -> year (+ era)
+ *   "Frostwane 454" / "12 Frostwane 454" (+ era)
+ *   "Shieldmeet 1372" (+ era)           -> intercalary day
+ *   "Frostwane 12" (no year)            -> resolved against the now's year
+ * Partial dates snap to the period's first step. Missing year with no now =
+ * error (never guess). p(f(n)) == n is NOT promised; f(p(f(n))) == f(n) is.
+ */
+declare function parseDate(cfg: CalendarConfig, input: string, opts?: ParseOptions): ParseResult | ParseError;
+declare function isParseError(r: ParseResult | ParseError): r is ParseError;
+
+/**
+ * World calendars: Atlas's calendar kernel, and which calendars a world holds.
+ *
+ * `calendar.ts` beside this file is Atlas's `src/core/calendar.ts`, byte for byte
+ * (Forge/tools/atlas; recorded in `SOURCES.json`, checked with Assembly's copy-drift).
+ * Never edit it here: change Atlas's, then copy and re-record. This file adapts Atlas's
+ * `src/core/calendar-lens.ts` (readCalendarValue, worldCalendars, resolveCalendarLens) to
+ * any element shape, since the SDK has no Atlas `Element`.
+ *
+ * The field: a calendar is an element (a Construct by convention) carrying `atlas_calendar`.
+ * Atlas owns the field, its meaning and its writes (its calendar design, §5 and §5b); every
+ * other tool reads it and never writes it (Skeld, h37 #4286: a prefix names the owner, not
+ * who may read). Detection keys on the field's presence, never on the supertype.
+ * Everything degrades to bare numbers: a missing, dangling or malformed calendar is null,
+ * never an error.
+ */
+
+/** The supertype Atlas gives a calendar Construct: convention and display only. */
+declare const CALENDAR_SUPERTYPE = "calendar";
+/** Atlas's field for a calendar's config (owned by Atlas: read it, never write it). */
+declare const CALENDAR_FIELD = "atlas_calendar";
+/** Any element: an id, a name, and the rest of its fields. */
+interface OwCalendarElement {
+    id: string;
+    name?: string | null;
+    [field: string]: unknown;
+}
+interface WorldCalendar {
+    /** The calendar element's id. */
+    id: string;
+    /** The element's name: the calendar's display name. */
+    name: string;
+    config: CalendarConfig;
+}
+/**
+ * The tolerant `atlas_calendar` read: an object or a JSON string (another tool may
+ * serialize it; Atlas writes objects). Null for anything unusable. Read the field only
+ * through this: a reader that took objects alone would blank a string config.
+ */
+declare function readCalendarValue(raw: unknown): CalendarConfig | null;
+/**
+ * Every usable calendar in the world: the elements with a valid `atlas_calendar`.
+ * A malformed config is skipped: a broken calendar is invisible, not an error.
+ */
+declare function worldCalendars(elements: Iterable<OwCalendarElement>): WorldCalendar[];
+/**
+ * Resolve a chosen calendar id against the elements. A null id, a dangling id or an
+ * invalid config resolve to null: bare numbers.
+ *
+ * `fallbackToOnly`: when no calendar was ever chosen (`activeId` is `undefined`, not
+ * `null`) and the world holds exactly one, use it. `null` is an explicit "no calendar" and
+ * stays null. With several calendars and no choice, nothing is guessed.
+ */
+declare function resolveCalendarLens(elements: Iterable<OwCalendarElement>, activeId: string | null | undefined, opts?: {
+    fallbackToOnly?: boolean;
+}): WorldCalendar | null;
+
 /**
  * OnlyWorlds Token Management API Types
  *
@@ -3273,4 +3534,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-export { ASK_LIMITS, type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, buildAskContext, buildWorldIndex, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, lookupWorld, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readWorldFile, renderElement, writeWorldFile };
+export { ASK_LIMITS, type AccessKeyResponse, CALENDAR_FIELD, CALENDAR_SUPERTYPE, type CalendarConfig, type CalendarEra, type CalendarIntercalary, type CalendarMonths, type CalendarWeek, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, type EraDomain, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAskAnswer, type OwAskContext, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwCalendarElement, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwJoinPreview, type OwJoinedMembership, type OwKeyKind, type OwLinkEdit, type OwLookupElement, type OwLookupHit, type OwLookupLink, type OwLookupOptions, type OwLookupReason, type OwMediaTicket, type OwMemberRole, OwNetworkError, type OwPage, type OwPhotoOptions, type OwPhotoPlan, OwPreconditionFailedError, type OwPreparedPhoto, type OwReadWorldFile, type OwReadWorldFileOptions, type OwRemovalTicket, type OwRemovedImage, type OwRenderOptions, type OwSortAddToRow, type OwSortAnswer, type OwSortAskRow, type OwSortLinkRow, type OwSortMakeRow, type OwSortNote, type OwSortRef, type OwSortRow, type OwUploadedImage, OwV2Client, type OwWorldFileEntry, OwWorldFileError, type OwWorldFileReason, type OwWorldIndex, type OwWorldMeta, PHOTO_MAX_BYTES, PHOTO_TYPES, type ParseError, type ParseOptions, type ParseResult, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type StepBreakdown, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, WORLD_FILE_MAX_BYTES, WORLD_FILE_MAX_ENTRIES, type WorldCalendar, absYearForEraYear, absoluteYear, approxYearLength, breakdownStep, buildAskContext, buildWorldIndex, detectKeyKind, displayYear, elementColor, eraForStep, errorFromResponse, familyOf, floorDiv, floorMod, formatDuration, formatMidLabel, formatStep, formatYearLabel, getElementIcon, getElementLabel, isDemoKey, isLeapYear, isParseError, kindCanWrite, lookupWorld, monthStartSteps, parseDate, parseErrorEnvelope, pinExpectation, planPhoto, preparePhoto, readCalendarConfig, readCalendarValue, readWorldFile, renderElement, resolveCalendarLens, resolveEraDomains, validateCalendarConfig, weekdayForStep, worldCalendars, writeWorldFile, yearLength, yearStartStep };

package/dist/index.js

@@ -2135,6 +2135,456 @@ async function preparePhoto(input, opts = {}) {
   }
 }
 
+// src/calendar/calendar.ts
+function floorDiv(a, b) {
+  return Math.floor(a / b);
+}
+function floorMod(a, b) {
+  return (a % b + b) % b;
+}
+function validateCalendarConfig(cfg) {
+  const errors = [];
+  if (cfg.version !== 1) errors.push(`Unsupported calendar version: ${cfg.version}`);
+  if (!cfg.grain || typeof cfg.grain !== "string") errors.push("Grain is required");
+  const months = cfg.bundles?.months;
+  if (months) {
+    if (!Array.isArray(months.names) || !Array.isArray(months.lengths) || months.names.length === 0 || months.names.length !== months.lengths.length) {
+      errors.push("months.names and months.lengths must be same-length non-empty arrays");
+    } else if (months.lengths.some((l) => !Number.isInteger(l) || l < 1)) {
+      errors.push("Every month length must be a whole number, 1 or more");
+    }
+    if (cfg.bundles?.year) errors.push("year.steps is legal only when no months are defined (year length is derived from months)");
+  } else if (cfg.bundles?.year) {
+    if (!Number.isInteger(cfg.bundles.year.steps) || cfg.bundles.year.steps < 1) {
+      errors.push("year.steps must be a positive integer");
+    }
+  }
+  const week = cfg.bundles?.week;
+  if (week) {
+    if (!Number.isInteger(week.length) || week.length < 1) errors.push("The week length must be a whole number, 1 or more");
+    else if (!Array.isArray(week.names) || week.names.length !== week.length) errors.push("Give the week as many day names as its length");
+  }
+  const inter = cfg.intercalary ?? [];
+  if (inter.length > 0 && !months) errors.push("Festival days need months");
+  const monthCount = months?.names.length ?? 0;
+  for (const ic of inter) {
+    if (!Number.isInteger(ic.after_month) || ic.after_month < 0 || ic.after_month > monthCount) {
+      errors.push(`Festival day "${ic.name}": pick the month it follows`);
+    }
+    if (ic.every_years != null && (!Number.isInteger(ic.every_years) || ic.every_years < 1)) {
+      errors.push(`Festival day "${ic.name}": every N yrs must be a whole number, 1 or more`);
+    }
+  }
+  const eras = cfg.eras ?? [];
+  for (const era of eras) {
+    if (!era.name) errors.push("Every era needs a name");
+    if (!Number.isFinite(era.start)) errors.push(`Era "${era.name}": start must be a number`);
+    if (era.end != null && !Number.isFinite(era.end)) errors.push(`Era "${era.name}": end must be a number`);
+    if ((era.direction ?? "up") === "up" && era.end != null && era.end <= era.start) {
+      errors.push(`Era "${era.name}": end must be after start`);
+    }
+    if ((era.direction ?? "up") === "down" && era.end != null && era.end >= era.start) {
+      errors.push(`Era "${era.name}": a counting-down era must end below its start`);
+    }
+  }
+  const domains = resolveEraDomains(eras);
+  for (let i = 0; i < domains.length; i++) {
+    for (let j = i + 1; j < domains.length; j++) {
+      const a = domains[i];
+      const b = domains[j];
+      if (a.lo < b.hi && b.lo < a.hi) {
+        errors.push(`Eras "${a.era.name}" and "${b.era.name}" overlap`);
+      }
+    }
+  }
+  return errors;
+}
+function readCalendarConfig(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const cfg = value;
+  if (cfg.version !== 1 || typeof cfg.grain !== "string") return null;
+  const months = cfg.bundles?.months;
+  if (months && (!Array.isArray(months.names) || !Array.isArray(months.lengths) || months.names.length !== months.lengths.length || months.names.length === 0)) return null;
+  if (cfg.eras && !Array.isArray(cfg.eras)) return null;
+  if (cfg.eras?.some((e) => typeof e?.name !== "string" || !Number.isFinite(e?.start))) return null;
+  if (cfg.intercalary && (!Array.isArray(cfg.intercalary) || cfg.intercalary.some((i) => typeof i?.name !== "string" || !Number.isInteger(i?.after_month)))) return null;
+  if (months && !months.lengths.every(isPositiveInt)) return null;
+  const year = cfg.bundles?.year;
+  if (year != null && !isPositiveInt(year.steps)) return null;
+  const week = cfg.bundles?.week;
+  if (week != null && (!isPositiveInt(week.length) || !Array.isArray(week.names))) return null;
+  if (cfg.intercalary?.some((i) => i.every_years != null && !isPositiveInt(i.every_years))) return null;
+  return cfg;
+}
+function isPositiveInt(n) {
+  return Number.isSafeInteger(n) && n >= 1;
+}
+function yearShape(cfg) {
+  const months = cfg.bundles?.months;
+  const inter = cfg.intercalary ?? [];
+  const leapPeriods = inter.filter((i) => i.every_years != null).map((i) => i.every_years);
+  if (months) {
+    const base = months.lengths.reduce((a, b) => a + b, 0) + inter.filter((i) => i.every_years == null).length;
+    return { baseLen: base, leapPeriods };
+  }
+  return { baseLen: cfg.bundles?.year?.steps ?? 1, leapPeriods };
+}
+function leapYearsBefore(y, N) {
+  if (y > 0) return floorDiv(y - 1, N) + 1;
+  if (y === 0) return 0;
+  return -floorDiv(-y, N);
+}
+function isLeapYear(y, N) {
+  return floorMod(y, N) === 0;
+}
+function yearStartStep(cfg, y) {
+  const shape = yearShape(cfg);
+  let start = y * shape.baseLen;
+  for (const N of shape.leapPeriods) start += leapYearsBefore(y, N);
+  return start;
+}
+function yearLength(cfg, y) {
+  const shape = yearShape(cfg);
+  let len = shape.baseLen;
+  for (const N of shape.leapPeriods) if (isLeapYear(y, N)) len += 1;
+  return len;
+}
+var MAX_YEAR_CORRECTION = 1e4;
+function absoluteYear(cfg, step) {
+  const shape = yearShape(cfg);
+  const meanLen = shape.leapPeriods.reduce((a, N) => a + 1 / N, shape.baseLen);
+  let y = floorDiv(step, meanLen);
+  if (!Number.isFinite(y)) return y;
+  for (let i = 0; i < MAX_YEAR_CORRECTION && step < yearStartStep(cfg, y); i++) y -= 1;
+  for (let i = 0; i < MAX_YEAR_CORRECTION && step >= yearStartStep(cfg, y + 1); i++) y += 1;
+  return y;
+}
+function resolveEraDomains(eras) {
+  const sorted = [...eras].sort((a, b) => a.start - b.start);
+  const out = [];
+  for (let i = 0; i < sorted.length; i++) {
+    const era = sorted[i];
+    if ((era.direction ?? "up") === "down") {
+      out.push({ era, lo: era.end ?? -Infinity, hi: era.start });
+    } else {
+      const nextStart = sorted[i + 1]?.start;
+      out.push({ era, lo: era.start, hi: era.end ?? nextStart ?? Infinity });
+    }
+  }
+  return out;
+}
+function eraForStep(cfg, step) {
+  const eras = cfg.eras ?? [];
+  if (eras.length === 0) return null;
+  const holding = resolveEraDomains(eras).filter((d) => step >= d.lo && step < d.hi);
+  if (holding.length === 0) return null;
+  holding.sort((a, b) => b.era.start - a.era.start || ((a.era.direction ?? "up") === "up" ? -1 : 1));
+  return holding[0].era;
+}
+function displayYear(cfg, step, era) {
+  const abs = absoluteYear(cfg, step);
+  if (!era || era.restart === false) return abs;
+  const base = era.year_base ?? 1;
+  if ((era.direction ?? "up") === "down") {
+    return absoluteYear(cfg, era.start) - abs + base - 1;
+  }
+  return abs - absoluteYear(cfg, era.start) + base;
+}
+function yearSlots(cfg, y) {
+  const months = cfg.bundles?.months;
+  if (!months) return [];
+  const inter = cfg.intercalary ?? [];
+  const active = (ic) => ic.every_years == null || isLeapYear(y, ic.every_years);
+  const slots = [];
+  const push = (afterMonth) => {
+    for (const ic of inter) if (ic.after_month === afterMonth && active(ic)) slots.push({ kind: "intercalary", intercalary: ic });
+  };
+  push(0);
+  for (let m = 1; m <= months.names.length; m++) {
+    for (let d = 1; d <= months.lengths[m - 1]; d++) slots.push({ kind: "month", month: m, day: d });
+    push(m);
+  }
+  return slots;
+}
+function skippedWeekDaysPerYear(cfg) {
+  const inter = (cfg.intercalary ?? []).filter((i) => i.in_week === false);
+  return {
+    base: inter.filter((i) => i.every_years == null).length,
+    leapPeriods: inter.filter((i) => i.every_years != null).map((i) => i.every_years)
+  };
+}
+function weekdayForStep(cfg, step, pre) {
+  const week = cfg.bundles?.week;
+  if (!week || week.length < 1 || week.names.length !== week.length) return null;
+  const pos = pre ?? positionOf(cfg, step);
+  if ((week.mode ?? "free") === "nested") {
+    if (pos.slot?.kind !== "month") return null;
+    return week.names[floorMod(pos.slot.day - 1, week.length)];
+  }
+  if (pos.slot?.kind === "intercalary" && pos.slot.intercalary?.in_week === false) return null;
+  const skipped = skippedWeekDaysPerYear(cfg);
+  const y = pos.absYear;
+  let skippedBeforeYear = y * skipped.base;
+  for (const N of skipped.leapPeriods) skippedBeforeYear += leapYearsBefore(y, N);
+  let skippedInYear = 0;
+  if (pos.slots) {
+    for (let i = 0; i < pos.offset; i++) {
+      const s = pos.slots[i];
+      if (s.kind === "intercalary" && s.intercalary?.in_week === false) skippedInYear += 1;
+    }
+  }
+  const counted = step - skippedBeforeYear - skippedInYear;
+  return week.names[floorMod(counted, week.length)];
+}
+function positionOf(cfg, step) {
+  const y = absoluteYear(cfg, step);
+  const offset = step - yearStartStep(cfg, y);
+  if (!cfg.bundles?.months) return { absYear: y, offset, slot: null, slots: null };
+  const slots = yearSlots(cfg, y);
+  return { absYear: y, offset, slot: slots[offset] ?? null, slots };
+}
+function breakdownStep(cfg, step) {
+  const pos = positionOf(cfg, step);
+  const era = eraForStep(cfg, step);
+  const months = cfg.bundles?.months;
+  const slot = pos.slot;
+  return {
+    step,
+    absYear: pos.absYear,
+    year: displayYear(cfg, step, era),
+    era,
+    month: slot?.kind === "month" ? slot.month : null,
+    monthName: slot?.kind === "month" && months ? months.names[slot.month - 1] : null,
+    day: slot?.kind === "month" ? slot.day : null,
+    intercalary: slot?.kind === "intercalary" ? slot.intercalary.name : null,
+    weekday: weekdayForStep(cfg, step, pos)
+  };
+}
+var KNOWN_TOKENS = ["day", "month", "weekday", "year", "era", "step", "intercalary"];
+var DEFAULT_FORMAT_MONTHS = "{day} {month}, {year} {era}";
+var DEFAULT_FORMAT_PLAIN = "{year} {era}";
+var DEFAULT_FORMAT_INTERCALARY = "{intercalary}, {year} {era}";
+var EMPTY_KNOWN = "\uE000";
+function renderTemplate(template, values) {
+  let out = template.replace(/\{([a-z_]+)\}/g, (whole, token) => {
+    if (!KNOWN_TOKENS.includes(token)) return whole;
+    const v = values[token];
+    return v == null || v === "" ? EMPTY_KNOWN : v;
+  });
+  out = out.replace(/\s*[,;·]?\s*\uE000\s*[,;·]?\s*/g, " ").replace(/\s{2,}/g, " ").trim().replace(/^[\s,;·]+|[\s,;·]+$/g, "");
+  return out;
+}
+function formatStep(cfg, step) {
+  const b = breakdownStep(cfg, step);
+  const values = {
+    day: b.day != null ? String(b.day) : null,
+    month: b.monthName,
+    weekday: b.weekday,
+    year: String(b.year),
+    era: b.era ? b.era.abbrev ?? b.era.name : null,
+    step: String(step),
+    intercalary: b.intercalary
+  };
+  const template = b.intercalary != null ? cfg.format_intercalary ?? DEFAULT_FORMAT_INTERCALARY : cfg.format ?? (cfg.bundles?.months ? DEFAULT_FORMAT_MONTHS : DEFAULT_FORMAT_PLAIN);
+  return renderTemplate(template, values);
+}
+function formatYearLabel(cfg, step) {
+  const era = eraForStep(cfg, step);
+  const year = displayYear(cfg, step, era);
+  const eraLabel = era ? era.abbrev ?? era.name : "";
+  return eraLabel ? `${year} ${eraLabel}` : String(year);
+}
+function approxYearLength(cfg) {
+  if (cfg.bundles?.months) {
+    return cfg.bundles.months.lengths.reduce((a, b) => a + b, 0) + (cfg.intercalary ?? []).filter((i) => i.every_years == null).length;
+  }
+  return cfg.bundles?.year?.steps ?? null;
+}
+function formatDuration(cfg, steps) {
+  const n = Math.abs(steps);
+  const unit = (cfg.step_name ?? cfg.grain ?? "step").trim() || "step";
+  const plural = (word, v) => v === 1 ? word : `${word}s`;
+  const yearLen = cfg.bundles?.months ? cfg.bundles.months.lengths.reduce((a, b) => a + b, 0) + (cfg.intercalary ?? []).filter((i) => i.every_years == null).length : cfg.bundles?.year?.steps ?? (unit.toLowerCase() === "year" ? 1 : null);
+  if (yearLen != null && yearLen > 1 && n >= yearLen) {
+    const years = n / yearLen;
+    const rounded = years >= 10 ? Math.round(years) : Math.round(years * 10) / 10;
+    return `${rounded} ${plural("year", rounded)}`;
+  }
+  const shown = Math.round(n * 100) / 100;
+  return `${shown} ${plural(unit, shown)}`;
+}
+function monthStartSteps(cfg, y) {
+  const months = cfg.bundles?.months;
+  if (!months) return [];
+  const inter = cfg.intercalary ?? [];
+  const active = (ic) => ic.every_years == null || isLeapYear(y, ic.every_years);
+  const out = [];
+  let offset = inter.filter((i) => i.after_month === 0 && active(i)).length;
+  const start = yearStartStep(cfg, y);
+  for (let m = 1; m <= months.names.length; m++) {
+    out.push({ month: m, name: months.names[m - 1], step: start + offset });
+    offset += months.lengths[m - 1] + inter.filter((i) => i.after_month === m && active(i)).length;
+  }
+  return out;
+}
+function formatMidLabel(cfg, step) {
+  const b = breakdownStep(cfg, step);
+  if (b.intercalary != null) return `${b.intercalary} ${b.year}`;
+  if (b.monthName != null && b.day != null) return `${b.day} ${b.monthName} ${b.year}`;
+  return formatYearLabel(cfg, step);
+}
+function absYearForEraYear(cfg, era, Y) {
+  if (era.restart === false) return Y;
+  const base = era.year_base ?? 1;
+  if ((era.direction ?? "up") === "down") return absoluteYear(cfg, era.start) - (Y - base + 1);
+  return absoluteYear(cfg, era.start) + (Y - base);
+}
+function defaultEra(cfg, now) {
+  const eras = cfg.eras ?? [];
+  if (eras.length === 0) return null;
+  if (now != null) {
+    const holder = eraForStep(cfg, now);
+    if (holder) return holder;
+  }
+  const open = eras.filter((e) => !e.closed);
+  const pool = open.length > 0 ? open : eras;
+  return [...pool].sort((a, b) => b.start - a.start)[0];
+}
+function parseDate(cfg, input, opts = {}) {
+  const raw = input.trim();
+  if (raw === "") return { error: "empty date" };
+  if (/^-?\d+$/.test(raw)) return { step: parseInt(raw, 10) };
+  const normalize2 = (s) => ` ${s.toLowerCase().replace(/[,.]/g, " ").replace(/\s+/g, " ").trim()} `;
+  const months = cfg.bundles?.months;
+  const inter = cfg.intercalary ?? [];
+  let era = null;
+  let monthIndex = null;
+  let intercalary = null;
+  let rest = normalize2(raw).replace(/ year /g, " ");
+  const eat = (name) => {
+    const needle = normalize2(name);
+    if (rest.includes(needle)) {
+      rest = rest.replace(needle, " ");
+      return true;
+    }
+    return false;
+  };
+  const eraCandidates = [...cfg.eras ?? []].flatMap((e) => [{ key: e.name, e }, ...e.abbrev ? [{ key: e.abbrev, e }] : []]).sort((a, b) => b.key.length - a.key.length);
+  for (const c of eraCandidates) if (eat(c.key)) {
+    era = c.e;
+    break;
+  }
+  const interCandidates = [...inter].sort((a, b) => b.name.length - a.name.length);
+  for (const c of interCandidates) if (eat(c.name)) {
+    intercalary = c;
+    break;
+  }
+  if (!intercalary && months) {
+    for (let m = 1; m <= months.names.length; m++) {
+      if (eat(months.names[m - 1])) {
+        monthIndex = m;
+        break;
+      }
+    }
+  }
+  const numbers = [];
+  for (const p of rest.trim().split(/\s+/).filter(Boolean)) {
+    if (/^-?\d+$/.test(p)) numbers.push(parseInt(p, 10));
+    else return { error: `unrecognized: "${p}"` };
+  }
+  let day = null;
+  let year = null;
+  if (monthIndex != null) {
+    if (numbers.length === 2) {
+      const len = months ? months.lengths[monthIndex - 1] : 0;
+      const [a, b] = numbers;
+      if (a >= 1 && a <= len) {
+        day = a;
+        year = b;
+      } else if (b >= 1 && b <= len) {
+        day = b;
+        year = a;
+      } else return { error: `no day in ${months?.names[monthIndex - 1]} matches ${a}/${b}` };
+    } else if (numbers.length === 1) {
+      const len = months ? months.lengths[monthIndex - 1] : 0;
+      const n = numbers[0];
+      if (n >= 1 && n <= len) {
+        day = n;
+        year = null;
+      } else {
+        year = n;
+      }
+    } else if (numbers.length !== 0) {
+      return { error: "too many numbers" };
+    }
+  } else if (intercalary != null) {
+    if (numbers.length > 1) return { error: "too many numbers" };
+    year = numbers[0] ?? null;
+  } else {
+    if (numbers.length !== 1) return { error: "expected a year" };
+    year = numbers[0];
+  }
+  const resolveInYear = (abs) => {
+    const start = yearStartStep(cfg, abs);
+    if (monthIndex == null && intercalary == null) return { step: start };
+    const slots = yearSlots(cfg, abs);
+    if (intercalary != null) {
+      const idx2 = slots.findIndex((s) => s.kind === "intercalary" && s.intercalary === intercalary);
+      if (idx2 === -1) return { error: `${intercalary.name} does not occur in that year` };
+      return { step: start + idx2 };
+    }
+    const idx = slots.findIndex((s) => s.kind === "month" && s.month === monthIndex && s.day === (day ?? 1));
+    if (idx === -1) return { error: "that day does not exist in that month" };
+    return { step: start + idx };
+  };
+  if (year == null) {
+    if (opts.now == null) return { error: "add a year (the world clock has no now set)" };
+    return resolveInYear(absoluteYear(cfg, opts.now));
+  }
+  const target = era ?? defaultEra(cfg, opts.now);
+  if (!target) return resolveInYear(year);
+  const viaEra = resolveInYear(absYearForEraYear(cfg, target, year));
+  if (isParseError(viaEra)) return viaEra;
+  if (eraForStep(cfg, viaEra.step) === target) return viaEra;
+  return resolveInYear(year);
+}
+function isParseError(r) {
+  return r.error !== void 0;
+}
+
+// src/calendar/index.ts
+var CALENDAR_SUPERTYPE = "calendar";
+var CALENDAR_FIELD = "atlas_calendar";
+function readCalendarValue(raw) {
+  if (raw == null) return null;
+  let value = raw;
+  if (typeof raw === "string") {
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  return readCalendarConfig(value);
+}
+function worldCalendars(elements) {
+  const out = [];
+  for (const el of elements) {
+    const config = readCalendarValue(el[CALENDAR_FIELD]);
+    if (!config) continue;
+    out.push({ id: el.id, name: el.name || "(unnamed calendar)", config });
+  }
+  return out;
+}
+function resolveCalendarLens(elements, activeId, opts) {
+  if (activeId === void 0 && opts?.fallbackToOnly) {
+    const all = worldCalendars(elements);
+    return all.length === 1 ? all[0] : null;
+  }
+  if (!activeId) return null;
+  return worldCalendars(elements).find((c) => c.id === activeId) ?? null;
+}
+
 // src/token-resource.ts
 var TokenResource = class {
   constructor(client) {
@@ -2307,6 +2757,8 @@ var GameTier = /* @__PURE__ */ ((GameTier2) => {
 })(GameTier || {});
 export {
   ASK_LIMITS,
+  CALENDAR_FIELD,
+  CALENDAR_SUPERTYPE,
   ELEMENT_FAMILIES,
   ELEMENT_ICONS,
   ELEMENT_LABELS,
@@ -2328,22 +2780,47 @@ export {
   TokenResource,
   WORLD_FILE_MAX_BYTES,
   WORLD_FILE_MAX_ENTRIES,
+  absYearForEraYear,
+  absoluteYear,
+  approxYearLength,
+  breakdownStep,
   buildAskContext,
   buildWorldIndex,
   detectKeyKind,
+  displayYear,
   elementColor,
+  eraForStep,
   errorFromResponse,
   familyOf,
+  floorDiv,
+  floorMod,
+  formatDuration,
+  formatMidLabel,
+  formatStep,
+  formatYearLabel,
   getElementIcon,
   getElementLabel,
   isDemoKey,
+  isLeapYear,
+  isParseError,
   kindCanWrite,
   lookupWorld,
+  monthStartSteps,
+  parseDate,
   parseErrorEnvelope,
   pinExpectation,
   planPhoto,
   preparePhoto,
+  readCalendarConfig,
+  readCalendarValue,
   readWorldFile,
   renderElement,
-  writeWorldFile
+  resolveCalendarLens,
+  resolveEraDomains,
+  validateCalendarConfig,
+  weekdayForStep,
+  worldCalendars,
+  writeWorldFile,
+  yearLength,
+  yearStartStep
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyworlds/sdk",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
   "type": "module",
   "exports": {