IMO the long-term return of the controller should be the default here.

Maybe we can do a backwards-comparable solution for now. Not sure if this is considered hacky or not:

What if we return something like this:

const useXY = ()=>{
  const controller /* is actually stop function */  = ()=>{
    // stop logic
  }
  controller.cancel = ()=>{
    shouldListen = false 
  }
  controller.stop = ()=>{
    // stop logic
  }
  controller.fire = (event)=>{
    shouldListen = true
    listener(event)
  }
  
  return controller
}

This should allow

const stop = useXY()
stop()

// AND
const {stop, fire, cancel} = useXY()
stop()
// ...

This means that we do not need an extra option.

IMO the long-term return of the controller should be the default here.

That's what I think too.

This means that we do not need an extra option.

I considered this option but it feels like anti-pattern and look ugly. And more importantly this is a breaking change for types. Without controller, handler function's first argument receives PointerEvent type. When controller is enabled it becomes Event. Similar to when detectIframe enabled, it's FocusEvent | PointerEvent.

If we decide to pursue controller approach, in next major, we can drop overloads, default to Event (or even Event | undefined) and significantly simplify types.

it feels like anti-pattern and look ugly

I agree with that. But it would ensure that a breaking change can also be a little softer.

If we decide to pursue controller approach, in next major, we can drop overloads, default to Event (or even Event | undefined) and significantly simplify types.

When we do, we might consider making sure that all composables return an object. That way we are consistent and future proof.

I considered this option but it feels like anti-pattern and look ugly. And more importantly this is a breaking change for types. Without controller, handler function's first argument receives PointerEvent type. When controller is enabled it becomes Event. Similar to when detectIframe enabled, it's FocusEvent | PointerEvent.

Just for reference, the vue 3.5 watcher does exactly this pattern: https://github.com/vuejs/core/blob/7ecd2a22c799d85b0c9857e48d97de5755197e87/packages/reactivity/src/watch.ts#L324-L328. Not to say it is not an anti-pattern.

Partially related: #4548 (comment)