# useSystemMonitor

Subscribes to system and hardware information streamed from the Fluxlay desktop app. Useful for building cyberpunk HUDs, system monitor wallpapers, and hardware-reactive visuals.

## Import

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

## Signature

```tsx
function useSystemMonitor(options?: SystemMonitorOptions): SystemMonitorInfo;
```

## Parameters

### SystemMonitorOptions

Per-category polling intervals in milliseconds. Omitted fields use their default values.

| Property                | Type     | Default | Description                               |
| ----------------------- | -------- | ------- | ----------------------------------------- |
| `cpuIntervalMs`         | `number` | `500`   | CPU usage, per-core usage, and frequency. |
| `memoryIntervalMs`      | `number` | `1000`  | Memory and swap usage.                    |
| `networkIntervalMs`     | `number` | `1000`  | Network receive/transmit speed.           |
| `diskIoIntervalMs`      | `number` | `2000`  | Disk read/write speed.                    |
| `diskSpaceIntervalMs`   | `number` | `30000` | Disk capacity per mount point.            |
| `batteryIntervalMs`     | `number` | `10000` | Battery level and charging status.        |
| `processIntervalMs`     | `number` | `10000` | Running process count.                    |
| `loadAverageIntervalMs` | `number` | `5000`  | System load average.                      |

Shorter intervals increase responsiveness but also increase CPU usage. Adjust the balance to suit your wallpaper's needs.

## Return Value

### CPU

| Property          | Type       | Description                                    |
| ----------------- | ---------- | ---------------------------------------------- |
| `cpuUsage`        | `number`   | Overall CPU usage percentage (0.0 – 100.0).    |
| `cpuPerCore`      | `number[]` | Per-core usage percentages (0.0 – 100.0 each). |
| `cpuFrequencyMhz` | `number[]` | Per-core clock frequency in MHz.               |

### Memory

| Property      | Type     | Description                            |
| ------------- | -------- | -------------------------------------- |
| `memoryTotal` | `number` | Total physical memory in bytes.        |
| `memoryUsed`  | `number` | Used physical memory in bytes.         |
| `memoryUsage` | `number` | Memory usage percentage (0.0 – 100.0). |
| `swapTotal`   | `number` | Total swap space in bytes.             |
| `swapUsed`    | `number` | Used swap space in bytes.              |
| `swapUsage`   | `number` | Swap usage percentage (0.0 – 100.0).   |

### Battery

| Property          | Type              | Description                                                             |
| ----------------- | ----------------- | ----------------------------------------------------------------------- |
| `batteryLevel`    | `number \| null`  | Battery charge level (0.0 – 100.0), or `null` if no battery is present. |
| `batteryCharging` | `boolean \| null` | Whether the battery is currently charging, or `null` if no battery.     |

### Network

| Property               | Type     | Description                                 |
| ---------------------- | -------- | ------------------------------------------- |
| `networkRxBytesPerSec` | `number` | Network receive speed in bytes per second.  |
| `networkTxBytesPerSec` | `number` | Network transmit speed in bytes per second. |

### Disk

| Property               | Type         | Description                                |
| ---------------------- | ------------ | ------------------------------------------ |
| `diskReadBytesPerSec`  | `number`     | Disk read speed in bytes per second.       |
| `diskWriteBytesPerSec` | `number`     | Disk write speed in bytes per second.      |
| `disks`                | `DiskInfo[]` | Per-mount-point disk capacity information. |

**DiskInfo:**

| Property         | Type     | Description                      |
| ---------------- | -------- | -------------------------------- |
| `mountPoint`     | `string` | Mount point path (e.g. `"/"`).   |
| `name`           | `string` | Disk/volume name.                |
| `totalBytes`     | `number` | Total capacity in bytes.         |
| `availableBytes` | `number` | Available (free) space in bytes. |
| `usage`          | `number` | Usage percentage (0.0 – 100.0).  |

### System Info

| Property            | Type                       | Description                                     |
| ------------------- | -------------------------- | ----------------------------------------------- |
| `loadAverage`       | `[number, number, number]` | Load average for the past 1, 5, and 15 minutes. |
| `processCount`      | `number`                   | Number of running processes.                    |
| `uptimeSecs`        | `number`                   | System uptime in seconds.                       |
| `hostname`          | `string`                   | System hostname.                                |
| `osName`            | `string`                   | Operating system name and version.              |
| `cpuBrand`          | `string`                   | CPU model name (e.g. `"Apple M2 Pro"`).         |
| `physicalCoreCount` | `number`                   | Number of physical CPU cores.                   |
| `logicalCoreCount`  | `number`                   | Number of logical CPU cores (threads).          |
| `cpuArch`           | `string`                   | CPU architecture (e.g. `"aarch64"`).            |
| `kernelVersion`     | `string`                   | Kernel version string.                          |

## Example

```tsx
function Wallpaper() {
  const { cpuUsage, memoryUsage, batteryLevel, batteryCharging } = useSystemMonitor({
    cpuIntervalMs: 500,
    memoryIntervalMs: 1000,
    batteryIntervalMs: 10000
  });

  // Change background color based on CPU load
  const bg = cpuUsage > 80 ? "#1a0000" : "#000a1a";

  return (
    <div style={{ background: bg, color: "white", padding: 32, fontFamily: "monospace" }}>
      <p>CPU: {cpuUsage.toFixed(1)}%</p>
      <p>Memory: {memoryUsage.toFixed(1)}%</p>
      <p>
        Battery: {batteryLevel !== null ? `${batteryLevel.toFixed(0)}%` : "N/A"}
        {batteryCharging ? " ⚡" : ""}
      </p>
    </div>
  );
}
```

### Combining with useProperties

Combine with `useProperties` to let end users adjust polling intervals.

```tsx
function Wallpaper() {
  const props = useProperties();
  const info = useSystemMonitor({
    cpuIntervalMs: props.cpuInterval as number
  });
  // ...
}
```

## Notes

- Each category is only refreshed and read at its configured interval. Cached values are used between refreshes.
- No data is sent to the stream on ticks where nothing was updated, so the effective receive rate matches the shortest configured interval.
- Static information (hostname, OS name, CPU model, etc.) is fetched once at app startup and never changes.
- Monitoring starts when the first subscriber connects and stops when all subscribers disconnect.
- This hook only works inside the Fluxlay desktop app. In a normal browser, it returns the initial zero values.
- When `options` values change, the stream is automatically reconnected.