@motion.page/sdk 0.1.0

package/dist/utils/PathParser.d.ts

@@ -0,0 +1,89 @@
+/**
+ * PathParser - Parse and animate elements along SVG paths
+ *
+ * Handles:
+ * - CSS selector to existing <path> element
+ * - Direct Element reference
+ * - Raw SVG path data string (starting with M/m)
+ * - Position and angle calculation along path
+ * - Alignment offset calculation
+ */
+/**
+ * Point on a path with position and angle
+ */
+export interface PathPoint {
+    x: number;
+    y: number;
+    angle: number;
+}
+/**
+ * Parsed path data ready for animation
+ */
+export interface ParsedPathData {
+    pathData: string;
+    length: number;
+}
+/**
+ * Check if a string is raw SVG path data (starts with M or m command)
+ */
+export declare function isPathData(value: string): boolean;
+/**
+ * Resolve path target to path data string
+ *
+ * @param target - CSS selector, Element, or raw path data
+ * @returns Path data string or null if not found
+ */
+export declare function resolvePathData(target: string | Element): string | null;
+/**
+ * Get the total length of a path
+ * Results are cached per path data string
+ */
+export declare function getPathLength(pathData: string): number;
+/**
+ * Clear the path length cache
+ * Call when path data changes dynamically
+ */
+export declare function clearPathLengthCache(): void;
+/**
+ * Get a point on the path at a given progress (0-1)
+ *
+ * @param pathData - SVG path data string
+ * @param progress - Position on path (0-1)
+ * @param calculateAngle - Whether to calculate rotation angle
+ * @returns Point with x, y, and angle
+ */
+export declare function getPointAtProgress(pathData: string, progress: number, calculateAngle?: boolean): PathPoint;
+/**
+ * Calculate the offset for the animated element itself
+ * This is used to position the element's center (or specified origin) on the path
+ *
+ * @param element - The element being animated (selector, Element, or undefined)
+ * @param alignAt - Origin point as [x%, y%], default [50, 50] (center)
+ * @returns Offset to subtract from path position
+ */
+export declare function calculateElementOffset(element: string | Element | undefined, alignAt?: [number, number]): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate offset to position path relative to an align element
+ * The path's first point (M command) will be positioned at the align element's center
+ *
+ * @param align - Element or selector to align the path to
+ * @param pathData - SVG path data string
+ * @param animatedElement - The element being animated (to calculate relative offset)
+ * @returns Offset to add to path coordinates
+ */
+export declare function calculatePathAlignOffset(align: string | Element | undefined, pathData: string, animatedElement?: Element): {
+    x: number;
+    y: number;
+};
+/**
+ * Parse a path configuration and prepare it for animation
+ */
+export declare function parsePath(target: string | Element, align?: string | Element, alignAt?: [number, number]): ParsedPathData | null;
+/**
+ * Cleanup function - removes hidden SVG from DOM
+ * Call when SDK is destroyed or for testing cleanup
+ */
+export declare function cleanupPathParser(): void;

package/dist/utils/PositionParser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * PositionParser - Parse timeline position parameters
+ *
+ * Supports:
+ * - Number: absolute time (e.g., 2)
+ * - "+=0.5": relative to current end (0.5s after)
+ * - "-=0.5": relative to current end (0.5s before, overlap)
+ * - "<": start of previous animation
+ * - ">": end of previous animation
+ * - "<0.5" or "<+0.5": start of previous + offset
+ * - "<-0.5": start of previous - offset
+ * - ">0.5" or ">+0.5": end of previous + offset
+ * - ">-0.5": end of previous - offset
+ */
+export declare class PositionParser {
+    /**
+     * Parse position parameter and return absolute time
+     * @param position Position parameter (string or number)
+     * @param currentEnd Current end time of timeline
+     * @param previousStart Start time of previous child
+     * @param previousEnd End time of previous child
+     */
+    static parse(position: string | number | undefined, currentEnd: number, previousStart: number, previousEnd: number): number;
+}

