godlights 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,29 +1,119 @@
 import { default as default_2 } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 
-/** Parameters that control the animation loop — not persisted in scene. */
+/**
+ * Parameters that drive the animation loop. These are **not** stored inside
+ * `SceneConfig` — they live separately so that the same scene can be rendered
+ * statically or animated without touching the scene object.
+ *
+ * **Common mistake:** there is NO `opacityAmp` field. The only amplitude
+ * controls are `angleAmp`, `lengthAmp`, `widthAmp`, and `haloAmp`.
+ *
+ * @example
+ * // Gentle sway, no width variation
+ * const anim: AnimParams = {
+ *   speed: 0.8,
+ *   angleAmp: 60,
+ *   lengthAmp: 40,
+ *   widthAmp: 0,   // ← set to 0 to disable an axis entirely
+ *   haloAmp: 50,
+ * };
+ */
 export declare interface AnimParams {
-    /** Time multiplier — higher = faster (default 1). */
+    /**
+     * Global time multiplier. Scales how fast the elapsed-time clock ticks.
+     * 1.0 = real-time, 2.0 = twice as fast, 0.5 = slow motion.
+     * Range: 0.01–10. Default: 1.
+     */
     speed: number;
-    /** Angle swing intensity 0–100 (default 50). */
+    /**
+     * Controls how much each ray's angle oscillates per frame.
+     * 0 = rays never swing, 100 = maximum swing.
+     * Range: 0–100. Default: 50.
+     */
     angleAmp: number;
-    /** Ray length oscillation intensity 0–100 (default 50). */
+    /**
+     * Controls how much each ray's length pulsates.
+     * 0 = static length, 100 = maximum pulsation.
+     * Range: 0–100. Default: 50.
+     */
     lengthAmp: number;
-    /** Ray width oscillation intensity 0–100 (default 50). */
+    /**
+     * Controls how much each ray's width breathes in and out.
+     * 0 = static width, 100 = maximum variation.
+     * Range: 0–100. Default: 50.
+     */
     widthAmp: number;
-    /** Halo pulse intensity 0–100 (default 50). */
+    /**
+     * Controls how much the halo radius pulses.
+     * 0 = static halo, 100 = most pronounced pulse.
+     * Range: 0–100. Default: 50.
+     */
     haloAmp: number;
 }
 
+/**
+ * The mandatory first layer in every scene. It clears the canvas and paints
+ * the backdrop before any rays or halos are composited on top.
+ *
+ * **This must always be `layers[0]`.** If it is missing or placed at any
+ * other index the canvas will not be cleared between animation frames, causing
+ * ray trails and other visual artifacts.
+ *
+ * @example
+ * const bg: BackgroundLayer = {
+ *   id: "background",       // must be the literal string "background"
+ *   type: "background",
+ *   bgType: "gradient",
+ *   bgColor: "#0b1024",     // gradient start (top by default)
+ *   bgColor2: "#1a1340",    // gradient end (bottom by default)
+ *   bgGradientAngle: 180,   // 180° = top-to-bottom
+ * };
+ */
 export declare interface BackgroundLayer {
+    /**
+     * Fixed identifier — must always be the string literal `"background"`.
+     * Only one BackgroundLayer per scene is supported.
+     */
     id: "background";
+    /** Discriminator — always `"background"` for this layer type. */
     type: "background";
+    /**
+     * Controls how the background is drawn.
+     * - `"transparent"` — nothing is painted; the canvas keeps whatever was
+     *   there before (or the browser default, usually white/transparent).
+     * - `"solid"` — fills the canvas with `bgColor`.
+     * - `"gradient"` — linear gradient from `bgColor` to `bgColor2`.
+     */
     bgType: BackgroundType;
+    /**
+     * Primary background color (solid fill, or gradient start).
+     * CSS hex string, e.g. `"#0b1024"`.
+     */
     bgColor: string;
+    /**
+     * Secondary background color used as the gradient end when
+     * `bgType === "gradient"`. Ignored for `"solid"` and `"transparent"`.
+     */
     bgColor2: string;
+    /**
+     * Angle of the linear gradient in degrees. 0 = left-to-right,
+     * 90 = bottom-to-top, 180 = top-to-bottom (default), 270 = top-to-bottom.
+     * Range: 0–360.
+     */
     bgGradientAngle: number;
 }
 
