# animotion-saply

A lightweight GSAP-based animation handler that enables declarative motion via HTML data attributes.
Ideal for ScrollTrigger, SplitText, and attribute-driven WebGL shader scenes.

For a full non-programmer walkthrough, read:
`COMPLETE-BEGINNER-GUIDE.md`

## Installation
```bash
npm install animotion-saply
```

## Runtime Requirements

`animotion-saply` expects these globals to be available at runtime:
- `gsap`
- `ScrollTrigger`
- `SplitText`

The package now ships with:
- ESM build: `dist/animotion-saply.esm.mjs`
- CJS build: `dist/animotion-saply.cjs`
- CDN/IIFE build: `dist/animotion-saply.min.js`

## Usage

### npm (ESM / client-side)
```js
import "animotion-saply";
// or:
// import { initAnimotionSaply } from "animotion-saply";
// initAnimotionSaply();
```

### npm (CommonJS)
```js
require("animotion-saply");
```

### CDN script
```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/SplitText.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/animotion-saply/dist/animotion-saply.min.js"></script>
```

## Using Each Build File Directly

### 1) `dist/animotion-saply.min.js` (IIFE / browser script tag)
Use this in plain HTML pages, CMS pages, or when loading from CDN.

```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/SplitText.min.js"></script>
<script src="/dist/animotion-saply.min.js"></script>
```

If installed from npm and copied by your build tool:

```html
<script src="/node_modules/animotion-saply/dist/animotion-saply.min.js"></script>
```

### 2) `dist/animotion-saply.esm.mjs` (ES Module import)
Use this for Vite, modern Webpack, Rollup, or client-side modules.

```js
import "animotion-saply";
```

Direct file import:

```js
import { initAnimotionSaply } from "animotion-saply/dist/animotion-saply.esm.mjs";
initAnimotionSaply();
```

### 3) `dist/animotion-saply.cjs` (CommonJS require)
Use this in CommonJS environments.

```js
require("animotion-saply");
```

Direct file require:

```js
const { initAnimotionSaply } = require("animotion-saply/dist/animotion-saply.cjs");
initAnimotionSaply();
```

### Quick Selection Guide
- Use `animotion-saply.min.js` for `<script>` tags and CDN usage.
- Use `animotion-saply.esm.mjs` for modern `import` workflows.
- Use `animotion-saply.cjs` for `require()` workflows.

## WebGL Shader Presets (Attribute-based)

Use declarative WebGL presets without writing GLSL:

```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="hero-shader"
  data-gsap-webgl-preset="aurora"
  data-gsap-webgl-props='{
    "autoplay": true,
    "maxDpr": 2,
    "scrollTrigger": { "start": "top bottom", "end": "bottom top", "scrub": true }
  }'
  data-gsap-webgl-preset-props='{ "u_intensity": 0.95, "u_speed": 0.7 }'
></section>
```

Supported presets:

`aurora`, `liquid`, `plasma`, `nebula`, `vortex`, `waves`, `ripples`, `marble`, `glitch`, `pixelate`, `halftone`, `tunnel`, `gridflow`, `metaball`, `fire`, `caustics`, `clouds`, `rainbowflow`, `monoscan`, `crt`, `kaleidoscope`, `chromaticshift`, `lenswarp`, `swirl`, `topography`, `matrixrain`, `lava`, `snow`, `sandstorm`, `inkblot`, `sonar`, `sunrise`, `moire`, `electric`, `checkerwarp`, `dreamscape`, `wireframe`, `bloomfield`, `ditherwave`

Key attributes:

- `data-gsap-webgl`: enables shader scene
- `data-gsap-webgl-id`: unique scene ID for controls
- `data-gsap-webgl-preset`: preset name
- `data-gsap-webgl-props`: renderer + behavior config
- `data-gsap-webgl-preset-props`: override preset uniform defaults
- `data-gsap-webgl-uniforms`: custom uniforms
- `data-gsap-webgl-textures`: texture bindings
- `data-gsap-webgl-scroll`: scroll behavior config
- `data-gsap-webgl-tween`: GSAP uniform tween list
- `data-gsap-webgl-control`: global scene control entries (`selector|event|sceneID|command`)
- `data-gsap-webgl-project`: load reusable scene project by name
- `data-gsap-webgl-scene`: scene authoring JSON (`layers`, `passes`, `keyframes`)
- `data-gsap-webgl-passes`: post-FX stack JSON
- `data-gsap-webgl-keyframes`: keyframe timeline JSON
- `data-gsap-webgl-authoring="true"`: authoring panel overlay
- `data-gsap-webgl-vertex`, `data-gsap-webgl-fragment`: inline custom shaders
- `data-gsap-webgl-vertex-id`, `data-gsap-webgl-fragment-id`: shader source from DOM script nodes

