@multiplatform.one/theme 6.4.2 → 6.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "6.4.2",
+  "version": "6.6.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.0.0-rc.41",
     "@tamagui/web": "2.0.0-rc.41",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/platform": "6.4.2",
-    "@multiplatform.one/store": "6.4.2"
+    "@multiplatform.one/platform": "6.6.0",
+    "@multiplatform.one/store": "6.6.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.0.0-rc.41",
@@ -69,8 +69,8 @@
     "tamagui": "2.0.0-rc.41",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.4.2",
-    "@multiplatform.one/test-utils": "6.4.2"
+    "@multiplatform.one/config": "6.6.0",
+    "@multiplatform.one/test-utils": "6.6.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/dates.spec.ts

@@ -1,5 +1,17 @@
 import { describe, expect, it } from "vitest";
-import { formatAbsoluteDate, formatAbsoluteDateTime, formatRelativeTimestamp } from "./dates";
+import {
+  formatAbsoluteDate,
+  formatAbsoluteDateTime,
+  formatDayLong,
+  formatDayOfMonth,
+  formatMonthYear,
+  formatRelativeTimestamp,
+  formatTimeOfDay,
+  getMonthNames,
+  getWeekdayNames,
+  parseCalendarDate,
+  type DateInput,
+} from "./dates";
 
 // Pin locale so assertions don't depend on the host machine.
 const enUS = { locale: "en-US" } as const;
@@ -73,3 +85,148 @@ describe("formatRelativeTimestamp (feed/social register)", () => {
     expect(formatRelativeTimestamp("garbage", base)).toBe("garbage");
   });
 });
