af-motion 0.0.0-stage → 1.0.0

package/dist/3d/world/types.d.ts

@@ -0,0 +1,272 @@
+/**
+ * AF Motion — 3D Procedural World & Environment Generator Types
+ *
+ * Strongly-typed contracts for procedural 3D worlds, unified 12-stage pipeline,
+ * hydrology, clustered population, dynamic atmosphere/lighting, physics, and streaming.
+ */
+import type { Vector3, AABB3D } from "../physics/types.js";
+import type { Terrain3D, TerrainConfig, BiomeType, VegetationInstance, VegetationScatterRule, TerrainChunk } from "../terrain/types.js";
+import type { WeatherState, WindSystem } from "../../graphics/environment/types.js";
+import type { PhysicsWorld3D } from "../physics/world.js";
+export type WorldGenerationStage = "seed-initialization" | "terrain-generation" | "heightmap-processing" | "erosion-simulation" | "biome-classification" | "terrain-materials" | "hydrology-simulation" | "vegetation-population" | "environmental-setup" | "lighting-atmosphere" | "physics-registration" | "scene-composition";
+export interface PipelineProgressEvent {
+    stage: WorldGenerationStage;
+    stageIndex: number;
+    totalStages: number;
+    progress: number;
+    message: string;
+}
+export type WaterBodyType = "ocean" | "lake" | "pond" | "river";
+export interface WaterBody {
+    id: string;
+    type: WaterBodyType;
+    surfaceElevation: number;
+    bounds: AABB3D;
+    flowDirection: Vector3;
+    flowSpeed: number;
+    color: [number, number, number];
+    opacity: number;
+}
+export interface RiverNode {
+    position: Vector3;
+    width: number;
+    depth: number;
+}
+export interface RiverPath {
+    id: string;
+    nodes: RiverNode[];
+    flowSpeed: number;
+}
+export interface WaterMeshBuffers {
+    positions: Float32Array;
+    normals: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+}
+export interface WorldHydrologyConfig {
+    /** Global sea level in world units. Default: 0. */
+    seaLevel?: number;
+    /** Whether to detect and carve lakes in depression basins. Default: true. */
+    enableLakes?: boolean;
+    /** Minimum depression area to form a lake. Default: 20. */
+    minLakeArea?: number;
+    /** Whether to simulate river paths. Default: true. */
+    enableRivers?: boolean;
+    /** Number of river spring sources to trace. Default: 2. */
+    riverCount?: number;
+    /** Base water color RGB tuple. Default: [0.1, 0.4, 0.65]. */
+    waterColor?: [number, number, number];
+    /** Water surface opacity [0, 1]. Default: 0.85. */
+    waterOpacity?: number;
+}
+export interface WorldHydrology {
+    seaLevel: number;
+    waterBodies: WaterBody[];
+    rivers: RiverPath[];
+    meshBuffers: WaterMeshBuffers;
+    sampleWater(x: number, z: number): {
+        inWater: boolean;
+        surfaceY: number;
+        depth: number;
+        flow: Vector3;
+    };
+}
+export interface ForestClusterConfig {
+    id: string;
+    center: {
+        x: number;
+        z: number;
+    };
+    radius: number;
+    densityMultiplier: number;
+    targetBiomes: BiomeType[];
+}
+export interface WorldPopulationConfig {
+    vegetationRules?: VegetationScatterRule[];
+    clusters?: ForestClusterConfig[];
+    /** Cluster generation count based on macro noise. Default: 4. */
+    autoClusterCount?: number;
+    /** Max instances to prevent GPU allocation overload. Default: 50000. */
+    maxInstances?: number;
+}
+export interface WorldPopulation {
+    instances: VegetationInstance[];
+    clusters: ForestClusterConfig[];
+    /** Instanced matrix transform arrays grouped by category for high-efficiency batch rendering. */
+    instancedBatches: Map<string, Float32Array>;
+}
+export interface DayNightState {
+    /** Time of day in hours [0, 24). */
+    timeOfDayHours: number;
+    /** Solar elevation angle in degrees [-90, 90]. */
+    sunElevationDegrees: number;
+    /** Sun azimuth angle in degrees [0, 360). */
+    sunAzimuthDegrees: number;
+    /** Direction vector to the sun. */
+    sunDirection: Vector3;
+    /** Direction vector to the moon. */
+    moonDirection: Vector3;
+    /** Normalized sunlight color RGB [0, 1]. */
+    sunColor: [number, number, number];
+    /** Sunlight intensity factor. */
+    sunIntensity: number;
+    /** Normalized ambient skylight color RGB. */
+    ambientColor: [number, number, number];
+    /** Ambient light intensity. */
+    ambientIntensity: number;
+    /** Sky clear color RGB. */
+    skyColor: [number, number, number];
+    /** Is daylight currently active. */
+    isDay: boolean;
+}
+export interface WorldLightingConfig {
+    /** Initial time of day in hours [0, 24). Default: 11.5 (near noon). */
+    initialTimeHours?: number;
+    /** Day cycle progression speed multiplier (e.g. 60 for 1 minute = 1 hour). Default: 0 (paused). */
+    timeScale?: number;
+    /** Solar latitude in degrees affecting sun arc. Default: 45. */
+    latitudeDegrees?: number;
+    /** Atmospheric haze density [0, 1]. Default: 0.15. */
+    hazeDensity?: number;
+    /** Volumetric fog near distance in world units. Default: 50. */
+    fogNear?: number;
+    /** Volumetric fog far distance in world units. Default: 500. */
+    fogFar?: number;
+    /** Base fog color. If omitted, matches ambient skylight. */
+    fogColor?: [number, number, number];
+}
+export interface WorldLighting {
+    dayNight: DayNightState;
+    hazeDensity: number;
+    fogNear: number;
+    fogFar: number;
+    fogColor: [number, number, number];
+    setTime(hours: number): void;
+    setWeather(weather: WeatherState): void;
+    update(deltaMs: number): void;
+}
+export interface WorldEnvironmentConfig {
+    initialWeather?: WeatherState;
+    windSpeed?: number;
+    windDirectionDegrees?: number;
+    temperatureCelsius?: number;
+    relativeHumidity?: number;
+}
+export interface WorldEnvironment {
+    weather: WeatherState;
+    wind: WindSystem;
+    temperatureCelsius: number;
+    relativeHumidity: number;
+    setWeather(weather: WeatherState): void;
+    update(deltaMs: number): void;
+}
+export interface WorldStreamingConfig {
+    /** Chunk dimension along X and Z. Default: 64. */
+    chunkSize?: number;
+    /** Radius in chunks around viewer to keep loaded. Default: 2. */
+    viewRadiusChunks?: number;
+    /** Max chunks cached before discarding. Default: 64. */
+    maxCachedChunks?: number;
+}
+export interface WorldChunkKey {
+    cx: number;
+    cz: number;
+}
+export interface WorldChunk3D {
+    key: string;
+    cx: number;
+    cz: number;
+    bounds: AABB3D;
+    terrainChunk: TerrainChunk;
+    vegetation: VegetationInstance[];
+    lodLevel: number;
+    disposed: boolean;
+}
+export interface WorldStreamingManager {
+    loadedChunks: Map<string, WorldChunk3D>;
+    cachedChunks: Map<string, WorldChunk3D>;
+    updateViewerPosition(viewerPos: Vector3): void;
+    loadChunk(cx: number, cz: number): WorldChunk3D;
+    unloadChunk(cx: number, cz: number): void;
+    clear(): void;
+}
+export type WorldPreset = "alpine-landscape" | "dense-forest" | "desert-world" | "tropical-island" | "snow-mountains" | "rolling-grasslands" | "volcanic-landscape" | "fantasy-world" | "custom";
+export interface World3DConfig {
+    id?: string;
+    seed?: number | string;
+    preset?: WorldPreset;
+    /** Total world width along X in world units. Default: 256. */
+    width?: number;
+    /** Total world length along Z in world units. Default: 256. */
+    length?: number;
+    /** Terrain generation options. */
+    terrain?: TerrainConfig;
+    /** Hydrology options. */
+    hydrology?: WorldHydrologyConfig;
+    /** Population options. */
+    population?: WorldPopulationConfig;
+    /** Lighting and atmospheric options. */
+    lighting?: WorldLightingConfig;
+    /** Environmental and weather options. */
+    environment?: WorldEnvironmentConfig;
+    /** Streaming options. */
+    streaming?: WorldStreamingConfig;
+    /** Physics world options. If true or provided, registers terrain and colliders. */
+    physics?: boolean | {
+        world?: PhysicsWorld3D;
+        gravity?: Vector3;
+    };
+}
+export type WorldLifecycleState = "uninitialized" | "generating" | "ready" | "paused" | "disposed";
+export interface WorldBenchmarkResult {
+    totalGenerationTimeMs: number;
+    stageTimesMs: Record<WorldGenerationStage, number>;
+    totalVertices: number;
+    totalTriangles: number;
+    vegetationInstancesCount: number;
+    waterBodiesCount: number;
+    chunksCount: number;
+}
+export interface World3D {
+    id: string;
+    config: Required<Pick<World3DConfig, "width" | "length" | "seed">> & World3DConfig;
+    state: WorldLifecycleState;
+    terrain: Terrain3D;
+    hydrology: WorldHydrology;
+    population: WorldPopulation;
+    lighting: WorldLighting;
+    environment: WorldEnvironment;
+    physicsWorld?: PhysicsWorld3D;
+    streaming: WorldStreamingManager;
+    timeOfDayHours: number;
+    /** Sample elevation in world units at (X, Z). */
+    sampleHeight(worldX: number, worldZ: number): number;
+    /** Sample water state (surface elevation, depth, flow vector) at (X, Z). */
+    sampleWater(worldX: number, worldZ: number): {
+        inWater: boolean;
+        surfaceY: number;
+        depth: number;
+        flow: Vector3;
+    };
+    /** Sample dominant biome at (X, Z). */
+    sampleBiome(worldX: number, worldZ: number): BiomeType;
+    /** Swept raycast against terrain and environment. */
+    raycast(origin: Vector3, direction: Vector3, maxDistance?: number): {
+        hit: boolean;
+        point: Vector3;
+        normal: Vector3;
+        distance: number;
+    } | null;
+    /** Set environmental weather state. */
+    setWeather(weather: WeatherState): void;
+    /** Set time of day in hours [0, 24). */
+    setTimeOfDay(hours: number): void;
+    /** Update world simulation systems by deltaTime in milliseconds. */
+    update(deltaTimeMs: number): void;
+    /** Pause world animation and time progression. */
+    pause(): void;
+    /** Resume world animation and time progression. */
+    resume(): void;
+    /** Cleanly dispose all allocated buffers, colliders, and sub-systems. */
+    dispose(): void;
+}

