@multiplatform.one/theme 7.34.3 → 7.35.0

package/src/theme/useResolvedKnobs.ts

@@ -4,15 +4,10 @@ import { useTouchSurface } from "./useTouchSurface";
 import { defaultKnobs, type Knobs } from "./knobs";
 import type { IntentOverride } from "./preset.types";
 import type { KnobPropsOverride, ResolvedKnobs } from "./recipes";
-import { applyDensity, compactSpaceMap, resolveKnobs } from "./resolveKnobs";
+import { resolveKnobs } from "./resolveKnobs";
 import { usePresetContext } from "./PresetContext";
 import { defaultIntents } from "./intents";
-import {
-  clampSurfaceDensity,
-  clampSurfaceSize,
-  SurfaceContext,
-  type SurfaceIntent,
-} from "./Surface";
+import { clampSurfaceSize, SurfaceContext } from "./Surface";
 
 export const IntentContext = createContext<string | null>(null);
 
@@ -46,61 +41,23 @@ function usePrefersReducedMotion(): boolean {
   return useSyncExternalStore(subscribeReducedMotion, readReducedMotion, serverReducedMotion);
 }
 
-function applySurfaceToKnobs(
-  knobs: Knobs,
-  surface: SurfaceIntent,
-  opts: { sizeOverride: boolean; densityOverride: boolean },
-): Knobs {
-  let next = knobs;
-  if (surface.size !== "unset") {
-    if (!opts.sizeOverride) {
-      next = { ...next, size: surface.size };
-    } else {
-      const size = clampSurfaceSize(next.size, surface.size);
-      if (size !== "unset" && size !== next.size) {
-        next = { ...next, size };
-      }
-    }
-  }
-  if (surface.density !== "unset") {
-    if (!opts.densityOverride) {
-      next = { ...next, density: surface.density };
-    } else {
-      const density = clampSurfaceDensity(next.density, surface.density);
-      if (density !== "unset" && density !== next.density) {
-        next = { ...next, density };
-      }
-    }
-  }
-  return next;
-}
-
 export interface UseResolvedKnobsOptions {
   intent?: string;
   component?: string;
   override?: KnobPropsOverride;
-  /** Override the size from knobs */
+  /**
+   * The control size token (Tamagui's own `size`, "$3"). Clamped to the
+   * nearest `<Surface size>` ceiling (LC-78); omitted = the Surface's token,
+   * else `$true`.
+   */
   size?: SizeTokens;
   /**
-   * Density-compact override (layout gaps only — does not step size).
-   * When set, wins over `knobs.density`:
-   * `true` forces compact density; `false` forces comfortable.
-   * Then re-clamped to the parent Surface ceiling (LC-68).
-   * When omitted, the density knob / Surface controls compact vs comfortable.
+   * Whether an ancestor already paints a surface box. Omitted = the nearest
+   * `<Surface painted>`; overlay frames pass `false` because they float.
    */
-  compact?: boolean;
+  painted?: boolean;
 }
 
