1 files changed, 61 insertions, 18 deletions
diff --git a/lib/leaves/types.ts b/lib/leaves/types.ts
index 36dd7f3..869a296 100644
--- a/lib/leaves/types.ts
+++ b/lib/leaves/types.ts
@@ -1,7 +1,7 @@
 /**
  * An individual leaf silhouette. `pathData` is the `d` attribute of an
  * `<path>` inside a `<symbol>` with the given viewBox. Rendered at various
- * pixel sizes with `width`; the aspect ratio derives from viewBox.
+ * pixel sizes; the aspect ratio derives from viewBox.
  */
 export interface LeafVariant {
   readonly id: string
@@ -11,9 +11,8 @@ export interface LeafVariant {
 
 /**
  * One leaf in flight. `x` / `y` are in CSS pixels from the top-left of the
- * scene container. `rotation` is degrees. `swayPhase` is the phase offset
- * for the horizontal sway oscillation — different per leaf so the cloud
- * doesn't drift in sync.
+ * scene container. `rotation` is degrees. `swayPhase` offsets the horizontal
+ * sway oscillation per leaf so the cloud doesn't drift in sync.
  */
 export interface Leaf {
   readonly id: number
@@ -31,23 +30,67 @@ export interface Leaf {
   readonly settled: boolean
 }
 
-/**
- * Periodic horizontal wind gusts that sweep across the scene. Direction
- * is -1 (rightward blown leftwards, odd convention — here we use +1 for
- * rightward, -1 for leftward). `remainingMs` counts down while a gust is
- * active. `nextGustInMs` counts down between gusts.
- */
-export interface WindState {
-  readonly active: boolean
-  readonly direction: 1 | -1
-  readonly strength: number
-  readonly remainingMs: number
-  readonly nextGustInMs: number
-}
-
 /** Viewport dimensions and the y-coordinate where leaves settle. */
 export interface SceneDimensions {
   readonly width: number
   readonly height: number
   readonly groundY: number
 }
+
+/**
+ * The three gust flavours the wind system can emit. Each has its own
+ * duration, strength, and particle-spawning profile.
+ *
+ *   breeze  small, slow, gentle, frequent — common idle motion
+ *   gust    medium, strong, mostly straight — occasional sweep
+ *   whirl   small, circular — rare twirl that spirals around its centre
+ */
+export type GustKind = 'breeze' | 'gust' | 'whirl'
+
+/**
+ * A wisp of visible air inside a gust — a short-lived dot that traces the
+ * gust's flow. Rendered as a small semi-transparent circle with opacity
+ * computed from `ageMs / lifetimeMs`.
+ */
+export interface WindParticle {
+  readonly id: number
+  readonly x: number
+  readonly y: number
+  readonly vx: number
+  readonly vy: number
+  readonly ageMs: number
+  readonly lifetimeMs: number
+  readonly size: number
+}
+
+/**
+ * A localised wind event. Lives for `totalDurationMs`, during which it
+ * applies force to leaves within `radius` of (`centerX`, `centerY`) and
+ * spawns `particles` that trace the wind's motion.
+ */
+export interface Gust {
+  readonly id: number
+  readonly kind: GustKind
+  readonly centerX: number
+  readonly centerY: number
+  readonly radius: number
+  readonly strength: number
+  readonly direction: number
+  readonly elapsedMs: number
+  readonly totalDurationMs: number
+  readonly particles: readonly WindParticle[]
+  readonly nextParticleSpawnInMs: number
+}
+
+/**
+ * The overall wind state. A constant horizontal prevailing wind drifts
+ * every leaf leftward at a low speed. Gusts are seldom, one at a time,
+ * and superimposed on the prevailing flow — they only apply within their
+ * own radius.
+ */
+export interface WindSystem {
+  readonly prevailingVx: number
+  readonly prevailingVy: number
+  readonly activeGust: Gust | null
+  readonly nextGustInMs: number
+}