package/dist/3d/world/world.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AF Motion — 3D Procedural World Master Controller
+ *
+ * Unified public entry point for procedural 3D world creation, asynchronous streaming,
+ * diurnal solar control, weather mutations, and resource lifecycle management.
+ */
+import type { Vector3 } from "../physics/types.js";
+import type { BiomeType } from "../terrain/types.js";
+import type { WeatherState } from "../../graphics/environment/types.js";
+import type { World3DConfig, World3D, WorldChunk3D, WorldBenchmarkResult } from "./types.js";
+import { type RunPipelineOptions } from "./pipeline.js";
+/**
+ * Creates and initializes a procedural 3D world synchronously.
+ */
+export declare function createWorld3D(config?: World3DConfig): World3D;
+/**
+ * Asynchronously generates a procedural 3D world with cancellation and progress reporting.
+ */
+export declare function generateWorld3D(config?: World3DConfig, options?: RunPipelineOptions): Promise<World3D>;
+/**
+ * Loads a world chunk at spatial grid coordinates (cx, cz).
+ */
+export declare function loadWorldChunk(world: World3D, cx: number, cz: number): WorldChunk3D;
+/**
+ * Unloads a world chunk at spatial grid coordinates (cx, cz).
+ */
+export declare function unloadWorldChunk(world: World3D, cx: number, cz: number): void;
+/**
+ * Updates world atmospheric, lighting, and physics simulation by deltaTime in milliseconds.
+ */
+export declare function updateWorldEnvironment(world: World3D, deltaMs: number): void;
+/**
+ * Dynamically changes the active environmental weather state.
+ */
+export declare function setWorldWeather(world: World3D, weather: WeatherState): void;
+/**
+ * Sets the world diurnal time of day in hours [0, 24).
+ */
+export declare function setWorldTime(world: World3D, timeOfDayHours: number): void;
+/**
+ * Samples the dominant ecological biome at world coordinates (X, Z).
+ */
+export declare function getWorldBiome(world: World3D, worldX: number, worldZ: number): BiomeType;
+/**
+ * Samples the ground terrain elevation at world coordinates (X, Z).
+ */
+export declare function sampleWorldHeight(world: World3D, worldX: number, worldZ: number): number;
+/**
+ * Samples water depth, surface elevation, and flow vector at world coordinates (X, Z).
+ */
+export declare function sampleWorldWater(world: World3D, worldX: number, worldZ: number): {
+    inWater: boolean;
+    surfaceY: number;
+    depth: number;
+    flow: Vector3;
+};
+/**
+ * Benchmarks world generation performance across all 12 pipeline stages.
+ */
+export declare function benchmarkWorldGeneration(config?: World3DConfig): WorldBenchmarkResult;
+/**
+ * Completely tears down and disposes of a world instance and all associated buffers.
+ */
+export declare function disposeWorld3D(world: World3D): void;

