From 0c0d7e90f534d3bcb275b8b48d795ecfa18a2d7a Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 11:54:53 -0700
Subject: [PATCH 1/6] fix: expose ISO PlainYearMonth values for non-Gregorian
 locales
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

onMonthChange, rootState.viewing, and NavButtonState.target were built
with `PlainYearMonth.from({ year, month, calendar: localeCalendar })`,
feeding ISO year/month numbers in as locale-calendar fields. With the
full @js-temporal/polyfill (and native Temporal) this reinterpreted the
numbers: for locale="th-TH" (Buddhist), viewing ISO June 2026 produced
1483-06-10[u-ca=buddhist] — off by ~543 years. (The mini shim is
ISO-only and silently ignored the field, so the bug only surfaced with a
real calendar implementation.)

These values are now built in ISO. The locale calendar only ever
affected display, which goes through `new Date(...).toLocaleDateString`
independently (MonthYearString) and is unchanged — Thai still renders
"มิถุนายน 2569". Making the exposed values ISO also lets the controlled
`month`/onMonthChange pair round-trip under the identity function.

`calendarForLocale` existed only to feed this buggy pattern and is now
removed (not a public export). month/defaultMonth/onMonthChange docs now
state the ISO contract.

Adds th-TH coverage: onMonthChange and rootState.viewing emit ISO,
NavButtonState.target is ISO, the label still localizes to the Buddhist
era, and a controlled round-trip does not jump centuries.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package/src/month-view-types.ts |   8 +-
 package/src/month-view.test.tsx | 129 ++++++++++++++++++++++++++++++++
 package/src/month-view.tsx      |  17 ++---
 package/src/navigation.tsx      |  16 ++--
 package/src/utils.test.ts       |  13 ----
 package/src/utils.ts            |  10 ---
 6 files changed, 148 insertions(+), 45 deletions(-)

diff --git a/package/src/month-view-types.ts b/package/src/month-view-types.ts
index 25a2543..5954506 100644
--- a/package/src/month-view-types.ts
+++ b/package/src/month-view-types.ts
@@ -33,15 +33,19 @@ export interface MonthViewRootProps {
   overflowBehavior?: MonthOverflowBehavior | undefined;
   /**
    * The controlled visible month. When provided, the component is controlled.
+   *
+   * Interpreted in the ISO calendar (the year/month are read as ISO values).
+   * The `locale` only affects how the month is displayed, so this value
+   * round-trips directly with {@link onMonthChange}.
    */
   month?: Temporal.PlainYearMonth | undefined;
   /**
-   * The initial visible month (uncontrolled).
+   * The initial visible month (uncontrolled). Interpreted in the ISO calendar.
    */
   defaultMonth?: Temporal.PlainYearMonth | undefined;
   /**
    * Called when the visible month changes via navigation or focus movement.
-   * Not called on initial mount.
+   * Not called on initial mount. The argument is an ISO `PlainYearMonth`.
    */
   onMonthChange?: ((month: Temporal.PlainYearMonth) => void) | undefined;
   /** React children. */
diff --git a/package/src/month-view.test.tsx b/package/src/month-view.test.tsx
index 1bdb1ac..1dcabea 100644
--- a/package/src/month-view.test.tsx
+++ b/package/src/month-view.test.tsx
@@ -1504,6 +1504,135 @@ describe("numberOfMonths", () => {
   });
 });
 
