@fiddle-digital/string-tune 1.1.48 → 1.1.50

package/dist/index.d.ts

@@ -71,7 +71,8 @@ declare class RenderState {
 }
 
 type ScrollDirection = 'vertical' | 'horizontal';
-type ScrollMode = 'smooth' | 'disable' | 'default';
+type BuiltInScrollMode = 'smooth' | 'disable' | 'default';
+type ScrollMode = BuiltInScrollMode | string;
 /**
  * Describes current scroll-related state for all calculations and modules.
  */
@@ -132,6 +133,7 @@ declare class ScrollState {
 declare class SystemState {
     fpsTracker: boolean;
     positionTracker: boolean;
+    suppressMasonryResize: boolean;
 }
 
 /**
@@ -230,6 +232,10 @@ interface IStringModule {
     destroy(): void;
     /** Called once when the module is initialized. */
     onInit(): void;
+    /** Called once when the module is registered and can subscribe to events. */
+    onSubscribe(): void;
+    /** Called once when the module is being removed and should unsubscribe. */
+    onUnsubscribe(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
     /** Called when the window or layout is resized. */
@@ -240,7 +246,7 @@ interface IStringModule {
     onDOMRebuild(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
-    /** Called when scroll change diraction. */
+    /** Called when scroll change direction. */
     onDirectionChange(): void;
     /** Called when scrolling starts (user begins scroll). */
     onScrollStart(): void;
@@ -450,6 +456,30 @@ declare class StringObject {
      * Internal key-value store of dynamic object properties (like offsets, progress, etc.).
      */
     private properties;
+    private eventNameCache;
+    private eventNameSuffixCache;
+    /**
+     * Direct properties for extremely hot, per-frame accessed metrics
+     * to avoid going through the Map and incurring overhead.
+     */
+    progress: number;
+    progressRaw: number;
+    startPosition: number;
+    differencePosition: number;
+    transformValue: {
+        transform: string;
+    } | null;
+    eventProgressName: string | null;
+    lerp: number;
+    glide: number;
+    isMagneting: boolean;
+    magneticX: number;
+    magneticY: number;
+    magneticTargetX: number;
+    magneticTargetY: number;
+    eventLerpName: string | null;
+    eventGlideName: string | null;
+    eventMagneticName: string | null;
     /**
      * Modules currently connected to this object.
      */
@@ -460,6 +490,12 @@ declare class StringObject {
      */
     events: EventManager;
     constructor(id: string, element: HTMLElement);
+    /**
+     * Returns a cached event name in one of these forms:
+     * - `${prefix}:${id}`
+     * - `${prefix}:${id}:${suffix}`
+     */
+    getScopedEventName(prefix: string, suffix?: string): string;
     /**
      * Stores a property value for this object.
      * @param key - Property name
@@ -500,7 +536,7 @@ declare class StringObject {
      * Connects a module to this object if not already connected.
      * @param module - The module to connect
      */
-    connect(module: IStringModule): void;
+    connect(module: IStringModule): boolean;
     addMirror(mirror: StringMirrorObject): void;
     removeMirror(id: string): void;
     get mirrorObjects(): StringMirrorObject[];
@@ -529,6 +565,40 @@ declare class HoverTracker {
     activeObjects(): StringObject[];
 }
 
+interface ISettingsChangeData {
+    isDesktop: boolean;
+    isForceRebuild: boolean;
+    widthChanged: boolean;
+    heightChanged: boolean;
+    scrollHeightChanged: boolean;
+}
+
+type StyleValue = string | number;
+type StyleVars = Record<string, StyleValue>;
+type StyleProps = Record<string, StyleValue>;
+declare class StyleTxn {
+    pendingVars: Map<Element, StyleVars>;
+    pendingProps: Map<Element, StyleProps>;
+    isOpen: boolean;
+    private canUseTypedOM;
+    private writeVar;
+    begin(): void;
+    setVars(el: Element, vars: StyleVars): void;
+    setVar(el: Element, key: string, value: StyleValue): void;
+    /**
+     * Directly sets a CSS custom property (variable) on an element using CSS Typed OM
+     * for improved performance. Falls back to string-based assignment if not supported.
+     * Note: This writes immediately. Use `begin()`, `setVar()`, `commit()` for batched writes.
+     */
+    setVarDirect(el: Element, key: string, value: StyleValue): void;
+    setProps(el: Element, props: StyleProps): void;
+    setProp(el: Element, key: string, value: StyleValue): void;
+    run(fn: () => void): void;
+    commit(): void;
+    cancel(): void;
+}
+declare const styleTxn: StyleTxn;
+
 /**
  * Base interface for injectable core tools in the String system.
  * Each tool takes input and returns output (transform, extract, calculate).
@@ -1062,7 +1132,8 @@ declare class ValidationTool implements IStringTool<ValidateInput, ValidationRes
 }
 
 /**
- * Interface describing all available tools used inside modules.
+ * Container holding references to all essential tools used within the library.
+ * Dependency injection.
  */
 interface StringToolsContainer {
     /** Tool for reading DOM attributes (including data-*). */
@@ -1123,38 +1194,7 @@ interface StringToolsContainer {
     transformScaleParser: TransformScaleParserTool;
     optionsParser: SplitOptionsParserTool;
     ruleParser: RuleParserTool;
-}
-
-/**
- * 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;
-    /**
-     * Caches the center positions of string objects.
-     */
-    centers: CenterCache;
-    /**
-     * Tracks hover states of string objects.
-     */
-    hover: HoverTracker;
+    styleTxn: typeof styleTxn;
 }
 
 type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "breakpoint-dimension" | "tuple" | "easing" | "color" | {
@@ -1205,6 +1245,17 @@ declare class StringModule implements IStringModule {
      * Example: ["offset-top", "offset-bottom"]
      */
     protected attributesToMap: AttributeMapping[];
+    /**
+     * Defines CSS Custom Properties (Houdini) strictly required by this module.
+     * ModuleManager will automatically register these properties on initialization
+     * for Typed Object Model hardware acceleration.
+     */
+    cssProperties: Array<{
+        name: string;
+        syntax: string;
+        initialValue: string;
+        inherits: boolean;
+    }>;
     /**
      * A map that associates string keys with `StringObject` instances.
      * This map is used to manage and track `StringObject` instances on a page.
@@ -1264,6 +1315,10 @@ declare class StringModule implements IStringModule {
      * Tracker for managing hover states of objects.
      */
     protected hover: HoverTracker;
+    /**
+     * Object manager for layout refreshes and in-view recalculation.
+     */
+    protected objectManager: ObjectManager;
     permissions: ModuleLifecyclePermissions;
     constructor(context: StringContext);
     /**
@@ -1373,12 +1428,36 @@ declare class StringModule implements IStringModule {
      * @param applyFn The function that receives an HTMLElement and performs any update.
      */
     protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void, copyFn?: (el: HTMLElement, mirror?: StringMirrorObject) => void): void;
+    /**
+     * Directly applies a CSS variable to the object's element without closures.
+     */
+    protected applyVarToElement(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a standard CSS property to the object's element without closures.
+     */
+    protected applyPropToElement(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a CSS variable to all connected mirrors without closures.
+     */
+    protected applyVarToConnects(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a standard CSS property to all connected mirrors without closures.
+     */
+    protected applyPropToConnects(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Returns a cached per-object event name to avoid building strings in hot paths.
+     */
+    protected getObjectEventName(object: StringObject, prefix: string, suffix?: string): string;
     /**
      * Cleans up internal state and detaches the module from the system.
      */
     destroy(): void;
     /** Called once when the module is initialized. */
     onInit(): void;
+    /** Called once when the module is registered and can subscribe to events. */
+    onSubscribe(): void;
+    /** Called once when the module is being removed and should unsubscribe. */
+    onUnsubscribe(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
     onMutate(data: StringData): void;
@@ -1390,7 +1469,7 @@ declare class StringModule implements IStringModule {
     onResizeWidth(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
-    /** Called when user changed scroll diraction. */
+    /** Called when user changed scroll direction. */
     onDirectionChange(): void;
     /** Called when user starts scrolling. */
     onScrollStart(): void;
@@ -1418,6 +1497,183 @@ declare class StringModule implements IStringModule {
     onDOMMutate(added: NodeList, removed: NodeList): void;
 }
 
+declare class ModuleManager {
+    private data;
+    private modules;
+    private uiModules;
+    private allModules;
+    constructor(data: StringData);
+    register(module: StringModule): void;
+    find<T>(type: new (...args: any[]) => T): T | undefined;
+    onInit(): void;
+    onFrame(): void;
+    onMutate(): void;
+    onScrollMeasure(): void;
+    onMouseMoveMeasure(): void;
+    onScroll(): void;
+    onResizeWidth(): void;
+    onResize(): void;
+    onMouseMove(e: MouseEvent): void;
+    onWheel(e: WheelEvent): void;
+    onDirectionChange(): void;
+    onScrollStart(): void;
+    onScrollStop(): void;
+    onAxisChange(): void;
+    onDeviceChange(): void;
+    onScrollConfigChange(): void;
+    onSettingsChange(_data: ISettingsChangeData): void;
+    onDOMMutate(added: NodeList, removed: NodeList): void;
+    destroy(): void;
+    get all(): IStringModule[];
+    get core(): IStringModule[];
+    get ui(): IStringModule[];
+    private callAll;
+    private callLifecycleStrict;
+    private rebuildAllModules;
+}
+
+declare class ObjectManager {
+    private data;
+    private modules;
+    private events;
+    private tools;
+    private objects;
+    private connectQueue;
+    private connectableModulesBuffer;
+    private mirrors;
+    private mirrorId;
+    private globalId;
+    private domBatcher;
+    private domBatcherEnabled;
+    private inviewStarts;
+    private inviewEnds;
+    private inviewActive;
+    private inviewStartIdx;
+    private inviewEndIdx;
+    private inviewIndexDirty;
+    private lastInviewScrollPos;
+    private intersectionObserverEnabled;
+    private domObserver;
+    constructor(data: StringData, modules: ModuleManager, events: EventManager, tools: StringToolsContainer);
+    /**
+     * Returns the object map (read-only).
+     */
+    get all(): ReadonlyMap<string, StringObject>;
+    /**
+     * Adds a new object from an element.
+     */
+    add(el: HTMLElement): void;
+    setDOMBatcherEnabled(enabled: boolean): void;
+    setIntersectionObserverEnabled(enabled: boolean): void;
+    invalidateInviewIndex(): void;
+    refreshLayoutForRoot(root: HTMLElement): void;
+    /**
+     * Removes an object by its id.
+     */
+    remove(id: string): void;
+    /**
+     * Add an element that will connect later.
+     */
+    enqueueConnection(id: string, element: HTMLElement): void;
+    linkMirror(id: string, element: HTMLElement): void;
+    private attachMirrorToObject;
+    private detachMirrorByElement;
+    private detachMirrorById;
+    private getMirrorIds;
+    private setMirrorIds;
+    private clearMirrorIds;
+    /**
+     * Retrieves all attributes of a given HTML element and returns them as a record.
+     *
+     * @param el - The HTML element from which to extract attributes.
+     * @returns A record where the keys are attribute names and the values are attribute values.
+     */
+    private getAllAttributes;
+    /**
+     * Initializes IntersectionObservers for a given object and its associated HTML element.
+     *
+     * This method sets up observer:
+     * - A "progress" observer to track when the object enters or leaves the viewport.
+     *
+     * The observers are configured with custom root margins and thresholds based on the object's properties.
+     * Existing observers, if any, are disconnected before creating new ones.
+     *
+     * @param obj - The `StringObject` instance containing properties and methods for interaction.
+     * @param el - The `HTMLElement` to observe for intersection changes.
+     */
+    private initObservers;
+    /**
+     * Observes DOM mutations to auto-add/remove elements with [string] attribute.
+     * Should be called once after DOM is ready.
+     */
+    observeDOM(): void;
+    /**
+     * Removes an object and its observers.
+     */
+    private handleRemoved;
+    /**
+     * Re-applies module initialization logic to all managed objects after settings change.
+     *
+     * This method should be called when `StringSettings` are updated at runtime,
+     * especially if the new settings affect how modules calculate offsets,
+     * easing, origins, or custom configuration.
+     *
+     * Internally, it re-runs `initializeObject`, `calculatePositions`, and `connectObject`
+     * for each core module that can connect to the object.
+     *
+     * This is useful for supporting dynamic configuration updates without requiring
+     * a full DOM rebuild or reinitialization.
+     */
+    onSettingsChange(data: ISettingsChangeData): void;
+    /**
+     * Checks whether the element is marked as fixed (not managed).
+     */
+    private isFixed;
+    checkInview(): void;
+    private checkInviewForObject;
+    private updateInviewWindow;
+    private rebuildInviewIndex;
+    private upperBound;
+    private splitPipeAndTrim;
+    destroy(): void;
+}
+
+/**
+ * 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;
+    /**
+     * Caches the center positions of string objects.
+     */
+    centers: CenterCache;
+    /**
+     * Tracks hover states of string objects.
+     */
+    hover: HoverTracker;
+    /**
+     * Manages all interactive objects (elements with `string-*` attributes).
+     */
+    objectManager: ObjectManager;
+}
+
 /**
  * StringCursor Module
  *
@@ -1475,6 +1731,7 @@ declare class StringCursor extends StringModule {
     private bindGlobalLifecycleListeners;
     private unbindGlobalLifecycleListeners;
     private setMouseCoordinates;
+    private writePortalVars;
     private parseCursorVars;
     private getFrameAdjustedLerp;
     private getObjectDimensions;
@@ -1504,6 +1761,28 @@ declare class StringImpulse extends StringModule {
      */
     private getRotationOriginFromRect;
     onFrame(_: StringData): void;
+    onMutate(): void;
+}
+
+declare class StringMasonry extends StringModule {
+    private states;
+    constructor(context: StringContext);
+    private parseEasing;
+    onObjectConnected(object: StringObject): void;
+    onFrame(data: StringData): void;
+    onResize(): void;
+    cleanupObject(object: StringObject): void;
+    private createState;
+    private handleAnimationEnd;
+    private scheduleLayout;
+    /**
+     * Performs the layout calculation and application synchronously.
+     * Optimizes for batched DOM reads and writes via `styleTxn`.
+     */
+    private performSyncLayout;
+    private getGridSettings;
+    private attachImgLoaders;
+    private cleanupImgListeners;
 }
 
 declare class StringMagnetic extends StringModule {
@@ -1511,6 +1790,7 @@ declare class StringMagnetic extends StringModule {
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     onMouseMove(e: MouseEvent): void;
     onFrame(data: StringData): void;
+    onMutate(): void;
 }
 
 declare abstract class CursorReactiveModule extends StringModule {
@@ -1533,11 +1813,13 @@ declare abstract class CursorReactiveModule extends StringModule {
 }
 
 declare class StringSpotlight extends CursorReactiveModule {
+    private readonly stepResult;
     constructor(context: any);
     initializeObject(id: number, obj: StringObject, el: HTMLElement, attrs: Record<string, any>): void;
     onMutate(data: StringData): void;
     protected onCursorScrollUpdate(): void;
     private updateSpotlightState;
+    private writeSpotlightVars;
 }
 
 declare class StringLazy extends StringModule {
@@ -1610,6 +1892,7 @@ declare class StringGlide extends StringModule {
     private negativeVelocityMultiplier;
     private maxDisplacementValue;
     constructor(context: StringContext);
+    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private setupItem;
     private onUpdateDesktopEvent;
     private onUpdateMobileEvent;
@@ -1621,6 +1904,9 @@ declare class StringGlide extends StringModule {
     onScrollStart(): void;
     onScrollStop(): void;
     onFrame(data: StringData): void;
+    onMutate(): void;
+    private applyPendingGlideStyles;
+    private flushPendingGlideStyles;
 }
 
 /**
@@ -1666,9 +1952,15 @@ declare class StringLerp extends StringModule {
 
 declare class StringProgress extends StringModule {
     protected updateScheduled: boolean;
+    private batchStarts;
+    private batchDiffs;
+    private batchOut;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    private sanitizeRawProgress;
+    private applyRawProgress;
     private recomputeProgress;
+    private ensureBatchCapacity;
     calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
     onObjectConnected(object: StringObject): void;
@@ -1713,6 +2005,7 @@ declare class StringScrollbar extends StringModule {
     private scrollbarState;
     private scrollbarStateHorizontal;
     private scrollbarStateVertical;
+    private requestScrollTo;
     constructor(context: StringContext);
     destructor(): void;
     onInit(): void;
@@ -2031,6 +2324,11 @@ interface ScrollMarkRule {
          */
         className: string;
     };
+    /**
+     * Internal state tracking whether the rule is currently active.
+     * prevents redundant callbacks and class toggles.
+     */
+    isActive?: boolean;
 }
 
 declare class StringSequence extends StringModule {
@@ -2121,6 +2419,95 @@ declare class StringScroller extends StringModule {
     onObjectDisconnected(object: StringObject): void;
 }
 
+/**
+ * Module that provides smooth scrolling behavior for isolated containers.
+ * Allows nested elements to have independent smooth scroll physics similar to the main window.
+ *
+ * Usage:
+ * Add `string="scroll-container"` to any block element.
+ * Optional: `string-lerp="0.1"` to controls the smoothing factor.
+ */
+declare class StringScrollContainer extends StringModule {
+    /**
+     * WeakMap storing the state for each managed HTMLElement.
+     */
+    private states;
+    /**
+     * Initializes the StringScrollContainer module.
+     * Registers the `lerp` attribute configuration.
+     *
+     * @param context The shared StringTune context.
+     */
+    constructor(context: StringContext);
+    /**
+     * Called when a new object with `string="scroll-container"` is initialized.
+     * Sets up initial state, event listeners, and default styles.
+     *
+     * @param object The StringObject instance being connected.
+     */
+    onObjectConnected(object: StringObject): void;
+    /**
+     * Called when an object is removed from the DOM or disconnected.
+     * Cleans up the state associated with the element.
+     *
+     * @param object The StringObject instance being disconnected.
+     */
+    onObjectDisconnected(object: StringObject): void;
+    /**
+     * Main animation loop for the module.
+     * Updates the scroll position of active containers based on their target state.
+     *
+     * @param data Global frame data including time deltas.
+     */
+    onFrame(data: StringData): void;
+    /**
+     * Called when the window or layout is resized.
+     * Recalculates scroll boundaries for all managed containers.
+     */
+    onResize(): void;
+    /**
+     * Recalculates the maximum scrollable distance for a container.
+     *
+     * @param el The scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private measure;
+    /**
+     * Handles the mouse wheel event to apply custom scroll physics.
+     * Intercepts the event to prevent native scrolling and updates the target position.
+     * Allows event propagation if scrolling past the boundaries (scroll chaining).
+     *
+     * @param e The WheelEvent triggered by the user.
+     * @param el The target scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private handleWheel;
+    /**
+     * Placeholder for global wheel handler if needed by generic StringModule interface.
+     * Specific handling is done via local event listeners in `handleWheel`.
+     *
+     * @param e Global WheelEvent.
+     */
+    onWheel(e: WheelEvent): void;
+    /**
+     * Handles native scroll events (dragbars, keyboard, touch).
+     * Syncs the internal state with the native scroll position if the custom animation is not active.
+     *
+     * @param e The Scroll event.
+     * @param el The target scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private onNativeScroll;
+    /**
+     * Updates the element's scrollTop property by interpolating towards the target.
+     * Stops the animation if the difference is negligible.
+     *
+     * @param el The scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private updateScroll;
+}
+
 declare class StringProgressPart extends StringModule {
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
@@ -2134,25 +2521,120 @@ declare class FrameDOM {
     private scheduled;
     measure(fn: Job): void;
     mutate(fn: Job): void;
-    private schedule;
+    schedule(): void;
+    flush(): void;
 }
 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 class StringRandom extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+}
+
+/**
+ * Base class for managing scroll behavior in the system.
+ * Handles abstract scroll state and updates, intended for extension.
+ */
+declare class ScrollController {
+    /** Shared context containing data and tools */
+    protected context: StringContext;
+    /** Reference to the document object */
+    protected document: Document;
+    /** Name of the scroll mode (e.g. 'default', 'smooth', etc.) */
+    name: string;
+    /** Whether the system is in programmatic scroll mode */
+    isProg: boolean;
+    /** Whether parallax-related logic should be active */
+    isParallaxEnabled: boolean;
+    /** Scroll direction: vertical or horizontal */
+    protected _scrollDirection: "vertical" | "horizontal";
+    /**
+     * Current scroll direction.
+     * - `true` — scrolling down
+     * - `false` — scrolling up
+     * - `null` — unknown (initial state)
+     */
+    protected isBottomScrollDirection: boolean | null;
+    protected isLastBottomScrollDirection: boolean;
+    protected scrollTriggerRules: Array<ScrollMarkRule>;
+    /** Tracks whether this controller is currently active */
+    protected isActive: boolean;
+    /** Last direction applied to DOM classes (for global-class toggles) */
+    protected lastAppliedDirection: boolean | null;
+    /**
+     * Sets scroll direction and updates internal scroll logic.
+     * @param scrollDirection Either 'vertical' or 'horizontal'.
+     */
+    set scrollDirection(scrollDirection: "vertical" | "horizontal");
+    /**
+     * Creates a new ScrollController instance.
+     * @param context Shared context containing data and settings.
+     */
+    constructor(context: StringContext);
+    /**
+     * Called when scroll direction changes (up ↔ down).
+     * Override this callback in subclasses or instances.
+     */
+    onChangeDirection: () => void;
+    /**
+     * Called when scroll starts (user input).
+     * Override this callback in subclasses or instances.
+     */
+    onScrollStart: () => void;
+    /**
+     * Called when scroll ends.
+     * Override this callback in subclasses or instances.
+     */
+    onScrollStop: () => void;
+    /**
+     * Scroll-to function called on each frame.
+     * This will be reassigned depending on scroll direction.
+     */
+    onCalcUpdate: () => void;
+    /**
+     * Called every animation frame.
+     * Intended to be overridden in subclasses.
+     */
+    onFrame(): void;
+    /**
+     * Called when wheel event is fired.
+     * Override to implement custom scroll interaction.
+     * @param e Wheel event.
+     */
+    onWheel(e: any): void;
+    /**
+     * Called when native scroll event is fired.
+     * Override to track native scroll position.
+     * @param e Scroll event.
+     */
+    onScroll(e: any): void;
+    disableScrollEvents(): void;
+    enableScrollEvents(): void;
+    /**
+     * Called when this controller becomes the active scroll engine.
+     * Ensures event bindings are attached only once.
+     */
+    activate(): void;
+    /**
+     * Called when this controller is deactivated.
+     * Ensures event bindings are detached only once.
+     */
+    deactivate(): void;
+    /**
+     * Allows controllers to clean up resources on global destroy.
+     */
+    destroy(): void;
+    /**
+     * Updates scroll direction state, emits events, and toggles global classes.
+     * Intended for reuse by custom scroll adapters.
+     */
+    protected updateScrollDirection(newDirection: boolean): void;
+    protected clearScrollingClasses(): void;
+    protected triggerScrollRules(): void;
+    addScrollMark(rule: ScrollMarkRule): void;
+    removeScrollMark(id: string): void;
+    scrollTo(position: number, immediate?: boolean): void;
 }
-declare const styleTxn: StyleTxn;
 
 interface ModuleBatchContext {
     module: StringModule;
@@ -2200,10 +2682,16 @@ declare class StringTune {
     private onResizeBind;
     /** Bound mouse move handler */
     private onMouseMoveBind;
+    /** Bound scroll to handler */
+    private onScrollToBind;
+    private onDOMChangedBind;
     private onContainerTransitionEndBind;
     private onResizeObserverBind;
     private pendingScroll;
     private lastScrollEmitted;
+    private observerContainerMutation;
+    private pendingResizeRaf;
+    private pendingResizeForce;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -2313,6 +2801,19 @@ declare class StringTune {
      * @param settings Optional settings specific to this module.
      */
     use(objectClass: typeof StringModule, settings?: any): void;
+    /**
+     * Registers a new scroll mode (provider) to the system.
+     * Allows integrating custom scroll implementations (e.g. Lenis, Locomotive).
+     *
+     * @param name The unique name for this scroll mode (e.g. 'smooth', 'lenis').
+     * @param factory A function that receives the StringContext and returns a ScrollController instance, OR a ScrollController class constructor.
+     *
+     * Example:
+     * ```ts
+     * stringTune.registerScrollMode("custom", (context) => new CustomAdapter(context));
+     * ```
+     */
+    registerScrollMode(name: string, factory: ((context: StringContext) => ScrollController) | (new (context: StringContext) => ScrollController)): void;
     /**
      * Subscribes to a global event within the system.
      *
@@ -2375,6 +2876,9 @@ declare class StringTune {
     setupSettings(settings: StringSettings): void;
     private onResizeObserverEvent;
     private onContainerTransitionEnd;
+    private onDOMChanged;
+    private observeContainerMutations;
+    private queueResize;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
      * @param e Native mouse move event.
@@ -2423,28 +2927,12 @@ declare class StringTune {
      * Rebuilds layout and triggers module resize if size really changed.
      */
     onResize(force?: boolean): 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;
-    scrollTo(position: number): void;
     invalidateCenter(id: string): 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.
-     */
+    scrollTo(value: number | {
+        position: number;
+        immediate?: boolean;
+    }): void;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, 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 };
+export { CursorReactiveModule, DOMBatcher, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };