===============
LIBRARY RULES
===============
From library maintainers:
- layers[0] must always be a BackgroundLayer with type:"background" and id:"background". Without it, the canvas is never cleared and animated rays will smear across frames.
- Never use blendMode "screen" or "lighter" on light or white backgrounds — rays become invisible. Use "multiply" instead.
- AnimParams has no opacityAmp field. Valid keys are: speed, angleAmp, lengthAmp, widthAmp, haloAmp.
- To make GodLights fill a container, pass style={{ position:"absolute", inset:0, width:"100%", height:"100%" }}. A Tailwind "absolute" class won't override the default position:relative.
- In Next.js App Router, always add "use client" at the top — GodLights uses useRef, useEffect, and requestAnimationFrame.
- Define SceneConfig outside the component or wrap it in useMemo. Constructing it inline causes unnecessary re-renders.
- originX and originY are percentages of scene width/height (0–100). blur is in absolute pixels and may need adjustment if scene dimensions change.

### Basic Scene Configuration

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/layer-system.md

This example demonstrates a basic scene setup with one background, one halo, and one ray layer. Ensure all necessary imports are included for `SceneConfig`.

```typescript
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1440,
  height: 900,
  noise: 8,
  grainSize: 1,
  layers: [
    {
      type: "background",
      bgType: "gradient",
      bgColor: "#0b1024",
      bgColor2: "#1a1340",
      bgGradientAngle: 180,
    },
    {
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffd28a",
      intensity: 0.35,
      size: 0.3,
      blendMode: "lighter",
    },
    {
      type: "rays",
      direction: 180,
      spread: 80,
      originX: 50,
      originY: -10,
      rayCount: 18,
      rayWidth: 52,
      divergence: 1.5,
      rayLength: 1.1,
      opacity: 0.3,
      blendMode: "screen",
      colorStart: "#ffd28a",
      colorEnd: "#ffd28a",
      fadeToTransparent: true,
      blur: 12,
      randomnessWidth: 35,
      randomnessLength: 20,
      randomnessAngle: 8,
      seed: 1200,
    },
  ],
};
```

--------------------------------

### Install and Run Locally

Source: https://github.com/gustavoquinalha/godlights/blob/main/AGENTS.md

Commands to install dependencies and run the development server or build the package.

```bash
npm install
npm run dev          # website at localhost:5173
npm run build:pkg    # build the godlights package
```

--------------------------------

### HaloLayer Example Configuration

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

An example of how to configure a HaloLayer object with specific properties.

```typescript
{
  type: "halo",
  originX: 50,
  originY: 0,
  color: "#3b82f6",
  intensity: 0.3,
  size: 0.45,
  blendMode: "lighter",
}
```

--------------------------------

### Common Pattern Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

An example demonstrating how to import and use default layer configurations to construct a scene.

```APIDOC
## Common Pattern Example

### Description
An example demonstrating how to import and use default layer configurations to construct a scene.

### Code
```typescript
import {
  DEFAULT_BACKGROUND_LAYER,
  DEFAULT_HALO_LAYER,
  DEFAULT_RAY_LAYER,
} from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1600,
  height: 900,
  noise: 8,
  grainSize: 1,
  layers: [
    { ...DEFAULT_BACKGROUND_LAYER, bgColor: "#050816", bgColor2: "#050816" },
    { ...DEFAULT_HALO_LAYER, color: "#ffffff" },
    { ...DEFAULT_RAY_LAYER, direction: 180 },
  ],
};
```

### Usage Note
Treat the default exports as templates, not shared mutable objects. Clone them with object spread before editing nested scene data, especially `DEFAULT_SCENE`, because the source exports a real object graph rather than a factory.
```

--------------------------------

### Install shadcn Components

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms.txt

Install pre-built Godlights components using the shadcn CLI. This command adds components for hero, background, and cycling effects.

```bash
npx shadcn@latest add "https://www.godlights.io/r/god-lights-hero.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-background.json"
npx shadcn@latest add "https://www.godlights.io/r/god-lights-cycling.json"
```

--------------------------------

### Paste Godlights Documentation Manually

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/ai-tools-setup.md

If your AI tool does not support Context7 MCP, you can paste the Godlights documentation directly. Use the provided URLs for the full API reference or quick start guides.

```text
https://context7.com/gustavoquinalha/godlights/llms.txt?tokens=10000
```

```text
https://www.godlights.io/llms.txt
```

```text
https://www.godlights.io/llms-full.txt
```

--------------------------------

### Use GodLightsBackground Component

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/ai-tools-setup.md

Example of how to use the installed GodLightsBackground component. This component allows for customizable backgrounds with color, background color, and animation parameters.

