@ansh-ui/core 0.2.0

package/dist/noise.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Fractal composition of a base noise function.
+ *
+ * A single octave of simplex noise is smooth and featureless. Real natural texture comes from
+ * summing octaves at increasing frequency and decreasing amplitude — fractional Brownian
+ * motion. This module provides the standard family of summations, all parameterised so that
+ * no frequency, amplitude, or octave count is hardcoded inside an effect.
+ */
+type Noise2DFn = (x: number, y: number) => number;
+type Noise3DFn = (x: number, y: number, z: number) => number;
+interface FractalOptions {
+    /**
+     * Number of summed layers. Each octave roughly doubles the cost, and beyond ~6 the added
+     * detail is below a pixel for typical scales. Default `4`.
+     */
+    octaves?: number;
+    /** Frequency multiplier per octave. `2` is the classic choice. Default `2`. */
+    lacunarity?: number;
+    /**
+     * Amplitude multiplier per octave. Also called persistence. `0.5` gives the pink-noise
+     * falloff that reads as natural. Default `0.5`.
+     */
+    gain?: number;
+    /** Frequency of the first octave. Default `1`. */
+    frequency?: number;
+    /** Amplitude of the first octave. Default `1`. */
+    amplitude?: number;
+    /**
+     * Normalise the result back into `[-1, 1]` by dividing by the total amplitude.
+     * Without this, more octaves means a quieter signal. Default `true`.
+     */
+    normalize?: boolean;
+}
+declare const FRACTAL_DEFAULTS: {
+    readonly octaves: 4;
+    readonly lacunarity: 2;
+    readonly gain: 0.5;
+    readonly frequency: 1;
+    readonly amplitude: 1;
+    readonly normalize: true;
+};
+/** Standard fBm over a 2D noise source. Output in `[-1, 1]` when normalised. */
+declare function fbm2D(noise: Noise2DFn, options?: FractalOptions): Noise2DFn;
+/** Standard fBm over a 3D noise source — use the third axis as time for animated fields. */
+declare function fbm3D(noise: Noise3DFn, options?: FractalOptions): Noise3DFn;
+/**
+ * Ridged multifractal. Inverts and sharpens each octave (`1 - |n|`, squared), producing crisp
+ * ridge lines instead of rolling hills. This is what makes convincing mountain silhouettes,
+ * lightning, and the filament structure in aurora curtains.
+ *
+ * Output is in `[0, 1]`.
+ */
+declare function ridged2D(noise: Noise2DFn, options?: FractalOptions): Noise2DFn;
+/**
+ * Turbulence: fBm over the absolute value of each octave. Produces the billowing,
+ * smoke-like structure used for clouds and flame.
+ *
+ * Output is in `[0, 1]`.
+ */
+declare function turbulence2D(noise: Noise2DFn, options?: FractalOptions): Noise2DFn;
+/**
+ * Domain warping — feed noise through itself.
+ *
+ * `warp(p) = noise(p + strength * noise(p))`. This single trick is responsible for most of
+ * the "organic liquid" look in modern generative backgrounds: it turns the isotropic blobs of
+ * plain fBm into flowing, marbled filaments.
+ *
+ * @param strength How far the domain is displaced, in noise-space units. `0.5`–`2` is useful.
+ */
+declare function warp2D(noise: Noise2DFn, strength?: number, offset?: number): Noise2DFn;
+interface CurlResult {
+    x: number;
+    y: number;
+}
+/**
+ * Curl (divergence-free) noise for 2D flow fields.
+ *
+ * A particle advected by raw noise will pool in sinks and thin out in sources, because the
+ * field has non-zero divergence. Taking the perpendicular gradient of a scalar potential —
+ * `(∂N/∂y, −∂N/∂x)` — yields a field with zero divergence, so particle density is preserved
+ * and the motion looks like real fluid.
+ *
+ * The derivative is a central difference; `epsilon` trades accuracy against smoothness.
+ */
+declare function curl2D(noise: Noise2DFn, epsilon?: number): (x: number, y: number) => CurlResult;
+/** The 3D-source variant of {@link curl2D}, letting you animate the field over time. */
+declare function curl2DAnimated(noise: Noise3DFn, epsilon?: number): (x: number, y: number, t: number) => CurlResult;
+/**
+ * Make a 2D noise field seamlessly tileable over `[0, width) × [0, height)`.
+ *
+ * Works by sampling 4D noise on the surface of a torus: each axis becomes a circle, so the
+ * field wraps exactly with no seam. This is the correct way to do it — blending mirrored
+ * copies leaves visible symmetry artefacts.
+ */
+declare function tileable2D(noise4D: (x: number, y: number, z: number, w: number) => number, width: number, height: number): Noise2DFn;
+
+/**
+ * Gradient tables and permutation setup shared by every noise variant.
+ *
+ * The permutation table is a shuffled `0..255` sequence duplicated to 512 entries. Doubling
+ * it lets the noise functions index `perm[i + perm[j]]` without a modulo on every lookup,
+ * which matters when these run millions of times per second.
+ *
+ * The table is derived from the effect's seed, so noise fields are reproducible — the same
+ * seed always produces the same landscape.
+ */
+/** 12 edge-midpoint gradients of a cube. Used by 2D and 3D noise. */
+declare const GRAD3: Float32Array<ArrayBuffer>;
+/** 32 gradients for 4D noise — the edge midpoints of a hypercube. */
+declare const GRAD4: Float32Array<ArrayBuffer>;
+interface NoiseTables {
+    /** 512-entry doubled permutation table. */
+    readonly perm: Uint8Array;
+    /** `perm[i] % 12`, precomputed — saves a modulo in the inner loop of 2D/3D noise. */
+    readonly permMod12: Uint8Array;
+    /** `perm[i] % 32`, precomputed for 4D noise. */
+    readonly permMod32: Uint8Array;
+}
+/**
+ * Build (or reuse) permutation tables for a seed.
+ *
+ * Tables are 1.5 KB each and construction costs a shuffle, so we memoise them. The cache is
+ * bounded because a page that animates its seed would otherwise grow it without limit; we
+ * evict oldest-first, which suits the access pattern (a handful of stable seeds per page).
+ */
+declare function createNoiseTables(seed?: number): NoiseTables;
+/** Clear the memoised permutation tables. Exposed for tests and long-lived workers. */
+declare function clearNoiseTableCache(): void;
+
+interface SimplexNoise {
+    noise2D(x: number, y: number): number;
+    noise3D(x: number, y: number, z: number): number;
+    noise4D(x: number, y: number, z: number, w: number): number;
+}
+declare function createSimplexNoise(seed?: number): SimplexNoise;
+
+interface PerlinNoise {
+    noise2D(x: number, y: number): number;
+    noise3D(x: number, y: number, z: number): number;
+}
+declare function createPerlinNoise(seed?: number): PerlinNoise;
+/**
+ * Value noise: interpolates hashed *values* at lattice points rather than gradients.
+ *
+ * Cheaper than gradient noise and blockier in character. Good for film grain, dithering and
+ * any place you want visible cell structure rather than smooth flow.
+ */
+declare function createValueNoise(seed?: number): {
+    noise2D(x: number, y: number): number;
+};
+
+/**
+ * The one-stop noise factory.
+ *
+ * Effects generally want several related fields from a single seed — a base simplex, an fBm
+ * for the large structure, and a curl field for advection. Creating them individually would
+ * rebuild the permutation table each time (it is cached, but the wiring is still repetitive),
+ * so `createNoise(seed)` hands back a coherent bundle.
+ *
+ * ```ts
+ * const noise = createNoise('hero')
+ * const height = noise.fbm2D({ octaves: 5, gain: 0.55 })
+ * const flow = noise.curl({ octaves: 2 })
+ * ```
+ */
+declare function createNoise(seed?: number | string): {
+    seed: number;
+    /** Raw single-octave sources. */
+    simplex2D: (x: number, y: number) => number;
+    simplex3D: (x: number, y: number, z: number) => number;
+    simplex4D: (x: number, y: number, z: number, w: number) => number;
+    perlin2D: (x: number, y: number) => number;
+    perlin3D: (x: number, y: number, z: number) => number;
+    value2D: (x: number, y: number) => number;
+    /** Fractal compositions over simplex. */
+    fbm2D: (options?: FractalOptions) => Noise2DFn;
+    fbm3D: (options?: FractalOptions) => Noise3DFn;
+    ridged2D: (options?: FractalOptions) => Noise2DFn;
+    turbulence2D: (options?: FractalOptions) => Noise2DFn;
+    /** Domain-warped fBm — the organic, marbled look. */
+    warped2D: (strength?: number, options?: FractalOptions) => Noise2DFn;
+    /** Divergence-free flow field for particle advection. */
+    curl: (options?: FractalOptions) => (x: number, y: number) => CurlResult;
+    curlAnimated: (options?: FractalOptions) => (x: number, y: number, t: number) => CurlResult;
+    /** Seamlessly tiling field over the given extent. */
+    tileable: (width: number, height: number) => Noise2DFn;
+};
+type Noise = ReturnType<typeof createNoise>;
+
+export { type CurlResult, FRACTAL_DEFAULTS, type FractalOptions, GRAD3, GRAD4, type Noise, type Noise2DFn, type Noise3DFn, type NoiseTables, type PerlinNoise, type SimplexNoise, clearNoiseTableCache, createNoise, createNoiseTables, createPerlinNoise, createSimplexNoise, createValueNoise, curl2D, curl2DAnimated, fbm2D, fbm3D, ridged2D, tileable2D, turbulence2D, warp2D };

