daymath 0.3.0 → 0.5.0

package/README.md

@@ -5,10 +5,11 @@
 [![codecov](https://codecov.io/gh/leemr/daymath/graph/badge.svg)](https://codecov.io/gh/leemr/daymath)
 [![license](https://img.shields.io/npm/l/daymath.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/daymath.svg)](https://www.npmjs.com/package/daymath)
+[![bundle](https://img.shields.io/bundlejs/size/daymath)](https://bundlejs.com/?q=daymath)
 
 **ISO 8601** calendar day math. **date-fns-shaped** names. **Temporal.PlainDate** under the hood.
 
-No `Date`. No time zones. No silent “local now.” ISO 8601 ❤️
+No `Date`. No time zones. No silent “local now”. ISO 8601 ❤️
 
 [**Play →**](https://leemr.github.io/daymath/) · [npm](https://www.npmjs.com/package/daymath) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [FUTURE](./FUTURE.md)
 
@@ -27,7 +28,7 @@ npm install @leemr/daymath
 Most people should keep using **`daymath` on npmjs**.
 
 ```js
-import { addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
+import { day, addDays, addMonths, differenceInDays, isSameDay } from 'daymath'
 
 addDays('2026-08-06', 1)      // '2026-08-07'
 addMonths('2026-01-31', 1)    // '2026-02-28'
@@ -35,6 +36,67 @@ differenceInDays('2026-08-06', '2026-08-01') // 5
 isSameDay('2026-08-06', '2026-08-06')        // true
 ```
 
+`day` is the way in. It turns a moment into a day, and it is the only function
+that reads a clock.
+
+Start here. No arguments means today, in UTC.
+
+```js
+day()                                  // '2026-08-08'
+addDays(day(), 2)                      // '2026-08-10'
+```
+
+Then hand it whatever you already have. It converts; it never stores what you gave it.
+
+```js
+day(row.createdAt)                     // '2026-08-07'  a Date
+day(1761616161771)                     // '2025-10-28'  epoch milliseconds
+day('1999-01-01T00:00:00Z')            // '1999-01-01'  an ISO timestamp
+day('2026-05-05')                      // '2026-05-05'  already a day
+```
+
+Name a zone when the answer depends on one.
+
+```js
+day('Asia/Tokyo')                      // '2026-08-09'  today in Tokyo
+day(row.createdAt, 'America/New_York') // '2026-08-06'  the evening before
+day('2026-08-08T23:00:00Z', 'Asia/Tokyo') // '2026-08-09'  same instant, next day
+day(zdt.toString())                    // the zone in the string wins
+```
+
+Both defaults are **stated**, not assumed.
+UTC is still not your day for part of every day — it runs ahead of `America/New_York`
+for 16.7% of the day, and behind `Asia/Tokyo` for 37.5% — so name your zone when
+that matters.
+
+Four rules worth knowing:
+
+- A **number is epoch milliseconds**, exactly as `new Date(n)` reads it. A seconds
+  timestamp read as milliseconds lands in 1970, with no error. daymath states the
+  unit rather than sniffing it, because no rule can separate the two: 13 digits
+  means milliseconds for 2001–2286 and seconds for the year 275760, and both are
+  inside the supported range.
+- A **day carries no time**, so a zone does not apply to one.
+  `day('2026-05-05', 'Asia/Tokyo')` is `'2026-05-05'`.
+- A **timestamp carrying `Z` or an offset** names an exact instant, so it is read
+  as a moment.
+- A **string carrying a `[Zone]`** names its own zone, so it keeps its own day and
+  the UTC default never applies. `day(zdt.toString())` equals `zdt.toPlainDate()`.
+  A browser sending `'2026-08-08T20:00:00-04:00[America/New_York]'` gets back the
+  8th, which is the date its user saw. Passing `tz` as well throws.
+- A string with **neither** is refused. `'2026-08-08T12:00'` names no instant and
+  no zone, so daymath would have to pick one, and it will not pick for you. Name
+  the zone — `'2026-08-08T12:00[America/New_York]'` — and it is accepted.
+- **`'11/12/2026'` is refused.** Nobody can tell November from December in it.
+
+A lone string takes one of four roles, decided in this order: a day, a zoned time,
+an instant, then a zone. The zone test is by **shape** — an IANA name, which carries no `:`, or
+a bare offset such as `+05:30`. Temporal's own zone grammar cannot decide the role:
+it accepts a whole timestamp and reads the zone out of it, so
+`day('1999-01-01T00:00:00Z')` would answer today. That grammar also differs between
+implementations — `'T12:00:00Z'` is a zone to native Temporal and not to the
+polyfill — which would make the answer depend on the runtime.
+
 ```bash
 node examples/basic.mjs   # from a clone
 ```
@@ -46,9 +108,14 @@ node examples/basic.mjs   # from a clone
 | In | Out |
 |----|-----|
 | `YYYY-MM-DD` or expanded `±YYYYYY-MM-DD` | same forms (Temporal `toString`) |
-| or `Temporal.PlainDate` | string |
+| or `Temporal.PlainDate`, from any implementation | string |
+
+A `Date` **throws** everywhere except `day()`, including in `isValid`.
+`isValid('asdf')` → `false`.
 
-`Date` **throws** (including `isValid`). `isValid('asdf')` → `false`.
+`day()` is the single door a `Date` comes through, and it makes you name the zone
+or take the stated UTC default. Nothing carries a zone past that point, and
+nothing gives you a `Date` back.
 
 Range: `-271821-04-19` … `+275760-09-13` — the `Temporal.PlainDate` limit, roughly ±10⁸ days from the epoch. A day outside it throws a `RangeError`.
 
@@ -66,6 +133,8 @@ Range: `-271821-04-19` … `+275760-09-13` — the `Temporal.PlainDate` limit, r
 
 ## API
 
+**Start here** — `day`  
+
 **Parse** — `parse` · `format` · `isValid`  
 
 **Add/sub** — Days · Weeks · Months · Years · Quarters  
@@ -86,11 +155,191 @@ Amounts are finite integers.
 
 ## Temporal
 
-Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill).
+Uses global `Temporal` when present; otherwise [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill),
+which does that resolution itself — so on a runtime with native Temporal the polyfill steps aside.
+
+A `Temporal.PlainDate` from *any* implementation is accepted — native, the bundled polyfill,
+or a second copy of it in the same dependency tree. daymath reads its ISO day and builds its
+own instance, so it never depends on `instanceof` agreeing across copies. The common case is
+`Temporal.Now.plainDateISO()`: daymath has no `today()` on purpose, so that is where a caller
+gets one.
+
+### Calendars
+
+Temporal can put a calendar on a `PlainDate`. The same *day* then carries different numbers:
+
+| calendar | year | month | day | `toString()` | daymath |
+|---|---|---|---|---|---|
+| `iso8601` | 2026 | 1 | 31 | `2026-01-31` | accepted |
+| `buddhist` | **2569** | 1 | 31 | `2026-01-31[u-ca=buddhist]` | **accepted** |
+| `roc` | **115** | 1 | 31 | `2026-01-31[u-ca=roc]` | **accepted** |
+| `japanese` | 2026 | 1 | 31 | `2026-01-31[u-ca=japanese]` | **accepted** |
+| `gregory` | 2026 | 1 | 31 | `2026-01-31[u-ca=gregory]` | **accepted** |
+| `hebrew` | 5786 | **5** | **13** | `2026-01-31[u-ca=hebrew]` | refused |
+| `chinese` | 2025 | **13** | **13** | `2026-01-31[u-ca=chinese]` | refused |
+
+**daymath accepts a calendar that only relabels the year, and refuses one that renumbers.** The
+line is measured at runtime, not held as a list, so a calendar CLDR adds later needs no code
+change here. Two conditions, both required, on nine probe dates spanning 1900 to 2100:
+
+1. **Month and day equal the ISO fields.** A month *count* would be wrong: `hebrew` is lunisolar,
+   so it has 12 months in 2025 and 13 in 2027.
+2. **The year offset is constant.** Two probe pairs straddle a Japanese era boundary, because an
+   era change inside one ISO year is what separates a label from a renumbering.
+
+For the accepting family only the year label moves, so every export still answers honestly, and
+the annotation rides along:
+
+```js
+getYear('2026-01-31[u-ca=buddhist]')        // 2569, not 2026
+getMonth('2026-01-31[u-ca=buddhist]')       // 1
+addDays('2026-01-31[u-ca=buddhist]', 1)     // '2026-02-01[u-ca=buddhist]'
+setYear('2026-01-31[u-ca=buddhist]', 2570)  // '2027-01-31[u-ca=buddhist]'
+getYear('2026-01-31[u-ca=roc]')             // 115
+getYear('2026-01-31[u-ca=japanese]')        // 2026
+```
+
+A renumbering calendar is refused, and the message names the calendar and the way out. A calendar
+this runtime cannot build at all gets its own message, so a typo does not read as a renumbering
+calendar:
+
+```js
+getMonth('2026-01-31[u-ca=hebrew]')
+// RangeError: daymath: date calendar "hebrew" renumbers months or days, so daymath
+//             cannot answer a day in it (convert with withCalendar('iso8601'))
+
+getYear('2026-01-31[u-ca=buddhst]')
+// RangeError: daymath: date calendar "buddhst" is not a calendar this runtime knows
+//             (convert with withCalendar('iso8601'))
+
+format(hebrewDate.withCalendar('iso8601'))   // '2026-01-31'
+```
+
+**A day is the same day whatever its year is labelled, so a mixed pair measures rather than
+throwing.** Temporal's own `since` refuses this with `Mismatched calendars`, and its `equals`
+compares the calendar as well as the day. Neither matters to a day count, so daymath normalises
+both sides for measurement. Only the exports that read or write a field honour the label:
+
+```js
+differenceInDays('2026-03-01', '2026-01-31[u-ca=buddhist]')   // 29
+isEqual('2026-01-31[u-ca=buddhist]', '2026-01-31')            // true
+```
+
+**The object form is a different day, and that is Temporal's rule, not daymath's.** A string's
+date part is always ISO; the annotation changes how fields are *read*, never how the string
+*parses*:
+
+```js
+Temporal.PlainDate.from('2026-01-31[u-ca=buddhist]')            // ISO 2026-01-31, .year 2569
+Temporal.PlainDate.from({year: 2026, month: 1, day: 31,
+                         calendar: 'buddhist'})                  // ISO 1483-01-31, .year 2026
+```
+
+543 years apart. daymath takes strings and `PlainDate` objects, never the fields form, so it
+inherits Temporal's rule and stays consistent with it.
+
+`[u-ca=iso8601]` is accepted and dropped rather than carried. Temporal writes it itself for
+`toString({ calendarName: 'always' })`, and daymath already answers in it:
+
+```js
+const written = plainDate.toString({ calendarName: 'always' })  // '2026-01-31[u-ca=iso8601]'
+getYear(written)                                                // 2026
+```
+
+A calendar is judged where it is **applied**. On a day string it is, and with a `[Zone]` bracket
+it is. Without a bracket the string names an `Instant`, which has no year, month or day for a
+calendar to renumber, so the annotation is inert.
+
+**`day()` accepts every annotation the other exports accept, and drops it from the result.** It is
+the normaliser: a moment converts to a plain ISO day, and so does a day. One rule, three input
+shapes:
+
+```js
+day('2026-08-08T20:00:00Z[u-ca=buddhist]')                  // '2026-08-08'
+day('2026-08-08T12:00[America/New_York][u-ca=buddhist]')    // '2026-08-08'
+day('2026-08-08[u-ca=buddhist]')                            // '2026-08-08'
+day('1999-06-06[Asia/Tokyo][u-ca=hebrew]')                  // throws
+
+parse('2026-08-08[u-ca=buddhist]')     // '2026-08-08[u-ca=buddhist]'  parse keeps it
+```
+
+`parse` validates and preserves. `day()` normalises. Every other export carries the annotation,
+because the caller asked for that numbering.
+
+### Working in a non-ISO calendar
+
+**Do not pass the calendar's own year as a bare ISO year.** This is the one way to get a wrong
+answer with no error, and it is why the annotation is not decoration.
+
+Buddhist 2567 is ISO 2024, which is a leap year. The Buddhist year is ISO + 543, and 543 mod 4 is
+3, so the leap years land in different places:
+
+| call | bare `2567` | annotated, the real Buddhist 2567 |
+|---|---|---|
+| `isLeapYear` | `false` | `true` |
+| `getDaysInMonth` for February | `28` | `29` |
+| `parse('…-02-29')` | throws `invalid date` | `2024-02-29[u-ca=buddhist]` |
+| `addDays(Feb 28, 1)` | `2567-03-01` | `2024-02-29[u-ca=buddhist]` |
+
+**The two disagree in 49 of the 101 Buddhist years from 2500 to 2600.** Nothing throws on the
+bare form, and `addDays('2567-02-28', 1)` answering `2567-03-01` looks reasonable, so a date lands
+one day early for the rest of that year. Every other month is identical, because February is the
+only month whose length varies.
+
+**A `Date` cannot help you here, because a `Date` has no calendar.** It is one number of
+milliseconds. `getUTCFullYear()` is always Gregorian, so a Thai user's `Date` already holds `2026`.
+The `2569` exists only at display time, when `Intl` formats it:
+
+```js
+new Intl.DateTimeFormat('th-TH-u-ca-buddhist', {dateStyle: 'short'}).format(d)   // '8/8/69'
+```
+
+So the recipe is:
+
+1. From a `Date` or a timestamp, call `day(…)`. You get a plain ISO day.
+2. To work in Buddhist years, annotate that day: `'2026-08-08[u-ca=buddhist]'`. Now `getYear` is
+   `2569`, `isLeapYear` is right, and every export carries the annotation through.
+3. **From a Buddhist year *number*, use Temporal's fields form.** This is the one place the
+   fields/string asymmetry helps rather than traps:
+
+```js
+Temporal.PlainDate.from({year: 2569, month: 8, day: 8, calendar: 'buddhist'}).toString()
+// '2026-08-08[u-ca=buddhist]'      <- and daymath accepts the object directly too
+```
+
+4. For display, use `Intl`. daymath does no localised formatting.
+
+One more trap in the same family: `'2569-08-08[u-ca=buddhist]'` is a valid string, and its
+`getYear` is **3112**. The date part is ISO 2569, and the annotation adds 543 on top.
+
+Supporting these calendars needs `temporal-polyfill/full`, because the base build cannot construct
+them where the runtime has no native Temporal. That costs **4.2 kB gzip**, and it is what makes
+the answers identical on every runtime rather than only on the ones with native Temporal.
+
+Error messages quote no Temporal text, because implementations word the same failure
+differently. The original error is on `cause`.
+
+Behaviour is checked against a recorded baseline on Node, Deno (which ships **native**
+Temporal) and Bun — every export, `npm run test:runtimes`. The exact call count lives
+in `scripts/cross-runtime.baseline.json`, which is the only place it cannot go stale.
+
+## Requirements
+
+ESM only. **Node 20.19+, or 22.12+.**
+
+That floor is `require()`, not `import`. Node's `require(esm)` landed in 20.19 and 22.12, so
+those are the versions where `require('daymath')` works. `engines` states the range exactly,
+including the gap at 22.0–22.11. `temporal-polyfill` is ESM-only too, so a CJS build of daymath
+would not escape this. Bundlers and browsers are unaffected. A Jest consumer needs a
+`transformIgnorePatterns` entry, because Jest does not use Node's resolution.
+
+Node 18 was supported through 0.3.0 and is dropped here. It went end-of-life in April 2025.
 
 ## Types & tests
 
-Plain JS + `index.d.ts` (no compile step). CI runs on Node 18, 20, 22, 24, and 26; the coverage gate runs on 24.
+Plain JS + `index.d.ts` (no compile step). CI runs on Node 20, 22, 24, and 26; the
+coverage gate runs on 26, which is also the version in `.node-version` and the one used
+to publish. The matrix still proves the floor.
 
 ```bash
 npm test

package/index.d.ts

@@ -8,6 +8,18 @@ import type { Temporal } from 'temporal-polyfill'
  * Usable range is the Temporal `PlainDate` range `-271821-04-19` …
  * `+275760-09-13`; a day outside it throws a `RangeError`.
  * `Date` is rejected at runtime (TypeError).
+ *
+ * A `[u-ca=…]` calendar annotation is accepted when the calendar only relabels
+ * the year, and it rides along into the result:
+ * `getYear('2026-01-31[u-ca=buddhist]')` is `2569` and `addDays` of it is
+ * `'2026-02-01[u-ca=buddhist]'`. Today that admits `buddhist`, `roc`,
+ * `japanese` and `gregory`. A calendar that renumbers months or days, such as
+ * `hebrew` or `chinese`, throws a `RangeError`. The line is measured at runtime
+ * rather than held as a list, so no code names a calendar.
+ *
+ * Measurement ignores the label, because a day is the same day whatever its
+ * year is called: `differenceInDays` and `isEqual` normalise both operands, so a
+ * mixed pair answers instead of throwing `Mismatched calendars`.
  */
 export type DayInput = string | Temporal.PlainDate
 
@@ -26,6 +38,40 @@ export type WeekOptions = {
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
 }
 
+/**
+ * The calendar day of a moment, in a zone. The way in.
+ *
+ * Both defaults are stated: the moment is now, the zone is UTC. A number is
+ * read as epoch **milliseconds**, exactly as `new Date(n)` reads it. An ISO day
+ * string is already a day, so a zone does not apply to it. An ISO timestamp
+ * carrying `Z` or an offset names an exact instant, so it is read as a moment.
+ *
+ * A string carrying a `[Zone]` annotation names its own zone, so it answers its
+ * own civil day and the UTC default never applies. Passing `tz` as well throws.
+ *
+ * `'11/12/2026'` is refused, because nobody can tell November from December in
+ * it. `'2026-08-08T12:00'` is refused too: no offset and no zone, so daymath
+ * would have to pick one. Name the zone and it is accepted.
+ *
+ * A lone string takes one of four roles, in this order: a day, a zoned time, an
+ * instant, then a zone. The zone test is by shape — an IANA name, which carries
+ * no `:`, or a bare offset — so a timestamp can never be read as a zone.
+ *
+ * **day() is the normaliser, and that is the whole rule: a moment converts to a
+ * plain ISO day, and so does a day.** A `[u-ca=…]` annotation is accepted
+ * wherever the other exports accept it, and then dropped from the result, so
+ * `day` never returns `[u-ca=…]`. Every other export carries it. `parse`
+ * validates and preserves; `day` normalises.
+ *
+ * A calendar that renumbers months or days is still refused where it is
+ * applied, which means with a `[Zone]` bracket and on a day string.
+ */
+export function day(tz?: string): string
+export function day(
+  moment: Date | number | DayInput | null | undefined,
+  tz?: string,
+): string
+
 /**
  * True for a valid daymath day string / PlainDate.
  * Invalid strings → false. `Date` → throws TypeError (not a quiet false).
@@ -81,11 +127,17 @@ export function endOfWeek(date: DayInput, options?: WeekOptions): string
 export function differenceInDays(dateLeft: DayInput, dateRight: DayInput): number
 export function differenceInWeeks(dateLeft: DayInput, dateRight: DayInput): number
 export function differenceInMonths(dateLeft: DayInput, dateRight: DayInput): number
-export function differenceInCalendarMonths(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInCalendarMonths(
+  dateLeft: DayInput,
+  dateRight: DayInput,
+): number
 export function differenceInYears(dateLeft: DayInput, dateRight: DayInput): number
 export function differenceInCalendarYears(dateLeft: DayInput, dateRight: DayInput): number
 export function differenceInQuarters(dateLeft: DayInput, dateRight: DayInput): number
-export function differenceInCalendarQuarters(dateLeft: DayInput, dateRight: DayInput): number
+export function differenceInCalendarQuarters(
+  dateLeft: DayInput,
+  dateRight: DayInput,
+): number
 
 export function isBefore(date: DayInput, dateToCompare: DayInput): boolean
 export function isAfter(date: DayInput, dateToCompare: DayInput): boolean

package/index.js

@@ -1,7 +1,95 @@
-/** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date / time zones. */
-import { Temporal as TemporalPolyfill } from 'temporal-polyfill'
+/** daymath — calendar date math (ISO 8601 day). date-fns-shaped. No Date. No time zones. */
+// The selection is HERE on purpose, and it must not be removed again.
+//
+// `temporal-polyfill`'s base entry resolves `globalThis.Temporal || bundled` itself, so importing
+// it gave native Temporal for free. But that base build can construct only iso8601 and gregory, so
+// it cannot serve the calendar rule below. `temporal-polyfill/full` can construct sixteen — and its
+// entry is a bare re-export with NO selection, so importing it alone silenced native Temporal on
+// every runtime, including Node 26 and Deno. Round 1 of a review caught that.
+//
+// Round 2 then caught the naive repair. A global `Temporal` is NOT necessarily native: an app doing
+// `import 'temporal-polyfill/global'` installs the BASE build, and the polyfill's own README calls
+// that the most common entry point. Selecting it blindly cost daymath three of its four calendars
+// on Node 20 and 22, which have no native Temporal, and the error blamed the caller's calendar
+// rather than naming the capability loss. Import order decided it, which is worse than a wrong
+// answer. So the candidate is PROBED, not trusted.
+//
+// The probe names no calendar. It asks the runtime for one, which keeps the "method, not a list"
+// rule that governs the calendar surface below.
+//
+// Measured: the selection costs 17 B gzip, because the polyfill ships either way — a bundler cannot
+// know at build time whether the runtime has Temporal, which is why FUTURE.md records dynamic
+// import as a dead end. Native and the bundled full build agree on every calendar daymath touches:
+// 464 date/calendar pairs over the four accepted calendars from 1900 to 2100, plus the eleven
+// refused ones, with zero disagreements.
+//
+// Native matters for three reasons beyond taste. daymath's contract is Temporal's behaviour, and
+// native IS Temporal. The deno CI lane exists to prove the polyfill and the standard agree, and it
+// cannot prove that if daymath runs the polyfill there. And an engine-level Temporal fix then
+// reaches callers with no release from here.
+import { Temporal as bundledTemporal } from 'temporal-polyfill/full'
 
-const Temporal = globalThis.Temporal ?? TemporalPolyfill
+/**
+ * Every calendar this runtime names. Read once, lowercased, because BCP-47 keys are
+ * case-insensitive while a `Map` key is not.
+ *
+ * This set is also what bounds the verdict cache below. It is closed and small — 18 ids on Node 26
+ * — so an id the runtime does not name is refused without ever being stored.
+ *
+ * `Intl.supportedValuesOf` is ES2022 and present on every runtime in `engines`.
+ */
+const RUNTIME_CALENDARS = new Set(
+  Intl.supportedValuesOf('calendar').map((id) => id.toLowerCase()),
+)
+
+/**
+ * Can this Temporal build a calendar beyond the two every build has?
+ *
+ * The cast is needed because `Temporal` is not declared on `globalThis` in the type space, and
+ * daymath deliberately installs no global of its own.
+ * @param {unknown} candidate
+ * @returns {candidate is typeof bundledTemporal}
+ */
+/*
+ * Every branch here turns on `globalThis.Temporal`, which is read once at module load. A test in
+ * this process cannot change it after the fact, so none of these branches is reachable from the
+ * suite. They are covered three other ways, and each is real:
+ *
+ * 1. `test.js` spawns a CHILD process that installs the BASE polyfill global and then imports
+ *    daymath. That is the exact scenario this function exists for, and it asserts the four
+ *    calendars survive. A child's execution does not count toward this file's coverage.
+ * 2. The Node 20 and bun CI lanes have no native Temporal, so they take the fallback for real.
+ * 3. `npm run test:runtimes` proves every lane answers identically.
+ */
+/* c8 ignore start */
+function buildsExoticCalendars(candidate) {
+  const temporal = /** @type {typeof bundledTemporal | undefined} */ (candidate)
+  if (temporal?.PlainDate?.from === undefined) return false
+  // Ask the runtime for a calendar rather than naming one. The two excluded here are the pair every
+  // build can construct, so anything else proves the exotic calendar data is present.
+  const exotic = [...RUNTIME_CALENDARS].find((id) => id !== 'iso8601' && id !== 'gregory')
+  if (exotic === undefined) return true // nothing to prove it against
+  try {
+    temporal.PlainDate.from('2026-01-31').withCalendar(exotic)
+    return true
+  } catch {
+    return false
+  }
+}
+/* c8 ignore stop */
+
+// The fallback needs a runtime whose global Temporal is absent or not calendar-capable, so a process
+// with native Temporal cannot reach it. It is covered for real by the Node 20 and bun CI lanes, and
+// `npm run test:runtimes` proves those lanes answer identically to the native ones.
+// One cast, because `Temporal` is not declared on `globalThis` in the type space and daymath
+// deliberately installs no global of its own.
+const globalTemporal = /** @type {{Temporal?: unknown}} */ (globalThis).Temporal
+
+// The fallback needs a runtime whose global Temporal is absent or not calendar-capable, so a process
+// with native Temporal cannot reach it. It is covered for real by the Node 20 and bun CI lanes, and
+// `npm run test:runtimes` proves those lanes answer identically to the native ones.
+/* c8 ignore next */
+const Temporal = buildsExoticCalendars(globalTemporal) ? globalTemporal : bundledTemporal
 
 /**
  * ISO 8601 calendar day string:
@@ -13,10 +101,79 @@ const Temporal = globalThis.Temporal ?? TemporalPolyfill
  * the epoch). Outside it, Temporal throws and we re-throw with the `daymath:`
  * prefix.
  */
-const ISO_DAY =
-  /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/
+const ISO_DAY = /^(?:[+-]\d{6}|\d{4})-\d{2}-\d{2}$/u
+
+/**
+ * Temporal's calendar annotation, `[u-ca=…]` or the critical `[!u-ca=…]`.
+ * Returns what it is attached to, and the calendar it names, or `null`.
+ *
+ * String operations, not a regex, and the reason is measured. The annotation can
+ * sit behind another one — `'…[America/New_York][u-ca=buddhist]'` — so the head
+ * may itself contain `[`. A pattern that allows that needs `^(.*)\[…\]$`, whose
+ * `.*` backtracks: `'[u-ca='.repeat(64000)` cost 9.0 s, growing with the square
+ * of the input. `lastIndexOf` answers the same question in one pass. CodeQL
+ * `js/polynomial-redos` caught the regex form; timing it confirmed the report.
+ * @param {string} text
+ * @returns {{ head: string, calendar: string } | null}
+ */
+function calendarAnnotation(text) {
+  if (!text.endsWith(']')) return null
+  const open = text.lastIndexOf('[')
+  if (open === -1) return null
+  const inner = text.slice(open + 1, -1)
+  const body = inner.startsWith('!') ? inner.slice(1) : inner
+  if (!body.startsWith('u-ca=')) return null
+  const calendar = body.slice(5)
+  // A `]` inside means the brackets do not nest as they appear, so this is not
+  // an annotation. `'[u-ca=[u-ca=[u-ca=x]]]'` reads as the calendar `x]]` here
+  // and as a malformed day everywhere else, which is what it is.
+  if (calendar === '' || calendar.includes(']')) return null
+  return { head: text.slice(0, open), calendar }
+}
+
+/**
+ * True when the string carries a time-zone annotation, `[Zone]` or `[!Zone]`.
+ * It is the one annotation with no `=`, which separates it from `[u-ca=…]`, and
+ * Temporal writes it first, so only the leading bracket can be one.
+ *
+ * Asking "does the string name a zone?" is a different question from "does it
+ * resolve?". A string can name one and still fail: an offset that disagrees with
+ * the zone, or a misspelled name. Both must be errors, never a silent fallback
+ * to the UTC default.
+ *
+ * String operations again. An unanchored `/\[!?[^\]=]+\]/` restarts at every
+ * position: `'[!'.repeat(64000)` cost 6.8 s, and it is the same defect an
+ * earlier commit removed from the calendar pattern.
+ * @param {string} text
+ */
+function hasZoneAnnotation(text) {
+  const open = text.indexOf('[')
+  if (open === -1) return false
+  const close = text.indexOf(']', open)
+  if (close === -1) return false
+  return !text.slice(open + 1, close).includes('=')
+}
 
-/** @typedef {string | Temporal.PlainDate} DayInput */
+/**
+ * A time zone, by shape: an IANA name, or a bare offset.
+ *
+ * A name is letter-led, slash-separated segments of letters, digits, `_`, `+`,
+ * `-` and `.`. It carries no `:`, which is what keeps an ISO time out. The
+ * `(?![Tt]\d)` guard rejects the compact spelling `T120000Z`, which has no `:`
+ * to catch it. Both matter: `T12:00:00Z` is a zone to native Temporal and not
+ * to temporal-polyfill, so letting either through splits the answer by runtime.
+ *
+ * Verified against every zone this runtime knows: 0 of 418 rejected, plus the
+ * aliases `UTC`, `GMT`, `US/Eastern`, `Asia/Calcutta` and `Etc/GMT+5`.
+ */
+const ZONE_LIKE =
+  /^(?:(?![Tt]\d)[A-Za-z][A-Za-z0-9_+.-]*(?:\/[A-Za-z0-9_+.-]+)*|[+-]\d{2}(?::?\d{2})?)$/u
+
+// `Temporal` is a const now, not an imported namespace, so it cannot carry types. `PlainDate` has
+// seven use sites, so a typedef earns itself. `Instant` and `ZonedDateTime` have one each and are
+// inlined, because measured the typedef plus its use is longer than the inline form.
+/** @typedef {import('temporal-polyfill').Temporal.PlainDate} PlainDate */
+/** @typedef {string | PlainDate} DayInput */
 /**
  * @typedef {object} Interval
  * @property {DayInput} start
@@ -31,11 +188,182 @@ const ISO_DAY =
 
 // ─── core conversion ───────────────────────────────────────────────
 
+/**
+ * The bare ISO day inside a string, or `null` if there is not one.
+ *
+ * An annotation is dropped here, never judged. `supportedCalendar` owns that rule, and the two do
+ * not run in a fixed order: `toPlainDate` judges first, and `day()` calls this first. That is safe
+ * precisely because this function strips the annotation without reading it.
+ *
+ * One predicate, because `toPlainDate` and `day()` both ask this question. They
+ * asked it separately once, and day() alone then refused a string that every
+ * other export accepted.
+ * @param {string} text
+ * @returns {string | null}
+ */
+function bareDay(text) {
+  const annotated = calendarAnnotation(text)
+  const bare = annotated ? annotated.head : text
+  return ISO_DAY.test(bare) ? bare : null
+}
+
+/**
+ * Nine probe dates for the calendar rule below.
+ *
+ * They span 1900 to 2100, they sit in different months, and two pairs straddle a Japanese era
+ * boundary: 1989-01-07/08 is Showa 64 into Heisei 1, and 2019-04-30/05-01 is Heisei 31 into
+ * Reiwa 1. An era change *inside* one ISO year is the case a single probe cannot see, and it is
+ * exactly what separates a year label from a year renumbering.
+ */
+const CALENDAR_PROBES = [
+  '1900-01-01',
+  '1900-07-01',
+  '1989-01-07',
+  '1989-01-08',
+  '2019-04-30',
+  '2019-05-01',
+  '2026-01-31',
+  '2026-12-31',
+  '2100-06-15',
+]
+
+/** @type {Map<string, {offset: number} | {reason: 'unknown' | 'renumbers'}>} */
+const calendarRuleCache = new Map()
+
+/**
+ * Is this a calendar the runtime actually names?
+ *
+ * **This is what bounds `calendarRuleCache`, and it is a memory-exhaustion fix.** The cache keys on
+ * whatever sits between `[u-ca=` and `]`, which is caller input.
+ *
+ * A shape guard was tried first and was only half a fix. It bounded the key LENGTH and not the
+ * entry COUNT, so any BCP-47-shaped string still bought a permanent entry: 800,000 distinct
+ * guard-passing ids retained 76.8 MB, growing linearly and never released. Case made it worse,
+ * because the shape test ignored case while the `Map` key did not, so one name had 256 keys.
+ *
+ * A closed set fixes both at once. `RUNTIME_CALENDARS` holds 18 ids on Node 26, so entries can
+ * never exceed what the runtime has, and a lowercased key collapses the case variants. It also
+ * needs no length cap and no pattern, which removes the last quadratic-regex risk from this file.
+ *
+ * The quiet path was `isValid`, which swallows the `RangeError`, so a loop raised nothing and
+ * logged nothing.
+ * @param {string} lowerId
+ */
+function runtimeKnowsCalendar(lowerId) {
+  return RUNTIME_CALENDARS.has(lowerId)
+}
+
+/**
+ * Measure whether a calendar only relabels the year.
+ *
+ * **This is a method, not a list.** Nothing here names a calendar, so a calendar CLDR adds later
+ * is admitted or refused by the same measurement, with no code change. Today it admits
+ * `buddhist` (+543), `roc` (−1911), `japanese` (0) and `gregory` (0), and refuses the other
+ * eleven the runtime knows.
+ *
+ * Two conditions, both required on every probe:
+ *
+ * 1. **Month and day equal the ISO fields.** A month-count test would be wrong: `hebrew` is
+ *    lunisolar, so `monthsInYear` is 13 in 2024, 12 in 2025 and 13 in 2027. Comparing the fields
+ *    is correct in every year.
+ * 2. **The year offset is constant.** `japanese` and `roc` pass condition 1, and Temporal reports
+ *    a continuous year for both, so both are pure labels — `roc` 1900 is −11, not "12 before".
+ *    Reading the year from `Intl` instead would fail here, because `Intl` reports the *era* year:
+ *    Reiwa 8 and B.R.O.C. 12. Temporal is the reference, so Temporal is what this asks.
+ *
+ * The verdict is cached per calendar. It cannot change while the process runs.
+ * @param {string} calendar
+ */
+function calendarRule(calendar) {
+  const cached = calendarRuleCache.get(calendar)
+  if (cached !== undefined) return cached
+  /** @type {{offset: number} | {reason: 'unknown' | 'renumbers'}} */
+  let verdict = { reason: 'renumbers' }
+  try {
+    const offsets = new Set()
+    for (const probe of CALENDAR_PROBES) {
+      const iso = Temporal.PlainDate.from(probe)
+      const dated = iso.withCalendar(calendar)
+      if (dated.month !== iso.month || dated.day !== iso.day) {
+        offsets.clear()
+        break
+      }
+      offsets.add(dated.year - iso.year)
+    }
+    // The offset is the discriminant — `'offset' in verdict` is what accepts — and the number
+    // itself is kept unread on purpose, so a debugger shows WHY a calendar passed.
+    if (offsets.size === 1) verdict = { offset: [...offsets][0] }
+  } catch {
+    // The runtime cannot build this calendar at all, which is a different message for the caller.
+    verdict = { reason: 'unknown' }
+  }
+  calendarRuleCache.set(calendar, verdict)
+  return verdict
+}
+
+/**
+ * Accept a calendar that only relabels the year, and refuse one that renumbers.
+ *
+ * Checked on the *string*, before any parse, so the outcome cannot depend on where the annotation
+ * sits. Returns the calendar for `toPlainDate` to carry, or `undefined` for plain ISO.
+ *
+ * `[u-ca=iso8601]` returns `undefined` rather than carrying: Temporal writes it itself for
+ * `toString({ calendarName: 'always' })`, and daymath already answers in it, so there is nothing
+ * to relabel.
+ * @param {string} text
+ * @param {string} label
+ * @returns {string | undefined}
+ */
+function supportedCalendar(text, label) {
+  const annotated = calendarAnnotation(text)
+  // A bare `return` rather than `return undefined`: oxlint's no-useless-undefined forbids the
+  // explicit spelling, and "nothing to carry" is what both of these mean.
+  if (annotated === null) return
+  const { calendar } = annotated
+  // Lowercased once. BCP-47 keys are case-insensitive, and this is also the cache key, so the case
+  // variants of one name must collapse to one entry rather than 256.
+  const lowerId = calendar.toLowerCase()
+  if (lowerId === 'iso8601') return
+  // Membership FIRST, so an id the runtime does not name is never stored. See runtimeKnowsCalendar.
+  // One throw, not two: an unknown id and a renumbering one differ only in the reason.
+  const verdict = runtimeKnowsCalendar(lowerId)
+    ? calendarRule(lowerId)
+    : /** @type {const} */ ({ reason: 'unknown' })
+  if ('offset' in verdict) return calendar
+  const why =
+    verdict.reason === 'unknown'
+      ? 'is not a calendar this runtime knows'
+      : 'renumbers months or days, so daymath cannot answer a day in it'
+  // The id is sliced because it is caller input, so a megabyte in cannot become a megabyte of error.
+  throw new RangeError(
+    `daymath: ${label} calendar ${JSON.stringify(calendar.slice(0, 40))} ${why} (convert with withCalendar('iso8601'))`,
+  )
+}
+
+/**
+ * True for a `Temporal.PlainDate` from *any* implementation: native, the
+ * bundled polyfill, or a second copy of it in the same dependency tree.
+ * `instanceof` recognises only one of those. Every Temporal puts this tag on
+ * `PlainDate.prototype` as a non-writable property, so it is the portable brand.
+ * @param {unknown} value
+ * @returns {value is PlainDate} a predicate, so callers narrow
+ */
+function isPlainDate(value) {
+  return Object.prototype.toString.call(value) === '[object Temporal.PlainDate]'
+}
+
 /**
  * Reject Date and non-calendar values. Accept ISO day string or PlainDate.
+ *
+ * A PlainDate becomes its ISO day string first, so every input reaches one
+ * validation path and daymath owns the resulting instance.
+ *
+ * A calendar annotation is judged by `supportedCalendar` and then CARRIED, so `getYear` answers
+ * the caller's own number: `2026-01-31[u-ca=buddhist]` reads 2569, not 2026. The rule and the
+ * reasons live on `supportedCalendar`; this function only applies the verdict.
  * @param {unknown} value
  * @param {string} label
- * @returns {Temporal.PlainDate}
+ * @returns {PlainDate}
  */
 function toPlainDate(value, label = 'date') {
   if (value instanceof Date) {
@@ -43,29 +371,48 @@ function toPlainDate(value, label = 'date') {
       `daymath: Date is not allowed for ${label} (pass ISO 8601 day string)`,
     )
   }
-  if (typeof value === 'string') {
-    if (!ISO_DAY.test(value)) {
-      throw new RangeError(
-        `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD (got ${JSON.stringify(value)})`,
-      )
-    }
-    try {
-      return Temporal.PlainDate.from(value)
-    } catch (err) {
-      throw new RangeError(`daymath: invalid ${label} ${JSON.stringify(value)}`, {
-        cause: err,
-      })
-    }
+  // Named `text`, not `day`: a local `day` would shadow the exported day().
+  const text = isPlainDate(value) ? value.toString() : value
+  if (typeof text !== 'string') {
+    throw new TypeError(
+      `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
+    )
   }
-  if (value instanceof Temporal.PlainDate) {
-    return value
+  // Before the shape check: an annotated day is well formed, not malformed.
+  const calendar = supportedCalendar(text, label)
+  const bare = bareDay(text)
+  if (bare === null) {
+    throw new RangeError(
+      `daymath: ${label} must be ISO 8601 day YYYY-MM-DD or ±YYYYYY-MM-DD (got ${JSON.stringify(text)})`,
+    )
   }
-  throw new TypeError(
-    `daymath: ${label} must be ISO 8601 day string or Temporal.PlainDate`,
-  )
+  try {
+    const plain = Temporal.PlainDate.from(bare)
+    // The annotation rides along, so getYear answers 2569 for a Buddhist day and every
+    // returned string keeps the calendar the caller named.
+    return calendar === undefined ? plain : plain.withCalendar(calendar)
+  } catch (err) {
+    throw new RangeError(`daymath: invalid ${label} ${JSON.stringify(text)}`, {
+      cause: err,
+    })
+  }
+}
+
+/**
+ * The same day in ISO, for measurement only.
+ *
+ * Temporal refuses `since` and `until` across two calendars with `Mismatched calendars`, and its
+ * `equals` compares the calendar as well as the day. Neither matters to a day count: a day is the
+ * same day whatever the year is labelled, so daymath normalises and answers. Only the exports that
+ * *read* or *write* a field honour the label.
+ * @param {PlainDate} plain
+ * @returns {PlainDate}
+ */
+function isoOf(plain) {
+  return plain.calendarId === 'iso8601' ? plain : plain.withCalendar('iso8601')
 }
 
-/** @param {Temporal.PlainDate} plain @returns {string} */
+/** @param {PlainDate} plain @returns {string} */
 function toDayString(plain) {
   return plain.toString()
 }
@@ -82,9 +429,14 @@ function assertFiniteNumber(n, label) {
 
 /**
  * Run a Temporal op and keep the `daymath:` message contract when it fails.
- * Temporal throws bare `Out-of-bounds date` / `Non-positive day`; we prefix and
- * keep the original text plus `cause`. Covers both a result past the range and
- * an argument Temporal refuses outright, hence the neutral wording.
+ * Covers both a result past the range and an argument Temporal refuses
+ * outright, hence the neutral wording.
+ *
+ * The message carries no Temporal text. Implementations word the same failure
+ * differently — the polyfill says `Out-of-bounds date` where native V8 says
+ * `Temporal error: epoch days exceed maximum range.` — so quoting it made
+ * daymath's own message vary by runtime. `cause` still holds the original
+ * error, which is where the detail belongs.
  * @template T
  * @param {string} label
  * @param {() => T} op
@@ -94,10 +446,9 @@ function guardRange(label, op) {
   try {
     return op()
   } catch (err) {
-    throw new RangeError(
-      `daymath: ${label} could not produce a valid date (${/** @type {Error} */ (err).message})`,
-      { cause: err },
-    )
+    throw new RangeError(`daymath: ${label} could not produce a valid date`, {
+      cause: err,
+    })
   }
 }
 
@@ -123,7 +474,7 @@ function assertNonEmptyDates(dates) {
 
 /**
  * @param {WeekOptions} [options]
- * @returns {0|1|2|3|4|5|6}
+ * @returns {0|1|2|3|4|5|6|7} 7 is the default, so 0-6 was never the real range
  */
 function weekStartsOnFrom(options) {
   const w = options?.weekStartsOn ?? 7
@@ -135,10 +486,18 @@ function weekStartsOnFrom(options) {
 
 /**
  * @param {unknown} interval
- * @returns {{ start: Temporal.PlainDate, end: Temporal.PlainDate }}
+ * @returns {{ start: PlainDate, end: PlainDate }}
  */
 function toInterval(interval) {
-  if (interval == null || typeof interval !== 'object') {
+  // `typeof x === 'object'` alone let a Date, an array or a PlainDate through,
+  // and the failure then surfaced as "start must be ISO 8601 day string" —
+  // naming a property the caller never meant to pass.
+  if (
+    interval === null || // typeof null is 'object', so it needs its own test
+    typeof interval !== 'object' || // and this already catches undefined
+    !('start' in interval) ||
+    !('end' in interval)
+  ) {
     throw new TypeError('daymath: interval must be { start, end }')
   }
   const start = toPlainDate(/** @type {Interval} */ (interval).start, 'start')
@@ -146,6 +505,228 @@ function toInterval(interval) {
   return { start, end }
 }
 
+// ─── the clock ─────────────────────────────────────────────────────
+
+/**
+ * The calendar day of a moment, in a zone. The way in.
+ *
+ * Both arguments have a **stated** default: the moment is now, and the zone is
+ * UTC. A default that is written down is not a guess; a default that is assumed
+ * is. UTC is still not your day for part of every day — it runs ahead of
+ * America/New_York for 16.7% of the day, and behind Asia/Tokyo for 37.5% — so
+ * name your zone when that matters.
+ *
+ * `moment` accepts what the world actually hands you:
+ * - a `Date`, the only carrier of an instant JavaScript has
+ * - a number, read as **epoch milliseconds**, exactly as `new Date(n)` reads it,
+ *   truncated the same way, so a fractional value is not an error
+ * - an ISO 8601 day string, or a `Temporal.PlainDate` from any implementation,
+ *   both of which are already a day
+ * - an ISO 8601 timestamp carrying `Z` or an offset, which names an exact
+ *   instant, so there is nothing left to guess
+ * - a string carrying a `[Zone]` annotation, which names its own zone, so it
+ *   answers its own civil day and the `tz` default never applies
+ *
+ * **day() is the normaliser, and that is the one rule to hold: a moment
+ * converts to a plain ISO day, and so does a day.** A `[u-ca=…]` annotation is
+ * accepted wherever the other 68 exports accept it, and then dropped from the
+ * result. Those exports carry it, because the caller asked for that numbering;
+ * day() exists to hand back the canonical form. It cannot do both, because an
+ * `Instant` has no fields for a calendar to renumber, so an annotation on
+ * `'…T20:00:00Z[u-ca=buddhist]'` is inert and that path has nothing to carry.
+ * Carrying only on the `[Zone]` path would make the same annotation behave two
+ * ways in one function.
+ *
+ * `'11/12/2026'` is refused. Nobody can tell November from December in it.
+ * `'2026-08-08T12:00'` is refused too: no offset and no zone, so daymath would
+ * have to pick one, and it will not pick on the caller's behalf. Name the zone
+ * — `'2026-08-08T12:00[America/New_York]'` — and it is accepted.
+ *
+ * A lone string takes one of four roles, decided in this order: a day, then a
+ * zoned time, then an instant, then a zone. The zone test is by **shape**, and
+ * the shape is on `ZONE_LIKE`. Temporal's own zone grammar cannot decide the role, because it
+ * accepts a whole timestamp and reads the zone out of it, so
+ * `day('1999-01-01T00:00:00Z')` would answer today. The grammar also differs
+ * between implementations: `'2026-08-08T25:00:00Z'` and `'T12:00:00Z'` are both
+ * zones to native Temporal and neither is one to `temporal-polyfill`. Shape
+ * settles the role and the runtime split together.
+ *
+ * With `day()` this is the only export that reads a clock, so the only one
+ * whose answer depends on when you call it. Give it a moment and it becomes a
+ * pure function, which is how the cross-runtime battery covers it.
+ *
+ * @param {Date | number | DayInput | null} [moment] instant, epoch ms, day, or a zone
+ * @param {string} [tz] IANA time zone id, e.g. `'utc'`, `'Asia/Tokyo'`
+ * @returns {string} a plain ISO day. `YYYY-MM-DD`, or expanded `±YYYYYY-MM-DD` outside years
+ *   0000-9999 — the annotation said `YYYY-MM-DD` alone, which was already wrong for
+ *   `day('+010000-01-01')`. **Never carries `[u-ca=…]`.** day() is the normaliser, so a calendar
+ *   annotation is accepted on input and dropped from the result. Every other export carries it.
+ * @throws {TypeError} If `moment` is not one of the accepted shapes
+ * @throws {RangeError} On an Invalid Date, a non-finite number, or an unknown zone
+ * @example day()                              // '2026-08-08'  now, UTC
+ * @example day('Asia/Tokyo')                  // '2026-08-09'  today in Tokyo
+ * @example day(row.createdAt)                 // '2026-08-07'  a Date, UTC
+ * @example day(row.createdAt, 'America/New_York') // '2026-08-06'
+ * @example day(1761616161771)                 // '2025-10-28'  epoch ms
+ * @example day('1999-01-01T00:00:00Z')        // '1999-01-01'  an ISO timestamp
+ * @example day(zdt.toString())                // the zone in the string wins
+ * @example addDays(day(), 2)                  // '2026-08-10'
+ */
+export function day(moment, tz) {
+  // Already a day, in every accepted spelling. `bareDay` is the same predicate
+  // toPlainDate uses, so day() cannot drift from the other 68 exports.
+  const isDay =
+    isPlainDate(moment) || (typeof moment === 'string' && bareDay(moment) !== null)
+  const isMoment = isDay || moment instanceof Date || typeof moment === 'number'
+
+  let zone = tz
+  /** @type {import('temporal-polyfill').Temporal.Instant | undefined} */
+  let instant
+  /** @type {import('temporal-polyfill').Temporal.ZonedDateTime | undefined} */
+  let zoned
+  if (!isMoment && moment !== undefined && moment !== null) {
+    if (typeof moment !== 'string') {
+      throw new TypeError(
+        'daymath: day() takes a Date, epoch milliseconds, or an ISO 8601 day',
+      )
+    }
+    // A `[Zone]` annotation makes the string a ZonedDateTime, and Temporal will
+    // not build one without it: a bare offset is refused. So the bracket is the
+    // caller naming a zone, and the string carries its own civil day. Reading
+    // the instant instead and applying UTC would move a browser's date by one.
+    //
+    // Naming a zone and resolving as one are different questions, so the
+    // annotation is detected first. A string can name a zone and still fail:
+    // `'…-05:00[America/New_York]'` has an offset the zone contradicts, and
+    // `'…[Asia/Tokoy]'` is a typo. Falling back to the instant would answer a
+    // UTC day for both, silently, which is the defect this branch exists to fix.
+    if (hasZoneAnnotation(moment)) {
+      // A calendar is judged only where it is applied. With a zone bracket it is: the fields get
+      // renumbered, and `toPlainDate()` carries the annotation into daymath's own output. Judged
+      // on the string, before the parse, so the message cannot depend on the runtime. A calendar
+      // that only relabels the year passes here, exactly as it does through toPlainDate.
+      supportedCalendar(moment, 'date')
+      if (tz !== undefined && tz !== null) {
+        throw new TypeError(
+          `daymath: day() got two time zones, ${JSON.stringify(moment)} and ${JSON.stringify(tz)}`,
+        )
+      }
+      try {
+        zoned = Temporal.ZonedDateTime.from(moment)
+      } catch (err) {
+        throw new RangeError(
+          `daymath: day() could not read ${JSON.stringify(moment)} in the time zone it names`,
+          { cause: err },
+        )
+      }
+    } else {
+      try {
+        // A timestamp carrying `Z` or an offset names an exact instant, so it
+        // reads as a moment. Temporal's own grammar is the definition of that.
+        //
+        // A calendar annotation here is inert and is ignored. An Instant has no
+        // year, month or day for a calendar to renumber, and without a zone
+        // bracket Temporal will not build anything that does. Refusing it would
+        // reject a right answer for a reason that cannot apply.
+        instant = Temporal.Instant.from(moment)
+      } catch {
+        // Not a moment, so the string must be a zone — decided by shape, before
+        // Temporal sees it. Temporal's zone grammar also accepts a whole
+        // timestamp and pulls the zone out of it, so letting it decide the role
+        // would read a date as a zone and silently answer today.
+        if (!ZONE_LIKE.test(moment)) {
+          throw new RangeError(
+            `daymath: day() got ${JSON.stringify(moment)}, which is neither a moment nor a time zone`,
+          )
+        }
+        if (tz !== undefined && tz !== null) {
+          throw new TypeError(
+            `daymath: day() got two time zones, ${JSON.stringify(moment)} and ${JSON.stringify(tz)}`,
+          )
+        }
+        zone = moment
+      }
+    }
+  }
+  zone ??= 'utc'
+
+  if (moment instanceof Date && Number.isNaN(moment.getTime())) {
+    throw new RangeError('daymath: day() got an Invalid Date')
+  }
+  if (typeof moment === 'number' && !Number.isFinite(moment)) {
+    throw new RangeError(`daymath: day() got a non-finite time value ${moment}`)
+  }
+
+  // Shape first, because implementations disagree past this point. The reasons
+  // are on ZONE_LIKE. The typeof test comes first because `.test()` coerces,
+  // and a caller-supplied toString could throw an error that is not ours.
+  if (typeof zone !== 'string' || !ZONE_LIKE.test(zone)) {
+    throw new RangeError(
+      `daymath: day() got an unknown time zone ${JSON.stringify(zone)}`,
+    )
+  }
+
+  // Checked before anything returns, so a mistyped zone fails the same way
+  // whatever the moment is. A caller mapping rows that are sometimes a Date and
+  // sometimes a day string would otherwise see the typo only on some rows.
+  //
+  // `ZonedDateTime.from` accepts exactly what `Temporal.Now` accepts and reads
+  // no clock, so a day input stays a pure function.
+  try {
+    Temporal.ZonedDateTime.from({ timeZone: zone, year: 1970, month: 1, day: 1 })
+  } catch (err) {
+    throw new RangeError(
+      `daymath: day() got an unknown time zone ${JSON.stringify(zone)}`,
+      { cause: err },
+    )
+  }
+
+  // A day carries no time, so a zone has nothing to shift. Applying one would
+  // invent a moment the caller never gave.
+  //
+  // `isoOf` is what makes day() the normaliser. Every other export carries a
+  // `[u-ca=…]` annotation through, because the caller asked for that numbering.
+  // day() is the door: something that is not a plain ISO day goes in, and a
+  // plain ISO day comes out. Carrying it here also could not be made
+  // consistent, because an `Instant` has no fields for a calendar to renumber,
+  // so that path has nothing to carry and would answer bare ISO regardless.
+  if (isDay) return toDayString(isoOf(toPlainDate(moment)))
+
+  // The string named its own zone, so that zone decides the day, not the
+  // default. This is the one path where `zone` is deliberately not consulted.
+  //
+  // The result still goes through `toPlainDate`, so the calendar is adjudicated
+  // in one place, and then through `isoOf` for the reason above.
+  if (zoned !== undefined) {
+    const plain = guardRange('day', () => zoned.toPlainDate())
+    return toDayString(isoOf(toPlainDate(plain)))
+  }
+
+  if (instant !== undefined) {
+    return guardRange('day', () =>
+      instant.toZonedDateTimeISO(zone).toPlainDate().toString(),
+    )
+  }
+
+  if (!isMoment) return Temporal.Now.plainDateISO(zone).toString()
+
+  // Truncate, because `new Date(n)` truncates, and the contract here is that a
+  // number reads exactly as it does. Verified equal on positive and negative
+  // fractions. Sub-millisecond precision cannot change a calendar day anyway.
+  // Every other shape returned above, so only a number or a Date reaches here.
+  // The cast says what the control flow already guarantees but tsc cannot see.
+  const epochMs =
+    typeof moment === 'number'
+      ? Math.trunc(moment)
+      : /** @type {Date} */ (moment).getTime()
+  return guardRange('day', () =>
+    Temporal.Instant.fromEpochMilliseconds(epochMs)
+      .toZonedDateTimeISO(zone)
+      .toPlainDate()
+      .toString(),
+  )
+}
+
 // ─── parse / format / valid ────────────────────────────────────────
 
 /**
@@ -454,7 +1035,7 @@ export function startOfWeek(date, options) {
 
 /**
  * How far the day sits past the start of its week.
- * @param {Temporal.PlainDate} d
+ * @param {PlainDate} d
  * @param {WeekOptions} [options]
  * @returns {number}
  */
@@ -489,7 +1070,7 @@ export function endOfWeek(date, options) {
 export function differenceInDays(dateLeft, dateRight) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
-  return left.since(right, { largestUnit: 'day' }).days
+  return isoOf(left).since(isoOf(right), { largestUnit: 'day' }).days
 }
 
 /**
@@ -518,8 +1099,12 @@ export function differenceInWeeks(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInMonths(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
+  // `isoOf` on both, like differenceInDays. Without it this function read TWO coordinate systems
+  // at once: the sign came from `compare`, which ignores the calendar, and the magnitude came from
+  // `differenceInCalendarMonths`, which does not. A mixed pair then measured 6,513 months for a
+  // 29-day gap, and two days 543 ISO years apart measured 0.
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
   const sign = Temporal.PlainDate.compare(left, right)
   if (sign === 0) return 0
   const diff = Math.abs(differenceInCalendarMonths(left, right))
@@ -541,8 +1126,8 @@ export function differenceInMonths(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarMonths(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
   return (left.year - right.year) * 12 + (left.month - right.month)
 }
 
@@ -557,8 +1142,9 @@ export function differenceInCalendarMonths(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInYears(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
+  // `isoOf` on both: a measurement, so it ignores the year LABEL. See differenceInMonths.
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
   const sign = Temporal.PlainDate.compare(left, right)
   if (sign === 0) return 0
   const diff = Math.abs(left.year - right.year)
@@ -584,7 +1170,12 @@ export function differenceInYears(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarYears(dateLeft, dateRight) {
-  return getYear(dateLeft) - getYear(dateRight)
+  // NOT getYear: that is a field read and honours the label, so a mixed pair subtracted two
+  // different year spaces and answered 0 for days 543 ISO years apart.
+  return (
+    isoOf(toPlainDate(dateLeft, 'dateLeft')).year -
+    isoOf(toPlainDate(dateRight, 'dateRight')).year
+  )
 }
 
 /**
@@ -606,11 +1197,9 @@ export function differenceInQuarters(dateLeft, dateRight) {
  * @returns {number}
  */
 export function differenceInCalendarQuarters(dateLeft, dateRight) {
-  const left = toPlainDate(dateLeft, 'dateLeft')
-  const right = toPlainDate(dateRight, 'dateRight')
-  return (
-    (left.year - right.year) * 4 + (getQuarter(left) - getQuarter(right))
-  )
+  const left = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const right = isoOf(toPlainDate(dateRight, 'dateRight'))
+  return (left.year - right.year) * 4 + (getQuarter(left) - getQuarter(right))
 }
 
 // ─── compare / equal ───────────────────────────────────────────────
@@ -671,10 +1260,15 @@ export function isSameWeek(dateLeft, dateRight, options) {
   const left = toPlainDate(dateLeft, 'dateLeft')
   const right = toPlainDate(dateRight, 'dateRight')
   // own guard, so a week start below the minimum does not say startOfWeek
-  return guardRange('isSameWeek', () =>
-    left.subtract({ days: daysIntoWeek(left, options) }).equals(
-      right.subtract({ days: daysIntoWeek(right, options) }),
-    ),
+  // compare, not equals: Temporal's equals compares the calendar as well as the day, so it
+  // answers false for the same week in two calendars. compare reads the ISO fields alone.
+  return guardRange(
+    'isSameWeek',
+    () =>
+      Temporal.PlainDate.compare(
+        left.subtract({ days: daysIntoWeek(left, options) }),
+        right.subtract({ days: daysIntoWeek(right, options) }),
+      ) === 0,
   )
 }
 
@@ -684,8 +1278,8 @@ export function isSameWeek(dateLeft, dateRight, options) {
  * @returns {boolean}
  */
 export function isSameMonth(dateLeft, dateRight) {
-  const a = toPlainDate(dateLeft, 'dateLeft')
-  const b = toPlainDate(dateRight, 'dateRight')
+  const a = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const b = isoOf(toPlainDate(dateRight, 'dateRight'))
   return a.year === b.year && a.month === b.month
 }
 
@@ -695,7 +1289,12 @@ export function isSameMonth(dateLeft, dateRight) {
  * @returns {boolean}
  */
 export function isSameYear(dateLeft, dateRight) {
-  return getYear(dateLeft) === getYear(dateRight)
+  // NOT getYear, for the same reason as differenceInCalendarYears: two days 543 ISO years apart
+  // both read year 2569 once one of them carries a Buddhist label, and this answered true.
+  return (
+    isoOf(toPlainDate(dateLeft, 'dateLeft')).year ===
+    isoOf(toPlainDate(dateRight, 'dateRight')).year
+  )
 }
 
 /**
@@ -704,8 +1303,8 @@ export function isSameYear(dateLeft, dateRight) {
  * @returns {boolean}
  */
 export function isSameQuarter(dateLeft, dateRight) {
-  const a = toPlainDate(dateLeft, 'dateLeft')
-  const b = toPlainDate(dateRight, 'dateRight')
+  const a = isoOf(toPlainDate(dateLeft, 'dateLeft'))
+  const b = isoOf(toPlainDate(dateRight, 'dateRight'))
   return a.year === b.year && getQuarter(a) === getQuarter(b)
 }
 
@@ -870,12 +1469,18 @@ export function eachYearOfInterval(interval) {
   }
   /** @type {string[]} */
   const out = []
-  let y = start.year
-  // Jan 1 of start's year can sit below the minimum PlainDate
+  // `with` then `add`, never `PlainDate.from({year})`: both keep start's calendar, and the object
+  // form would read `year` as an ISO year, which is 543 years out for a Buddhist day.
+  // Jan 1 of start's year can sit below the minimum PlainDate.
   guardRange('eachYearOfInterval', () => {
-    while (y <= end.year) {
-      out.push(toDayString(Temporal.PlainDate.from({ year: y, month: 1, day: 1 })))
-      y += 1
+    // Compare ISO years, then add. Testing the loop condition AFTER the push is what keeps the
+    // top edge working: Jan 1 of +275760 is valid, and adding a year to it is not.
+    const lastIsoYear = isoOf(end).year
+    let cur = start.with({ month: 1, day: 1 })
+    for (;;) {
+      out.push(toDayString(cur))
+      if (isoOf(cur).year >= lastIsoYear) break
+      cur = cur.add({ years: 1 })
     }
   })
   return out
@@ -894,8 +1499,7 @@ export function isWithinInterval(date, interval) {
     throw new RangeError('daymath: interval start must not be after end')
   }
   return (
-    Temporal.PlainDate.compare(d, start) >= 0 &&
-    Temporal.PlainDate.compare(d, end) <= 0
+    Temporal.PlainDate.compare(d, start) >= 0 && Temporal.PlainDate.compare(d, end) <= 0
   )
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "daymath",
-  "version": "0.3.0",
-  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No time zones.",
+  "version": "0.5.0",
+  "description": "Calendar date math (ISO 8601 day / PlainDate). date-fns-shaped. No Date. No time zones.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -18,21 +18,34 @@
   ],
   "scripts": {
     "test": "node --test test.js",
+    "lint": "oxlint -c oxlint.jsonc",
+    "lint:fix": "oxlint -c oxlint.jsonc --fix",
+    "typecheck": "tsc -p tsconfig.json",
+    "format": "oxfmt -c oxfmt.json index.js index.d.ts test.js scripts examples",
+    "format:check": "oxfmt -c oxfmt.json --check index.js index.d.ts test.js scripts examples",
     "test:coverage": "c8 --include=index.js --check-coverage --lines 100 --functions 100 --branches 100 --reporter=text --reporter=lcov node --test test.js",
     "test:differential": "node scripts/differential.mjs",
     "test:differential:quick": "node scripts/differential.mjs 2020 2030",
+    "test:runtimes": "node scripts/cross-runtime.mjs",
+    "test:runtimes:write": "node scripts/cross-runtime.mjs --write",
+    "test:intl-day": "node scripts/intl-day.mjs",
+    "test:intl-day:sweep": "node scripts/intl-day.mjs --sweep",
+    "size": "node scripts/bundle-size.mjs --run",
+    "size:check": "node scripts/bundle-size.mjs --check",
+    "size:write": "node scripts/bundle-size.mjs --write",
     "prepublishOnly": "npm run test:coverage",
     "publish:github": "node scripts/publish-github-packages.mjs"
   },
   "keywords": [
     "date",
     "calendar",
+    "civil-date",
     "plain-date",
-    "temporal",
-    "date-fns",
     "YYYY-MM-DD",
     "ISO-8601",
-    "PlainDate"
+    "Temporal",
+    "PlainDate",
+    "date-fns"
   ],
   "author": "leemr",
   "license": "MIT",
@@ -49,10 +62,14 @@
     "temporal-polyfill": "^1.0.3"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19.0 <21 || >=22.12.0"
   },
   "devDependencies": {
     "c8": "^12.0.0",
-    "date-fns": "4.4.0"
+    "date-fns": "4.4.0",
+    "esbuild": "0.28.1",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
+    "typescript": "7.0.2"
   }
 }