```tsx
import { GodLightsBackground } from "@/components/god-lights-background";

export function Section() {
  return (
    <GodLightsBackground color="#34d399" bgColor="#060f08" style={{ minHeight: "100vh" }}>
      <p>Content over animated rays</p>
    </GodLightsBackground>
  );
}
```

--------------------------------

### RayLayer Configuration Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

An example configuration for a `RayLayer`, specifying ray direction, spread, origin, count, width, divergence, length, color, opacity, blend mode, fading, blur, randomness, and RNG seed.

```ts
{
  type: "rays",
  direction: 180,
  spread: 100,
  originX: 50,
  originY: -15,
  rayCount: 30,
  rayWidth: 80,
  divergence: 1.6,
  rayLength: 1.2,
  colorStart: "#3b82f6",
  colorEnd: "#3b82f6",
  opacity: 0.2,
  blendMode: "screen",
  fadeToTransparent: true,
  blur: 12,
  randomnessWidth: 60,
  randomnessLength: 20,
  randomnessAngle: 15,
  seed: 42,
}
```

--------------------------------

### Complete Canvas Export Workflow Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/canvas-export-workflow.md

A comprehensive example demonstrating drawing a scene to a canvas, exporting it as a PNG Blob, creating a downloadable link, and generating a CSS background snippet. It includes scene definition and asynchronous operations.

```typescript
import { buildSceneCssSnippet, drawScene, exportScene } from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1200,
  height: 630,
  noise: 6,
  grainSize: 1,
  layers: [
    {
      type: "background",
      bgType: "gradient",
      bgColor: "#0b1024",
      bgColor2: "#050816",
      bgGradientAngle: 180,
    },
    {
      type: "halo",
      originX: 22,
      originY: 12,
      color: "#93c5fd",
      intensity: 0.18,
      size: 0.32,
      blendMode: "lighter",
    },
    {
      type: "rays",
      direction: 165,
      spread: 58,
      originX: 16,
      originY: -10,
      rayCount: 18,
      rayWidth: 54,
      divergence: 1.8,
      rayLength: 0.8,
      opacity: 0.22,
      blendMode: "screen",
      colorStart: "#93c5fd",
      colorEnd: "#93c5fd",
      fadeToTransparent: true,
      blur: 12,
      randomnessWidth: 40,
      randomnessLength: 20,
      randomnessAngle: 8,
      seed: 404,
    },
  ],
};

async function run() {
  const canvas = document.querySelector("canvas") as HTMLCanvasElement;
  canvas.width = scene.width;
  canvas.height = scene.height;

  drawScene(canvas, scene);

  const blob = await exportScene(scene, "image/png");
  const url = URL.createObjectURL(blob);

  const link = document.createElement("a");
  link.href = url;
  link.download = "godlights-og.png";
  link.click();
  URL.revokeObjectURL(url);

  const css = await buildSceneCssSnippet(scene);
  console.log(css);
}

run();
```

--------------------------------

### Local Development Commands

Source: https://github.com/gustavoquinalha/godlights/blob/main/README.md

Commands to install dependencies, run the development server, and build the project or its npm package.

```bash
npm install
npm run dev        # editor app → http://localhost:5173
npm run build      # production build
npm run build:pkg  # build the godlights npm package
```

--------------------------------

### Install Godlights using package managers

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/index.md

Install Godlights using your preferred package manager. Godlights is available via npm, pnpm, yarn, and bun.

```bash
npm install godlights
```

```bash
pnpm add godlights
```

```bash
yarn add godlights
```

```bash
bun add godlights
```

--------------------------------

### Install Godlights Package

Source: https://github.com/gustavoquinalha/godlights/blob/main/README.md

Install the Godlights React package using npm. This package contains the rendering engine with no runtime dependencies.

```bash
npm install godlights
```

--------------------------------

### Default Scene Configuration Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

Illustrates how to use default configurations like `DEFAULT_RAY_LAYER` and override specific properties to create a custom layer.

```typescript
import {
  DEFAULT_SCENE,
  DEFAULT_RAY_LAYER,
  DEFAULT_HALO_LAYER,
  DEFAULT_BACKGROUND_LAYER,
  DEFAULT_ANIM_PARAMS,
  BLEND_MODES,
} from "godlights";

// Spread defaults and override only what you need
const myLayer: RayLayer = {
  ...DEFAULT_RAY_LAYER,
  colorStart: "#ff6600",
  colorEnd: "#ff6600",
};
```

--------------------------------

### Export Scene as PNG Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

Demonstrates how to export the current scene as a PNG Blob and trigger a download in the browser. Requires importing `exportScene`.

```typescript
import { exportScene } from "godlights";

const blob = await exportScene(scene, "image/png");
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "rays.png";
a.click();
URL.revokeObjectURL(url);
```

