feat: Add parameterization and color-morphing to wave animations

Enable full customization of the wave effect in bubbles animation with new
parameters and add a mesmerizing color-morphing gradient option.

New Parameters:
1. wave_speed (default: 2)
   - Controls wave cycle duration in seconds
   - Lower values = faster waves
   - Range: 0.5 to 5 seconds recommended

2. wave_amplitude (default: 3)
   - Controls vertical movement height in pixels
   - Higher values = bigger waves
   - Range: 1 to 10 pixels recommended

3. wave_delay (default: 0.05)
   - Controls delay between each character in seconds
   - Determines how fast wave travels horizontally
   - Range: 0.01 to 0.2 seconds recommended

4. color_morph (default: false)
   - Enables color morphing gradient effect
   - Letters cycle through theme colors smoothly
   - Animation cycle is 3x the wave_speed

Color Morphing Implementation:
- Animates through titleColor → iconColor → textColor → iconColor → titleColor
- Uses CSS fill animation for smooth transitions
- Combines with wave motion for dual-animation effect
- Automatically uses theme colors for perfect integration

Technical Details:
- Parameters passed through API → renderRepoCard → getAnimationStyle
- wrapTextInWave updated to conditionally add wave-char-morph class
- CSS keyframes dynamically generated with user parameters
- Proper type conversion (parseFloat) for numeric params in API
- Maintains backward compatibility with default values

Example Usage:
- Fast big waves: wave_speed=1&wave_amplitude=6&wave_delay=0.03
- Slow gentle: wave_speed=3&wave_amplitude=2&wave_delay=0.08
- Color morph: color_morph=true (combines with any wave params)

Documentation:
- Added Wave Customization Parameters section
- New usage examples showing different combinations
- Parameter reference with ranges and recommendations
- Examples of fast, slow, and color-morphing variations

Author: claude

ANIMATION_EXAMPLES.md

@@ -76,15 +76,29 @@ animation_style=bubbles
 - 2 glowing jellyfish with wavy tentacles drifting left to right
 - 2 starfish slowly rotating and drifting right to left
 - **🌊 Horizontal wave text effect**: Letters ripple like a wave traveling across the text
-  - Each character animates individually with a staggered delay (0.05s per letter)
+  - Each character animates individually with a staggered delay
   - Creates a smooth left-to-right wave motion across the title
-  - 2-second wave cycle with 3px vertical movement
-  - Like text floating and undulating in water
+  - Fully customizable wave parameters (see below)
+  - Optional color-morphing gradient effect
 - Jellyfish appear every ~12 seconds with gentle pulsing glow
 - Starfish drift across every ~15 seconds with slow rotation
 - All creatures layered behind text for depth
 - Perfect for: Calm, steady progress projects, marine/ocean themes, underwater aesthetics
 
+**Wave Customization Parameters:**
+- `wave_speed` - Wave cycle duration in seconds (default: `2`)
+  - Lower = faster wave, Higher = slower wave
+  - Example: `wave_speed=1.5` for faster waves
+- `wave_amplitude` - Vertical movement in pixels (default: `3`)
+  - How high each letter bounces
+  - Example: `wave_amplitude=5` for bigger waves
+- `wave_delay` - Delay between each character in seconds (default: `0.05`)
+  - Controls how quickly wave travels horizontally
+  - Example: `wave_delay=0.08` for slower wave travel
+- `color_morph` - Enable color morphing gradient (default: `false`)
+  - Letters cycle through theme colors
+  - Example: `color_morph=true`
+
 ### 2. **embers** - Burning Particles 🔥
 Glowing particles pulse and float like hot embers.
 ```
@@ -148,6 +162,21 @@ animation_style=sparks
 ![Repo Card](https://your-domain.vercel.app/api/pin?username=hesreallyhim&repo=your-repo&theme=robot_blue&animation_style=sparks&show_owner=true&all_stats=true)
 ```
 
