snowstack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carl Kendrick Camus
+
+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

@@ -0,0 +1,169 @@
+# ❄️ SnowStack
+
+**SnowStack** is a lightweight, interactive snow effect for React/Next.js that combines:
+
+- Smooth snowfall (React-Snowfall–style calm mode)
+- Snow accumulation at the bottom of the screen
+- Optional **interactive shovel** (scoop + throw with physics)
+- Mobile-safe interaction (no scroll hijacking)
+- Performance-bounded presets to protect production sites
+
+Built with **Canvas + Matter.js**, designed to be fun without being destructive.
+
+---
+
+## ✨ Features
+
+- 🌨 **Snowfall Engine** — density, speed, size, wind
+- ❄️ **Accumulation** — piles up naturally at the bottom
+- 🥄 **Interactive Shovel (optional)** — scoop and throw chunks with physics
+- 📱 **Mobile-safe controls** — shovel ON/OFF toggle + pointer capture
+- 🧊 **Presets-first** — safe defaults, bounded ranges
+- ⚡ **Performance guarded** — capped FPS and chunk limits
+
+---
+
+## 📦 Install
+
+```bash
+npm install snowstack
+# or
+pnpm add snowstack
+# or
+yarn add snowstack
+````
+
+---
+
+## 🚀 Quick Start
+
+> ⚠️ SnowStack is a client-side effect and must be used inside `"use client"` components.
+
+
+```tsx
+import { SnowStack } from "snowstack";
+
+export default function Page() {
+  return <SnowStack />;
+}
+```
+
+Default behavior is **calm, non-interactive snowfall**.
+
+---
+
+## 🎛 Presets
+
+Available presets:
+
+* `calm` (default) — subtle snowfall
+* `cozy` — a bit denser
+* `storm` — heavy snow + stronger wind (still clamped for safety)
+* `interactive` — enables shovel + physics chunks
+
+```tsx
+<SnowStack preset="cozy" />
+```
+
+---
+
+## 🥄 Interactive Mode (Shovel)
+
+```tsx
+<SnowStack preset="interactive" interactive />
+```
+
+### Desktop
+
+* Hold **Shift**
+* Drag near the snow pile to scoop
+* Release to throw
+
+### Mobile
+
+* Tap **Shovel: ON**
+* Drag to scoop
+* Release to throw
+* Tap **Shovel: OFF** to disable
+
+---
+
+## Safe Customization (Limited by Design)
+
+SnowStack exposes only safe knobs:
+
+```tsx
+<SnowStack
+  preset="calm"
+  intensity={0.4}  // 0..1 (density)
+  speed={0.3}      // 0..1 (fall speed)
+  wind={0.2}       // 0..1 (wind influence)
+  interactive={false}
+/>
+```
+
+All internal values are **clamped** to prevent runaway CPU usage.
+
+---
+
+## 📷 Demo
+
+![SnowStack Demo](./assets/demo.gif)
+
+- This demo used a preset "storm" 
+---
+
+## 🧠 Tech
+
+* React / Next.js (`"use client"`)
+* Canvas rendering
+* Matter.js (snow chunks only)
+* requestAnimationFrame loops
+* Minimal DOM (mostly canvas)
+
+---
+
+## ⚡ Performance Notes
+
+SnowStack automatically:
+
+* caps snowflake counts
+* limits physics bodies
+* removes off-screen chunks
+* keeps FPS bounded
+
+---
+
+## 🤝 Contributing & Forking
+
+SnowStack is intentionally designed to be **safe by default**.
+
+You are welcome to:
+
+- Fork the project
+- Modify visuals (SVGs, colors, shovel appearance)
+- Create new presets
+- Optimize or extend physics behavior
+
+### Design Philosophy
+
+To keep SnowStack production-friendly:
+
+- Public props are **intentionally limited**
+- All internal values are **clamped**
+- Presets are preferred over raw configuration
+- Heavy physics runs **only when interactive mode is enabled**
+
+If you add new controls, please:
+- keep reasonable bounds
+- avoid unbounded loops or unguarded physics
+- respect mobile performance constraints
+
+Pull requests are welcome if they align with these goals.
+
+---
+
+
+
+## 📜 License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type SnowPresetName = "calm" | "cozy" | "storm" | "interactive";
+type SnowStackProps = {
+    enabled?: boolean;
+    preset?: SnowPresetName;
+    intensity?: number;
+    speed?: number;
+    wind?: number;
+    interactive?: boolean;
+};
+declare function SnowStack(props: SnowStackProps): react_jsx_runtime.JSX.Element;
+
+type MatterConfig = {
+    gravityY: number;
+    restitution: number;
+    friction: number;
+    frictionAir: number;
+    ttlMs: number;
+    allowSideExit: boolean;
+    maxBodies: number;
+};
+type MatterAPI = {
+    throwChunks: (x: number, y: number, vx: number, vy: number, count: number, rBase: number) => void;
+    setConfig: (partial: Partial<MatterConfig>) => void;
+};
+declare function MatterSnowChunks({ zIndex, apiRef, initialConfig, }: {
+    zIndex?: number;
+    apiRef: React.MutableRefObject<MatterAPI | null>;
+    initialConfig?: Partial<MatterConfig>;
+}): react_jsx_runtime.JSX.Element;
+
+export { type MatterAPI, type MatterConfig, MatterSnowChunks, SnowStack, type SnowStackProps };

package/dist/index.js

@@ -0,0 +1,907 @@
+import { useRef, useEffect, useMemo, useState } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { Shovel } from 'lucide-react';
+import Matter from 'matter-js';
+
+function useRafLoop(fn) {
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  useEffect(() => {
+    let raf = 0;
+    const loop = (t) => {
+      raf = requestAnimationFrame(loop);
+      fnRef.current(t);
+    };
+    raf = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(raf);
+  }, []);
+}
+
+// src/physics/physics.ts
+function clamp(n, a, b) {
+  return Math.max(a, Math.min(b, n));
+}
+
+// src/physics/snowHeightfield.ts
+function createHeightfield(cols, colW, w, h, maxDepth) {
+  return { cols, colW, w, h, maxDepth, heights: new Float32Array(cols) };
+}
+function depositAtX(model, x, amount) {
+  const i = clamp(Math.floor(x / model.colW), 0, model.cols - 1);
+  add(model, i, amount * 0.6);
+  add(model, i - 1, amount * 0.22);
+  add(model, i + 1, amount * 0.22);
+}
+function add(model, idx, amt) {
+  if (idx < 0 || idx >= model.cols) return;
+  model.heights[idx] = clamp(model.heights[idx] + amt, 0, model.maxDepth);
+}
+function smoothHeights(model, k) {
+  const h = model.heights;
+  const tmp = new Float32Array(h.length);
+  for (let i = 0; i < h.length; i++) {
+    const a = h[i - 1] ?? h[i];
+    const b = h[i];
+    const c = h[i + 1] ?? h[i];
+    const avg = (a + b + c) / 3;
+    tmp[i] = b + (avg - b) * k;
+  }
+  model.heights.set(tmp);
+}
+function avgHeight(model) {
+  const h = model.heights;
+  let sum = 0;
+  for (let i = 0; i < h.length; i++) sum += h[i];
+  return sum / h.length;
+}
+function driftGround(model, windX) {
+  const h = model.heights;
+  const tmp = new Float32Array(h.length);
+  tmp.set(h);
+  const k = Math.min(0.06, Math.abs(windX) * 0.02);
+  if (k <= 0) return;
+  if (windX > 0) {
+    for (let i = h.length - 2; i >= 0; i--) {
+      const move = tmp[i] * k;
+      tmp[i] -= move;
+      tmp[i + 1] += move;
+    }
+  } else {
+    for (let i = 1; i < h.length; i++) {
+      const move = tmp[i] * k;
+      tmp[i] -= move;
+      tmp[i - 1] += move;
+    }
+  }
+  for (let i = 0; i < tmp.length; i++) tmp[i] = clamp(tmp[i], 0, model.maxDepth);
+  model.heights.set(tmp);
+}
+function removeSnowRect(model, x, y, w, h, maxRemove) {
+  const leftCol = clamp(Math.floor(x / model.colW), 0, model.cols - 1);
+  const rightCol = clamp(Math.floor((x + w) / model.colW), 0, model.cols - 1);
+  let removed = 0;
+  for (let i = leftCol; i <= rightCol; i++) {
+    if (removed >= maxRemove) break;
+    const surfaceY = model.h - model.heights[i];
+    const rectBottom = y + h;
+    if (rectBottom <= surfaceY) continue;
+    const penetration = rectBottom - surfaceY;
+    const take = clamp(penetration * 0.35, 0, model.heights[i]);
+    const remaining = maxRemove - removed;
+    const actual = Math.min(take, remaining);
+    model.heights[i] = clamp(model.heights[i] - actual, 0, model.maxDepth);
+    removed += actual;
+  }
+  return removed;
+}
+function SnowAccumulationCanvas({
+  zIndex = 2,
+  enabled,
+  windX,
+  apiRef,
+  onAvgDepth,
+  // package controls
+  pileMaxDepth = 220,
+  pileSmoothness = 0.06,
+  pileFPS = 30,
+  colW = 6
+}) {
+  const canvasRef = useRef(null);
+  const modelRef = useRef(null);
+  const drawRef = useRef({
+    dpr: 1,
+    w: 0,
+    h: 0
+  });
+  const settings = useMemo(
+    () => ({
+      colW,
+      maxDepth: pileMaxDepth,
+      smoothK: pileSmoothness,
+      fps: pileFPS
+    }),
+    [colW, pileMaxDepth, pileSmoothness, pileFPS]
+  );
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const resize = () => {
+      const dpr = Math.max(1, Math.min(2, window.devicePixelRatio || 1));
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      canvas.style.width = w + "px";
+      canvas.style.height = h + "px";
+      canvas.width = Math.floor(w * dpr);
+      canvas.height = Math.floor(h * dpr);
+      drawRef.current = { dpr, w, h };
+      const cols = Math.ceil(w / settings.colW);
+      modelRef.current = createHeightfield(cols, settings.colW, w, h, settings.maxDepth);
+      apiRef.current = {
+        getHeights: () => modelRef.current.heights,
+        getMeta: () => ({
+          cols: modelRef.current.cols,
+          colW: modelRef.current.colW,
+          w: modelRef.current.w,
+          h: modelRef.current.h
+        }),
+        removeRect: (x, y, rw, rh, maxRemove) => removeSnowRect(modelRef.current, x, y, rw, rh, maxRemove),
+        depositAtX: (x, amount) => {
+          const m = modelRef.current;
+          if (!m) return;
+          depositAtX(m, x, amount);
+        }
+      };
+    };
+    resize();
+    window.addEventListener("resize", resize);
+    return () => window.removeEventListener("resize", resize);
+  }, [apiRef, settings]);
+  const lastFrameRef = useRef(0);
+  useRafLoop((t) => {
+    if (!enabled) return;
+    const model = modelRef.current;
+    const canvas = canvasRef.current;
+    if (!model || !canvas) return;
+    const targetMs = 1e3 / settings.fps;
+    if (t - lastFrameRef.current < targetMs) return;
+    lastFrameRef.current = t;
+    driftGround(model, windX);
+    smoothHeights(model, settings.smoothK);
+    onAvgDepth?.(avgHeight(model));
+    drawSnow(canvas, model, drawRef.current.dpr);
+  });
+  if (!enabled) return null;
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      "aria-hidden": "true",
+      style: { position: "fixed", inset: 0, zIndex, pointerEvents: "none" }
+    }
+  );
+}
+function drawSnow(canvas, model, dpr) {
+  const ctx = canvas.getContext("2d");
+  const w = model.w;
+  const h = model.h;
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, w, h);
+  const heights = model.heights;
+  const colW = model.colW;
+  ctx.beginPath();
+  ctx.moveTo(0, h);
+  for (let i = 0; i < heights.length; i++) {
+    const x = i * colW;
+    const y = h - heights[i];
+    ctx.lineTo(x, y);
+  }
+  ctx.lineTo(w, h);
+  ctx.closePath();
+  ctx.fillStyle = "rgba(255,255,255,0.92)";
+  ctx.fill();
+  ctx.strokeStyle = "rgba(255,255,255,0.65)";
+  ctx.lineWidth = 1;
+  ctx.stroke();
+}
+function SnowfallEngine({
+  zIndex = 1,
+  enabled,
+  getAPI,
+  windX,
+  flakeCount = 220,
+  snowfallSpeed = 1,
+  snowflakeSize = [0.9, 2.2]
+}) {
+  const canvasRef = useRef(null);
+  const flakesRef = useRef([]);
+  const lastRef = useRef(0);
+  useEffect(() => {
+    if (!enabled) return;
+    const init = () => {
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      const [rMin, rMax] = snowflakeSize;
+      flakesRef.current = Array.from({ length: flakeCount }, () => ({
+        x: Math.random() * w,
+        y: Math.random() * h,
+        vx: (Math.random() - 0.5) * 0.25,
+        vy: (0.35 + Math.random() * 0.9) * snowfallSpeed,
+        r: rMin + Math.random() * (rMax - rMin)
+      }));
+    };
+    init();
+    window.addEventListener("resize", init);
+    return () => window.removeEventListener("resize", init);
+  }, [enabled, flakeCount, snowfallSpeed, snowflakeSize]);
+  useEffect(() => {
+    if (!enabled) return;
+    let raf = 0;
+    const loop = (t) => {
+      raf = requestAnimationFrame(loop);
+      const canvas = canvasRef.current;
+      const api = getAPI();
+      if (!canvas || !api) return;
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      const dpr = Math.max(1, Math.min(2, window.devicePixelRatio || 1));
+      canvas.style.width = w + "px";
+      canvas.style.height = h + "px";
+      canvas.width = Math.floor(w * dpr);
+      canvas.height = Math.floor(h * dpr);
+      const ctx = canvas.getContext("2d");
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      ctx.clearRect(0, 0, w, h);
+      const dt = Math.min(40, Math.max(10, t - (lastRef.current || t)));
+      lastRef.current = t;
+      const flakes = flakesRef.current;
+      const meta = api.getMeta();
+      const heights = api.getHeights();
+      ctx.fillStyle = "rgba(255,255,255,0.92)";
+      for (const f of flakes) {
+        f.vx += windX * 26e-4;
+        f.vx *= 0.995;
+        f.vy += 11e-4 * (dt / 16.67) * snowfallSpeed;
+        f.x += f.vx * dt;
+        f.y += f.vy * dt;
+        if (f.x < -10) f.x = w + 10;
+        if (f.x > w + 10) f.x = -10;
+        const col = Math.max(0, Math.min(meta.cols - 1, Math.floor(f.x / meta.colW)));
+        const surfaceY = meta.h - heights[col];
+        if (f.y >= surfaceY) {
+          api.depositAtX(f.x, 0.55 + f.r * 0.28);
+          const [rMin, rMax] = snowflakeSize;
+          f.x = Math.random() * w;
+          f.y = -10 - Math.random() * 140;
+          f.vx = (Math.random() - 0.5) * 0.25;
+          f.vy = (0.35 + Math.random() * 0.95) * snowfallSpeed;
+          f.r = rMin + Math.random() * (rMax - rMin);
+        }
+        ctx.beginPath();
+        ctx.arc(f.x, f.y, f.r, 0, Math.PI * 2);
+        ctx.fill();
+      }
+    };
+    raf = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(raf);
+  }, [enabled, getAPI, windX, snowfallSpeed, snowflakeSize]);
+  if (!enabled) return null;
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      "aria-hidden": "true",
+      style: { position: "fixed", inset: 0, zIndex, pointerEvents: "none" }
+    }
+  );
+}
+var clamp01 = (v) => Math.max(0, Math.min(1, v));
+function ShovelWithSnow({
+  loadRatio,
+  size = 46,
+  strokeWidth = 2.2
+}) {
+  const r = clamp01(loadRatio);
+  const snowOpacity = 0.25 + 0.75 * r;
+  const snowScale = 0.65 + 0.75 * r;
+  const snowX = 10.5;
+  const snowY = 13.2;
+  return /* @__PURE__ */ jsxs("div", { style: { position: "relative", width: size, height: size }, children: [
+    /* @__PURE__ */ jsx(Shovel, { size, strokeWidth }),
+    r > 0.03 && /* @__PURE__ */ jsx(
+      "svg",
+      {
+        width: size,
+        height: size,
+        viewBox: "0 0 24 24",
+        style: {
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+          opacity: 1,
+          filter: "drop-shadow(0 4px 8px rgba(0,0,0,0.22))"
+        },
+        children: /* @__PURE__ */ jsxs("g", { transform: `translate(${snowX}, ${snowY}) scale(${snowScale})`, children: [
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              d: "M0.4 5.8\n                 C1.6 3.2 5.6 2.8 7.6 4.1\n                 C9.9 5.5 10.1 8.1 8.3 9.6\n                 C6.2 11.4 3.0 11.0 1.3 9.7\n                 C-0.4 8.4 -0.3 7.1 0.4 5.8 Z",
+              fill: `rgba(245,248,255,${snowOpacity})`
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              d: "M1.6 5.8 C2.8 4.6 5.2 4.3 6.8 5.1",
+              stroke: `rgba(255,255,255,${0.35 + 0.5 * r})`,
+              strokeWidth: "0.7",
+              strokeLinecap: "round",
+              fill: "none"
+            }
+          ),
+          r > 0.2 && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("circle", { cx: "7.5", cy: "8.2", r: 0.35 + 0.25 * r, fill: "rgba(255,255,255,0.95)" }),
+            /* @__PURE__ */ jsx("circle", { cx: "5.8", cy: "7.1", r: 0.28 + 0.18 * r, fill: "rgba(255,255,255,0.9)" }),
+            /* @__PURE__ */ jsx("circle", { cx: "6.4", cy: "6.3", r: 0.22 + 0.14 * r, fill: "rgba(255,255,255,0.85)" })
+          ] })
+        ] })
+      }
+    )
+  ] });
+}
+function isTouchDevice() {
+  if (typeof window === "undefined") return false;
+  return "ontouchstart" in window || navigator.maxTouchPoints > 0;
+}
+function SnowShovel({
+  zIndex = 3,
+  visible,
+  scale,
+  getAPI,
+  getMatter
+}) {
+  const touch = useMemo(() => isTouchDevice(), []);
+  const [armed, setArmed] = useState(false);
+  const [pos, setPos] = useState({ x: 120, y: 120 });
+  const [loadUI, setLoadUI] = useState(0);
+  const loadRef = useRef(0);
+  const draggingRef = useRef(false);
+  const lastRef = useRef({ x: 0, y: 0, t: 0 });
+  const lastCommitRef = useRef(0);
+  const shovel = useMemo(() => {
+    const headW = 92 * scale;
+    const headH = 44 * scale;
+    const capacity = 140 * scale;
+    return { headW, headH, capacity };
+  }, [scale]);
+  useEffect(() => {
+    if (touch) return;
+    const kd = (e) => e.key === "Shift" && setArmed(true);
+    const ku = (e) => e.key === "Shift" && setArmed(false);
+    window.addEventListener("keydown", kd);
+    window.addEventListener("keyup", ku);
+    return () => {
+      window.removeEventListener("keydown", kd);
+      window.removeEventListener("keyup", ku);
+    };
+  }, [touch]);
+  useEffect(() => {
+    let raf = 0;
+    const tick = (t) => {
+      raf = requestAnimationFrame(tick);
+      if (!visible || !armed || !draggingRef.current) return;
+      const api = getAPI();
+      if (!api) return;
+      const load = loadRef.current;
+      const remaining = shovel.capacity - load;
+      if (remaining <= 0) return;
+      const bladeX = pos.x + 22 * scale;
+      const bladeY = pos.y + 16 * scale;
+      const rectX = bladeX - shovel.headW / 2;
+      const rectY = bladeY - shovel.headH / 2;
+      const taken = api.removeRect(rectX, rectY, shovel.headW, shovel.headH, remaining);
+      if (taken > 0) {
+        loadRef.current = clamp(load + taken, 0, shovel.capacity);
+        if (t - lastCommitRef.current > 50) {
+          lastCommitRef.current = t;
+          setLoadUI(loadRef.current);
+        }
+      }
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [armed, visible, pos.x, pos.y, scale, shovel.capacity, shovel.headW, shovel.headH, getAPI]);
+  function throwSnow(x, y) {
+    const matter = getMatter();
+    if (!matter) return;
+    const now = performance.now();
+    const last = lastRef.current;
+    const dt = Math.max(16, now - last.t);
+    const dx = x - last.x;
+    const dy = y - last.y;
+    let vx = dx / (dt / 16.67);
+    let vy = dy / (dt / 16.67);
+    vx = clamp(vx, -70, 70);
+    vy = clamp(vy, -70, 70);
+    lastRef.current = { x, y, t: now };
+    const amt = loadRef.current;
+    loadRef.current = 0;
+    setLoadUI(0);
+    const count = Math.floor(clamp(amt / (7 * scale), 10, 44));
+    const rBase = 2.4 * scale;
+    matter.throwChunks(x, y, vx, vy, count, rBase);
+  }
+  if (!visible) return null;
+  const loadRatio = loadUI / shovel.capacity;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    touch && /* @__PURE__ */ jsx(
+      "button",
+      {
+        onClick: () => setArmed((v) => !v),
+        style: {
+          position: "fixed",
+          right: 16,
+          bottom: 16,
+          zIndex: zIndex + 50,
+          padding: "10px 14px",
+          borderRadius: 999,
+          border: "1px solid rgba(255,255,255,0.22)",
+          background: armed ? "rgba(255,255,255,0.92)" : "rgba(15, 23, 42, 0.60)",
+          color: armed ? "rgba(15,23,42,0.95)" : "rgba(255,255,255,0.92)",
+          fontSize: 12,
+          fontWeight: 700,
+          cursor: "pointer"
+        },
+        children: armed ? "Shovel: ON" : "Shovel: OFF"
+      }
+    ),
+    touch && armed && /* @__PURE__ */ jsx(
+      "div",
+      {
+        style: {
+          position: "fixed",
+          inset: 0,
+          zIndex: zIndex + 40,
+          background: "transparent",
+          touchAction: "none",
+          // ✅ stop scroll/zoom stealing drag
+          pointerEvents: "auto"
+        },
+        onPointerDown: (e) => {
+          const el = e.currentTarget;
+          el.setPointerCapture(e.pointerId);
+          draggingRef.current = true;
+          setPos({ x: e.clientX, y: e.clientY });
+          lastRef.current = { x: e.clientX, y: e.clientY, t: performance.now() };
+        },
+        onPointerMove: (e) => {
+          setPos({ x: e.clientX, y: e.clientY });
+        },
+        onPointerUp: (e) => {
+          if (loadRef.current > 1) throwSnow(e.clientX, e.clientY);
+          draggingRef.current = false;
+        },
+        onPointerCancel: () => {
+          draggingRef.current = false;
+        }
+      }
+    ),
+    !touch && /* @__PURE__ */ jsx(
+      DesktopPointerTracker,
+      {
+        onMove: (x, y) => setPos({ x, y }),
+        onDown: (x, y) => {
+          if (!armed) return;
+          draggingRef.current = true;
+          lastRef.current = { x, y, t: performance.now() };
+        },
+        onUp: (x, y) => {
+          if (armed && loadRef.current > 1) throwSnow(x, y);
+          draggingRef.current = false;
+        }
+      }
+    ),
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        style: {
+          position: "fixed",
+          left: pos.x,
+          top: pos.y,
+          zIndex,
+          pointerEvents: "none",
+          transform: `translate(-30%, -30%) rotate(${armed ? -18 : -35}deg) scale(${scale})`,
+          opacity: armed ? 1 : 0.92,
+          transition: "opacity 200ms ease, transform 200ms ease",
+          userSelect: "none",
+          filter: "drop-shadow(0 10px 18px rgba(0,0,0,0.25))"
+        },
+        children: [
+          /* @__PURE__ */ jsx(ShovelWithSnow, { loadRatio, size: 46 }),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              style: {
+                marginTop: 6,
+                width: 120,
+                height: 8,
+                borderRadius: 999,
+                background: "rgba(255,255,255,0.25)",
+                overflow: "hidden"
+              },
+              children: /* @__PURE__ */ jsx(
+                "div",
+                {
+                  style: {
+                    width: `${loadRatio * 100}%`,
+                    height: "100%",
+                    background: "rgba(255,255,255,0.92)"
+                  }
+                }
+              )
+            }
+          )
+        ]
+      }
+    )
+  ] });
+}
+function DesktopPointerTracker({
+  onMove,
+  onDown,
+  onUp
+}) {
+  useEffect(() => {
+    const move = (e) => onMove(e.clientX, e.clientY);
+    const down = (e) => onDown(e.clientX, e.clientY);
+    const up = (e) => onUp(e.clientX, e.clientY);
+    window.addEventListener("pointermove", move, { passive: true });
+    window.addEventListener("pointerdown", down);
+    window.addEventListener("pointerup", up);
+    return () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerdown", down);
+      window.removeEventListener("pointerup", up);
+    };
+  }, [onMove, onDown, onUp]);
+  return null;
+}
+var DEFAULT_CFG = {
+  gravityY: 1,
+  restitution: 0.35,
+  friction: 0.1,
+  frictionAir: 0.02,
+  ttlMs: 2500,
+  allowSideExit: true,
+  maxBodies: 200
+};
+function MatterSnowChunks({
+  zIndex = 4,
+  apiRef,
+  initialConfig
+}) {
+  const canvasRef = useRef(null);
+  useEffect(() => {
+    const Engine = Matter.Engine;
+    const World = Matter.World;
+    const Bodies = Matter.Bodies;
+    const Composite = Matter.Composite;
+    const engine = Engine.create({ enableSleeping: true });
+    const cfgRef = { current: { ...DEFAULT_CFG, ...initialConfig ?? {} } };
+    const bornAt = /* @__PURE__ */ new WeakMap();
+    const order = [];
+    const canvas = canvasRef.current;
+    const ctx = canvas.getContext("2d");
+    const buildBoundaries = () => {
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      Composite.clear(engine.world, false);
+      const thick = 160;
+      const ground = Bodies.rectangle(w / 2, h + thick / 2, w + 800, thick, { isStatic: true });
+      World.add(engine.world, [ground]);
+      if (!cfgRef.current.allowSideExit) {
+        const wallT = 160;
+        const left = Bodies.rectangle(-wallT / 2, h / 2, wallT, h + 800, { isStatic: true });
+        const right = Bodies.rectangle(w + wallT / 2, h / 2, wallT, h + 800, { isStatic: true });
+        World.add(engine.world, [left, right]);
+      }
+    };
+    const syncSize = () => {
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      const dpr = Math.max(1, Math.min(2, window.devicePixelRatio || 1));
+      canvas.style.width = w + "px";
+      canvas.style.height = h + "px";
+      canvas.width = Math.floor(w * dpr);
+      canvas.height = Math.floor(h * dpr);
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      buildBoundaries();
+    };
+    const applyEngineCfg = () => {
+      engine.gravity.y = cfgRef.current.gravityY;
+    };
+    const removeBody = (b) => {
+      World.remove(engine.world, b);
+      const idx = order.indexOf(b);
+      if (idx >= 0) order.splice(idx, 1);
+    };
+    const enforceCap = () => {
+      const cfg = cfgRef.current;
+      let dynCount = 0;
+      for (const b of order) if (!b.isStatic) dynCount++;
+      while (dynCount > cfg.maxBodies) {
+        const oldest = order.find((b) => !b.isStatic);
+        if (!oldest) break;
+        removeBody(oldest);
+        dynCount--;
+      }
+    };
+    syncSize();
+    applyEngineCfg();
+    window.addEventListener("resize", syncSize);
+    apiRef.current = {
+      throwChunks: (x, y, vx, vy, count, rBase) => {
+        const cfg = cfgRef.current;
+        for (let i = 0; i < count; i++) {
+          const r = rBase * (0.7 + Math.random() * 0.9);
+          const b = Bodies.circle(x, y, r, {
+            restitution: cfg.restitution,
+            friction: cfg.friction,
+            frictionAir: cfg.frictionAir
+          });
+          Matter.Body.setVelocity(b, {
+            x: vx * 0.9 + (Math.random() - 0.5) * 6,
+            y: vy * 0.7 - (8 + Math.random() * 8)
+          });
+          bornAt.set(b, performance.now());
+          order.push(b);
+          World.add(engine.world, b);
+        }
+        enforceCap();
+      },
+      setConfig: (partial) => {
+        const prevAllow = cfgRef.current.allowSideExit;
+        cfgRef.current = { ...cfgRef.current, ...partial };
+        applyEngineCfg();
+        if (partial.allowSideExit !== void 0 && partial.allowSideExit !== prevAllow) {
+          buildBoundaries();
+        }
+        if (partial.maxBodies !== void 0) {
+          enforceCap();
+        }
+      }
+    };
+    let raf = 0;
+    const loop = () => {
+      raf = requestAnimationFrame(loop);
+      Engine.update(engine, 1e3 / 60);
+      const w = window.innerWidth;
+      const h = window.innerHeight;
+      ctx.clearRect(0, 0, w, h);
+      ctx.fillStyle = "rgba(255,255,255,0.92)";
+      const now = performance.now();
+      const ttl = cfgRef.current.ttlMs;
+      for (const b of [...order]) {
+        if (b.isStatic) continue;
+        const born = bornAt.get(b) ?? now;
+        const age = now - born;
+        if (age > ttl) {
+          removeBody(b);
+          continue;
+        }
+        if (b.position.x < -500 || b.position.x > w + 500 || b.position.y > h + 800 || b.position.y < -800) {
+          removeBody(b);
+          continue;
+        }
+        const r = b.circleRadius || 3;
+        ctx.beginPath();
+        ctx.arc(b.position.x, b.position.y, r, 0, Math.PI * 2);
+        ctx.fill();
+      }
+      enforceCap();
+    };
+    loop();
+    return () => {
+      cancelAnimationFrame(raf);
+      window.removeEventListener("resize", syncSize);
+      apiRef.current = null;
+    };
+  }, [apiRef, initialConfig]);
+  return /* @__PURE__ */ jsx(
+    "canvas",
+    {
+      ref: canvasRef,
+      "aria-hidden": "true",
+      style: { position: "fixed", inset: 0, zIndex, pointerEvents: "none" }
+    }
+  );
+}
+function useWindFromScroll() {
+  const [windX, setWindX] = useState(0);
+  useEffect(() => {
+    let lastY = window.scrollY;
+    let lastT = performance.now();
+    const onScroll = () => {
+      const y = window.scrollY;
+      const t = performance.now();
+      const dt = Math.max(16, t - lastT);
+      const v = (y - lastY) / dt;
+      const w = Math.max(-2, Math.min(2, v * 20));
+      setWindX(w);
+      lastY = y;
+      lastT = t;
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+  return windX;
+}
+var PRESETS = {
+  calm: {
+    flakeCount: 120,
+    snowfallSpeed: 0.6,
+    snowflakeSize: [0.8, 1.8],
+    windStrength: 0.5,
+    pileMaxDepth: 160,
+    pileSmoothness: 0.078,
+    pileFPS: 20,
+    shovelScale: 1,
+    shovelRevealDepth: 9999,
+    chunkTtlMs: 3800,
+    chunkBounciness: 0.25,
+    chunkAirDrag: 0.03,
+    chunkAllowSideExit: true,
+    chunkGravityY: 0.9
+  },
+  cozy: {
+    flakeCount: 170,
+    snowfallSpeed: 0.9,
+    snowflakeSize: [0.9, 2.2],
+    windStrength: 0.8,
+    pileMaxDepth: 200,
+    pileSmoothness: 0.06,
+    pileFPS: 30,
+    shovelScale: 1,
+    shovelRevealDepth: 28,
+    chunkTtlMs: 4500,
+    chunkBounciness: 0.35,
+    chunkAirDrag: 0.02,
+    chunkAllowSideExit: true,
+    chunkGravityY: 1
+  },
+  storm: {
+    flakeCount: 240,
+    snowfallSpeed: 1.15,
+    snowflakeSize: [1, 2.6],
+    windStrength: 1.15,
+    pileMaxDepth: 220,
+    pileSmoothness: 0.058,
+    pileFPS: 30,
+    shovelScale: 1,
+    shovelRevealDepth: 22,
+    chunkTtlMs: 5e3,
+    chunkBounciness: 0.35,
+    chunkAirDrag: 0.02,
+    chunkAllowSideExit: true,
+    chunkGravityY: 1.05
+  },
+  interactive: {
+    flakeCount: 220,
+    snowfallSpeed: 1,
+    snowflakeSize: [0.9, 2.3],
+    windStrength: 1,
+    pileMaxDepth: 220,
+    pileSmoothness: 0.06,
+    pileFPS: 30,
+    shovelScale: 1,
+    shovelRevealDepth: 18,
+    chunkTtlMs: 4500,
+    chunkBounciness: 0.35,
+    chunkAirDrag: 0.02,
+    chunkAllowSideExit: true,
+    chunkGravityY: 1
+  }
+};
+var clamp012 = (v) => Math.max(0, Math.min(1, v));
+var clampNum = (v, a, b) => Math.max(a, Math.min(b, v));
+function applySafety(p) {
+  return {
+    ...p,
+    flakeCount: clampNum(p.flakeCount, 60, 260),
+    snowfallSpeed: clampNum(p.snowfallSpeed, 0.45, 1.2),
+    snowflakeSize: [clampNum(p.snowflakeSize[0], 0.6, 1.6), clampNum(p.snowflakeSize[1], 1.2, 3.2)],
+    windStrength: clampNum(p.windStrength, 0, 1.2),
+    pileMaxDepth: clampNum(p.pileMaxDepth, 80, 220),
+    pileSmoothness: clampNum(p.pileSmoothness, 0.055, 0.085),
+    pileFPS: clampNum(p.pileFPS, 15, 30),
+    // cap to protect CPU
+    shovelScale: clampNum(p.shovelScale, 0.85, 1.2),
+    shovelRevealDepth: clampNum(p.shovelRevealDepth, 12, 9999),
+    chunkTtlMs: clampNum(p.chunkTtlMs, 2e3, 7e3),
+    chunkBounciness: clampNum(p.chunkBounciness, 0.15, 0.55),
+    chunkAirDrag: clampNum(p.chunkAirDrag, 0.01, 0.06),
+    chunkAllowSideExit: p.chunkAllowSideExit,
+    chunkGravityY: clampNum(p.chunkGravityY, 0.7, 1.2)
+  };
+}
+function morphPreset(base, intensity = 0, speed = 0, wind = 0) {
+  const i = clamp012(intensity);
+  const s = clamp012(speed);
+  const w = clamp012(wind);
+  return applySafety({
+    ...base,
+    flakeCount: Math.round(base.flakeCount * (0.85 + 0.35 * i)),
+    snowfallSpeed: base.snowfallSpeed * (0.9 + 0.25 * s),
+    windStrength: base.windStrength * (0.9 + 0.25 * w)
+  });
+}
+function SnowStack(props) {
+  const {
+    enabled = true,
+    preset = "calm",
+    intensity = 0,
+    // default calm
+    speed = 0,
+    wind = 0,
+    interactive = false
+  } = props;
+  const base = PRESETS[interactive ? "interactive" : preset];
+  const cfg = useMemo(() => morphPreset(base, intensity, speed, wind), [base, intensity, speed, wind]);
+  const apiRef = useRef(null);
+  const matterRef = useRef(null);
+  const windFromScroll = useWindFromScroll();
+  const windX = useMemo(() => clamp(windFromScroll * cfg.windStrength, -2, 2), [windFromScroll, cfg.windStrength]);
+  const [avgDepth, setAvgDepth] = useState(0);
+  const shovelVisible = enabled && interactive && avgDepth >= cfg.shovelRevealDepth;
+  const matterInit = useMemo(
+    () => ({
+      ttlMs: cfg.chunkTtlMs,
+      restitution: cfg.chunkBounciness,
+      frictionAir: cfg.chunkAirDrag,
+      allowSideExit: cfg.chunkAllowSideExit,
+      gravityY: cfg.chunkGravityY
+    }),
+    [cfg.chunkTtlMs, cfg.chunkBounciness, cfg.chunkAirDrag, cfg.chunkAllowSideExit, cfg.chunkGravityY]
+  );
+  useEffect(() => {
+    matterRef.current?.setConfig(matterInit);
+  }, [matterInit]);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      SnowfallEngine,
+      {
+        zIndex: 1,
+        enabled,
+        getAPI: () => apiRef.current,
+        windX,
+        flakeCount: cfg.flakeCount,
+        snowfallSpeed: cfg.snowfallSpeed,
+        snowflakeSize: cfg.snowflakeSize
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      SnowAccumulationCanvas,
+      {
+        zIndex: 2,
+        enabled,
+        windX,
+        apiRef,
+        onAvgDepth: setAvgDepth,
+        pileMaxDepth: cfg.pileMaxDepth,
+        pileSmoothness: cfg.pileSmoothness,
+        pileFPS: cfg.pileFPS
+      }
+    ),
+    enabled && interactive && /* @__PURE__ */ jsx(MatterSnowChunks, { zIndex: 4, apiRef: matterRef, initialConfig: matterInit }),
+    /* @__PURE__ */ jsx(
+      SnowShovel,
+      {
+        zIndex: 3,
+        visible: shovelVisible,
+        scale: cfg.shovelScale,
+        getAPI: () => apiRef.current,
+        getMatter: () => matterRef.current
+      }
+    )
+  ] });
+}
+
+export { MatterSnowChunks, SnowStack };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "snowstack",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Calm, interactive snowfall with accumulation and shovel physics for React",
+  "keywords": [
+    "react",
+    "snow",
+    "snowfall",
+    "canvas",
+    "matter-js",
+    "animation",
+    "winter",
+    "effects",
+    "ui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ist00dent/snowstack"
+  },
+  "license": "MIT",
+  "author": "ist00dent",
+  "homepage": "https://github.com/ist00dent/snowstack",
+  "bugs": {
+    "url": "https://github.com/ist00dent/snowstack/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "dependencies": {
+    "lucide-react": "^0.268.0",
+    "matter-js": "^0.19.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup src/index.ts --format esm --dts --clean"
+  },
+  "devDependencies": {
+    "@types/matter-js": "^0.20.2",
+    "@types/react": "^19.2.7",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  }
+}