--------------------------------

### Basic Scene Configuration Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/scene-config.md

Illustrates how to create a minimal SceneConfig object with basic dimensions, noise, grain settings, and a background layer. Additional layers like halo and ray layers can be added to the 'layers' array.

```typescript
import type { SceneConfig } from "godlights";

export const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,
  grainSize: 1,
  layers: [
    {
      type: "background",
      bgType: "gradient",
      bgColor: "#081122",
      bgColor2: "#02040a",
      bgGradientAngle: 180,
    },
  ],
};
```

--------------------------------

### Minimal Godlights Scene in React

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/index.md

A basic Godlights scene configuration for React, including a solid background, a ray fan, and a halo. This example demonstrates the minimal setup required for a functional scene. Ensure the background layer is always the first in the `layers` array.

```tsx
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1280,
  height: 720,
  noise: 6,
  grainSize: 1,
  layers: [
    {
      type: "background",
      bgType: "solid",
      bgColor: "#000000",
      bgColor2: "#000000",
      bgGradientAngle: 180,
    },
    {
      type: "rays",
      direction: 180,
      spread: 90,
      originX: 50,
      originY: -12,
      rayCount: 20,
      rayWidth: 60,
      divergence: 1.4,
      rayLength: 0.9,
      colorStart: "#ffffff",
      colorEnd: "#ffffff",
      opacity: 0.28,
      blendMode: "screen",
      fadeToTransparent: true,
      blur: 14,
      randomnessWidth: 40,
      randomnessLength: 25,
      randomnessAngle: 0,
      seed: 1337,
    },
    {
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffffff",
      intensity: 0.24,
      size: 0.35,
      blendMode: "lighter",
    },
  ],
};

export function Background() {
  return <GodLights scene={scene} className="w-full h-[480px]" ></GodLights>;
}

```

--------------------------------

### Build Scene CSS Snippet Example

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

Shows how to generate CSS background-image properties for a scene and apply them to an HTML element. Requires importing `buildSceneCssSnippet`.

```typescript
import { buildSceneCssSnippet } from "godlights";

const css = await buildSceneCssSnippet(scene);
document.getElementById("hero").style.cssText = css;
```

--------------------------------

### Use GodLightsHero Component

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/ai-tools-setup.md

Example of how to use the installed GodLightsHero component in your React application. Ensure the component is imported correctly from the '@/components/god-lights-hero' path.

```tsx
import { GodLightsHero } from "@/components/god-lights-hero";

export function HeroSection() {
  return (
    <GodLightsHero color="#a78bfa">
      <h1>Your content here</h1>
    </GodLightsHero>
  );
}
```

--------------------------------

### DEFAULT_SCENE

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

The default scene configuration, providing a complete starting point for a new scene.

```APIDOC
## DEFAULT_SCENE

### Description
The default scene configuration, providing a complete starting point for a new scene.

### Type
`SceneConfig`

### Usage Note
Treat default exports as templates. Clone them with object spread before editing nested scene data, especially `DEFAULT_SCENE`, as the source exports a real object graph, not a factory.
```

--------------------------------

### Add Godlights Components via shadcn Registry

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/ai-tools-setup.md

Install pre-built Godlights components directly into your project using the shadcn CLI. This automatically adds the component files and the godlights dependency.

```bash
# Hero section with animated rays and color prop
npx shadcn@latest add "https://www.godlights.io/r/god-lights-hero.json"
```

```bash
# Minimal background wrapper (color, bgColor, animParams props)
npx shadcn@latest add "https://www.godlights.io/r/god-lights-background.json"
```

```bash
# Auto-cycling presets with smooth cross-fade
npx shadcn@latest add "https://www.godlights.io/r/god-lights-cycling.json"
```

--------------------------------

### Cycling GodLights Presets with Transitions

Source: https://github.com/gustavoquinalha/godlights/blob/main/packages/godlights/README.md

Implement smooth transitions between different visual presets by swapping the `scene` prop. This example uses two GodLights instances and animates opacity for a cross-fade effect.

