@ansh-ui/core 0.2.0

package/dist/index-CCdpefMp.d.ts

@@ -0,0 +1,967 @@
+import { U as Unsubscribe, R as ReducedMotionStrategy, a as FrameState } from './reduced-motion-D0LUgZle.js';
+import { R as Rng } from './random--4mSc5Lp.js';
+import { Noise } from './noise.js';
+import { R as Rgb, a as ColorInput, P as PaletteName } from './palette-6HkVltYU.js';
+
+/**
+ * Unified pointer tracking.
+ *
+ * Three problems this solves that every project re-solves badly:
+ *
+ * 1. **Mouse, touch and pen are one input.** Pointer Events already unify them; this wraps
+ *    that so effects never branch on input type. Touch gets a synthetic "leave" on `pointerup`
+ *    because a finger genuinely does leave the surface, which mouse code forgets.
+ *
+ * 2. **Raw pointer coordinates are jittery.** A cursor moves in discrete jumps and a mesh
+ *    gradient that follows it exactly looks nervous. We expose both the raw position and a
+ *    critically-damped smoothed position; effects should use the smoothed one.
+ *
+ * 3. **Reading `getBoundingClientRect()` per move is a layout read in an event handler** —
+ *    the classic thrash. The element rect is cached and refreshed in the ticker's `read` phase.
+ */
+interface PointerState {
+    /** Position in CSS pixels relative to the element's top-left. */
+    x: number;
+    y: number;
+    /** Normalised to `[0, 1]` across the element. Clamped, so it stays sane outside the bounds. */
+    nx: number;
+    ny: number;
+    /** Critically-damped position, in element pixels. Prefer this for anything visual. */
+    smoothX: number;
+    smoothY: number;
+    /** Normalised smoothed position. */
+    smoothNx: number;
+    smoothNy: number;
+    /** Velocity in element pixels per second. */
+    velocityX: number;
+    velocityY: number;
+    /** Is the pointer currently over the element? */
+    inside: boolean;
+    /** Is a button or finger currently down? */
+    down: boolean;
+    /** Normalised pressure in `[0, 1]`. `0.5` for devices that don't report it. */
+    pressure: number;
+    /** `'mouse' | 'pen' | 'touch'`, or `'none'` before the first event. */
+    type: 'mouse' | 'pen' | 'touch' | 'none';
+    /**
+     * Has the pointer ever been over this element?
+     *
+     * Effects use this to avoid snapping from the element's centre to the cursor on first hover —
+     * before any interaction, the "pointer" should be treated as absent, not as at (0,0).
+     */
+    everInside: boolean;
+}
+interface PointerOptions {
+    /**
+     * Smoothing half-life factor passed to `damp`. Lower is snappier.
+     * `0.001` is near-instant, `0.2` is languid. Default `0.005`.
+     */
+    smoothing?: number;
+    /** Track movement even when the pointer is outside the element. Default `false`. */
+    trackOutside?: boolean;
+    /**
+     * Where the smoothed position rests before first interaction, normalised.
+     * Default `{ x: 0.5, y: 0.5 }` — the centre, which is the least surprising neutral pose.
+     */
+    origin?: {
+        x: number;
+        y: number;
+    };
+}
+interface PointerTracker {
+    readonly state: Readonly<PointerState>;
+    /** Recompute the cached element rect. Called automatically on resize and scroll. */
+    refresh(): void;
+    destroy(): void;
+}
+/**
+ * Attach pointer tracking to an element.
+ *
+ * Listeners are passive and the only per-event work is arithmetic — no layout reads, no style
+ * writes. Smoothing is integrated in the ticker's `compute` phase so it stays frame-rate
+ * independent.
+ */
+declare function trackPointer(element: HTMLElement, options?: PointerOptions): PointerTracker;
+
+/**
+ * A managed canvas drawing surface.
+ *
+ * Getting a canvas right is deceptively fiddly, and every project gets some of it wrong:
+ *
+ *  - **Device pixel ratio.** A canvas sized only in CSS renders blurry on any Retina display.
+ *    The backing store must be `size × dpr` with a matching context transform.
+ *  - **Resolution scaling.** Full DPR is wasteful for soft, out-of-focus imagery. A blurred
+ *    gradient at 0.5× resolution is visually identical and costs a quarter of the fill rate,
+ *    so effects declare their own `resolution` and adaptive quality can lower it further.
+ *  - **Context loss.** Browsers discard canvas backing stores under memory pressure —
+ *    routinely on iOS Safari with several canvases on a page. Without a restore path the
+ *    effect silently goes blank and never comes back.
+ *  - **Resize storms.** A window drag fires dozens of resize events per second, and
+ *    reallocating a multi-megabyte backing store on each one janks badly. Resizes are
+ *    coalesced to one per frame.
+ */
+interface Size {
+    /** CSS pixels. */
+    width: number;
+    height: number;
+    /** Backing-store pixels: `width × dpr × resolution`. */
+    pixelWidth: number;
+    pixelHeight: number;
+    /** The effective scale factor from CSS pixels to backing-store pixels. */
+    scale: number;
+}
+interface SurfaceOptions {
+    /**
+     * Resolution multiplier applied on top of the device pixel ratio, in `(0, 1]`.
+     * `1` is full DPR; `0.5` quarters the pixel count. Default `1`.
+     */
+    resolution?: number;
+    /**
+     * Cap on the device pixel ratio actually used. Default `2`.
+     *
+     * Phones report DPRs up to 4. Rendering a full-viewport canvas at 4× costs sixteen times
+     * the fill rate of 1× for a difference nobody can see on a 5-inch screen at arm's length.
+     */
+    maxDevicePixelRatio?: number;
+    /** `alpha: false` lets the compositor skip blending. Default `true` — most effects need it. */
+    alpha?: boolean;
+    /** Hint that the canvas will be read back with `getImageData`. Default `false`. */
+    willReadFrequently?: boolean;
+    /** Called after a resize, before the next frame is drawn. */
+    onResize?: (size: Size) => void;
+    /**
+     * Called after the context is lost and restored. All GPU-side state is gone at this point;
+     * the effect must rebuild any cached gradients or patterns.
+     */
+    onRestore?: () => void;
+}
+interface Surface {
+    readonly canvas: HTMLCanvasElement;
+    /** The 2D context, or `null` if the browser refused to provide one. */
+    readonly ctx: CanvasRenderingContext2D | null;
+    readonly size: Readonly<Size>;
+    /** `true` while the context is lost; effects should skip drawing. */
+    readonly isLost: boolean;
+    /**
+     * Reset the transform to the current scale and clear the canvas.
+     * Call at the top of each frame unless deliberately compositing over the previous one.
+     */
+    clear(): void;
+    /** Change the resolution multiplier at runtime. Used by adaptive quality. */
+    setResolution(resolution: number): void;
+    /** Force a re-measure and resize. */
+    resize(): void;
+    destroy(): void;
+}
+/**
+ * Create a managed surface over a canvas element.
+ *
+ * The canvas is sized from its parent element, because a canvas has no intrinsic layout size
+ * of its own — it must be told, and its parent is the thing CSS has actually sized.
+ */
+declare function createSurface(canvas: HTMLCanvasElement, options?: SurfaceOptions): Surface;
+/** Is `OffscreenCanvas` with a 2D context available? Gates the worker rendering path. */
+declare function supportsOffscreenCanvas(): boolean;
+/** Can this canvas hand its rendering to a worker? Requires `transferControlToOffscreen`. */
+declare function supportsWorkerRendering(canvas: HTMLCanvasElement): boolean;
+type Unsub = Unsubscribe;
+
+/**
+ * Canvas drawing primitives shared across effects.
+ *
+ * These exist so that "draw a soft glow" is one call with one consistent look, rather than
+ * eight effects each inventing their own radial gradient with slightly different falloff.
+ * Consistency of light and falloff is a large part of why a component set looks designed
+ * rather than assembled.
+ */
+/**
+ * A cache for `CanvasGradient` objects.
+ *
+ * Creating a gradient is not free, and effects that draw dozens of glows per frame would
+ * otherwise allocate dozens of gradient objects per frame. Keyed by geometry and colour, so
+ * a field of identically-coloured particles shares one object.
+ *
+ * Bounded and cleared wholesale rather than evicted per-entry: gradients are cheap to rebuild,
+ * the working set is small and stable, and LRU bookkeeping would cost more than it saves.
+ */
+declare class GradientCache {
+    private readonly limit;
+    private readonly cache;
+    constructor(limit?: number);
+    radial(ctx: CanvasRenderingContext2D, radius: number, stops: readonly [number, string][], key: string): CanvasGradient;
+    clear(): void;
+}
+/**
+ * A soft radial glow.
+ *
+ * The falloff is deliberately not linear. A linear alpha ramp produces a visible hard edge at
+ * the boundary because the eye is sensitive to the discontinuity in the *derivative*. Two
+ * intermediate stops approximating a Gaussian shoulder remove it, which is the difference
+ * between "glow" and "circle with a gradient".
+ */
+declare function drawGlow(ctx: CanvasRenderingContext2D, x: number, y: number, radius: number, color: Rgb, intensity?: number, cache?: GradientCache): void;
+/** A filled circle. Cheaper than {@link drawGlow} when no falloff is needed. */
+declare function drawDot(ctx: CanvasRenderingContext2D, x: number, y: number, radius: number, color: Rgb): void;
+/**
+ * A closed Catmull-Rom spline through the given points, rendered as bézier segments.
+ *
+ * Effects that morph organic shapes (blobs, aurora ribbons, wave crests) need a curve that
+ * passes *through* its control points, which bézier does not and Catmull-Rom does. Converting
+ * to cubic béziers lets the canvas rasterise it natively rather than us approximating with
+ * line segments.
+ *
+ * @param tension `0.5` is the standard Catmull-Rom; lower is tighter, higher is looser.
+ */
+declare function traceClosedSpline(ctx: CanvasRenderingContext2D, points: readonly {
+    x: number;
+    y: number;
+}[], tension?: number): void;
+/** An open Catmull-Rom spline. Used for wave crests and ribbon paths. */
+declare function traceOpenSpline(ctx: CanvasRenderingContext2D, points: readonly {
+    x: number;
+    y: number;
+}[], tension?: number): void;
+/** A rounded rectangle path, using the native `roundRect` when available. */
+declare function traceRoundRect(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number): void;
+/**
+ * Canvas composite operations, narrowed to the ones that behave consistently across browsers
+ * and are actually useful for the effects here.
+ *
+ * `'lighter'` (additive) is the workhorse: overlapping glows accumulate brightness the way
+ * real light does, which is what makes particle fields look luminous instead of pasted.
+ */
+type BlendMode = 'source-over' | 'lighter' | 'screen' | 'overlay' | 'multiply' | 'soft-light' | 'hard-light' | 'color-dodge' | 'hue' | 'saturation' | 'color' | 'luminosity';
+declare function supportsCanvasFilter(ctx: CanvasRenderingContext2D): boolean;
+/** Reset the memoised filter probe. Test-only. */
+declare function resetFilterSupport(): void;
+
+/**
+ * The Effect contract.
+ *
+ * This is the interface that makes "500+ components" a tractable claim rather than a marketing
+ * one. An Effect is a plain object with no framework knowledge, no DOM ownership beyond the
+ * canvas it is handed, and no lifecycle of its own. Everything shared — canvas sizing, pointer
+ * tracking, reduced-motion handling, off-screen pausing, adaptive quality, teardown — lives in
+ * {@link import('./mount').mountEffect}.
+ *
+ * The consequence: a new visual effect is one file with one `frame()` function, and a new
+ * *framework binding* is one `createEffectComponent` helper rather than N component rewrites.
+ */
+/**
+ * Options every effect accepts.
+ *
+ * These are deliberately uniform across the whole library. A developer who has learned
+ * `speed`/`intensity`/`colors` on one background knows them on all of them, and a design
+ * system can set them globally without knowing which effect is underneath.
+ */
+interface BaseEffectOptions {
+    /**
+     * Any number of colours, or the name of a built-in palette.
+     *
+     * There is no cap and no assumption about count — an effect that wants exactly six control
+     * colours expands or samples whatever it is given. Accepts every CSS colour syntax including
+     * `var(--token)`.
+     */
+    colors?: readonly ColorInput[] | PaletteName;
+    /** Time multiplier. `0` freezes, `1` is the designed speed, `2` is double. Default `1`. */
+    speed?: number;
+    /**
+     * Strength of the effect's defining characteristic — amplitude, contrast, displacement.
+     * Normalised so `1` is the designed look and `0` is the effect's null state. Default `1`.
+     */
+    intensity?: number;
+    /** Overall alpha applied to the whole effect, in `[0, 1]`. Default `1`. */
+    opacity?: number;
+    /** Blur in CSS pixels applied via the canvas filter, where supported. Default `0`. */
+    blur?: number;
+    /** Canvas composite operation for the effect's own internal layering. */
+    blend?: BlendMode;
+    /**
+     * Seed for all stochastic behaviour. The same seed always produces the same composition,
+     * which is what makes SSR agreement and screenshot testing possible. Accepts a string.
+     * Default `1`.
+     */
+    seed?: number | string;
+    /** React to pointer input. Default `true` for effects that support it. */
+    interactive?: boolean;
+    /**
+     * Render resolution multiplier in `(0, 1]`. Soft, blurred imagery is indistinguishable at
+     * `0.5` and costs a quarter of the fill rate. Each effect picks a sensible default.
+     */
+    resolution?: number;
+    /**
+     * - `'auto'` — adapt quality to measured frame cost. The default, and the right choice.
+     * - `'high'` — pin maximum quality. For controlled environments and screenshot capture.
+     * - `'low'`  — pin reduced quality. For dashboards where the effect is decorative.
+     */
+    performance?: 'auto' | 'high' | 'low';
+    /** How to behave under `prefers-reduced-motion`. Each effect declares a sensible default. */
+    reducedMotion?: ReducedMotionStrategy;
+    /** Stop rendering while `true`, holding the last frame. Default `false`. */
+    paused?: boolean;
+    /**
+     * Skip rendering while the host element is outside the viewport. Default `true`.
+     *
+     * This is usually the single largest performance win on a long marketing page: five
+     * animated sections cost the same as one, because only the visible one runs.
+     */
+    pauseOffscreen?: boolean;
+}
+/** What an effect is given at setup. Everything it needs, nothing it must construct. */
+interface EffectContext {
+    /** The 2D context, pre-scaled for device pixel ratio. Draw in CSS pixels. */
+    readonly ctx: CanvasRenderingContext2D;
+    readonly surface: Surface;
+    /** Current dimensions. Mutated in place on resize — read it, don't cache it. */
+    readonly size: Readonly<Size>;
+    /** Seeded RNG. Never call `Math.random()` in an effect. */
+    readonly rng: Rng;
+    /** Noise fields derived from the same seed. */
+    readonly noise: Noise;
+    /** Pointer state, or `null` when `interactive` is false. */
+    readonly pointer: Readonly<PointerState> | null;
+    /** The element the canvas lives in. Use for `var()` resolution against the local cascade. */
+    readonly host: HTMLElement;
+    /** Resolved palette, already parsed. Never re-parse colours in a frame loop. */
+    readonly colors: readonly Rgb[];
+}
+/** A live, mounted effect. */
+interface EffectInstance {
+    /** Draw one frame. Called by the ticker in the `write` phase. */
+    frame(state: FrameState): void;
+    /** Called after the canvas has been resized. Rebuild any size-dependent caches. */
+    resize?(size: Readonly<Size>): void;
+    /**
+     * Apply changed options without remounting.
+     *
+     * Implement this for anything cheap (colours, speed, intensity). Omit it for options that
+     * change the effect's structure — {@link import('./mount').mountEffect} remounts instead,
+     * which is correct and much simpler than reconciling a particle system in place.
+     */
+    update?(options: Record<string, unknown>, context: EffectContext): void;
+    /** Release anything the effect allocated. The surface and observers are not yours to free. */
+    destroy?(): void;
+}
+/**
+ * A registered effect.
+ *
+ * `defaults` is `Required<Options>` on purpose: it is both the runtime fallback and the
+ * documentation source. The docs site renders the props table from it, and the CLI uses it to
+ * scaffold examples — so "every option has a documented default" is enforced by the type system
+ * rather than by review.
+ */
+interface EffectDefinition<Options extends BaseEffectOptions = BaseEffectOptions> {
+    readonly name: string;
+    readonly defaults: Required<Options>;
+    /**
+     * Options that cannot be applied live and require a remount when they change.
+     * Keeps the "should I remount?" decision with the effect that knows the answer.
+     */
+    readonly structuralOptions?: readonly (keyof Options)[];
+    /** Capability required to instantiate. Used for Pro-tier gating. Default `'effect:core'`. */
+    readonly capability?: string;
+    setup(context: EffectContext, options: Required<Options>): EffectInstance;
+}
+/** Convenience alias for the frame callback signature effects receive. */
+type EffectFrame = (state: FrameState) => void;
+
+/**
+ * Mount an effect into a host element.
+ *
+ * Everything that is the same for every effect happens here, exactly once:
+ *
+ *  - creating and sizing the canvas (DPR-correct, resize-coalesced, context-loss-recovering)
+ *  - resolving colours, seeds and noise fields
+ *  - pointer tracking, if the effect wants it
+ *  - reduced-motion resolution and live reaction to the preference changing
+ *  - off-screen pausing via a pooled IntersectionObserver
+ *  - adaptive quality → render resolution
+ *  - one ticker subscription, in the `write` phase
+ *  - complete teardown
+ *
+ * An individual effect therefore contains only what makes it *that* effect. This is the
+ * single most important structural decision in the library: it is why adding an effect is
+ * ~100 lines and why the React and Vue components are ~40.
+ */
+interface EffectHandle {
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * Apply new options.
+     *
+     * Live-updates whatever the effect supports and remounts when a structural option changes.
+     * Framework bindings call this on every prop change, so it must be cheap in the common case.
+     */
+    update(options: Partial<BaseEffectOptions & Record<string, unknown>>): void;
+    pause(): void;
+    resume(): void;
+    /** Force one frame to be drawn even while paused. Used for the static reduced-motion render. */
+    renderOnce(): void;
+    destroy(): void;
+    readonly isRunning: boolean;
+}
+declare function mountEffect<Options extends BaseEffectOptions>(definition: EffectDefinition<Options>, host: HTMLElement, userOptions?: Partial<Options>): EffectHandle;
+/**
+ * Register an effect so the CLI, docs site and registry can discover it.
+ * Returns the definition unchanged, so it can wrap a declaration inline.
+ */
+declare function defineEffect<Options extends BaseEffectOptions>(definition: EffectDefinition<Options>): EffectDefinition<Options>;
+
+/**
+ * A structure-of-arrays particle buffer.
+ *
+ * Every particle effect in the library sits on this. The layout is deliberate:
+ *
+ * **SoA, not AoS.** An array of `{x, y, vx, vy}` objects means the integrator walks a pointer
+ * chase through scattered heap allocations, and V8 must check the hidden class of each. Parallel
+ * `Float32Array`s mean the integration loop reads contiguous memory, stays monomorphic, and
+ * never allocates. At 2,000 particles the difference is roughly 4×; more importantly, the AoS
+ * version generates garbage every frame, and GC pauses are exactly the stutter users notice.
+ *
+ * **Swap-remove, not splice.** Killing a particle moves the last live one into its slot and
+ * decrements the count. O(1), no reallocation, no shifting. Particle order is not meaningful
+ * so nothing is lost — and the effects that *do* care about draw order (depth-sorted snow)
+ * sort an index array instead.
+ *
+ * **Fixed capacity.** Allocated once at the maximum the effect will ever need. Growing a
+ * typed array means allocating a new one and copying, which is precisely the kind of
+ * multi-megabyte operation that must never happen inside a frame.
+ */
+declare class ParticleBuffer {
+    readonly capacity: number;
+    readonly x: Float32Array;
+    readonly y: Float32Array;
+    readonly vx: Float32Array;
+    readonly vy: Float32Array;
+    /** Remaining life in seconds. `Infinity` for particles that never expire. */
+    readonly life: Float32Array;
+    /** Life the particle started with, for computing normalised age. */
+    readonly maxLife: Float32Array;
+    readonly size: Float32Array;
+    /** Index into the effect's resolved palette. */
+    readonly colorIndex: Uint8Array;
+    /** Free-form per-particle scalar — phase, spin, depth, whatever the effect needs. */
+    readonly seed: Float32Array;
+    /** Second free-form scalar. */
+    readonly extra: Float32Array;
+    private liveCount;
+    constructor(capacity: number);
+    get count(): number;
+    /**
+     * Claim a slot.
+     * @returns The particle index, or `-1` when the buffer is full. Callers must check.
+     */
+    spawn(): number;
+    /**
+     * Kill particle `index` by swapping the last live particle into its slot.
+     *
+     * The caller's loop must **not** advance its cursor after calling this, since a new particle
+     * now occupies the current index. Every consumer in this package follows that contract with
+     * a `while` loop rather than a `for`.
+     */
+    kill(index: number): void;
+    /** Normalised age in `[0, 1]`. `0` for immortal particles. */
+    age(index: number): number;
+    /**
+     * Reduce the live count, keeping the first `target` particles.
+     *
+     * Used by adaptive quality: dropping from 1,200 to 800 particles must not resample or
+     * reshuffle, because a visible reshuffle draws far more attention than the density change.
+     */
+    truncate(target: number): void;
+    clear(): void;
+}
+/**
+ * Advance positions by velocity — symplectic Euler.
+ *
+ * Deliberately not Runge-Kutta. RK4 is more *accurate*, but for particles driven by noise
+ * fields there is no ground truth to be accurate to, and symplectic Euler has the property
+ * that actually matters here: it conserves energy over long runs, so a field of particles
+ * doesn't slowly gain or lose speed over minutes of animation.
+ */
+declare function integrate(buffer: ParticleBuffer, dt: number, drag?: number): void;
+/** Reduce life and swap-remove anything that has expired. */
+declare function ageAndCull(buffer: ParticleBuffer, dt: number): void;
+/** Wrap particles that leave the bounds back to the opposite edge, with a margin. */
+declare function wrapBounds(buffer: ParticleBuffer, width: number, height: number, margin?: number): void;
+/**
+ * A uniform grid for neighbour queries.
+ *
+ * The constellation effect needs "every pair of particles within distance R", which is O(n²)
+ * naively — 2,000 particles is 4 million distance checks per frame, which is not viable. A
+ * spatial hash with cell size R reduces it to checking each particle against the nine cells
+ * around it, which is effectively O(n) for uniformly distributed particles.
+ *
+ * Cells are stored as a flat `Int32Array` bucket list rather than an array of arrays, so
+ * rebuilding it each frame allocates nothing.
+ */
+declare class SpatialGrid {
+    private capacity;
+    private cols;
+    private rows;
+    private cellSize;
+    /** Start index of each cell's run inside `items`. Length `cols * rows + 1`. */
+    private cellStart;
+    /** Particle indices, grouped by cell. */
+    private items;
+    /** Scratch counters used while building. */
+    private counts;
+    constructor(capacity: number);
+    /**
+     * Bucket every live particle. Must be called before {@link forEachNeighbour}.
+     * @param cellSize Should equal the query radius — smaller means more cells to scan, larger
+     *                 means more candidates per cell.
+     */
+    build(buffer: ParticleBuffer, width: number, height: number, cellSize: number): void;
+    private cellIndex;
+    /**
+     * Visit candidate neighbours of particle `index` in the 3×3 cell block around it.
+     *
+     * Only pairs where `neighbour > index` are visited, so each pair is reported exactly once —
+     * which halves the work and means the caller doesn't need a "have I drawn this line" check.
+     * The callback still receives candidates outside the radius; the caller does the exact test,
+     * because it usually needs the distance anyway.
+     */
+    forEachNeighbour(buffer: ParticleBuffer, index: number, visit: (neighbour: number) => void): void;
+}
+
+/**
+ * Aurora — vertical curtains of light with filament structure.
+ *
+ * What separates this from "a few blurred gradients" is the *filaments*. A real aurora is
+ * ridged: bright vertical striations at many scales, because the emission follows magnetic
+ * field lines. We get that from ridged multifractal noise (`1 - |n|`, squared) sampled per
+ * vertical slice, which produces sharp bright lines with soft valleys between them — exactly
+ * the wrong result for terrain and exactly the right one here.
+ *
+ * Rendering is a set of vertical slices per curtain rather than a single filled path, because
+ * the per-slice alpha *is* the filament structure. Each slice is one gradient fill, so a
+ * four-curtain composition at 48 slices is under 200 fills per frame — comfortably inside
+ * budget at half resolution, which is where blurred imagery belongs anyway.
+ */
+interface AuroraOptions extends BaseEffectOptions {
+    /** Number of overlapping curtains. More reads as depth. Default `4`. */
+    curtains?: number;
+    /** Vertical slices per curtain — the filament resolution. Default `48`. */
+    slices?: number;
+    /** Height of the curtains as a fraction of the canvas. Default `0.75`. */
+    height?: number;
+    /** Vertical position of the curtain band centre, `0` top to `1` bottom. Default `0.42`. */
+    position?: number;
+    /** Spatial frequency of the filaments. Higher is finer. Default `2.4`. */
+    detail?: number;
+    /** How far curtains drift horizontally, as a fraction of width. Default `0.18`. */
+    drift?: number;
+    /** Softness of the vertical falloff, in `[0, 1]`. Default `0.55`. */
+    falloff?: number;
+    /** Pointer influence on curtain sway, in `[0, 1]`. Default `0.35`. */
+    pointerInfluence?: number;
+}
+declare const aurora: EffectDefinition<AuroraOptions>;
+
+/**
+ * Mesh Gradient — soft overlapping colour fields that drift and blend.
+ *
+ * This is the effect behind almost every modern SaaS hero section, and it is nearly always
+ * implemented as a static SVG or a CSS blur stack. Doing it properly on canvas buys three
+ * things those can't:
+ *
+ *  1. **Motion that isn't a loop.** Control points follow a two-frequency Lissajous path with
+ *     an irrational frequency ratio, so the composition never visibly repeats. A CSS keyframe
+ *     animation always does, and the eye finds the loop point within about fifteen seconds.
+ *  2. **Perceptual blending.** Overlaps are composited in linear-ish additive space with
+ *     OKLab-derived palettes, so blue over magenta stays vivid instead of going grey.
+ *  3. **Pointer response.** Points lean toward the cursor, which makes a hero section feel
+ *     inhabited rather than decorative.
+ *
+ * Rendered as one radial gradient fill per point at quarter resolution with a heavy blur. The
+ * blur is doing most of the visual work, which is precisely why the low resolution is free.
+ */
+interface MeshGradientOptions extends BaseEffectOptions {
+    /** Number of colour control points. Default `5`. */
+    points?: number;
+    /** Radius of each field as a fraction of the canvas diagonal. Default `0.55`. */
+    radius?: number;
+    /** How far each point wanders from its home, as a fraction of the canvas. Default `0.22`. */
+    wander?: number;
+    /** Pointer attraction strength, in `[0, 1]`. Default `0.4`. */
+    pointerInfluence?: number;
+    /** Radius of the pointer's influence as a fraction of the canvas. Default `0.45`. */
+    pointerRadius?: number;
+    /**
+     * Fill the canvas with the darkest palette colour before drawing.
+     * Without it the effect composites onto whatever is behind, which is usually what you want
+     * for an overlay and not what you want for a hero. Default `true`.
+     */
+    backdrop?: boolean;
+    /** Grain overlay strength, in `[0, 1]`. A little grain hides gradient banding. Default `0.04`. */
+    grain?: number;
+}
+declare const meshGradient: EffectDefinition<MeshGradientOptions>;
+/**
+ * Animated Gradient — a simpler two-to-many stop linear gradient that rotates and shifts.
+ *
+ * Shares the mesh gradient's palette handling but costs a single fill per frame, which makes it
+ * the right choice for cards, buttons and any element small enough that the mesh's radial
+ * fields would overlap into mush.
+ */
+interface AnimatedGradientOptions extends BaseEffectOptions {
+    /** Rotations per minute of the gradient axis. `0` holds a fixed angle. Default `4`. */
+    rotation?: number;
+    /** Starting angle in degrees. Default `120`. */
+    angle?: number;
+    /** How far stops slide along the axis, in `[0, 1]`. Default `0.25`. */
+    travel?: number;
+    /** Number of interpolated stops handed to the canvas. Default `24`. */
+    stops?: number;
+}
+declare const animatedGradient: EffectDefinition<AnimatedGradientOptions>;
+
+/**
+ * Particle Field — points advected by a curl-noise flow.
+ *
+ * The detail that makes this look like fluid rather than like scattered dots: the velocity
+ * field is **divergence-free**. Advecting particles by raw noise makes them pool into sinks and
+ * evacuate sources, so within a few seconds the field is visibly clumpy and half the canvas is
+ * empty. Taking the perpendicular gradient of a noise potential — `(∂N/∂y, −∂N/∂x)` — gives a
+ * field with zero divergence, so particle density is preserved indefinitely and the motion reads
+ * as smoke or water.
+ *
+ * Particles are immortal and wrap at the edges rather than respawning, which avoids the
+ * distracting pop of particles appearing and vanishing.
+ */
+interface ParticleFieldOptions extends BaseEffectOptions {
+    /** Particle count at full quality. Scaled down by adaptive quality. Default `700`. */
+    count?: number;
+    /** Particle radius in CSS pixels. Default `1.6`. */
+    size?: number;
+    /** Random variation in size, in `[0, 1]`. Default `0.6`. */
+    sizeVariance?: number;
+    /** Flow field spatial scale. Smaller means larger, smoother eddies. Default `0.0016`. */
+    scale?: number;
+    /** Speed of the particles through the field, in pixels per second. Default `48`. */
+    flowSpeed?: number;
+    /** How fast the field itself evolves. `0` gives a static flow. Default `0.12`. */
+    fieldDrift?: number;
+    /** Draw particles as soft glows rather than hard dots. Costs more. Default `true`. */
+    glow?: boolean;
+    /** Trail persistence in `[0, 1)`. `0` clears each frame; `0.9` leaves long trails. Default `0`. */
+    trails?: number;
+    /** Radius in pixels within which the pointer pushes particles. Default `140`. */
+    pointerRadius?: number;
+    /** Pointer force. Negative attracts, positive repels. Default `1`. */
+    pointerForce?: number;
+}
+declare const particleField: EffectDefinition<ParticleFieldOptions>;
+
+/**
+ * Constellation — drifting points joined by lines when they come close.
+ *
+ * The interesting engineering problem here is the pairing. "Draw a line between every pair
+ * within distance R" is O(n²): at 220 points that's 24,000 checks per frame, which is fine, but
+ * authors routinely push the count to 800 and then it's 320,000 checks — enough to blow the
+ * budget on its own before anything is drawn.
+ *
+ * So this uses the {@link SpatialGrid} with cell size R. Each point only checks the nine cells
+ * around it, which is effectively O(n), and the grid reports each pair exactly once so no
+ * duplicate-line bookkeeping is needed.
+ *
+ * Lines are drawn in a single batched path per alpha bucket rather than one `stroke()` per line:
+ * `strokeStyle` changes force the canvas to flush, so 400 individual strokes cost far more than
+ * 8 batched ones.
+ */
+interface ConstellationOptions extends BaseEffectOptions {
+    /** Number of nodes at full quality. Default `120`. */
+    count?: number;
+    /** Maximum distance in pixels at which two nodes are linked. Default `140`. */
+    linkDistance?: number;
+    /** Node radius in pixels. Default `2`. */
+    nodeSize?: number;
+    /** Line width in pixels. Default `1`. */
+    lineWidth?: number;
+    /** Drift speed in pixels per second. Default `18`. */
+    drift?: number;
+    /** Radius in pixels within which the pointer becomes a node. Default `180`. */
+    pointerRadius?: number;
+    /** Link the pointer position into the graph. Default `true`. */
+    pointerLinks?: boolean;
+    /** Alpha buckets used to batch line strokes. More is smoother, slower. Default `6`. */
+    alphaSteps?: number;
+}
+declare const constellation: EffectDefinition<ConstellationOptions>;
+
+/**
+ * Meteor Shower — streaks that fall across the canvas and fade.
+ *
+ * The two things that make streaks convincing:
+ *
+ * **The trail is a gradient along the direction of travel, not a fading line.** A meteor is
+ * bright at the head and fades behind it, and the gradient must be rebuilt as the meteor moves
+ * because its endpoints move. That is one gradient per meteor per frame, which is affordable
+ * because there are only ever a dozen or so.
+ *
+ * **Spawning is Poisson, not periodic.** Evenly spaced spawns read as a machine. Sampling the
+ * gap between spawns from an exponential distribution gives clustering and lulls, which is what
+ * real meteor showers do and what makes the effect feel observed rather than generated.
+ */
+interface MeteorsOptions extends BaseEffectOptions {
+    /** Average meteors visible at once. Default `12`. */
+    count?: number;
+    /** Direction of travel in degrees. `135` falls down-and-right. Default `135`. */
+    angle?: number;
+    /** Random variation in angle, in degrees. Default `8`. */
+    angleVariance?: number;
+    /** Speed in pixels per second. Default `420`. */
+    velocity?: number;
+    /** Random variation in speed, in `[0, 1]`. Default `0.45`. */
+    velocityVariance?: number;
+    /** Trail length in pixels. Default `160`. */
+    trailLength?: number;
+    /** Head thickness in pixels. Default `2` */
+    thickness?: number;
+    /** Draw a bright point at the head. Default `true`. */
+    head?: boolean;
+}
+declare const meteors: EffectDefinition<MeteorsOptions>;
+
+/**
+ * Rain and Snow.
+ *
+ * These share one implementation because they are the same simulation with different
+ * parameters and one different draw call — and because the part that makes both convincing is
+ * the same: **depth**.
+ *
+ * Each drop or flake gets a `depth` in `[0, 1]`. Depth scales size, opacity *and* speed
+ * together, which produces motion parallax: near particles are large, opaque and fast; distant
+ * ones small, faint and slow. Without that coupling, precipitation looks like a flat sheet of
+ * identical sprites sliding down the screen, which is the tell in almost every implementation.
+ *
+ * Snow additionally sways — a sinusoidal horizontal drift with a per-flake phase and frequency,
+ * because a flake's motion is dominated by air resistance rather than gravity.
+ */
+interface PrecipitationShared extends BaseEffectOptions {
+    /** Particle count at full quality. */
+    count?: number;
+    /** Fall angle in degrees, measured from the positive x-axis. `90` is straight down. */
+    angle?: number;
+    /** Wind offset in degrees added to `angle`. Separated so wind can be animated. */
+    wind?: number;
+    /** Fall speed in pixels per second at maximum depth. */
+    velocity?: number;
+    /** Depth range as `[near, far]` scale factors. */
+    depthRange?: readonly [number, number];
+}
+interface RainOptions extends PrecipitationShared {
+    /** Streak length in pixels at maximum depth. Default `18`. */
+    length?: number;
+    /** Streak width in pixels. Default `1.2`. */
+    thickness?: number;
+    /** Draw splash rings where drops reach the bottom. Default `false`. */
+    splash?: boolean;
+}
+declare const rain: EffectDefinition<RainOptions>;
+interface SnowOptions extends PrecipitationShared {
+    /** Flake radius in pixels at maximum depth. Default `2.6`. */
+    size?: number;
+    /** Horizontal sway amplitude in pixels. Default `28`. */
+    sway?: number;
+    /** Sway cycles per second. Default `0.35`. */
+    swaySpeed?: number;
+    /** Soften flakes with a radial falloff. Costs more; looks better on dark backgrounds. Default `true`. */
+    soft?: boolean;
+}
+declare const snow: EffectDefinition<SnowOptions>;
+
+/**
+ * Fireflies — soft points that wander and pulse.
+ *
+ * Two details do all the work:
+ *
+ * **Wandering, not drifting.** Each firefly's heading is driven by a slowly-evolving noise
+ * sample rather than a fixed velocity, so it curves and doubles back. A constant velocity —
+ * even a slow one — reads as dust falling, not as something alive.
+ *
+ * **Asymmetric pulsing.** The brightness envelope rises faster than it falls (a raised sine
+ * with a shaped exponent), because a real bioluminescent flash does. A symmetric sine looks
+ * like a dimmer being turned up and down.
+ */
+interface FirefliesOptions extends BaseEffectOptions {
+    /** Number of fireflies at full quality. Default `40`. */
+    count?: number;
+    /** Glow radius in pixels. Default `5`. */
+    size?: number;
+    /** Wander speed in pixels per second. Default `22`. */
+    wanderSpeed?: number;
+    /** How sharply headings change. Higher is more erratic. Default `0.35`. */
+    turbulence?: number;
+    /** Average pulses per second. Default `0.5`. */
+    pulseRate?: number;
+    /** Minimum brightness between pulses, in `[0, 1]`. Default `0.12`. */
+    baseGlow?: number;
+    /** Radius in pixels within which the pointer scatters fireflies. Default `120`. */
+    pointerRadius?: number;
+}
+declare const fireflies: EffectDefinition<FirefliesOptions>;
+
+/**
+ * Waves — layered undulating bands.
+ *
+ * The crest of each layer is the sum of three sine components at incommensurable frequencies
+ * plus a noise term. That specific recipe matters:
+ *
+ *  - **One sine** is obviously a sine wave.
+ *  - **Two sines** beat against each other in a period the eye picks up within seconds.
+ *  - **Three sines at non-integer frequency ratios** produce a profile with no visible period.
+ *  - **Plus noise** breaks the remaining symmetry so crests differ in height and sharpness.
+ *
+ * Layers are drawn back to front with decreasing opacity and increasing amplitude, which reads
+ * as depth. The path is a Catmull-Rom spline through sampled crest points rather than a polyline,
+ * because at 32 samples across a wide canvas a polyline shows visible faceting on the crests.
+ */
+interface WavesOptions extends BaseEffectOptions {
+    /** Number of stacked wave layers. Default `4`. */
+    layers?: number;
+    /** Crest samples per layer. More is smoother and slower. Default `28`. */
+    samples?: number;
+    /** Wave height in pixels at the frontmost layer. Default `40`. */
+    amplitude?: number;
+    /** Horizontal wavelength as a fraction of canvas width. Default `0.6`. */
+    wavelength?: number;
+    /** Vertical position of the wave band, `0` top to `1` bottom. Default `0.68`. */
+    position?: number;
+    /** Noise contribution to the crest profile, in `[0, 1]`. Default `0.35`. */
+    roughness?: number;
+    /** Fill below the crest as a solid band rather than stroking the line. Default `true`. */
+    filled?: boolean;
+    /** Stroke width when `filled` is false, or the highlight width when it is true. Default `0`. */
+    lineWidth?: number;
+}
+declare const waves: EffectDefinition<WavesOptions>;
+
+/**
+ * Liquid Blob — organic shapes that morph continuously.
+ *
+ * The radius at each angle is `base * (1 + noise(angle, time) * distortion)`, sampled around
+ * the circle and traced as a closed Catmull-Rom spline.
+ *
+ * The subtlety that most implementations get wrong: the noise must be sampled on a **circle in
+ * noise space**, not on the angle as a linear coordinate. If you sample `noise(angle, t)`
+ * directly, the value at `angle = 0` and `angle = 2π` are different points in the noise field,
+ * so the shape has a visible seam where it fails to close. Sampling
+ * `noise(cos(angle) * r, sin(angle) * r, t)` instead means the sample path is genuinely closed
+ * and the blob is seamless.
+ */
+interface BlobOptions extends BaseEffectOptions {
+    /** Number of overlapping blobs. Default `3`. */
+    count?: number;
+    /** Points sampled around each blob's circumference. More is smoother. Default `48`. */
+    segments?: number;
+    /** Base radius as a fraction of the smaller canvas dimension. Default `0.32`. */
+    radius?: number;
+    /** How far the radius deviates, in `[0, 1]`. `0` is a circle. Default `0.35`. */
+    distortion?: number;
+    /** Noise detail around the circumference. Higher gives more lobes. Default `1.6`. */
+    detail?: number;
+    /** How fast the shape morphs. Default `0.4`. */
+    morphSpeed?: number;
+    /** How far blobs drift from their home position, as a fraction of the canvas. Default `0.1`. */
+    drift?: number;
+    /** Draw a stroke outline instead of a fill. Default `false`. */
+    outline?: boolean;
+    /** Stroke width when `outline` is true. Default `2`. */
+    lineWidth?: number;
+    /** Pointer attraction, in `[0, 1]`. Default `0.25`. */
+    pointerInfluence?: number;
+}
+declare const blob: EffectDefinition<BlobOptions>;
+
+/**
+ * Noise Layer — film grain and dithering overlay.
+ *
+ * Grain does real work in a design system: it hides the banding that 8-bit gradients produce on
+ * large soft fills, and it gives flat colour a physical texture that reads as premium. It is the
+ * single cheapest way to make a gradient look intentional rather than default.
+ *
+ * The implementation is a pre-rendered tile stamped as a repeating pattern. That choice is not
+ * an optimisation, it is the only viable approach: generating full-canvas grain per frame needs
+ * `createImageData` + a per-pixel write + `putImageData`, which at 1920×1080 is 8 million writes
+ * — roughly 30 ms, twice the entire frame budget.
+ *
+ * Animated grain works by cycling between a handful of pre-generated tiles and jittering the
+ * pattern origin, which is visually indistinguishable from true per-frame noise because the eye
+ * cannot track individual grain pixels anyway.
+ */
+interface NoiseLayerOptions extends BaseEffectOptions {
+    /** Grain strength in `[0, 1]`. `0.05` is subtle, `0.2` is heavy. Default `0.08`. */
+    amount?: number;
+    /** Tile size in pixels. Larger tiles repeat less visibly but cost more memory. Default `160`. */
+    tileSize?: number;
+    /** Number of pre-generated tiles cycled through when animating. Default `4`. */
+    frames?: number;
+    /** Tile changes per second. `0` gives static grain. Default `12`. */
+    frameRate?: number;
+    /**
+     * Grain scale in pixels. `1` is per-pixel; `2` gives chunkier, more filmic grain.
+     * Values above 1 also reduce generation cost quadratically. Default `1`.
+     */
+    grainSize?: number;
+    /** Monochrome grain, or independent per-channel (chromatic) noise. Default `true`. */
+    monochrome?: boolean;
+}
+declare const noiseLayer: EffectDefinition<NoiseLayerOptions>;
+
+/**
+ * Spotlight — a soft light that follows the pointer.
+ *
+ * The trick that makes this read as *light* rather than as a moving circle is that it is drawn
+ * once as a large, very soft radial gradient with an additive blend, and it *eases into
+ * existence* rather than appearing at full strength. A spotlight that snaps on at the moment
+ * the cursor enters reads as a bug; one that fades up over ~200 ms reads as a light being aimed.
+ *
+ * The pointer position comes from the tracker's critically-damped `smooth` values, so the light
+ * trails very slightly behind the cursor. That lag is deliberate — a spotlight rigidly locked to
+ * the cursor feels weightless and cheap.
+ */
+interface SpotlightOptions extends BaseEffectOptions {
+    /** Radius in pixels. Default `320`. */
+    radius?: number;
+    /** Falloff shape. `1` is linear, `2` is quadratic (softer core). Default `1.6`. */
+    falloff?: number;
+    /** Seconds for the light to fade in and out as the pointer enters and leaves. Default `0.35`. */
+    fade?: number;
+    /**
+     * Keep the light visible when the pointer is elsewhere, drifting slowly.
+     * Useful for hero sections that should look alive before any interaction. Default `false`.
+     */
+    ambient?: boolean;
+    /** Drift radius for the ambient light, as a fraction of the canvas. Default `0.25`. */
+    ambientDrift?: number;
+    /** Add a second, tighter and brighter core. Default `true`. */
+    core?: boolean;
+}
+declare const spotlight: EffectDefinition<SpotlightOptions>;
+
+/**
+ * Every built-in effect, keyed by name.
+ *
+ * Used by the docs site to enumerate the catalogue and by the CLI to resolve `ansh add`.
+ * Application code should import individual effects so the rest tree-shake away — importing this
+ * map pulls in all of them.
+ */
+declare const effects: {
+    readonly aurora: EffectDefinition<AuroraOptions>;
+    readonly 'mesh-gradient': EffectDefinition<MeshGradientOptions>;
+    readonly 'animated-gradient': EffectDefinition<AnimatedGradientOptions>;
+    readonly 'particle-field': EffectDefinition<ParticleFieldOptions>;
+    readonly constellation: EffectDefinition<ConstellationOptions>;
+    readonly meteors: EffectDefinition<MeteorsOptions>;
+    readonly rain: EffectDefinition<RainOptions>;
+    readonly snow: EffectDefinition<SnowOptions>;
+    readonly fireflies: EffectDefinition<FirefliesOptions>;
+    readonly waves: EffectDefinition<WavesOptions>;
+    readonly blob: EffectDefinition<BlobOptions>;
+    readonly 'noise-layer': EffectDefinition<NoiseLayerOptions>;
+    readonly spotlight: EffectDefinition<SpotlightOptions>;
+};
+type EffectName = keyof typeof effects;
+
+export { supportsOffscreenCanvas as $, type AnimatedGradientOptions as A, type BaseEffectOptions as B, type ConstellationOptions as C, drawGlow as D, type EffectContext as E, type FirefliesOptions as F, GradientCache as G, effects as H, fireflies as I, integrate as J, meshGradient as K, meteors as L, type MeshGradientOptions as M, type NoiseLayerOptions as N, mountEffect as O, ParticleBuffer as P, noiseLayer as Q, type RainOptions as R, type Size as S, particleField as T, type Unsub as U, rain as V, type WavesOptions as W, resetFilterSupport as X, snow as Y, spotlight as Z, supportsCanvasFilter as _, type AuroraOptions as a, supportsWorkerRendering as a0, traceClosedSpline as a1, traceOpenSpline as a2, traceRoundRect as a3, trackPointer as a4, waves as a5, wrapBounds as a6, type BlendMode as b, type BlobOptions as c, type EffectDefinition as d, type EffectFrame as e, type EffectHandle as f, type EffectInstance as g, type EffectName as h, type MeteorsOptions as i, type ParticleFieldOptions as j, type PointerOptions as k, type PointerState as l, type PointerTracker as m, type SnowOptions as n, SpatialGrid as o, type SpotlightOptions as p, type Surface as q, type SurfaceOptions as r, ageAndCull as s, animatedGradient as t, aurora as u, blob as v, constellation as w, createSurface as x, defineEffect as y, drawDot as z };