# Aureole — WebGL Background for React

> Volumetric god rays through drifting atmosphere: a light source anchored to a frame edge or corner pours a bundle of shafts into the dark, an angular noise mask slowly churns so individual beams brighten, split, and die like sun through smoke, and sparse dust motes twinkle only inside the lit volume. Inverse power-law bloom at the source, radial falloff keeping the far field text-safe, and a gentle searchlight re-aim toward the pointer. An original OGL fragment shader — DPR-clamped, offscreen-paused, with a composed static frame under reduced motion; the beam idles on its own when untouched.

- Page: https://crucibleui.com/components/backgrounds/aureole
- Category: [backgrounds](https://crucibleui.com/backgrounds)
- Tier: pro (one-time purchase, see https://crucibleui.com/pricing)
- Engine: ogl
- npm dependencies: ogl

## Install

```bash
npx shadcn@latest add @crucible/aureole
```

Pro install requires adding the token-bearing `@crucible` registry to components.json (issued at https://crucibleui.com/account after purchase).

Import from `@/components/crucible/aureole`.

Backgrounds render `absolute inset-0 -z-10`. Their parent must be a stacking context — wrap in `relative isolate` and put your content in a `relative z-10` child, or the background disappears behind an opaque ancestor.

## Props (`AureoleProps`)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `edge?` | `AureoleEdge` | `"top-left"` | Which frame edge the light pours in from. The source sits just outside the frame so only its bloom and the shaft bundle are visible. |
| `colors?` | `[string, string]` | `pale gold/ivory through a warm neutral haze` | Two tones: `[light, haze]`. `light` is the pale core of the brightest shafts, the source bloom, and the dust motes; `haze` tints the dimmer shaft bodies and the soft atmospheric fill between beams. |
| `beamCount?` | `number` | `12` | Approximate number of distinct shafts across the fan. Higher packs the fan with fine rays; lower gives a few broad cathedral beams. Clamped 2–48. |
| `churn?` | `number` | `1` | How actively the angular noise mask evolves — beams brightening, splitting and dying like sun through smoke. 0 = a fixed arrangement that only drifts along its length, 2 = restless. |
| `motes?` | `number` | `1` | Density/brightness of the dust-mote layer drifting through the lit shafts (motes never appear in the dark field). 0 disables. |
| `reach?` | `number` | `1` | How far the shafts reach into the frame before falling to black, 0.2–3. 1 keeps the far field dark enough for overlay text. |
| `interactive?` | `boolean` | `true` | Searchlight follow: the shaft bundle re-aims a few degrees toward the pointer, heavily smoothed. Disabled automatically under reduced motion. |
| `speed?` | `number` | `1` | Animation speed multiplier for churn, drift, and motes. |
| `intensity?` | `number` | `1` | Overall brightness multiplier, 0–2. |
| `seed?` | `number` | — | Deterministic per-instance variation: offsets the noise domain and clock so multiple instances on one page desynchronize. Auto-assigned by mount order when omitted. |
| `paused?` | `boolean` | — | Freeze the render loop, holding the current frame. |
| `idle?` | `boolean` | `true` | Idle autoplay: after ~1.5s with no pointer present, a seeded ghost drifts slowly across the field and re-aims the searchlight bundle, so thumbnails and heroes never look still; a real pointer takes over instantly. Never runs under reduced motion or with `interactive` off. |
| `className?` | `string` | — | Extra classes for the wrapper. Positioned `absolute inset-0 -z-10`. |

Also accepts: `React.ComponentPropsWithoutRef<"div">`.

## Usage example

`DemoScene` is a site-only preview harness, not part of the component — replace it with your own layout.

```tsx
import { Aureole } from "@/components/crucible/aureole";
import { DemoScene } from "@/components/registry/demo-scene";

export default function AureoleDemo() {
  return (
    <DemoScene
      background={<Aureole />}
      headline="Let the light pour in"
      subhead="Volumetric shafts churn through drifting dust. Move your cursor to re-aim the beam."
    />
  );
}
```

## Accessibility & performance

Honors `prefers-reduced-motion` with a designed static frame or fade (never a blank box) and passes `className` through. Pauses offscreen and on hidden tabs, clamps device pixel ratio, and tears down its GL/canvas context on unmount.