File Structure

interface FmtionFile {
  meta: FmtionMeta;                              // Required
  smoothScroll?: SmoothScrollConfig;             // Optional
  parameters: Record<string, FmtionParameterDef>; // Required
  scrollBindings: FmtionScrollBinding[];         // Required
  listeners: InteractionListener[];              // Required
  pointerFollow?: PointerFollowEffect[];         // Optional
  dom: DomAnimation[];                           // Required
  canvas: CanvasArea[];                          // Required
  lottie?: LottieAnimation[];                    // Optional
  three?: ThreeDContent;                         // Optional
  assets?: AssetLibrary;                         // Optional
}

interface FmtionMeta {
  name: string;           // Required - Project name
  author?: string;        // Author name
  description?: string;   // Project description
  duration?: number;      // Total duration in milliseconds
  createdAt?: string;     // ISO 8601 creation timestamp
  modifiedAt?: string;    // ISO 8601 modification timestamp
}

{
  "meta": {
    "name": "Hero Animation",
    "author": "Design Team",
    "description": "Landing page hero section animations",
    "duration": 5000,
    "createdAt": "2026-01-01T00:00:00Z",
    "modifiedAt": "2026-01-01T12:00:00Z"
  }
}

interface SmoothScrollConfig {
  enabled?: boolean;           // Enable smooth scrolling (default: true)
  wrapper?: string;            // Outer wrapper selector (default: '#smooth-wrapper')
  content?: string;            // Inner content selector (default: '#smooth-content')
  smooth?: number;             // Smoothing amount - lower = smoother (default: 1)
  effects?: boolean;           // Enable parallax via data-speed (default: true)
  smoothTouch?: boolean;       // Enable on touch devices (default: false)
  normalizeScroll?: boolean;   // Normalize scroll across devices (default: false)
  momentum?: boolean;          // Enable momentum after release (default: false)
  momentumDecay?: number;      // Momentum decay per frame 0-1 (default: 0.95)
  momentumMinVelocity?: number; // Min velocity to continue (default: 0.5)
  ignoreMobileResize?: boolean; // Ignore mobile address bar (default: true)
}

{
  "smoothScroll": {
    "enabled": true,
    "wrapper": "#smooth-wrapper",
    "content": "#smooth-content",
    "smooth": 1.5,
    "effects": true,
    "momentum": true,
    "momentumDecay": 0.95
  }
}

type ParameterType = 'float' | 'int' | 'bool' | 'trigger';

interface FmtionParameterDef {
  type: ParameterType;           // Parameter type
  default: number | boolean;     // Default value
  name?: string;                 // Display name (for editor)
  min?: number;                  // Minimum value (float/int)
  max?: number;                  // Maximum value (float/int)
  step?: number;                 // Step increment (float/int)
  readOnly?: boolean;            // Cannot be modified
}

{
  "parameters": {
    "hero/scrollProgress": {
      "type": "float",
      "default": 0,
      "min": 0,
      "max": 1,
      "name": "Hero Scroll Progress"
    },
    "hero/hovered": {
      "type": "bool",
      "default": false
    },
    "menu/open": {
      "type": "bool",
      "default": false
    },
    "counter/value": {
      "type": "int",
      "default": 0,
      "min": 0,
      "max": 100,
      "step": 1
    },
    "form/submit": {
      "type": "trigger",
      "default": false
    }
  }
}

interface FmtionScrollBinding {
  id: string;                    // Unique binding ID
  parameter: string;             // Parameter path to drive
  trigger: string;               // CSS selector for trigger element
  start: string;                 // Start position
  end: string;                   // End position
  outputType?: 'float' | 'bool'; // Output type (default: 'float')
  threshold?: number;            // Threshold for bool output (default: 0.5)
  pin?: boolean;                 // Pin element during scroll
  pinSpacing?: boolean;          // Add spacing for pinned element
  scrub?: boolean | number;      // Smoothing factor (0-1)
}

{
  "scrollBindings": [
    {
      "id": "hero-scroll",
      "parameter": "hero/scrollProgress",
      "trigger": ".hero-section",
      "start": "top bottom",
      "end": "bottom top"
    },
    {
      "id": "fade-trigger",
      "parameter": "content/visible",
      "trigger": ".content",
      "start": "top 80%",
      "end": "top 50%",
      "outputType": "bool",
      "threshold": 0.5
    },
    {
      "id": "pinned-section",
      "parameter": "pinned/progress",
      "trigger": ".pinned",
      "start": "top top",
      "end": "+=200%",
      "pin": true,
      "pinSpacing": true,
      "scrub": 0.5
    }
  ]
}

type InteractionEvent =
  | 'click' | 'dblclick'
  | 'mouseenter' | 'mouseleave' | 'mousedown' | 'mouseup' | 'mousemove'
  | 'focus' | 'blur'
  | 'pointerenter' | 'pointerleave' | 'pointerdown' | 'pointerup'
  | 'touchstart' | 'touchend'
  | 'keydown' | 'keyup'
  | 'scroll' | 'resize';

interface InteractionAction {
  set: string;                   // Parameter path to modify
  value: number | boolean | 'toggle' | 'fire' | 'increment' | 'decrement';
  amount?: number;               // Amount for increment/decrement
  delay?: number;                // Delay before executing (ms)
}