```tsx
"use client";
import { useState, useEffect, useRef } from "react";
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

const presets: SceneConfig[] = [
  {
    width: 1920, height: 1080, noise: 8, grainSize: 1,
    layers: [
      { type: "background", bgType: "solid", bgColor: "#06060f", bgColor2: "#06060f", bgGradientAngle: 180 },
      { type: "halo", originX: 20, originY: 5, color: "#a78bfa", intensity: 0.3, size: 0.5, blendMode: "lighter" },
      { type: "rays", direction: 160, spread: 70, originX: 20, originY: 5, rayCount: 24, rayWidth: 70, divergence: 1.8, rayLength: 1.0, colorStart: "#a78bfa", colorEnd: "#a78bfa", opacity: 0.18, blendMode: "screen", fadeToTransparent: true, blur: 12, randomnessWidth: 60, randomnessLength: 20, randomnessAngle: 15, seed: 1 },
    ],
  },
  {
    width: 1920, height: 1080, noise: 8, grainSize: 1,
    layers: [
      { type: "background", bgType: "solid", bgColor: "#060f08", bgColor2: "#060f08", bgGradientAngle: 180 },
      { type: "halo", originX: 80, originY: 5, color: "#34d399", intensity: 0.3, size: 0.5, blendMode: "lighter" },
      { type: "rays", direction: 200, spread: 70, originX: 80, originY: 5, rayCount: 24, rayWidth: 70, divergence: 1.8, rayLength: 1.0, colorStart: "#34d399", colorEnd: "#34d399", opacity: 0.18, blendMode: "screen", fadeToTransparent: true, blur: 12, randomnessWidth: 60, randomnessLength: 20, randomnessAngle: 15, seed: 2 },
    ],
  },
];

export function CyclingPresets() {
  const [current, setCurrent] = useState(0);
  const [next, setNext] = useState(1);
  const [fading, setFading] = useState(false);

  useEffect(() => {
    const id = setInterval(() => {
      setNext((current + 1) % presets.length);
      setFading(true);
      setTimeout(() => {
        setCurrent((c) => (c + 1) % presets.length);
        setFading(false);
      }, 800);
    }, 4000);
    return () => clearInterval(id);
  }, [current]);

  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights scene={presets[current]} animParams={{ speed: 1, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 }} style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }} />
      <GodLights
        scene={presets[next]}
        animParams={{ speed: 1, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 }}
        style={{
          position: "absolute", inset: 0, width: "100%", height: "100%",
          opacity: fading ? 1 : 0,
          transition: "opacity 0.8s ease",
        }}
      />
    </div>
  );
}

```

--------------------------------

### Dynamic Animation Parameters with useMemo

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms-full.txt

Example of using `useMemo` to dynamically update animation parameters based on activity level, ensuring efficient re-computation.

```tsx
const animParams = useMemo(() => ({
  speed: 0.5 + (activityLevel / 100) * 2,
  angleAmp: 20 + (activityLevel / 100) * 60,
  lengthAmp: 10 + (activityLevel / 100) * 50,
  widthAmp: 10 + (activityLevel / 100) * 40,
  haloAmp: 20 + (activityLevel / 100) * 60,
}), [activityLevel]);
```

--------------------------------

### Add godlights components with shadcn CLI

Source: https://github.com/gustavoquinalha/godlights/blob/main/packages/godlights/README.md

Install pre-made godlights components directly into your project using the shadcn CLI. This automatically adds godlights as a dependency.

```bash
# Hero section with animated rays
npx shadcn@latest add "https://www.godlights.io/r/god-lights-hero.json"
```

```bash
# Minimal background wrapper
npx shadcn@latest add "https://www.godlights.io/r/god-lights-background.json"
```

```bash
# Auto-cycling presets with cross-fade
npx shadcn@latest add "https://www.godlights.io/r/god-lights-cycling.json"
```

--------------------------------

### Default Ray Layer Configuration

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

Provides the safest starting point for configuring a new ray layer.

```typescript
export const DEFAULT_RAY_LAYER: RayLayer
```

--------------------------------

### GodLights Component Usage

Source: https://github.com/gustavoquinalha/godlights/blob/main/packages/godlights/README.md

Example of how to use the GodLights component in a React application with a sample scene configuration.

```APIDOC
## GodLights Component

### Description

This component renders animated god-ray and light-beam effects on a canvas.

### Usage

```tsx
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,
  grainSize: 1,
  layers: [
    {
      type: "background",
      bgType: "solid",
      bgColor: "#000000",
      bgColor2: "#000000",
      bgGradientAngle: 180,
    },
    // ... other layers
  ],
};

export default function App() {
  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights
        scene={scene}
        animParams={{ speed: 3, angleAmp: 40, lengthAmp: 30, widthAmp: 20, haloAmp: 50 }}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
    </div>
  );
}
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `scene` | `SceneConfig` | **required** | Full scene configuration |
| `animParams` | `AnimParams` | — | Pass to enable the animation loop; omit for a static render |
| `showFps` | `boolean` | `false` | Show FPS counter overlay |
| `className` | `string` | — | CSS class on the wrapper `<div>` |
| `style` | `CSSProperties` | — | Inline style on the wrapper `<div>` |

> **Positioning note:** The wrapper defaults to `position: relative`. For full-bleed use, pass `style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}` as an inline style — this takes precedence over any `className` you add.
```

--------------------------------

### Common Workflow for Exporting Assets

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/export-helpers.md

This example demonstrates a common workflow combining `exportScene` and `buildSceneCssSnippet` to export both a PNG Blob and CSS snippet from a scene. Both helpers create temporary canvases and render static frames.

```typescript
import { buildSceneCssSnippet, exportScene } from "godlights";

async function exportAssets(scene: SceneConfig) {
  const png = await exportScene(scene, "image/png");
  const css = await buildSceneCssSnippet(scene);
  return { png, css };
}
```

--------------------------------

### Static Godlights Render

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms.txt

Example of a static render using GodLights with a predefined scene configuration. Ensure the first layer is a BackgroundLayer to prevent smearing.

```tsx
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

// layers[0] MUST be a BackgroundLayer — it clears the canvas each frame.
// Without it, animated rays smear and trail across frames.
const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,        // film grain 0–100
  grainSize: 1,    // grain pixel size 1–4
  layers: [
    {
      type: "background",
      bgType: "solid",
      bgColor: "#000000",
      bgColor2: "#000000",
      bgGradientAngle: 180,
    },
    {
      type: "rays",
      direction: 180,       // compass degrees (0=up, 90=right, 180=down, 270=left)
      spread: 120,          // angular fan width in degrees
      originX: 50,          // % of canvas width (can exceed 0–100 for off-screen sources)
      originY: -20,         // % of canvas height (can be negative)
      rayCount: 40,
      rayWidth: 87,         // 1–200
      divergence: 0.4,      // 0.1–5
      rayLength: 0.55,      // fraction of canvas diagonal
      colorStart: "#ffffff",
      colorEnd: "#ffffff",
      opacity: 0.42,
      blendMode: "screen",  // use "overlay" or "soft-light" on light/white backgrounds
      fadeToTransparent: true,
      blur: 17.5,
      randomnessWidth: 100,
      randomnessLength: 24,
      randomnessAngle: 0,
      seed: 1337,
    },
    {
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffffff",
      intensity: 0.25,  // 0–1
      size: 0.5,        // fraction of canvas diagonal
      blendMode: "lighter",
    },
  ],
};

// Static render
export function Background() {
  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights scene={scene} style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }} />
    </div>
  );
}
```

--------------------------------

### GodLights Component Usage

Source: https://github.com/gustavoquinalha/godlights/blob/main/AGENTS.md

Example of how to use the GodLights component with scene configuration and animation parameters. Ensure the background layer is always the first layer with id 'background'.

```tsx
import { GodLights } from "godlights";
import { DEFAULT_RAY_LAYER, DEFAULT_HALO_LAYER } from "godlights";
import type { SceneConfig, RayLayer, HaloLayer, BackgroundLayer } from "godlights";

// Background must always be the first layer with id "background"
const scene: SceneConfig = {
  width: 1920, height: 1080, noise: 8, grainSize: 1,
  layers: [bgLayer, ...rayOrHaloLayers],
};

<GodLights scene={scene} animate animParams={{ speed: 1, angleAmp: 20 }} style={{ ... }} />
```

--------------------------------

### Download Godlights Cursor Rules

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms.txt

Download the Godlights rules for Cursor. Use the new format for `.cursor/rules/` or the legacy format for `.cursorrules`.

```bash
# New Cursor format (.cursor/rules/)
curl -o .cursor/rules/godlights.mdc https://www.godlights.io/godlights.mdc

# Legacy format (.cursorrules)
curl -o .cursorrules https://www.godlights.io/godlights.cursorrules
```

--------------------------------

### DEFAULT_ANIM_PARAMS

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

Default animation parameters to use as a starting point for ray animations.

```APIDOC
## DEFAULT_ANIM_PARAMS

### Description
Default animation parameters to use as a starting point for ray animations.

### Type
`AnimParams`

### Default Value
```json
{
  "speed": 1,
  "angleAmp": 50,
  "lengthAmp": 50,
  "widthAmp": 50,
  "haloAmp": 50
}
```
```

--------------------------------

### Common Scene Initialization Pattern

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

Demonstrates how to initialize a scene using default layer configurations and custom properties. Treat default exports as templates; clone them with object spread before editing nested data.

```typescript
import {
  DEFAULT_BACKGROUND_LAYER,
  DEFAULT_HALO_LAYER,
  DEFAULT_RAY_LAYER,
} from "godlights";
import type { SceneConfig } from "godlights";

