/**
 * Represents a map of configurable settings for the StringTune system.
 * Each key corresponds to a setting name (e.g. 'offset-top', 'parallax', etc.).
 *
 * These settings can be used as:
 * - Global fallbacks via `setupSettings`
 * - Module-specific overrides via `use(MyModule, settings)`
 *
 * The values are typically string-based, but can also be numbers or booleans.
 */
interface StringSettings {
    [key: string]: string | number | boolean;
}

type EventCallback<T = any> = (payload: T) => void;

/**
 * Manages custom event subscriptions and dispatching.
 * Allows multiple listeners per event and supports optional `id` suffixing.
 */
declare class EventManager {
    private listeners;
    private stateEvents;
    private lastPayloads;
    constructor();
    /**
     * Subscribes to an event.
     * Optionally appends an `id` to the event name for namespacing.
     *
     * @param eventName The base event name (e.g. "scroll", "update").
     * @param callback The function to call when the event is emitted.
     * @param id Optional unique identifier to scope the event (e.g. element ID).
     */
    on<T = any>(eventName: string, callback: EventCallback<T>, id?: string | null): void;
    /**
     * Unsubscribes from a specific event listener.
     * Must match the original `eventName`, `callback`, and optional `id`.
     *
     * @param eventName The base event name to unsubscribe from.
     * @param callback The callback function to remove.
     * @param id Optional identifier used when subscribing.
     */
    off<T = any>(eventName: string, callback: EventCallback<T>, id?: string): void;
    /**
     * Emits an event with an optional payload.
     * All matching listeners will be called.
     *
     * @param eventName The full event name (must include `id` if used).
     * @param payload Optional data passed to event listeners.
     */
    emit<T = any>(eventName: string, payload?: T): void;
    /**
     * Subscribes to a per-object progress event.
     * @param id The object ID.
     * @param callback The callback to handle progress value.
     */
    onProgress(id: string, callback: EventCallback<number>): void;
    /**
     * Emits a per-object progress event.
     * @param id The object ID.
     * @param value The progress value.
     */
    emitProgress(id: string, value: number): void;
    /**
     * Subscribes to a per-object in-view event.
     * @param id The object ID.
     * @param callback The callback to handle visibility.
     */
    onInview(id: string, callback: EventCallback<boolean>): void;
    /**
     * Emits a per-object in-view event.
     * @param id The object ID.
     * @param visible Whether the object is visible.
     */
    emitInview(id: string, visible: boolean): void;
    /**
     * Subscribes to the global scroll event.
     * @param callback The callback to handle scroll value.
     */
    onScroll(callback: EventCallback<number>): void;
    /**
     * Emits the global scroll event.
     * @param value The scroll value.
     */
    emitScroll(value: number): void;
    /**
     * Subscribes to the global update event.
     * @param callback The callback to handle update.
     */
    onUpdate(callback: EventCallback<void>): void;
    /**
     * Emits the global update event.
     */
    emitUpdate(): void;
    /**
     * Clears all listeners for a specific event.
     *
     * @param eventName The full event name (including optional `id`).
     */
    clear(eventName: string): void;
    /**
     * Clears all registered events.
     */
    clearAll(): void;
}

/**
 * Reactive cursor data for raw, target, smoothed and step deltas.
 */
declare class CursorState {
    /**
     * Target X position of the cursor (e.g., from `mousemove`)
     */
    targetX: number;
    /**
     * Target Y position of the cursor.
     */
    targetY: number;
    /**
     * Smoothed X position after applying lerp.
     */
    smoothedX: number;
    /**
     * Smoothed Y position after applying lerp.
     */
    smoothedY: number;
    /**
     * Delta step between current and target X (used internally for lerp).
     */
    stepX: number;
    /**
     * Delta step between current and target Y.
     */
    stepY: number;
}

/**
 * Global Three.js or rendering context reference.
 */
declare class RenderState {
    /** Instance of Three.js or another render context */
    threeInstance: any;
}

type ScrollDirection = 'vertical' | 'horizontal';
type ScrollMode = 'smooth' | 'disable' | 'default';
/**
 * Describes current scroll-related state for all calculations and modules.
 */
declare class ScrollState {
    /** Target scroll value — where we want to scroll to (used in smooth scroll) */
    target: number;
    /** Current scroll value (actual scroll position) */
    current: number;
    /** Transformed current scroll value (with transform by scroll container) */
    transformedCurrent: number;
    /** Delta between frames (used for animation / velocity) */
    delta: number;
    /** Interpolated scroll value for smooth transitions */
    lerped: number;
    /** Displacement value (similar to lerped, but used for other animations) */
    displacement: number;
    /** Whether scroll direction is downward */
    isScrollingDown: boolean;
    /** Top screen scroll position */
    topPosition: number;
    /** Bottom screen scroll position */
    bottomPosition: number;
    /** Scroll direction (vertical / horizontal) */
    direction: ScrollDirection;
    /** Scroll container element */
    elementContainer: HTMLElement;
    /** Scroll container element */
    scrollContainer: HTMLElement | Window;
    /** Scroll container element */
    container: HTMLElement;
    /**
     * Currently active scroll mode.
     * Can be 'smooth', 'default', or 'disable'.
     */
    mode: ScrollMode;
    /**
     * Scroll mode to use on mobile devices.
     * Can be 'smooth', 'default', or 'disable'.
     */
    modeMobile: ScrollMode;
    /**
     * Scroll mode to use on desktop devices.
     * Can be 'smooth', 'default', or 'disable'.
     */
    modeDesktop: ScrollMode;
    /**
     * Base scroll speed used for calculating smooth scrolling.
     * Typically a small value between 0 and 1.
     */
    speed: number;
    /**
     * Acceleration factor used for scroll easing or velocity-based animations.
     * Also typically a value between 0 and 1.
     */
    speedAccelerate: number;
}

/**
 * Represents the time-related state of the current and previous animation frames.
 *
 * Useful for calculating delta time, total elapsed time, and implementing
 * time-based animations or physics.
 */
declare class TimeState {
    /**
     * Timestamp of the current animation frame in milliseconds.
     * This value is typically obtained via `performance.now()`.
     */
    now: number;
    /**
     * Timestamp of the previous animation frame in milliseconds.
     */
    previous: number;
    /**
     * Time difference between the current and previous frames in milliseconds.
     * Commonly used to calculate animation progress.
     */
    delta: number;
    /**
     * Total time elapsed since the start of the animation or system in milliseconds.
     */
    elapsed: number;
}

/**
 * Describes current viewport size and scaling.
 */
declare class ViewportState {
    /** Width of the visible window */
    windowWidth: number;
    /** Height of the visible window */
    windowHeight: number;
    /** Full scroll width (content width inside scroll container) */
    contentWidth: number;
    /** Full scroll height (content height inside scroll container) */
    contentHeight: number;
    /** Screen scale ratio for width (e.g. device pixel ratio or zoom level) */
    scaleWidth: number;
    /** Screen scale ratio for height */
    scaleHeight: number;
    transformScale: number;
    baseRem: number;
}

/**
 * Container for global dynamic state used throughout the string-tune system.
 * Provides access to live scroll, viewport, cursor, and render states,
 * which are updated each frame and shared across modules and tools.
 */
declare class StringData {
    /**
     * Scroll-related state object.
     * Contains live values like `target`, `current`, `delta`, `direction`, and more.
     * Used for scroll-based animations, transitions, and effects.
     */
    scroll: ScrollState;
    /**
     * Viewport-related state object.
     * Holds dimensions like window size, content size, aspect ratios, and more.
     * Useful for layout calculations, unit parsing, and element positioning.
     */
    viewport: ViewportState;
    /**
     * Cursor-related state object.
     * Tracks cursor position, velocity, movement, and derived values.
     * Can be used for pointer interactions, proximity effects, and hover states.
     */
    cursor: CursorState;
    /**
     * Render-related state object.
     * Stores data related to rendering context (e.g. WebGL, Three.js),
     * such as shared materials, textures, or active render frame data.
     */
    render: RenderState;
    /**
    * Time-related state object.
    * Tracks frame timings, including current timestamp, delta between frames,
    * and total elapsed time since animation start.
    * Useful for time-based animations, easing, frame consistency, and syncing logic.
    */
    time: TimeState;
}

