@motion.page/sdk 1.0.2 → 1.0.4

package/dist/triggers/EventTrigger.d.ts

@@ -23,6 +23,8 @@ export declare class EventTrigger extends BaseTrigger<EventTriggerConfig> {
     private _listeners;
     private _isForward;
     private _frozenRects;
+    private _snapshotScrollX;
+    private _snapshotScrollY;
     private _wasHovering;
     private _hoverLeaveTimeout;
     private _boundMouseMoveHandler;
@@ -40,6 +42,8 @@ export declare class EventTrigger extends BaseTrigger<EventTriggerConfig> {
      * Called by TriggerManager.refreshScrollTriggers() on resize.
      */
     refresh(): void;
+    /** Snapshot frozen rects and the current scroll offset. */
+    private _snapshotRects;
     private _resolveTargets;
     private _addHoverListeners;
     private _handleLeaveAction;

package/dist/triggers/GlobalScrollListener.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GlobalScrollListener
+ *
+ * Consolidates per-instance scroll listeners into a single listener per scroller.
+ * This mirrors GSAP's architecture where one global scroll handler reads scrollY
+ * once and dispatches to all active ScrollTrigger instances in a single pass.
+ *
+ * Benefits:
+ * - Eliminates N scroll event listeners (one per ScrollTrigger) → 1 per scroller
+ * - For instant scrub: wraps all instance updates in a single runBatched() call,
+ *   so DOM writes are flushed once instead of N times per scroll event
+ * - Reads scrollY once per scroll event, shared across all instances
+ *
+ * Architecture:
+ * - Each unique scroller (window or custom element) gets ONE passive scroll listener
+ * - On scroll, all registered callbacks for that scroller run inside a single
+ *   runBatched() wrapper (batches instant-scrub DOM writes into one flush)
+ * - When the last callback for a scroller is removed, the listener is detached
+ */
+type ScrollCallback = () => void;
+/**
+ * Register a scroll callback for a given scroller.
+ * The first registration for a scroller attaches a single passive scroll listener.
+ */
+export declare function addScrollCallback(scroller: EventTarget, callback: ScrollCallback): void;
+/**
+ * Remove a scroll callback for a given scroller.
+ * When the last callback is removed, the scroll listener is detached.
+ */
+export declare function removeScrollCallback(scroller: EventTarget, callback: ScrollCallback): void;
+/**
+ * Reset all state (for testing only).
+ * @internal
+ */
+export declare function _resetGlobalScrollListener(): void;
+export {};

package/dist/triggers/MarkerManager.d.ts

@@ -25,15 +25,29 @@ export declare class MarkerManager {
     private _scroller;
     private _startConfig;
     private _endConfig;
+    private _cachedElStartDocTop;
+    private _cachedElEndDocTop;
+    private _cachedElPositionValid;
     constructor(triggerId: number);
     /**
      * Create debug markers showing trigger positions
      */
     setup(config: MarkerSetupConfig): void;
     /**
-     * Update marker positions on scroll
+     * Cache element marker positions in document/content coordinates.
+     * Called at setup and on refresh. This is the only place getLayoutRect() is called
+     * for element markers — the per-frame update() uses cached values instead.
+     */
+    private _cacheElementPositions;
+    /**
+     * Update marker positions on scroll.
+     * Uses cached document-relative positions to avoid getLayoutRect() per frame.
      */
     update(scrollTop: number, triggerElement: HTMLElement | null, viewportHeight: number): void;
+    /**
+     * Recache element positions after layout changes (resize, refresh).
+     */
+    recachePositions(viewportHeight: number): void;
     /**
      * Remove all markers
      */

package/dist/triggers/PinManager.d.ts

@@ -39,6 +39,10 @@ export declare class PinManager {
     private _fixedTop;
     private _fixedLeft;
     private _width;
+    private _fixedBreakingAncestors;
+    private _isBodyPin;
+    private _originalHtmlHeight;
+    private _originalHtmlOverflow;
     constructor(id: number);
     /**
      * Setup pinning for an element
@@ -97,12 +101,74 @@ export declare class PinManager {
         bottom: number;
         right: number;
     } | null;
+    /**
+     * Whether this manager is using the body-pin strategy (html height extension).
+     */
+    isBodyPin(): boolean;
+    /**
+     * Temporarily reset html.style.height to its original (pre-pin) value so that
+     * callers can measure the body's natural height without the inflation caused
+     * by the pin spacing.  Returns a restore function that re-applies the current
+     * (inflated) height.  No-op for non-body pins.
+     *
+     * Used by ScrollTrigger.refresh() before _calculateTriggerPositions() so
+     * trigger positions are derived from the body's real content height.
+     */
+    suspendHtmlHeight(): (() => void) | null;
     /**
      * Check if using fixed pin strategy
      */
     isFixedPin(): boolean;
     /**
-     * Resolve pinSpacing config to a concrete value
+     * Detect ancestor elements with CSS properties that break position:fixed.
+     *
+     * Any of these on an ancestor creates a new containing block, causing
+     * position:fixed to position relative to that ancestor instead of the
+     * viewport — making pinned elements scroll off-screen:
+     *
+     * - filter (even blur(0px)) — set by animation libraries as initial state
+     * - transform (even translate(0)) — set by smooth scroll libraries (Lenis)
+     * - will-change: transform/filter/perspective
+     * - perspective
+     * - contain: paint/layout/strict/content
+     * - backdrop-filter
+     * - overflow: clip — clips fixed descendants at element's padding box
+     *
+     * Only needs to run once during first setup (not on refresh).
+     */
+    private _detectFixedBreakingAncestors;
+    /**
+     * Override properties on ancestors that break position:fixed.
+     *
+     * IMPORTANT: Captures the current inline style value RIGHT BEFORE overriding,
+     * not at detection time. This prevents restoring stale values — e.g. if an
+     * animation set `filter: blur(5px)` at detection time but has since completed
+     * and the SDK cleaned it to `none`, we'd wrongly restore `blur(5px)` on unpin.
+     *
+     * Safe fallback values:
+     * - filter/transform/perspective → 'none'
+     * - will-change → 'auto'
+     * - contain → 'none'
+     * - overflow-x:clip → 'hidden' (still prevents horizontal scrollbar)
+     * - overflow-y:clip → 'visible'
+     */
+    private _overrideFixedBreakingAncestors;
+    /**
+     * Restore original values on ancestors that were overridden during pin.
+     * The values restored are the ones captured at override time (pin entry),
+     * not detection time — so they reflect the element's actual state just
+     * before the pin started.
+     */
+    private _restoreFixedBreakingAncestors;
+    /**
+     * Resolve pinSpacing config to a concrete value.
+     *
+     * 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).
      */
     private _resolvePinSpacing;
     /**

package/dist/triggers/TriggerManager.d.ts

@@ -13,6 +13,8 @@ import type { Timeline } from '../core/Timeline';
 /** Config for page load trigger */
 export interface PageLoadTriggerConfig {
     timing?: 'before' | 'during' | 'after';
+    /** When true, the timeline is built but not played — use Motion('name').play() to start it manually */
+    paused?: boolean;
 }
 /** Interface that trigger instances must satisfy for cleanup */
 interface TriggerInstance {

package/dist/types/index.d.ts

@@ -18,6 +18,28 @@ export interface RepeatConfig {
     delay?: number;
     yoyo?: boolean;
 }
+/**
+ * Configuration for a Timeline instance
+ */
+export interface TimelineConfig {
+    /**
+     * Number of times to repeat the entire timeline.
+     * Use a number for simple repeats, or RepeatConfig for advanced options.
+     * Use -1 for infinite repeat.
+     * @example
+     * new Timeline('loop', { repeat: -1 })
+     * new Timeline('bounce', { repeat: { times: 3, delay: 0.2, yoyo: true } })
+     */
+    repeat?: number | RepeatConfig;
+    /** Called when the timeline starts playing (first frame with time > 0) */
+    onStart?: () => void;
+    /** Called every frame with the current progress (0–1) and time (seconds) */
+    onUpdate?: (progress: number, time: number) => void;
+    /** Called when the timeline completes all repeats */
+    onComplete?: () => void;
+    /** Called at the end of each repeat cycle */
+    onRepeat?: (repeatCount: number) => void;
+}
 /**
  * Stagger configuration for multiple elements
  */
@@ -67,6 +89,7 @@ export interface AnimationVars {
     paddingBottom?: number | string;
     paddingLeft?: number | string;
     borderRadius?: number | string;
+    borderWidth?: number | string;
     fontSize?: number | string;
     lineHeight?: number | string;
     letterSpacing?: number | string;

package/dist/utils/FilterParser.d.ts

@@ -26,7 +26,13 @@ export interface ParsedFilterFunction {
  */
 export declare function parseFilter(filter: string): ParsedFilterFunction[] | null;
 /**
- * Convert parsed filter functions back to CSS filter string
+ * Convert parsed filter functions back to CSS filter string.
+ *
+ * Returns 'none' when all filters are at their identity/default values
+ * (e.g. blur(0px), brightness(1)). This is critical because any filter
+ * value other than 'none' — even visually invisible ones like blur(0px) —
+ * creates a CSS containing block that breaks position:fixed on descendants.
+ * This would cause pinned sections to disappear during scroll animations.
  */
 export declare function filterToString(filters: ParsedFilterFunction[]): string;
 /**

package/dist/utils/TextSplitter.d.ts

@@ -41,6 +41,11 @@ export declare class TextSplitter {
     private static _splitWordsDom;
     /**
      * Split text nodes into character spans, preserving existing element wrappers.
+     *
+     * Characters are grouped by word inside implicit wrapper spans with
+     * `white-space: nowrap` so the browser never breaks a word across lines
+     * (matching GSAP SplitText behaviour). Only the char spans are exposed
+     * as animatable elements — the word wrappers are transparent to consumers.
      */
     private static _splitCharsDom;
     /**
@@ -62,6 +67,14 @@ export declare class TextSplitter {
      * The wrapper clips content so animating y:'100%' creates a reveal effect.
      */
     private static _applyMaskWrappers;
+    /**
+     * Detect if the split element uses `background-clip: text` (gradient text)
+     * and propagate the gradient through all generated spans so text stays visible.
+     *
+     * Without this, inline-block split spans inherit `-webkit-text-fill-color: transparent`
+     * but NOT the parent's gradient background, making the text invisible.
+     */
+    private static _propagateGradientText;
     /**
      * Revert element to original content
      */

package/dist/utils/getLayoutRect.d.ts

@@ -11,5 +11,11 @@
  * coordinates from getBoundingClientRect(), which would produce incorrect
  * document-relative trigger positions.  Temporarily clearing position/top/left/width
  * restores document-flow measurement before reading the rect.
+ *
+ * Performance notes:
+ * - The getComputedStyle() call to detect position:fixed is skipped when we
+ *   can tell from the inline style alone (fast path for the common case).
+ * - No forced reflow after restoring styles — the browser batches style
+ *   writes and applies them before the next paint automatically.
  */
 export declare function getLayoutRect(element: Element): DOMRect;

package/package.json

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