loopwind 0.21.0 → 0.23.0

package/website/dist/llm.txt

@@ -1,7 +1,7 @@
 # loopwind - Complete Documentation for LLMs
 
 This is a comprehensive, single-file documentation for loopwind, optimized for LLM consumption.
-Generated: 2025-11-20T11:24:11.500Z
+Generated: 2025-12-15T21:23:12.229Z
 
 ---
 
@@ -750,8 +750,8 @@ Create animated videos programmatically using React components. Perfect for auto
 # Render a video template with inline props
 loopwind render video-intro '{"title":"Welcome!"}' --out intro.mp4
 
-# With custom encoding
-loopwind render video-intro '{"title":"Welcome!"}' --preset ultrafast
+# Faster encoding with FFmpeg (requires FFmpeg installed)
+loopwind render video-intro '{"title":"Welcome!"}' --ffmpeg
 
 # Or use a props file
 loopwind render video-intro props.json --out intro.mp4
@@ -918,29 +918,52 @@ export const meta = {
 
 ## Encoding Options
 
-### Default (Balanced)
+loopwind supports two encoding backends:
+
+### WASM Encoder (Default)
 
 ```bash
 loopwind render video-intro '{"title":"Welcome"}'
 ```
 
-Uses H.264 codec with good quality/size balance.
+Pure JavaScript/WASM H.264 encoder. **Serverless-compatible** - works on Vercel, Cloudflare Workers, AWS Lambda, and anywhere JavaScript runs.
 
-### Fast Encoding
+### FFmpeg Encoder (Faster)
 
 ```bash
-loopwind render video-intro '{"title":"Welcome"}' --preset ultrafast
+loopwind render video-intro '{"title":"Welcome"}' --ffmpeg
 ```
 
-Faster encoding, slightly larger files. Good for previews.
+Uses FFmpeg for **2x faster encoding** and smaller file sizes. Requires FFmpeg installed on your system.
+
+**Install FFmpeg:**
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+winget install ffmpeg
+```
 
-### High Quality
+### Quality Settings
 
 ```bash
-loopwind render video-intro '{"title":"Welcome"}' --preset slow
+# Higher quality (lower CRF = better quality, default: 23)
+loopwind render video-intro '{"title":"Welcome"}' --crf 18
+
+# Lower quality, smaller files
+loopwind render video-intro '{"title":"Welcome"}' --crf 28
 ```
 
-Better compression, slower encoding. Good for final output.
+### When to Use Each
+
+| Encoder | Use Case |
+|---------|----------|
+| **WASM (default)** | Serverless, CI/CD, no dependencies needed |
+| **FFmpeg (`--ffmpeg`)** | Local development, faster iteration, smaller files |
 
 ## Performance
 
@@ -1551,6 +1574,122 @@ Add an easing class **before** the animation class to control the timing curve.
 | `ease-out-quart` | Very strong fast start | Punchy entrances |
 | `ease-in-out-quart` | Very strong both ends | Maximum drama |
 
+### Per-Animation-Type Easing
+
+You can apply **different easing functions** to enter, exit, and loop animations on the same element using `enter-ease-*`, `exit-ease-*`, and `loop-ease-*` classes.
+
+```tsx
+// Different easing for enter and exit
+<h1 style={tw('enter-ease-out-cubic enter-fade-in/0/500 exit-ease-in exit-fade-out/2500/500')}>
+  Smooth entrance, sharp exit
+</h1>
+
+// Loop with linear easing, enter with bounce
+<div style={tw('enter-ease-out enter-bounce-in/0/400 loop-ease-linear loop-fade/1000')}>
+  Bouncy entrance, linear loop
+</div>
+
+// Default easing still works (applies to all animations)
+<div style={tw('ease-in-out enter-fade-in/0/500 exit-fade-out/2500/500')}>
+  Same easing for both
+</div>
+
+// Mix default with specific overrides
+<div style={tw('ease-out enter-fade-in/0/500 exit-ease-in-cubic exit-fade-out/2500/500')}>
+  Default ease-out for enter, cubic-in for exit
+</div>
+```
+
+**How it works:**
+
+1. **Default easing** (`ease-*`) applies to ALL animations if no specific override is set
+2. **Specific easing** (`enter-ease-*`, `exit-ease-*`, `loop-ease-*`) overrides the default for that animation type
+3. If both are present, specific easing takes priority for its animation type
+
+**Available easing classes:**
+
+| Default (all animations) | Enter only | Exit only | Loop only |
+|--------------------------|------------|-----------|-----------|
+| `ease-in` | `enter-ease-in` | `exit-ease-in` | `loop-ease-in` |
+| `ease-out` | `enter-ease-out` | `exit-ease-out` | `loop-ease-out` |
+| `ease-in-out` | `enter-ease-in-out` | `exit-ease-in-out` | `loop-ease-in-out` |
+| `ease-in-cubic` | `enter-ease-in-cubic` | `exit-ease-in-cubic` | `loop-ease-in-cubic` |
+| `ease-out-cubic` | `enter-ease-out-cubic` | `exit-ease-out-cubic` | `loop-ease-out-cubic` |
+| `ease-in-out-cubic` | `enter-ease-in-out-cubic` | `exit-ease-in-out-cubic` | `loop-ease-in-out-cubic` |
+| `ease-in-quart` | `enter-ease-in-quart` | `exit-ease-in-quart` | `loop-ease-in-quart` |
+| `ease-out-quart` | `enter-ease-out-quart` | `exit-ease-out-quart` | `loop-ease-out-quart` |
+| `ease-in-out-quart` | `enter-ease-in-out-quart` | `exit-ease-in-out-quart` | `loop-ease-in-out-quart` |
+| `linear` | `enter-ease-linear` | `exit-ease-linear` | `loop-ease-linear` |
+| `ease-spring` | `enter-ease-spring` | `exit-ease-spring` | `loop-ease-spring` |
+
+### Spring Easing
+
+Spring easing creates natural, physics-based bouncy animations. Use the built-in `ease-spring` easing or create custom springs with configurable parameters.
+
+```tsx
+// Default spring easing
+<h1 style={tw('ease-spring enter-bounce-in/0/500')}>Bouncy spring!</h1>
+
+// Per-animation-type spring
+<div style={tw('enter-ease-spring enter-fade-in/0/500 exit-ease-out exit-fade-out/2500/500')}>
+  Spring entrance, smooth exit
+</div>
+
+// Custom spring with parameters: ease-spring/mass/stiffness/damping
+<h1 style={tw('ease-spring/1/100/10 enter-scale-in/0/800')}>
+  Custom spring (mass=1, stiffness=100, damping=10)
+</h1>
+
+// More bouncy spring (lower damping)
+<div style={tw('ease-spring/1/170/8 enter-bounce-in-up/0/600')}>
+  Extra bouncy!
+</div>
+
+// Stiffer spring (higher stiffness, faster)
+<div style={tw('ease-spring/1/200/12 enter-fade-in-up/0/400')}>
+  Snappy spring
+</div>
+
+// Per-animation-type custom springs
+<div style={tw('enter-ease-spring/1/150/10 enter-fade-in/0/500 exit-ease-spring/1/100/15 exit-fade-out/2500/500')}>
+  Different springs for enter and exit
+</div>
+```
+
+**Spring parameters:**
+
+| Parameter | Description | Effect when increased | Default |
+|-----------|-------------|----------------------|---------|
+| **mass** | Mass of the spring | Slower, more inertia | 1 |
+| **stiffness** | Spring stiffness | Faster, snappier | 100 |
+| **damping** | Damping coefficient | Less bounce, smoother | 10 |
+
+**Common spring presets:**
+
+```tsx
+// Gentle bounce (default)
+ease-spring/1/100/10
+
+// Extra bouncy
+ease-spring/1/170/8
+
+// Snappy (no bounce)
+ease-spring/1/200/15
+
+// Slow and bouncy
+ease-spring/2/100/8
+
+// Fast and tight
+ease-spring/0.5/300/20
+```
+
+**How spring works:**
+
+1. **Default `ease-spring`** - Uses a pre-calculated spring curve optimized for most use cases
+2. **Custom `ease-spring/mass/stiffness/damping`** - Generates a physics-based spring curve using the [damped harmonic oscillator](https://www.kvin.me/css-springs) formula
+3. The spring automatically calculates its ideal duration to reach the final state
+4. Works with all animation types: `ease-spring`, `enter-ease-spring`, `exit-ease-spring`, `loop-ease-spring`
+
 ## Combining Enter and Exit
 
 You can use both enter and exit animations on the same element:
@@ -1793,7 +1932,7 @@ export default function CustomEasing({ tw, progress, title }) {
 ### When to Use Programmatic Animations
 
 Use `progress`/`frame` instead of animation classes when you need:
-- **Custom easing functions** (elastic, spring, bounce with specific curves)
+- **Custom easing functions** (elastic, bounce with specific curves beyond built-in ease-spring)
 - **Color cycling or gradients** based on time
 - **Mathematical animations** (sine waves, spirals, etc.)
 - **Complex multi-property animations** that need precise coordination
@@ -1801,6 +1940,498 @@ Use `progress`/`frame` instead of animation classes when you need:
 
 For everything else, prefer animation classes - they're simpler and more maintainable.
 
+### Animating Along Paths
+
+Animate elements along SVG paths with proper rotation using built-in **path helpers**:
+
+```tsx
+export default function PathFollowing({ tw, progress, path }) {
+  // Follow a quadratic Bezier curve - one line!
+  const rocket = path.followQuadratic(
+    { x: 200, y: 400 },   // Start point
+    { x: 960, y: 150 },   // Control point
+    { x: 1720, y: 400 },  // End point
+    progress
+  );
+
+  return (
+    <div style={{ display: 'flex', ...tw('relative w-full h-full bg-gray-900') }}>
+      {/* Draw the path (optional) */}
+      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
+        <path
+          d="M 200 400 Q 960 150 1720 400"
+          stroke="rgba(255,255,255,0.2)"
+          strokeWidth={2}
+          fill="none"
+        />
+      </svg>
+
+      {/* Element following the path */}
+      <div
+        style={{
+          position: "absolute",
+          left: rocket.x,
+          top: rocket.y,
+          transform: `translate(-50%, -50%) rotate(${rocket.angle}deg)`,
+          fontSize: '48px'
+        }}
+      >
+        🚀
+      </div>
+    </div>
+  );
+}
+```
+
+### Text Path Animations
+
+Combine `textPath` helpers with animation classes to create animated text along curves:
+
+**Rotating text around a circle:**
+```tsx
+export default function RotatingCircleText({ tw, textPath, progress }) {
+  return (
+    <div style={tw('relative w-full h-full bg-black')}>
+      {/* Text rotates around circle using progress */}
+      {textPath.onCircle(
+        "SPINNING TEXT • AROUND • ",
+        960,      // center x
+        540,      // center y
+        400,      // radius
+        progress, // rotation offset (0-1 animates full rotation)
+        {
+          fontSize: "3xl",
+          fontWeight: "bold",
+          color: "yellow-300"
+        }
+      )}
+    </div>
+  );
+}
+```
+
+**Animated text reveal along a path:**
+```tsx
+export default function PathTextReveal({ tw, textPath, progress }) {
+  // Create custom path follower that animates position
+  const pathFollower = (t) => {
+    // Only show characters up to current progress
+    const visibleProgress = progress * 1.5; // Extend range for smooth reveal
+    const opacity = t < visibleProgress ? 1 : 0;
+
+    // Follow quadratic curve
+    const pos = {
+      x: (1 - t) * (1 - t) * 200 + 2 * (1 - t) * t * 960 + t * t * 1720,
+      y: (1 - t) * (1 - t) * 400 + 2 * (1 - t) * t * 150 + t * t * 400,
+      angle: 0
+    };
+
+    return { ...pos, opacity };
+  };
+
+  return (
+    <div style={tw('relative w-full h-full bg-gray-900')}>
+      {textPath.onPath(
+        "REVEALING TEXT",
+        pathFollower,
+        {
+          fontSize: "4xl",
+          fontWeight: "bold",
+          color: "blue-300"
+        }
+      ).map((char, i) => (
+        <div key={i} style={{ ...char.props.style, opacity: char.props.style.opacity || 1 }}>
+          {char}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Staggered character entrance:**
+```tsx
+export default function StaggeredCircleText({ tw, textPath }) {
+  const text = "HELLO WORLD";
+
+  return (
+    <div style={tw('relative w-full h-full bg-slate-900')}>
+      {textPath.onCircle(
+        text,
+        960, 540, 400, 0,
+        { fontSize: "4xl", fontWeight: "bold", color: "white" }
+      ).map((char, i) => {
+        // Stagger fade-in: each character starts 50ms later
+        const staggerDelay = i * 50;
+        return (
+          <div
+            key={i}
+            style={{
+              ...char.props.style,
+              ...tw(`enter-fade-in/${staggerDelay}/300 enter-scale-100/${staggerDelay}/300`)
+            }}
+          >
+            {char.props.children}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+**Text with bounce entrance along arc:**
+```tsx
+export default function BouncyArcText({ tw, textPath }) {
+  return (
+    <div style={tw('relative w-full h-full bg-gradient-to-br from-purple-600 to-blue-500')}>
+      {/* Draw the arc path */}
+      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
+        <path
+          d="M 300 900 A 600 600 0 0 1 1620 900"
+          stroke="rgba(255,255,255,0.2)"
+          strokeWidth={2}
+          fill="none"
+          strokeDasharray="5 5"
+        />
+      </svg>
+
+      {/* Text follows arc with staggered bounce */}
+      {textPath.onArc(
+        "BOUNCING ON ARC",
+        960,  // cx
+        300,  // cy
+        600,  // radius
+        180,  // start angle
+        360,  // end angle
+        { fontSize: "3xl", fontWeight: "bold", color: "white" }
+      ).map((char, i) => (
+        <div
+          key={i}
+          style={{
+            ...char.props.style,
+            ...tw(`ease-out enter-bounce-in-up/${i * 80}/500`)
+          }}
+        >
+          {char.props.children}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Loop animation with text on curve:**
+```tsx
+export default function LoopingCurveText({ tw, textPath, frame }) {
+  // Calculate wave effect using frame
+  const waveOffset = Math.sin(frame / 30 * Math.PI * 2) * 0.1;
+
+  return (
+    <div style={tw('relative w-full h-full bg-black')}>
+      {textPath.onQuadratic(
+        "WAVY TEXT",
+        { x: 200, y: 400 },
+        { x: 960, y: 150 },
+        { x: 1720, y: 400 },
+        { fontSize: "4xl", fontWeight: "bold", color: "pink-300" }
+      ).map((char, i) => (
+        <div
+          key={i}
+          style={{
+            ...char.props.style,
+            transform: `${char.props.style.transform} translateY(${Math.sin((i + frame) / 5) * 10}px)`
+          }}
+        >
+          {char.props.children}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+**Tips for animating text paths:**
+1. **Use `progress` for smooth rotation** on circles and arcs
+2. **Map over returned characters** to apply individual animations
+3. **Combine with animation classes** like `enter-fade-in`, `enter-bounce-in`, etc.
+4. **Stagger character animations** by calculating delays: `i * delayMs`
+5. **Use `frame` for continuous effects** like waves or pulsing
+6. **Preserve the original transform** when adding animations: `transform: '${char.props.style.transform} ...'`
+
+**Common path types:**
+
+**Quadratic Bezier** (Q command):
+```tsx
+// Position: (1-t)²·P0 + 2(1-t)t·P1 + t²·P2
+function pointOnQuadraticBezier(p0, p1, p2, t) {
+  const x = (1 - t) * (1 - t) * p0.x + 2 * (1 - t) * t * p1.x + t * t * p2.x;
+  const y = (1 - t) * (1 - t) * p0.y + 2 * (1 - t) * t * p1.y + t * t * p2.y;
+  return { x, y };
+}
+
+// Tangent angle
+function angleOnQuadraticBezier(p0, p1, p2, t) {
+  const dx = 2 * (1 - t) * (p1.x - p0.x) + 2 * t * (p2.x - p1.x);
+  const dy = 2 * (1 - t) * (p1.y - p0.y) + 2 * t * (p2.y - p1.y);
+  return Math.atan2(dy, dx) * (180 / Math.PI);
+}
+```
+
+**Cubic Bezier** (C command):
+```tsx
+// Position: (1-t)³·P0 + 3(1-t)²t·P1 + 3(1-t)t²·P2 + t³·P3
+function pointOnCubicBezier(p0, p1, p2, p3, t) {
+  const mt = 1 - t;
+  const mt2 = mt * mt;
+  const mt3 = mt2 * mt;
+  const t2 = t * t;
+  const t3 = t2 * t;
+  const x = mt3 * p0.x + 3 * mt2 * t * p1.x + 3 * mt * t2 * p2.x + t3 * p3.x;
+  const y = mt3 * p0.y + 3 * mt2 * t * p1.y + 3 * mt * t2 * p2.y + t3 * p3.y;
+  return { x, y };
+}
+
+// Tangent angle
+function angleOnCubicBezier(p0, p1, p2, p3, t) {
+  const mt = 1 - t;
+  const mt2 = mt * mt;
+  const t2 = t * t;
+  const dx = -3 * mt2 * p0.x + 3 * mt2 * p1.x - 6 * mt * t * p1.x - 3 * t2 * p2.x + 6 * mt * t * p2.x + 3 * t2 * p3.x;
+  const dy = -3 * mt2 * p0.y + 3 * mt2 * p1.y - 6 * mt * t * p1.y - 3 * t2 * p2.y + 6 * mt * t * p2.y + 3 * t2 * p3.y;
+  return Math.atan2(dy, dx) * (180 / Math.PI);
+}
+```
+
+**Circle**:
+```tsx
+function pointOnCircle(cx, cy, radius, angleRadians) {
+  return {
+    x: cx + radius * Math.cos(angleRadians),
+    y: cy + radius * Math.sin(angleRadians)
+  };
+}
+
+// Usage
+const angleRadians = progress * Math.PI * 2;
+const pos = pointOnCircle(300, 300, 100, angleRadians);
+const tangentAngle = (angleRadians * 180 / Math.PI) + 90; // Tangent is perpendicular
+```
+
+**Tips:**
+- Use `progress` (0-1) for smooth animation
+- The `translate(-50%, -50%)` centers the element on the path
+- Combine rotation with the translate: `translate(-50%, -50%) rotate(${angle}deg)`
+- For text following a path, you can animate individual characters at different progress values
+
+## SVG Stroke Animations
+
+Animate SVG path strokes with the **stroke-dash** classes, perfect for drawing or erasing line art, icons, and illustrations.
+
+### How It Works
+
+SVG stroke animations use `strokeDasharray` and `strokeDashoffset` CSS properties to create drawing effects:
+
+1. **Enter animations** - Draw the stroke from start to finish
+2. **Exit animations** - Erase the stroke from finish to start
+3. **Loop animations** - Continuously draw and erase
+
+### Format
+
+All stroke-dash animations require the **path length** in brackets:
+
+```tsx
+enter-stroke-dash-[length]/start/duration
+exit-stroke-dash-[length]/start/duration
+loop-stroke-dash-[length]/duration
+```
+
+### Basic Examples
+
+```tsx
+export default function SVGAnimation({ tw }) {
+  return (
+    <svg width="400" height="200" viewBox="0 0 400 200">
+      {/* Draw a curve over 1 second */}
+      <path
+        d="M10 150 Q 95 10 180 150"
+        stroke="black"
+        strokeWidth={4}
+        fill="none"
+        style={tw('enter-stroke-dash-[300]/0/1000')}
+      />
+    </svg>
+  );
+}
+```
+
+### Enter Animations (Drawing)
+
+Draw strokes from 0% to 100%:
+
+```tsx
+// Draw a 300px path over 1 second
+<path style={tw('enter-stroke-dash-[300]/0/1000')} />
+
+// Draw with spring easing
+<path style={tw('ease-spring enter-stroke-dash-[500]/0/1500')} />
+
+// Stagger multiple paths
+<path style={tw('enter-stroke-dash-[200]/0/600')} />
+<path style={tw('enter-stroke-dash-[200]/200/600')} />
+<path style={tw('enter-stroke-dash-[200]/400/600')} />
+```
+
+### Exit Animations (Erasing)
+
+Erase strokes from 100% to 0%:
+
+```tsx
+// Erase starting at 2000ms, lasting 500ms
+<path style={tw('exit-stroke-dash-[300]/2000/500')} />
+
+// Draw then erase the same path
+<path style={tw('enter-stroke-dash-[400]/0/800 exit-stroke-dash-[400]/2200/800')} />
+```
+
+### Loop Animations
+
+Continuously draw and erase:
+
+```tsx
+// Loop every 2 seconds (draws in first half, erases in second half)
+<path style={tw('loop-stroke-dash-[300]/2000')} />
+
+// Faster loop
+<path style={tw('loop-stroke-dash-[200]/1000')} />
+```
+
+### Getting Path Length
+
+To find the path length for your SVG:
+
+```tsx
+// In browser console or component:
+const path = document.querySelector('path');
+const length = path.getTotalLength();
+console.log(length); // e.g., 347.89
+```
+
+Then use that value:
+
+```tsx
+<path style={tw('enter-stroke-dash-[347.89]/0/1000')} />
+```
+
+### Complete Example
+
+```tsx
+export default function DrawingEffect({ tw }) {
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
+      <svg width="600" height="400" viewBox="0 0 600 400">
+        {/* Checkmark icon drawn in sequence */}
+        <path
+          d="M100 200 L 200 300 L 400 100"
+          stroke="#10b981"
+          strokeWidth={8}
+          fill="none"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={tw('ease-out enter-stroke-dash-[600]/0/1200')}
+        />
+
+        {/* Circle drawn after checkmark */}
+        <circle
+          cx="250"
+          cy="200"
+          r="150"
+          stroke="#10b981"
+          strokeWidth={6}
+          fill="none"
+          style={tw('ease-out enter-stroke-dash-[942]/1000/1000')}
+        />
+      </svg>
+    </div>
+  );
+}
+```
+
+### Combining with Other Animations
+
+Stroke animations work alongside other animation classes:
+
+```tsx
+// Fade in while drawing
+<path style={tw('enter-stroke-dash-[300]/0/1000 enter-fade-in/0/1000')} />
+
+// Draw with pulsing color
+<svg>
+  <path
+    stroke="url(#gradient)"
+    style={tw('enter-stroke-dash-[500]/0/1500')}
+  />
+  <defs>
+    <linearGradient id="gradient">
+      <stop offset="0%" stopColor="#8b5cf6" />
+      <stop offset="100%" stopColor="#ec4899" />
+    </linearGradient>
+  </defs>
+</svg>
+```
+
+### Animated Dashed Strokes (Marching Ants)
+
+For **marching ants** or **animated dashed patterns**, use `frame` or `progress` directly instead of animation classes:
+
+```tsx
+export default function MarchingAnts({ tw, frame }) {
+  // Calculate animated offset (loops every 30 frames)
+  const dashOffset = -(frame % 30) * 2;
+
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
+      <svg width="600" height="400" viewBox="0 0 600 400">
+        {/* Marching ants border */}
+        <rect
+          x="50"
+          y="50"
+          width="500"
+          height="300"
+          fill="none"
+          stroke="#3b82f6"
+          strokeWidth={3}
+          strokeDasharray="10 5"
+          strokeDashoffset={dashOffset}
+        />
+
+        {/* Animated circle with different speed */}
+        <circle
+          cx="300"
+          cy="200"
+          r="80"
+          fill="none"
+          stroke="#10b981"
+          strokeWidth={4}
+          strokeDasharray="15 8"
+          strokeDashoffset={dashOffset * 1.5}
+        />
+      </svg>
+    </div>
+  );
+}
+```
+
+**Tips:**
+- `strokeDasharray="10 5"` - 10px dash, 5px gap
+- `strokeDashoffset={dashOffset}` - animates the pattern position
+- Negative offset moves forward, positive moves backward
+- Different speeds: multiply by different values (e.g., `dashOffset * 2`)
+
+This technique is different from `stroke-dash` classes:
+- **`stroke-dash` classes** - Draw/erase the stroke (reveal animation)
+- **Marching ants** - Move a dashed pattern along the stroke
+
 ## Performance Tips
 
 1. **Use Tailwind classes** when possible - they're optimized for the renderer
@@ -1986,27 +2617,246 @@ export default function BrandedTemplate({ tw, config, title }) {
 
 This allows templates to adapt to user preferences and brand guidelines.
 
+## Text on Path
+
+Render text along curves, circles, and custom paths with automatic character positioning and rotation.
+
+### Usage
+
+```tsx
+export default function CircleText({ tw, textPath, message }) {
+  return (
+    <div style={tw('relative w-full h-full bg-slate-900')}>
+      {textPath.onCircle(
+        message,
+        960,  // center x
+        540,  // center y
+        400,  // radius
+        0,    // rotation offset (0-1)
+        {
+          fontSize: "4xl",
+          fontWeight: "bold",
+          color: "white",
+          letterSpacing: 0.05
+        }
+      )}
+    </div>
+  );
+}
+```
+
+### Available Functions
+
+All `textPath` functions return an array of positioned character elements:
+
+**`textPath.onCircle(text, cx, cy, radius, offset, options?)`**
+```tsx
+// Text around a circle
+textPath.onCircle("HELLO WORLD", 960, 540, 400, 0, {
+  fontSize: "4xl",
+  color: "white"
+})
+```
+
+**`textPath.onPath(text, pathFollower, options?)`**
+```tsx
+// Text along any custom path
+textPath.onPath("CUSTOM PATH", (t) => ({
+  x: 100 + t * 800,
+  y: 200 + Math.sin(t * Math.PI) * 100,
+  angle: Math.cos(t * Math.PI) * 20
+}), {
+  fontSize: "2xl",
+  fontWeight: "semibold"
+})
+```
+
+**`textPath.onQuadratic(text, p0, p1, p2, options?)`**
+```tsx
+// Text along a quadratic Bezier curve
+textPath.onQuadratic(
+  "CURVED TEXT",
+  { x: 200, y: 400 },   // start
+  { x: 960, y: 100 },   // control point
+  { x: 1720, y: 400 },  // end
+  { fontSize: "3xl", color: "blue-300" }
+)
+```
+
+**`textPath.onCubic(text, p0, p1, p2, p3, options?)`**
+```tsx
+// Text along a cubic Bezier curve
+textPath.onCubic(
+  "S-CURVE",
+  { x: 200, y: 600 },   // start
+  { x: 600, y: 400 },   // control 1
+  { x: 1320, y: 800 },  // control 2
+  { x: 1720, y: 600 },  // end
+  { fontSize: "3xl", color: "purple-300" }
+)
+```
+
+**`textPath.onArc(text, cx, cy, radius, startAngle, endAngle, options?)`**
+```tsx
+// Text along a circular arc
+textPath.onArc(
+  "ARC TEXT",
+  960,   // center x
+  540,   // center y
+  400,   // radius
+  0,     // start angle (degrees)
+  180,   // end angle (degrees)
+  { fontSize: "2xl", color: "pink-300" }
+)
+```
+
+### Options
+
+All `textPath` functions accept an optional `options` object:
+
+```typescript
+{
+  fontSize?: string;      // Tailwind size: "xl", "2xl", "4xl", etc.
+  fontWeight?: string;    // Tailwind weight: "bold", "semibold", etc.
+  color?: string;         // Tailwind color: "white", "blue-500", etc.
+  letterSpacing?: number; // Space between characters (0-1, default: 0)
+  style?: any;           // Additional inline styles
+}
+```
+
+### Examples
+
+**Animated rotating text:**
+```tsx
+export default function RotatingText({ tw, textPath, progress }) {
+  return (
+    <div style={tw('relative w-full h-full bg-black')}>
+      {textPath.onCircle(
+        "SPINNING • TEXT • ",
+        960, 540, 400,
+        progress,  // Rotate based on video progress
+        { fontSize: "3xl", color: "yellow-300" }
+      )}
+    </div>
+  );
+}
+```
+
+**Multiple text paths:**
+```tsx
+export default function MultiPath({ tw, textPath }) {
+  return (
+    <div style={tw('relative w-full h-full bg-gradient-to-br from-slate-900 to-slate-700')}>
+      {/* Text on outer circle */}
+      {textPath.onCircle(
+        "OUTER RING",
+        960, 540, 500, 0,
+        { fontSize: "5xl", fontWeight: "bold", color: "white" }
+      )}
+
+      {/* Text on inner circle */}
+      {textPath.onCircle(
+        "inner ring",
+        960, 540, 300, 0.5,  // offset by 50% for rotation
+        { fontSize: "2xl", color: "white/60" }
+      )}
+    </div>
+  );
+}
+```
+
+**Text following a drawn path:**
+```tsx
+export default function PathText({ tw, textPath }) {
+  return (
+    <div style={tw('relative w-full h-full bg-gray-900')}>
+      {/* Draw the path */}
+      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
+        <path
+          d="M 200 400 Q 960 150 1720 400"
+          stroke="rgba(255,255,255,0.2)"
+          strokeWidth={2}
+          fill="none"
+        />
+      </svg>
+
+      {/* Text following the path */}
+      {textPath.onQuadratic(
+        "FOLLOWING THE CURVE",
+        { x: 200, y: 400 },
+        { x: 960, y: 150 },
+        { x: 1720, y: 400 },
+        { fontSize: "3xl", fontWeight: "bold", color: "blue-300" }
+      )}
+    </div>
+  );
+}
+```
+
+For animated text paths, see [Text Path Animations](/animation#text-path-animations).
+
+## Reserved Prop Names
+
+The following prop names are **reserved** and cannot be used in your template's `meta.props`:
+
+- `tw`, `qr`, `image`, `template` - Core helpers
+- `path`, `textPath` - Path and text helpers
+- `config`, `frame`, `progress` - System props
+
+**Why?** These names are used for loopwind's built-in helpers. Using them as prop names would cause conflicts.
+
+**Example:**
+```tsx
+// ❌ BAD - 'image' is reserved
+export const meta = {
+  props: {
+    title: "string",
+    image: "string"  // Error!
+  }
+};
+
+// ✅ GOOD - Use descriptive alternatives
+export const meta = {
+  props: {
+    title: "string",
+    imageUrl: "string",    // or imageSrc, photoUrl, etc.
+    logoUrl: "string"
+  }
+};
+```
+
+If you try to use a reserved name, you'll get a helpful error:
+```
+Template uses reserved prop names: image
+
+Try renaming: "image" → "imageUrl" or "imageSrc"
+
+Reserved names: tw, qr, image, template, path, textPath, config, frame, progress
+```
+
 ## All Props Reference
 
 Every template receives these props:
 
 ```tsx
-export default function MyTemplate({ 
-  // Core helpers
+export default function MyTemplate({
+  // Core helpers (RESERVED - cannot be used as prop names)
   tw,        // Tailwind class converter
   qr,        // QR code generator (this page)
   template,  // Template composer (this page)
   config,    // User config from loopwind.json (this page)
-  
-  // Media helpers (see dedicated pages)
+  textPath,  // Text on path helpers (this page)
+
+  // Media helpers (RESERVED)
   image,     // Image embedder → see /images
+  path,      // Path following → see /animation
 
-  // Video-specific (only in video templates)
+  // Video-specific (RESERVED - only in video templates)
   frame,     // Current frame number → see /video
   progress,  // Animation progress 0-1 → see /video
-  
-  // Your custom props
-  ...props   // Any props from your props.json
+
+  // Your custom props (use any names EXCEPT the reserved ones above)
+  ...props   // Any props from your meta.props
 }) {
   // Your template code
 }