package/dist/utils/PropertyParser.d.ts

@@ -0,0 +1,159 @@
+/**
+ * PropertyParser - Parse and normalize animation properties
+ *
+ * Handles:
+ * - Transform shortcuts (x, y, rotate, scale, etc.)
+ * - Relative values (+=, -=, *=, /=)
+ * - Unit parsing and defaulting
+ * - Color parsing (hex, rgb, hsl, named, CSS variables) - OPTIONAL
+ * - Filter parsing (blur, brightness, contrast, etc.) - OPTIONAL
+ * - DrawSVG parsing (SVG stroke animations) - OPTIONAL
+ *
+ * Optional parsers are loaded conditionally via SDKRegistry.
+ * If a parser is not loaded, those property types will be skipped.
+ */
+import type { AnimationTarget } from '../types';
+import type { ParsedFilterFunction } from './FilterParser';
+import type { ParsedDrawSVG } from './DrawSVGParser';
+/**
+ * Valid property value types for animation
+ */
+export type PropertyValue = number | string;
+/**
+ * Base fields shared by all parsed property types
+ */
+interface ParsedPropertyBase {
+    property: string;
+    isTransform: boolean;
+}
+/**
+ * Scalar property (numbers with units)
+ */
+interface ParsedScalarProperty extends ParsedPropertyBase {
+    type: 'scalar';
+    startValue: number;
+    endValue: number;
+    unit: string;
+}
+/**
+ * Color property (RGBA values)
+ */
+interface ParsedColorProperty extends ParsedPropertyBase {
+    type: 'color';
+    startColor: Float32Array;
+    endColor: Float32Array;
+}
+/**
+ * Filter property (CSS filters)
+ */
+interface ParsedFilterProperty extends ParsedPropertyBase {
+    type: 'filter';
+    startFilters: ParsedFilterFunction[];
+    endFilters: ParsedFilterFunction[];
+}
+/**
+ * DrawSVG property (SVG stroke animation)
+ */
+interface ParsedDrawSVGProperty extends ParsedPropertyBase {
+    type: 'drawSVG';
+    startDraw: ParsedDrawSVG;
+    endDraw: ParsedDrawSVG;
+    length: number;
+}
+/**
+ * Path property (motion along SVG path)
+ */
+interface ParsedPathProperty extends ParsedPropertyBase {
+    type: 'path';
+    pathData: string;
+    pathLength: number;
+    startProgress: number;
+    endProgress: number;
+    rotate: boolean;
+    alignOffset: {
+        x: number;
+        y: number;
+    };
+    pathOffset: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Discriminated union of all parsed property types
+ */
+export type ParsedProperty = ParsedScalarProperty | ParsedColorProperty | ParsedFilterProperty | ParsedDrawSVGProperty | ParsedPathProperty;
+/**
+ * Check if a property is a transform property
+ */
+export declare function isTransformProp(prop: string): boolean;
+/**
+ * Check if a property is a color property
+ */
+export declare function isColorProp(prop: string): boolean;
+/**
+ * Check if a property is the filter property
+ */
+export declare function isFilterProp(prop: string): boolean;
+/**
+ * Check if a property is the drawSVG property
+ */
+export declare function isDrawSVGProp(prop: string): boolean;
+/**
+ * Check if a property is the path property (motion path)
+ */
+export declare function isPathProp(prop: string): boolean;
+/**
+ * Check if a property is a CSS variable (custom property)
+ */
+export declare function isCSSVariable(prop: string): boolean;
+/**
+ * Check if a value looks like a color (for CSS variable type detection)
+ */
+export declare function looksLikeColor(value: PropertyValue): boolean;
+/**
+ * Parse a property value and extract numeric value and unit
+ */
+export declare function parseValue(value: PropertyValue): {
+    value: number;
+    unit: string;
+};
+/**
+ * Get the default unit for a property
+ */
+export declare function getDefaultUnit(prop: string): string;
+/**
+ * Get the current computed value of a property from a target
+ * Handles both DOM Elements and plain objects
+ */
+export declare function getCurrentValue(target: AnimationTarget, prop: string): number;
+/**
+ * Get the original CSS value AND unit of a property (excluding inline styles)
+ * Returns both value and unit to preserve the original CSS unit (%, rem, em, vh, etc.)
+ */
+export declare function getOriginalCSSValueWithUnit(target: Element, prop: string): {
+    value: number;
+    unit: string;
+};
+/**
+ * Convert camelCase to kebab-case
+ */
+export declare function camelToKebab(str: string): string;
+/**
+ * Check if a value is relative (+=, -=, *=, /=)
+ */
+export declare function isRelativeValue(value: PropertyValue): boolean;
+/**
+ * Get relative operator from value string
+ */
+export declare function getRelativeOperator(value: string): '+=' | '-=' | '*=' | '/=' | null;
+/**
+ * Calculate relative end value
+ */
+export declare function calculateRelativeValue(startValue: number, relativeValue: number, operator: '+=' | '-=' | '*=' | '/='): number;
+/**
+ * Parse a property for animation
+ * Handles both DOM Elements and plain objects
+ */
+export declare function parseProperty(target: AnimationTarget, prop: string, targetValue: PropertyValue, fromValue?: PropertyValue): ParsedProperty;
+export {};

package/dist/utils/QuickSetter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * QuickSetter - High-performance property setter for per-frame updates
+ *
+ * Bypasses the full animation pipeline for maximum speed.
+ * Used by CursorTrigger for smooth position tracking.
+ */
+export type QuickSetterFn = (value: number) => void;
+/**
+ * Create a high-performance property setter for per-frame updates.
+ * Returns a function that sets the value directly without animation overhead.
+ *
+ * @param target - The element to animate
+ * @param property - CSS property name (camelCase)
+ * @param unit - Unit to append (default: 'px' for transforms, '' for others)
+ */
+export declare function createQuickSetter(target: Element, property: string, unit?: string): QuickSetterFn;

package/dist/utils/ScrollPositionParser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ScrollPositionParser
+ *
+ * Shared utility for parsing scroll trigger position values.
+ * Used by ScrollTrigger and MarkerManager.
+ *
+ * Supports:
+ * - Keywords: top, center, bottom
+ * - Keywords with offsets: top+100px, center-50%, bottom+20vh
+ * - Units: px, %, vh, vw
+ */
+/**
+ * Parse a position value into pixels
+ * @param value - Position string (e.g., "top", "center", "50%", "100px", "top+100px")
+ * @param referenceSize - Reference size for percentage calculations (element height)
+ * @param viewportHeight - Viewport height for vh calculations
+ * @param viewportWidth - Viewport width for vw calculations (optional)
+ */
+export declare function parseScrollPosition(value: string, referenceSize: number, viewportHeight: number, viewportWidth?: number): number;

package/dist/utils/StyleReset.d.ts

@@ -0,0 +1,73 @@
+/**
+ * StyleReset - Clear animation-related inline styles from elements
+ *
+ * Only clears styles that our SDK has animated or set for pinning,
+ * preserving user's original inline styles.
+ * Uses registries to track which CSS properties have been set by the SDK.
+ */
+/**
+ * Register that a CSS property has been animated on an element.
+ * Call this when setting inline styles during animation.
+ */
+export declare function registerAnimatedProp(element: Element, prop: string): void;
+/**
+ * Register multiple animated properties at once.
+ */
+export declare function registerAnimatedProps(element: Element, props: string[]): void;
+/**
+ * Get all CSS properties that have been animated on an element.
+ */
+export declare function getAnimatedProps(element: Element): Set<string>;
+/**
+ * Clear tracking for an element (called after Motion.reset).
+ */
+export declare function clearAnimatedPropsRegistry(element: Element): void;
+/**
+ * Clear specific animation properties from an element's inline styles.
+ * Only clears the properties specified, preserving other inline styles.
+ *
+ * @param element - The element to clear styles from
+ * @param props - Animation property names to clear (e.g., 'x', 'opacity', 'backgroundColor')
+ */
+export declare function clearAnimationStylesForProps(element: Element, props: string[]): void;
+/**
+ * Clear all animation-related inline styles that our SDK has set on an element.
+ * Only clears properties tracked in the registry, preserving user's original inline styles.
+ */
+export declare function clearAnimationStyles(element: Element): void;
+/**
+ * Clear animation styles and remove from registry (full reset).
+ * Use this for Motion.reset() to completely clean up.
+ */
+export declare function clearAnimationStylesAndUnregister(element: Element): void;
+/**
+ * Clear animation styles from multiple elements
+ */
+export declare function clearAnimationStylesAll(elements: Element[]): void;
+/**
+ * Register that a pin-related CSS property has been set on an element.
+ * Call this when PinManager sets styles during pinning.
+ */
+export declare function registerPinnedProp(element: Element, prop: string): void;
+/**
+ * Register multiple pinned properties at once.
+ */
+export declare function registerPinnedProps(element: Element, props: string[]): void;
+/**
+ * Get all pin-related CSS properties that have been set on an element.
+ */
+export declare function getPinnedProps(element: Element): Set<string>;
+/**
+ * Clear tracking for pinned properties on an element.
+ */
+export declare function clearPinnedPropsRegistry(element: Element): void;
+/**
+ * Clear pin-related inline styles that our SDK has set on an element.
+ * Only clears properties tracked in the pin registry.
+ */
+export declare function clearPinStyles(element: Element): void;
+/**
+ * Clear pin styles and remove from registry.
+ * Use this for Motion.reset() to completely clean up pin styles.
+ */
+export declare function clearPinStylesAndUnregister(element: Element): void;

package/dist/utils/TargetResolver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TargetResolver - Convert various target formats to AnimationTarget array
+ *
+ * Supports both DOM elements and plain JS objects for universal animation.
+ */
+import type { AnimationTarget, TargetInput } from '../types';
+/**
+ * Execute callback when DOM is ready
+ * If DOM is already ready, executes immediately
+ */
+export declare function whenDOMReady(callback: () => void): void;
+/**
+ * Check if a resolved target is a DOM Element
+ * Used for caching _isElement flag in PropTween
+ * Also recognizes mock elements (objects with 'style' property) in test environments
+ */
+export declare function isElement(target: AnimationTarget): target is Element;
+/**
+ * Resolve animation targets to an array of AnimationTargets
+ * @param targets - CSS selector, string[], Element, NodeList, Element[], plain object, or object array
+ * @returns Array of resolved AnimationTargets (Element or ObjectTarget)
+ */
+export declare function resolveTargets(targets: TargetInput): AnimationTarget[];

package/dist/utils/TextSplitter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * TextSplitter - Split text into animatable elements
+ *
+ * Splits text content into chars, words, or lines wrapped in spans.
+ * Supports nested splitting (e.g., 'chars,words' = words containing char spans).
+ *
+ * Preserves existing element structure — inline elements like
+ * `<span class="accent">word</span>` keep their wrapper and styling.
+ * Only text nodes are replaced with split spans.
+ *
+ * Usage:
+ *   const elements = TextSplitter.split(element, 'chars');
+ *   const elements = TextSplitter.split(element, 'words');
+ *   const elements = TextSplitter.split(element, 'chars,words');
+ *
+ * Revert:
+ *   TextSplitter.revert(element);
+ */
+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;
+}
+interface SplitResult {
+    chars: HTMLElement[];
+    words: HTMLElement[];
+    lines: HTMLElement[];
+    elements: HTMLElement[];
+}
+export declare class TextSplitter {
+    /**
+     * Split text content into animatable elements
+     */
+    static split(element: Element, type: SplitType, options?: SplitOptions): HTMLElement[];
+    /**
+     * Split text nodes into word spans, preserving existing element wrappers.
+     * Recurses into child elements so `<span class="accent">word</span>` keeps
+     * its wrapper and the text inside is split within it.
+     */
+    private static _splitWordsDom;
+    /**
+     * Split text nodes into character spans, preserving existing element wrappers.
+     */
+    private static _splitCharsDom;
+    /**
+     * Split text nodes into word spans containing character spans.
+     * Preserves existing element wrappers.
+     */
+    private static _splitWordsWithCharsDom;
+    /**
+     * Split with line detection (requires layout measurement).
+     *
+     * Strategy:
+     * 1. DOM-walk to split into word spans (preserving element wrappers)
+     * 2. Measure each word span's vertical position to group into lines
+     * 3. Wrap each line group in a line span
+     */
+    private static _splitWithLinesDom;
+    /**
+     * Wrap each split element in a parent with overflow:hidden for clip-reveal.
+     * The wrapper clips content so animating y:'100%' creates a reveal effect.
+     */
+    private static _applyMaskWrappers;
+    /**
+     * Revert element to original content
+     */
+    static revert(element: Element): boolean;
+    /**
+     * Check if element has been split
+     */
+    static isSplit(element: Element): boolean;
+    /**
+     * Get split result for an element
+     */
+    static getResult(element: Element): SplitResult | undefined;
+    /**
+     * Get the chain of wrapper elements between a word span and the root element.
+     * Returns outermost-first order (root's direct child → … → word's parent).
+     */
+    private static _getWrapperChain;
+    /**
+     * Serialize an element's opening tag, preserving all attributes (class, style, data-*, etc).
+     */
+    private static _openTag;
+    /**
+     * Escape HTML special characters
+     */
+    private static _escapeHtml;
+}