/**
 * Base interface for injectable core tools in the String system.
 * Each tool takes input and returns output (transform, extract, calculate).
 */
interface IStringTool<Input = any, Output = any> {
    /**
     * Process input and return result.
     * Can be a transformation, extraction, interpolation, etc.
     *
     * @param input - Any input relevant to the tool.
     * @returns Output result from the tool.
     */
    process(input: Input): Output;
}

/**
 * Input for `BoundingClientRectTool`.
 */
interface BoundingClientRectInput {
    /** The DOM element to retrieve bounding rect from. */
    element: HTMLElement;
}
/**
 * Tool for accessing `getBoundingClientRect()` in a consistent, testable way.
 */
declare class BoundingClientRectTool implements IStringTool<BoundingClientRectInput, DOMRect> {
    /**
     * @returns The bounding client rect of the provided element.
     */
    process({ element }: BoundingClientRectInput): DOMRect;
}

interface DOMAttributeInput {
    element: HTMLElement;
    key: string;
    fallback?: string | null;
}
declare class DOMAttributeTool implements IStringTool<DOMAttributeInput, string | null> {
    /**
     * Retrieves the value of either `string-${key}` or `data-string-${key}` attribute.
     *
     * @example key = "offset-tom" → tries:
     *   - element.getAttribute("string-offset-tom")
     *   - element.getAttribute("data-string-offset-tom")
     */
    process({ element, key, fallback }: DOMAttributeInput): string | null;
}

/**
 * Input for retrieving a value from a key-value object or dataset-like structure.
 */
interface RecordAttributeInput {
    /** Source object to read from (e.g. dataset or plain record). */
    record: Record<string, any>;
    /** Key to look up (without `"data-"` prefix). */
    name: string;
    /** Fallback value if both keys are missing. */
    fallback?: any;
}
/**
 * Retrieves a value from an object or dataset-like structure.
 * Tries `record[name]` first, then `record["data-" + name]`, or returns fallback.
 */
declare class RecordAttributeTool implements IStringTool<RecordAttributeInput, any> {
    /**
     * @returns Value from the record or fallback.
     */
    process({ record, name, fallback }: RecordAttributeInput): any;
}

/**
 * Input for removing transform effects from an element's bounding box.
 */
interface TransformNullifyInput {
    /** The DOM element whose CSS transform should be nullified. */
    element: HTMLElement;
}
/**
 * Output with corrected bounding box values.
 */
interface TransformNullifyOutput {
    /** Top position without transform effects. */
    top: number;
    /** Left position without transform effects. */
    left: number;
    /** Width without transform scaling. */
    width: number;
    /** Height without transform scaling. */
    height: number;
}
/**
 * Computes the true bounding box of a DOM element,
 * nullifying CSS `transform: matrix(...)` effects.
 */
declare class TransformNullifyTool implements IStringTool<TransformNullifyInput, TransformNullifyOutput> {
    /**
     * @returns Element position and size without transform influence.
     */
    process({ element }: TransformNullifyInput): TransformNullifyOutput;
}

/**
 * Input for calculating the position of an element relative to a container.
 */
interface RelativePositionInput {
    /** The DOM element whose position should be calculated. */
    element: HTMLElement;
    /** Optional container to measure against. Defaults to `document.body`. */
    container?: HTMLElement;
}
/**
 * Output: relative position in pixels.
 */
interface RelativePositionOutput {
    /** Distance from the top of the container. */
    top: number;
    /** Distance from the left of the container. */
    left: number;
}
/**
 * Calculates an element's position relative to a container.
 * Uses `TransformNullifyTool` to account for CSS transforms.
 */
declare class RelativePositionTool implements IStringTool<RelativePositionInput, RelativePositionOutput> {
    /** Optional tool for CSS transform-neutral measurements. */
    private transformTool;
    constructor(
    /** Optional tool for CSS transform-neutral measurements. */
    transformTool?: TransformNullifyTool);
    /**
     * @returns Relative top/left position of element within container.
     */
    process({ element, container }: RelativePositionInput): RelativePositionOutput;
}

interface LerpInput {
    /** Starting value of the interpolation. */
    from: number;
    /** Target value to interpolate towards. */
    to: number;
    /** Interpolation progress between 0 (start) and 1 (end). */
    progress: number;
}
declare class LerpTool implements IStringTool<LerpInput, number> {
    /**
     * Calculates the linear interpolation between two values.
     * @returns Interpolated value.
     */
    process({ from, to, progress }: LerpInput): number;
}

/**
 * Input for parsing unit-based strings into numeric pixel values.
 */
interface UnitParserInput {
    /** Unit string, e.g. `"20px"`, `"50%"`, `"1.5rem"`, or `"selfHeight"` */
    value: string;
    /** DOM element used for `"selfHeight"` calculation */
    element: HTMLElement;
    /** Viewport height in pixels (for percentage conversion) */
    viewportHeight: number;
    /** Root font size in pixels (for rem conversion) */
    baseRem: number;
    boundingRect: DOMRect;
}
/**
 * Converts unit-based strings to numeric pixel values.
 * Supports `px`, `%`, `rem`, and `"selfHeight"` keyword. Handles negatives.
 */
declare class UnitParserTool implements IStringTool<UnitParserInput, number> {
    /**
     * @returns Numeric value in pixels (positive or negative).
     */
    process({ value, element, viewportHeight, baseRem, boundingRect, }: UnitParserInput): number;
}

/**
 * Input for adaptive lerp factor calculation.
 * Maps a speed-like value to a lerp factor, where:
 * - lower speed ⇒ slower smoothing (higher lerp factor)
 * - higher speed ⇒ faster response (lower lerp factor)
 */
interface AdaptiveLerpInput {
    /** Current value (e.g., speed or delta). */
    value: number;
    /** Minimum input threshold (default: 0.1) */
    inMin?: number;
    /** Maximum input threshold (default: 1.0) */
    inMax?: number;
    /** Output when input is at minimum (default: 0.65) */
    outMax?: number;
    /** Output when input is at maximum (default: 0.05) */
    outMin?: number;
}
/**
 * Converts a numeric input (like velocity) into an adaptive lerp factor.
 * Useful for scroll or speed-based smoothing effects.
 */
declare class AdaptiveLerpTool implements IStringTool<AdaptiveLerpInput, number> {
    /**
     * @returns A remapped lerp factor from `outMax` to `outMin`.
     */
    process({ value, inMin, inMax, outMin, outMax }: AdaptiveLerpInput): number;
}

/**
 * Input for origin parser.
 * Supports static values or `random(...)` expressions.
 */
interface OriginInput {
    /** Raw origin string, e.g. `'center'` or `'random(top, bottom)'`. */
    value: string;
}
/**
 * Tool that parses origin strings.
 * Allows static values like `'center'`, or expressions like `'random(...)'` to select one randomly.
 */
declare class OriginParserTool implements IStringTool<OriginInput, string> {
    /**
     * @returns Parsed string value (static or randomly chosen).
     */
    process({ value }: OriginInput): string;
}

interface StringColor {
    r: number;
    g: number;
    b: number;
    a: number;
}

/**
 * Input for parsing color strings into RGBA format.
 */