+### Custom Wave Effect (Fast & Big)
+```markdown
+![Repo Card](https://your-domain.vercel.app/api/pin?username=hesreallyhim&repo=your-repo&theme=mad_scientist&animation_style=bubbles&wave_speed=1&wave_amplitude=6&wave_delay=0.03)
+```
+
+### Color Morphing Wave
+```markdown
+![Repo Card](https://your-domain.vercel.app/api/pin?username=hesreallyhim&repo=your-repo&theme=electric_laboratory&animation_style=bubbles&color_morph=true)
+```
+
+### Slow Gentle Wave
+```markdown
+![Repo Card](https://your-domain.vercel.app/api/pin?username=hesreallyhim&repo=your-repo&theme=robot_blue&animation_style=bubbles&wave_speed=3&wave_amplitude=2&wave_delay=0.08)
+```
+
 ### Disable Animations (for static images)
 ```markdown
 ![Repo Card](https://your-domain.vercel.app/api/pin?username=hesreallyhim&repo=your-repo&theme=electric_laboratory&disable_animations=true)
@@ -202,6 +231,28 @@ Dark background with pulsing radiant center - excellent for core libraries.
   - Options: `true`, `false`
   - Default: `false`
 
+### Wave Customization Parameters (bubbles only)
+- `wave_speed` - Duration of one wave cycle in seconds
+  - Range: `0.5` to `5` (recommended)
+  - Default: `2`
+  - Example: `wave_speed=1.5` (faster)
+
+- `wave_amplitude` - Vertical movement height in pixels
+  - Range: `1` to `10` (recommended)
+  - Default: `3`
+  - Example: `wave_amplitude=5` (bigger waves)
+
+- `wave_delay` - Delay between each character in seconds
+  - Range: `0.01` to `0.2` (recommended)
+  - Default: `0.05`
+  - Example: `wave_delay=0.08` (slower horizontal travel)
+
+- `color_morph` - Enable color morphing gradient effect
+  - Options: `true`, `false`
+  - Default: `false`
+  - Cycles through title, icon, and text colors
+  - Example: `color_morph=true`
+
 ### All Compatible Parameters
 You can combine animations with all existing repo card parameters:
 - `theme` - Choose from 65+ themes (including 5 new cybernetic ones)

api/pin.js

@@ -44,6 +44,10 @@ export default async (req, res) => {
     age_metric,
     animation_style,
     disable_animations,
+    wave_speed,
+    wave_amplitude,
+    wave_delay,
+    color_morph,
   } = req.query;
 
   res.setHeader("Content-Type", "image/svg+xml");
@@ -120,6 +124,10 @@ export default async (req, res) => {
         age_metric: age_metric || "first",
         animation_style: animation_style || "none",
         disable_animations: parseBoolean(disable_animations),
+        wave_speed: wave_speed ? parseFloat(wave_speed) : 2,
+        wave_amplitude: wave_amplitude ? parseFloat(wave_amplitude) : 3,
+        wave_delay: wave_delay ? parseFloat(wave_delay) : 0.05,
+        color_morph: parseBoolean(color_morph),
       }),
     );
   } catch (err) {

src/cards/repo.js

@@ -25,15 +25,22 @@ const DESCRIPTION_MAX_LINES = 3;
  * @param {string} text The text to wrap.
  * @param {number} baseDelay Base delay in seconds before wave starts.
  * @param {number} delayPerChar Delay in seconds between each character.
+ * @param {boolean} colorMorph Whether to enable color morphing effect.
  * @returns {string} SVG tspan elements with wave animation.
  */
-const wrapTextInWave = (text, baseDelay = 0, delayPerChar = 0.05) => {
+const wrapTextInWave = (
+  text,
+  baseDelay = 0,
+  delayPerChar = 0.05,
+  colorMorph = false,
+) => {
   return Array.from(text)
     .map((char, i) => {
       const delay = baseDelay + i * delayPerChar;
       // Preserve spaces
       const displayChar = char === " " ? "\u00A0" : char;
-      return `<tspan class="wave-char" style="animation-delay: ${delay}s">${displayChar}</tspan>`;
+      const morphClass = colorMorph ? " wave-char-morph" : "";
+      return `<tspan class="wave-char${morphClass}" style="animation-delay: ${delay}s">${displayChar}</tspan>`;
     })
     .join("");
 };
@@ -45,15 +52,21 @@ const wrapTextInWave = (text, baseDelay = 0, delayPerChar = 0.05) => {
  * @param {object} colors Card colors for theming animations.
  * @param {number} width Card width.
  * @param {number} height Card height.
+ * @param {object} waveParams Wave animation parameters.
  * @returns {{css: string, svg: string}} Animation CSS and SVG elements.
  */
-const getAnimationStyle = (style, colors, width, height) => {
+const getAnimationStyle = (style, colors, width, height, waveParams = {}) => {
   if (!style || style === "none") {
     return { css: "", svg: "" };
   }
 
   const iconColor = colors.iconColor || "38bdf8";
   const titleColor = colors.titleColor || "00d9ff";
+  const textColor = colors.textColor || "434d58";
+
+  // Wave parameters with defaults
+  const waveSpeed = waveParams.speed || 2; // seconds
+  const waveAmplitude = waveParams.amplitude || 3; // pixels
 
   switch (style) {
     case "bubbles": {
@@ -191,7 +204,14 @@ const getAnimationStyle = (style, colors, width, height) => {
         }
         @keyframes letterWave {
           0%, 100% { transform: translateY(0px); }
-          50% { transform: translateY(-3px); }
+          50% { transform: translateY(-${waveAmplitude}px); }
+        }
+        @keyframes colorMorph {
+          0% { fill: #${titleColor}; }
+          25% { fill: #${iconColor}; }
+          50% { fill: #${textColor}; }
+          75% { fill: #${iconColor}; }
+          100% { fill: #${titleColor}; }
         }
         .bubble {
           animation: bubbleFloat 3s infinite ease-in-out;
@@ -208,7 +228,11 @@ const getAnimationStyle = (style, colors, width, height) => {
         }
         /* Character-by-character wave effect */
         .wave-char {
-          animation: letterWave 2s ease-in-out infinite;
+          animation: letterWave ${waveSpeed}s ease-in-out infinite;
+        }
+        /* Color morphing effect */
+        .wave-char-morph {
+          animation: letterWave ${waveSpeed}s ease-in-out infinite, colorMorph ${waveSpeed * 3}s ease-in-out infinite;
         }`;
 
       // SVG filter for jellyfish glow