package/dist/utils/executeTimelineAction.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimal interface for timeline playback control.
+ * Using an interface instead of importing Timeline directly to avoid circular dependencies
+ * (utils/ never imports from core/).
+ */
+export interface PlaybackTarget {
+    play(): unknown;
+    pause(): unknown;
+    reverse(): unknown;
+    restart(): unknown;
+    progress(value: number): unknown;
+}
+export type TimelineAction = 'play' | 'pause' | 'resume' | 'reverse' | 'restart' | 'reset' | 'complete' | 'none';
+/**
+ * Execute a GSAP-compatible timeline action. Maps action strings to method calls.
+ * Covers all 8 GSAP toggleActions keywords.
+ */
+export declare function executeTimelineAction(action: TimelineAction, timeline: PlaybackTarget): void;

package/dist/utils/getLayoutRect.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns the element's bounding rect as if no CSS transform were applied.
+ * Temporarily strips the inline transform, measures, then restores it.
+ * This gives us the "layout" position in the document flow.
+ *
+ * Used by ScrollTrigger and MarkerManager to compute trigger positions and
+ * marker placements relative to the element's original layout position,
+ * regardless of any animation transforms currently applied.
+ */
+export declare function getLayoutRect(element: Element): DOMRect;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@motion.page/sdk",
+  "version": "0.1.0",
+  "description": "High-performance CSS animation SDK with scroll, hover, gesture, and cursor triggers",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun build src/index.ts --outdir dist --minify --sourcemap=linked && mkdir -p dist/.cjs-tmp && bun build src/index.ts --outdir dist/.cjs-tmp --format=cjs --minify --sourcemap=linked && mv dist/.cjs-tmp/index.js dist/index.cjs && mv dist/.cjs-tmp/index.js.map dist/index.cjs.map && rm -rf dist/.cjs-tmp",
+    "test": "bun test",
+    "test:parity": "bun test tests/parity",
+    "test:bench": "bun test --bench",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^15.0.0",
+    "@types/bun": "latest",
+    "@types/jsdom": "^27.0.0",
+    "esbuild": "^0.27.2",
+    "jsdom": "^27.3.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {},
+  "keywords": [
+    "animation",
+    "gsap",
+    "tween",
+    "timeline",
+    "motion",
+    "css",
+    "transform"
+  ],
+  "author": "Motion.page",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicDamours/motion.page",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://motion.page",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": true
+}