package/dist/noise.js

@@ -0,0 +1,5 @@
+export { FRACTAL_DEFAULTS, GRAD3, GRAD4, clearNoiseTableCache, createNoise, createNoiseTables, createPerlinNoise, createSimplexNoise, createValueNoise, curl2D, curl2DAnimated, fbm2D, fbm3D, ridged2D, tileable2D, turbulence2D, warp2D } from './chunk-FAVIEION.js';
+import './chunk-YFQXRC5R.js';
+import './chunk-KU2C6GEA.js';
+//# sourceMappingURL=noise.js.map
+//# sourceMappingURL=noise.js.map

package/dist/noise.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"noise.js"}

package/dist/palette-6HkVltYU.d.cts

@@ -0,0 +1,219 @@
+/**
+ * Colour model types.
+ *
+ * The engine's canonical internal representation is {@link Rgb}: sRGB components and alpha,
+ * all normalised to `[0, 1]`. Everything parses *into* it and formats *out of* it. Working in
+ * `0..1` rather than `0..255` avoids repeated division in the interpolation hot path and
+ * matches how every other colour space here is expressed.
+ */
+/** sRGB with alpha, components in `[0, 1]`. The canonical form. */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Linear-light RGB (gamma removed), components in `[0, 1]`. */
+interface LinearRgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Hue in degrees `[0, 360)`, saturation and lightness in `[0, 1]`. */
+interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+/** Hue in degrees `[0, 360)`, saturation and value in `[0, 1]`. */
+interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+/**
+ * OKLab — a perceptually uniform opponent-colour space.
+ *
+ * `l` is perceived lightness in `[0, 1]`; `a` (green↔red) and `b` (blue↔yellow) are roughly
+ * in `[-0.4, 0.4]`. Equal numeric steps here correspond to equal perceived steps, which is
+ * exactly what you want when interpolating or generating scales.
+ */
+interface Oklab {
+    l: number;
+    a: number;
+    b: number;
+    alpha: number;
+}
+/**
+ * OKLCH — the cylindrical form of OKLab.
+ *
+ * `l` lightness `[0, 1]`, `c` chroma (`0` grey, ~`0.37` maximum for sRGB primaries),
+ * `h` hue in degrees `[0, 360)`. This is the space to reason about when building palettes:
+ * hold `l` and `c` fixed, rotate `h`, and every result has matching perceived weight.
+ */
+interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+    alpha: number;
+}
+/**
+ * Interpolation spaces, in rough order of how good they look.
+ *
+ * - `oklab` — the default. Perceptually uniform, no dead grey midpoints, no hue drift.
+ * - `oklch` — like `oklab` but travels around the hue circle, keeping chroma high through
+ *   the transition. Best for vivid gradients between distant hues.
+ * - `lrgb` — linear RGB. Physically correct light mixing; what a real spotlight does.
+ * - `srgb` — naive component blending. Fast, and what CSS gradients historically did, so
+ *   pick it when you must match an existing design exactly.
+ * - `hsl` — legacy; included for parity with older tooling.
+ */
+type ColorSpace = 'oklab' | 'oklch' | 'lrgb' | 'srgb' | 'hsl';
+/** Direction to travel around the hue circle when interpolating in a cylindrical space. */
+type HueDirection = 'shorter' | 'longer' | 'increasing' | 'decreasing';
+/**
+ * Anything the engine accepts where a colour is expected.
+ *
+ * Strings cover every CSS syntax (`#0275f4`, `rgb()`, `hsl()`, `oklch()`, named colours,
+ * and `var(--token)` which resolves against the document at mount time).
+ */
+type ColorInput = string | Rgb | Oklch | Oklab | Hsl;
+
+/**
+ * Palette generation in OKLCH.
+ *
+ * Generating a scale by scaling HSL lightness produces the familiar problem where the
+ * "same" adjustment makes yellow wash out and blue go muddy — because HSL lightness is not
+ * perceptual. Doing it in OKLCH means step 500 of a blue scale and step 500 of a yellow scale
+ * have genuinely matching visual weight, which is what makes a generated theme usable.
+ */
+type HarmonyKind = 'analogous' | 'complementary' | 'splitComplementary' | 'triadic' | 'tetradic' | 'square' | 'monochromatic';
+/**
+ * Derive a set of harmonious colours from a base.
+ *
+ * Chroma and lightness are preserved from the base and each result is gamut-mapped, so a
+ * harmony built from a displayable colour is always itself displayable.
+ */
+declare function harmony(base: ColorInput, kind?: HarmonyKind): Rgb[];
+interface ScaleOptions {
+    /**
+     * Number of steps. `11` matches the Tailwind convention (50–950) and is the default,
+     * because that is the shape most consumers will slot this into.
+     */
+    steps?: number;
+    /** Lightness of the lightest step, in OKLCH `[0, 1]`. Default `0.97`. */
+    lightest?: number;
+    /** Lightness of the darkest step. Default `0.18`. */
+    darkest?: number;
+    /**
+     * How much chroma falls off at the extremes, in `[0, 1]`.
+     *
+     * Real pigments lose saturation as they approach white or black, and scales that hold
+     * chroma constant look artificial at the ends. `0.35` is a natural-looking default.
+     */
+    chromaFalloff?: number;
+    /**
+     * Hue drift across the scale, in degrees.
+     *
+     * Slightly warming the light end and cooling the dark end (or vice versa) is what makes
+     * hand-tuned scales feel considered. Default `0` — opt in deliberately.
+     */
+    hueShift?: number;
+}
+interface ColorScale {
+    /** The generated colours, lightest first. */
+    colors: Rgb[];
+    /** Hex strings, lightest first. Convenient for theme output. */
+    hex: string[];
+    /** Tailwind-style numeric keys when `steps` is 11, otherwise `0..steps-1`. */
+    byKey: Record<string, string>;
+}
+/**
+ * Build a lightness scale from a single seed colour.
+ *
+ * The seed's own hue and chroma anchor the scale; its lightness is *not* preserved, since the
+ * point of a scale is to span the range. Use `scale.colors[5]` (or key `500`) as the closest
+ * equivalent of the input.
+ */
+declare function createScale(base: ColorInput, options?: ScaleOptions): ColorScale;
+interface PaletteOptions {
+    /** Number of colours to generate. Default `5`. */
+    count?: number;
+    /** Seed for the stochastic variation. Same seed ⇒ same palette. Default `1`. */
+    seed?: number | string;
+    /**
+     * Overall lightness of the palette in `[0, 1]`. `0.75` reads as pastel, `0.5` as vivid,
+     * `0.3` as moody. Default `0.65`.
+     */
+    lightness?: number;
+    /** Chroma as a fraction of the maximum available at each hue, in `[0, 1]`. Default `0.85`. */
+    saturation?: number;
+    /** Total hue span in degrees the palette covers. Default `120`. */
+    spread?: number;
+    /** Starting hue in degrees. Random (but seeded) when omitted. */
+    baseHue?: number;
+    /** Random variation applied to lightness and chroma, in `[0, 1]`. Default `0.12`. */
+    variance?: number;
+}
+/**
+ * Generate a coherent palette from scratch.
+ *
+ * Hues are distributed with a golden-ratio walk rather than evenly, because even spacing
+ * produces the flat, obviously-computed look of an auto-generated chart palette. The walk
+ * gives spacing that reads as deliberate.
+ */
+declare function generatePalette(options?: PaletteOptions): Rgb[];
+/**
+ * Extend a short palette to `count` colours by interpolating between the ones given.
+ *
+ * Effects that need N colours (a mesh gradient with 6 control points, say) shouldn't force
+ * the author to supply exactly N. This fills the gap perceptually, so the extras look like
+ * they belong to the same palette rather than like interpolation artefacts.
+ */
+declare function expandPalette(colors: readonly ColorInput[], count: number): Rgb[];
+/**
+ * Sort a palette by perceived lightness. Ascending puts the darkest first.
+ * Layered effects use this so that lighter colours land on top by default.
+ */
+declare function sortByLightness(colors: readonly ColorInput[], ascending?: boolean): Rgb[];
+/**
+ * Derive a palette suited to a dark surface from one designed for light (or vice versa).
+ *
+ * Not a lightness inversion — that ruins hue relationships. Instead lightness is reflected
+ * about the midpoint while chroma is *raised*, compensating for the fact that saturated
+ * colours read as less vivid against dark backgrounds (the Helmholtz–Kohlrausch effect).
+ */
+declare function invertForSurface(colors: readonly ColorInput[], chromaBoost?: number): Rgb[];
+/**
+ * The Ansh signature palettes.
+ *
+ * These are the defaults every effect falls back to when no colours are supplied. They are
+ * chosen so that a developer who writes `<AuroraBackground />` with no props gets something
+ * that looks like a considered design decision rather than a debug view.
+ */
+declare const palettes: {
+    /** Deep blue → violet → magenta. The house palette. */
+    readonly ansh: readonly ["#0275f4", "#5b3df5", "#9f0550"];
+    /** Cool northern lights: teal, green, indigo. */
+    readonly aurora: readonly ["#00d4ff", "#22e39a", "#4f46e5"];
+    /** Warm dusk: amber through rose. */
+    readonly ember: readonly ["#ff9d00", "#ff4d6d", "#c026d3"];
+    /** Oceanic blues and cyans. */
+    readonly abyss: readonly ["#012a4a", "#0275f4", "#00d4ff"];
+    /** Monochrome with a cool cast — for restrained, editorial designs. */
+    readonly graphite: readonly ["#f8fafc", "#94a3b8", "#0f172a"];
+    /** High-energy neon for AI and developer-tool aesthetics. */
+    readonly neon: readonly ["#00d4ff", "#8a2be2", "#ff0066"];
+    /** Soft pastel wash for marketing and onboarding. */
+    readonly bloom: readonly ["#fbcfe8", "#c7d2fe", "#a7f3d0"];
+    /** Gold and bronze — luxury, premium tiers, testimonials. */
+    readonly gilded: readonly ["#fde68a", "#d97706", "#78350f"];
+};
+type PaletteName = keyof typeof palettes;
+/** Resolve a palette name, an explicit colour list, or `undefined` (→ the house palette). */
+declare function resolvePalette(input: PaletteName | readonly ColorInput[] | undefined, fallback?: PaletteName): Rgb[];
+
+export { type ColorSpace as C, type HarmonyKind as H, type LinearRgb as L, type Oklab as O, type PaletteName as P, type Rgb as R, type ScaleOptions as S, type ColorInput as a, type ColorScale as b, type Hsl as c, type Hsv as d, type HueDirection as e, type Oklch as f, type PaletteOptions as g, createScale as h, expandPalette as i, generatePalette as j, harmony as k, invertForSurface as l, palettes as p, resolvePalette as r, sortByLightness as s };

