react-weather-effects 0.1.0-beta.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allwin Antony
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,17 @@
 
 Composable, high-performance rain, snow, and fog visual effects for React, rendered on a single lightweight 2D canvas.
 
+[![npm version](https://img.shields.io/npm/v/react-weather-effects.svg)](https://www.npmjs.com/package/react-weather-effects)
+[![Live Demo](https://img.shields.io/badge/Demo-Live%20Playground-0070f3?logo=vercel)](https://react-weather-effects-smoky.vercel.app/)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?logo=github)](https://github.com/allwin-antony/react-weather-effects)
+[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/allwin-antony)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+- **Live Demo:** [https://react-weather-effects-smoky.vercel.app/](https://react-weather-effects-smoky.vercel.app/)
+- **GitHub:** [https://github.com/allwin-antony/react-weather-effects](https://github.com/allwin-antony/react-weather-effects)
+- **npm:** [https://www.npmjs.com/package/react-weather-effects](https://www.npmjs.com/package/react-weather-effects)
+- **Sponsor:** [https://github.com/sponsors/allwin-antony](https://github.com/sponsors/allwin-antony)
+
 ## Installation
 
 Install `react-weather-effects` using your package manager of choice:
@@ -61,6 +72,7 @@ By default, `<WeatherCanvas>` runs in `mode="fullscreen"`, covering the viewport
 - **Single Canvas Engine:** One 2D `<canvas>` manages all effects, batching rendering at 60 FPS without DOM bloat.
 - **Composable:** Combine multiple effects (`Rain`, `Snow`, `Fog`) inside a single canvas.
 - **Configurable:** Adjust intensity, speed, wind angle, colors, and custom snowflake sprite artwork.
+- **Smooth Scene Changes:** Opt into particle-preserving intensity and density fades with `transitionDuration`.
 - **Motion-Aware & Accessible:** Automatically respects `prefers-reduced-motion` and pauses when hidden or offscreen.
 - **Contained & Fullscreen:** Place inside specific cards/heroes (`mode="contained"`) or cover the whole screen.
 - **SSR & Next.js Safe:** Safe for React Server Components (RSC) and Next.js App Router (runs cleanly with `'use client'`).
@@ -76,6 +88,7 @@ By default, `<WeatherCanvas>` runs in `mode="fullscreen"`, covering the viewport
 - [Server rendering and Next.js](#server-rendering-and-nextjs)
 - [Troubleshooting](#troubleshooting)
 - [Local development](#local-development)
+- [Sponsoring](#sponsoring)
 - [License](#license)
 
 ## Usage examples
@@ -130,6 +143,30 @@ export function RainyScene() {
 
 Fog draws behind rain and snow. Rain and snow share a drawing priority; instances at that priority draw in registration order. Each effect has its own settings and can be mounted or removed independently.
 
+### Transition between scenes
+
+Set `transitionDuration` on each effect to fade intensity or density changes over that many milliseconds. Keep the canvas and effects mounted, and use `0` to hide an effect instead of conditionally removing it:
+
+```tsx
+import { WeatherCanvas, Rain, Snow, Fog } from 'react-weather-effects';
+
+export function TransitioningScene({ scene }: { scene: 'rain' | 'snow' | 'clear' }) {
+  return (
+    <WeatherCanvas>
+      <Fog density={scene === 'rain' ? 0.3 : 0} transitionDuration={800} />
+      <Rain intensity={scene === 'rain' ? 0.8 : 0} transitionDuration={800} />
+      <Snow intensity={scene === 'snow' ? 0.6 : 0} transitionDuration={800} />
+    </WeatherCanvas>
+  );
+}
+```
+
+- The default is `0`, preserving instant updates. Initial mounting and unmounting are also immediate.
+- Rain and snow fade added or removed particles without resetting the pool. Retained particles stay visible and continue moving; fog keeps its existing wisps and texture.
+- Changing the target mid-fade continues from the current visibility. Negative or non-finite durations are treated as `0`.
+- Fades use the shared simulation clock, so hidden/offscreen time does not advance them. Static and paused presentations apply the latest settings immediately without animating.
+- Only rain/snow `intensity` and fog `density` are transitioned. Other props, including rain's existing velocity smoothing, retain their current behavior.
+
 ### Use custom snow artwork
 
 Add a static image to your application's public assets, for example `public/snowflakes/crystal.svg`, and pass its served URL:
@@ -167,7 +204,7 @@ Pass a **URL string**, not an SVG React component or raw SVG markup. PNG, SVG, a
 
 For remote images, the image server must allow anonymous cross-origin requests with an appropriate `Access-Control-Allow-Origin` header. Serving artwork from your own application is the simplest option.
 
-`wobble={false}` disables the animated sway and gentle sprite rotation. Wind can still move the flakes. There is no separate `rotation` prop in the current API.
+`wobble={false}` disables animated sideways sway and fall flutter. You can control sprite rotation separately with `rotation` (set `false` to let custom sprites drift upright without rotating, or `true` with `wobble={false}` to rotate without swaying) and adjust the spinning rate with `rotationSpeed` (multiplier, default `1`; set `0` to freeze rotation).
 
 ### Pause and resume a scene
 
@@ -220,21 +257,30 @@ Wind is an effect-specific input, not a velocity in pixels per second. Rain and
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `intensity` | `number` | `0.7` | Fraction of this instance's particle budget to draw. `0` draws no rain. |
+| `transitionDuration` | `number` | `0` | Intensity fade duration in milliseconds. Keep mounted and set intensity to `0` to fade out. |
 | `angle` | `number` | `10` | Degrees from vertical. Positive values lean right; negative values lean left. |
 | `speed` | `number` | `1` | Multiplier for intrinsic falling speed. |
-| `color` | `string` | `'rgba(190, 215, 245, 0.8)'` | CSS color for rain trails. |
+| `dropLength` | `number` | `1` | Multiplier for raindrop streak length (< 1 for fine drizzle, > 1 for heavy downpour). Alias: `length`. |
+| `dropThickness` | `number` | `1` | Multiplier for raindrop stroke thickness (< 1 for fine mist, > 1 for heavy rain). Alias: `thickness`. |
+| `splashes` | `boolean` | `false` | Enable animated bottom-edge splashes for contained cards or heroes. Alias: `splash`. |
+| `color` | `string` | `'rgba(190, 215, 245, 0.8)'` | CSS color for rain trails and splashes. |
+
+With `splashes`, visible drops produce small, varied droplets that rise and fall over a softly expanding ground ripple. Splash size follows `dropThickness`; existing impacts finish their short animation when rain stops. Under heavy rain, excess impacts are skipped instead of restarting active splashes. Splashes stay at the current canvas bottom edge after resizing, and paused/static redraws preserve their state. Use contained mode for a defined ground edge; splashes do not detect other DOM surfaces.
 
 ### `Snow`
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `intensity` | `number` | `0.5` | Fraction of this instance's particle budget to draw. `0` draws no snow. |
+| `transitionDuration` | `number` | `0` | Intensity fade duration in milliseconds. Keep mounted and set intensity to `0` to fade out. |
 | `speed` | `number` | `1` | Multiplier for intrinsic falling speed and wobble progression. |
 | `color` | `string` | `'rgba(255, 255, 255, 0.85)'` | CSS color for built-in flakes and the sprite fallback. Does not tint artwork. |
 | `sprite` | `string` | None | Static image URL. Omitting it uses soft, built-in snowflakes. |
 | `minSize` | `number` | `1.5`, or `6` with a sprite | Minimum flake radius in CSS pixels. |
 | `maxSize` | `number` | `4`, or `18` with a sprite | Maximum flake radius in CSS pixels. |
-| `wobble` | `boolean` | `true` | Enable animated sway and gentle sprite rotation. |
+| `wobble` | `boolean` | `true` | Enable animated sideways sway and fall flutter. |
+| `rotation` | `boolean` | `true` (or `wobble`) | Enable sprite rotation/spinning. Defaults to `wobble`. Set `false` to drift without rotating. |
+| `rotationSpeed` | `number` | `1` | Multiplier for sprite rotation/spinning speed. Defaults to `1`. Set to `0` to freeze angle. |
 
 Use nonnegative sizes, with `minSize <= maxSize`. Built-in flakes have a feathered glow that extends beyond their nominal radius.
 
@@ -243,6 +289,7 @@ Use nonnegative sizes, with `minSize <= maxSize`. Built-in flakes have a feather
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `density` | `number` | `0.4` | Opacity multiplier. `0` draws no fog. |
+| `transitionDuration` | `number` | `0` | Density fade duration in milliseconds. Keep mounted and set density to `0` to fade out. |
 | `speed` | `number` | `1` | Multiplier for intrinsic drift and shape movement. |
 | `color` | `string` | `'rgba(220, 225, 235, 0.35)'` | CSS color used to tint the cached fog texture. |
 | `layers` | `number` | `3` | Layer count, rounded and clamped between `1` and `6`. |
@@ -413,6 +460,12 @@ npm install /path/to/react-weather-effects-0.1.0-beta.0.tgz
 
 For implementation contracts, package boundaries, and future plans, see `ARCHITECTURE.md` in the source repository. Keep changes focused, cover rendering and lifecycle behavior with tests, and verify the build, types, and size budget before submitting changes.
 
+## Sponsoring
+
+If you find `react-weather-effects` useful, please consider sponsoring its ongoing development and maintenance:
+
+💖 [**Sponsor on GitHub**](https://github.com/sponsors/allwin-antony)
+
 ## License
 
 Licensed under the MIT license.

package/dist/index.cjs

@@ -179,6 +179,7 @@ function WeatherCanvas({
     const frameState = {
       ctx,
       dt,
+      isAnimating: shouldAnimateRef.current,
       width: dimensions.width,
       height: dimensions.height,
       dpr: currentDpr,
@@ -491,6 +492,51 @@ function growParticlePool(pool, count) {
   next.set(pool);
   return next;
 }
+function resolveDuration(duration) {
+  return Number.isFinite(duration) ? Math.max(0, duration) : 0;
+}
+function createTransition(target, duration) {
+  return { target, duration: resolveDuration(duration), remaining: 0 };
+}
+function stepTransition(transition, target, duration, state) {
+  const nextDuration = resolveDuration(duration);
+  if (target !== transition.target || nextDuration !== transition.duration) {
+    transition.target = target;
+    transition.duration = nextDuration;
+    transition.remaining = nextDuration;
+  }
+  if (!state.isAnimating || nextDuration === 0) {
+    transition.remaining = 0;
+    return 1;
+  }
+  if (transition.remaining === 0) return 1;
+  const elapsed = state.dt * 1e3;
+  const step = elapsed + 1e-6 >= transition.remaining ? 1 : elapsed / transition.remaining;
+  transition.remaining = step === 1 ? 0 : transition.remaining - elapsed;
+  return step;
+}
+function createParticleTransition(count, capacity, duration) {
+  const visibility = new Float32Array(capacity);
+  visibility.fill(1, 0, count);
+  return { transition: createTransition(count, duration), visibility, count };
+}
+function updateParticleTransition(particles, targetCount, duration, state) {
+  const capacity = state.budget.maxParticles;
+  if (particles.visibility.length < capacity) {
+    const visibility = new Float32Array(capacity);
+    visibility.set(particles.visibility);
+    particles.visibility = visibility;
+  }
+  if (particles.count > capacity) particles.visibility.fill(0, capacity, particles.count);
+  const count = Math.min(capacity, Math.max(particles.count, targetCount));
+  const step = stepTransition(particles.transition, targetCount, duration, state);
+  for (let i = 0; i < count; i++) {
+    const target = i < targetCount ? 1 : 0;
+    particles.visibility[i] = step === 1 ? target : particles.visibility[i] + (target - particles.visibility[i]) * step;
+  }
+  particles.count = step === 1 ? targetCount : count;
+}
+var SPLASH_STRIDE = 7;
 function seedParticle(pool, i, state, settings, isInitial) {
   const base = i * PARTICLE_STRIDE;
   const angleRad = settings.angle * Math.PI / 180;
@@ -514,7 +560,7 @@ function seedParticleRange(pool, startIndex, endIndex, state, settings) {
     seedParticle(pool, i, state, settings, true);
   }
 }
-function updatePool(pool, count, state, settings) {
+function updatePool(pool, count, state, settings, visibility, splashPool, maxSplashes, splashState) {
   const dt = state.dt;
   const width = state.width;
   const height = state.height;
@@ -523,6 +569,15 @@ function updatePool(pool, count, state, settings) {
   const sinAngle = Math.sin(angleRad);
   const cosAngle = Math.cos(angleRad);
   const response = 1 - Math.exp(-dt * 5);
+  if (splashState.active) {
+    splashState.active = false;
+    for (let s = 0; s < maxSplashes; s++) {
+      const sBase = s * SPLASH_STRIDE;
+      if (splashPool[sBase + 5] === 0 || splashPool[sBase + 2] >= 1) continue;
+      splashPool[sBase + 2] = Math.min(1, splashPool[sBase + 2] + dt * splashPool[sBase + 3]);
+      if (splashPool[sBase + 2] < 1) splashState.active = true;
+    }
+  }
   for (let i = 0; i < count; i++) {
     const base = i * PARTICLE_STRIDE;
     let x = pool[base];
@@ -535,8 +590,28 @@ function updatePool(pool, count, state, settings) {
     const targetVy = cosAngle * speed + state.wind.y * (60 + depth * 50);
     vx += (targetVx - vx) * response;
     vy += (targetVy - vy) * response;
+    const prevY = y;
     x += vx * dt;
     y += vy * dt;
+    if (settings.splashes && prevY < height && y >= height && visibility[i] > 0.05) {
+      const elapsed = (y - height) / vy;
+      const impactX = x - vx * elapsed;
+      if (impactX >= 0 && impactX <= width) {
+        const sBase = splashState.head * SPLASH_STRIDE;
+        splashState.head = (splashState.head + 1) % maxSplashes;
+        if (splashPool[sBase + 5] === 0 || splashPool[sBase + 2] >= 1) {
+          const duration = 0.3 + depth * 0.18;
+          splashState.active = true;
+          splashPool[sBase] = impactX;
+          splashPool[sBase + 1] = Math.max(-40, Math.min(40, vx * 0.04));
+          splashPool[sBase + 2] = elapsed / duration;
+          splashPool[sBase + 3] = 1 / duration;
+          splashPool[sBase + 4] = (2.8 + depth * 4.6) * Math.sqrt(Math.max(0.4, Math.min(3, settings.dropThickness)));
+          splashPool[sBase + 5] = (0.25 + depth * 0.45) * visibility[i];
+          splashPool[sBase + 6] = (depth + i * 0.618) % 1;
+        }
+      }
+    }
     if (x > width + 100 || x < -100) {
       x = ((x + 100) % wrapWidth + wrapWidth) % wrapWidth - 100;
     }
@@ -550,65 +625,162 @@ function updatePool(pool, count, state, settings) {
     }
   }
 }
-function drawPool(pool, count, state, settings) {
-  if (count === 0) return;
+function drawPool(pool, count, state, settings, visibility, splashPool, maxSplashes) {
+  if (count === 0 && (!settings.splashes || maxSplashes === 0)) return;
   const ctx = state.ctx;
   ctx.strokeStyle = settings.color;
   ctx.lineCap = "round";
-  for (let i = 0; i < count; i++) {
-    const base = i * PARTICLE_STRIDE;
-    const x = pool[base];
-    const y = pool[base + 1];
-    const vx = pool[base + 2];
-    const vy = pool[base + 3];
-    const depth = pool[base + 6];
-    const trailFactor = 0.012 + depth * 0.025;
-    const fade = Math.max(0, Math.min(1, (y + 25) / 45, (state.height + 35 - y) / 80));
-    for (let segment = 0; segment < 3; segment++) {
-      const start = segment / 3 * trailFactor;
-      const end = (segment + 1) / 3 * trailFactor;
-      ctx.globalAlpha = pool[base + 4] * fade * Math.pow(1 - segment / 3, 2);
-      ctx.lineWidth = (0.6 + depth * 1.1) * (1 - segment * 0.2);
+  if (count > 0) {
+    for (let i = 0; i < count; i++) {
+      if (visibility[i] === 0) continue;
+      const base = i * PARTICLE_STRIDE;
+      const x = pool[base];
+      const y = pool[base + 1];
+      const vx = pool[base + 2];
+      const vy = pool[base + 3];
+      const depth = pool[base + 6];
+      const trailFactor = (0.012 + depth * 0.025) * settings.dropLength;
+      const fade = Math.max(0, Math.min(1, (y + 25) / 45, (state.height + 35 - y) / 80));
+      for (let segment = 0; segment < 3; segment++) {
+        const start = segment / 3 * trailFactor;
+        const end = (segment + 1) / 3 * trailFactor;
+        ctx.globalAlpha = pool[base + 4] * fade * visibility[i] * Math.pow(1 - segment / 3, 2);
+        ctx.lineWidth = (0.6 + depth * 1.1) * (1 - segment * 0.2) * settings.dropThickness;
+        ctx.beginPath();
+        ctx.moveTo(x - vx * start, y - vy * start);
+        ctx.lineTo(x - vx * end, y - vy * end);
+        ctx.stroke();
+      }
+    }
+  }
+  if (settings.splashes) {
+    ctx.fillStyle = settings.color;
+    const thickness = Math.max(0.4, Math.min(3, settings.dropThickness));
+    for (let s = 0; s < maxSplashes; s++) {
+      const sBase = s * SPLASH_STRIDE;
+      const progress = splashPool[sBase + 2];
+      if (progress >= 1 || splashPool[sBase + 5] === 0) continue;
+      const x = splashPool[sBase];
+      const y = state.height;
+      const size = splashPool[sBase + 4];
+      const alpha = splashPool[sBase + 5];
+      const elapsed = progress / splashPool[sBase + 3];
+      const drift = splashPool[sBase + 1] * elapsed;
+      ctx.globalAlpha = alpha * 0.45 * Math.pow(1 - progress, 1.5);
+      ctx.lineWidth = Math.max(0.35, 0.6 * thickness * (1 - progress * 0.4));
+      const rx = size * (0.25 + 1.9 * (1 - Math.pow(1 - progress, 3)));
+      const ry = Math.max(0.25, rx * 0.19);
       ctx.beginPath();
-      ctx.moveTo(x - vx * start, y - vy * start);
-      ctx.lineTo(x - vx * end, y - vy * end);
+      ctx.ellipse(x, y, rx, ry, 0, Math.PI, Math.PI * 2);
       ctx.stroke();
+      for (let bead = 0; bead < 5; bead++) {
+        const variation = (splashPool[sBase + 6] + bead * 0.37) % 1;
+        const beadProgress = progress / (0.72 + variation * 0.28);
+        if (beadProgress >= 1) continue;
+        const direction = (bead - 2) * 0.5;
+        const peak = size * (0.9 + (1 - Math.abs(direction)) * 1.1 + variation * 0.4);
+        const beadX = x + drift + direction * size * (1.5 + variation * 0.7) * beadProgress;
+        const beadY = y - peak * 4 * beadProgress * (1 - beadProgress);
+        const radius = Math.max(0.3, (0.4 + thickness * 0.35) * (1 - beadProgress * 0.45));
+        ctx.globalAlpha = alpha * Math.pow(1 - beadProgress, 1.25);
+        ctx.beginPath();
+        ctx.arc(beadX, beadY, radius, 0, Math.PI * 2);
+        ctx.fill();
+      }
     }
   }
   ctx.globalAlpha = 1;
 }
 function Rain({
   intensity = 0.7,
+  transitionDuration = 0,
   angle = 10,
   color = "rgba(190, 215, 245, 0.8)",
-  speed = 1
+  speed = 1,
+  dropLength,
+  length,
+  dropThickness,
+  thickness,
+  splashes,
+  splash
 }) {
   const ticker = React.useContext(TickerCtx);
   if (!ticker) {
     throw new Error("<Rain /> must be used inside <WeatherCanvas>");
   }
-  const settingsRef = React.useRef({ intensity, angle, color, speed });
+  const effectiveDropLength = dropLength ?? length ?? 1;
+  const effectiveDropThickness = dropThickness ?? thickness ?? 1;
+  const effectiveSplashes = splashes ?? splash ?? false;
+  const settingsRef = React.useRef({
+    intensity,
+    transitionDuration,
+    angle,
+    color,
+    speed,
+    dropLength: effectiveDropLength,
+    dropThickness: effectiveDropThickness,
+    splashes: effectiveSplashes
+  });
   React.useEffect(() => {
-    settingsRef.current = { intensity, angle, color, speed };
+    settingsRef.current = {
+      intensity,
+      transitionDuration,
+      angle,
+      color,
+      speed,
+      dropLength: effectiveDropLength,
+      dropThickness: effectiveDropThickness,
+      splashes: effectiveSplashes
+    };
     ticker.invalidate();
-  }, [ticker, intensity, angle, color, speed]);
+  }, [
+    ticker,
+    intensity,
+    transitionDuration,
+    angle,
+    color,
+    speed,
+    effectiveDropLength,
+    effectiveDropThickness,
+    effectiveSplashes
+  ]);
   React.useEffect(() => {
-    let pool = createParticlePool(ticker.getBudget().maxParticles);
+    const capacity = ticker.getBudget().maxParticles;
+    let pool = createParticlePool(capacity);
+    const particles = createParticleTransition(
+      Math.round(Math.max(0, Math.min(1, settingsRef.current.intensity)) * capacity),
+      capacity,
+      settingsRef.current.transitionDuration
+    );
     let initializedCount = 0;
+    const maxSplashes = Math.min(128, Math.max(32, Math.round(capacity * 0.5)));
+    const splashPool = new Float32Array(maxSplashes * SPLASH_STRIDE);
+    const splashState = { head: 0, active: false };
     const unregister = ticker.register(LAYER.MIDGROUND, (state) => {
       const settings = settingsRef.current;
-      const count = Math.round(
+      const targetCount = Math.round(
         Math.max(0, Math.min(1, settings.intensity)) * state.budget.maxParticles
       );
+      updateParticleTransition(particles, targetCount, settings.transitionDuration, state);
+      const count = particles.count;
       pool = growParticlePool(pool, state.budget.maxParticles);
       if (count > initializedCount) {
         seedParticleRange(pool, initializedCount, count, state, settings);
         initializedCount = count;
       }
       if (state.dt > 0) {
-        updatePool(pool, count, state, settings);
+        updatePool(
+          pool,
+          count,
+          state,
+          settings,
+          particles.visibility,
+          splashPool,
+          maxSplashes,
+          splashState
+        );
       }
-      drawPool(pool, count, state, settings);
+      drawPool(pool, count, state, settings, particles.visibility, splashPool, maxSplashes);
     });
     return unregister;
   }, [ticker]);
@@ -674,12 +846,13 @@ function seedSnowflake(pool, i, state, isInitial) {
       y = -20 - state.random() * 50;
     }
   }
+  const phase = state.random() * Math.PI * 2;
   pool[base] = x;
   pool[base + 1] = y;
-  pool[base + 2] = 0;
+  pool[base + 2] = phase;
   pool[base + 3] = fallSpeed;
   pool[base + 4] = 0.3 + depth * 0.6;
-  pool[base + 5] = state.random() * Math.PI * 2;
+  pool[base + 5] = phase;
   pool[base + 6] = depth;
 }
 function seedSnowRange(pool, startIndex, endIndex, state) {
@@ -697,6 +870,7 @@ function updateSnow(pool, count, state, settings) {
     const base = i * PARTICLE_STRIDE;
     let x = pool[base];
     let y = pool[base + 1];
+    let angle = pool[base + 2];
     let phase = pool[base + 5];
     const baseVy = pool[base + 3];
     const depth = pool[base + 6];
@@ -704,6 +878,11 @@ function updateSnow(pool, count, state, settings) {
       phase += dt * (0.65 + depth * 1.4) * settings.speed;
       pool[base + 5] = phase;
     }
+    if (settings.rotation && settings.rotationSpeed !== 0) {
+      const spinDir = i % 2 === 0 ? 1 : -1;
+      const spinRate = (0.65 + depth * 1.4) * spinDir;
+      angle += dt * spinRate * settings.rotationSpeed;
+    }
     const sway = settings.wobble ? (Math.sin(phase) * (10 + depth * 22) + Math.sin(phase * 0.5) * 8) * settings.speed : 0;
     const vx = sway + state.wind.x * (50 + depth * 80) * gust;
     const flutter = settings.wobble ? 1 + Math.sin(phase * 0.8) * 0.12 : 1;
@@ -718,16 +897,17 @@ function updateSnow(pool, count, state, settings) {
     } else {
       pool[base] = x;
       pool[base + 1] = y;
-      pool[base + 2] = vx;
+      pool[base + 2] = angle;
     }
   }
 }
-function drawSnow(pool, count, state, settings, texture, sprite) {
+function drawSnow(pool, count, state, settings, texture, sprite, visibility) {
   if (count === 0) return;
   const ctx = state.ctx;
   const aspect = sprite ? sprite.aspect : 1;
   ctx.fillStyle = settings.color;
   for (let i = 0; i < count; i++) {
+    if (visibility[i] === 0) continue;
     const base = i * PARTICLE_STRIDE;
     const x = pool[base];
     const y = pool[base + 1];
@@ -735,14 +915,14 @@ function drawSnow(pool, count, state, settings, texture, sprite) {
     const r = Math.max(0, settings.minSize + depth * (settings.maxSize - settings.minSize));
     if (r === 0) continue;
     const fade = Math.max(0, Math.min(1, (y + 20) / 45, (state.height + 20 - y) / 55));
-    ctx.globalAlpha = pool[base + 4] * fade;
+    ctx.globalAlpha = pool[base + 4] * fade * visibility[i];
     if (sprite) {
       const halfWidth = r * Math.min(1, aspect);
       const halfHeight = r / Math.max(1, aspect);
       ctx.save();
       try {
         ctx.translate(x, y);
-        if (settings.wobble) ctx.rotate(Math.sin(pool[base + 5]) * 0.35);
+        if (settings.rotation) ctx.rotate(pool[base + 2]);
         ctx.drawImage(sprite.texture, -halfWidth, -halfHeight, halfWidth * 2, halfHeight * 2);
       } finally {
         ctx.restore();
@@ -760,31 +940,60 @@ function drawSnow(pool, count, state, settings, texture, sprite) {
 }
 function Snow({
   intensity = 0.5,
+  transitionDuration = 0,
   speed = 1,
   color = "rgba(255, 255, 255, 0.85)",
   sprite,
   minSize = sprite ? 6 : 1.5,
   maxSize = sprite ? 18 : 4,
-  wobble = true
+  wobble = true,
+  rotation,
+  rotationSpeed
 }) {
   const ticker = React.useContext(TickerCtx);
   if (!ticker) {
     throw new Error("<Snow /> must be used inside <WeatherCanvas>");
   }
+  const effectiveRotation = rotation ?? (rotationSpeed !== void 0 ? true : wobble);
+  const effectiveRotationSpeed = rotationSpeed ?? 1;
   const settingsRef = React.useRef({
     intensity,
+    transitionDuration,
     speed,
     color,
     minSize,
     maxSize,
-    wobble
+    wobble,
+    rotation: effectiveRotation,
+    rotationSpeed: effectiveRotationSpeed
   });
   const textureRef = React.useRef(null);
   const spriteRef = React.useRef(null);
   React.useEffect(() => {
-    settingsRef.current = { intensity, speed, color, minSize, maxSize, wobble };
+    settingsRef.current = {
+      intensity,
+      transitionDuration,
+      speed,
+      color,
+      minSize,
+      maxSize,
+      wobble,
+      rotation: effectiveRotation,
+      rotationSpeed: effectiveRotationSpeed
+    };
     ticker.invalidate();
-  }, [ticker, intensity, speed, color, minSize, maxSize, wobble]);
+  }, [
+    ticker,
+    intensity,
+    transitionDuration,
+    speed,
+    color,
+    minSize,
+    maxSize,
+    wobble,
+    effectiveRotation,
+    effectiveRotationSpeed
+  ]);
   React.useEffect(() => {
     textureRef.current = createSnowTexture(color);
     ticker.invalidate();
@@ -827,13 +1036,21 @@ function Snow({
     };
   }, [ticker, sprite]);
   React.useEffect(() => {
-    let pool = createParticlePool(ticker.getBudget().maxParticles);
+    const capacity = ticker.getBudget().maxParticles;
+    let pool = createParticlePool(capacity);
+    const particles = createParticleTransition(
+      Math.round(Math.max(0, Math.min(1, settingsRef.current.intensity)) * capacity),
+      capacity,
+      settingsRef.current.transitionDuration
+    );
     let initializedCount = 0;
     const unregister = ticker.register(LAYER.MIDGROUND, (state) => {
       const settings = settingsRef.current;
-      const count = Math.round(
+      const targetCount = Math.round(
         Math.max(0, Math.min(1, settings.intensity)) * state.budget.maxParticles
       );
+      updateParticleTransition(particles, targetCount, settings.transitionDuration, state);
+      const count = particles.count;
       pool = growParticlePool(pool, state.budget.maxParticles);
       if (count > initializedCount) {
         seedSnowRange(pool, initializedCount, count, state);
@@ -850,7 +1067,7 @@ function Snow({
           spriteRef.current = createSnowSprite(cachedSprite.image, size) ?? cachedSprite;
         }
       }
-      drawSnow(pool, count, state, settings, textureRef.current, spriteRef.current);
+      drawSnow(pool, count, state, settings, textureRef.current, spriteRef.current, particles.visibility);
     });
     return unregister;
   }, [ticker]);
@@ -892,6 +1109,7 @@ function renderRadialGradient(surface, size, color) {
 }
 function Fog({
   density = 0.4,
+  transitionDuration = 0,
   speed = 1,
   color = "rgba(220, 225, 235, 0.35)",
   layers = 3
@@ -900,11 +1118,11 @@ function Fog({
   if (!ticker) {
     throw new Error("<Fog /> must be used inside <WeatherCanvas>");
   }
-  const settingsRef = React.useRef({ density, speed, color, layers });
+  const settingsRef = React.useRef({ density, transitionDuration, speed, color, layers });
   React.useEffect(() => {
-    settingsRef.current = { density, speed, color, layers };
+    settingsRef.current = { density, transitionDuration, speed, color, layers };
     ticker.invalidate();
-  }, [ticker, density, speed, color, layers]);
+  }, [ticker, density, transitionDuration, speed, color, layers]);
   const textureRef = React.useRef(null);
   const imageBitmapRef = React.useRef(null);
   React.useEffect(() => {
@@ -951,13 +1169,18 @@ function Fog({
   }, [ticker, color]);
   React.useEffect(() => {
     const puffs = [];
+    let currentDensity = Math.max(0, Math.min(1, settingsRef.current.density));
+    const transition = createTransition(currentDensity, settingsRef.current.transitionDuration);
     const unregister = ticker.register(LAYER.BACKGROUND, (state) => {
       const texture = textureRef.current;
       if (!texture) return;
       const settings = settingsRef.current;
       const numLayers = Math.round(Math.max(1, Math.min(6, settings.layers)));
       const count = numLayers * 3;
-      const baseAlpha = Math.max(0, Math.min(1, settings.density));
+      const targetDensity = Math.max(0, Math.min(1, settings.density));
+      const step = stepTransition(transition, targetDensity, settings.transitionDuration, state);
+      currentDensity = step === 1 ? targetDensity : currentDensity + (targetDensity - currentDensity) * step;
+      const baseAlpha = currentDensity;
       if (baseAlpha === 0) return;
       for (let i = puffs.length; i < count; i++) {
         const layer = Math.floor(i / 3);