fix: prevent transient HOC stacking in CompositionStore (#5047)

Author: Pavel910

packages/react-composition/src/Compose.tsx

@@ -52,6 +52,7 @@ export const Compose = (props: ComposeProps) => {
             target={targetFn.original}
             decorators={decorators}
             scope={currentScope}
+            inherit={inherit}
         />
     );
 };
@@ -64,27 +65,42 @@ function ComposeEffects({
     store,
     target,
     decorators,
-    scope
+    scope,
+    inherit
 }: {
     store: ReturnType<typeof useCompositionStore>;
     target: any;
     decorators: Decorator<GenericComponent | GenericHook>[];
     scope: string;
+    inherit: boolean;
 }) {
     const prevRef = useRef<{
         decorators: Decorator<GenericComponent | GenericHook>[];
         scope: string;
     } | null>(null);
 
+    // Tracks the decorators currently live in the store as of the last render.
+    // Updated synchronously during render so it always reflects the most recently
+    // registered decorators, allowing the atomic swap below to remove the right ones.
+    const liveRef = useRef<Decorator<GenericComponent | GenericHook>[]>(decorators);
+
+    // On re-render with new decorators: atomically replace the old ones in the store
+    // during render (before React commits). This ensures the store never transiently
+    // holds both old and new HOCs — which would cause useSyncExternalStore subscribers
+    // to render with a doubly-wrapped component and mount inner components twice.
+    if (liveRef.current !== decorators) {
+        store.register(target, decorators, scope, inherit, true, liveRef.current);
+        liveRef.current = decorators;
+    }
+
     useEffect(() => {
         const prev = prevRef.current;
 
-        // On prop change: unregister old decorators.
+        // On prop change: the render-phase atomic swap already updated the store.
+        // Emit a non-silent notification now that effects have settled so subscribers
+        // re-render with the final, clean composition (old HOCs fully gone).
         if (prev && (prev.decorators !== decorators || prev.scope !== scope)) {
-            store.unregister(target, prev.decorators, prev.scope);
-            // Re-register new ones (they were already registered during render,
-            // but the idempotency check handles this).
-            store.register(target, decorators, scope);
+            store.notify();
         }
 
         prevRef.current = { decorators, scope };

packages/react-composition/src/domain/CompositionStore.ts

@@ -22,7 +22,8 @@ export class CompositionStore {
         hocs: Decorator<GenericComponent | GenericHook>[],
         scope = "*",
         inherit = false,
-        silent = false
+        silent = false,
+        replaces: Decorator<GenericComponent | GenericHook>[] = []
     ): () => void {
         const scopeMap: ComposedComponents = this.scopes.get(scope) || new Map();
         const recipe = scopeMap.get(component) || {
@@ -32,11 +33,17 @@ export class CompositionStore {
 
         // Idempotent: skip if all HOCs are already registered (handles StrictMode double-render).
         const newHocs = hocs.filter(hoc => !recipe.hocs.includes(hoc));
-        if (newHocs.length === 0) {
+        if (newHocs.length === 0 && replaces.length === 0) {
             return () => this.unregister(component, hocs, scope);
         }
 
-        const existingHocs = [...recipe.hocs];
+        // Atomically remove the HOCs being replaced so the store never transiently
+        // holds both the old and new decorators at the same time. This prevents
+        // useSyncExternalStore subscribers from seeing a doubly-wrapped component
+        // in the window between a render-phase registration and its effect cleanup.
+        const existingHocs = replaces.length
+            ? recipe.hocs.filter(hoc => !replaces.includes(hoc))
+            : [...recipe.hocs];
         if (inherit && scope !== "*") {
             const globalScope = this.scopes.get("*") || new Map();
             const globalRecipe = globalScope.get(component) || {
@@ -124,6 +131,16 @@ export class CompositionStore {
         return undefined;
     }
 
+    /**
+     * Bump version and notify listeners without changing store state.
+     * Used after a render-phase atomic swap (silent) to inform subscribers
+     * that the swap has settled and they should re-render with the final state.
+     */
+    notify(): void {
+        this.version++;
+        this.notifyListeners();
+    }
+
     subscribe = (listener: Listener): (() => void) => {
         this.listeners.add(listener);
         return () => {