changes

Author: Your Name

packages/react-native/Libraries/Utilities/differ/BEST_PRACTICES.md

@@ -0,0 +1 @@
+/**\n * Best Practices for Using Differ Functions\n * \n * 1. Remember the Return Convention\n *    ❌ if (deepDiffer(a, b)) { /* a == b */ }\n *    ✅ if (deepDiffer(a, b)) { /* a != b */ }\n * \n * 2. Use Specialized Differs When Possible\n *    Prefer pointsDiffer over deepDiffer for points\n *    Prefer sizesDiffer over deepDiffer for sizes\n *    General rule: use most specific function for your data type\n * \n * 3. Be Careful with Max Depth\n *    deepDiffer({a: {b: {c: 1}}}, {a: {b: {c: 2}}}, 2)\n *    This won't detect the difference at c because depth is limited\n * \n * 4. Function Comparison Behavior\n *    deepDiffer treats all functions as equal by default\n *    This is intentional - function identity shouldn't trigger updates\n * \n * 5. Null/Undefined Handling\n *    Most differs handle null/undefined gracefully\n *    They use dummy objects to avoid crashes\n * \n * 6. Performance Notes\n *    - Use differs in shouldComponentUpdate/useMemo\n *    - Avoid deep nesting - consider flattening your data\n *    - Array differences always trigger full array check\n *    - Early exit on first difference found\n * \n * 7. Common Pitfalls\n *    ❌ deepDiffer(prev, curr) === false means no change (WRONG)\n *    ✅ deepDiffer(prev, curr) === false means no change (CORRECT)\n *    ✅ !deepDiffer(prev, curr) means no change (CORRECT)\n */\n

packages/react-native/Libraries/Utilities/differ/README.md

@@ -0,0 +1,52 @@
+/**
+ * Differ Utilities Module Documentation
+ * 
+ * Purpose:
+ * --------
+ * Provides optimized equality comparison functions for React Native styling
+ * and layout calculations. These are specialized differ functions designed for
+ * high-performance use in the render loop where speed is critical.
+ * 
+ * Return Value Convention:
+ * -----------------------
+ * All differ functions return:
+ *   - true  = values are DIFFERENT
+ *   - false = values are EQUAL
+ * 
+ * This is opposite to standard JS equality (===) and is optimized for
+ * React's shouldComponentUpdate pattern.
+ * 
+ * Available Functions:
+ * -------------------
+ * 
+ * deepDiffer(one, two, maxDepth?, options?)
+ *   Deep recursive comparison for arbitrary objects/arrays
+ *   - O(n) worst case, but short-circuits on first difference
+ *   - Supports max depth limiting to avoid excessive recursion
+ *   - Handles circular references gracefully
+ * 
+ * matricesDiffer(one, two)
+ *   Optimized for 4x4 transformation matrices
+ *   - O(1) fixed size, checks indices by change likelihood
+ *   - Critical for transform performance
+ * 
+ * pointsDiffer(one, two)
+ *   Compares {x, y} coordinate pairs
+ *   - O(1) tiny allocation footprint
+ *   - Null-safe with dummy object fallback
+ * 
+ * sizesDiffer(one, two)
+ *   Compares {width, height} dimensions
+ *   - O(1) with graceful null handling
+ *   - Commonly used in layout calculations
+ * 
+ * insetsDiffer(one, two)
+ *   Compares {top, left, right, bottom} spacing
+ *   - O(1) for padding/margin comparisons
+ *   - Null-safe with dummy fallback
+ * 
+ * Performance Characteristics:
+ * ---------------------------
+ * All functions are allocation-free after initialization and suitable for
+ * use in hot paths like render methods and event handlers.
+ */

packages/react-native/Libraries/Utilities/differ/deepDiffer.js

@@ -112,3 +112,25 @@ function deepDiffer(
 
 deepDiffer.unstable_setLogListeners = unstable_setLogListeners;
 export default deepDiffer;
+
+/**
+ * USAGE EXAMPLES:
+ * 
+ * // Primitive comparison
+ * deepDiffer(1, 2); // true
+ * deepDiffer('hello', 'hello'); // false
+ * 
+ * // Object comparison
+ * deepDiffer({a: 1}, {a: 1}); // false
+ * deepDiffer({a: 1, b: 2}, {a: 1}); // true
+ * 
+ * // Array comparison
+ * deepDiffer([1, 2], [1, 2]); // false
+ * deepDiffer([1, 2], [1, 3]); // true
+ * 
+ * // Nested structures
+ * deepDiffer({a: {b: [1, 2]}}, {a: {b: [1, 2]}}); // false
+ * 
+ * // With depth limit
+ * deepDiffer({a: {b: {c: 1}}}, {a: {b: {c: 2}}}, 2); // false (depth limited)
+ */

packages/react-native/Libraries/Utilities/differ/index.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+/**
+ * Collection of specialized comparison functions for React Native styling.
+ * 
+ * These utilities provide optimized equality checks for common data types
+ * used in styling and layout calculations. They return true if values differ,
+ * false if equal - opposite of standard equality comparisons.
+ */
+
+export {default as deepDiffer} from './deepDiffer';
+export {default as matricesDiffer} from './matricesDiffer';
+export {default as pointsDiffer} from './pointsDiffer';
+export {default as sizesDiffer} from './sizesDiffer';
+export {default as insetsDiffer} from './insetsDiffer';

packages/react-native/Libraries/Utilities/differ/pointsDiffer.js

@@ -30,6 +30,7 @@ const dummyPoint: Point = {x: undefined, y: undefined};
 function pointsDiffer(one: ?Point, two: ?Point): boolean {
   one = one || dummyPoint;
   two = two || dummyPoint;
+  // Null-safe comparison: handles undefined values gracefully
   return one !== two && (one.x !== two.x || one.y !== two.y);
 }