+
+describe("formatTimeOfDay (time-of-day register)", () => {
+  it("renders hour and minutes, never seconds", () => {
+    expect(formatTimeOfDay(new Date(2026, 7, 12, 14, 30, 45), enUS)).toBe("2:30 PM");
+  });
+
+  it("drops minutes for hour ticks", () => {
+    expect(formatTimeOfDay(new Date(2026, 7, 12, 14, 0), { ...enUS, minutes: false })).toBe("2 PM");
+  });
+
+  it("accepts a clock-time string — the wire shape Frappe Time fields send", () => {
+    expect(formatTimeOfDay("14:30", enUS)).toBe("2:30 PM");
+    expect(formatTimeOfDay("14:30:00", enUS)).toBe("2:30 PM");
+  });
+
+  it("passes unparseable strings through and renders empty input empty", () => {
+    expect(formatTimeOfDay("later", enUS)).toBe("later");
+    expect(formatTimeOfDay(null, enUS)).toBe("");
+  });
+});
+
+describe("calendar chrome registers", () => {
+  it("speaks a long day name for headers and accessible names", () => {
+    expect(formatDayLong(new Date(2026, 2, 10), enUS)).toBe("Tuesday, March 10");
+    expect(formatDayLong(new Date(2026, 2, 10), { ...enUS, weekday: false })).toBe("March 10");
+    expect(formatDayLong(new Date(2026, 2, 10), { ...enUS, year: true })).toBe(
+      "Tuesday, March 10, 2026",
+    );
+  });
+
+  it("names months and weekdays for calendar grids", () => {
+    expect(getMonthNames(enUS)[0]).toBe("January");
+    expect(getMonthNames({ ...enUS, style: "short" })[2]).toBe("Mar");
+    expect(getWeekdayNames(enUS)).toEqual(["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]);
+    expect(getWeekdayNames({ ...enUS, firstDay: 1 })[0]).toBe("Mon");
+  });
+});
+
+describe("axis-tick registers", () => {
+  it("drops the year entirely so ticks keep a stable width", () => {
+    expect(formatAbsoluteDate(new Date(2025, 2, 10), { ...enUS, now, year: "never" })).toBe(
+      "Mar 10",
+    );
+  });
+
+  it("renders month-year and day-of-month ticks", () => {
+    expect(formatMonthYear(new Date(2026, 2, 10), enUS)).toBe("Mar 2026");
+    expect(formatMonthYear(new Date(2026, 2, 10), { ...enUS, month: "long" })).toBe("March 2026");
+    expect(formatDayOfMonth(new Date(2026, 2, 10), enUS)).toBe("10");
+  });
+});
+
+// Spans UTC, two negative offsets and the far positive extreme (UTC+14), so a
+// parse that leans on the host zone fails somewhere in this list.
+const ZONES = ["UTC", "America/Los_Angeles", "America/New_York", "Pacific/Kiritimati"] as const;
+
+function inZone<T>(timeZone: string, read: () => T): T {
+  const previous = process.env.TZ;
+  process.env.TZ = timeZone;
+  try {
+    return read();
+  } finally {
+    if (previous === undefined) delete process.env.TZ;
+    else process.env.TZ = previous;
+  }
+}
+
+/**
+ * Local wall-clock reading of a parse, taken INSIDE the zone — a Date is an
+ * instant, so its day and hour only mean something against an ambient zone.
+ */
+function readLocal(timeZone: string, value: DateInput) {
+  return inZone(timeZone, () => {
+    const date = parseCalendarDate(value);
+    if (!date) return null;
+    const pad = (n: number) => String(n).padStart(2, "0");
+    return {
+      day: `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+      clock: `${pad(date.getHours())}:${pad(date.getMinutes())}`,
+    };
+  });
+}
+
+describe("parseCalendarDate (day-grid parse)", () => {
+  it("reads a date-only string as the same calendar day in every timezone", () => {
+    for (const timeZone of ZONES) {
+      expect({ timeZone, ...readLocal(timeZone, "2026-03-10") }).toEqual({
+        timeZone,
+        day: "2026-03-10",
+        // Local midnight, which is what day-grid math tests for: Gantt's
+        // normalizeSpanEdges only grants a date-only end its inclusive last
+        // day when the edge sits exactly on midnight.
+        clock: "00:00",
+      });
+    }
+  });
+
+  it("guards the ECMA-262 default this exists to avoid", () => {
+    // `new Date("YYYY-MM-DD")` is UTC midnight, so the naive parse names the
+    // previous day west of UTC. If this ever stops shifting, the test above
+    // has stopped proving anything.
+    const naive = inZone("America/Los_Angeles", () => new Date("2026-03-10").getDate());
+    expect(naive).toBe(9);
+  });
+
+  it("keeps the timezone-aware parse for values that carry a time", () => {
+    for (const timeZone of ZONES) {
+      // No offset in the string — a local wall-clock reading, unchanged.
+      expect(readLocal(timeZone, "2026-03-10 14:30:00")).toEqual({
+        day: "2026-03-10",
+        clock: "14:30",
+      });
+    }
+    // An explicit offset names one instant, which lands on different local
+    // days by design — genuine datetime semantics are untouched.
+    expect(readLocal("UTC", "2026-03-10T00:00:00Z")).toEqual({ day: "2026-03-10", clock: "00:00" });
+    expect(readLocal("America/Los_Angeles", "2026-03-10T00:00:00Z")).toEqual({
+      day: "2026-03-09",
+      clock: "17:00", // PDT — March 10 is past the 2026 DST switch
+    });
+  });
+
+  it("passes Date instances and epoch millis through untouched", () => {
+    const instance = new Date(2026, 2, 10, 9, 15);
+    expect(parseCalendarDate(instance)).toBe(instance);
+    expect(parseCalendarDate(Date.UTC(2026, 2, 10))?.toISOString()).toBe(
+      "2026-03-10T00:00:00.000Z",
+    );
+  });
+
+  it("returns null for empty, unparseable and out-of-range input", () => {
+    expect(parseCalendarDate(null)).toBeNull();
+    expect(parseCalendarDate(undefined)).toBeNull();
+    expect(parseCalendarDate("")).toBeNull();
+    expect(parseCalendarDate("not-a-date")).toBeNull();
+    expect(parseCalendarDate(new Date("nonsense"))).toBeNull();
+    // Rolled over rather than rejected would silently render April 14.
+    expect(parseCalendarDate("2026-13-45")).toBeNull();
+    expect(parseCalendarDate("2026-02-30")).toBeNull();
+  });
+
+  it("keeps a two-digit-looking year literal instead of mapping it to 19xx", () => {
+    expect(inZone("UTC", () => parseCalendarDate("0050-03-10")?.getFullYear())).toBe(50);
+  });
+});

package/src/dates.ts

@@ -65,6 +65,43 @@ function coerceDateInput(value: DateInput): CoercedDate | null {
   return Number.isNaN(date.getTime()) ? null : { date, dateOnly: false };
 }
 
+/**
+ * Parse a date value onto the LOCAL calendar day it names — the canonical
+ * parse for anything that will be positioned on a day grid (calendar cells,
+ * Gantt bars, date axes) rather than merely formatted.
+ *
+ * A date-only string ("YYYY-MM-DD") is a calendar date carrying no timezone,
+ * which is how Frappe sends `Date` fields. ECMA-262 parses that form as UTC
+ * midnight, so every zone west of UTC reads it as the *previous* local day,
+ * and no zone but UTC lands it on the local midnight that day-grid math tests
+ * for. Those are built from local parts instead.
+ *
+ * Values that carry a time ("YYYY-MM-DD HH:MM:SS", ISO with an offset, epoch
+ * millis) are genuine instants and keep the timezone-aware parse untouched.
+ *
+ * Returns null for empty and unparseable input, and for out-of-range parts
+ * ("2026-13-45") rather than silently rolling them into the next month.
+ */
+export function parseCalendarDate(value: DateInput): Date | null {
+  if (value == null || value === "") return null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === "number") {
+    const fromEpoch = new Date(value);
+    return Number.isNaN(fromEpoch.getTime()) ? null : fromEpoch;
+  }
+  const trimmed = value.trim();
+  if (ISO_DATE_ONLY.test(trimmed)) {
+    const [year, month, day] = trimmed.split("-").map(Number);
+    const date = new Date(year, month - 1, day);
+    // `new Date(50, …)` means 1950 — pin the year the string actually named.
+    if (year < 100) date.setFullYear(year);
+    if (date.getMonth() !== month - 1 || date.getDate() !== day) return null;
+    return date;
+  }
+  const parsed = new Date(trimmed.replace(" ", "T"));
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
 /**
  * Compact absolute date — the house register for every absolute date.
  * "Jul 1" / "Jul 1, 2025" (year auto-elided when current), or with

package/src/devWarn.ts

@@ -32,6 +32,42 @@ export type DevWarnDetail = {
   [key: string]: unknown;
 };
 
+/**
+ * LC-57 GUARDRAIL-CLEAN-STORIES allowlist entry, declared as a Storybook story
+ * parameter (`parameters.guardrailSpecimen`).
+ *
+ * Catalog stories emit zero `[theme]` guardrail warnings at rest. A story whose
+ * whole purpose is to demonstrate the warned state (a disabled-dial specimen, a
+ * pager boundary case) is allowlisted by declaring itself:
+ *
+ * ```ts
+ * export const Disabled: Story = {
+ *   parameters: {
+ *     guardrailSpecimen: {
+ *       warns: ["bare-disabled"],
+ *       reason: "Demonstrates the disabled dial; Stepper has no disabledReason plumbing.",
+ *     } satisfies GuardrailSpecimenParameter,
+ *   },
+ * };
+ * ```
+ *
+ * Semantics, pinned:
+ * - `warns` is the CLOSED set of codes the story may emit at rest. An emitted
+ *   code outside the set still FAILs the story.
+ * - A declared code that happens not to fire passes — component improvements
+ *   must never break an allowlist entry.
+ * - The declaration NEVER suppresses the console warning — the warn still
+ *   fires; only the warn-harvester tolerates it (explicit, never tacit).
+ * - Harvesters (`p-results/story-hygiene/verify.mjs`) read this parameter off
+ *   the rendered story and fail CLOSED when parameters cannot be read at all.
+ */
+export type GuardrailSpecimenParameter = {
+  /** Warn codes this story may emit at rest — a closed set, not a wildcard. */
+  warns: DevWarnCode[];
+  /** Why the warned state is the story's subject (recorded per LC-57). */
+  reason: string;
+};
+
 const seen = new Set<string>();
 
 function isDev(): boolean {

package/src/numbers.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { formatCurrency, formatNumber, formatPercent, resolveCurrencyCode } from "./numbers";
+
+// Pin locale so assertions don't depend on the host machine.
+const enUS = { locale: "en-US" } as const;
+
+describe("formatNumber (LC-12 cardinal register)", () => {
+  it("groups thousands — the aggregate that used to render raw", () => {
+    expect(formatNumber(15400, enUS)).toBe("15,400");
+    expect(formatNumber(1234567, enUS)).toBe("1,234,567");
+  });
+
+  it("keeps up to two fraction digits without inventing any", () => {
+    expect(formatNumber(5133.33, enUS)).toBe("5,133.33");
+    expect(formatNumber(5133.3, enUS)).toBe("5,133.3");
+    expect(formatNumber(5133, enUS)).toBe("5,133");
+    expect(formatNumber(5133.336, enUS)).toBe("5,133.34");
+  });
+
+  it("pins fraction digits with precision (fixed-precision columns)", () => {
+    expect(formatNumber(15400, { ...enUS, precision: 2 })).toBe("15,400.00");
+    expect(formatNumber(15400.6, { ...enUS, precision: 0 })).toBe("15,401");
+  });
+
+  it("honours a wider maximum for report floats", () => {
+    expect(formatNumber(3.14159, { ...enUS, maximumFractionDigits: 4 })).toBe("3.1416");
+  });
+
+  it("can drop grouping when a caller owns the layout", () => {
+    expect(formatNumber(15400, { ...enUS, grouping: false })).toBe("15400");
+  });
+
+  it("coerces numeric strings — wire values still reach the register", () => {
+    expect(formatNumber("15400", enUS)).toBe("15,400");
+  });
+
+  it("renders empty input as empty and passes unparseable text through", () => {
+    expect(formatNumber(null, enUS)).toBe("");
+    expect(formatNumber(undefined, enUS)).toBe("");
+    expect(formatNumber("", enUS)).toBe("");
+    expect(formatNumber("n/a", enUS)).toBe("n/a");
+    expect(formatNumber(Number.NaN, enUS)).toBe("");
+  });
+});
+
+describe("formatCurrency (LC-12 money register)", () => {
+  it("defaults to two fraction digits so a money column stays aligned", () => {
+    expect(formatCurrency(15400, enUS)).toBe("15,400.00");
+    expect(formatCurrency(15400, { ...enUS, symbol: "$" })).toBe("$15,400.00");
+  });
+
+  it("elides a whole-value .00 in the summary-tile variant", () => {
+    expect(formatCurrency(48250, { ...enUS, symbol: "$", fractionDigits: "auto" })).toBe("$48,250");
+  });
+
+  it("still shows cents in the summary variant when the value has them", () => {
+    expect(formatCurrency(48250.5, { ...enUS, symbol: "$", fractionDigits: "auto" })).toBe(
+      "$48,250.50",
+    );
+  });
+
+  it("renders an ISO code through the currency's own symbol placement", () => {
+    expect(formatCurrency(15400, { ...enUS, currency: "USD" })).toBe("$15,400.00");
+    expect(formatCurrency(15400, { ...enUS, currency: "EUR" })).toBe("€15,400.00");
+  });
+
+  it("resolves a known symbol to its code, prefixes an unknown one", () => {
+    expect(formatCurrency(1500, { ...enUS, symbol: "₹" })).toBe("₹1,500.00");
+    expect(formatCurrency(1500, { ...enUS, symbol: "¤" })).toBe("¤1,500.00");
+  });
+
+  it("keeps the grouped register when a bad code makes Intl throw", () => {
+    // A Frappe field can hand over a malformed code; the money register must
+    // still group ("EUROS1,500.00", never a bare "1500").
+    expect(formatCurrency(1500, { ...enUS, currency: "EUROS" })).toBe("EUROS1,500.00");
+  });
+
+  it("honours an explicit precision from a Frappe field", () => {
+    expect(formatCurrency(1500.456, { ...enUS, symbol: "$", precision: 3 })).toBe("$1,500.456");
+  });
+
+  it("renders empty input as empty", () => {
+    expect(formatCurrency(null, enUS)).toBe("");
+    expect(formatCurrency("", { ...enUS, symbol: "$" })).toBe("");
+  });
+});
+
+describe("formatPercent (LC-12 rate register)", () => {
+  it("takes percent units, not a ratio", () => {
+    expect(formatPercent(94.2, enUS)).toBe("94.2%");
+    expect(formatPercent(3, enUS)).toBe("3%");
+  });
+
+  it("pins report precision", () => {
+    expect(formatPercent(94.25, { ...enUS, precision: 1 })).toBe("94.3%");
+  });
+
+  it("renders empty input as empty", () => {
+    expect(formatPercent(null, enUS)).toBe("");
+  });
+});
+
+describe("resolveCurrencyCode", () => {
+  it("maps the common symbols and passes codes through", () => {
+    expect(resolveCurrencyCode("$")).toBe("USD");
+    expect(resolveCurrencyCode("₹")).toBe("INR");
+    expect(resolveCurrencyCode("eur")).toBe("EUR");
+    expect(resolveCurrencyCode("R$")).toBe("BRL");
+    expect(resolveCurrencyCode("¤")).toBeUndefined();
+    expect(resolveCurrencyCode(undefined)).toBeUndefined();
+  });
+});

package/src/numbers.ts

@@ -62,6 +62,8 @@ const CURRENCY_SYMBOL_TO_CODE: Record<string, string> = {
   "¥": "JPY",
   "₹": "INR",
   "₩": "KRW",
+  "₽": "RUB",
+  R$: "BRL",
 };
 
 /**
@@ -85,10 +87,9 @@ function coerceNumberInput(value: NumberInput): CoercedNumber | null {
   return Number.isFinite(num) ? { num } : null;
 }
 
-function resolveDigits(options: NumberFormatOptions): Pick<
-  Intl.NumberFormatOptions,
-  "minimumFractionDigits" | "maximumFractionDigits"
-> {
+function resolveDigits(
+  options: NumberFormatOptions,
+): Pick<Intl.NumberFormatOptions, "minimumFractionDigits" | "maximumFractionDigits"> {
   const { precision, minimumFractionDigits, maximumFractionDigits } = options;
   if (precision != null) {
     return { minimumFractionDigits: precision, maximumFractionDigits: precision };
@@ -98,14 +99,22 @@ function resolveDigits(options: NumberFormatOptions): Pick<
   return { minimumFractionDigits: min, maximumFractionDigits: Math.max(min, max) };
 }
 
-function formatWith(num: number, options: Intl.NumberFormatOptions, locale?: string): string {
+function tryFormatWith(
+  num: number,
+  options: Intl.NumberFormatOptions,
+  locale?: string,
+): string | null {
   try {
     return new Intl.NumberFormat(locale, options).format(num);
   } catch {
-    return String(num);
+    return null;
   }
 }
 
+function formatWith(num: number, options: Intl.NumberFormatOptions, locale?: string): string {
+  return tryFormatWith(num, options, locale) ?? String(num);
+}
+
 /**
  * Cardinal / aggregate register — grouped digits, at most two fraction
  * digits ("15,400", "5,133.33"). Empty input renders "" and an unparseable
@@ -143,10 +152,19 @@ export function formatCurrency(value: NumberInput, options: CurrencyFormatOption
   const code = currency ?? resolveCurrencyCode(symbol);
   const useGrouping = grouping ?? true;
   if (code) {
-    return formatWith(coerced.num, { ...digits, useGrouping, style: "currency", currency: code }, locale);
+    // A malformed code from a Frappe field must not cost the whole money
+    // register: fall back to the grouped register with the label prefixed
+    // rather than letting Intl's throw leak a bare `String(num)`.
+    const styled = tryFormatWith(
+      coerced.num,
+      { ...digits, useGrouping, style: "currency", currency: code },
+      locale,
+    );
+    if (styled != null) return styled;
   }
   const amount = formatWith(coerced.num, { ...digits, useGrouping }, locale);
-  return symbol ? `${symbol}${amount}` : amount;
+  const label = symbol ?? currency;
+  return label ? `${label}${amount}` : amount;
 }
 
 /**

package/src/theme/cookies.spec.ts

@@ -104,6 +104,85 @@ describe("readOverridesCookie", () => {
   });
 });
 
+// Regression: react-cookie's jar (universal-cookie) auto-JSON-parses every
+// cookie value it can, so the KnobBridge/useTheme read path receives
+// already-parsed OBJECTS — the old reader joined them into "[object Object]",
+// JSON.parse threw, and overrides silently resolved to {} app-wide.
+describe("readOverridesCookie with universal-cookie auto-parsed values", () => {
+  it("accepts an already-parsed object cookie value (universal-cookie shape)", () => {
+    const overrides: Partial<Knobs> = { borderRadius: "none", space: "small" };
+    expect(readOverridesCookie({ "mp.ov.0": overrides })).toEqual(overrides);
+  });
+
+  it("accepts a raw JSON string cookie value (document.cookie / SSR shape)", () => {
+    const overrides: Partial<Knobs> = { borderRadius: "none", space: "small" };
+    expect(readOverridesCookie({ "mp.ov.0": JSON.stringify(overrides) })).toEqual(overrides);
+  });
+
+  it("preserves nested interaction-state overrides from a parsed object", () => {
+    const overrides: Partial<Knobs> = { hover: { elevation: "large" } };
+    expect(readOverridesCookie({ "mp.ov.0": overrides })).toEqual(overrides);
+  });
+
+  it("round-trips writeOverridesCookie output through an auto-parsing jar", () => {
+    const overrides: Partial<Knobs> = { density: "compact", fillStyle: "outlined" };
+    const { toSet } = writeOverridesCookie(overrides);
+    // Simulate universal-cookie readCookie: JSON.parse succeeds on the
+    // single-chunk value, so the jar hands back an object.
+    const jar = Object.fromEntries(toSet.map(({ key, value }) => [key, JSON.parse(value)]));
+    expect(readOverridesCookie(jar)).toEqual(overrides);
+  });
+
+  it("round-trips oversized multi-chunk payloads through an auto-parsing jar", () => {
+    const bigValue = "x".repeat(8000);
+    const overrides = { animation: bigValue } as unknown as Partial<Knobs>;
+    const { toSet } = writeOverridesCookie(overrides);
+    expect(toSet.length).toBeGreaterThan(1);
+    // universal-cookie leaves each chunk a string: a JSON fragment throws in
+    // its JSON.parse attempt, so readCookie falls back to the raw value.
+    const jar = Object.fromEntries(
+      toSet.map(({ key, value }) => {
+        try {
+          return [key, JSON.parse(value)];
+        } catch {
+          return [key, value];
+        }
+      }),
+    );
+    expect(readOverridesCookie(jar)).toEqual(overrides);
+  });
+
+  it("returns safe empty for garbage values", () => {
+    expect(readOverridesCookie({ "mp.ov.0": 42 })).toEqual({});
+    expect(readOverridesCookie({ "mp.ov.0": true })).toEqual({});
+    expect(readOverridesCookie({ "mp.ov.0": ["not", "overrides"] })).toEqual({});
+    expect(readOverridesCookie({ "mp.ov.0": "not{valid json" })).toEqual({});
+    expect(readOverridesCookie({ "mp.ov.0": "[object Object]" })).toEqual({});
+  });
+
+  it("returns safe empty for mixed chunk types (object followed by string)", () => {
+    expect(
+      readOverridesCookie({
+        "mp.ov.0": { borderRadius: "none" },
+        "mp.ov.1": '{"space":"small"}',
+      }),
+    ).toEqual({});
+  });
+
+  it("drops non-knob-shaped entries inside a parsed object", () => {
+    expect(
+      readOverridesCookie({
+        "mp.ov.0": {
+          borderRadius: "none",
+          count: 3,
+          list: ["a"],
+          hover: { elevation: "large", depth: { nested: true } },
+        },
+      }),
+    ).toEqual({ borderRadius: "none", hover: { elevation: "large" } });
+  });
+});
+
 describe("readPresetCookie", () => {
   it("returns undefined when cookie is missing", () => {
     expect(readPresetCookie({})).toBeUndefined();
@@ -116,6 +195,11 @@ describe("readPresetCookie", () => {
   it("returns the preset name", () => {
     expect(readPresetCookie({ [cookiePreset]: "dark-mode" })).toBe("dark-mode");
   });
+
+  it("returns undefined for non-string jar values (universal-cookie auto-parse)", () => {
+    expect(readPresetCookie({ [cookiePreset]: 123 })).toBeUndefined();
+    expect(readPresetCookie({ [cookiePreset]: { nested: true } })).toBeUndefined();
+  });
 });
 
 describe("writePresetCookie", () => {

package/src/theme/cookies.ts

@@ -69,34 +69,82 @@ function chunkKey(index: number): string {
 // Cookie read helpers (work with raw cookie objects from react-cookie)
 // ---------------------------------------------------------------------------
 
+/**
+ * Shape-validate a parsed overrides payload before it reaches knob
+ * resolution: keep knob-shaped entries — string values plus one-level
+ * StateKnobs-style objects of string values (`hover`, `press`, …) — and drop
+ * everything else, so a corrupt or foreign cookie can never spread garbage
+ * (arrays, numbers, deep objects) into `{ ...preset.knobs, ...overrides }`.
+ */
+function sanitizeOverrides(parsed: unknown): Partial<Knobs> {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {};
+  }
+  const overrides: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value === "string") {
+      overrides[key] = value;
+    } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const nested: Record<string, string> = {};
+      for (const [stateKey, stateValue] of Object.entries(value)) {
+        if (typeof stateValue === "string") nested[stateKey] = stateValue;
+      }
+      overrides[key] = nested;
+    }
+  }
+  return overrides as Partial<Knobs>;
+}
+
 /**
  * Read the overrides cookie value, handling chunked cookies.
- * Accepts the cookies object from `useCookies()`.
+ *
+ * Accepts BOTH value shapes a cookie jar can deliver:
+ *   - already-parsed OBJECTS — react-cookie's `useCookies()` jar
+ *     (universal-cookie) auto-JSON-parses every cookie value it can (its
+ *     `readCookie` tries `JSON.parse` unless `doNotParse` is set), so a
+ *     single-chunk overrides cookie arrives here as an object, not a string;
+ *   - raw JSON STRINGS — direct `document.cookie` / SSR cookie-header reads
+ *     (`loadPresetOverrides`), and multi-chunk payloads on every path (a
+ *     fragment of a split JSON document does not parse on its own, so even
+ *     universal-cookie leaves those chunks as strings).
+ *
+ * Anything else (numbers, arrays, mixed chunk types, malformed JSON) reads
+ * as no overrides, and every parsed payload is shape-validated before use.
  */
-export function readOverridesCookie(cookies: Record<string, string | undefined>): Partial<Knobs> {
+export function readOverridesCookie(cookies: Record<string, unknown>): Partial<Knobs> {
   // Reconstruct from chunked cookies: mp.ov.0, mp.ov.1, …
-  const chunks: string[] = [];
+  const chunks: unknown[] = [];
   for (let i = 0; i < maxChunks; i++) {
     const chunk = cookies[chunkKey(i)];
     if (!chunk) break;
     chunks.push(chunk);
   }
-  if (chunks.length > 0) {
-    try {
-      return JSON.parse(joinSplitCookieValues(chunks));
-    } catch {
-      return {};
-    }
+  if (chunks.length === 0) return {};
+
+  // universal-cookie path: the jar already parsed the JSON for us.
+  if (chunks.length === 1 && typeof chunks[0] === "object") {
+    return sanitizeOverrides(chunks[0]);
   }
 
-  return {};
+  // Raw string path: join chunks and parse the canonical JSON serialization.
+  if (!chunks.every((chunk): chunk is string => typeof chunk === "string")) {
+    return {};
+  }
+  try {
+    return sanitizeOverrides(JSON.parse(joinSplitCookieValues(chunks)));
+  } catch {
+    return {};
+  }
 }
 
 /**
- * Read the preset name from the cookie.
+ * Read the preset name from the cookie. universal-cookie auto-JSON-parses
+ * jar values, so a numeric-looking name would arrive as a number — preset
+ * names are strings by contract, anything else reads as no preset.
  */
-export function readPresetCookie(cookies: Record<string, string | undefined>): string | undefined {
-  return cookies[cookiePreset] || undefined;
+export function readPresetCookie(cookies: Record<string, unknown>): string | undefined {
+  const value = cookies[cookiePreset];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
 // ---------------------------------------------------------------------------

package/src/theme/index.ts

@@ -18,6 +18,7 @@ export * from "./Preset";
 export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
 export * from "./PresetContext";
 export * from "./presets";
+export * from "./radiusClass";
 export * from "./readableColor";
 export * from "./recipes";
 export * from "./resolveKnobs";