+describe("non-Gregorian locale (th-TH)", () => {
+  // th-TH defaults to the Buddhist calendar (ISO year + 543). All
+  // PlainYearMonth values the component exposes must be ISO; the locale
+  // calendar only affects display.
+  const thProps = { ...defaultProps, locale: "th-TH" } as const;
+  const march15 = Temporal.PlainDate.from("2026-03-15");
+
+  /** Captures rootState.viewing from MonthView context. */
+  function ViewingCapture({
+    onCapture,
+  }: {
+    onCapture: (viewing: Temporal.PlainYearMonth) => void;
+  }) {
+    const { rootState } = useMonthViewState();
+    onCapture(rootState.viewing as Temporal.PlainYearMonth);
+    return null;
+  }
+
+  it("onMonthChange emits an ISO PlainYearMonth, not the locale calendar", () => {
+    const onMonthChange = vi.fn();
+    const { container, unmount } = render(
+      <MonthView
+        {...thProps}
+        defaultValue={march15}
+        onMonthChange={onMonthChange}
+      >
+        <NextMonthButton data-testid="next" />
+      </MonthView>,
+    );
+
+    act(() => {
+      container
+        .querySelector('[data-testid="next"]')!
+        .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    expect(onMonthChange).toHaveBeenCalledTimes(1);
+    const arg = onMonthChange.mock.calls[0]![0];
+    // ISO April 2026 — NOT Buddhist-2026 (which is ISO 1483-06).
+    expect(arg.toString()).toBe("2026-04");
+    expect(arg.year).toBe(2026);
+    expect(arg.month).toBe(4);
+
+    unmount();
+  });
+
+  it("rootState.viewing is an ISO PlainYearMonth", () => {
+    let viewing: Temporal.PlainYearMonth | undefined;
+    const { unmount } = render(
+      <MonthView {...thProps} defaultValue={march15}>
+        <ViewingCapture
+          onCapture={(v) => {
+            viewing = v;
+          }}
+        />
+      </MonthView>,
+    );
+
+    expect(viewing!.toString()).toBe("2026-03");
+
+    unmount();
+  });
+
+  it("NavButtonState.target is an ISO PlainYearMonth", () => {
+    let nextTarget: Temporal.PlainYearMonth | undefined;
+    const { unmount } = render(
+      <MonthView {...thProps} defaultValue={march15}>
+        <NextMonthButton
+          render={(props, state) => {
+            nextTarget = state.target;
+            return <button {...props} />;
+          }}
+        />
+      </MonthView>,
+    );
+
+    // Next from ISO March 2026 → ISO April 2026, not Buddhist.
+    expect(nextTarget!.toString()).toBe("2026-04");
+
+    unmount();
+  });
+
+  it("still renders the month label in the locale calendar", () => {
+    const { container, unmount } = render(
+      <MonthView {...thProps} defaultValue={march15}>
+        <MonthYearString data-testid="label" />
+      </MonthView>,
+    );
+
+    // ISO 2026 → Buddhist Era 2569.
+    expect(
+      container.querySelector('[data-testid="label"]')!.textContent,
+    ).toContain("2569");
+
+    unmount();
+  });
+
+  it("controlled round-trips without a century jump", () => {
+    function Harness() {
+      const [month, setMonth] = useState(
+        Temporal.PlainYearMonth.from("2026-03"),
+      );
+      return (
+        <MonthView {...thProps} month={month} onMonthChange={setMonth}>
+          <MonthYearString data-testid="label" />
+          <NextMonthButton data-testid="next" />
+        </MonthView>
+      );
+    }
+
+    const { container, unmount } = render(<Harness />);
+    const label = () =>
+      container.querySelector('[data-testid="label"]')!.textContent ?? "";
+    expect(label()).toContain("2569"); // March 2569 BE
+
+    act(() => {
+      container
+        .querySelector('[data-testid="next"]')!
+        .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    // Advanced one month, still Buddhist 2569 — not jumped ~543 years.
+    expect(label()).toContain("2569");
+    expect(label()).not.toContain("3112");
+
+    unmount();
+  });
+});
+
 describe("outsideDays", () => {
   const march15 = Temporal.PlainDate.from("2026-03-15");
 
diff --git a/package/src/month-view.tsx b/package/src/month-view.tsx
index 7fe7f7f..9476d9c 100644
--- a/package/src/month-view.tsx
+++ b/package/src/month-view.tsx
@@ -14,7 +14,6 @@ import type {
 } from "./month-view-types";
 import type { MonthData, RootState, ValueFormat } from "./types";
 import {
-  calendarForLocale,
   computeAdjacentMonth,
   focusedDateForMonth,
   getMonthWeeks,
@@ -105,21 +104,21 @@ function MonthViewRoot(props: MonthViewRootProps) {
     [],
   );
 
-  const localeCalendar = useMemo(() => calendarForLocale(locale), [locale]);
-
   // Always-current ref so callbacks/effects don't re-subscribe on every
   // onMonthChange identity change.
   const onMonthChangeRef = useRef(onMonthChange);
   onMonthChangeRef.current = onMonthChange;
 
   // Request the parent move the view to `{year, month}` (controlled mode).
+  // Built in ISO — `year`/`month` are ISO numbers, and the locale calendar
+  // only affects display (see MonthYearString). Passing `calendar` here would
+  // reinterpret the ISO numbers as locale-calendar fields (e.g. Buddhist),
+  // shifting the value by centuries.
   const notifyMonth = useCallback(
     (year: number, month: number) => {
-      onMonthChangeRef.current?.(
-        T.PlainYearMonth.from({ year, month, calendar: localeCalendar }),
-      );
+      onMonthChangeRef.current?.(T.PlainYearMonth.from({ year, month }));
     },
-    [T, localeCalendar],
+    [T],
   );
 
   // Whether `{year, month}` falls within the currently displayed window.
@@ -343,14 +342,14 @@ function MonthViewRoot(props: MonthViewRootProps) {
   );
 
   // --- viewingYearMonth (for the render-prop rootState) ---
+  // ISO — the locale calendar only affects display, not this value.
   const viewingYearMonth = useMemo(
     () =>
       T.PlainYearMonth.from({
         year: currentMonth.year,
         month: currentMonth.month,
-        calendar: localeCalendar,
       }),
-    [currentMonth, T, localeCalendar],
+    [currentMonth, T],
   );
 
   // --- Fire onMonthChange when uncontrolled navigation moves the view (not on
diff --git a/package/src/navigation.tsx b/package/src/navigation.tsx
index bcf3ad9..0fea075 100644
--- a/package/src/navigation.tsx
+++ b/package/src/navigation.tsx
@@ -16,7 +16,7 @@ import type {
   NextMonthButtonProps,
   NavButtonState,
 } from "./types";
-import { selectedToZdt, zdtToNativeDate, calendarForLocale } from "./utils";
+import { selectedToZdt, zdtToNativeDate } from "./utils";
 
 const dateStringStateAttributesMapping = {
   root: () => null,
@@ -246,7 +246,6 @@ function useNavButton<F extends ValueFormat = ValueFormat>(
     disabled: globalDisabled,
     minValue,
     maxValue,
-    locale,
     temporal: T,
   } = useCalendarStable();
   const monthViewStable = useMonthViewStable();
@@ -304,16 +303,11 @@ function useNavButton<F extends ValueFormat = ValueFormat>(
     );
   }, [globalDisabled, destYear, destMonth, boundValue, direction]);
 
-  const localeCalendar = useMemo(() => calendarForLocale(locale), [locale]);
-
+  // ISO — `destYear`/`destMonth` are ISO numbers; the locale calendar only
+  // affects display, so it must not be injected into this value.
   const target = useMemo(
-    () =>
-      T.PlainYearMonth.from({
-        year: destYear,
-        month: destMonth,
-        calendar: localeCalendar,
-      }),
-    [destYear, destMonth, T, localeCalendar],
+    () => T.PlainYearMonth.from({ year: destYear, month: destMonth }),
+    [destYear, destMonth, T],
   );
 
   const state = useMemo<NavButtonState<F>>(
diff --git a/package/src/utils.test.ts b/package/src/utils.test.ts
index 3949366..4070019 100644
--- a/package/src/utils.test.ts
+++ b/package/src/utils.test.ts
@@ -3,7 +3,6 @@ import { describe, it, expect } from "vitest";
 import { temporalVariants } from "./test-temporal";
 import type { TemporalNamespace } from "./types";
 import {
-  calendarForLocale,
   resolveTemporal,
   getSystemTimeZone,
   toZonedDateTime,
@@ -32,18 +31,6 @@ const T: TemporalNamespace = {
   PlainYearMonth: Temporal.PlainYearMonth,
 };
 
-describe("calendarForLocale", () => {
-  it("returns 'gregory' for en-US", () => {
-    expect(calendarForLocale("en-US")).toBe("gregory");
-  });
-
-  it("returns a calendar string for an empty locale (runtime default)", () => {
-    const result = calendarForLocale("");
-    expect(typeof result).toBe("string");
-    expect(result.length).toBeGreaterThan(0);
-  });
-});
-
 describe("resolveTemporal", () => {
   it("returns the provided namespace when given", () => {
     expect(resolveTemporal(T)).toBe(T);
diff --git a/package/src/utils.ts b/package/src/utils.ts
index fd5af91..186b9dc 100644
--- a/package/src/utils.ts
+++ b/package/src/utils.ts
@@ -6,16 +6,6 @@ import type {
   WeekStartDay,
 } from "./types";
 
-/**
- * Returns the default calendar system for a given locale (e.g. `"gregory"` for `"en-US"`).
- *
- * @param locale - A BCP 47 locale string. Falls back to the runtime default when empty.
- */
-export function calendarForLocale(locale: string): string {
-  return new Intl.DateTimeFormat(locale || undefined).resolvedOptions()
-    .calendar;
-}
-
 /**
  * Resolves a {@link TemporalNamespace} instance.
  *

From 88b33b0dd8ca83a4d339a493abbf3d4752858257 Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:13:10 -0700
Subject: [PATCH 2/6] refactor: format the month label through Temporal, not
 native Date
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MonthYearString built `new Date(year, month-1, 1).toLocaleDateString(...)`
in component code. Format through the injected Temporal instead, so the
only native `Date` on this display path lives inside the polyfill — the
bundled shim's `PlainDate.toLocaleString` (Gregorian-only) or the full
polyfill.

Uses `PlainDate.toLocaleString`, NOT `PlainYearMonth.toLocaleString`:
verified the latter throws on any iso8601-vs-locale calendar mismatch
("cannot format PlainYearMonth with calendar iso8601 in locale with
calendar gregory") — even for en-US. An iso8601 `PlainDate` is the
documented compatibility exception and adopts the locale's calendar, so
th-TH still renders the Buddhist era (2569). The mini shim's existing
`MiniPlainDate.toLocaleString` already localizes through Intl; no new
shim method was added (a non-throwing `MiniPlainYearMonth.toLocaleString`
would diverge from real Temporal, which throws).

Documents the shim as ISO/Gregorian-only (module doc + the public
`Temporal` export): display localizes via Intl, but calendar math is
Gregorian; use @js-temporal/polyfill or native Temporal for other
calendars.

Tests: MiniPlainDate.toLocaleString (en-US, th-TH Buddhist, no day leak,
custom options) and a MonthYearString th-TH label rendered with the
bundled shim.

Note: DateString/TimeString (selected ZonedDateTime + timezone) and the
locale-prop-driven MonthSeparator still format via native Date; those are
a separate, larger surface left for a follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package/src/index.ts                  |  8 +++++++
 package/src/month-view.test.tsx       | 21 +++++++++++++++++++
 package/src/navigation.tsx            | 16 ++++++++------
 package/src/temporal-polyfill.test.ts | 30 +++++++++++++++++++++++++++
 package/src/temporal-polyfill.ts      | 14 +++++++++++++
 5 files changed, 83 insertions(+), 6 deletions(-)

diff --git a/package/src/index.ts b/package/src/index.ts
index a616154..ff65c90 100644
--- a/package/src/index.ts
+++ b/package/src/index.ts
@@ -36,6 +36,14 @@ export {
 export { computePreviewRange } from "./root-selection";
 export { computeWeeksInWindow } from "./compute-weeks-in-window";
 export { resolveFirstWeek, resolveFirstWeekSpec } from "./resolve-first-week";
+/**
+ * A bundled, dependency-free `Temporal` implementation — **ISO 8601 /
+ * Gregorian only**. Use it when you don't need non-Gregorian calendar math.
+ * `toLocaleString` still localizes display via `Intl` (so e.g. `th-TH` renders
+ * the Buddhist era), but all date arithmetic and field values are Gregorian.
+ * For non-Gregorian calendars, install `@js-temporal/polyfill` (or use native
+ * `Temporal`) and pass it via the `temporal` prop instead.
+ */
 export { Temporal } from "./temporal-polyfill";
 export { useCalendarStable, useCalendarState } from "./calendar-context";
 export { useMonthViewStable, useMonthViewState } from "./month-view-context";
diff --git a/package/src/month-view.test.tsx b/package/src/month-view.test.tsx
index 1dcabea..a38c3c2 100644
--- a/package/src/month-view.test.tsx
+++ b/package/src/month-view.test.tsx
@@ -12,6 +12,7 @@ import {
   PrevMonthButton,
   NextMonthButton,
 } from "./navigation";
+import { Temporal as MiniTemporal } from "./temporal-polyfill";
 import type { DateRange, ValueChangeMeta, MonthData } from "./types";
 import { useViewContext } from "./view-context";
 
@@ -1601,6 +1602,26 @@ describe("non-Gregorian locale (th-TH)", () => {
     unmount();
   });
 
+  it("renders the locale-calendar label with the bundled shim", () => {
+    // The label path now formats via PlainDate.toLocaleString, so the
+    // Gregorian-only mini shim must still localize display through Intl.
+    const { container, unmount } = render(
+      <MonthView
+        {...thProps}
+        temporal={MiniTemporal}
+        defaultValue={MiniTemporal.PlainDate.from("2026-03-15")}
+      >
+        <MonthYearString data-testid="label" />
+      </MonthView>,
+    );
+
+    expect(
+      container.querySelector('[data-testid="label"]')!.textContent,
+    ).toContain("2569");
+
+    unmount();
+  });
+
   it("controlled round-trips without a century jump", () => {
     function Harness() {
       const [month, setMonth] = useState(
diff --git a/package/src/navigation.tsx b/package/src/navigation.tsx
index 0fea075..2576a22 100644
--- a/package/src/navigation.tsx
+++ b/package/src/navigation.tsx
@@ -166,7 +166,7 @@ function MonthYearStringFn(
     ...otherProps
   } = props;
   const monthIndex = monthIndexProp ?? 0;
-  const { locale } = useCalendarStable();
+  const { locale, temporal: T } = useCalendarStable();
   const monthViewStable = useMonthViewStable();
   const {
     currentMonth: currentDateTime,
@@ -186,15 +186,19 @@ function MonthYearStringFn(
   const displayYear = monthData?.year ?? currentDateTime.year;
   const displayMonth = monthData?.month ?? currentDateTime.month;
 
-  const displayDate = new Date(displayYear, displayMonth - 1, 1);
   const defaultOptions: Intl.DateTimeFormatOptions = options ?? {
     month: "long",
     year: "numeric",
   };
-  const formatted = displayDate.toLocaleDateString(
-    locales ?? locale,
-    defaultOptions,
-  );
+  // Format through Temporal so the only native `Date` lives inside the
+  // polyfill. `displayYear`/`displayMonth` are ISO; formatting an ISO
+  // `PlainDate` (not `PlainYearMonth`, which throws on calendar mismatch)
+  // lets Intl render it in the locale's calendar (e.g. Buddhist for th-TH).
+  const formatted = T.PlainDate.from({
+    year: displayYear,
+    month: displayMonth,
+    day: 1,
+  }).toLocaleString(locales ?? locale, defaultOptions);
 
   const state = useMemo<MonthYearStringState>(
     () => ({
diff --git a/package/src/temporal-polyfill.test.ts b/package/src/temporal-polyfill.test.ts
index e5616d6..c4dfa1a 100644
--- a/package/src/temporal-polyfill.test.ts
+++ b/package/src/temporal-polyfill.test.ts
@@ -177,6 +177,36 @@ describe("PlainDate toString roundtrip", () => {
   });
 });
 
+describe("PlainDate toLocaleString", () => {
+  const june = T.PlainDate.from("2026-06-01");
+
+  it("localizes the Gregorian year and month for en-US", () => {
+    const s = june.toLocaleString("en-US", { year: "numeric", month: "long" });
+    expect(s).toContain("2026");
+    expect(s).toContain("June");
+  });
+
+  it("localizes to the locale's calendar (th-TH → Buddhist era)", () => {
+    const s = june.toLocaleString("th-TH", { year: "numeric", month: "long" });
+    // ISO 2026 → Buddhist Era 2569.
+    expect(s).toContain("2569");
+  });
+
+  it("does not leak a day with year+month options", () => {
+    const s = june.toLocaleString("en-US", { year: "numeric", month: "long" });
+    expect(s).not.toMatch(/\b1\b/);
+  });
+
+  it("honors custom options (numeric month)", () => {
+    const s = june.toLocaleString("en-US", {
+      year: "numeric",
+      month: "2-digit",
+    });
+    expect(s).toContain("06");
+    expect(s).toContain("2026");
+  });
+});
+
 describe("PlainDate equals", () => {
   it("returns true for same date", () => {
     expect(date("2026-03-15").equals(date("2026-03-15"))).toBe(true);
diff --git a/package/src/temporal-polyfill.ts b/package/src/temporal-polyfill.ts
index a9fc18c..66acf42 100644
--- a/package/src/temporal-polyfill.ts
+++ b/package/src/temporal-polyfill.ts
@@ -1,3 +1,17 @@
+/**
+ * Minimal, dependency-free `Temporal` shim — **ISO 8601 / Gregorian only**.
+ *
+ * It implements just enough of the `Temporal` surface for the calendar to
+ * operate (`PlainDate`, `PlainDateTime`, `PlainMonthDay`, `PlainYearMonth`,
+ * `Now`) using Gregorian date arithmetic. `toLocaleString` formats via the
+ * host `Intl`, so display still localizes to the locale's calendar (e.g.
+ * Buddhist for `th-TH`), but the shim performs **no non-Gregorian calendar
+ * math** — all field values and arithmetic are Gregorian.
+ *
+ * To use non-Gregorian calendars (Buddhist, Hebrew, Islamic, etc.) for
+ * computation, install `@js-temporal/polyfill` or run where native `Temporal`
+ * is available, and pass it via the `temporal` prop.
+ */
 import type { TemporalNamespace } from "./types";
 
 // ---------------------------------------------------------------------------

From b3f1c1bb75e6f731548bae147f593d94108067db Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:16:06 -0700
Subject: [PATCH 3/6] docs: clarify the bundled Temporal shim's intended use
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Frame it as the internal Gregorian-only date engine for callers who use
non-Temporal value formats (Date/object/string) on hosts without native
Temporal and don't want the @js-temporal/polyfill dependency — not as a
"Gregorian Temporal" picked for calendar reasons. It is never
auto-selected; resolveTemporal uses what you pass, else native Temporal,
else throws.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package/src/index.ts             | 17 +++++++++++------
 package/src/temporal-polyfill.ts | 27 +++++++++++++++++----------
 2 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/package/src/index.ts b/package/src/index.ts
index ff65c90..1a35c69 100644
--- a/package/src/index.ts
+++ b/package/src/index.ts
@@ -37,12 +37,17 @@ export { computePreviewRange } from "./root-selection";
 export { computeWeeksInWindow } from "./compute-weeks-in-window";
 export { resolveFirstWeek, resolveFirstWeekSpec } from "./resolve-first-week";
 /**
- * A bundled, dependency-free `Temporal` implementation — **ISO 8601 /
- * Gregorian only**. Use it when you don't need non-Gregorian calendar math.
- * `toLocaleString` still localizes display via `Intl` (so e.g. `th-TH` renders
- * the Buddhist era), but all date arithmetic and field values are Gregorian.
- * For non-Gregorian calendars, install `@js-temporal/polyfill` (or use native
- * `Temporal`) and pass it via the `temporal` prop instead.
+ * A bundled, dependency-free `Temporal` engine for environments without native
+ * `Temporal`. Intended for when you drive the calendar with non-`Temporal`
+ * value formats (`Date`, `object`, ISO string, …) and don't want to add
+ * `@js-temporal/polyfill` — pass it via the `temporal` prop to give the
+ * calendar a date engine.
+ *
+ * **ISO 8601 / Gregorian only.** `toLocaleString` localizes display via `Intl`
+ * (so e.g. `th-TH` renders the Buddhist era), but all date arithmetic and
+ * field values are Gregorian. If you work with `Temporal` objects directly or
+ * need non-Gregorian calendar math, provide native `Temporal` or
+ * `@js-temporal/polyfill` via the `temporal` prop instead.
  */
 export { Temporal } from "./temporal-polyfill";
 export { useCalendarStable, useCalendarState } from "./calendar-context";
diff --git a/package/src/temporal-polyfill.ts b/package/src/temporal-polyfill.ts
index 66acf42..41dbf3a 100644
--- a/package/src/temporal-polyfill.ts
+++ b/package/src/temporal-polyfill.ts
@@ -1,16 +1,23 @@
 /**
- * Minimal, dependency-free `Temporal` shim — **ISO 8601 / Gregorian only**.
+ * Minimal, dependency-free `Temporal` engine for the calendar's **internal**
+ * date math — used only when the host lacks native `Temporal` and the caller
+ * drives the calendar with non-`Temporal` value formats (`Date`, `object`,
+ * ISO string, …) rather than `Temporal` objects. It is the date engine you
+ * reach for to avoid adding the `@js-temporal/polyfill` dependency; pass it
+ * via the `temporal` prop. It is not auto-selected — {@link resolveTemporal}
+ * uses what you provide, else native `globalThis.Temporal`, else throws.
  *
- * It implements just enough of the `Temporal` surface for the calendar to
- * operate (`PlainDate`, `PlainDateTime`, `PlainMonthDay`, `PlainYearMonth`,
- * `Now`) using Gregorian date arithmetic. `toLocaleString` formats via the
- * host `Intl`, so display still localizes to the locale's calendar (e.g.
- * Buddhist for `th-TH`), but the shim performs **no non-Gregorian calendar
- * math** — all field values and arithmetic are Gregorian.
+ * **ISO 8601 / Gregorian only.** It implements just enough of the `Temporal`
+ * surface for the calendar to operate (`PlainDate`, `PlainDateTime`,
+ * `PlainMonthDay`, `PlainYearMonth`, `Now`) using Gregorian arithmetic.
+ * `toLocaleString` formats via the host `Intl`, so display still localizes to
+ * the locale's calendar (e.g. Buddhist for `th-TH`), but the shim performs
+ * **no non-Gregorian calendar math** — all field values and arithmetic are
+ * Gregorian.
  *
- * To use non-Gregorian calendars (Buddhist, Hebrew, Islamic, etc.) for
- * computation, install `@js-temporal/polyfill` or run where native `Temporal`
- * is available, and pass it via the `temporal` prop.
+ * If you work with `Temporal` objects directly, or need non-Gregorian calendar
+ * math (Buddhist, Hebrew, Islamic, …), provide native `Temporal` or
+ * `@js-temporal/polyfill` via the `temporal` prop instead.
  */
 import type { TemporalNamespace } from "./types";
 

From 1c4a6aaec1d8dbe34d1a4b3d5773ec5f7dc5cd89 Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:23:26 -0700
Subject: [PATCH 4/6] feat: auto-select the bundled shim for non-Temporal
 formats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

resolveTemporal now falls back to the bundled Gregorian shim when no
Temporal is provided and none is native — but only for non-Temporal value
formats (`object`, `Date`), whose values never expose Temporal objects to
the caller. So a `format="Date"` consumer on a host without native
Temporal works with no `temporal` prop and no `@js-temporal/polyfill`.

Temporal value formats (PlainDate, PlainYearMonth, …) still throw when no
real Temporal is available: the caller wants real Temporal objects and
the shim is not one, so silently substituting it would be wrong. The
calendar passes the resolved `format` into resolveTemporal for this
decision.

Updates the shim docs (module + public export) to describe the
auto-selection. resolveTemporal is not a public export, so the new
optional `format` param is non-breaking.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package/src/calendar-provider.tsx |  7 +++++--
 package/src/index.ts              | 11 +++++------
 package/src/temporal-polyfill.ts  | 13 ++++++------
 package/src/utils.test.ts         | 33 +++++++++++++++++++++++++++++++
 package/src/utils.ts              | 17 ++++++++++++++--
 5 files changed, 65 insertions(+), 16 deletions(-)

diff --git a/package/src/calendar-provider.tsx b/package/src/calendar-provider.tsx
index f12641f..24c8b21 100644
--- a/package/src/calendar-provider.tsx
+++ b/package/src/calendar-provider.tsx
@@ -50,11 +50,14 @@ function CalendarProvider<F extends ValueFormat = "PlainDate">(
   } = props;
 
   // --- Resolve defaults ---
-  const T = resolveTemporal(temporalProp);
+  const resolvedFormat = (formatProp ?? "PlainDate") as F;
+  // Falls back to the bundled Gregorian shim for non-Temporal formats when no
+  // Temporal is available, so callers using `Date`/`object` values don't need
+  // a polyfill.
+  const T = resolveTemporal(temporalProp, resolvedFormat);
   const locale = localeProp ?? "en-US";
   const timeZone = timeZoneProp ?? getSystemTimeZone(T);
   const weekStartDay = weekStartDayProp ?? 0;
-  const resolvedFormat = (formatProp ?? "PlainDate") as F;
   const selectionMode = selectionModeProp ?? "single";
   const disabled = disabledProp ?? false;
   const readOnly = readOnlyProp ?? false;
diff --git a/package/src/index.ts b/package/src/index.ts
index 1a35c69..2d51596 100644
--- a/package/src/index.ts
+++ b/package/src/index.ts
@@ -37,15 +37,14 @@ export { computePreviewRange } from "./root-selection";
 export { computeWeeksInWindow } from "./compute-weeks-in-window";
 export { resolveFirstWeek, resolveFirstWeekSpec } from "./resolve-first-week";
 /**
- * A bundled, dependency-free `Temporal` engine for environments without native
- * `Temporal`. Intended for when you drive the calendar with non-`Temporal`
- * value formats (`Date`, `object`, ISO string, …) and don't want to add
- * `@js-temporal/polyfill` — pass it via the `temporal` prop to give the
- * calendar a date engine.
+ * A bundled, dependency-free `Temporal` engine. When the host has no native
+ * `Temporal` and you use a non-`Temporal` value format (`object`, `Date`), the
+ * calendar selects this automatically — no `@js-temporal/polyfill` needed. You
+ * may also pass it explicitly via the `temporal` prop.
  *
  * **ISO 8601 / Gregorian only.** `toLocaleString` localizes display via `Intl`
  * (so e.g. `th-TH` renders the Buddhist era), but all date arithmetic and
- * field values are Gregorian. If you work with `Temporal` objects directly or
+ * field values are Gregorian. If you work with `Temporal` value formats or
  * need non-Gregorian calendar math, provide native `Temporal` or
  * `@js-temporal/polyfill` via the `temporal` prop instead.
  */
diff --git a/package/src/temporal-polyfill.ts b/package/src/temporal-polyfill.ts
index 41dbf3a..3296f98 100644
--- a/package/src/temporal-polyfill.ts
+++ b/package/src/temporal-polyfill.ts
@@ -1,11 +1,12 @@
 /**
  * Minimal, dependency-free `Temporal` engine for the calendar's **internal**
- * date math — used only when the host lacks native `Temporal` and the caller
- * drives the calendar with non-`Temporal` value formats (`Date`, `object`,
- * ISO string, …) rather than `Temporal` objects. It is the date engine you
- * reach for to avoid adding the `@js-temporal/polyfill` dependency; pass it
- * via the `temporal` prop. It is not auto-selected — {@link resolveTemporal}
- * uses what you provide, else native `globalThis.Temporal`, else throws.
+ * date math. {@link resolveTemporal} selects it automatically — with no
+ * `@js-temporal/polyfill` dependency — when the host lacks native `Temporal`
+ * and the caller drives the calendar with a non-`Temporal` value format
+ * (`object`, `Date`), since those values never expose `Temporal` objects. It
+ * can also be passed explicitly via the `temporal` prop. For a `Temporal`
+ * value format with no native/provided `Temporal`, resolution throws rather
+ * than substitute the shim (the caller wants real `Temporal` objects).
  *
  * **ISO 8601 / Gregorian only.** It implements just enough of the `Temporal`
  * surface for the calendar to operate (`PlainDate`, `PlainDateTime`,
diff --git a/package/src/utils.test.ts b/package/src/utils.test.ts
index 4070019..46599c5 100644
--- a/package/src/utils.test.ts
+++ b/package/src/utils.test.ts
@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { describe, it, expect } from "vitest";
+import { Temporal as bundledTemporal } from "./temporal-polyfill";
 import { temporalVariants } from "./test-temporal";
 import type { TemporalNamespace } from "./types";
 import {
@@ -45,6 +46,38 @@ describe("resolveTemporal", () => {
       if (orig) (globalThis as any).Temporal = orig;
     }
   });
+
+  it.each<{ description: string; format: "object" | "Date" }>([
+    { description: "object", format: "object" },
+    { description: "Date", format: "Date" },
+  ])(
+    "falls back to the bundled shim for the $description format when no Temporal is available",
+    ({ format }) => {
+      const orig = (globalThis as any).Temporal;
+      delete (globalThis as any).Temporal;
+      try {
+        expect(resolveTemporal(undefined, format)).toBe(bundledTemporal);
+      } finally {
+        if (orig) (globalThis as any).Temporal = orig;
+      }
+    },
+  );
+
+  it("throws for a Temporal format when no Temporal is available", () => {
+    const orig = (globalThis as any).Temporal;
+    delete (globalThis as any).Temporal;
+    try {
+      expect(() => resolveTemporal(undefined, "PlainDate")).toThrow(
+        "Temporal is not available",
+      );
+    } finally {
+      if (orig) (globalThis as any).Temporal = orig;
+    }
+  });
+
+  it("prefers an explicitly provided namespace over the shim fallback", () => {
+    expect(resolveTemporal(T, "object")).toBe(T);
+  });
 });
 
 describe.each(temporalVariants)("getSystemTimeZone ($name)", ({ T }) => {
diff --git a/package/src/utils.ts b/package/src/utils.ts
index 186b9dc..8715690 100644
--- a/package/src/utils.ts
+++ b/package/src/utils.ts
@@ -1,4 +1,5 @@
 import type { Temporal } from "@js-temporal/polyfill";
+import { Temporal as bundledTemporal } from "./temporal-polyfill";
 import type {
   TemporalNamespace,
   DateValueObject,
@@ -6,21 +7,33 @@ import type {
   WeekStartDay,
 } from "./types";
 
+/** Value formats whose values are plain (non-`Temporal`) objects. */
+const NON_TEMPORAL_FORMATS = new Set<ValueFormat>(["object", "Date"]);
+
 /**
  * Resolves a {@link TemporalNamespace} instance.
  *
- * Returns `provided` when given, otherwise checks `globalThis.Temporal`.
- * Throws if neither is available.
+ * Resolution order: an explicitly `provided` namespace, then native
+ * `globalThis.Temporal`. If neither exists, the behavior depends on `format`:
+ * non-`Temporal` formats (`object`, `Date`) don't expose `Temporal` objects to
+ * the caller, so the bundled Gregorian-only shim is used as the internal date
+ * engine. `Temporal` formats imply the caller wants real `Temporal` objects —
+ * the shim is not one, so resolution throws instead of silently substituting.
  *
  * @param provided - An explicit Temporal polyfill or namespace.
+ * @param format - The active value format (decides the no-Temporal fallback).
  */
 export function resolveTemporal(
   provided?: TemporalNamespace,
+  format?: ValueFormat,
 ): TemporalNamespace {
   if (provided) return provided;
   if (typeof globalThis !== "undefined" && (globalThis as any).Temporal) {
     return (globalThis as any).Temporal;
   }
+  if (format !== undefined && NON_TEMPORAL_FORMATS.has(format)) {
+    return bundledTemporal;
+  }
   throw new Error(
     "DatePicker: Temporal is not available. Pass a Temporal polyfill via the `temporal` prop, or use a browser that supports the Temporal API natively.",
   );

From 224d087b9f5bd787d5ddb7bcf40a1bc5c2dc1842 Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:39:25 -0700
Subject: [PATCH 5/6] feat!: remove the bundled Temporal shim; require a
 user-provided Temporal

BREAKING CHANGE: the library no longer bundles a `Temporal` implementation.
Provide one via the `temporal` prop (or run where native `Temporal`
exists). Two recommended polyfills:
  - temporal-polyfill        https://github.com/fullcalendar/temporal-polyfill
  - @js-temporal/polyfill    https://github.com/js-temporal/temporal-polyfill

The `Temporal` value export is removed from the package barrel and from
every `@klinking/colander/*` format subpath. resolveTemporal reverts to
provided -> native -> throw (no shim fallback); the error message points
to the two polyfills. The `temporal` prop docs document them.

Drops the temporal-polyfill module + test, the "mini polyfill" entry in
the test matrix, and the shim-specific tests. The month label still
formats through the provided Temporal (PlainDate.toLocaleString), which
both recommended polyfills implement.

Removing the shim also drops the ~148KB Gregorian engine from the bundle.

Follow-up tracked in #16: run the whole suite against both polyfills.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package/src/calendar-provider.tsx       |   7 +-
 package/src/calendar-types.ts           |   4 +-
 package/src/formats/date.ts             |   2 -
 package/src/formats/object.ts           |   2 -
 package/src/formats/plain-date-time.ts  |   2 -
 package/src/formats/plain-date.ts       |   2 -
 package/src/formats/plain-month-day.ts  |   2 -
 package/src/formats/plain-year-month.ts |   2 -
 package/src/formats/zoned-date-time.ts  |   2 -
 package/src/index.ts                    |  13 -
 package/src/month-view.test.tsx         |  21 -
 package/src/temporal-polyfill.test.ts   | 363 -------------
 package/src/temporal-polyfill.ts        | 649 ------------------------
 package/src/test-temporal.ts            |   2 -
 package/src/types.ts                    |  13 +-
 package/src/utils.test.ts               |  33 --
 package/src/utils.ts                    |  23 +-
 17 files changed, 22 insertions(+), 1120 deletions(-)
 delete mode 100644 package/src/temporal-polyfill.test.ts
 delete mode 100644 package/src/temporal-polyfill.ts

diff --git a/package/src/calendar-provider.tsx b/package/src/calendar-provider.tsx
index 24c8b21..f12641f 100644
--- a/package/src/calendar-provider.tsx
+++ b/package/src/calendar-provider.tsx
@@ -50,14 +50,11 @@ function CalendarProvider<F extends ValueFormat = "PlainDate">(
   } = props;
 
   // --- Resolve defaults ---
-  const resolvedFormat = (formatProp ?? "PlainDate") as F;
-  // Falls back to the bundled Gregorian shim for non-Temporal formats when no
-  // Temporal is available, so callers using `Date`/`object` values don't need
-  // a polyfill.
-  const T = resolveTemporal(temporalProp, resolvedFormat);
+  const T = resolveTemporal(temporalProp);
   const locale = localeProp ?? "en-US";
   const timeZone = timeZoneProp ?? getSystemTimeZone(T);
   const weekStartDay = weekStartDayProp ?? 0;
+  const resolvedFormat = (formatProp ?? "PlainDate") as F;
   const selectionMode = selectionModeProp ?? "single";
   const disabled = disabledProp ?? false;
   const readOnly = readOnlyProp ?? false;
diff --git a/package/src/calendar-types.ts b/package/src/calendar-types.ts
index 2aaf065..3ff8d47 100644
--- a/package/src/calendar-types.ts
+++ b/package/src/calendar-types.ts
@@ -53,7 +53,9 @@ interface CalendarProviderPropsBase<F extends ValueFormat = ValueFormat> {
    */
   locale?: string;
   /**
-   * Custom Temporal namespace for environments without native Temporal support.
+   * The `Temporal` implementation to use. Not bundled — provide a `Temporal`
+   * namespace (e.g. from `temporal-polyfill` or `@js-temporal/polyfill`) unless
+   * the host exposes native `Temporal`. See `RootOwnProps.temporal` for links.
    */
   temporal?: TemporalNamespace;
   /**
diff --git a/package/src/formats/date.ts b/package/src/formats/date.ts
index cd27338..dd51723 100644
--- a/package/src/formats/date.ts
+++ b/package/src/formats/date.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/object.ts b/package/src/formats/object.ts
index 88bb4a1..6418475 100644
--- a/package/src/formats/object.ts
+++ b/package/src/formats/object.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/plain-date-time.ts b/package/src/formats/plain-date-time.ts
index fe2aca2..cad6d6c 100644
--- a/package/src/formats/plain-date-time.ts
+++ b/package/src/formats/plain-date-time.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/plain-date.ts b/package/src/formats/plain-date.ts
index 505b9b5..d9154b4 100644
--- a/package/src/formats/plain-date.ts
+++ b/package/src/formats/plain-date.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/plain-month-day.ts b/package/src/formats/plain-month-day.ts
index 3bdcd5f..6c985a7 100644
--- a/package/src/formats/plain-month-day.ts
+++ b/package/src/formats/plain-month-day.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/plain-year-month.ts b/package/src/formats/plain-year-month.ts
index 1f64b39..1e18aae 100644
--- a/package/src/formats/plain-year-month.ts
+++ b/package/src/formats/plain-year-month.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/formats/zoned-date-time.ts b/package/src/formats/zoned-date-time.ts
index f3f79a5..85b833b 100644
--- a/package/src/formats/zoned-date-time.ts
+++ b/package/src/formats/zoned-date-time.ts
@@ -99,8 +99,6 @@ export { computeWeeksInWindow } from "../compute-weeks-in-window";
 
 export { resolveFirstWeek, resolveFirstWeekSpec } from "../resolve-first-week";
 
-export { Temporal } from "../temporal-polyfill";
-
 export { useCalendarStable, useCalendarState } from "../calendar-context";
 
 export { useMonthViewStable, useMonthViewState } from "../month-view-context";
diff --git a/package/src/index.ts b/package/src/index.ts
index 2d51596..e99024a 100644
--- a/package/src/index.ts
+++ b/package/src/index.ts
@@ -36,19 +36,6 @@ export {
 export { computePreviewRange } from "./root-selection";
 export { computeWeeksInWindow } from "./compute-weeks-in-window";
 export { resolveFirstWeek, resolveFirstWeekSpec } from "./resolve-first-week";
-/**
- * A bundled, dependency-free `Temporal` engine. When the host has no native
- * `Temporal` and you use a non-`Temporal` value format (`object`, `Date`), the
- * calendar selects this automatically — no `@js-temporal/polyfill` needed. You
- * may also pass it explicitly via the `temporal` prop.
- *
- * **ISO 8601 / Gregorian only.** `toLocaleString` localizes display via `Intl`
- * (so e.g. `th-TH` renders the Buddhist era), but all date arithmetic and
- * field values are Gregorian. If you work with `Temporal` value formats or
- * need non-Gregorian calendar math, provide native `Temporal` or
- * `@js-temporal/polyfill` via the `temporal` prop instead.
- */
-export { Temporal } from "./temporal-polyfill";
 export { useCalendarStable, useCalendarState } from "./calendar-context";
 export { useMonthViewStable, useMonthViewState } from "./month-view-context";
 export { useViewContext } from "./view-context";
diff --git a/package/src/month-view.test.tsx b/package/src/month-view.test.tsx
index a38c3c2..1dcabea 100644
--- a/package/src/month-view.test.tsx
+++ b/package/src/month-view.test.tsx
@@ -12,7 +12,6 @@ import {
   PrevMonthButton,
   NextMonthButton,
 } from "./navigation";
-import { Temporal as MiniTemporal } from "./temporal-polyfill";
 import type { DateRange, ValueChangeMeta, MonthData } from "./types";
 import { useViewContext } from "./view-context";
 
@@ -1602,26 +1601,6 @@ describe("non-Gregorian locale (th-TH)", () => {
     unmount();
   });
 
-  it("renders the locale-calendar label with the bundled shim", () => {
-    // The label path now formats via PlainDate.toLocaleString, so the
-    // Gregorian-only mini shim must still localize display through Intl.
-    const { container, unmount } = render(
-      <MonthView
-        {...thProps}
-        temporal={MiniTemporal}
-        defaultValue={MiniTemporal.PlainDate.from("2026-03-15")}
-      >
-        <MonthYearString data-testid="label" />
-      </MonthView>,
-    );
-
-    expect(
-      container.querySelector('[data-testid="label"]')!.textContent,
-    ).toContain("2569");
-
-    unmount();
-  });
-
   it("controlled round-trips without a century jump", () => {
     function Harness() {
       const [month, setMonth] = useState(
diff --git a/package/src/temporal-polyfill.test.ts b/package/src/temporal-polyfill.test.ts
deleted file mode 100644
index c4dfa1a..0000000
--- a/package/src/temporal-polyfill.test.ts
+++ /dev/null
@@ -1,363 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { Temporal } from "./temporal-polyfill";
-
-const T = Temporal;
-
-function date(iso: string) {
-  return T.PlainDate.from(iso);
-}
-
-describe("PlainDate.from", () => {
-  it("parses ISO string", () => {
-    const d = date("2026-03-15");
-    expect(d.year).toBe(2026);
-    expect(d.month).toBe(3);
-    expect(d.day).toBe(15);
-  });
-
-  it("parses ISO string with time portion (ignores time)", () => {
-    const d = T.PlainDate.from("2026-03-15T10:30:00");
-    expect(d.year).toBe(2026);
-    expect(d.month).toBe(3);
-    expect(d.day).toBe(15);
-  });
-
-  it("creates from object", () => {
-    const d = T.PlainDate.from({ year: 2026, month: 2, day: 28 });
-    expect(d.toString()).toBe("2026-02-28");
-  });
-
-  it("constrains overflow day", () => {
-    const d = T.PlainDate.from(
-      { year: 2026, month: 2, day: 31 },
-      { overflow: "constrain" },
-    );
-    expect(d.day).toBe(28);
-  });
-
-  it("constrains overflow day for leap year", () => {
-    const d = T.PlainDate.from(
-      { year: 2024, month: 2, day: 31 },
-      { overflow: "constrain" },
-    );
-    expect(d.day).toBe(29);
-  });
-});
-
-describe("PlainDate.compare", () => {
-  it.each<{
-    description: string;
-    a: string;
-    b: string;
-    expected: number;
-  }>([
-    {
-      description: "equal dates",
-      a: "2026-03-15",
-      b: "2026-03-15",
-      expected: 0,
-    },
-    {
-      description: "a before b (day)",
-      a: "2026-03-14",
-      b: "2026-03-15",
-      expected: -1,
-    },
-    {
-      description: "a after b (day)",
-      a: "2026-03-16",
-      b: "2026-03-15",
-      expected: 1,
-    },
-    {
-      description: "a before b (month)",
-      a: "2026-02-15",
-      b: "2026-03-15",
-      expected: -1,
-    },
-    {
-      description: "a before b (year)",
-      a: "2025-03-15",
-      b: "2026-03-15",
-      expected: -1,
-    },
-  ])("$description", ({ a, b, expected }) => {
-    expect(T.PlainDate.compare(date(a), date(b))).toBe(expected);
-  });
-});
-
-describe("PlainDate add/subtract", () => {
-  it("adds days", () => {
-    expect(date("2026-03-15").add({ days: 5 }).toString()).toBe("2026-03-20");
-  });
-
-  it("adds weeks", () => {
-    expect(date("2026-03-15").add({ weeks: 2 }).toString()).toBe("2026-03-29");
-  });
-
-  it("adds months with day clamping (Jan 31 + 1 month)", () => {
-    expect(date("2026-01-31").add({ months: 1 }).toString()).toBe("2026-02-28");
-  });
-
-  it("adds months with day clamping (Jan 31 + 1 month, leap year)", () => {
-    expect(date("2024-01-31").add({ months: 1 }).toString()).toBe("2024-02-29");
-  });
-
-  it("subtracts days", () => {
-    expect(date("2026-03-15").subtract({ days: 5 }).toString()).toBe(
-      "2026-03-10",
-    );
-  });
-
-  it("subtracts months", () => {
-    expect(date("2026-03-31").subtract({ months: 1 }).toString()).toBe(
-      "2026-02-28",
-    );
-  });
-
-  it("crosses year boundary forward", () => {
-    expect(date("2026-12-31").add({ days: 1 }).toString()).toBe("2027-01-01");
-  });
-
-  it("crosses year boundary backward", () => {
-    expect(date("2027-01-01").subtract({ days: 1 }).toString()).toBe(
-      "2026-12-31",
-    );
-  });
-
-  it("adds months crossing year boundary", () => {
-    expect(date("2026-11-15").add({ months: 3 }).toString()).toBe("2027-02-15");
-  });
-});
-
-describe("PlainDate since/until", () => {
-  it("positive days", () => {
-    expect(date("2026-03-20").since(date("2026-03-10")).days).toBe(10);
-  });
-
-  it("negative days", () => {
-    expect(date("2026-03-10").since(date("2026-03-20")).days).toBe(-10);
-  });
-
-  it("zero days", () => {
-    expect(date("2026-03-15").since(date("2026-03-15")).days).toBe(0);
-  });
-
-  it("until returns positive for future dates", () => {
-    expect(date("2026-03-10").until(date("2026-03-20")).days).toBe(10);
-  });
-});
-
-describe("PlainDate dayOfWeek", () => {
-  it.each<{ description: string; d: string; expected: number }>([
-    { description: "2026-03-15 is Sunday", d: "2026-03-15", expected: 7 },
-    { description: "2026-03-16 is Monday", d: "2026-03-16", expected: 1 },
-    { description: "2026-03-17 is Tuesday", d: "2026-03-17", expected: 2 },
-    { description: "2026-03-21 is Saturday", d: "2026-03-21", expected: 6 },
-  ])("$description", ({ d, expected }) => {
-    expect(date(d).dayOfWeek).toBe(expected);
-  });
-});
-
-describe("PlainDate daysInMonth", () => {
-  it.each<{ description: string; d: string; expected: number }>([
-    { description: "Feb non-leap", d: "2026-02-01", expected: 28 },
-    { description: "Feb leap", d: "2024-02-01", expected: 29 },
-    { description: "30-day month (Apr)", d: "2026-04-15", expected: 30 },
-    { description: "31-day month (Mar)", d: "2026-03-15", expected: 31 },
-  ])("$description", ({ d, expected }) => {
-    expect(date(d).daysInMonth).toBe(expected);
-  });
-});
-
-describe("PlainDate toString roundtrip", () => {
-  it("roundtrips through from/toString", () => {
-    const iso = "2026-03-15";
-    expect(T.PlainDate.from(date(iso).toString()).toString()).toBe(iso);
-  });
-});
-
-describe("PlainDate toLocaleString", () => {
-  const june = T.PlainDate.from("2026-06-01");
-
-  it("localizes the Gregorian year and month for en-US", () => {
-    const s = june.toLocaleString("en-US", { year: "numeric", month: "long" });
-    expect(s).toContain("2026");
-    expect(s).toContain("June");
-  });
-
-  it("localizes to the locale's calendar (th-TH → Buddhist era)", () => {
-    const s = june.toLocaleString("th-TH", { year: "numeric", month: "long" });
-    // ISO 2026 → Buddhist Era 2569.
-    expect(s).toContain("2569");
-  });
-
-  it("does not leak a day with year+month options", () => {
-    const s = june.toLocaleString("en-US", { year: "numeric", month: "long" });
-    expect(s).not.toMatch(/\b1\b/);
-  });
-
-  it("honors custom options (numeric month)", () => {
-    const s = june.toLocaleString("en-US", {
-      year: "numeric",
-      month: "2-digit",
-    });
-    expect(s).toContain("06");
-    expect(s).toContain("2026");
-  });
-});
-
-describe("PlainDate equals", () => {
-  it("returns true for same date", () => {
-    expect(date("2026-03-15").equals(date("2026-03-15"))).toBe(true);
-  });
-
-  it("returns false for different date", () => {
-    expect(date("2026-03-15").equals(date("2026-03-16"))).toBe(false);
-  });
-});
-
-describe("PlainDateTime", () => {
-  it("from string", () => {
-    const dt = T.PlainDateTime.from("2026-03-15T10:30:45");
-    expect(dt.year).toBe(2026);
-    expect(dt.hour).toBe(10);
-    expect(dt.minute).toBe(30);
-    expect(dt.second).toBe(45);
-  });
-
-  it("from object", () => {
-    const dt = T.PlainDateTime.from({
-      year: 2026,
-      month: 3,
-      day: 15,
-      hour: 10,
-    });
-    expect(dt.hour).toBe(10);
-    expect(dt.minute).toBe(0);
-  });
-
-  it("toPlainDate", () => {
-    const dt = T.PlainDateTime.from("2026-03-15T10:30:00");
-    expect(dt.toPlainDate().toString()).toBe("2026-03-15");
-  });
-});
-
-describe("PlainMonthDay", () => {
-  it("from object", () => {
-    const md = T.PlainMonthDay.from({ month: 7, day: 4 });
-    expect(md.monthCode).toBe("M07");
-    expect(md.day).toBe(4);
-  });
-
-  it("toPlainDate with year", () => {
-    const md = T.PlainMonthDay.from({ month: 2, day: 28 });
-    const pd = md.toPlainDate({ year: 2026 });
-    expect(pd.toString()).toBe("2026-02-28");
-  });
-});
-
-describe("PlainYearMonth", () => {
-  it("from object", () => {
-    const ym = T.PlainYearMonth.from({ year: 2026, month: 6 });
-    expect(ym.year).toBe(2026);
-    expect(ym.month).toBe(6);
-  });
-
-  it("toPlainDate with day", () => {
-    const ym = T.PlainYearMonth.from({ year: 2026, month: 6 });
-    expect(ym.toPlainDate({ day: 15 }).toString()).toBe("2026-06-15");
-  });
-
-  it("daysInMonth", () => {
-    expect(T.PlainYearMonth.from({ year: 2026, month: 2 }).daysInMonth).toBe(
-      28,
-    );
-    expect(T.PlainYearMonth.from({ year: 2024, month: 2 }).daysInMonth).toBe(
-      29,
-    );
-  });
-});
-
-describe("ZonedDateTime", () => {
-  it("extracts components in UTC", () => {
-    const pdt = T.PlainDateTime.from("2026-03-15T10:30:00");
-    const zdt = pdt.toZonedDateTime("UTC");
-    expect(zdt.year).toBe(2026);
-    expect(zdt.month).toBe(3);
-    expect(zdt.day).toBe(15);
-    expect(zdt.hour).toBe(10);
-    expect(zdt.minute).toBe(30);
-    expect(zdt.timeZoneId).toBe("UTC");
-  });
-
-  it("extracts components in a non-UTC timezone", () => {
-    const pdt = T.PlainDateTime.from("2026-03-15T10:30:00");
-    const zdt = pdt.toZonedDateTime("America/New_York");
-    expect(zdt.year).toBe(2026);
-    expect(zdt.month).toBe(3);
-    expect(zdt.day).toBe(15);
-    expect(zdt.hour).toBe(10);
-    expect(zdt.timeZoneId).toBe("America/New_York");
-  });
-
-  it("toPlainDate roundtrip", () => {
-    const pd = date("2026-06-20");
-    const zdt = pd.toZonedDateTime("America/New_York");
-    expect(zdt.toPlainDate().toString()).toBe("2026-06-20");
-  });
-
-  it("toPlainDateTime roundtrip", () => {
-    const pdt = T.PlainDateTime.from("2026-03-15T14:30:00");
-    const zdt = pdt.toZonedDateTime("UTC");
-    const roundtrip = zdt.toPlainDateTime();
-    expect(roundtrip.hour).toBe(14);
-    expect(roundtrip.minute).toBe(30);
-  });
-
-  it("epochMilliseconds is valid", () => {
-    const zdt = T.Now.zonedDateTimeISO("UTC");
-    expect(typeof zdt.epochMilliseconds).toBe("number");
-    expect(Math.abs(zdt.epochMilliseconds - Date.now())).toBeLessThan(1000);
-  });
-});
-
-describe("Now", () => {
-  it("timeZoneId returns a non-empty string", () => {
-    const tz = T.Now.timeZoneId();
-    expect(typeof tz).toBe("string");
-    expect(tz.length).toBeGreaterThan(0);
-  });
-
-  it("zonedDateTimeISO returns current time", () => {
-    const zdt = T.Now.zonedDateTimeISO("UTC");
-    expect(zdt.year).toBeGreaterThan(2020);
-  });
-
-  it("plainDateISO returns today", () => {
-    const pd = T.Now.plainDateISO();
-    expect(pd.year).toBeGreaterThan(2020);
-    expect(pd.month).toBeGreaterThanOrEqual(1);
-    expect(pd.month).toBeLessThanOrEqual(12);
-  });
-});
-
-describe("PlainDate → ZonedDateTime → PlainDate roundtrip", () => {
-  it.each(["2026-01-01", "2026-06-15", "2026-12-31", "2024-02-29"])(
-    "%s roundtrips through UTC",
-    (iso) => {
-      const pd = date(iso);
-      const zdt = pd.toZonedDateTime("UTC");
-      expect(zdt.toPlainDate().toString()).toBe(iso);
-    },
-  );
-
-  it.each(["2026-01-01", "2026-06-15", "2026-12-31"])(
-    "%s roundtrips through America/New_York",
-    (iso) => {
-      const pd = date(iso);
-      const zdt = pd.toZonedDateTime("America/New_York");
-      expect(zdt.toPlainDate().toString()).toBe(iso);
-    },
-  );
-});
diff --git a/package/src/temporal-polyfill.ts b/package/src/temporal-polyfill.ts
deleted file mode 100644
index 3296f98..0000000
--- a/package/src/temporal-polyfill.ts
+++ /dev/null
@@ -1,649 +0,0 @@
-/**
- * Minimal, dependency-free `Temporal` engine for the calendar's **internal**
- * date math. {@link resolveTemporal} selects it automatically — with no
- * `@js-temporal/polyfill` dependency — when the host lacks native `Temporal`
- * and the caller drives the calendar with a non-`Temporal` value format
- * (`object`, `Date`), since those values never expose `Temporal` objects. It
- * can also be passed explicitly via the `temporal` prop. For a `Temporal`
- * value format with no native/provided `Temporal`, resolution throws rather
- * than substitute the shim (the caller wants real `Temporal` objects).
- *
- * **ISO 8601 / Gregorian only.** It implements just enough of the `Temporal`
- * surface for the calendar to operate (`PlainDate`, `PlainDateTime`,
- * `PlainMonthDay`, `PlainYearMonth`, `Now`) using Gregorian arithmetic.
- * `toLocaleString` formats via the host `Intl`, so display still localizes to
- * the locale's calendar (e.g. Buddhist for `th-TH`), but the shim performs
- * **no non-Gregorian calendar math** — all field values and arithmetic are
- * Gregorian.
- *
- * If you work with `Temporal` objects directly, or need non-Gregorian calendar
- * math (Buddhist, Hebrew, Islamic, …), provide native `Temporal` or
- * `@js-temporal/polyfill` via the `temporal` prop instead.
- */
-import type { TemporalNamespace } from "./types";
-
-// ---------------------------------------------------------------------------
-// Helpers (private)
-// ---------------------------------------------------------------------------
-
-function daysInMonth(year: number, month: number): number {
-  return new Date(year, month, 0).getDate();
-}
-
-function toUTC(y: number, m: number, d: number): number {
-  return Date.UTC(y, m - 1, d);
-}
-
-function isoWeekday(utcDate: Date): number {
-  const dow = utcDate.getUTCDay();
-  return dow === 0 ? 7 : dow;
-}
-
-function pad2(n: number): string {
-  return n < 10 ? `0${n}` : `${n}`;
-}
-
-function clamp(val: number, min: number, max: number): number {
-  return val < min ? min : val > max ? max : val;
-}
-
-function parseDateISO(str: string): {
-  year: number;
-  month: number;
-  day: number;
-} {
-  const [datePart] = str.split("T");
-  const [y, m, d] = datePart?.split("-").map(Number) ?? [];
-  if (y === undefined || m === undefined || d === undefined) {
-    throw new RangeError(`Invalid ISO date string: ${str}`);
-  }
-  return { year: y, month: m, day: d };
-}
-
-function parseDateTimeISO(str: string): {
-  year: number;
-  month: number;
-  day: number;
-  hour: number;
-  minute: number;
-  second: number;
-} {
-  const [datePart, timePart] = str.split("T");
-  const [y, m, d] = datePart?.split("-").map(Number) ?? [];
-  if (y === undefined || m === undefined || d === undefined) {
-    throw new RangeError(`Invalid ISO date-time string: ${str}`);
-  }
-  if (!timePart)
-    return { year: y, month: m, day: d, hour: 0, minute: 0, second: 0 };
-  const [h, min, s] = timePart.split(":").map(Number);
-  return {
-    year: y,
-    month: m,
-    day: d,
-    hour: h || 0,
-    minute: min || 0,
-    second: s || 0,
-  };
-}
-
-// Cache Intl.DateTimeFormat instances per timezone
-const dtfCache = new Map<string, Intl.DateTimeFormat>();
-
-function getDTF(tz: string): Intl.DateTimeFormat {
-  let dtf = dtfCache.get(tz);
-  if (!dtf) {
-    dtf = new Intl.DateTimeFormat("en-US", {
-      timeZone: tz,
-      year: "numeric",
-      month: "numeric",
-      day: "numeric",
-      hour: "numeric",
-      minute: "numeric",
-      second: "numeric",
-      hour12: false,
-    });
-    dtfCache.set(tz, dtf);
-  }
-  return dtf;
-}
-
-interface TzParts {
-  year: number;
-  month: number;
-  day: number;
-  hour: number;
-  minute: number;
-  second: number;
-}
-
-function extractTzParts(epochMs: number, tz: string): TzParts {
-  const dtf = getDTF(tz);
-  const parts = dtf.formatToParts(new Date(epochMs));
-  const vals: Record<string, number> = {};
-  for (const p of parts) {
-    if (p.type !== "literal") {
-      vals[p.type] = Number(p.value);
-    }
-  }
-  const { year, month, day, hour, minute, second } = vals;
-  if (
-    year === undefined ||
-    month === undefined ||
-    day === undefined ||
-    hour === undefined ||
-    minute === undefined ||
-    second === undefined
-  ) {
-    throw new RangeError(`Invalid time zone: ${tz}`);
-  }
-  return {
-    year,
-    month,
-    day,
-    hour: hour === 24 ? 0 : hour,
-    minute,
-    second,
-  };
-}
-
-function wallToEpoch(
-  y: number,
-  m: number,
-  d: number,
-  h: number,
-  min: number,
-  s: number,
-  tz: string,
-): number {
-  const utcGuess = Date.UTC(y, m - 1, d, h, min, s);
-  const inTz = extractTzParts(utcGuess, tz);
-  const wallOfGuess = Date.UTC(
-    inTz.year,
-    inTz.month - 1,
-    inTz.day,
-    inTz.hour,
-    inTz.minute,
-    inTz.second,
-  );
-  return utcGuess - (wallOfGuess - utcGuess);
-}
-
-// ---------------------------------------------------------------------------
-// MiniPlainDate
-// ---------------------------------------------------------------------------
-
-class MiniPlainDate {
-  readonly year: number;
-  readonly month: number;
-  readonly day: number;
-
-  constructor(year: number, month: number, day: number) {
-    this.year = year;
-    this.month = month;
-    this.day = day;
-  }
-
-  get dayOfWeek(): number {
-    return isoWeekday(new Date(toUTC(this.year, this.month, this.day)));
-  }
-
-  get daysInWeek(): number {
-    return 7;
-  }
-
-  get daysInMonth(): number {
-    return daysInMonth(this.year, this.month);
-  }
-
-  get monthCode(): string {
-    return `M${pad2(this.month)}`;
-  }
-
-  add(dur: {
-    days?: number;
-    weeks?: number;
-    months?: number;
-    years?: number;
-  }): MiniPlainDate {
-    let y = this.year + (dur.years || 0);
-    let m = this.month + (dur.months || 0);
-
-    // Resolve month overflow/underflow
-    while (m > 12) {
-      m -= 12;
-      y += 1;
-    }
-    while (m < 1) {
-      m += 12;
-      y -= 1;
-    }
-
-    // Clamp day to valid range for new month
-    const d = Math.min(this.day, daysInMonth(y, m));
-
-    // Add days and weeks via epoch arithmetic
-    const totalDays = (dur.days || 0) + (dur.weeks || 0) * 7;
-    if (totalDays === 0) return new MiniPlainDate(y, m, d);
-
-    const epoch = toUTC(y, m, d) + totalDays * 86400000;
-    const ud = new Date(epoch);
-    return new MiniPlainDate(
-      ud.getUTCFullYear(),
-      ud.getUTCMonth() + 1,
-      ud.getUTCDate(),
-    );
-  }
-
-  subtract(dur: {
-    days?: number;
-    weeks?: number;
-    months?: number;
-    years?: number;
-  }): MiniPlainDate {
-    return this.add({
-      ...(dur.days && { days: -dur.days }),
-      ...(dur.weeks && { weeks: -dur.weeks }),
-      ...(dur.months && { months: -dur.months }),
-      ...(dur.years && { years: -dur.years }),
-    });
-  }
-
-  since(other: MiniPlainDate, _opts?: any): { days: number } {
-    const thisUTC = toUTC(this.year, this.month, this.day);
-    const otherUTC = toUTC(other.year, other.month, other.day);
-    return { days: Math.round((thisUTC - otherUTC) / 86400000) };
-  }
-
-  until(other: MiniPlainDate, _opts?: any): { days: number } {
-    const thisUTC = toUTC(this.year, this.month, this.day);
-    const otherUTC = toUTC(other.year, other.month, other.day);
-    return { days: Math.round((otherUTC - thisUTC) / 86400000) };
-  }
-
-  equals(other: MiniPlainDate): boolean {
-    return (
-      this.year === other.year &&
-      this.month === other.month &&
-      this.day === other.day
-    );
-  }
-
-  toString(): string {
-    return `${String(this.year).padStart(4, "0")}-${pad2(this.month)}-${pad2(this.day)}`;
-  }
-
-  toZonedDateTime(tz: string | { timeZone: string }): MiniZonedDateTime {
-    const tzId = typeof tz === "string" ? tz : tz.timeZone;
-    return this.toPlainDateTime().toZonedDateTime(tzId);
-  }
-
-  toPlainDateTime(timeLike?: {
-    hour?: number;
-    minute?: number;
-    second?: number;
-  }): MiniPlainDateTime {
-    return new MiniPlainDateTime(
-      this.year,
-      this.month,
-      this.day,
-      timeLike?.hour ?? 0,
-      timeLike?.minute ?? 0,
-      timeLike?.second ?? 0,
-    );
-  }
-
-  toPlainMonthDay(): MiniPlainMonthDay {
-    return new MiniPlainMonthDay(this.month, this.day);
-  }
-
-  toPlainYearMonth(): MiniPlainYearMonth {
-    return new MiniPlainYearMonth(this.year, this.month);
-  }
-
-  toLocaleString(
-    locale?: string | string[],
-    options?: Intl.DateTimeFormatOptions,
-  ): string {
-    return new Date(toUTC(this.year, this.month, this.day)).toLocaleDateString(
-      locale,
-      {
-        timeZone: "UTC",
-        ...options,
-      },
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// MiniPlainDateTime
-// ---------------------------------------------------------------------------
-
-class MiniPlainDateTime {
-  readonly year: number;
-  readonly month: number;
-  readonly day: number;
-  readonly hour: number;
-  readonly minute: number;
-  readonly second: number;
-
-  constructor(
-    year: number,
-    month: number,
-    day: number,
-    hour = 0,
-    minute = 0,
-    second = 0,
-  ) {
-    this.year = year;
-    this.month = month;
-    this.day = day;
-    this.hour = hour;
-    this.minute = minute;
-    this.second = second;
-  }
-
-  get dayOfWeek(): number {
-    return isoWeekday(new Date(toUTC(this.year, this.month, this.day)));
-  }
-
-  get daysInMonth(): number {
-    return daysInMonth(this.year, this.month);
-  }
-
-  toZonedDateTime(tz: string | { timeZone: string }): MiniZonedDateTime {
-    const tzId = typeof tz === "string" ? tz : tz.timeZone;
-    const epoch = wallToEpoch(
-      this.year,
-      this.month,
-      this.day,
-      this.hour,
-      this.minute,
-      this.second,
-      tzId,
-    );
-    return new MiniZonedDateTime(epoch, tzId);
-  }
-
-  toPlainDate(): MiniPlainDate {
-    return new MiniPlainDate(this.year, this.month, this.day);
-  }
-
-  toString(): string {
-    return `${String(this.year).padStart(4, "0")}-${pad2(this.month)}-${pad2(this.day)}T${pad2(this.hour)}:${pad2(this.minute)}:${pad2(this.second)}`;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// MiniPlainMonthDay
-// ---------------------------------------------------------------------------
-
-class MiniPlainMonthDay {
-  readonly monthCode: string;
-  readonly month: number;
-  readonly day: number;
-
-  constructor(month: number, day: number) {
-    this.month = month;
-    this.day = day;
-    this.monthCode = `M${pad2(month)}`;
-  }
-
-  toPlainDate(fields: { year: number }): MiniPlainDate {
-    return new MiniPlainDate(fields.year, this.month, this.day);
-  }
-
-  equals(other: MiniPlainMonthDay): boolean {
-    return this.month === other.month && this.day === other.day;
-  }
-
-  toString(): string {
-    return `${pad2(this.month)}-${pad2(this.day)}`;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// MiniPlainYearMonth
-// ---------------------------------------------------------------------------
-
-class MiniPlainYearMonth {
-  readonly year: number;
-  readonly month: number;
-
-  constructor(year: number, month: number) {
-    this.year = year;
-    this.month = month;
-  }
-
-  get monthCode(): string {
-    return `M${pad2(this.month)}`;
-  }
-
-  get daysInMonth(): number {
-    return daysInMonth(this.year, this.month);
-  }
-
-  toPlainDate(fields: { day: number }): MiniPlainDate {
-    return new MiniPlainDate(this.year, this.month, fields.day);
-  }
-
-  add(dur: { months?: number; years?: number }): MiniPlainYearMonth {
-    let y = this.year + (dur.years || 0);
-    let m = this.month + (dur.months || 0);
-    while (m > 12) {
-      m -= 12;
-      y += 1;
-    }
-    while (m < 1) {
-      m += 12;
-      y -= 1;
-    }
-    return new MiniPlainYearMonth(y, m);
-  }
-
-  subtract(dur: { months?: number; years?: number }): MiniPlainYearMonth {
-    return this.add({
-      ...(dur.months && { months: -dur.months }),
-      ...(dur.years && { years: -dur.years }),
-    });
-  }
-
-  equals(other: MiniPlainYearMonth): boolean {
-    return this.year === other.year && this.month === other.month;
-  }
-
-  toString(): string {
-    return `${String(this.year).padStart(4, "0")}-${pad2(this.month)}`;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// MiniZonedDateTime
-// ---------------------------------------------------------------------------
-
-class MiniZonedDateTime {
-  readonly epochMilliseconds: number;
-  readonly timeZoneId: string;
-  private _parts?: TzParts;
-
-  constructor(epochMs: number, timeZoneId: string) {
-    this.epochMilliseconds = epochMs;
-    this.timeZoneId = timeZoneId;
-  }
-
-  private get parts(): TzParts {
-    if (!this._parts) {
-      this._parts = extractTzParts(this.epochMilliseconds, this.timeZoneId);
-    }
-    return this._parts;
-  }
-
-  get year(): number {
-    return this.parts.year;
-  }
-  get month(): number {
-    return this.parts.month;
-  }
-  get day(): number {
-    return this.parts.day;
-  }
-  get hour(): number {
-    return this.parts.hour;
-  }
-  get minute(): number {
-    return this.parts.minute;
-  }
-  get second(): number {
-    return this.parts.second;
-  }
-
-  get dayOfWeek(): number {
-    return isoWeekday(new Date(toUTC(this.year, this.month, this.day)));
-  }
-
-  toPlainDate(): MiniPlainDate {
-    return new MiniPlainDate(this.year, this.month, this.day);
-  }
-
-  toPlainDateTime(): MiniPlainDateTime {
-    return new MiniPlainDateTime(
-      this.year,
-      this.month,
-      this.day,
-      this.hour,
-      this.minute,
-      this.second,
-    );
-  }
-
-  toPlainTime(): { hour: number; minute: number; second: number } {
-    return { hour: this.hour, minute: this.minute, second: this.second };
-  }
-
-  toPlainYearMonth(): MiniPlainYearMonth {
-    return new MiniPlainYearMonth(this.year, this.month);
-  }
-
-  toString(): string {
-    return `${String(this.year).padStart(4, "0")}-${pad2(this.month)}-${pad2(this.day)}T${pad2(this.hour)}:${pad2(this.minute)}:${pad2(this.second)}[${this.timeZoneId}]`;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Static constructors
-// ---------------------------------------------------------------------------
-
-const PlainDate = {
-  from(item: any, options?: { overflow?: string }): MiniPlainDate {
-    if (typeof item === "string") {
-      const { year, month, day } = parseDateISO(item);
-      if (options?.overflow === "constrain") {
-        return new MiniPlainDate(
-          year,
-          month,
-          clamp(day, 1, daysInMonth(year, month)),
-        );
-      }
-      return new MiniPlainDate(year, month, day);
-    }
-    const year = item.year;
-    const month = item.month;
-    let day = item.day;
-    if (options?.overflow === "constrain") {
-      day = clamp(day, 1, daysInMonth(year, month));
-    }
-    return new MiniPlainDate(year, month, day);
-  },
-
-  compare(a: MiniPlainDate, b: MiniPlainDate): number {
-    if (a.year !== b.year) return Math.sign(a.year - b.year);
-    if (a.month !== b.month) return Math.sign(a.month - b.month);
-    if (a.day !== b.day) return Math.sign(a.day - b.day);
-    return 0;
-  },
-};
-
-const PlainDateTime = {
-  from(item: any, _options?: { overflow?: string }): MiniPlainDateTime {
-    if (typeof item === "string") {
-      const { year, month, day, hour, minute, second } = parseDateTimeISO(item);
-      return new MiniPlainDateTime(year, month, day, hour, minute, second);
-    }
-    return new MiniPlainDateTime(
-      item.year,
-      item.month,
-      item.day,
-      item.hour ?? 0,
-      item.minute ?? 0,
-      item.second ?? 0,
-    );
-  },
-};
-
-const PlainMonthDay = {
-  from(item: any): MiniPlainMonthDay {
-    if (typeof item === "string") {
-      // "MM-DD" or "YYYY-MM-DD" — take last two numeric segments
-      const [first, second, third] = item.split("-").map(Number);
-      if (first === undefined || second === undefined) {
-        throw new RangeError(`Invalid ISO month-day string: ${item}`);
-      }
-      if (third !== undefined) return new MiniPlainMonthDay(second, third);
-      return new MiniPlainMonthDay(first, second);
-    }
-    const month =
-      item.month ??
-      (item.monthCode ? Number.parseInt(item.monthCode.slice(1), 10) : 1);
-    return new MiniPlainMonthDay(month, item.day);
-  },
-};
-
-const PlainYearMonth = {
-  from(item: any): MiniPlainYearMonth {
-    if (typeof item === "string") {
-      const [y, m] = item.split("-").map(Number);
-      if (y === undefined || m === undefined) {
-        throw new RangeError(`Invalid ISO year-month string: ${item}`);
-      }
-      return new MiniPlainYearMonth(y, m);
-    }
-    return new MiniPlainYearMonth(item.year, item.month);
-  },
-
-  compare(a: MiniPlainYearMonth, b: MiniPlainYearMonth): number {
-    if (a.year !== b.year) return Math.sign(a.year - b.year);
-    if (a.month !== b.month) return Math.sign(a.month - b.month);
-    return 0;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Now
-// ---------------------------------------------------------------------------
-
-const Now = {
-  timeZoneId(): string {
-    return Intl.DateTimeFormat().resolvedOptions().timeZone;
-  },
-
-  zonedDateTimeISO(tz?: string): MiniZonedDateTime {
-    return new MiniZonedDateTime(Date.now(), tz ?? Now.timeZoneId());
-  },
-
-  plainDateISO(): MiniPlainDate {
-    const tz = Now.timeZoneId();
-    const parts = extractTzParts(Date.now(), tz);
-    return new MiniPlainDate(parts.year, parts.month, parts.day);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Export
-// ---------------------------------------------------------------------------
-
-export const Temporal = {
-  Now,
-  PlainDate,
-  PlainDateTime,
-  PlainMonthDay,
-  PlainYearMonth,
-} as unknown as TemporalNamespace;
diff --git a/package/src/test-temporal.ts b/package/src/test-temporal.ts
index 0d6486b..432abea 100644
--- a/package/src/test-temporal.ts
+++ b/package/src/test-temporal.ts
@@ -1,5 +1,4 @@
 import { Temporal as FullTemporal } from "@js-temporal/polyfill";
-import { Temporal as MiniTemporal } from "./temporal-polyfill";
 import type { TemporalNamespace } from "./types";
 
 export const temporalVariants: { name: string; T: TemporalNamespace }[] = [
@@ -13,5 +12,4 @@ export const temporalVariants: { name: string; T: TemporalNamespace }[] = [
       PlainYearMonth: FullTemporal.PlainYearMonth,
     },
   },
-  { name: "mini polyfill", T: MiniTemporal },
 ];
diff --git a/package/src/types.ts b/package/src/types.ts
index 6d90a9d..ff9d2b7 100644
--- a/package/src/types.ts
+++ b/package/src/types.ts
@@ -276,9 +276,16 @@ interface RootOwnPropsBase<F extends ValueFormat = ValueFormat> {
    */
   locale?: string;
   /**
-   * Custom Temporal namespace for environments without native Temporal support.
-   * Typically the `Temporal` export from `@js-temporal/polyfill`. When using
-   * `@js-temporal/polyfill`.
+   * The `Temporal` implementation to use. This library does not bundle one:
+   * provide a `Temporal` namespace here unless the host already exposes the
+   * native `Temporal` API. Two well-supported polyfills:
+   *
+   * - `temporal-polyfill` — https://github.com/fullcalendar/temporal-polyfill
+   * - `@js-temporal/polyfill` — https://github.com/js-temporal/temporal-polyfill
+   *
+   * @example
+   * import { Temporal } from "temporal-polyfill";
+   * <MonthView temporal={Temporal} … />
    */
   temporal?: TemporalNamespace;
   /**
diff --git a/package/src/utils.test.ts b/package/src/utils.test.ts
index 46599c5..4070019 100644
--- a/package/src/utils.test.ts
+++ b/package/src/utils.test.ts
@@ -1,6 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { describe, it, expect } from "vitest";
-import { Temporal as bundledTemporal } from "./temporal-polyfill";
 import { temporalVariants } from "./test-temporal";
 import type { TemporalNamespace } from "./types";
 import {
@@ -46,38 +45,6 @@ describe("resolveTemporal", () => {
       if (orig) (globalThis as any).Temporal = orig;
     }
   });
-
-  it.each<{ description: string; format: "object" | "Date" }>([
-    { description: "object", format: "object" },
-    { description: "Date", format: "Date" },
-  ])(
-    "falls back to the bundled shim for the $description format when no Temporal is available",
-    ({ format }) => {
-      const orig = (globalThis as any).Temporal;
-      delete (globalThis as any).Temporal;
-      try {
-        expect(resolveTemporal(undefined, format)).toBe(bundledTemporal);
-      } finally {
-        if (orig) (globalThis as any).Temporal = orig;
-      }
-    },
-  );
-
-  it("throws for a Temporal format when no Temporal is available", () => {
-    const orig = (globalThis as any).Temporal;
-    delete (globalThis as any).Temporal;
-    try {
-      expect(() => resolveTemporal(undefined, "PlainDate")).toThrow(
-        "Temporal is not available",
-      );
-    } finally {
-      if (orig) (globalThis as any).Temporal = orig;
-    }
-  });
-
-  it("prefers an explicitly provided namespace over the shim fallback", () => {
-    expect(resolveTemporal(T, "object")).toBe(T);
-  });
 });
 
 describe.each(temporalVariants)("getSystemTimeZone ($name)", ({ T }) => {
diff --git a/package/src/utils.ts b/package/src/utils.ts
index 8715690..f93fb30 100644
--- a/package/src/utils.ts
+++ b/package/src/utils.ts
@@ -1,5 +1,4 @@
 import type { Temporal } from "@js-temporal/polyfill";
-import { Temporal as bundledTemporal } from "./temporal-polyfill";
 import type {
   TemporalNamespace,
   DateValueObject,
@@ -7,35 +6,27 @@ import type {
   WeekStartDay,
 } from "./types";
 
-/** Value formats whose values are plain (non-`Temporal`) objects. */
-const NON_TEMPORAL_FORMATS = new Set<ValueFormat>(["object", "Date"]);
-
 /**
  * Resolves a {@link TemporalNamespace} instance.
  *
- * Resolution order: an explicitly `provided` namespace, then native
- * `globalThis.Temporal`. If neither exists, the behavior depends on `format`:
- * non-`Temporal` formats (`object`, `Date`) don't expose `Temporal` objects to
- * the caller, so the bundled Gregorian-only shim is used as the internal date
- * engine. `Temporal` formats imply the caller wants real `Temporal` objects —
- * the shim is not one, so resolution throws instead of silently substituting.
+ * Returns `provided` when given, otherwise native `globalThis.Temporal`. This
+ * library does not bundle a `Temporal` implementation — if neither is
+ * available, it throws. Provide one via the `temporal` prop, e.g. the
+ * `Temporal` export from `temporal-polyfill`
+ * (https://github.com/fullcalendar/temporal-polyfill) or `@js-temporal/polyfill`
+ * (https://github.com/js-temporal/temporal-polyfill).
  *
  * @param provided - An explicit Temporal polyfill or namespace.
- * @param format - The active value format (decides the no-Temporal fallback).
  */
 export function resolveTemporal(
   provided?: TemporalNamespace,
-  format?: ValueFormat,
 ): TemporalNamespace {
   if (provided) return provided;
   if (typeof globalThis !== "undefined" && (globalThis as any).Temporal) {
     return (globalThis as any).Temporal;
   }
-  if (format !== undefined && NON_TEMPORAL_FORMATS.has(format)) {
-    return bundledTemporal;
-  }
   throw new Error(
-    "DatePicker: Temporal is not available. Pass a Temporal polyfill via the `temporal` prop, or use a browser that supports the Temporal API natively.",
+    "DatePicker: Temporal is not available. Pass a Temporal implementation via the `temporal` prop — e.g. `temporal-polyfill` or `@js-temporal/polyfill` — or run where the native Temporal API exists.",
   );
 }
 

From 2cb57eb85098ba46ed3e3188dee98d4108baa585 Mon Sep 17 00:00:00 2001
From: Klink <85062+dogmar@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:47:08 -0700
Subject: [PATCH 6/6] Apply suggestion from @dogmar

---
 package/src/navigation.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/package/src/navigation.tsx b/package/src/navigation.tsx
index 2576a22..6cba259 100644
--- a/package/src/navigation.tsx
+++ b/package/src/navigation.tsx
@@ -190,8 +190,8 @@ function MonthYearStringFn(
     month: "long",
     year: "numeric",
   };
-  // Format through Temporal so the only native `Date` lives inside the
-  // polyfill. `displayYear`/`displayMonth` are ISO; formatting an ISO
+  // Format through Temporal
+  // `displayYear`/`displayMonth` are ISO; formatting an ISO
   // `PlainDate` (not `PlainYearMonth`, which throws on calendar mismatch)
   // lets Intl render it in the locale's calendar (e.g. Buddhist for th-TH).
   const formatted = T.PlainDate.from({