interface ColorParserInput {
    /** Color string in hex, rgb[a], or hsl[a] format. */
    value: string;
}
/**
 * Parses a CSS color string (`#fff`, `rgb(...)`, `hsl(...)`, etc.)
 * into an object with `r`, `g`, `b`, `a` values.
 */
declare class ColorParserTool implements IStringTool<ColorParserInput, StringColor> {
    /**
     * @returns RGBA object parsed from color string.
     */
    process({ value }: ColorParserInput): StringColor;
    private hslToRgb;
}

type ValidationErrorCode = "required" | "invalid-email" | "too-short" | "too-long";
type ValidationRule = "required" | "email" | {
    type: "minLength";
    value: number;
} | {
    type: "maxLength";
    value: number;
};
interface ValidationInput {
    /** Value to validate. */
    value: string;
    /** List of rules to apply. */
    rules: ValidationRule[];
    /**
     * Optional message map: key = errorCode, value = string or function returning a message.
     */
    messages?: Partial<Record<ValidationErrorCode, string | ((args: {
        value: string;
        rule: ValidationRule;
    }) => string)>>;
}
interface ValidationOutput {
    /** `true` if valid, `false` if error found. */
    valid: boolean;
    /** One of the known error codes (or null if no error). */
    error: ValidationErrorCode | null;
    /** Final message (either default or user-defined). */
    message: string | null;
}
/**
 * Tool for validating strings using rules like `required`, `minLength`, etc.
 * Allows custom error messages (as string or generator function).
 */
declare class ValidationTool implements IStringTool<ValidationInput, ValidationOutput> {
    /**
     * Validates input value and returns error code + message.
     */
    process({ value, rules, messages }: ValidationInput): ValidationOutput;
    private defaultMessage;
}

/**
 * Input parameters for EasingFunctionTool.
 */
interface EasingFunctionInput {
    /**
     * The easing string.
     * Can be: 'linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', or 'cubic-bezier(...)'
     */
    easing: string;
}
/**
 * Output of the easing function: receives t in [0,1] and returns eased value.
 */
type EasingFunctionOutput = (t: number) => number;
/**
 * Tool for parsing easing strings into easing functions.
 * Supports standard keywords (`ease-in`, `ease-out`, etc.) and `cubic-bezier(...)` expressions.
 */
declare class EasingFunctionTool implements IStringTool<EasingFunctionInput, EasingFunctionOutput> {
    private namedCurves;
    /**
     * Parses an easing string and returns a corresponding easing function.
     */
    process({ easing }: EasingFunctionInput): EasingFunctionOutput;
    /**
     * Generates a cubic-bezier easing function.
     * Ported from https://github.com/gre/bezier-easing (MIT)
     */
    private cubicBezier;
}

/**
 * Input parameters for calculating magnetic pull factor.
 */
interface MagneticPullInput {
    /** Distance between pointer and element center (px). */
    distance: number;
    /** Max distance within which magnetic pull is active. */
    radius: number;
    /** Strength of the magnetic pull (0–1 recommended). */
    strength: number;
}
/**
 * Output: factor to multiply by direction vector (dx/dy) to get magnetic offset.
 */
type MagneticPullOutput = number;
/**
 * Tool for calculating magnetic attraction based on distance to element.
 * Returns a scalar value (0..strength) depending on proximity.
 */
declare class MagneticPullTool implements IStringTool<MagneticPullInput, MagneticPullOutput> {
    /**
     * Returns a pull factor based on distance to target within a radius.
     * @param input - Magnetic pull parameters.
     * @returns A multiplier (typically < 1) to apply to dx/dy.
     */
    process({ distance, radius, strength }: MagneticPullInput): number;
}

/**
 * Input parameters for `LerpColorTool`.
 */
interface LerpColorInput {
    /**
     * Starting color as an object `{ r, g, b, a }` where each value is in the range `0–1`.
     */
    from: StringColor;
    /**
     * Target color as an object `{ r, g, b, a }` where each value is in the range `0–1`.
     */
    to: StringColor;
    /**
     * Interpolation progress from `0` (start) to `1` (end).
     */
    progress: number;
}
/**
 * Tool for linearly interpolating between two RGBA colors using `StringColor` format.
 * Each channel (`r`, `g`, `b`, `a`) is interpolated independently.
 * Returns a new `StringColor` with the interpolated values.
 */
declare class LerpColorTool implements IStringTool<LerpColorInput, StringColor> {
    /**
     * Performs linear interpolation between two `StringColor` values.
     *
     * @param input.from - The starting color `{ r, g, b, a }`.
     * @param input.to - The target color `{ r, g, b, a }`.
     * @param input.progress - A number from `0` to `1` indicating interpolation progress.
     * @returns Interpolated color as a new `StringColor`.
     */
    process({ from, to, progress }: LerpColorInput): StringColor;
}

interface StringVector {
    x: number;
    y: number;
}

/**
 * Input parameters for LerpVector2Tool.
 */
interface LerpVector2Input {
    /**
     * Starting vector value `{ x, y }`.
     */
    from: StringVector;
    /**
     * Target vector value `{ x, y }`.
     */
    to: StringVector;
    /**
     * Interpolation progress from `0` (start) to `1` (end).
     */
    progress: number;
}
/**
 * Tool for linearly interpolating between two 2D vectors.
 * Useful for cursor smoothing, UI element animations, and motion blending.
 */
declare class LerpVector2Tool implements IStringTool<LerpVector2Input, StringVector> {
    /**
     * Calculates the interpolated vector between `from` and `to`.
     *
     * @param input.from - The starting vector `{ x, y }`.
     * @param input.to - The target vector `{ x, y }`.
     * @param input.progress - Interpolation progress from `0` (start) to `1` (end).
     * @returns Interpolated vector `{ x, y }`.
     */
    process({ from, to, progress }: LerpVector2Input): {
        x: number;
        y: number;
    };
}

/**
 * Input for parsing the transform string to extract scale.
 */
interface TransformParserInput {
    /** CSS transform string (e.g., "matrix(0.5, 0, 0, 0.5, 10, 20)", "scale(0.5)", "none"). */
    value: string;
}
/**
 * Parses a CSS transform string to extract the primary scale factor.
 * Assumes uniform scale or extracts the X-axis scale factor from matrix/scale functions.
 */
declare class TransformScaleParserTool implements IStringTool<TransformParserInput, number> {
    /**
     * Processes the transform string and extracts the scale factor.
     * @returns Numeric scale factor (defaults to 1 if no scale transform is found or parsing fails).
     */
    process({ value }: TransformParserInput): number;
}

/**
 * Represents a single parsed option item definition
 * (e.g., the result of parsing '[center]' or '[random(0,10)|abs]').
 */
interface ISplitOptionItem {
    /** The alignment type ('start', 'center', 'end', 'random'). */
    align: string;
    /** Optional parameters for random alignment. */
    random?: {
        min: number;
        max: number;
    };
    /** Flag indicating if the absolute value should be used. */
    abs?: boolean;
}

/**
 * Represents the fully parsed options from the string-split attribute.
 * Holds arrays of option definitions for each split type.
 */
interface ISplitOptions {
    line?: ISplitOptionItem[];
    word?: ISplitOptionItem[];
    char?: ISplitOptionItem[];
    charLine?: ISplitOptionItem[];
    charWord?: ISplitOptionItem[];
    wordLine?: ISplitOptionItem[];
}

/**
 * Input interface for the SplitOptionsParserTool.
 */
interface SplitOptionsParserInput {
    /**
     * The raw string value from the 'string-split' attribute (or similar).
     * Can be null if the attribute is not present.
     */
    attributeValue: string | null;
}

/**
 * Tool responsible for parsing the string value of a split attribute
 * (e.g., "line[center]|char[random(0,10)|abs]") into a structured
 * ISplitOptions object.
 * Implements the IStringTool interface.
 */
