@motion.page/sdk 1.0.5 → 1.0.6

package/dist/registries/SDKRegistry.d.ts

@@ -35,8 +35,9 @@ interface DrawSVGParserFunctions {
 interface TextSplitterFunctions {
     split: (element: Element, type: SplitType, options?: {
         mask?: boolean;
+        consumer?: object;
     }) => HTMLElement[];
-    revert: (element: Element) => boolean;
+    revert: (element: Element, consumer?: object) => boolean;
     isSplit: (element: Element) => boolean;
 }
 interface StyleResetFunctions {

package/dist/triggers/PinManager.d.ts

@@ -166,9 +166,12 @@ export declare class PinManager {
      * Auto-detection rules (when pinSpacing is undefined or true):
      * - Body pin: scroll room is handled via documentElement height, not a spacer.
      *   Return false so the (non-existent) spacer gets no extra padding/margin.
-     * - Flex parent: GSAP parity — a flex container reflows automatically around a
-     *   fixed child via the spacer's dimensions; extra padding would double-count.
      * - Everything else: default to 'padding' (adds pinDistance as padding-bottom).
+     *   Works reliably in both flex and non-flex contexts with content-box sizing.
+     *
+     * Flex-aware behavior is handled separately in setup() by adding flex-shrink: 0
+     * to the spacer when inside a flex container, preventing the flex algorithm from
+     * collapsing the spacer below its needed size (GSAP-compatible).
      */
     private _resolvePinSpacing;
     /**

package/dist/utils/TextSplitter.d.ts

@@ -15,12 +15,21 @@
  *
  * Revert:
  *   TextSplitter.revert(element);
+ *   TextSplitter.revert(element, consumer); // reference-counted
  */
 import type { SplitType } from '../types';
 export type { SplitType };
 export interface SplitOptions {
     /** Wrap each split element in a parent with overflow:hidden for clip-reveal effects */
     mask?: boolean;
+    /**
+     * Opaque token identifying the caller (e.g. an AnimationBuilder instance).
+     * When provided, splits are reference-counted: the DOM is only reverted once
+     * all registered consumers release their claim via revert(element, consumer).
+     * A second consumer on the same element triggers a smart DOM upgrade (nesting)
+     * rather than destroying the first consumer's spans.
+     */
+    consumer?: object;
 }
 interface SplitResult {
     chars: HTMLElement[];
@@ -30,9 +39,45 @@ interface SplitResult {
 }
 export declare class TextSplitter {
     /**
-     * Split text content into animatable elements
+     * Split text content into animatable elements.
+     *
+     * When `options.consumer` is provided the split is reference-counted.
+     * A second consumer on the same element will have the DOM upgraded
+     * (chars nested inside existing word spans, or word-wraps promoted to
+     * word spans) rather than reverted and rebuilt, so the first consumer's
+     * DOM references remain valid.
+     *
+     * Without a consumer token the function behaves exactly like before:
+     * any existing split is reverted and a fresh split is performed.
      */
     static split(element: Element, type: SplitType, options?: SplitOptions): HTMLElement[];
+    /**
+     * Attempt to upgrade an existing split to satisfy a new type request without
+     * destroying existing DOM references.
+     *
+     * Returns the appropriate span array on success, or null if the upgrade is
+     * not possible (caller must fall back to a full revert + re-split).
+     */
+    private static _tryUpgrade;
+    /**
+     * Return the appropriate span array from a SplitResult for the requested type.
+     * Chars have highest priority, then words, then lines.
+     */
+    private static _getSpansForType;
+    /**
+     * Build a combined data-split attribute value from existing and requested types,
+     * ordered as: lines, words, chars (broadest → most granular).
+     */
+    private static _buildTypeString;
+    /**
+     * Walk a word span's text nodes and replace them with individual char spans,
+     * appending each new span to the provided `chars` array.
+     *
+     * Used when upgrading an existing 'words' split to include 'chars'.
+     * The word span itself is NOT moved or recreated — only its text node
+     * children are swapped out, so existing references to the word span remain valid.
+     */
+    private static _nestCharsInElement;
     /**
      * Split text nodes into word spans, preserving existing element wrappers.
      * Recurses into child elements so `<span class="accent">word</span>` keeps
@@ -76,9 +121,17 @@ export declare class TextSplitter {
      */
     private static _propagateGradientText;
     /**
-     * Revert element to original content
+     * Revert element to original content.
+     *
+     * When `consumer` is provided the revert is reference-counted: the DOM is
+     * only restored once all registered consumers have released via this method.
+     * If the consumer is the last one (or no consumer tracking is active), the
+     * element's innerHTML is restored to the pre-split original immediately.
+     *
+     * Without `consumer` (legacy / forced revert), the DOM is restored regardless
+     * of how many consumers are still registered. All consumer refs are cleared.
      */
-    static revert(element: Element): boolean;
+    static revert(element: Element, consumer?: object): boolean;
     /**
      * Check if element has been split
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion.page/sdk",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "High-performance CSS animation SDK with scroll, hover, gesture, and cursor triggers",
   "type": "module",
   "main": "dist/index.js",