@hdcodedev/snowfall 1.0.3 → 1.0.5

package/README.md

@@ -1,7 +1,14 @@
-# @hdcodedev/snowfall
+# [@hdcodedev/snowfall](https://next-snowfall.vercel.app)
+
+[![npm version](https://img.shields.io/npm/v/@hdcodedev/snowfall.svg)](https://www.npmjs.com/package/@hdcodedev/snowfall)
+
 
 A realistic snowfall effect for React with physics-based accumulation on surfaces. Features melting, wind, and smart surface detection.
 
+![ScreenRecording2025-12-23at00 07 30-ezgif com-optimize](https://github.com/user-attachments/assets/49c4a537-7f04-4043-806e-21478f419dd7)
+
+
+
 ## Features
 
 - **Realistic Physics** - Wind, wobble, and varied snowflake speeds
@@ -39,39 +46,69 @@ export default function App() {
     <SnowfallProvider>
       <Snowfall />
 
-      {/* Auto-detected: Semantic tags */}
+      {/* Auto-detected: Headers accumulate snow on BOTTOM */}
       <header>
         <h1>My Site</h1>
       </header>
       
+      {/* Auto-detected: Footers accumulate snow on TOP (natural piling) */}
+      <footer>
+        <p>© 2025</p>
+      </footer>
+      
       {/* Manual: Force accumulation on any element */}
       <div data-snowfall="top">
         <h2>Custom Element</h2>
       </div>
+      
+      {/* Disable accumulation on specific elements */}
+      <div data-snowfall="ignore">
+        <p>No snow here</p>
+      </div>
     </SnowfallProvider>
   );
 }
 ```
 
+### Surface Types
+
+- **`data-snowfall="top"`** (default for most elements): Snow accumulates on the top edge, piling downward
+- **`data-snowfall="bottom"`** (default for `<header>` tags): Snow accumulates on the bottom edge
+- **`data-snowfall="ignore"`**: Prevents snow accumulation on the element
+
+By default:
+- `<header>` and `role="banner"` → Bottom accumulation
+- `<footer>` and other elements → Top accumulation (natural piling)
+
 ## Customization
 
-The snowfall physics can be customized by modifying the `SNOW_PHYSICS` constant:
+You can customize physics via the `SnowfallProvider`:
 
-```typescript
-const SNOW_PHYSICS = {
+```tsx
+import { SnowfallProvider, DEFAULT_PHYSICS } from '@hdcodedev/snowfall';
+
+const customPhysics = {
+  ...DEFAULT_PHYSICS,
   MAX_FLAKES: 500,              // Maximum number of snowflakes
   MELT_SPEED: 0.00005,          // How fast snow melts (lower = lasts longer)
+  WIND_STRENGTH: 1.5,           // Wind intensity
   ACCUMULATION: {
-    SIDE_RATE: 1.2,             // Accumulation rate on sides
-    TOP_CARD_RATE: 1.9,         // Accumulation rate on card tops
-    TOP_HEADER_RATE: 1.2,       // Accumulation rate on header tops
+    SIDE_RATE: 1.0,             // Accumulation rate on sides
+    TOP_RATE: 5.0,              // Accumulation rate on top surfaces
+    BOTTOM_RATE: 5.0,           // Accumulation rate on bottom surfaces (headers)
   },
   MAX_DEPTH: {
-    CARD_TOP: 50,               // Max snow height on cards (px)
-    HEADER_TOP: 25,             // Max snow height on headers (px)
-    CARD_SIDE: 8,               // Max snow width on card sides (px)
+    TOP: 100,                   // Max snow height on top surfaces (px)
+    BOTTOM: 50,                 // Max snow height on bottom surfaces (px)
+    SIDE: 20,                   // Max snow width on sides (px)
+  },
+  FLAKE_SIZE: {
+    MIN: 0.5,                   // Minimum flake radius
+    MAX: 1.6,                   // Maximum flake radius
   }
 };
+
+// Then use it in your provider - see API section below
 ```
 
 ## API
@@ -95,15 +132,14 @@ Hook to access snowfall controls. Must be used within `SnowfallProvider`.
 **Returns:**
 ```typescript
 {
-  isEnabled: boolean;        // Current enabled state
-  toggleSnow: () => void;    // Function to toggle snow on/off
+  isEnabled: boolean;                           // Current enabled state
+  toggleSnow: () => void;                       // Function to toggle snow on/off
+  physicsConfig: PhysicsConfig;                 // Current physics configuration
+  updatePhysicsConfig: (config: Partial<PhysicsConfig>) => void;  // Update physics
+  resetPhysics: () => void;                     // Reset to default physics
 }
 ```
 
-## Demo
-
-Check out the [live demo](https://snowfall-2026.vercel.app)
-
 ## Tips
 
 - The snowfall canvas has `pointer-events: none`, so it won't interfere with user interactions

package/dist/index.d.mts

@@ -23,16 +23,35 @@ interface PhysicsConfig {
     };
 }
 declare const DEFAULT_PHYSICS: PhysicsConfig;
+interface PerformanceMetrics {
+    fps: number;
+    frameTime: number;
+    scanTime: number;
+    rectUpdateTime: number;
+    surfaceCount: number;
+    flakeCount: number;
+    maxFlakes: number;
+    rafGap: number;
+    clearTime: number;
+    physicsTime: number;
+    drawTime: number;
+}
 interface SnowfallContextType {
     isEnabled: boolean;
     toggleSnow: () => void;
     physicsConfig: PhysicsConfig;
     updatePhysicsConfig: (config: Partial<PhysicsConfig>) => void;
     resetPhysics: () => void;
+    debugMode: boolean;
+    toggleDebug: () => void;
+    metrics: PerformanceMetrics | null;
+    setMetrics: (metrics: PerformanceMetrics) => void;
 }
 declare function SnowfallProvider({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 declare function useSnowfall(): SnowfallContextType;
 
-export { DEFAULT_PHYSICS, type PhysicsConfig, Snowfall, SnowfallProvider, useSnowfall };
+declare function DebugPanel(): react_jsx_runtime.JSX.Element | null;
+
+export { DEFAULT_PHYSICS, DebugPanel, type PerformanceMetrics, type PhysicsConfig, Snowfall, SnowfallProvider, useSnowfall };

package/dist/index.d.ts

@@ -23,16 +23,35 @@ interface PhysicsConfig {
     };
 }
 declare const DEFAULT_PHYSICS: PhysicsConfig;
+interface PerformanceMetrics {
+    fps: number;
+    frameTime: number;
+    scanTime: number;
+    rectUpdateTime: number;
+    surfaceCount: number;
+    flakeCount: number;
+    maxFlakes: number;
+    rafGap: number;
+    clearTime: number;
+    physicsTime: number;
+    drawTime: number;
+}
 interface SnowfallContextType {
     isEnabled: boolean;
     toggleSnow: () => void;
     physicsConfig: PhysicsConfig;
     updatePhysicsConfig: (config: Partial<PhysicsConfig>) => void;
     resetPhysics: () => void;
+    debugMode: boolean;
+    toggleDebug: () => void;
+    metrics: PerformanceMetrics | null;
+    setMetrics: (metrics: PerformanceMetrics) => void;
 }
 declare function SnowfallProvider({ children }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 declare function useSnowfall(): SnowfallContextType;
 
-export { DEFAULT_PHYSICS, type PhysicsConfig, Snowfall, SnowfallProvider, useSnowfall };
+declare function DebugPanel(): react_jsx_runtime.JSX.Element | null;
+
+export { DEFAULT_PHYSICS, DebugPanel, type PerformanceMetrics, type PhysicsConfig, Snowfall, SnowfallProvider, useSnowfall };