@fiddle-digital/string-tune 1.1.41-fix.1 → 1.1.42

package/dist/index.d.mts

@@ -737,15 +737,50 @@ interface OriginInput {
     /** Raw origin string, e.g. `'center'` or `'random(top, bottom)'`. */
     value: string;
 }
+/**
+ * Input for parsing origin to normalized coordinates.
+ * Supports formats like `'left top'`, `'center center'`, `'50% 50%'`, `'35% 76%'`.
+ */
+interface OriginToNormalizedInput {
+    /** Raw origin string, e.g. `'left top'`, `'center'`, `'50% 25%'`. */
+    value: string;
+}
+/**
+ * Output: normalized origin coordinates (0-1 range).
+ */
+interface NormalizedOrigin {
+    /** Normalized X coordinate (0 = left, 0.5 = center, 1 = right). */
+    x: number;
+    /** Normalized Y coordinate (0 = top, 0.5 = center, 1 = bottom). */
+    y: number;
+}
 /**
  * Tool that parses origin strings.
  * Allows static values like `'center'`, or expressions like `'random(...)'` to select one randomly.
+ * Also provides `toNormalized()` method to convert origin strings to `{ x, y }` coordinates.
  */
 declare class OriginParserTool implements IStringTool<OriginInput, string> {
     /**
      * @returns Parsed string value (static or randomly chosen).
      */
     process({ value }: OriginInput): string;
+    /**
+     * Parses an origin string to normalized `{ x, y }` coordinates (0-1 range).
+     *
+     * Supported formats:
+     * - Single keyword: `'center'`, `'top'`, `'left'`, etc.
+     * - Two keywords: `'left top'`, `'right bottom'`, `'center center'`
+     * - Percentages: `'50% 50%'`, `'0% 100%'`, `'35% 76%'`
+     * - Mixed: `'left 25%'`, `'50% top'`
+     *
+     * @param input - The origin string to parse.
+     * @returns Normalized `{ x, y }` coordinates.
+     */
+    toNormalized({ value }: OriginToNormalizedInput): NormalizedOrigin;
+    /**
+     * Parses a single value (keyword or percentage) to a normalized number.
+     */
+    private parseValue;
 }
 
 interface StringColor {
@@ -1464,11 +1499,25 @@ declare class StringCursor extends StringModule {
 }
 
 declare class StringImpulse extends StringModule {
+    private originObservers;
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
     onObjectDisconnected(object: StringObject): void;
     onMouseMove(_e?: MouseEvent): void;
-    private getElementsAtPoint;
+    /**
+     * Parses and caches the rotation origin for an object.
+     * Called once on object connection and when attribute changes.
+     */
+    private cacheRotationOrigin;
+    /**
+     * Observes changes to the rotation-origin attribute and re-caches when changed.
+     */
+    private observeRotationOrigin;
+    /**
+     * Calculates the rotation origin point using cached normalized values and provided rect.
+     * Avoids re-parsing origin string and extra getBoundingClientRect calls.
+     */
+    private getRotationOriginFromRect;
     onFrame(_: StringData): void;
 }
 
@@ -1776,16 +1825,22 @@ declare class StringDelayLerpTracker extends StringModule {
 
 /**
  * FPS Tracker Module.
- * Displays how many times `onFrame()` is called per second.
- * Useful for debugging rendering performance or vsync issues.
+ * Broadcasts frame rate to elements with `data-fps` attribute.
+ * Also creates an optional debug display element.
  */
 declare class StringFPSTracker extends StringModule {
     private displayElement;
     private intervalId;
     private frameCount;
+    /** Cached elements with data-fps attribute */
+    private fpsElements;
+    /** MutationObserver for DOM changes */
+    private observer;
+    /** Last known FPS to avoid redundant updates */
+    private lastFps;
     constructor(context: StringContext);
     /**
-     * Initializes the visual FPS counter and update interval.
+     * Initializes the visual FPS counter, scans for elements, and starts interval.
      */
     onInit(): void;
     /**
@@ -1793,9 +1848,29 @@ declare class StringFPSTracker extends StringModule {
      */
     onFrame(_data: StringData): void;
     /**
-     * Cleans up DOM and interval.
+     * Cleans up DOM, observer, and interval.
      */
     destroy(): void;
+    /**
+     * Handles visibility toggle from external API.
+     */
+    private onVisibilityChange;
+    /**
+     * Removes the display element and its styles.
+     */
+    private removeDisplayElement;
+    /**
+     * Updates all tracked elements with current FPS.
+     */
+    private updateFPS;
+    /**
+     * Scans document for elements with data-fps attribute.
+     */
+    private scanElements;
+    /**
+     * Observes DOM for added/removed elements with data-fps attribute.
+     */
+    private observeDOM;
     /**
      * Creates and styles the floating FPS display.
      */
@@ -1842,24 +1917,55 @@ declare class StringLerpTracker extends StringModule {
 }
 
 /**
- * Tracker module that shows current scroll position and direction.
- * Displays a fixed label in the corner of the screen for debugging.
+ * Tracker module that broadcasts scroll position to elements with data attributes.
+ * Elements with `data-val`, `data-val-pct`, or `data-dir` will receive updates.
+ * Also creates an optional debug display element.
  */
 declare class StringPositionTracker extends StringModule {
     private displayElement;
+    /** Cached elements by attribute type */
+    private valElements;
+    private valPctElements;
+    private dirElements;
+    /** MutationObserver for DOM changes */
+    private observer;
+    /** Last known values to avoid redundant updates */
+    private lastVal;
+    private lastValPct;
+    private lastDir;
     constructor(context: StringContext);
     /**
-     * Called on start — creates the DOM element for position display.
+     * Called on start — creates debug element and scans for tracked elements.
      */
     onInit(): void;
     /**
-     * Called on scroll — updates scroll position and direction symbol.
+     * Called on scroll — updates all tracked elements with position data.
      */
     onScroll(data: StringData): void;
     /**
-     * Removes display element from DOM.
+     * Cleans up DOM observer and display element.
      */
     destroy(): void;
+    /**
+     * Handles visibility toggle from external API.
+     */
+    private onVisibilityChange;
+    /**
+     * Removes the display element.
+     */
+    private removeDisplayElement;
+    /**
+     * Scans document for elements with tracking attributes.
+     */
+    private scanElements;
+    /**
+     * Observes DOM for added/removed elements with tracking attributes.
+     */
+    private observeDOM;
+    /**
+     * Checks if element has any tracking attribute.
+     */
+    private hasTrackingAttr;
     /**
      * Creates and styles the floating position indicator.
      */
@@ -2125,6 +2231,8 @@ declare class StringTune {
      * Can be 'smooth', 'default', or 'disable'.
      */
     set scrollMobileMode(mode: ScrollMode);
+    set FPSTrackerVisible(visible: boolean);
+    set PositionTrackerVisible(visible: boolean);
     private debouncedResize;
     private constructor();
     /**

package/dist/index.d.ts

@@ -737,15 +737,50 @@ interface OriginInput {
     /** Raw origin string, e.g. `'center'` or `'random(top, bottom)'`. */
     value: string;
 }
+/**
+ * Input for parsing origin to normalized coordinates.
+ * Supports formats like `'left top'`, `'center center'`, `'50% 50%'`, `'35% 76%'`.
+ */
+interface OriginToNormalizedInput {
+    /** Raw origin string, e.g. `'left top'`, `'center'`, `'50% 25%'`. */
+    value: string;
+}
+/**
+ * Output: normalized origin coordinates (0-1 range).
+ */
+interface NormalizedOrigin {
+    /** Normalized X coordinate (0 = left, 0.5 = center, 1 = right). */
+    x: number;
+    /** Normalized Y coordinate (0 = top, 0.5 = center, 1 = bottom). */
+    y: number;
+}
 /**
  * Tool that parses origin strings.
  * Allows static values like `'center'`, or expressions like `'random(...)'` to select one randomly.
+ * Also provides `toNormalized()` method to convert origin strings to `{ x, y }` coordinates.
  */
 declare class OriginParserTool implements IStringTool<OriginInput, string> {
     /**
      * @returns Parsed string value (static or randomly chosen).
      */
     process({ value }: OriginInput): string;
+    /**
+     * Parses an origin string to normalized `{ x, y }` coordinates (0-1 range).
+     *
+     * Supported formats:
+     * - Single keyword: `'center'`, `'top'`, `'left'`, etc.
+     * - Two keywords: `'left top'`, `'right bottom'`, `'center center'`
+     * - Percentages: `'50% 50%'`, `'0% 100%'`, `'35% 76%'`
+     * - Mixed: `'left 25%'`, `'50% top'`
+     *
+     * @param input - The origin string to parse.
+     * @returns Normalized `{ x, y }` coordinates.
+     */
+    toNormalized({ value }: OriginToNormalizedInput): NormalizedOrigin;
+    /**
+     * Parses a single value (keyword or percentage) to a normalized number.
+     */
+    private parseValue;
 }
 
 interface StringColor {
@@ -1464,11 +1499,25 @@ declare class StringCursor extends StringModule {
 }
 
 declare class StringImpulse extends StringModule {
+    private originObservers;
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
     onObjectDisconnected(object: StringObject): void;
     onMouseMove(_e?: MouseEvent): void;
-    private getElementsAtPoint;
+    /**
+     * Parses and caches the rotation origin for an object.
+     * Called once on object connection and when attribute changes.
+     */
+    private cacheRotationOrigin;
+    /**
+     * Observes changes to the rotation-origin attribute and re-caches when changed.
+     */
+    private observeRotationOrigin;
+    /**
+     * Calculates the rotation origin point using cached normalized values and provided rect.
+     * Avoids re-parsing origin string and extra getBoundingClientRect calls.
+     */
+    private getRotationOriginFromRect;
     onFrame(_: StringData): void;
 }
 
@@ -1776,16 +1825,22 @@ declare class StringDelayLerpTracker extends StringModule {
 
 /**
  * FPS Tracker Module.
- * Displays how many times `onFrame()` is called per second.
- * Useful for debugging rendering performance or vsync issues.
+ * Broadcasts frame rate to elements with `data-fps` attribute.
+ * Also creates an optional debug display element.
  */
 declare class StringFPSTracker extends StringModule {
     private displayElement;
     private intervalId;
     private frameCount;
+    /** Cached elements with data-fps attribute */
+    private fpsElements;
+    /** MutationObserver for DOM changes */
+    private observer;
+    /** Last known FPS to avoid redundant updates */
+    private lastFps;
     constructor(context: StringContext);
     /**
-     * Initializes the visual FPS counter and update interval.
+     * Initializes the visual FPS counter, scans for elements, and starts interval.
      */
     onInit(): void;
     /**
@@ -1793,9 +1848,29 @@ declare class StringFPSTracker extends StringModule {
      */
     onFrame(_data: StringData): void;
     /**
-     * Cleans up DOM and interval.
+     * Cleans up DOM, observer, and interval.
      */
     destroy(): void;
+    /**
+     * Handles visibility toggle from external API.
+     */
+    private onVisibilityChange;
+    /**
+     * Removes the display element and its styles.
+     */
+    private removeDisplayElement;
+    /**
+     * Updates all tracked elements with current FPS.
+     */
+    private updateFPS;
+    /**
+     * Scans document for elements with data-fps attribute.
+     */
+    private scanElements;
+    /**
+     * Observes DOM for added/removed elements with data-fps attribute.
+     */
+    private observeDOM;
     /**
      * Creates and styles the floating FPS display.
      */
@@ -1842,24 +1917,55 @@ declare class StringLerpTracker extends StringModule {
 }
 
 /**
- * Tracker module that shows current scroll position and direction.
- * Displays a fixed label in the corner of the screen for debugging.
+ * Tracker module that broadcasts scroll position to elements with data attributes.
+ * Elements with `data-val`, `data-val-pct`, or `data-dir` will receive updates.
+ * Also creates an optional debug display element.
  */
 declare class StringPositionTracker extends StringModule {
     private displayElement;
+    /** Cached elements by attribute type */
+    private valElements;
+    private valPctElements;
+    private dirElements;
+    /** MutationObserver for DOM changes */
+    private observer;
+    /** Last known values to avoid redundant updates */
+    private lastVal;
+    private lastValPct;
+    private lastDir;
     constructor(context: StringContext);
     /**
-     * Called on start — creates the DOM element for position display.
+     * Called on start — creates debug element and scans for tracked elements.
      */
     onInit(): void;
     /**
-     * Called on scroll — updates scroll position and direction symbol.
+     * Called on scroll — updates all tracked elements with position data.
      */
     onScroll(data: StringData): void;
     /**
-     * Removes display element from DOM.
+     * Cleans up DOM observer and display element.
      */
     destroy(): void;
+    /**
+     * Handles visibility toggle from external API.
+     */
+    private onVisibilityChange;
+    /**
+     * Removes the display element.
+     */
+    private removeDisplayElement;
+    /**
+     * Scans document for elements with tracking attributes.
+     */
+    private scanElements;
+    /**
+     * Observes DOM for added/removed elements with tracking attributes.
+     */
+    private observeDOM;
+    /**
+     * Checks if element has any tracking attribute.
+     */
+    private hasTrackingAttr;
     /**
      * Creates and styles the floating position indicator.
      */
@@ -2125,6 +2231,8 @@ declare class StringTune {
      * Can be 'smooth', 'default', or 'disable'.
      */
     set scrollMobileMode(mode: ScrollMode);
+    set FPSTrackerVisible(visible: boolean);
+    set PositionTrackerVisible(visible: boolean);
     private debouncedResize;
     private constructor();
     /**