-const sizeTokenToKnobSize: Record<string, Knobs["size"]> = {
-  $1: "small",
-  $2: "small",
-  $3: "small",
-  $4: "medium",
-  $5: "large",
-  $6: "large",
-  $true: "medium",
-};
-
 export const solidButtonIntents = new Set(["error", "warning", "success"]);
 
 /**
@@ -118,12 +75,11 @@ export const solidPaletteThemes = new Set(["accent"]);
  *   1. Base knobs from nearest <Preset> context
  *   2. Merge intent-level overrides (if intent provided or from context)
  *   3. Merge intent+component overrides (if both provided)
- *   4. Apply size override if provided
- *   5. Clamp size/density to Surface context (step-down only, LC-68)
- *   6. Apply density (space only; compact option wins when provided)
- *   7. Re-clamp to Surface ceiling (compact option cannot exceed parent)
- *   8. OS reduced-motion forces animation="none"
- *   9. Call resolveKnobs(mergedKnobs, override, scheme) — override merges last
+ *   4. Size token: the `size` option clamped to the Surface ceiling (LC-78);
+ *      `painted` from the option, else the Surface
+ *   5. OS reduced-motion forces animation="none"
+ *   6. Call resolveKnobs(mergedKnobs, override, scheme, { touch, sizeToken, painted })
+ *      — override merges last
  */
 export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKnobs {
   const touch = useTouchSurface();
@@ -134,13 +90,12 @@ export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKno
   const scheme = themeName?.startsWith("dark") ? "dark" : "light";
   const surfaceCtx = SurfaceContext.useStyledContext();
   const surfaceSize = surfaceCtx?.size ?? "unset";
-  const surfaceDensity = surfaceCtx?.density ?? "unset";
+  const painted = options?.painted ?? surfaceCtx?.painted ?? false;
 
   const intent = options?.intent ?? contextIntent ?? undefined;
   const component = options?.component;
   const override = options?.override;
   const sizeOverride = options?.size;
-  const compact = options?.compact;
 
   return useMemo(() => {
     const baseKnobs: Knobs = presetCtx
@@ -171,37 +126,16 @@ export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKno
       }
     }
 
-    if (sizeOverride) {
-      const sizeStr = String(sizeOverride);
-      const knobSize = sizeTokenToKnobSize[sizeStr];
-      if (knobSize) {
-        merged = { ...merged, size: knobSize };
-      }
-    }
-
-    const surfaceIntent: SurfaceIntent = { size: surfaceSize, density: surfaceDensity };
-    merged = applySurfaceToKnobs(merged, surfaceIntent, {
-      sizeOverride: Boolean(sizeOverride),
-      densityOverride: compact !== undefined,
-    });
-
-    const spaceBeforeDensity = merged.space;
-    merged = applyDensity(merged, compact);
-    merged = applySurfaceToKnobs(merged, surfaceIntent, {
-      sizeOverride: true,
-      densityOverride: true,
-    });
-    if (merged.density === "compact") {
-      merged = { ...merged, space: compactSpaceMap[spaceBeforeDensity] };
-    } else {
-      merged = { ...merged, space: spaceBeforeDensity };
-    }
-
     if (prefersReducedMotion) {
       merged = { ...merged, animation: "none" };
     }
 
-    const resolved = resolveKnobs(merged, override, scheme, { touch });
+    const sizeToken = clampSurfaceSize(sizeOverride ?? "unset", surfaceSize);
+    const resolved = resolveKnobs(merged, override, scheme, {
+      touch,
+      sizeToken: sizeToken === "unset" ? undefined : String(sizeToken),
+      painted,
+    });
 
     if (intent && component === "Button" && solidButtonIntents.has(intent)) {
       const labelColor = merged.fillStyle === "filled" ? "$color" : "$color11";
@@ -221,10 +155,9 @@ export function useResolvedKnobs(options?: UseResolvedKnobsOptions): ResolvedKno
     component,
     override,
     sizeOverride,
-    compact,
     prefersReducedMotion,
     surfaceSize,
-    surfaceDensity,
+    painted,
     scheme,
     touch,
   ]);

package/src/theme/useResolvedKnobsBehavior.spec.tsx

@@ -1,8 +1,8 @@
 import { TestProviders } from "@multiplatform.one/test-utils";
 /**
  * useResolvedKnobs behavior specs — the resolution rules consumers feel but
- * that aren't covered by the pure resolveKnobs specs: Tamagui size-token →
- * knob-size mapping, OS reduced-motion forcing animation off, the legacy
+ * that aren't covered by the pure resolveKnobs specs: the Tamagui size token
+ * passing through as the control token, OS reduced-motion forcing animation off, the legacy
  * addListener matchMedia branch, and the semantic-intent Button label color
  * rule (filled binds $color, outlined pins $color11).
  */
@@ -79,22 +79,23 @@ function makePreset(overrides: Partial<PresetType> = {}): PresetType {
   };
 }
 