declare class SplitOptionsParserTool implements IStringTool<SplitOptionsParserInput, ISplitOptions> {
    /**
     * Parses the attribute string into an ISplitOptions object.
     * Handles splitting by '|', parsing prefixes (word-, char-), main types (line, word, char),
     * and parameters within brackets (align, random, abs).
     *
     * @param input - An object containing the attributeValue string (can be null).
     * @returns An ISplitOptions object representing the parsed rules.
     * Returns an object with empty arrays if the attributeValue is null or empty.
     */
    process({ attributeValue }: SplitOptionsParserInput): ISplitOptions;
    /**
     * Parses an array of string parameters (extracted from within brackets `[...]`).
     * Determines alignment, random settings, and absolute flag.
     * Example input: ['center'], ['random(0, 10)', 'abs']
     *
     * @param params - An array of string parameters.
     * @returns An ISplitOptionItem object representing the parsed parameters.
     */
    private parseParamsArray;
}

/**
 * Interface describing all available tools used inside modules.
 */
interface StringToolsContainer {
    /** Tool for reading DOM attributes (including data-*). */
    domAttribute: DOMAttributeTool;
    /** Tool for reading attributes from a plain JS object or dataset. */
    recordAttribute: RecordAttributeTool;
    /** Tool for calculating the relative position between two elements. */
    relativePosition: RelativePositionTool;
    /** Tool that nullifies the effect of CSS transform matrix. */
    transformNullify: TransformNullifyTool;
    /** Tool that wraps getBoundingClientRect with consistent output. */
    boundingClientRect: BoundingClientRectTool;
    /** Tool for parsing string-based values like '50%', '2rem', 'selfHeight'. */
    unitParser: UnitParserTool;
    /** Tool for performing linear interpolation (lerp). */
    lerp: LerpTool;
    /**
     * Tool for adaptive interpolation based on dynamic input value.
     * Useful when smoothing cursor speed, scroll velocity, etc.
     */
    adaptiveLerp: AdaptiveLerpTool;
    /**
     * Tool for parsing origin strings.
     * Supports values like `'top'`, `'center'`, or random expressions like `'random(top, bottom)'`.
     */
    originParser: OriginParserTool;
    /**
     * Tool for parsing CSS color strings into { r, g, b, a } format.
     * Supports `#hex`, `rgb[a](...)`, `hsl[a](...)` inputs.
     */
    colorParser: ColorParserTool;
    /**
     * Tool for validating strings using rules like `required`, `minLength`, `email`, etc.
     * Returns validation status, error code, and optional message.
     */
    validation: ValidationTool;
    /**
     * Tool for parsing CSS-like easing strings into easing functions.
     * Supports keywords like `'ease'`, `'linear'`, and full `cubic-bezier(...)` expressions.
     */
    easingFunction: EasingFunctionTool;
    /**
     * Tool for calculating magnetic offset strength based on proximity to pointer.
     */
    magneticPull: MagneticPullTool;
    /**
     * Tool for interpolating between two RGBA colors.
     * Accepts `from` and `to` colors as `{ r, g, b, a }`, and a `progress` value from `0` to `1`.
     * Returns an interpolated `StringColor` object.
     */
    lerpColor: LerpColorTool;
    /**
     * Tool for interpolating between two 2D vectors.
     * Accepts `{ x, y }` objects and a `progress` value between `0` and `1`.
     * Returns a new `{ x, y }` vector.
     */
    lerpVector: LerpVector2Tool;
    transformScaleParser: TransformScaleParserTool;
    optionsParser: SplitOptionsParserTool;
}

/**
 * Shared context object passed to all modules and core controllers.
 *
 * Provides access to shared tools, data, settings, and event handling.
 */
interface StringContext {
    /**
     * Collection of utility tools (e.g. lerp, dom parser, unit converter).
     */
    tools: StringToolsContainer;
    /**
     * Reactive state container including scroll, viewport, cursor, etc.
     */
    data: StringData;
    /**
     * Global configuration settings for modules and system behavior.
     */
    settings: StringSettings;
    /**
     * Centralized event emitter and listener system.
     */
    events: EventManager;
}

/**
 * Internal class representing a DOM-bound interactive object.
 * Connected to modules and holds its own internal state.
 */
declare class StringObject {
    /**
     * The DOM element this object wraps.
     */
    htmlElement: HTMLElement;
    /**
     * Unique global ID assigned by the system.
     */
    id: string;
    /**
     * Space-separated list of all attribute keys associated with this object.
     */
    keys: string[];
    /**
     * A list of elements that should be affected in sync with this one.
     */
    connects: HTMLElement[];
    /**
     * Internal key-value store of dynamic object properties (like offsets, progress, etc.).
     */
    private properties;
    /**
     * Modules currently connected to this object.
     */
    private modules;
    /**
     * Manages and handles events for the object.
     * Provides functionality to register, trigger, and manage event listeners.
     */
    events: EventManager;
    constructor(id: string, element: HTMLElement);
    /**
     * Stores a property value for this object.
     * @param key - Property name
     * @param value - Value to store
     */
    setProperty<T>(key: string, value: T): void;
    /**
     * Retrieves a previously stored property value.
     * @param key - Property name
     * @returns The value or null if not set
     */
    getProperty<T>(key: string): T;
    /**
     * Marks this object as "active" (usually on intersection/scroll enter).
     */
    enter(): void;
    /**
     * Marks this object as "inactive" (usually on intersection/scroll leave).
     */
    leave(): void;
    /**
     * Removes the current object by iterating through all associated modules
     * and invoking their `removeObject` method with the object's ID.
     *
     * This method ensures that the object is properly removed from all
     * modules it is associated with.
     */
    remove(): void;
    /**
     * Shows the object, applies visual class and notifies connected modules.
     */
    show(): void;
    /**
     * Hides the object, removes visual class (if repeat is enabled), and notifies modules.
     */
    hide(): void;
    /**
     * Connects a module to this object if not already connected.
     * @param module - The module to connect
     */
    connect(module: IStringModule): void;
}

/**
 * Base interface for scroll/interaction modules in the StringScroll system.
 */
interface IStringModule {
    /** Cleans up all internal state and detaches from the system. */
    destroy(): void;
    /** Called once when the module is initialized. */
    onInit(): void;
    /** Called on each frame with current scroll and state data. */
    onFrame(data: StringData): void;
    /** Called when the window or layout is resized. */
    onResize(): void;
    /** Called when the system rebuilds the DOM (e.g. after mutations). */
    onDOMRebuild(): void;
    /** Called when scroll position changes. */
    onScroll(data: StringData): void;
    /** Called when scroll change diraction. */
    onDirectionChange(): void;
    /** Called when scrolling starts (user begins scroll). */
    onScrollStart(): void;
    /** Called when scrolling ends (user stops scroll). */
    onScrollStop(): void;
    /** Called when scroll direction changes (e.g. up → down). */
    onScrollDirectionChange(): void;
    /** Called when overall scroll axis changes (vertical ↔ horizontal). */
    onAxisChange(): void;
    /** Called when device type changes (e.g. desktop ↔ mobile). */
    onDeviceChange(): void;
    /** Called when scroll-related system settings or params are updated. */
    onScrollConfigChange(): void;
    /**
     * Called when global system settings are updated via `setupSettings`.
     * Modules can override this to re-read default values, refresh configs,
     * or reapply any cached parameters that depend on settings.
     *
     * This method is triggered after global fallback settings are merged into context.
     *
     * Example use cases:
     * - Recalculating default lerp, anchor, radius, etc.
     * - Updating internal thresholds or animation values.
     * - Reacting to system-wide design changes.
     */
    onSettingsChange(): void;
    /** Called on mouse move (for interaction-based modules). */
    onMouseMove(event: MouseEvent): void;
    /** Called on wheel scroll (separate from general scroll). */
    onWheel(event: WheelEvent): void;
    /**
     * Called when the DOM mutates — useful for detecting new or removed elements.
     */
    onDOMMutate(added: NodeList, removed: NodeList): void;
    /**
     * Triggered when an object was successfully connected.
     */
    onObjectConnected(object: StringObject): void;
    /**
     * Called when a DOM element is detected as a potential interactive object.
     */
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    calculatePositions(object: StringObject, windowSize: number): void;
    /**
     * Check if a module should connect to a given object.
     */
    canConnect(object: StringObject): boolean;
    /**
     * Called to connect this module to the object.
     */
    connectObject(object: StringObject): void;
    /**
     * Called when the cursor or interaction enters an object's area.
     */
    enterObject(id: string, object: StringObject): void;
    /**
     * Called when the interaction leaves the object's area.
     */
    exitObject(id: string): void;
    addObject(id: string, object: StringObject): void;
    removeObject(id: string): void;
}

