# useMouseEvents

Subscribes to global mouse click and wheel (trackpad scroll) events streamed from the Fluxlay desktop app. Coordinates are normalized to the wallpaper window with the Y axis flipped to a math-style system (positive Y is up).

## Import

```tsx
import { useMouseEvents } from "@fluxlay/react";
```

## Signature

```tsx
function useMouseEvents(handlers: MouseEventHandlers): void;

interface MouseEventHandlers {
  onButton?: (event: MouseButtonEvent) => void;
  onWheel?: (event: MouseWheelEvent) => void;
}
```

Pass only the callbacks you need; missing ones are simply ignored.

## Usage

```tsx
import { useMouseEvents } from "@fluxlay/react";

function Wallpaper() {
  useMouseEvents({
    onButton: event => {
      if (event.pressed) {
        console.log("pressed", event.button, event.x, event.y);
      }
    },
    onWheel: event => {
      console.log("scroll", event.deltaX, event.deltaY);
    }
  });
  return <div />;
}
```

## Event types

### MouseButtonEvent

| Property      | Type                                       | Description                                                              |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| `type`        | `"button"`                                 | Discriminator.                                                           |
| `button`      | `"left" \| "right" \| "middle" \| "other"` | Which button was pressed / released.                                     |
| `pressed`     | `boolean`                                  | `true` for press, `false` for release.                                   |
| `x`           | `number`                                   | Cursor X at click time, normalized to the wallpaper window (`-1` … `1`). |
| `y`           | `number`                                   | Cursor Y at click time (`-1` … `1`, positive Y points up).               |
| `windowLabel` | `string`                                   | Label of the window the event was normalized against.                    |

### MouseWheelEvent

| Property      | Type      | Description                                                               |
| ------------- | --------- | ------------------------------------------------------------------------- |
| `type`        | `"wheel"` | Discriminator.                                                            |
| `deltaX`      | `number`  | Horizontal scroll delta (OS-defined units).                               |
| `deltaY`      | `number`  | Vertical scroll delta (OS-defined units).                                 |
| `x`           | `number`  | Cursor X at scroll time, normalized to the wallpaper window (`-1` … `1`). |
| `y`           | `number`  | Cursor Y at scroll time (`-1` … `1`, positive Y points up).               |
| `windowLabel` | `string`  | Label of the window the event was normalized against.                     |

## Notes

- The subscription is scoped to the window identified by the `window_label` query parameter of the current URL, defaulting to `"main"`.
- Like `useMousePosition`, the Y axis is inverted (positive Y is up). Flip it back when feeding into CSS coordinates.
- On macOS, the user must grant Fluxlay "Input Monitoring" in System Settings. On Windows the global hook may be flagged by some antivirus software, and events targeting processes running at higher integrity levels (e.g. apps launched as Administrator) are not delivered due to UIPI.