@@ -499,6 +523,10 @@ const renderRepoCard = (repo, options = {}) => {
     age_metric = "first",
     animation_style = "none",
     disable_animations = false,
+    wave_speed = 2,
+    wave_amplitude = 3,
+    wave_delay = 0.05,
+    color_morph = false,
   } = options;
 
   const lineHeight = 10;
@@ -687,8 +715,14 @@ const renderRepoCard = (repo, options = {}) => {
 
   // Get animation styles if enabled
   const hasAnimation = !disable_animations && animation_style !== "none";
+  const waveParams = {
+    speed: wave_speed,
+    amplitude: wave_amplitude,
+    delay: wave_delay,
+    colorMorph: color_morph,
+  };
   const animationData = hasAnimation
-    ? getAnimationStyle(animation_style, colors, 400, cardHeight)
+    ? getAnimationStyle(animation_style, colors, 400, cardHeight, waveParams)
     : { css: "", svg: "" };
 
   // Check if we should add wave effect to text
@@ -736,7 +770,7 @@ const renderRepoCard = (repo, options = {}) => {
         ${icons.contribs}
       </svg>
       <text x="25" y="0" class="wave-title" data-testid="header">
-        ${wrapTextInWave(header.length > 35 ? `${header.slice(0, 35)}...` : header)}
+        ${wrapTextInWave(header.length > 35 ? `${header.slice(0, 35)}...` : header, 0, wave_delay, color_morph)}
       </text>
     </g>
   `