const scene: SceneConfig = {
  width: 1600,
  height: 900,
  noise: 8,
  grainSize: 1,
  layers: [
    { ...DEFAULT_BACKGROUND_LAYER, bgColor: "#050816", bgColor2: "#050816" },
    { ...DEFAULT_HALO_LAYER, color: "#ffffff" },
    { ...DEFAULT_RAY_LAYER, direction: 180 },
  ],
};
```

--------------------------------

### DEFAULT_RAY_LAYER

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/api-reference/defaults-and-utilities.md

The default configuration for a ray layer, serving as a safe starting point for new ray layers.

```APIDOC
## DEFAULT_RAY_LAYER

### Description
The default configuration for a ray layer, serving as a safe starting point for new ray layers.

### Type
`RayLayer`
```

--------------------------------

### Using the GodLights Component for Animated Backgrounds

Source: https://context7.com/gustavoquinalha/godlights/llms.txt

Demonstrates how to use the `<GodLights>` component to create a full-bleed animated background. Ensure the component has explicit sizing via CSS. Define scene configuration and animation parameters outside the component or memoize them to prevent re-renders.

```tsx
import { GodLights } from "godlights";
import type { SceneConfig, AnimParams } from "godlights";
import { useMemo } from "react";

// Define scene outside the component (or memoize) — avoids re-rendering on every parent render
const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,        // film-grain intensity 0–100
  grainSize: 1,    // grain pixel size 1–20
  layers: [
    // layers[0] MUST be a BackgroundLayer — it clears the canvas each frame
    {
      id: "background",
      type: "background",
      bgType: "gradient",
      bgColor: "#0b1024",
      bgColor2: "#1a1340",
      bgGradientAngle: 180,
    },
    {
      id: "halo-1",
      name: "Sun glow",
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffd28a",
      intensity: 0.5,
      size: 0.25,
      blendMode: "lighter",
    },
    {
      id: "rays-1",
      name: "Sun rays",
      type: "rays",
      direction: 200,
      spread: 60,
      originX: 50,
      originY: 0,
      rayCount: 24,
      rayWidth: 60,
      divergence: 1.6,
      rayLength: 1.4,
      opacity: 0.6,
      blendMode: "lighter",
      colorStart: "#ffd28a",
      colorEnd: "#ffd28a",
      fadeToTransparent: true,
      blur: 8,
      randomnessWidth: 30,
      randomnessLength: 18,
      randomnessAngle: 30,
      seed: 1337,
    },
  ],
};

export function HeroSection() {
  const animParams: AnimParams = useMemo(() => ({
    speed: 1,
    angleAmp: 50,   // ray swing 0–100
    lengthAmp: 40,  // length pulsation 0–100
    widthAmp: 20,   // width breathing 0–100
    haloAmp: 50,    // halo size pulse 0–100
    // ⚠️ opacityAmp does NOT exist — TypeScript will catch it
  }), []);

  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      {/* Full-bleed animated background */}
      <GodLights
        scene={scene}
        animate                   // starts the requestAnimationFrame loop
        animParams={animParams}
        showFps                   // optional dev-mode FPS badge (top-right corner)
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
      {/* Content sits above the canvas */}
      <h1 style={{ position: "relative", color: "#fff" }}>Hello World</h1>
    </div>
  );
}

```

--------------------------------

### Animated Godlights Render

Source: https://github.com/gustavoquinalha/godlights/blob/main/public/llms.txt

Example of an animated render using GodLights by passing `animParams`. This activates the requestAnimationFrame loop for dynamic effects.

```tsx
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

// layers[0] MUST be a BackgroundLayer — it clears the canvas each frame.
// Without it, animated rays smear and trail across frames.
const scene: SceneConfig = {
  width: 1920,
  height: 1080,
  noise: 8,        // film grain 0–100
  grainSize: 1,    // grain pixel size 1–4
  layers: [
    {
      type: "background",
      bgType: "solid",
      bgColor: "#000000",
      bgColor2: "#000000",
      bgGradientAngle: 180,
    },
    {
      type: "rays",
      direction: 180,       // compass degrees (0=up, 90=right, 180=down, 270=left)
      spread: 120,          // angular fan width in degrees
      originX: 50,          // % of canvas width (can exceed 0–100 for off-screen sources)
      originY: -20,         // % of canvas height (can be negative)
      rayCount: 40,
      rayWidth: 87,         // 1–200
      divergence: 0.4,      // 0.1–5
      rayLength: 0.55,      // fraction of canvas diagonal
      colorStart: "#ffffff",
      colorEnd: "#ffffff",
      opacity: 0.42,
      blendMode: "screen",  // use "overlay" or "soft-light" on light/white backgrounds
      fadeToTransparent: true,
      blur: 17.5,
      randomnessWidth: 100,
      randomnessLength: 24,
      randomnessAngle: 0,
      seed: 1337,
    },
    {
      type: "halo",
      originX: 50,
      originY: 0,
      color: "#ffffff",
      intensity: 0.25,  // 0–1
      size: 0.5,        // fraction of canvas diagonal
      blendMode: "lighter",
    },
  ],
};

