@ansh-ui/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1122 @@
+export { EPSILON, HALF_PI, PI, Rect, TAU, Vec2, addScaledVec2, addVec2, addVec2Into, angleDelta, angleOfVec2, approximately, clamp, cloneVec2, crossVec2, damp, degrees, distanceSqVec2, distanceVec2, dotVec2, finite, fromAngle, inverseLerp, lengthSqVec2, lengthVec2, lerp, lerpAngle, lerpVec2, lerpVec2Into, limitVec2, mean, moveTowards, normalizeInRect, normalizeVec2, percentileSorted, pingPong, radians, rectContains, reflectVec2, remap, rotateVec2, roundTo, scaleVec2, scaleVec2Into, setVec2, smootherstep, smoothstep, snap, subVec2, subVec2Into, vec2, wrap } from './math.cjs';
+export { R as Rng, c as createRng, d as deriveSeed, g as goldenRatioSequence, h as hashString, j as jitter, r as r2Sequence, w as weightedPick } from './random--4mSc5Lp.cjs';
+import { E as EasingInput } from './types-B1FLLf3-.cjs';
+export { a as EasingFn, b as EasingName } from './types-B1FLLf3-.cjs';
+export { anticipate, cubicBezier, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, easings, linear, listEasings, mirrorEasing, power, readEasingTable, registerEasing, resolveEasing, reverseEasing, sampleEasing, signature, steps, unregisterEasing } from './easing.cjs';
+export { CurlResult, FRACTAL_DEFAULTS, FractalOptions, GRAD3, GRAD4, Noise, Noise2DFn, Noise3DFn, NoiseTables, PerlinNoise, SimplexNoise, clearNoiseTableCache, createNoise, createNoiseTables, createPerlinNoise, createSimplexNoise, createValueNoise, curl2D, curl2DAnimated, fbm2D, fbm3D, ridged2D, tileable2D, turbulence2D, warp2D } from './noise.cjs';
+import { C as ColorSpace } from './palette-6HkVltYU.cjs';
+export { a as ColorInput, b as ColorScale, H as HarmonyKind, c as Hsl, d as Hsv, e as HueDirection, L as LinearRgb, O as Oklab, f as Oklch, P as PaletteName, g as PaletteOptions, R as Rgb, S as ScaleOptions, h as createScale, i as expandPalette, j as generatePalette, k as harmony, l as invertForSurface, p as palettes, r as resolvePalette, s as sortByLightness } from './palette-6HkVltYU.cjs';
+export { ColorParseError, ContrastResult, Gradient, GradientOptions, GradientStop, MixOptions, TextSize, WcagLevel, applyGradientStops, blend, checkContrast, clearColorCache, composite, contrastRatio, createGradient, ensureContrast, fadeBy, fromUint32, gamutError, gamutMapOklch, hslToRgb, hsvToRgb, inSrgbGamut, isGamutStable, lerpHue, linearToOklab, linearToRgb, linearToSrgbChannel, listNamedColors, maxChroma, mixColors, mixParsed, namedColorToHex, oklabToLinear, oklabToOklch, oklabToRgb, oklchToOklab, oklchToRgb, oklchToRgbMapped, parseColor, perceivedLightness, pickReadable, relativeLuminance, requiredRatio, resolveComputed, resolveCssVariable, rgbToHsl, rgbToHsv, rgbToLinear, rgbToOklab, rgbToOklch, srgbToLinearChannel, toHex, toHslString, toOklchString, toRgbString, toUint32, tryParseColor, withAlpha, worstContrast } from './color.cjs';
+import { F as FrameCallback, S as SubscribeOptions, U as Unsubscribe, a as FrameState, b as FramePhase } from './reduced-motion-D0LUgZle.cjs';
+export { c as FRAME_PHASES, M as MotionResolution, d as ReducedMotionMode, R as ReducedMotionStrategy, g as getReducedMotionMode, o as onReducedMotionChange, p as prefersReducedMotion, r as resetReducedMotion, e as resolveMotion, s as setReducedMotionMode } from './reduced-motion-D0LUgZle.cjs';
+import { S as StaggerOptions } from './index-Dl8GCsya.cjs';
+export { B as BaseBehaviourOptions, a as BehaviourDefinition, b as BehaviourHandle, c as BehaviourInstance, d as BehaviourName, M as MagneticOptions, e as MarqueeOptions, P as ParallaxOptions, R as RippleOptions, f as ScrollRevealOptions, g as SplitTextOptions, h as SplitTextResult, i as SplitUnit, j as StaggerFrom, T as TiltOptions, k as behaviours, l as captureStyles, m as defineBehaviour, n as getSplitResult, o as magnetic, p as marquee, q as mountBehaviour, r as parallax, s as ripple, t as scrollReveal, u as split, v as splitText, w as stagger, x as staggerDuration, y as tilt } from './index-Dl8GCsya.cjs';
+export { A as AnimatedGradientOptions, a as AuroraOptions, B as BaseEffectOptions, b as BlendMode, c as BlobOptions, C as ConstellationOptions, E as EffectContext, d as EffectDefinition, e as EffectFrame, f as EffectHandle, g as EffectInstance, h as EffectName, F as FirefliesOptions, G as GradientCache, M as MeshGradientOptions, i as MeteorsOptions, N as NoiseLayerOptions, P as ParticleBuffer, j as ParticleFieldOptions, k as PointerOptions, l as PointerState, m as PointerTracker, R as RainOptions, S as Size, n as SnowOptions, o as SpatialGrid, p as SpotlightOptions, q as Surface, r as SurfaceOptions, U as Unsub, W as WavesOptions, s as ageAndCull, t as animatedGradient, u as aurora, v as blob, w as constellation, x as createSurface, y as defineEffect, z as drawDot, D as drawGlow, H as effects, I as fireflies, J as integrate, K as meshGradient, L as meteors, O as mountEffect, Q as noiseLayer, T as particleField, V as rain, X as resetFilterSupport, Y as snow, Z as spotlight, _ as supportsCanvasFilter, $ as supportsOffscreenCanvas, a0 as supportsWorkerRendering, a1 as traceClosedSpline, a2 as traceOpenSpline, a3 as traceRoundRect, a4 as trackPointer, a5 as waves, a6 as wrapBounds } from './index-DHOfsEIn.cjs';
+
+/**
+ * Spring physics, solved analytically.
+ *
+ * Most libraries integrate springs numerically, stepping the ODE once per frame. That is
+ * simple but has two real drawbacks: the result depends on frame rate (a dropped frame
+ * changes the motion), and you cannot *seek* — asking "where is this spring at t = 0.4s?"
+ * requires replaying every frame up to that point.
+ *
+ * Ansh solves the damped harmonic oscillator in closed form instead:
+ *
+ *     y'' + 2ζω₀y' + ω₀²y = 0
+ *
+ * where `y` is displacement from the target, `ω₀` is the undamped angular frequency and `ζ`
+ * is the damping ratio. That gives an exact position and velocity for any `t`, which makes
+ * springs frame-rate independent, seekable, reversible, and placeable on a timeline.
+ */
+/** Physical parameterisation — think in terms of the mass-spring-damper system. */
+interface PhysicalSpringOptions {
+    /** Spring constant. Higher is snappier. Default `170`. */
+    stiffness?: number;
+    /** Damping coefficient. Higher settles sooner with less oscillation. Default `26`. */
+    damping?: number;
+    /** Mass of the attached body. Higher is more sluggish. Default `1`. */
+    mass?: number;
+}
+/**
+ * Perceptual parameterisation — think in terms of how the motion *reads*.
+ *
+ * This is almost always the better API for designers, and it is what Apple's
+ * `spring(duration:bounce:)` exposes. We use the same mapping so values transfer between
+ * SwiftUI and Ansh unchanged.
+ */
+interface PerceptualSpringOptions {
+    /** Approximate settling time in seconds. Default `0.6`. */
+    duration?: number;
+    /**
+     * Bounciness in `[-1, 1]`.
+     *
+     * - `0` — critically damped: reaches the target as fast as possible with no overshoot.
+     * - `> 0` — underdamped: overshoots and oscillates. `0.3` is lively, `0.7` is springy.
+     * - `< 0` — overdamped: creeps in slowly. Useful for heavy, weighty motion.
+     *
+     * Default `0`.
+     */
+    bounce?: number;
+}
+interface SpringRestOptions {
+    /** Distance from target below which the spring is considered settled. Default `0.01`. */
+    restDelta?: number;
+    /** Speed below which the spring is considered settled. Default `0.01`. */
+    restSpeed?: number;
+}
+interface SpringOptions extends PhysicalSpringOptions, PerceptualSpringOptions, SpringRestOptions {
+    /** Starting position. Default `0`. */
+    from?: number;
+    /** Target position. Default `1`. */
+    to?: number;
+    /** Initial velocity in units per second. Default `0`. */
+    velocity?: number;
+}
+interface SpringState {
+    position: number;
+    velocity: number;
+    /** `true` once both displacement and speed are inside the rest thresholds. */
+    done: boolean;
+}
+interface SpringSolver {
+    /** Exact state at time `t` (seconds since the spring started). */
+    at(t: number): SpringState;
+    /** Estimated time in seconds until the spring settles. Capped at 10s. */
+    readonly duration: number;
+    /** Resolved damping ratio ζ. `< 1` underdamped, `= 1` critical, `> 1` overdamped. */
+    readonly dampingRatio: number;
+    /** Resolved undamped angular frequency ω₀ in radians per second. */
+    readonly angularFrequency: number;
+}
+declare const SPRING_DEFAULTS: {
+    readonly stiffness: 170;
+    readonly damping: 26;
+    readonly mass: 1;
+    readonly duration: 0.6;
+    readonly bounce: 0;
+    readonly restDelta: 0.01;
+    readonly restSpeed: 0.01;
+    readonly from: 0;
+    readonly to: 1;
+    readonly velocity: 0;
+};
+declare function perceptualToPhysical(duration: number, bounce: number, mass?: number): Required<PhysicalSpringOptions>;
+/** The inverse of {@link perceptualToPhysical}. */
+declare function physicalToPerceptual(stiffness: number, damping: number, mass?: number): Required<PerceptualSpringOptions>;
+/**
+ * Build a closed-form solver for the given spring.
+ *
+ * If `duration` or `bounce` is supplied, the perceptual parameterisation wins and
+ * `stiffness`/`damping` are ignored — mixing the two is always a mistake, and silently
+ * preferring one is friendlier than throwing at runtime inside a render.
+ */
+declare function createSpring(options?: SpringOptions): SpringSolver;
+/**
+ * Momentum / inertial decay — the "flick and let go" motion behind momentum scrolling.
+ *
+ * Velocity decays exponentially with a time constant of `power * 1000 / decay`, and the
+ * resting point is derived from the initial velocity, so a harder flick travels further.
+ */
+interface DecayOptions {
+    from?: number;
+    velocity?: number;
+    /** How far a given velocity carries. Default `0.8`. */
+    power?: number;
+    /** Exponential decay rate. Higher stops sooner. Default `0.325`. */
+    timeConstant?: number;
+    /** Stop when within this distance of the resting point. Default `0.5`. */
+    restDelta?: number;
+    /** Optional clamp on the resting point, e.g. scroll bounds. */
+    min?: number;
+    max?: number;
+}
+declare function createDecay(options?: DecayOptions): {
+    at: (t: number) => SpringState;
+    duration: number;
+    target: number;
+};
+
+/**
+ * Named spring presets.
+ *
+ * These exist so that a team can agree on "use `snappy` for menus" rather than negotiating
+ * stiffness values in code review. They are expressed perceptually (`duration`/`bounce`)
+ * because that is the vocabulary a designer can reason about.
+ */
+declare const springs: {
+    /** No overshoot, quick. The safe default for UI state changes. */
+    default: {
+        duration: number;
+        bounce: number;
+    };
+    /** Fast and crisp. Menus, dropdowns, toggles. */
+    snappy: {
+        duration: number;
+        bounce: number;
+    };
+    /** Lively overshoot. Playful confirmations, likes, badges. */
+    bouncy: {
+        duration: number;
+        bounce: number;
+    };
+    /** Slow, deliberate, weighty. Large surfaces and sheets. */
+    heavy: {
+        duration: number;
+        bounce: number;
+    };
+    /** Barely-there motion for micro-interactions. */
+    subtle: {
+        duration: number;
+        bounce: number;
+    };
+    /** Long, luxurious settle. Hero content and page transitions. */
+    cinematic: {
+        duration: number;
+        bounce: number;
+    };
+    /** Rubber-band feel for drag release. */
+    elastic: {
+        duration: number;
+        bounce: number;
+    };
+    /** Molasses. Deliberately sluggish — use for depth cues, not for controls. */
+    molasses: {
+        duration: number;
+        bounce: number;
+    };
+};
+type SpringPresetName = keyof typeof springs;
+/** Accept a preset name or an explicit options object anywhere a spring is configured. */
+type SpringInput = SpringPresetName | SpringOptions;
+declare function resolveSpringOptions(input: SpringInput | undefined): SpringOptions;
+
+/**
+ * Time keeping for the ticker.
+ *
+ * Two decisions here matter more than they look:
+ *
+ * **Delta clamping.** When a tab is backgrounded, `requestAnimationFrame` stops. On return,
+ * the first frame's delta is however long the user was away — seconds, or minutes. Feeding
+ * that into a physics integrator sends every particle to infinity, and into a tween makes it
+ * jump to its end. We clamp to `maxDelta` so the worst case is one slightly-long frame.
+ *
+ * **Seconds, not milliseconds.** Every public duration in Ansh is in seconds, because
+ * that is what designers and CSS authors think in, and because it keeps spring constants at
+ * human-readable magnitudes. Conversion happens once, here.
+ */
+interface ClockOptions {
+    /**
+     * Largest delta the clock will report, in seconds. Default `1 / 15` (≈67 ms), which is
+     * two dropped frames at 30 FPS — slow enough to notice, small enough to be harmless.
+     */
+    maxDelta?: number;
+    /** Multiplier on the passage of time. `0.5` is slow motion, `2` is double speed. Default `1`. */
+    timeScale?: number;
+}
+interface FrameTiming {
+    /** Scaled seconds elapsed since the clock started, excluding paused time. */
+    readonly time: number;
+    /** Scaled, clamped seconds since the previous frame. */
+    readonly delta: number;
+    /** Unscaled, unclamped seconds since the previous frame. Use for profiling, not motion. */
+    readonly rawDelta: number;
+    /** Monotonically increasing frame counter. */
+    readonly frame: number;
+    /** The raw `performance.now()` timestamp for this frame. */
+    readonly timestamp: number;
+}
+declare class Clock {
+    private maxDelta;
+    private scale;
+    private startTimestamp;
+    private lastTimestamp;
+    private accumulatedTime;
+    private frameIndex;
+    private running;
+    /** Leftover time for the fixed-step accumulator. */
+    private fixedRemainder;
+    constructor(options?: ClockOptions);
+    get timeScale(): number;
+    set timeScale(value: number);
+    get isRunning(): boolean;
+    get elapsed(): number;
+    start(timestamp: number): void;
+    /**
+     * Resume after a pause.
+     *
+     * Only `lastTimestamp` is reset, so the delta for the resumed frame is small rather than
+     * "however long the pause lasted". `accumulatedTime` continues from where it stopped, which
+     * is what makes pause/resume invisible to animations mid-flight.
+     */
+    resume(timestamp: number): void;
+    pause(): void;
+    reset(): void;
+    /** Advance the clock and produce this frame's timing. */
+    tick(timestamp: number): FrameTiming;
+    /**
+     * Number of fixed-size physics steps to run for a variable-length frame.
+     *
+     * Verlet and spring-constraint integrators are only stable at a fixed step; running them
+     * with a variable delta makes stiffness frame-rate dependent, so a 144 Hz monitor gets
+     * different physics from a 60 Hz one. This accumulates the leftover and reports whole steps.
+     *
+     * `maxSteps` bounds the work when a long frame has queued up many steps — better to fall
+     * slightly behind real time than to spiral into an ever-longer catch-up.
+     */
+    fixedSteps(delta: number, step: number, maxSteps?: number): number;
+    /** Fraction of the way into the next fixed step, for interpolating rendered positions. */
+    get fixedAlpha(): number;
+    get totalWallTime(): number;
+}
+
+/**
+ * Adaptive frame budgeting.
+ *
+ * The premise: an effect authored on a MacBook Pro will drop frames on a mid-range Android
+ * phone, and the author will never see it. Rather than asking developers to hand-tune particle
+ * counts per device — which nobody does — the kernel measures how long frames actually take and
+ * publishes a single `quality` scalar in `[0, 1]`. Effects scale their own cost against it.
+ *
+ * Why p95 rather than the mean: a mean is dominated by the many cheap frames and hides the
+ * occasional 40 ms stall that the user actually perceives as a stutter. p95 tracks the bad
+ * frames, which are the ones worth reacting to.
+ *
+ * Quality moves slowly and asymmetrically — quick to shed work when frames are expensive, slow
+ * to add it back. Oscillating between quality levels is more visually distracting than simply
+ * running at the lower one, so hysteresis is deliberate.
+ */
+interface FrameBudgetOptions {
+    /**
+     * Target frame duration in milliseconds. Defaults to the display's refresh interval as
+     * measured at runtime, falling back to 16.67 ms.
+     */
+    targetFrameMs?: number;
+    /**
+     * Fraction of the frame Ansh is allowed to spend. The rest is left for the browser's
+     * own work — style, layout, paint, compositing — plus the host application. Default `0.5`.
+     */
+    share?: number;
+    /** Rolling window size in frames. Default `90` (≈1.5 s at 60 FPS). */
+    window?: number;
+    /** How fast quality drops when over budget, per second. Default `0.6`. */
+    degradeRate?: number;
+    /** How fast quality recovers when under budget, per second. Default `0.12`. */
+    recoverRate?: number;
+    /** Floor on quality, so an effect never disappears entirely. Default `0.25`. */
+    minQuality?: number;
+}
+interface BudgetReport {
+    /** Adaptive quality in `[minQuality, 1]`. Multiply your work by this. */
+    quality: number;
+    /** Smoothed frames per second. */
+    fps: number;
+    /** Median frame cost attributable to Ansh, in milliseconds. */
+    p50: number;
+    /** 95th-percentile Ansh frame cost, in milliseconds. */
+    p95: number;
+    /** The budget being measured against, in milliseconds. */
+    budgetMs: number;
+    /** `true` while quality is below 1 — useful for a dev-mode indicator. */
+    degraded: boolean;
+}
+declare class FrameBudget {
+    private readonly share;
+    private readonly windowSize;
+    private readonly degradeRate;
+    private readonly recoverRate;
+    private readonly minQuality;
+    private targetFrameMs;
+    private explicitTarget;
+    private costs;
+    private cursor;
+    private filled;
+    private scratch;
+    private qualityValue;
+    private fpsValue;
+    private p50Value;
+    private p95Value;
+    /** Frame intervals used to detect the display refresh rate. */
+    private intervalSamples;
+    private refreshDetected;
+    constructor(options?: FrameBudgetOptions);
+    get quality(): number;
+    get budgetMs(): number;
+    /**
+     * Record one frame.
+     *
+     * @param costMs   Milliseconds spent inside Ansh callbacks this frame.
+     * @param rawDelta Unscaled seconds since the previous frame, for FPS and refresh detection.
+     */
+    record(costMs: number, rawDelta: number): void;
+    /**
+     * Infer the display refresh rate from observed frame intervals.
+     *
+     * Assuming 60 Hz wastes half the available budget on a 120 Hz display and overspends on a
+     * 30 Hz one. We take the median of the first 40 intervals (median, not mean, so a couple of
+     * long startup frames don't skew it) and snap to the nearest common rate.
+     */
+    private detectRefreshRate;
+    private recomputePercentiles;
+    private adaptQuality;
+    report(): BudgetReport;
+    /** Force quality to a fixed value, disabling adaptation. Used by `performance="high"`. */
+    lockQuality(value: number): void;
+    reset(): void;
+}
+
+interface TickerOptions extends ClockOptions {
+    budget?: FrameBudgetOptions;
+    /**
+     * Schedule frames yourself instead of using `requestAnimationFrame`.
+     * Tests inject a manual driver; a worker-based renderer could supply its own.
+     */
+    scheduler?: (callback: (timestamp: number) => void) => number;
+    canceller?: (handle: number) => void;
+    /**
+     * Read the current time. Defaults to `performance.now()`.
+     *
+     * Must share a time origin with whatever `scheduler` passes to its callback — in the browser
+     * `requestAnimationFrame` and `performance.now()` already do. An injected scheduler on its own
+     * clock must supply this too, otherwise the first frame's delta is computed between two unrelated
+     * timelines and clamps to zero.
+     */
+    now?: () => number;
+    /** Start automatically when the first subscriber is added. Default `true`. */
+    autoStart?: boolean;
+}
+declare class Ticker {
+    private readonly clock;
+    private readonly budget;
+    private readonly phases;
+    private readonly autoStart;
+    private readonly schedule;
+    private readonly cancel;
+    private readonly readTime;
+    private handle;
+    private nextId;
+    private paused;
+    private pauseReasons;
+    private disposed;
+    /**
+     * Phase arrays are rebuilt lazily rather than re-sorted on every add/remove: components
+     * mount in bursts, and sorting once before the next frame is cheaper than sorting per call.
+     */
+    private dirtyPhases;
+    /** Callbacks queued to run exactly once on the next frame. */
+    private onceQueue;
+    private listeners;
+    private readonly state;
+    constructor(options?: TickerOptions);
+    /**
+     * Register a per-frame callback.
+     *
+     * @returns An idempotent unsubscribe function. Always call it on unmount — the leak harness
+     *          in the test suite fails the build if a component forgets.
+     */
+    add(callback: FrameCallback, options?: SubscribeOptions): Unsubscribe;
+    /** Run a callback on the next frame only. Useful for deferring a DOM read past a write. */
+    once(callback: FrameCallback): void;
+    /** Resolve on the next frame. `await ticker.nextFrame()` reads well in setup code. */
+    nextFrame(): Promise<FrameState>;
+    get subscriberCount(): number;
+    /** Per-phase subscriber counts. Consumed by the dev inspector and the leak harness. */
+    inspect(): Record<FramePhase, {
+        count: number;
+        names: string[];
+    }>;
+    start(): void;
+    stop(): void;
+    /**
+     * Pause the ticker, tagged with a reason.
+     *
+     * Reasons are reference-counted by name so that independent systems can pause without
+     * fighting: if the tab is hidden *and* the user prefers reduced motion, both hold a pause,
+     * and resuming one doesn't restart animation while the other still applies.
+     */
+    pause(reason?: string): void;
+    resume(reason?: string): void;
+    get isPaused(): boolean;
+    get pausedBecause(): string[];
+    get isRunning(): boolean;
+    get timeScale(): number;
+    set timeScale(value: number);
+    get time(): number;
+    /**
+     * Advance one frame manually.
+     *
+     * The escape hatch that makes the whole engine testable: a test can drive 100 deterministic
+     * frames without waiting on a real display, and a screenshot harness can seek to an exact
+     * frame index.
+     */
+    step(deltaMs?: number): FrameState;
+    /** Release everything. The ticker cannot be restarted afterwards. */
+    dispose(): void;
+    get quality(): number;
+    budgetReport(): BudgetReport;
+    /** Disable adaptation and pin quality. Backs the `performance="high" | "low"` prop. */
+    lockQuality(value: number): void;
+    /** Subscribe to per-frame budget reports — powers the dev-mode FPS overlay. */
+    onBudget(listener: (report: BudgetReport) => void): Unsubscribe;
+    private readonly loop;
+    private runFrame;
+    /**
+     * Run one subscriber, containing its failures.
+     *
+     * A throwing callback must not stop every other animation on the page — that turns one
+     * component's bug into a whole-page visual failure. We log, and after several consecutive
+     * throws we evict the subscriber, because 60 identical stack traces per second is not
+     * diagnostics, it's a denial of service on the console.
+     */
+    private invoke;
+    private sortDirtyPhases;
+}
+/** Monotonic clock, falling back to `Date.now()` where `performance` is unavailable. */
+declare function now(): number;
+/**
+ * The process-wide ticker.
+ *
+ * Created lazily on first access so that importing Ansh has no side effects — important
+ * for SSR, and for tree-shaking in apps that only use the pure colour or easing modules.
+ */
+declare function getTicker(): Ticker;
+/**
+ * Replace the shared ticker.
+ *
+ * Exists for tests (inject a manually-driven ticker) and for advanced hosts that need a
+ * custom scheduler. Disposes the previous instance so subscribers can't leak across the swap.
+ */
+declare function setTicker(ticker: Ticker): void;
+/** Tear down the shared ticker. Call between tests to guarantee isolation. */
+declare function resetTicker(): void;
+
+/**
+ * Environment-driven pausing.
+ *
+ * Animation that runs while nobody is looking is pure waste: it drains battery, heats the
+ * device, and on a laptop spins the fan for a page in a background tab. This module wires the
+ * ticker to the signals that tell us animation is pointless or unwelcome.
+ *
+ * Each signal holds a named pause on the ticker, so they compose — being both hidden and
+ * battery-saving means two holds, and restoring one doesn't resume prematurely.
+ */
+interface LifecycleOptions {
+    /** Pause while the document is hidden. Default `true`. */
+    pauseWhenHidden?: boolean;
+    /**
+     * Pause while the window has no focus.
+     *
+     * Off by default: a user with the page visible in a split-screen alongside their editor
+     * still expects to see the animation. Only worth enabling for genuinely heavy scenes.
+     */
+    pauseWhenBlurred?: boolean;
+    /**
+     * Reduce quality when the device reports low battery while discharging. Default `true`.
+     *
+     * The Battery Status API is only exposed in Chromium; where unavailable this is a no-op
+     * rather than an approximation, because guessing wrong either wastes power or degrades
+     * quality for no reason.
+     */
+    respectBattery?: boolean;
+    /** Battery level below which quality is reduced, in `[0, 1]`. Default `0.2`. */
+    batteryThreshold?: number;
+    /** Quality ceiling applied while on low battery. Default `0.5`. */
+    batterySaveQuality?: number;
+}
+/**
+ * Attach environment listeners to a ticker.
+ *
+ * @returns A cleanup function that removes every listener. Safe to call during SSR, where it
+ *          is a no-op — nothing is attached in the first place.
+ */
+declare function attachLifecycle(ticker: Ticker, options?: LifecycleOptions): Unsubscribe;
+
+/**
+ * An observable animated value.
+ *
+ * `MotionValue` is the interop currency of Ansh. It deliberately sits *outside* any
+ * framework's reactivity system, which is what lets one engine serve React, Vue and vanilla
+ * JS without adapters in the middle:
+ *
+ *  - React subscribes with `useSyncExternalStore` (or writes straight to the DOM, bypassing
+ *    re-renders entirely — the reason 60 FPS animation in React is possible at all).
+ *  - Vue wraps it in a `shallowRef`.
+ *  - Plain JS just calls `.on()`.
+ *
+ * Velocity tracking is built in because it is needed constantly (a spring that takes over from
+ * a drag must inherit the drag's velocity) and reconstructing it after the fact is lossy.
+ */
+type MotionValueListener<T> = (value: T, previous: T) => void;
+declare class MotionValue<T = number> {
+    private current;
+    private previous;
+    private listeners;
+    private renderListeners;
+    /** Timestamp and value of the last update, for velocity. */
+    private lastUpdated;
+    private lastValue;
+    private velocityValue;
+    /** Set while an `animate()` drives this value, so a new animation can cancel the old one. */
+    private stopAnimation;
+    constructor(initial: T);
+    get(): T;
+    getPrevious(): T;
+    /**
+     * Write a new value and notify subscribers.
+     *
+     * Notification is synchronous. That is a deliberate choice: this is called from inside the
+     * ticker's `write` phase, and deferring would push DOM writes into the next frame, adding a
+     * frame of latency to every animation.
+     */
+    set(value: T): void;
+    /**
+     * Write without notifying, then notify once.
+     * Used when several related values change together and should produce one visual update.
+     */
+    setSilent(value: T): void;
+    private updateVelocity;
+    /**
+     * Current velocity in units per second.
+     *
+     * Returns 0 if the value hasn't changed recently, so a spring picking up from rest doesn't
+     * inherit a phantom velocity from an interaction that ended a second ago.
+     */
+    getVelocity(): number;
+    /** Directly set velocity — used when handing off from a gesture to a spring. */
+    setVelocity(velocity: number): void;
+    /** Subscribe to changes. The listener is *not* called immediately. */
+    on(listener: MotionValueListener<T>): Unsubscribe;
+    /**
+     * Subscribe as a renderer — called before regular listeners.
+     *
+     * Framework bindings use this for the DOM write, so that visual output is never delayed by
+     * application-level subscribers.
+     */
+    onRender(listener: (value: T) => void): Unsubscribe;
+    get listenerCount(): number;
+    /**
+     * Register the currently-running animation so a subsequent one can interrupt it.
+     * Called by `animate()`; not part of the public surface.
+     */
+    attachAnimation(stop: () => void): void;
+    /** Stop whatever is animating this value, leaving it wherever it is. */
+    stop(): void;
+    get isAnimating(): boolean;
+    /** Release listeners and stop any animation. */
+    destroy(): void;
+}
+declare function motionValue<T>(initial: T): MotionValue<T>;
+/** Maps a tuple of value types to a tuple of MotionValues holding them. */
+type MotionValueTuple<Values extends readonly unknown[]> = {
+    [K in keyof Values]: MotionValue<Values[K]>;
+};
+/**
+ * A read-only value computed from one or more others.
+ *
+ * The derived value updates synchronously when any source changes, so a chain of transforms
+ * settles within a single frame rather than propagating one link per frame.
+ */
+declare function derived<Values extends readonly unknown[], Result>(sources: MotionValueTuple<Values>, compute: (...values: Values) => Result): MotionValue<Result> & {
+    destroy(): void;
+};
+/**
+ * Map one motion value through a function.
+ * Shorthand for the overwhelmingly common single-source case.
+ */
+declare function mapValue<In, Out>(source: MotionValue<In>, transform: (value: In) => Out): MotionValue<Out> & {
+    destroy(): void;
+};
+
+/**
+ * Generic value interpolation.
+ *
+ * `animate()` accepts numbers, colours, arrays, objects and unit strings, so it needs to pick
+ * an interpolator at runtime. Resolution happens **once**, at animation setup, and returns a
+ * closure — never per frame. A `typeof` check inside a frame loop that runs for every animated
+ * property on the page is exactly the sort of cost that quietly adds up to a dropped frame.
+ */
+type Interpolator<T> = (t: number) => T;
+interface InterpolateOptions {
+    /** Colour space for colour interpolation. Default `'oklab'`. */
+    colorSpace?: ColorSpace;
+}
+/** Numeric interpolation. The fast path, and by far the most common. */
+declare function interpolateNumber(from: number, to: number): Interpolator<number>;
+/**
+ * Colour interpolation, producing `rgb()`/`rgba()` strings ready for style assignment.
+ *
+ * Endpoints are parsed at setup, so per-frame cost is one mix plus one string build.
+ */
+declare function interpolateColor(from: string, to: string, space?: ColorSpace): Interpolator<string>;
+declare function interpolateUnitValue(from: string, to: string): Interpolator<string> | null;
+declare function interpolateNumericString(from: string, to: string): Interpolator<string> | null;
+/** Element-wise array interpolation. Length is taken from `from`. */
+declare function interpolateArray<T>(from: readonly T[], to: readonly T[], options?: InterpolateOptions): Interpolator<T[]>;
+/** Key-wise object interpolation. Keys absent from `to` hold their `from` value. */
+declare function interpolateObject<T extends Record<string, unknown>>(from: T, to: Partial<T>, options?: InterpolateOptions): Interpolator<T>;
+/**
+ * Pick the right interpolator for a pair of values.
+ *
+ * Order matters. Colours are checked before generic unit/numeric strings because
+ * `rgb(0, 0, 0)` would otherwise match the numeric-string path and get interpolated in sRGB,
+ * silently losing the perceptual blending that is the whole point of the colour engine.
+ */
+declare function resolveInterpolator<T>(from: T, to: T, options?: InterpolateOptions): Interpolator<T>;
+/**
+ * Interpolate through a series of keyframes.
+ *
+ * `offsets` default to even spacing. Segment interpolators are built once at setup, so a
+ * 20-keyframe animation costs the same per frame as a 2-keyframe one plus a short scan.
+ */
+declare function interpolateKeyframes<T>(values: readonly T[], offsets?: readonly number[], options?: InterpolateOptions): Interpolator<T>;
+
+/**
+ * A pure, seekable function of time.
+ *
+ * This is the shared core beneath both `animate()` and `Timeline`. Separating it out matters
+ * for more than DRY: because a sampler is a *pure function of elapsed time* with no internal
+ * cursor, a timeline can evaluate it at any point, in any order, forwards or backwards. An
+ * animation that advanced itself statefully could not be seeked or reversed at all.
+ *
+ * `animate()` adds a ticker subscription, delay and repeat handling on top. `Timeline` adds
+ * positioning and orchestration. Neither re-implements spring maths or interpolator resolution.
+ */
+type SamplerType = 'tween' | 'spring' | 'decay';
+interface SamplerOptions extends InterpolateOptions {
+    type?: SamplerType;
+    duration?: number;
+    easing?: EasingInput;
+    spring?: SpringInput;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    bounce?: number;
+    velocity?: number;
+    power?: number;
+    timeConstant?: number;
+    /** Explicit keyframe offsets in `[0, 1]`. Defaults to even spacing. */
+    offsets?: readonly number[];
+}
+interface Sampler<T> {
+    /** Value at `elapsed` seconds. Clamped at both ends — sampling past the end holds the last value. */
+    at(elapsed: number): T;
+    /** Natural duration in seconds. Tweens use the given duration; springs derive their own. */
+    readonly duration: number;
+    /** Normalised progress at `elapsed`, before interpolation. Springs may exceed `[0, 1]`. */
+    progressAt(elapsed: number): number;
+}
+declare const DEFAULT_TWEEN_DURATION = 0.4;
+/**
+ * Build a sampler for a value transition.
+ *
+ * Springs on numeric values drive the number directly, so overshoot is physically correct.
+ * Springs on anything else (colours, transform strings) drive *progress* through the
+ * interpolator instead — the overshoot is preserved, but there is no meaningful way to
+ * integrate a colour through a differential equation, and interpolating past 1 in OKLab is
+ * exactly the right visual result.
+ */
+declare function createSampler<T>(from: T, to: T | readonly T[], options?: SamplerOptions): Sampler<T>;
+declare function hasSpringOptions(options: SamplerOptions): boolean;
+
+/**
+ * The imperative animation driver.
+ *
+ * One function covers tweens, springs and inertial decay, because from a caller's point of view
+ * they differ only in how progress is generated — which is the {@link createSampler} concern.
+ * `animate()` owns only the parts that are about *driving*: the ticker subscription, delay,
+ * repeat handling and lifecycle callbacks.
+ *
+ * ```ts
+ * animate(0, 100, { duration: 0.6, easing: 'easeOutCubic', onUpdate: (v) => … })
+ * animate(x, 240, { type: 'spring', bounce: 0.3 })
+ * animate('#0275f4', '#9f0550', { duration: 1, onUpdate: (c) => (el.style.color = c) })
+ * ```
+ */
+type RepeatMode = 'loop' | 'reverse' | 'mirror';
+interface AnimationOptions<T> extends SamplerOptions {
+    /** Seconds to wait before starting. Default `0`. */
+    delay?: number;
+    /** Times to repeat after the first pass. `Infinity` is allowed. Default `0`. */
+    repeat?: number;
+    /** How to repeat. `'reverse'` plays backwards on alternate passes. Default `'loop'`. */
+    repeatMode?: RepeatMode;
+    /** Seconds to wait between repeats. Default `0`. */
+    repeatDelay?: number;
+    onUpdate?: (value: T) => void;
+    onComplete?: () => void;
+    onStart?: () => void;
+    /** Called on `stop()`, or when a new animation interrupts this one on the same MotionValue. */
+    onStop?: () => void;
+    /**
+     * How to behave under `prefers-reduced-motion`.
+     *
+     * `'jump'` (default) applies the final value immediately — the state change still happens, it
+     * just isn't animated, which is nearly always right for UI. `'ignore'` animates anyway; only
+     * correct when the motion itself carries information the user needs.
+     */
+    reducedMotion?: 'jump' | 'ignore';
+}
+interface AnimationControls {
+    /** Stop and leave the value where it is. */
+    stop(): void;
+    pause(): void;
+    play(): void;
+    /** Jump to a time in seconds, measured from the animation's start including its delay. */
+    seek(time: number): void;
+    /** Apply the final value and fire `onComplete`. */
+    finish(): void;
+    readonly isActive: boolean;
+    /** Total seconds including delay and repeats. `Infinity` when repeating forever. */
+    readonly duration: number;
+    /** Resolves on completion *or* on stop — it never rejects. */
+    readonly finished: Promise<void>;
+}
+declare function animate<T>(from: T | MotionValue<T>, to: T | readonly T[], options?: AnimationOptions<T>): AnimationControls;
+/**
+ * Continuously track a moving target with a spring.
+ *
+ * Distinct from `animate(…, { type: 'spring' })`, which resolves its target once at setup.
+ * Cursor followers, magnetic buttons and drag handles all need a target that moves *while* the
+ * spring is still travelling toward it.
+ *
+ * Uses semi-implicit Euler rather than the analytic solver: with a target that changes every
+ * frame, rebuilding the closed form each frame would cost more than integrating.
+ */
+declare function springTo(value: MotionValue<number>, getTarget: () => number, options?: SpringOptions & {
+    name?: string;
+}): Unsubscribe;
+
+/**
+ * A seekable, composable animation timeline.
+ *
+ * The central design decision: a timeline is a **pure function of time**, not a queue that
+ * advances itself. Every entry is a {@link import('./sampler').Sampler} placed at an absolute
+ * offset, so evaluating the timeline at `t` means evaluating each overlapping entry at `t - start`.
+ *
+ * That single choice is what makes `seek`, `reverse`, `timeScale` and scroll-driving all fall out
+ * for free. A queue-based timeline can only go forwards, one frame at a time, which is why
+ * scrubbing is a hard retrofit in libraries built that way.
+ *
+ * ```ts
+ * const tl = createTimeline()
+ *   .to(opacity, 1, { duration: 0.4 })
+ *   .to(y, 0, { duration: 0.6, easing: 'easeOutCubic' }, '<')   // with the previous
+ *   .label('revealed')
+ *   .to(scale, 1.05, { duration: 0.2 }, '+=0.1')                // 0.1s after the previous ends
+ *   .call(() => announce('ready'))
+ * ```
+ */
+/**
+ * Where to place an entry.
+ *
+ * - `number`       — absolute seconds from the timeline's start.
+ * - `'>'`          — after the previous entry ends. The default.
+ * - `'<'`          — at the same time the previous entry *started* (parallel).
+ * - `'+=0.2'`      — 0.2s after the previous entry ends.
+ * - `'-=0.2'`      — 0.2s before the previous entry ends (overlap).
+ * - `'<+=0.1'`     — 0.1s after the previous entry started.
+ * - `'myLabel'`    — at a label, optionally with `'myLabel+=0.3'`.
+ */
+type TimelinePosition = number | string;
+interface TimelineEntry {
+    start: number;
+    duration: number;
+    /** Apply this entry's state for a local time within `[0, duration]`. */
+    apply(localTime: number): void;
+    /** One-shot callbacks fire on crossing rather than continuously. */
+    readonly isCallback: boolean;
+    /** Tracks whether a callback has already fired in the current direction of travel. */
+    fired: boolean;
+    readonly name: string;
+}
+interface TimelineOptions {
+    /** Start playing as soon as the first entry is added. Default `true`. */
+    autoplay?: boolean;
+    /** Times to repeat after the first pass. `Infinity` allowed. Default `0`. */
+    repeat?: number;
+    /** Alternate direction each repeat. Default `false`. */
+    yoyo?: boolean;
+    /** Playback rate. Negative values play in reverse. Default `1`. */
+    timeScale?: number;
+    onComplete?: () => void;
+    onUpdate?: (time: number, progress: number) => void;
+    onRepeat?: (iteration: number) => void;
+    /**
+     * Under `prefers-reduced-motion`, jump straight to the end state. Default `true`.
+     * Set `false` only for timelines whose motion conveys required information.
+     */
+    respectReducedMotion?: boolean;
+}
+interface Timeline {
+    /** Animate a MotionValue to a target. */
+    to<T>(value: MotionValue<T>, to: T | readonly T[], options?: SamplerOptions & {
+        duration?: number;
+    }, position?: TimelinePosition): Timeline;
+    /** Animate a MotionValue *from* a value to its current one — the reveal-in pattern. */
+    from<T>(value: MotionValue<T>, from: T, options?: SamplerOptions & {
+        duration?: number;
+    }, position?: TimelinePosition): Timeline;
+    /** Animate an arbitrary value, receiving updates through a callback. */
+    tween<T>(from: T, to: T | readonly T[], options: SamplerOptions & {
+        duration?: number;
+        onUpdate: (value: T) => void;
+    }, position?: TimelinePosition): Timeline;
+    /** Animate many MotionValues with a stagger between them. */
+    stagger<T>(values: readonly MotionValue<T>[], to: T | readonly T[], options?: SamplerOptions & {
+        duration?: number;
+        stagger?: StaggerOptions;
+    }, position?: TimelinePosition): Timeline;
+    /** Fire a callback at a point in time. Fires once per crossing. */
+    call(fn: () => void, position?: TimelinePosition): Timeline;
+    /** Name a point so later entries can be positioned relative to it. */
+    label(name: string, position?: TimelinePosition): Timeline;
+    /** Nest another timeline. Its entries are flattened in at the given offset. */
+    add(child: Timeline, position?: TimelinePosition): Timeline;
+    play(): Timeline;
+    pause(): Timeline;
+    /** Play backwards from the current position. */
+    reverse(): Timeline;
+    /** Jump to a time in seconds without playing. */
+    seek(time: number): Timeline;
+    /** Jump to a normalised position in `[0, 1]`. */
+    progress(value: number): Timeline;
+    restart(): Timeline;
+    /** Apply the final state and stop. */
+    complete(): Timeline;
+    /** Stop and release the ticker subscription. */
+    kill(): void;
+    readonly duration: number;
+    readonly time: number;
+    readonly isPlaying: boolean;
+    timeScale: number;
+    /** Resolves when playback completes. Also resolves on `kill()`. */
+    readonly finished: Promise<void>;
+    /** Internal: used by `add()` to flatten a nested timeline. */
+    readonly entries: readonly TimelineEntry[];
+    readonly labels: ReadonlyMap<string, number>;
+}
+declare function createTimeline(options?: TimelineOptions): Timeline;
+
+/**
+ * Pooled `IntersectionObserver` and `ResizeObserver`.
+ *
+ * Creating one observer per element is the default pattern in most React/Vue code, and it is
+ * measurably wasteful: each observer is a separate object with its own callback and its own
+ * entry in the browser's internal bookkeeping. A page with 200 scroll-revealed elements creates
+ * 200 observers where 1 would do.
+ *
+ * These pools key observers by their *configuration*, so every element sharing a threshold
+ * and root margin shares one observer. Callbacks are dispatched from a `WeakMap` keyed by
+ * element, so unobserving an element cannot leak its callback.
+ */
+interface IntersectionConfig {
+    root?: Element | Document | null;
+    rootMargin?: string;
+    /** A single threshold or a list. Lists are sorted so `[0, 1]` and `[1, 0]` share a pool. */
+    threshold?: number | readonly number[];
+}
+type IntersectionCallback = (entry: IntersectionObserverEntry) => void;
+/**
+ * Observe an element's intersection with the viewport (or a custom root).
+ *
+ * @returns An unsubscribe function. When the last subscriber for an element leaves, the
+ *          element is unobserved; when the last element leaves a pool, the observer is
+ *          disconnected and dropped.
+ */
+declare function observeIntersection(element: Element, callback: IntersectionCallback, config?: IntersectionConfig): Unsubscribe;
+interface ResizeInfo {
+    width: number;
+    height: number;
+    /** Device-pixel dimensions when the browser reports them, else `width`/`height` × DPR. */
+    devicePixelWidth: number;
+    devicePixelHeight: number;
+    entry: ResizeObserverEntry;
+}
+type ResizeCallback = (info: ResizeInfo) => void;
+/**
+ * Observe an element's size.
+ *
+ * Defaults to the `content-box`, matching CSS layout intuition. Canvas-backed effects pass
+ * `'device-pixel-content-box'` where supported, because that gives the exact backing-store
+ * size and avoids the half-pixel blurring that comes from rounding CSS pixels ourselves.
+ */
+declare function observeResize(element: Element, callback: ResizeCallback, box?: ResizeObserverBoxOptions): Unsubscribe;
+/** Live pool counts. The leak harness asserts these return to zero after unmount. */
+declare function observerPoolStats(): {
+    intersection: number;
+    resize: number;
+};
+/** Disconnect every pooled observer. Test-only. */
+declare function resetObserverPools(): void;
+
+/**
+ * Scroll progress tracking.
+ *
+ * Scroll-linked animation is where layout thrashing is most likely, because the natural
+ * implementation — read `getBoundingClientRect()` in a `scroll` handler, then write a
+ * transform — forces a synchronous layout on every event, and scroll events fire faster than
+ * frames on many devices.
+ *
+ * Instead: the scroll handler only records that something changed, all measurement happens in
+ * the ticker's `read` phase, and consumers receive progress values in `compute`/`write`. One
+ * layout read per frame at most, no matter how many elements are tracked.
+ */
+type ScrollAxis = 'y' | 'x';
+/**
+ * Where an element's progress starts and ends, expressed as two alignment points.
+ *
+ * Read as "`element` edge relative to `viewport` edge", matching the mental model of GSAP
+ * ScrollTrigger and CSS scroll-driven animations:
+ *
+ * - `['start', 'end']`   — starts when the element's top reaches the viewport bottom.
+ * - `['start', 'start']` — starts when the element's top reaches the viewport top.
+ * - `['end', 'start']`   — ends when the element's bottom reaches the viewport top.
+ */
+type ScrollOffset = readonly [ScrollEdge, ScrollEdge];
+type ScrollEdge = 'start' | 'center' | 'end' | number;
+interface ScrollProgress {
+    /** Progress through the tracked range, `0` to `1`. */
+    progress: number;
+    /** Signed scroll velocity in pixels per second. */
+    velocity: number;
+    /** Scroll offset of the container, in pixels. */
+    scroll: number;
+    /** `1` when scrolling toward the end, `-1` toward the start, `0` when still. */
+    direction: -1 | 0 | 1;
+    /** Is any part of the element within the viewport range? */
+    inView: boolean;
+}
+interface ScrollTrackOptions {
+    axis?: ScrollAxis;
+    /** Start and end alignment. Default `['start', 'end']` and `['end', 'start']` respectively. */
+    offset?: {
+        start: ScrollOffset;
+        end: ScrollOffset;
+    };
+    /** Scroll container. Defaults to the window. */
+    container?: HTMLElement | null;
+}
+/**
+ * Track an element's progress through the viewport.
+ *
+ * @returns An unsubscribe function. The callback runs in the `compute` phase, so it is safe to
+ *          write styles from it — though writing in `write` is tidier for anything expensive.
+ */
+declare function trackScroll(element: HTMLElement, callback: (progress: ScrollProgress) => void, options?: ScrollTrackOptions): Unsubscribe;
+/**
+ * Track raw container scroll without reference to an element.
+ * Backs progress bars, "scrolled" header states, and scroll-velocity effects.
+ */
+declare function trackContainerScroll(callback: (info: {
+    progress: number;
+    scroll: number;
+    velocity: number;
+    max: number;
+}) => void, options?: {
+    axis?: ScrollAxis;
+    container?: HTMLElement | null;
+}): Unsubscribe;
+
+/**
+ * The plugin registry — Ansh's dependency-injection seam.
+ *
+ * Three jobs:
+ *
+ *  1. **Effect discovery.** The CLI and the docs site need to enumerate every available effect
+ *     without importing all of them. Registration provides that index.
+ *  2. **Renderer backends.** `canvas2d` ships today; `webgl` and `webgpu` will register against
+ *     the same interface. Effects request a *capability*, not a concrete API, so a new backend
+ *     requires no changes to any effect.
+ *  3. **Edition gating.** Pro components declare the capabilities they need. The registry is the
+ *     one place that decides whether they're available, instead of `if (isPro)` checks scattered
+ *     through eighty components.
+ *
+ * Deliberately not a general-purpose IoC container. It is a typed map with lifecycle hooks —
+ * enough for the extension points we actually have, and small enough to reason about.
+ */
+type CapabilityName = 'renderer:canvas2d' | 'renderer:webgl' | 'renderer:webgpu' | 'renderer:offscreen' | 'worker' | 'effect:core' | 'effect:pro' | 'behaviour:core' | 'behaviour:pro' | (string & {});
+interface Plugin {
+    readonly name: string;
+    readonly version?: string;
+    /** Capabilities this plugin provides once installed. */
+    readonly provides?: readonly CapabilityName[];
+    /** Capabilities that must already be present. Installation throws if any are missing. */
+    readonly requires?: readonly CapabilityName[];
+    install?(registry: Registry): void;
+    uninstall?(registry: Registry): void;
+}
+declare class CapabilityError extends Error {
+    readonly capability: CapabilityName;
+    constructor(capability: CapabilityName, hint?: string);
+}
+declare class Registry {
+    private readonly entries;
+    private readonly plugins;
+    private readonly capabilities;
+    /** Human-readable reason a gated capability is unavailable, keyed by capability. */
+    private readonly gateHints;
+    /**
+     * Store a value under `namespace:key`.
+     *
+     * Namespacing keeps effects, behaviours, renderers and easings from colliding, and lets
+     * `list('effect')` enumerate one kind without filtering.
+     */
+    register<T>(namespace: string, key: string, value: T): void;
+    get<T>(namespace: string, key: string): T | undefined;
+    /** Like {@link get} but throws a helpful error rather than returning `undefined`. */
+    require<T>(namespace: string, key: string): T;
+    has(namespace: string, key: string): boolean;
+    unregister(namespace: string, key: string): boolean;
+    list(namespace: string): string[];
+    entriesOf<T>(namespace: string): Array<[string, T]>;
+    provide(capability: CapabilityName): void;
+    revoke(capability: CapabilityName, hint?: string): void;
+    supports(capability: CapabilityName): boolean;
+    /**
+     * Assert a capability is available.
+     *
+     * This is the edition gate. A Pro effect calls
+     * `registry.requireCapability('effect:pro')` in its setup, and in the Free edition that
+     * throws with a message explaining what to do — at mount time, with a stack trace pointing
+     * at the component, rather than as a mysteriously blank canvas.
+     */
+    requireCapability(capability: CapabilityName): void;
+    listCapabilities(): CapabilityName[];
+    use(plugin: Plugin): this;
+    remove(name: string): boolean;
+    listPlugins(): Array<{
+        name: string;
+        version: string;
+    }>;
+    /** Wipe everything. Used between tests. */
+    clear(): void;
+}
+/** The process-wide registry, created on first use. */
+declare function getRegistry(): Registry;
+declare function resetRegistry(): void;
+
+/**
+ * @ansh-ui/core — the Ansh animation engine.
+ *
+ * A zero-dependency, framework-agnostic kernel. Everything the React, Vue and Nuxt packages do
+ * is a thin binding over what is exported here, and nothing in this package knows those
+ * frameworks exist.
+ *
+ * ## Deep imports
+ *
+ * For the smallest possible bundles, import from a subpath rather than the root:
+ *
+ * ```ts
+ * import { mixColors } from '@ansh-ui/core/color'
+ * import { createNoise } from '@ansh-ui/core/noise'
+ * import { easings } from '@ansh-ui/core/easing'
+ * ```
+ *
+ * Root imports tree-shake correctly in any modern bundler, so this is an optimisation for
+ * unusual setups rather than a requirement.
+ */
+
+/** The package version, injected at build time and useful in bug reports. */
+declare const VERSION = "0.1.0";
+
+export { type AnimationControls, type AnimationOptions, type BudgetReport, CapabilityError, type CapabilityName, Clock, type ClockOptions, ColorSpace, DEFAULT_TWEEN_DURATION, type DecayOptions, EasingInput, FrameBudget, type FrameBudgetOptions, FrameCallback, FramePhase, FrameState, type FrameTiming, type InterpolateOptions, type Interpolator, type IntersectionConfig, type LifecycleOptions, MotionValue, type MotionValueListener, type MotionValueTuple, type PerceptualSpringOptions, type PhysicalSpringOptions, type Plugin, Registry, type RepeatMode, type ResizeInfo, SPRING_DEFAULTS, type Sampler, type SamplerOptions, type SamplerType, type ScrollAxis, type ScrollEdge, type ScrollOffset, type ScrollProgress, type ScrollTrackOptions, type SpringInput, type SpringOptions, type SpringPresetName, type SpringRestOptions, type SpringSolver, type SpringState, StaggerOptions, SubscribeOptions, Ticker, type TickerOptions, type Timeline, type TimelineOptions, type TimelinePosition, Unsubscribe, VERSION, animate, attachLifecycle, createDecay, createSampler, createSpring, createTimeline, derived, getRegistry, getTicker, hasSpringOptions, interpolateArray, interpolateColor, interpolateKeyframes, interpolateNumber, interpolateNumericString, interpolateObject, interpolateUnitValue, mapValue, motionValue, now, observeIntersection, observeResize, observerPoolStats, perceptualToPhysical, physicalToPerceptual, resetObserverPools, resetRegistry, resetTicker, resolveInterpolator, resolveSpringOptions, setTicker, springTo, springs, trackContainerScroll, trackScroll };