@fiddle-digital/string-tune 1.1.28 → 1.1.29

package/dist/index.d.mts

@@ -1378,6 +1378,21 @@ declare class StringModule implements IStringModule {
     onDOMMutate(added: NodeList, removed: NodeList): void;
 }
 
+/**
+ * StringCursor Module
+ *
+ * Handles cursor tracking and hover states for StringTune objects.
+ *
+ * Safari Navigation Fix:
+ * Safari has an issue where mouseleave events are not fired when navigation occurs
+ * (especially with NuxtLink/router navigation). This module includes several
+ * workarounds to ensure proper cleanup:
+ *
+ * 1. MutationObserver - detects when elements are removed from DOM
+ * 2. beforeunload/pagehide - captures traditional navigation
+ * 3. visibilitychange - captures modern SPA navigation
+ * 4. DOM existence checks - prevents operations on removed elements
+ */
 declare class StringCursor extends StringModule {
     protected enterObjectsMap: Map<string, StringObject>;
     protected enterObjects: Array<StringObject>;
@@ -1394,6 +1409,9 @@ declare class StringCursor extends StringModule {
     onMouseLeave(object: StringObject): void;
     private onEnterObject;
     private onLeaveObject;
+    private safariNavigationCleanup;
+    private onElementRemovedFromDOM;
+    onObjectDisconnected(object: StringObject): void;
     private setMouseCoordinates;
     private calculateOffset;
 }
@@ -1448,17 +1466,23 @@ declare class StringSpotlight extends CursorReactiveModule {
 
 /**
  * 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,
- * and then displays it.
+ * Aspect ratios are precomputed before the real source is revealed in view.
  */
 declare class StringLazy extends StringModule {
     private isStartLoaded;
     private loadingCount;
+    private imageStates;
     constructor(context: StringContext);
     onInit(): void;
     onObjectConnected(object: StringObject): void;
-    private loadImage;
-    private handleLoadingCompletion;
+    onObjectDisconnected(object: StringObject): void;
+    private ensureState;
+    private readSource;
+    private prepareAspectRatio;
+    private loadIntrinsicSize;
+    private handleInView;
+    private maybeActivateImage;
+    private activateImage;
 }
 
 /**
@@ -1990,6 +2014,7 @@ declare class StringTune {
     /** Tracks hover states of string objects. */
     private hoverManager;
     private observerContainerResize;
+    canRebuild: boolean;
     /**
      * Sets the scroll position manually.
      * This overrides all internal scroll states including target and lerped values.
@@ -2013,6 +2038,8 @@ declare class StringTune {
      * This is typically updated every frame.
      */
     get scrollPosition(): number;
+    get scrollHeight(): number;
+    get containerHeight(): number;
     /**
      * Sets the base scroll speed for smooth scrolling.
      * Typically a value between 0 and 1.

package/dist/index.d.ts

@@ -1378,6 +1378,21 @@ declare class StringModule implements IStringModule {
     onDOMMutate(added: NodeList, removed: NodeList): void;
 }
 
+/**
+ * StringCursor Module
+ *
+ * Handles cursor tracking and hover states for StringTune objects.
+ *
+ * Safari Navigation Fix:
+ * Safari has an issue where mouseleave events are not fired when navigation occurs
+ * (especially with NuxtLink/router navigation). This module includes several
+ * workarounds to ensure proper cleanup:
+ *
+ * 1. MutationObserver - detects when elements are removed from DOM
+ * 2. beforeunload/pagehide - captures traditional navigation
+ * 3. visibilitychange - captures modern SPA navigation
+ * 4. DOM existence checks - prevents operations on removed elements
+ */
 declare class StringCursor extends StringModule {
     protected enterObjectsMap: Map<string, StringObject>;
     protected enterObjects: Array<StringObject>;
@@ -1394,6 +1409,9 @@ declare class StringCursor extends StringModule {
     onMouseLeave(object: StringObject): void;
     private onEnterObject;
     private onLeaveObject;
+    private safariNavigationCleanup;
+    private onElementRemovedFromDOM;
+    onObjectDisconnected(object: StringObject): void;
     private setMouseCoordinates;
     private calculateOffset;
 }
@@ -1448,17 +1466,23 @@ declare class StringSpotlight extends CursorReactiveModule {
 
 /**
  * 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,
- * and then displays it.
+ * Aspect ratios are precomputed before the real source is revealed in view.
  */
 declare class StringLazy extends StringModule {
     private isStartLoaded;
     private loadingCount;
+    private imageStates;
     constructor(context: StringContext);
     onInit(): void;
     onObjectConnected(object: StringObject): void;
-    private loadImage;
-    private handleLoadingCompletion;
+    onObjectDisconnected(object: StringObject): void;
+    private ensureState;
+    private readSource;
+    private prepareAspectRatio;
+    private loadIntrinsicSize;
+    private handleInView;
+    private maybeActivateImage;
+    private activateImage;
 }
 
 /**
@@ -1990,6 +2014,7 @@ declare class StringTune {
     /** Tracks hover states of string objects. */
     private hoverManager;
     private observerContainerResize;
+    canRebuild: boolean;
     /**
      * Sets the scroll position manually.
      * This overrides all internal scroll states including target and lerped values.
@@ -2013,6 +2038,8 @@ declare class StringTune {
      * This is typically updated every frame.
      */
     get scrollPosition(): number;
+    get scrollHeight(): number;
+    get containerHeight(): number;
     /**
      * Sets the base scroll speed for smooth scrolling.
      * Typically a value between 0 and 1.