# useImageMode

## Usage

Detects whether an image is predominantly dark or light by sampling pixels through `OffscreenCanvas`. Uses APCA perceptual lightness (sRGB linearization plus a power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns `null` while loading and falls back gracefully on CORS or network errors.

The image is fetched, drawn into a 10×10 offscreen canvas, and averaged, so a new `src` cancels the answer that is still in flight. `src` and `options` may be refs or getters.

```ts
import { useImageMode } from '@astryx-vue/core'
```

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Pair with `MediaTheme` to automatically adapt text color over dynamic background images. |
| Do | Use the `region` option to sample only the area where text overlays will appear for more accurate results. |
| Don't | Use for images that change rapidly (e.g. video frames); each `src` change triggers a new fetch and analysis. |

## Parameters

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `MaybeRefOrGetter<string \| null \| undefined>` | — | Image source URL to analyze. A plain string, a ref, or a getter. When null or undefined, the result is the fallback value. Required. |
| `options` | `MaybeRefOrGetter` | `{}` | Optional configuration for the analysis. Read on each run, so a getter keeps it current. |
| `options.region` | `ImageSampleRegion` | whole image | Region to sample within the image, using normalized 0-1 coordinates `{ x, y, width, height }`. |
| `options.threshold` | `number` | `0.5` | Luminance threshold for the dark/light split. Below is dark, above is light. |
| `options.fallback` | `'dark' \| 'light' \| null` | `null` | Value returned while loading or on error. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `mode` | `Ref<'dark' \| 'light' \| null>` | Detected luminance mode of the image. Returns `null` while loading, or the fallback when `src` is null or undefined. |

The two pieces of the analysis are exported too: `perceptualLightness(r, g, b)` returns the APCA lightness of one color, and `imageModeFromPixels(pixels, threshold)` averages an RGBA buffer into `'dark'` or `'light'`.