{"_id":"@affectively/confetti-physics","_rev":"4-61567df12f329ddbb31d5285f01bf688","name":"@affectively/confetti-physics","dist-tags":{"latest":"5.0.0"},"versions":{"1.0.0":{"name":"@affectively/confetti-physics","version":"1.0.0","keywords":["confetti","celebration","physics","particles","fluid-dynamics","haptic","sound","web-audio","vibration","canvas","animation","react","hooks"],"author":{"name":"AFFECTIVELY","email":"opensource@affectively.ai"},"license":"MIT","_id":"@affectively/confetti-physics@1.0.0","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/confetti-physics#readme","bugs":{"url":"https://github.com/affectively-ai/confetti-physics/issues"},"dist":{"shasum":"cd55ed1cd21717870b175d17b70afc80d55c7581","tarball":"https://registry.npmjs.org/@affectively/confetti-physics/-/confetti-physics-1.0.0.tgz","fileCount":13,"integrity":"sha512-FsksbbEH+LZZh5ibxYrewbR26zbW1mEKxMm7MnZG/W/7rE0Z5xpFg0D617FNuPOXXPR8GMjjtseAsOBgL1c0MQ==","signatures":[{"sig":"MEUCIQCDvsLLenTso5fmad7nJXNxUWUZ/n+orjA3s4nvp4TMOgIgbBAzRWlFCI5tDywoUZE85DFPiymFp6Bxo2l5rzvImRg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":291972},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.mjs","require":"./dist/react.js"}},"gitHead":"42b2ab809d00d02fd52dde50bfff7af405d30bd9","scripts":{"test":"bun test","build":"tsup src/index.ts src/react.ts --format cjs,esm --dts --external react","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/confetti-physics.git","type":"git"},"_npmVersion":"11.7.0","description":"Physics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.","directories":{},"_nodeVersion":"25.4.0","dependencies":{"canvas-confetti":"^1.9.0","@buley/hexgrid-3d":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","react":"^19.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"peerDependencies":{"react":">=17.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/confetti-physics_1.0.0_1769377447210_0.3471083060301072","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."},"1.0.1":{"name":"@affectively/confetti-physics","version":"1.0.1","keywords":["confetti","celebration","physics","particles","fluid-dynamics","haptic","sound","web-audio","vibration","canvas","animation","react","hooks"],"author":{"name":"AFFECTIVELY","email":"opensource@affectively.ai"},"license":"MIT","_id":"@affectively/confetti-physics@1.0.1","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/confetti-physics#readme","bugs":{"url":"https://github.com/affectively-ai/confetti-physics/issues"},"dist":{"shasum":"635e4e79f61348f629d37ba7a866015d0e3fbcdb","tarball":"https://registry.npmjs.org/@affectively/confetti-physics/-/confetti-physics-1.0.1.tgz","fileCount":14,"integrity":"sha512-HIVYPLuq22xlYlHRAmf1SrD36HU+XUhTBUSGUcfV8WjmrJiVQskBhEzbb8fT6+p6Kk5xPMLtFgA9IlV2C0unow==","signatures":[{"sig":"MEUCIG4y1Rt3sxVy8cT0i0Z/utveonVxeTX4GGWjBTWLJTr0AiEAjvJ01W8ay/EqZoCCWmrIOKkbitbebxF9Z8NiKz1Auqw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":364752},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.mjs","require":"./dist/react.js"}},"scripts":{"test":"bun test","build":"tsup src/index.ts src/react.ts --format cjs,esm --dts --external react","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/confetti-physics.git","type":"git"},"_npmVersion":"11.8.0","description":"Physics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.","directories":{},"_nodeVersion":"25.5.0","dependencies":{"canvas-confetti":"^1.9.0","@buley/hexgrid-3d":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","react":"^19.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"peerDependencies":{"react":">=17.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/confetti-physics_1.0.1_1770699970752_0.881067161219746","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."},"5.0.0":{"name":"@affectively/confetti-physics","version":"5.0.0","keywords":["confetti","celebration","physics","particles","fluid-dynamics","haptic","sound","web-audio","vibration","canvas","animation","react","hooks"],"author":{"name":"AFFECTIVELY","email":"opensource@affectively.ai"},"license":"UNLICENSED","_id":"@affectively/confetti-physics@5.0.0","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"homepage":"https://github.com/affectively-ai/confetti-physics#readme","bugs":{"url":"https://github.com/affectively-ai/confetti-physics/issues"},"dist":{"shasum":"7895049ff1fdf0daccba27e86353a4a93a88abf4","tarball":"https://registry.npmjs.org/@affectively/confetti-physics/-/confetti-physics-5.0.0.tgz","fileCount":14,"integrity":"sha512-43oKRmDYa01hAONi0WzYO6ADoDEosO0r1joF8Rh0AyGvXq2Bqysdu85j/7KjqrspFYqDxVyR/uxmtdtvq12qwQ==","signatures":[{"sig":"MEUCIQD6bXinaoCEKScgtVavHvSag5xVMC0sFghi28agOQbUIwIgBscYxAms7l4BVX0lrcI3cycsYQU2tnnIlZx9GUifPY0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":520802},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./react":{"types":"./dist/react.d.ts","import":"./dist/react.mjs","require":"./dist/react.js"}},"scripts":{"test":"bun test","build":"tsup src/index.ts src/react.ts --format cjs,esm --dts --external react","prepublishOnly":"npm run build"},"_npmUser":{"name":"buley","email":"buley@outlook.com"},"repository":{"url":"git+https://github.com/affectively-ai/confetti-physics.git","type":"git"},"_npmVersion":"11.8.0","description":"Physics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.","directories":{},"_nodeVersion":"25.5.0","dependencies":{"canvas-confetti":"^1.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","react":"^19.0.0","typescript":"^5.9.0","@types/node":"^22.0.0"},"peerDependencies":{"react":">=17.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/confetti-physics_5.0.0_1773156222255_0.8866109640790314","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is deprecated and no longer supported. Do not use."}},"time":{"created":"2026-01-25T21:44:07.152Z","modified":"2026-03-27T20:03:20.395Z","1.0.0":"2026-01-25T21:44:07.409Z","1.0.1":"2026-02-10T05:06:10.950Z","5.0.0":"2026-03-10T15:23:42.394Z"},"bugs":{"url":"https://github.com/affectively-ai/confetti-physics/issues"},"author":{"name":"AFFECTIVELY","email":"opensource@affectively.ai"},"license":"UNLICENSED","homepage":"https://github.com/affectively-ai/confetti-physics#readme","keywords":["confetti","celebration","physics","particles","fluid-dynamics","haptic","sound","web-audio","vibration","canvas","animation","react","hooks"],"repository":{"url":"git+https://github.com/affectively-ai/confetti-physics.git","type":"git"},"description":"Physics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with hexgrid-3d math.","maintainers":[{"name":"buley","email":"buley@outlook.com"}],"readme":"# @affectively/confetti-physics\n\nPhysics-based confetti celebrations with fluid dynamics, haptic feedback, and procedural audio. Built with [hexgrid-3d](https://github.com/buley/hexgrid-3d) math.\n\n[![npm version](https://img.shields.io/npm/v/@affectively/confetti-physics.svg)](https://www.npmjs.com/package/@affectively/confetti-physics)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- 🌀 **Physics-based confetti** - Fluid dynamics, flow fields, and particle attractors\n- 🎉 **Classic confetti** - Traditional particle effects via canvas-confetti\n- 🔊 **Procedural audio** - Web Audio API tones (no audio files needed)\n- 📳 **Haptic feedback** - Web Vibration API patterns\n- ⚛️ **React hooks** - Easy integration with React apps\n- ♿ **Accessibility** - Respects `prefers-reduced-motion`\n- 💾 **Preference persistence** - User settings saved to localStorage\n\n## Installation\n\n```bash\nnpm install @affectively/confetti-physics\n# or\nyarn add @affectively/confetti-physics\n# or\nbun add @affectively/confetti-physics\n```\n\n## Quick Start\n\n### Basic Usage\n\n```typescript\nimport { CelebrationService, ConfettiService, SoundService, HapticService } from '@affectively/confetti-physics';\n\n// Quick celebration with confetti + sound + haptic\nCelebrationService.celebrate('achievement');\n\n// Physics-based confetti only\nConfettiService.supernova();\nConfettiService.aurora();\nConfettiService.vortex();\n\n// Individual services\nSoundService.success();\nHapticService.celebrate();\n```\n\n### React Hooks\n\n```tsx\nimport { useCelebration, useConfetti, usePhysicsConfetti } from '@affectively/confetti-physics/react';\n\nfunction MyComponent() {\n const { celebrate, success, milestone } = useCelebration();\n const confetti = useConfetti();\n\n return (\n
\n \n \n
\n );\n}\n```\n\n## Celebration Types\n\n### Orchestrated Celebrations\n\n`CelebrationService` combines confetti, sound, and haptic feedback:\n\n| Type | Confetti | Sound | Haptic |\n|------|----------|-------|--------|\n| `tap` | - | tap | light |\n| `success` | - | success | medium |\n| `complete` | sparkles | complete | medium |\n| `achievement` | achievement | milestone | strong |\n| `milestone` | milestone | milestone | strong |\n| `streak` | burst | streak | medium |\n| `streakMilestone` | streak | celebration | strong |\n| `levelUp` | levelUp | levelUp | strong |\n| `unlock` | stars | unlock | strong |\n| `premium` | premium | celebration | strong |\n| `welcome` | welcome | success | medium |\n| `error` | - | error | medium |\n| `warning` | - | warning | light |\n\n### Classic Confetti Effects\n\n| Type | Description |\n|------|-------------|\n| `burst` | Quick celebration burst |\n| `shower` | Confetti rain from top |\n| `fireworks` | Firework explosions |\n| `sparkles` | Gentle sparkle effect |\n| `stars` | Star-shaped particles |\n| `hearts` | Heart emoji particles |\n| `achievement` | Grand achievement celebration |\n| `streak` | Fire + gold confetti |\n| `milestone` | Trophy + stars |\n| `levelUp` | Rocket + fireworks |\n| `welcome` | Gentle welcome |\n| `premium` | Crown + gem + gold |\n\n### Physics-Based Confetti Effects\n\nThese use fluid dynamics, flow fields, and attractors from hexgrid-3d:\n\n| Type | Description |\n|------|-------------|\n| `vortex` | Spiral vortex pulling particles inward |\n| `supernova` | Explosive burst with fluid shockwave |\n| `aurora` | Flowing northern lights ribbons |\n| `resonance` | Heart-rate synced pulsing |\n| `orbit` | Particles orbiting multiple attractors |\n| `cascade` | Fluid waterfall effect |\n| `emergence` | Particles following flow field |\n| `harmony` | Lissajous pattern attractors |\n| `helix` | DNA-like double helix spiral |\n| `bloom` | Flower-like unfolding pattern |\n| `constellation` | Particles forming and connecting |\n| `nebula` | Gas cloud effect with density |\n\n## Emotion-Aware Celebrations\n\nAutomatically select effects and colors based on emotional context:\n\n```typescript\nimport { ConfettiService } from '@affectively/confetti-physics';\n\nConfettiService.celebrateEmotion({\n emotion: 'joy',\n valence: 0.8, // -1 to 1 (negative to positive)\n arousal: 0.7, // 0 to 1 (calm to excited)\n heartRate: 80 // Optional: sync with biometrics\n});\n```\n\n### Emotion Color Palettes\n\n| Emotion | Colors |\n|---------|--------|\n| joy | Gold, amber |\n| serenity | Emerald, mint |\n| excitement | Rose, gold |\n| love | Pink, rose |\n| triumph | Purple, gold |\n| gratitude | Teal, emerald |\n| wonder | Sky blue, purple |\n| peace | Green, teal |\n\n## Sound Effects\n\n14 procedurally generated sounds using Web Audio API:\n\n```typescript\nimport { SoundService } from '@affectively/confetti-physics';\n\nSoundService.tap(); // Soft click\nSoundService.success(); // C5-E5-G5 ascending\nSoundService.celebration(); // Full fanfare\nSoundService.milestone(); // Grand achievement\nSoundService.streak(); // Quick excitement\nSoundService.levelUp(); // Ascending scale\nSoundService.unlock(); // Unlocking tone\nSoundService.complete(); // Task done\nSoundService.breatheIn(); // Rising tone for breathing exercises\nSoundService.breatheOut(); // Falling tone\nSoundService.heartbeat(); // Lub-dub rhythm\nSoundService.error(); // Descending tone\nSoundService.warn(); // Alert tone\n```\n\n### Volume Control\n\n```typescript\nSoundService.setVolume(0.5); // 0-1\nSoundService.setEnabled(false); // Mute\n```\n\n## Haptic Feedback\n\n15 vibration patterns via Web Vibration API:\n\n```typescript\nimport { HapticService } from '@affectively/confetti-physics';\n\nHapticService.tap('light'); // Light tap\nHapticService.success('medium'); // Satisfying success\nHapticService.celebrate('strong'); // Excitement burst\nHapticService.milestone(); // Grand achievement\nHapticService.streak(); // Rapid fire\nHapticService.levelUp(); // Ascending power\nHapticService.unlock(); // Unlocking sensation\nHapticService.heartbeat(); // Calming heartbeat\nHapticService.breatheIn(); // For breathing exercises\nHapticService.breatheOut();\n```\n\n### Intensity Levels\n\n- `light` - 50% duration multiplier\n- `medium` - 100% (default)\n- `strong` - 150%\n\n## User Preferences\n\nPreferences are automatically saved to localStorage:\n\n```typescript\nimport { CelebrationService } from '@affectively/confetti-physics';\n\n// Get current settings\nconst settings = CelebrationService.getSettings();\n// { soundEnabled, hapticEnabled, confettiEnabled, volume, hapticSupported, soundSupported }\n\n// Update settings\nCelebrationService.setSoundEnabled(false);\nCelebrationService.setHapticEnabled(true);\nCelebrationService.setConfettiEnabled(true);\nCelebrationService.setVolume(0.7);\n\n// Enable/disable all at once\nCelebrationService.enableAll();\nCelebrationService.disableAll();\n```\n\n## React Hooks\n\n### useCelebration\n\nMain hook for all celebration functionality:\n\n```tsx\nconst {\n celebrate, // (type) => void\n celebrateCustom, // (config) => void\n celebrateStreak, // (days) => void\n tap, success, complete, achievement, milestone,\n levelUp, unlock, premium, welcome, error, warning,\n settings, // Current settings\n setSoundEnabled, setHapticEnabled, setConfettiEnabled, setVolume\n} = useCelebration();\n```\n\n### useConfetti\n\nFor visual celebrations:\n\n```tsx\nconst {\n celebrate, // (type) => void\n celebratePhysics, // (config) => void\n celebrateEmotion, // ({ emotion, valence, arousal }) => void\n enabled, setEnabled,\n physicsEnabled, setPreferPhysics,\n fromElement, // (element, type?) => void\n reset, // () => void\n // Classic: burst, shower, fireworks, sparkles, stars, hearts, etc.\n // Physics: vortex, supernova, aurora, resonance, orbit, cascade, etc.\n} = useConfetti();\n```\n\n### usePhysicsConfetti\n\nDirect access to physics engine:\n\n```tsx\nconst {\n celebrate, // (config) => void\n celebrateWithEmotion, // (type, emotion, options) => void\n clear, // () => void\n enabled, setEnabled,\n isAvailable,\n // Each type as a method with optional config\n vortex, supernova, aurora, resonance, orbit, cascade,\n emergence, harmony, helix, bloom, constellation, nebula\n} = usePhysicsConfetti();\n```\n\n### useSound / useHaptic\n\nIndividual service hooks:\n\n```tsx\nconst sound = useSound();\nconst haptic = useHaptic();\n\n// Both have:\n// - enabled, supported, setEnabled\n// - Convenience methods (tap, success, etc.)\n```\n\n### useInteractionFeedback\n\nFor button feedback:\n\n```tsx\nconst { onPress, onSuccess, onError } = useInteractionFeedback();\n\n\n```\n\n### useBreathingFeedback\n\nFor breathing exercises:\n\n```tsx\nconst { breatheIn, breatheOut, hold, complete, breathingCycle } = useBreathingFeedback();\n```\n\n### useStreakCelebration\n\nFor streak milestones:\n\n```tsx\nconst { celebrateStreak, celebrateDaily, celebrateWeekly } = useStreakCelebration();\n\n// celebrateStreak(days) automatically picks the right celebration:\n// - Day 1: dailyCheckIn\n// - Days 7, 30, 100, 365: streakMilestone\n// - Other days: streak\n```\n\n## Accessibility\n\nThe library automatically respects `prefers-reduced-motion`:\n\n```css\n@media (prefers-reduced-motion: reduce) {\n /* Confetti and animations are disabled */\n}\n```\n\nYou can also manually disable effects:\n\n```typescript\nCelebrationService.disableAll();\n// or individually:\nConfettiService.setEnabled(false);\nSoundService.setEnabled(false);\nHapticService.setEnabled(false);\n```\n\n## Browser Support\n\n| Feature | Browser Support |\n|---------|-----------------|\n| Confetti (canvas) | All modern browsers |\n| Physics engine | All modern browsers |\n| Web Audio API | All modern browsers |\n| Vibration API | Android Chrome, Firefox |\n\n## Dependencies\n\n- [`@affectively/hexgrid-3d`](https://github.com/buley/hexgrid-3d) - Physics math (fluid dynamics, flow fields)\n- [`canvas-confetti`](https://github.com/catdad/canvas-confetti) - Classic confetti effects\n- `react` (peer, optional) - For React hooks\n\n## License\n\nMIT © [AFFECTIVELY](https://affectively.ai)\n\n## Contributing\n\nContributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.\n\n## Related Projects\n\n- [hexgrid-3d](https://github.com/buley/hexgrid-3d) - The math library powering the physics\n- [canvas-confetti](https://github.com/catdad/canvas-confetti) - Classic confetti effects\n","readmeFilename":"README.md"}