+/**
+ * How the background layer fills the canvas.
+ *
+ * - `"transparent"` — does not paint anything; the canvas keeps its current
+ *   state (or whatever the browser renders behind it). Useful when the
+ *   component is overlaid on top of existing content.
+ * - `"solid"` — fills the entire canvas with `bgColor`.
+ * - `"gradient"` — fills with a linear gradient from `bgColor` to `bgColor2`
+ *   at the angle specified by `bgGradientAngle`.
+ */
 export declare type BackgroundType = "transparent" | "solid" | "gradient";
 
 export declare const BLEND_MODES: {
@@ -32,8 +122,43 @@ export declare const BLEND_MODES: {
 }[];
 
 /**
- * God Rays / Light Rays rendering engine
- * Supports multiple independent ray and halo layers per scene.
+ * God Rays / Light Rays rendering engine.
+ *
+ * Renders a layered scene of light rays, halos, and backgrounds onto a
+ * `HTMLCanvasElement`. Supports static one-shot rendering and a
+ * `requestAnimationFrame` loop driven by an elapsed-time clock.
+ *
+ * **Typical layer stack (back → front)**
+ * 1. `BackgroundLayer` (index 0, **required** — clears the canvas each frame)
+ * 2. One or more `HaloLayer`s
+ * 3. One or more `RayLayer`s
+ *
+ * @example
+ * // Minimal static render
+ * import { drawScene, DEFAULT_SCENE } from "./godrays";
+ * const canvas = document.createElement("canvas");
+ * canvas.width = 1920; canvas.height = 1080;
+ * drawScene(canvas, DEFAULT_SCENE);
+ * document.body.appendChild(canvas);
+ */
+/**
+ * Canvas 2-D composite operation to use when blending a layer onto the scene.
+ *
+ * **Choosing the right mode:**
+ * - `"screen"` / `"lighter"` — additive-style brightening. Only looks correct
+ *   on **dark backgrounds**; on light backgrounds they blow out to white.
+ * - `"multiply"` — darkening blend. Use on **light/white backgrounds** to keep
+ *   the rays visible without washing them out.
+ * - `"source-over"` — plain alpha compositing, background-agnostic.
+ * - `"overlay"` / `"soft-light"` / `"hard-light"` — contrast-boosting blends;
+ *   effect depends heavily on the underlying colors.
+ *
+ * @example
+ * // Good for a dark background
+ * const darkBgRay: Partial<RayLayer> = { blendMode: "lighter" };
+ *
+ * // Good for a light/white background
+ * const lightBgRay: Partial<RayLayer> = { blendMode: "multiply" };
  */
 export declare type BlendMode = "source-over" | "lighter" | "screen" | "overlay" | "soft-light" | "hard-light";
 
@@ -43,45 +168,307 @@ export declare function buildSceneCssSnippet(scene: SceneConfig): Promise<string
 
 export declare const DEFAULT_ANIM_PARAMS: AnimParams;
 
+/**
+ * Ready-to-use solid black `BackgroundLayer`. Use as `layers[0]` in every
+ * scene. The `id` is already set to the required literal `"background"`.
+ *
+ * @example
+ * const scene: SceneConfig = {
+ *   width: 1920, height: 1080, noise: 8, grainSize: 1,
+ *   layers: [
+ *     { ...DEFAULT_BACKGROUND_LAYER, bgColor: "#0b1024" },
+ *     { ...DEFAULT_HALO_LAYER, id: "halo-1", name: "Halo" },
+ *   ],
+ * };
+ */
 export declare const DEFAULT_BACKGROUND_LAYER: BackgroundLayer;
 
 export declare const DEFAULT_CONFIG: GodRaysConfig;
 
+/**
+ * Ready-to-use base values for a `HaloLayer`. Spread and add `id` / `name`.
+ *
+ * Produces a white glow at the top-center of the canvas, with radius = 25% of
+ * the canvas diagonal, peak intensity 0.5, and additive `"lighter"` blending.
+ *
+ * @example
+ * const myHalo: HaloLayer = { ...DEFAULT_HALO_LAYER, id: "halo-2", name: "Secondary glow" };
+ */
 export declare const DEFAULT_HALO_LAYER: Omit<HaloLayer, "id" | "name">;
 
+/**
+ * Ready-to-use base values for a `RayLayer`. Spread this object and supply
+ * the required `id` and `name` fields to create a new layer quickly.
+ *
+ * Produces a white, top-centered fan pointing downward with 24 rays,
+ * additive `"lighter"` blending (dark backgrounds only), and a soft 8 px blur.
+ *
+ * @example
+ * const myRays: RayLayer = { ...DEFAULT_RAY_LAYER, id: "rays-2", name: "Accent rays" };
+ */
 export declare const DEFAULT_RAY_LAYER: Omit<RayLayer, "id" | "name">;
 
+/**
+ * A complete, ready-to-render scene: 1920×1080, solid black background, one
+ * white halo, and one 24-ray fan. Safe to pass directly to `drawScene` or
+ * the `<GodLights>` component.
+ *
+ * Deep-clone this object before mutating it so that multiple scenes do not
+ * share the same layer array reference.
+ *
+ * @example
+ * import { drawScene, DEFAULT_SCENE } from "./godrays";
+ *
+ * const canvas = document.createElement("canvas");
+ * canvas.width = DEFAULT_SCENE.width;
+ * canvas.height = DEFAULT_SCENE.height;
+ * drawScene(canvas, DEFAULT_SCENE);
+ * document.body.appendChild(canvas);
+ */
 export declare const DEFAULT_SCENE: SceneConfig;
 
 export declare function drawGodRays(canvas: HTMLCanvasElement, config: GodRaysConfig): void;
 
+/**
+ * Renders a complete `SceneConfig` onto a `HTMLCanvasElement`.
+ *
+ * Call this once for a static image, or on every `requestAnimationFrame` tick
+ * for animation — increment `time` by `deltaSeconds * speed` each frame.
+ *
+ * The canvas `width` and `height` attributes are **not** set by this function;
+ * make sure they match `scene.width` / `scene.height` before calling.
+ *
+ * @param canvas - Target canvas element. Must already be appended to the DOM
+ *   (or at least have a valid 2-D context) before this is called.
+ * @param scene  - Scene configuration. `scene.layers[0]` **must** be a
+ *   `BackgroundLayer`; otherwise the canvas is not cleared between frames and
+ *   you will see ghosting / smearing artifacts.
+ * @param time   - Elapsed animation time in seconds (default `0`). When `0`,
+ *   every ray is rendered at its rest position with no oscillation. Pass a
+ *   monotonically increasing value to animate.
+ * @param anim   - Optional amplitude modifiers. Only used when `time !== 0`.
+ *   **Note:** there is no `opacityAmp` — the valid keys are `speed`,
+ *   `angleAmp`, `lengthAmp`, `widthAmp`, and `haloAmp`.
+ * @param skipGrain - When `true`, the film-grain pass is skipped. Set this to
+ *   `true` in animated mode when grain is handled by a separate static overlay
+ *   canvas (as `GodLights` does) to avoid re-generating grain every frame.
+ *
+ * @example
+ * // Static render
+ * const canvas = document.getElementById("canvas") as HTMLCanvasElement;
+ * canvas.width = scene.width;
+ * canvas.height = scene.height;
+ * drawScene(canvas, scene);
+ *
+ * @example
+ * // Animated render loop
+ * let time = 0;
+ * let last: number | null = null;
+ * const anim: AnimParams = { speed: 1, angleAmp: 50, lengthAmp: 50, widthAmp: 50, haloAmp: 50 };
+ *
+ * function frame(ts: number) {
+ *   if (last !== null) time += ((ts - last) / 1000) * anim.speed;
+ *   last = ts;
+ *   drawScene(canvas, scene, time, anim);
+ *   requestAnimationFrame(frame);
+ * }
+ * requestAnimationFrame(frame);
+ */
 export declare function drawScene(canvas: HTMLCanvasElement, scene: SceneConfig, time?: number, anim?: AnimParams, skipGrain?: boolean): void;
 
+/**
+ * Renders the legacy flat `GodRaysConfig` and returns the result as a PNG or
+ * JPEG data URL string (a `"data:image/..."` Base64-encoded string).
+ *
+ * Use this when you need an inline image string — e.g. to set as a CSS
+ * `background-image`, embed in an `<img src>`, or store in `localStorage`.
+ * For downloads or network uploads, prefer `exportScene` which returns a
+ * `Blob` instead (more memory-efficient for large images).
+ *
+ * @param config  - Legacy flat config. For the layer-based API use
+ *   `exportScene` with a `SceneConfig` instead.
+ * @param type    - MIME type: `"image/png"` or `"image/jpeg"`.
+ * @param quality - JPEG quality 0–1 (default `0.95`). Ignored for PNG.
+ * @returns A `Promise` resolving to a Base64 data URL string.
+ *
+ * @example
+ * const dataUrl = await exportDataURL(config, "image/png");
+ * document.body.style.backgroundImage = `url("${dataUrl}")`;
+ */
 export declare function exportDataURL(config: GodRaysConfig, type: "image/png" | "image/jpeg", quality?: number): Promise<string>;
 
 export declare function exportImage(config: GodRaysConfig, type: "image/png" | "image/jpeg", quality?: number): Promise<Blob>;
 
+/**
+ * Renders `scene` at its native resolution and returns the result as a PNG or
+ * JPEG `Blob` suitable for `URL.createObjectURL`, `<a download>`, or
+ * `FormData` uploads.
+ *
+ * Internally creates a temporary off-screen `<canvas>` (never attached to the
+ * DOM), draws the full scene statically (`time = 0`, grain enabled), and calls
+ * `canvas.toBlob`.
+ *
+ * @param scene   - Scene to render. Uses `scene.width` × `scene.height` as the
+ *   canvas dimensions.
+ * @param type    - MIME type. Use `"image/png"` for lossless export or
+ *   `"image/jpeg"` for smaller files with lossy compression.
+ * @param quality - Compression quality for JPEG, 0–1 (default `0.95`).
+ *   Ignored for PNG.
+ * @returns A `Promise` that resolves to a `Blob` containing the encoded image.
+ *
+ * @example
+ * const blob = await exportScene(scene, "image/png");
+ * const url = URL.createObjectURL(blob);
+ * const a = document.createElement("a");
+ * a.href = url;
+ * a.download = "godlights.png";
+ * a.click();
+ * URL.revokeObjectURL(url);
+ */
 export declare function exportScene(scene: SceneConfig, type: "image/png" | "image/jpeg", quality?: number): Promise<Blob>;
 
 /**
- * Standalone Godlights canvas component.
+ * Standalone canvas component that renders a Godlights scene.
+ *
+ * The outer wrapper is a `position: relative` `<div>` with `overflow: hidden`.
+ * Inside it, one `<canvas>` is used for the main render. In animated mode a
+ * second `<canvas>` is added as a fixed grain overlay — grain is drawn once
+ * and composited with `mixBlendMode: "overlay"`, avoiding the cost of
+ * regenerating noise on every frame.
+ *
+ * **Positioning:** the component does not set its own size. You must give it
+ * explicit dimensions via `className`, `style`, or a parent constraint.
+ * For a full-bleed background behind other content:
+ *
+ * ```tsx
+ * // Parent must have position: relative (or absolute/fixed)
+ * <div style={{ position: "relative" }}>
+ *   <GodLights
+ *     scene={myScene}
+ *     style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
+ *   />
+ *   <p style={{ position: "relative" }}>Content on top</p>
+ * </div>
+ * ```
+ *
+ * **Blend modes:** `scene` layers using `blendMode: "screen"` or
+ * `blendMode: "lighter"` look correct only on dark backgrounds. Switch to
+ * `blendMode: "multiply"` when the background layer is light or white.
+ *
+ * **`opacityAmp` does not exist.** The animation amplitude fields are:
+ * `angleAmp`, `lengthAmp`, `widthAmp`, and `haloAmp` (all 0–100).
+ *
+ * @example
+ * // Static render — draws once, no RAF loop
+ * import { GodLights, DEFAULT_SCENE } from "@your-org/godlights";
+ *
+ * export function HeroBackground() {
+ *   return (
+ *     <GodLights
+ *       scene={DEFAULT_SCENE}
+ *       className="w-full h-64"
+ *     />
+ *   );
+ * }
  *
  * @example
- * <GodLights scene={myScene} className="w-full h-full" />
- * <GodLights scene={myScene} animate animParams={{ speed: 1, angleAmp: 50, lengthAmp: 50, widthAmp: 50, haloAmp: 50 }} />
+ * // Animated render — continuous RAF loop with custom amplitudes
+ * import { GodLights, DEFAULT_SCENE, AnimParams } from "@your-org/godlights";
+ * import { useMemo } from "react";
+ *
+ * export function AnimatedBackground() {
+ *   const animParams: AnimParams = useMemo(() => ({
+ *     speed: 1,
+ *     angleAmp: 60,   // moderate swing
+ *     lengthAmp: 40,  // subtle length pulsation
+ *     widthAmp: 20,   // gentle width breathing
+ *     haloAmp: 50,    // standard halo pulse
+ *     // ⚠️ opacityAmp does NOT exist — omit it
+ *   }), []);
+ *
+ *   return (
+ *     <div style={{ position: "relative", height: 480 }}>
+ *       <GodLights
+ *         scene={DEFAULT_SCENE}
+ *         animate
+ *         animParams={animParams}
+ *         showFps   // optional FPS badge for dev
+ *         style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
+ *       />
+ *       <h1 style={{ position: "relative", color: "#fff" }}>Hello</h1>
+ *     </div>
+ *   );
+ * }
  */
 export declare function GodLights({ scene, animate, animParams, showFps, className, style, }: GodLightsProps): JSX_2.Element;
 
+/**
+ * Props for the `<GodLights>` React component.
+ *
+ * **Positioning note:** the component renders a `position: relative` `<div>`
+ * that contains one or two absolutely-positioned `<canvas>` elements. To make
+ * it fill a parent container as a full-bleed background, give the parent
+ * `position: relative` (or `absolute`) and pass:
+ * ```tsx
+ * style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
+ * ```
+ */
 export declare interface GodLightsProps {
-    /** Full scene configuration — use the Godlights editor to build this. */
+    /**
+     * Full scene configuration describing the background, halos, and ray layers.
+     * Build this with the Godlights visual editor, or construct it manually
+     * using `DEFAULT_SCENE` / `DEFAULT_RAY_LAYER` as starting points.
+     *
+     * **`scene.layers[0]` must be a `BackgroundLayer`** — it is the only thing
+     * that clears the canvas between animation frames. Omitting it causes ray
+     * trails in animated mode.
+     *
+     * The component re-renders whenever this prop reference changes, so avoid
+     * constructing the object inline in JSX; memoize it with `useMemo` or
+     * define it outside the component.
+     */
     scene: SceneConfig;
-    /** Enable animation loop. */
+    /**
+     * When `true`, starts a `requestAnimationFrame` loop that continuously
+     * redraws the scene with an incrementing time clock, producing smooth
+     * animation. When `false` (default), the scene is drawn once statically.
+     */
     animate?: boolean;
-    /** Animation parameters (speed, amplitudes). Only used when animate=true. */
+    /**
+     * Amplitude and speed settings for the animation loop. Only consulted when
+     * `animate={true}`.
+     *
+     * **Common mistake:** there is NO `opacityAmp` field. The valid keys are:
+     * - `speed` — global time multiplier (default `1`)
+     * - `angleAmp` — ray swing amount 0–100 (default `50`)
+     * - `lengthAmp` — ray length pulsation 0–100 (default `50`)
+     * - `widthAmp` — ray width breathing 0–100 (default `50`)
+     * - `haloAmp` — halo size pulse 0–100 (default `50`)
+     *
+     * Omit this prop to use the defaults from `DEFAULT_ANIM_PARAMS`.
+     */
     animParams?: AnimParams;
-    /** Show FPS counter overlay. Only visible when animate=true. */
+    /**
+     * When `true`, a small FPS counter badge is rendered in the top-right corner
+     * of the canvas. Only visible when `animate={true}`. Useful during
+     * development to check rendering performance. Default: `false`.
+     */
     showFps?: boolean;
+    /**
+     * Optional CSS class name applied to the outer wrapper `<div>`.
+     * Useful for Tailwind sizing utilities, e.g. `className="w-full h-full"`.
+     */
     className?: string;
+    /**
+     * Inline styles merged onto the outer wrapper `<div>`, which already has
+     * `position: "relative"` and `overflow: "hidden"` set.
+     *
+     * **Full-bleed background pattern** — add this to a relatively-positioned
+     * parent and pass:
+     * ```tsx
+     * style={{ position: "absolute", inset: 0, width: "100%", height: "100%" }}
+     * ```
+     */
     style?: default_2.CSSProperties;
 }
 
@@ -121,15 +508,60 @@ export declare interface GodRaysConfig {
     seed: number;
 }
 
+/**
+ * A layer that renders a soft radial glow centered on a point. Useful for
+ * simulating a light source (sun, lamp, portal, etc.) at the ray origin.
+ *
+ * @example
+ * const halo: HaloLayer = {
+ *   id: "halo-1",
+ *   type: "halo",
+ *   name: "Sun glow",
+ *   originX: 50,       // center of canvas
+ *   originY: 0,        // top edge
+ *   intensity: 0.5,    // 0–1 peak opacity at center
+ *   size: 0.25,        // radius = 25% of canvas diagonal
+ *   color: "#ffd28a",  // warm amber
+ *   blendMode: "lighter",
+ * };
+ */
 export declare interface HaloLayer {
+    /** Unique identifier. Must be distinct from all other layer ids. */
     id: string;
+    /** Discriminator — always `"halo"` for this layer type. */
     type: "halo";
+    /** Human-readable label shown in the editor UI. */
     name: string;
+    /**
+     * Horizontal center of the halo as a percentage of canvas width.
+     * Range: 0–100. 50 = horizontally centered.
+     */
     originX: number;
+    /**
+     * Vertical center of the halo as a percentage of canvas height.
+     * Range: 0–100. 0 = top edge, 100 = bottom edge.
+     */
     originY: number;
+    /**
+     * Peak opacity at the center of the radial gradient.
+     * Range: 0–1. 0 = invisible, 1 = fully opaque at center.
+     */
     intensity: number;
+    /**
+     * Radius of the halo as a multiplier of the canvas diagonal.
+     * 0.25 means the halo radius is 25% of `Math.hypot(width, height)`.
+     * Range: 0.01–2. Typical: 0.1–0.5.
+     */
     size: number;
+    /**
+     * CSS hex color of the glow.
+     * @example "#ffffff"
+     */
     color: string;
+    /**
+     * Canvas composite operation. Use `"lighter"` or `"screen"` for dark
+     * backgrounds; use `"multiply"` for light/white backgrounds.
+     */
     blendMode: BlendMode;
 }
 
@@ -143,38 +575,199 @@ export declare type Layer = RayLayer | HaloLayer | BackgroundLayer;
 
 export declare function mulberry32(seed: number): () => number;
 
+/**
+ * A layer that renders a fan of light-beam polygons radiating from an origin
+ * point. All numeric positions are expressed as percentages of the canvas
+ * dimensions (0–100) unless otherwise noted.
+ *
+ * @example
+ * const rays: RayLayer = {
+ *   id: "rays-1",
+ *   type: "rays",
+ *   name: "Sun rays",
+ *   direction: 200,       // pointing downward-left (compass degrees)
+ *   spread: 60,           // 60° fan
+ *   originX: 50,          // centered horizontally
+ *   originY: 0,           // at the top edge
+ *   rayCount: 24,
+ *   rayWidth: 60,         // px at the origin end
+ *   divergence: 1.6,      // tip is 1.6× wider than the base
+ *   rayLength: 1.4,       // 1.4× the canvas diagonal
+ *   opacity: 0.6,         // 0–1
+ *   blendMode: "lighter", // additive — good on dark backgrounds
+ *   colorStart: "#ffffff",
+ *   colorEnd: "#ffffff",
+ *   fadeToTransparent: true,
+ *   blur: 8,
+ *   randomnessWidth: 30,
+ *   randomnessLength: 18,
+ *   randomnessAngle: 30,
+ *   seed: 1337,
+ * };
+ */
 export declare interface RayLayer {
+    /** Unique identifier. Must be distinct from all other layer ids. */
     id: string;
+    /** Discriminator — always `"rays"` for this layer type. */
     type: "rays";
+    /** Human-readable label shown in the editor UI. */
     name: string;
+    /**
+     * Compass bearing the rays point toward, in degrees. 0 = North (up),
+     * 90 = East (right), 180 = South (down), 270 = West (left).
+     * Range: 0–360.
+     */
     direction: number;
+    /**
+     * Total angular width of the ray fan, in degrees.
+     * Range: 1–360. Typical: 30–120.
+     */
     spread: number;
+    /**
+     * Horizontal origin as a percentage of the canvas width.
+     * Range: 0–100. 50 = horizontally centered.
+     */
     originX: number;
+    /**
+     * Vertical origin as a percentage of the canvas height.
+     * Range: 0–100. 0 = top edge, 100 = bottom edge.
+     */
     originY: number;
+    /**
+     * Number of individual ray polygons to draw.
+     * Range: 1–200. Typical: 10–40.
+     */
     rayCount: number;
+    /**
+     * Base width of each ray polygon at the origin end, in pixels.
+     * Range: 1–500. Typical: 10–120.
+     */
     rayWidth: number;
+    /**
+     * Tip-to-base width ratio — how much wider the far end is relative to the
+     * near end. 1.0 = uniform beam, 2.0 = tip is twice as wide.
+     * Range: 0.1–10. Typical: 1.0–3.0.
+     */
     divergence: number;
+    /**
+     * Length of each ray as a multiplier of the canvas diagonal.
+     * 1.0 = exactly fits corner-to-corner. 1.4 overshoots a bit.
+     * Range: 0.1–5. Typical: 0.8–2.0.
+     */
     rayLength: number;
+    /**
+     * Master opacity of the entire layer.
+     * Range: 0–1. 0 = invisible, 1 = fully opaque.
+     */
     opacity: number;
+    /**
+     * Canvas composite operation. Use `"lighter"` or `"screen"` for dark
+     * backgrounds; use `"multiply"` for light/white backgrounds.
+     */
     blendMode: BlendMode;
+    /**
+     * Gradient color at the origin (near) end of each ray. CSS hex string.
+     * @example "#ffd28a"
+     */
     colorStart: string;
+    /**
+     * Gradient color at the tip (far) end of each ray. CSS hex string.
+     * Ignored when `fadeToTransparent` is `true` (the tip becomes fully
+     * transparent instead).
+     */
     colorEnd: string;
+    /**
+     * When `true`, rays fade from `colorStart` at the origin to fully
+     * transparent at the tip, producing a natural light-beam look.
+     * When `false`, the gradient goes from `colorStart` to `colorEnd`.
+     */
     fadeToTransparent: boolean;
+    /**
+     * Gaussian blur applied to the ray shapes before compositing, in pixels.
+     * Values > 0 soften hard edges and produce a glow effect.
+     * Range: 0–80. Typical: 4–20.
+     */
     blur: number;
-    /** @deprecated use randomnessWidth/Length/Angle */
+    /**
+     * @deprecated Replaced by the separate `randomnessWidth`, `randomnessLength`,
+     * and `randomnessAngle` fields. Still accepted for backward compatibility.
+     */
     randomness?: number;
+    /**
+     * Per-ray width variation, as a percentage of `rayWidth`.
+     * Range: 0–100. 0 = all rays identical width, 100 = maximum variation.
+     */
     randomnessWidth: number;
+    /**
+     * Per-ray length variation, as a percentage of `rayLength`.
+     * Range: 0–100. 0 = uniform length.
+     */
     randomnessLength: number;
+    /**
+     * Per-ray angle jitter, as a percentage of the per-ray angular slot.
+     * Range: 0–100. Higher values break up the regular fan pattern.
+     */
     randomnessAngle: number;
+    /**
+     * Seed for the deterministic pseudo-random number generator (mulberry32).
+     * Two layers with the same parameters but different seeds will produce
+     * visually different ray distributions. Change this integer to get a new
+     * random layout without touching any other parameter.
+     */
     seed: number;
 }
 
+/**
+ * Top-level description of everything that gets rendered onto a canvas.
+ *
+ * Layers are composited in array order, back-to-front. **`layers[0]` MUST be
+ * a `BackgroundLayer`** — it performs the `clearRect` equivalent each frame.
+ * Omitting it or placing it at any other index causes visual artifacts in
+ * animated mode (rays will smear across frames).
+ *
+ * @example
+ * const scene: SceneConfig = {
+ *   width: 1920,
+ *   height: 1080,
+ *   noise: 8,        // film-grain intensity 0–100
+ *   grainSize: 1,    // pixel size of grain
+ *   layers: [
+ *     // index 0: BackgroundLayer — REQUIRED, must come first
+ *     { id: "background", type: "background", bgType: "solid", bgColor: "#000011", bgColor2: "#000011", bgGradientAngle: 180 },
+ *     // index 1+: halos and rays in any order
+ *     { id: "halo-1", name: "Glow", type: "halo", originX: 50, originY: 0, intensity: 0.5, size: 0.25, color: "#ffffff", blendMode: "lighter" },
+ *     { ...DEFAULT_RAY_LAYER, id: "rays-1", name: "Rays" },
+ *   ],
+ * };
+ */
 export declare interface SceneConfig {
+    /**
+     * Canvas width in pixels. Should match the `HTMLCanvasElement.width` you
+     * pass to `drawScene`. Typical: 1920.
+     */
     width: number;
+    /**
+     * Canvas height in pixels. Should match `HTMLCanvasElement.height`.
+     * Typical: 1080.
+     */
     height: number;
+    /**
+     * Film-grain intensity. 0 disables grain entirely; higher values add more
+     * visible noise. Range: 0–100. Typical: 4–15.
+     */
     noise: number;
+    /**
+     * Size of each grain "pixel" in screen pixels. 1 = per-pixel noise,
+     * 2+ = chunky grain. Range: 1–20. Typical: 1–3.
+     */
     grainSize: number;
-    /** Ordered back-to-front. BackgroundLayer is always at index 0. */
+    /**
+     * Ordered back-to-front list of layers.
+     *
+     * **`layers[0]` MUST be a `BackgroundLayer`** — it is the only thing that
+     * clears the canvas before each frame. All subsequent entries can be
+     * `HaloLayer` or `RayLayer` in any order.
+     */
     layers: Layer[];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godlights",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Animated god ray / light beam effects for React — zero dependencies beyond React itself.",
   "type": "module",
   "main": "./dist/godlights.js",