// Animated render — pass animParams to activate the RAF loop
export function AnimatedBackground() {
  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights
        scene={scene}
        animParams={{ speed: 3, angleAmp: 40, lengthAmp: 30, widthAmp: 20, haloAmp: 50 }}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
    </div>
  );
}
```

--------------------------------

### Monorepo Directory Structure

Source: https://github.com/gustavoquinalha/godlights/blob/main/README.md

Overview of the project's monorepo layout, detailing the purpose of each directory and key files.

```bash
/
├── src/                        # Editor app (React + Vite + Tailwind + shadcn/ui)
│   ├── pages/
│   │   ├── LandingPage.tsx
│   │   ├── PresetsPage.tsx
│   │   ├── DocsPage.tsx
│   │   └── PreviewPage.tsx
│   ├── components/
│   │   ├── GodRaysGenerator.tsx  # main editor UI
│   │   └── ui/                   # shadcn components
│   └── lib/
│       ├── presets.ts
│       ├── share.ts              # URL encode/decode
│       └── utils.ts
├── packages/
│   └── godlights/              # npm package
│       ├── src/
│       │   ├── GodLights.tsx   # React component
│       │   ├── godrays.ts      # Canvas 2D rendering engine
│       │   └── index.ts
│       └── package.json
├── public/
│   ├── llms.txt                # AI-friendly quick start
│   ├── llms-full.txt           # Full API reference for LLMs
│   ├── registry.json           # shadcn registry index
│   ├── r/                      # shadcn registry items (hero, background, cycling)
│   ├── godlights.mdc           # Cursor rules file (.cursor/rules/ format)
│   └── godlights.cursorrules   # Cursor rules file (legacy .cursorrules format)
└── index.html
```

--------------------------------

### Define a Stable Scene Configuration

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/react-hero-background.md

Use `useMemo` to define a stable scene configuration object for GodLights. This includes background properties, halo effects, and rays, ensuring consistent animation.

```tsx
import {
  useMemo
} from "react";
import type { SceneConfig } from "godlights";

export function useHeroScene(): SceneConfig {
  return useMemo(
    () => ({
      width: 1920,
      height: 1080,
      noise: 8,
      grainSize: 1,
      layers: [
        {
          type: "background",
          bgType: "gradient",
          bgColor: "#050816",
          bgColor2: "#0b1024",
          bgGradientAngle: 180,
        },
        {
          type: "halo",
          originX: 18,
          originY: 5,
          color: "#ffffff",
          intensity: 0.18,
          size: 0.46,
          blendMode: "lighter",
        },
        {
          type: "rays",
          direction: 160,
          spread: 65,
          originX: 14,
          originY: -16,
          rayCount: 24,
          rayWidth: 76,
          divergence: 1.9,
          rayLength: 0.82,
          opacity: 0.2,
          blendMode: "screen",
          colorStart: "#ffffff",
          colorEnd: "#ffffff",
          fadeToTransparent: true,
          blur: 18,
          randomnessWidth: 75,
          randomnessLength: 25,
          randomnessAngle: 8,
          seed: 42,
        },
      ],
    }),
    []
  );
}
```

--------------------------------

### Use GodLightsBackground Across Sections

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/reusable-wrapper.md

Demonstrates applying the GodLightsBackground wrapper with different configurations for color, origin, and animation across various UI sections. For performance, omit `animParams` for static sections and keep `rayCount` low.

```tsx
const defaultAnimParams = { speed: 1, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 };

// Purple — top-left origin, animated
<div style={{ position: "relative", minHeight: "100vh" }}>
  <GodLightsBackground
    color="#a78bfa"
    originX={20}
    originY={5}
    animParams={defaultAnimParams}
    style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
  />
  <div style={{ position: "relative", zIndex: 1 }}>Hero content</div>
</div>

// Warm amber — top-right, slower animation
<div style={{ position: "relative", height: 400 }}>
  <GodLightsBackground
    color="#ffd28a"
    originX={80}
    originY={0}
    direction={200}
    animParams={{ speed: 0.5, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 }}
    style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
  />
</div>

// Teal — static, no animation
<div style={{ position: "relative", height: 400 }}>
  <GodLightsBackground
    color="#34d399"
    style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
  />