type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "tuple" | "easing" | "color" | {
    type: "enum";
    values: string[];
};

/**
 * Represents the fallback value for an attribute mapping.
 * It can either be a static value or a function that dynamically
 * computes a value based on the element, object, and its bounding rectangle.
 */
type AttributeFallback = any | ((context: {
    element: HTMLElement;
    object: StringObject;
    boundingRect: DOMRect;
}) => any);
/**
 * Describes how a specific attribute should be mapped from an HTML element
 * to internal module data. Each mapping defines the attribute key, its expected type,
 * an optional fallback value, and an optional transformation function.
 */
type AttributeMapping = {
    /** Attribute name (without `string-` prefix). */
    key: string;
    /** The type used for parsing this attribute (e.g., 'number', 'boolean', 'tuple'). */
    type: AttributeType;
    /**
     * Optional fallback value if the attribute is not present on the element.
     * Can be a static value or a dynamic function.
     */
    fallback?: AttributeFallback;
    /**
     * Optional transformation function to apply to the parsed attribute value.
     * Useful for converting parsed data into a more usable format.
     */
    transform?: (value: any) => any;
};

/**
 * Base class for a module used in the string-tune system.
 * Extend this class to create custom modules that respond to scroll, resize, input, etc.
 */
declare class StringModule implements IStringModule {
    /**
     * List of attribute names this module should automatically read
     * from the DOM element and assign to the object properties.
     * Example: ["offset-top", "offset-bottom"]
     */
    protected attributesToMap: AttributeMapping[];
    /**
     * A map that associates string keys with `StringObject` instances.
     * This map is used to manage and track `StringObject` instances on a page.
     */
    protected objectMapOnPage: Map<string, StringObject>;
    /**
     * A protected array that holds the collection of `StringObject` instances
     * currently present on the page.
     */
    protected objectsOnPage: StringObject[];
    /**
     * A map of all entered objects by their unique ID.
     */
    protected objectMap: Map<string, StringObject>;
    /**
     * A flat array of all connected objects.
     */
    protected objects: StringObject[];
    /**
     * The HTML attribute key that identifies objects this module is responsible for.
     */
    protected htmlKey: string;
    /**
     * Module type ID used internally to categorize module behavior.
     */
    protected _type: number;
    /**
     * Returns the type of the module.
     * Type 1 = core module, type 2 = UI module.
     */
    get type(): number;
    /**
     * Tools container providing utilities for attribute parsing, unit conversion, etc.
     * Acts as a dependency injection hub for core IStringTool implementations.
     */
    protected tools: StringToolsContainer;
    /**
     * Shared global data object containing scroll state, viewport info, cursor position, etc.
     * Used for calculations within lifecycle hooks like `onScroll`, `onFrame`, and `onResize`.
     */
    protected data: StringData;
    /**
     * Configuration object specific to the current module.
     * Passed in during module registration or initialization.
     */
    protected settings: Record<string, any>;
    /**
     * Event hub for communication between modules or systems.
     * Supports custom event emitting, listening, and unsubscription.
     */
    protected events: EventManager;
    constructor(context: StringContext);
    /**
     * Initializes a `StringObject` by mapping attributes from an HTML element
     * and applying transformations as needed.
     *
     * @param globalId - A unique identifier for the object being initialized.
     * @param object - The `StringObject` instance to be initialized.
     * @param element - The HTML element from which attributes are extracted.
     * @param attributes - A record of additional attributes to be used during initialization.
     *
     * The method performs the following steps:
     * 1. Retrieves the bounding rectangle of the provided HTML element.
     * 2. Iterates over a predefined list of attributes to map.
     * 3. Resolves fallback values for attributes, either from the provided attributes,
     *    settings, or a fallback function.
     * 4. Processes and parses the raw attribute values based on their expected type.
     * 5. Applies optional transformations to the parsed values.
     * 6. Sets the processed attributes as properties on the `StringObject` instance.
     */
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    /**
     * Calculates object-specific positions or metrics based on the current layout or scroll state.
     * This method is intended to be overridden in subclasses if the module needs to precompute
     * layout-dependent values (e.g. parallax offsets, trigger zones, distances).
     *
     * @param object The `StringObject` instance whose positions are being calculated.
     * @param windowSize The current window height or width (depending on scroll axis).
     */
    calculatePositions(object: StringObject, windowSize: number): void;
    /**
     * Parses a raw DOM attribute value into the correct type based on mapping.
     * Handles fallback resolution, transformation, and special units.
     *
     * @param value Raw attribute string from DOM.
     * @param type The expected attribute type (e.g. number, boolean, dimension).
     * @param context Optional helper values like element or viewport size.
     * @returns The parsed and transformed value.
     */
    protected parseAttribute(value: string | null, type: AttributeType, context?: {
        element?: HTMLElement;
        boundingRect?: DOMRect;
        viewportHeight?: number;
        baseRem?: number;
    }): any;
    /**
     * Determines whether the module should attach to a given object,
     * based on the presence of the module's `htmlKey` in the object keys.
     *
     * @param object The target object to test.
     * @returns `true` if the module can connect, `false` otherwise.
     */
    canConnect(object: StringObject): boolean;
    /**
     * Registers the module on a given object, adds the object to internal list,
     * and triggers connection logic.
     *
     * @param object The object to connect to.
     */
    connectObject(object: StringObject): void;
    /**
     * Registers the object internally when it enters the module’s scope.
     */
    enterObject(id: string, object: StringObject): void;
    /**
     * Unregisters the object when it leaves the module’s scope.
     */
    exitObject(id: string): void;
    /**
     * Adds a `StringObject` to the internal collections if it does not already exist.
     *
     * @param id - The unique identifier for the `StringObject`.
     * @param object - The `StringObject` to be added.
     *
     * @remarks
     * This method ensures that the object is added to both `objectMapOnPage` and
     * `objectsOnPage` only if the `id` is not already present in `objectMapOnPage`.
     */
    addObject(id: string, object: StringObject): void;
    /**
     * Removes an object from the page by its unique identifier.
     *
     * This method performs the following steps:
     * 1. Retrieves the object associated with the given `id` from `objectMapOnPage`.
     * 2. If the object is not found, the method exits early.
     * 3. Deletes the object from `objectMapOnPage`.
     * 4. Finds the index of the object in the `objectsOnPage` array.
     * 5. If the object exists in the array, it is removed using `splice`.
     *
     * @param id - The unique identifier of the object to be removed.
     */
    removeObject(id: string): void;
    /**
     * Called when an object is connected. Can be overridden to apply initial styles or logic.
     * @param object The connected object.
     */
    onObjectConnected(object: StringObject): void;
    /**
     * Applies a style or callback to both the main element and all its connected elements.
     *
     * @param object The object whose elements to update.
     * @param applyFn The function that receives an HTMLElement and performs any update.
     */
    protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void): void;
    /**
     * Cleans up internal state and detaches the module from the system.
     */
    destroy(): void;
    /** Called once when the module is initialized. */
    onInit(): void;
    /** Called on each frame with current scroll and state data. */
    onFrame(data: StringData): void;
    /** Called when the window or layout is resized. */
    onResize(): void;
    /** Called when scroll position changes. */
    onScroll(data: StringData): void;
    /** Called when user changed scroll diraction. */
    onDirectionChange(): void;
    /** Called when user starts scrolling. */
    onScrollStart(): void;
    /** Called when user stops scrolling. */
    onScrollStop(): void;
    /** Called when scroll direction changes (e.g., up ↔ down). */
    onScrollDirectionChange(): void;
    /** Called when scroll axis changes (vertical ↔ horizontal). */
    onAxisChange(): void;
    /** Called when device type changes (e.g., desktop ↔ mobile). */
    onDeviceChange(): void;
    /** Called when scroll-related system settings or parameters change. */
    onScrollConfigChange(): void;
    /** Called when scroll-related system settings or parameters change. */
    onSettingsChange(): void;
    /** Called when the DOM is rebuilt, such as after a major mutation. */
    onDOMRebuild(): void;
    /** Called on every mouse movement. */
    onMouseMove(event: MouseEvent): void;
    /** Called on wheel input (independent of scroll). */
    onWheel(event: WheelEvent): void;
    /**
     * Called when DOM elements are added or removed.
     */
    onDOMMutate(added: NodeList, removed: NodeList): void;
}