-describe("size token mapping", () => {
-  it.each([
-    ["$1", "small"],
-    ["$3", "small"],
-    ["$4", "medium"],
-    ["$5", "large"],
-    ["$6", "large"],
-    ["$true", "medium"],
-  ] as const)("maps Tamagui size %s to knob size %s", (token, expected) => {
-    const { result } = renderHook(() => useResolvedKnobs({ size: token as never }));
-    expect(result.current.knobProps.size).toBe(expected);
+describe("size token", () => {
+  it.each(["$1", "$2", "$3", "$4", "$5", "$6", "$true"] as const)(
+    "the Tamagui size %s is the control token, unmapped",
+    (token) => {
+      const { result } = renderHook(() => useResolvedKnobs({ size: token }));
+      expect(result.current.knobProps.sizeToken).toBe(token);
+    },
+  );
+
+  it("defaults to $true with no size option and no Surface", () => {
+    const { result } = renderHook(() => useResolvedKnobs());
+    expect(result.current.knobProps.sizeToken).toBe("$true");
   });
 
-  it("keeps the knob size for unmapped tokens", () => {
-    const { result } = renderHook(() => useResolvedKnobs({ size: "$11" as never }));
-    expect(result.current.knobProps.size).toBe(defaultKnobs.size);
+  it("a numeric size is not a token and resolves $true", () => {
+    const { result } = renderHook(() => useResolvedKnobs({ size: 40 as never }));
+    expect(result.current.knobProps.sizeToken).toBe("$true");
   });
 });
 
@@ -176,19 +177,13 @@ describe("intent + component knob merging", () => {
     );
   });
 
-  it("compact option does not shrink size; it shrinks gap and sets density compact", () => {
-    const comfortable = renderHook(() => useResolvedKnobs());
-    const compact = renderHook(() => useResolvedKnobs({ compact: true }));
-    expect(comfortable.result.current.knobProps.size).toBe("medium");
-    expect(compact.result.current.knobProps.size).toBe("medium");
-    expect(compact.result.current.knobProps.sizeToken).toBe(
-      comfortable.result.current.knobProps.sizeToken,
-    );
-    expect(compact.result.current.knobProps.control.height).toBe(
-      comfortable.result.current.knobProps.control.height,
-    );
-    expect(compact.result.current.knobProps.density).toBe("compact");
-    expect(comfortable.result.current.knobProps.gap).toEqual({ gap: "$4" });
-    expect(compact.result.current.knobProps.gap).toEqual({ gap: "$2" });
+  it("the options carry no compact switch: a smaller size token is the only per-site control", () => {
+    const options: Parameters<typeof useResolvedKnobs>[0] = {
+      // @ts-expect-error density is folded into the preset's token scale
+      compact: true,
+    };
+    const { result } = renderHook(() => useResolvedKnobs(options));
+    expect(result.current.knobProps.gap).toEqual({ gap: "$3" });
+    expect(result.current.knobProps).not.toHaveProperty("density");
   });
 });

package/src/theme/useSchemePreference.native.ts

@@ -0,0 +1,33 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { Appearance, useColorScheme } from "react-native";
+import { useDidFinishSSR } from "tamagui";
+import { isWeb } from "@multiplatform.one/platform";
+import { getStoredScheme, setStoredScheme, subscribeStoredScheme } from "./schemeStore";
+import type { ThemeScheme } from "./useTheme";
+
+export interface SchemePreference {
+  setting: ThemeScheme;
+  value: "light" | "dark";
+  set(scheme: ThemeScheme): void;
+}
+const serverScheme = (): ThemeScheme => "system";
+
+export function useSchemePreference(): SchemePreference {
+  const setting = useSyncExternalStore(subscribeStoredScheme, getStoredScheme, serverScheme);
+  const os = useColorScheme();
+  const hydrated = useDidFinishSSR();
+  useEffect(() => {
+    if (!isWeb) Appearance.setColorScheme(setting === "system" ? "unspecified" : setting);
+  }, [setting]);
+  return {
+    setting: hydrated ? setting : "system",
+    value: !hydrated
+      ? "light"
+      : setting === "system"
+        ? os === "dark"
+          ? "dark"
+          : "light"
+        : setting,
+    set: setStoredScheme,
+  };
+}

package/src/theme/useSchemePreference.spec.tsx

@@ -0,0 +1,51 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useSyncExternalStore } from "react";
+
+const os = vi.hoisted(() => ({
+  value: "light",
+  forced: null as string | null,
+  listeners: new Set<() => void>(),
+}));
+vi.mock("@multiplatform.one/platform", () => ({ isWeb: false }));
+vi.mock("@multiplatform.one/store", () => ({
+  storage: { getItem: () => null, setItem: () => {} },
+}));
+vi.mock("tamagui", () => ({ useDidFinishSSR: () => true }));
+vi.mock("react-native", () => ({
+  useColorScheme: () =>
+    useSyncExternalStore(
+      (l) => {
+        os.listeners.add(l);
+        return () => {
+          os.listeners.delete(l);
+        };
+      },
+      () => os.forced ?? os.value,
+    ),
+  Appearance: {
+    setColorScheme: (value: string | null) => {
+      os.forced = value === "unspecified" ? null : value;
+      os.listeners.forEach((l) => l());
+    },
+  },
+}));
+import { useSchemePreference } from "./useSchemePreference.native";
+afterEach(cleanup);
+
+it("shares selection, clears the native override for System and follows subsequent OS changes", () => {
+  const first = renderHook(useSchemePreference);
+  const second = renderHook(useSchemePreference);
+  act(() => first.result.current.set("dark"));
+  expect(second.result.current.value).toBe("dark");
+  expect(os.forced).toBe("dark");
+  act(() => first.result.current.set("system"));
+  expect(os.forced).toBeNull();
+  expect(second.result.current.value).toBe("light");
+  act(() => {
+    os.value = "dark";
+    os.listeners.forEach((l) => l());
+  });
+  expect(second.result.current.value).toBe("dark");
+  expect(second.result.current.setting).toBe("system");
+});

package/src/theme/useSchemePreference.ts

@@ -0,0 +1,32 @@
+import { useSyncExternalStore } from "react";
+import { useDidFinishSSR } from "tamagui";
+import { getStoredScheme, setStoredScheme, subscribeStoredScheme } from "./schemeStore";
+import type { ThemeScheme } from "./useTheme";
+
+export interface SchemePreference {
+  setting: ThemeScheme;
+  value: "light" | "dark";
+  set(scheme: ThemeScheme): void;
+}
+const serverScheme = (): ThemeScheme => "system";
+const serverDark = () => false;
+const prefersDark = () =>
+  typeof window !== "undefined" &&
+  window.matchMedia?.("(prefers-color-scheme: dark)").matches === true;
+function subscribeOs(listener: () => void) {
+  const query = window.matchMedia?.("(prefers-color-scheme: dark)");
+  if (!query) return () => {};
+  query.addEventListener("change", listener);
+  return () => query.removeEventListener("change", listener);
+}
+
+export function useSchemePreference(): SchemePreference {
+  const setting = useSyncExternalStore(subscribeStoredScheme, getStoredScheme, serverScheme);
+  const dark = useSyncExternalStore(subscribeOs, prefersDark, serverDark);
+  const hydrated = useDidFinishSSR();
+  return {
+    setting: hydrated ? setting : "system",
+    value: !hydrated ? "light" : setting === "system" ? (dark ? "dark" : "light") : setting,
+    set: setStoredScheme,
+  };
+}

package/src/theme/useSchemePreference.web.spec.tsx

@@ -0,0 +1,32 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { useSchemePreference } from "./useSchemePreference";
+import { setStoredScheme } from "./schemeStore";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+it("follows browser OS changes only while System is selected", () => {
+  let dark = false;
+  const listeners = new Set<() => void>();
+  vi.stubGlobal("matchMedia", () => ({
+    get matches() {
+      return dark;
+    },
+    addEventListener: (_event: string, listener: () => void) => listeners.add(listener),
+    removeEventListener: (_event: string, listener: () => void) => listeners.delete(listener),
+  }));
+  setStoredScheme("system");
+  const hook = renderHook(useSchemePreference);
+  expect(hook.result.current.value).toBe("light");
+  act(() => {
+    dark = true;
+    listeners.forEach((l) => l());
+  });
+  expect(hook.result.current.value).toBe("dark");
+  act(() => hook.result.current.set("light"));
+  expect(hook.result.current.value).toBe("light");
+  act(() => hook.result.current.set("system"));
+  expect(hook.result.current.value).toBe("dark");
+});

package/src/theme/useTheme.native.spec.tsx

@@ -0,0 +1,68 @@
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { items } = vi.hoisted(() => ({ items: new Map<string, string>() }));
+vi.mock("@multiplatform.one/store", () => ({
+  storage: {
+    getItem: (key: string) => items.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      items.set(key, value);
+    },
+    removeItem: (key: string) => {
+      items.delete(key);
+    },
+  },
+}));
+
+vi.mock("./shared", async () => {
+  const { densePreset, roomyPreset } = await import("./presets");
+  return {
+    getPreset: (name: string) =>
+      name === "dense" ? densePreset : name === "roomy" ? roomyPreset : undefined,
+  };
+});
+
+beforeEach(() => {
+  items.clear();
+  vi.resetModules();
+});
+afterEach(cleanup);
+
+async function nativeHooks() {
+  const hooks = await import("./useTheme.native");
+  const store = await import("./presetStore");
+  return { ...hooks, ...store };
+}
+
+describe("native useTheme persistence", () => {
+  it("persists the active preset and hydrates it after an in-memory reset", async () => {
+    const first = await nativeHooks();
+    const { result, unmount } = renderHook(() => first.useTheme());
+    act(() => result.current[3]("dense"));
+    await vi.waitFor(() => expect(items.get("mp.preset")).toBe("dense"));
+    expect(result.current[4]).toBe("dense");
+    expect(items.has("mp.preset.by-user")).toBe(false);
+    unmount();
+    vi.resetModules();
+    const fresh = await nativeHooks();
+    await fresh.hydrateStoredPreset();
+    expect(fresh.getStoredPreset()).toEqual({ presetName: "dense", overrides: {}, hydrated: true });
+    expect(renderHook(() => fresh.useTheme()).result.current[4]).toBe("dense");
+  });
+
+  it("records the user's choice only when options are supplied", async () => {
+    const hooks = await nativeHooks();
+    const { result } = renderHook(() => hooks.useTheme());
+    act(() => result.current[3]("roomy", { userId: "u1" }));
+    await vi.waitFor(() => expect(items.get("mp.preset")).toBe("roomy"));
+    expect(hooks.getPresetChoices()).toEqual({ users: { u1: "roomy" }, owner: "u1" });
+    await vi.waitFor(() => expect(items.has("mp.preset.by-user")).toBe(true));
+    expect(JSON.parse(items.get("mp.preset.by-user")!)).toEqual(hooks.getPresetChoices());
+    act(() => result.current[3]("dense", {}));
+    expect(hooks.getPresetChoices()).toEqual({
+      device: "dense",
+      users: { u1: "roomy" },
+      owner: undefined,
+    });
+  });
+});

package/src/theme/useTheme.native.ts

@@ -1,5 +1,13 @@
-import { useCallback, useState } from "react";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { computeOverrides } from "./cookies";
 import { type Knobs, defaultKnobs } from "./knobs";
+import {
+  getStoredPreset,
+  recordPresetChoice,
+  setStoredOverrides,
+  setStoredPreset,
+  subscribeStoredPreset,
+} from "./presetStore";
 import { getPreset } from "./shared";
 
 // ---------------------------------------------------------------------------
@@ -9,41 +17,58 @@ import { getPreset } from "./shared";
 export type ThemeScheme = "system" | "dark" | "light";
 
 // ---------------------------------------------------------------------------
-// useTheme hook — knob-aware (native variant uses local state only, no cookies)
+// useTheme hook — knob-aware (native variant persists through the preset store)
 // ---------------------------------------------------------------------------
 
+/**
+ * Same tuple as the web hook. State lives in the shared preset store
+ * (`presetStore.ts`), persisted to `@multiplatform.one/store` storage under
+ * `mp.preset` / `mp.ov`, so every caller and the ThemeProvider see one preset
+ * and it survives a relaunch. The fourth element switches presets; supplying
+ * options also records the user's (or signed-out device's) choice.
+ */
 export function useTheme(): [
   Knobs,
   (knobs?: Partial<Knobs>) => void,
   boolean,
-  (presetName: string) => void,
+  (presetName: string, options?: { userId?: string | null }) => void,
   string | undefined,
 ] {
-  const [localKnobs, setLocalKnobs] = useState<Knobs>(() => ({ ...defaultKnobs }));
-  const [activePreset, setActivePreset] = useState<string | undefined>(undefined);
-
-  const setKnobs = useCallback((partial?: Partial<Knobs>): void => {
-    if (!partial) return;
-    setLocalKnobs((prev) => {
-      let hasChanges = false;
-      const updated = { ...prev };
+  const stored = useSyncExternalStore(subscribeStoredPreset, getStoredPreset, getStoredPreset);
+  const presetName = stored.presetName;
+  const baseKnobs = (presetName ? getPreset(presetName)?.knobs : undefined) ?? defaultKnobs;
+
+  const knobs = useMemo<Knobs>(
+    () => ({ ...baseKnobs, ...stored.overrides }),
+    [baseKnobs, stored.overrides],
+  );
+
+  const setKnobs = useCallback(
+    (partial?: Partial<Knobs>): void => {
+      if (!partial) return;
+      let changed = false;
+      const next = { ...knobs };
       for (const key of Object.keys(partial) as Array<keyof Knobs>) {
-        const newValue = partial[key];
-        if (newValue !== undefined && newValue !== prev[key]) {
-          (updated as Record<string, unknown>)[key] = newValue;
-          hasChanges = true;
+        const value = partial[key];
+        if (value === undefined) continue;
+        const differs =
+          typeof value === "object" && value !== null
+            ? JSON.stringify(value) !== JSON.stringify(knobs[key])
+            : value !== knobs[key];
+        if (differs) {
+          (next as Record<string, unknown>)[key] = value;
+          changed = true;
         }
       }
-      return hasChanges ? updated : prev;
-    });
-  }, []);
+      if (changed) setStoredOverrides(computeOverrides(baseKnobs, next));
+    },
+    [knobs, baseKnobs],
+  );
 
-  const setPresetFn = useCallback((newPresetName: string) => {
-    const preset = getPreset(newPresetName);
-    const knobs = preset?.knobs ?? defaultKnobs;
-    setActivePreset(newPresetName);
-    setLocalKnobs(knobs);
+  const setPresetFn = useCallback((newPresetName: string, options?: { userId?: string | null }) => {
+    if (options) recordPresetChoice(newPresetName, options.userId);
+    setStoredPreset(newPresetName);
   }, []);
 
-  return [localKnobs, setKnobs, false, setPresetFn, activePreset];
+  return [knobs, setKnobs, presetName != null, setPresetFn, presetName];
 }

package/src/theme/useTheme.ts

@@ -5,11 +5,13 @@ import {
   cookiePreset,
   computeOverrides,
   getCookieWatchList,
+  isKnobKey,
   readOverridesCookie,
   readPresetCookie,
   writeOverridesCookie,
 } from "./cookies";
 import { type Knobs, defaultKnobs } from "./knobs";
+import { recordPresetChoice } from "./presetStore";
 import { getPreset } from "./shared";
 
 // ---------------------------------------------------------------------------
@@ -34,7 +36,7 @@ export type ThemeScheme = "system" | "dark" | "light";
  *   Knobs,                              // resolved knobs
  *   (knobs?: Partial<Knobs>) => void,   // merge partial knob updates
  *   boolean,                            // true if initialized from cookie
- *   (presetName: string) => void,       // switch preset (resets overrides)
+ *   (presetName: string, options?: { userId?: string | null }) => void,       // switch preset; options record a choice
  *   string | undefined,                 // active preset name
  * ]
  * ```
@@ -47,7 +49,7 @@ export function useTheme(): [
   Knobs,
   (knobs?: Partial<Knobs>) => void,
   boolean,
-  (presetName: string) => void,
+  (presetName: string, options?: { userId?: string | null }) => void,
   string | undefined,
 ] {
   const isCookieDisabled =
@@ -132,7 +134,7 @@ export function useTheme(): [
       let hasChanges = false;
       const updated = { ...current };
 
-      for (const key of Object.keys(partial) as Array<keyof Knobs>) {
+      for (const key of Object.keys(partial).filter(isKnobKey)) {
         const newValue = partial[key];
         if (newValue === undefined) continue;
         const oldValue = current[key];
@@ -177,7 +179,8 @@ export function useTheme(): [
   // setPreset — switch the active preset (resets overrides to empty)
   // -------------------------------------------------------------------------
   const setPresetFn = useCallback(
-    (newPresetName: string) => {
+    (newPresetName: string, options?: { userId?: string | null }) => {
+      if (options) recordPresetChoice(newPresetName, options.userId);
       const preset = getPreset(newPresetName);
       const knobs = preset?.knobs ?? defaultKnobs;
 

package/types/audit/constraintAudit.d.ts

@@ -5,7 +5,8 @@
  * Tamagui token steps defined by the knob system. Off-scale values indicate
  * styles that bypassed the constraint system.
  *
- * Token values are from @tamagui/themes v5 + resolveKnobs.ts mappings.
+ * Token values are the active generated scale (`globalThis.__MPO_SCALE__`,
+ * else the default `generateScale`) + resolveKnobs.ts mappings.
  * Run this in-browser via Playwright's page.evaluate(runConstraintAudit).
  */
 export interface PropertyAudit {
@@ -76,13 +77,13 @@ export interface AuditReport {
     elements: ElementAudit[];
 }
 /**
- * Gap (inner spacing) knob → pixel value
- * Source: gapMap in resolveKnobs.ts ($2, $4, $5 space tokens)
+ * Within-group gap roles → pixel value on the scale.
+ * Source: spacingRoles in resolveKnobs.ts (gapSm $2, gap $3).
  */
 export declare const GAP_KNOB: Record<string, number>;
 /**
- * Gap large (gapLg) knob → pixel value
- * Source: gapLgMap in resolveKnobs.ts ($3, $5, $6 space tokens)
+ * Between-groups gap role → pixel value on the scale.
+ * Source: spacingRoles in resolveKnobs.ts (gapLg $5).
  */
 export declare const GAP_LG_KNOB: Record<string, number>;
 /**

package/types/audit/constraintAudit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constraintAudit.d.ts","sourceRoot":"","sources":["../../src/audit/constraintAudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC,oBAAoB,CAAC,EAAE,aAAa,CAAC;IACrC,uBAAuB,CAAC,EAAE,aAAa,CAAC;IACxC,sBAAsB,CAAC,EAAE,aAAa,CAAC;IACvC,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,uCAAuC;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AA6ED;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI9C,CAAC;AAmJF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAguBrE"}
+{"version":3,"file":"constraintAudit.d.ts","sourceRoot":"","sources":["../../src/audit/constraintAudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,mBAAmB,CAAC,EAAE,aAAa,CAAC;IACpC,oBAAoB,CAAC,EAAE,aAAa,CAAC;IACrC,uBAAuB,CAAC,EAAE,aAAa,CAAC;IACxC,sBAAsB,CAAC,EAAE,aAAa,CAAC;IACvC,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,uCAAuC;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AA+DD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE9C,CAAC;AAmJF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CA4vBrE"}