package/dist/backgrounds/advanced-gradient.d.ts

@@ -0,0 +1,32 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type AdvancedGradientType = "mesh" | "aurora" | "radial" | "conic";
+export interface AdvancedGradientOptions {
+    /** Visual gradient treatment. Defaults to "mesh". */
+    type?: AdvancedGradientType;
+    /** CSS colors used when no palette is selected. Defaults to violet, cyan, and pink. */
+    colors?: readonly string[];
+    /** Registered palette name, or "active" to use and follow the current active palette. */
+    palette?: string | "active";
+    /** Mesh/aurora animation cycle duration in seconds. Use 0 for a static gradient. Defaults to 12. */
+    speed?: number;
+    /** Gradient strength from 0 to 1. Defaults to 0.65. */
+    intensity?: number;
+    /** Gradient direction in degrees. Defaults to 135. */
+    direction?: number;
+    /** Overlay opacity from 0 to 1. Defaults to 0.8. */
+    opacity?: number;
+    /** Optional class applied to every generated overlay. */
+    className?: string;
+    /** Additional inline CSS declarations applied to every generated overlay. */
+    style?: Readonly<Record<string, string>>;
+}
+export interface AdvancedGradientControls {
+    /** Removes the overlay and releases styles, listeners, and generated keyframes. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Adds a configurable animated gradient overlay behind target content.
+ * Mesh and aurora types animate softly; radial and conic types use a static gradient.
+ * Reduced-motion preferences disable animation while retaining the rendered background.
+ */
+export declare function advancedGradientBackground(target: AnimateTarget, options?: AdvancedGradientOptions): AdvancedGradientControls;

package/dist/backgrounds/atmospheric-backgrounds.d.ts

@@ -0,0 +1,79 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type AtmosphericBackgroundEffect = "aurora" | "fog" | "rainfall" | "snowfall" | "sunbeams";
+export type AtmosphericDirection = "left" | "right";
+export interface AtmosphericBackgroundBaseOptions {
+    /** Visual treatment. Defaults to "aurora". */
+    effect?: AtmosphericBackgroundEffect;
+    /** CSS colors for the effect, or palette primary/secondary/accent colors. */
+    colors?: readonly string[];
+    /** Registered built-in/custom palette name, or "active" to follow active palette changes. */
+    palette?: string;
+    /** Animation speed multiplier. Must be greater than 0. Defaults to 1. */
+    speed?: number;
+    /** Overall visual intensity from 0 to 1. Defaults to 0.7. */
+    intensity?: number;
+}
+export interface AuroraBorealisOptions extends AtmosphericBackgroundBaseOptions {
+    effect?: "aurora";
+    /** Number of flowing gradient ribbons from 1 to 8. Defaults to 4. */
+    waveCount?: number;
+    /** Gradient softness in pixels. Defaults to 60. */
+    softness?: number;
+}
+export interface FogMistOptions extends AtmosphericBackgroundBaseOptions {
+    effect: "fog";
+    /** Number of drifting fog banks from 1 to 16. Defaults to 6. */
+    density?: number;
+    /** Fog edge softness from 0 to 1. Defaults to 0.85. */
+    softness?: number;
+    /** Horizontal fog drift direction. Defaults to "right". */
+    direction?: AtmosphericDirection;
+}
+export interface RainfallOptions extends AtmosphericBackgroundBaseOptions {
+    effect: "rainfall";
+    /** Raindrops per 10,000 CSS square pixels. Capped at 3,000 drops per target. Defaults to 18. */
+    density?: number;
+    /** Rain speed in CSS pixels per second. Defaults to 560. */
+    dropSpeed?: number;
+    /** Rain angle in degrees from vertical, between -60 and 60. Defaults to 8. */
+    angle?: number;
+    /** Streak length in CSS pixels. Defaults to 16. */
+    streakLength?: number;
+    /** Adds a subtle glow at the lower edge. Defaults to false. */
+    surfaceGlow?: boolean;
+}
+export interface SnowfallOptions extends AtmosphericBackgroundBaseOptions {
+    effect: "snowfall";
+    /** Snowflakes per 10,000 CSS square pixels. Capped at 1,800 flakes per target. Defaults to 12. */
+    density?: number;
+    /** Snowflake radius range in CSS pixels. Defaults to 3. */
+    size?: number;
+    /** Falling speed in CSS pixels per second. Defaults to 48. */
+    fallSpeed?: number;
+    /** Horizontal wind offset in CSS pixels per second. Defaults to 8. */
+    wind?: number;
+    /** Side-to-side drift amplitude in CSS pixels. Defaults to 12. */
+    drift?: number;
+}
+export interface SunbeamsOptions extends AtmosphericBackgroundBaseOptions {
+    effect: "sunbeams";
+    /** Normalized light origin within the target. Defaults to { x: 0.5, y: 0.05 }. */
+    origin?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Angular spread of the light rays in degrees, from 5 to 120. Defaults to 48. */
+    spread?: number;
+    /** Animated sway amount in degrees, from 0 to 30. Defaults to 5. */
+    movement?: number;
+}
+export type AtmosphericBackgroundOptions = AuroraBorealisOptions | FogMistOptions | RainfallOptions | SnowfallOptions | SunbeamsOptions | AtmosphericBackgroundBaseOptions;
+export interface AtmosphericBackgroundControls {
+    /** Stops animation, removes the effect, and restores target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Adds aurora, fog, rain, snow, or sunbeam ambience. Aurora delegates to the
+ * existing aurora effect; the Canvas effects share responsive motion-aware cleanup.
+ */
+export declare function atmosphericBackground(target: AnimateTarget, options?: AtmosphericBackgroundOptions): AtmosphericBackgroundControls;

package/dist/backgrounds/aurora.d.ts

@@ -0,0 +1,24 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface AuroraOptions {
+    /** CSS colors used to create the aurora gradient. Defaults to a violet/cyan/pink palette. */
+    colors?: readonly string[];
+    /** Duration of one animation cycle, in seconds. Must be > 0. Defaults to 8. */
+    speed?: number;
+    /** Blur radius in pixels. Must be >= 0. Defaults to 60. */
+    blur?: number;
+    /** Overlay opacity between 0 and 1. Defaults to 0.7. */
+    opacity?: number;
+    /** Overlay corner radius in pixels. Must be >= 0. Defaults to 24. */
+    borderRadius?: number;
+    /** Number of flowing gradient ribbons from 1 to 8. Defaults to 3. */
+    waveCount?: number;
+}
+export interface AuroraControls {
+    /** Removes the background, injected keyframes and any temporary target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Adds a softly blurred, animated gradient behind each target's content.
+ * Reduced-motion preferences disable the keyframe animation while keeping the static gradient.
+ */
+export declare function aurora(target: AnimateTarget, options?: AuroraOptions): AuroraControls;

package/dist/backgrounds/cosmic-background.d.ts

@@ -0,0 +1,31 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type CosmicBackgroundEffect = "starfield" | "nebula" | "shooting-stars" | "galaxy";
+export interface CosmicBackgroundOptions {
+    /** Visual treatment. Defaults to "starfield". */
+    effect?: CosmicBackgroundEffect;
+    /** Stars per 10,000 CSS square pixels. Capped at 2,400 stars per target. Defaults to 1.5. */
+    density?: number;
+    /** Animation speed multiplier. Set to 0 for a static scene. Defaults to 1. */
+    speed?: number;
+    /** Star depth amount from 0 to 1; affects star size and parallax. Defaults to 1. */
+    depth?: number;
+    /** Overall visual intensity from 0 to 1. Defaults to 0.8. */
+    intensity?: number;
+    /** CSS colors for the stars/clouds, or a registered palette's primary, secondary, and accent colors. */
+    colors?: readonly string[];
+    /** Registered built-in/custom palette name, or "active" to follow active palette changes. */
+    palette?: string;
+    /** Shooting-star events per minute when effect is "shooting-stars". Set to 0 to disable. Defaults to 6. */
+    shootingFrequency?: number;
+    /** Shooting-star trail length in CSS pixels. Defaults to 140. */
+    trailLength?: number;
+}
+export interface CosmicBackgroundControls {
+    /** Stops animation, removes the canvas, and restores target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Renders a Canvas-based cosmic scene behind target content. Starfield, nebula,
+ * shooting-star, and spiral-galaxy treatments share responsive and motion-aware cleanup.
+ */
+export declare function cosmicBackground(target: AnimateTarget, options?: CosmicBackgroundOptions): CosmicBackgroundControls;

package/dist/backgrounds/energy-effects.d.ts

@@ -0,0 +1,78 @@
+import type { AnimateTarget } from "../core/animate.js";
+export type EnergyBackgroundEffect = "lightning" | "plasma-field" | "laser-beams" | "energy-pulse" | "electric-arcs";
+export interface EnergyBackgroundBaseOptions {
+    /** Visual treatment. Defaults to "lightning". */
+    effect?: EnergyBackgroundEffect;
+    /** CSS colors for the effect, or palette primary/secondary/accent colors. */
+    colors?: readonly string[];
+    /** Registered built-in/custom palette name, or "active" to follow active palette changes. */
+    palette?: string;
+    /** Animation speed multiplier. Set to 0 for a static scene. Defaults to 1. */
+    speed?: number;
+    /** Overall effect intensity from 0 to 1. Defaults to 0.75. */
+    intensity?: number;
+}
+export interface LightningOptions extends EnergyBackgroundBaseOptions {
+    effect?: "lightning";
+    /** Electrical strikes per minute. Defaults to 12. */
+    frequency?: number;
+    /** Branches per bolt from 0 to 12. Defaults to 4. */
+    branchCount?: number;
+    /** Bolt brightness from 0 to 1. Defaults to 1. */
+    brightness?: number;
+}
+export interface PlasmaFieldOptions extends EnergyBackgroundBaseOptions {
+    effect: "plasma-field";
+    /** Number of flowing colour formations from 2 to 10. Defaults to 5. */
+    formationCount?: number;
+    /** Formation scale relative to the canvas from 0.1 to 1. Defaults to 0.55. */
+    scale?: number;
+}
+export interface LaserBeamsOptions extends EnergyBackgroundBaseOptions {
+    effect: "laser-beams";
+    /** Number of beams from 1 to 32. Defaults to 8. */
+    count?: number;
+    /** Beam angle in degrees from -80 to 80. Defaults to -12. */
+    angle?: number;
+    /** Glow radius in CSS pixels from 0 to 80. Defaults to 18. */
+    glow?: number;
+    /** Beam width in CSS pixels from 0.25 to 12. Defaults to 2. */
+    width?: number;
+    /** Maximum beam sweep in degrees from 0 to 45. Defaults to 8. */
+    movement?: number;
+}
+export interface EnergyPulseOptions extends EnergyBackgroundBaseOptions {
+    effect: "energy-pulse";
+    /** Normalized pulse origin within the target. Defaults to { x: 0.5, y: 0.5 }. */
+    origin?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Seconds between expanding pulses. Defaults to 1.8. */
+    interval?: number;
+    /** Ring expansion speed in CSS pixels per second. Defaults to 220. */
+    pulseSpeed?: number;
+    /** Ring line width in CSS pixels. Defaults to 3. */
+    width?: number;
+}
+export interface ElectricArcsOptions extends EnergyBackgroundBaseOptions {
+    effect: "electric-arcs";
+    /** Arc paths per 10,000 CSS square pixels, capped at 64 per target. Defaults to 8. */
+    density?: number;
+    /** Arc flicker intensity from 0 to 1. Defaults to 0.65. */
+    flicker?: number;
+    /** Branches per arc from 0 to 8. Defaults to 2. */
+    branchCount?: number;
+    /** Arc stroke width in CSS pixels. Defaults to 1.5. */
+    width?: number;
+}
+export type EnergyBackgroundOptions = LightningOptions | PlasmaFieldOptions | LaserBeamsOptions | EnergyPulseOptions | ElectricArcsOptions | EnergyBackgroundBaseOptions;
+export interface EnergyBackgroundControls {
+    /** Stops animation, removes the canvas, and restores target styles. Safe to repeat. */
+    destroy(): void;
+}
+/**
+ * Renders Canvas energy effects with bounded path/gradient work and shared
+ * palette-aware, responsive, reduced-motion-safe lifecycle management.
+ */
+export declare function energyBackground(target: AnimateTarget, options?: EnergyBackgroundOptions): EnergyBackgroundControls;

package/dist/backgrounds/floating-orbs.d.ts

@@ -0,0 +1,26 @@
+import type { AnimateTarget } from "../core/animate.js";
+export interface FloatingOrbsOptions {
+    /** CSS colors assigned to the orbs in order. Defaults to a violet/cyan/pink palette. */
+    colors?: readonly string[];
+    /** Number of orbs per target. Must be an integer from 1 to 100. Defaults to 5. */
+    count?: number;
+    /** Smallest orb diameter in pixels. Must be > 0. Defaults to 80. */
+    minSize?: number;
+    /** Largest orb diameter in pixels. Must be >= minSize. Defaults to 240. */
+    maxSize?: number;
+    /** Blur radius in pixels. Must be >= 0. Defaults to 40. */
+    blur?: number;
+    /** Duration of one animation cycle, in seconds. Must be > 0. Defaults to 12. */
+    speed?: number;
+    /** Orb opacity between 0 and 1. Defaults to 0.6. */
+    opacity?: number;
+}
+export interface FloatingOrbsControls {
+    /** Removes the orbs, keyframes and temporary target styles. Safe to call repeatedly. */
+    destroy(): void;
+}
+/**
+ * Adds softly glowing, CSS-animated orbs behind target content.
+ * Reduced-motion preferences keep the orbs visible but disable their animation.
+ */
+export declare function floatingOrbs(target: AnimateTarget, options?: FloatingOrbsOptions): FloatingOrbsControls;