declare class StringCursor extends StringModule {
    protected enterObjectsMap: Map<string, StringObject>;
    protected enterObjects: Array<StringObject>;
    cursor: any;
    cursorContent: any;
    overCount: number;
    constructor(context: StringContext);
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    onFrame(data: StringData): void;
    onObjectConnected(object: StringObject): void;
    getCursorClass(object: StringObject): string | null;
    onMouseEnter(object: StringObject): void;
    onMouseLeave(object: StringObject): void;
    private onEnterObject;
    private onLeaveObject;
    private setMouseCoordinates;
    private calculateOffset;
}

declare class StringMagnetic extends StringModule {
    constructor(context: StringContext);
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    onMouseMove(e: MouseEvent): void;
    onFrame(data: StringData): void;
}

/**
 * Module that handles lazy-loading of images with `string-lazy` attribute.
 * Automatically loads and applies aspect-ratio once image is loaded.
 */
declare class StringLazy extends StringModule {
    private isStartLoaded;
    private loadingCount;
    constructor(context: StringContext);
    /**
     * Called on module start — preloads all <img string-lazy> in DOM.
     */
    onInit(): void;
    /**
     * Called when an image becomes a managed object.
     */
    onObjectConnected(object: StringObject): void;
    /**
     * Loads image and sets aspect-ratio based on real dimensions.
     */
    private loadImage;
    /**
     * Loads image data to extract real dimensions and apply aspect-ratio style.
     */
    private setAspectRatio;
}

/**
 * Represents a module responsible for handling loading-related functionality.
 * Extends the `StringModule` class and provides additional behavior for managing
 * loading states and timeouts.
 */
declare class StringLoading extends StringModule {
    loadingTimeout: number;
    constructor(context: StringContext);
    onInit(): void;
}

declare class StringResponsive extends StringModule {
    private queries;
    private isMobileMedia;
    private isTabletMedia;
    private isLaptopMedia;
    private isDesktopMedia;
    private matchMedias;
    constructor(context: StringContext);
    onConnect(): void;
    onInit(): void;
    onResize(): void;
    private updateElements;
}

/**
 * The `StringAnchor` class extends the `StringModule` class and is responsible for
 * managing anchor-related functionality within the string module system.
 *
 * This class maps an `anchor` attribute to a tuple containing x and y coordinates,
 * processes these coordinates using the `originParser` tool, and applies the resulting
 * values to the connected object's element as a CSS `transform-origin` style.
 */
declare class StringAnchor extends StringModule {
    constructor(context: StringContext);
    onObjectConnected(object: StringObject): void;
}

/**
 * The `StringGlide` class is a module that handles the glide effect for string objects
 * based on scroll events. It calculates displacement, acceleration, and velocity
 * to create a smooth scrolling effect for objects.
 */
declare class StringGlide extends StringModule {
    private previousLerp;
    private displacement;
    private acceleration;
    private velocityMultiplier;
    private isInitialScroll;
    private baseVelocityMultiplier;
    private reducedVelocityMultiplier;
    private negativeVelocityMultiplier;
    private maxDisplacementValue;
    constructor(context: StringContext);
    private setupItem;
    private onUpdateDesktopEvent;
    private onUpdateMobileEvent;
    private onUpdateEvent;
    private calcExpanderFactor;
    onStart(): void;
    onResize(): void;
    private resetState;
    onScrollStart(): void;
    onScrollStop(): void;
    onFrame(data: StringData): void;
}

/**
 * Module that updates the `--lerp` CSS variable on elements
 * based on current scroll velocity.
 */
declare class StringLerp extends StringModule {
    constructor(context: StringContext);
    /**
     * Resets the `--lerp` value to 0 when scroll stops.
     */
    onScrollStop(): void;
    /**
     * Updates `--lerp` value for each connected object during scroll.
     */
    onFrame(data: StringData): void;
    /**
     * Sets the `--lerp` CSS variable on the object.
     */
    private setLerpValue;
}

/**
 * The `StringProgress` class extends the `StringModule` class and is responsible for
 * managing progress-based behavior for elements during scroll events. It maps specific
 * attributes, initializes objects, and updates their progress based on scroll data.
 */
declare class StringProgress extends StringModule {
    constructor(context: StringContext);
    /**
     * Called when an object is initialized.
     */
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    /**
     * Called on scroll.
     */
    onScroll(data: StringData): void;
    onObjectConnected(object: StringObject): void;
    private setUpObject;
}

/**
 * The `StringParallax` class extends the `StringProgress` class to provide
 * functionality for handling parallax effects on scrollable elements.
 * It maps specific attributes related to parallax and calculates the
 * necessary transformations based on scroll progress and viewport size.
 */
declare class StringParallax extends StringProgress {
    constructor(context: StringContext);
    /**
     * Called when an object is initialized.
     */
    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
    /**
     * Called on scroll.
     */
    onScroll(data: StringData): void;
    /**
     * Called on resize.
     */
    onResize(): void;
    private handleScrollDesktop;
    private handleScrollMobile;
    private scrollHandler;
}

declare class StringScrollbar extends StringModule {
    private scrollbar;
    private thumb;
    private scrollTimeout;
    private isDragging;
    private scrollMode;
    private mouseUpEventBind;
    private mouseDownEventBind;
    private mouseMoveEventBind;
    private scrollbarState;
    private scrollbarStateHorizontal;
    private scrollbarStateVertical;
    constructor(context: StringContext);
    destructor(): void;
    onInit(): void;
    onScroll(data: StringData): void;
    onResize(): void;
    private addCustomStyles;
    private createScrollbar;
    private updateThumb;
    private mouseDownEvent;
    private mouseMoveEvent;
    private mouseUpEvent;
    private showScrollbar;
    private hideScrollbar;
}

/**
 * StringSplit module: splits text into lines, words, chars,
 * computes alignment/random values, and applies CSS vars.
 */
