@multiplatform.one/theme 7.11.0 → 7.15.0

package/src/theme/resolveKnobs.spec.ts

@@ -24,6 +24,7 @@ import { defaultPreset, boldPreset, heroPreset } from "./presets";
 import {
   applyDensity,
   capContainerRadius,
+  containerCapProps,
   resolveKnobs,
   resolvePageTitleScale,
 } from "./resolveKnobs";
@@ -224,8 +225,10 @@ describe("resolveKnobs", () => {
       expect(resolveKnobs(knobsWith({ elevation: "none" })).knobProps.elevation).toBeUndefined();
     });
 
-    it('maps "small" → "$1"', () => {
-      expect(resolveKnobs(knobsWith({ elevation: "small" })).knobProps.elevation).toBe("$1");
+    it('maps "small" → undefined: controls paint no resting shadow at the default (MPO-96)', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ elevation: "small" }));
+      expect(knobProps.elevation).toBeUndefined();
+      expect(knobProps.elevationChrome).toEqual({});
     });
 
     it("overlay elevation at small is $2, not the control $1 token", () => {
@@ -250,7 +253,7 @@ describe("resolveKnobs", () => {
       expect(knobProps.cardSurface.backgroundColor).toBe("$background");
       expect(knobProps.inputBackground).toBe("$background");
       expect(knobProps.elevatedSurface.shadowColor).toBe("#000");
-      expect(knobProps.elevatedSurface.shadowOpacity).toBe(0.15);
+      expect(knobProps.elevatedSurface.shadowOpacity).toBe(0.12);
       expect(knobProps.elevationChrome.elevation).toBe(8);
     });
 
@@ -298,7 +301,8 @@ describe("resolveKnobs", () => {
         const small = resolveNative(
           knobsWith({ elevation: "small", hover: { elevation: "medium" } }),
         );
-        expect(small.knobProps.elevation).toBe(20);
+        expect(small.knobProps.elevation).toBeUndefined();
+        expect(small.knobProps.elevationChrome).toEqual({});
         expect(small.knobProps.overlayElevation).toBe(28);
         expect(small.knobProps.elevatedSurface.elevation).toBe(28);
         expect(small.knobProps.elevatedSurface.elevation).not.toBe(small.knobProps.elevation);
@@ -315,6 +319,52 @@ describe("resolveKnobs", () => {
     });
   });
 
+  describe("overlay elevation ladder (MPO-99)", () => {
+    const paint = (elevation: "small" | "medium" | "large", scheme: "light" | "dark") =>
+      resolveKnobs(knobsWith({ elevation }), undefined, scheme).knobProps;
+
+    it("overlay medium and large paint the reference popper and dialog shadows", () => {
+      expect(paint("medium", "light").overlayElevation).toBe("$3");
+      expect(paint("medium", "light").elevatedSurface.style?.boxShadow).toBe(
+        "0 4px 8px rgba(0,0,0,0.10), 0 12px 32px rgba(0,0,0,0.08)",
+      );
+      expect(paint("large", "light").overlayElevation).toBe("$5");
+      expect(paint("large", "light").elevatedSurface.style?.boxShadow).toBe(
+        "0 12px 24px rgba(0,0,0,0.12)",
+      );
+    });
+
+    it("overlay medium and large differ from control medium and large, in both schemes", () => {
+      for (const scheme of ["light", "dark"] as const) {
+        for (const stop of ["medium", "large"] as const) {
+          const knobProps = paint(stop, scheme);
+          expect(knobProps.elevatedSurface.style?.boxShadow).toBeTruthy();
+          expect(knobProps.elevationChrome.style?.boxShadow).toBeTruthy();
+          expect(knobProps.elevatedSurface.style?.boxShadow).not.toBe(
+            knobProps.elevationChrome.style?.boxShadow,
+          );
+        }
+      }
+    });
+
+    it("dark keeps each overlay stop's geometry and inverts the hue (LC-85)", () => {
+      expect(paint("medium", "dark").elevatedSurface.style?.boxShadow).toBe(
+        "0 4px 8px rgba(255,255,255,0.10), 0 12px 32px rgba(255,255,255,0.08)",
+      );
+      expect(paint("large", "dark").elevatedSurface.style?.boxShadow).toBe(
+        "0 12px 24px rgba(255,255,255,0.12)",
+      );
+    });
+
+    it("overlays keep a shadow at the default stop while controls go flat (MPO-96)", () => {
+      const knobProps = paint("small", "light");
+      expect(knobProps.elevationChrome).toEqual({});
+      expect(knobProps.elevatedSurface.style?.boxShadow).toBe(
+        "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)",
+      );
+    });
+  });
+
   // ── interaction state overrides ──────────────────────────────
 
   describe("interaction state overrides", () => {
@@ -351,8 +401,8 @@ describe("resolveKnobs", () => {
     });
 
     it("focus.elevation maps to elevation.focusKnobProps.elevation", () => {
-      const { elevation } = resolveKnobs(knobsWith({ focus: { elevation: "small" } }));
-      expect(elevation.focusKnobProps?.elevation).toBe("$1");
+      const { elevation } = resolveKnobs(knobsWith({ focus: { elevation: "large" } }));
+      expect(elevation.focusKnobProps?.elevation).toBe("$4");
     });
 
     it("focusVisible.borderWidth maps to control.focusVisibleKnobProps.borderWidth", () => {
@@ -958,7 +1008,7 @@ describe("resolveKnobs", () => {
       const overridden = resolveKnobs(defaultKnobs, () => ({
         elevation: "$4",
       }));
-      expect(baseline.knobProps.elevation).toBe("$1");
+      expect(baseline.knobProps.elevation).toBeUndefined();
       expect(overridden.knobProps.elevation).toBe("$4");
     });
 
@@ -1376,3 +1426,19 @@ describe("LC-67 touch height floor via resolveKnobs", () => {
     }
   });
 });
+
+describe("containerCapProps (DG-RAD-04 provenance)", () => {
+  it("names the knob stop a borderRadiusMap token came from", () => {
+    expect(containerCapProps("PageSection", "$12", "small")).toEqual({
+      "data-constraint-container": "PageSection",
+      "data-radius-knob": "full",
+      "data-space-knob": "small",
+    });
+  });
+
+  it("makes no claim for a radius that did not come from the knob", () => {
+    expect(containerCapProps("TextArea", 13, "small")).toBeUndefined();
+    expect(containerCapProps("TextArea", "$5", "small")).toBeUndefined();
+    expect(containerCapProps("TextArea", "$12", "roomy")).toBeUndefined();
+  });
+});

package/src/theme/resolveKnobs.ts

@@ -174,6 +174,43 @@ export function capContainerRadius(
   return radiusPx > paddingPx ? paddingPx : borderRadiusMap[borderRadius];
 }
 
+/** Containers the constraint audit measures against the cap (DG-RAD-04). */
+export type CappedContainer = "PageSection" | "TextArea";
+
+export interface ContainerCapDeclaration {
+  "data-constraint-container": CappedContainer;
+  "data-radius-knob": Knobs["borderRadius"];
+  "data-space-knob": Knobs["space"];
+}
+
+/**
+ * Declare a container that spreads `containerRadius`, with the knob stops it
+ * resolved, so the constraint audit checks its painted corners against
+ * `capContainerRadius` for those stops. The cap is a padding px value, not a
+ * radius token, so an undeclared capped container reads off-scale at `full`.
+ * Returns nothing when `radiusToken` is not a `borderRadiusMap` token or
+ * `space` is not a space stop: a part whose radius did not come from the knob
+ * makes no claim.
+ *
+ * @example
+ * <YStack {...knobProps.containerRadius} {...containerCapProps("PageSection", knobProps.borderRadius.borderRadius, knobProps.space)} />
+ */
+export function containerCapProps(
+  container: CappedContainer,
+  radiusToken: unknown,
+  space: string,
+): ContainerCapDeclaration | undefined {
+  const radiusKnob = (Object.keys(borderRadiusMap) as Knobs["borderRadius"][]).find(
+    (stop) => borderRadiusMap[stop] === radiusToken,
+  );
+  if (!radiusKnob || !Object.hasOwn(panelPaddingPxMap, space)) return undefined;
+  return {
+    "data-constraint-container": container,
+    "data-radius-knob": radiusKnob,
+    "data-space-knob": space as Knobs["space"],
+  };
+}
+
 const gapMap = {
   small: "$2",
   medium: "$4",
@@ -252,14 +289,16 @@ const fontWeightMap = {
 // tokens.size values Tamagui resolves those tokens to ($1=20, $2=28, $4=44),
 // so Tamagui consumers render identical shadows either way.
 //
-// Control elevation ($1 at the default small stop) is the in-page Button
-// token. Overlay elevation is a DISTINCT token one step above that stop so
-// a dialog over a scrim and a Button on the page do not read as the same
+// Controls are flat at the default `small` stop (MPO-96: the reference
+// measures no resting shadow on a button or a card), so `small` paints
+// nothing on the control map and only medium / large lift a control.
+// Overlay elevation is a DISTINCT ladder one step above the control map, so
+// a dialog over a scrim and a Button on the page never read as the same
 // distance off the surface (DG-OVL-01 / E-OVERLAY). elevatedSurface binds
 // the overlay token — not the control one.
 export const elevationMap: Record<string, string | number | undefined> = isWeb
-  ? { none: undefined, small: "$1", medium: "$2", large: "$4" }
-  : { none: undefined, small: 20, medium: 28, large: 44 };
+  ? { none: undefined, small: undefined, medium: "$2", large: "$4" }
+  : { none: undefined, small: undefined, medium: 28, large: 44 };
 
 export const overlayElevationMap: Record<string, string | number | undefined> = isWeb
   ? { none: undefined, small: "$2", medium: "$3", large: "$5" }
@@ -285,43 +324,70 @@ const elevationTintInput: Record<Elevation, string> = {
   large: "$color5",
 };
 
+type ElevationKey = "$1" | "$2" | "$3" | "$4" | "$5";
+
 // Axiom 14 light source: y-offset:blur = 0.5. Metrics match the maps
-// InputParts / getElevationWrapperProps already shipped.
+// InputParts / getElevationWrapperProps already shipped. `$3` and `$5` are
+// the overlay-only stops (MPO-99): the reference §8 popper and dialog
+// shadows. Native paints one shadow, so it takes the first web layer.
 const elevationShadowMetrics: Record<
-  "$1" | "$2" | "$4",
+  ElevationKey,
   { offsetY: number; radius: number; android: number }
 > = {
   $1: { offsetY: 1, radius: 2, android: 2 },
   $2: { offsetY: 3, radius: 6, android: 4 },
+  $3: { offsetY: 4, radius: 8, android: 6 },
   $4: { offsetY: 10, radius: 20, android: 8 },
+  $5: { offsetY: 12, radius: 24, android: 12 },
 };
 
-const elevationKeyAlias: Record<string, "$1" | "$2" | "$4"> = {
+const elevationKeyAlias: Record<string, ElevationKey> = {
   $1: "$1",
   $2: "$2",
-  $3: "$2",
+  $3: "$3",
   $4: "$4",
-  $5: "$4",
+  $5: "$5",
   "20": "$1",
   "28": "$2",
-  "36": "$2",
+  "36": "$3",
   "44": "$4",
-  "52": "$4",
+  "52": "$5",
 };
 
-const webShadowLight: Record<"$1" | "$2" | "$4", string> = {
+const webShadowLight: Record<ElevationKey, string> = {
   $1: "0 1px 2px rgba(0,0,0,0.12), 0 0 1px rgba(0,0,0,0.08)",
   $2: "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)",
+  $3: "0 4px 8px rgba(0,0,0,0.10), 0 12px 32px rgba(0,0,0,0.08)",
   $4: "0 10px 20px rgba(0,0,0,0.15), 0 3px 6px rgba(0,0,0,0.10)",
+  $5: "0 12px 24px rgba(0,0,0,0.12)",
 };
 
-const webShadowDark: Record<"$1" | "$2" | "$4", string> = {
+// LC-85: dark keeps each stop's geometry and inverts the hue.
+const webShadowDark: Record<ElevationKey, string> = {
   $1: "0 1px 2px rgba(255,255,255,0.08), 0 0 1px rgba(255,255,255,0.06)",
   $2: "0 3px 6px rgba(255,255,255,0.10), 0 2px 4px rgba(255,255,255,0.06)",
+  $3: "0 4px 8px rgba(255,255,255,0.10), 0 12px 32px rgba(255,255,255,0.08)",
   $4: "0 10px 20px rgba(255,255,255,0.12), 0 3px 6px rgba(255,255,255,0.08)",
+  $5: "0 12px 24px rgba(255,255,255,0.12)",
+};
+
+const shadowOpacityLight: Record<ElevationKey, number> = {
+  $1: 0.12,
+  $2: 0.15,
+  $3: 0.1,
+  $4: 0.15,
+  $5: 0.12,
+};
+
+const shadowOpacityDark: Record<ElevationKey, number> = {
+  $1: 0.08,
+  $2: 0.1,
+  $3: 0.1,
+  $4: 0.12,
+  $5: 0.12,
 };
 
-function elevationTokenKey(token: string | number | undefined): "$1" | "$2" | "$4" | undefined {
+function elevationTokenKey(token: string | number | undefined): ElevationKey | undefined {
   if (token == null) return undefined;
   return elevationKeyAlias[String(token)];
 }
@@ -337,15 +403,7 @@ function elevationPaint(
   const paint: ElevationPaintProps = {
     shadowColor: dark ? "$color12" : "#000",
     shadowOffset: { width: 0, height: metrics.offsetY },
-    shadowOpacity: dark
-      ? key === "$4"
-        ? 0.12
-        : key === "$2"
-          ? 0.1
-          : 0.08
-      : key === "$1"
-        ? 0.12
-        : 0.15,
+    shadowOpacity: dark ? shadowOpacityDark[key] : shadowOpacityLight[key],
     shadowRadius: metrics.radius,
   };
   if (isWeb) {
@@ -489,6 +547,7 @@ export function resolveKnobs(
   knobs: Knobs,
   override?: KnobPropsOverride,
   scheme: ColorScheme = "light",
+  environment?: { touch?: boolean },
 ): ResolvedKnobs {
   const radiusToken = borderRadiusMap[knobs.borderRadius];
   const nestedRadiusToken = nestedRadiusMap[knobs.borderRadius];
@@ -496,7 +555,7 @@ export function resolveKnobs(
   const nestedPx = nestedControlPxMap[knobs.size];
   const nestedHitSlop = pressTargetHitSlop(nestedPx);
   const sizeRecipe = sizeRecipeForToken(sizeToken, {
-    touch: isTouchable || isWebTouchable,
+    touch: environment?.touch ?? (isTouchable || isWebTouchable),
     family: knobs.density === "compact" ? "controlCompact" : "control",
   });
   const paddingToken = panelPaddingMap[knobs.space];

package/src/theme/sizeRecipes.ts

@@ -217,14 +217,17 @@ export function sizeRecipeForToken(
 /**
  * Identity helper for the LC-65 SIZE-RECIPE ESCAPE lint
  * (`scripts/lint-conventions.mjs`). Wrap a numeric height / minHeight /
- * paddingHorizontal / fontSize that must stay a literal:
+ * paddingHorizontal / fontSize that must stay a literal, and say why:
  *
- *   height={sizeRecipeEscape(20)}
+ *   height={sizeRecipeEscape(20, "toolbar chrome match")}
  *
- * Or comment `// size-recipe-escape:` on the previous line or same
- * statement. Pilot: Button/, InputParts/, fields/Select/.
+ * Or write the same reason in a `size-recipe-escape:` line comment on the
+ * previous line or same statement. Pilot: Button/, InputParts/,
+ * fields/Select/. Either way the file and the reason must be a row in
+ * `docs/theme-propagation-spec.md` `## Size-recipe escapes` (MPO-23, `00` L8
+ * E8); an undeclared escape fails `lint-conventions`.
  */
-export function sizeRecipeEscape<T>(value: T): T {
+export function sizeRecipeEscape<T>(value: T, _reason?: string): T {
   return value;
 }
 

package/src/theme/subsetThemes.spec.ts

@@ -0,0 +1,102 @@
+/**
+ * `10` AC-6 (MPO-23): a narrow surface ships a narrow theme matrix. The filter
+ * is pinned twice, once over hand-named themes and once over the matrix the
+ * house builder really emits, so a builder rename that stops a component
+ * sub-theme matching shows up here rather than as an untinted control.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("tamagui", () => ({
+  createTamagui: vi.fn((config: Record<string, unknown>) => config),
+}));
+vi.mock("./animations/index", () => ({ animations: {} }));
+
+import { createDefaultThemeConfig } from "./createDefaultThemeConfig";
+import { createThemesBuilder } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+import { type ThemeSubset, subsetThemes } from "./subsetThemes";
+
+const narrow: ThemeSubset = {
+  components: ["Button", "Input"],
+  tints: ["accent", "active", "error"],
+};
+
+describe("subsetThemes", () => {
+  const names = [
+    "light",
+    "dark",
+    "light_accent",
+    "dark_accent_Button",
+    "light_Button",
+    "light_Input",
+    "light_active_Button",
+    "light_error",
+    "light_blue",
+    "dark_blue_Button",
+    "light_Tooltip",
+    "light_accent_Tooltip",
+  ];
+  const themes = Object.fromEntries(names.map((name) => [name, { name }]));
+
+  it("keeps the bare schemes and every listed tint x component, and nothing else", () => {
+    expect(Object.keys(subsetThemes(themes, narrow))).toEqual([
+      "light",
+      "dark",
+      "light_accent",
+      "dark_accent_Button",
+      "light_Button",
+      "light_Input",
+      "light_active_Button",
+      "light_error",
+    ]);
+  });
+
+  it("never rewrites a theme it keeps: filtering is not redefinition", () => {
+    const kept = subsetThemes(themes, narrow);
+    for (const [name, theme] of Object.entries(kept)) expect(theme).toBe(themes[name]);
+  });
+
+  it("keeps only the schemes when the subset is empty", () => {
+    expect(Object.keys(subsetThemes(themes, { components: [], tints: [] }))).toEqual([
+      "light",
+      "dark",
+    ]);
+  });
+});
+
+describe("subsetThemes over the house matrix", () => {
+  const built = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes() as Record<string, Record<string, unknown>>;
+
+  it("drops the decorative hues and keeps the semantic and state children", () => {
+    const kept = subsetThemes(built, {
+      components: ["Button"],
+      tints: ["accent", "active", "alt1", "alt2", "error", "success", "warning"],
+    });
+    expect(Object.keys(kept).length).toBeLessThan(Object.keys(built).length / 4);
+    for (const name of ["light", "dark", "light_accent", "light_Button", "dark_error_Button"]) {
+      expect(kept).toHaveProperty(name);
+    }
+    for (const name of ["light_blue", "dark_red", "light_Tooltip", "light_accent_Input"]) {
+      expect(built).toHaveProperty(name);
+      expect(kept).not.toHaveProperty(name);
+    }
+  });
+
+  it("is what createDefaultThemeConfig({ subset }) ships, and omitting it ships everything", () => {
+    const full = createDefaultThemeConfig().tamagui.themes as Record<string, unknown>;
+    const subset = createDefaultThemeConfig({ subset: narrow }).tamagui.themes as Record<
+      string,
+      unknown
+    >;
+    expect(Object.keys(full)).toEqual(Object.keys(built));
+    expect(Object.keys(subset)).toEqual(Object.keys(subsetThemes(built, narrow)));
+    expect(subset.light).toEqual(full.light);
+  });
+});

package/src/theme/subsetThemes.ts

@@ -0,0 +1,56 @@
+/**
+ * The themes one surface can reach (`10` AC-6, MPO-23).
+ *
+ * Themes are emitted into the served document as CSS, so a surface pays for
+ * every theme it will never enter. shc measured it on the live storefront:
+ * 721,818 of 1,232,058 decompressed bytes were the theme sheet, 921 classes of
+ * which the rendered routes asked for seven, and building the same house
+ * config over a named subset cut the sheet from 697,788 to 186,158 bytes
+ * (`shc/packages/themes/storefront.ts`). This is that subset as a pure
+ * function over the built matrix, so every app can do it the same way.
+ *
+ * It filters WHICH themes exist, never what a theme contains: `$color5` means
+ * the same thing in every theme that survives. A subset is a loaded gun, all
+ * the same. A component whose sub-theme was dropped does not crash, it renders
+ * in its parent's colours, so list everything the surface renders.
+ */
+export interface ThemeSubset {
+  /**
+   * Component sub-themes the surface renders, by Tamagui componentName
+   * (`Button`, `Input`, `ListItem`, `SelectTrigger`, …). Tamagui enters one
+   * by rendering the component, so this is "which components exist on this
+   * surface", not a style choice.
+   */
+  components: readonly string[];
+  /**
+   * Named themes the surface can enter beside the bare `light`/`dark`
+   * schemes: `accent`, the semantic children (`error`, `success`,
+   * `warning`), Tamagui's state children (`active`, `alt1`, `alt2`), and any
+   * decorative hue a `theme="…"` or `<Theme name="…">` on the surface names.
+   */
+  tints: readonly string[];
+}
+
+const SCHEMES = new Set(["light", "dark"]);
+
+/**
+ * Keep a theme when its component suffix (if any) is in `components` and
+ * every other non-scheme segment of its name is in `tints`. Names are
+ * `[light|dark_]<tint>*[_Component]`, so `light` and `dark` always survive.
+ */
+export function subsetThemes<T>(themes: Record<string, T>, subset: ThemeSubset): Record<string, T> {
+  const components = new Set(subset.components);
+  const tints = new Set(subset.tints);
+  const kept: Record<string, T> = {};
+  for (const [name, theme] of Object.entries(themes)) {
+    const segments = name.split("_");
+    const last = segments[segments.length - 1] ?? "";
+    if (/^[A-Z]/.test(last)) {
+      segments.pop();
+      if (!components.has(last)) continue;
+    }
+    if (segments.some((segment) => !SCHEMES.has(segment) && !tints.has(segment))) continue;
+    kept[name] = theme;
+  }
+  return kept;
+}

package/src/theme/theme.tsx

@@ -1,7 +1,12 @@
 import { ToastProvider } from "@tamagui/toast";
 import { useContext, useEffect, useInsertionEffect, useMemo, useRef } from "react";
 import { useCookies } from "react-cookie";
-import { type CreateTamaguiProps, TamaguiProvider, type TamaguiProviderProps } from "tamagui";
+import {
+  type CreateTamaguiProps,
+  TamaguiProvider,
+  type TamaguiProviderProps,
+  useDidFinishSSR,
+} from "tamagui";
 import type { PropsWithChildren } from "react";
 import { animationDurations } from "./animations/css";
 import { getCookieWatchList, readOverridesCookie, readPresetCookie } from "./cookies";
@@ -67,12 +72,15 @@ export function ThemeProvider<T extends CreateTamaguiProps>({
   //   - Storybook: decorator resolves "system"/"light"/"dark" with OS listener
   // ThemeProvider simply applies whatever the caller provides.
   const activeTheme = systemTheme;
+  // A hydrating root renders a light placeholder to match SSR (MPO-278); the
+  // blocking scheme script owns <html> until hydration finishes.
+  const hydrated = useDidFinishSSR();
 
-  const prevThemeRef = useRef(activeTheme);
+  const prevThemeRef = useRef<string | undefined>(undefined);
 
   // Set the initial theme class synchronously to avoid FOUC.
   useInsertionEffect(() => {
-    if (typeof document === "undefined") return;
+    if (typeof document === "undefined" || !hydrated) return;
     const classList = document.documentElement.classList;
     const toAdd = `t_${activeTheme}`;
     if (!classList.contains(toAdd)) {
@@ -80,12 +88,14 @@ export function ThemeProvider<T extends CreateTamaguiProps>({
       classList.add(toAdd);
     }
     document.documentElement.style.colorScheme = activeTheme;
-  }, [activeTheme]);
+  }, [activeTheme, hydrated]);
 
   // Animate subsequent scheme changes via View Transitions / class-gated fallback.
   useEffect(() => {
-    if (prevThemeRef.current === activeTheme) return;
+    if (!hydrated) return;
+    const previous = prevThemeRef.current;
     prevThemeRef.current = activeTheme;
+    if (previous === undefined || previous === activeTheme) return;
 
     startThemeTransition(() => {
       const classList = document.documentElement.classList;

package/src/theme/transitionProps.native.ts

@@ -0,0 +1,15 @@
+import type { TransitionProp } from "tamagui";
+
+/**
+ * Native twin of `transitionProps.ts`.
+ *
+ * The React Native driver resolves an undefined `transition` to an empty
+ * config and animates with a default spring (LC-59), so keeping the key at
+ * animation `none` would put motion on every part that is meant to be still.
+ * Native keeps omitting it until the driver has an instant token to pass.
+ */
+export function transitionProps(transition: TransitionProp | undefined): {
+  transition?: TransitionProp;
+} {
+  return transition ? { transition } : {};
+}

package/src/theme/transitionProps.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { transitionProps } from "./transitionProps";
+
+describe("transitionProps (web)", () => {
+  it("keeps the transition key at animation none so a live knob flip adds no hooks (MPO-327)", () => {
+    const atNone = transitionProps(undefined);
+    expect("transition" in atNone).toBe(true);
+    expect(atNone.transition).toBeUndefined();
+  });
+
+  it("passes a knob token through unchanged", () => {
+    expect(transitionProps("bouncy")).toEqual({ transition: "bouncy" });
+  });
+});

package/src/theme/transitionProps.ts

@@ -0,0 +1,16 @@
+import type { TransitionProp } from "tamagui";
+
+/**
+ * Spreadable `transition` for a part that rides the animation knob.
+ *
+ * Tamagui decides whether a component runs its animation hooks from
+ * `"transition" in props`, so a part that drops the key at animation `none`
+ * throws "Rendered more hooks than during the previous render" the moment the
+ * knob flips to any other stop (MPO-327). On web the key therefore stays, and
+ * an undefined value paints no CSS transition. The native twin differs.
+ */
+export function transitionProps(transition: TransitionProp | undefined): {
+  transition?: TransitionProp;
+} {
+  return { transition };
+}