package/dist/palette-6HkVltYU.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Colour model types.
+ *
+ * The engine's canonical internal representation is {@link Rgb}: sRGB components and alpha,
+ * all normalised to `[0, 1]`. Everything parses *into* it and formats *out of* it. Working in
+ * `0..1` rather than `0..255` avoids repeated division in the interpolation hot path and
+ * matches how every other colour space here is expressed.
+ */
+/** sRGB with alpha, components in `[0, 1]`. The canonical form. */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Linear-light RGB (gamma removed), components in `[0, 1]`. */
+interface LinearRgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Hue in degrees `[0, 360)`, saturation and lightness in `[0, 1]`. */
+interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+/** Hue in degrees `[0, 360)`, saturation and value in `[0, 1]`. */
+interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+/**
+ * OKLab — a perceptually uniform opponent-colour space.
+ *
+ * `l` is perceived lightness in `[0, 1]`; `a` (green↔red) and `b` (blue↔yellow) are roughly
+ * in `[-0.4, 0.4]`. Equal numeric steps here correspond to equal perceived steps, which is
+ * exactly what you want when interpolating or generating scales.
+ */
+interface Oklab {
+    l: number;
+    a: number;
+    b: number;
+    alpha: number;
+}
+/**
+ * OKLCH — the cylindrical form of OKLab.
+ *
+ * `l` lightness `[0, 1]`, `c` chroma (`0` grey, ~`0.37` maximum for sRGB primaries),
+ * `h` hue in degrees `[0, 360)`. This is the space to reason about when building palettes:
+ * hold `l` and `c` fixed, rotate `h`, and every result has matching perceived weight.
+ */
+interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+    alpha: number;
+}
+/**
+ * Interpolation spaces, in rough order of how good they look.
+ *
+ * - `oklab` — the default. Perceptually uniform, no dead grey midpoints, no hue drift.
+ * - `oklch` — like `oklab` but travels around the hue circle, keeping chroma high through
+ *   the transition. Best for vivid gradients between distant hues.
+ * - `lrgb` — linear RGB. Physically correct light mixing; what a real spotlight does.
+ * - `srgb` — naive component blending. Fast, and what CSS gradients historically did, so
+ *   pick it when you must match an existing design exactly.
+ * - `hsl` — legacy; included for parity with older tooling.
+ */
+type ColorSpace = 'oklab' | 'oklch' | 'lrgb' | 'srgb' | 'hsl';
+/** Direction to travel around the hue circle when interpolating in a cylindrical space. */
+type HueDirection = 'shorter' | 'longer' | 'increasing' | 'decreasing';
+/**
+ * Anything the engine accepts where a colour is expected.
+ *
+ * Strings cover every CSS syntax (`#0275f4`, `rgb()`, `hsl()`, `oklch()`, named colours,
+ * and `var(--token)` which resolves against the document at mount time).
+ */
+type ColorInput = string | Rgb | Oklch | Oklab | Hsl;
+
+/**
+ * Palette generation in OKLCH.
+ *
+ * Generating a scale by scaling HSL lightness produces the familiar problem where the
+ * "same" adjustment makes yellow wash out and blue go muddy — because HSL lightness is not
+ * perceptual. Doing it in OKLCH means step 500 of a blue scale and step 500 of a yellow scale
+ * have genuinely matching visual weight, which is what makes a generated theme usable.
+ */
+type HarmonyKind = 'analogous' | 'complementary' | 'splitComplementary' | 'triadic' | 'tetradic' | 'square' | 'monochromatic';
+/**
+ * Derive a set of harmonious colours from a base.
+ *
+ * Chroma and lightness are preserved from the base and each result is gamut-mapped, so a
+ * harmony built from a displayable colour is always itself displayable.
+ */
+declare function harmony(base: ColorInput, kind?: HarmonyKind): Rgb[];
+interface ScaleOptions {
+    /**
+     * Number of steps. `11` matches the Tailwind convention (50–950) and is the default,
+     * because that is the shape most consumers will slot this into.
+     */
+    steps?: number;
+    /** Lightness of the lightest step, in OKLCH `[0, 1]`. Default `0.97`. */
+    lightest?: number;
+    /** Lightness of the darkest step. Default `0.18`. */
+    darkest?: number;
+    /**
+     * How much chroma falls off at the extremes, in `[0, 1]`.
+     *
+     * Real pigments lose saturation as they approach white or black, and scales that hold
+     * chroma constant look artificial at the ends. `0.35` is a natural-looking default.
+     */
+    chromaFalloff?: number;
+    /**
+     * Hue drift across the scale, in degrees.
+     *
+     * Slightly warming the light end and cooling the dark end (or vice versa) is what makes
+     * hand-tuned scales feel considered. Default `0` — opt in deliberately.
+     */
+    hueShift?: number;
+}
+interface ColorScale {
+    /** The generated colours, lightest first. */
+    colors: Rgb[];
+    /** Hex strings, lightest first. Convenient for theme output. */
+    hex: string[];
+    /** Tailwind-style numeric keys when `steps` is 11, otherwise `0..steps-1`. */
+    byKey: Record<string, string>;
+}
+/**
+ * Build a lightness scale from a single seed colour.
+ *
+ * The seed's own hue and chroma anchor the scale; its lightness is *not* preserved, since the
+ * point of a scale is to span the range. Use `scale.colors[5]` (or key `500`) as the closest
+ * equivalent of the input.
+ */
+declare function createScale(base: ColorInput, options?: ScaleOptions): ColorScale;
+interface PaletteOptions {
+    /** Number of colours to generate. Default `5`. */
+    count?: number;
+    /** Seed for the stochastic variation. Same seed ⇒ same palette. Default `1`. */
+    seed?: number | string;
+    /**
+     * Overall lightness of the palette in `[0, 1]`. `0.75` reads as pastel, `0.5` as vivid,
+     * `0.3` as moody. Default `0.65`.
+     */
+    lightness?: number;
+    /** Chroma as a fraction of the maximum available at each hue, in `[0, 1]`. Default `0.85`. */
+    saturation?: number;
+    /** Total hue span in degrees the palette covers. Default `120`. */
+    spread?: number;
+    /** Starting hue in degrees. Random (but seeded) when omitted. */
+    baseHue?: number;
+    /** Random variation applied to lightness and chroma, in `[0, 1]`. Default `0.12`. */
+    variance?: number;
+}
+/**
+ * Generate a coherent palette from scratch.
+ *
+ * Hues are distributed with a golden-ratio walk rather than evenly, because even spacing
+ * produces the flat, obviously-computed look of an auto-generated chart palette. The walk
+ * gives spacing that reads as deliberate.
+ */
+declare function generatePalette(options?: PaletteOptions): Rgb[];
+/**
+ * Extend a short palette to `count` colours by interpolating between the ones given.
+ *
+ * Effects that need N colours (a mesh gradient with 6 control points, say) shouldn't force
+ * the author to supply exactly N. This fills the gap perceptually, so the extras look like
+ * they belong to the same palette rather than like interpolation artefacts.
+ */
+declare function expandPalette(colors: readonly ColorInput[], count: number): Rgb[];
+/**
+ * Sort a palette by perceived lightness. Ascending puts the darkest first.
+ * Layered effects use this so that lighter colours land on top by default.
+ */
+declare function sortByLightness(colors: readonly ColorInput[], ascending?: boolean): Rgb[];
+/**
+ * Derive a palette suited to a dark surface from one designed for light (or vice versa).
+ *
+ * Not a lightness inversion — that ruins hue relationships. Instead lightness is reflected
+ * about the midpoint while chroma is *raised*, compensating for the fact that saturated
+ * colours read as less vivid against dark backgrounds (the Helmholtz–Kohlrausch effect).
+ */
+declare function invertForSurface(colors: readonly ColorInput[], chromaBoost?: number): Rgb[];
+/**
+ * The Ansh signature palettes.
+ *
+ * These are the defaults every effect falls back to when no colours are supplied. They are
+ * chosen so that a developer who writes `<AuroraBackground />` with no props gets something
+ * that looks like a considered design decision rather than a debug view.
+ */
+declare const palettes: {
+    /** Deep blue → violet → magenta. The house palette. */
+    readonly ansh: readonly ["#0275f4", "#5b3df5", "#9f0550"];
+    /** Cool northern lights: teal, green, indigo. */
+    readonly aurora: readonly ["#00d4ff", "#22e39a", "#4f46e5"];
+    /** Warm dusk: amber through rose. */
+    readonly ember: readonly ["#ff9d00", "#ff4d6d", "#c026d3"];
+    /** Oceanic blues and cyans. */
+    readonly abyss: readonly ["#012a4a", "#0275f4", "#00d4ff"];
+    /** Monochrome with a cool cast — for restrained, editorial designs. */
+    readonly graphite: readonly ["#f8fafc", "#94a3b8", "#0f172a"];
+    /** High-energy neon for AI and developer-tool aesthetics. */
+    readonly neon: readonly ["#00d4ff", "#8a2be2", "#ff0066"];
+    /** Soft pastel wash for marketing and onboarding. */
+    readonly bloom: readonly ["#fbcfe8", "#c7d2fe", "#a7f3d0"];
+    /** Gold and bronze — luxury, premium tiers, testimonials. */
+    readonly gilded: readonly ["#fde68a", "#d97706", "#78350f"];
+};
+type PaletteName = keyof typeof palettes;
+/** Resolve a palette name, an explicit colour list, or `undefined` (→ the house palette). */
+declare function resolvePalette(input: PaletteName | readonly ColorInput[] | undefined, fallback?: PaletteName): Rgb[];
+
+export { type ColorSpace as C, type HarmonyKind as H, type LinearRgb as L, type Oklab as O, type PaletteName as P, type Rgb as R, type ScaleOptions as S, type ColorInput as a, type ColorScale as b, type Hsl as c, type Hsv as d, type HueDirection as e, type Oklch as f, type PaletteOptions as g, createScale as h, expandPalette as i, generatePalette as j, harmony as k, invertForSurface as l, palettes as p, resolvePalette as r, sortByLightness as s };