declare class StringSplit extends StringModule {
    constructor(context: StringContext);
    onResize(): void;
    onObjectConnected(object: StringObject): void;
    split(element: HTMLElement, options: ISplitOptions): {
        fragment: DocumentFragment;
        result: DocumentFragment;
    };
    /**
     * Computes a numeric value based on the provided split option, index, and total count.
     *
     * @param opt - The split option item containing alignment and optional random range.
     * @param index - The current index in the sequence.
     * @param total - The total number of items in the sequence.
     * @returns A computed numeric value based on the alignment strategy:
     *          - "random": A random value within the specified range or default range.
     *          - "start": The current index.
     *          - "end": The reverse index from the end of the sequence.
     *          - "center": The distance from the center index.
     *          - Default: The current index.
     */
    private computeValue;
    /**
     * Applies calculated values to the provided layout lines and their components (words and characters)
     * based on the given options. This method computes and assigns various calculated values
     * (e.g., alignment and value) to lines, words, and characters, depending on the specified options.
     *
     * @param lines - An array of `LayoutLine` objects representing the lines of text to process.
     * @param options - An `ISplitOptions` object specifying the calculation options for lines, words, and characters.
     *
     * The `options` parameter can include the following properties:
     * - `line`: An array of options for calculating values at the line level.
     * - `word`: An array of options for calculating values at the word level.
     * - `wordLine`: An array of options for calculating values at the word level relative to the line.
     * - `char`: An array of options for calculating values at the character level.
     * - `charWord`: An array of options for calculating values at the character level relative to the word.
     * - `charLine`: An array of options for calculating values at the character level relative to the line.
     *
     * Each calculated value is assigned to the corresponding `calculatedValues` property of the line, word, or character.
     * The method ensures that all specified options are processed and the calculated values are appended accordingly.
     */
    private applyCalculatedValues;
    /**
     * Escapes the `src` attribute in a given string by removing the quotes around the URL.
     *
     * This method searches for occurrences of `src="URL"` where `URL` is an HTTP or HTTPS link,
     * and replaces it with `src=URL` (removing the quotes around the URL).
     *
     * @param str - The input string containing the `src` attributes to be escaped.
     * @returns The modified string with escaped `src` attributes.
     */
    private escapeAttribute;
}

/**
 * Visual tracker that plots scroll displacement (velocity) in real time.
 * Useful for debugging and tuning smoothing behavior.
 */
declare class StringDelayLerpTracker extends StringModule {
    private canvas;
    private context;
    private history;
    private maxPoints;
    private height;
    private value;
    private target;
    constructor(context: StringContext);
    /**
     * Called when the module starts — sets up canvas.
     */
    onInit(): void;
    /**
     * Called on scroll — stores current displacement and redraws.
     */
    onScroll(data: StringData): void;
    /**
     * Draws the displacement graph to canvas.
     */
    private draw;
    /**
     * Creates and styles the tracking canvas.
     */
    private initCanvas;
    /**
     * Optional method to update external comparison target.
     */
    setTarget(position: number): void;
    /**
     * Removes the canvas from DOM and resets.
     */
    clear(): void;
}

/**
 * FPS Tracker Module.
 * Displays how many times `onFrame()` is called per second.
 * Useful for debugging rendering performance or vsync issues.
 */
declare class StringFPSTracker extends StringModule {
    private displayElement;
    private intervalId;
    private frameCount;
    constructor(context: StringContext);
    /**
     * Initializes the visual FPS counter and update interval.
     */
    onInit(): void;
    /**
     * Increments the frame counter each frame.
     */
    onFrame(_data: StringData): void;
    /**
     * Cleans up DOM and interval.
     */
    destroy(): void;
    /**
     * Creates and styles the floating FPS display.
     */
    private createDisplayElement;
}

/**
 * Visual tracker that plots lerped scroll velocity (v) in real time.
 * Useful for analyzing smooth scroll interpolation behavior.
 */
declare class StringLerpTracker extends StringModule {
    private canvas;
    private context;
    private history;
    private maxPoints;
    private canvasHeight;
    private currentValue;
    private targetValue;
    constructor(context: StringContext);
    /**
     * Called on start — sets up canvas overlay.
     */
    onInit(): void;
    /**
     * Called on scroll — reads smoothed scroll velocity (v).
     */
    onScroll(data: StringData): void;
    /**
     * Draws the current graph line based on v-history.
     */
    private draw;
    /**
     * Creates the canvas overlay and applies style.
     */
    private initCanvas;
    /**
     * Optional external target value for debugging.
     */
    setTarget(position: number): void;
    /**
     * Removes canvas from DOM and clears history.
     */
    clear(): void;
}

/**
 * Tracker module that shows current scroll position and direction.
 * Displays a fixed label in the corner of the screen for debugging.
 */
declare class StringPositionTracker extends StringModule {
    private displayElement;
    constructor(context: StringContext);
    /**
     * Called on start — creates the DOM element for position display.
     */
    onInit(): void;
    /**
     * Called on scroll — updates scroll position and direction symbol.
     */
    onScroll(data: StringData): void;
    /**
     * Removes display element from DOM.
     */
    destroy(): void;
    /**
     * Creates and styles the floating position indicator.
     */
    private createDisplayElement;
}

declare class StringVideoAutoplay extends StringModule {
    constructor(context: StringContext);
    onObjectConnected(object: StringObject): void;
    private onEnterObject;
    private onLeaveObject;
    private tryPlay;
}

/**
 * Represents a rule for triggering actions based on scroll events.
 */
interface ScrollMarkRule {
    /**
     * A unique identifier for the scroll trigger rule.
     */
    id: string;
    /**
     * The offset value (in pixels) from the top of the viewport where the rule is triggered.
     */
    offset: number;
    /**
     * The direction of the scroll that activates the rule.
     * - `"forward"`: Trigger when scrolling down.
     * - `"backward"`: Trigger when scrolling up.
     * - `"any"`: Trigger regardless of scroll direction.
     */
    direction: "forward" | "backward" | "any";
    /**
     * Optional callback function to execute when the scroll position enters the trigger zone.
     */
    onEnter?: () => void;
    /**
     * Optional callback function to execute when the scroll position leaves the trigger zone.
     */
    onLeave?: () => void;
    /**
     * Optional configuration for toggling a CSS class on a target element.
     */
    toggleClass?: {
        /**
         * The target HTML element on which the class will be toggled.
         */
        target: HTMLElement;
        /**
         * The name of the CSS class to toggle.
         */
        className: string;
    };
}

/**
 * Module that manages sequence states for elements based on slider step events.
 * Updates element classes (ACTIVE, HIDE, DISABLE) according to the current sequence position.
 */
declare class StringSequence extends StringModule {
    /**
     * Stores the current active step index for each slider.
     */
    private activeStepForSlides;
    /**
     * Stores the last active step index for each slider to hide the previous element.
     */
    private hideStepForSlides;
    /**
     * @param context StringContext instance for dependency injection.
     */
    constructor(context: StringContext);
    /**
     * Subscribes to slider step events and updates element states:
     * - Sets ACTIVE for the current element.
     * - Sets HIDE for the previously active element.
     * - Sets DISABLE for all others.
     */
    onInit(): void;
    /**
     * Sets initial state DISABLE for a newly connected element.
     * @param object The connected StringObject.
     */
    onObjectConnected(object: StringObject): void;
    /**
     * Updates the element's class according to the given SequenceState.
     * Removes all possible sequence state classes before applying the new one.
     * @param object The target StringObject.
     * @param state The state to set (ACTIVE, HIDE, DISABLE).
     */
    private setSequenceState;
}