Built-in uniforms available to presets/custom shaders:

- `u_time`
- `u_resolution`
- `u_mouse`
- `u_scroll`
- `u_progress`
- `u_pixelRatio`
- `u_intensity`
- `u_speed`
- `u_scale`
- `u_seed`
- `u_colorA`
- `u_colorB`
- `u_colorC`

Debug:

- `window.__GSAP_WEBGL_SCENES__`
- `window.__GSAP_WEBGL_PRESETS__`
- `window.__GSAP_WEBGL_PRESET_CATEGORIES__`
- `window.__GSAP_WEBGL_POSTFX__`
- `window.__GSAP_WEBGL_PROJECTS__`

## Preset Categories

- Hero backgrounds: `aurora`, `nebula`, `dreamscape`, `sunrise`, `clouds`, `rainbowflow`
- Liquid/energy: `liquid`, `waves`, `ripples`, `caustics`, `vortex`, `swirl`
- Tech/cyber: `crt`, `matrixrain`, `monoscan`, `gridflow`, `wireframe`, `electric`
- Glitch/experimental: `glitch`, `chromaticshift`, `pixelate`, `halftone`, `moire`, `ditherwave`
- Cinematic/depth: `tunnel`, `lenswarp`, `kaleidoscope`, `checkerwarp`, `plasma`, `topography`
- Organic/material: `marble`, `metaball`, `lava`, `fire`, `sandstorm`, `inkblot`, `snow`, `bloomfield`
- Interactive/reactive: `sonar`, `ripples`, `metaball`, `vortex`, `electric`, `kaleidoscope`

## Starter Snippets

### 1) Hero Background (slow ambient)
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="hero-bg"
  data-gsap-webgl-preset="dreamscape"
  data-gsap-webgl-props='{"autoplay":true,"maxDpr":2}'
  data-gsap-webgl-preset-props='{"u_intensity":0.82,"u_speed":0.35,"u_scale":1.15}'
></section>
```

### 2) Scroll-Reactive Section Transition
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="section-transition"
  data-gsap-webgl-preset="kaleidoscope"
  data-gsap-webgl-props='{
    "autoplay": true,
    "scrollTrigger": {"start":"top bottom","end":"bottom top","scrub":true}
  }'
  data-gsap-webgl-preset-props='{"u_intensity":0.9,"u_speed":0.7}'
></section>
```

### 3) Interactive Card Hover Aura
```html
<article
  data-gsap-webgl
  data-gsap-webgl-id="card-aura"
  data-gsap-webgl-preset="sonar"
  data-gsap-webgl-props='{"autoplay":true,"maxDpr":1.5}'
  data-gsap-webgl-preset-props='{"u_intensity":0.95,"u_speed":1.0,"u_scale":0.9}'
></article>
```

### 4) Tech Hero (cyber dashboard style)
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="tech-hero"
  data-gsap-webgl-preset="matrixrain"
  data-gsap-webgl-props='{"autoplay":true}'
  data-gsap-webgl-preset-props='{"u_intensity":0.92,"u_speed":1.25}'
></section>
```

### 5) CTA Strip (high-energy)
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="cta-strip"
  data-gsap-webgl-preset="electric"
  data-gsap-webgl-props='{"autoplay":true}'
  data-gsap-webgl-preset-props='{"u_intensity":1.0,"u_speed":1.2,"u_scale":1.4}'
></section>
```

### 6) Scene Control Example
```html
<button class="pause-scene">Pause</button>
<button class="play-scene">Play</button>

<div
  data-gsap-webgl-control=".pause-scene|click|hero-bg|pause,.play-scene|click|hero-bg|play"
></div>
```

## Advanced Engine

### Multi-pass Post FX Stack
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="fx-scene"
  data-gsap-webgl-preset="nebula"
  data-gsap-webgl-passes='[
    {"type":"bloom","uniforms":{"u_amount":0.35,"u_radius":1.6}},
    {"type":"chromatic","uniforms":{"u_amount":0.01}},
    {"type":"vignette","uniforms":{"u_amount":0.22}}
  ]'
></section>
```

Built-in post FX:
`bloom`, `vignette`, `grain`, `chromatic`, `pixelate`

### Node/Material Graph (Layer-level)
```html
<section
  data-gsap-webgl
  data-gsap-webgl-scene='{
    "layers":[
      {
        "id":"graph-layer",
        "graph":{
          "nodes":[
            {"id":"n1","type":"fbm","input":"p * 2.2 + t * 0.2"},
            {"id":"n2","type":"palette","t":"n1","a":"u_colorA","b":"u_colorB","c":"vec3(1.0)","d":"u_colorC"}
          ],
          "output":"n2"
        }
      }
    ]
  }'