</div>
```

--------------------------------

### Download Cursor Rule for Godlights

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/ai-tools-setup.md

Use this command to download the Godlights rules file for Cursor. This enables automatic application of Godlights when requesting light effects or backgrounds.

```bash
curl -o .cursor/rules/godlights.mdc https://www.godlights.io/godlights.mdc
```

```bash
curl -o .cursorrules https://www.godlights.io/godlights.cursorrules
```

--------------------------------

### Reactive Mouse Tracking Background with GodLights

Source: https://github.com/gustavoquinalha/godlights/blob/main/packages/godlights/README.md

Use this component to create a dynamic background that reacts to mouse movement. Wrap the scene configuration in `useMemo` to optimize performance by recomputing only when mouse position changes.

```tsx
"use client";
import { useState, useCallback, useMemo } from "react";
import { GodLights, DEFAULT_BACKGROUND_LAYER, DEFAULT_HALO_LAYER, DEFAULT_RAY_LAYER } from "godlights";
import type { SceneConfig } from "godlights";

export function MouseTrackingBackground() {
  const [mouse, setMouse] = useState({ x: 50, y: 10 });

  const handleMouseMove = useCallback((e: React.MouseEvent<HTMLDivElement>) => {
    const rect = e.currentTarget.getBoundingClientRect();
    setMouse({
      x: ((e.clientX - rect.left) / rect.width) * 100,
      y: ((e.clientY - rect.top) / rect.height) * 100,
    });
  }, []);

  const scene: SceneConfig = useMemo(() => ({
    width: 1920,
    height: 1080,
    noise: 6,
    grainSize: 1,
    layers: [
      { ...DEFAULT_BACKGROUND_LAYER, bgColor: "#06060f" },
      { ...DEFAULT_HALO_LAYER, originX: mouse.x, originY: mouse.y, color: "#a78bfa", intensity: 0.28, size: 0.45 },
      { ...DEFAULT_RAY_LAYER, originX: mouse.x, originY: mouse.y, direction: 180, spread: 80, colorStart: "#a78bfa", colorEnd: "#a78bfa", opacity: 0.18 },
    ],
  }), [mouse]);

  return (
    <div
      style={{ position: "relative", width: "100%", height: "100vh" }}
      onMouseMove={handleMouseMove}
    >
      <GodLights
        scene={scene}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
      <div style={{ position: "relative", zIndex: 1 }}>{/* content */}</div>
    </div>
  );
}

```

--------------------------------

### Simple Preset Swap with GodLights

Source: https://github.com/gustavoquinalha/godlights/blob/main/docs/codedocs/guides/preset-transitions.md

Swaps between scene presets immediately by updating the `scene` prop. The animation loop continues seamlessly without any visual interruption. This is suitable when instant changes are desired.

```tsx
"use client";
import { useState } from "react";
import { GodLights } from "godlights";
import type { SceneConfig } from "godlights";

const presets: SceneConfig[] = [
  {
    width: 1920, height: 1080, noise: 8, grainSize: 1,
    layers: [
      { type: "background", bgType: "solid", bgColor: "#06060f", bgColor2: "#06060f", bgGradientAngle: 180 },
      { type: "halo", originX: 20, originY: 5, color: "#a78bfa", intensity: 0.3, size: 0.5, blendMode: "lighter" },
      { type: "rays", direction: 160, spread: 70, originX: 20, originY: 5, rayCount: 24, rayWidth: 70, divergence: 1.8, rayLength: 1.0, colorStart: "#a78bfa", colorEnd: "#a78bfa", opacity: 0.18, blendMode: "screen", fadeToTransparent: true, blur: 12, randomnessWidth: 60, randomnessLength: 20, randomnessAngle: 15, seed: 1 },
    ],
  },
  {
    width: 1920, height: 1080, noise: 8, grainSize: 1,
    layers: [
      { type: "background", bgType: "solid", bgColor: "#060f08", bgColor2: "#060f08", bgGradientAngle: 180 },
      { type: "halo", originX: 80, originY: 5, color: "#34d399", intensity: 0.3, size: 0.5, blendMode: "lighter" },
      { type: "rays", direction: 200, spread: 70, originX: 80, originY: 5, rayCount: 24, rayWidth: 70, divergence: 1.8, rayLength: 1.0, colorStart: "#34d399", colorEnd: "#34d399", opacity: 0.18, blendMode: "screen", fadeToTransparent: true, blur: 12, randomnessWidth: 60, randomnessLength: 20, randomnessAngle: 15, seed: 2 },
    ],
  },
];

const animParams = { speed: 1, angleAmp: 40, lengthAmp: 25, widthAmp: 15, haloAmp: 40 };

export function PresetSwitcher() {
  const [index, setIndex] = useState(0);

  return (
    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
      <GodLights
        scene={presets[index]}
        animParams={animParams}
        style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
      />
      <div style={{ position: "relative", zIndex: 1 }}>
        <button onClick={() => setIndex((i) => (i + 1) % presets.length)}>
          Next preset
        </button>
      </div>
    </div>
  );
}

```