declare class StringTune {
    /** Bound handler for the scroll start event */
    private onScrollStartBind;
    /** Bound handler for the scroll stop event */
    private onScrollStopBind;
    /** Bound handler for the scroll direction change event */
    private onDirectionChangeBind;
    /** Bound wheel event handler */
    private onWheelBind;
    /** Bound scroll event handler */
    private onScrollBind;
    /** Bound resize event handler */
    private onResizeBind;
    /** Bound mouse move handler */
    private onMouseMoveBind;
    /** Singleton instance of StringTune */
    private static i;
    /** Root scrollable element (typically <body>) */
    private root;
    /** Window object (used for event bindings and dimensions) */
    private window;
    /** Previous window width for resize diff check */
    private prevWidth;
    /** Previous window height for resize diff check */
    private prevHeight;
    /** Manages all modules registered in the system */
    private moduleManager;
    /** Manages scroll modes and active scroll engine */
    private scrollManager;
    /** Manages all interactive objects (elements with `string-*` attributes) */
    private objectManager;
    /** Central event manager for internal pub-sub logic */
    private eventManager;
    /** Handles custom cursor logic (if enabled) */
    private cursorController;
    /** Provides default utility tools (parsers, interpolation, etc.) */
    private tools;
    /** Main loop used for frame updates (with fixed FPS) */
    private loop;
    /** Global reactive data store (scroll, viewport, etc.) */
    private data;
    /** Context shared across all modules (events, data, tools, settings) */
    private context;
    /**
     * Sets the scroll position manually.
     * This overrides all internal scroll states including target and lerped values.
     * Useful for programmatic jumps or syncing scroll externally.
     *
     * @param value The new scroll position in pixels.
     */
    set scrollPosition(value: number);
    /**
     * Configures the container element(s) used for scroll tracking.
     * Accepts either the `Window` object or an `HTMLElement`.
     * Determines the appropriate internal element references based on the input type
     * and triggers a resize calculation.
     *
     * @param {Window | HTMLElement | any} container The target window or HTML element to associate with scrolling.
     * Handles `Window`, `HTMLElement`, and potentially other types via fallback.
     */
    set scrollContainer(container: any);
    /**
     * Gets the current scroll position in pixels.
     * This is typically updated every frame.
     */
    get speed(): number;
    /**
     * Sets the base scroll speed for smooth scrolling.
     * Typically a value between 0 and 1.
     */
    set speed(value: number);
    /**
     * Sets the scroll acceleration using a normalized value from 0 to 1.
     * Internally maps it to a real acceleration value between 0.1 and 0.5.
     *
     * @param speed A normalized acceleration factor (0 to 1).
     */
    set speedAccelerate(speed: number);
    /**
     * Sets the scroll mode for desktop devices.
     * Can be 'smooth', 'default', or 'disable'.
     */
    set scrollDesktopMode(mode: ScrollMode);
    /**
     * Sets the scroll mode for mobile devices.
     * Can be 'smooth', 'default', or 'disable'.
     */
    set scrollMobileMode(mode: ScrollMode);
    private debouncedResize;
    private constructor();
    /**
     * Returns the singleton instance of StringTune.
     * If not already created, initializes it.
     */
    static getInstance(): StringTune;
    /**
     * Finds and returns an existing module by its class.
     * Useful for reusing a module instance without re-registering.
     *
     * @template T The type of the module to retrieve.
     * @param type The module class constructor.
     * @returns The module instance if found, otherwise undefined.
     */
    reuse<T>(type: new (...args: any[]) => T): T | undefined;
    /**
     * Instantiates and registers a new module.
     * Accepts optional per-instance settings that override global settings.
     *
     * @param objectClass The module class to instantiate.
     * @param settings Optional settings specific to this module.
     */
    use(objectClass: typeof StringModule, settings?: any): void;
    /**
     * Subscribes to a global event within the system.
     *
     * @param eventName The name of the event to listen for.
     * @param callback The function to call when the event is triggered.
     * @param id Optional subscription ID (for easier management).
     */
    on(eventName: string, callback: EventCallback<any>, id?: string): void;
    emit(eventName: string, data: any): void;
    /**
     * Unsubscribes from a global event.
     *
     * @param eventName The name of the event.
     * @param callback The previously registered callback.
     * @param id Optional ID used during subscription.
     */
    off(eventName: string, callback: EventCallback<any>, id?: string): void;
    /**
     * Adds a scroll trigger rule that activates when the user scrolls past a defined offset
     * in a specific direction. This can be used to toggle CSS classes or execute callbacks
     * when elements come into view or go out of view.
     *
     * @param rule - The scroll trigger configuration object.
     *   - `id`: A unique identifier for this rule.
     *   - `offset`: The vertical scroll offset (in pixels) where the rule should activate.
     *   - `direction`: Defines the scroll direction required to activate the rule.
     *                 Can be `"forward"`, `"backward"`, or `"any"`.
     *   - `onEnter`: (Optional) A function that will be called when the scroll position enters the trigger zone
     *                in the specified direction.
     *   - `onLeave`: (Optional) A function that will be called when the scroll position leaves the trigger zone
     *                or scrolls in the opposite direction.
     *   - `toggleClass`: (Optional) An object defining a class toggle behavior.
     *                    It contains a target element and a class name to be added when the trigger is active
     *                    and removed when it's not.
     */
    addScrollMark(rule: ScrollMarkRule): void;
    /**
     * Removes a scroll trigger by its unique identifier.
     *
     * @param id - The unique identifier of the scroll trigger to be removed.
     */
    removeScrollMark(id: string): void;
    /**
     * Starts the scroll engine and initializes all listeners, observers, and modules.
     *
     * @param fps Desired frames per second for the update loop.
     */
    start(fps: number): void;
    /**
     * Initializes all DOM elements with `string` or `string-copy-from` attributes.
     * Registers them with the object manager and triggers resize/scroll/frame hooks.
     */
    private initObjects;
    /**
     * Sets global fallback settings for all modules.
     * These can be overridden by module-specific settings during `use(...)`.
     *
     * @param settings A key-value map of default settings (e.g. 'offset-top': '-10%').
     */
    setupSettings(settings: StringSettings): void;
    /**
     * Handles mouse move event and dispatches it to cursor and modules.
     * @param e Native mouse move event.
     */
    private onMouseMoveEvent;
    /**
     * Handles wheel scroll event and passes it to the scroll engine and modules.
     * @param e Native wheel event.
     */
    private onWheelEvent;
    /**
     * Called when scrolling begins.
     * Triggers module scroll start lifecycle hook.
     */
    private onScrollStart;
    /**
     * Called when scrolling ends.
     * Triggers module scroll stop lifecycle hook.
     */
    private onScrollStop;
    /**
     * Called when scrolling ends.
     * Triggers module scroll stop lifecycle hook.
     */
    private onDirectionChange;
    /**
     * Called when global or module settings are updated.
     * Notifies all managers and modules to re-read new settings.
     */
    private onSettingsChange;
    /**
     * Handles native scroll event.
     * Prevents default behavior and triggers internal scroll logic and event emissions.
     *
     * @param e The native scroll event.
     */
    private onScrollEvent;
    /**
     * Called every frame by the update loop.
     * Triggers scroll engine, modules, and global `update` event.
     */
    private onUpdateEvent;
    /**
     * Handles resize events from scroll container or window.
     * Ignores height-only changes on mobile to prevent layout jumps.
     * Rebuilds layout and triggers module resize if size really changed.
     */
    onResize(): void;
    /**
     * Scrolls the container to the specified element identified by a CSS selector, applying an optional offset.
     *
     * Calculates the vertical position of the target element relative to the scroll container and updates the scroll delta accordingly.
     * If the element is not found, a warning is logged to the console.
     *
     * @param selector - The CSS selector string used to identify the target element.
     * @param offset - Optional. The number of pixels to offset from the target element's top position. Defaults to 0.
     */
    scrollToElement(selector: string, offset?: number): void;
    /**
     * Cleans up the system, removes all event listeners, stops the loop,
     * and destroys modules and event subscriptions.
     */
    destroy(): void;
}

export { type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringGlide, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringResponsive, StringScrollbar, StringSequence, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };