@fiddle-digital/string-tune 1.1.46 → 1.1.47

package/dist/index.d.mts

@@ -315,6 +315,11 @@ declare class EventManager {
     private stateEvents;
     private lastPayloads;
     constructor();
+    /**
+     * Marks an event as stateful so the last payload is cached and replayed to new listeners.
+     * Optionally seeds the initial payload.
+     */
+    registerStateEvent(eventName: string, initialPayload?: any): void;
     /**
      * Subscribes to an event.
      * Optionally appends an `id` to the event name for namespacing.
@@ -1462,6 +1467,7 @@ declare class StringCursor extends StringModule {
     private lastFrameTime;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    onResize(): void;
     onMutate(data: StringData): void;
     onObjectConnected(object: StringObject): void;
     getCursorClass(object: StringObject): string | null;
@@ -1491,6 +1497,7 @@ declare class StringCursor extends StringModule {
     private bindGlobalLifecycleListeners;
     private unbindGlobalLifecycleListeners;
     private setMouseCoordinates;
+    private parseCursorVars;
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
@@ -1643,7 +1650,16 @@ declare class StringGlide extends StringModule {
  * based on current scroll velocity.
  */
 declare class StringLerp extends StringModule {
+    private hasInitializedCSS;
     constructor(context: StringContext);
+    /**
+     * Initialize lerp value when object connects.
+     */
+    onObjectConnected(object: StringObject): void;
+    /**
+     * Called on resize - use this to apply initial values after mirrors are created.
+     */
+    onResize(): void;
     /**
      * Resets the `--lerp` value to 0 when scroll stops.
      */
@@ -1653,9 +1669,21 @@ declare class StringLerp extends StringModule {
      */
     onFrame(data: StringData): void;
     /**
-     * Sets the `--lerp` CSS variable on the object.
+     * Computes the lerp value for the object.
+     */
+    private recomputeLerp;
+    /**
+     * Applies the lerp value to the object and its mirrors.
      */
-    private setLerpValue;
+    onMutate(): void;
+    /**
+     * Updates the CSS variable on the object and connected elements.
+     */
+    private updateObjectLerp;
+    /**
+     * Cleans up the CSS variable when object is disconnected.
+     */
+    onObjectDisconnected(object: StringObject): void;
 }
 
 declare class StringProgress extends StringModule {
@@ -2034,6 +2062,8 @@ declare class StringSequence extends StringModule {
     private elementIndex;
     private triggerElements;
     private globalSettings;
+    private stateRegistered;
+    private lastEnteredStep;
     private defaultDuration;
     private initialized;
     private static readonly ALL_STATES;
@@ -2047,6 +2077,7 @@ declare class StringSequence extends StringModule {
     private tryApplyPendingActiveStep;
     canConnect(object: StringObject): boolean;
     onObjectConnected(object: StringObject): void;
+    private ensureStateEventRegistered;
     private parseTriggerKey;
     private getMaxStep;
     private resolveDuration;
@@ -2064,6 +2095,12 @@ declare class StringSequence extends StringModule {
     private setStepState;
     private setState;
     onFrame(data: StringData): void;
+    private emitTransitionStart;
+    private emitTransitionProgress;
+    private emitTransitionEnd;
+    private emitStepEnter;
+    private emitStepLeave;
+    private emitActiveState;
 }
 
 type FormField = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
@@ -2139,6 +2176,37 @@ declare class StyleTxn {
 }
 declare const styleTxn: StyleTxn;
 
+interface ModuleBatchContext {
+    module: StringModule;
+    object: StringObject;
+    element: HTMLElement;
+    attributes: Record<string, any>;
+    globalId: number;
+    windowSize: number;
+}
+declare class DOMBatcher {
+    private readQueue;
+    private writeQueue;
+    private computeQueue;
+    private isProcessing;
+    private pendingFrame;
+    private rectCache;
+    private dimensionCache;
+    scheduleRead(task: () => void, priority?: number): void;
+    scheduleCompute(task: () => void, priority?: number): void;
+    scheduleWrite(task: () => void, priority?: number): void;
+    batchModuleInitialization(contexts: ModuleBatchContext[]): void;
+    getCachedRect(element: HTMLElement): DOMRect | undefined;
+    getCachedDimensions(element: HTMLElement): {
+        width: number;
+        height: number;
+    } | undefined;
+    private scheduleFlush;
+    private flush;
+    flushSync(): void;
+    clear(): void;
+}
+
 declare class StringTune {
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
@@ -2156,6 +2224,8 @@ declare class StringTune {
     private onMouseMoveBind;
     private onContainerTransitionEndBind;
     private onResizeObserverBind;
+    private pendingScroll;
+    private lastScrollEmitted;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -2239,6 +2309,8 @@ declare class StringTune {
     set scrollMobileMode(mode: ScrollMode);
     set FPSTrackerVisible(visible: boolean);
     set PositionTrackerVisible(visible: boolean);
+    set domBatcherEnabled(enabled: boolean);
+    set intersectionObserverEnabled(enabled: boolean);
     private debouncedResize;
     private constructor();
     /**
@@ -2397,4 +2469,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-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 };
+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 };

package/dist/index.d.ts

@@ -315,6 +315,11 @@ declare class EventManager {
     private stateEvents;
     private lastPayloads;
     constructor();
+    /**
+     * Marks an event as stateful so the last payload is cached and replayed to new listeners.
+     * Optionally seeds the initial payload.
+     */
+    registerStateEvent(eventName: string, initialPayload?: any): void;
     /**
      * Subscribes to an event.
      * Optionally appends an `id` to the event name for namespacing.
@@ -1462,6 +1467,7 @@ declare class StringCursor extends StringModule {
     private lastFrameTime;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    onResize(): void;
     onMutate(data: StringData): void;
     onObjectConnected(object: StringObject): void;
     getCursorClass(object: StringObject): string | null;
@@ -1491,6 +1497,7 @@ declare class StringCursor extends StringModule {
     private bindGlobalLifecycleListeners;
     private unbindGlobalLifecycleListeners;
     private setMouseCoordinates;
+    private parseCursorVars;
     private getFrameAdjustedLerp;
     private getObjectDimensions;
     private calculateOffset;
@@ -1643,7 +1650,16 @@ declare class StringGlide extends StringModule {
  * based on current scroll velocity.
  */
 declare class StringLerp extends StringModule {
+    private hasInitializedCSS;
     constructor(context: StringContext);
+    /**
+     * Initialize lerp value when object connects.
+     */
+    onObjectConnected(object: StringObject): void;
+    /**
+     * Called on resize - use this to apply initial values after mirrors are created.
+     */
+    onResize(): void;
     /**
      * Resets the `--lerp` value to 0 when scroll stops.
      */
@@ -1653,9 +1669,21 @@ declare class StringLerp extends StringModule {
      */
     onFrame(data: StringData): void;
     /**
-     * Sets the `--lerp` CSS variable on the object.
+     * Computes the lerp value for the object.
+     */
+    private recomputeLerp;
+    /**
+     * Applies the lerp value to the object and its mirrors.
      */
-    private setLerpValue;
+    onMutate(): void;
+    /**
+     * Updates the CSS variable on the object and connected elements.
+     */
+    private updateObjectLerp;
+    /**
+     * Cleans up the CSS variable when object is disconnected.
+     */
+    onObjectDisconnected(object: StringObject): void;
 }
 
 declare class StringProgress extends StringModule {
@@ -2034,6 +2062,8 @@ declare class StringSequence extends StringModule {
     private elementIndex;
     private triggerElements;
     private globalSettings;
+    private stateRegistered;
+    private lastEnteredStep;
     private defaultDuration;
     private initialized;
     private static readonly ALL_STATES;
@@ -2047,6 +2077,7 @@ declare class StringSequence extends StringModule {
     private tryApplyPendingActiveStep;
     canConnect(object: StringObject): boolean;
     onObjectConnected(object: StringObject): void;
+    private ensureStateEventRegistered;
     private parseTriggerKey;
     private getMaxStep;
     private resolveDuration;
@@ -2064,6 +2095,12 @@ declare class StringSequence extends StringModule {
     private setStepState;
     private setState;
     onFrame(data: StringData): void;
+    private emitTransitionStart;
+    private emitTransitionProgress;
+    private emitTransitionEnd;
+    private emitStepEnter;
+    private emitStepLeave;
+    private emitActiveState;
 }
 
 type FormField = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
@@ -2139,6 +2176,37 @@ declare class StyleTxn {
 }
 declare const styleTxn: StyleTxn;
 
+interface ModuleBatchContext {
+    module: StringModule;
+    object: StringObject;
+    element: HTMLElement;
+    attributes: Record<string, any>;
+    globalId: number;
+    windowSize: number;
+}
+declare class DOMBatcher {
+    private readQueue;
+    private writeQueue;
+    private computeQueue;
+    private isProcessing;
+    private pendingFrame;
+    private rectCache;
+    private dimensionCache;
+    scheduleRead(task: () => void, priority?: number): void;
+    scheduleCompute(task: () => void, priority?: number): void;
+    scheduleWrite(task: () => void, priority?: number): void;
+    batchModuleInitialization(contexts: ModuleBatchContext[]): void;
+    getCachedRect(element: HTMLElement): DOMRect | undefined;
+    getCachedDimensions(element: HTMLElement): {
+        width: number;
+        height: number;
+    } | undefined;
+    private scheduleFlush;
+    private flush;
+    flushSync(): void;
+    clear(): void;
+}
+
 declare class StringTune {
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
@@ -2156,6 +2224,8 @@ declare class StringTune {
     private onMouseMoveBind;
     private onContainerTransitionEndBind;
     private onResizeObserverBind;
+    private pendingScroll;
+    private lastScrollEmitted;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -2239,6 +2309,8 @@ declare class StringTune {
     set scrollMobileMode(mode: ScrollMode);
     set FPSTrackerVisible(visible: boolean);
     set PositionTrackerVisible(visible: boolean);
+    set domBatcherEnabled(enabled: boolean);
+    set intersectionObserverEnabled(enabled: boolean);
     private debouncedResize;
     private constructor();
     /**
@@ -2397,4 +2469,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-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 };
+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 };