interface InteractionListener {
  id: string;                    // Unique listener ID
  target: string;                // CSS selector for target
  event: InteractionEvent;       // DOM event to listen for
  actions: InteractionAction[];  // Actions to execute
  condition?: string;            // Condition expression
  preventDefault?: boolean;      // Prevent default behavior
  stopPropagation?: boolean;     // Stop event propagation
  debounce?: number;             // Debounce time in ms
  throttle?: number;             // Throttle time in ms
}

{
  "listeners": [
    {
      "id": "hero-hover-enter",
      "target": ".hero-card",
      "event": "mouseenter",
      "actions": [
        { "set": "hero/hovered", "value": true }
      ]
    },
    {
      "id": "menu-toggle",
      "target": ".menu-button",
      "event": "click",
      "actions": [
        { "set": "menu/open", "value": "toggle" }
      ],
      "preventDefault": true
    },
    {
      "id": "delayed-action",
      "target": ".delayed-trigger",
      "event": "click",
      "actions": [
        { "set": "step/one", "value": true },
        { "set": "step/two", "value": true, "delay": 500 },
        { "set": "step/three", "value": true, "delay": 1000 }
      ]
    }
  ]
}

type DriverType = 'scroll' | 'bool' | 'float';

interface DomAnimation {
  id?: string;                    // Unique animation ID
  selector: string;               // CSS selector for target
  driver?: string;                // Parameter path that drives animation
  driverType?: DriverType;        // How driver controls animation
  from: Record<string, number | string>;  // Start values
  to: Record<string, number | string>;    // End values
  ease?: string;                  // Easing function
  duration?: number;              // Duration in ms (for bool driver)
  delay?: number;                 // Delay before starting
  reverseOnFalse?: boolean;       // Reverse when driver becomes false
  splitText?: 'chars' | 'words' | 'lines'; // Split text for stagger
  stagger?: number;               // Stagger delay between elements
  path?: string;                  // SVG path for motion path
  pathCoords?: 'percentage' | 'pixels'; // Path coordinate system
}

x, y, rotation, scale, scaleX, scaleY, opacity,
width, height, borderRadius, backgroundColor, color,
translateX, translateY, rotate, skewX, skewY

{
  "dom": [
    {
      "id": "hero-fade",
      "selector": ".hero-title",
      "driver": "hero/scrollProgress",
      "driverType": "scroll",
      "from": { "opacity": 0, "y": 50 },
      "to": { "opacity": 1, "y": 0 },
      "ease": "easeOutCubic"
    },
    {
      "id": "text-reveal",
      "selector": ".reveal-text",
      "driver": "content/visible",
      "driverType": "bool",
      "from": { "opacity": 0, "y": 30 },
      "to": { "opacity": 1, "y": 0 },
      "splitText": "lines",
      "stagger": 0.1,
      "duration": 600
    }
  ]
}

interface AssetLibrary {
  images?: ImageAsset[];
  fonts?: FontAsset[];
  audio?: AudioAsset[];
  paths?: PathAsset[];
}

interface ImageAsset {
  id: string;
  name: string;
  src: string;
  width?: number;
  height?: number;
}

interface FontAsset {
  id: string;
  family: string;
  src: string;
  weight?: string;
  style?: string;
}

interface AudioAsset {
  id: string;
  name: string;
  src: string;
  duration?: number;
}

interface PathAsset {
  id: string;
  name: string;
  d: string;           // SVG path data
  closed?: boolean;
}

{
  "assets": {
    "images": [
      {
        "id": "hero-bg",
        "name": "Hero Background",
        "src": "/images/hero-bg.jpg",
        "width": 1920,
        "height": 1080
      }
    ],
    "fonts": [
      {
        "id": "heading-font",
        "family": "Inter",
        "src": "/fonts/Inter-Bold.woff2",
        "weight": "700"
      }
    ],
    "paths": [
      {
        "id": "wave-path",
        "name": "Wave Path",
        "d": "M0,100 Q250,0 500,100 T1000,100",
        "closed": false
      }
    ]
  }
}

interface PointerFollowEffect {
  id: string;
  name?: string;
  trigger: string;              // CSS selector that triggers effect
  images: string;               // Selector for images to animate
  showInterval?: number;        // Min interval between images (ms)
  visibleDuration?: number;     // How long images stay visible (ms)
  offsets?: PointerFollowOffset[];
  randomRotation?: number;      // Random rotation range
  showAnimation?: { ... };
  hideAnimation?: { ... };
  imageStyles?: { ... };
}

{
  "pointerFollow": [
    {
      "id": "portfolio-images",
      "trigger": ".portfolio-link",
      "images": ".follow-image",
      "showInterval": 120,
      "visibleDuration": 1500,
      "randomRotation": 10,
      "offsets": [
        { "x": -150, "y": -100, "rotation": -12 },
        { "x": 130, "y": -80, "rotation": 8 }
      ],
      "showAnimation": {
        "duration": 400,
        "ease": "easeOutBack",
        "fromOpacity": 0,
        "fromScale": 0.5
      },
      "hideAnimation": {
        "duration": 800,
        "ease": "easeInCubic",
        "toOpacity": 0
      }
    }
  ]
}

{
  "easing": {
    "type": "bezier",
    "controlPoints": [0.68, -0.55, 0.265, 1.55]
  }
}