></section>
```

### Scene Authoring (Layers + Keyframes + Reusable Projects)
```html
<section
  data-gsap-webgl
  data-gsap-webgl-id="author-scene"
  data-gsap-webgl-project="cinematic-hero"
  data-gsap-webgl-authoring="true"
  data-gsap-webgl-scene='{
    "layers":[
      {"id":"base","preset":"dreamscape","blend":"normal","uniforms":{"u_intensity":0.8}},
      {"id":"accent","preset":"electric","blend":"screen","uniforms":{"u_intensity":0.3}}
    ],
    "keyframes":[
      {"target":"layer:base.u_speed","from":0.3,"to":0.8,"duration":4,"position":0,"ease":"sine.inOut"},
      {"target":"layer:accent.u_intensity","from":0.2,"to":0.6,"duration":3,"position":0.5,"ease":"sine.inOut"}
    ]
  }'
></section>
```

Control commands in `data-gsap-webgl-control`:
- `play`, `pause`, `toggle`, `restart`, `seek:0.5`
- `timeline:play`, `timeline:pause`, `timeline:seek:0.5`
- `setUniform:u_intensity:0.9`
- `setLayerUniform:base:u_intensity:0.9`
- `layerVisible:accent:false`
- `saveProject:my-project-name`

## Three.js + GLTF (Attribute-driven)

This project now supports declarative Three.js scenes with GLTF, GSAP ScrollTrigger mappings, and non-scroll interactions.

### Runtime requirement
Load these before using `data-gsap-three`:
- `THREE`
- `GLTFLoader` (for GLTF files)
- `OrbitControls` (optional, only if orbit interaction is enabled)

### Basic GLTF scene
```html
<section
  data-gsap-three
  data-gsap-three-id="phone-hero"
  data-gsap-three-model="/models/phone.glb"
  data-gsap-three-props='{
    "fov": 42,
    "cameraZ": 4.8,
    "ambientIntensity": 0.9,
    "directionalIntensity": 1.2,
    "playAllClips": true
  }'
></section>
```

### ScrollTrigger mapping (animate model/camera/material/light paths)
```html
<section
  data-gsap-three
  data-gsap-three-id="watch-scene"
  data-gsap-three-model="/models/watch.glb"
  data-gsap-three-scroll='{
    "start": "top top",
    "end": "bottom bottom",
    "scrub": true,
    "tracks": [
      {"path":"model.rotation.y","from":0,"to":6.28318},
      {"path":"camera.position.z","from":5.2,"to":3.8},
      {"path":"light:key.intensity","from":0.8,"to":1.6},
      {"path":"material:Glass.roughness","from":0.2,"to":0.05}
    ]
  }'
></section>
```

### Non-scroll interactions (without ScrollTrigger)
```html
<section
  data-gsap-three
  data-gsap-three-id="shoe-interactive"
  data-gsap-three-model="/models/shoe.glb"
  data-gsap-three-interactions='{
    "orbitControls": true,
    "enableZoom": true,
    "enablePan": false,
    "hover": {"enabled": true, "scale": 1.06},
    "dragRotate": {"enabled": true, "axis": "y", "sensitivity": 0.006},
    "parallax": {"enabled": true, "strength": 0.28, "duration": 0.3},
    "autoRotate": false,
    "clickMap": [
      {"object":"Laces","command":"set:object:Laces.material.metalness:0.9"},
      {"object":"Sole","command":"set:object:Sole.material.roughness:0.35"}
    ]
  }'
></section>
```

### Global controls
```html
<button class="play-scene">Play</button>
<button class="pause-scene">Pause</button>
<button class="spin-half">Spin 50%</button>
<button class="clip-run">Run Clip</button>

<div
  data-gsap-three-control="
    .play-scene|click|shoe-interactive|play,
    .pause-scene|click|shoe-interactive|pause,
    .spin-half|click|shoe-interactive|seek:0.5,
    .clip-run|click|shoe-interactive|actionPlay:Run
  "
></div>
```

### Supported Three command patterns (`data-gsap-three-control`)
- `play`, `pause`, `toggle`, `restart`, `seek:0.5`
- `set:camera.position.z:3.8`
- `set:model.rotation.y:1.57`
- `set:object:Wheel_FL.rotation.x:12.56`
- `actionPlay:ClipName`
- `actionStop:ClipName`
- `actionCrossFade:Idle:Run:0.6`

### Supported reference tokens in paths
- `model.*`
- `camera.*`
- `scene.*`
- `group.*`
- `renderer.*`
- `object:ObjectName.*`
- `material:MaterialName.*`
- `light:LightName.*`

Debug registry:
- `window.__GSAP_THREE_SCENES__`