@fiddle-digital/string-tune 1.1.26 → 1.1.28

package/dist/index.d.mts

@@ -12,96 +12,16 @@ 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;
+interface ModuleLifecyclePermissionsItem {
+    rebuild: {
+        width: boolean;
+        height: boolean;
+        scrollHeight: boolean;
+    };
+}
+declare class ModuleLifecyclePermissions {
+    desktop: ModuleLifecyclePermissionsItem;
+    mobile: ModuleLifecyclePermissionsItem;
 }
 
 /**
@@ -132,6 +52,14 @@ declare class CursorState {
      * Delta step between current and target Y.
      */
     stepY: number;
+    /**
+     * Velocity in X direction, calculated from smoothed position.
+     */
+    velocityX: number;
+    /**
+     * Velocity in Y direction, calculated from smoothed position.
+     */
+    velocityY: number;
 }
 
 /**
@@ -201,6 +129,11 @@ declare class ScrollState {
     speedAccelerate: number;
 }
 
+declare class SystemState {
+    fpsTracker: boolean;
+    positionTracker: boolean;
+}
+
 /**
  * Represents the time-related state of the current and previous animation frames.
  *
@@ -255,36 +188,339 @@ declare class ViewportState {
  */
 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-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;
+    system: SystemState;
+}
+
+/**
+ * Base interface for scroll/interaction modules in the StringScroll system.
+ */
+interface IStringModule {
+    permissions: ModuleLifecyclePermissions;
+    /** 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 layout is resize width. */
+    onResizeWidth(): 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 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;
+}
+
+type MirrorEasingFn = (value: number) => number;
+/**
+ * Lightweight wrapper that mirrors a primary StringObject while keeping
+ * its own easing and state. Intended for elements linked via
+ * `[string-copy-from]`.
+ */
+declare class StringMirrorObject {
+    private parent;
+    readonly id: string;
+    readonly htmlElement: HTMLElement;
+    private properties;
+    private easingFn?;
+    constructor(id: string, element: HTMLElement, parent: StringObject);
+    get parentObject(): StringObject;
+    setProperty<T>(key: string, value: T): void;
+    getProperty<T>(key: string): T;
+    setEasing(easing: MirrorEasingFn | null | undefined): void;
+    getEasing(): MirrorEasingFn | undefined;
+    /**
+     * Returns eased progress using mirror easing (if set) or fallback.
+     */
+    applyProgress(rawProgress: number, fallback?: MirrorEasingFn): number;
+}
+
+/**
+ * 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[];
+    /**
+     * Mirror objects linked via `string-copy-from`.
+     */
+    private mirrors;
+    /**
+     * 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).
      */
-    scroll: ScrollState;
+    enter(): void;
     /**
-     * Viewport-related state object.
-     * Holds dimensions like window size, content size, aspect ratios, and more.
-     * Useful for layout calculations, unit parsing, and element positioning.
+     * Marks this object as "inactive" (usually on intersection/scroll leave).
      */
-    viewport: ViewportState;
+    leave(): void;
     /**
-     * Cursor-related state object.
-     * Tracks cursor position, velocity, movement, and derived values.
-     * Can be used for pointer interactions, proximity effects, and hover states.
+     * 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.
      */
-    cursor: CursorState;
+    remove(): void;
     /**
-     * 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.
+     * Shows the object, applies visual class and notifies connected modules.
      */
-    render: RenderState;
+    show(): void;
     /**
-    * 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;
+     * 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;
+    addMirror(mirror: StringMirrorObject): void;
+    removeMirror(id: string): void;
+    get mirrorObjects(): StringMirrorObject[];
+    get connects(): HTMLElement[];
+}
+
+declare class CenterCache {
+    private map;
+    private all;
+    attach(obj: StringObject): void;
+    detach(obj: StringObject): void;
+    invalidateAll(): void;
+    getCenter(obj: StringObject): {
+        cx: number;
+        cy: number;
+    };
+}
+
+declare class HoverTracker {
+    private active;
+    private subs;
+    track(obj: StringObject): void;
+    untrack(obj: StringObject): void;
+    isActive(obj: StringObject): boolean;
+    activeObjects(): StringObject[];
 }
 
 /**
@@ -460,7 +696,7 @@ declare class UnitParserTool implements IStringTool<UnitParserInput, number> {
     /**
      * @returns Numeric value in pixels (positive or negative).
      */
-    process({ value, element, viewportHeight, baseRem, boundingRect, }: UnitParserInput): number;
+    process({ value, element, viewportHeight, baseRem, boundingRect }: UnitParserInput): number;
 }
 
 /**
@@ -871,182 +1107,17 @@ interface StringContext {
      * Centralized event emitter and listener system.
      */
     events: EventManager;
-}
-
-interface ModuleLifecyclePermissionsItem {
-    rebuild: {
-        width: boolean;
-        height: boolean;
-        scrollHeight: boolean;
-    };
-}
-declare class ModuleLifecyclePermissions {
-    desktop: ModuleLifecyclePermissionsItem;
-    mobile: ModuleLifecyclePermissionsItem;
-}
-
-/**
- * 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 {
-    permissions: ModuleLifecyclePermissions;
-    /** 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 layout is resize width. */
-    onResizeWidth(): 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.
+     * Caches the center positions of string objects.
      */
-    enterObject(id: string, object: StringObject): void;
+    centers: CenterCache;
     /**
-     * Called when the interaction leaves the object's area.
+     * Tracks hover states of string objects.
      */
-    exitObject(id: string): void;
-    addObject(id: string, object: StringObject): void;
-    removeObject(id: string): void;
+    hover: HoverTracker;
 }
 
-type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "tuple" | "easing" | "color" | {
+type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "breakpoint-dimension" | "tuple" | "easing" | "color" | {
     type: "enum";
     values: string[];
 };
@@ -1145,6 +1216,14 @@ declare class StringModule implements IStringModule {
      * Supports custom event emitting, listening, and unsubscription.
      */
     protected events: EventManager;
+    /**
+     * Cache for storing and managing object centers.
+     */
+    protected centers: CenterCache;
+    /**
+     * Tracker for managing hover states of objects.
+     */
+    protected hover: HoverTracker;
     permissions: ModuleLifecyclePermissions;
     constructor(context: StringContext);
     /**
@@ -1242,13 +1321,18 @@ declare class StringModule implements IStringModule {
      * @param object The connected object.
      */
     onObjectConnected(object: StringObject): void;
+    /**
+     * Called when an object is disconnected. Can be overridden to clean up styles or logic.
+     * @param object The disconnected object.
+     */
+    onObjectDisconnected(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;
+    protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void, copyFn?: (el: HTMLElement, mirror?: StringMirrorObject) => void): void;
     /**
      * Cleans up internal state and detaches the module from the system.
      */
@@ -1257,6 +1341,9 @@ declare class StringModule implements IStringModule {
     onInit(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
+    onMutate(data: StringData): void;
+    onScrollMeasure(data: StringData): void;
+    onMouseMoveMeasure(data: StringData): void;
     /** Called when the window or layout is resized. */
     onResize(): void;
     /** Called when the layout is resized width. */
@@ -1297,9 +1384,10 @@ declare class StringCursor extends StringModule {
     cursor: any;
     cursorContent: any;
     overCount: number;
+    private cursorPrev;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    onFrame(data: StringData): void;
+    onMutate(data: StringData): void;
     onObjectConnected(object: StringObject): void;
     getCursorClass(object: StringObject): string | null;
     onMouseEnter(object: StringObject): void;
@@ -1310,6 +1398,15 @@ declare class StringCursor extends StringModule {
     private calculateOffset;
 }
 
+declare class StringImpulse extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    onMouseMove(_e?: MouseEvent): void;
+    private getElementsAtPoint;
+    onFrame(_: StringData): void;
+}
+
 declare class StringMagnetic extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
@@ -1317,6 +1414,38 @@ declare class StringMagnetic extends StringModule {
     onFrame(data: StringData): void;
 }
 
+declare abstract class CursorReactiveModule extends StringModule {
+    protected nearOnly: boolean;
+    protected useAllObjects: boolean;
+    protected maxDistanceMultiplier: number;
+    protected updateThreshold: number;
+    private objectDeltaData;
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    removeObject(id: string): void;
+    onScroll(): void;
+    onMouseMoveMeasure(data: StringData): void;
+    onMutate(data: StringData): void;
+    protected getCursorTargets(): StringObject[];
+    protected refreshPointerState(target?: StringObject): void;
+    private scrollUpdateScheduled;
+    protected scheduleCursorUpdate(): void;
+    protected onCursorScrollUpdate(): void;
+}
+
+declare class StringSpotlight extends CursorReactiveModule {
+    protected onCursorFrame(data: StringData, frame: number): void;
+    private updateScheduledSpotlight;
+    constructor(context: any);
+    initializeObject(id: number, obj: StringObject, el: HTMLElement, attrs: Record<string, any>): void;
+    protected onPointerDelta(obj: StringObject, dx: number, dy: number, dist: number): void;
+    onMouseMoveMeasure(data: StringData): void;
+    onMutate(data: StringData): void;
+    private ensurePointerState;
+    private updateSpotlightState;
+    protected onCursorScrollUpdate(): void;
+}
+
 /**
  * Module that handles lazy-loading of images with `string-lazy` attribute.
  * It loads the image only once, calculates its aspect-ratio to prevent layout shift,
@@ -1419,23 +1548,21 @@ declare class StringLerp extends StringModule {
     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 {
+    protected updateScheduled: boolean;
+    private static readonly PROGRESS_EPSILON;
     constructor(context: StringContext);
-    /**
-     * Called when an object is initialized.
-     */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    /**
-     * Called on scroll.
-     */
+    private recomputeProgress;
+    private applyProgressValue;
+    calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
     onObjectConnected(object: StringObject): void;
-    private setUpObject;
+    onScrollMeasure(data: StringData): void;
+    onMutate(): void;
+    private updateObjectProgress;
+    private hasProgressChanged;
+    onObjectDisconnected(object: StringObject): void;
 }
 
 /**
@@ -1445,22 +1572,20 @@ declare class StringProgress extends StringModule {
  * necessary transformations based on scroll progress and viewport size.
  */
 declare class StringParallax extends StringProgress {
+    private updateScheduledTransform;
+    private calculateParallaxForObject;
     constructor(context: StringContext);
     /**
      * Called when an object is initialized.
      */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    /**
-     * Called on scroll.
-     */
+    calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
-    /**
-     * Called on resize.
-     */
     onResize(): void;
-    private handleScrollDesktop;
-    private handleScrollMobile;
-    private scrollHandler;
+    onScrollMeasure(data: StringData): void;
+    onMutate(): void;
+    private calculateDesktopParallax;
+    private calculateMobileParallax;
 }
 
 declare class StringScrollbar extends StringModule {
@@ -1501,6 +1626,7 @@ declare class StringSplit extends StringModule {
     split(element: HTMLElement, options: ISplitOptions): {
         fragment: DocumentFragment;
         result: DocumentFragment;
+        extraProps: Map<string, string>;
     };
     /**
      * Computes a numeric value based on the provided split option, index, and total count.
@@ -1775,6 +1901,45 @@ declare class StringForm extends StringModule {
     getFieldValue(field: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): any;
 }
 
+declare class StringScroller extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+}
+
+declare class StringProgressPart extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+}
+
+type Job = () => void;
+declare class FrameDOM {
+    private measureQueue;
+    private mutateQueue;
+    private scheduled;
+    measure(fn: Job): void;
+    mutate(fn: Job): void;
+    private schedule;
+}
+declare const frameDOM: FrameDOM;
+
+type StyleValue = string | number;
+type StyleVars = Record<string, StyleValue>;
+type StyleProps = Record<string, StyleValue>;
+declare class StyleTxn {
+    private pendingVars;
+    private pendingProps;
+    private isOpen;
+    begin(): void;
+    setVars(el: Element, vars: StyleVars): void;
+    setProps(el: Element, props: StyleProps): void;
+    run(fn: () => void): void;
+    commit(): void;
+    cancel(): void;
+}
+declare const styleTxn: StyleTxn;
+
 declare class StringTune {
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
@@ -1790,6 +1955,8 @@ declare class StringTune {
     private onResizeBind;
     /** Bound mouse move handler */
     private onMouseMoveBind;
+    private onContainerTransitionEndBind;
+    private onResizeObserverBind;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -1818,6 +1985,11 @@ declare class StringTune {
     private data;
     /** Context shared across all modules (events, data, tools, settings) */
     private context;
+    /** Caches the center positions of string objects. */
+    private centers;
+    /** Tracks hover states of string objects. */
+    private hoverManager;
+    private observerContainerResize;
     /**
      * Sets the scroll position manually.
      * This overrides all internal scroll states including target and lerped values.
@@ -1840,7 +2012,7 @@ declare class StringTune {
      * Gets the current scroll position in pixels.
      * This is typically updated every frame.
      */
-    get speed(): number;
+    get scrollPosition(): number;
     /**
      * Sets the base scroll speed for smooth scrolling.
      * Typically a value between 0 and 1.
@@ -1947,6 +2119,8 @@ declare class StringTune {
      * @param settings A key-value map of default settings (e.g. 'offset-top': '-10%').
      */
     setupSettings(settings: StringSettings): void;
+    private onResizeObserverEvent;
+    private onContainerTransitionEnd;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
      * @param e Native mouse move event.
@@ -2005,6 +2179,12 @@ declare class StringTune {
      * @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;
+    scrollTo(position: number): void;
+    /**
+     * Forces center cache recalculation for all tracked objects.
+     * Useful when DOM geometry changes outside of StringTune's control.
+     */
+    invalidateCenters(): void;
     /**
      * Cleans up the system, removes all event listeners, stops the loop,
      * and destroys modules and event subscriptions.
@@ -2012,4 +2192,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringResponsive, StringScrollbar, StringSequence, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };
+export { CursorReactiveModule, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringResponsive, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };